因为知识库只是资料放在哪里，RAG 真正要解决的是：当 AI 给出一个答案时，我们能不能知道它依据了哪段材料、有没有遗漏限制条件、能不能在证据不足时拒答。

但如果继续往下讲 RAG，很快就会遇到一堆术语：

Embedding、Chunk、Vector DB、BM25、Reranker、Citation、Faithfulness、RAG Eval……

这些词如果直接堆出来，文章会很像技术名词表。读者看完还是不知道：它们到底在 RAG 系统里解决什么问题？

所以这一篇不写代码，不写复杂架构，只做一件事：

把 RAG 里的核心术语翻译成人话，并说明每个组件在“证据链”里负责什么。

如果把 RAG 看成一条可信回答链路，它大概是这样：

原始文档
  ↓
清洗 / 解析
  ↓
Chunking
  ↓
Embedding
  ↓
向量检索 / BM25 检索
  ↓
Hybrid Search
  ↓
RRF 融合排序
  ↓
Reranker 精排
  ↓
Final Evidence
  ↓
LLM 基于证据生成回答
  ↓
Citation / Faithfulness / Abstention
  ↓
RAG Eval

这条链路看起来很长，但它其实只服务一个目标：

让 AI 的回答从“看起来对”，走向“有证据、可追溯、可验证”。

1. Document：原始资料

Document，就是进入知识库的原始资料。它可以是公司制度 PDF、产品说明书、客服 SOP、GitHub README、技术文档、Markdown 博客、简历、订单规则、FAQ，也可以是数据库里的业务记录。

Document 解决的是 RAG 里最基础的问题：

系统到底从哪里拿事实？

如果没有外部资料，模型只能依赖参数记忆。它可能知道一些通用知识，但不知道你的公司政策、项目文档、订单状态、内部流程、用户简历。

所以 Document 是 RAG 的原料。

但原始文档不能直接塞给模型。原因很简单：

• 太长。
• 太乱。
• 格式复杂。
• 版本不清楚。
• 里面可能有页眉、页脚、目录、广告、水印、重复段落。
• 有些信息已经过期。
• 有些信息不属于当前用户或当前租户。

所以进入 RAG 系统的第一步，不是 embedding，也不是向量库，而是文档治理：这份文档是谁的、从哪里来、什么时候更新、属于哪个业务线、是否有效、用户有没有权限看。

一句话总结：
Document 是 RAG 的事实来源，但原始文档本身还不是可用证据。

2. Chunk：证据片段

Chunk，就是把大文档切成一小段一小段，方便检索和引用。

很多人会把 chunking 理解成“把长文切短”，比如每 500 tokens 切一段，重叠 50 tokens。

这个理解太粗。

真正好的 chunk，不只是短，而是要成为一个“证据单元”。

比如一份退款政策里有这样一段：

定制商品非质量问题不支持七天无理由退货。若商品存在质量问题，用户需在签收后 7 日内提交图片或视频证据，客服审核后进入售后流程。

如果你把它切成两段：

• 第一段只保留“定制商品非质量问题不支持七天无理由退货”。
• 第二段只保留“用户需在签收后 7 日内提交证据”。

那模型可能在回答时丢掉条件，或者误解适用范围。

所以 chunk 的目标不是平均切短，而是：

把文档切成能被检索、被引用、被验证的最小证据单元。

好的 chunk 不只包含正文，还应该带上能追溯和过滤的信息，比如标题、章节、来源、页码、版本、所属租户、更新时间和权限范围。

比如：

{
  "content": "定制商品非质量问题不支持七天无理由退货...",
  "source": "refund_policy_v3.pdf",
  "section": "定制商品售后限制",
  "page": 7,
  "tenantId": "merchant_001",
  "version": "v3",
  "updatedAt": "2026-06-01"
}

这才是一个对 RAG 友好的 chunk。

一句话总结：

Chunk 不是把文档切短，而是把文档切成 AI 能使用、用户能追溯的证据片段。

3. Embedding：把文本变成语义坐标

Embedding 是 RAG 里最常被提到的词。

简单说，Embedding 就是把一段文本变成一串数字，也就是向量。

为什么要这么做？

因为计算机不能直接理解“这两句话意思很接近”。它需要一种可以计算的表示方式。

比如用户问：

出差住酒店最多能报销多少钱？

文档里写的是：

差旅住宿报销标准：一线城市 600 元/晚，其他城市 400 元/晚。

这两句话用词不完全一样。

用户说的是“出差”“住酒店”“最多能报销多少钱”，文档写的是“差旅”“住宿”“报销标准”。如果只靠关键词，系统不一定能稳定命中。但从语义上看，它们问的其实是同一类问题。

Embedding 的作用，就是把这些文本映射到一个向量空间里。你可以把它理解成“语义坐标”。

• 意思接近的文本，坐标距离更近。
• 意思不相关的文本，坐标距离更远。

所以在 RAG 里，Embedding 解决的是：

让系统可以计算用户问题和文档片段之间的语义相似度。

具体流程分成两个阶段。

第一阶段是文档入库，也就是提前处理知识库：

原始文档
  ↓
切成 chunk
  ↓
每个 chunk 做 embedding
  ↓
得到每个 chunk 的向量
  ↓
把 chunk 原文 + 向量 + metadata 存入数据库

比如文档被切成三个 chunk：

chunk_001：差旅住宿报销标准：一线城市 600 元/晚，其他城市 400 元/晚。
chunk_002：交通费报销需提供发票。
chunk_003：餐饮补贴按城市等级计算。

系统会把每个 chunk 都转成向量。真实的向量通常有几百到几千维，这里只用简化数字演示：

chunk_001 embedding = [0.12, -0.44, 0.87, ...]
chunk_002 embedding = [0.31, 0.22, -0.10, ...]
chunk_003 embedding = [-0.18, 0.62, 0.40, ...]

这些数字不是给人看的，而是给系统计算相似度用的。

第二阶段是用户提问，也就是在线检索：

用户问题
  ↓
问题也做 embedding
  ↓
得到 query 向量
  ↓
拿 query 向量去数据库里查相似 chunk
  ↓
返回最相似的 topK 个 chunk
  ↓
把这些 chunk 原文交给 LLM 生成回答

比如用户问：

出差住酒店最多能报销多少钱？

系统会把这个问题也转成向量：

query embedding = [0.10, -0.41, 0.83, ...]

然后系统会比较：

query embedding 和 chunk_001 embedding 距离很近
query embedding 和 chunk_002 embedding 距离较远
query embedding 和 chunk_003 embedding 距离较远

所以它会优先召回 chunk_001：

差旅住宿报销标准：一线城市 600 元/晚，其他城市 400 元/晚。

最后，LLM 不是凭空回答，而是基于召回的 chunk 生成：

根据差旅住宿报销标准，一线城市住宿最高可报销 600 元/晚，其他城市最高可报销 400 元/晚。

所以 Embedding 不是直接回答问题，它只负责把“可能相关的证据”找出来。

你可以把它理解成 RAG 检索层的第一步：

文档 chunk 先变成向量
用户问题也变成向量
系统比较两边向量的距离
距离越近，说明语义越相关
然后取回对应 chunk 原文
再交给大模型生成回答

但这里有一个非常重要的边界：

Embedding 解决的是语义相似，不等于事实正确。

• 相似，不代表能回答。
• 相关，不代表完整。
• 语义接近，不代表证据足够。

比如用户问：

SKU-A1937 是否支持德国仓发货？

这个问题最关键的是两个精确信息：

SKU-A1937
德国仓

系统必须找到同时和这两个条件相关的内容。

如果只靠 Embedding，它可能召回这些看起来相近的内容：

SKU-A1938 支持德国仓发货。
SKU-A1937 支持法国仓发货。
德国仓发货规则说明。

这些内容都“相关”，但不一定能回答用户的问题。

因为用户问的不是“德国仓规则是什么”，也不是“类似 SKU 怎么发货”，而是：

SKU-A1937 这个具体商品，是否支持德国仓发货？

这种问题不能只靠语义相似，还需要 BM25 / 关键词检索、metadata filter，甚至直接查业务数据库。

所以不要把 Embedding 当成语义魔法。它只是 RAG 检索系统的一部分。

一句话总结：

Embedding 是 RAG 检索层的语义匹配器：它把文档片段和用户问题都变成向量，通过相似度找到可能相关的候选证据。但它只能说明“语义接近”，不能保证证据完整、事实正确、权限合规，也不能替代关键词检索和业务数据查询。

4. Vector DB：存向量、查相似

有了 embedding 之后，需要一个地方存这些向量，并支持按相似度检索。

这就是 Vector DB。

常见选择包括 PGVector、Milvus、Qdrant、Weaviate、Pinecone，也可以使用 Elasticsearch / OpenSearch 的向量检索能力。

Vector DB 的基本工作方式是：

• 文档被切成 chunk。
• 每个 chunk 被 embedding 成向量。
• 向量和 chunk 一起存入数据库。
• 用户提问时，问题也被 embedding 成向量。
• 系统查找和问题向量最相似的 chunk。
• 把这些 chunk 交给大模型生成答案。

基本流程：

chunk 文本
  ↓
embedding 模型
  ↓
向量
  ↓
Vector DB
  ↓
相似度检索
  ↓
topK chunks

如果你用 Java / Spring Boot / PostgreSQL 技术栈，PGVector 是一个很适合入门和工程落地的选择。它是 PostgreSQL 的向量相似搜索扩展，可以让你在 PostgreSQL 里存向量、建索引、做相似度查询。

对个人项目和中小型应用来说，PGVector 的优势是工程成本低：document、chunk、metadata、tenant_id 可以和业务数据放在同一个 PostgreSQL 里，也方便接入 Spring AI 的 VectorStore 抽象，不需要一开始就维护单独的向量数据库集群。

但 Vector DB 不是 RAG 的全部。

很多人做 RAG 的第一个误区就是：

我接了向量数据库，所以我有 RAG 了。

不一定。

如果你没有好的 chunk，没有 metadata filter，没有 citation，没有拒答，没有 eval，那它只是一个“向量检索 + Prompt”demo。

用一个生活类比：

假设你有一个图书馆。

• Document 是一本本书。
• Chunk 是书里被裁出来的一小段内容。
• Embedding 是给每一段内容贴一个“语义坐标”。
• Vector DB 是图书馆的“语义索引系统”。
• 用户问题也会被贴一个“语义坐标”。
• 系统就看：用户问题这个坐标，离哪些内容的坐标最近。
• 最近的几段，就是候选证据。

所以 Vector DB 不是“知识库本身”的全部，它只是知识库里的一个检索组件。

一句话总结：

Vector DB 负责把 chunk 的语义坐标存起来，并在用户提问时找出最相似的候选证据；但证据是否完整、是否有权限、是否支持答案，还要靠 chunk 质量、metadata filter、reranker、citation、faithfulness 和 eval。

5. topK：到底取多少条证据

topK 是一个很小但很重要的参数。

它表示：检索时取前 K 条结果。

比如：

topK = 5

意思是：系统会取最相似的 5 个 chunk 放进上下文。

很多人会以为 topK 越大越好，因为取更多证据似乎更安全。

但真实情况不是这样。

• topK 太小，可能漏掉关键证据。
• topK 太大，可能引入噪声，污染上下文。
• 无关 chunk 进入 prompt 后，模型可能把错误信息也编进答案。
• 上下文越长，成本越高，延迟越大。

比如用户问住宿报销标准，topK 太小可能只拿到金额，漏掉“必须提供发票”；topK 太大又可能把交通费、餐饮补贴、加班餐费一起塞进上下文，污染回答。

如果 topK 太小，比如 topK = 1：

只取第 1 条 chunk

好处是上下文很干净，成本低，速度快。

但风险是：如果第 1 条不完整，系统就漏掉关键条件。

比如第 1 条只说：

一线城市住宿最高 600 元/晚。

但第 4 条才说：

报销时必须提供住宿发票，且需经过部门负责人审批。

如果 topK = 1，模型只能看到第一条，就可能回答不完整。

这叫：漏召回。

如果 topK 太大，比如 topK = 20：

取前 20 条 chunk

看起来证据更多，好像更安全。

但问题是，前 20 条里很可能混进很多“看起来相关但其实没用”的内容：

差旅住宿标准
交通费规则
餐饮补贴
出差审批
酒店协议
员工福利
加班餐费
团队建设报销……

这些内容一起塞进 Prompt，模型可能被干扰。

用户问的是“住宿最高报销多少”，但上下文里混入“餐饮补贴”“交通费”“加班餐费”，模型就可能把不相关规则也带进答案。

这叫：噪声污染上下文。

所以 topK 的本质是一个平衡：

topK 太小：容易漏掉关键证据
topK 太大：容易引入无关噪声

所以 topK 不是越大越好，而是要和 chunk 质量、检索质量、reranker、上下文窗口一起调。

比如：

• naive RAG 可能直接取 top5。
• Hybrid Search 可能先召回 top50。
• Reranker 再从 top50 里选 top5。
• 最终只把最可靠的 3–5 个 chunk 放进 prompt。

