11 KiB
Cursor Auto 与 Subagent 工作流研究及文档验证报告
日期：2026-09-24；owner：Codex；task_id：subagent-workflow-standard-2026-09-24。 范围：现行规范、Cursor 项目配置及官方文档；交付规范草案。未运行 Cursor 对话/真实 subagent，未修改产品或运行环境。
1. 研究结论
推荐主 Agent 协调、按需委派、独立审查与验证的流程。用户提出的八步可作为起点，但需在开始明确授权/验收标准，在方案阶段设计测试，在实施中自测，合并后核对实际运行结果，最后归档和清理。
| 方案 | 收益 | 代价/缺陷 | 结论 |
|---|---|---|---|
| 单 Agent 顺序完成全部阶段 | 简单、额外上下文成本低 | 实施者自审容易沿用错误假设 | 适合小型文档/研究；代码交付补独立审查 |
| 每阶段固定一个 Agent / 固定模型 | 阶段职责直观 | 无效启动和文档重复；固定模型背离 Auto；阶段间易丢授权/版本 | 不采用 |
| 主 Agent + 按需 analyst/reviewer/verifier | 保留上下文入口，独立检查，成本可控 | 需可靠派发包、证据接收和异常恢复 | 推荐；实现并行按风险逐步启用 |
这是本项目基于现状的设计判断，不是 Cursor 平台保证。
2. 官方能力与推论
查阅日期为 2026-09-24。在线文档会变化，客户端接入必须另验；不采用社区传闻作为技术契约。
| 来源 | 查证事实 | 对本规范的影响 |
|---|---|---|
| Cursor Subagents | 自定义角色可位于 .cursor/agents；model 默认 inherit；readonly 与后台字段可配置；子上下文需要主 Agent 提供输入；默认共享 checkout | 采用继承策略、显式交接、仓库管理的写隔离；只读报告由主 Agent 保存 |
| Cursor Models & Pricing | Auto 是平台模型路由选项，公开文档列有不同优化模式 | 规则不绑定模型、价格或固定路由；按实际 UI/账户能力记录 |
| Cursor Rules | 支持 AGENTS.md 和项目规则 .mdc | 根入口/客户端入口只指向单一规范，避免重复规则漂移 |
推论与限制：inherit 能表达继承意图，不足以证明实际模型身份或所有 Auto 请求的路由；独立上下文不保证跨模型独立性；只读权限与运行测试的写产物需要区别处理。Auto 可用性、角色加载、权限、真实派发及费用均未在本会话实测，不保证任何套餐或所有版本可用。云执行不在本次授权与建议默认范围内。
3. 当前仓库证据
检查基线：dev = 5423b261f97f371bdf7fa5066e9305f9eddaef42；本地 origin/dev 跟踪引用比较为 ahead 74 / behind 0。未 fetch，不能据此声明服务器当前引用。
- AGENTS / PROJECT：已定义授权分级、任务 worktree、独立状态、业务实施和研究边界。
- worktree 操作规范：已有 agentctl 租约、候选验证/合入、共享环境持锁、清理负例和收口要求。
- 验证契约：依据变更范围取并集，要求真实用户流程与持久证据；文档变更不要求产品回归。
- 文档地图/任务模板：已有最小文档原则，可以按阶段留证而不制造九份重复文档。
- .cursor/rules：已有 agentctl、文档、Git 和测试入口。rg --files .cursor 未发现项目 .cursor/agents 角色定义；不推断用户全局目录没有角色。
- .cursor/hooks.json：存在 beforeShellExecution 的 Git 守卫；未见本流程阶段完整性校验。此处仅配置阅读，没有实际触发 hook。
- cursor --version：3.21.16 / 8ae78e8eee1e63479c7e0504b664bc0a80c68000 / x64；agent --version：2026.09.18-9a7762b。CLI 版本不代表 IDE 当前会话配置已验收。
- agentctl status：当前配置 policy_revision 为 agent-governance-2026-09-23-fav-constraint-restored；存在其他任务持 env:dev。研究不使用该环境，不改他人任务。
已读规范修订与工具配置 revision 不同，记录两者分别是什么，不把一个全局字段视作所有 Markdown 修订版本。
4. ISSUE-20260924-cursor-test-rule-drift
issue_state：open；严重度：medium；owner：Codex（研究）；evidence_basis：本次源码/配置阅读；产品影响未复现。 预期：客户端测试规则只引用验证契约，由适用范围和批准环境决定套件/Runner。 实际：.cursor/rules/test-reports-standard.mdc（alwaysApply=true）仍要求报告附全量 go test -v ./...，固定 MiniMax-M2.7-highspeed，并指向已不存在的 PROJECT §8。与验证契约中的范围选择、实际批准模型、普通小任务记录方式不一致。
已证实机制：客户端复制完整测试规则形成第二份来源，主规范修订后副本继续陈旧。未证实：实际 Cursor 是否因此执行了错误模型/测试、费用或运行行为是否受影响。 为何已有保护不足：静态读取显示没有针对该副本文案与验证契约的一致性证据；本次没有运行 hook/CI，不能断言所有自动防护都缺失。 同类检查范围：.cursor/rules 下五个规则文件及 hooks 配置、根 AGENTS/PROJECT、验证契约、规范登记、任务/收口模板。其余四个 mdc 主要转发入口；本次未检查所有其他客户端和全局规则。
推荐修复：将该 mdc 缩为验证契约与报告路径指针；结构要求归并现有权威文件，避免再复制模型与全量命令。不是改产品 Runner 模型或删除必要验证。 验收：规则文本无固定模型/无条件全量测试/失效章节；文档任务、Go 任务、产品 PI 任务分别映射到既有验证矩阵；Cursor 实际读取入口并正确选择验证层级。静态修复与实机行为分别报告。 时间线：2026-09-24 发现并登记；本次仅提出修复，未实施，issue 保持 open。无新 validated lesson；未验证修复不包装成经验。
5. 风险和关键设计
- 阶段和角色不是一对一关系：固定九名 Agent 会增加交接成本；初期三角色足够，主 Agent 可实施。
- 只读 reviewer 无法自行写审查文件：主 Agent 转存并保留作者/ID，避免“要求只读同时要求落盘”的矛盾。
- verifier 运行构建/测试会写缓存、数据甚至环境：单独授权，持对应租约，不能装作普通只读检查。
- 子 Agent 默认共享目录：采用单写者；并行写另建登记 worktree，主会话的自动隔离配置不替代仓库门禁。
- 审查和测试必须绑定版本：修复后重审受影响范围；候选变化重验；运行制品与报告提交分开。
- 清理在验收后：唯一日志/截图先归档，owner 退出后由维护者复查，不主动删除当前使用的工作区。
- 人工确认默认在可审方案形成后；已有端到端授权则沿用。用户未回复偏好，本草案采用该可调整默认，不把沉默当批准。
- 模型路由和自动审批不同：Auto 不扩大业务或环境权限，普通 Cursor 不套用 Herdr 固定模型。
- 阶段规范为 manual；文档审核通过不等于自动执行系统已实现。
6. 文档验收与未运行项
本次仅文档研究。静态检查结果在任务“验证与证据”节记录；检查对象为本次全部变更文件内容。 情景自审覆盖：研究-only、简单文档、标准功能、修复回环、并行冲突、readonly 转存、子任务未知、候选变化、验收失败、清理拒绝、上下文恢复。该项是文档推演，不能作为运行负例 PASS。
本次未执行：Cursor Auto 真实派发、Cursor 项目角色配置安装、并行写锁实测、业务测试、产品 PI、浏览器、部署和清理。新规范的 V1–V10 实机清单是后续接入验收项。
7. 文档情景自审记录
审查者：Codex 主 Agent；独立性：self_review。以下为阅读草案逐项推演，结果仅表示文字路径可执行，不表示已运行客户端。
| 情景 | 对照位置 | 结论 |
|---|---|---|
| 只研究方案，未授权实现 | §2、S3 | 可交付研究，其后标不适用；不会顺推业务实现 |
| 一处低风险文档修改 | §4、§7 | 主 Agent 自检，一份主文档可承载阶段，无需九个角色 |
| 代码已修改但审查未回收 | S5、§5 | 不进入集成；后台结果需接收 |
| 修复后旧审查/旧测试仍通过 | S5–S7 | 新版本需适用复核与验证，旧 PASS 不覆盖 |
| readonly reviewer 需要报告 | §4、§7 | 子角色回传，主 Agent 在租约内转存 |
| 测试生成缓存或写环境 | S6、§8 | verifier 可写但须明确产物范围/环境与租约 |
| 两个子任务争用同路径 | §5 | 单写者或独立登记隔离，不能无锁并发 |
| 子任务超时且副作用未知 | §6 | 保留 unknown，核对现场后决定恢复 |
| 合并前 dev 已变化 | S7 | 重建候选并重新验证 |
| 已合入但运行验收失败 | S8、S9 | 不宣布完成、不清理；修复/交接 |
| owner 仍在 worktree 或有唯一日志 | S9、§5 | 保留现场，归档后由独立维护者复查 |
| 会话中断后恢复 | §6、§7 | 从首个未满足门禁继续，核对未回收子任务 |
初次静态检查真实输出：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 的接入建议；前文保留为研究历史，不再作为当前实现方向。现行模型映射唯一来源为模型配置，流程草案同步到 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 人工读取，当前不含执行器/热加载/自动校验实现。
9. 执行器已接入（后续实现）
用户进一步授权接入自动调用 PI 的执行器。代码提交 69ffaa677e23a1dd9aa0528bb09b3acfcd38b119，真实 Cursor CLI→MCP→PI 和 173 项工程回归通过，详情见验证报告及运行说明。前文关于未接入/未调用的说明属于当时研究阶段；当前交付范围与未覆盖项以上述新报告为准。完整流程草案审批、dev 集成和远端同步分别记录。