# Pi Agent 项目学习大纲

> 项目仓库：<https://github.com/earendil-works/pi>
> 本地源码：`C:\pi_agent_study\pi-main`
> 适用读者：Java 后端开发者，有前后端基础，Agent 零基础
> 配套网页课程：本目录下 `01` ~ `14` 号 HTML 文件（每讲一页）

Pi 是一个**极简、可扩展的 Agent Harness（代理框架）**：它把「大模型请求 → 工具执行 → 结果回填 → 再次请求」的循环封装成可插拔的运行时，并附带一个可日常使用的编码代理 CLI。整个 monorepo 从底层的遥测/Schema 到上层的交互式终端，共 11 个核心 package，是学习「一个生产级 Agent 系统如何分层」的极佳样本。

## 学习路径总览

| 阶段 | 讲次 | 主题 | 建议时长 |
|------|------|------|----------|
| 一、准备与全景 | 第 1 讲 | Agent 零基础：LLM、消息与工具调用 | 2~3 小时 |
| 一、准备与全景 | 第 2 讲 | Pi 项目全景：monorepo 结构与各 package 职责 | 2 小时 |
| 一、准备与全景 | 第 3 讲 | 安装与使用初体验：从 /login 到多模式运行 | 2~3 小时 |
| 二、模型层 | 第 4 讲 | pi-ai（上）：统一 LLM API——消息、流式与模型目录 | 3~4 小时 |
| 二、模型层 | 第 5 讲 | pi-ai（下）：Provider 适配、认证与工具调用协议 | 3~4 小时 |
| 三、Agent 内核 | 第 6 讲 | pi-agent-core（上）：Agent Loop 与事件流 | 4 小时 |
| 三、Agent 内核 | 第 7 讲 | pi-agent-core（下）：工具定义、校验与执行策略 | 4 小时 |
| 四、编码代理 | 第 8 讲 | pi-coding-agent 架构：AgentSession 与核心模块 | 4 小时 |
| 四、编码代理 | 第 9 讲 | 系统提示词、上下文组装与压缩（Compaction） | 3~4 小时 |
| 四、编码代理 | 第 10 讲 | 内置工具集与会话持久化（JSONL 树、分支、Fork） | 4 小时 |
| 四、编码代理 | 第 11 讲 | 扩展系统：自定义工具、事件拦截与 UI 集成 | 4~5 小时 |
| 四、编码代理 | 第 12 讲 | Skills、提示模板、主题与 Pi Packages 生态 | 3 小时 |
| 五、集成与实战 | 第 13 讲 | TUI、Codemode、MCP 与自动化（RPC / SDK） | 4 小时 |
| 五、集成实战 | 第 14 讲 | 安全、容器化与综合实战项目 | 4~6 小时 |

每讲学习节奏建议：**先读官方文档 → 再读关键源码 → 完成实践任务 → 回答自测问题**。

---

## 第 1 讲 Agent 零基础：LLM、消息与工具调用

**学习目标**：建立 Agent 领域的核心心智模型。理解 LLM API 的本质（无状态的请求-响应）、消息角色体系（system / user / assistant / toolResult）、工具调用（Tool Call）闭环，以及「Agent Loop」为什么是所有 Agent 框架的心脏。全程用 Java 后端熟悉的概念做类比。

**知识点**
1. LLM API 的本质：类似一个无状态的 HTTP RPC——每次请求都要带上完整「上下文」（历史消息数组），服务端不保存会话状态；所谓「记忆」只是把历史重新发一遍。
2. 消息角色：`system`（系统提示词，相当于环境配置）、`user`（用户输入）、`assistant`（模型输出，可含文本与工具调用块）、`toolResult`（工具执行结果回填）。
3. 工具调用闭环：模型在回复中发出 `toolCall`（工具名 + JSON 参数）→ 运行时执行真实代码 → 把结果包成 `toolResult` 消息追加到历史 → 再次请求模型 → 模型基于结果继续，直到不再需要工具。
4. Agent Loop：上述「请求-执行-回填-再请求」的循环；一个 turn = 一次模型请求 + 它触发的工具执行；steering（中途插话）与 abort（取消）如何介入循环。
5. Context Window 与 Token：上下文窗口限制、为什么需要裁剪历史与压缩（compaction）、缓存（prompt caching）为何与上下文稳定性相关。
6. Agent = LLM + 工具 + 循环 + 状态管理。Harness（框架/挽具）一词的含义：Pi 不训练模型，它负责围绕模型的一切工程。

