mano-afk

一套全自动流水线，可根据自然语言描述完成应用的构建、部署与测试。用户在整个过程中全程离线（AFK）。该技能具备持续学习能力——构建规则与用户偏好将在各会话间持久化，从而随时间推移不断提升输出质量及与用户偏好的契合度。

Claude Code 用户：请使用位于 claude/SKILL.md 的 Claude Code 专用 SKILL.md 文件。

架构

三个角色协同协作，共同交付应用：

• 主智能体（即你）：负责编排调度、执行测试、协调修复、与用户沟通
• 构建子智能体：将需求转化为架构 → 生成代码 → 部署 → （在给定具体错误时）修复缺陷
• 对抗子智能体：独立设计端到端测试用例（不执行测试）

主智能体将代码生成任务委托给子智能体（此阶段耗时最长），自身在此期间保持空闲。所有测试均由主智能体直接运行，以确保对测试结果拥有完整可见性。

编排流程

AFK 规则：第 0 步是唯一允许用户交互的窗口；从第 1 步起，所有决策必须完全自主完成——禁止向用户提问。对于存在歧义的决策（如 8bit vs float、React vs Vue、端口选择等），应采用最合理的默认值，并在 PRD.md 中明确记录。仅当任务完全不可行时（例如缺失必要硬件、无权限、已耗尽 10 次修复迭代）才可中止流程。

第 0 步：用户初始化（交互式）

这是唯一允许智能体向用户提问的步骤。

需求评估：若用户请求过于模糊，无法确定核心功能（例如“帮我做一个应用”），或包含可能导致产品形态根本不同的歧义需求，则应请用户澄清——问题数量应严格控制在 1–2 个，聚焦关键点，避免长篇访谈。非关键性缺失项（如视觉设计、校验规则、技术栈、页面布局等）由构建子智能体自主补全。

端到端（E2E）测试配置：运行 mano-afk config --get e2e-mode 进行检查。

• local 或 cloud —— 已完成配置，可继续流程。
• 未设置 —— 向用户推荐启用 E2E 测试：“E2E 测试能让 mano-afk 通过真实 UI 验证您的应用——点击按钮、填写表单、检查视觉结果。是否要现在配置？”随后运行 mano-afk check，并按其输出的指引完成配置。若用户拒绝，则跳过 E2E 测试环节——本技能在无 E2E 支持下仍可正常工作。

第 0 步完成后，向用户告知：“请握好啤酒。从现在起全程 AFK。”

第 1 步：准备（全自动 —— 无用户交互）

根据用户请求推导出一个简短、符合 kebab-case 命名规范的项目名称（例如，“帮我做一个待办事项应用” → todo-app）。

项目目录：通过 mano-afk config --get projects-dir 读取已配置的项目根目录（默认为 ~/Projects/）；项目路径为：{projects-dir}/{project-name}/。

读取 references/report-template.md —— 你将在第 4 步中使用该模板生成 report.md。注意记录 references/ 目录的绝对路径——该路径将传递给后续子智能体，用于访问其余参考文件。

第 2 步：构建（子智能体）

通过 sessions_spawn 启动构建子智能体，参数设为 runtime="subagent"。构造 prompt 时需包含以下内容：

1. build-pipeline.md 的绝对路径 —— 指示子智能体读取并遵循该文件
2. 本技能 references/ 目录的绝对路径 —— 子智能体按需读取 rules.md、preferences.md 和各类模板
3. 用户原始请求（逐字保留）
4. 项目目录路径

立即向用户响应当前正在构建的内容及项目目录路径。构建子智能体内部遵循四个阶段：阶段 1 生成 PRD.md（含验收标准的产品需求文档），阶段 2 设计架构并生成 README.md（其中的测试用例由 PRD 推导而来），阶段 3 编写代码，阶段 4 执行部署。等待 progress.md 中显示 status: ready_for_testing 后再继续。

超时设置：构建任务（依赖安装、编译、部署等）可能耗时较长。启动子智能体时应设置充足超时时间——至少 30 分钟；若平台支持，建议不设超时限制。

第 3 步：验证部署

开始测试前，需确认应用已成功部署并可访问：

