Pi Harness 之书

外观

4.1 Pi 是什么 ​

本页分析版本earendil-works/pi@c13ffe12026-07-30

本章解决什么问题：用第三部分建立的概念框架，回答「Pi 是什么、不是什么、解决什么问题、怎么用」。 前置知识：3.5 Agent 与 Agent Loop、3.6 Agent Harness、Session 与状态。 学习目标：① 能用一句话向别人解释 Pi；② 知道 Pi 的四种使用方式；③ 能把第三部分的每个概念对应到 Pi 的具体组成部分。

一句话定义 ​

Pi 是一个用 TypeScript 编写的开源 Agent Harness 项目，其旗舰产品是运行在终端里的 AI 编程助手（coding agent）pi。

官方 README 的自我定位是（官方说明）：

"This is the home of the Pi agent harness project including our self extensible coding agent."

「self extensible（自我扩展）」是它最鲜明的特点：Pi 的扩展（Extension）、技能（Skill）、主题都是普通的 TypeScript/Markdown 文件，你甚至可以让 Pi 自己给自己写扩展。第七部分会专门展开。

pi --help 的第一行是对它最朴素的描述（真实输出）：

text
pi - AI coding assistant with read, bash, edit, write tools

即：一个自带 read（读文件）、bash（执行命令）、edit（改文件）、write（写文件）四个内置工具的 AI 编程助手——这四个工具正是 3.4 里讲的 Tool Calling 的具体化。

Pi 在分层图中的位置 ​

回顾 3.6 的六层分层，Pi 的 monorepo 恰好按这个分层拆成了不同的 package：

图加载中…

图 4.1-1 Pi 的分层与 package 对应关系
从上到下：用户界面层（coding-agent）调用 Harness 层（agent），Harness 通过统一模型接口（ai）访问各家 LLM 服务；TUI 渲染由独立的 tui 库承担。实线箭头表示「依赖并调用」，虚线表示「仅用于渲染」。

这张图是第五、六部分全部内容的地图：我们会沿着「UI → Harness → 模型接口 → 模型」这条线追踪一次真实请求的完整路径。

Pi 不是什么 ​

初学者容易把几个层面混为一谈，先划清边界：

  • Pi 不是一个 LLM。它自己不做任何推理，所有智能都来自你配置的模型服务（Anthropic、OpenAI、Google 等 20 余家 Provider，见 6.2）。
  • Pi 不是 IDE 或编辑器插件。它运行在终端里；当然你可以在 IDE 的内置终端里用它。
  • Pi 不是云服务。pi 在你的机器上运行，会话数据默认保存在本地 ~/.pi/agent/sessions/（源码事实，见 5.5）；只有对模型 API 的请求会发往网络。
  • Pi 没有内置权限系统。官方 README 明确声明（官方说明）：Pi 默认以启动它的用户权限运行，不内置文件系统/网络/进程级别的权限限制；需要更强隔离时，官方建议用容器或沙箱方案（README「Permissions & Containerization」一节给出三种模式）。这一点与某些同类产品的「逐操作审批」设计不同，是理解 Pi 设计哲学的重要背景。

Pi 解决什么问题 ​

对使用者：在终端里获得一个能读代码、跑命令、改文件、自我扩展的 AI 助手。

对本书读者（学习源码的人），Pi 还解决了另一类问题——它把第三部分的所有抽象概念都给出了生产级实现：

第三部分的概念Pi 中的实现深入章节
统一的模型 API@earendil-works/pi-ai6.1 / 6.2
Agent Loop@earendil-works/pi-agent-core 的 runLoop6.3
工具调用与校验内置 7 个工具 + TypeBox schema6.4
Session 持久化JSONL 会话文件 + 会话树6.5
Context Compaction自动/手动压缩 + 分支摘要6.6
Extension / SkillTypeScript 扩展 + Markdown 技能7.1 / 7.2

四种使用方式 ​

同一个核心，四种外壳（第五、六部分会看到它们共享同一个 AgentSession 核心，这是源码事实）：

  1. 交互模式（TUI）：直接运行 pi，得到一个全功能终端界面。这是默认方式。
  2. 打印模式（print）：pi -p "问题"，一次性输出结果后退出，适合脚本和管道。
  3. JSON / RPC 模式：pi --mode json 把事件流打印成 JSON 行；pi --mode rpc 在 stdin/stdout 上说 JSONL 协议，供其他程序驱动（6.10）。
  4. SDK：在你自己的 Node.js 程序里 import 它，把 Pi 当库用（6.11）。

