从代码到文档，从模块到流程，构建高效知识库的实战经验分享。
核心内容：
1. 内网数据与工具选型的关键考量
2. 从业务代码提取功能说明的方法
3. 模块文档与流程关联的双层结构设计

最近在做一个项目知识库，过程中积累了一些体会。

最开始想到的是选什么产品、怎么部署。实际做起来后才发现，平台反而可以往后放。更需要先想清楚的是：现有资料能不能用，缺失的资料怎么补，以及这个知识库究竟给谁使用。

一、内网数据决定了知识库的建设方式

有些项目的业务数据和代码都在内网，受安全要求限制，不能传到外部。这类项目使用乐享等需要联网的知识库产品并不方便，也容易带来数据安全问题。

一种解决方式是私有化部署 Dify，把文档、数据和模型调用都留在内部环境中。

不过，私有化部署需要准备服务器、模型、向量数据库，还要处理权限和后续维护。对于刚开始建设知识库的团队来说，这些工作可能比整理知识本身还费时间。

因此，工具选型需要结合项目实际情况。知识库规模较大、使用人数较多时，可以考虑 Dify 这类完整的平台。知识主要服务开发人员时，还有更轻的做法，后面会具体说到。

二、业务文档缺失，可以从代码中找回来

很多运行多年的项目都有类似问题：代码还在，系统也能正常使用，但早期的需求文档、设计文档已经找不到了。

这会直接影响知识库的质量。知识库里没有足够的信息，AI 自然无法给出准确回答。

遇到这种情况，可以从业务代码中提取功能逻辑，重新整理成说明文档。至少在系统当前如何运行这件事上，代码通常是最完整、最准确的信息来源。

这里说的提取，并不是简单地把代码注释复制出来，而是把代码逻辑翻译成更容易理解的功能说明。比如：

• 这个模块负责什么业务
• 功能从哪里进入
• 一次操作会经过哪些步骤
• 中间有哪些判断条件
• 会产生哪些状态变化
• 异常情况如何处理
• 使用了哪些数据
• 与其他模块有什么关系

整理完成后，一个原本只能靠人读代码才能理解的业务模块，就有了一份相对完整的功能说明。新接手项目的人可以先看文档，再进入代码，理解成本会低很多。AI 也能根据这些内容回答更具体的问题。

当然，代码主要记录系统如何执行，部分业务背景和设计原因未必能从代码中找到。对于这部分内容，可以请熟悉业务的人补充。暂时无法确认的地方，也可以明确标记出来。

三、功能模块文档和关联说明需要配合使用

一个大型项目通常包含多个业务模块。单独整理每个模块，只能解决局部理解问题。AI 知道某个功能怎么运行，却未必知道它在整个业务流程中处于什么位置。

我比较倾向于把文档分成两层。

第一层是功能模块说明。每个模块单独整理，把业务规则、处理流程、数据变化和异常情况写清楚。

第二层是模块关联和使用指南。它负责说明各个模块之间的关系，以及一次完整的业务操作会经过哪些模块。

比如，订单创建之后会进入哪个模块，库存什么时候扣减，审批结果如何影响订单状态，结算数据从哪里产生。把这些关系串起来之后，AI 才能理解整个业务链路。

有了这两层内容，查询某个功能时可以看模块说明，查询跨模块流程时可以看关联指南。文档之间各有分工，也更容易维护。

四、相关数据可以整理成 JSONL

功能说明和使用指南适合使用 Markdown 编写。对于业务规则、常见问题、接口示例、异常案例等相对独立的数据，可以进一步整理成 JSONL 格式。

每一行保存一条完整信息，并补充所属模块、内容类型和来源等字段。例如：

{”module”:”订单”,”type”:”业务规则”,”question”:”什么情况下订单会自动关闭”,”answer”:”待支付订单超过规定时间后自动关闭”,”source”:”OrderTimeoutService”}

这种格式方便程序处理，也方便 AI 按条读取和检索。后续增加新内容时，直接追加记录即可。

