# 子代理标准协议

本文档定义了 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；不要跳过会话层直接改写上游真相源。

### 最终状态块中的会话字段

最终 `BOSS_STATUS` 除状态本身外，还要在相关时携带以下字段：

- `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轮）
```

### 标准状态块格式

```text
[BOSS_STATUS]
status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED | REVISION_NEEDED
summary: 一句话总结执行结果
conversation_id: [仅参与执行中会话时填写]
resolution_summary: [仅会话已收敛时填写]
todo_ids: [仅会话已 materialize 出 todo 时填写]
concerns: [仅 DONE_WITH_CONCERNS 时填写]
missing: [仅 NEEDS_CONTEXT 时填写]
blocker: [仅 BLOCKED 时填写]
revision_target: [仅 REVISION_NEEDED 或会话升级为正式修订时填写]
revision_reason: [仅 REVISION_NEEDED 时填写]
[/BOSS_STATUS]
```

---

## Wave 派发前写集校验

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

**派发规则**：
- 同一 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. **BLOCKED 是最后手段** — 先确认自己真的无法解决再报告阻塞
5. **保持原子性** — 一个子代理完成一个明确的任务单元
6. **尊重边界** — 不要做任务范围之外的事情，发现额外问题通过 DONE_WITH_CONCERNS 报告