KBC — Knowledge Base Construction

从源码自动构建设计知识库与故障排查知识库的 Agent Skill 工作流平台。

KBC 面向 AI 编码助手，通过递归扫描源码、确认模块和能力值命名、提炼架构与设计、分析故障路径，最终组装出可审计、可恢复的代码知识库。

特性

• 完整工作流：扫描、架构提炼、设计提取、故障提取、组装、完结六个阶段。
• 熔断确认：新模块、业务术语和能力值字段必须由用户确认，不自动猜名。
• 证据优先：设计和故障结论必须绑定源码、测试或 CodeGraph 证据。
• CodeGraph 集成：使用第三方 CodeGraph 查询符号、调用链、依赖和影响范围。
• 可恢复与可审计：状态、标签、阶段守卫、交接记录和原始查询证据均可保留。
• 跨平台部署：自动检测项目中已有的平台，再由用户选择要配置的平台。

工作流

/kbc-workflows
  |
  +-> /kbc-scan                 扫描源码，发现模块并确认命名
  +-> /kbc-arch-extract         提炼整体架构、能力值和业务术语
  +-> /kbc-design-extract       提取设计、组件、流程和配置知识
  +-> /kbc-troubleshoot-extract 提取错误、调用链和排查方法
  +-> /kbc-assemble             生成索引、交叉引用和注册表
  +-> /kbc-finish               完成质量检查和用户确认

后处理：
  +-> /kbc-revise               增量修订已有知识
  +-> /kbc-recode               完全重建已有知识

安装

前置要求：Node.js >=20.17.0、npm 或 pnpm。当前已在 Node.js v26.5.1 和 npm 11.17.0 上完成构建与 CLI 冒烟验证。

npm install -g @halfofpeotry/kbc

从源码安装：

cd knowledge-base-for-code
npm install
npm install -g .

快速开始

cd your-project
kbc init
kbc status

kbc init 会检测项目中已有的 AI 编程平台。交互模式允许选择平台；--yes 或 --json 模式只配置检测到的平台，不会默认配置全部平台。

指定平台：

kbc init --platform claude,cursor,github-copilot

当前平台定义如下。project 路径相对于项目根目录；global 路径相对于用户主目录。kbc init 会先检测这些路径，再由用户选择是否配置。

| 平台 ID | 平台名称 | Project Skills 目录 | Global Skills 目录 | |---------|----------|---------------------|-------------------| | claude | Claude Code | .claude/skills | .claude/skills | | cursor | Cursor | .cursor/skills | .cursor/skills | | codex | Codex | .agents/skills | .agents/skills | | opencode | OpenCode | .opencode/skills | .config/opencode/skills | | windsurf | Windsurf | .windsurf/skills | .windsurf/skills | | cline | Cline | .cline/skills | .cline/skills | | roocode | RooCode | .roo/skills | .roo/skills | | continue | Continue | .continue/skills | .continue/skills | | github-copilot | GitHub Copilot | .github/skills | .github/skills | | gemini | Gemini CLI | .gemini/skills | .gemini/skills | | amazon-q | Amazon Q Developer | .amazonq/skills | .amazonq/skills | | qwen | Qwen Code | .qwen/skills | .qwen/skills | | kilocode | Kilo Code | .kilocode/skills | .kilocode/skills | | auggie | Auggie | .augment/skills | .augment/skills | | kiro | Kiro | .kiro/skills | .kiro/skills | | kimicode | Kimi Code | .kimi-code/skills | .kimi-code/skills | | lingma | Lingma | .lingma/skills | .lingma/skills | | junie | Junie | .junie/skills | 由平台定义 | | codebuddy | CodeBuddy Code | .codebuddy/skills | .codebuddy/skills | | costrict | CoStrict | .cospec/skills | 由平台定义 | | crush | Crush | .crush/skills | 由平台定义 | | factory | Factory Droid | .factory/skills | 由平台定义 | | iflow | iFlow | .iflow/skills | 由平台定义 | | pi | Pi | .pi/skills | .pi/agent/skills | | qoder | Qoder | .qoder/skills | .qoder/skills | | antigravity | Antigravity | .agents/skills | .gemini/antigravity/skills | | antigravity2 | Antigravity 2.0 | .agents/skills | .gemini/config/skills | | bob | Bob Shell | .bob/skills | 由平台定义 | | forgecode | ForgeCode | .forge/skills | 由平台定义 | | trae | Trae | .trae/skills | .trae/skills | | trae-cn | Trae CN | .trae-cn/skills | .trae-cn/skills | | zcode | ZCode | .zcode/skills | .zcode/skills | | mimocode | MimoCode | .mimocode/skills | .config/mimocode/skills |

部分平台的全局路径由平台自身决定，KBC 会使用平台定义的默认目录；具体行为以 kbc status 和平台文档为准。

初始化完成后，在 AI 编辑器中使用 /kbc-workflows 启动工作流。

CLI

kbc init [path]

检测平台并部署 Skills，同时可配置 CodeGraph。

