subagent-protocol

子代理标准协议

本文档定义了 Boss 编排流水线中所有子代理必须遵循的标准化通信协议，包括状态报告规范和编排器的响应策略。

---

状态报告协议

每个子代理在完成工作后，**必须**使用以下五种状态之一进行报告。不允许使用自由格式的输出。

执行中会话层

Boss 以文档为正式媒介，但执行过程允许 Agent 之间通过短会话对齐差异、发起求助和落地修复。

• 任意 Agent 都可以向相关 Agent 发起执行中会话。
• 每条会话都必须带 `anchor`，锚定到 `artifact`、`task`、`scope` 或 `decision`。
• 统一会话原语：`ask`、`challenge`、`propose`、`request_change`、`escalate`、`huddle`、`resolve`。
• `resolve` 只在会话已经 materialize / materialized 为至少一个 executable todo，或升级为正式 `RevisionRequested` / `REVISION_NEEDED` 修订循环时成立。
• 若当前角色无权直接发起正式修订，先 `escalate` 给有裁决权的 Agent；不要跳过会话层直接改写上游真相源。

最终状态块中的会话字段

最终上报除状态本身外，还要在相关时于正文说明以下字段：

• `conversation_id`：本次任务引用的执行中会话线程 ID
• `resolution_summary`：会话收敛后的 1 句结论
• `todo_ids`：会话落下的 todo ID 列表
• `revision_target`：仅在会话升级为正式修订或状态为 `REVISION_NEEDED` 时填写

DONE

**含义**：任务已成功完成，所有验证通过，无遗留问题。

**报告要求**：

• 已完成内容的清单
• 测试通过情况（如适用）
• 变更文件列表

**编排器处理策略**：

• 记录完成状态到 `execution.json`
• 将产物传递给下游代理或下一阶段
• 无需人工介入

---

DONE_WITH_CONCERNS

**含义**：任务已完成且通过验证，但子代理发现了需要关注的潜在问题。

**报告要求**：

• 与 DONE 相同的完成信息
• 疑虑清单（每条包含：问题描述、潜在影响、建议处理方式）

**编排器处理策略**：

• 记录完成状态到 `execution.json`，标记 `has_concerns: true`
• 评估疑虑的严重程度：
• **低风险疑虑**：记录到日志，继续流水线，在最终报告中汇总
• **高风险疑虑**：暂停流水线，向用户展示疑虑内容，等待用户决定继续或回退
• 疑虑不会自动阻塞流水线，由编排器判断

---

NEEDS_CONTEXT

**含义**：缺少必要信息，无法继续或完成任务。子代理不会猜测——它选择停下来请求澄清。

**报告要求**：

• 已完成的部分（如有）
• 缺失信息清单（每条包含：需要什么、为什么需要、影响哪个决策）
• 建议的信息获取方式

**编排器处理策略**：

• 记录状态为 `needs_context`
• 尝试自动解决：
• 检查上游产物中是否已包含所需信息
• 检查项目文件中是否可以推断答案
• 查询其他已完成子代理的输出
• 如果自动解决失败：
• 向用户转发缺失信息请求
• 等待用户补充后重新派发任务
• 不会重试同一任务（信息不足时重试无意义）

---

BLOCKED

**含义**：遇到无法自行解决的阻碍，需要外部干预才能继续。

**报告要求**：

• 阻塞原因的具体描述
• 已尝试的解决方案及结果
• 需要什么外部变更才能解除阻塞
• 对后续任务的影响范围

**编排器处理策略**：

• 记录状态为 `blocked`，标记阻塞原因
• 立即暂停当前阶段
• 检查是否有可并行的不受影响的任务可以先执行
• 向用户报告阻塞情况，提供：
• 阻塞原因摘要
• 子代理已尝试的方案
• 建议的解决路径
• 等待外部干预后，由编排器检查状态并触发阶段重试

---

REVISION_NEEDED

**含义**：当前任务已完成评审/验证，但发现上游产物存在需要修订的问题。触发 Critic-Actor 反馈循环。

**报告要求**：

