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

小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 |