高德广告工程的AI Native知识库体系

**一、背景与目标
**

当我们需要了解“某业务能力如何实现”时，相关知识往往分散在不同地方：一部分记录在 CodeWiki 中，一部分散落在设计文档里，还有一些只存在于少数研发人员的经验中。要完整找到这些信息，通常需要跨越多个平台，并进一步判断内容是否齐全、是否仍然有效。人可以凭借经验串联线索、辨别时效，但 Agent 往往难以准确识别这些信息之间的关联及其有效性。

广告工程团队正推动研发流程向 AI Native 模式演进。一个需求周期可拆分为六个阶段：需求增强、需求拆解、方案设计、代码开发、测试闭环和线上运维，每个阶段都有 Agent 深度参与。但 Agent 在复杂任务中的表现仍会受到上下文质量影响，尤其缺少对系统整体的认知、对历史经验的记忆以及对实现细节的掌握，这正是知识库需要补齐的部分。团队过去在 CodeWiki、设计文档、需求复盘等多处有积累，却彼此割裂，覆盖率、准确性、时效性都难保证，知识虽多却无法有效驱动 Agent。

各阶段对知识的依赖各不相同，这张表既是需求清单，也是“够不够用”的标尺。

**二、总体架构
**

体系分四层，支撑研发与运维两条流程。规模上，这套底座已沉淀 6 个知识域、千余篇知识，由数十个代码仓库、上千篇文档抽取而来，稳定支撑需求增强、需求拆解、SDD、运维等多阶段 AI 任务。

层	职责
接入层	体系向调用方提供统一的知识入口，以便集中管理检索、发布、审计与演进能力。当前入口以 Skill 形态嵌入各类研发 Agent，并为后续独立部署保留扩展空间。
能力层	Skill 内核，一次请求统一走 “意图识别 → 路由 → 执行 → 审计回执”。读侧负责检索、重排、跨库探索、效果评测；写侧负责发布、更新、索引重对齐、SDD 归档、规约同步、案例沉淀。
知识层	六个并列知识域（索引上的 L1）构成面向联邦演进的底座，各域组织模型不同，通过统一跨层映射相互引用。
反馈层	让知识库在规则约束和人工审核下随研发过程持续演进的一组机制，覆盖纠错、案例沉淀、规约同步、效果回归。

**三、知识底座：六个知识域
**

3.1 怎么分域

不按团队或系统切，按 Agent 提问的“知识类型”切：需求阶段问“是什么、像不像”，开发阶段问“在哪、怎么实现”，运维阶段问“为什么、怎么排”。每类问题落一个域，域内再按最自然的维度细分。

除了“分哪几个域”，域内的组织方式上我们做了三处针对性设计：

语义域、架构域采用全局统一组织：术语与架构以全局一份为主、不按模块切分，换取跨域引用时的一致性；不同业务线对同一术语的差异，通过语义域的“映射”维度表达，而非强求口径一致。
服务域按实例驱动、不预先登记：不额外维护一张“应有哪些服务”的总表，新服务发布后即纳入；同时每个服务固定六类 L3（框架/流程/接口/实现/最佳实践/规约，允许留空），保证结构一致、Agent 知道去哪类找，覆盖完整性由抽取流水线的覆盖率审计兜底。
项目域采用扁平单篇：一次研发的需求、方案、反思作为一个整体归档为一篇，以保留上下文的完整性。

3.2 三条约束

六域能协同、且能被准确命中，靠三条贯穿全域的约束：

跨层映射：每篇文档底部预留其他五个知识域的映射项；存在明确关系时填写相关链接，无关联时显式标注，避免遗漏或制造无效关联。
索引归纳纪律：每级只归纳直接下级、严格不跨级（L1 不列具体项目，L2 不写代码字段）；索引页正文必须写“下级一句话归纳 + 内联 URL”——这是 §4“读正文直达”的前提。
******模板即契约：******除服务规约等明确例外外，普通知识文档统一采用四段式骨架（Preamble / Body / 跨层映射 / Metadata）；发布前必须通过模板校验，避免不完整内容进入知识库。

**四、检索能力
**

知识库的价值，最终取决于能不能在需要时把对的知识、准确地、低成本地交到调用方手里。