**关键源码与文档**
- `packages/coding-agent/docs/how-pi-works.md`（官方架构总览，精读）
- `packages/agent/src/agent-loop.ts`（对照循环源码，只看结构）
- `packages/agent/README.md`（事件序列图）

**实践任务**：在任意 LLM Playground 中手工完成一次「伪工具调用」：你扮演运行时，让模型给出工具调用 JSON，你执行后把结果贴回去，观察模型如何继续。

**自测问题**：① 为什么说 LLM API 是无状态的？② 一个 turn 由什么组成？③ toolResult 消息由谁产生、包含什么？④ 如果不裁剪历史会发生什么？

---

## 第 2 讲 Pi 项目全景：monorepo 结构与各 package 职责

**学习目标**：掌握 Pi 仓库 11 个核心 package 的职责、依赖方向与分层理由，建立「源码地图」，后续每一讲都知道自己在地图的哪一层。理解自底向上的构建顺序（telemetry → schema → chord → tui → codemode → mcp → ai → durable → env → agent → coding-agent）。

**知识点**
1. 顶层结构：`packages/`（11 个库）、`apps/`（p2、p3 实验性应用）、`.pi/`（Pi 用自身管理自身：extensions / skills / prompts）、`scripts/`（构建检查）。
2. 各 package 职责一览：
   - `pi-telemetry`：厂商中立的遥测契约与适配器（最底层）；
   - `pi-schema`：JSON Schema 校验（TypeBox 兼容），工具参数校验的基础；
   - `chord`：跨进程对象运行时（contracts / documents / store / plugins / HTTP / workers），`pi-durable` 的地基；
   - `pi-tui`：终端 UI 库，差分渲染、组件体系；
   - `codemode`：让模型编写 TypeScript 脚本来调用工具的模式；
   - `pi-mcp`：独立、轻量的 MCP（Model Context Protocol）客户端；
   - `pi-ai`：统一多厂商 LLM API（消息、流式、模型目录、认证）；
   - `pi-durable`：实验性持久化 Agent 运行时（进程崩溃可恢复）；
   - `pi-env`：环境/进程抽象；
   - `pi-agent-core`：Agent 运行时（循环、工具执行、状态、事件流）；
   - `pi-coding-agent`：交互式编码代理 CLI（最终产品）。
3. 依赖方向图：`coding-agent → agent → ai → (schema/telemetry/mcp/tui/…)`；为什么依赖只允许向下。
4. 工程实践：npm workspaces monorepo、`npm run build` 的手工串联顺序、biome lint、vitest 测试、AGENTS.md（项目对 AI 协作者的规则）——这本身是「Agent 时代的工程规范」样本。

**关键源码与文档**
- 根目录 `README.md`、`package.json`（workspaces 与 build 脚本顺序）
- 各 `packages/*/README.md`（通读第一屏即可，建立索引）
- `AGENTS.md`（了解项目如何要求 AI 协作者）

**实践任务**：画出自己的 package 依赖图；对照 `npm run build` 脚本里的构建顺序验证你的理解。

**自测问题**：① pi-agent-core 与 pi-ai 的边界在哪？② 为什么 MCP 客户端要独立成包且不依赖官方 SDK？③ `.pi/` 目录为什么能证明「Pi 可自我托管」？

---

## 第 3 讲 安装与使用初体验：从 /login 到多模式运行

**学习目标**：先把 Pi 用起来，获得对「Agent 编码助手」的直接体感，为后续源码学习提供现象层参照。掌握交互模式的完整工作流与四种运行接口（interactive / print / JSON / RPC）。

**知识点**
1. 安装：`curl -fsSL https://pi.dev/install.sh | sh`（Windows: `powershell -c "irm https://pi.dev/install.ps1 | iex"`）；npm 方式 `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`；要求 Node ≥ 22.19。
2. 首次配置：`pi` 启动 → `/login` 选择厂商登录（OAuth 或 API Key，凭据存 `~/.pi/agent/auth.json`）→ `/model` 选模型 → `/thinking` 调思考等级。
3. 交互工作流：提交 prompt；模型流式输出；工具调用可视化；**steering**（模型工作时插话，当前 turn 结束后进入）与 **follow-up**（等待全部工作结束后进入）；abort 取消。
4. 会话命令：`/tree`（在树内回到历史分支）、`/fork`（分叉新会话）、`/clone`（克隆当前分支）、`/compact`（手动压缩）、`/export`、`/resume`、`/session`。
5. 四种接口：交互 TUI；`pi -p "..."` print 模式（输出最终回复）；`--json` JSONL 事件流模式；RPC 模式（stdin/stdout JSONL 命令，供外部程序控制）。
6. 定制入口速览：`~/.pi/agent/`（settings.json、models.json、auth.json、sessions/）、项目级 `.pi/`、extensions / skills / themes / packages 的存在感。

