第 1 章 · Pi 是什么：极简终端编码智能体

本章目标：理解 pi 的"harness（挽具）"设计理念与四种运行模式，能说清它与 IDE 内置智能体、重型 Agent 框架的本质区别，并对五大扩展点建立全景认知。

1.1 什么是编码智能体的"harness"

在 AI 编码工具的语境里，harness 指"套在模型外面的那层马具"：它把模型接上工具（读写文件、执行命令）、管理对话上下文与会话持久化，然后把控制权交还给模型。harness 本身不规定工作流，只提供可靠的执行底座。

pi 的设计哲学是最小核心 + 按需扩展：

核心默认只给模型 4 个工具：read（读文件）、write（写文件）、edit(补丁修改)、bash（执行命令）——模型用它们组合出几乎一切能力；
另有一组只读工具（grep、find、ls）可通过工具选项开启；
子代理、计划模式这类"重特性"故意不做进核心，需要时让 pi 自己帮你写一个扩展，或安装第三方 pi 包。

这与很多"全家桶"式工具形成鲜明对比：全家桶替你决定工作流，功能越多菜单越乱；pi 则主张让 pi 适配你的工作流，而不是反过来。

1.2 四种运行模式

模式	启动方式	适用场景
交互模式（TUI）	`pi`	日常人机结对编程
Print 模式	`pi -p "提示词"`	一次性任务、shell 管道
JSON 模式	`pi --mode json`	程序解析事件流
RPC 模式	`pi --mode rpc`	被其他进程集成驱动
SDK	在 Node 应用中引入	把 pi 嵌入你自己的产品

bash

# 交互模式：进入当前项目目录直接启动
cd /path/to/project
pi

# Print 模式：一次性提问，输出后退出
pi -p "总结这个仓库的目录结构"

# 管道输入也支持
cat README.md | pi -p "用三句话概括这份文档"

同一套模型配置、会话存储和扩展体系贯穿四种模式——你在交互模式里调好的 provider 配置，脚本模式里同样生效。后续章节会逐一深入：第 4 章讲交互模式，第 5 章讲会话，第 14–16 章讲 SDK/RPC/JSON 与自动化。

1.3 与 IDE 内置智能体、重型框架的对比

vs IDE 内置智能体（如 VS Code Copilot Chat）

IDE 智能体深度绑定图形界面与厂商托管服务；pi 是纯终端程序，SSH 到远程服务器照样能用；
IDE 智能体的行为定制空间有限；pi 的编辑器、快捷键、系统提示、工具集全部可替换或扩展。

vs 重型 Agent 框架（LangGraph/CrewAI 等）

那类框架解决的是"如何编排多个 LLM 调用"，你要自己搭会话持久化、上下文压缩、UI；
pi 直接给你一个生产可用的终端智能体，同时暴露 SDK/RPC 让你编程接管——相当于"编排框架 + 成品客户端"二合一。

一句话定位

pi = 极简内核的终端编码智能体 + TypeScript 扩展系统 + 可嵌入 SDK。它既是日常工具，也是构建你自己智能体产品的地基。

1.4 五大扩展点全景

pi 的可定制性由五个层次组成，复杂度从低到高：

Prompt Templates（提示词模板）：Markdown 文件定义可复用的提示词，/模板名 展开注入；
Skills（技能）：带元数据的技能包（SKILL.md），按需被模型发现并加载，以 /skill:名称 显式调用；
Extensions（扩展）：TypeScript 程序，可注册自定义斜杠命令、自定义工具、替换编辑器 UI、拦截事件；
Themes（主题）：终端配色方案；
Pi Packages（包）：把以上资源打包成 npm/git 包分发安装。

text

定制成本低 ◄──────────────────────────────► 定制能力强
 [Prompt Templates] → [Skills] → [Themes] → [Extensions] → [Pi Packages]
   提示词复用        能力注入    外观换肤     行为编程        打包分享

本教程将按此顺序逐章展开（第 8–13 章）。核心心法：能用模板解决的不写技能，能用技能解决的不写扩展。

1.5 适用与不适用场景

适合用 pi：

终端为主力工作环境的开发者，尤其在远程服务器/容器内作业；
希望精确控制智能体能做什么（工具白名单、项目信任机制）的团队；
想把编码智能体嵌入自家产品（SDK/RPC）的团队；
对订阅账号敏感、想自由切换几十家模型供应商的重度用户。

不太适合：

完全没有命令行经验、只想点按钮的用户（先去用 IDE 内置智能体）；
需要 GUI 代码评审界面的场景（pi 的输出是文本流，可配合 /share 导出 HTML 分享）。

1.6 本章小结

pi 是极简终端编码 harness：4 个默认工具 + 按需扩展，不预设工作流；
五种形态：交互 TUI、Print、JSON、RPC、SDK，配置与会话全线打通；
相比 IDE 智能体更开放可远程，相比编排框架更是开箱即用的成品；
扩展点五层：模板 → 技能 → 主题 → 扩展 → 包，成本递增按需选用。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. pi 默认给模型的四个工具是？

2. 想在 shell 脚本里一次性向 pi 提问并拿到输出后退出，应使用？

3. 关于 pi 的设计理念，下列说法正确的是？

4. 想把"团队统一的代码评审提示词"做成可复用资产，成本最低的方式是？

🛠️ 动手实践

通读 pi 仓库 README 的 Philosophy（哲学）一节，用自己的话写下 3 条 pi 与你所熟悉工具的差异。
列出你最近一周的 3 个编码任务，判断各自适合哪种运行模式（交互/Print/JSON/RPC）。
浏览 ~/.pi/agent/ 目录（若已安装），确认 settings.json、sessions/ 等结构是否与本章描述一致。

准备好了就进入下一章：安装与快速上手，把 pi 跑起来。

第 1 章 · Pi 是什么：极简终端编码智能体 ​

1.1 什么是编码智能体的"harness" ​

1.2 四种运行模式 ​

1.3 与 IDE 内置智能体、重型框架的对比 ​

1.4 五大扩展点全景 ​

1.5 适用与不适用场景 ​

1.6 本章小结 ​