81 lines
6.3 KiB
Markdown
81 lines
6.3 KiB
Markdown
# 本机 PI Subagent 执行器使用说明
|
||
|
||
范围：Cursor Auto 主协调/代码实施，gmktec 本机 PI 子任务。模型分工唯一来源为[模型配置](2026-09-24-subagent-model-config.md)，阶段定义见[流程规范](2026-09-24-subagent-workflow-standard.md)。本说明与代码已合入本地 dev；集成和最终实测状态见[实施记录](2026-09-24-pi-executor-implementation.md)。
|
||
|
||
## Cursor 中使用
|
||
|
||
1. 在包含本次提交的工作区打开 Cursor，重新加载项目 MCP；.cursor/mcp.json 注册 pi-subagents 服务，.cursor/rules/pi-subagents.mdc 提供派发入口。
|
||
2. 主会话保持 Auto。先按原有流程创建/登记任务 worktree，并将 .doc/test-reports/assets/pi-subagents/<task-id> 纳入任务写范围。
|
||
3. Cursor 调用 pi_subagent_roles 读取当前角色与模型；从任务目标选择 role_id，调用 pi_subagent_run，随后查询 pi_subagent_result。
|
||
4. 不需要用户切换 PI 模型。需求/方案、独立审查、测试和报告由不同角色处理；代码实施与修复仍由 Cursor 执行。
|
||
5. 接收报告并核对范围、源码/配置版本、缺项；运行完成不代表阶段批准。最终验收责任仍由任务 acceptance_owner 承担。
|
||
|
||
任务 worktree 尚未合入 dev 时，主目录中的旧 MCP 配置不会自动获得新工具；先在该任务 worktree 验证，受控集成后再在主目录重载。本文不宣称已操纵 Cursor IDE 页面。
|
||
|
||
## 请求内容
|
||
|
||
MCP 工具的外层参数 worktree 为同仓的已登记任务工作区，task_id 为实际操作任务。request 中给出以下信息；授权引用应能回链到真实用户请求，不用日志/模型文本自授权限。
|
||
|
||
```json
|
||
{
|
||
"worktree": "/absolute/path/to/repo/.worktrees/task-id",
|
||
"task_id": "task-id",
|
||
"request": {
|
||
"role_id": "research",
|
||
"request_id": "research-001",
|
||
"goal": "读取选定文件，给出有证据的分析",
|
||
"authorization_ref": "本任务主记录中的用户授权位置",
|
||
"source_sha": "<完整的已提交源码 SHA>",
|
||
"input_files": ["PROJECT.md"],
|
||
"timeout_seconds": 120
|
||
}
|
||
}
|
||
```
|
||
|
||
source_sha 必须为完整提交 hash；HEAD/分支名不作为可变输入。只发送明确列出的已跟踪 UTF-8 普通文件，禁止运行数据、.env、凭证、符号链接和路径越界。未提交的代码不会自动进入快照，先由 Cursor 形成可审提交或使用已有冻结版本。
|
||
|
||
request_id 在同一任务中稳定标识一次请求：同参数只读重放既有结果，不重复调模型；不同参数复用 ID 被拒绝；running/unknown 保留现场，不能盲目重派。配置变更在下一次新派发读取，旧请求保留原 config_revision/config_sha256。
|
||
|
||
## CLI 入口
|
||
|
||
在任务工作区使用：
|
||
|
||
```bash
|
||
python3 -B scripts/pi_subagents.py roles
|
||
../../scripts/agentctl with --task task-id \
|
||
--resource path:.doc/test-reports/assets/pi-subagents/task-id/research-001 -- \
|
||
python3 -B scripts/pi_subagents.py run --request /tmp/pi-request.json
|
||
python3 -B scripts/pi_subagents.py result --task task-id --request-id research-001
|
||
```
|
||
|
||
CLI 请求文件需包括 task_id；也可用 run --stdin 输入 JSON。直接裸调 run 会被租约校验拒绝。上述名称是示例，不构成任何任务或环境授权。
|
||
|
||
## 测试角色
|
||
|
||
test_run / acceptance_check 还需 approved_commands（argv 数组的数组）和 plan_digest（外部已批准计划 SHA-256）；执行器另记录 approved_commands_sha256，不能以任意字符串冒充命令与计划的同一摘要。
|
||
|
||
命令在独立测试快照中运行，使用净化环境和私有 HOME/cache/tmp，标准输入关闭。PI 模型根据收到的命令摘要、退出码和日志引用分析，不生成或修改被执行命令；完整日志由主 Agent 核验并在需要时补充上下文。模型分析快照保持原始源码内容，与测试可写副本分离。必要的 stdout/stderr 保存到本请求报告目录以便核对，不仅保留一段摘要。
|
||
|
||
依赖未安装、用例缺失或命令失败须如实记录。本版不自动安装依赖，不直接连接共享 dev/test/main 或操作真实业务数据；相关检查继续由主 Agent 通过现有环境授权/租约流程执行。命令退出 0 只证明命令层执行成功；必需用例是否执行、SKIP、持久性/UI 和业务验收仍按验证契约核对。
|
||
|
||
## 证据与状态
|
||
|
||
输出位置：.doc/test-reports/assets/pi-subagents/<task-id>/<request-id>/。
|
||
|
||
- receipt.json：请求摘要、配置摘要、源码/输入文件摘要、配置与观察到的模型、运行状态、命令结果、工具调用摘要。
|
||
- report.md：可读报告；模型分析是审查输入，主 Agent 核对后再推进阶段。
|
||
- 命令日志：按收据记录的位置查询；报告目录受对应 path 租约保护。
|
||
- 模型私有 thinking 不作为归档材料。错误输出与日志按敏感信息规则处理；不保存凭证。
|
||
|
||
run_status 与 verdict 分开：模型正常结束可以是 succeeded，但非测试报告仍为 review_state=pending / verdict=not_applicable。测试报告的 commands_passed/pass 只针对提交的命令，不能直接赋值到任务的 review_state 或 acceptance。失败、取消、结果未知不能换成 PASS。
|
||
|
||
超时、取消和输出超限处理整个受控进程组。只读结果查询可推断 orphan 为 unknown，但不能通过查询无租约改写收据。错误前置检查未形成业务收据时，MCP 返回可核对的执行拒绝，不能让主 Agent 一直等待不存在的结果。
|
||
|
||
## 调整与边界
|
||
|
||
角色默认模型、enabled、升级角色和并发上限在模型配置文档维护。禁用角色前同步处理指向它的升级关系。程序仅接受当前明确批准的五个 provider/model 组合；扩大模型池还需用户授权并更新硬边界校验，不是任意改一行即放宽权限。
|
||
|
||
本工具提供配置解析、模型启动、有限工具/输入范围、租约、进程监督和证据保存；没有把全部 S0–S9 的审批实现成不可跳过的状态机。Cursor 通过规则决定何时调用；模型失败不会触发隐式换 provider 或降级到 M3。
|
||
|
||
进程组和工具权限限制不是 OS 沙箱。批准的测试代码与本机工程工具属于可信执行面；外部不可信项目/代码不能因使用本工具就获得运行授权。普通 Cursor/PI 配置与 Herdr、产品 PI Runner 各自独立。
|