**关键源码与文档**
- `packages/coding-agent/docs/quickstart.md`、`usage.md`、`cli.md`、`sessions.md`（前半）
- `packages/coding-agent/src/modes/`（浏览目录结构即可）

**实践任务**：① 完成安装并用一个真实小任务（改一个 bug）观察完整工具调用链；② 分别用 print 和 `--json` 模式跑同一 prompt，对比输出；③ 在会话中用 `/tree` 回退并改写提问，体验分支。

**自测问题**：① steering 与 follow-up 的进入时机差异？② JSON 模式输出的每一行是什么？③ 会话默认存在哪里？

---

## 第 4 讲 pi-ai（上）：统一 LLM API——消息、流式与模型目录

**学习目标**：读懂 Pi 如何把各家 LLM API 抽象成统一类型层。掌握 `Models` / `Model` / `Provider` 核心抽象、`Message` 类型体系、流式事件流 `EventStream`、模型目录（catalog）机制与 usage 计量。这是理解 agent 层的前提。

**知识点**
1. `Model`：对「一个可用模型」的描述（provider、id、api、能力、上下文窗口、价格等）；`Models`：模型注册表（`createModels()`、`setProvider()`、`getModel()`、`streamSimple()`）。
2. `Provider`：厂商抽象，提供 `listModels()` 与 API 实现；provider 与 api 的两层解耦（一个 `api` 如 `openai-completions` 可被多个厂商复用）。
3. `Message` 类型体系：`SystemMessage` / `UserMessage` / `AssistantMessage` / `ToolResultMessage`；内容块（text / image / toolCall / thinking…）；`stopReason`（stop / toolCalls / error / aborted…）。
4. 流式：`EventStream` 拉模式迭代器；`AssistantMessageEvent`（message_start / text_delta / tool_call_delta / message_end…）——与 agent 层事件的区别与衔接。
5. 模型目录：`catalog/` 源定义 → 生成 `models.generated.ts` → 运行时叠加 pi.dev 最新目录（`pi update --models`）；离线可用。
6. `Usage` 计量与 token 统计；`TranscriptContext`：把 system prompt 与工具声明规范化进 transcript 的请求上下文（agent 层的 StreamFn 契约）。

**关键源码与文档**
- `packages/ai/src/models.ts`、`models-store.ts`、`model-catalog.ts`、`types.ts`、`index.ts`
- `packages/ai/README.md`（Quick Start 与核心概念）
- `packages/coding-agent/docs/models.md`（模型选择与目录行为）

**实践任务**：写一个最小脚本（`createModels` + `streamSimple`）打印一次流式回复的所有事件类型；换成两个不同厂商模型再跑一遍，验证抽象的一致性。

**自测问题**：① Provider 与 Api 为什么要两层？② prompt caching 对消息顺序提出了什么要求？③ 模型数据「生成 + 运行时叠加」解决了什么矛盾？

---

## 第 5 讲 pi-ai（下）：Provider 适配、认证与工具调用协议

**学习目标**：理解多厂商适配的实现细节与成本，掌握「新增一个自定义端点」与「新增一个自定义 Provider」两条路径，以及认证体系（API Key / OAuth PKCE / 设备码 / 云凭据）。理解工具声明在各协议间的归一化。

**知识点**
1. `api/` 目录逐类解析：`anthropic-messages`、`openai-responses` / `openai-completions`（兼容大量厂商）、`google-generative-ai` / `google-vertex`、`bedrock-converse-stream`、`mistral-conversations` 等；lazy 加载（`.lazy.ts`）控制启动开销。
2. 统一 → 各协议的转换层：Pi 内部 `Message` 与各厂商 wire 格式互转；`transform-messages.ts`、`strict-tool-limits.ts` 等共享工具。
3. `providers/`：每厂商一个注册文件（`*.models.ts` 描述模型元数据）；`providers/all.ts` 汇总。
4. 认证体系：`auth/`（context、resolve、credential-store）+ `auth/oauth/`（PKCE、device-code、各厂商 OAuth）；凭据优先级：运行时 `--api-key` > `auth.json` > `models.json` > 环境变量/云凭据。
5. 自定义端点：`models.json` 中声明 `baseUrl` + `api` + `models`（Ollama / vLLM / LM Studio / 代理）；`modelOverrides` 只改元数据；环境变量插值与 `!command` 动态取密钥。
6. 自定义 Provider 扩展（provider extensions）与虚拟模型（virtual models：把提示词/路由包装成一个模型）。
7. 工具声明协议：`Tool` → `toToolDeclaration()` → 各协议格式；工具参数 JSON Schema 在不同协议的约束差异。

