Pi Agent 非交互模式
除了交互式对话，Pi Agent 还提供了三种非交互模式，适用于脚本集成、自动化流程和程序间通信。
Print 模式（-p）
Print 模式是最常用的非交互模式，执行一次性问答后输出结果并退出。
基本用法
最简单的形式是在 -p 后面直接跟一句提问，AI 回答完就退出。
$ pi -p "帮我总结一下这个项目的结构" 这是一个 TypeScript + Vite 项目，源码集中在 src/ 目录下。 入口文件是 src/main.ts，工具函数位于 src/utils/，共 18 个模块。
用 @ 引用文件，让 AI 读取指定文件的内容：
$ pi -p @README.md "这段文档的主要内容是什么" 这份 README 介绍了安装步骤、环境变量配置和三条常用命令。
用管道把命令输出直接喂给 AI，适合处理日志、文档等文本：
$ cat README.md | pi -p "用三句话总结这段文字" 1. 项目要求 Node 20 以上版本。 2. 安装依赖后先把 .env.example 复制为 .env。 3. 日常调试用 npm run dev，发布构建用 npm run build。
@ 同样可以引用图片，让 AI 分析图像内容：
$ pi -p @screenshot.png "图片中显示的错误信息是什么" 截图中的报错是 Module not found: Can't resolve './utils/format'， 说明 src/index.ts 里的相对路径拼写有误。
用 --name 给会话命名，之后可以在交互模式中接着这条线继续问：
$ pi --name "快速审查" -p "审查 src/ 目录下的代码质量" 代码整体质量良好，有 3 处可以改进： 1. src/api/user.ts 缺少对分页参数的校验。 2. src/utils/format.ts 的日期格式化未处理时区。 3. src/db/query.ts 的裸抛异常建议补充错误码。
指定模型
用 --provider 加 --model 指定模型，也可以把两者合并写成 provider/model 的组合形式。
$ pi --provider openai --model gpt-4o -p "帮我重构这段代码的逻辑" 重构建议：把 src/service/order.ts 中 120 行的 createOrder 拆成 校验参数、计算金额、落库三个函数，并为每个函数补充单元测试。
下面这种组合写法与上一条完全等价，写起来更短：
$ pi --model openai/gpt-4o -p "帮我重构这段代码的逻辑"
模型名后加冒号和推理等级，可以控制这次调用的思考深度：
$ pi --model sonnet:high -p "这个复杂的算法有什么潜在问题" 主要风险有三点：递归深度没有上限会导致栈溢出； 缓存键未包含用户身份，存在越权读取的可能； 批量写入缺少事务包裹，失败时会出现半提交状态。
--model 中的 :thinking 后缀（如 sonnet:high）与 --thinking 参数都能设定推理等级。
建议二选一，避免两处写法不一致时难以排查。
用 --models 限定可用的模型范围，多个模式之间用逗号分隔：
$ pi --models "claude-*,gpt-4o" -p "审查代码" 审查完成：共发现 2 个阻塞问题和 5 个改进建议， 详细列表已按严重程度排序。
工具控制
通过命令行参数控制 AI 能使用哪些工具，是让非交互模式安全跑在脚本里的关键。
Pi Agent 在非 Windows 平台内置 7 个工具：read、write、edit、bash、grep、find、ls。
Windows 下 bash 由 powershell 替代。
用 --tools 做白名单，只保留指定工具，例如不改动任何文件的只读模式：
$ pi --tools read,grep,find,ls -p "审查代码不修改" 审查结果：共 4 个问题，其中 1 个涉及并发写入， 完整报告已输出到终端，本次未修改任何文件。
用 --exclude-tools 排除指定工具：
$ pi --exclude-tools bash -p "分析代码但不执行命令" 分析结论：该模块的性能瓶颈在循环内的重复文件读取， 建议把目录列表提到循环外，预计可减少 80% 的 I/O。
用 --no-builtin-tools 禁用全部内置工具，AI 只能基于对话内容回答，扩展和自定义工具仍然可用：
$ pi --no-builtin-tools -p "纯问答" Quicksort 的平均时间复杂度是 O(n log n)， 最坏情况是 O(n^2)，出现在已排序数组上选取首元素为主元时。
需要把扩展、自定义工具也一起禁用时，改用 --no-tools。
JSON 模式（--mode json）
JSON 模式将所有事件以 JSON 行（JSONL）格式输出，适合程序解析和处理。
$ pi --mode json "总结项目结构"
{"type":"session","version":3,"id":"019f8c2e-7a41-7b3d-9e5f-2c6a1d84b0e7","timestamp":"2026-08-31T02-40-11-000Z","cwd":"/Users/runoob/projects/runoob-demo"}
{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{...}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{...}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}
首行是会话元数据头，记录格式版本、会话 ID、时间戳和工作目录。
之后的每一行都是一个独立的 JSON 事件，包含事件类型和对应的数据。
这种模式适合以下场景：
| 场景 | 说明 |
|---|---|
| 数据处理管道 | 把事件流接入后处理脚本，逐行解析并加工 |
| 行为监控分析 | 记录并分析 AI 的每一次工具调用与决策过程 |
| 自定义工具链 | 在事件流之上构建自己的自动化工作流 |
RPC 模式（--mode rpc）
RPC 模式通过 stdin/stdout 的 JSONL 协议实现进程间通信。
它允许另一个程序通过标准输入发送命令，并从标准输出读取响应。
RPC 模式支持扩展 UI 协议，使远程客户端能够呈现 confirm 对话框、选择列表等交互元素。
这种模式适合以下场景：
| 场景 | 说明 |
|---|---|
| 编辑器插件 | 在 VS Code 等编辑器扩展中集成 Pi Agent |
| 自定义前端 | 基于 RPC 协议构建自己的 Pi Agent 界面 |
| 后台服务 | 把 Pi Agent 作为子进程嵌入更大的系统 |
RPC 模式和 JSON 模式是面向开发者的高级特性。
作为初学者，你大概率只需要交互模式和 Print 模式。
当你需要将 Pi Agent 集成到工具链中时，可以再回来深入学习这两种模式。
模式对比
三种非交互模式的差异主要体现在交互性和输出格式上，按下表选择即可。
| 模式 | 命令 | 交互性 | 输出格式 | 适用场景 |
|---|---|---|---|---|
| 交互模式 | pi（默认） | 实时对话 | 终端 TUI 渲染 | 日常开发、交互式编程 |
| Print 模式 | pi -p | 一次回答 | 纯文本 | 脚本集成、快速查询 |
| JSON 模式 | pi --mode json | 事件流（非交互） | JSONL 事件流 | 程序解析、管道处理 |
| RPC 模式 | pi --mode rpc | 持续通信 | JSONL 双向协议 | 编辑器集成、进程通信 |
CLI 参数速查
下表按用途归类列出 pi 命令的常用参数，可与交互模式中的命令互相配合。
| 分类 | 参数 | 说明 |
|---|---|---|
| 模型选项 | --provider name | 指定 AI 提供商 |
| 模型选项 | --model pattern | 指定模型 ID，支持 provider/id 和 :thinking 格式 |
| 模型选项 | --api-key key | 直接传入 API Key（最高优先级） |
| 模型选项 | --thinking level | 推理等级：off/minimal/low/medium/high/xhigh/max |
| 模型选项 | --models patterns | 逗号分隔的模型列表，限制 Ctrl+P 循环范围 |
| 会话选项 | -c, --continue | 继续最近的会话 |
| 会话选项 | -r, --resume | 浏览并选择历史会话 |
| 会话选项 | --session path|id | 使用指定的会话文件或 UUID |
| 会话选项 | --fork path|id | 从指定会话分叉出新会话 |
| 会话选项 | --name, -n name | 设置会话显示名称 |
| 会话选项 | --no-session | 不记录会话 |
| 会话选项 | --export <输入> [输出] | 导出会话为 HTML（输出路径可省略） |
| 工具选项 | --tools, -t list | 白名单特定工具 |
| 工具选项 | --exclude-tools, -xt list | 禁用特定工具 |
| 工具选项 | --no-builtin-tools, -nbt | 禁用所有内置工具 |
| 工具选项 | --no-tools, -nt | 禁用所有工具（纯对话模式） |
| 资源选项 | -e, --extension source | 加载扩展（可重复使用） |
| 资源选项 | --skill path | 加载 Skill（可重复使用） |
| 资源选项 | --theme path | 加载主题（可重复使用） |
| 其他选项 | -a, --approve | 本次运行信任项目本地文件 |
| 其他选项 | --no-context-files, -nc | 禁用 AGENTS.md/CLAUDE.md 自动加载 |