面向 Agent 的分层知识库设计：从 RAG 到 Knowledge Context Layer

很多团队搭建知识库时，第一反应是把文档切块、向量化、塞进向量数据库，再让大模型根据相似片段回答问题。这就是 RAG（Retrieval-Augmented Generation，检索增强生成）的基本形态。

RAG 适合解决“我问一句，系统帮我从文档里找几段相关内容”的问题，但工程知识库不只是问答系统。它还要回答这些更复杂的问题：

• 新人应该按什么顺序理解一个系统？
• 某个服务的设计原则、架构约束、代码实现和线上经验之间是什么关系？
• 修改一条规范会影响哪些模板、SDK 和排障手册？
• 架构师、开发者、SRE 需要看的知识层级是否一样？
• Agent 在有限上下文窗口里，应该优先读取哪些内容？

这些问题靠“语义相似度 Top-K”很难稳定解决。原因不是 embedding 不够好，而是工程知识本身需要结构。它既像一棵树，有从原则到实现的抽象层级；又像一张图，有服务依赖、规范约束、故障反馈和跨模块引用。

分层知识库的目标，就是在 RAG 之上增加一层面向 Agent 的 Knowledge Context Layer。它不直接替代向量检索，而是先告诉 Agent：该去哪个层级找、沿着哪些关系扩展、按照什么角色筛选上下文。

RAG 在工程知识库里的三个瓶颈

经典 RAG 的流程很直接：

flowchart LR
    A[源文档] --> B[切分 Chunk]
    B --> C[Embedding 向量化]
    C --> D[(向量数据库)]
    E[用户问题] --> F[问题向量化]
    F --> D
    D --> G[Top-K 相似片段]
    G --> H[拼接 Prompt]
    H --> I[LLM 生成答案]

这个流程在 FAQ、产品手册、简单规章检索里很好用，因为问题通常能被少量片段直接回答。但工程知识库的内容更复杂，常见瓶颈主要有三个。

每次查询都从零开始

如果一个问题需要综合 5 份设计文档、2 份故障复盘和 1 份代码规范，普通 RAG 每次都要重新召回、拼接、推理。上一次已经整理过的中间结论不会沉淀下来，系统也不会因为被问过多次而自然变聪明。

这种模式的问题在于：检索结果只是临时上下文，不是长期知识资产。回答结束后，综合出来的结构、引用路径、概念关系都丢掉了。

很难把分散信息连成关系

向量检索擅长找到“语义相近”的片段，却不擅长表达“它们之间是什么关系”。

例如，一个系统里有这些信息：

• A 服务调用 B 服务；
• B 服务依赖一张订单表；
• 某次故障是订单表索引失效导致；
• 一条架构原则要求核心链路避免跨域同步调用。

这些内容可能散落在服务说明、数据库设计、故障复盘和架构原则里。普通 RAG 也许能召回其中几段，但它并不知道这些片段共同构成了一条影响链路。

知识粒度容易混在一起

同一个关键词可能出现在不同抽象层次里。比如“单一职责”既可能出现在架构原则里，也可能出现在某个函数重构说明里。向量空间会认为它们语义接近，但用户的问题可能完全不同：

RAG 的默认假设是“相关片段越相似越好”，但工程知识库更需要先判断“问题属于哪个层级”。

主流知识库范式的能力边界

从“平铺文档”走向“结构化知识”，常见做法大致可以分成四类：Naive RAG、LLM Wiki、Graphify 和 GraphRAG。它们分别解决了不同问题，也留下了不同缺口。

Naive RAG：平铺向量检索

Naive RAG 把所有文档切成片段，然后按向量相似度召回。

flowchart LR
    A[文档集合] --> B[Chunk]
    B --> C[Embedding]
    C --> D[(Vector Store)]
    E[Query] --> F[Embedding]
    F --> D
    D --> G[Top-K Chunk]
    G --> H[LLM]

它的优点是工程落地简单：不需要设计复杂数据模型，也不需要提前梳理文档关系，只要能切块和向量化，就能跑起来。

它的限制也很明显：

现代 RAG 可以加入 metadata filter、rerank、hybrid search、访问控制、query routing 等机制补齐部分能力，但这意味着系统已经不再是“简单向量库问答”，而是在向结构化检索演进。

LLM Wiki：把知识编译成持续维护的页面

LLM Wiki 的核心思想是：不要让大模型每次问答都重新综合知识，而是让它把读过的资料整理成稳定的 wiki 页面，并持续维护这些页面。

它可以分成三层：

核心操作通常有三类。

Ingest：摄入新资料

当一份新资料进入知识库时，LLM 不只是写一段摘要，而是要完成一组维护动作：