**关键源码与文档**
- `packages/ai/src/api/anthropic-messages.ts` 与 `api/openai-responses.ts`（对比精读）
- `packages/ai/src/auth/`、`providers/all.ts`
- `docs/models-configuration.md`、`custom-provider.md`、`virtual-models.md`、`providers.md`

**实践任务**：在 `models.json` 里接入一个 OpenAI 兼容端点（如本地 Ollama），让 Pi 的 `/model` 中出现它并用它完成一次带工具调用的任务。

**自测问题**：① 新增厂商时需要写哪几类文件？② OAuth PKCE 解决什么问题？③ 为什么工具参数最终统一为 JSON Schema？

---

## 第 6 讲 pi-agent-core（上）：Agent Loop 与事件流

**学习目标**：精读 Agent 内核。掌握 `Agent` 类的状态机与公开 API、`agentLoop` / `agentLoopContinue` 两条入口、`AgentMessage` 与 LLM `Message` 的分离（`convertToLlm` / `transformContext`）、完整事件序列、中断与 steering 队列机制。这是整个项目最核心的一讲。

**知识点**
1. `Agent` 类：构造（`initialState`：systemPrompt、model；`streamFn`）；`subscribe(event)` 订阅；`prompt()` / `steer()` / `followUp()` / `abort()`；`setModel()` / `setTools()` / `setSystemPrompt()`；状态与 `messages` 语义。
2. 消息流水线：`AgentMessage[]` →（可选 `transformContext`：裁剪、注入）→ `AgentMessage[]` →（必需 `convertToLlm`：过滤 UI 消息、转换自定义类型）→ `Message[]` → LLM。两个钩子的契约（不得 throw）。
3. 事件序列精读：无工具时 `agent_start → turn_start → message_start(user) → … → message_end(assistant) → turn_end → agent_end`；有工具时插入 `tool_execution_start/update/end` 与 `toolResult` 消息事件，然后开启新 turn。
4. `StreamFn` 契约：不得 throw；失败必须编码进事件流（stopReason=error/aborted + errorMessage）——错误处理的设计哲学。
5. 队列与模式：`QueueMode`（all / one-at-a-time）控制 drain 点注入多少排队消息；steering 在当前 assistant turn 后进入；Agent 类对 `message_end` 的 barrier 语义（低层 `agentLoop()` 是观测性的，不等待你的异步处理器）。
6. `FinishTurn` / `PrepareRequest` / `PrepareNextTurn` 钩子：干预下一次请求的上下文、模型与 thinking level。
7. 中断：AbortSignal 贯穿；`agentLoopContinue` 用于重试（上下文最后一条必须是 user/toolResult）。

**关键源码与文档**
- `packages/agent/src/agent.ts`、`agent-loop.ts`、`types.ts`、`stream-fn.ts`（全文精读）
- `packages/agent/README.md`（事件序列两图）
- 测试：`packages/agent/test/agent.test.ts`、`agent-loop.test.ts`（用例即文档）

**实践任务**：基于 `Agent` 类写一个 50 行以内的小 agent：订阅事件打印时间线、注册一个 `calculate` 工具、发起一次带工具调用的 prompt；然后给同一 prompt 分别实现 `transformContext`（注入一条假消息）与 `convertToLlm`（过滤一种自定义消息）并观察请求差异。

**自测问题**：① 为什么 `convertToLlm` 是必需而 `transformContext` 是可选？② tool_execution_end 在 parallel 模式下按什么顺序发出、toolResult 消息按什么顺序持久化？③ 「barrier」语义解决什么竞态？

---

## 第 7 讲 pi-agent-core（下）：工具定义、校验与执行策略

**学习目标**：掌握 Agent 工具系统的完整生命周期：定义（TypeBox schema）→ 校验（pi-schema，宽松类型矫正）→ 预检（beforeToolCall）→ 执行（sequential/parallel）→ 终检（afterToolCall）→ 结果回填（content/details/structuredContent/terminate）。理解工具是 Agent 的「手脚」，其工程质量决定 Agent 上限。