topK也分两种，第一种是：召回阶段的 topK。

它的目标是“不要漏”。

比如：

Vector Search 先召回 top50
BM25 也召回 top50

这时候 topK 可以大一点，因为只是候选池，还没直接塞进 Prompt。

第二种是：最终上下文的 topK。

它的目标是“少噪声”。

比如 reranker 从 top50 里重新排序，最后只选：

final topK = 3 或 5

这几条才会真正进入 Prompt，让 LLM 生成答案。

所以完整流程是：

用户问题
  ↓
向量检索 / BM25 检索
  ↓
先多召回一些候选证据，比如 top50
  ↓
Reranker 重排
  ↓
最终只选 top3~top5
  ↓
放进 Prompt
  ↓
LLM 生成答案

一句话总结：

topK 决定有多少候选证据进入下一步，太少会漏召回，太多会污染上下文。

6. Similarity Threshold：相似度阈值

Similarity Threshold，就是相似度低于某个分数的结果不要。

比如：

similarityThreshold = 0.75

意思是：相似度低于 0.75 的 chunk 不进入上下文。

它的作用是减少无关内容进入 prompt。

但这个参数也不能迷信。

• 阈值太高，可能把有用证据过滤掉。
• 阈值太低，可能放进很多噪声。
• 不同 embedding 模型、不同业务问题、不同 query 长度都会影响分数分布，所以 threshold 不能照抄，需要靠 eval 调。

Similarity Threshold 可以理解成：检索结果的最低及格线。

Similarity Threshold 的本质是一个平衡：

阈值太高：结果更干净，但可能漏掉有用证据
阈值太低：结果更多，但可能引入噪声

它和 topK 的区别也要分清。

topK 控制的是：

最多取几条

Similarity Threshold 控制的是：

低于多少分不要

比如：

topK = 5
similarityThreshold = 0.75

意思不是“无论如何取 5 条”，而是：

先按相似度排序最多取前 5 条但低于 0.75 的不要

假设结果是：

0.91：chunk A
0.86：chunk B
0.79：chunk C
0.68：chunk D
0.62：chunk E

虽然 topK = 5，但因为 threshold = 0.75，最后只保留：

chunk A
chunk B
chunk C

所以可以这样理解：

topK 是数量上限
threshold 是质量底线

一句话总结：

topK 决定“最多拿几条”，Similarity Threshold 决定“太不像的不要”。

7. BM25 / Lexical Search：关键词检索不是过时技术

BM25 或 lexical search，可以简单理解成关键词检索。

它不像 embedding 那样理解语义，而是更关注词面命中。

比如：

SKU-A1937
HTTP 401
退款政策第 7 条
tenant_id
RetrievalAugmentationAdvisor
PGVector

这些查询不需要先“理解语义”，而是要精确命中。

如果用户问“SKU-A1937 是否支持德国仓发货”，系统就应该优先找到包含 SKU-A1937 的文档或表格。

如果用户问“Spring AI 的 RetrievalAugmentationAdvisor 怎么用”，系统就应该优先命中官方文档里包含这个类名的片段。

所以 BM25 / lexical search 没有过时。

它解决的是向量检索不擅长的问题：

• 编号。
• 错误码。
• 字段名。
• 类名。
• 方法名。
• 产品型号。
• 政策条款。
• 固定术语。
• 短 query。
• 中英混合表达。

这也是为什么很多生产 RAG 系统会做 Hybrid Search，而不是只做向量检索。

BM25 / Lexical Search 这段的核心意思是：

不要以为 RAG 只靠 Embedding。Embedding 擅长找“意思相近”的内容，但 BM25 擅长找“字面上必须命中”的内容。

你不需要记 BM25 的公式，只要理解它比普通关键词匹配更会衡量词的重要性和匹配强度，特别适合编号、类名、字段名、错误码、政策条款这类必须精确命中的内容。

你只要理解：BM25 更重视词面命中，尤其适合查精确词。

如果用 Embedding，系统可能觉得这些内容相关：

HTTP 403 权限错误
HTTP 401 未认证
HTTP 500 服务异常

但如果用户明确问 HTTP 401，那系统就必须优先命中包含 HTTP 401 的片段。

这就是 BM25 的价值。

它不是过时技术，而是在 RAG 里补 Embedding 的短板。

更具体一点，Embedding 容易在这些场景失手：

比如用户问“退款政策第 7 条怎么说？”，Embedding 可能召回退款政策总则、退款流程、售后说明，但不一定精确命中“第 7 条”。BM25 会更关注“第 7 条”这个词面。

一句话总结：

Embedding 找语义相似，BM25 / lexical search 找精确命中。

8. Hybrid Search：两路一起找证据

Hybrid Search，就是混合检索。

最常见的是：

Vector Search + BM25 / Lexical Search

也就是：

向量检索负责找语义相关。
关键词检索负责找精确命中。
两路结果合并后再排序。

它解决的是一个非常现实的问题：

单一路检索器容易漏证据。

比如：

用户问：

我的简历里有没有能支撑 RAG evaluation 的证据？

简历里可能没写 “RAG evaluation”，但写了：

设计了 evidence guard、citation check、unsupported claim detection，用于限制 AI 生成中的无证据扩写。

这个时候向量检索有价值。

但如果用户问：

我的项目有没有写 PGVector？

那就应该精确命中 PGVector 这个词，关键词检索更重要。

所以 Hybrid Search 不是炫技，而是降低漏召回。

基本流程是：

用户问题
  ↓
Vector Recall：找语义相关
  +
Lexical Recall：找精确命中
  ↓
融合排序/去重/重排
  ↓
候选证据

Vector Search 像一个懂意思的人：
“你虽然没说 evidence guard，但我知道它和 RAG evaluation 有关。”

BM25 像一个认真查关键词的人：
“你问 PGVector，我就必须找到 PGVector 这个词。”

一句话总结：

Hybrid Search = 语义检索负责“意思相近”，关键词检索负责“原词命中”。两路一起召回，可以降低关键证据被漏掉的概率。

9. RRF：把多路检索结果合并

Hybrid Search 会产生两张排行榜，RRF 的作用就是把这两张排行榜合并成一张总榜。

做完 Hybrid Search 后，会出现一个新问题：

• Vector Search 有一组结果。
• BM25 / Lexical Search 有一组结果。
• 这两组结果怎么合并？

最直接的想法是把分数加起来。

但这通常不严谨。

因为向量相似度和 BM25 分数不是同一种分数。它们来自不同算法，尺度不同，不能简单相加。

这时候可以用 RRF。

RRF，全称 Reciprocal Rank Fusion，中文可以理解成“倒数排名融合”。

它不直接比较原始分数，而是看排名。

公式大概是：

RRF score = Σ 1 / (k + rank)

不用被公式吓到，它的意思很简单：

• 如果一个 chunk 在向量检索里排得很靠前，在关键词检索里也排得靠前，那它更可能重要。
• 如果一个 chunk 只在某一路检索里非常靠前，它也有机会被保留下来。
• RRF 关心的是“排第几”，不是原始分数是多少。

举个简单例子：

Chunk A：向量检索第 1，关键词检索第 5
Chunk B：向量检索第 20，关键词检索第 1
Chunk C：向量检索第 3，关键词检索没有召回

RRF 会综合这些排名，而不是强行比较“向量相似度 0.82”和“BM25 分数 12.7”谁更大。

RRF 最适合解决的问题是：

Vector Search 和 BM25 的分数不能直接加，但它们的排名可以融合。

你可以把它放回整个 RAG 流程：

用户问题
  ↓
Vector Search 返回一组排行榜
  ↓
BM25 返回一组排行榜
  ↓
RRF 根据“排名”融合两组结果
  ↓
得到候选证据总榜
  ↓
Reranker 再精排
  ↓
选出 Final Evidence

这里还要分清 RRF 和 Reranker：

RRF：用排名规则快速融合多路检索结果
Reranker：用模型进一步判断 query 和 chunk 是否真的相关

一句话总结：

RRF 是把 Vector Search 和 BM25 的结果合并成一张更合理的候选证据排行榜。

10. Reranker：最终复核候选证据

Retriever 是粗筛，Reranker 是复核。

• 检索器先找出一批候选 chunk，比如 top50 或 top100。
• Reranker 再判断这些 chunk 和当前问题到底有多相关。
• 最后只选最适合回答问题的几个 chunk 进入 prompt。

为什么要这样做？

因为召回阶段追求“不要漏”。
重排阶段追求“更准确”。

• 如果一开始就只取 top5，很可能漏掉关键证据。
• 如果把 top50 全部塞进 prompt，又会污染上下文。
• 所以常见做法是：先多召回，再精排。

典型流程：

用户问题
  ↓
Vector Search / BM25 先召回 top50
  ↓
RRF 把多路结果融合成候选列表
  ↓
Reranker 逐条判断：这个 chunk 到底能不能回答这个问题？
  ↓
重新排序
  ↓
只选 top3 / top5 放进 Prompt
  ↓
LLM 基于最终证据生成答案

Reranker 和 Embedding 的区别非常重要。

Embedding 的做法一般是：

把 query 单独变成向量
把 chunk 单独变成向量
然后计算两个向量距离

它更像是快速粗筛：

这个问题和这个 chunk 的语义大概像不像？

Reranker 的做法通常是：

把 query 和 chunk 放在一起让模型直接判断它们的相关性

它问的是更细的问题：

这个 chunk 是否真的能回答当前 query？
这个 chunk 是强相关、弱相关，还是只是沾边？
这个 chunk 是否包含用户问题需要的关键条件？

举个例子。

用户问：

退款政策第 7 条怎么说？

前面检索可能召回：

A：退款政策总则
B：退款申请流程
C：第 7 条：定制商品非质量问题不支持七天无理由退货
D：售后审核要求
E：退货运费说明

Embedding 可能觉得 A、B、D、E 都和“退款政策”相关。

但 Reranker 会更容易判断：

用户问的是“第 7 条”
C 直接包含“第 7 条”
所以 C 应该排第一

这就是 reranker 的价值：它不是只看大概相关，而是更细地判断“能不能支撑这个问题”。

一句话总结：

Reranker 是 final context 之前的最后一道证据复核：它决定哪些候选 chunk 真正有资格进入大模型上下文。

11. Metadata Filter：只在正确范围里检索

很多 RAG demo 会直接在所有文档里检索，但生产系统不能这样做。

Metadata，就是文档或 chunk 附带的信息。

比如：

{
  "tenantId": "merchant_001",
  "sourceType": "refund_policy",
  "language": "zh",
  "version": "v3",
  "status": "active",
  "updatedAt": "2026-06-01"
}

Metadata Filter 就是按这些字段过滤。

为什么它重要？

因为不是所有文档都应该被检索。

用户问退款政策时，系统要先判断：

• 是不是当前商家的政策？
• 是不是当前语言？
• 是不是当前版本？
• 是不是 active 状态？
• 是不是当前用户有权限访问？
• 是不是对应业务线？

如果不做 metadata filter，系统可能召回：

• 旧版本政策。
• 其他租户文档。
• 测试文档。
• 英文文档。
• 无权限文档。
• 已废弃规则。

这不是回答不准的问题，而是系统边界问题。

RAG 检索时，不能在所有文档里乱找。它必须先限定范围，只在“当前用户应该看的、当前业务应该用的、当前版本有效的文档”里检索。

Chunk 本身是正文，比如：

定制商品非质量问题不支持七天无理由退货。

Metadata 是这段 chunk 身上的标签，比如：

{
  "tenantId": "merchant_001",
  "sourceType": "refund_policy",
  "language": "zh",
  "version": "v3",
  "status": "active",
  "updatedAt": "2026-06-01"
}

这些标签不是给大模型看的废信息，而是给系统检索时做过滤用的。

也就是说，系统不是直接问：

哪些 chunk 和用户问题最相似？

而应该先问：

在当前商家 merchant_001 的 active 中文退款政策里，哪些 chunk 和用户问题最相似？

这就是 Metadata Filter。

一句话总结：

Metadata Filter 决定“哪些资料有资格参与检索”；Embedding / BM25 决定“这些资料里哪些最相关”。

12. Tenant Filter：多租户系统的硬隔离

Tenant Filter 可以理解成 Metadata Filter 里最不能出错的一种。

Metadata Filter 是范围控制，Tenant Filter 是权限隔离。

如果一个系统服务多个公司、多个商家、多个团队，每个组织就是一个 tenant。

比如：

• 商家 A 有自己的退款政策。
• 商家 B 有自己的退款政策。
• 商家 C 有自己的商品知识库。

用户来自商家 A，那么系统只能检索商家 A 的文档。

不能靠 prompt 说：

请你只回答当前商家的内容。

这不够。

真正的 tenant filter 应该在数据库查询、检索条件、权限系统里生效。

比如：

WHERE tenant_id = 'merchant_001'

如果 tenant filter 漏了，后果不是“回答不够好”，而是“数据越权”。

一句话总结：

