From 52462b45e985f596b2a503fc70ac12c3bd5fe571 Mon Sep 17 00:00:00 2001 From: weichen Date: Thu, 24 Sep 2026 02:19:28 +0000 Subject: [PATCH] docs(workflow): configure local PI model roles with Cursor implementation --- .doc/README.md | 2 +- .../2026-09-24-subagent-workflow-research.md | 8 ++ .doc/ops/2026-09-21-policy-registry.md | 4 +- .doc/ops/2026-09-24-subagent-model-config.md | 88 +++++++++++++ .../2026-09-24-subagent-workflow-standard.md | 116 ++++++++---------- .doc/ops/CURRENT.md | 1 + .../2026-09-24-subagent-workflow-standard.md | 31 ++++- .doc/ops/templates/subagent-stage-record.md | 6 +- 8 files changed, 182 insertions(+), 74 deletions(-) create mode 100644 .doc/ops/2026-09-24-subagent-model-config.md diff --git a/.doc/README.md b/.doc/README.md index 67041b8e..bd3e97d7 100644 --- a/.doc/README.md +++ b/.doc/README.md @@ -33,7 +33,7 @@ | 我要… | 读这里 | |--------|--------| -| Subagent 阶段与报告（待审） | [协作规范草案](ops/2026-09-24-subagent-workflow-standard.md) · [研究依据](audit/2026-09-24-subagent-workflow-research.md) | +| Subagent 模型配置 / 流程 | [可调整模型配置](ops/2026-09-24-subagent-model-config.md) · [流程草案](ops/2026-09-24-subagent-workflow-standard.md) · [研究依据](audit/2026-09-24-subagent-workflow-research.md) | | 规则来源/生效版本 | [规范登记](ops/2026-09-21-policy-registry.md) | | 选择测试/报告范围 | [验证契约](ops/2026-09-21-validation-contract.md) | | 任务模板与会话收口 | [任务模板](ops/templates/short-term-task.md) · [收口清单](ops/templates/session-close-checklist.md) | diff --git a/.doc/audit/2026-09-24-subagent-workflow-research.md b/.doc/audit/2026-09-24-subagent-workflow-research.md index e4d2702c..ae1c0bac 100644 --- a/.doc/audit/2026-09-24-subagent-workflow-research.md +++ b/.doc/audit/2026-09-24-subagent-workflow-research.md @@ -97,3 +97,11 @@ issue_state：open；严重度：medium；owner：Codex（研究）；evidence_b 初次静态检查真实输出：`FILES=8 LOCAL_LINKS=84 STAGES=10 ISSUE_IDS=5 / PASS`。 命令：`git diff --check`（exit 0）；Python 内联检查全部本次 Markdown 变更（含 untracked）的相对链接/锚点、S0–S9、规则状态字段和 issue ID 唯一性（exit 0）。不验证外部网页永久可达或实际 Cursor 行为。 只读 `agentctl docs drift`：status=ok、regressions=[]；开放能力候选未修改，不等于产品就绪。 + +## 8. 后续决策：本机 PI 与可调整模型配置 + +用户在同一任务后续对话明确：子智能体采用 gmktec 本机 PI；仅允许 minimax-cn/MiniMax-M3、zai-coding-cn/glm-5.3、zai-coding-cn/glm-5.3-flash、qwen-token-plan-cn/qwen3.8-max、qwen-token-plan-cn/qwen3.8-flash。随后明确代码由 Cursor 实施，并因 M3 的实际使用反馈将其移出默认流程，最后确认该默认安排并要求可调整文档。 + +这些用户决策取代本报告前文 r1 中 Cursor 原生 .cursor/agents/inherit 的接入建议；前文保留为研究历史，不再作为当前实现方向。现行模型映射唯一来源为[模型配置](../ops/2026-09-24-subagent-model-config.md)，流程草案同步到 r2。没有改变 Herdr 或产品 Runner。 + +2026-09-24 再次执行 pi --offline --no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files --no-approve --list-models，exit 0；精确五个 provider/model 均存在。此命令没有模型推理，不证明各角色能力或连接状态。配置字段由主 Agent 人工读取，当前不含执行器/热加载/自动校验实现。 diff --git a/.doc/ops/2026-09-21-policy-registry.md b/.doc/ops/2026-09-21-policy-registry.md index 9564118e..c6a2813b 100644 --- a/.doc/ops/2026-09-21-policy-registry.md +++ b/.doc/ops/2026-09-21-policy-registry.md @@ -48,6 +48,6 @@ CURRENT 是带时间的活跃协调快照；Git/机器状态用于核验实际 ## Subagent 工作流拟议修订 -修订 ID：`subagent-workflow-2026-09-24-r1`；owner：Codex；state：`proposed`；能力：`manual`；effective_commit：无。 +修订 ID：`subagent-workflow-2026-09-24-r2`；owner：Codex；state：`proposed`；能力：`manual`；effective_commit：无。 用户要求研究 Cursor Auto 下的 subagent 分工、阶段流程及报告，授权与本次验收见[任务](short-term/2026-09-24-subagent-workflow-standard.md)。[规范草案](2026-09-24-subagent-workflow-standard.md)为拟议行为的唯一来源，[研究报告](../audit/2026-09-24-subagent-workflow-research.md)给出事实和待修冲突，[模板](templates/subagent-stage-record.md)承载交接。 -本次仅研究编制；尚未安装 Cursor 角色、修改 active 工作流或验证真实派发。经用户采纳、受控集成后记录 active 与生效 SHA；客户端接入实测和机器执行能力另行验收。 +用户后续明确采用 Cursor Auto 实施 + gmktec 本机 PI 子任务，并批准默认模型分工及可调整文档。[模型配置](2026-09-24-subagent-model-config.md)为模型路由唯一来源，decision_state=approved；流程整体仍 proposed，未合入 dev。原 Cursor 原生角色/inherit 方案被替代。当前为文档人工读取，尚未实现自动调度或验证真实派发；受控集成、客户端接入和机器执行能力分别验收。 diff --git a/.doc/ops/2026-09-24-subagent-model-config.md b/.doc/ops/2026-09-24-subagent-model-config.md new file mode 100644 index 00000000..91edcc72 --- /dev/null +++ b/.doc/ops/2026-09-24-subagent-model-config.md @@ -0,0 +1,88 @@ +# Subagent 模型分配配置 + +config_revision：`subagent-models-2026-09-24-r1` + +owner：用户；维护执行者：当前任务主 Agent。 + +decision_state：`approved`（本会话确认）；integration_state：`pending`；execution：`manual`。 + +**这是模型分配的唯一配置文档。** 用户调整下列表格；主 Agent 每次派发前读取，并把解析结果写入[派发记录](templates/subagent-stage-record.md)。当前没有程序自动解析、热加载或启动 PI；不能仅凭此文件声称执行器已接入。完整流程见[协作规范](2026-09-24-subagent-workflow-standard.md)。 + +## 1. 日常调整入口 + +| 想调整什么 | 修改位置 | 生效方式 | +|---|---|---| +| 某角色的默认模型 | §3 对应角色的“默认模型”列 | 修改后递增 config_revision；下一次派发读取 | +| 复杂任务的升级去向 | §3 “升级角色”列 | 升级时保留原报告与原因；以目标角色重新派发 | +| 启停某角色 | §3 enabled 列 | false 时不自动派发；必需职责暂停或显式重新分配，不能跳过门禁 | +| 允许使用的 provider/model | §2 模型池 | 使用本机精确 ID；新增模型需用户明确调整授权范围 | +| 并发量、失败处理 | §4 | 主 Agent 按配置与任务实际资源取更严格边界 | +| 只改本次任务 | 在任务主记录写 override | 记录用户指令、角色、原值/新值、期限；不改全局默认 | + +文档中表格值为配置；其他文件只引用本文件，不重复维护模型名。用户可以直接编辑，也可以说“把本任务 code_review 改用 qwen_max”或“以后 report 都用 glm_full”。后者需按仓库 worktree/受控集成流程保存。 + +字段规则：enabled 只取 true/false；默认模型引用 §2 的 alias；升级角色引用 §3 的 role_id，或 none；缺字段、未知 alias、循环升级、角色越权时停止该派发并报告错误，不自行猜测模型。 + +## 2. 允许的模型池 + +主会话：**Cursor，模型选择 Auto**；工程子任务：**gmktec 本机 PI CLI**。这份配置不改变 Cursor UI 模型开关、PI 全局默认设置或产品 PI Agent Runner。 + +| alias | provider | model（精确 ID） | 使用限制 | +|---|---|---|---| +| qwen_max | qwen-token-plan-cn | qwen3.8-max | 可分配分析、规划、报告与复核 | +| qwen_flash | qwen-token-plan-cn | qwen3.8-flash | 默认检索、资料与初稿；复杂任务升级 | +| glm_full | zai-coding-cn | glm-5.3 | 默认评估、独立审查和复杂归因 | +| glm_flash | zai-coding-cn | glm-5.3-flash | 默认测试执行与证据收集；复杂判断升级 | +| minimax_aux | minimax-cn | MiniMax-M3 | 默认停用，仅明确启用后用于易核验辅助任务；不能承担关键判断 | + +本机 provider 是 qwen-token-plan-cn；用户提到的 qwen-token-plan 在此明确映射到该通道。相同模型名出现在其他 provider 不构成可替换授权。M3 不进入规划、代码审查、根因裁决、最终验收或主力自动备用链；需要改变这些限制时由用户明确修订本节。 + +目录核对：2026-09-24，通过本机 pi 的离线 --list-models 核实以上五个组合。存在于目录不等于远端连通、工具调用、性能和任务质量已实测。 + +## 3. 角色路由表 + +代码实施与修复固定由 **Cursor Auto** 承担；下表只路由 PI 子任务。PI 不修改产品代码或测试源码，所需修复/新测试交回 Cursor。 + +| role_id | 工作 | enabled | 默认模型 | 升级角色 | 执行边界 | +|---|---|---|---|---|---| +| research | 检索、代码定位、资料摘录、需求初稿 | true | qwen_flash | planning | 只读；结论回传主 Agent | +| planning | 需求分析、方案制定、复杂问题综合分析 | true | qwen_max | none | 只读；保留假设与依据 | +| requirements_review | 独立评估需求与影响 | true | glm_full | none | 新上下文；不代替用户取舍 | +| plan_review | 独立方案审查 | true | glm_full | none | 不自审自己编制的方案 | +| code_review | 代码审查与回归风险检查 | true | glm_full | none | 冻结 diff；不修改被审内容 | +| diagnosis | 复杂失败归因、跨模块机制分析 | true | glm_full | none | 只读分析；复现操作由 test_run 在授权环境执行 | +| test_run | 按已批准验证计划执行测试、收集证据、初步分析 | true | glm_flash | diagnosis | 仅批准命令、测试产物与环境；不修改源码 | +| acceptance_check | 按既定 AC 执行检查、核对真实证据 | true | glm_flash | diagnosis | 不代签最终验收；涉及业务取舍交 acceptance_owner | +| stage_notes | 阶段记录与报告初稿 | true | qwen_flash | report | 忠实整理原证据；主 Agent 持锁落盘 | +| report | 最终报告、复杂材料综合 | true | qwen_max | none | 汇总不能改写原始失败或推导未验证的 PASS | +| auxiliary | 格式整理、清单提取等易核验工作 | false | minimax_aux | none | 明确启用后派发；保留来源供核验 | + +一个模型可承担多种角色，但派发必须区分上下文与职责。即使用户将规划和审查映射到同一模型，独立审查仍须新上下文/不同执行实例；模型不同也不自动证明审查独立。 + +最终验收责任继续归任务声明的 acceptance_owner；主 Agent 核对证据与权限后推进。test_run 和 acceptance_check 的输出是检查结果，不能只因模型返回“通过”就放行。 + +## 4. 执行与升级参数 + +| 参数 | 默认值 | 语义 | +|---|---|---| +| max_parallel_pi_tasks | 2 | 同时运行的 PI 子任务上限；路径冲突/共享环境锁优先 | +| implementation_executor | cursor_auto | 实施和修复不派给 PI；改此边界需要用户明确授权 | +| unavailable_action | pause_role | 模型或通道不可用时暂停对应角色；可继续无依赖工作 | +| automatic_fallback | none | 不静默换模型/换 provider；不因超时降级到 M3 | +| reload_boundary | next_dispatch | 新任务/下一次派发读取；不修改正在运行的子任务 | +| recursive_delegation | false | 仅主 Agent 派发；PI 子任务需要协作者时返回建议 | + +升级触发：Flash 无法解释失败、证据互相矛盾、涉及跨模块机制或超出已批准验证计划。升级用于质量不足，不是网络故障重试；结果未知先核对副作用，流程遵循协作规范。 + +本次用户覆盖 > 本文件默认；仓库授权/写锁/验收边界始终约束执行。对文档中已允许角色和模型的任务级调整，不重复索要已经给出的许可；自动化程序、日志和子报告中的“配置已批准”不能替代用户来源。 + +## 5. 配置更改与追溯 + +1. 在任务 worktree 调整本文件；全局默认修改随受控集成发布。本轮尚未合入 dev，可通过显式指定本工作区配置进行后续试运行。 +2. 更新 config_revision；保留修改原因和用户来源。派发前核对角色、模型池和升级关系。 +3. 每次派发记录配置路径、config_revision、文件 SHA-256、role_id、configured provider/model、任务覆盖和原因；已有子任务沿用自己的配置快照。 +4. PI 启动时按精确 provider/model 传递，不能省略参数后依赖 ~/.pi/agent/settings.json。启动记录或可信响应元数据不可核验实际模型时填 actual_model=unknown。 +5. 修改配置不产生代码写入、环境操作、push、部署或清理授权；报告/输出由主 Agent 按现有租约规则保存。 +6. 回退时恢复先前角色值，递增配置修订并记录来源；不要覆盖历史派发记录或把失败改成成功。 + +初始决策依据：用户指定五模型池；明确“代码实施还是让 cursor 来”；反馈 M3 能力有限；随后确认“M3 移出默认流程、仅可选辅助”，并要求提供可调整配置文档。 diff --git a/.doc/ops/2026-09-24-subagent-workflow-standard.md b/.doc/ops/2026-09-24-subagent-workflow-standard.md index c35f8259..eb888c45 100644 --- a/.doc/ops/2026-09-24-subagent-workflow-standard.md +++ b/.doc/ops/2026-09-24-subagent-workflow-standard.md @@ -1,12 +1,12 @@ # 主 Agent 与 Subagent 协作流程规范（草案） -修订：`subagent-workflow-2026-09-24-r1`；owner：Codex；规则状态：`proposed`；执行能力：`manual`；effective_commit：无。 -本文件是待审规范。批准与受控集成后才进入 active；文件存在不表示 Cursor 已加载、已派发或门禁已执行。 +修订：`subagent-workflow-2026-09-24-r2`；owner：Codex；规则状态：`proposed`；执行能力：`manual`；effective_commit：无。 +本流程规范仍为待审稿；用户已确认 Cursor 实施、本机 PI 分析/审查/验证及模型默认分工，具体值唯一维护在[模型配置](2026-09-24-subagent-model-config.md)。规则批准与受控集成后才进入 active；文档存在不表示 PI 调度器已接入。 研究与来源见[研究报告](../audit/2026-09-24-subagent-workflow-research.md)，本次授权及交付状态见[任务](short-term/2026-09-24-subagent-workflow-standard.md)。 ## 1. 目标、适用范围和权威 -用户在 Cursor 主会话保持 Auto，以一个任务入口推进需求、方案、实现、评审、验证和收口；主 Agent 决定是否委派，每阶段产生可恢复的记录。规范也适用于其他具备 subagent 能力的本地客户端，客户端配置另行适配。 +用户在 Cursor 主会话保持 Auto；Cursor 负责主协调、代码实施和修复，通过 gmktec 本机工程 PI CLI 委派分析、审查、测试和报告。每阶段产生可恢复记录。此配置不自动适用其他客户端或 Herdr。 本规范只定义角色、阶段、交接和证据引用。授权边界沿用 [AGENTS](../../AGENTS.md)，写锁/候选合并/环境/清理沿用 [worktree 操作规范](2026-09-21-agent-worktree-workflow.md)，测试层级沿用[验证契约](2026-09-21-validation-contract.md)，问题闭环沿用[既有规范](2026-09-23-issue-learning-workflow.md)。不建立第二套测试门禁。 @@ -14,12 +14,12 @@ ## 2. Auto、授权和推进规则 -- **模型策略**：主会话选择 Auto；自定义角色配置 `model: inherit`，不为阶段绑定具体模型。Auto 由客户端提供，本文件不负责开启 UI 开关。 +- **模型策略**：主会话选择 Auto；PI 子任务按[模型配置](2026-09-24-subagent-model-config.md)的角色、provider 和 model 派发。Cursor 原生 subagent 的 model: inherit 方案已被用户后续选择替代，本规范不以 .cursor/agents 实现 PI 路由。 - **能力核验**：首次接入、客户端升级或模型行为异常时，记录客户端版本、角色可发现性、派发 ID、工作目录、配置模型策略及可观察的实际模型；不可见时写 `actual_model=unknown`。不得从自我介绍推断模型。 -- **证据边界**：配置继承是意图，平台可能回退；不能保证所有角色由同一个底层模型执行，也不能宣称模型多样性带来了独立复核。 +- **证据边界**：记录配置指定值与可核验的实际模型；未核验不声称模型调用成功。模型多样性不替代独立上下文和证据。 - **授权策略**：Auto 只表示模型选择，不表示自动授权 shell、外部写入、合并、部署、推送或删除。任务开始记录已有授权，后续不重复询问相同范围。 - **默认确认点（待用户采纳）**：需求形成、评估、方案编制可连续进行；方案可审后，一次确认方案与实施范围。已明确授权按该方案端到端执行，则该确认已经满足。只有范围/环境/外部副作用扩大、破坏性动作或需要用户作业务取舍时再确认。 -- **验收人**：需求阶段明确 acceptance_owner。技术验收可由获授权 verifier 执行；产品效果/业务取舍需要用户判定时，技术通过后保留 `acceptance=pending`，不由 Agent 代签。用户预先委托按明确客观标准验收时，记录委托来源和证据即可。 +- **验收人**：需求阶段明确 acceptance_owner。技术验收检查可由获授权 acceptance_check 执行；产品效果/业务取舍需要用户判定时，技术通过后保留 `acceptance=pending`，不由 Agent 代签。用户预先委托按明确客观标准验收时，记录委托来源和证据即可。 - 仅请求研究/方案的任务交付可审产物后结束。实现、运行验证、合并等阶段逐项写 `not_applicable + 原因`，不为了流程齐全擅自执行。 ## 3. 标准流程 @@ -54,43 +54,43 @@ flowchart TD | 阶段 | 责任与输入 | 最小产物 | 放行条件 / 失败去向 | |---|---|---|---| | S0 建场 | 主 Agent；用户请求、当前规则、Git/认领状态 | task 主记录：目标、授权、基线、写路径、环境、交付终点、policy_revision | 允许范围明确；持久成果在任务 worktree；按现行入口登记 | -| S1 形成需求 | 主 Agent 与用户；原始描述 | 需求记录：用户场景、范围/非目标、R-ID、AC-ID、优先级、验收人 | 可验证预期明确；影响方案的歧义解决，小型假设标注 | -| S2 评估需求 | analyst；S1 和当前证据 | 评估报告：现状差距、替代方案、依赖、风险、复杂度和建议 | 结论为 proceed / revise / defer；高风险未知有验证路径；revise 回 S1 | -| S3 制定方案 | 主 Agent，可委派 analyst；S2 | 方案：改动位置、接口/数据影响、实施依赖、写者、验证矩阵、恢复方案；附方案审查结论 | AC 映射到验证项；必要权限齐备；授权不足交付方案等待；设计疑问回 S2 | -| S4 实施与自测 | 主 Agent 或 implementer；已授权方案 | 实施记录：变更、提交、偏差、自测与失败记录 | 实现满足方案且自测有证据；范围变化回 S1/S3；不得降低 AC 迁就实现 | -| S5 独立代码审查 | reviewer；需求/方案、base/head、完整差异 | 审查报告：范围、审查者、严重度、位置、依据、处置与复核 | 无未解决阻断项；修复回 S4，变更后的代码需复核 | -| S6 交付验证 | verifier；冻结版本、AC、验证契约 | 测试报告：预期用例、实际命令/输入/输出、环境、SHA、PASS/FAIL/SKIP/未运行 | 适用必需项均通过；SKIP/基础设施失败保留阻塞；失败回 S4 或 S3 | +| 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 运行与交付验收 | verifier + acceptance_owner；受控制品、AC | 验收报告：实际制品、环境、用户流程、持久状态、逐项 AC 结论 | 所需运行/UI 验收通过；无运行影响写 not_required；失败不清理、不冒充完成 | +| S8 运行与交付验收 | acceptance_check + acceptance_owner；受控制品、AC | 验收报告：实际制品、环境、用户流程、持久状态、逐项 AC 结论 | 所需运行/UI 验收通过；无运行影响写 not_required；失败不清理、不冒充完成 | | S9 归档与清理 | 主 Agent 固化证据，owner 退出后维护者执行清理 | 收口报告：提交/集成/部署/远端/cleanup 分离；归档证据、清理结果与遗留 owner | 满足现行普通 remove/-d 条件；拒绝保留 pending，登记触发和接管者 | -S5 与 S6 可以在同一不可变版本上并行；必要产物必须都回来才能进入 S7。测试产生构建目录/缓存/数据也算写副作用，先核对其环境和锁。reviewer 阅读稳定 Git 快照，不在 implementer 正在改写的工作树上宣布最终通过。 +S5 与 S6 可以在同一不可变版本上并行；必要产物必须都回来才能进入 S7。测试产生构建目录/缓存/数据也算写副作用，先核对其环境和锁。code_review 阅读稳定 Git 快照，不在 Cursor 正在改写的工作树上宣布最终通过。 S7 候选需执行该范围的真实检查，不能用分支自测替代合并结果验证。S8 后新增的报告提交也需受控集成；分别记录被测业务 SHA 与报告 SHA，说明仅文档变化的复用依据。影响运行内容的后续变更使相关验收失效。 ## 4. 角色和分工 -角色是职责，不是固定模型或必须同时运行的进程。初期配置 analyst、reviewer、verifier 三个角色；主 Agent 承担实施，存在可独立实施的明确边界时再启用 implementer。 +角色是职责，不要求每阶段单独启动一个进程。精确 role_id、enabled、默认模型和升级链只维护在[模型配置](2026-09-24-subagent-model-config.md)，下表说明权限边界。 | 角色 | 职责 | 写权限和独立性 | |---|---|---| -| 主 Agent / coordinator | 与用户对话、授权核对、任务图、派发、证据汇总、冲突处理、推进门禁和交接 | 唯一任务协调者；报告汇总不改变原作者/证据/结论；不能从子报告推导额外授权 | -| analyst | 需求影响、可行性、方案选项和不确定性调查 | 默认只读；返回结构化报告，由主 Agent 落盘；若编制方案，另一个上下文审查方案 | -| implementer | 在授权路径实现指定交付单元、配套测试和实施报告 | 仅获认领的工作路径；不得自行修改验收标准、共享状态或操作共享服务 | -| reviewer | 方案一致性、代码正确性、边界、授权、回归与测试充分性 | 新的只读上下文；不修改被审内容；发现问题返回 implementer；不自签自己实施的改动 | -| verifier | 按冻结 AC 执行测试和运行验收，核对实际行为与宣称 | 可写专用测试产物并操作明确授权的测试环境；不顺手修业务代码；需要修复时重新派发 | +| 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。 -- 默认最多两个并行子任务；资源不足串行。此值是本项目建议预算，不是 Cursor 的平台上限；调整需在任务记录理由。默认只由主 Agent 派发，子 Agent 发现进一步分解需求先返回建议。 +- 并发上限及递归委派规则以模型配置为准；资源不足串行。它是项目预算，不是平台上限；子 Agent 发现进一步分解需求先返回建议。 - 先画依赖再并行；有先后依赖的任务等待前置证据。有相同文件、公共 lockfile、路由、迁移号或共享环境的写任务不能同时认领。 -- 初期同一任务 worktree 采用单写者，读任务读取冻结快照。子 Agent 若无法在有效 agentctl supervisor 身份下写入，改为返回补丁/报告，由主 Agent 持锁应用，不能裸写或绕过 hooks。 -- 并行实现使用已登记的独立任务 worktree，各自从当时明确的 dev SHA 创建；父子关系用 parent_task_id/subtask_id 关联，不从父 feature 分支直接建场。已有依赖通过先集成前置变更、重建基线或明确的受控移植解决，并重新验证。 +- 同一任务 worktree 的源码写者为 Cursor，PI 只读任务读取冻结快照；只读报告由 Cursor 持锁保存。PI 验证涉及产物/环境写入必须在有效 agentctl supervisor 下运行；无法保证时停止执行并报告条件缺失。 +- 若另行开展多 Cursor 并行实施，仍须独立登记 worktree，各自从明确 dev SHA 创建；父子关系用 parent_task_id/subtask_id 关联。此条不授权 PI 实施代码。 - 父任务只承担汇总。写子任务登记独立操作 ID/路径；只读子审查复用父任务文档，不重复创建任务链。子分支结果通过现行候选集成流程交付；不能由 Cursor 的自动隔离/自动合并绕过本仓注册和准入。 - 有后台任务时，主 Agent 可继续独立工作，但不得在结果未回收时发布依赖它的 PASS、合并或清理。各子任务的工具可用性不代表授权可用性。 @@ -98,17 +98,17 @@ S7 候选需执行该范围的真实检查，不能用分支自测替代合并 每次派发至少包含： -1. parent_task_id、subtask_id、角色、具体目标、输入版本（需求/方案/代码 SHA）。 +1. parent_task_id、subtask_id、role_id、具体目标、输入版本（需求/方案/代码 SHA）；配置路径、config_revision、文件 SHA-256、解析后的 provider/model 和任务覆盖依据。 2. 需要读的规范和证据、已有用户授权来源、明确的非目标。 3. 工作目录、允许写路径、环境、mutex/租约执行方式；只读者明确只读。 4. 完成条件、输出格式/报告路径、需要验证的 AC；子 Agent 不依赖未传入的主会话历史。 5. 预算（时间或步骤）、进度回传点、失败/超时和副作用核对方式。 -回传至少包括：执行身份/agent_id、实际输入版本、结果与证据、变更文件/提交、实际命令与环境、结论、缺项/风险、遗留进程/产物。主 Agent 校验路径、版本和证据后标记 accepted；子 Agent 自报 done 只表示执行结束。 +回传至少包括：执行身份/PI run_id、配置版本与指定/实际模型、实际输入版本、结果与证据、变更文件/提交、实际命令与环境、结论、缺项/风险、遗留进程/产物。主 Agent 校验路径、版本和证据后标记 accepted；子 Agent 自报 done 只表示执行结束。 - 分开记录 run_status（running/succeeded/failed/cancelled/unknown）与 verdict（pass/changes_required/blocked/not_applicable），不可把退出成功等同质量通过。 - 超时/失联先检查进程、worktree、Git 和外部副作用；结果未知时保留 unknown，不同时重派同一写任务。纯只读且确认无副作用的失败可有限重试，并保留原记录。 -- reviewer/verifier 有异议时，主 Agent 依据原需求和证据裁决。能修复则回 S4；需要业务取舍则向用户汇总一个关键问题，不以多数投票覆盖阻断证据。 +- 审查/验证角色有异议时，主 Agent 依据原需求和证据裁决。能修复则回 S4；需要业务取舍则向用户汇总一个关键问题，不以多数投票覆盖阻断证据。 - 连续两轮修复仍未解决同类阻断时，停止机械重试，回 S2 重查机制/测试前提；授权内可继续研究。不得为放行删除失败用例或降低 AC。 - 用户中断、客户端退出、上下文压缩时，先固化阶段、版本、未回收子任务、owner 和接管条件；恢复后从首个未满足门禁继续，不能整条流程重跑或直接跳到收口。 @@ -129,57 +129,37 @@ S7 候选需执行该范围的真实检查，不能用分支自测替代合并 任务 status 继续只有 planned/in_progress/blocked/done/cancelled；phase 与 review_state、integration_state、deployment、cleanup、remote_sync、acceptance 独立记录。done 取决于授权交付终点。清理待办不扩充任务状态，但必须有人接管。需求验收 pending 时，若验收属于授权交付终点，任务不能 done。 -## 8. Cursor 接入方案（尚未执行） +## 8. Cursor → 本机 PI 接入（执行器尚未实现） -### 配置原则 +### 配置与能力边界 -官方能力依据见研究报告。首次落地用项目级 .cursor/agents，避免更改用户全局配置。项目入口只放短指针，业务流程以本文件为单一来源。 +用户已明确选择 Cursor Auto 主协调和实施、gmktec 本机 PI 承担子任务；原 r1 的 Cursor 原生 .cursor/agents + inherit 方案废止，历史研究保留说明。当前[模型配置](2026-09-24-subagent-model-config.md)可人工调整，由主 Agent 读取；不是 PI 原生配置格式，不会自动改变 ~/.pi/agent/settings.json。 -拟配置角色： +PI 模型和角色路由以配置文档为唯一来源。主 Agent 根据任务读取 role_id，显式传入 provider/model、独立会话、输入版本、工作目录与工具范围，收取结果后按本规范形成阶段记录。不能把主会话可用工具全部自动授予子任务。 -| 文件 | model | readonly | 执行范围 | -|---|---|---|---| -| .cursor/agents/workflow-analyst.md | inherit | true | S2/S3 研究和方案建议 | -| .cursor/agents/workflow-reviewer.md | inherit | true | S3 方案复核、S5 代码审查，均不修复 | -| .cursor/agents/workflow-verifier.md | inherit | false | S6/S8 已批准检查；写产物/环境仍受租约限制 | -| .cursor/agents/workflow-implementer.md（按需） | inherit | false | S4 已划定工作单元 | +- 只读研究/审查不需要 bash/edit/write；后续接入时显式限制工具，并核对扩展是否引入额外能力。 +- 测试角色需要执行批准的命令并产生缓存/产物，不能假称只读；将测试工作目录、数据和环境放在批准范围内，使用既有 agentctl 租约。 +- PI 报告由主 Agent 持锁落盘；PI 不修改业务代码或测试源码。将诊断建议交回 Cursor 实施。 +- 模型不可用、实际模型不符、配置缺失或未知结果遵循配置和 §6，不隐式换通道或降级。 +- 普通本机 PI 调度不复用 Herdr 自动审批/模型预算；产品 PI Runner 仍按目标环境批准配置独立验收。 -readonly verifier 无法可靠执行会生成缓存或产物的测试，因此测试角色与静态只读审查分离。readonly=false 不授予环境权限。默认前台收取有依赖的工作；后台仅用于主 Agent 有独立工作可继续的情况。 - -角色文件示例（待实施时创建）： - -```yaml ---- -name: workflow-reviewer -description: 在方案形成后或代码交付前独立审查；返回有版本和证据的结论，不修改内容。 -model: inherit -readonly: true ---- -``` - -正文要求：先核验收到的派发包，按仓库 AGENTS 和本规范的 reviewer 职责检查；缺少输入版本或授权来源返回 blocked；只回传阶段模板，主 Agent 持锁保存。其余角色使用各自职责，避免复制整份治理规则。 - -建议 AGENTS 启动段新增短指针：“多阶段开发、委派 subagent 或验收收口前，读主 Agent 与 Subagent 协作流程规范；按阶段留证，按现有授权持续推进，独立审查与验收通过后才交付。”仅在新规范获批并集成时加入。 - -### 接入顺序与验收 +### 后续接入步骤与验收 | 步骤 | 变更 | 必需证据 | |---|---|---| -| A 采纳规范 | 确认默认确认点/验收人；核对与当前 dev 规则差异；按登记流程 approved→active | 批准来源、受控集成 SHA；manual 标识 | -| B 消除冲突 | 将 .cursor/rules/test-reports-standard.mdc 缩为验证契约/报告路径指针；保留契约要求 | 不再固定旧模型或强制无关全量测试；相关 ISSUE 复核 | -| C 接入角色 | AGENTS/文档地图短入口、三个角色文件、任务模板追加阶段记录链接 | 配置加载、角色发现、权限行为与 dispatch ID；无需修改产品业务代码 | -| D 实机试运行 | Cursor Auto 下执行一个小型文档任务和一个受控代码任务 | 无需手动切模型；派发/回传/转存可追溯；明确最终代码版本，审查和测试各有记录 | -| E 异常演练 | 同路径写冲突、子任务未知、缺少必需测试、dev 基线变化、验收失败、清理拒绝 | 均停在正确门禁；保留失败证据，不越权继续 | -| F 决定自动化 | 依据 D/E 结果再决定是否开发阶段校验/hook | 独立授权、实现和真实负例验证后才把对应能力标 enforced | +| A 文档配置 | 已确认分工，维护模型配置/派发模板；流程整体另按规范登记 | 默认值与用户选择一致；修改可追溯；未合入前不称全仓 active | +| B 消除旧规则冲突 | 修订 Cursor 测试规则副本为验证契约指针 | 相关 ISSUE 单独修复验证；本次不改变 Runner | +| C 实现派发入口 | Cursor 读取配置，启动本机 PI，限制工具、传入任务包、收取报告 | 配置校验、精确模型、独立上下文、权限拒绝、超时处理；需后续实现 | +| D 实机试运行 | 小型文档任务和受控代码任务（代码由 Cursor 写） | Auto 不需手动切模型；PI 角色/模型/run_id/证据可追溯；不冒充真实产品 PI | +| E 异常演练 | 同路径写冲突、PI 失联、必需测试缺项、dev 变化、验收失败、清理拒绝 | 正确暂停/升级；保留失败证据 | +| F 工具门禁 | 据试运行决定是否增加阶段校验/hook | 实现和真实负例验收后才将相应能力标 enforced | -阶段记录与质量门禁目前是人工/Agent 遵约。既有 agentctl 只在自身已证明的范围内提供机器门禁，不能推导其已校验本规范的 S1–S9。 +接入验收 V1–V10：V1 Cursor Auto 与配置指定 PI provider/model；V2 授权/需求上下文传递；V3 独立只读审查与报告转存；V4 租约内测试；V5 输入 SHA 变化后复核；V6 写冲突拒绝；V7 缺项不合并；V8 验收失败保留现场；V9 清理拒绝有 owner；V10 中断后恢复。新增 V11：修改配置只影响下一次派发、记录 hash；V12：M3 停用/越权路由及未知 alias 被拒绝。以上均为后续实机验收项，本次仅文档静态检查。 -本规范接入验收矩阵：V1 Auto 与 inherit 可用；V2 主会话上下文正确传递；V3 reviewer 静态只读且报告能转存；V4 verifier 在租约内产出测试证据；V5 输入 SHA 变化使复核失效；V6 同路径写冲突拒绝；V7 缺项不合并；V8 运行验收失败保留现场；V9 清理拒绝留 owner；V10 中断后恢复阶段和子任务。以上本次均为待执行，不是已通过。 +### 日常使用与调整 -### 日常对话用法（接入验收后） +用户只需保持 Cursor Auto，说明任务目标与授权终点；主 Agent 读取本规范和模型配置，按需要派发 PI。修改默认分工只编辑模型配置文档；临时调整写入任务 override，不静默改全局默认。流程、模型配置和某任务授权是三个不同对象。 -用户保持 Auto，可直接说：“按本仓协作规范处理：<目标>。先形成需求、评估和可审方案；方案确认后在授权范围内推进。每阶段留证，完成独立审查、测试和验收后交付。”主 Agent 据任务判断派发，不要求用户记角色名或逐步切模型。 +用户可以授权“按已确认方案执行到 local dev 集成与 dev 验收”；该授权不会自动包含 push 或晋升 test/main。验收后归档证据，当前 owner 退出后再由独立维护者复查清理。 -用户已经知道方案且明确授权全过程时，可在任务中一次写明：“按已确认方案执行到 local dev 集成与 dev 验收；验收后由独立维护者按现有门禁清理；不 push，不晋升 test/main。”这是授权示例，未由用户提出的内容不能反向当成当前授权。 - -回退：角色加载/权限行为不符时先停止相关自动派发，回到主 Agent 串行实施和独立会话审查；保留任务与报告，修正规范/配置后再试。规则撤销通过新的受控修订完成，不删除历史证据。 +回退：调度入口或权限不满足时暂停相应 PI 阶段，保留现场与证据，交回 Cursor 处理；不能以主 Agent 自审替代要求的独立审查。修复接入后再验证。 diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index 5c93a16b..3a25786e 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -18,6 +18,7 @@ | owner | task | branch | worktree | mutex | status | |---|---|---|---|---|---| +| Codex | subagent-workflow-standard-2026-09-24-config-r2 | feature/subagent-workflow-standard-2026-09-24 | .worktrees/subagent-workflow-standard-2026-09-24 | subagent-workflow-docs | done | | Codex | subagent-workflow-standard-2026-09-24 | feature/subagent-workflow-standard-2026-09-24 | .worktrees/subagent-workflow-standard-2026-09-24 | subagent-workflow-docs | done | | Cursor | fix-fav-staging-uuid-2026-09-24 | fix/fix-fav-staging-uuid-2026-09-24 | .worktrees/fix-fav-staging-uuid-2026-09-24 | artifactvault | done | | Cursor | gate-e1a-unique-project-name-2026-09-24 | fix/gate-e1a-unique-project-name-2026-09-24 | .worktrees/gate-e1a-unique-project-name-2026-09-24 | docnotify | in_progress | diff --git a/.doc/ops/short-term/2026-09-24-subagent-workflow-standard.md b/.doc/ops/short-term/2026-09-24-subagent-workflow-standard.md index e1802d7c..325733ba 100644 --- a/.doc/ops/short-term/2026-09-24-subagent-workflow-standard.md +++ b/.doc/ops/short-term/2026-09-24-subagent-workflow-standard.md @@ -11,7 +11,7 @@ policy_revision: "agent-governance-2026-09-21-r1 + issue-learning-2026-09-23-r1 branch: feature/subagent-workflow-standard-2026-09-24 worktree: .worktrees/subagent-workflow-standard-2026-09-24 base_dev_sha: 5423b261f97f371bdf7fa5066e9305f9eddaef42 -write_scope: [".doc/ops/2026-09-24-subagent-workflow-standard.md", ".doc/ops/short-term/2026-09-24-subagent-workflow-standard.md", ".doc/audit/2026-09-24-subagent-workflow-research.md", ".doc/ops/templates/subagent-stage-record.md", ".doc/ops/2026-09-21-policy-registry.md", ".doc/README.md", ".doc/audit/ISSUES.md", ".doc/ops/CURRENT.md"] +write_scope: [".doc/ops/2026-09-24-subagent-model-config.md", ".doc/ops/2026-09-24-subagent-workflow-standard.md", ".doc/ops/short-term/2026-09-24-subagent-workflow-standard.md", ".doc/audit/2026-09-24-subagent-workflow-research.md", ".doc/ops/templates/subagent-stage-record.md", ".doc/ops/2026-09-21-policy-registry.md", ".doc/README.md", ".doc/audit/ISSUES.md", ".doc/ops/CURRENT.md"] allowed_environments: [] mutex: subagent-workflow-docs review_state: pending @@ -78,3 +78,32 @@ remote_sync: not_requested 本任务工作区保留供审阅，未合入 dev；cleanup 由独立维护者在满足祖先/证据/进程条件后复查。无需重建产品服务；未申请或使用 env:dev。 本地认领在结束前标记研究 done；此状态只关闭本次规范编制，不关闭 open 问题或自动批准规范。文件含可再生 .codegraph 缓存，独立维护者清理前另行盘点；草案是唯一新增研究成果，当前工作区需保留供审阅。 + +## 后续修订 r2：用户确认模型配置 + +逻辑 task_id 沿用 subagent-workflow-standard-2026-09-24；本机 agentctl 不支持重开已关闭记录，也不允许原记录隐式扩 scope，因此仅创建 operation_task_id=subagent-workflow-standard-2026-09-24-config-r2 作为本次写入租约身份，仍在原 worktree、分支和本主记录继续，不另建业务任务。 +写范围沿用原规范/研究/入口/模板/主记录并增加 .doc/ops/2026-09-24-subagent-model-config.md；未认领业务源码、PI 全局配置或任何运行环境。 + +授权来源：用户指定本机 PI 和五模型池；明确代码由 Cursor 实施；确认 M3 不进入默认流程；本轮“可以，默认这样，可以设置一个配置文档，让我可以根据需要进行调整”。 + +交付：可编辑模型配置 + 旧草案中的执行方式修正 + 配置版本/覆盖来源进入派发模板。模型分配 decision_state=approved；流程整体仍 proposed，自动派发器未实现，未扩大为客户端安装、产品实施、dev 集成或 push。 + +验收项： +- AC6：五个精确 provider/model，Cursor 独占代码实施与修复。 +- AC7：M3 辅助角色 enabled=false，禁止关键判断/自动备用链。 +- AC8：角色默认、升级关系、启停、并发和任务覆盖可在文档中调整。 +- AC9：配置版本/hash 随派发记录，下一次派发生效；文件明确尚无自动解析器。 +- AC10：模型配置为唯一来源；流程与研究历史明确取代旧原生 Cursor/inherit 方案。 + +使用 writing-for-agents 的单一来源/短入口原则维护文档。继续采纳 LESSON-20260923-matrix-status-cas；不新增已验证经验，未将文档推演当运行证明。 + +本轮验证结果（文档静态检查，非运行验收）： +- git diff --check：exit 0。 +- Python 内联检查：五个模型精确匹配本机目录；11 个 role_id 唯一且升级关系无循环；auxiliary=false，M3 仅辅助；implementation_executor=cursor_auto；无自动备用；模板包含 config_revision/config_sha256。初次输出 MODELS=5 ROLES=11 STAGES=10，PASS。 +- 本次变更 Markdown 的相对链接及锚点检查通过；旧 PI implementer 配置已移除。保留的 inherit 提及均说明旧方案已废止。 +- agentctl docs drift：status=ok，regressions=[]；cleanup report 为只读盘点，本任务因未合入/文件及登记状态不能删除。未操作其他任务。 +- codegraph sync -q：exit 0。仅文档变更，产品测试、真实模型调用和派发器验收不适用/未运行，未记 PASS。 + +本轮交付已完成；逻辑任务恢复 done，模型分工已获用户确认。新增配置与配套文档保存于本地任务分支；未合入 dev、未 push，主目录与 PI 全局设置均未修改。自动调用 PI 的执行器、角色工具限制实测、流程整体采纳和相关旧规则修复作为后续工作，不因配置文档存在视为已完成。 + +提交前检查记录：首次 git diff --cached --check 检出新配置头部两处 Markdown 行末双空格，提交未执行。已改为段落分隔并重跑检查；此前 git diff --check 不包含未跟踪新文件，最终以暂存区检查为准。 diff --git a/.doc/ops/templates/subagent-stage-record.md b/.doc/ops/templates/subagent-stage-record.md index b28f5996..3557209e 100644 --- a/.doc/ops/templates/subagent-stage-record.md +++ b/.doc/ops/templates/subagent-stage-record.md @@ -4,7 +4,9 @@ ## 派发包 -- parent_task_id / subtask_id / stage_id / role： +- parent_task_id / subtask_id / stage_id / role_id： +- [模型配置](../2026-09-24-subagent-model-config.md)路径 / config_revision / config_sha256： +- 解析后的 provider / model / enabled / upgrade_role；本任务 override、用户来源与期限： - 目标、非目标、授权来源和交付终点： - 输入：R-ID / AC-ID / 方案版本 / base_sha / head_sha： - 必读规则：AGENTS、policy_revision、适用专门规范： @@ -15,7 +17,7 @@ ## 子任务回传 -- agent_id / producer / 开始结束时间： +- PI run_id / producer / 开始结束时间： - configured_model / actual_model（不可观察填 unknown）： - 实际输入版本、实际 cwd： - run_status：running | succeeded | failed | cancelled | unknown