**知识点**
1. `AgentTool` 定义：name / description / parameters（JSON Schema，TypeBox 构建）/ execute(toolCallId, args, signal, onUpdate, ctx)；execute 返回 `AgentToolResult`（content、details、structuredContent、isError、usage）。
2. 参数校验：`validateToolArguments`；pi-schema 的宽松矫正（数字字符串→数字、"true"→true、单值→单元素数组、可选属性中的 null 丢弃）；TypeBox 超出 JSON Schema 的特性（Refine/BigInt/Format 扩展）不生效——模型看到的错误消息格式。
3. 执行模式：`parallel`（默认，预检串行、放行的并发执行、完成即发事件、结果按 assistant 源顺序持久化）vs `sequential`；per-tool `executionMode` 覆盖全局（批次内任一 sequential 则整批串行）。
4. 钩子：`beforeToolCall`（可 block + reason，产出错误 toolResult；可 terminate）；`afterToolCall`（字段级替换 content/details/usage/isError，非深合并）；`terminate: true` 的批语义（当批内全部结果 terminate 才提前结束循环）。
5. 流式工具输出：`onUpdate` 部分结果 → `tool_execution_update` 事件（长命令进度）。
6. 工具状态与声明变更：`getCurrentTools` / `getToolStateChanges` / `toToolDeclaration`；中途增删工具如何声明进 transcript（cache 稳定性）。
7. 设计对比：与 Java 反射/接口注册（如 SPI）、MCP 工具、Function Calling 的关系。

**关键源码与文档**
- `packages/agent/src/types.ts`（AgentTool 及结果类型全文）、`agent-loop.ts` 中工具执行段
- `packages/schema/README.md`、`packages/coding-agent/docs/extensions.md` 的 Custom Tools 段
- 测试：`agent-tool-typebox.test.ts`、`test/utils/*.ts`

**实践任务**：给第 6 讲的小 agent 增加两个工具：一个返回结构化 JSON（structuredContent），一个长任务流式 onUpdate；实现 beforeToolCall 拦截危险参数、afterToolCall 改写结果文本；分别用 sequential/parallel 观察事件顺序差异。

**自测问题**：① 为什么参数校验要做「宽松矫正」？② parallel 模式下「完成序」与「持久化序」为什么分离？③ terminate 为什么要求整批一致才生效？

---

## 第 8 讲 pi-coding-agent 架构：AgentSession 与核心模块

**学习目标**：从内核上升到产品层。掌握 coding-agent 的模块地图与启动流程：`AgentSession` 如何编排 agent 内核、模型解析、设置体系、事件总线与信任管理。能独立跟踪「一条用户输入从 TUI 到模型再回来」的完整调用链。

**知识点**
1. 目录地图：`src/core/`（会话运行时、设置、模型、扩展、工具）、`src/modes/`（interactive TUI / rpc）、`src/extensions/`（内置扩展 codemode、llama、mcp、tool-search）、`src/cli/`。
2. `agent-session.ts` / `agent-session-runtime.ts` / `agent-session-services.ts` 三件套的分工：会话状态、运行循环、服务依赖注入。
3. `event-bus.ts`：扩展事件系统的底座；`AgentEvent → 扩展事件`的桥接。
4. 模型解析链：`model-registry` / `model-resolver` / `model-runtime` / `models-store` / `provider-composer` / `preferred-providers`——从设置到一次可用的 `(model, streamFn)`。
5. 设置体系：`settings-schema` / `settings-manager` / `settings-defaults` / `resolve-config-value`；全局 `~/.pi/agent/settings.json` 与项目 `.pi/settings.json` 的合并与优先级。
6. 信任与启动：`project-trust.ts` / `trust-manager.ts`——项目级资源（extensions/skills/settings）只在信任后加载；启动阶段顺序（trust → 项目资源 → context files）。
7. `bash-executor` / `exec` / `http-dispatcher` 等基础设施；`crash-log` / `diagnostics` / `bug-report` 可观测性。

**关键源码与文档**
- `packages/coding-agent/src/core/agent-session.ts`（精读）
- `docs/how-pi-works.md`、`configuration.md`、`settings.md`、`security.md`（信任部分）
- `src/modes/`（浏览）

**实践任务**：用调试器或打日志的方式跟踪一条消息的完整路径：TUI editor → AgentSession.prompt → Agent.prompt → streamFn → 事件回流 TUI 渲染；画出自己的时序图。

**自测问题**：① AgentSession 与 Agent 类的职责边界？② 设置优先级顺序？③ 为什么项目级扩展必须过信任门槛？

---

## 第 9 讲 系统提示词、上下文组装与压缩（Compaction）

**学习目标**：掌握 Agent 的「灵魂装配线」：系统提示词如何构建、项目上下文文件（AGENTS.md 等）如何被发现与注入、Skills 描述的按需加载、以及接近上下文上限时的自动压缩机制。

