术语表
全书关键术语的统一定义。每个词条给出：定义、首次讲解章节、深入章节。译法全书统一（见排版约定）。按主题分组，组内按学习顺序排列。
语言与运行环境
| 术语 | 定义 | 讲解章节 |
|---|---|---|
| JavaScript（JS） | 最初为浏览器设计、现已通用的动态类型编程语言 | 1.1 |
| Node.js | 让 JavaScript 在浏览器之外运行的运行时环境，提供文件、网络、进程等 API | 1.1 |
| TypeScript（TS） | 在 JavaScript 之上增加静态类型系统的语言，需编译/转换为 JS 后执行 | 1.1 |
| 编译（compile）/ 类型检查 | 把 .ts 源码检查并转换为 .js 的过程；类型只存在于编译期 | 1.2 |
| tsx | 直接运行 .ts 文件的命令行工具（内部完成即时转换），Pi 的 pi-test.sh 也用它 | 1.2 |
| npm | Node.js 的包管理器：安装依赖、运行脚本、访问 registry | 1.3 |
| package.json | 一个 npm 包/项目的清单文件：名称、版本、脚本、依赖 | 1.3 |
| 依赖锁定（lockfile） | package-lock.json 精确记录整棵依赖树的版本，保证可复现安装 | 1.3 |
| monorepo / workspaces | 单仓库多包结构；npm workspaces 让多个包共享一次安装并互相链接 | 1.3 · 深入 4.3 |
| 模块（module）/ ESM | 以文件为单位的代码组织方式；ESM 是使用 import/export 的标准模块系统 | 1.4 |
| tsconfig.json | TypeScript 项目的编译与检查配置 | 1.2 |
TypeScript 类型系统
| 术语 | 定义 | 讲解章节 |
|---|---|---|
| 类型（type） | 编译期对值的形状约束；运行时会被完全擦除 | 2.1 |
| optional 属性 | 用 ? 标记的可缺省对象属性 | 2.1 |
| readonly | 标记属性不可再赋值的修饰符 | 2.1 |
| any / unknown | 关闭类型检查的逃生舱 / 类型安全的「未知」，使用前必须收窄 | 2.1 · 2.4 |
| interface | 描述对象形状的类型声明 | 2.2 |
| type（类型别名） | 给任意类型起名字的声明，常用于联合与组合 | 2.2 |
| 结构化类型（structural typing） | TS 按「形状」而非「名字」判断类型兼容 | 2.2 |
| union（联合类型） | A | B：值是若干候选类型之一 | 2.3 |
| 字面量类型（literal type） | 以具体值为类型，如 'text'、42 | 2.3 |
| 可辨识联合（discriminated union） | 用公共字段（常为 type）区分成员的联合类型；Pi 的消息、内容块、事件都是它 | 2.3 |
| never | 「不可能出现」的类型，常用于 switch 的完备性兜底 | 2.3 |
| 泛型（generic） | 带类型参数的函数/接口/类，让容器不丢内容物的类型 | 2.4 |
| 类型收窄（narrowing） | 通过 typeof/in/instanceof/判别字段等把宽类型缩小为具体类型 | 2.4 |
| type guard | 形如 x is T 的自定义收窄函数 | 2.4 |
异步与事件
| 术语 | 定义 | 讲解章节 |
|---|---|---|
| 事件循环（event loop） | Node.js 单线程调度异步任务的机制 | 2.5 |
| Promise | 表示「未来才有结果」的对象，三态：pending/fulfilled/rejected | 2.5 |
| async/await | 以同步写法消费 Promise 的语法 | 2.5 |
| 异步迭代器（Async Iterator） | 可以逐个、异步地产生值的对象；LLM 流式输出的天然形状 | 2.6 |
| 异步生成器（async function*） | 用 yield 产生异步序列的函数 | 2.6 |
| for await…of | 消费异步迭代器的循环语法 | 2.6 |
| 事件订阅（on/emit） | 「发生了什么就通知谁」的解耦模式；Node 内置 EventEmitter | 2.7 |
| AbortController / AbortSignal | 标准取消原语：controller 发令，signal 层层传递到最底层 I/O | 2.7 · 深入 5.6 |
LLM 与 Agent
| 术语 | 定义 | 讲解章节 |
|---|---|---|
| LLM（大语言模型，Large Language Model） | 输入 token 序列、预测输出 token 的模型；本书视为黑盒 | 3.1 |
| Provider（模型服务提供方） | 提供模型 API 的厂商/服务（Anthropic、OpenAI、Google…） | 3.1 · 深入 6.2 |
| system / user / assistant | 三种消息角色：系统指令 / 用户输入 / 模型输出 | 3.1 |
| API Key | 调用模型服务的身份凭证 | 3.1 |
| Fake Model | 教学用的脚本化假模型：不联网、零成本、输出可控 | 3.1 |
| 上下文（Context） | 一次模型请求携带的全部内容：系统提示词+历史消息+新输入 | 3.2 |
| token | 模型处理文本的基本单位（词元）；计费与上下文窗口都以它计量 | 3.2 |
| 上下文窗口（context window） | 模型单次请求能容纳的 token 上限 | 3.2 |
| 流式输出（Streaming） | 模型边生成边分块返回；表现为一串增量事件 | 3.3 · 深入 5.4 |
| SSE（Server-Sent Events） | HTTP 上服务器持续推送事件的传输格式，多数模型 API 用它做流式 | 3.3 |
| 工具调用（Tool Calling） | 模型输出结构化「调用某工具」请求、应用执行后回填结果的协议 | 3.4 · 深入 5.3 |
| Tool Call | 一次具体的工具调用请求（含工具名与参数） | 3.4 |
| 工具结果（Tool Result） | 工具执行的返回，作为消息回到历史供模型继续 | 3.4 |
| 参数校验（schema 校验） | 模型生成的参数是不可信的运行时数据，必须按 schema 验证 | 3.4 · 深入 6.4 |
| Agent | LLM + 工具 + 循环 + 状态组成的自主执行体 | 3.5 |
| Agent Loop（Agent 循环） | 「请求模型→执行工具→回填结果→再请求」直至完成的循环 | 3.5 · 深入 6.3 |
| Agent Harness（Agent 运行框架） | 围绕 Agent Loop 的整套工程设施：状态、Session、取消、扩展、UI 解耦 | 3.6 |
| 会话（Session） | 一次对话的持久化身份：可保存、恢复、分叉 | 3.6 · 深入 5.5、6.5 |
| 上下文压缩（Context Compaction） | 历史过长时以摘要替换旧消息、释放上下文窗口的机制 | 3.7 · 深入 6.6 |
| 扩展（Extension） | 不改核心源码为 harness 增加工具/命令/行为的代码插件 | 3.7 · 深入 7.1 |
| 技能（Skill） | 以文档形式按需注入的「怎么做某类事」的知识 | 3.7 · 深入 7.2 |
Pi 专有
| 术语 | 定义 | 讲解章节 |
|---|---|---|
| pi-ai | @earendil-works/pi-ai：统一多 Provider 的 LLM 接口层 | 6.1 |
| pi-agent-core | @earendil-works/pi-agent-core：Agent 运行时（循环、工具执行、Harness） | 6.3 |
| pi-coding-agent | @earendil-works/pi-coding-agent：pi 命令的产品层 | 5.1 |
| pi-tui | @earendil-works/pi-tui：终端 UI 库（差分渲染） | 6.9 |
| AgentSession | coding-agent 的核心对象：组装模型、工具、扩展、会话为一体 | 5.2 |
| streamFn | 「向模型发起一次流式请求」的函数抽象；Harness 与具体 Provider 的解耦点 | 6.1 |
| 交互模式 / print 模式 / JSON / RPC 模式 | pi 的四种运行模式，由 TTY 与 --mode 决定 | 4.4 · 6.10 |
| 差分渲染（differential rendering） | 只重绘终端上变化部分的渲染策略 | 6.9 |
| 会话树 / 分支（branch） | Session 条目以 parent 指针构成的树；压缩与分叉产生分支 | 6.5 |
| SDK | 把 pi 作为库嵌入自己程序的编程接口 | 6.11 |
| Prompt Template（提示词模板） | 可复用的提示词文件（斜杠命令形式展开） | 6.7 |
| TypeBox | Pi 用于定义工具参数 schema 并做运行时校验的库 | 6.4 |
工程与本书基础设施
| 术语 | 定义 | 讲解章节 |
|---|---|---|
| commit hash / permalink | Git 提交的唯一编号 / 指向固定 commit 的不变链接 | 4.2 |
| canonical repository | 项目的官方权威仓库（区别于镜像/旧名重定向） | 4.2 |
| CLI（命令行界面，Command-Line Interface） | 以文本命令交互的程序形态 | 1.2 |
| TUI（终端界面，Terminal User Interface） | 在终端里绘制的交互界面（Pi 的默认形态） | 4.1 |
| TTY | 终端设备；程序据此判断自己是否连着交互式终端 | 4.4 |
| RPC（远程过程调用，Remote Procedure Call） | 进程间以协议互调功能；Pi 用 stdin/stdout 上的 JSONL | 6.10 |
| JSONL（JSON Lines） | 每行一个 JSON 对象的文本格式；Pi 的会话文件与 RPC 协议均用它 | 5.5 |
| Mermaid | 用文本描述、在页面内渲染的图表格式（本书大量使用） | 阅读指南 |