Tenant Filter 不是 Prompt 约束，而是数据访问控制。

13. Citation：答案来自哪里，但不代表答案一定被支持

Citation，就是引用来源。

它告诉用户：

• 这个答案来自哪篇文档。
• 来自哪个 chunk。
• 来自哪一页。
• 来自哪个章节。
• 原文片段是什么。

比如：

{
  "answer": "一线城市住宿最高可报销 600 元/晚。",
  "citation": {
    "document": "2026 差旅报销制度",
    "section": "住宿标准",
    "page": 3,
    "quote": "一线城市 600 元/晚，其他城市 400 元/晚"
  }
}

Citation 的价值是让答案可追溯。

但要注意：

有引用不等于可信。

引用只能说明系统给了来源。
它不能自动说明答案真的被来源支持。

比如原文说：

定制商品非质量问题不支持七天无理由退货。

模型回答：

所有跨境商品都不支持退货。

这个答案可能也带了引用，但它扩大了原文范围，所以不可信。

一句话总结：

Citation 是可信的起点，不是终点。

14. Faithfulness / Groundedness：答案是否忠于证据

Faithfulness 和 Groundedness 经常一起出现。

你可以先不用纠结二者的边界，它们都在问一个核心问题：

模型说的话，证据里到底有没有？

如果证据说：

候选人参与了 Spring Boot 后端开发，并接入了 Redis 限流。

模型改写成：

主导设计高并发 AI Agent 平台，使用 Redis、RocketMQ、PGVector 构建生产级 RAG 系统。

这就是典型不 faithful。

因为模型加了很多证据里没有的东西。

这在 AI 简历、项目包装、求职材料里尤其危险。它不是简单“润色”，而是把没有证据的经历写成了事实。

所以 Faithfulness / Groundedness 不是看答案是否流畅，也不是看答案是否有引用，而是看：

答案里的每个关键 claim 是否被证据支持。

你可以把它拆成 claim 检查：

Claim 1：主导设计高并发 AI Agent 平台证据支持？没有。
Claim 2：使用 Redis证据支持？有。
Claim 3：使用 RocketMQ证据支持？没有。
Claim 4：使用 PGVector证据支持？没有。
Claim 5：构建生产级 RAG 系统证据支持？没有。

所以 Faithfulness 检查的不是“这句话写得好不好”，而是：

每一个关键 claim 是否有证据支撑？
有没有夸大？
有没有扩展范围？
有没有补充证据里没有的技术？
有没有把参与说成主导？
有没有把 demo 说成生产级？

这也是为什么 Faithfulness 不能只看语言是否流畅，也不能只看答案是否带了引用。

因为模型最容易出现的问题就是：它可以把错误答案说得非常自然。

一个不 faithful 的答案可能具备这些表象：

语言很流畅结构很清楚看起来专业甚至带了引用

但只要答案里的关键结论没有被证据支持，它仍然不可信。

一句话总结：

Citation 问的是“答案挂了哪个来源”，Faithfulness 问的是“这个来源到底支不支持答案”。有引用只是把答案和资料连起来；Faithfulness 才是在检查这条连接是不是真的成立。

15. Abstention：证据不足时，系统应该拒答

Abstention，就是拒答。

但这里的拒答不是“模型不会”，而是“系统知道不该答”。

什么时候应该拒答？

• 没有检索到证据。
• 证据之间互相冲突。
• 用户没有权限访问相关资料。
• 问题超出知识库范围。
• 答案需要实时订单状态，但当前只有静态政策文档。
• 检索结果只支持一部分结论，不支持完整回答。

比如用户问：

这个订单还能退吗？

如果系统只检索到通用退款政策，但没有订单状态、商品类型、物流节点、是否定制商品这些信息，就不应该直接回答“可以退”或“不可以退”。

更好的回答是：

当前知识库只包含通用退款政策，无法确认该订单是否符合退款条件。需要查询订单状态、商品类型和物流信息后才能判断。

这就是可信 RAG 的边界感。

一句话总结：

可信 RAG 不应该永远给答案。它必须能识别证据不足、权限不足、信息缺失和结论无法成立的情况。

16. RAG Eval：证明系统真的变好了

RAG Eval，就是评测 RAG 系统是不是真的有效，要用一组可重复的测试问题，检查系统到底坏在哪个环节。

很多 demo 的评测方式是：

• 问几个问题。
• 看起来回答不错。
• 觉得系统可以上线。

这很危险。

因为 RAG 的错误可能发生在多个环节：

• 文档解析错。
• chunk 切坏了。
• embedding 召回错。
• BM25 没命中。
• RRF 排序不好。
• reranker 选错证据。
• final context 被噪声污染。
• 模型没有忠实使用证据。
• 引用不支持答案。
• 该拒答时没有拒答。

所以 eval 的价值不是打一个漂亮分数，而是定位系统坏在哪里。

常见评测维度包括：

• retrieval recall：该召回的证据有没有召回。
• context precision：召回的上下文有多少真的有用。
• faithfulness：答案是否忠于证据。
• answer relevance：答案是否回应问题。
• citation accuracy：引用是否真的支持答案。
• abstention accuracy：该拒答时有没有拒答。

RAG 不是一个单点功能，而是一条链路：

文档解析
  ↓
chunk 切分
  ↓
embedding / BM25 召回
  ↓
RRF / Reranker 排序
  ↓
final context 选择
  ↓
LLM 生成回答
  ↓
citation 引用
  ↓
faithfulness 检查
  ↓
abstention 拒答

这条链路任何一环出问题，最后答案都可能错。

一句话总结：

没有 Eval，你只能凭感觉调 RAG。
有了 Eval，你才能知道问题到底出在检索、排序、上下文选择、生成、引用，还是拒答边界。
到这一步，RAG 才开始从 demo 接近工程系统。

17. 把这些词放回一条证据链里

现在再回头看这些术语，它们其实不是孤立概念。

• Document 是原料。
• Chunk 是证据单元。
• Embedding 是语义坐标。
• Vector DB 是语义检索工具。
• BM25 / Lexical Search 是精确词面检索工具。
• Hybrid Search 是双路召回。
• RRF 是多路排序融合。
• Reranker 是候选证据复核。
• Metadata Filter 是检索范围控制。
• Tenant Filter 是数据隔离。
• Citation 是来源标记。
• Faithfulness / Groundedness 是答案是否忠于证据。
• Abstention 是边界控制。
• RAG Eval 是质量证明。

它们共同组成的是：

问题
  ↓
检索正确范围内的证据
  ↓
选择最能支撑答案的证据
  ↓
基于证据生成回答
  ↓
标记引用来源
  ↓
检查答案是否忠于证据
  ↓
证据不足时拒答
  ↓
用 eval 证明系统是否变好

这就是我理解的可信 RAG。

• 它不是“向量库 + Prompt”。
• 也不是“把 PDF 丢进去让 AI 聊天”。
• 它是一套把问题、证据、生成、引用、拒答、评测串起来的工程系统。

18. 下一篇：从 0 到 1 搭一个个人技术资产知识库

下一篇，我会开始写保姆级实战：

从 0 到 1 搭一个个人技术资产知识库：Spring Boot + Spring AI + PGVector 保姆级教程。

这次不做泛泛的“PDF 聊天机器人”，而是用自己的真实技术资产作为知识库来源：

• 个人博客文章

• GitHub README

• 项目文档

• 技术复盘

• Markdown 笔记

目标也不是一上来做完整企业级平台，而是搭出一个最小可信 RAG 骨架：

• 文档从哪里来

• chunk 怎么切

• embedding 怎么入库

• PGVector 怎么检索

• metadata 怎么过滤

• 回答怎么带 citation

• 证据不足怎么拒答

• retrieval trace 怎么记录

• 最小 eval case 怎么设计

它还不是完整企业级知识库，但会保留企业级系统最关键的边界意识：来源、权限、版本、证据、引用、拒答和评测。

最后回到一句话：

RAG 的目标不是让 AI 更会说，而是让 AI 的回答更值得被信任。

参考资料

• Patrick Lewis et al. Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS 2020 / arXiv:2005.11401.
  https://arxiv.org/abs/2005.11401

• Spring AI Reference Documentation. Retrieval Augmented Generation.
  https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

• pgvector. Open-source vector similarity search for Postgres. GitHub.
  https://github.com/pgvector/pgvector

• Gordon V. Cormack, Charles L. A. Clarke, Stefan Büttcher. Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods. SIGIR 2009.
  https://research.google/pubs/reciprocal-rank-fusion-outperforms-condorcet-and-individual-rank-learning-methods/

• Shahul Es et al. RAGAS: Automated Evaluation of Retrieval Augmented Generation. EACL 2024 / arXiv:2309.15217.
  https://arxiv.org/abs/2309.15217

我是 Ryan，一个专注于可信 AI 应用工程的开发者，技术博客：yanxai.com。相比让 AI 生成更多内容，我更关心它的回答是否有证据，过程是否可追溯，结果是否经得起验证。

它语气很稳定，结构很完整，甚至还会列出步骤、注意事项和看起来很专业的判断。

可真正危险的地方在于：你不知道它到底是根据什么说出这句话的。

很多人第一次听到 RAG，会把它理解成“给 AI 接一个知识库”。

这个理解不算错，但太浅。

知识库只是资料放在哪里。RAG 真正要解决的是另一个问题：

当 AI 给你一个答案时，你能不能判断这个答案到底靠不靠谱？

比如你在电商平台问客服：

我这个商品还能退吗？

一个普通大模型可能会根据常见售后规则回答：

一般情况下，签收 7 天内可以申请退货。

这句话听起来很正常，甚至很像客服话术。

但问题是：它真的知道你的订单状态吗？知道你买的是不是定制商品吗？知道商品有没有拆封吗？知道是否超过签收时间吗？知道当前店铺的退货政策是不是最新版吗？

如果这些信息都没有，它直接回答“可以退”，其实就是在没有证据的情况下装作知道。

RAG 真正要解决的，不只是让 AI 多读几份文档，而是让它在回答前先去找证据：订单状态是什么，商品类型是什么，售后政策怎么写，是否存在例外条款。只有这些证据足够支持结论，它才能回答；如果证据不够，它就应该说“不确定，还需要查询订单状态”。

所以我现在更愿意这样理解 RAG：

RAG 不是让模型知道更多，而是让模型的回答有证据、有边界、可追溯、可评测。

什么是 RAG：让模型先找证据，再回答问题

RAG = Retrieval-Augmented Generation，检索增强生成。

这个概念来自 2020 年 Lewis 等人的论文《Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks》。这篇论文提出的核心思路，是把预训练模型的参数化记忆和外部检索得到的非参数化记忆结合起来，让模型在知识密集型任务中利用外部资料生成回答。但在今天的 AI 应用工程里，如果我们要把 RAG 用到客服、企业知识库、求职材料、内部系统，就不能只停留在“检索 + 生成”，还要继续解决引用、权限、拒答、评测和可追溯问题。

用更简单的话说：

RAG 不是让大模型只靠“脑子里记住的参数”回答，而是在回答前先去外部知识源检索相关资料，再把检索到的内容作为上下文交给模型生成答案。

基本流程可以理解成：

用户问题
  ↓
检索相关文档 / 数据 / 片段
  ↓
把检索结果作为上下文
  ↓
交给大模型生成回答
  ↓
返回答案 + 来源

更准确地说，RAG 不等于知识库。

知识库是数据。
Embedding 是表示方式。
Vector DB 是存储和检索工具。
RAG 是把检索结果接入生成过程的架构。
可信 RAG 还要有 citation、faithfulness、abstention、eval。

所以：

有知识库 ≠ 有 RAG。
有向量库 ≠ 有可信 RAG。

很多“AI 知识库聊天机器人”只是做到了文档检索 + 模型回答，但还没有真正解决证据是否可靠、引用是否准确、回答是否忠实、证据不足时是否拒答这些问题。

RAG 的真正价值：不是知识更多，而是答案更可追溯

大模型的参数里确实存了大量知识，但这种知识有几个天然问题。

第一，它不一定新。

模型训练完成后，外部世界继续变化。政策会改，商品库存会变，订单状态会更新，公司内部文档会迭代。如果只依赖模型参数，知识更新成本很高。

第二，它不一定属于你的业务。

企业内部 SOP、用户简历、订单物流、客户服务记录、项目 README、私有代码文档，都不可能稳定存在于通用模型参数里。

第三，它很难给出 provenance，也就是可追溯的依据。

模型生成一个结论时，你很难知道它到底依据了哪份文档、哪段材料、哪条规则。

RAG 的核心价值就在这里：它把生成过程从纯参数记忆拉回到外部证据上。LangChain 文档把 retrieval 描述为在查询时获取相关外部知识，以增强 LLM 对上下文特定信息的回答能力；Spring AI 的 RAG 文档里，QuestionAnswerAdvisor 会查询向量数据库，把相关文档追加到用户文本中，为模型生成提供上下文。

这也是为什么 RAG 很适合作为 AI 应用工程里的长期专题。它不是一个单点技术，而是一条系统链路：

