Agent-System/.doc/ops/2026-09-24-subagent-workflow-standard.md

主 Agent 与 Subagent 协作流程规范（草案）

修订：subagent-workflow-2026-09-24-r2；owner：Codex；规则状态：proposed；执行能力：manual；effective_commit：无。 本流程规范仍为待审稿；用户已确认 Cursor 实施、本机 PI 分析/审查/验证及模型默认分工，具体值唯一维护在模型配置。规则批准与受控集成后才进入 active；文档存在不表示 PI 调度器已接入。 研究与来源见研究报告，本次授权及交付状态见任务。

1. 目标、适用范围和权威

用户在 Cursor 主会话保持 Auto；Cursor 负责主协调、代码实施和修复，通过 gmktec 本机工程 PI CLI 委派分析、审查、测试和报告。每阶段产生可恢复记录。此配置不自动适用其他客户端或 Herdr。

本规范只定义角色、阶段、交接和证据引用。授权边界沿用 AGENTS，写锁/候选合并/环境/清理沿用 worktree 操作规范，测试层级沿用验证契约，问题闭环沿用既有规范。不建立第二套测试门禁。

普通 Cursor 会话不启用 Herdr 角色和固定模型路由；只有明确使用 Herdr 时适用其专门规范。工程 subagent 与产品 PI Agent Runner 分开记录，前者的执行不能替代后者的验收。

2. Auto、授权和推进规则

• 模型策略：主会话选择 Auto；PI 子任务按模型配置的角色、provider 和 model 派发。Cursor 原生 subagent 的 model: inherit 方案已被用户后续选择替代，本规范不以 .cursor/agents 实现 PI 路由。
• 能力核验：首次接入、客户端升级或模型行为异常时，记录客户端版本、角色可发现性、派发 ID、工作目录、配置模型策略及可观察的实际模型；不可见时写 actual_model=unknown。不得从自我介绍推断模型。
• 证据边界：记录配置指定值与可核验的实际模型；未核验不声称模型调用成功。模型多样性不替代独立上下文和证据。
• 授权策略：Auto 只表示模型选择，不表示自动授权 shell、外部写入、合并、部署、推送或删除。任务开始记录已有授权，后续不重复询问相同范围。
• 默认确认点（待用户采纳）：需求形成、评估、方案编制可连续进行；方案可审后，一次确认方案与实施范围。已明确授权按该方案端到端执行，则该确认已经满足。只有范围/环境/外部副作用扩大、破坏性动作或需要用户作业务取舍时再确认。
• 验收人：需求阶段明确 acceptance_owner。技术验收检查可由获授权 acceptance_check 执行；产品效果/业务取舍需要用户判定时，技术通过后保留 acceptance=pending，不由 Agent 代签。用户预先委托按明确客观标准验收时，记录委托来源和证据即可。
• 仅请求研究/方案的任务交付可审产物后结束。实现、运行验证、合并等阶段逐项写 not_applicable + 原因，不为了流程齐全擅自执行。

3. 标准流程

flowchart TD
  A[建场与授权记录] --> B[形成需求和验收标准]
  B --> C[评估需求与影响]
  C --> D[制定方案和验证计划]
  D --> E{实施授权是否满足}
  E -->|是| F[实施和开发自测]
  E -->|否| P[交付可审方案]
  F --> G[独立代码审查]
  G -->|需修改| F
  G -->|通过| H[冻结交付版本并验证]
  H -->|失败| F
  H -->|通过| I[构造候选并验证合并结果]
  I -->|通过| J[受控合入 dev]
  J --> K[按授权部署与运行验收]
  K -->|失败| R[保留现场并修复或交接]
  R --> F
  K -->|通过或不适用| L[确认交付并归档证据]
  L --> M[owner退出后独立复查清理]

测试计划在方案阶段形成；自测贯穿实施；独立审查和必要测试必须覆盖最终版本。清理安排在验收与证据保存之后。合并前的工程验证与合并后的运行验收分别报告。

阶段、产物和放行条件

每行都是阶段记录要求，不要求每行一个文件。记录使用阶段模板。

