在没有人的情况下运行 Pi
print 与 JSON 模式、你不说时模式如何被选定、退出码在各自模式里意味着什么,以及 --tools 如何收窄一个无人值守的智能体。
一个 CI 作业和一个 pre-commit 钩子都需要没有终端的 Pi。模式决定输入如何进入智能体、输出如何被暴露、失败如何被报告。下面的每一条论断都是在 1.0.4 上已观察的:以子进程的方式驱动随附的 pi 二进制文件,配一个脚本化的模型——真实的命令行、模式选择和退出码,没有凭据,也没有 provider。
选择模式
pi --print "Summarize the changes" # one final string, then exit
pi --mode json "Review this repository" > events.jsonl # events on stdout
git diff | pi --print "Review this change" # piped stdin, prepended to the prompt
pi --mode json "@notes.md" "summarise" # @path includes a text file
pi --mode json -- "-5 degrees is cold" # -- stops option parsing
pi --print "Review this change" --tools read,grep,find,ls --no-session当 stdin 和 stdout 都是终端时,Pi 会打开终端 UI,除非选定了一个模式。当两条流中有任意一条被重定向、而又没有选定 JSON 或 RPC 时,它选择 print 模式——所以一个只是把输入管进来、再捕获输出的脚本会隐式地得到 print 模式。不管怎样还是显式一点;一个依赖 TTY 检测的脚本,在从一个交互式 shell 里运行时会改变行为。
退出码意味着什么
| 模式 | 成功的运行 | 失败的最终响应 |
|---|---|---|
| stdout 上的最终文本,退出码 0 | 非零退出,消息在 stderr 上,stdout 上什么也没有 | |
| JSON | stdout 上的事件,退出码 0 | 事件流里同一个失败,仍然退出码 0 |
JSON 的不对称是刻意的:一个只检查 $? 的脚本会把一次失败的评审叫做成功。如果这次调用本身抛出,Pi 仍然以非零退出。print 模式不暴露任何中间事件——整个界面就是最终文本。
收窄一个无人值守的智能体
在 --tools read,grep,find,ls 下,一个索要 bash 的模型收到一个失败的工具结果,而那条命令没有运行;用默认工具它运行了。--no-session 没有写会话文件;而没有它时,一次对着真实目录的运行在智能体目录下写了一个。
| 旗标 | 已观察的效果 |
|---|---|
--tools read,grep,find,ls |
bash、edit 和 write 不被提供;一次对 bash 的请求失败,什么也不运行 |
--no-session |
内存中的会话,什么也不持久化 |
机制与局限
有文档记载:cli-integration.md 钉住模式选择规则,以及 print 和 JSON 的退出行为,而 cli.md 钉住输入表(message、@path、管道进来的 stdin、--),外加用 --print 而不是 --mode text 做一次性的那条提醒。从 1.0.4 起,--tools 单独并不能移除 MCP 工具;--no-mcp 是连接不到任何服务器的那条有文档记载的路。**已观察:**上面两张表由 headless.test.ts 断言,它在 1.0.4 上对着随附的二进制文件运行,模型通过一个扩展注入:真实的子进程、真实的配置目录、真实的参数解析。
--tools 收窄模型的词汇表;它不改变进程的操作系统权限,也不约束从未索要工具的代码。工具选择不是沙箱。print 和 JSON 是一次性的:进程从不接受第一条之后的第二条指令。本示例不展示一个真实模型如何回答。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.