**知识点**
1. `system-prompt.ts`：基础指令 + 上下文文件 + 工具说明 + 技能描述的组装顺序；对 prompt cache 的友好设计（稳定前缀）。
2. Context files 发现规则：从工作目录向上的 AGENTS.md / CLAUDE.md 等层级合并；`.pi/` 中的 prompts。
3. Skills 注入：启动时只把「名字 + 描述 + 路径」放进系统提示词，任务匹配时模型才读 `SKILL.md` 全文——按需加载的上下文经济学。
4. Compaction：阈值触发自动压缩；摘要条目（summary entry）替换旧历史进入后续请求，但原始条目仍留在会话树中；保留边界（最近消息保留）；`/compact` 手动压缩可带指令；压缩失败的降级行为。
5. `transformContext` 在 coding-agent 中的实际用法：裁剪 + 注入；分支摘要（离开分支时可生成摘要带到新分支）。
6. 扩展介入点：注入指令、定制 compaction。

**关键源码与文档**
- `core/system-prompt.ts`、`core/compaction/*`、`core/resource-loader.ts`、`core/skills.ts`
- `docs/compaction.md`（精读）、`docs/how-pi-works.md` 的 Context 节

**实践任务**：① 在测试项目放不同层级的 AGENTS.md，用 `/export` 导出会话观察系统提示词实际内容；② 人为调小上下文阈值触发自动压缩，对比压缩前后的请求消息数组；③ 写一个自定义 compaction 扩展把压缩摘要改成结构化要点。

**自测问题**：① 为什么技能只注入描述？② 压缩后原始条目为什么保留？③ 系统提示词的哪些部分必须保持稳定、为什么？

---

## 第 10 讲 内置工具集与会话持久化（JSONL 树、分支、Fork）

**学习目标**：精读 Pi 的内置工具实现（工程质量范本）与会话持久化格式（JSONL 事件树）。理解「会话即树、分支即路径」的设计，以及工具输出的截断、排队与安全策略。

**知识点**
1. 工具集总览：`read` / `write` / `edit` / `bash`（+ PowerShell 支持）/ `ls` / `find` / `grep`；每工具的参数 schema、返回结构与 prompt 描述。
2. 输出治理：`truncate.ts`（行数/字节上限、首尾保留 + 省略标记）、`output-accumulator.ts`、bash 的 1MiB 上限与 full_output_path；大输出对上下文的保护。
3. `file-mutation-queue.ts`：写类操作串行化，避免并发写竞态；`path-utils`（路径解析与规范化）。
4. 会话格式：JSONL 每行一个 entry；entry 有 id 与 parent 引用构成树；current entry 指针决定活跃分支；entry 类型（user / assistant / toolResult / compact / custom…）。
5. 分支操作：`/tree` 树内移动（回退到历史 user 消息改写 → 新分支）；`/fork` 拷贝到新会话文件；`/clone` 克隆活跃分支；resume 重建模型上下文 = 活跃分支回放。
6. steering / follow-up / abort 在持久化层的体现；`session-manager.ts` 的存储布局（按工作目录分组）；`--no-session` 临时会话。
7. 消息类型扩展：`message-types.md`——自定义消息进入会话树但可被 convertToLlm 过滤。

**关键源码与文档**
- `core/tools/*.ts`（read/write/edit/bash 四个精读）
- `core/session-manager.ts`、`core/messages.ts`
- `docs/session-format.md`（精读）、`sessions.md`（后半）、`message-types.md`

**实践任务**：① 手工解析一个真实会话 JSONL 文件，画出 entry 树；② 用 `/tree` 制造两个分支后再 fork，对比三个文件的树结构；③ 读 bash 工具源码，列出至少 5 条它对输出/超时/退出码的处理规则。

**自测问题**：① 为什么写工具需要全局串行队列？② fork 与 tree 分支的本质区别？③ 大输出的三层防线是什么？

---

## 第 11 讲 扩展系统：自定义工具、事件拦截与 UI 集成

**学习目标**：掌握 Pi 最强大的定制机制——Extensions。能编写拦截工具调用（权限门）、注册自定义工具与命令、注入上下文、持久化扩展状态、自定义 TUI 渲染的完整扩展，理解热重载与扩展加载的安全边界。

