自动化与程序集成
Pi 提供四个不同层级的程序入口。最小的入口通常最可靠:只需要最终文本就用 Print,需要同进程控制才用 SDK。
先做选择
| 目标 | 推荐入口 | 进程关系 | 输出 |
|---|---|---|---|
| shell 脚本只需要最终回复 | pi -p | 子进程 | 文本 |
| 日志、评测或 UI 需要完整事件 | pi --mode json | 子进程 | 单向 JSONL |
| IDE 或服务需要持续双向控制 | pi --mode rpc | 长驻子进程 | 双向 JSONL |
| Node.js 应用需要完整会话对象 | coding-agent SDK | 同进程 | TypeScript API |
| 只需要模型或自定义 Agent 循环 | pi-ai / pi-agent-core | 同进程 | 更底层 API |
记法:要文本用 -p,要事件用 JSON,要控制用 RPC,要对象用 SDK。
不要用 RPC 解决一次性文本任务,也不要为了“未来可能需要”把完整 coding-agent SDK 嵌入第一版服务。
Print:最短的自动化路径
Print 模式输出最终回复后退出:
pi -p "概览当前项目,并列出应该运行的检查命令"它也会合并管道输入:
git diff --stat HEAD | pi -p --no-session --no-approve --no-tools \ --no-context-files --no-extensions --no-skills \ --no-prompt-templates --system-prompt "" \ --append-system-prompt "" \ "根据输入生成一段简洁的变更摘要"这个例子显式选择:
--no-session:不保存一次性任务。--no-approve:不加载项目级受保护资源和设置。--no-tools:不向模型暴露可调用工具。--no-context-files与三个--no-*资源参数:忽略上下文文件,以及全局和项目级 Extensions、Skills、Prompt Templates。- 两个空系统提示参数:忽略用户级
SYSTEM.md和APPEND_SYSTEM.md;Pi 内置系统提示仍然存在。
这些参数组合后,除 Pi 内置系统提示外,模型只消费管道内容和显式提示。单独使用 --no-approve 并不会禁用 AGENTS.md、CLAUDE.md 或用户级 Extension;单独使用 --no-tools 也不会阻止 Extension 工厂在启动时执行。
CI 中不要依赖交互式信任提示,因为 Print、JSON 和 RPC 模式不会显示它。需要项目 Skill 或 Extension 时,审查后使用 --approve;需要真正的最小资源基线时,像上面一样显式关闭各类资源。
获取稳定退出结果
脚本至少区分:
- 进程是否成功启动。
- 模型运行是否返回错误。
- 输出是否满足你的业务格式。
- 超时或取消是否生效。
不要仅以“stdout 非空”判断任务成功。对于机器消费结果,优先使用结构化工具、JSON 模式或应用自己的 schema 校验。
JSON:消费完整事件流
JSON 模式把会话头和所有事件按 JSON Lines 输出到 stdout:
pi --mode json --no-session --no-approve \ "读取 README 并概览项目" \ 2>pi-error.log | jq -c 'select(.type == "message_end")'输出中的每一行都是独立 JSON 对象。下面的 "..." 字段表示为说明而省略的内容,不是完整协议示例:
{"type":"session","version":3,"id":"...","timestamp":"...","cwd":"..."}{"type":"agent_start"}{"type":"message_update","usage":{"...":"..."},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"..."}}{"type":"message_end","message":{"role":"assistant","...":"..."}}{"type":"agent_end","messages":[{"...":"..."}],"willRetry":false}{"type":"agent_settled","aborted":false}JSON/RPC 的 message_update 是增量事件,不包含 SDK 事件中的累积 message 或 partial。按 contentIndex 拼接增量,并以 message_end.message 为最终结果。
需要处理的主要事件:
| 事件 | 用途 |
|---|---|
message_update | 文本或思考内容增量 |
tool_execution_start/update/end | 工具生命周期 |
message_end | 一条完整消息 |
turn_end | 一次模型回复及其工具结果 |
agent_end | 一个底层 Agent 运行结束;自动恢复或队列仍可能继续 |
agent_settled | 当前会话运行不会再自动继续;不代表业务结果一定成功 |
compaction_start/end | 上下文压缩 |
auto_retry_start/end | 自动重试 |
queue_update | steering 与 follow-up 队列变化 |
把 stderr 和 stdout 分开。协议事件在 stdout,诊断信息应单独记录,避免污染 JSONL。
RPC:控制一个长驻 Pi 子进程
RPC 模式通过 stdin 接收命令,通过 stdout 返回响应和异步事件:
pi --mode rpc --no-session --no-approve每条命令占一行:
{"id":"state-1","type":"get_state"}{"id":"run-1","type":"prompt","message":"概览当前项目"}{"id":"abort-1","type":"abort"}响应复用请求 ID:
{"id":"run-1","type":"response","command":"prompt","success":true,"data":{"disposition":"started"}}success: true 只表示 prompt 已接受、入队或被处理。之后的模型失败通过事件流报告,不会为同一个请求再发第二个失败响应。根据 data.disposition 区分启动、入队和被扩展处理;若为 handled,没有启动运行,不应等待 agent_settled。
严格处理 JSONL 分帧
RPC 只使用 LF,也就是 \n,作为记录分隔符:
- 按
\n拆分记录。 - 输入可以接受
\r\n,解析前移除末尾\r。 - 保留最后一个尚未出现换行的半包。
- 不要使用会把
U+2028或U+2029当换行的通用 line reader。
Pi 官方明确指出 Node.js readline 不符合这个 RPC 分帧要求。TypeScript 子进程客户端优先复用 coding-agent 包中的 RpcClient 实现,或自己按字节缓存并只寻找 0x0A。
运行中发送消息
Agent 正在运行时,普通 prompt 必须指定投递方式:
{ "id": "steer-1", "type": "prompt", "message": "先停下写操作,只汇报当前发现", "streamingBehavior": "steer"}steer:当前 assistant turn 的工具执行结束后、下一次模型调用前送达。followUp:Agent 完成现有工作后送达。
缺少 streamingBehavior 时,运行中的 prompt 会被拒绝。也可以直接发送 steer 或 follow_up 命令。
SDK:在 Node.js 中直接控制会话
安装并固定版本:
最小内存会话:
import { createAgentSession, SessionManager,} from "@earendil-works/pi-coding-agent";
const { session } = await createAgentSession({ sessionManager: SessionManager.inMemory(), tools: ["read", "grep", "find", "ls"],});
const unsubscribe = session.subscribe((event) => { if ( event.type === "message_update" && event.assistantMessageEvent.type === "text_delta" ) { process.stdout.write(event.assistantMessageEvent.delta); }});
try { await session.prompt("概览当前目录,只读取文件");} finally { unsubscribe(); session.dispose();}几个重要细节:
SessionManager.inMemory()不写会话文件。tools选择示例中的只读内置工具;SDK 默认不加载内置 MCP 扩展。自行加载扩展时要重新检查可达工具和副作用,工具选择不是系统沙箱。session.prompt()等待当前 prompt 的 Agent 运行结束。- 无论成功、失败还是取消,都调用
session.dispose()。
从旧 SDK 迁移模型运行时
旧版 SDK 示例可能还传入 AuthStorage 和 ModelRegistry。从 Pi 0.80.8 开始,编码 Agent SDK 使用异步 ModelRuntime:
import { createAgentSession, ModelRuntime, SessionManager,} from "@earendil-works/pi-coding-agent";
const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({ modelRuntime, sessionManager: SessionManager.inMemory(),});不要把旧版认证对象和新版 modelRuntime 混用。升级时对照与你安装版本一致的 SDK 文档与 changelog。
SDK 中的 MCP 与 Codemode
CLI 默认加载内置 MCP、Codemode 和工具搜索扩展;SDK 的 createAgentSession() 不会自动加载它们。需要时,在资源加载器中加入工厂,并在使用前绑定扩展:
import { createAgentSession, createCodemodeExtension, createMcpExtension, createToolSearchExtension, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager,} from "@earendil-works/pi-coding-agent";
const cwd = process.cwd();const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: getAgentDir(), extensionFactories: [ createCodemodeExtension({ mode: "on" }), createToolSearchExtension(), createMcpExtension(), ],});await resourceLoader.reload();const settingsManager = SettingsManager.create(cwd);settingsManager.applyOverrides({ defaultTools: ["+codemode", "+tool_search"] });const { session } = await createAgentSession({ resourceLoader, settingsManager, sessionManager: SessionManager.inMemory(),});
try { await session.bindExtensions({}); await session.prompt("只列出可用工具,不执行写操作");} finally { session.dispose();}这段代码会读取当前用户和受信任项目的 MCP 配置;绑定后服务器可能启动或发起网络连接。先审查配置,不要在不可信环境直接运行。+codemode 和 +tool_search 保留其他默认工具,并不意味着只读。更完整示例见 Pi SDK Codemode 和 MCP。
Web 应用的推荐边界
浏览器 / Vue │ 只理解应用自己的事件协议 ▼应用后端 ├── 用户认证、限流、审计 ├── 模型与工具白名单 ├── Pi SDK 或受控 RPC 子进程 └── 供应商凭据浏览器不要直接持有供应商密钥,也不要把完整 coding-agent SDK 打进客户端 bundle。Vue 侧只需要稳定事件和停止接口,具体实现见 SDK 与 Vue 最小集成。
生产检查清单
- Pi 与 Node.js 版本固定并记录。
- 非交互模式显式选择
--approve或--no-approve。 - 工具使用 allowlist,默认不开放写入和 shell;单独检查 MCP 与 Codemode 的间接可达能力。
- stdout 协议流与 stderr 诊断分离。
- RPC 按 LF 做半包和粘包测试。
- 请求、响应和工具调用使用稳定 ID。
- 取消信号传到模型和工具。
- 超时、输出大小、并发和重试有上限。
- 日志中的 prompt、工具参数和凭据经过脱敏。
- 真实模型测试之外,还有确定性的假事件测试。
什么时候不要使用 Pi coding-agent
如果产品只需要:
- 调用一个模型并流式输出文本:直接使用
@earendil-works/pi-ai。 - 自己定义工具循环和消息状态:使用
@earendil-works/pi-agent-core。 - 一个固定、无工具的后台任务:供应商 SDK 可能更小。
coding-agent 的价值是完整会话、编码工具、资源加载和 Pi 工作流。没有这些需求时,少一层通常更容易运维。
相关入口: