附录 A 术语表
按主题分组的全书术语速查。详见列给首次系统讲解的位置；同组内大体按在书中出现的先后排序。技术名词在正文中保留英文，此处一并给出中文对照。
一、检索范式与鸿沟
| 术语 |
英文/全称 |
一句话解释 |
详见 |
| 命名鸿沟 |
naming gap |
用户心里的概念与代码里的标识符对不上（"注销"vs kill_session） |
1.1 |
| 别名鸿沟 |
alias gap |
同一概念多种写法（logout/signout/kill session） |
1.1 |
| 意图鸿沟 |
intent gap |
查询描述"想做什么"，不是"找什么名字" |
1.1 |
| 文本检索 |
lexical/text search |
按字面匹配（grep/BM25/Zoekt），精确但不懂语义 |
1.1 |
| 符号检索 |
symbol search |
按定义/引用/调用图导航（ctags/LSP/tree-sitter），精确但要求先知道名字 |
1.2 |
| 语义检索 |
semantic search |
嵌入向量上的近邻检索，跨命名与意图鸿沟但丢精确性 |
1.3 |
| 意图级检索 |
intent-level search |
查询直接是自然语言意图（Sourcegraph 形态） |
8.1 |
二、切分与解析
| 术语 |
英文/全称 |
一句话解释 |
详见 |
| chunk |
chunk |
嵌入与检索单位的代码块（函数/类/兜底块），带元数据 |
3.1 |
| AST |
Abstract Syntax Tree |
语法树：代码的结构化表示，tree-sitter 的产出 |
1.2 |
| tree-sitter |
tree-sitter |
增量解析框架，容错强、多语言，符号切分的地基 |
1.2/3.2 |
| py-tree-sitter |
— |
tree-sitter 的 Python 绑定（Language/Parser/QueryCursor） |
3.2 |
| S-expression 查询 |
query |
tree-sitter 的语法树模式匹配语言，@名 捕获结果 |
3.2 |
| 孤儿代码 |
orphan code |
模块级 import/常量/散语句，切分时兜底成 module chunk |
3.2 |
| 类骨架 |
class skeleton |
巨类只切出签名+docstring 的骨架块，方法另切 |
3.2 |
| 身份前缀 |
identity prefix |
chunk 文本前加 # kind symbol of class X，注入上下文身份 |
3.3/4.1 |
| 拦腰截断 |
mid-function split |
坏切块症状一：函数被固定窗口切开 |
3.3 |
三、嵌入与向量
| 术语 |
英文/全称 |
一句话解释 |
详见 |
| 嵌入 |
embedding |
文本 → 定长向量，语义相近则几何相近 |
2.1 |
| 代码嵌入模型 |
code embedding model |
在代码语料上特训的嵌入模型（voyage-code-3 等） |
2.2 |
| 余弦相似度 |
cosine similarity |
归一化向量的内积，本书的"语义距离" |
2.1 |
| bi-encoder |
bi-encoder |
查询与文档各自编码、最后算相似度——召回便宜但无交互 |
5.2 |
| ANN |
Approximate Nearest Neighbor |
近似最近邻：放弃一点召回换数量级加速（IVF/HNSW） |
4.1 |
| 向量库 |
vector store |
存向量+元数据、支持近邻查询（numpy 暴力即最简形态） |
4.1 |
| 嵌入维度 |
dimension |
向量长度，库的配置项，随模型而定 |
2.2 |
| model_ver |
— |
state 里记录的嵌入模型版本，防混库保险丝 |
4.2 |
四、混合检索与重排
| 术语 |
英文/全称 |
一句话解释 |
详见 |
| BM25 |
Okapi BM25 |
词频×逆文档频率×长度归一的词法打分函数 |
1.1/5.1 |
| TF / IDF |
term frequency / inverse document frequency |
词在文档中的频率 / 词的稀有度 |
5.1 |
| 标识符拆分 |
identifier splitting |
killSession→kill session：代码分词的核心步 |
5.1 |
| RRF |
Reciprocal Rank Fusion |
score=Σ 1/(k+rank) 的排名融合，k 常取 60 |
5.1 |
| 召回宽度 |
recall width |
每路召回的候选条数（recall 参数） |
5.1/7.4 |
| 混合权重 |
hybrid weights |
两路在融合里的配比（bm25_w/vec_w） |
5.1 |
| 重排 |
rerank |
对 top 几十候选做精排的最后一公里 |
5.2 |
| 交叉编码器 |
cross-encoder |
query 与文档拼接后同框编码，精度高但每对都要跑模型 |
5.2 |
| 重排深度 |
rerank depth |
送入重排的候选条数（depth），0 即关闭 |
5.2 |
| 校准概率 |
calibrated probability |
可当置信度用的 0~1 概率（LLM 逐项打分重排的输出） |
5.2 |
| HyDE |
Hypothetical Document Embeddings |
先生成假想文档再拿它当查询检索 |
5.3 |
| 同义扩展 |
synonym expansion |
查询扩成多变体，多路召回再融合 |
5.3 |
五、agentic 检索
| 术语 |
英文/全称 |
一句话解释 |
详见 |
| agentic coding |
agentic coding |
Agent 自主读改代码的工作形态，检索是其粮食 |
0.1 |
| repo-map |
repository map |
压缩进上下文的仓库符号地图（aider） |
1.2/6.1 |
| 类 PageRank |
PageRank-like ranking |
沿引用图迭代传播权重的排序，挑代表性符号 |
6.1 |
| 阻尼系数 |
damping factor |
PageRank 的 d（0.85 经验值），防强者恒强 |
6.1 |
| 惰性检索 |
lazy retrieval |
不预建索引，glob/grep 按需检索（Claude Code） |
4.3/6.2 |
| 预建索引 |
prebuilt index |
离线建好索引换在线速度的两极之另一极 |
6.2 |
| 工具 schema |
tool schema |
Agent 工具的名称/参数/描述定义，能力边界画在参数里 |
6.3 |
| 上下文窗口 |
context window |
模型一次能读的 token 预算，repo-map 省的就是它 |
6.1 |
六、索引工程
| 术语 |
英文/全称 |
一句话解释 |
详见 |
| 增量更新 |
incremental update |
只重处理失效文件/chunk 的索引更新 |
4.2 |
| 两级失效判定 |
two-level invalidation |
mtime 快查、内容哈希定谳 |
4.2 |
| 稳定 chunk ID |
stable chunk ID |
path:start-end:symbol，差分与评测的对齐键 |
4.2 |
| 先删后插 |
delete-then-insert |
增量写入顺序，防同 ID 新旧并存 |
4.2 |
| 防抖 |
debounce |
合并"保存风暴"的短时重复事件 |
4.2 |
| 分片 |
sharding |
按目录/仓库切索引，并行与隔离的基本单位 |
4.3 |
| 优先级队列 |
priority queue |
热文件先索引的调度结构 |
4.3 |
| 冷热分层 |
hot/cold tiering |
活跃与陈旧索引分存储与更新策略 |
4.3 |
| trigram |
trigram |
三字符组，Zoekt 的索引单位，任意子串的公共货币 |
8.1 |
| 倒排索引 |
inverted index |
词元→文档列表的映射，全文检索的地基 |
8.1 |
七、评测
| 术语 |
英文/全称 |
一句话解释 |
详见 |
| 金标 |
gold / ground truth |
评测集里"正确答案"的标注（chunk ID→相关度） |
2.3/9.2 |
| 三级相关度 |
graded relevance |
3=命中本体 / 2=同文件 / 1=相关模块 的分级金标 |
9.1 |
| MRR |
Mean Reciprocal Rank |
首个相关结果排名倒数的平均，盯"第一枪" |
9.1 |
| Recall@K |
Recall at K |
前 K 结果覆盖金标的比例，盯"漏没漏" |
9.1/2.3 |
| nDCG |
normalized Discounted Cumulative Gain |
位置折损×等级增益的归一化，盯"排序质量" |
9.1 |
| 消融 |
ablation |
开/关单个组件看指标变化的实验 |
5.3/9.3 |
| holdout |
holdout set |
从不参与调参的保留评测集，防过拟合 |
9.2 |
| 回归护栏 |
regression guard |
CI 上与基线比指标、掉点即拦截的门 |
9.3 |
| 弱标注 |
weak labeling |
用启发式（git 历史）自动产的候选金标，须人审 |
9.2 |
| CoIR |
Code Information Retrieval |
2024 年起的代码检索标准评测套件 |
2.3 |
八、产品与平台（描述以官方文档为准）
| 术语 |
一句话解释 |
详见 |
| Zoekt |
开源 trigram 代码索引引擎，Sourcegraph 的字面层 |
8.1 |
| Sourcegraph |
意图级语义检索 + Zoekt 的企业代码搜索平台 |
1.3/8.1 |
| Greptile |
符号感知 chunk + 语义检索、面向 agentic coding 的 API |
0.1/8.2 |
| Copilot 即时索引 |
GitHub 2025-03 GA 的秒级语义索引（官方自报） |
4.3/8.2 |
| aider repo-map |
tree-sitter 符号 + 类 PageRank 的仓库地图 |
1.2/6.1 |
| Claude Code |
惰性检索的代表：glob/grep/read 组合按需翻文件 |
4.3/6.2 |