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

小A和老Z把不同颜色的术语卡按概念、源码与实现分组,逐一理清容易混淆的词。

小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