中文 | English
一个 Claude Code plugin:为 code agent 提供分层知识地图索引——让人 5 分钟看懂全局框架,agent 能渐进式下钻到真实代码。
knowledge-map 是一个 Claude Code plugin(skill + slash 命令 + hooks)。给它一个或多个代码仓库,产出一套四层可下钻的知识地图:
| 层 | 内容 |
|---|---|
| L0 全局总图 | 子系统/服务依赖图 + 架构图 + 部署图 + 业务域划分 |
| L1 概览 | 每个服务/子系统的边界、对外接口、上下游、存储 |
| L2 模块地图 | 模块依赖图 + 核心业务流程图 / 时序图 / 状态机 |
| L3 实现细节 | agent 按需下钻现场读真实代码(不预生成成文档) |
双受众,agent 优先:
- 给人看(框架文档 L0/L1/L2 热点):讲清基本逻辑,容许粗,不强求细节 100% 精准。
- 给 agent 用(
graph.json+cite+audit+importMap):精确、可下钻、可验证。每条 cite 精确到行,经 tree-sitter AST 校验,不是 AI 凭直觉编的。
- agent 优先 + 渐进式下钻:
graph.json+cite是 agent 的索引,按需读真实代码;L2/L3 逐行细节不预生成,现场读。 - 增量更新(fingerprint):
update.py比对文件 sha256,只重抽脏文件;结构性变化(顶层服务增删 OR 节点>8 OR 边>15)才刷框架文档。 - 图内部一致性(D 关):audit 验节点 id 唯一 / 边端点存在(硬失败)+ 孤儿(软警告)——agent 据此决策不会踩空。
- importMap 预解析:
imports.json给 agent 下钻路径 + 增量影响传播。 - 分层探测 + 归一化:Greptile / Sourcegraph / tree-sitter,换工具不换产物;grep/rg 兜底。
- 双向迭代收敛:骨架假设 → 下探取证 → 回写修正 L0 → 收敛。
- 查询回写(沉淀页 deep-dives):下钻验证过的问答成果持久化为
deep-dives/页,cite 由 audit 持续验真——知识复利,而非每次重算。 - 新鲜度锚点 + 操作日志:manifest 记
built_at_commit(commit 级新鲜度提示),log.mdappend-only 时间线可追溯每次 build/update。 - 触发四层:skill 自动 +
/km-build/km-update+ SessionStart/Stop hooks + 脚本退出码门禁。 - 质量保证(audit 门禁):文件系统当绝对标尺,覆盖完备 + cite 验真 + 规模实测,exit 0 才交付。
推荐(plugin,自动注册 skill + slash 命令 + hooks):
/plugin marketplace add beihai23/knowledge-map
/plugin install knowledge-map@beihai23-knowledge-map
安装后:/km-build(全量生成)、/km-update(增量更新)直接可用,skill 自动加载,SessionStart/Stop hooks 自动生效。
plugin 装完是起点,不是终点 —— 默认走 Tier 3(grep 兜底,零依赖,装即用),但强烈建议装工具链升到 Tier 2,质量差距巨大(语法级调用图 + 精确 cite 行号 vs grep 推断)。见下方"推荐:升 Tier 2"。
GitHub clone 失败(报 git-submodule signal 9 或超时)? 用本地路径绕开(无 git 操作,适合沙箱/网络受限环境):
git clone https://github.com/beihai23/knowledge-map ~/knowledge-map
/plugin marketplace add ~/knowledge-map
/plugin install knowledge-map@beihai23-knowledge-map
旧方式(裸 skill clone,仅 skill,无 commands/hooks):
git clone https://github.com/beihai23/knowledge-map ~/.claude/skills/knowledge-map注:裸 clone 只加载 skill,不会注册
/km-*命令和 hooks — 这些随 plugin 安装才生效。推荐用 plugin 方式。
推荐:升 Tier 2(显著提升质量) —— 装完 plugin 默认是 Tier 3(grep 兜底)。升 Tier 2 拿到语法级调用图 + 精确 cite 行号,差距巨大。两条路,按需选:
路径 A —— ast-grep(推荐起点,30 秒): 单二进制,零配置,内置常见语言 parser,加新语言只写一个 YAML。
brew install ast-grep # macOS / Linuxbrew
pip install ast-grep-cli # 有 Python 就行(skill 本就依赖 python3,最低门槛)
npm install --global @ast-grep/cli # 有 Node
winget install ast-grep.ast-grep # Windows(Win10/11 自带 winget)详见 references/ast-grep-setup.md。
路径 B —— tree-sitter(需要复杂语义查询时): 适合数据流污点链等 ast-grep YAML 表达不了的结构查询,或某语言 ast-grep 不支持。装起来更重(需配 grammar):
brew install tree-sitter-cli graphviz # macOS
npm install -g tree-sitter-cli # 跨平台含 Windows,有 Node 就行
tree-sitter init-config
git clone --depth 1 https://github.com/tree-sitter/tree-sitter-go ~/github/tree-sitter-go其他语言 grammar 按目标仓库技术栈装,详见 references/tree-sitter-setup.md。
⚠️ brew 坑:brew install tree-sitter装的是库不是 CLI,要tree-sitter-cli。
装不上?Tier 3 兜底保证 skill 不失能(调用图打
[推断]标如实反映准确度)。但那是保险,不是推荐路径——能装就装。
在 Claude Code 里说类似的话即可触发 skill(或用 /km-build 显式全量、/km-update 增量):
- "梳理一下这个仓库 / 帮我理解这个代码库"
- "画一下各服务的调用图 / 依赖图 / 时序图"
- "新人 onboarding,做个知识库"
- "这几个微服务之间什么关系?"
产出落到目标仓库的 .knowledge-map/ 目录,入口是 INDEX.md。产物侧 zh/content/deep-dives/ 存放沉淀问答页(查询回写,见上方核心特性)。会话在有 .knowledge-map/ 的仓开始时,SessionStart hook 会告知 agent 地图存在(作为可选工具,需要时再用)。
knowledge-map/ # plugin 根 = 仓库根
├── .claude-plugin/
│ ├── plugin.json # plugin 清单
│ └── marketplace.json # marketplace 声明(/plugin install 用)
├── commands/ # slash 命令
│ ├── km-build.md # /km-build 全量
│ └── km-update.md # /km-update 增量
├── hooks/ # 自动注册的 hooks
│ ├── hooks.json # SessionStart + Stop 配置
│ ├── session-hello.py # SessionStart:告知 agent 地图存在
│ └── check-stale.py # Stop:过时提示
├── skills/knowledge-map/ # skill 本体
│ ├── SKILL.md # 主流程
│ ├── references/
│ │ ├── layer-templates.md # 图表矩阵 + 各层模板
│ │ ├── adapters.md # 工具分层探测 + 适配器接口
│ │ ├── graph-model.md # 统一图模型 + manifest/imports schema
│ │ ├── incremental-update.md # 增量更新流程
│ │ ├── iterative-refinement.md # 双向迭代收敛
│ │ ├── parallel-extraction.md # 并发模式
│ │ ├── coverage-audit.md # audit 关卡(A-E)+ 标尺独立性
│ │ └── tree-sitter-setup.md # Tier 2 安装
│ └── templates/ # 可执行脚本(实例化到目标仓)
│ ├── audit.py.tmpl # 覆盖审计(A/B/C/D/E 关)
│ ├── update.py.tmpl # 增量编排(plan/finalize)
│ ├── extract_imports.py.tmpl # importMap 预解析
│ ├── km-ci.yml.tmpl # CI 自动保鲜模板(GitHub Actions,可选)
│ └── tests/ # 单测(24 个)
├── docs/ # 设计 spec + 实施计划
├── README.md # 本文件(中文)
├── README.en.md # English version
└── LICENSE # MIT
防过时靠基础设施,不靠纪律:把 skills/knowledge-map/templates/km-ci.yml.tmpl 复制到目标仓 .github/workflows/km-update.yml,配好 ANTHROPIC_API_KEY secret,push 到默认分支即 headless 跑 /km-update;.knowledge-map/ 的改动由 peter-evans/create-pull-request 开成 PR,人审后合并——不直推 main。可按需加 paths 过滤。
AI 仓库文档工具不少(DeepWiki / Factory AutoWiki / OpenWiki / GBrain),本 plugin 的差异不在"也能生成 wiki",而在可验证性:
| 它们 | 本 plugin | |
|---|---|---|
| 防幻觉 | 无独立校验(覆盖自检靠模型自觉;DeepWiki 实测会编造构建系统) | audit.py 拿文件系统当标尺穷举校验:覆盖孤儿 / cite 逐条验真 / 规模数字 wc 实测,exit 0 才交付 |
| 溯源粒度 | 段落级行区间(未校验)或仅文件路径/commit | cite 精确到行,经 tree-sitter AST 校验 |
| 增量更新 | 整仓重生成(DeepWiki 强制 2 天刷新)或 commit 粒度黑盒 | 文件级 sha256 指纹 + importMap 影响传播,只重抽脏文件 |
| 私有部署 | SaaS / 绑厂商云 / 需 Postgres | 代码不出仓:Tier 2(ast-grep/tree-sitter)本机跑,或 Tier 3(grep 兜底)零依赖——脚本全 Python 标准库,内网/涉密仓不发给云端 RAG |
| 消费方式 | 读 AI 写的散文(会过期会幻觉) | 地图是索引:agent 凭 graph.json + cite 下钻读真实代码,散文只给框架 |
一句话:别的工具让你信任 AI 生成的文档,这个让文档可被证伪。公开仓快速看个大概用 DeepWiki 即可;代码不能出内网、或要拿地图做改动决策不能容忍幻觉,那是本 plugin 的场景。
比 AI 工具批量生成的文档(如 qoder repowiki)强在:真实溯源 + 迭代修正 + agent 优先。批量文档图好看但行为图常虚构——实测发现某 repowiki 的任务状态机(待处理→进行中→已完成→已结算)在代码中根本不存在。本 plugin 的图都挂在经 AST 校验的真实行号上,且通过迭代收敛纠正骨架期的错误假设。
与 Understand-Anything 的区别:UA 主打交互式 dashboard(给人看);本 plugin 走 docs-as-code + agent 优先(graph.json/cite/audit 精确,框架文档容许粗),配合 SessionStart hook 让 agent 知道地图存在、按需消费——地图是工具之一,不霸占每次操作。
MIT