← Pi Agents

写出一个 Pi 能完成的任务

Pi 不会在工具调用之前提问,所以任务的陈述必须自带范围、验收检查,以及文件;下面给出一种行得通的形状。

最常见的失败不是因为模型不好,而是因为一个从没说清楚"完成"是什么意思的任务。你写下"清理一下 auth 模块",Pi 跑了四十轮,产出的东西你现在还得像自己从头写一遍那样仔细审阅。

Pi 在这方面帮不上忙,因为它不会开口问。quickstart.md 说 Pi 会展示它执行的每一次文件读取、每一次搜索、每一条命令和每一次编辑,并且它不会在每次工具调用之前询问。任务的规格说明完全在你的提示词里。

快速上手实际推荐的是什么

quickstart.md 中的那些示例共享同一种形状:

总结 @meeting-notes.md,把行动项保存到 action-items.md。
说明这个仓库是如何组织的,以及如何运行它的各项检查。
比较 @previous.csv 与 @current.csv,总结其中重要的变更。

三个属性,三条里全都具备:

  1. 一个具名的输入,用 @ 附上。
  2. 一个具名的输出——一个要写入的文件,或一个要返回的答案。
  3. 一个有界的范围。

没有一条写着"并且要干得好"。每一条都说了要读什么、要产出什么。

下面把同一个意思作为对照摆出来,因为"清理一下"正是大多数任务实际到来时的形状:

清理一下 auth 模块。
清理 src/auth/:删掉没有任何地方导入的那两个导出,把 300 行的
verify() 拆成 parse() 和 check()。
保持 src/auth/index.ts 中的调用签名不变。
不添加任何依赖。
用以下命令验证:pnpm typecheck && pnpm test auth

第二条并不是为了长而长。它点明了目录、改动的形状、边界,以及那个能判断它是否奏效的命令。第一条只点明了一个名词和一种心情。

把输入附加进来,不要描述它

usage.md 给出了操作方式:输入 @ 搜索一个文件并把它加进你的提示词,按 Tab 补全路径,粘贴一张图片或把它拖进一个兼容的终端。

附加胜过描述,因为文件内容直接进入请求,而不需要一次工具往返。它还消除了一整类失败:Pi 猜你指的是四个名字相似的文件中的哪一个。

说出验收标准

你能对任务做出的最有力的一处修改,是说清"完成"长什么样:

给 src/cli.ts 加一个 `--json` 标志,把会话条目按 JSONL 打印出来。

要求:
- 默认行为不变。
- `--json` 为每个条目打印一个 JSON 对象,与会话文件格式一致。
- 错误写到 stderr,并以状态码 2 退出。

用以下命令验证:npm test && node bin/cli.js --session tests/fixtures/minimal.jsonl --json | head -5
不要修改 tests/fixtures 下的任何文件。

最后两行比前三行做的事更多。一个具名的命令给了 Pi 可以运行的东西,一个具名的禁止路径给了它一道没有理由就不会跨越的边界。

保持在一个跨度内

压缩(compaction)是在用户消息边界处下刀的,compaction.md 把 用户消息跨度(user-message span)描述为一条用户消息,加上直到下一条用户消息为止的每一轮。一个再也没有收到其他用户消息的任务就是一个单独的跨度——这意味着,如果它长得很大,它正是最有可能被切得很别扭的那一个。

这是"要有意识地引导,而不是从不引导"的一个论据。usage.md 区分了在一次运行中途改变方向的两种方式:

你想做什么 操作
调整当前任务 输入一条消息并按 Enter
在当前任务之后追加工作 输入一条消息并按 Alt+Enter
把排队的消息还给编辑器 按 Alt+Up
停止当前任务 按 Escape

用 Enter 发出的消息会等到当前响应和它的工具调用结束,然后引导下一个响应。用 Alt+Enter 发出的后续跟进(follow-up)消息会等到 Pi 完成当前任务。中止会把排队的消息还给编辑器,这正是"停下来"代价很低的原因。

    flowchart TD
  T["一个 Pi 能完成的任务"] --> S{"它有具名的、<br/>可检查的结果吗?"}
  S -->|否| FORM["重写它:<br/>点明命令,点明边界"]
  S -->|"是"| SMALL{"它是一个跨度吗?<br/>其中没有用户消息"}
  FORM --> SMALL
  SMALL -->|是| RUN["发出去"]
  SMALL -->|"否,它变大了"| STEER["引导:Enter 细化,<br/>Alt+Enter 在其后追加工作"]
  RUN --> B{"是方法错了,<br/>而不是细节错了?"}
  STEER --> B
  B -->|细节| STEER
  B -->|方法| BRANCH["/tree,编辑一条更早的<br/>用户消息,提交"]
  

底部那个分叉是值得记住的区分:引导修改的是当前分支,而分支是从一个选定的点重新开始。 一个打错的细节是引导问题;一个错误的抽象不是,因为已经完成的工作仍留在转录记录里。

什么时候该分支而不是引导

引导修改的是当前分支。当方法本身错了时,适用第 4 章的答案:/tree,选一条更早的用户消息,编辑它,提交。旧的尝试留在文件里,但不进请求。

一条粗略的规则:要细化就引导,要重来就分支。如果 Pi 已经建出了错误的抽象,再怎么引导也挽回不了那份代价。

说出不该做什么

否定式表述成本低廉且有效,前提是它们具体:

不要添加新依赖。
不要修改 src/auth/index.ts 中的公开函数签名。
不要运行 `git commit`。
不要往 src/auth/ 之外的任何地方写入。

“不要造成破坏"不是约束,“不要往 src/auth/ 之外写入"才是。

自己先把命令跑一遍

如果一个验证命令将决定任务是否成功,那就要知道它现在是否通过。针对一个本来就在失败的测试套件,把任务表述成"让 npm test 通过”,这是一个有一半没说出来的任务。

基线:`npm test` 目前在 tests/auth.test.ts 上失败,报错 "expected 401, got 403"。
任务:修复 token 刷新路径,使 tests/auth.test.ts 通过。
不要修改测试文件。

比较的两边现在都已知,这正是"已修复"变得无歧义的原因。

在 print 模式下工作

不是每个任务都需要一个交互式会话。cli.md:

pi --print "Summarize this repository"
git diff | pi --print "Review this change"
pi --mode json "Inspect this repository" > events.jsonl

--print 会运行给定的提示词,把最后的助手文本写到 stdout,然后退出。@path 参数把一个文本文件或一张图片包含进第一条提示词,管道传入的 stdin 会被前置到它前面。-- 会停止选项解析,这样提示词就可以以 - 开头。

当 stdin 和 stdout 都是终端时,Pi 会打开终端 UI,除非 --print、--mode json 或 --mode rpc 选择了另一个界面。当两条流中有任意一条被重定向、而又没有选择 JSON 或 RPC 时,Pi 使用 print 模式。

复用任务,不要重新键入

重新键入一个行之有效的提示词,是这套措辞已经超出当前会话的信号。问题不再是要键入什么,而是应该由什么来承载它;答案有四级代价各不相同的台阶。第 11 章就是从中挑出一级的那套流程;本部分在它之后的一切,都是把那一个机制推到它所能到达的极限。