Pi Agent 非交互模式

除了交互式对话，Pi Agent 还提供了三种非交互模式，适用于脚本集成、自动化流程和程序间通信。

Print 模式（-p）

Print 模式是最常用的非交互模式，执行一次性问答后输出结果并退出。

基本用法

# 基本问答
pi -p "帮我总结一下这个项目的结构"

# 带文件的问答
pi -p @README.md "这段文档的主要内容是什么"

# 管道输入：将命令输出传给 AI
cat README.md | pi -p "用三句话总结这段文字"

# 带图片的问答
pi -p @screenshot.png "图片中显示的错误信息是什么"

# 命名会话（方便之后在交互模式中继续）
pi --name "快速审查" -p "审查 src/ 目录下的代码质量"

指定模型

# 使用特定模型
pi --provider openai --model gpt-4o -p "帮我重构这段代码的逻辑"

# 使用带推理等级的模型
pi --model sonnet:high -p "这个复杂的算法有什么潜在问题"

# 限制模型循环范围
pi --models "claude-*,gpt-4o" -p "审查代码"

工具控制

# 只读模式：仅允许读取类工具
pi --tools read,grep,find,ls -p "审查代码不修改"

# 排除特定工具
pi --exclude-tools bash -p "分析代码但不执行命令"

# 禁用所有内置工具
pi --no-builtin-tools -p "纯问答"

JSON 模式（--mode json）

JSON 模式将所有事件以 JSON 行（JSONL）格式输出，适合程序解析和处理。

$ pi --mode json -p "总结项目结构"
{"type":"session_start","sessionId":"abc123",...}
{"type":"message_start","message":{...},...}
{"type":"message_update","message":{...},...}
{"type":"message_end","message":{...},...}
{"type":"agent_end",...}

每行是一个独立的 JSON 对象，包含事件类型和对应的数据。

这种模式特别适合：

将 Pi Agent 集成到数据处理管道中
监控和分析 AI 的行为与决策过程
构建自定义的工具链和自动化工作流

RPC 模式（--mode rpc）

RPC 模式通过 stdin/stdout 的 JSONL 协议实现进程间通信。

它允许另一个程序通过标准输入发送命令，并从标准输出读取响应。

RPC 模式支持扩展 UI 协议，使远程客户端能够呈现 confirm 对话框、选择列表等交互元素。

这种模式适合：

编辑器插件（如 VS Code 扩展）集成 Pi Agent
构建自定义的 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 参数速查

分类	参数	说明
模型选项	--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	设置会话显示名称
工具选项	--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 自动加载

返回顶部

菜鸟教程