还是开头那个问题——问 “某业务能力如何实现”：

意图识别 → 动作=查询，域=业务服务（“怎么实现”是落地），阶段=代码开发。“某业务能力”跨域同名（语义域讲是什么 / 前台域讲怎么承接 / 服务域讲怎么实现），靠句式锚到服务域。
路由 → 解析到“服务域 → 相关业务服务 → 代码实现 L3”。
直达短路→ 命中索引节点先读正文；正文若已给出叶子链接且置信度足够高，直接返回、全程不发向量。
兜底重排（拿不到直达）→ 结构化检索与向量检索并发，merge 时把最贴意图的服务域提前，语义域“是什么”作“相关”列出、不喧宾夺主。
文档回溯 → 向量命中碎片后，先回溯至完整权威文档，再根据当前任务选取相关章节或摘要交给调用方。

对比开头“翻三四个平台”的窘境：在高置信命中时，同一问题可以通过一次查询定位到完整权威文档；未能直达时，则进入结构化检索、向量召回与重排流程。下面各节将进一步展开这次查询过程中的关键设计。

4.1 意图识别：声明式 registry + LLM 判定 + 置信度兜底

意图识别是入口、决定后面所有路由，因此，本方案既不依赖硬编码的 if-else，也不依赖另行训练的分类器，而是由以下三部分组成：

声明式 registry：所有意图登记在一张表，按三维度组织——动作（必选 1 个）× 目标域（可选 0-1）× 流程阶段（可选 0-1），各配触发关键词与典型句式。
LLM 判定：Skill 内核拿自然语言对着表打标（非精确匹配），“我在写代码，某业务能力的实现资料给我”也能判成 查询 × 服务域 × 代码开发。
置信度兜底：三个维度均明确且相互无冲突时，按高置信请求处理；存在缺失或冲突时，返回候选或发起澄清；连动作都认不出=低置信，强制反问一次、绝不硬猜。

好处：路由结果可追溯（能够映射到 registry 中的意图项和触发依据）、可扩展（新增意图主要调整声明配置）、有兜底（低置信时先澄清）。

4.2 索引正文优先

节点名多是代码标识符，跟自然语言查询对不上，所以命中索引后优先读取正文进行语义匹配，而不是只依赖节点名称。正文提供直接下级的归纳与链接；当当前索引直接关联叶子文档时，可以通过一次跳转定位目标内容。导航点查通常只需读取索引与目标文档，并不产生向量检索调用。节点名称仅作为补充线索。

4.3 直达短路 + 并发召回

本方案采用“高置信直达，否则并发召回”：能够从索引正文获得高置信结果时直接返回；不能直达时，结构化检索与向量检索并发执行，并在合并阶段完成重排。merge 守两条硬规则：

以结构 canonical 为权威锚、向量补漏；
向量命中后先回溯至完整权威文档，避免脱离上下文理解碎片；再根据当前任务选取相关章节或摘要交给调用方。

4.4 意图加权重排

同一概念常跨域同名（“某业务能力”在语义域描述概念，在前台域描述承接方式，在服务域描述具体实现），向量 top1 容易落在“是什么”上、未必是提问者要的。

因此不固定某个知识域始终优先，避免抑制其他类型任务的召回结果，而是按“流程阶段 × 域”优先级矩阵重排、保留多域：最贴意图的域提前，同名其它域作“相关”列出，意图不明则多域并列。唯一硬约束——不能因向量分高，就拿“是什么”答“怎么做”。

4.5 检索质量怎么看

效果由独立的 recall-eval 持续校验。这里讲清两件事，避免把指标讲过头：

召回率只是手段、不是目的：评测集上观测“有值召回”，但召回高 ≠ 下游 Agent 任务准——塞一堆不相关内容进上下文反而是负担。它只作检索层的回归哨兵，不代表整体价值。
整体价值还需要结合采纳信号、消融对照等代理证据观察：Agent 任务难做严格 A/B。改看两个更贴目标的信号——① 采纳信号：案例沉淀记录“使用了哪些知识，以及哪些内容被采用、修改或未使用”，形成知识采纳情况等代理信号；②消融对照：挑真实查询，关库 vs 接库各跑一遍，定性比对 Agent 输出差异。这比单一召回率更能说明知识库到底有没有帮上 Agent。

4.6 与纯向量 RAG 的差异

很多人第一反应是"这不就是个 RAG 吗"。确实，向量检索是本系统的一个组件——rerank、hybrid 召回、metadata 过滤这些现代 RAG 的常规手段我们也在用。差异不在"有没有用向量"，而在我们把检索放进了一套带索引契约的结构里，针对几个在我们场景里特别突出的问题做了取舍：

场景里的问题	朴素向量 RAG（仅 chunk+top-k）的局限	我们的处理
节点名是代码标识符、查询是自然语言	chunk 相似度对不上	索引正文语义匹配 + 向量补漏
调用方要的是完整上下文	抛 top-k 碎片	回溯至完整权威文档，再按任务选取相关内容
同名概念跨多个域	top1 易落错域	阶段 × 域加权重排，消歧不删域
导航/点查其实不需要向量	每次查询都走向量、有成本	命中索引正文可直达，不发向量
多域知识具有不同的组织与治理规则	仅依赖统一切片和相似度排序时，难以表达域间结构与治理约束	通过六域模型和统一映射补充治理语义
知识要能被人维护	碎片化索引不便于人工直接维护和持续治理	模板即契约，人能读能写能校验

（这些都不是"向量检索做不到"，而是把它跟结构化索引、模板契约组合起来的结果。与只索引代码的 codebase index 相比，本方案覆盖的知识类型更广；与知识图谱或 GraphRAG 相比，我们在当前场景下选择了相对轻量、便于人工共建的组织方式。三类方案各有适用边界，并非相互替代。）

**五、知识生产
**

三条路径共享一套写入纪律：URL 完整性（终态不留 TBD）、写后逐篇回读（不抽样）、Owner-only 索引更新（不级联改上级）、命名含中文描述。

5.1 手工发布与更新

publish 按模板创建、update 整体覆盖。服务规约是特例，走 spec-sync：豁免四段式、只校验最简骨架（标题 / Owner / 最后更新），规约内容由负责人提供并审核，不由 Agent 直接生成，以避免未经确认的内容进入正式规约。

5.2 SDD 归档

sdd-archive 是研发流程的自然出口，做完一个项目就把需求、方案、反思归档为一篇：解析校验（必填原始诉求、整体设计、至少一条反思）→方向路由（按服务归类到方向 L2）→落库登记（渲染模板、追加项目花名册一行）。边界：反思里的服务规约不自动写入，只生成“建议整理入 service_spec”提示，经人工审核后再正式落地。

5.3 多 Agent 批量抽取

初始填充与大规模补全是另一个量级——数十仓库、上千文档、还要跨仓建依赖关联，一次跑数十小时，远超单 Agent 上下文与单次会话。kb_multi_agent 为此而生，独立于接入层、专司大规模生产。

五个关键设计：

流水线：主对话作 orchestrator，triage → explore → review → publish 四阶段各有专职 worker，另有排障角色按需处理 issue。
长时运行：/goal 绑 Stop hook，每次想结束都检查终止条件（完成 / 取消 / 失败 / escalation 堆积 / 30 分钟未变），不满足就继续；状态全落盘、从文件 resume——上下文可丢、进度不丢。
抗遗漏：源树 BFS 全展开；按源型拆 batch 串行跑；spec 按层级归并、跨 batch 累积（上千压到几百）；代码源三层防线（survey 标优先级 / explorer 带 file:line 取证 / reviewer 覆盖率审计）。
多来源整合：reviewer 对同一篇 spec 的多源贡献逐段比对（去重 / 互补合并 / 矛盾升级 / 新主题追加），并扫描其它仓库 spec、自动匹配本仓 depends_on 与别人 exposes，反向补齐“被谁调用”。
两段式发布：本地先产中性数据半成品落 published/ 供人 review，确认后 /extract-doc-publish-remote对齐远端模板、逐篇推送，并记录每篇文档的执行状态与失败项，以便失败后定向重试。好处是产出与格式解耦——远端模板变了只重跑发布，已抽结果不重来。

**六、闭环与保鲜
**

知识库如果只持续积累，而缺少反馈和更新机制，很快就会与真实系统脱节。三组机制构成闭环：流程沉淀 → 反哺各域 → 保鲜更新。

