pi 系统学习手册 第 05 / 12 章 总目录 单页全本 架构图 GitHub

手册/第 05 章

05

六个关键机制

下面每一条都是「一个真实的问题 → 一个被验证过的解法」。 建议按顺序读,因为它们从协议层一路爬到产品层。点击标题展开。

① 四个 API 统一成一个事件流 pi-ai
"There's really only four APIs you need to speak to talk to pretty much any LLM provider: OpenAI's Completions API, their newer Responses API, Anthropic's Messages API, and Google's Generative AI API."
要和几乎所有 LLM 厂商对话,你其实只需要说四种 API:OpenAI 的 Completions、OpenAI 的 Responses、Anthropic 的 Messages、Google 的 Generative 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_content vs reasoning

值得注意的是现在仓库里的处理方式变了:不是硬编码厂商名,而是做运行时归一化与字段回退 ——例如 OPENAI_COMPLETIONS_REASONING_FIELDS 依次尝试 reasoning / reasoning_content / reasoning_text, max_tokens 与 max_completion_tokens 统一收口到一个上限计算函数。 这是从「补丁」走向「契约」的典型演进。

还有两个作者点名的问题,值得所有做统一 API 的人记住:

!token 与缓存计量是狂野西部
有的厂商在 SSE 开头就报 token,有的只在结尾报;请求一旦 abort 就永远拿不到准确值。pi-ai 只能做 best-effort 统计。
!Google 至今不支持工具调用流式
作者的原话是一句冷笑话级的吐槽:"extremely Google"。

openai-completions.ts:279 anthropic-messages.ts:660 models.ts:1077 · createProvider

② 跨 provider 的上下文交接 handoff
"Context handoff between providers was a feature pi-ai was designed for from the start."
跨 provider 的上下文交接,是 pi-ai 从一开始就设计好的能力。

这是 pi 相对多数 harness 的一个明显差异化能力:会话中途换模型,历史不丢。 代价是必须做一层有损转换——每家厂商对「工具调用」和「思维链」的表示都不同。

  • 从 Anthropic 切到 OpenAI 时,Anthropic 的 thinking trace 会被转成 <thinking>...</thinking> 包裹的内容块
  • 厂商还会往事件流里插入签名 blob,后续带相同消息的请求必须原样回放; 同厂商内换模型也一样
  • 所以这是一条「尽力而为」的转换管线,语义上并不保证等价
工程含义 这解释了一个常见困惑:为什么 pi 的 message 类型看起来比 SDK 更「胖」。 因为它必须能同时容纳四家厂商的私有表示,才能在序列化后仍然可交接。 JSON.stringify(context) 之后换任何模型都能继续—— 这是把「会话」当一等公民的直接结果。

同一条设计线还带来两个能力:全链路 abort(连工具调用阶段也能中断, 并返回部分结果与 stopReason: 'aborted'),以及 浏览器内可用(Anthropic 与 xAI 支持 CORS)。

docs/models.md docs/message-types.md

③ 工具结果拆成「给模型的」和「给界面的」 tool result

这是作者认为「所有统一 LLM API 都缺」的一个抽象。通常工具只能返回一段文本, 于是 UI 想要漂亮地展示结果,就得去 parse 那段文本再重新结构化——既脆弱又浪费。

pi 的做法是让工具同时返回两个东西:

typescript
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 渲染不需要理解业务语义

docs/extensions.md tools/write.ts:82

④ system prompt:从一段文本变成可组装的契约 prompt

博客里给出的原始 system prompt 非常短,核心只有三部分:角色、工具清单、行为准则。

system prompt(2025-11 博客原文节选)
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
...
"pi's system prompt and tool definitions together come in below 1000 tokens."
pi 的 system prompt 加上工具定义,加起来不到 1000 token。

而仓库现状已经演进了:prompt 不再是硬编码字符串,而是由 buildSystemPromptSections() 组装出的若干可独立替换的 section。

section内容谁决定
preamble角色定义;若提供 customPrompt 则整段替换内置默认 / 用户
tools仅列出实际可见的工具及其一行说明当前工具选择
rules按启用工具动态生成(有 bash 无 grep 才提示用 bash 找文件)工具集 + 扩展
docs指向 README / docs / examples 的按需阅读索引内置
project_contextAGENTS.md 等项目上下文文件项目目录
skills可用 skill 的描述(完整指令按需加载)发现结果
addendum--append-system-prompt 追加内容命令行 / 扩展

这个演进很关键:它把「prompt 稳定性」从作者的自我约束变成了结构保证。 工具增删不会污染无关段落,扩展可以只改自己那一节,用户甚至可以整段替换 preamble。 这正好回应了他对「每次发版 prompt 都变」的抱怨。

system-prompt.ts:124 · buildSystemPromptSections :156 · 默认 preamble

⑤ 最小工具集:四个就够 tools
"As it turns out, these four tools are all you need for an effective coding agent. Models know how to use bash and have been trained on the read, write, and edit tools with similar input schemas."
事实证明,这四个工具就是高效 coding agent 所需的全部。模型会用 bash,而且已经被训练过输入 schema 相似的 read / write / edit 工具。
rread
按行读取,支持图片附件;默认前 2000 行,用 offset/limit 翻页。
wwrite
整文件写入,不存在则创建,自动建父目录。
eedit
精确文本替换,oldText 必须完全匹配(含空白)。
$bash
在当前工作目录执行命令,返回 stdout/stderr,可选超时。

另外还有 grep / find / ls 三个只读工具, 以及 Windows 上的 powershell;这些默认关闭,只在需要限制 agent 写权限时启用。 --tools 参数可以精确控制暴露哪些工具,包括按命名空间通配(如 'mcp__radius__*')。

为什么这能成立 因为「工具描述的 token 成本」是每轮都要付的。四个工具 ≈ 几百 token, 而某些 MCP 服务器光工具定义就是 1.4 万~1.8 万 token(见第 07 节)。 在长会话里,这个差值是复利。

tools/index.ts docs/cli.md · --tools

⑥ 默认 YOLO:不做权限系统,改做隔离 security
"pi runs in full YOLO mode and assumes you know what you're doing. It has unrestricted access to your filesystem and can execute any command without permission checks or safety rails."
pi 以完全 YOLO 模式运行,并假设你知道自己在做什么。它可以不受限制地访问文件系统,执行任何命令,没有权限检查,也没有安全护栏。

作者给出的论证是一个三段论,很值得完整理解:

  1. 只要能读私有数据、执行代码、访问网络,数据外泄就无法用提示层拦住了
  2. 要真正拦住,只能切断网络——但那样 agent 基本没用;域名白名单也能被绕过
  3. 所以大多数 harness 的权限提示是安全剧场:反正大家为了干活都会一路点同意

结论不是「不安全没关系」,而是把安全边界从「提示」下移到「隔离」。官方文档把可选方案列得很清楚:

运行方式被保护的是什么强度
直接用当前 OS 用户运行只有该用户访问不到的东西最弱
整个 pi 跑在容器 / VM / 沙箱里未暴露进环境的主机文件与进程最强实用选项
pi 在外,只有内置工具进沙箱仅工具侧动作受限;pi 自身与扩展仍在边界外折中
必须知道的一点 扩展与工具运行在同一个进程、同一套操作系统权限下。 所以「装一个扩展」=「允许它读你的凭据、会话历史和任意文件」。 这条在文档里写得非常直白,也解释了为什么架构图里要把 extensions 单独圈成 security-group。

docs/security.md docs/containerization.md README · 无内置权限系统

本章学习记录

记录仅保存在当前浏览器。