全书术语索引：概念、源码与实现

小A在写周报时，把“token”和“context window”混着用，被老Z逮住了。他讪讪地问：“那我该去哪儿查这些词到底什么意思？”

“你不是第一个问这个的。”老Z把本索引翻出来，“这本索引贯穿全书：概念篇条目给出本书工作定义，源码篇条目固定到指定源码快照，实现篇条目只描述本书参考产物。每个条目都标注它在哪一章被定义或展开（只写章节名，不给链接）；并列词表示该章将它们作为同一组概念说明，不意味着它们在所有实现中可互换。”

怎么用这本索引

读到某个术语拿不准时，先查这里的工作定义；定义里标注的章节名告诉你去哪儿看完整论证。工作定义是本书的约定，不是行业标准。换一本书，同一个词可能有不同侧重。

模型与推理

中文名	英文／缩写	本书工作定义	定义章节
大语言模型	Large Language Model(LLM)	根据输入 token 生成后续 token 概率分布的模型或服务，一台接龙机器，不是“会思考”的主体	第2章 接龙机器的真相——LLM
token／分词器	token／tokenizer	文本被编码成模型处理的离散单位；一个 token 不等于一个字、一个词或半词，取决于分词器	第2章 接龙机器的真相——LLM
自回归生成	autoregressive generation	选中一个 token 后把它追加为条件，继续生成下一个，即“自己生成自己后续”	第2章 接龙机器的真相——LLM
参数	parameters／weights	训练中被优化的数值；推理时固定不变，决定了模型对输入的响应	第2章 接龙机器的真相——LLM
训练	training	用训练目标更新模型参数的过程；与推理(inference)是两个完全不同的阶段	第2章 接龙机器的真相——LLM
模型推理／推断	inference	用固定参数处理新输入并生成输出；与 reasoning 的“中间计算”含义区分，别混	第2章 接龙机器的真相——LLM
采样	sampling	从下一个 token 的概率分布选择 token 的规则(贪心、温度、top-k、top-p 等)	第2章 接龙机器的真相——LLM
温度	temperature	改变采样候选分布平坦度的控制参数；高温度更随机，低温度更确定	第2章 接龙机器的真相——LLM
幻觉	hallucination	看似合理但不真实的事实、引用或代码细节；根因是概率生成而非“查证”，不是模型“撒谎”	第2章 接龙机器的真相——LLM
上下文窗口	context window	一次请求共同可见的 token 预算；超出窗口的内容模型看不见，因为从未收到，谈不上“忘了”	第2章 接龙机器的真相——LLM
提示词缓存	prompt caching	服务对可复用输入前缀复用计算的机制；命中要求前缀稳定，前缀一变后面全废	第2章 接龙机器的真相——LLM
推理	reasoning	多约束任务中的中间计算、搜索或控制过程；与 inference(推断)是完全不同的两件事，中文易混	第3章 给思考留一张草稿纸——CoT
思维链	Chain-of-Thought(CoT)	输出或提示中的中间推理步骤方法；让模型“先想后答”，不是让模型“变得更聪明”	第3章 给思考留一张草稿纸——CoT
推理强度／预算	reasoning effort／budget	特定 API 对推理资源或输出预算的控制项；调高不等于更准，可能更慢更贵	第3章 给思考留一张草稿纸——CoT
停止原因	stop reason／finish reason	响应结束时供调用方选择控制流的状态(complete / length / tool_use / error 等)；它决定下一步，不只是个标签	第3章 给思考留一张草稿纸——CoT

提供方、提示与消息

中文名	英文／缩写	本书工作定义	定义章节
提供方	Provider	认证、模型目录和请求行为的服务边界，一个封装了认证、限流、错误语义的完整抽象，不止是一个“URL”	第4章 翻译局如何接通模型——Provider
适配器	adapter	统一契约与厂商协议之间的转换实现；屏蔽外部形状，可能丢失厂商专有信息	第4章 翻译局如何接通模型——Provider
统一消息	unified message	角色、内容块、调用与结果的业务表示；与各厂商原生格式通过适配器互转	第4章 翻译局如何接通模型——Provider
流式传输	streaming	有生命周期的增量事件，按 start / delta / stop 的事件流推进，而非“一次返回全部”	第4章 翻译局如何接通模型——Provider
超时／重试	timeout／retry	取消未完成请求／对明确的瞬时故障有限重试的控制；不是“无限重试到成功”	第4章 翻译局如何接通模型——Provider
幂等性	idempotency	重复操作不额外改变目标状态的性质；重试安全的前提，不是所有操作都具备	第4章 翻译局如何接通模型——Provider
系统提示词／系统消息	System Prompt／System Message	应用在请求中提供的前置工作规则；定“规矩”，不定“人格”，模型不会因为 system prompt 就变成另一个人	第5章 先把规矩说清楚——System Prompt
指令层级	instruction hierarchy	特定 API 定义的消息来源或角色优先顺序；system 通常高于 user，但不绝对	第5章 先把规矩说清楚——System Prompt
提示词组合	prompt composition	将基础规则、工具说明、项目资料和任务分层装配为请求的过程，不是“写一段话”	第5章 先把规矩说清楚——System Prompt
提示词版本／评测	prompt version／evaluation	记录变更并用探针比较可观察行为；改 prompt 不跑回归等于盲改	第5章 先把规矩说清楚——System Prompt