阶段	责任与输入	最小产物	放行条件 / 失败去向
S0 建场	主 Agent；用户请求、当前规则、Git/认领状态	task 主记录：目标、授权、基线、写路径、环境、交付终点、policy_revision	允许范围明确；持久成果在任务 worktree；按现行入口登记
S1 形成需求	Cursor 与用户，可委派 research/planning；原始描述	需求记录：用户场景、范围/非目标、R-ID、AC-ID、优先级、验收人	可验证预期明确；影响方案的歧义解决，小型假设标注
S2 评估需求	requirements_review；S1 和当前证据	评估报告：现状差距、替代方案、依赖、风险、复杂度和建议	结论为 proceed / revise / defer；高风险未知有验证路径；revise 回 S1
S3 制定方案	Cursor 协调 planning 编制、plan_review 独立复核；S2	方案：改动位置、接口/数据影响、实施依赖、写者、验证矩阵、恢复方案；附方案审查结论	AC 映射到验证项；必要权限齐备；授权不足交付方案等待；设计疑问回 S2
S4 实施与自测	Cursor；已授权方案	实施记录：变更、提交、偏差、自测与失败记录	实现满足方案且自测有证据；范围变化回 S1/S3；不得降低 AC 迁就实现
S5 独立代码审查	code_review；需求/方案、base/head、完整差异	审查报告：范围、审查者、严重度、位置、依据、处置与复核	无未解决阻断项；修复回 S4，变更后的代码需复核
S6 交付验证	test_run；冻结版本、AC、验证契约	测试报告：预期用例、实际命令/输入/输出、环境、SHA、PASS/FAIL/SKIP/未运行	适用必需项均通过；SKIP/基础设施失败保留阻塞；失败回 S4 或 S3
S7 候选与集成	串行集成执行者；S5/S6、最新 dev D、冻结 T	集成报告：D/T/M、候选验证收据、锁内结果、实际 dev	按现行 --no-ff 候选与 --ff-only 入口；D/T/M 变化须重新准入
S8 运行与交付验收	acceptance_check + acceptance_owner；受控制品、AC	验收报告：实际制品、环境、用户流程、持久状态、逐项 AC 结论	所需运行/UI 验收通过；无运行影响写 not_required；失败不清理、不冒充完成
S9 归档与清理	主 Agent 固化证据，owner 退出后维护者执行清理	收口报告：提交/集成/部署/远端/cleanup 分离；归档证据、清理结果与遗留 owner	满足现行普通 remove/-d 条件；拒绝保留 pending，登记触发和接管者

S5 与 S6 可以在同一不可变版本上并行；必要产物必须都回来才能进入 S7。测试产生构建目录/缓存/数据也算写副作用，先核对其环境和锁。code_review 阅读稳定 Git 快照，不在 Cursor 正在改写的工作树上宣布最终通过。

S7 候选需执行该范围的真实检查，不能用分支自测替代合并结果验证。S8 后新增的报告提交也需受控集成；分别记录被测业务 SHA 与报告 SHA，说明仅文档变化的复用依据。影响运行内容的后续变更使相关验收失效。

4. 角色和分工

角色是职责，不要求每阶段单独启动一个进程。精确 role_id、enabled、默认模型和升级链只维护在模型配置，下表说明权限边界。

角色	职责	写权限和独立性
Cursor / coordinator	与用户对话、授权核对、任务图、派发、证据汇总、冲突处理、推进门禁和交接	唯一任务协调者；报告汇总不改变原作者/证据/结论；不能从子报告推导额外授权
research / planning / report / stage_notes	需求影响、方案、资料和报告	默认只读；返回结构化报告，由主 Agent 落盘；若编制方案，另一个上下文审查方案
Cursor / implementation	实施方案、修复问题、编写和修改测试源码	产品和测试源码的实施者；按认领/租约操作，PI 建议交回 Cursor 处理
requirements_review / plan_review / code_review / diagnosis	独立评估、审查与复杂故障归因	新的只读上下文；不修改被审内容；发现问题返回 Cursor；复现交给获授权的 test_run
test_run / acceptance_check	按冻结 AC 和已批准计划执行验证，核对真实行为	仅写批准的测试产物/环境；不改源码、不代签最终验收，需要修复交回 Cursor
integrator / maintainer	候选验证、受控合并；owner 退出后的清理	串行短时角色，使用现有工具/权限；不能把长驻 worker 同时当作可删除的 worktree owner

同模型的独立上下文可以提供独立检查，但不消除共同盲区；验证仍以源码、命令和用户流程证据为准。主 Agent 自审只能记录 self_review。要求独立审查的代码任务如无 subagent 能力，交给另一个独立会话/人员；该项完成前不自动放行。低风险纯文档可自检并记录理由。

5. 何时派发与如何并行