flowchart LR
    A[新资料进入] --> B[通读并提取主题]
    B --> C[创建摘要页]
    C --> D[更新索引页]
    D --> E[修订相关概念页]
    E --> F[补充交叉引用]

一次摄入可能会改动多个 wiki 页面，因为新资料可能影响已有概念、实体、结论和引用关系。

Query：基于页面回答

查询时，系统先通过索引定位相关页面，再让 LLM 读取页面并生成带引用的回答。高质量回答还可以反向沉淀成新的 wiki 页面，让探索过程变成知识积累过程。

Lint：检查知识库健康度

Wiki 会随着资料增长而出现问题，比如页面孤立、概念重复、引用断裂、旧结论没有更新。Lint 机制负责定期发现这些问题。

flowchart TD
    A[Wiki 健康检查] --> B[矛盾声明]
    A --> C[过期引用]
    A --> D[孤立页面]
    A --> E[缺失概念]
    A --> F[断裂链接]

LLM Wiki 的价值在于“持续编译”。它把临时推理变成稳定知识工件，适合中等规模、主题相对明确的知识库。它的短板是关系结构通常依赖 wikilink，缺少自动关系推断、社区发现和严格的层级模型。

Graphify：把代码和文档变成知识图谱

Graphify 的思路是把代码库、配置、数据库、文档、设计稿等资源统一映射成一张图。图里有节点，也有边；节点表示函数、类、服务、概念、数据库表等实体，边表示调用、依赖、解释、实现、关联等关系。

典型提取流程可以分成两条管道：

flowchart LR
    A[代码仓库] --> B[AST 解析管道]
    B --> C[函数/类/模块/导入关系]

    D[文档/PDF/图片/视频] --> E[LLM 语义管道]
    E --> F[概念节点/语义关系]

    C --> G[(知识图谱)]
    F --> G
    G --> H[graph.json]
    G --> I[graph.html]
    G --> J[GRAPH_REPORT.md]

AST（Abstract Syntax Tree，抽象语法树）管道适合解析代码结构，LLM 语义管道适合理解非结构化资料。最终产物通常包括：

知识图谱带来的能力和普通文档不同。它可以发现系统里的 God Nodes，也就是连接度很高的关键节点；也可以发现看似不相关模块之间的跨域联系；还可以识别某些服务、表、接口缺少解释文档的知识缺口。

为了降低误导，图谱里的关系最好带置信度：

Graphify 很适合回答“A 和 B 有什么关系”“系统里哪些节点最关键”“哪里缺文档”。但它不适合单独承担所有问答任务，因为图谱是骨架，具体参数、代码示例、操作步骤仍然要回到原始文档或代码。

GraphRAG：用图谱增强检索

GraphRAG 把知识图谱和 RAG 结合起来。它先从文档里提取实体和关系，构建知识图谱，再用社区发现算法把图划分成多个社区，并为每个社区生成摘要。查询时，系统可以根据问题类型选择全局搜索或局部搜索。

flowchart LR
    A[源文档] --> B[实体与关系提取]
    B --> C[(知识图谱)]
    C --> D[社区聚类]
    D --> E[分层社区摘要]

    F[用户问题] --> G{查询类型}
    G -->|全局问题| H[Global Search]
    G -->|实体问题| I[Local Search]
    H --> E
    I --> C
    E --> J[LLM 回答]
    C --> J

两种查询模式适合不同场景：

GraphRAG 能缓解普通 RAG 的两个典型问题：通过图结构把分散信息连成关系，通过社区摘要支持全局理解。代价也比较高：实体抽取需要大量 LLM 调用，图谱和社区摘要的增量更新较复杂，而且源文档质量会直接影响图谱质量。

四种范式对比

这些方案都在解决知识库结构问题，但它们普遍缺少一个明确设计：把知识按抽象度和稳定性分层，再根据角色选择上下文。

分层知识库：把知识组织成金字塔

工程知识不是同一种东西。有些知识非常稳定，比如设计原则；有些知识变化很快，比如故障排查命令。把它们放在同一个向量空间里统一召回，会导致高层原则和低层细节互相干扰。

更合理的方式是把知识分成 5 层：

flowchart TB
    L1["L1 原则<br/>稳定、抽象、长期有效"]
    L2["L2 架构<br/>系统结构、技术选型、ADR"]
    L3["L3 规范<br/>编码标准、接口约定、流程规则"]
    L4["L4 实现<br/>代码模板、SDK、配置、API 示例"]
    L5["L5 经验<br/>故障复盘、运维日志、排障 SOP"]

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5

这 5 层对应软件工程里常见的抽象层次：

分层之后，检索不再是“从所有文档里找最像的片段”，而是先判断问题属于哪个层级，再在目标层级里查找内容。

例如：

层级的作用不是替代搜索，而是先缩小搜索空间。问题一旦被路由到正确层级，后续检索的噪声会小很多。

知识图谱：让五层之间产生关系

分层不能只做成 5 个文件夹。如果文档之间没有关系，系统仍然无法回答“影响面”“约束来源”“经验反馈到哪里”这类问题。

分层知识库需要把每篇文档看成节点，再用有向边表达关系：

flowchart TD
    P[L1 原则] -->|governs| A[L2 架构决策]
    P -->|defines| S[L3 规范]
    A -->|constrains| S
    A -->|implements| I[L4 实现]
    S -->|implements| I
    I -->|validates| E[L5 运行经验]
    E -->|feedback| S
    E -->|feedback| I
    X[任意文档] -.->|cross_ref| Y[相关文档]

常用边类型如下：

有了这些边，知识库就能支持几类重要能力。

从实现上溯到原则

开发者看到一段代码模板时，可以追溯它为什么这么设计：它实现了哪条规范，规范来自哪个架构约束，架构约束又受哪条原则影响。

从原则下探到实现

架构师提出一条原则后，可以检查它是否已经落到架构决策、编码规范和代码模板里。如果原则只停留在 L1，没有下游文档承接，就说明它还没有变成可执行知识。

让经验形成反馈环

一次故障复盘不应该只归档在 L5。它可能需要修改 L3 的规范，也可能需要更新 L4 的模板或排障脚本。feedback 边能把经验和改进行动连接起来。

角色感知：不同人需要不同上下文

同一个知识库不应该给所有人返回同一种上下文。架构师关心原则和架构约束，开发者更关心规范和实现，SRE 需要实现细节和运行经验，新人则需要一条能逐步理解系统的阅读路径。

可以用角色-层级矩阵描述访问优先级：

角色感知还需要配合 context budget。大模型上下文窗口再大，也不能无节制塞文档。更稳妥的方式是为不同角色设置优先层级和预算。

roles:
  architect:
    context_budget: 12000
    priority_order: [L1, L2, L3, L5, L4]

  developer:
    context_budget: 10000
    priority_order: [L3, L4, L2, L5, L1]

  sre:
    context_budget: 10000
    priority_order: [L5, L4, L2, L3, L1]

  newcomer:
    context_budget: 8000
    priority_order: [L1, L2, L3, L5, L4]

系统检索时按照优先顺序逐层填充内容，直到预算用完。这样可以避免一个 SRE 排障问题被大量原则文档占满，也能避免架构讨论被底层代码片段干扰。

分层检索：先路由，再召回，再扩展

分层知识库的检索流程可以拆成 5 步：

flowchart LR
    A[用户问题] --> B[识别角色]
    B --> C[判断目标层级]
    C --> D[层内关键词/索引检索]
    D --> E[图谱邻域扩展]
    E --> F[按预算裁剪上下文]
    F --> G[LLM 生成答案]

它和普通向量检索的核心区别在于：普通向量检索先找相似片段，分层检索先判断“去哪里找”。

最实用的组合不是二选一，而是混合：

sequenceDiagram
    participant U as 用户
    participant P as 分层知识库
    participant V as 向量检索
    participant L as LLM

    U->>P: 提问
    P->>P: 识别角色和层级
    P->>P: 找到相关文档与图谱邻域
    P->>V: 对需要细节的节点做向量检索
    V-->>P: 返回代码级片段
    P->>L: 组装结构化上下文
    L-->>U: 返回答案

分层知识库负责导航和结构，向量检索负责补充函数、配置、行号、参数等细节。这样既保留了 RAG 的精确召回能力，又减少了“所有问题都从全量 chunk 里盲搜”的不稳定性。

分层知识库和其他范式的关系

分层知识库更像一个上层编排层，而不是底层存储方案。它可以建立在 Wiki、Graph、Vector Store 之上。

flowchart TB
    A[Agent / LLM 应用] --> B[Knowledge Context Layer]
    B --> C[层级路由]
    B --> D[角色过滤]
    B --> E[图谱扩展]
    B --> F[Context Budget 管理]

    C --> G[LLM Wiki]
    D --> H[知识图谱]
    E --> I[GraphRAG]
    F --> J[Vector Store]
    G --> K[源文档]
    H --> K
    I --> K
    J --> K

它承担的是“让 Agent 知道该读什么”的职责：

• LLM Wiki 负责沉淀可读页面；
• Graphify 负责发现实体和关系；
• GraphRAG 负责全局摘要和局部图谱搜索；
• 向量数据库负责精确片段召回；
• 分层知识库负责层级、角色、路径和预算编排。