• 需要修订的上游产物名称（如 `architecture.md`）
• 修订原因清单（每条包含：问题描述、期望修改、影响范围）
• 当前任务的部分成果（已完成的部分可保留）
• 修订优先级：`critical`（阻塞继续）/ `recommended`（可继续但建议修）

**适用角色**：

• **Tech Lead** → 可对 `architecture.md` 发起修订请求
• **QA** → 可对代码产物发起修订请求
• 其他角色不允许发起 REVISION_NEEDED

**编排器处理策略**： 1. 调用内部反馈记录器追加 `RevisionRequested` 事件并物化状态 2. 检查 `feedbackLoops.currentRound`：若已达 `maxRounds`（默认 2），停止循环并报告用户 3. 继续按物化后的 `feedbackLoops.currentRound` 决定是否重派 4. 记录反馈事件 5. 重新派发上游 Agent 执行修订（携带修订原因作为上下文） 6. 修订完成后，重新派发当前 Agent 验证 7. 若验证通过（DONE/DONE_WITH_CONCERNS），结束循环

---

状态流转图

子代理启动
    │
    ├── 正常完成 ──────────── → DONE
    │
    ├── 完成但有疑虑 ──────── → DONE_WITH_CONCERNS
    │
    ├── 缺少信息 ──────────── → NEEDS_CONTEXT
    │
    ├── 无法继续 ──────────── → BLOCKED
    │
    └── 需要上游修订 ──────── → REVISION_NEEDED

编排器收到状态后的流转：

DONE                → 记录 → 继续下一任务
DONE_WITH_CONCERNS  → 评估风险 → 继续 / 暂停等待用户
NEEDS_CONTEXT       → 尝试自动解决 → 成功则重新派发 / 失败则请求用户
BLOCKED             → 暂停 → 报告用户 → 等待干预 → 重试
REVISION_NEEDED     → 记录反馈 → 检查轮次 → 重派上游修订 → 重新验证（≤2轮）

标准上报方式

状态是控制流输入，必须通过命令上报，由工具层校验枚举；不得用自然语言描述状态， 编排器也不会从散文中解析状态。

boss runtime report-agent-status <feature> <stage> <agent> <STATUS> --reason "<一句话总结>"

• `STATUS` ∈ `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED` | `REVISION_NEEDED`
• 非法值会返回 `invalid_agent_status` 且 `retryable: true`，需改用合法枚举重试
• 未上报视为「未推进」，不会被记为失败 —— 但下游门禁同样不会放行

补充字段（`concerns` / `missing` / `blocker` / `revision_target` / `revision_reason` / `conversation_id` / `resolution_summary` / `todo_ids`）在正文中说明，并按上文各状态的 「报告要求」给出证据；它们是给人和评审看的上下文，不参与状态判定。

---

Wave 派发前写集校验

进入 code 阶段时，编排器不得只按角色或前后端标签决定并行度。必须先从 `waves.json` 的 `writeSet` （或 `tasks.md` 中每个 Task 的「文件输出列表 / 写集」）解析计划写入路径，构建冲突图，再决定哪些任务可进入同一 Wave。

运行时的节点级调度遵循同一原则：`boss` 按写集不重叠分组派发，而非按 stage 分批 —— DAG 的 `inputs` 已表达数据依赖，写集冲突才是并行度的真实约束。

**派发规则**：

• 同一 Wave 的任务写集必须互斥；写同一文件、同一中央索引、同一依赖清单、锁文件、全局配置、`i18n.ts`、`store.ts` 等共享文件时，视为冲突。
• 共享文件必须指定 owner；非 owner 任务只能读取或在后续 Wave 集成，不得并行落盘。
• 文件输出列表缺失、路径为 `待确认`、或 owner 不明确时，返回 Scrum Master 修订 `tasks.md`，不要用临时 prompt 手工分地盘。
• 子代理的最终变更不得超出派发时分配的写集；确需新增写入路径时，报告 `DONE_WITH_CONCERNS` 或 `NEEDS_CONTEXT`，由 orchestrator 重新计算后再继续。

---

风险等级感知确认

