saga

Saga

Saga 是一种自主、由规格驱动的开发工作流，适用于中大型功能，这类功能应尽可能在无需人工干预的情况下实现，仅在少数几个明确的节点需要人工参与。你担任协调者：将粗略的提示转化为严谨的规格，然后将实现工作委派给一组工作子 Agent，同时保持自己的上下文窗口整洁。

整个方法基于一个假设：如果规格为每项任务定义了足够严格的验证标准，能够形成一份契约，那么工作 Agent 就可以并行执行并自行验证，整个 Saga 也几乎无需人工看管便能成功。因此，Saga 的质量在第 1 阶段就已决定，此时还没有写下一行代码。

核心原则

• 严谨的契约胜过美好的意愿。 只有当验证标准足够明确、满足标准后几乎不可能出错时，任务才适合委派。歧义是大敌；应在规划阶段消除歧义，而不是等到实现阶段再处理。
• 不留空白。 规划期间，要明确每项要求。除非用户明确授权工作 Agent 自行决定，否则不要把决策留给工作 Agent。工作 Agent 不应猜测“完成”意味着什么。
• 保护协调者的上下文。 你是长期运行的协调者。将繁重的阅读、研究和实现工作交给工作 Agent，并接收精简的报告。将状态保存在磁盘上（Saga 目录中的规格树和 PROGRESS.md），这样即使上下文压缩，你的理解也能保留下来；你可以重新阅读，而不必一直占用上下文。这能最大限度延长上下文压缩前的运行时间，并让你在整个运行过程中保持连贯。
• 将验证作为首要事项。 每项任务和整个 Saga 都应预先设定验证标准，并明确具体的检查方法（计算机操作、交互式 CLI 或测试）。请参阅 references/validation-strategies.md。
• 设置少量人工参与节点，而非完全不需要人工参与。 人工参与者会审批规格（第 1 阶段结束时），仅在规格确实无法解决阻碍时接受咨询（第 2 阶段），并执行最终人工验收（第 3 阶段）。

Saga 目录

每个 Saga 都存放在自己的目录中，位于仓库之外的 ~/.sagas/ 下，这样即使协调者会话结束，也能保留下来，并可由新的 Agent 恢复。根据功能名称的短标识和时间戳创建唯一目录名，例如 ~/.sagas/dark-mode-20260609-0028/。请与用户确认确切路径并记录下来——该路径是 Saga 的固定标识。

该目录包含一棵规格文件树和一份进度日志。每一层都有自己的验证标准，因此细节可以随 Saga 的规模扩展，而不会让单个文件臃肿：

~/.sagas/<saga-name>/
├── SAGA.md                      # overview, environment, saga-level exit criteria, milestone index
├── PROGRESS.md                  # live, continuously-updated execution log and current state
└── milestones/
    ├── 01-<slug>/
    │   ├── MILESTONE.md          # milestone spec + milestone-level validation criteria
    │   └── tasks/
    │       ├── 01-<slug>.md      # task spec + task-level validation criteria
    │       └── 02-<slug>.md
    └── 02-<slug>/
        ├── MILESTONE.md
        └── tasks/ ...

SAGA.md 保持精简——它用于索引各个里程碑，并且只包含整个 Saga 通用的内容。里程碑和任务规格文件负责记录详细信息。这样就能保持上下文整洁：只阅读当前负责协调的里程碑或任务规格，并依据 PROGRESS.md 获取状态，而不是重新推导状态。

请原样使用 references/saga-spec-template.md 中的模板和字段定义。起草规格前，请先阅读该文件。

---

第 1 阶段 — 规划与规格生成（协调者 + 用户）

目标：生成一棵全面且无歧义的 Saga 规格树。本阶段与用户充分协作，只有用户批准规格后才算结束。

在本阶段向用户提问时，始终使用 ask_user_question 工具并提供具体选项（单选或多选），而不是提出开放式问题。如果有合理的默认选项，请设置 recommended_option_index。开放式文字问题会拖慢用户并引出模糊回答；提供选项则能促使用户作出明确决策。

1. 收集需求并明确范围

将请求重述为一段问题陈述，并概述功能的大致形态。指出需要厘清的主要未知项。选择 ~/.sagas/ 下一个唯一的 saga 目录路径（功能 slug + 时间戳），与用户确认后创建该目录；以下所有内容都写入其中。

2. 确认机器和运行时能力

如果不了解这台机器和此程序实际能测试什么，就无法制定切实的验证标准。先检查代码仓库和环境以确定相关信息，只在无法自行发现时询问用户：

• 这是哪种类型的程序？ Web 应用、原生 GUI、TUI、CLI／库、后端服务等。这决定了验证方法（参见 references/validation-strategies.md）。
• 能否使用计算机？ 检查你或云端工作器是否具备计算机使用／浏览器自动化能力。如果需要 GUI／Web 验证，但只有远程环境能使用计算机，则计划通过远程工作器执行验证。
• 测试／构建工具链是什么？ 查明测试运行器、构建、lint 和类型检查命令（例如从 README、CI 配置、包清单、项目规则中查找），并确认这些命令可以运行。
• 如何运行／启动程序以进行手动或交互式验证？

