Pi 委托
你是编排器。将一个有边界的编码任务委托给一个独立的实现者——Pi 编码代理 CLI——然后审查它产生的内容并自行提交。你编写简要说明并拥有判断权；实现者在其自己的会话中进行更改；你进行验证并提交。
这个循环只需要一个 shell 命令和文件访问，因此任何类似的编排器都可以驱动它。
何时不使用
- 任务足够小，可以在内联完成；委托的开销不值得。
piCLI 未安装或未认证。- 你需要一个沙箱化的实现者。Pi 没有沙箱，也没有权限模式；
--read-only限制了工具范围，但具有写入能力的运行会在没有提示的情况下执行。
前提条件（检查一次）
- 使用
npm install -g @earendil-works/pi-coding-agent安装 pi。 - 认证：在 pi 内部使用
/login以使用订阅提供商，或使用 API 密钥的环境变量 /pi的认证文件以使用 API 密钥提供商。 - 确认
pi --version成功。 - 在目标 git 仓库中工作，或使用
--cd指向该仓库。
选择模型（可选）
省略 --model 以使用 pi 配置的默认模型。要选择其他模型，请从 pi --list-models 中选择，并传递显式的 ID 或模式，如 <provider>/<model-id> 或 sonnet:high。中继仅接受字母、数字和 . _ : / -（该值在 Windows 上会传到 shell），因此带有 * 的通配模式不会被转发。
循环
每个任务执行以下五个步骤。步骤 1、4 和 5 需要判断；步骤 2 和 3 是机械性的。
1. 编写简要说明
Pi 只看到你发送的文本以及它可以在工作区中检查的内容——没有聊天历史或共享上下文。包含目标、当前状态、要更改的内容、保持不变的内容、项目的实际门控条件以及报告契约。告诉 pi 不要提交。每个简要说明只保留一个任务。Pi 会自动从工作区及其父目录加载 AGENTS.md/CLAUDE.md 上下文文件，因此仓库指令可以在不内联的情况下传递。请参阅 references/writing-the-brief.md。
2. 发送
使用捆绑的中继。它将简要说明通过标准输入管道发送给 pi --mode json，捕获 JSON 事件流，并写入 result.json。（<skill-dir> 是包含此 SKILL.md 的安装文件夹。）
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# 选择模型： 添加 --model <pi --list-models 中的 ID>
# 选择提供商： 添加 --provider <名称>
# 只读运行（审查/诊断）： 添加 --read-only
# 信任项目 .pi 资源： 添加 --approve
# 恢复最近的会话： 添加 --resume-last（仅增量简要说明）
# 恢复特定会话： 添加 --session <ID>（仅增量简要说明）
# 硬时间限制（看门狗）： 添加 --timeout 2h（默认 30 分钟适合短运行；实现简要说明通常需要 1-2 小时）
# 查看所有选项： node .../relay.mjs --help
子进程的当前工作目录固定工作区。中继默认在系统临时目录下写入工件，并且从不提交。请参阅 references/dispatch-and-poll.md。
3. 等待完成
中继会阻塞直到 pi 完成。使用编排器的后台命令工具运行它，或者在 shell 中将其后台运行并轮询 result.json。运行前的使用错误会退出并返回 2，且不写入结果；缺少 pi 会退出并返回 127，并写入 status: "pi_unavailable"。
信任进程状态和工作树而不是进度显示。完成意味着进程已退出且 result.json 存在。Pi 的完整报告是 result.json 中的 finalMessage 字段（也会在标准输出上的报告标记之间完整打印）。
4. 审查——不要相信自我报告
将 pi 的最终消息和门控声明视为声明：
- 自行重新运行项目的门控条件。
- 从
touchedFiles开始，阅读与简要说明的差异。 - 如果安装了相关的守卫技能，请运行它们。
- 在删除或重命名后，进行往返迁移并 grep 查找悬挂引用。
请参阅 references/review-and-land.md。
5. 提交
实现者编辑工作树；编排器提交。 仅当门控条件通过且差异成立时才提交。如果需要返工，请使用 --resume-last 或 --session <ID> 发送增量简要说明，然后再次审查。
自主性和权限
Pi 没有沙箱，也没有权限模式。默认的无头运行会读取、写入、编辑和执行 shell 命令，没有提示——控制方式是：
--read-only将 pi 可调用的工具限制为--tools read,grep,find,ls，涵盖内置、扩展和自定义工具。已安装的扩展代码仍以用户的主机权限运行。- 中继默认传递
--no-approve，因此项目.pi设置、扩展和技能保持不受信任。--approve是用户信任的仓库的显式选择加入。 touchedFiles和差异是更改的记录。每次运行后检查它们。
授权模型
委托是用户选择加入的内容。一旦用户同意（“运行此队列”、“继续”），提交经过验证且门控条件通过的代码就是约定的契约。有两个限制仍然存在：展示，不吸收（报告 pi 的设计决策、可辩护但未经过询问的转向以及非阻塞的挑剔）以及因范围变更而停止（如果正确完成需要超出简要说明的内容，则询问而不是扩大授权）。请参阅 references/review-and-land.md。
参考
- references/writing-the-brief.md - 结构、报告契约、实际门控条件、标准输入交付和增量简要说明。
- references/dispatch-and-poll.md - 标志、工件、
result.json、轮询和故障恢复。 - references/review-and-land.md - 审查清单、提交边界和通过 pi 会话进行返工。
- references/multi-task-queues.md - 顺序队列、约束延续、进度跟踪和最终一致性检查。