文档进入系统之前，要清洗、切块、加元数据。
问题进入系统之后，要改写、检索、混合召回、重排。
答案生成之前，要选择证据、控制上下文、约束输出。
答案生成之后，要检查引用、忠实度、拒答、可追溯性。
系统上线之后，还要持续评测、监控、回放、修复。

如果只写“Embedding 是什么”“Vector DB 怎么用”，你只是在写 RAG 的零件。

真正值得写的是：这些零件如何共同决定一个 AI 应用是否可信。

第一个误区：只要接了知识库，就算有 RAG 了

很多人做 RAG 的第一个动作，是接一个向量数据库。

这当然重要。

有了 embedding 之后，需要一个地方存这些向量，并支持按相似度检索。这就是 Vector DB。

比如 pgvector 是 PostgreSQL 的开源向量相似搜索扩展，它可以让你在 PostgreSQL 里存向量，并支持精确或近似最近邻搜索、余弦距离、内积、L2 距离等能力。

如果你用 Java / Spring Boot / PostgreSQL 技术栈，PGVector 很适合作为入门和工程落地选择。因为你可以把 document、chunk、embedding、metadata、tenant_id 放在同一个 PostgreSQL 体系里，而不是一开始就维护单独的向量数据库集群。

但 Vector DB 不是 RAG 的全部。

Vector DB 解决的是：

这些 chunk 里，哪些和用户问题的向量最接近？

它不解决：

这个 chunk 是否来自最新版文档？
这个 chunk 是否属于当前用户或当前租户？
这个 chunk 是否完整包含限制条件？
这个 chunk 是否真的能支撑答案？
模型是否忠实使用了这个 chunk？
证据不足时系统是否拒答？

所以不要把“接入向量库”误认为“完成了 RAG”。

如果你没有好的 chunk，没有 metadata filter，没有 citation，没有拒答，没有 eval，那它只是一个“向量检索 + Prompt”demo。

更准确地说：

Vector DB 负责存向量和查相似，但它不能自动保证答案可信。

第二个误区：只靠向量检索，就能找到正确证据

很多 RAG 教程会从 Embedding 开始。

Embedding 的确重要。OpenAI 文档把 embedding 定义为向量表示，并指出可以通过向量之间的距离衡量文本之间的相关程度。

简单说，Embedding 可以把一段文本变成一串数字，让系统按语义相似度检索内容。

比如用户问：

出差住酒店最多能报销多少钱？

文档里写的是：

差旅住宿报销标准：一线城市 600 元/晚，其他城市 400 元/晚。

这两句话词不完全一样，但意思相关。Embedding 能把它们映射到相近的向量空间里，让系统知道它们语义接近。

但真实系统里，只靠 Embedding 很容易出问题。

比如用户问：

退款政策第 7 条怎么说？

向量检索可能召回“售后政策总则”“退货流程说明”“跨境商品说明”，但漏掉真正包含“第 7 条”的精确条款。

用户问：

SKU-A1937 是否支持德国仓发货？

这里的关键不是语义相似，而是精确编号、地区、仓库、商品属性。BM25 / lexical search 这类词面检索反而更稳。

OpenSearch 文档把 BM25 描述为一种基于关键词的 lexical search 算法，会考虑词频、逆文档频率等因素来计算文档相关性。

所以，RAG 检索的第一条原则是：

不要迷信单一检索器。

Embedding 解决的是语义相似，不等于事实正确。
BM25 / lexical search 擅长词面匹配、编号、术语、错误码、固定表达。
Hybrid Search 把稀疏检索和稠密检索结合起来，降低漏召回风险。
RRF 可以把多个检索器的排序结果融合起来。
Reranker 再对候选结果做更精细的 query-document 匹配。

Qdrant 的 hybrid queries 文档也把 dense、sparse、多向量检索，以及 RRF、DBSF 等融合方式放在同一个检索框架下讨论。

一个最简 RAG demo 可能是：

query → embedding → vector db → answer

但一个更接近生产的 RAG，应该更接近：

query
  ↓
query rewrite
  ↓
BM25 / lexical recall + vector recall
  ↓
RRF fusion
  ↓
rerank
  ↓
evidence selection
  ↓
answer generation
  ↓
citation / faithfulness check

这条链路看起来复杂，但它解决的是同一个问题：

先尽可能不要漏掉证据，再尽可能把真正相关的证据排到前面。

第三个误区：把文档切碎，就等于做好了知识库

Chunking 是 RAG 里最容易被低估的环节。

很多人会直接用固定长度，比如 500 tokens 一个 chunk，50 tokens overlap。这个做法能跑，但不一定能用。

因为真实文档不是纯文本流。真实文档有标题、层级、表格、FAQ、代码块、步骤、异常说明、法律条款、商品参数、订单字段、版本记录。

如果你把一个退款规则从条件和例外之间切开，模型可能只看到“支持退款”，看不到“定制商品除外”。

如果你把项目架构图的说明和模块列表切散，模型可能知道用了 Redis，却不知道 Redis 是用于限流、缓存还是会话。

如果你把简历项目经历按固定长度切开，模型可能看到“AI 应用开发”，却看不到对应技术栈和结果证据。

所以 Chunking 的本质不是“把长文变短”，而是：

把文档切成适合被检索、被引用、被验证的证据单元。

好的 chunk 至少要满足几个条件：

它要足够小，小到能被精确召回。
它要足够完整，完整到能支撑一个回答 claim。
它要保留结构，例如标题、章节、来源、页码、版本、所属租户。
它要可追溯，生成答案时能反查原文位置。
它要可评测，能判断某个 query 是否应该召回它。

这也是为什么“RAG 做不好”很多时候不是模型问题，而是知识工程问题。

第四个误区：检索到相似内容，就等于找到了证据

相似，不等于正确。

这个问题在 RAG 里非常常见。

比如用户问：

这个订单还能退吗？

系统召回了一段“通用退款政策”，这当然相关。但它是否足够回答这个订单能不能退？

不一定。

因为这个问题还需要订单状态、商品类型、签收时间、是否定制商品、是否有质量问题、是否拆封等信息。

也就是说，检索到“相似内容”只说明系统找到了一些可能相关的文本，不代表它已经找到了足够支撑结论的证据。

这里至少有三层过滤。

第一层是 topK：最多取多少条候选 chunk。topK 太小，可能漏掉关键证据；topK 太大，可能把噪声塞进上下文。

第二层是 similarity threshold：相似度低于某个分数的结果不要。阈值太高，可能过滤掉有用证据；阈值太低，又会放进太多无关内容。

第三层是 metadata filter / tenant filter：只在正确范围里检索。

Metadata，就是文档或 chunk 附带的信息。

比如：

{
  "tenantId": "merchant_001",
  "sourceType": "refund_policy",
  "language": "zh",
  "version": "v3",
  "status": "active",
  "updatedAt": "2026-06-01"
}

用户问退款政策时，系统要先判断：

是不是当前商家的政策？
是不是当前语言？
是不是当前版本？
是不是 active 状态？
是不是当前用户有权限访问？
是不是对应业务线？

如果不做 metadata filter，系统可能召回旧版本政策、其他租户文档、测试文档、英文文档、无权限文档、已废弃规则。

这不是回答不准的问题，而是系统边界问题。

尤其在多租户系统里，tenant filter 不是 Prompt 约束，而是数据访问控制。你不能靠一句“请只回答当前商家的内容”来防止越权检索。真正的过滤应该发生在数据库查询、检索条件和权限系统里。

一句话总结：

RAG 不是在全库里找最像的内容，而是在正确范围里找能支撑答案的证据。

第五个误区：有引用，就说明答案可信

普通大模型胡说，用户至少还会怀疑：

它是不是编的？

但 RAG 系统一旦答错，问题反而更隐蔽。因为它通常会带着文档名、引用片段、相似度分数和来源链接，看起来像是经过检索验证的结果。

真正危险的不是 AI 没有依据，而是它拿着不完整、错误或不相关的依据，生成了一个看起来很确定的答案。

很多 RAG 系统会在回答后面附上引用来源，看起来很专业。但 citation 不等于 faithfulness。

引用只能说明：系统给了一个来源。
它不能自动说明：答案中的每一句都被这个来源支持。

举个例子。

原文说：

跨境定制商品非质量问题不支持七天无理由退货。

AI 回答：

所有跨境商品都不支持退货。

这个回答可能带着引用，但它把“定制商品”“非质量问题”“七天无理由”这些限定条件丢掉了。它不是没引用，而是引用不忠实。

所以 RAG 的可信问题至少要拆成三层：

Context relevance：检索到的上下文是否真的相关。
Groundedness / Faithfulness：回答是否被上下文支持。
Answer relevance：回答是否真正回应用户问题。

TruLens 的 RAG Triad 使用 context relevance、groundedness、answer relevance 三个维度来检查 RAG 应用；DeepEval 的 faithfulness 指标也强调要判断生成结果是否与 retrieval context 中的内容事实一致。

这三件事不能混在一起。

检索相关不代表生成忠实。
生成忠实不代表回答完整。
回答完整也不代表应该回答。

有些问题在证据不足时就应该拒答。

一句话总结：

Citation 问的是答案来自哪里，Faithfulness 问的是来源到底支不支持答案。

第六个误区：AI 应该永远给出答案

真正成熟的 RAG 系统必须有 abstention，也就是拒答能力。

当证据不足时，它应该说“不确定”。
当检索结果冲突时，它应该暴露冲突。
当问题超出知识库范围时，它应该说明边界。
当用户试图诱导它越权访问其他租户数据时，它应该拒绝。
当答案需要实时数据库状态，而当前只检索到静态文档时，它应该提示需要调用订单系统或业务 API。

很多 AI 应用失败，不是因为它答不出来，而是因为它在不该回答时回答了。

对客服系统来说，这可能是错误承诺。
对求职材料来说，这可能是简历造假。
对医疗、法律、金融来说，这可能是高风险误导。
对企业内部知识库来说，这可能是权限越界。

所以 RAG 不应该只追求“回答率”，还要追求“正确拒答率”。

一个可信 RAG 的目标不是让模型每次都有话说，而是让系统在证据不足、权限不足、上下文冲突或需要实时数据时，能主动暴露边界。

一句话总结：

可信 RAG 不应该永远回答，它应该知道什么时候不该回答。

第七个误区：问几个问题感觉不错，就可以上线

RAG demo 最危险的地方是：你问三五个问题，感觉它回答不错，就以为系统可用了。

但 RAG 的质量不能靠肉眼感受。你至少要把评测拆成两部分。

第一部分评测检索：

该召回的证据有没有召回？
相关 chunk 是否排在前面？
无关 chunk 是否污染上下文？
BM25、Embedding、Hybrid、RRF、Reranker 哪个环节带来了提升？
metadata filter 和 tenant filter 是否真的生效？

第二部分评测生成：

答案是否只基于证据？
引用是否准确？
是否遗漏关键限定条件？
是否在证据不足时拒答？
是否把多个来源中的冲突信息混成一个确定结论？
是否能把“不确定”说清楚，而不是装作知道？

RAGAS 论文把 RAG 评测拆成多个维度，包括检索系统能否识别相关且聚焦的上下文、LLM 是否忠实利用这些上下文、生成质量如何等；LangSmith 的 RAG 评测教程也会评估 RAG 应用；OpenAI 的评测最佳实践也强调，evals 应该是面向具体应用的测试，用来衡量 LLM 应用表现。

这就是 RAG Eval 的价值。它不是为了做漂亮分数，而是为了定位系统坏在哪里。

如果 retrieval recall 低，说明证据根本没进上下文。
如果 context precision 低，说明召回内容太脏。
如果 faithfulness 低，说明模型拿到了证据但没有忠实使用。
如果 answer relevance 低，说明回答没有解决用户问题。
如果 citation accuracy 低，说明引用链不可信。
如果 abstention accuracy 低，说明系统不知道什么时候不该回答。

从这个角度看：

RAG Eval 不是上线后的评分表，而应该是 RAG 开发的导航系统。

没有 eval 的 RAG，只能叫 demo；有 eval 的 RAG，才开始接近工程系统。

重新定义 RAG：从“能回答”到“可验证”

以前我会说：

RAG = Retrieval-Augmented Generation，检索增强生成。

现在我更愿意说：

RAG 是一种把外部证据引入生成过程，并通过检索、重排、引用、拒答和评测机制约束模型输出的 AI 应用架构。

这个定义更长，但更接近真实工程。

因为真实业务要的不是“AI 能说”，而是：

它引用的是不是正确来源？
它有没有越权拿到别人的数据？
它有没有遗漏关键例外条款？
它能不能承认证据不足？
它的回答能不能被回放、检查和复盘？
当知识库更新后，它能不能及时反映变化？

如果这些问题解决不了，RAG 就只是一个看起来更专业的聊天机器人。

如果这些问题解决了，RAG 才真正成为可信 AI 应用工程的底座。

接下来这个专题，我会按工程链路继续拆开写：