下面是本书在锁定版本源码上真实采集的交互模式启动画面（无 API Key 场景，tmux 终端 100×30）：

text
 Press ctrl+o to show full startup help and loaded resources.

 Pi can explain its own features and look up its docs. Ask it how to use or extend Pi.

[Context]
  AGENTS.md

[Skills]
  add-llm-provider, find-skills, ssh-skill

[Prompts]
  /cl, /is, /pr, /sa, /wr

[Extensions]
  import-repro.ts, prompt-url-widget.ts, redraws.ts, tps.ts

 Warning: No models available. Use /login to log into a provider via OAuth or API key.
 ...
────────────────────────────────────────────────────────────────
/Volumes/macport/pibook/pipibook/_sources/pi (main)
0.0%/0 (auto)                                                unknown

值得注意的细节：即使还没配置任何模型，Pi 已经从当前项目加载了 Context（AGENTS.md）、Skills、Prompts 和 Extensions——它加载的正是 Pi 仓库自己的 .pi 资源目录。「Pi 用 Pi 的机制开发 Pi」，这就是 self extensible 的日常形态。

生态一览 ​

围绕核心仓库还有几个相关项目，本书的态度如下：

项目是什么官方/第三方本书是否覆盖
pi.dev官网：文档、演示官方引用其文档作为「官方说明」
earendil-works/pi-chatSlack/聊天自动化官方（独立仓库）仅说明关系，不分析
agegr/pi-web「Web UI for the pi coding agent」（其仓库简介），TypeScript第三方社区项目在 6.10 讨论 RPC 协议时说明这类集成的接入方式；不逐行分析其源码，与本书锁定版本的兼容性尚未确认

第三方 Web UI 之所以可能存在，正是因为 Pi 提供了稳定的 RPC/JSON 协议边界——这是 Harness 分层设计的直接收益。

实践任务 ​

🛠 实践任务第一次从源码启动 Pi

目标：在本地从源码启动 Pi 交互模式，亲眼看到上面的启动画面。

前提：已完成 4.2 的源码 checkout；Node.js ≥ 22.19（Pi 的 engines 要求）。

步骤：

  1. 在 Pi 仓库根目录安装依赖：npm install --ignore-scripts（官方 README 推荐的安装方式）
  2. 补齐生成的模型数据：npm run hydrate:model-data（需要网络；跳过会报 Cannot find module '.../providers/data/amazon-bedrock.json'——这是我们实际踩过并验证的错误）
  3. 运行 ./pi-test.sh --no-env（--no-env 会临时清空所有 API Key 环境变量，保证与本章截图一致）
  4. 首次会弹出「Trust project folder?」对话框，选择 Trust (this session only)
  5. 观察启动画面后，按两次 Ctrl+C 退出

如何判断成功：看到 [Context]/[Skills]/[Prompts]/[Extensions] 清单与「No models available」警告。

常见错误：① Node 版本过低——升级到 22+；② 忘记 --ignore-scripts 也能装上，但与官方供应链加固实践不一致；③ 在别的目录运行 pi-test.sh 是允许的（脚本内部用绝对路径定位源码）。

对应源码：pi-test.sh 用 tsx 直接运行 packages/coding-agent/src/cli.ts，见下方引用。

pi-test.sh · tsx
earendil-works/pi@c13ffe1第 57 行在 GitHub 查看 ↗
从源码直接运行 pi 的入口：用 tsx 免编译执行 coding-agent 的 cli.ts。

本章小结 ​

  • Pi = Agent Harness 项目 + 终端 coding agent 产品；核心特征是 self extensible。
  • Pi 不是模型、不是 IDE、不是云服务，也没有内置权限系统（官方建议容器化获得隔离）。
  • 四种使用方式：TUI / print / JSON·RPC / SDK，共享同一个核心。
  • 生态：官网 pi.dev、官方 pi-chat、第三方 pi-web；本书聚焦核心仓库。
  • 关键术语：coding agent、self extensible、print 模式、RPC 模式。
  • 自测问题：① Pi 的四个默认内置工具是哪几个？② 为什么说「Pi 不是 LLM」？③ 无 API Key 启动 Pi 时它仍然加载了什么？
  • 下一章：4.2 仓库、版本与历史。

本书分析的 Pi 版本：earendil-works/pi@c13ffe1（2026-07-30）

教学用途 · 基于 MIT 许可的 Pi 源码