1. 检查项目中是否存在 deploy/start.sh
2. 若服务尚未运行，则执行该脚本启动服务
3. 使用 curl 或端口检测命令验证服务可达性
4. 若部署失败（如 start.sh 缺失、服务崩溃、端口不可达），读取 deploy/backend.log 和 deploy/frontend.log，然后进入第 5 步（修复循环），并将部署错误作为本次失败的描述

第 4 步：测试

执行 README 中定义的所有类别下的全部测试用例，不得跳过或延迟任一用例。

开始每个类别测试前，先统计 README 中该类别的总测试用例数。每执行一个测试，打印带进度标识的输出，例如：[3/18] api_3 PASS 或 [5/18] api_5 FAIL。该机制可清晰暴露跳过的测试——若计数器从 3 直接跳至 7，则表明测试 4–6 被跳过。

将测试结果记录至 report.md（使用 report-template.md 模板）。若测试失败，需完整记录错误输出（响应体、stderr、日志等）。

4.1 代码风格检查（Lint）

运行构建子智能体所配置的 Linter 工具。对可自动修复的问题启用 --fix 参数，然后报告剩余错误。

4.2 API 测试

执行 README 中定义的全部 API 测试用例。使用 curl -s -w "\nHTTP_STATUS:%{http_code}\n" 同时捕获响应体与 HTTP 状态码。测试失败时需打印完整响应体。

4.3 端到端（E2E）测试（可选）

E2E 测试通过 mano-afk run 在浏览器中打开应用，借助视觉-语言模型（VLA）与 UI 交互，并验证视觉结果。

前提条件 —— 若任一检查失败，请跳过本节全部内容：

1. mano-afk 已加入系统 PATH（安装方式为：技能安装时通过 brew metadata 自动完成 —— 切勿自行安装任何包）
2. mano-afk config --get e2e-mode 返回 local 或 cloud（若未设置，则跳过并记录原因至 report.md）

数据库重置：运行首个 E2E 测试前，清空所有应用数据表（例如对每个应用表执行 DELETE FROM，或删除并重新初始化 SQLite 文件）。此举可清除 API 测试遗留的数据。注意：不得在单个 E2E 测试之间重置数据库——E2E 测试顺序执行，且后序测试可能依赖前序测试创建的状态。

执行 README 中定义的全部 E2E 测试用例：

mano-afk run "{steps}" --url "{url}" --expect "{expected}"

--url 参数会在智能体启动前于默认浏览器中打开目标页面。智能体将看到已加载完毕的页面——切勿在任务步骤中包含“打开 localhost:...”类指令。

所有执行参数（--local/--cloud、--max-steps、--minimize）均从 mano-afk config 中读取。若 CLI 显式指定标志位，则优先级高于配置。可通过 mano-afk config --list 查看当前配置值。

执行规则：

• 各测试用例须顺序执行
• 每次 mano-afk 任务最长允许运行 30 分钟。请将 exec 超时设为至少 1800 秒，或使用 background: true 配合 yieldMs: 1800000。严禁使用过短超时
• 测试运行期间禁止手动操作鼠标或键盘
• 使用 mano-afk stop 解决 409 会话冲突、清理被终止进程的残留、或中止正在运行的任务

4.4 对抗审查（Adversary Review）

在前述全部测试均通过后，通过 sessions_spawn 启动对抗子智能体，参数设为 runtime="subagent"。构造 prompt 时需包含以下内容：

1. 角色定义：“你是一名独立的 QA 审查员。你的职责是识别构建者可能遗漏的潜在问题。”
2. 项目完整 PRD.md（含需求与验收标准）和 README.md（含架构与测试用例）内容
3. 项目目录路径（对抗子智能体将据此读取源码，进行代码级分析）

对抗子智能体不与运行中的应用交互——仅审查需求文档与源代码。

对抗子智能体仅识别潜在问题，不执行任何操作。其返回的发现结果分为两层，每层均以表格形式呈现，列包括：ID、Finding（问题描述）、Severity（严重程度）、Suggested Verification（建议验证方式）。

• 第一层 —— 用户视角：可用性缺口、跨功能一致性、流程混淆、用户体验不佳等问题
• 第二层 —— 代码视角：数据完整性、缺失校验、异常处理、状态一致性等问题

约束条件：必须覆盖两层问题；不得重复 README 中已有的测试用例；不得标记安全漏洞（如 XSS、SQL 注入、CSRF）。