Embedding / Vector DB：语义表示和向量召回。
BM25 / Hybrid Search / RRF：降低只靠向量检索带来的漏召回。
Reranker：对候选证据重新排序。
Chunking：决定证据单元是否完整。
Metadata Filter / Tenant Filter：控制版本、权限和租户边界。
Citation / Faithfulness / Groundedness：判断答案是否真的被证据支持。
Abstention / RAG Eval：决定系统什么时候该拒答，以及如何证明它变好了。

但我不会把它们写成孤立概念。

每一个技术点都要回答同一个问题：

它能不能帮助 RAG 从“能回答”走向“可验证”？

我的目标不是证明“AI 能回答文档问题”，而是回答一个更硬的问题：

这个答案为什么值得被信任？

最后，用一张图把这篇文章的核心逻辑收束一下：

参考资料

[1] Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks, NeurIPS 2020.
[2] LangChain Docs, Retrieval / RAG.
[3] Spring AI Reference, Retrieval Augmented Generation.
[4] OpenAI Docs, Vector embeddings.
[5] pgvector GitHub, Open-source vector similarity search for Postgres.
[6] OpenSearch Docs, Keyword search / BM25.
[7] Qdrant Docs, Hybrid Queries.
[8] Cormack et al., Reciprocal Rank Fusion, SIGIR 2009.
[9] RAGAS, Automated Evaluation of Retrieval Augmented Generation.
[10] TruLens Docs, RAG Triad.
[11] DeepEval Docs, Faithfulness Metric.
[12] LangSmith Docs, Evaluate a RAG application.
[13] OpenAI Docs, Evaluation best practices.

结语

下一篇，我会用类比讲透 RAG 的核心术语：Embedding、Chunk、Vector DB、BM25、Reranker 到底是什么。

我是 Ryan，一个专注于可信 AI 应用工程的开发者，个人技术博客：yanxai.com，研究如何让 AI 生成从“看起来对”走向“有证据、可追溯、可验证”。

1.能做出产品，但不等于完全具备工程能力

小白能用AI做产品，但开发的时候他是否知道什么场景用什么技术栈，架构如何设计，如何用工作树和Git提交或回滚代码，如果一个系统真的上线，并发怎么处理？数据库事务边界在哪里？缓存失效怎么办？权限绕过怎么防？日志怎么设计？成本异常怎么定位？AI 改了鉴权逻辑但测试没覆盖怎么办？线上出错谁回滚？这些问题不是“生成代码”本身，而是工程责任。

未来最危险的岗位不是“程序员”，而是“只会接明确需求、写普通 CRUD、不会判断架构、不懂测试、不懂安全、不懂业务的人”。因为这类工作最适合被AI批量生成。

AI 让代码产出变快，必然让review、测试、安全和治理变成瓶颈。

AI 时代的高阶程序员价值链变成：定义问题 → 拆解任务 → 设计架构 → 给 AI 上下文 → 审查 diff → 写测试和评测 → 控制权限和安全边界 → 监控线上行为 → 复盘成本和质量 → 长期维护系统。

AI 时代越往后，“能生成代码”越不稀缺，“能证明代码可信”越稀缺。

我所做的项目：

PatchBrake 不是为了再做一个代码扫描器，而是盯住 AI-generated diff 里的工程风险：删测试、放大权限、弱化鉴权、修改规则文件、引入危险脚本。

Token Studio ROI 不是为了记 token，而是把 AI 编程从“感觉效率很高”变成可复盘的工作证据：不同项目、不同模型、不同任务到底消耗了多少，产出了什么，值不值得继续。

OmniMerchant 不是客服 demo，而是在跨境电商场景里处理 RAG、tool calling、多租户、流式响应、fallback、成本和权限边界。

简喵不是泛泛的简历评分器，而是证据约束型岗位竞争力诊断：JD里哪些能匹配，哪些有证据，哪些不能硬补，改写后能不能经得起面试追问。

这些项目表面不同，底层是同一个问题： AI 生成之后，如何留下证据、边界和责任？ 我把它叫作可信交付。 它至少包含五件事：

• 生成结果有证据。
• 系统行为有边界。
• 质量风险可验证。
• 线上问题可追溯。
• 长期演进可复盘。

在AI应用工程中：

RAG系统不是接一个向量库。 它要评估retrieval recall、context precision、faithfulness、answer relevance。

Agent系统不是让模型调用工具。 它要设计tool permission、approval flow、audit log、failure fallback。

AI observability不是看一眼 token 数。 它要记录模型、延迟、成本、trace、tool call、错误、用户反馈和版本变化。 这些才是AI应用开发的真实壁垒。

所以AI时代真正的出路是：能把AI生成的软件纳入一套可验证、可审计、可交付的工程流程，建立一套自己的AI工作流。AI时代不缺代码生成，缺的是可信交付。

2.小白也能做产品，程序员的出路在哪里？

（1）做 AI 应用工程，而不是“套壳应用”。

用上Codex和Claude Code确实可以做一个“看起来不错”的工具，但多数人做不出稳定的 AI 应用。因为 AI 应用真正难的地方不是页面，也不是调 API，而是这些问题：

• 模型输出不稳定怎么办？
• 结构化 JSON 解析失败怎么办？
• RAG 检索到错误证据怎么办？
• 用户输入包含 prompt injection 怎么办？
• tool calling 调错工具怎么办？
• 多租户数据串了怎么办？
• token 成本失控怎么办？
• 流式响应中途失败怎么办？
• 模型降级后质量怎么保证？

AI 生成内容如何可追溯、可解释、可复盘？ 这些才是AI应用开发的真实壁垒。

普通小白能上线 demo，但很难建立一套 evidence、eval、observability、guardrail、fallback、audit trail。 出路不是“我也会用 Claude Code 做项目”，而应该是：“我能把 Claude Code、Codex 生成的软件纳入一套可验证、可审计、可交付的工程流程。”

• 不只是我的项目能跑，而是我能解释核心链路和关键实现。
• 不只是我的技术栈很丰富，而是我选择了有取舍、有边界、有替代方案。
• 不只是我用了 Claude Code / Codex，而是我能审查、约束、验证 AI 产物。
• 不只是我做了几个单元测试，而是我的测试覆盖了异常、边界、回归和 CI。
• 不只是我实现了登录鉴权，而是我能处理越权、注入、敏感信息和多租户隔离。
• 不只是我本地运行成功，而是我有日志、错误码、重试、回滚和监控。
• 不只是我的README很漂亮，而是我有 changelog、benchmark、failure cases 和复盘。
• 不只是我会背项目介绍，而是我能现场改需求、debug、解释取舍。

（2）掌握领域，而不是只掌握工具。

AI 最擅长的是通用模式。越通用，越容易被生成；越需要领域判断，越不容易被替代。

比如跨境电商客服系统，不只是写一个聊天框。它涉及订单、物流、售后、退换货政策、多语言、商家规则、平台合规、用户情绪、风控和成本。求职材料生成也不是“润色简历”，而是 JD → 证据 → 改写 → 风险控制 → 面试可追问。AI 可以帮你写代码，但它不知道你的产品到底要对谁负责。

所以程序员的长期出路之一，是变成“某个领域里的工程师”，而不是“只会某个技术栈的人”。Java 后端、Spring AI、RAG、Agent 都只是武器；真正值钱的是你能把它们用于一个真实问题，并且知道哪些地方不能乱生成。

AI 可以生成代码、README、测试样例、架构图，但很难伪造你对系统的真实理解、取舍过程、排障能力和长期维护能力。

3.AI 时代，项目本身会贬值，工程证据会升值

（1）设计取舍证据。

面试官问：

• “为什么用这个架构？”
• “为什么不用更简单的方案？”
• “这个模块的边界在哪里？”
• “如果用户量扩大10倍，哪个地方先出问题？”
• “这个设计最失败的地方是什么？”

真正做过工程的人，回答里会有取舍：性能、复杂度、开发时间、可维护性、安全、成本、团队能力。只靠 AI 堆出来的人，通常只能复述架构名词，比如“用了 Redis、用了 MQ、用了 RAG、用了微服务”，但说不出为什么。

（2）debug 证据。

AI 能生成新代码，但真实工程能力很大一部分体现在出问题后能不能定位。

面试官会问：

• “线上接口变慢，你怎么排查？”
• “Redis 缓存命中率下降，你看什么指标？”
• “数据库偶发死锁，你怎么复现？”
• “用户说 AI 回答错了，你怎么判断是 prompt 问题、检索问题、模型问题还是数据问题？”
• “流式响应中途断了，前后端分别怎么处理？”

这类问题很难靠背诵解决。因为它考的是排查路径：日志、traceId、metrics、SQL explain、异常栈、请求链路、复现条件、最小化变量、回滚策略。

所以项目里要有日志、错误码、traceId、监控截图、故障复盘。哪怕是个人项目，也可以写一份“线上事故排查文档”。

（3）测试和验证证据。

未来 AI 生成代码越多，测试越重要。面试官会越来越看重你有没有能力验证 AI 产物。

他会问：

• “你怎么证明这个功能是对的？”
• “边界条件测了哪些？”
• “单测、集成测试、端到端测试分别覆盖什么？”
• “AI 生成代码你怎么 review？”
• “你怎么防止修改 A 功能时破坏 B 功能？”

小白做项目通常是“能跑就行”。工程师要回答的是“为什么我相信它长期能跑”。

项目需要的东西：

单元测试、集成测试、异常测试、边界测试、benchmark、CI、测试覆盖范围说明、失败用例说明。

除此之外还应该有 AI eval：比如 RAG 回答是否引用了正确证据、简历改写是否夸大事实、客服 Agent 是否越权调用工具、AI 生成 diff 是否删除测试或放大权限。

（4）代码审查证据。

面试官不一定只让你写代码，可能直接给你一段AI生成代码，让你 review。

他会看你能不能发现： 并发问题。 权限绕过。 事务边界错误。 N+1 查询。 空指针和异常吞噬。 SQL 注入。 缓存穿透/击穿/雪崩。 日志泄露敏感信息。 测试只测 happy path。 代码过度抽象。

AI 最容易写出“看起来完整，但边界很脆”的代码。会工程的人，能看出这些脆点。

我会把 PatchBrake 这类项目继续往“AI diff 风险审查”方向做。它不只是一个工具，而是能力定位的证据：你不是只会用 AI 写代码，你还能审计 AI 写出来的代码。

（5）系统边界和安全证据。

AI 写代码后，最容易被忽视的是边界。 面试官问：

• “用户输入恶意内容怎么办？”
• “多租户数据怎么隔离？”
• “普通用户能不能越权访问别人的资源？”
• “tool calling 有没有权限控制？”
• “模型输出不合法怎么办？”
• “敏感信息会不会进日志？”
• “AI 生成内容错了，系统怎么兜底？”

（6）长期维护证据。

很多 AI 项目是一次性 demo。面试官会越来越警惕这种“短期堆出来”的项目。 更关注：

• 有没有版本演进记录。
• 有没有 changelog。
• 有没有 issue/roadmap。
• 有没有重构记录。
• 有没有测试随功能增长而增长。
• 有没有配置说明。
• 有没有部署说明。
• 有没有已知问题。
• 有没有从 v1 到 v2 的设计变化。

真正的工程能力不是“做出来”，而是“维护得住”。一个项目连续迭代 3 个月，比 5 个一次性AI demo更有说服力。

（7）表达和复盘证据。

AI 能帮你写项目介绍，但很难替你讲清楚真实经历。面试官会通过追问判断你是不是 owner。 面试官问：

• “这个项目里你最难的一个 bug 是什么？”
• “你做过最错误的设计是什么？”
• “哪一部分后来推翻了？”
• “你最不满意的地方是什么？”
• “如果再做一遍，你会怎么改？”
• “这个项目真正服务了谁？”
• “有没有用户反馈？”

这些问题非常关键。因为没真正做过的人，通常只会讲正面包装，不会讲失败、返工、妥协和权衡。

所以文章里可以考虑主动写失败点。不是自曝缺点，而是证明你真的经历过工程过程。

这些都是我后面做内容和产品会坚持的方向。

4.关于我个人对AI时代的思考

我不会把自己的产品和文章做成“手把手复制一个爆款项目”的流量模板。

更不会承诺“学完某个项目就能找到工作”。

这种话听起来很有吸引力，但很多时候只是另一种自我安慰。

AI 应用开发不是背几个框架名词，也不是照着教程部署一个项目。

真正重要的是：你有没有在一个具体问题里做过判断，踩过坑，推翻过方案，修过错误，理解过边界，并且能把这些过程沉淀成自己的工程认知。

我更在意长期品牌，而不是短期热点。

热点可以带来流量，但很难带来信任。

真正能让别人相信你的，不是你追上了多少话题，而是你是否长期围绕一个方向持续输出，是否能在项目、代码、文章和复盘里看见稳定的判断力。

我现在做的事情很简单：

记录自己从 0 到 1 学习 AI 应用开发的过程。

记录项目踩坑、架构取舍、错误判断、重构过程和复盘。

