知识库不是文档仓库，而是 Agent 的上下文底座

过去两年，企业内部出现了大量 AI 工具：Agent、工作流、问答助手、研发辅助平台、运维排查系统。模型能力越来越强，工具接入也越来越完整。

但用得越多，越容易看到一个共性问题：真正限制 AI 应用效果的，常常不是模型，而是上下文。

如果业务知识只存在于几个人脑子里，如果文档散在不同系统里，如果口径互相冲突，如果一篇文档过了三个月就没人知道还能不能信，那么再强的 Agent 接进来，也只能在不完整信息里猜。

反过来，一旦知识本身结构清晰、边界明确、来源可查、状态可判断，Agent 才能稳定消费它。上层应用无论是问答、排查、代码生成，还是需求到实现的协作链路，都有了可靠底座。

所以，AI 时代建设知识库，不只是“把文档整理好”。更准确地说，是把业务知识和代码知识沉淀成一套人能读、Agent 能用、系统能持续更新的知识基础设施。

图：散落文档需要先变成可路由、可复核的上下文资产

知识库的目标不是存档，而是可消费

一个面向 AI 的知识库，至少要完成三件事。

第一，沉淀业务和代码知识。

它不只记录业务背景，还要记录核心概念、主流程、指标口径、边界、FAQ、排查抓手和经验沉淀。更重要的是，它要建立从业务问题到代码入口、模块、仓库、接口和链路的映射。这样人和 Agent 才能从一个真实问题定位到实现位置。

第二，面向不同平台和系统消费。

知识库不应该被锁死在某个专有工具里。它可以同步到在线文档，也可以放进 Git 仓库、静态托管、打包分发、被 Agent 检索。关键是知识本身要有开放格式，而不是先绑定平台，再把内容塞进去。

第三，支撑持续演进。

知识库不是一次性文档工程。业务会变，代码会变，指标口径会变，排查经验也会更新。知识库必须支持新增、补全、修订、拆分、合并、归档和复核。

三条设计原则：可读、可更新、可消费

参考 Google OKF，也就是 Open Knowledge Format 的思路，再结合工程实践，可以把知识库设计原则收敛成三个词：可读、可更新、可消费。

可读：人和 Agent 都要准确地读

传统文档更关注人的阅读体验，允许大量自由叙事。但 Agent 需要更稳定的结构。标题分级、列表、表格、状态字段、来源字段、交叉链接，都不是形式主义，而是为了让机器能准确解析。

可读也不只是“看得懂”，还包括“找得到”。如果每次回答问题都要全库扫描，token 和算力都会被浪费，结果也不稳定。

因此，知识库需要一个轻量路由层。它负责识别业务域、主题归属、父子 wiki 关系，以及业务知识和代码知识之间的映射。检索应该先经过路由，再命中具体知识，而不是直接把所有内容丢给模型。

可更新：每份 wiki 都是活资产

知识库最怕变成“建成即过期”的文档墓地。

每份 wiki 都应该被视为可演进资产。它需要有状态，需要能被复核，需要能被拆分和合并，也需要在废弃后保留历史参考。

这要求知识库在结构上支持生命周期，而不是只靠人工记忆维护。

可消费：开放格式优先，还要标清可信度

AI 消费知识时，一个危险点是把所有内容都当成同等可信。

人读文档时，会凭经验判断哪些段落可能过时，哪些只是临时结论，哪些是明确事实。Agent 没有这种组织记忆，必须靠显式标注。

所以知识库不能只记录确定结论，也要记录不覆盖范围、相邻 wiki 边界、待确认事项、低证据等级内容、易变事实的时间窗。

这类信息对人是提醒，对 Agent 是安全边界。

三层结构：领域目录、路由文件、知识文件

一个可维护的知识库，不应该只有一堆散落的 Markdown。更稳妥的结构是三层：

图：全局目录、领域路由和具体 wiki 共同构成 Agent 的导航层

三类文件各有职责：

其中 topic-map.md 很关键。它不是目录美化，而是 Agent 的导航层。没有它，Agent 很容易在大量文档里全局搜索，召回一堆相关但不精确的信息。

生命周期状态要显式写出来

知识库里的内容不可能永远同等可靠。一个成熟 wiki、一个刚创建的初稿、一个过期待复核的页面，不能被 Agent 视为同一等级。

可以给每个 wiki 维护一组轻量状态：

这类状态对 AI 很重要。它能帮助 Agent 判断：这份知识能不能直接采用？是否需要提醒用户复核？是否只能作为历史背景？

图：状态、复核和归档让知识不再被默认视为永远可信

wiki 文件应该有固定骨架

每个具体 wiki 可以使用 UTF-8 Markdown，由 Frontmatter 和正文两部分组成。

