saga

Saga

Saga 是一种自主的、规范驱动的开发工作流，适用于中大型功能，这些功能应在几乎没有人工干预的情况下实现，除了少数离散的接触点。你作为编排器：将粗略的提示转化为严密的规范，然后将实现委托给一组工作子代理，同时保持自己的上下文窗口干净。

整个方法基于一个假设：如果规范为每个任务定义了足够严格的验证标准以形成契约，那么工作代理可以并行执行并自我验证，saga 几乎不需要人工监督就能成功。因此，saga 的质量在阶段 1 就决定了，在编写一行代码之前。

核心原则

• 严密的契约胜过良好的意图。 只有当任务的验证标准足够明确，以至于满足它们几乎不可能出错时，该任务才准备好委托。模糊性是敌人；在规划期间解决它，而不是在实现期间。
• 不留空白。 在规划期间，使每个需求明确。除非用户明确授予了自由裁量权，否则不要将决策留给工作代理自行判断。工作代理永远不必猜测“完成”意味着什么。
• 保护编排器的上下文。 你是长期存在的协调者。将繁重的阅读、研究和实现推给工作代理；接收紧凑的报告。将状态保存在磁盘上（在 saga 目录的规范树和 PROGRESS.md 中），这样你的理解在压缩后仍然存在，并且你可以重新读取而不是重新持有。这最大化压缩时间，并使你在整个运行过程中保持连贯。
• 验证是一等公民。 每个任务和整个 saga 都带有预先定义的验证标准，以及检查它们的具体方法（计算机使用、交互式 CLI 或测试）。参见 references/validation-strategies.md。
• 少量人工接触点，而非零。 人工批准规范（阶段 1 结束），仅在规范确实无法解决阻塞时被咨询（阶段 2），并进行最终的人工验收（阶段 3）。

Saga 目录

每个 saga 位于其自己的目录中，在仓库之外，位于 ~/.sagas/ 下，这样它可以在编排器会话之间存活，并且可以被新的代理恢复。使用功能 slug 加时间戳唯一命名，例如 ~/.sagas/dark-mode-20260609-0028/。与用户确认确切路径并记录下来——这是 saga 的稳定标识。

该目录包含一个树结构的规范文件以及一个进度日志。每个级别带有自己的验证标准，因此细节随 saga 的大小而扩展，而不是使一个文件臃肿：

~/.sagas/<saga-name>/
├── SAGA.md                      # 概述、环境、saga 级退出标准、里程碑索引
├── PROGRESS.md                  # 实时、持续更新的执行日志和当前状态
└── milestones/
    ├── 01-<slug>/
    │   ├── MILESTONE.md          # 里程碑规范 + 里程碑级验证标准
    │   └── tasks/
    │       ├── 01-<slug>.md      # 任务规范 + 任务级验证标准
    │       └── 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 的契约，也是阶段 3 的基础。

5. 分解为里程碑和任务

将工作分解为里程碑（连贯的、独立有意义的块，按依赖关系排序），在每个里程碑内，分解为任务，范围限定为单个工作代理可以在一次集中努力中完成一个。对于每个任务，指定：范围、拥有的文件/界面、对其他任务的依赖关系，以及验证标准 + 验证方法。围绕功能的实际依赖关系实用地塑造拓扑——最大化可以在里程碑内并行运行的任务，并按顺序排列里程碑，使后续工作依赖于先前工作。

在 saga 目录中将其编写为规范树：里程碑索引和 saga 退出标准在 SAGA.md 中，每个里程碑的详细信息和里程碑级验证标准在其 MILESTONE.md 中，每个任务的详细信息和验证标准在其自己的任务规范文件中。每个任务的验证标准必须按照 references/validation-strategies.md 严密。如果你无法为任务编写严密的标准，则该任务规范不足——拆分它或返回用户。

6. 获得批准

展示 saga 规范——引导用户浏览 SAGA.md 和里程碑/任务规范——并要求他们批准或请求更改（通过 ask_user_question）。在用户批准之前不要开始阶段 2。 这是主要的人工检查点。

---

阶段 2 — 实现与验证（工作代理池，循环）

目标：逐个里程碑执行每个任务以达到其验证标准，委托给工作代理并保持自身精简。仅当阻塞无法从规范中解决时，用户才参与其中。

编排机制

• 委托，而非实现。 使用 run_agents 启动工作代理。你进行协调；你不自己编写功能代码。这保护了你的上下文。

• 按并行性分批。 在一个里程碑内，将所有独立任务作为一个 run_agents 批次启动（共享 base_prompt，每个任务有 prompt）。按顺序运行依赖的里程碑。使用任务依赖关系的 Mermaid/DAG 心智模型。

• 隔离本地工作代理。 当工作代理修改同一个仓库时，为每个工作代理提供自己的 git worktree 和分支。遵循 saga 分支命名约定，以便每个分支都可以追溯到其 saga 目录、里程碑和任务，而无需查阅 PROGRESS.md：

  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>/... 结构完整，以便分支保持可过滤。工作代理绝不能共享检出或在用户当前分支上工作。提前决定合并策略（通常：在里程碑边界集成每个里程碑的分支）。工作代理的更改必须在任何 worktree 被移除之前提交、推送或以其他方式持久移交。

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