记录我如何从一个学生慢慢建立起对 AI 应用工程、可信交付、证据链、评测、安全和长期产品判断的理解。

这不是速成路线。

也不是求职捷径。

它更像是一条长期训练路径。

我希望我的内容不是让人看完以后产生虚假的兴奋，而是让真正愿意思考的人看到：一个项目为什么这样做，哪里容易错，哪些地方不能骗自己，什么才算真正有工程价值。

我相信，一个人需要在某个领域建立足够稳定的判断，才不会被网上的情绪、热点和速成叙事随意带偏。

我也相信，真正有判断力的人，最终会通过长期内容找到彼此。

不是因为标题足够刺激。

而是因为文字里有真实经历，有取舍，有问题意识，有持续迭代的痕迹。

我不会只做“看起来很热”的内容。

我会继续做有我自己工程路径、成长痕迹和判断密度的深度内容。

短期流量会过去。

长期品牌会留下。

我是 Ryan，一个专注于可信 AI 应用工程的开发者，个人技术博客：yanxai.com，研究如何让 AI 生成从“看起来对”走向“有证据、可追溯、可验证”。

Windows 用户可以直接用第 3 节里的固定版本命令下载并启动。完整 PowerShell 命令放在“下载和使用全流程”，可以整段复制运行。

这张图回答的问题：本期 AI 编程 token 花在哪些模型、来源和趋势上，哪些消耗最值得先复盘。

我以前只想知道自己 AI 编程花了多少 token。

后来发现，这个数字本身没什么用。

真正的问题是：这些 token 到底换来了什么？

如果一天用了几千万 token，但我不知道它们是花在功能开发、调试修复、上下文整理，还是无效试错上，那 token 总数只是一个越来越大的数字。它既不能告诉我哪个项目值得继续投，也不能告诉我下周应该少用重模型，还是该先压缩上下文。

所以我做了 Token Studio。它不是一个普通 token meter，而是一个本地 AI 编程 ROI 复盘系统：先可信地采集本机结构化 token 元数据，再把 token 连接到项目、任务、产出证据、模型策略和行动报告。

1. 普通 token 看板少回答了一个关键问题

市面上的 token 工具大多能回答“用了多少”。这当然重要，但对高频 AI 编程用户来说还不够。

我真正想回答的是：

• 这些 token 是花在探索、实现、验证、发布，还是重复上下文里？
• 哪些项目消耗最高，最后有没有 PR、commit、文档、部署或可展示产出？
• 重模型是不是被用在了测试验证、上下文整理这种低 ROI 场景？
• 哪些 session 只是在烧 token，却没有形成任何可复盘证据？
• 下周我应该继续用同样的模型策略，还是先把低价值任务切到轻量模型？

这就是 Token Studio 的核心差异：

统计工具告诉你用了多少；Token Studio 追问这些 token 换来了什么。

这个定位也影响了整个设计。它不追求做云端 SaaS，不追求团队排行榜，也不为了覆盖数量去伪造 token。它先做一件事：把本地真实 token 变成可信工作证据。

2. Token Studio 的闭环

Token Studio 当前围绕一条闭环设计：

真实本地 token
  -> 可信覆盖
  -> 自动证据
  -> ROI 复盘
  -> 模型策略
  -> 行动报告

这条链路里，每一步都要回答一个实际问题。

2.1 真实本地采集：先确认数据是真的

Token Studio 会读取本机仍然存在、且带有可靠 token 字段的结构化日志。核心可信来源是 Claude Code 和 Codex CLI。

它采集的是结构化使用元数据，例如 source、model、session、timestamp、input/output/cache/reasoning tokens。它不保存 prompt、response、transcript、diff、文件内容或完整本机路径。

这个边界很关键：如果连采集数据本身都不可信，后面的 ROI 判断就只是漂亮图表。

2.2 Coverage Trust：解释为什么某些工具没有数据

很多工具会在本机留下目录或日志，但检测到目录不等于拿到了可靠 token。

所以 Token Studio 把来源拆成几类：原生可信采集、ccusage 可导入、实验采集、仅检测到、无可靠 token 字段 / 不支持。

这不是为了保守而保守，而是为了避免一种很危险的假象：覆盖名单很好看，但实际 token 是估出来的。

我宁愿页面告诉用户“这个来源现在没有可靠 token 字段”，也不希望它用文本长度估算 token，然后生成看似完整但不能复盘的数据。

2.3 Evidence Flywheel：把消耗数字变成工作证据

采到 token 之后，还不够。

真正有价值的是这些 token 对应了什么工作：项目、任务类型、工作目的、阶段、产出状态、产出价值、产出链接，以及这些字段是人工确认、自动推断，还是待确认草稿。

比如一个 session 可以从“某模型消耗了 200 万 token”，变成：

项目：Token Studio ROI
任务：功能开发
阶段：实现
产出状态：已完成
产出：commit / PR / 文档
价值：中 / 高
证据来源：自动高置信或人工确认

只有走到这一步，/review 才能继续判断：哪些 token 有产出，哪些高成本 session 还没归因，哪些模型策略值得调整。

2.4 ROI Advisor：不给玄学建议，只给可解释规则

Token Studio 不调用 LLM 生成建议。原因很简单：这个工具本身就是为了帮我少花 token，不应该为了分析 token 再消耗一轮 token。

它用本地规则做判断：

• 高成本未归因 session：先补证据。
• 测试验证、探索、上下文整理使用重模型：建议切到轻量模型。
• 低价值或废弃任务使用高成本模型：建议先轻量试错。
• 高 input / low output：建议压缩上下文。
• cache 复用低且 input 高：建议沉淀项目上下文。
• 未定价模型：不参与美元节省判断。

Savings Simulator 也不声称真实节省金额，只做官方价换算下的策略模拟。

2.5 Desktop Pulse：给实时状态一个轻量入口

浏览器里的 Dashboard、Trust、Review 是完整复盘入口。Desktop Pulse 只是伴侣。

它解决的是另一个问题：我不想一直开着浏览器 tab，但想随时知道今天 token 有没有失控。

所以 Pulse 重点展示近 24 小时 token、官方价换算、请求数、输入/输出/cache、模型消耗、来源分布、预算 guardrail 和当前建议。它只读本地 API / SQLite 聚合数据，不上传，也不重新实现采集。

3. 下载和使用全流程

这里给 Windows 用户两份命令：PowerShell 用 PowerShell 版，CMD 用 CMD 版。不要混用。

PowerShell 版：

# 前提：已安装 nvm-windows
nvm install 24.17.0
nvm use 24.17.0

node.exe -v
npm.cmd -v

New-Item -ItemType Directory -Force D:\TokenStudio | Out-Null
Set-Location D:\TokenStudio

$pkg = 'token-studio' + '@' + '6.0.8'
npx.cmd -y $pkg

CMD 版：

REM 前提：已安装 nvm-windows
nvm install 24.17.0
nvm use 24.17.0

node -v
npm -v

mkdir D:\TokenStudio
cd /d D:\TokenStudio

set "pkg=token-studio"
set "at=@"
set "ver=6.0.8"
npx -y %pkg%%at%%ver%

如果已经有 Node 24，也可以只运行最后三行。它做的是完整本地真实模式，不是 demo：

1. npx 从 npm 下载并运行 token-studio
2. Token Studio 做只读 coverage，检查本机是否有 Claude Code / Codex CLI 结构化 token 日志
3. 通过可信 gate 后，把 event 级 token 元数据写入本地 SQLite
4. 启动 127.0.0.1 上的本地 Web/API 服务
5. 自动打开浏览器 Dashboard
6. 后台定时刷新可信 Claude/Codex token 元数据
7. 在 Trust 页面确认数据可信度
8. 在 Review 页面生成证据队列、模型策略和行动报告
9. 如需实时观察，再打开 Desktop Pulse 或 /live

第一次使用可以按这个顺序看：

几个常用命令也可以分开用：

$pkg = 'token-studio' + '@' + '6.0.8'

# 真实模式：下载、采集可信 token、启动本地看板
npx.cmd -y $pkg

# 只做只读检查，不写 SQLite
npx.cmd -y $pkg --dry-run-only --no-open

# 只打开已有本地数据库，不重新采集
npx.cmd -y $pkg --no-collect

# 查看本地实时状态摘要
npx.cmd -y $pkg statusline --format=text

# 如果你只想看产品界面，可以用合成数据
npx.cmd -y $pkg demo

注意：第 3 节里的真实模式命令会读取本机结构化 token 元数据，但不会读取 prompt、response、transcript、diff 或完整本机路径。demo 是合成数据，只用于看界面，不代表真实采集成功。

3.1 Dashboard：先看成本、模型和趋势

这张图回答的问题：当前周期 token、官方价换算、模型消耗和趋势是否异常。

Dashboard 的首屏不应该先解释产品理念，而应该先让用户看到真实数据：总 token、输入、输出、缓存、推理 token、官方价换算、模型分布和趋势。

因为用户打开看板的第一反应通常不是“这个工具有什么功能”，而是：

我的 token 到底花在哪里？哪个模型最贵？今天有没有异常？

3.2 Trust：确认数据是否能用于复盘

这张图回答的问题：当前数据是 demo、旧聚合库，还是可信 event 级真实采集；哪些来源能用于 ROI 判断。

Trust 页面是我认为最容易被低估的一页。

它负责回答：当前是 demo、空库、旧聚合库，还是真实 event 级数据？Claude / Codex / Cursor 等来源分别是什么状态？daily、session、event 之间能不能对齐？哪些来源只是 detected-only，不能当成真实覆盖？

如果这一步不清楚，用户就会把“看起来有数据”误当成“可以做决策”。

3.3 Review：把 token 变成 ROI 证据

这张图回答的问题：哪些 token 已经有产出证据，哪些 session 仍缺项目、任务、阶段、价值或产出链接。

Review 不是普通报表，而是复盘页。

它关心：哪些 token 产出了东西，哪些高成本 session 仍缺证据，哪些模型策略可以调整，哪些建议应该进入下周行动清单。

我还加了三个专业可复制输出包：

• 复盘证据包
• 技术博客草稿
• 简历 / 面试项目描述

这些内容不是静态 bullet，而是基于当前结构化数据生成的 Markdown，方便直接复制到周报、博客或简历项目说明里。缺人工确认或产出链接时，它会明确写限制，不会编造成果。

3.4 Desktop Pulse：桌面实时伴侣

这张图回答的问题：过去 24 小时 token、成本、请求、缓存复用和模型消耗是否处在可控范围内。

Desktop Pulse 是 v6 的桌面端补强。它不是主产品，也不替代浏览器复盘页。

它更像一个本地实时仪表盘：当我正在高频使用 Claude Code 或 Codex 时，它能快速告诉我今天 token 是否失控、重模型是否用得过多、是否有预算风险、是否该停下来处理 open actions。

3.5 动图体验

这张动图回答的问题：从 Dashboard 到 Trust、Review、Live，完整复盘流是怎么走的。

动图地址：https://yanxai.com/images/token-studio-roi/token-studio-walkthrough.gif

4. 和竞品相比，Token Studio 的差异在哪里

我查过同类项目后，结论比较明确：竞品很强，但强项不一样。

ccusage 的优势是多来源覆盖和 JSON 报表。它能统一读取 Claude Code、Codex、OpenCode、Amp、Goose、Kimi、Qwen、Copilot CLI、Gemini CLI 等本地数据源，并提供 daily、weekly、monthly、session 等视图。

CodeBurn 的优势是 TUI 和快速成本观测，强调按 task、model、project、provider 拆分 AI spend。

TokenTracker 的优势是覆盖工具数量、桌面组件、菜单栏和去重能力。

tokscale 的优势是 CLI/TUI、贡献图、leaderboard 和更强的可视化传播感。

Token Studio 没有选择去硬拼这些方向。它的差异是：

所以它不是 ccusage 的替代品，也不是 CodeBurn 的 TUI 复制品。更准确地说，它是本地复盘层：把可信 token 进一步变成工作证据、策略判断和下周行动。

5. 架构设计

Token Studio 的架构很简单，但每一层都保持边界清楚。

Claude Code / Codex CLI 本地日志
        |
        v
结构化 collector
        |
        v
SQLite: token_events / session_usage / daily_usage
        |
        v
Coverage Trust / Reconciliation
        |
        v
Evidence Flywheel
        |
        v
Dashboard / Trust / Review / Live / Desktop Pulse

5.1 为什么用 SQLite

因为这是个人本地工具。

SQLite 不需要部署数据库，容易备份，适合单用户本地场景，也方便把数据文件明确排除在 npm 包和 Git 仓库之外。

5.2 为什么不用云端

AI 编程数据很敏感。即便不保存正文，session、模型、时间、项目名、产出链接也可能透露工作节奏和项目方向。

所以默认选择是：数据留在本地，复盘也在本地完成。

5.3 为什么不估算所有工具

覆盖数量本身不是目标。可信覆盖才是目标。

