代码会不断变化但团队对代码的理解不应该每次都从零开始。我正在做一个开源项目 KBC希望和更多开发者一起把“让 AI 读懂代码”进一步变成“让团队持续拥有一套可信、可维护的代码知识库”。项目地址https://github.com/HalfOfPoetry/knowledge-base-for-code一、我为什么要做 KBC在使用 AI 编程助手的过程中我经常遇到一个问题AI 可以很快回答某个函数“做了什么”但当问题变成下面这些内容时答案就容易变得不稳定这个模块在整个系统中的位置是什么某个配置项到底在哪里读取又如何影响运行行为一个错误是在哪里产生的经过哪些调用链传播修改一个核心符号会影响哪些模块新同事应该从哪里开始理解这个项目如果只是临时问一次 AI答案通常会随着上下文、模型和提问方式变化。更麻烦的是一些看起来合理的内容可能只是模型根据经验补出来的并没有源码证据。所以我想做的不是一个“问答机器人”而是一套从源码持续构建设计知识库和故障排查知识库的工作流。这就是 KBCKnowledge 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 与 LLMLLM 很擅长总结和解释但如果没有流程约束容易出现几个问题跳过源码读取直接根据文件名猜测职责忽略已有模块名称重新创造一套命名把“可能的设计模式”写成确定事实把一次调用关系误写成完整的运行时因果忘记生成某些必需文档或更新状态。KBC Skills 的作用就是把这些容易被忽略的步骤显式化。LLM 仍然负责理解和归纳但必须沿着 Skill 规定的路径工作并遵守用户确认和证据核验规则。Skills 与 RAGRAG 通常解决的是上下文检索问题例如从已有文档中找到某个模块的说明、业务术语或历史故障案例。但 RAG 不能自动保证检索到的内容仍然适用于当前源码。旧文档可能已经过时模块可能已经重构术语也可能发生变化。因此 KBC 将 RAG 能力拆成两部分来使用读取已有知识读取kbc-state.json、.kb/tags.json、架构文档、设计文档和历史故障记录。回到当前源码核验使用 CodeGraph 和源码阅读确认当前实现是否仍然一致。这意味着 RAG 提供的是“历史上下文”而不是无需验证的最终答案。Skills 与 CodeGraphSkill 会定义什么时候调用 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.mjsnode$KBC_CODEGRAPHensure-index--project$SOURCE_DIRnode$KBC_CODEGRAPHexplore\模块入口和生命周期是什么\--project$SOURCE_DIR\--labeldesign-lifecycle原始证据默认保存在knowledge-base/.evidence/codegraph/证据记录会保留项目路径、命令、查询内容、原始输出、错误输出、状态码和采集时间。这样后续可以回头检查AI 的结论到底有没有依据。七、一次 KBC 初始化会做什么首先安装 KBCnpminstall-ghalfofpeotry/kbc然后进入目标项目cdyour-project kbc initKBC 会自动检测项目中已有的 AI 编程平台再由用户选择实际要配置的平台而不是默认把所有平台都写入项目。非交互模式可以使用kbc init--yes--json也可以明确指定平台kbc init--platformclaude,cursor,github-copilot初始化后可以使用kbc status kbc status--jsonkbc resolve-probe--json如果选择安装 CodeGraphproject 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 gitgithub.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 和我一起共创 KBCHalfOfPoetry/knowledge-base-for-code让 AI 帮我们更快读懂代码也让团队真正留下可以复用的知识。