需由你亲自对每项发现进行分类评估，方法包括：代码检查（用于 Schema/配置类问题）、API 测试（通过 curl 验证后端行为）、或 E2E 测试（验证 UI 渲染、用户流程、视觉状态）。其中，至少 2–3 项发现必须通过 E2E 测试验证。执行对抗子智能体的 E2E 验证前，必须重置数据库，以避免受先前测试污染。每项评估结论（确认 → 进入修复循环 / 驳回 → 注明理由）均需记录至 report.md。

完成检查清单（进入第 5 或第 6 步前）

继续流程前，请逐一核对以下各项。若任一项为“否”，请返回补全。

• README 中定义的全部 API 测试用例均已执行并记录
• README 中定义的全部 E2E 测试用例均已执行并记录（若前提条件未满足，则全部跳过并注明原因）
• 对抗审查已完成，且包含两层问题的发现结果
• 至少 2–3 项对抗审查发现已通过 E2E 测试验证（若 E2E 可用）
• 所有确认的对抗审查发现均已纳入修复循环

第 5 步：修复循环

若任一测试失败：

1. 收集全部失败详情，含完整错误输出（响应体、stderr、日志、mano-afk 输出）
2. 通过 sessions_spawn 启动一个全新的构建子智能体（修复模式），参数设为 runtime="subagent"，并提供以下信息：
   • build-pipeline.md 的绝对路径（修复模式无需其他参考文件）
   • 项目目录路径
   • 详细失败描述：测试 ID、执行命令、预期结果、实际结果、完整错误输出
3. 等待子智能体完成修复与重新部署（progress.md 显示 status: ready_for_testing）
4. 使用与原始测试相同的工具与方法重新运行失败的测试。经 E2E 测试验证的用例，必须再次通过 E2E 测试验证。
5. 重复上述过程直至全部通过（最多 10 次迭代）

E2E 误报处理：若某 E2E 测试失败，但经代码检查确认实现逻辑正确（失败源于视觉模型误判），则在 report.md 中将其标记为误报，并说明理由。误报不得进入修复循环——修复正确代码将浪费迭代次数。

重复失败应对策略：若同一测试连续失败 2 次及以上，需在修复 prompt 中添加备注：“该测试已失败 N 次。此前修复尝试：[简述]。请考虑结构性修复而非补丁式修复。”

迭代耗尽处理：若已达 10 次迭代上限但仍有失败项，则携带当前结果进入第 6 步。在 report.md 中完整记录所有剩余失败项、迭代历史及已尝试的修复措施总结。

第 6 步：完成

• 向用户总结：测试总数、通过/失败数、项目目录路径
• 更新规则：回顾修复循环历史。若某类错误模式可在未来项目中预防同类缺陷，则将通用规则追加至 references/rules.md（上限 100 条；若已达上限，则移除价值最低的一条）。同时合并构建子智能体在项目根目录下生成的 new-rules.md 文件。
• 更新偏好：若用户给出后续反馈（如样式、功能等），则更新 references/preferences.md

参考目录（Reference Directory）

references/ 目录属于本技能本地专属，其中文件随项目演进而持续更新。该目录不会修改任何全局 CLI 配置、系统设置，亦不会影响本技能目录以外的任何文件。

作用范围：这些文件仅被 mano-afk 的构建子智能体与对抗子智能体读取。对其他技能、其他 CLI 工具或宿主系统均无任何影响。

存储内容：

执行过程中仅 rules.md 与 preferences.md 会被修改，其余文件均为只读模板。规则与偏好将在各项目间持久化，使本技能具备长期进化能力。

数据与隐私

• 默认本地运行：代码生成、代码风格检查（Lint）、API 测试及部署全部在本地机器上完成。
• 云端数据传输：在 cloud 模式下执行的 E2E 测试（4.3 节）会调用 mano-afk run，将截图与任务描述发送至云端视觉-语言模型（VLA）服务商。该行为仅在通过 mano-afk config 显式将 e2e-mode 设为 cloud 后触发。local 模式及跳过 E2E 测试均不涉及任何云端通信。
• 纯属用户主动启用：E2E 测试需用户显式配置（mano-afk config --set e2e-mode local|cloud）。未配置时，该功能默认禁用。
• 无其他外部调用：本技能除上述用户主动启用的测试执行外，不会回传数据、采集遥测信息，亦不会向任何服务发送项目数据。