如果某个工具没有稳定 token 字段，Token Studio 不会用文本长度估算 token，也不会把 detected-only 写成采集成功。它会建议用 ccusage bridge 导入结构化 JSON，或者明确标记“当前无可靠 token 字段”。

6. 隐私和安全边界

这部分很重要，但不需要在每一段重复。

Token Studio 的边界集中在几条：

• 不保存 prompt、response、transcript、diff、文件内容或完整本机路径。
• Web API 默认绑定本机地址。
• 普通写接口要求 local Origin + JSON。
• /api/ingest 默认关闭，只有设置 INGEST_TOKEN 后才启用 Bearer token 写入。
• Desktop Pulse 只读本地聚合数据，不上传，不做远程控制面板。
• 官方价换算不是供应商账单，只用于复盘和策略模拟。

这也是为什么我没有把它做成云端 SaaS。对这个产品来说，隐私不是附加卖点，而是系统边界。

7. 我怎么判断这个项目是否有价值

我不想把 Token Studio 写成“又一个全能平台”。

它解决的是一个很具体的问题：

对高频 AI 编程用户来说，token 已经变成持续投入，但缺少一个本地、可信、可复盘的投入产出系统。

如果只看 token 数，意义有限。
如果 token 能连接到项目、任务、阶段、产出和模型策略，它才开始变成可管理的工作资产。

这个判断也符合软件工程研究里常见的问题-方法-证据-评价结构：先定义真实问题，再做可运行系统，然后用真实数据、限制条件和验收门来评价，而不是只做一个漂亮页面。

Token Studio 不会自动证明“ROI 提升了 37%”。它更保守，也更可信：

• 哪些数据可信。
• 哪些只能看趋势。
• 哪些不能下结论。
• 哪些证据缺口最值得补。
• 哪些模型策略值得下周试。

8. 当前局限

这个项目有明确边界。

第一，它不能恢复所有历史。它只能覆盖本机仍然保留、且日志里有可靠 token 字段的数据。

第二，它不是供应商账单。官方价换算适合做趋势和策略复盘，不适合做财务对账。

第三，它不会读取正文，所以不会自动理解任务质量。产出价值仍然需要人工确认或结构化证据支撑。

第四，它不会为了覆盖面伪造 token。没有可靠 token 字段，就不会写成“已采集成功”。

第五，桌面 Pulse 只是伴侣。真正的复盘仍然在浏览器 Review 和 Trust 页面里完成。

9. 后续是否继续做

v6 之后，我不打算继续无限追竞品功能。

后续只维护几类事情：

• 上游日志格式变化
• 官方价格变化
• 真实 bug
• 隐私和安全问题
• release / npm / 桌面打包问题

明确不做：云同步、账号体系、多用户、leaderboard、大型 TUI、伪造 collector、文本长度估算 token。

因为再往后加功能，收益已经不如把当前闭环打磨稳定。

10. 排错命令速查

完整下载和启动命令见第 3 节。下面是几个排错或进阶命令。

如果你只想确认它能不能看到你的本机日志，可以先运行：

$pkg = 'token-studio' + '@' + '6.0.8'
npx.cmd -y $pkg --dry-run-only --no-open

如果你已经有本地 SQLite，只想打开看板，不想重新扫描日志：

$pkg = 'token-studio' + '@' + '6.0.8'
npx.cmd -y $pkg --no-collect

如果你要看桌面端实时伴侣，当前推荐先从本地源码或 GitHub Release asset 体验；npm 主入口仍是 Web/CLI：

git clone https://github.com/RyanCoreAI/token-studio-roi.git
cd token-studio-roi
npm install
npm run desktop

项目地址：

• GitHub：https://github.com/RyanCoreAI/token-studio-roi
• npm registry：https://registry.npmjs.org/token-studio/latest
• Release：https://github.com/RyanCoreAI/token-studio-roi/releases/tag/v6.0.8
• 动图体验：https://yanxai.com/images/token-studio-roi/token-studio-walkthrough.gif

如果你想验证它是否真的能采到你本机的数据，最直接的方式还是在本机运行真实模式，而不是看 demo。

参考资料

• GitHub README 文档：About READMEs
• OpenAI Prompt Caching：Prompt caching
• OpenAI Reasoning models：Reasoning models
• Anthropic Prompt Caching：Prompt caching
• Anthropic Extended Thinking：Extended thinking
• ccusage：ccusage documentation
• CodeBurn：GitHub
• TokenTracker：GitHub
• tokscale：GitHub
• Mary Shaw, Writing Good Software Engineering Research Papers：PDF
• Design Science Research：PDF

现在很多人的 AI 编码流程大概是这样：先和 AI 讨论需求、拆实现方案，然后让 Codex、Claude Code、Cursor 或 Copilot 直接改本地代码。AI 改完后，如果项目能跑、页面看起来没问题，很多人就准备提交了。问题恰恰出在这里。

以前 review 代码，主要看逻辑对不对、命名清不清楚、有没有明显 bug。现在 AI 一次能改很多文件，而且改得很自然，很多风险不是“代码完全不能跑”，而是混在 diff 里，看起来没那么刺眼。

比如：代码能跑，但测试被删了；功能能过，但权限判断被弱化了；CI 还能跑，但 GitHub Actions 权限被放大了；配置文件看起来正常，但 secret 被写进了代码；甚至 AGENTS.md、CLAUDE.md、Cursor rules 这类文件被改了，后续 AI 的行为规则也跟着变了。

这些问题不一定马上炸，但很适合藏进一次普通提交里。所以我做了一个很小的工具：PatchBrake。

项目地址：https://github.com/RyanCoreAI/patchbrake

Demo 在线体验：https://raw.githubusercontent.com/RyanCoreAI/patchbrake/main/assets/demo.gif

1. PatchBrake 是什么？

PatchBrake 的定位很窄：AI 改完代码后，在提交前扫描这次 diff，看看有没有明显危险信号。

它不是 AI Reviewer，也不调用 LLM。它不会上传你的代码，不会接 SaaS，不会做 Web Dashboard，也不会替你判断业务逻辑。它做的事情更像是提交前的一脚刹车：在代码进入 commit 之前，先把一些高风险 diff 提醒出来。

我反而是故意把它做得很“笨”：只看 diff、只跑本地规则、只报能解释清楚的风险。 因为很多 AI 编码带来的问题，并不需要另一个 AI 来推理，它们本来就是很直接的信号。

比如 staged diff 里出现：

+ permissions: write-all

或者测试被删掉：

- test("rejects anonymous users", () => {
-   expect(() => requireAdmin(null)).toThrow("Unauthorized");
- });

再或者配置里出现：

+ OPENAI_API_KEY="sk-..."

这些不是复杂安全研究问题，而是提交前就应该被提醒的问题。

2. 怎么安装和使用？

先说前提：需要已经安装 Node.js 20+。

npx 本身是 npm 附带的工具。也就是说，如果你的电脑里没有 Node.js / npm，通常也就没有 npx，这时直接运行下面的命令会失败：

npx patchbrake scan --staged

所以第一次使用前，可以先在终端里检查一下：

node --version
npm --version
npx --version

如果这三个命令不存在，先安装 Node.js 20+。安装完成后，一般会自带 node、npm 和 npx。

环境没问题后，就不需要手动安装 PatchBrake 了，直接用 npx 运行：

npx patchbrake scan --staged

如果你想全局安装，也可以：

npm install -g patchbrake
patchbrake scan --staged

实际使用流程很简单。AI 改完代码后，先把准备检查的改动放进 staged 区域：

git add <changed-files>

如果你确认这次所有改动都属于同一个任务，也可以：

git add .

然后运行：

npx patchbrake scan --staged

这里的 staged 不是让你必须立刻提交。它只是告诉 PatchBrake：请检查我准备提交的这批改动。

如果你用的是 Codex 桌面版，也一样。PatchBrake 不关心代码是 Codex 桌面版改的、Claude Code 改的，还是 Cursor 改的。只要最后文件落在本地 Git 仓库里，就可以在项目目录打开终端，先 git add，再运行：

npx patchbrake scan --staged

如果扫出 error，就先修掉，再重新扫描；没有明显风险后，再正常提交。

3. 实际效果

我做了一个测试 diff：新增一个疑似 OpenAI API key、删除一个测试文件、把 GitHub Actions 权限改成 write-all。PatchBrake 扫出来是这样：

这个输出里可以看到三类风险：

• secret-leak：新增了疑似 API key，并且输出里已经脱敏
• deleted-tests：测试文件被删除
• workflow-permissions：GitHub Actions 权限被放大到 write-all

这就是我想要的效果：它不需要理解整个业务，只要能在提交前把这些明显风险拦一下，就已经很有价值。

4. 为什么只扫 diff？

因为 AI 编码真正容易出问题的地方，经常不是“整个仓库历史上有没有漏洞”，而是：这一次 AI 到底改了什么。

你让 AI 重构认证模块，它可能顺手删掉一个断言；你让 AI 改 release workflow，它可能把权限放大；你让 AI 补配置，它可能把 token 写进文件；你让 AI 整理项目规则，它可能改掉 agent 的约束。

这些变化如果进了主分支，后面再查就麻烦了。所以 PatchBrake 的位置很靠前：在 commit 前，多做一次本地 diff 质检。

5. 现在能检查什么？

目前 PatchBrake 主要覆盖这些风险：

• secret-leak：新增 API key、token、private key、.env 风险
• deleted-tests：测试文件、测试用例或断言被删除
• workflow-permissions：GitHub Actions 权限被放大
• migration-risk：危险 migration，比如 DROP、TRUNCATE、无 WHERE 的 DELETE
• prompt-config-drift：AGENTS.md、CLAUDE.md、.cursor/rules、prompt 配置变化
• beta 规则：auth guard 删除、危险 npm script、危险 shell 命令、依赖风险等

它不追求覆盖所有漏洞。我更在意的是，先抓住 AI 改代码时最容易被忽略、但提交前最值得停一下的那几类问题。

6. 它和 Gitleaks / Semgrep / CodeQL 是什么关系？

PatchBrake 不是用来替代这些工具的。

Gitleaks、TruffleHog 更专注 secret scanning；Semgrep、CodeQL 更接近静态分析和 SAST；zizmor 对 GitHub Actions 安全检查更深入。PatchBrake 的目标更小：把 AI 生成代码中常见的 diff 风险，用一个本地 CLI 在提交前统一拦一下。

它更像是 AI coding workflow 前面的一道轻量 safety gate，而不是完整安全平台。

7. 现在还很早

PatchBrake 还是早期版本。我最想要的反馈不是泛泛夸奖，而是这三类：

• false positive：它误报了什么？
• real bad diff：你真的遇到过哪些 AI 生成的危险 diff？
• rule request：你希望它多检查什么？

如果你经常用 Codex、Claude Code、Cursor 或 Copilot 改代码，可以拿自己的项目跑一次：

npx patchbrake scan --staged

如果它帮你拦下过一次低级但严重的 diff 风险，欢迎给个 star，或者直接提 issue，把你的 bad diff case 留下来。

Hexo 是一个基于 Node.js 的静态博客框架，一条命令就能把 Markdown 文章生成完整的 HTML 站点。Matery 是 Hexo 生态中最受欢迎的 Material Design 风格主题之一，自带响应式布局、暗黑模式、代码高亮、相册灯箱、搜索、评论等全套功能。

相比 WordPress 需要服务器和数据库，Hexo 的纯静态方案配合 GitHub Pages 零成本、免运维、加载快，非常适合个人博客。

本教程最终效果预览：https://ryancoreai.github.io

读完这篇教程，你将拥有一个完全免费、加载飞快、可深度定制的个人博客站点。

一、环境准备

1.1 安装 Node.js

• 官网：https://nodejs.org/
• 下载 LTS（长期支持版），一路 Next 默认安装即可
• 验证安装（打开终端或 Git Bash）：

node -v
npm -v

1.2 安装 Git

• 官网：https://git-scm.com/
• 默认安装，验证：

git --version

1.3 注册 GitHub 账号

• 注册地址：https://github.com/

二、创建 GitHub 仓库（关键：命名规则）

1. 登录 GitHub → 右上角 + → New repository
2. 仓库名必须严格写：你的用户名.github.io
   • 例：用户名是 peter-create-ai → 仓库名 peter-create-ai.github.io
3. 选 Public
4. 其他默认 → Create repository

这个仓库就是你的博客站点入口，GitHub 会自动把它识别为 GitHub Pages 站点。

三、安装 Hexo 并初始化博客

3.1 换国内镜像（下载提速）

npm config set registry https://registry.npmmirror.com

3.2 全局安装 Hexo

npm install -g hexo-cli

验证：

hexo -v

3.3 创建博客项目

hexo init blog
cd blog
npm install

完成后目录结构：

blog/
├── _config.yml        # 全局配置文件（核心）
├── source/
│   └── _posts/        # 文章 Markdown 放这里
├── themes/            # 主题目录
├── scaffolds/         # 文章模板
└── package.json       # 插件依赖

四、安装必备插件

在博客根目录 (blog/) 执行以下命令：

4.1 部署插件

npm install hexo-deployer-git --save

