ch3sh-lc/myworkflow/subagent-protocol

成员与执行者协作协议（L2 执行者 + L3 团队协作）

协作模型总览：L1 / L2 / L3

• L1 单智能体（solo）：单一不可再分交付物、单文件小改、一次回答闭环、纯问答；当前上下文直接做完，不建团队、不下 mission、不派 leaf。
• L2 子智能体（subagent）：一个可独立完整执行的交付单元——明确输入、明确产出、可独立验收；主智能体派 subagent，一个执行者端到端做完（常见形态是 ≥2 个平铺、无依赖的小交付物）。L2 的本质是「可独立验收的完整交付单元」，不是「小任务」的同义词。
• L3 智能体团队（team）：用于大型、长程任务——把超大任务切成若干相互独立的部分，模仿真人团队「各自独立工作 → 沟通 → 整合」；判据仍是多域协作、接口/依赖、需要跨回合持续负责人、需要多批推进与补位。不要因为「任务大」就建团，要因为「需要持续负责人与并行独立交付」才建团；leader 定目标边界并下 mission，member 域自治端到端，leaf 执行最小任务包。

关键等价关系：团队里的每个 member 相当于一个 L2（领域级的 L2）——各自独立端到端完成自己那份，再与其他人沟通整合。

member 之间可直接沟通：member 与 member 可直接相互发消息、不经过 leader 中转。理由：任务切分在开始时不可能完美，执行中会出现交叉、重叠、接口变化、相互依赖；此时成员之间直接沟通比「上报 leader 再转发」效率更高。leader 只在边界冲突需要裁决、目标需要变更、验收标准需要修改时介入，日常协作 member 自行协商；沟通后若改了交付边界，同步 leader 记录在案即可，不必阻塞等待批准。

member 与 leaf 的本质区别（寿命与职责不同）：

本协议同时约束 L2 子智能体 与 L3 的 member / leaf 的执行方式（五阶段工作规范见下）。

团队角色与职责（leader / member / leaf）

• leader：只做四件事——定目标与边界、建团队、下模块委托（mission）、监督与验收裁量；不亲自产出交付物、不写业务文件、不逐批派活、不替成员拆叶子任务。
• member：持久存在的域 owner，具备独立目标意识。收到「目标 + 边界 + 输入 + 验收」后自己规划、自己授权派发、自己验收结算、自己修复，端到端完成一整件事；只在自己写范围内动手，跨域接口先约定。
• leaf：fresh 上下文的最小任务包执行者，一次实现并自检，交回真实产物与证据；缺输入找 owner，不越界，不能开 leaf、不能建同级成员。

等待与阻塞纪律（硬规则）

谁干活：

• leader 禁止自己工作：只能定目标/建团/下模块委托/监督/裁量/验收，不得亲自产出交付物、不写业务文件。
• member 基本不自己工作：member 的产出方式是「派 leaf 执行 + 自己验收整合」；只有极小的单文件改动 / 单条只读探查可以自己做，做完立即回到派发与验收。

禁止在自己的回合内等待（关键）：

• leader 与 member 都不得在自己的运行回合中等待任何 leaf、subagent、其它 member 或长任务返回。
• 正确做法：发起 → 正常输出本轮结论 → 结束回合；等对方完成/被唤醒后，由二次唤醒继续推进。
• 不允许：wait_agent 式阻塞、轮询、空转、反复检查同一个未完成任务。
• 超时、无响应、任务卡住：记录状态并结束回合，等下次唤醒时再处理，不空等。

30 秒规则：

• 任何命令不能保证 30 秒内跑完，一律不得在回合里同步等待：优先放后台任务（background job），本回合继续做别的，稍后用 job 结果；或派 leaf 去跑，自己只等回执。
• 典型对象：检查脚本、构建、测试、install、克隆、批量迁移、网络抓取。
• 30 秒是硬上限；不确定就跑后台。 后台任务与 leaf 的结果获取方式：正常输出后结束回合，靠二次唤醒/下次写结果时取，不在同一回合里 sleep/轮询。