**知识点**
1. 扩展模型：TypeScript 模块，默认导出工厂 `(pi: ExtensionAPI) => void`；运行在 Pi 进程内、拥有完整系统权限——信任前提。
2. 加载位置与发现：`~/.pi/agent/extensions/`（全局）与 `.pi/extensions/`（项目，需信任）；`pi -e` 临时加载；`/reload` 热重载；npm 依赖解析。
3. `ExtensionAPI` 方法总览：`on()` 订阅事件、`registerTool()`、`registerCommand()`、`registerRenderer()`、`appendEntry()`（状态持久化进会话）、`setModel` 等。
4. 事件目录：startup / resource / session / agent / model / tool（tool_call 拦截与 block）/ user bash / input；处理器组合顺序。
5. `ctx.ui` 交互：notify / confirm / select / input / setStatus / setWidget / custom（完整 TUI 组件 + 键盘输入）。
6. 官方案例精读：权限门（rm -rf 确认）、git checkpoint、路径保护、自定义 compaction、snake 游戏、summarize。
7. 扩展与模式：interactive 下 UI 可用，print/JSON/RPC 下的降级行为。

**关键源码与文档**
- `docs/extensions.md`（全文精读，最重要的单篇文档之一）
- `packages/coding-agent/examples/extensions/`（挑 3 个精读）
- `core/extensions/` 源码

**实践任务**：写一个真实可用的扩展：拦截 `write/edit` 对 `.env` 与 `node_modules` 的写入需确认；注册 `/review-checklist` 命令；把每次拦截记录 appendEntry 持久化；在会话重启后恢复记录。

**自测问题**：① tool_call 事件返回 `{block:true, reason}` 后循环发生什么？② 扩展状态如何跨会话存活？③ 为什么扩展不能在 print 模式弹 confirm？

---

## 第 12 讲 Skills、提示模板、主题与 Pi Packages 生态

**学习目标**：掌握 Pi 的「轻量定制四件套」（skills / prompt templates / themes / packages）：不写代码也能教 Pi 新工作流；掌握通过 npm / git 打包分发扩展资源的机制。

**知识点**
1. Skills：目录 + `SKILL.md`（frontmatter：name / description / license / compatibility / allowed-tools / disable-model-invocation）；Agent Skills 规范兼容；按需加载机制与 `/skill:name` 强制调用；`~/.pi/agent/skills/`、`.agents/skills/` 位置；描述写法决定路由质量。
2. Prompt templates：可复用消息模板（`.pi/prompts/`），编辑器中展开；与 skills 的适用边界（模板 = 文本起点，技能 = 完整工作流）。
3. Themes：终端配色主题（`.pi/themes/`），TUI 主题接口。
4. Pi Packages：`pi install npm:@foo/bar@1.0.0` / `git:...`；`package.json` 的 `pi.extensions/skills/prompts/themes` 声明；`package-manager.ts` / `pi-manifest.ts` 的安装与解析；运行时依赖声明规则。
5. 生态观：Anthropic skills 集合、pi-skills 集合；把团队规范做成包的实践。

**关键源码与文档**
- `docs/skills.md`、`prompt-templates.md`、`themes.md`、`packages.md`
- `core/skills.ts`、`core/prompt-templates.ts`、`core/package-manager.ts`
- 根目录 `.pi/skills/`（项目自用技能实例）

**实践任务**：为一个真实工作流（如「数据库变更审查」）写一个技能（含 references 与 scripts）；再做一个小包把技能 + 一个扩展 + 一个主题打包，`pi install` 本地路径安装验证。

**自测问题**：① 技能 description 应该同时写清什么？② `disable-model-invocation` 何时用？③ 打包时为什么不能把宿主提供的包列进 dependencies？

---

## 第 13 讲 TUI、Codemode、MCP 与自动化（RPC / SDK）

**学习目标**：横跨四个集成维度：① pi-tui 的差分渲染与组件体系如何支撑交互模式；② codemode 如何让模型用 TypeScript 脚本编排工具；③ pi-mcp 客户端如何接入外部工具生态；④ RPC 与 SDK 如何把 Pi 变成可编程组件嵌入其他应用。

**知识点**
1. pi-tui：`TUI` 接口（main-screen / alternate-screen）、差分渲染（只更新变化行）、CSI 2026 同步输出防闪烁、bracketed paste、组件体系（Editor/Markdown/SelectList/ScrollView/Image…）、焦点与键位、内联图片协议；interactive 模式如何组装这些组件。
2. Codemode：模型生成 TS 脚本，在沙箱评估器中调用 `tools.*`；`ALL_TOOLS` / `searchTools` / `describeTool`；`store/load` 跨调用小状态（成功脚本才写入，分支可见性）；`codemode.mode`（on/only）对其他工具呈现的影响；适用场景（批量/组合/循环工具链）。
3. pi-mcp：独立 MCP 客户端（不依赖官方 SDK）；transport 抽象（Stdio / StreamableHttp / Pipe / 内存测试）；McpClient 生命周期（connect / listTools / callTool / close）；coding-agent 中 MCP 服务器配置与 `mcp__server__tool` 命名空间、`mcp-servers.ts`、tool-search 扩展的延迟暴露。
4. RPC 模式：stdin JSONL 命令 / stdout 事件与响应；`rpc-commands.md` 命令目录；`rpc-extension-ui`（扩展 UI 跨 RPC）。
5. TypeScript SDK：`core/sdk.ts`，进程内创建与控制会话；与 OpenClaw、pi-chat 等真实集成案例。
6. 自动化模式选型：print（一次性） / JSON（事件流） / RPC（双向控制） / SDK（进程内）。