工具与循环

中文名	英文／缩写	本书工作定义	定义章节
函数调用／工具使用	function calling／tool use	模型输出结构化调用请求的接口能力；决定调用是模型的事，执行不是	第6章 从“会说”到“会做”——Function Calling
工具调用	tool call	带名称、参数、调用 ID 的未执行请求；它是一个意图，执行与否由宿主决定	第6章 从“会说”到“会做”——Function Calling
JSON Schema	JSON Schema	描述参数数据形状的约束；模型给出的参数仍需运行时校验，不能假设一定合法	第6章 从“会说”到“会做”——Function Calling
工具结果	tool result	执行器按调用 ID 回传的结构化状态；失败也是结果，不是“没有结果”	第6章 从“会说”到“会做”——Function Calling
并行调用	parallel calls	一轮出现多个调用请求的协议可能性；并行的是“请求”，执行是否并行由宿主决定	第6章 从“会说”到“会做”——Function Calling
工具	Tool	可被宿主声明、校验与执行的具体能力，是模型操作世界的“把手”，但它本身有独立的安全边界	第8章 给能力装上把手——Tool
工具规格	ToolSpec	名称、描述、输入 schema、结果契约的声明；是工具的“说明书”，执行器是“手”	第8章 给能力装上把手——Tool
运行时校验	runtime validation	对模型给出的实际值做 schema 与业务检查；模型会给出 schema 外的值，这步不能省略	第8章 给能力装上把手——Tool
执行边界／输出预算	execution boundary／output budget	副作用真正发生的位置／限制工具结果进入上下文的大小与形状；两者都是工程约束，不是模型能感知的	第8章 给能力装上把手——Tool
Agent 循环	Agent Loop	反复请求模型、处理工具结果、更新状态的控制流；“循环”是它的本质，单次问答不是 Agent	第9章 让工作真正循环起来——Agent Loop
回合	turn	一次模型响应及其后续工具结果的状态单元；一个 turn 可以包含多次工具调用	第9章 让工作真正循环起来——Agent Loop
ReAct	Reasoning and Acting	推理轨迹与动作交替的研究方法；是 Agent Loop 的一种历史范式，不是唯一实现	第9章 让工作真正循环起来——Agent Loop
停止条件	stop condition	预算、完成、失败、取消等终止转移；它决定循环何时结束，不结束的循环会烧钱	第9章 让工作真正循环起来——Agent Loop
事件／状态机	event／state machine	可观测事实和允许转移的控制模型；调试 Agent 就是调试这个状态机	第9章 让工作真正循环起来——Agent Loop
取消	cancellation	通过 signal／控制器请求停止当前工作；协作式的，工具不响应 signal 时取消不生效	第9章 让工作真正循环起来——Agent Loop

记忆、扩展与协议