| 选项 | 说明 | |------|------| | --yes | 非交互模式，只配置检测到的平台 | | --skip-existing | 跳过已存在的文件 | | --overwrite | 覆盖已管理文件 | | --json | 输出 JSON | | --skip-codegraph | 跳过 CodeGraph 安装和初始化 | | --platform <platforms> | 逗号分隔的平台 ID | | --scope <scope> | project 或 global | | --language <lang> | en 或 zh |

kbc status [path]

显示每个平台的实际安装状态以及当前 KBC session：

kbc status --json

kbc resolve-probe [path]

检测当前目录是否存在可恢复的 KBC session：

kbc resolve-probe --json

kbc deploy 已移除。部署统一通过 kbc init 完成。

CodeGraph

KBC 使用第三方 CodeGraph 作为代码语义索引和查询工具。KBC 不把 CodeGraph 输出直接当作最终知识，而是将其作为候选证据，再回到源码、配置和测试进行核验。

在 project scope 下，初始化会执行：

codegraph install --yes
codegraph init -i

CodeGraph 提供：

| 能力 | 用途 | |------|------| | status | 检查索引是否存在以及索引统计 | | query | 查询函数、类、接口、错误类型等符号 | | explore | 查看相关源码、调用路径和依赖关系 | | node | 查看符号源码、调用者和被调用者 | | impact | 分析符号变更影响范围 |

KBC CodeGraph 封装

KBC 通过 kbc-codegraph.mjs 统一传递项目路径、检查索引、调用 CodeGraph 并保存原始结果：

KBC_ENV="$(find . -path '*/skills/kbc-workflows/scripts/kbc-env.mjs' -type f -print -quit)"
KBC_SCRIPTS_DIR="$(node "$KBC_ENV")"
KBC_CODEGRAPH="$KBC_SCRIPTS_DIR/kbc-codegraph.mjs"

node "$KBC_CODEGRAPH" status --project "$SOURCE_DIR"
node "$KBC_CODEGRAPH" ensure-index --project "$SOURCE_DIR"
node "$KBC_CODEGRAPH" explore "模块入口和生命周期是什么？" --project "$SOURCE_DIR" --label design-lifecycle
node "$KBC_CODEGRAPH" impact "核心故障符号" --project "$SOURCE_DIR" --label troubleshoot-impact

原始证据默认保存到：

knowledge-base/.evidence/codegraph/

每个证据文件保存项目路径、命令、查询结果、标准错误、状态码和采集时间。封装脚本只负责确定性工具调用，不生成设计或故障结论。

选择 CodeGraph 的好处

• 关系更准确：相比目录名和关键词，CodeGraph 能追踪符号引用、调用者、被调用者和接口实现。
• 减少遗漏：可以发现跨文件、跨模块的依赖和错误传播路径。
• 支持影响分析：故障提取可以从错误符号追踪调用方和受影响文件。
• 便于复核：原始输出被保存，后续可以检查模型是否正确理解了工具结果。
• 降低幻觉：模型不能凭经验补写设计模式、根因、错误码、日志或修复步骤。

CodeGraph 不替代源码阅读，也不自动生成知识库。它提供结构化证据，最终结论必须由源码、配置、测试或可复现行为确认。

证据状态

设计和故障文档使用以下核验状态：

• 源码已证实：有明确源码、配置、测试或运行结果。
• CodeGraph 已发现但待源码核验：工具发现了关系，但还不能作为最终事实。
• 未确认：证据不足，必须列出待补查文件，不得使用推测性措辞伪装成结论。

第三方工具边界

| 组件 | 职责 | |------|------| | KBC CLI | 初始化、平台检测、Skill 部署和状态查询 | | KBC Skills | 工作流阶段、源码分析任务、命名确认和知识库组织 | | CodeGraph | 代码索引、符号关系、调用链、依赖和影响分析 | | Commander.js | CLI 命令和参数解析 | | @inquirer/prompts | 平台、安装模式和范围的交互选择 |

KBC 的状态、标签、阶段守卫和恢复脚本不直接生成 CodeGraph 结论；CodeGraph 的调用和证据归档由 kbc-codegraph.mjs 统一处理。

核心脚本

KBC_SCRIPTS_DIR="$(node path/to/kbc-env.mjs)"

node "$KBC_SCRIPTS_DIR/kbc-state.mjs" init <source-dir> [output-dir]
node "$KBC_SCRIPTS_DIR/kbc-state.mjs" get [key]
node "$KBC_SCRIPTS_DIR/kbc-state.mjs" set <key> <value>
node "$KBC_SCRIPTS_DIR/kbc-guard.mjs" <phase> [--apply]
node "$KBC_SCRIPTS_DIR/kbc-handoff.mjs" <target-phase> [--write]
node "$KBC_SCRIPTS_DIR/kbc-resume-probe.mjs" [path]
node "$KBC_SCRIPTS_DIR/kbc-tags.mjs" dump
node "$KBC_SCRIPTS_DIR/kbc-codegraph.mjs" ensure-index --project <source-dir>

输出目录

