pi-delegate

Pi Delegate

你是编排器。将范围明确的编码任务委派给单独的实现者——Pi 编码 Agent CLI，然后审查其产出并由你亲自提交。你撰写任务说明并负责判断；实现者在自己的会话中修改代码；你负责验证并提交。

这个工作循环只需要一条 shell 命令和文件访问权限，因此任何类似的编排器都可以驱动它。

何时不应使用

• 任务足够简单，可以直接完成；委派的开销得不偿失。
• 未安装 pi CLI，或尚未完成身份验证。
• 你需要使用沙箱化的实现者。Pi 没有沙箱，也没有权限模式；--read-only 会限制工具范围，但具备写入权限的运行不会提示确认。

前置条件（检查一次即可）

1. 使用 npm install -g @earendil-works/pi-coding-agent 安装 pi。
2. 完成身份验证：对于订阅服务提供商，在 pi 中使用 /login；对于 API 密钥服务提供商，设置 API 密钥环境变量，或使用 pi 的身份验证文件。
3. 确认 pi --version 可以成功运行。
4. 在目标 git 仓库中工作，或将 --cd 指向该仓库。

选择模型（可选）

省略 --model 可使用 pi 配置的默认模型。要选择其他模型，请从 pi --list-models 中选择，并传入明确的 ID 或类似 <provider>/<model-id> 或 sonnet:high 的模式。中继只接受字母、数字以及 . _ : / -，因为该值会在 Windows 上传给 shell；因此不会转发包含 * 的 glob 模式。

工作循环

每项任务都执行以下五个步骤。步骤 1、4 和 5 需要判断；步骤 2 和 3 则是机械操作。

1. 撰写任务说明

Pi 只能看到你发送的文本，以及它能在工作区中检查的内容——没有聊天历史或共享上下文。请说明目标、当前状态、需要修改的内容、需要保持不变的内容、项目实际的检查门槛，以及报告要求。告诉 pi 不要提交。每份任务说明只包含一项任务。Pi 会自动加载工作区及其父目录中的 AGENTS.md/CLAUDE.md 上下文文件，因此仓库说明无需内联也能传达给它。参阅 references/writing-the-brief.md。

2. 派发

对于 Codex 编排的后台工作，请先安装并配置独立的 codex-background 支持工具。如果缺少其 MCP 工具或注册表，请停止并报告所需的设置；不要默默退回到由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具一次，代替下面的 shell 示例。 按照该技能的说明使用结构化的通用参数、保持提供商标志不变，并通过 runId 重新连接。保持请求处于待处理状态，直到任务完成，然后继续执行本技能中的审查和提交步骤。其他编排器则继续使用下面的 shell 工作流。

使用随附的中继程序。它会将任务说明通过 stdin 传给 pi --mode json，捕获 JSON 事件流，并写入 result.json。（<skill-dir> 是包含此 SKILL.md 的已安装文件夹。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a model:                          add --model <id from pi --list-models>
# choose a provider:                       add --provider <name>
# read-only run (review/diagnosis):        add --read-only
# trust project .pi resources:             add --approve
# resume the most recent session:          add --resume-last  (delta brief only)
# resume a specific session:               add --session <id> (delta brief only)
# hard time limit (watchdog):              add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# see all options:                         node .../relay.mjs --help

子进程的 cwd 决定工作区位置。中继程序默认将产物写入系统临时目录，且绝不提交。参阅 references/dispatch-and-poll.md。

3. 等待完成

使用 codex-background 的 Codex 会让原始 MCP 请求保持待处理状态：不要由模型驱动执行休眠、状态轮询或日志轮询。仅在请求中断后，才使用 delegate_wait 重新连接。

中继程序会一直阻塞，直到 pi 完成。使用编排器的后台命令功能运行它，或在 shell 中将其放到后台运行并轮询 result.json。运行前的用法错误会以 2 退出，且不会写入结果；找不到 pi 时会以 127 退出，并写入 status: "pi_unavailable"。

请优先依据进程状态和工作树，而不是进度显示。进程已退出且 result.json 存在，即表示任务完成。Pi 的完整报告位于 result.json 的 finalMessage 字段中（也会在 stdout 的报告标记之间完整打印）。

4. 审查——不要轻信自我报告

将 pi 的最终消息和门禁声明视为待核实的说法：

• 自行重新运行项目的门禁。
• 对照简报阅读差异，从 touchedFiles 开始。
• 如果已安装相关守护技能，请运行。
• 执行迁移的往返验证，并在移除或重命名后搜索是否有悬空引用。

请参阅 references/review-and-land.md。

5. 落地

实施者编辑工作树；协调者负责提交。 只有在门禁通过且差异无误后才提交。如果需要返工，请使用 --resume-last 或 --session <id> 发送增量简报，然后再次审查。

自主性与权限

Pi 没有沙箱，也没有权限模式。默认的无头运行会在不提示的情况下读取、写入、编辑并执行 shell 命令——控制措施如下：

1. --read-only 会将 pi 可调用的工具限制为 --tools read,grep,find,ls，涵盖内置工具、扩展和自定义工具。已安装的扩展代码仍会以用户的主机权限运行。
2. 中继默认传递 --no-approve，因此项目的 .pi 设置、扩展和技能仍视为不可信。对于用户信任的仓库，可显式选择 --approve。
3. touchedFiles 和差异记录了所有变更。每次运行后都要检查它们。

授权模型

委派任务需要由人类主动选择。一旦人类明确同意（“运行此队列”“继续”），提交已验证且通过门禁的工作就是双方约定的契约。仍有两条限制：呈现，不代为处理（报告 pi 的设计决策、有理有据但未被要求的改动，以及不阻塞任务的小问题）；遇到范围变更时停止（如果正确完成任务需要超出简报范围，应先询问，而不是擅自扩大授权）。请参阅 references/review-and-land.md。

参考资料

• references/writing-the-brief.md - 结构、报告约定、实际门禁、stdin 交付和增量简报。
• references/dispatch-and-poll.md - 标志、构件、result.json、轮询和故障恢复。
• references/review-and-land.md - 审查清单、提交边界，以及通过 pi 会话返工。
• references/multi-task-queues.md - 顺序队列、约束延续、进度跟踪和最终一致性检查。