中文名	英文／缩写	本书工作定义	定义章节
会话	session	跨多个回合组织消息、调用与状态的应用记录；不是模型的“记忆”，模型本身是无状态的	第10章 记住什么，忘掉什么：Memory
短期／长期记忆	short-term／long-term memory	当前任务材料／经确认可跨会话复用的信息；边界在于“是否跨会话”，不在于“存在哪”	第10章 记住什么，忘掉什么：Memory
截断／压缩	truncation／compaction	删除部分材料／以摘要替代旧材料；截断无损但有界，压缩有损但保摘要，两者代价不同	第10章 记住什么，忘掉什么：Memory
检索	retrieval	按查询从受控存储取回材料；检索质量决定 RAG 的上限，模型能力影响结果下限；具体上限和下限按任务指标评测	第10章 记住什么，忘掉什么：Memory
保留策略	retention	数据保留、访问、更新与删除的规则；是隐私和合规问题，不是纯技术问题	第10章 记住什么，忘掉什么：Memory
Agent 钩子	Agent Hook／Hook	Agent 生命周期事件发生时被调用的应用代码；接口名和时序由具体实现定义，不是通用标准	第11章 在动作发生前插一句话——Hooks
拦截器	interceptor	可允许、拒绝或改写主路径的 Hook；出错可能影响整个 turn	第11章 在动作发生前插一句话——Hooks
订阅者／监听器	subscriber／listener	观察事件而不改变主路径的接收者；出错影响取决于调用方是否捕获和隔离	第11章 在动作发生前插一句话——Hooks
生命周期事件	lifecycle event	运行时约定的状态转换点；hook 挂在事件上，事件由 loop 触发	第11章 在动作发生前插一句话——Hooks
重入	reentrancy	Hook 执行时再次触发同一事件链；会导致无限递归，需显式防护	第11章 在动作发生前插一句话——Hooks
模型上下文协议	Model Context Protocol(MCP)	固定版本规范定义的能力与上下文交换协议；不是某个厂商的私有 API，是开放规范	第12章 给外部工具留一扇门——MCP
宿主／客户端／服务端	host／client／server	承载应用、发起协议操作、暴露能力的三个角色；一个进程可以同时扮演多个角色	第12章 给外部工具留一扇门——MCP
版本与能力声明	protocol version／client capabilities	外部规范 MCP 2026-07-28 版中每个请求在 _meta 里声明协议版本和客户端能力，可先用 server/discover 查询服务端；pi v1.0.0 实现的是 2025-11-25 一代，不是这些机制。不能默认连上就能用所有功能	第12章 给外部工具留一扇门——MCP
多轮请求	Multi Round-Trip Requests（MRTR）	外部规范 MCP 2026-07-28 的概念：服务端需要补充信息时返回 input_required，客户端带着 inputResponses 用新请求 ID 重发原请求；pi v1.0.0 未实现该机制	第12章 给外部工具留一扇门——MCP
提示／资源／工具	Prompt／Resource／Tool	模板、可读取上下文、可调用动作三类原语；三类各有边界，不能混用	第12章 给外部工具留一扇门——MCP
标准输入输出／可流式 HTTP	stdio／Streamable HTTP	规范定义的本地与远程传输方式；stdio 是本地进程间，HTTP 是远程网络	第12章 给外部工具留一扇门——MCP

技能、协作与检索

中文名	英文／缩写	本书工作定义	定义章节
技能	Skill	可发现、可按需加载的任务经验说明，靠文本影响模型，本身不直接执行，是“说明书”不是“代码”	第13章 把经验装进说明书——Skill
指令包	instruction bundle	适用条件、步骤、资料、工具和验收说明的组合；一个 skill 是一个完整的指令包	第13章 把经验装进说明书——Skill
发现／触发／渐进加载	discovery／trigger／progressive loading	先读索引、判定适用、再加载正文的三步；避免一次性加载所有 skill 撑爆上下文	第13章 把经验装进说明书——Skill
软约束	soft constraint	借文本影响模型决策的规则；“软”意味着模型可能不遵守，硬约束要靠工具和权限	第13章 把经验装进说明书——Skill
子代理	subagent	被委派边界任务的独立执行者；独立意味着有自己的上下文和状态，不和主 Agent 共享	第14章 一个人做，还是一群人做：Multi-Agent
多 Agent 系统	multi-agent system	两个以上执行者通过任务或消息协作的系统；“多”不等于“更好”，协调成本是真实代价	第14章 一个人做，还是一群人做：Multi-Agent
编排器／控制面	orchestrator／control plane	分配、取消、汇总和观察任务的协调层；它管理队列，不消除冲突	第14章 一个人做，还是一群人做：Multi-Agent
任务所有权／共享状态	task ownership／shared state	谁可修改何物、哪些状态共同可见的契约；没有这个契约的多 Agent 系统会产生不可归属的 bug	第14章 一个人做，还是一群人做：Multi-Agent
检索增强生成	Retrieval-Augmented Generation(RAG)	检索证据后将其纳入生成上下文的链路；检索是手段，生成才是目的	第15章 让模型带着资料回答——RAG
摄取／切分／索引	ingestion／chunking／index	将源资料变成带元数据、可检索片段的过程；切分策略决定召回质量上限	第15章 让模型带着资料回答——RAG
稀疏／稠密／混合检索	sparse／dense／hybrid retrieval	词项、向量及候选合并的召回方法；稀疏抓关键词，稠密抓语义，混合兼顾	第15章 让模型带着资料回答——RAG
重排／落地	reranking／grounding	重选候选、让回答受证据支持；重排提升精度，落地防止编造引用	第15章 让模型带着资料回答——RAG

编排与安全

