← Pi Agents

无头 Pi

在没有人附着的情况下运行 Pi——print 与 JSON 模式、模式如何被选定、没有终端时什么还能活下来,以及每种模式的代价与给予。

一个 CI 作业需要对一份 diff 跑一次评审。一个 pre-commit 钩子需要对刚刚改变的东西做个摘要。两者都没有人,也都不想要一个终端。

pi 已经处理了这件事,而相关的处理几乎完全记录在一个地方:cli-integration.md。但有意思的问题不是"我怎么把答案打印出来"——而是当智能体没有一个人附着时,有什么不同了,因为你在前面二十九章里建起的大多数东西,都假定有一个人在。

四种模式,以及它们之间变了什么

cli-integration.md 先把这条不变式说在前面:“四种模式使用同一个智能体、同一批会话、同一批资源和同一批工具。模式决定输入如何进入 Pi、输出如何被暴露,以及进程是否还能继续接收更多命令。”

模式 界面 存活期 什么时候用它
交互式 终端 UI 直到用户退出 有一个人正在直接使用 Pi
print stdout 上的最终文本 一次调用 一个脚本需要最终的助手响应
JSON stdout 上的 JSONL 事件 一次调用 一个进程需要一次运行的结构化进展
RPC JSONL 命令、响应与事件 长期存活 一个进程需要双向控制

那张表就是整章的缩影。最后一列是一个关于你的调用方需要什么的判断,而不是关于 Pi 有多强大。其余一切都是细节。

那张表底下的形状,才是本章真正的内容:

    flowchart TD
  CORE["同一个智能体、会话、资源与工具"] --> A["交互式"] --> A2["驱动者:人"]
  CORE --> B["print"] --> B2["驱动者:脚本"]
  CORE --> C["JSON"] --> C2["驱动者:脚本"]
  CORE --> D["RPC"] --> D2["驱动者:进程"]
  CORE -.-> E["SDK"] --> E2["驱动者:你的进程"]
  

一个内核,五种界面,以及 top.txt 所记录的同一个划分——“谁在驱动,谁在看”。第二行改变的是观察者,而每一个观察者都有一份不同的失败契约:一个人看到的是转录记录,--print 给出一个字符串加一个退出码,JSON 给出事件、而对于一次失败的运行不给出退出信号,RPC 给出相互关联的响应与事件,SDK 给出类型化对象。还要注意那条虚线边:cli-integration.md 说得很直白——“SDK 不是一种 CLI 模式。“它把智能体嵌进一个 Node.js 或 Bun 进程,而不是跨越一道进程边界,而第 34 章会单独讲它。

把 SDK 与那四种模式分开,是第一件要弄对的事。

你不指定时,模式如何被选定

这件事记录得非常精确,而它值得知道,因为这意味着一个脚本可能碰巧就能工作:

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

所以 pi --print "..." 是显式的,git diff | pi --print "Review this change" 是显式外加输入,而 pi --mode json "..." > events.jsonl 是显式加重定向。但一个仅仅把东西管进去、再捕获 stdout 的脚本,是隐式得到 print 模式的。

cli-integration.md 在 print 那一节确认了这一点:“当没有显式选择模式时,非 TTY 的 stdin 或 stdout 也会选定 print 模式。这样就允许管道式的输入与输出,而不必加 --print。”

不管怎样,还是显式一点好。一个依赖 TTY 检测的脚本,会在有人从一个交互式 shell 里运行它的那一刻改变行为。

print 模式"运行给定的提示词,把最终的助手文本写到 stdout,然后退出。”

pi --print "Summarize the changes in this repository"

三条有文档记载的行为,值得围着它们搭建:

  • **中间事件不被暴露。**如果你需要知道 Pi 做了什么,print 模式告诉不了你。
  • **错误去 stderr。**stdout 只承载最终的助手文本。
  • 退出码跟随停止原因。“一条带有 error 或 aborted 停止原因的最终助手响应会产生一个非零退出码。“那正是一个 CI 步骤应当据此分流的契约。

