附录
A. 术语表
| 术语 | 英文 | 说明 | Java 等价 |
|---|---|---|---|
| 联合类型 | Union Type | A | B | C，值可以是多种类型之一 | sealed interface |
| 判别式联合 | Discriminated Union | 通过公共字段区分的联合类型 | sealed + record 模式匹配 |
| 类型收窄 | Type Narrowing | TypeScript 根据条件自动缩小类型范围 | instanceof 检查后的强制转换 |
| 泛型约束 | Generic Constraint | <T extends Schema> | <T extends Comparable<T>> |
| 类型守卫 | Type Guard | x is Foo 或 x.type === "foo" | instanceof |
| TypeBox | - | 运行时 JSON Schema + 编译时类型推断的库 | Jackson + Bean Validation |
| Static<T> | - | 从 TypeBox Schema 推导出 TypeScript 类型 | 编译时生成的 POJO |
| async/await | - | 异步编程语法糖 | CompletableFuture.join() |
| Promise | - | 异步操作的容器 | CompletableFuture |
| 解构赋值 | Destructuring | const {a, b} = obj | Java 16+ 模式匹配 |
| 展开运算符 | Spread | [...arr, item] | List.copyOf() + add() |
| 闭包 | Closure | 捕获外部变量的函数 | Lambda 表达式 |
| 模块 | Module | 一个 .ts 文件就是一个模块 | 一个 .java 文件 |
| export | - | 导出（公开）成员 | public |
| import type | - | 仅导入类型信息，编译后删除 | 无直接等价 |
| satisfies | - | 验证类型但不改变推断 | 无直接等价 |
| readonly | - | 只读属性 | final |
| Optional (?😃 | - | 可选属性 | @Nullable |
| null 合并 (??) | - | a ?? b，a 为 null/undefined 时返回 b | Optional.orElse() |
| JSONL | JSON Lines | 每行一个 JSON 对象的文件格式 | 类似 CSV 但用 JSON |
| Append-Only | - | 只追加不修改的存储模式 | Event Sourcing |
| jiti | - | TypeScript 运行时加载器 | 类似 ClassLoader |
B. 设计模式索引
本书涉及的设计模式及其在 Pi 中的体现：
| 模式 | Pi 中的实例 | 说明 |
|---|---|---|
| 策略模式 | AgentTool 接口 | 每个工具是一个策略 |
| 工厂模式 | createReadTool(), createBashTool() | 工具创建通过工厂函数 |
| 观察者模式 | agent.subscribe(listener) | 事件订阅机制 |
| 适配器模式 | wrapToolDefinition() | ToolDefinition → AgentTool |
| 注册表模式 | apiProviderRegistry | 全局 Provider 注册表 |
| 模板方法 | Agent Loop | 固定的循环骨架，可变的钩子 |
| 依赖注入 | Operations 接口 | 通过接口注入文件系统操作 |
| 建造者模式 | AgentOptions | 复杂对象的构建 |
| 命令模式 | ToolCall | LLM 的工具调用是命令对象 |
| 状态模式 | AgentState | Agent 的运行状态 |
| 迭代器模式 | AssistantMessageEventStream | 流式事件的异步迭代器 |
| 拦截器模式 | beforeToolCall / afterToolCall | AOP 的函数式实现 |
| 队列模式 | PendingMessageQueue | Steering/FollowUp 消息队列 |
| 快照模式 | createContextSnapshot() | 不可变的上下文快照 |
| ServiceLoader | registerApiProvider() | Java SPI 的 TypeScript 版本 |
C. 文件导航
快速查找关键文件：
想理解... → 看这个文件
| 你想理解 | 文件路径 |
|---|---|
| LLM 调用是怎么工作的 | packages/ai/src/stream.ts |
| 消息类型有哪些 | packages/ai/src/types.ts |
| Provider 怎么注册的 | packages/ai/src/api-registry.ts |
| Agent Loop 核心循环 | packages/agent/src/agent-loop.ts |
| Agent 类的全部 API | packages/agent/src/agent.ts |
| 工具是怎么定义的 | packages/coding-agent/src/core/tools/read.ts |
| 工具参数 Schema | packages/coding-agent/src/core/tools/read.ts (前 30 行) |
| 会话怎么持久化的 | packages/coding-agent/src/core/session-manager.ts |
| 上下文怎么压缩的 | packages/coding-agent/src/core/compaction/compaction.ts |
| 扩展 API 全部接口 | packages/coding-agent/src/core/extensions/types.ts |
| 扩展怎么加载的 | packages/coding-agent/src/core/extensions/loader.ts |
| 怎么写一个扩展 | packages/coding-agent/examples/extensions/dynamic-tools.ts |
| AgentSession 怎么组装的 | packages/coding-agent/src/core/agent-session.ts (前 100 行) |
| CLI 入口在哪里 | packages/coding-agent/src/cli.ts |
| 系统提示词怎么构建的 | packages/coding-agent/src/core/system-prompt.ts |
| 内置工具有哪些 | packages/coding-agent/src/core/tools/index.ts |
| TUI 怎么实现的 | packages/tui/src/tui.ts |
D. 延伸阅读
官方文档
TypeScript 学习资源
AI Agent 相关
- Anthropic Claude API 文档
- OpenAI API 文档
- LangChain -- Python/JS Agent 框架
- AutoGen -- 微软的多 Agent 框架
设计模式
- 《设计模式》-- GoF
- 《Effective Java》-- Joshua Bloch
- 《Clean Architecture》-- Robert C. Martin
E. 常见问题
Q: 我完全不懂 TypeScript，能读懂这本书吗？
A: 可以。第一章就是专门为 Java 开发者写的 TypeScript 速成。每一章都有 ⚡ Java 对照 标记，帮你把新概念映射到已知的 Java 概念。
Q: 我需要把 Pi 的源码克隆下来吗？
A: 强烈建议。本书的 📌 源码定位 标记指向具体的文件和行号，你可以边读边看源码。
Q: 我想基于 Pi 开发自己的 Agent，应该从哪里开始？
A: 先读完前六章理解核心架构，然后直接跳到第十一章动手实践。第十章的扩展系统是日常开发最常用的部分。
Q: 本书的源码版本会更新吗？
A: 本书基于 Pi v0.70.6。如果 Pi 有重大架构变更，我们会更新对应章节。
Q: 我发现书中有错误，怎么反馈？
A: 请开一个 Issue，或者直接提交 Pull Request。