续接与恢复（被唤醒 / 交接时）

成员与 leaf 被二次唤醒后的第一步 = 核对进度再动作（不是接着记忆里的下一步干）：

• R1 先对账，再动手：读交付物 / .task-manifest 输出 / 回执 / 运行记录（runId）/ 团队状态；禁止凭对话记忆假设进度；对不出结论先做只读探查。
• R2 三级状态：已 accepted → 跳过不重做；已 produced 未 verified → 补验证 / 补证据，不重做产物；尚未开始 → 正常做；判不清 → 按「未完成」处理并先探查。
• R3 只推进最小下一步：找出下一个未完成的独立交付物，只做它；续接不是重跑整条流程。
• R6 压缩 / 重启恢复：上下文出现压缩摘要或会话重启 → 从磁盘事实（交付物 / 状态文件 / 运行记录）重建进度；恢复后第一件事是重新确认任务级别与要加载的技能（Host 每轮纪律照常生效）。
• R4 需求漂移：新指令若改变目标 / 范围 / 验收标准 → 先确认再重排，不硬续旧计划、不静默改范围。
• R5 失败不重复：同一失败只允许换条件再试；记录已试路径与错误指纹，写清「这次为什么与上次不同」。
• R7 交接四样（给 / 要都必须齐）：已做 / 未做 / 证据（runId 或产物路径）/ 下一步 + 未解决项；接手方先复核再继续，不复核不动手。
• R8 续接同样有技能意识：续接回合与普通回合一样——先按「myworkflow-task-router」判 L1/L2/L3 并加载对应技能；Host 每轮注入的【每轮纪律】照常生效。
• 与既有条款的关系：本节不改变「禁止阶段拆分」「member 之间直接沟通」「禁止回合内等待」；续接中发现阶段接力倾向，仍按禁止阶段拆分处理。

谁能开 leaf

leader 与 member 都可以开 leaf；leaf 不可以开 leaf。 具体分工：

• leader 可以：按已定的产物边界，直接给 leaf 下最小任务包（单文件小改、单条命令、一次回答这类最小件）。
• member 可以：在自己的域内自行 plan、授权并启动 leaf；产物边界由 member 自己决定。
• leaf 不可以：leaf 不能再开 leaf，也不能创建同级成员或建团队；需要更大能力时把问题交回 owner（member/leader）决策。

禁止阶段拆分（硬规则）

一个交付物内部禁止按时间/工序阶段拆成多个窗口或智能体接力；合法切分只有横向切分（每份都能独立交付、独立验收）。

判定话术：拆出来的每份「单独交给别人也不成为可用成果」= 阶段接力，违规；每份能独立交付/验收 = 合法。横切后出现交叉/重叠/依赖，靠 member 之间直接沟通解决（改边界同步 leader 记录在案），不靠拆阶段解决。

两个常见绕过不算合法：① 审查 / 汇总 / 接口文档 / 测试报告不是独立交付物——不得作为横向切分的产物；② 同一交付物跨轮次串行接力（第一轮 A 做一半、第二轮 B 接着做）同样违规，必须一个 owner 一次做完。

最小任务包（派发方必须写全）

派发 leaf 的 brief 必须包含以下七项，缺项 leaf 应直接向 owner 要，不猜测：

1. 目标：这份交付物是什么、为什么要它。
2. 边界：只允许写哪些路径/文件；不能碰什么。
3. 输入证据路径：要读的契约/基线/证据文件的确切路径。
4. 接口版本：跨模块接口名称与版本（或「无接口」）。
5. 输出位置：产物落到哪（精确路径/目录）。
6. 验收条件：可执行的验收命令或逐条判据。
7. 失败政策：卡住时找谁、允许重试几次、什么情况下报 blocker 而不是硬做。