• 适合派发 PI：较长只读研究、独立审查、按批准计划验证、报告整理。代码实施和修复保留给 Cursor。
• 主 Agent 直接处理：一次定位、简短文案、单一顺序操作；仍留下对应阶段记录。无需为了覆盖阶段机械启动九个 Agent。
• 并发上限及递归委派规则以模型配置为准；资源不足串行。它是项目预算，不是平台上限；子 Agent 发现进一步分解需求先返回建议。
• 先画依赖再并行；有先后依赖的任务等待前置证据。有相同文件、公共 lockfile、路由、迁移号或共享环境的写任务不能同时认领。
• 同一任务 worktree 的源码写者为 Cursor，PI 只读任务读取冻结快照；只读报告由 Cursor 持锁保存。PI 验证涉及产物/环境写入必须在有效 agentctl supervisor 下运行；无法保证时停止执行并报告条件缺失。
• 若另行开展多 Cursor 并行实施，仍须独立登记 worktree，各自从明确 dev SHA 创建；父子关系用 parent_task_id/subtask_id 关联。此条不授权 PI 实施代码。
• 父任务汇总子任务成果，源码仍由 Cursor 实施。涉及测试产物写入的子任务登记独立操作 ID/路径；只读子审查复用父任务文档，不重复创建任务链。子分支结果通过现行候选集成流程交付；不能由 Cursor 的自动隔离/自动合并绕过本仓注册和准入。
• 有后台任务时，主 Agent 可继续独立工作，但不得在结果未回收时发布依赖它的 PASS、合并或清理。各子任务的工具可用性不代表授权可用性。

6. 派发、回传与失败处理

每次派发至少包含：

1. parent_task_id、subtask_id、role_id、具体目标、输入版本（需求/方案/代码 SHA）；配置路径、config_revision、文件 SHA-256、解析后的 provider/model 和任务覆盖依据。
2. 需要读的规范和证据、已有用户授权来源、明确的非目标。
3. 工作目录、允许写路径、环境、mutex/租约执行方式；只读者明确只读。
4. 完成条件、输出格式/报告路径、需要验证的 AC；子 Agent 不依赖未传入的主会话历史。
5. 预算（时间或步骤）、进度回传点、失败/超时和副作用核对方式。

回传至少包括：执行身份/PI run_id、配置版本与指定/实际模型、实际输入版本、结果与证据、变更文件/提交、实际命令与环境、结论、缺项/风险、遗留进程/产物。主 Agent 校验路径、版本和证据后标记 accepted；子 Agent 自报 done 只表示执行结束。

• 分开记录 run_status（running/succeeded/failed/cancelled/unknown）与 verdict（pass/changes_required/blocked/not_applicable），不可把退出成功等同质量通过。
• 超时/失联先检查进程、worktree、Git 和外部副作用；结果未知时保留 unknown，不同时重派同一写任务。纯只读且确认无副作用的失败可有限重试，并保留原记录。
• 审查/验证角色有异议时，主 Agent 依据原需求和证据裁决。能修复则回 S4；需要业务取舍则向用户汇总一个关键问题，不以多数投票覆盖阻断证据。
• 连续两轮修复仍未解决同类阻断时，停止机械重试，回 S2 重查机制/测试前提；授权内可继续研究。不得为放行删除失败用例或降低 AC。
• 用户中断、客户端退出、上下文压缩时，先固化阶段、版本、未回收子任务、owner 和接管条件；恢复后从首个未满足门禁继续，不能整条流程重跑或直接跳到收口。

7. 文档与报告契约

“一步一记录”，无需“一步一文件”。现有文件优先复用，原始证据只存一处：

任务类型	最小文档集合
信息问答，无持久成果或运行副作用	对话答复
小型规范/研究/低风险变更	一个 task 或分析主文档，含适用阶段、验证与交接
标准功能/缺陷修复	task + 方案 + 报告；评估/实施/审查/测试/验收可为清楚分段
跨模块、迁移或部署	task + 必要 plan + 分开的审查/测试/验收证据；handoff 仅在独立信息有价值时拆分

每份阶段记录包含 stage_id、输入版本、producer、reviewer/独立性、decision、证据链接、缺项和下一步。需求用 R-ID，验收用 AC-ID，测试用 T-ID；报告提供 R → AC → 改动 → 审查 → 测试 → 运行验收映射，避免仅列“文档已生成”。