6.1 流程沉淀

需求增强 / 架构拆解：主任务完成后隐式自动沉淀一篇案例，采集“用了哪些知识、哪些有用、交付物是什么”——正是 §4.5 采纳信号的来源。
SDD 产出：sdd-archive 一次研发归档一篇。
线上问题：系统/架构故障归报警 Case，业务/效果问题归业务排查 Case。

6.2 反哺各域

运维 Case 反向沉淀 SOP（硬约束）：报警类回报警 SOP、排查类回业务排查 SOP，下次同类有 SOP 可循。
SDD 反思反哺服务/架构域：服务规约生成建议经 spec-sync 落地。
案例 consolidate：隐式案例累积到量后，周期性扫某个 L2、提炼共性反向 publish 到上层。
使用即反馈：检索/注入被用后发现“找错 / 不全 / 过期”即经 feedback 沉淀，owner 跟进——最轻量、最高频的纠错入口。

6.3 保鲜更新

核心挑战是源头变化的同步：代码、接口、架构变了，知识不跟着更新就从“权威”退化成“误导”，过期内容一旦被当作权威依据，可能放大误导风险。目前靠两条线：

reindex：索引页与内容不一致时按四档严重度对齐（空页 / 轻修链接 / 补框架 / 重建漂移），默认走最轻档。
巡检 + 分层评测：定期全量扫描下线过期知识；recall-eval 分层守护——定期全量回归、逻辑变更即时跑全量、大批量发布跑 smoke、高频 query 每周抽样。

仍待补强（下一阶段重点）：变更感知触发更新（代码合入即识别受影响知识页）、知识版本与影响评估（改前评估波及的引用方）、时效与置信度标注（每条带“最后验证时间”、久未验证能被提示复核）。

6.4 当前局限与边界

******保鲜是相对薄弱的一环：******已有“使用即反馈”、例行巡检与索引维护机制作为兜底，部分过期内容可以在使用和巡检过程中被发现并纠正；但源头变化尚未做到自动感知，从变更发生到被纠正之间仍有时间窗口。
******跨服务调用关系可能不全：******服务间"谁调用谁"是靠抽取到的代码证据自动连起来的，证据挖得少的仓库会漏掉一部分调用关系。
检索对索引正文质量敏感：正文缺失或过薄时退化为翻名字兜底、检索质量可能下降——也就是说，§4 那条最快的主路径，恰恰建立在最依赖人工维护的索引正文上，这是我们持续投入正文质量的原因。

三组机制合起来，目标是让知识库正向循环：流程产生知识 → 沉淀提升知识的完整性与准确性 → 更高质量的知识更容易被采用 → 使用过程继续产生反馈。保鲜机制是这个循环的“防腐层”，确保它不因源头变化而悄悄失真。

**七、总结
**

AI Native 知识库并不是再建设一个文档存放平台，也不只是给现有资料叠加一层 RAG。它要解决的核心问题，是如何把分散在代码、设计文档和研发经验中的知识，转化为结构清晰、能够准确检索、可以持续更新的工程资产。

围绕这一目标，我们形成了一套完整链路：以统一入口承接人与 Agent 的知识请求，以六个知识域组织不同类型的内容，通过跨层映射和模板契约保持结构一致；消费侧结合意图识别、结构化索引与向量召回，将可回溯至完整权威文档、且与当前任务匹配的内容交给调用方；生产侧则通过手工发布、SDD 归档和多 Agent 批量抽取持续补充知识，再借助案例沉淀、使用反馈、巡检与评测形成闭环。

这套体系的价值不取决于文档数量，也不能只用一次召回结果衡量。更重要的是：知识能否在研发和运维的关键环节被找到、被采用，并在系统变化后及时得到修正。当前体系已经搭起了从知识生产到消费反馈的基本框架，后续还需要继续补强变更感知、版本影响评估以及时效与置信度标注。最终希望实现的，是让人与 Agent 基于同一套经过治理的知识源协作，并根据各自需要采用不同的消费方式，使知识不再只是项目结束后的静态沉淀，而是持续参与研发过程、并随实践不断演进的基础能力。

#Agent #知识库体系 #高德 #高德技术

END