非交互模式与脚本集成

前面两章都在讲交互模式——你在终端里跟 pi 面对面聊天。但不是所有场景都需要聊天。比如写个脚本自动审查代码、在 CI 里让 pi 跑一次检查就退出、或者把 pi 的输出接到另一个程序里继续处理。

pi 专门为这些场景准备了三套非交互模式。

Print 模式：一行命令搞定一次问答

加 -p 参数，pi 执行一次任务后输出纯文本结果并退出，不启动交互界面：

pi -p "总结一下这个项目的代码结构"

pi 启动 → 分析项目 → 输出结果 → 退出，全程不弹 TUI。这就是 Print 模式最基本的用法。

带文件一起问

pi -p @README.md "用三句话概括这份文档"
pi -p @src/app.ts "这个文件里有哪些潜在的性能问题"
pi -p @screenshot.png "截图中显示了什么"

管道输入

Print 模式会读取管道传来的内容，合并到你的提示词里。这是它最强大的用法之一：

cat README.md | pi -p "总结这段文字"
git diff HEAD~3 | pi -p "审查最近 3 次提交的变更，列出潜在风险"
tail -100 error.log | pi -p "分析这些错误日志，总结最多发的问题类型"

你不用手动把内容贴进去——任何命令的输出都能直接喂给 pi 分析。

命名会话

Print 模式也会保存会话。取个名字方便以后在交互模式里继续讨论：

pi --name "发布前审查" -p "审查 src/ 最新变更有没有安全问题"

之后用 pi -r 就能找到这个会话，切回交互模式跟 pi 继续深聊。

指定模型

pi --model claude-sonnet-4-20250514 --thinking-level high -p "这段代码的架构设计有什么问题"
pi --provider openai --model gpt-4o -p "重构下面这个函数"

控制工具权限

跑在 CI 里的时候，你大概率不想让 pi 动你的文件：

# 只读模式：能看能搜，不能写
pi --tools read,grep,find,ls -p "审查代码，只报告问题不修改"

# 不让执行命令
pi --exclude-tools bash -p "分析代码结构，别跑任何东西"

# 纯对话模式，所有工具都关掉
pi --no-tools -p "解读一下这段日志的含义"

项目信任

Print 模式默认不弹信任提示。想让 pi 加载项目本地资源，加 --approve：

pi --approve -p "用项目配置的模型审查代码"

不想加载就用 --no-approve，或者在全局设置里配 defaultProjectTrust。

JSON 模式：给程序读的结构化输出

加 --mode json，pi 把所有事件以 JSONL 格式（一行一个 JSON 对象）输出到 stdout：

pi --mode json -p "总结项目结构"

输出大概是这样的：

{"type":"session_start","sessionId":"abc123","timestamp":1234567890}
{"type":"message_start","message":{"role":"user","content":[{"type":"text","text":"总结项目结构"}]}}
{"type":"tool_call","tool":"ls","params":{"path":"."}}
{"type":"tool_result","tool":"ls","output":"...目录列表..."}
{"type":"message_update","message":{"role":"assistant","content":[...]}}
{"type":"message_end","message":{"role":"assistant","content":[...]}}
{"type":"agent_end"}

每行是一个独立事件，包含类型标签和对应的数据。你可以在 Python / Node.js 脚本里逐行解析，也可以用 jq 在命令行中提取关键字段。

典型用法

提取 AI 的最终回复：

pi --mode json -p "审查 src/" | \
  jq -r 'select(.type=="message_end") | .message.content[0].text'

记录完整工具调用链，用于调试审计：

pi --mode json -p "找出所有未使用的导入" > audit-$(date +%Y%m%d).jsonl

之后用 grep 或脚本分析 pi 调了哪些工具、看了哪些文件、每一步花了多久。

接入监控管道：

pi --mode json -p "检查安全问题" | \
  jq 'select(.type=="tool_call" or .type=="tool_result")' | \
  tee security-check.jsonl

RPC 模式：进程间通信

加 --mode rpc，pi 通过 stdin/stdout 的 JSONL 协议与另一个程序持续通信：

pi --mode rpc

pi 启动后不会退出，一直等待 stdin 上的指令，结果输出到 stdout。这使它成为一个可被其他程序调用的 Agent 服务。

这种模式是给编辑器插件和自定义前端设计的。比如 VS Code 扩展通过 RPC 协议调用 pi 做代码补全、诊断、重构。你还可以在 RPC 模式下渲染 confirm 对话框、选项列表等交互元素——给远程客户端用的。

四种模式对比

模式	命令	交互方式	输出格式	什么时候用
交互	pi（默认）	实时对话	TUI 渲染	日常开发，你跟 pi 聊天
Print	pi -p	一次回答	纯文本	脚本、快速查询
JSON	pi --mode json	一次输出	JSONL 事件流	程序解析、管道处理
RPC	pi --mode rpc	持续双向通信	JSONL 协议	编辑器集成、自定义前端

把 pi 放进你的工作流

以下是四种真实的集成场景，每条命令都能直接复制跑。

场景一：Git pre-commit hook 代码审查

创建 .git/hooks/pre-commit：

#!/bin/bash
echo "pi is reviewing staged changes..."
git diff --cached | pi -p "审查这些变更，只列出潜在问题，不要改代码" \
  --tools read,grep,find,ls

场景二：定时任务自动生成周报

# crontab: 每周五 18:00 跑
cd ~/project && \
  git log --since="1 week ago" --oneline | \
  pi -p "根据这些 commit 生成一份中文周报，按功能模块分组" \
  > weekly-report.md

场景三：管道链式处理

把 pi 当成一个”理解代码”的 filter，嵌在管道中间：

# 列出需要重构的函数名
find src/ -name "*.ts" -exec cat {} + | \
  pi -p "列出最需要重构的 5 个函数名，每行一个，不要任何解释" --no-tools

场景四：CI 流水线安全检查

# GitHub Actions 示例
- name: AI Security Review
  run: |
    pi -p "审查 PR 变更，有安全问题输出 'BLOCK: 原因'" \
      --tools read,grep,find,ls \
      --model claude-sonnet-4-20250514 --thinking-level medium