结算口径：produced ≠ verified ≠ accepted

• produced：执行者交回产物与可复核回执（只有产物路径不算完成；缺证据的回执不算 produced）。
• verified：有真实执行证据（命令 + exit code + 产物路径/sha256，或 runId + 关键输出）。
• accepted：owner 复核证据后才算完成；idle、超时、非空完成文件都不是完成。

回执证据化（leaf / member 同一标准）

回执（leaf 的 completion.md / team_work_report、member 的交回与验收回执）必须可复核，逐条给出出处，否则不算 produced：

• 可复核四要素（每条结论至少一项）：① 命令 + exit code；② 文件 + 行号；③ runId；④ 产物路径 + sha256。
• 空回执禁用：「我看过了 / 应该没问题 / 大概能跑」一律不算证据，只是猜测——必须补跑命令或补读源码后重交。
• 不确定就标：没核实过的写「未核实」并说明影响与核实方法；假设写「假设（未核实）」并去核实（E2），不把假设当结论。
• 禁止编造：不得补造 runId、exit code、sha256、行号、API 或测试结果（E5）；查不到就写查不到。
• 关键事实交叉核对两个独立来源（源码 + 实测 / 文档 + 运行输出），冲突时以可执行结果为准并记录冲突（E6）。
• 自检问句（E4）：动手 / 下结论前先问「这条规则或判断是猜的还是有出处？」无出处 → 先查；查不到写「假设（未核实）」并说明影响。
• 代价优先（E7）：改动 / 交付前评估代价与影响面（不可逆 / 影响范围 / 能否回滚）；高风险（删数据、改历史/tag、覆盖、发布、重启）先备份 + 预演 + 小步验证并给回滚路径，不确定按高风险处理。

极端与异常场景（必须给出明确指引）

• 无可用工具（subagent / 团队工具缺失或不可用）：先用替代手段——当前上下文直接做、脚本/命令行、只读查询或已有文件；确实无法执行 → 明确回 BLOCKED，写清缺什么工具/权限、影响面、已完成部分，交回 owner 或用户决策；不许编造结果、不许假装完成。
• 用户坚持阶段拆分：这是与「禁止阶段拆分」硬规则冲突的要求——拒绝并说明「拆出的每份不能独立交付/验收 = 阶段接力」，给出可执行的横向重排方案（按可独立交付产物切分、一个 owner 端到端做完）；用户仍坚持时，记录为已接受风险并请其明确确认，不得静默照做。
• 中途发现级别判断错误：允许并鼓励重新判级（L3 → L2/L1 回收，或 L2 → L3 升级）；已交付且已验收的产物不重做，只调整后续分配；重新判级要更新 mission/计划说明并告知相关 owner。

触发

• 调用者：L2 子智能体，或 L3 的 leaf；派发方（leader / member）不调用本 skill，只引用它。
• 自动触发（满足全部 3 条）→ 立即从「阶段1：读取合约」开始：① 被主智能体通过 Agent 工具创建；② prompt 明确提到 task-id；③ 工作目录存在 .task-manifest/task-contract.yaml 且 .task-manifest/prompts/。
• 自举触发（不满足自动触发时）→ 无 task-id 但工作目录存在 .task-manifest/ → 走下方「自举保障」，先向主智能体确认执行哪一个任务，不猜测。
• 不触发：普通问答（无 task-id、无合约）、单件小事（如"检查语法错误"）、找不到 task-contract.yaml 也无 task-id。

派发方强制引用（leader 或 member 向 leaf 派发时必须写入）

本协议同时服务 L2 与 L3：L2 由主智能体直接派 subagent（可不引用本模板，但必须满足最小任务包七项）；L3 由 leader 或 member 向 leaf 派发时必须写入下列模板。