格式本身并不复杂，重点是每条内容都要尽量完整。只记录一个结论，却没有适用条件和来源，AI 使用时仍然容易产生误解。

五、大项目先确定知识库给谁使用

对于一个大型项目，建设知识库之前，先看它面向哪些用户。

如果主要面向项目的开发和维护人员，一开始就把所有业务放进同一个知识库，实际效果未必理想。项目越大，业务之间的差异越明显，资料放在一起后，检索结果也容易互相干扰。

开发人员平时的工作往往集中在某几个业务模块。负责订单的人主要查询订单规则，负责结算的人更关心账单和对账流程。每个人真正需要的知识，只是整个项目的一部分。

基于这一点，可以把复杂业务拆成多个独立的小知识库。每个知识库对应一个业务领域，内容尽量做细，既包括功能说明，也包括模块关系和常见问题。

这种拆分方式还有一个好处，就是权限更容易管理。不同职责的人可以访问与工作相关的知识库，涉及敏感数据的业务模块也能单独控制。

六、小而完整的知识库更容易发挥作用

知识库的价值和文档数量没有直接关系。一个范围较小、内容足够细的知识库，已经可以帮助 AI 完成很多工作。

它可以回答某个业务规则如何实现，也可以帮助开发人员找到相关代码。遇到线上问题时，还能根据模块关系梳理排查路径。

相比之下，把大量零散文档放在一起，看起来内容很多，真正查询时却经常找不到准确答案。与其一开始覆盖整个项目，不如先选择一个复杂、维护频繁的业务模块，把这部分知识整理扎实。

等这个小知识库能够稳定解决实际问题，再用同样的方式扩展到其他业务。这样更容易验证效果，也能及时调整文档结构。

七、起步阶段可以直接结合 Claude Code 或 Codex 使用

知识内容整理好以后，最简单的方式可能并不是马上部署一套私有化 Dify，也不一定需要把文档搬进现有的知识库产品。

如果使用者主要是开发人员，可以把 Markdown、JSONL 和代码放在同一个项目目录中，再通过 Claude Code 或 Codex 直接使用。

AI 可以读取功能文档，也可以结合代码分析。文档里写清楚业务逻辑，代码里保留具体实现，两部分内容可以相互补充。

这种方式基本不改变开发人员原来的工作习惯，也省去了知识库平台的部署和维护工作。前提是所使用的模型、账号和数据链路符合公司的安全要求。

当知识库的使用范围扩大，出现统一检索、多人协作和更复杂的权限需求时，再考虑引入 Dify 等平台会更合适。

八、用 Git 或 SVN 管理知识更新

知识库整理完成之后，还需要考虑更新问题。

业务会变化，代码也会调整。如果知识文档一直停留在最初版本，很快就会和实际系统脱节。

由于这些知识本身就是 Markdown、JSONL 等文件，可以直接使用 Git 或 SVN 管理。每次功能修改时，同步更新对应的模块文档和关联说明。通过版本记录，也能看到文档改了什么、由谁修改，以及为什么修改。

知识库和代码放在一起还有一个实际好处：开发人员修改业务逻辑时，更容易顺手检查相关文档。时间长了，更新文档会逐渐变成开发流程的一部分，而不是项目结束后再补的一项工作。

写在最后

回头看这次知识库建设，我最大的感受是，知识库首先是知识整理问题，其次才是平台问题。

内部资料无法外传，就在合规的环境中处理。业务文档丢失，就从代码中还原功能逻辑。大型项目内容太多，就按业务模块拆分，并根据使用者控制权限。文档有变化，就交给 Git 或 SVN 管理。

第一版知识库也不必做得很大。先选一个复杂业务，把功能逻辑、模块关系和相关数据整理清楚，再交给 AI 使用。

如果它能让新接手项目的人少翻几天代码，让维护人员更快找到问题，这个知识库就已经发挥作用了。

登录查看剩余 70% 内容