• 远程工作代理用于计算机使用。 如果任务的验证需要计算机使用且仅远程可用，则远程启动该工作代理（或其验证步骤），启用计算机使用，并使其返回持久工件（推送的分支、草稿 PR 或紧凑的补丁/差异），而不是仅将工作留在远程环境中。

给予每个工作代理的任务契约

将共享规则放在 base_prompt 中（仓库路径、基础分支、工具链命令、编码标准、验证方法、如何报告），并将具体任务放在每个工作代理的 prompt 中。指示每个工作代理：

1. 仅实现其分配的任务和拥有的文件。
2. 在循环中自我验证，针对任务的验证标准使用规定的方法（计算机使用 / 交互式 CLI 子代理 / 单元 + 集成测试）。迭代修复→验证，直到所有标准通过或确实被阻塞。
3. 在清理之前创建持久移交。 对于本地 git worktree 任务，将验证后的更改提交到任务分支，并确保分支对编排器可见。对于远程任务，推送分支、打开草稿 PR 或返回完整的补丁/差异；不要将工作的唯一副本留在远程检出中。如果被阻塞但有部分有用工作，则在报告之前将其保存为 WIP 提交或补丁；如果没有值得保留的部分工作，则明确说明。
4. 仅在持久移交存在后移除 worktree：git worktree remove <worktree-path> --force。分支或补丁持久存在；worktree 不持久。过时的 worktree 是不可接受的，但清理绝不能丢弃已验证或有用部分工作的唯一副本。
5. 紧凑地报告：分支名称、提交哈希或补丁/推送分支工件、更改的文件、验证证据（测试输出、截图、CLI 转录），以及明确的通过/阻塞状态。保持发现简洁——你正在保护上下文。

参见 references/validation-strategies.md 以选择和应用验证方法，以及什么构成充分证据。

编排循环

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

1. 启动里程碑的可并行任务作为工作代理。立即在 PROGRESS.md 中记录每个工作代理的可寻址代理/运行 ID，以及其任务、分支和 worktree。显示名称不足以用于恢复；新的编排器需要运行 ID 来与进行中的工作代理通信。
2. 收集报告（读取工作代理的消息内容；不要仅依赖生命周期成功）。在 saga 目录的 PROGRESS.md 中更新每个任务的状态和证据指针。
3. 处理阻塞的任务。 如果工作代理无法满足其标准，则决定：重新范围并重新委托给同一工作代理（它保留上下文），在其任务规范文件中调整任务，或者——仅当阻塞是真正的规范空白或外部决策时——升级给用户并提供选项。优先不升级；规范通常应有答案。
4. 集成并运行里程碑级验证。 将里程碑的分支合并到集成分支，解决冲突，并验证里程碑整体成立（在集成结果上运行相关测试/验证）。如果有任何工作代理尽管有指示仍留下 worktree，现在移除它（git worktree remove <path> --force），然后再继续。
5. 移动到下一个里程碑。

每当需要状态时，从磁盘重新读取相关的规范文件和 PROGRESS.md，而不是将其保留在上下文中。随着进展保持 PROGRESS.md 更新——它是新编排器用于恢复 saga 的事实来源，因此过时的日志意味着丢失的 saga。如果你感觉上下文已满，首先将简洁的进度检查点写入 PROGRESS.md。

---

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

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

1. 使用最强可用的方法（GUI/Web 使用计算机使用，TUI 使用交互式 CLI，否则使用完整的测试/集成套件）运行完整的 saga 级退出标准。针对每个退出标准总结证据。
2. 向用户呈现简洁的完成报告：构建了什么，每个退出标准如何验证，以及他们手动验证的确切步骤（如何运行/启动，查找什么）。
3. 通过 ask_user_question 循环让用户进行手动验收：接受，或报告具体问题。如果他们报告问题，将其捕获为新任务，运行集中的阶段 2 小循环（委托→自我验证→集成），并重新呈现。重复直到用户接受。

仅在用户确认接受时认为 saga 完成。

---

恢复 Saga

由于 saga 目录和 PROGRESS.md 位于仓库之外并捕获完整状态，saga 可以在任何时候被新的编排器接手（在压缩、新会话或移交之后）。当被要求继续、恢复或接手 saga 时，读取 references/continuing-a-saga.md 并遵循它。

实用说明

• 除非用户要求，否则绝不提交或打开 PR；在这样做时遵循仓库的版本控制规则。
• 保持规范树最新——如果实现迫使范围或标准发生变化，则更新相关规范文件，而不是让其偏离。
• 对于非常大的 saga（约 10 个以上并发工作代理），优先使用远程执行，以免耗尽用户的机器。
• 除非被要求，否则不要在面向用户的摘要中暴露内部工作代理 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 时阅读。