手册/第 05 章
六个关键机制
下面每一条都是「一个真实的问题 → 一个被验证过的解法」。 建议按顺序读,因为它们从协议层一路爬到产品层。点击标题展开。
① 四个 API 统一成一个事件流 pi-ai
这个判断是整个模型层的地基。它意味着 pi-ai 不需要为每一家厂商写一套逻辑,
只需要写四个 HTTP 适配器,再用「模型描述」把厂商差异声明出来。
但四个协议只是起点,真正的成本在厂商各自的「方言」上。作者列过一份很实在的清单:
- Cerebras、xAI、Mistral、Chutes 不喜欢
store字段 - Mistral、Chutes 用
max_tokens而不是max_completion_tokens - Cerebras、xAI、Mistral、Chutes 不支持 system prompt 用
developer角色 - Grok 系列不喜欢
reasoning_effort - 不同厂商把推理内容放在不同字段:
reasoning_contentvsreasoning
值得注意的是现在仓库里的处理方式变了:不是硬编码厂商名,而是做运行时归一化与字段回退
——例如 OPENAI_COMPLETIONS_REASONING_FIELDS 依次尝试
reasoning / reasoning_content / reasoning_text,
max_tokens 与 max_completion_tokens 统一收口到一个上限计算函数。
这是从「补丁」走向「契约」的典型演进。
还有两个作者点名的问题,值得所有做统一 API 的人记住:
openai-completions.ts:279 anthropic-messages.ts:660 models.ts:1077 · createProvider
② 跨 provider 的上下文交接 handoff
这是 pi 相对多数 harness 的一个明显差异化能力:会话中途换模型,历史不丢。 代价是必须做一层有损转换——每家厂商对「工具调用」和「思维链」的表示都不同。
- 从 Anthropic 切到 OpenAI 时,Anthropic 的 thinking trace 会被转成
<thinking>...</thinking>包裹的内容块 - 厂商还会往事件流里插入签名 blob,后续带相同消息的请求必须原样回放; 同厂商内换模型也一样
- 所以这是一条「尽力而为」的转换管线,语义上并不保证等价
JSON.stringify(context) 之后换任何模型都能继续——
这是把「会话」当一等公民的直接结果。
同一条设计线还带来两个能力:全链路 abort(连工具调用阶段也能中断,
并返回部分结果与 stopReason: 'aborted'),以及
浏览器内可用(Anthropic 与 xAI 支持 CORS)。
③ 工具结果拆成「给模型的」和「给界面的」 tool result
这是作者认为「所有统一 LLM API 都缺」的一个抽象。通常工具只能返回一段文本, 于是 UI 想要漂亮地展示结果,就得去 parse 那段文本再重新结构化——既脆弱又浪费。
pi 的做法是让工具同时返回两个东西:
const weatherTool: AgentTool<typeof weatherSchema, { temp: number }> = { name: 'get_weather', execute: async (toolCallId, args) => ({ // 给模型看的:文本或 JSON output: `Temperature in ${args.city}: ${temp}°C`, // 给 UI 看的:结构化数据,不用再解析文本 details: { temp }, }), };
- 参数用 TypeBox schema + AJV 自动校验,失败时给出详细错误信息
- 工具还能返回图片等附件,并按各 provider 的原生格式附着
- 这条设计让「模型看到的内容」和「人看到的内容」可以解耦, 也让 TUI 渲染不需要理解业务语义
④ system prompt:从一段文本变成可组装的契约 prompt
博客里给出的原始 system prompt 非常短,核心只有三部分:角色、工具清单、行为准则。
You are an expert coding assistant. You help users with coding tasks by reading files, executing commands, editing code, and writing new files. Available tools: - read: Read file contents - bash: Execute bash commands - edit: Make surgical edits to files - write: Create or overwrite files Guidelines: - Use bash for file operations like ls, grep, find - Use read to examine files before editing ...
而仓库现状已经演进了:prompt 不再是硬编码字符串,而是由
buildSystemPromptSections() 组装出的若干可独立替换的 section。
| section | 内容 | 谁决定 |
|---|---|---|
preamble | 角色定义;若提供 customPrompt 则整段替换 | 内置默认 / 用户 |
tools | 仅列出实际可见的工具及其一行说明 | 当前工具选择 |
rules | 按启用工具动态生成(有 bash 无 grep 才提示用 bash 找文件) | 工具集 + 扩展 |
docs | 指向 README / docs / examples 的按需阅读索引 | 内置 |
project_context | AGENTS.md 等项目上下文文件 | 项目目录 |
skills | 可用 skill 的描述(完整指令按需加载) | 发现结果 |
addendum | --append-system-prompt 追加内容 | 命令行 / 扩展 |
这个演进很关键:它把「prompt 稳定性」从作者的自我约束变成了结构保证。 工具增删不会污染无关段落,扩展可以只改自己那一节,用户甚至可以整段替换 preamble。 这正好回应了他对「每次发版 prompt 都变」的抱怨。
system-prompt.ts:124 · buildSystemPromptSections :156 · 默认 preamble
⑤ 最小工具集:四个就够 tools
另外还有 grep / find / ls 三个只读工具,
以及 Windows 上的 powershell;这些默认关闭,只在需要限制 agent 写权限时启用。
--tools 参数可以精确控制暴露哪些工具,包括按命名空间通配(如 'mcp__radius__*')。
⑥ 默认 YOLO:不做权限系统,改做隔离 security
作者给出的论证是一个三段论,很值得完整理解:
- 只要能读私有数据、执行代码、访问网络,数据外泄就无法用提示层拦住了
- 要真正拦住,只能切断网络——但那样 agent 基本没用;域名白名单也能被绕过
- 所以大多数 harness 的权限提示是安全剧场:反正大家为了干活都会一路点同意
结论不是「不安全没关系」,而是把安全边界从「提示」下移到「隔离」。官方文档把可选方案列得很清楚:
| 运行方式 | 被保护的是什么 | 强度 |
|---|---|---|
| 直接用当前 OS 用户运行 | 只有该用户访问不到的东西 | 最弱 |
| 整个 pi 跑在容器 / VM / 沙箱里 | 未暴露进环境的主机文件与进程 | 最强实用选项 |
| pi 在外,只有内置工具进沙箱 | 仅工具侧动作受限;pi 自身与扩展仍在边界外 | 折中 |