关于 --mode text 有一句提醒。cli.md 指出 --mode text “在 stdin 和 stdout 都是终端时不会强制一次性执行”,并说你应当为此行为使用 --print。这两个旗标不能互换。

JSON 模式:是进展,而不只是一个结果

JSON 模式"写一个会话头,后面跟着智能体会话事件与会话事件,以换行分隔的 JSON 形式”:

pi --mode json "Review this repository" > events.jsonl

cli-integration.md 坚持这个区分:“这是结构化的事件输出,不是单一的 JSON 结果,也不是对模型响应格式的约束。”

这里的退出码规则不一样,而它会咬到一个 CI 作业。JSON 模式:“一次失败或被中止的助手响应会出现在事件流里,但它本身不产生非零退出码。当成功或失败要紧时,请检查那些事件。如果这次调用抛出了错误,Pi 仍然以非零退出。”

那是一个刻意的对称破缺。print 模式用它的退出码报告失败;JSON 模式用它的流报告失败。如果你的脚本只检查 $?,它会把一次失败的评审当成一次成功的。

还有两条流上的规则,cli-integration.md 和 json.md 都说了:stdout 专留给 JSONL,诊断信息去 stderr;以及持续地读 stdout,因为一个停止消费记录的读者,会在管道缓冲区满时让 Pi 卡住。

输入的几种形式,以及其中一种会失效

cli.md 给出了输入表,它适用于除 RPC 以外的每一种模式:

输入 行为
message 提供一条初始提示词
@path 在第一条提示词里包含一个文本文件或图片
管道进来的 stdin 把它的内容前置到第一条提示词前
-- 停止选项解析,好让一条提示词能以 - 开头

@path 从当前工作目录解析,而工作目录还控制项目配置、资源发现与会话分组——所以在一场无头运行里,cwd 不是装饰性的。它决定哪些扩展和上下文文件被加载。这既是一个功能性的事实,也是一个与安全相关的事实,而最后一章会回到它。

-- 值得单独占一行,因为它的缺失是一个真实的 bug:一条以 - 开头的提示词会被当成选项而不是文本解析,于是脚本悄悄地把错误的东西发了出去。

约束一个无头智能体可以做什么

选项与模式无关,所以你不离开 CLI 就能收窄一场无人值守的运行:

pi --print "Review this change" \
  --tools read,grep,find,ls \
  --no-mcp \
  --model sonnet:high \
  --no-session

--tools 是彻底替换默认选择,而不是往里面添加,所以把你想要的每个工具都点名。默认集合是 read、bash、edit 和 write;这条命令没有点名 bash、edit 或 write 中的任何一个,所以在这四个之中,智能体能查看而不能改变。按它陈述的宽度去读这个论断。它讲的是模型被给予了什么,而不是进程能够到什么东西,而这是两个不同的问题。

**--no-mcp 出现在那条命令里是有理由的,而 1.0.4 就是那个理由。**从 1.0.4 起,--tools 不移除 MCP 工具:它们会被保留,除非某个条目以 mcp__ 开头。没有 --no-mcp,一个配置了 MCP 服务器的智能体目录仍然拥有它们,而一个 MCP 工具完全能改动一棵工作树——所以上面那条四工具论断在这样的机器上会是假的。注意 --tools read,grep,find,ls,'mcp__*' 不能替代它:一个点名了每一个 MCP 工具的模式会让它们保持注册状态,而在默认的 codemode 暴露方式下,它们仍然可以被模型自己写的一个脚本调用。条目可以是带 * 的模式,这就是你保留一个服务器、丢掉其余的方式:--tools read,bash,'mcp__radius__*'。要把它们全部去掉,那是 --no-mcp 或 --exclude-tools 'mcp__*'。

这条命令保证什么、不保证什么

值得分三部分说,因为把三者揉成一团,正是一个无人值守的作业最终得到一条比旗标所暗示的更弱的边界的方式。

它做什么
模型的词汇表 有界。bash、edit 和 write 没有被声明给模型,而一个模型不会调用它未被给予的东西。这就是本章的测试所观察到的:一次对 bash 的请求以一个失败的工具结果回来,而那条命令没有运行
MCP 工具 有界,由 --no-mcp 划定:它不连接任何服务器,不留任何 MCP 工具,也不留 /mcp。省掉它,这个界就不成立
Pi 进程本身 完全没有界。--tools 配置的是给予模型的东西;它不改变运行 Pi 的那个进程的操作系统权限,也不约束从未请求工具的任何代码

第三行才是对任何无人值守之事要紧的那一行。一个被加载进 Pi 进程的扩展拥有该进程的权限,并且不必查阅工具列表;一个指示模型运行一个随附脚本的技能,会让那个脚本拿到该账户的全部触及范围;你自己的宿主代码在同一个进程里。工具选择收窄的是模型。它不是沙箱,也不是遏制。

如果你需要第三行也有界,那是一条操作系统边界——一个容器、一个微型虚拟机、一个进程干脆就不持有的凭据——而第 42 章就是讲这个差别的那一章。在你把这条命令当成横在一个模型与你的工作树之间的唯一东西之前,先读它。

--no-session 使用一个不被持久化的内存中会话,这对于一个你永远不想恢复的作业是对的。注意它的对偶:因为否则会话会被自动保存,一场对着一个真实目录的无头运行会写出一个按该目录分组的会话文件。

--offline 禁用自动的网络活动,包括模型目录刷新,它等价于 PI_OFFLINE=1。-a / --approve 和 -na / --no-approve 这一对是一次性的信任决定,而 security.md 明确说在 print、JSON 和 RPC 模式里没有可以用来询问的提示——所以你必须显式地决定它。

一个关于分叉与改名的脚注

cli-integration.md 以一些值得知道的东西收尾,如果你曾经以自己的名义发布 Pi。一个 package.json 可以设置:

{
  "piConfig": {
    "name": "my-agent",
    "configDir": ".my-agent"
  }
}

改动顶层 bin 字段会设定可执行文件的名字。这些设置"影响 CLI 横幅、配置路径,以及派生出来的环境变量名”——所以一次改名改变的是设置与会话住在哪里,而不只是这个程序怎么称呼自己。

运行了什么

本章的一切都是在 examples/ch32-headless/ 里、以子进程的方式对着随附的 pi 二进制文件运行的。一个小扩展把 faux provider 注册为一个模型,并从环境变量取它的脚本,于是真实的命令行、模式选择与退出码都在没有凭据的情况下被演练。这个接缝第一次尝试就奏效了:没有任何东西导入 Pi 的内部实现。

  • print 模式只把最终文本写到 stdout 并以 0 退出,而一次失败的最终响应以非零退出,消息在 stderr 上,stdout 上什么也没有;
  • JSON 模式在事件流里报告同一个失败,并以 0 退出,所以一个只检查 $? 的脚本会把一次失败的评审叫做成功;
  • 在 stdin 和 stdout 都被重定向而没有给出模式时,Pi 选择了 print 模式;
  • 管道进来的 stdin 被前置到第一条提示词前,@notes.md 把该文件的内容放进了第一条提示词,而 -- 让一条提示词能以一个短横开头;
  • 在 --tools read,grep,find,ls 下,一个索要 bash 的模型得到一个失败的工具结果,而那条命令没有运行;用默认工具它运行了;
  • --no-session 没有写会话文件,而没有它时一次运行在智能体目录下写了一个。

全部与本章相符。模型是脚本化的,所以这展示的是进程拿一个响应做什么,而不是一个真实模型如何回答。

本章没有解决什么

print 模式给你一个字符串。JSON 模式给你一串记录,而对于一次失败的运行不给退出码信号。两者都不让你在第一条指令被接受之后再发一条——进程已经在退出了。那是一次性集成的边界,而它是一个出于设计的边界:cli-integration.md 说 JSON 模式的进程"为该次运行流出事件然后退出;它不接受之后的命令。”

下一章逐条地把这条流拆开,因为下一个决策不是要不要无头,而是你要在那些记录之上建什么。

下一章:JSON 事件流——分帧规则、事件词汇表,以及重建契约。