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

小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	跨多个回合组织消息、调用与状态的应用记录;不是模型的“记忆”,模型本身是无状态的	Memory:记住什么,忘掉什么
短期／长期记忆	short-term／long-term memory	当前任务材料／经确认可跨会话复用的信息;边界在于“是否跨会话”,不在于“存在哪”	Memory:记住什么,忘掉什么
截断／压缩	truncation／compaction	删除部分材料／以摘要替代旧材料;截断无损但有界,压缩有损但保摘要——两者代价不同	Memory:记住什么,忘掉什么
检索	retrieval	按查询从受控存储取回材料;检索质量决定 RAG 上限,模型能力决定下限不会太低	Memory:记住什么,忘掉什么
保留策略	retention	数据保留、访问、更新与删除的规则;是隐私和合规问题,不是纯技术问题	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
能力协商	capability negotiation	初始化中声明和确认支持功能;不是“连上就能用所有功能”,而是“先谈妥再干活”	第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 共享	Multi-Agent:一个人做,还是一群人做
多 Agent 系统	multi-agent system	两个以上执行者通过任务或消息协作的系统;“多”不等于“更好”,协调成本是真实代价	Multi-Agent:一个人做,还是一群人做
编排器／控制面	orchestrator／control plane	分配、取消、汇总和观察任务的协调层;它管理队列,不消除冲突	Multi-Agent:一个人做,还是一群人做
任务所有权／共享状态	task ownership／shared state	谁可修改何物、哪些状态共同可见的契约;没有这个契约的多 Agent 系统会产生不可归属的 bug	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-mono 提交 583f153d502aa8e958eefdb9af0fbd3344e68f95(简称 583f153d),不外推到其他版本。

源码术语	固定快照工作定义	定义章节
ModelsImpl	持有 Provider 映射,并负责模型查找、认证合并与流入口委派的模型集合实现	第19章 目录与户口——pi-ai
Provider	按模型 API 暴露流实现、认证与模型目录行为的运行时服务边界	第19章 目录与户口——pi-ai
lazyStream	把流创建延迟到订阅时、并统一错误入口的包装;不改变厂商事件格式	第20章 先开票，后办事——pi-ai
Agent	持有 transcript、监听器、消息队列与当前中止控制器,并调用低层循环的宿主包装	第21章 双层循环——pi-agent-core
AgentHarness	将 Agent、模型、工具、提示、会话写入和宿主生命周期组合起来的装配层	第22章 调度台——pi-agent-core
JSONL session entry	JSONL header 之后的会话树条目;可记录消息、配置变化、压缩或导航信息——不只保存对话	第22章 调度台——pi-agent-core
session fork	从选定会话历史派生新 session 的操作;不创建 Git 分支或 worktree	第22章 调度台——pi-agent-core
compaction	通过可能失败的独立摘要请求缩小后续上下文,并写入压缩条目的有损过程	第22章 调度台——pi-agent-core
ValidatedMessageDecoder／FrameDecoder	前者串接 frame、CBOR 与 schema 验证;后者从字节 chunk 中切出完整 payload	第26章 发货与报关——pi-protocol
snapshot／progress	用较新完整状态校正客户端／表达增量活动的两类远程会话消息	第27章 黑板与便签——pi-server+pi-client
eval harness	为一次评测建立临时环境、运行 Agent、收集输出与 artifact 并清理资源的适配层	第28章 每次考试换新考场——pi-evals

实现篇参考产物术语

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

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

回到全书目标:术语是沟通的工具,不是装饰。用错术语会让团队对同一个概念各想各的;用对术语,讨论才能聚焦在真正的问题上。