Frontmatter 记录机器可读的元数据，正文记录人和 Agent 共同消费的内容。正文不必完全一致，但最好有相对固定的章节骨架，便于定位。

一个通用骨架可以包含：

这里有几个实践约定值得保留。

主流程只写主链路。旁支、例外、历史原因，不要塞进主线里，否则文档会很快失焦。

架构与模块只记录业务主题到代码入口的映射，不重复展开实现细节。代码知识可以由下游代码管道归纳，业务 wiki 不应该变成低质量代码说明书。

经验沉淀要短。每条最好只保留现象、根因、抓手三类信息，详细复盘单独归档。

易变数据要单独放数据快照，并标注窗口、口径、采集时间和证据等级。否则 Agent 很容易把过期数据当成当前事实。

拆分粒度：默认主题级，不要无限细拆

知识库最容易走向两个极端。

一种是所有内容塞进一篇大文档，最后谁也不敢改。另一种是无限拆分，每个小点一页，导航成本高到难以维护。

更稳妥的默认粒度是主题级。只有满足以下条件时，才拆成子 wiki：

拆分后，parent wiki 应只保留总览、边界和导航，不要复制子页全文。重复内容越多，后续口径越容易分裂。

用 Skill 标准化建设过程

如果知识库要长期运行，不能完全依赖人工整理。建设和维护动作本身也应该标准化，让 Agent 能参与。

可以把流程拆成三类 Skill：

这样做的意义不只是提效，而是让产物格式稳定。无论来源是飞书文档、代码仓、oncall 记录还是会议纪要，最终进入知识库时都能落到同一套结构。

知识库也需要评测

知识库不是建完就算完成。它必须被评测，否则很难知道到底好不好用。

可以从四个维度看：

评测集最好来自真实场景：oncall 问题、业务问答记录、人工补充的边界题、长尾题、用户反馈记录。

当评测集成熟后，可以让专用 Agent 参与生成和维护。知识库的迭代就不再依赖偶发整理，而是能围绕问题闭环。

AI 应用不该只停留在“替换某个人工步骤”

当知识底座足够 AI-friendly 后，AI 应用的形态也会变化。

很多现有 AI 工具，本质是在旧流程里把某一步从人换成 AI。流程本身、权限边界、系统组织方式都没变。这样做当然能提效，但也容易把 AI 限制在“功能按钮”层面。

更值得探索的是：让 AI 承接一段完整工作。

例如，在 IM thread 里讨论需求，Agent 直接进入上下文，理解问题、定位相关模块、产出变更，人负责 review 和授权。thread 本身就是上下文，不需要额外整理一份很快过期的 PRD。

再比如 oncall 场景，Agent 不只是帮人查资料，而是先通过路由命中对应 wiki，再根据排查抓手拉日志、查配置、比对指标，给出初判，最后把确认后的经验回流到知识库。

这种形态的前提，是知识库能被 Agent 稳定读取和操作。否则 Agent 只能靠对话里临时提供的信息做一次性判断。

图：可靠知识底座让 Agent 从一次性问答走向完整工作闭环

AI-friendly 正在变成基础项

过去选工具，常常看人用起来是否顺手：界面好不好看，排版够不够丰富，协作体验是否流畅。

现在还要加一个新维度：Agent 能不能顺畅读取和操作。

有些工具对人很友好，但对 Agent 不友好。接口弱、结构不稳定、难检索、难自动修改。另一些工具也许视觉体验普通，但开放接口好、结构清楚、能被 MCP 或 API 稳定操作。随着越来越多工作变成人指挥 Agent 完成，后者的权重会越来越高。

放到知识库上，AI-friendly 意味着三类取舍：

但 AI-friendly 不等于去人化。

有些环节确实是历史包袱，比如纯粹为了人工流转而设计的中间步骤。模型和工具能力提升后，这些步骤可以重新审视。

但另一些环节承载的是人的判断、责任和品味，比如关键变更的 review、口径和边界的拍板、经验中的判断抓手。这些不但不能删，还应该做得更顺手。

合理的方向不是让机器替代一切，而是重新分工：

知识库的结构化、路由和开放格式，是为机器优化的。证据等级、待确认项、经验沉淀和风险判断，则必须把人保留在回路里。

结语

AI 时代的知识库，不应该只是文档仓库。它应该是一层可消费的知识底座。

这层底座要能让人读懂，也要让 Agent 读准；要能承载确定结论，也要标注不确定边界；要能记录业务知识，也要连接代码入口；要能被今天的工具使用，也要能随明天的系统迁移。

当知识本身变得结构化、可路由、可更新、可信度可判断，上层 AI 应用才不必每次从零开始猜。Agent 能做得多远，很多时候取决于组织把知识准备到了什么程度。

AI-friendly 不再只是加分项，而正在变成知识系统的基础项