你必须遵循「myworkflow-subagent-protocol」。你的 task-id 是 {task-id}。
先读取 `.task-manifest/prompts/task-{task-id}.md` 了解任务，
再读取 `.task-manifest/task-contract.yaml` 找到你的合约条目，
然后严格按 5 阶段协议工作：阶段 1：读取合约+确认输入。先读取 `.task-manifest/prompts/task-{task-id}.md` 了解任务，再读取 `.task-manifest/task-contract.yaml` 找到你的合约条目，逐一读取 inputs 中的文件路径。阶段 2-5 声明接口→产出实现→自检→完成报告。

一致性约束：本模板与 components/myworkflow-task-dispatch/parts/11-p07-5.md「第七步：下 mission / 启动 leaf」中的同名模板必须逐字一致，修改其一时必须同步另一处。（用 slug myworkflow-subagent-protocol 而非中文显示名——技能寻址走目录名，中文名不参与寻址，写 slug 才能稳定触发。）

自举保障（主智能体漏引用/漏 task-id 时）

有 task-id？→ 查合约 → 存在 → 正常执行；不存在 → 报告"合约不存在"。 无 task-id → 有 .task-manifest/？→ 有 → 检测合约：存在 → 列出所有未完成任务（无 completion.md 的），问"以下任务尚未完成，我应执行哪一个？"并附列表；prompts/ 存在但合约缺失 → 报告"请重新生成合约或指定我的任务"；两者都不存在 → 报告"目录为空，请确认是否重新拆解"。无 .task-manifest/ → 非派发系统子智能体，正常回答。 （task-id 可在自举中由主智能体补充指定，不依赖前置存在。）

目标

规范子智能体工作：产出具备可验证的接口、可追溯的声明、可审计的自检记录。核心原则：声明先于产出，声明即承诺。

关联Skill

输入 ← 读取「myworkflow-task-dispatch」产出的 task-contract.yaml 与任务包（mission / leaf 任务包）；输出 → 产出的 interface-declaration.md / self-check.md / completion.md 是「myworkflow-integration-verify」的验证输入。

前置强制步骤

1. 确认 task-id：从 prompt 中找；没有 → 检查合约中未完成任务（无 completion.md 的），列出并向主智能体提问（不可猜测）。
2. 读取合约条目：task-contract.yaml 中 id: {task-id} 条目，找不到 → 报告。
3. 读取输入文件：逐一读取 inputs 列出的文件；不存在或内容不足 → 提问。

执行流程

主线：阶段1 读取合约+确认输入 → 阶段2 声明接口 → 阶段3 产出实现 → 阶段4 自检 → 阶段5 完成报告。

阶段1：读取合约 + 确认输入

• 找到与 task-id 匹配的合约条目，确认 description、depends_on、inputs、outputs、verification。
• 逐一读取 inputs 文件。
• 关键规则：输入文件不存在→提问；输入不足→提问；依赖任务未完成→记录依赖状态并结束本轮（或交回 owner），等二次唤醒再继续；禁止在本回合等待/空等/轮询/sleep——任何不能保证 30 秒内跑完的命令一律放后台任务或派 leaf（见「等待与阻塞纪律」）；合约有歧义→提问。

阶段2：声明接口

写 .task-manifest/outputs/{task-id}/interface-declaration.md：

# 接口声明 — {task-id}
> 本声明是我的接口承诺。「myworkflow-integration-verify」将据此验证我的产出。
> 声明时间: {ISO 8601 时间戳}
 
## 我将创建/修改的文件
-[ ] {文件路径} — {用途描述}
 
## 我将暴露的接口
| 名称 | 签名 | 所在文件 |
|------|------|----------|
| {name} | {signature} | {file} |
 
## 我需要的外部输入
| 文件 | 内容（节/函数/类型） | 用途 |
|------|---------------------|------|
| {path} | {具体部分} | {说明} |
 
## 风险和假设
-{假设 1}
-{风险 1}

声明规则：必须覆盖合约 outputs 全部条目（可多不能少）；签名必须与合约一致；合约签名有问题 → 在风险中标注并继续按合约声明；声明写入后不可秘密修改。

