pi-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pi Delegate

Pi 任务委托

You are the orchestrator. Delegate a bounded coding task to a separate implementer - the Pi coding agent CLI - then review what it produced and land it yourself. You write the brief and own the judgment; the implementer makes changes in its own session; you verify and commit.

The loop needs only a shell command and file access, so any comparable orchestrator can drive it.

你是编排者。将一个明确界定的编码任务委托给独立的实现工具——Pi coding agent CLI，之后审核其产出内容并自行完成提交。由你撰写任务简报并负责判断；实现工具在独立会话中进行修改；你负责验证并提交代码。

这个循环仅需要Shell命令和文件访问权限，因此任何类似的编排工具都可以驱动它。

When NOT to use this

何时不使用此方法

The task is small enough to do inline; delegation overhead is not worth it.
The
```
pi
```
CLI is not installed or authenticated.
You need a sandboxed implementer. Pi has no sandbox and no permission modes;
```
--read-only
```
restricts the tool surface, but a write-capable run executes without prompts.

任务规模小到可直接完成；委托的开销得不偿失。
未安装或未认证
```
pi
```
CLI。
需要沙箱化的实现工具。Pi没有沙箱环境和权限模式；
```
--read-only
```
参数会限制工具可用范围，但具备写入权限的运行会直接执行，无任何提示。

Prerequisites (check once)

前置条件（只需检查一次）

Install pi with

npm install -g @earendil-works/pi-coding-agent

Authenticate:
```
/login
```
inside pi for a subscription provider, or an API-key environment variable /
```
pi
```
's auth file for an API-key provider.
Confirm
```
pi --version
```
succeeds.
Work in, or point
```
--cd
```
at, the target git repository.

使用

npm install -g @earendil-works/pi-coding-agent

安装pi。

认证：在pi内执行
```
/login
```
以使用订阅提供商，或通过API密钥环境变量/
```
pi
```
的认证文件使用API密钥提供商。
确认
```
pi --version
```
命令执行成功。
在目标Git仓库中工作，或通过
```
--cd
```
参数指定目标Git仓库路径。

Choose the model (optional)

选择模型（可选）

Omit

--model

to use pi's configured default. To pick another, choose from

pi --list-models

and pass an explicit id or pattern like

<provider>/<model-id>

sonnet:high

. The relay accepts letters, digits, and

. _ : / -

only (the value reaches a shell on Windows), so glob patterns with

are not forwarded.

省略

--model

参数将使用pi的配置默认模型。如需选择其他模型，可从

pi --list-models

的输出中选择，传入明确的ID或模式，例如

<provider>/<model-id>

或

sonnet:high

。中继仅接受字母、数字以及

. _ : / -

字符（该值会传递到Windows系统的Shell），因此带有

的通配符模式不会被转发。

The loop

工作循环

Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.

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

1. Write the brief

1. 撰写任务简报

Pi sees only the text you send plus what it can inspect in the workspace - no chat history or shared context. Include the goal, current state, what to change, what to leave untouched, the project's actual gates, and a report contract. Tell pi not to commit. Keep one task per brief. Pi auto-loads

AGENTS.md

CLAUDE.md

context files from the workspace and its parents, so repo instructions reach it without inlining. See references/writing-the-brief.md.

Pi只能看到你发送的文本以及它可以在工作区中检查的内容——无聊天历史或共享上下文。请包含目标、当前状态、需要修改的内容、需要保留不变的内容、项目的实际准入标准，以及报告约定。告知pi不要提交代码。每份简报对应一个任务。Pi会自动从工作区及其父目录加载

AGENTS.md

CLAUDE.md

上下文文件，因此仓库中的说明无需内联到简报中。详情请见references/writing-the-brief.md。

2. Dispatch

2. 分发任务

Use the bundled relay. It pipes the brief to

pi --mode json

on stdin, captures the JSON event stream, and writes

result.json