路径沿用 .doc taxonomy：任务在 ops/short-term，研究/审查在 audit，方案在 remediation 或既有 ops 主文档，独立测试/验收在 test-reports，附件在其 assets。只读 subagent 由主 Agent 保存原始结论及必要摘录，标明“由主 Agent 转存”与 agent_id；不伪造子 Agent 已写文件。

任务 status 继续只有 planned/in_progress/blocked/done/cancelled；phase 与 review_state、integration_state、deployment、cleanup、remote_sync、acceptance 独立记录。done 取决于授权交付终点。清理待办不扩充任务状态，但必须有人接管。需求验收 pending 时，若验收属于授权交付终点，任务不能 done。

8. Cursor → 本机 PI 接入（任务分支已实现）

配置与能力边界

用户已明确选择 Cursor Auto 主协调和实施、gmktec 本机 PI 承担子任务；原 r1 的 Cursor 原生 .cursor/agents + inherit 方案废止，历史研究保留说明。当前模型配置可人工调整，由执行器每次派发读取；不是 PI 原生配置格式，不改变 PI 全局模型设置。CLI/MCP 接入与限制见运行说明，实际验证见报告。

PI 模型和角色路由以配置文档为唯一来源。主 Agent 根据任务读取 role_id，显式传入 provider/model、独立会话、输入版本、工作目录与工具范围，收取结果后按本规范形成阶段记录。不能把主会话可用工具全部自动授予子任务。

• 只读研究/审查不需要 bash/edit/write；后续接入时显式限制工具，并核对扩展是否引入额外能力。
• 测试角色需要执行批准的命令并产生缓存/产物，不能假称只读；将测试工作目录、数据和环境放在批准范围内，使用既有 agentctl 租约。
• PI 报告由主 Agent 持锁落盘；PI 不修改业务代码或测试源码。将诊断建议交回 Cursor 实施。
• 模型不可用、实际模型不符、配置缺失或未知结果遵循配置和 §6，不隐式换通道或降级。
• 普通本机 PI 调度不复用 Herdr 自动审批/模型预算；产品 PI Runner 仍按目标环境批准配置独立验收。

后续接入步骤与验收

步骤	变更	必需证据
A 文档配置	已确认分工，维护模型配置/派发模板；流程整体另按规范登记	默认值与用户选择一致；修改可追溯；未合入前不称全仓 active
B 消除旧规则冲突	修订 Cursor 测试规则副本为验证契约指针	相关 ISSUE 单独修复验证；本次不改变 Runner
C 实现派发入口	已实现 CLI + 项目 MCP；本地任务分支代码 69ffaa67	配置/租约/模型/快照/结果校验与异常回归已验证；dev 集成另记
D 实机试运行	小型文档任务和受控代码任务（代码由 Cursor 写）	Auto 不需手动切模型；PI 角色/模型/run_id/证据可追溯；不冒充真实产品 PI
E 异常演练	同路径写冲突、PI 失联、必需测试缺项、dev 变化、验收失败、清理拒绝	正确暂停/升级；保留失败证据
F 工具门禁	据试运行决定是否增加阶段校验/hook	实现和真实负例验收后才将相应能力标 enforced

接入验收 V1–V10：V1 Cursor Auto 与配置指定 PI provider/model；V2 授权/需求上下文传递；V3 独立只读审查与报告转存；V4 租约内测试；V5 输入 SHA 变化后复核；V6 写冲突拒绝；V7 缺项不合并；V8 验收失败保留现场；V9 清理拒绝有 owner；V10 中断后恢复。新增 V11：修改配置只影响下一次派发、记录 hash；V12：M3 停用/越权路由及未知 alias 被拒绝。本轮执行器已完成 173 项工程回归与真实 Cursor CLI→MCP→PI 验证，覆盖及未覆盖项以测试报告为准；这不是宣称全部 S0–S9 审批、产品 UI/共享环境或清理已自动执行。

日常使用与调整

用户只需保持 Cursor Auto，说明任务目标与授权终点；主 Agent 读取本规范和模型配置，按需要派发 PI。修改默认分工只编辑模型配置文档；临时调整写入任务 override，不静默改全局默认。流程、模型配置和某任务授权是三个不同对象。

用户可以授权“按已确认方案执行到 local dev 集成与 dev 验收”；该授权不会自动包含 push 或晋升 test/main。验收后归档证据，当前 owner 退出后再由独立维护者复查清理。

回退：调度入口或权限不满足时暂停相应 PI 阶段，保留现场与证据，交回 Cursor 处理；不能以主 Agent 自审替代要求的独立审查。修复接入后再验证。