**关键源码与文档**
- `packages/tui/README.md` + `src/`（组件清单）
- `docs/codemode.md`（精读）、`packages/codemode/`
- `packages/mcp/README.md`、`docs/mcp.md`
- `docs/rpc.md`、`rpc-commands.md`、`sdk.md`、`json.md`

**实践任务**：① 用 SDK 写一个 30 行程序：创建会话、发 prompt、收集事件、打印工具调用；② 给 Pi 接入一个 MCP 文件系统服务器并用它完成文件操作；③ 开启 codemode 让模型用脚本一次性重命名 20 个文件。

**自测问题**：① 差分渲染为什么能防闪烁？② codemode 与普通工具调用的本质区别？③ RPC 与 SDK 各自的进程边界？

---

## 第 14 讲 安全、容器化与综合实战项目

**学习目标**：建立 Agent 系统的安全观与工程化收尾能力：理解 Pi 的信任模型与三大容器化方案；通过一个综合实战把全部知识串起来（扩展 + 技能 + 包 + 自动化），并了解如何参与项目贡献。

**知识点**
1. 信任模型：Pi 默认以启动用户的完整权限运行；无内置文件/进程/网络权限系统是「有意的极简」；项目信任（project trust）保护的是什么；凭据存储与隐私（auth.json、导出/分享会话的泄露面、`/bug` 报告内容）。
2. 容器化三方案：Gondolin 扩展（宿主保存认证、工具进 micro-VM）、Plain Docker（整进程容器）、OpenShell（策略沙箱）；适用场景与权衡。
3. 安全清单：只装可信扩展/包；审查 SKILL.md 与 scripts；会话导出脱敏；短时会话与最小目录授权。
4. 综合实战项目（建议）：为你的 Java 工作流构建 `pi-java-review` 包——一个扩展（拦截对 `src/main` 之外的写、跑 `mvn compile` 校验）+ 一个技能（团队代码规范，含 references）+ 一个提示模板 + RPC 自动化脚本（PR 批量预审）。
5. 贡献流程：AGENTS.md 协作规则、CHANGELOG 规范、biome + vitest、`./test.sh` 与 `pi-test.sh`、RFC 流程。
6. 延伸阅读：pi-durable 与 chord（持久化运行时的方向）、p2/p3 原型、pi-chat。

**关键源码与文档**
- `docs/security.md`、`containerization.md`（精读）
- `AGENTS.md`、`CONTRIBUTING.md`
- `packages/durable/README.md`、`apps/p2/README.md`（拓展视野）

**实践任务**：完成综合实战项目并开源或内部分发；给 Pi 提交一个文档修正或小 bugfix（走完贡献流程）。

**自测问题**：① 三种容器化方案各自信任边界？② 为什么 Pi 拒绝内置权限系统？③ durable 解决了 agent 的什么可靠性问题？

---

## 附：与 Java 后端概念的对照表

| Pi / Agent 概念 | Java 世界类比 |
|---|---|
| LLM API | 无状态 HTTP RPC（每次带全量上下文） |
| System Prompt | 应用启动配置 / 全局拦截器注入的公共上下文 |
| Agent Loop | Servlet 容器的事件循环 / 带回调的命令总线 |
| Tool / ToolCall | SPI 接口实现 + 反射调用（带 JSON Schema 校验的参数绑定） |
| toolResult 回填 | 异步任务结果写回请求上下文 |
| EventStream（事件流） | Reactive Streams / Flow.Publisher |
| transformContext / convertToLlm | Filter 链（请求出站前的装饰与裁剪） |
| Extension | Spring Boot Starter / 插件模块 |
| Session JSONL 树 | 事件溯源（Event Sourcing）+ 不可变事件日志 |
| Compaction | 日志压缩（Log Compaction）/ 快照 |
| MCP | 标准化的 RPC 服务发现与调用（如 gRPC + 注册中心） |
| RPC 模式 | 进程间 JSONL 协议（类比 JMX/管理端口） |