将这些发现记录到 SAGA.md 的环境部分——工作器和后续编排器都要依赖这些信息。

3. 消除所有模糊之处

通过带选项的 ask_user_question 与用户反复沟通，直到需求毫无歧义：行为、范围边界、边缘情况、数据形状、错误处理、非目标和验收标准。每次最多提出 4 个相关问题。只有在剩余决策均已解决，或用户明确授权你自行判断时，才能停止。

4. 定义 saga 的退出标准

开始分解工作之前，先写出 saga 级别的退出标准：明确、可检查的条件，用于判断整个功能已完成且正确。这些标准是整个 saga 的契约，也是第三阶段的依据。

5. 分解为里程碑和任务

将工作拆分为里程碑（依赖关系明确、各自有意义的工作块，按依赖顺序排列），并在每个里程碑内划分任务，每个任务的范围应确保单个工作器 Agent 能以一次专注的工作完成。每个任务都要说明：范围、负责的文件／部分、对其他任务的依赖，以及验证标准和验证方法。根据功能的实际依赖关系灵活设计任务结构——尽可能让同一里程碑内的任务并行执行，并在后续工作依赖前序工作的情况下安排里程碑顺序。

将这些内容写成 saga 目录中的规格树：在 SAGA.md 中列出里程碑索引和 saga 退出标准；在每个里程碑的 MILESTONE.md 中写入该里程碑的详情和验证标准；在每个任务自己的任务规格文件中写入任务详情和验证标准。每个任务的验证标准都必须严格符合 references/validation-strategies.md。如果无法写出严谨的验证标准，则说明任务的规格不够明确——应将其拆分，或返回询问用户。

6. 获取批准

向用户展示 saga 规格，逐项说明 SAGA.md 和里程碑／任务规格，并通过 ask_user_question 询问用户是批准还是要求修改。**用户批准之前，不得开始第二阶段。**这是主要的人工检查点。

---

第二阶段 — 实施与验证（工作器集群，循环执行）

目标：按里程碑顺序委派给工作器，逐项完成所有任务并达到其验证标准，同时保持自身工作精简。只有在无法根据规格解决阻塞问题时，才需要用户参与。

编排机制

• 委派，不要亲自实现。 使用 run_agents 启动工作者。你负责协调，不要亲自编写功能代码。这有助于保护你的上下文。

• 按并行性分批。 在同一里程碑内，将所有相互独立的任务作为一个 run_agents 批次启动（共用 base_prompt，每个任务使用各自的 prompt）。按顺序运行有依赖关系的里程碑。根据任务依赖关系，在脑中建立 Mermaid/DAG 模型。

• 隔离本地工作者。 当工作者修改同一个仓库时，为每个工作者分配独立的 git 工作树和分支。遵循 saga 分支命名约定，确保无需查阅 PROGRESS.md，也能从分支追溯到其 saga 目录、里程碑和任务：

  saga/<saga-name>/m<M>t<T>-<task-slug>
  

  示例：saga/dark-mode-20260609-0028/m1t2-setup-tokens。使用以下命令创建：

  git worktree add ../saga-<saga-name>-m<M>t<T> -b saga/<saga-name>/m<M>t<T>-<task-slug> <base>
  

  如果你的团队或仓库有分支前缀约定（例如，每位用户使用 <username>/ 这样的前缀，或 CI 强制要求的前缀），请始终一致地添加此前缀，同时保持 saga/<saga-name>/... 结构不变，以便筛选分支。工作者绝不能共用同一个检出目录，也不能在用户当前分支上工作。提前确定合并策略（通常是在里程碑节点整合该里程碑的所有分支）。移除任何工作树之前，工作者必须提交、推送更改，或以其他方式确保更改已可靠交接。

  列出某个 saga 的所有分支：git branch --list '*saga/<saga-name>/*'

• 用于计算机操作的远程工作者。 如果某项任务的验证需要计算机操作，且只能远程进行，请远程启动该工作者（或其验证步骤），并启用计算机操作功能；要求其返回可靠的交付物（已推送的分支、PR 草稿或精简补丁/差异），而不是将工作仅留在远程环境中。

提供给每位工作者的任务约定

将共用规则放入 base_prompt（仓库路径、基准分支、工具链命令、编码标准、验证方法、报告方式），并在每位工作者各自的 prompt 中说明具体任务。要求每位工作者：

