代码会不断变化，但团队对代码的理解不应该每次都从零开始。
我正在做一个开源项目 KBC，希望和更多开发者一起，把“让 AI 读懂代码”进一步变成“让团队持续拥有一套可信、可维护的代码知识库”。
项目地址：
https://github.com/HalfOfPoetry/knowledge-base-for-code
一、我为什么要做 KBC
在使用 AI 编程助手的过程中，我经常遇到一个问题：AI 可以很快回答某个函数“做了什么”，但当问题变成下面这些内容时，答案就容易变得不稳定：
- 这个模块在整个系统中的位置是什么？
- 某个配置项到底在哪里读取，又如何影响运行行为？
- 一个错误是在哪里产生的，经过哪些调用链传播？
- 修改一个核心符号，会影响哪些模块？
- 新同事应该从哪里开始理解这个项目？
如果只是临时问一次 AI，答案通常会随着上下文、模型和提问方式变化。更麻烦的是，一些看起来合理的内容可能只是模型根据经验补出来的，并没有源码证据。
所以我想做的不是一个“问答机器人”，而是一套从源码持续构建设计知识库和故障排查知识库的工作流。
这就是 KBC：Knowledge Base Construction。
二、KBC 是什么
KBC 是一套面向 AI 编码助手的 Agent Skill 工作流平台。它把代码理解拆成多个阶段，让 AI 不只是回答问题，而是按照固定流程完成源码走读、证据记录和文档组织。
核心流程是：
扫描源码 -> 确认模块和业务术语 -> 提炼整体架构 -> 提取模块设计 -> 提取故障排查知识 -> 组装索引和交叉引用 -> 完成质量检查对应的 Skills 包括：
/kbc-scan /kbc-arch-extract /kbc-design-extract /kbc-troubleshoot-extract /kbc-assemble /kbc-finish另外还提供两个后处理 Skill：
/kbc-revise 增量修订已有知识 /kbc-recode 完全重建已有知识三、Skills 在智能体中的作用
我希望特别说明一点：KBC 里的 Skill 不是普通的提示词集合，也不是把几段命令简单拼在一起。
在我的设计中，Skill 更像是给智能体提供的一套“工作方法”和“阶段合同”，它会告诉智能体：
- 当前阶段要解决什么问题；
- 需要先读取哪些状态和历史记录；
- 哪些内容必须向用户确认；
- 应该使用哪些工具和查询方式；
- 产出哪些文档和结构化记录；
- 什么条件满足后才能进入下一阶段；
- 哪些内容没有证据时必须标记为“未确认”。
例如，/kbc-design-extract并不是简单地让 LLM “写一份设计文档”，而是约束智能体先读取模块名称、能力值字段和业务术语，再使用 CodeGraph 查询入口、组件协作、生命周期和配置读取路径，最后回到源码核验并生成文档。
所以，Skills 在智能体中的作用可以概括为：
Skill = 目标 + 流程 + 工具调用规则 + 证据要求 + 输出格式 + 阶段约束它把一次性、容易漂移的自然语言对话，变成可以重复执行、可以中断恢复、可以检查结果的工程流程。
四、KBC、LLM、RAG 和 CodeGraph 如何分工
我把 KBC 看成连接 LLM、RAG 和代码工具的一层工作流系统，而不是试图替代其中任何一个组件。
| 组成部分 | 主要职责 | 在 KBC 中的定位 |
|---|---|---|
| LLM | 理解自然语言、归纳证据、解释设计和故障 | 负责在证据基础上形成可读知识 |
| Agent | 规划步骤、调用工具、读写文件和推进流程 | 执行 KBC Skills 定义的工作流 |
| Skills | 提供任务目标、阶段规则、工具流程和输出要求 | 约束 Agent 如何完成知识提取 |
| CodeGraph | 建立代码索引，查询符号、调用链和影响范围 | 提供代码结构证据 |
| RAG | 从已有知识中检索相关上下文 | 提供历史知识、术语和已确认记录 |
| KBC Runtime | 管理状态、标签、守卫和阶段交接 | 保证流程可恢复、可审计 |
这几个部分解决的问题并不相同：
RAG 解决“过去记录过什么” CodeGraph 解决“代码之间实际有什么关系” LLM 解决“如何理解和表达这些证据” Skills 解决“应该按什么流程理解，哪些结论允许写入” KBC Runtime 解决“流程走到哪里，是否满足进入下一阶段的条件”Skills 与 LLM
LLM 很擅长总结和解释，但如果没有流程约束，容易出现几个问题：
- 跳过源码读取，直接根据文件名猜测职责；
- 忽略已有模块名称，重新创造一套命名；
- 把“可能的设计模式”写成确定事实；
- 把一次调用关系误写成完整的运行时因果；
- 忘记生成某些必需文档或更新状态。
KBC Skills 的作用，就是把这些容易被忽略的步骤显式化。LLM 仍然负责理解和归纳，但必须沿着 Skill 规定的路径工作，并遵守用户确认和证据核验规则。
Skills 与 RAG
RAG 通常解决的是上下文检索问题，例如从已有文档中找到某个模块的说明、业务术语或历史故障案例。
但 RAG 不能自动保证检索到的内容仍然适用于当前源码。旧文档可能已经过时，模块可能已经重构，术语也可能发生变化。
因此 KBC 将 RAG 能力拆成两部分来使用：
- 读取已有知识：读取
kbc-state.json、.kb/tags.json、架构文档、设计文档和历史故障记录。 - 回到当前源码核验：使用 CodeGraph 和源码阅读确认当前实现是否仍然一致。
这意味着 RAG 提供的是“历史上下文”，而不是无需验证的最终答案。
Skills 与 CodeGraph
Skill 会定义什么时候调用 CodeGraph、查询什么问题、如何保存证据，以及如何将结果和源码交叉核验。
例如故障提取阶段不会只问一次“这个模块有什么问题”，而是要求智能体分别查询：
错误处理入口 异常传播路径 错误类型或错误码的产生位置 调用方和被调用方 核心符号的影响范围这样做的重点不是增加调用次数，而是让每个查询都对应一个明确的知识目标，减少大模型在宽泛问题中自行补全信息的空间。
五、KBC 为什么要结合 CodeGraph
传统的目录扫描和关键词搜索很适合做第一步发现，但它们很难回答真正的代码关系问题。
例如，某个函数可能：
- 在另一个目录被间接调用；
- 实现了某个接口，但文件名中没有明显提示；
- 通过多层封装影响一个配置流程；
- 在错误处理路径中被多个模块共同依赖。
因此，KBC 使用第三方 CodeGraph 建立代码索引，并辅助查询：
| CodeGraph 能力 | 在 KBC 中的用途 |
|---|---|
status | 检查项目索引是否存在和完整 |
query | 查询函数、类、接口和错误类型 |
explore | 查看相关源码、调用路径和依赖关系 |
node | 查看符号源码、调用者和被调用者 |
impact | 分析修改某个符号的影响范围 |
CodeGraph 的价值不在于替 AI 直接写结论，而在于给 AI 提供更可靠的结构化证据。
六、我如何降低 AI 的“幻觉”
这是 KBC 中我比较重视的一部分。
我没有让模型拿到一次explore输出后就直接生成最终文档，而是设计了证据优先的约束：
- 结论必须绑定源码文件、符号、配置键、测试或 CodeGraph 查询结果。
- CodeGraph 发现的关系必须回到源码核验。
- 静态调用关系不能直接被描述成确定的运行时因果。
- 无法确认的内容必须标记为“未确认”。
- 设计模式、根因、错误码、日志和修复步骤不能凭经验补写。
KBC 还提供了kbc-codegraph.mjs封装脚本，统一处理项目路径、索引检查、查询调用和原始证据保存：
KBC_ENV="$(find.-path'*/skills/kbc-workflows/scripts/kbc-env.mjs'-typef-print-quit)"KBC_SCRIPTS_DIR="$(node"$KBC_ENV")"KBC_CODEGRAPH="$KBC_SCRIPTS_DIR/kbc-codegraph.mjs"node"$KBC_CODEGRAPH"ensure-index--project"$SOURCE_DIR"node"$KBC_CODEGRAPH"explore\"模块入口和生命周期是什么？"\--project"$SOURCE_DIR"\--labeldesign-lifecycle原始证据默认保存在：
knowledge-base/.evidence/codegraph/证据记录会保留项目路径、命令、查询内容、原始输出、错误输出、状态码和采集时间。这样后续可以回头检查：AI 的结论到底有没有依据。
七、一次 KBC 初始化会做什么
首先安装 KBC：
npminstall-g@halfofpeotry/kbc然后进入目标项目：
cdyour-project kbc initKBC 会自动检测项目中已有的 AI 编程平台，再由用户选择实际要配置的平台，而不是默认把所有平台都写入项目。
非交互模式可以使用：
kbc init--yes--json也可以明确指定平台：
kbc init--platformclaude,cursor,github-copilot初始化后，可以使用：
kbc status kbc status--jsonkbc resolve-probe--json如果选择安装 CodeGraph，project scope 下会执行：
codegraphinstall--yescodegraph init-i目前 KBC 已支持多类 AI 编程平台，包括 Claude Code、Cursor、Codex、OpenCode、Windsurf、Cline、RooCode、Continue、GitHub Copilot、Gemini CLI、Amazon Q、Qwen Code、Kiro、Pi、Qoder、Trae 等。
八、最终会生成什么
默认知识库输出目录是项目下的knowledge-base/：
knowledge-base/ index.md # 知识库总入口 kbc-state.json # 工作流状态和模块注册信息 .kb/ # 标签、守卫和阶段交接记录 .evidence/codegraph/ # CodeGraph 原始查询证据 architecture/ # 整体架构知识 design/ # 模块设计知识 troubleshooting/ # 故障排查知识设计知识库重点记录：
- 模块职责和边界；
- 组件划分；
- 数据流和生命周期；
- 对外接口和依赖关系；
- 配置项和能力值字段；
- 关键流程和设计依据。
故障知识库重点记录：
- 常见错误和触发条件；
- 错误产生、传播和处理路径；
- 日志与调试入口；
- 配置、权限、容量相关问题；
- 可执行的排查清单；
- 已验证的解决方案和证据。
九、我希望和大家一起共创什么
KBC 还处在持续迭代阶段，我不希望它只是一个“我自己定义好的工具”，更希望它能吸收真实项目和真实开发流程中的反馈。
我目前最欢迎以下方向的贡献：
| 共创方向 | 可以参与的内容 |
|---|---|
| 新平台适配 | 增加 AI 编程平台目录、检测路径和安装验证 |
| Skill 优化 | 改进扫描、架构、设计和故障提取流程 |
| CodeGraph 集成 | 优化查询模板、证据归档和不同语言项目的分析方式 |
| 知识库质量 | 完善阶段守卫、交叉引用和完整性检查 |
| 测试兼容性 | 验证不同 Node.js、操作系统和 AI 编辑器环境 |
| 文档示例 | 增加真实项目、迁移指南和中英文使用示例 |
特别欢迎三类反馈：
- 你在使用 AI 阅读大型项目时遇到过什么问题？
- 哪些设计知识或故障知识最值得自动沉淀？
- CodeGraph 在你的语言或项目类型中，哪些查询最有价值？
十、如何参与
项目 GitHub 地址：
https://github.com/HalfOfPoetry/knowledge-base-for-code
欢迎大家：
- Star 项目，帮助更多人发现 KBC；
- 提交 Issue，分享问题和使用场景；
- 提交 Pull Request，贡献代码、Skill、测试或文档；
- 分享不同语言、不同规模项目中的验证结果。
参与开发前，可以先运行：
gitclone git@github.com:HalfOfPoetry/knowledge-base-for-code.gitcdknowledge-base-for-codenpminstallnpmrun build提交变更前建议执行：
npmrun buildnpmtestnpmrun lint如果是平台适配或 CodeGraph 相关变更，请在 Pull Request 中说明：
- 测试的平台和版本；
- Node.js 版本；
- CodeGraph 版本；
- 实际生成的目录；
- 是否有原始查询证据；
- 是否改变了现有知识库格式。
十一、写在最后
我做 KBC 的初衷很简单：我希望 AI 不只是“看过代码”，而是能帮助团队把代码背后的设计、依赖、风险和排查经验真正沉淀下来。
AI 可以提高理解代码的速度，但可信的知识仍然需要证据、复核和持续维护。
如果你也在思考如何让 AI 更可靠地参与大型项目理解，欢迎来 GitHub 和我一起共创 KBC：
HalfOfPoetry/knowledge-base-for-code
让 AI 帮我们更快读懂代码，也让团队真正留下可以复用的知识。