. (

<skill-dir>

is the installed folder containing this

SKILL.md

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

使用捆绑的中继工具。它会将简报通过标准输入传递给

pi --mode json

，捕获JSON事件流，并写入

result.json

文件。（

<skill-dir>

是包含此

SKILL.md

文件的已安装技能目录。）

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

choose a model: add --model <id from pi --list-models>

选择模型: 添加 --model <pi --list-models中的ID>

choose a provider: add --provider <name>

选择提供商: 添加 --provider <名称>

read-only run (review/diagnosis): add --read-only

只读运行（审核/诊断）: 添加 --read-only

trust project .pi resources: add --approve

信任项目的.pi资源: 添加 --approve

resume the most recent session: add --resume-last (delta brief only)

恢复最近的会话: 添加 --resume-last （仅需增量简报）

resume a specific session: add --session <id> (delta brief only)

恢复特定会话: 添加 --session <ID>（仅需增量简报）

hard time limit (watchdog): add --timeout 2h (the 30m default suits short runs; implementation briefs routinely need 1-2h)

硬时间限制（监控）: 添加 --timeout 2h （默认30分钟适合短任务；实现类简报通常需要1-2小时）

see all options: node .../relay.mjs --help

查看所有选项: node .../relay.mjs --help


The child process's cwd pins the workspace. The relay writes artifacts under the system temp dir
by default and never commits. See [references/dispatch-and-poll.md](references/dispatch-and-poll.md).


子进程的当前工作目录固定为工作区。中继默认将产物写入系统临时目录，且绝不会提交代码。详情请见[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Wait for completion

3. 等待完成

The relay blocks until pi finishes. Run it with the orchestrator's background-command facility, or background it in the shell and poll for

result.json

. A pre-run usage error exits 2 and writes no result; a missing

pi

exits 127 and writes

status: "pi_unavailable"

Trust process state and the working tree over a progress display. Completion means the process exited and

result.json

exists. Pi's full report is the

finalMessage

field in

result.json

(also printed in full on stdout between the report markers).

中继会阻塞直到pi完成任务。可以使用编排工具的后台命令功能运行它，或在Shell中将其置于后台并轮询

result.json

文件。预运行使用错误会以状态码2退出，且不会写入结果；若

pi

不存在则以状态码127退出，并写入

status: "pi_unavailable"

。

优先信任进程状态和工作树而非进度显示。完成意味着进程已退出且

result.json

文件存在。Pi的完整报告位于

result.json

的

finalMessage

字段中（也会完整打印在标准输出的报告标记之间）。

4. Review - do not trust the self-report

4. 审核——不要信任自我报告

Treat pi's final message and gate claims as claims:

Re-run the project's gates yourself.
Read the diff against the brief, starting with
```
touchedFiles
```
.
Run relevant guard skills if installed.
Round-trip migrations and grep for dangling references after removals or renames.

See references/review-and-land.md.

将pi的最终消息和准入标准声明视为待验证的主张：

自行重新运行项目的准入标准检查。
根据简报审核代码差异，从
```
touchedFiles
```
开始。
若已安装相关防护技能，则运行它们。
在删除或重命名后，往返迁移并搜索悬空引用。

详情请见references/review-and-land.md。

5. Land it

5. 完成提交

The implementer edits the working tree; the orchestrator commits. Commit only after the gates pass and the diff holds. If rework is needed, send a delta brief with

--resume-last

--session <id>

, then review again.

实现工具会编辑工作树；由编排者提交代码。仅当准入标准通过且代码差异符合要求时再提交。若需要返工，使用

--resume-last

或

--session <ID>

参数发送增量简报，之后再次审核。

Autonomy and permissions

自主性与权限

Pi has no sandbox and no permission modes. A default headless run reads, writes, edits, and executes shell commands with no prompts - the controls are:

```
--read-only
```
restricts pi's callable tools to
```
--tools read,grep,find,ls
```
across built-in, extension, and custom tools. Installed extension code still runs with the user's host permissions.
The relay passes
```
--no-approve
```
by default, so project
```
.pi
```
settings, extensions, and skills stay untrusted.
```
--approve
```
is the explicit opt-in for a repository the user trusts.
```
touchedFiles
```
and the diff are the record of what changed. Inspect them after every run.

Pi没有沙箱环境和权限模式。默认的无头运行会读取、写入、编辑并执行Shell命令，无任何提示——控制方式如下：

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

Authorization model

授权模型

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing verified, gate-passing work is the agreed contract. Two limits remain: surface, don't absorb (report pi's design decisions, defensible-but-unasked turns, and non-blocking nitpicks) and stop for scope changes (if correct completion needs going beyond the brief, ask instead of expanding the mandate). See references/review-and-land.md.

委托是用户主动选择的操作。一旦用户选择（例如“运行此队列”、“继续”），提交经过验证且符合准入标准的工作就是约定的内容。仍有两个限制：披露而非隐瞒（报告pi的设计决策、合理但未被要求的变更，以及非阻塞性的小问题），以及范围变更时停止（若正确完成任务需要超出简报范围，需先询问用户而非自行扩大任务范围）。详情请见references/review-and-land.md。

References

参考资料

references/writing-the-brief.md - structure, report contract, real gates, stdin delivery, and delta briefs.
references/dispatch-and-poll.md - flags, artifacts,
```
result.json
```
, polling, and failure recovery.
references/review-and-land.md - review checklist, commit boundary, and rework through pi sessions.
references/multi-task-queues.md - sequential queues, constraint carry-forward, progress tracking, and the final coherence pass.

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