<output-dir>/
  index.md                         # 知识库总入口，链接架构、设计和故障文档
  kbc-state.json                   # 工作流状态、模块、能力值、术语和当前阶段
  .kb/                             # KBC 运行时元数据，不是业务知识正文
    tags.json                      # 已确认名称和标签索引
    guard-<phase>.json             # 阶段守卫检查结果和证据
    handoff-<phase>.json           # 阶段交接记录和下一阶段信息
  .evidence/                       # 外部工具原始证据
    codegraph/                     # CodeGraph 查询结果，供模型和人工复核
      <timestamp>-<label>.json     # 单次查询的命令、路径、输出和状态码
  architecture/                    # 整体架构知识，不按单个设计点分散
    index.md                       # 架构目录和入口
    overview.md                    # 分层、边界和总体职责
    module-relations.md            # 模块调用、依赖和关系图
    capability-fields.md           # 能力值字段注册表
    business-terms.md              # 业务术语字典
    data-flow.md                   # 关键数据流和处理链路
  design/                          # 设计知识库
    index.md                       # 所有模块设计文档总目录
    <module-name>/                 # 一个已确认名称对应一个模块目录
      index.md                     # 模块设计导航
      design.md                    # 模块设计要点、组件和生命周期
      capabilities.md              # 模块涉及的能力值和配置字段
      components/                  # 可选：重要组件的详细设计
      flows/                       # 可选：关键流程的详细设计
  troubleshooting/                 # 故障排查知识库
    index.md                       # 所有模块故障文档总目录
    <module-name>/                 # 与 design 使用相同的模块确认名称
      index.md                     # 模块故障排查导航
      common-errors.md             # 常见错误、触发条件、证据和解决方案
      debugging-guide.md           # 调试入口、日志和排查路径
      checklists.md                # 可执行的排查清单
      cases/                       # 可选：可复用的具体故障案例

<output-dir> 默认是项目下的 knowledge-base/。平台 Skills 部署目录（例如 .github/skills）属于项目配置，不是知识库输出目录；CodeGraph 原始证据则保存在 <output-dir>/.evidence/codegraph/。

GitHub 开源与共创

KBC 计划发布到 GitHub，目标是把“从源码构建设计知识和故障知识”的流程沉淀为可复用、可审计的社区工具。项目目前重点欢迎以下类型的共创：

| 共创方向 | 可以贡献什么 | |----------|--------------| | 新平台适配 | 新 AI 编程平台的 Skills 目录、检测路径和全局目录验证 | | Skill 优化 | 改进扫描、架构、设计、故障提取中的提示、证据约束和产出模板 | | CodeGraph 集成 | 查询模板、证据归档、索引检查和不同语言项目的验证 | | 知识库质量 | 完善阶段守卫、交叉引用、能力值字段和故障案例检查 | | 测试与兼容性 | Node.js、操作系统、包管理器和 AI 编辑器平台的安装测试 | | 文档与示例 | 快速开始、真实项目示例、迁移指南和中文/英文文档 |

如何参与

1. Fork 仓库并创建分支：feature/<topic>、fix/<topic> 或 docs/<topic>。

2. 先阅读对应 Skill 和 脚本说明，理解状态、守卫和证据约束。

3. 对行为变更补充测试或可复现命令，尤其是平台检测、目录部署和 CodeGraph 查询。

4. 运行构建、测试和 lint：

   npm run build
   npm test
   npm run lint

5. 在 Pull Request 中说明：变更目的、影响的平台或 Skill、验证环境、CodeGraph 版本，以及是否改变输出格式。

共创原则

• 不提交真实项目源码、密钥、内部路径或未经脱敏的 CodeGraph 证据。
• 新平台支持必须提供实际目录验证，不只根据平台名称猜测路径。
• Skill 的新结论必须有源码、测试或 CodeGraph 证据，未知内容明确标记为“未确认”。
• 修改状态字段、阶段守卫或证据格式时，同时更新参考文档和示例。
• 保持小而聚焦的 Pull Request，便于审查和回滚。

Issue、Pull Request、平台兼容性反馈和真实使用案例，都是对 KBC 很有价值的共创方式。

设计原则

1. 熔断优先：新模块、业务术语和能力值字段必须确认，不猜测。
2. 递归完整：扫描所有有效源码目录，排除构建产物和依赖目录。
3. 名称一致：确认后的名称在状态、标签和全部文档中保持一致。
4. 证据优先：CodeGraph 结果必须回到源码核验。
5. 状态驱动：阶段状态由 kbc-state.json 管理，守卫通过后才能推进。
6. 可审计：保留状态、标签、守卫、交接和 CodeGraph 原始证据。
7. 可恢复：中断后通过恢复探针继续未完成阶段。

开发验证

npm run build
npm test
npm run lint

KBC CLI 的实测流程包括：安装本地包、运行 kbc --help、运行 kbc status --json、检测平台、部署 Skills、检查目录层级，以及执行 codegraph install --yes 和 codegraph init -i。

参考文档

• 包说明
• 状态字段
• 脚本说明
• 阶段过渡
• 上下文恢复
• 熔断决策
• 并行分发
• 文件结构