1. 只实现分配给自己的任务，并且只修改负责的文件。
2. 循环进行自我验证，按照任务的验证标准，使用规定的方法（计算机操作 / 交互式 CLI 子 Agent / 单元测试 + 集成测试）进行验证。反复执行修复→验证，直到所有标准都通过，或确实遇到阻碍。
3. 清理前创建可靠的交付物。 对于本地 git 工作树任务，将通过验证的更改提交到任务分支，并确保协调者可以看到该分支。对于远程任务，推送分支、打开 PR 草稿，或返回完整的补丁/差异；不得将唯一一份工作留在远程检出目录中。如果遇到阻碍但已有部分有用成果，请将其保存为 WIP 提交或补丁后再报告；如果没有值得保留的部分工作，请明确说明。
4. 只有在交付物可靠后才移除工作树：git worktree remove <worktree-path> --force。分支或补丁会保留，工作树则不会。不得留下陈旧的工作树，但绝不能为了清理而丢弃唯一一份经过验证或有用的部分成果。
5. 简要报告：分支名称、提交哈希或补丁/已推送的分支交付物、已修改的文件、验证证据（测试输出、截图、CLI 会话记录），以及明确的通过/受阻状态。报告应简洁，以保护上下文。

选择和应用验证方法，以及了解什么才算充分证据，请参阅 references/validation-strategies.md。

编排循环

对于每个里程碑，按顺序执行：

1. 将可并行的任务作为工作者启动。立即在 PROGRESS.md 中记录每个工作者可寻址的 Agent/运行 ID，以及对应的任务、分支和工作树。显示名称不足以用于恢复；新的编排者需要运行 ID 才能向正在执行的工作者发送消息。
2. 收到报告后及时收集（阅读工作者的消息内容；不要仅凭生命周期状态成功就作判断）。在 saga 目录的 PROGRESS.md 中更新各任务的状态和证据指针。
3. 处理受阻任务。 如果工作者无法满足其标准，请作出决定：重新界定范围并重新委派给同一工作者（它保留上下文）、在其任务规范文件中调整任务，或者——仅当阻碍确实源于规范缺失或需要外部决策时——向用户说明情况并提供选项。尽量不要升级；规范通常应该已有答案。
4. 集成并运行里程碑级验证。 将里程碑的分支合并到集成分支，解决冲突，并验证里程碑各部分能否协同工作（针对集成后的结果运行相关测试/验证）。如果任何工作者未按要求清理工作树，现在先将其移除（git worktree remove <path> --force），再继续。
5. 进入下一个里程碑。

需要了解状态时，请重新从磁盘读取相关规范文件和 PROGRESS.md，不要仅依赖上下文记忆。持续更新 PROGRESS.md——它是新编排者恢复 saga 时使用的事实来源，因此日志过时就意味着 saga 状态丢失。如果感觉上下文即将用尽，请先将简明的进度检查点写入 PROGRESS.md。

---

阶段 3 — 最终验证（编排者 + 用户）

目标：确认 saga 的退出标准已满足，然后交由用户进行手动验收。

1. 使用最强的可用方法执行完整的 saga 级退出标准（GUI/网页使用计算机操作，TUI 使用交互式命令行，否则使用完整测试/集成套件）。针对每项退出标准，总结相应证据。
2. 向用户提交简明的完成报告：说明构建了什么、如何验证每项退出标准，以及用户手动验证的具体步骤（如何运行/启动、检查什么）。
3. 通过 ask_user_question 邀请用户手动验收：接受，或报告具体问题。如果用户报告问题，将其记录为新任务，运行有针对性的阶段 2 小循环（委派 → 自行验证 → 集成），然后重新提交。重复此过程，直至用户接受。

只有用户确认接受后，才可认为 saga 已完成。

---

恢复 saga

由于 saga 目录和 PROGRESS.md 位于仓库之外并记录了完整状态，因此任何时候都可以由新的编排者接手 saga（上下文压缩、新会话或交接之后）。收到继续、恢复或接手 saga 的请求时，请阅读 references/continuing-a-saga.md 并遵循其中说明。

实用说明

• 除非用户要求，否则不要提交更改或创建 PR；如需执行，请遵循仓库的版本控制规则。
• 保持规范树内容最新——如果实现迫使范围或标准发生变化，请更新相关规范文件，不要让其与实际情况脱节。
• 对于规模很大的 saga（约 10 个或更多并发工作者），优先使用远程执行，以免耗尽用户设备资源。
• 除非用户提出要求，否则不要在面向用户的摘要中披露内部工作者 Agent ID。

参考文件

• references/saga-spec-template.md — saga 目录结构，以及 SAGA.md、MILESTONE.md、任务规范和 PROGRESS.md 的准确模板。起草规范前请阅读。
• references/validation-strategies.md — 如何选择验证方法、编写严谨的标准并收集充分证据。在阶段 1（标准）和阶段 2（执行）期间阅读。
• references/continuing-a-saga.md — 新编排者如何接手现有 saga 目录并安全恢复。收到继续/恢复 saga 的请求时阅读。