固定阶段确认不足以覆盖高 Blast Radius 变更。code 阶段派发前，编排器必须读取 `tasks.md` 的 `Blast Radius` 与 `风险确认触发项`，在风险命中时先请求用户确认。

**强制确认 trigger**：

• 计划写入文件数达到项目阈值（默认 ≥ 10 个；项目可降低阈值）
• 修改依赖清单、锁文件、构建配置或部署配置，例如 `package.json`
• 需要运行依赖安装命令，例如 `npm install`、`pnpm install`、`pip install`
• 修改认证、支付、数据模型、迁移、权限、全局状态、路由入口等核心模块
• 删除文件、迁移数据、或执行不可逆操作

命中任一项时，不得派发 code Agent，直到 orchestrator 向用户展示风险摘要并取得明确确认。若用户已在本轮请求中明确授权对应高风险动作，记录授权来源后继续。

---

Wave 边界校验

子代理的 `DONE` / `DONE_WITH_CONCERNS` 只是声明，不是事实来源。编排器必须在每个 Wave 边界执行自动校验，校验通过后才允许进入下一 Wave、标记阶段 completed、或继续派发下游产物。

**触发时机**：

• 同一 Wave 中所有并行子代理均返回 `DONE` 或 `DONE_WITH_CONCERNS` 后
• 反馈循环修订完成并重新验证通过后
• 任何阶段状态从 running 准备进入 completed 前

**校验选择**：

• 按项目技术栈选择对应的类型检查、编译检查、测试套件、lint/格式检查等验证命令。
• 若项目有依赖清单或锁文件，检查这些文件的 diff 摘要；不限于 Node.js，也包括 Python、Go、Rust、Java、移动端等生态的等价文件。
• 若项目没有可运行的自动化校验，orchestrator 必须记录原因，并至少执行文件 diff 与产物一致性检查。

**处理规则**：

• 类型检查、测试套件、lint/格式检查等任一适用校验失败时，不得推进流水线；编排器将失败摘要交给对应实现 Agent 修复，然后重新执行本节校验。
• 依赖清单、锁文件或构建配置出现意外 diff 时，强制暂停让 orchestrator 看一眼：确认依赖新增、删除、锁文件变化是否与本 Wave 的任务和 Agent 报告一致。
• 若 package diff 合理，orchestrator 记录确认结论后继续；若 diff 来自过时副本覆盖、误删依赖或锁文件漂移，回退到对应 Agent 修复，不得等到 DevOps 阶段才发现。
• 子代理报告的变更文件清单只能作为线索；最终以命令输出和 git diff 为准。

---

模型选择策略

不是所有任务都需要最强的模型。编排器根据任务复杂度选择合适的模型，以优化成本和速度。

分级标准

| 等级 | 模型选择 | 适用任务类型 | 示例 | |------|----------|-------------|------| | **轻量级** | 低成本快速模型 | 机械性、模板化、规则明确的任务 | 格式检查、Lint 修复、简单的文件重命名、模板填充、状态更新 | | **标准级** | 中等能力模型 | 需要理解上下文但逻辑清晰的任务 | 集成测试编写、API 实现、组件开发、Bug 修复、代码审查 | | **旗舰级** | 最强推理模型 | 需要深度推理、全局视角或创造性的任务 | 架构设计、复杂算法实现、安全审计、性能优化方案、技术选型 |

选择决策树

任务是否需要创造性思考或全局架构视角？
├── 是 → 旗舰级
└── 否 → 任务是否需要理解多文件上下文或业务逻辑？
    ├── 是 → 标准级
    └── 否 → 轻量级

动态升级

如果子代理在低等级模型下返回 NEEDS_CONTEXT 或 BLOCKED，编排器可以： 1. 先尝试补充上下文后重试同等级模型 2. 如果仍然失败，升级到更高等级的模型重新执行 3. 升级记录写入 `execution.json` 用于后续优化

---

子代理通用规则

1. **必须使用标准状态报告** — 不允许自由格式输出 2. **必须在报告中列出所有变更文件** — 遗漏会导致审查不完整 3. **不确定时选择 NEEDS_CONTEXT** — 宁可停下来问，不要猜测后出错 4. **