Example

在没有人的情况下运行 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 里运行时会改变行为。

退出码意味着什么

模式 成功的运行 失败的最终响应
print 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.