知识库会腐烂，必须设计同步机制

知识库最危险的问题不是没内容，而是内容过期。没有文档时，用户至少知道要去问人；过期文档会让用户带着错误信心执行错误操作。

常见腐烂形式有三类：

一个简单判断标准是：新人按知识库操作会踩坑，说明知识已经失效。

不同层级需要不同保鲜周期

分层以后，维护策略也应该分层。原则不需要每天检查，但实现文档和排障 SOP 可能几天就会过期。

这意味着维护系统不能只靠“每月统一检查一次”。更有效的做法是让变更事件触发知识更新。

用审计指标代替人工巡检

靠人逐页检查知识库很难持续。更稳定的方式是定义健康指标，让系统自动发现问题。

增量同步可以设计成三段式：

flowchart LR
    A[Phase 1 审计] --> B[发现覆盖缺口和过期条目]
    B --> C[Phase 2 摄入]
    C --> D[加载源文档]
    D --> E[分块/分类/去重]
    E --> F[写入或更新分层知识库]
    F --> G[Phase 3 后审计]
    G --> H[对比覆盖率和连通性变化]

去重和更新策略可以结合 checksum 与 entry ID：

这套机制的重点不是一次性生成漂亮目录，而是让知识库能随着代码、架构和运维经验持续变化。

检索效果应该怎么评估

分层知识库不能只看主观体验，需要用检索指标评估。常见指标包括：

一个工程知识库的评测集应覆盖不同问题类型，而不是只测简单问答：

从常见表现看，不同方案的优势并不一样：

在工程实践里，混合检索通常更稳：分层结构负责让系统找对方向，RAG 负责补齐具体细节，知识图谱负责连接上下游关系。

一个可落地的目录结构

分层知识库可以从简单目录开始，不一定一开始就上复杂平台。

knowledge-base/
  L1-principles/
    engineering-principles.md
    reliability-principles.md

  L2-architecture/
    order-domain-adr.md
    service-topology.md

  L3-standards/
    api-design-standard.md
    logging-standard.md
    lint-rules.md

  L4-implementation/
    java-sdk-usage.md
    service-template.md
    config-examples.md

  L5-experience/
    incident-2026-05-order-timeout.md
    rollback-sop.md
    alert-troubleshooting.md

  graph/
    edges.yaml
    nodes.yaml

  roles.yaml
  index.md

关系边可以用 YAML 描述：

edges:
  - from: engineering-principles
    to: order-domain-adr
    type: governs

  - from: order-domain-adr
    to: api-design-standard
    type: constrains

  - from: api-design-standard
    to: java-sdk-usage
    type: implements

  - from: incident-2026-05-order-timeout
    to: rollback-sop
    type: feedback

索引页负责给人和 Agent 提供入口：

# Knowledge Index

## 新人路径
1. L1-principles/engineering-principles.md
2. L2-architecture/service-topology.md
3. L3-standards/api-design-standard.md
4. L5-experience/alert-troubleshooting.md

## 开发者路径
1. L3-standards/api-design-standard.md
2. L4-implementation/service-template.md
3. L4-implementation/java-sdk-usage.md

## SRE 路径
1. L5-experience/alert-troubleshooting.md
2. L5-experience/rollback-sop.md
3. L2-architecture/service-topology.md

只要有分层、索引、角色和关系边，就已经具备 Knowledge Context Layer 的雏形。后续可以逐步增加自动分类、图谱可视化、向量检索、健康审计和增量同步。

适合和不适合使用分层知识库的场景

分层知识库适合知识复杂、角色多、文档生命周期差异明显的团队。对于只有少量文档的小项目，直接用搜索或简单 RAG 就够了。

核心设计原则

分层知识库最重要的不是“五个目录”，而是几条设计原则：

1. 先分层，再检索。 先判断问题需要原则、架构、规范、实现还是经验，再进入对应层级召回。
2. 用图谱表达关系。 文档之间要有约束、实现、验证、反馈等明确边，不能只靠文件夹隔离。
3. 按角色分配上下文。 不同角色有不同优先层级和上下文预算，不能返回同一批材料。
4. 把更新绑定到变更事件。 架构评审、规则变更、故障复盘、新服务上线都应该触发知识同步。
5. 让 RAG 补细节，不让 RAG 承担全部结构。 向量检索适合找代码级片段，但不适合独自管理知识层级、角色和关系。

最终目标很明确：当用户或 Agent 提出问题时，系统不是返回几段看起来相似的文本，而是在正确层级、正确角色和正确关系路径上组织答案。这样，知识库才不只是文档仓库，而是真正可被 Agent 使用的上下文基础设施。