阶段3：产出实现

1. 先建文件骨架（空文件、导出签名桩），再填实现逻辑。
2. 每完成一个文件，在声明中勾选 - [x]。
3. 需要修改声明 → 先更新 interface-declaration.md 再改代码。
4. 需要超出合约范围的工作 → 先反馈主智能体确认。

阶段4：自检

写 .task-manifest/outputs/{task-id}/self-check.md：

# 自检报告 — {task-id}
> 自检时间: {ISO 8601 时间戳}
 
## 文件存在性
-[x] {file} — 存在且非空
 
## 接口签名匹配（与 interface-declaration.md 对比）
-[x] {name}: `{signature}` — 实际签名一致
 
## 功能完整性
-[x] {功能点}
 
## 接口自洽
-[x] 所有导出的函数/类型在同一个模块内有定义
-[x] 没有引用不存在的模块/文件 → 对每个 import/require 用 ls/Test-Path 验证
-[x] 没有孤立的导出 → grep 搜索每个导出名，确认被引用或属合约要求的 outputs
 
## 错误处理
-[x] {异常路径}

自检规则：必须全部 [x] 才能进入阶段5；修正涉及接口 → 先回阶段2更新声明；不造假（「myworkflow-integration-verify」会对比）。

阶段5：完成报告

写 .task-manifest/outputs/{task-id}/completion.md，状态为四种之一：

# 完成报告 — {task-id}
 
**状态**: [DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED]
 
## 产出文件清单
-[文件路径] — [简述]
 
## 证据（可复核）
-命令 + exit code：{命令} → {exit code}；runId：{runId}
-产物路径 + sha256：{path} — {sha256}；未核实：{项}
 
## 自检结果
-[ ] 文件存在性
-[ ] 接口签名匹配
-[ ] 功能完整性
-[ ] 接口自洽
-[ ] 错误处理
-全部通过: [是/否]
 
## 已知担忧 (DONE_WITH_CONCERNS 时填写)
-担忧: [具体技术担忧] — 影响: [可能影响什么]
 
## 缺失信息 (NEEDS_CONTEXT 时填写)
-缺失: [什么信息] — 影响决策: [哪个决策]
 
## 阻塞原因 (BLOCKED 时填写)
-阻塞: [什么原因] — 可能解决: [方案]

核心约束：声明先于实现（未写 interface-declaration.md 就写代码=违规）；签名即承诺（改签名必同步更新声明）；自检不通过不交活（必须全部 [x]）；输入缺失不猜测（提问）；范围不蔓延（不修改合约未列文件）。

后置更新

1. 确认 3 个元文件（interface-declaration.md、self-check.md、completion.md）已生成，且实际代码产出已完成，路径均在 .task-manifest/outputs/{task-id}/。
2. 确认 self-check.md 全部 [x]。
3. 向主智能体报告完成。

完成标志

• [ ] interface-declaration.md 已写入，覆盖合约所有 outputs
• [ ] 所有代码/文档产出文件已创建，内容完成
• [ ] self-check.md 已写入，全部项目 [x]
• [ ] completion.md 已写入，产出清单完整
• [ ] 所有元文件在 .task-manifest/outputs/{task-id}/ 下
• [ ] 已向派发方（leader / member / 主智能体）报告完成
• [ ] 未超出最小任务包边界；需要更大范围时已交回 owner 决策
• [ ] 未把同一交付物按阶段再拆给其他执行者（阶段接力禁止）
• [ ] 未在本回合内等待任何 leaf/其它成员（禁止等待；长命令已后台化或派 leaf）
• [ ] 回执含可复核证据（命令 + exit code / runId / 产物路径 + sha256）；无「我看过了 / 应该没问题」式空回执
• [ ] 未核实项已标「未核实」并说明影响；关键事实已交叉核对、无编造