中文名	英文／缩写	本书工作定义	定义章节
工作流／图	Workflow／Graph	固定步骤／节点边和路由表达；workflow 是预设路线，graph 允许动态路由	第16章 当路线不止一条——Workflow & Graph
检查点／重放	checkpoint／replay	保存恢复点／按恢复契约再次执行；重放要求幂等，否则副作用会重复	第16章 当路线不止一条——Workflow & Graph
威胁模型	threat model	资产、攻击面、主体与可接受损失的假设，用来分清哪些值得防，不是把所有风险列一遍	第17章 给自主性装上护栏——Security
信任边界／提示注入	trust boundary／prompt injection	不可信输入的边界／诱导模型越权的内容；注入是 Agent 时代的新型攻击面	第17章 给自主性装上护栏——Security
最小权限／审批	least privilege／approval	默认能力收缩／单次高风险动作决定；最小权限是默认，审批是例外	第17章 给自主性装上护栏——Security
沙箱／隔离	sandbox／isolation	限制进程、文件、网络或虚拟化影响面的机制；OS 级沙箱是硬隔离，prompt 级“沙箱”是软约束，两者不等价	第17章 给自主性装上护栏——Security
纵深防御	defense in depth	多层独立控制共同限制损失；任何一层都不能单点保证安全	第17章 给自主性装上护栏——Security

源码篇固定快照术语

以下工作定义固定到上游 pi 标签 v1.0.0（提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32，简称 a13d35a7），不外推到其他版本。

源码术语	固定快照工作定义	定义章节
ModelsImpl	持有 Provider 映射，并负责模型查找、认证合并与流入口委派的模型集合实现	源码篇第2章 目录与户口——pi-ai
Provider	按模型 API 暴露流实现、认证与模型目录行为的运行时服务边界	源码篇第2章 目录与户口——pi-ai
lazyStream	把流创建延迟到订阅时、并统一错误入口的包装；不改变厂商事件格式	源码篇第3章 先开票，后办事——pi-ai
Agent	持有 transcript、监听器、消息队列与当前中止控制器，并调用低层循环的宿主包装	源码篇第4章 双层循环——pi-agent-core
回合插口	finishTurn、prepareNextTurn、prepareRequest 三个由宿主注入、在回合边界改写运行状态的回调	源码篇第4章 双层循环——pi-agent-core
AgentSession	coding-agent 中把会话写入、压缩、扩展和请求投影接到 Agent 插口上的装配层	源码篇第5章 调度台——pi-coding-agent
JSONL session entry	JSONL header 之后的会话树条目；可记录消息、配置变化、压缩或导航信息，不只保存对话	源码篇第5章 调度台——pi-coding-agent
session fork	从选定会话历史派生新 session 的操作；不创建 Git 分支或 worktree	源码篇第5章 调度台——pi-coding-agent
compaction	通过可能失败的独立摘要请求缩小后续上下文，并写入压缩条目的有损过程	源码篇第5章 调度台——pi-coding-agent
ValidatedMessageDecoder／FrameDecoder	前者串接 frame、CBOR 与 schema 验证；后者从字节 chunk 中切出完整 payload	源码篇第9章 发货与报关——pi-protocol
附着（attachment）	一条远程连接对一个托管会话的当前绑定，带随机 attachmentId；会话请求必须与它一致	源码篇第10章 黑板与便签——pi-server+pi-client
订阅快照／service_update	服务订阅时随响应返回的完整状态／之后在该快照上推送的增量	源码篇第10章 黑板与便签——pi-server+pi-client
eval harness	为一次评测建立临时环境、运行 Agent、收集输出与 artifact 并清理资源的适配层	源码篇第11章 每次考试换新考场——pi-evals

实现篇参考产物术语

以下名称只描述 examples/mini-agent 的当前接口和行为，不是行业标准。

实现术语	mini-agent 当前工作定义	定义章节
ModelClient	接收 system、messages、tools 与可选 signal，并异步产出内部模型事件的可注入接口	实现篇第2章 接通第一根管道——ModelClient
ModelEvent	当前产物用于表达 text、tool_call 与 done 的内部事件联合类型	实现篇第2章 接通第一根管道——ModelClient
ToolSpec	当前工具的名称、描述、输入 schema 与执行函数契约	实现篇第4章 给手装上工具——Tools
BeforeToolCall	工具执行前返回允许或拒绝结果的策略扩展缝；不是全局强制安全层	实现篇第7章 在执行前设一道卡——Approval
workspace path boundary	以 realpath、最近存在祖先和相对路径检查约束工作区路径的边界；不是 OS 沙箱	实现篇第4章 给手装上工具——Tools
character approximation budget	按完整消息 JSON 字符长度估算并裁剪一致上下文单元的预算；不是 token 计数	实现篇第5章 让记忆续上——Session
FakeClient	按预设事件轮次实现 ModelClient 的离线测试替身，不验证真实 Provider 网络	实现篇第1章 白纸与边界——Scope
complete／max_turns／aborted	当前循环分别表示无工具调用完成、轮次预算耗尽和外部信号中止的返回状态	实现篇第3章 把方向盘交给循环——Agent Loop