将生成的静态文件推送至 GitHub Pages。

4.2 搜索插件

npm install hexo-generator-search --save

生成 search.xml，供 Matery 主题的本地搜索功能使用。

4.3 中文链接转拼音

npm i hexo-permalink-pinyin --save

文章标题包含中文时，URL 自动转为拼音，避免链接中出现乱码。

4.4 RSS 订阅 + 站点地图（SEO 优化）

npm install hexo-generator-feed --save
npm install hexo-generator-sitemap --save

这两个插件为搜索引擎提供标准化的内容索引，利于收录。

4.5 静态资源压缩（加载速度优化）

npm install hexo-all-minifier --save

自动压缩 HTML、CSS、JS、图片，显著减少页面体积。

五、配置 _config.yml（核心步骤）

用编辑器打开 blog/_config.yml，按以下内容修改：

5.1 网站基本信息

title: 我的博客
subtitle: ''
description: '记录学习与思考'
keywords: blog, tech, AI
author: 你的名字
language: zh-CN
timezone: ''

# URL 配置
url: https://peter-create-ai.github.io
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:
  trailing_index: true
  trailing_html: true

5.2 文章与分页

new_post_name: :title.md
default_layout: post
titlecase: false
external_link:
  enable: true
  field: site
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
highlight:
  enable: false
prism_plugin:
  mode: 'preprocess'
  theme: 'tomorrow'
  line_number: false
index_generator:
  path: ''
  per_page: 12
  order_by: -date

关键点：

• post_asset_folder: false —— 图片统一管理更方便（见下文图片管理章节）
• highlight.enable: false —— 关闭 Hexo 默认高亮，改用主题自带的 Prism

5.3 搜索配置

search:
  path: search.xml
  field: post

5.4 中文链接转拼音配置

permalink_pinyin:
  enable: true
  separator: '-'

5.5 RSS 配置

feed:
  enable: true
  type:
    - atom
    - rss2
  path:
    - atom.xml
    - rss.xml
  limit: 20
  content: true
  content_limit: 200
  order_by: -date
  autodiscovery: true

5.6 Sitemap 配置

sitemap:
  path: sitemap.xml
  template:
  rel: false
  tags: true
  categories: true

5.7 部署配置（到你的 GitHub 仓库）

deploy:
  type: git
  repo: https://github.com/peter-create-ai/peter-create-ai.github.io.git
  branch: main

把所有 peter-create-ai 替换成你自己的 GitHub 用户名。

六、安装并启用 Matery 主题

6.1 下载主题

cd themes
git clone https://github.com/blinkfox/hexo-theme-matery.git
cd ..

6.2 启用主题

在 _config.yml 中修改：

theme: hexo-theme-matery

七、配置 Matery 主题（themes/matery/_config.yml）

Matery 主题有自己的配置文件 themes/matery/_config.yml，一定要改，否则首页显示的是默认信息。

7.1 首页个人信息

# 首页大图轮播
cover:
  enable: true
  length: 5           # 展示文章数
  showTitle: true     # 显示文章标题

# 头像 & 社交链接
profile:
  avatar: /medias/avatar.jpg
  name: Ryan Guo      # 你的名字
  socialLinks:
    - icon: fab fa-github
      url: https://github.com/你的用户名
    - icon: fas fa-envelope
      url: mailto:你的邮箱@gmail.com

7.2 导航菜单

menu:
  Home: /
  Archives: /archives
  Categories: /categories
  Tags: /tags
  About: /about
  Friends: /friends
  # 不需要的注释掉即可

7.3 文章与代码块配置

# 文章展示
postInfo:
  date: true
  update: true
  wordCount: true      # 需 hexo-wordcount 插件
  totalCount: true
  min2read: true
  readCount: true

# 代码块功能
code:
  break: false         # 是否强制折行
  lang: true           # 显示语言标签
  copy: true           # 一键复制按钮
  shrink: false        # 代码块折叠

7.4 评论系统（推荐 Giscus）

# Giscus —— 基于 GitHub Discussions，免费、无广告、开源
giscus:
  enable: true
  repo: 你的用户名/你的用户名.github.io
  repoID: 你的仓库ID
  category: Announcements
  categoryID: 你的分类ID

申请 Giscus 非常简单：访问 giscus.app，填入仓库名，自动生成配置。

7.5 搜索 & 打赏

# 本地搜索（需 hexo-generator-search 插件）
search:
  enable: true

# 打赏
reward:
  enable: false        # 需要时改为 true
  QRCode:
    - /medias/reward/wechat.png
    - /medias/reward/alipay.jpg

7.6 首页文章摘要

Matery 默认在首页显示文章全文，建议配合 <!-- more --> 使用摘要截断：

这是文章开头，会显示在首页卡片中。

<!-- more -->

从这里开始的内容，需要点击文章进去才能看到。

八、创建 Matery 必需的页面

Matery 主题依赖以下页面结构，逐个创建：

7.1 分类页

hexo new page categories

编辑 source/categories/index.md：

---
title: categories
type: "categories"
layout: "categories"
---

7.2 标签页

hexo new page tags

编辑 source/tags/index.md：

---
title: tags
type: "tags"
layout: "tags"
---

7.3 关于页

hexo new page about

编辑 source/about/index.md：

---
title: about
type: "about"
layout: "about"
---

内容自由发挥，放自我介绍、联系方式等。

7.4 友链页

hexo new page friends

编辑 source/friends/index.md：

---
title: friends
type: "friends"
layout: "friends"
---

九、文章图片管理方案（推荐）

在 source/ 下创建 images/ 文件夹，所有图片统一放在这里：

source/
├── images/
│   ├── avatar.png
│   └── blog01.jpg
└── _posts/
    └── 你的文章.md

文章内引用图片

格式固定：

![图片描述](/images/图片名.jpg)

示例：

![博客配图](/images/blog01.jpg)

建议分类管理

图片多了可以建子目录：

![生活照](/images/life/001.jpg)
![学习笔记](/images/study/note01.webp)

图片命名规则

• 使用英文 + 数字命名，如 blog01.jpg
• 避免中文和空格
• 建议压缩后再上传（推荐在线工具 TinyPNG 或 squoosh）

为什么不用 post_asset_folder？
每次新建文章自动创建同名文件夹会分散图片管理。统一放在 /images/ 下，路径固定、好找、可复用。

十、写第一篇完整文章

9.1 新建文章

hexo new "我的第一篇博客"

生成文件：source/_posts/我的第一篇博客.md

9.2 文章 Front-matter 完整写法

---
title: 我的第一篇博客
date: 2026-05-10 12:00:00
categories: 生活
tags:
  - 随笔
  - 日常
top: true       # 置顶，放在首页最上面
cover: true     # 首页轮播大图展示
toc: true       # 显示文章目录（默认就是 true）
---

9.3 Matery 文章专属配置项

9.4 Markdown 正文示例

以下是文章正文的常见写法，直接复制模板修改即可：

二级标题和段落

## 二级标题 后用空行分隔正文。正文直接写，无需额外标记。

列表

- 列表项 1
- 列表项 2
  - 嵌套子项

插入图片

![插图](/images/blog01.jpg)

文字样式

**加粗文字** 和 *斜体文字*

引用块

> 学而不思则罔，思而不学则殆

行内代码

用 `hexo server` 命令启动本地预览。

Java 代码块

```java
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
```

提示：展示 “如何在 Markdown 里写代码块” 时，外层用四个反引号 ```` `````` ` 包裹，内层的三个反引号就不会被解析为结束标记。

写好文章后，配合 Matery 的目录导航和代码高亮，阅读体验就是上面这样。

十一、本地预览

hexo server

浏览器打开 http://localhost:4000

边写边预览，修改保存后页面自动刷新。按 Ctrl+C 停止服务。

十二、发布上线

11.1 一键部署命令

hexo clean && hexo g && hexo d

命令含义：

• hexo clean —— 清空旧生成的静态文件
• hexo g (generate) —— 生成新的静态 HTML
• hexo d (deploy) —— 推送至 GitHub Pages

11.2 访问博客

https://你的用户名.github.io

部署后等待 1-2 分钟，GitHub Pages 会自动刷新。

部署成功后，你的博客主页大概长这样。Matery 的大图轮播 + Material Design 卡片布局，颜值在线。

十三、部署英文作品集（进阶：单仓库多站点）

如果你的英文作品集（Portfolio）也需要上线，可以和博客共用一个 GitHub Pages 仓库：

1. 单独创建一个 Portfolio 项目，使用 Cactus 或其他主题
2. Portfolio 的 _config.yml 中设置 root: /portfolio/
3. 在博客部署前，把 Portfolio 的 public/ 复制到博客的 public/portfolio/ 下

这样就能同时拥有：

• 中文博客：https://用户名.github.io
• 英文作品集：https://用户名.github.io/portfolio/

十四、主题美化：统一配色方案

Matery 默认使用绿色作为主题色。以下是以紫色（#8b5cf6）为例的替代方案。

13.1 修改的完整文件清单

13.2 颜色映射表

13.3 批量查找替换命令（Bash）

# 在 themes/matery 目录下查找所有绿色残留
grep -rn "42b983\|0f9d58\|4cbf30\|38a274\|3ecf8e\|0ba360\|3cba92" \
  --include="*.css" --include="*.ejs" .

十五、关闭不需要的功能

14.1 统计与分析

编辑 themes/matery/_config.yml：

# 关闭百度统计
baiduAnalytics:
  enable: false
  id:

# 关闭 Google Analytics
googleAnalytics:
  enable: false
  id:

# 关闭百度推送
baiduPush: false

14.2 移除不用的插件

npm uninstall hexo-theme-landscape hexo-renderer-pug

hexo-theme-landscape 是 Hexo 默认主题，已用 Matery 就不需要了。hexo-renderer-pug 是 Pug 模板引擎，Matery 用的是 EJS。

十六、日常写作工作流

新文章

hexo new "文章标题"

本地预览

hexo server

访问 http://localhost:4000 实时查看效果。

发布上线

hexo clean && hexo g && hexo d

一句话总结

写 Markdown → hexo server 预览 → hexo clean && hexo g && hexo d 发布

十七、常见问题排查

Q1：部署后页面空白 / 404？

检查 _config.yml 中的 url 和 root：

• 根站点：root: /
• 子目录站点：root: /子目录名/

Q2：图片显示不出来（裂图）？

1. 确认图片放在了 source/images/ 下
2. 引用路径必须以 /images/ 开头，如 ![图](/images/xxx.jpg)
3. 不要用相对路径 ../images/

Q3：部署后网站没变化？

• GitHub Pages 有 1-5 分钟缓存，等一等
• 强制刷新浏览器：Ctrl+Shift+R
• 检查 GitHub 仓库的 Actions 页面是否显示绿色对勾

Q4：想要自定义域名？

1. 在 source/ 下创建 CNAME 文件，写入你的域名（如 blog.example.com）
2. 去域名 DNS 服务商添加 CNAME 记录指向 你的用户名.github.io
3. GitHub 仓库 Settings → Pages → Custom domain 填写域名

Q5：如何添加评论系统？

推荐 Giscus（基于 GitHub Discussions），比 Gitalk 更简单，无需申请 OAuth App：

1. 访问 giscus.app，填入仓库名
2. 在 GitHub 仓库 Settings → Features 中开启 Discussions
3. 把生成的配置填入 themes/matery/_config.yml：

giscus:
  enable: true
  repo: 你的用户名/你的用户名.github.io
  repoID: 从 giscus.app 获取
  category: Announcements
  categoryID: 从 giscus.app 获取
  mapping: pathname
  lang: zh-CN

Matery 还支持 Gitalk、Valine、Waline、Twikoo 等，按需选择即可。

Q6：代码块没有语法高亮？

确认 _config.yml 中启用了 Prism.js：

prismjs:
  enable: true
  preprocess: true

Matery 主题内置了 Prism.js 的支持，开启后代码块会自动应用 Okaidia 暗色主题 + 行号。

Q7：首页显示文章全文而不是摘要？

在文章中加入 <!-- more --> 标签，前面的内容作为摘要显示在首页卡片中，后面的内容只有点进去才能看到。

总结

这篇保姆级教程从一个空仓库开始，手把手带你完成了：

1. 环境搭建 → Node.js + Git + GitHub 仓库
2. 博客创建 → Hexo 初始化 + 必备插件
3. 核心配置 → _config.yml 网站配置 + Matery 主题配置
4. 内容写作 → Front-matter 配置 + Markdown 规范 + 图片管理
5. 主题美化 → 全站配色统一（紫/蓝/任意色）
6. 功能增强 → 评论系统（Giscus）+ 搜索 + RSS + Sitemap
7. 部署发布 → 一键推送到 GitHub Pages
8. 进阶扩展 → 多站点部署、自定义域名、代码高亮（Prism.js 暗色主题）

如果你已经跟着教程做完了所有步骤，恭喜——你现在拥有的是一个零成本、完全自定义、加载飞速、好看又好用的个人博客。

写吧。写得越多，收获越多。