代码图谱 longbowzz/CodeGraph

CodeGraph

English ·

把一段代码流程变成可点击的图，或一篇可交互的长文讲解——由 AI Agent 生成，产物是单个离线 HTML 文件。

CodeGraph 是一个 Agent Skill，适用于 Claude Code、DeepSeek Harness、Cursor、Codex 等兼容 Agent Skills 的工具。你只需描述流程，Agent 会阅读代码、生成产物，并让每个元素都能跳回源码。

为什么用 CodeGraph

普通 Mermaid 图到“一张图”就结束了。CodeGraph 保留了图和代码之间的连接：

- 点击跳源码——点节点、边、时序消息、类或关系，直接打开对应源码行；可以在编辑器里打开，也可以在页内面板查看。
- 带上下文 review——把 PR、commit 或 base..head 范围交给 Agent，图里会用颜色标出新增 / 修改 / 删除的元素。
- 图表或课程——用流程图、时序图或 UML 类图看结构；要讲清楚一个模块，就用 CodeWalkthrough 生成可滚动的长文讲解页，带小节、内联图、源码链接和可选自测。

所有内容都会打包成一个自包含 HTML：不需要服务器、CDN，查看端也不需要 npm install，离线可用。

演示

CodeGraph 演示

Review 模式流程图。 绿色为新增，橙色为修改，灰色为未变；点击节点会打开对应源码行。

Review 模式流程图

时序图。 同样的 review 配色，包含参与者、消息和可点击的源码位置。

Review 模式时序图

图表

让 Agent 画一个流程或建立类模型，它会生成单个 graph.html：

- 流程图、时序图或 UML 类图；
- 缩放、平移、hover 和点击跳源码；
- PR / commit / diff 的 review 模式；
- 任意浏览器可用，离线也能看。

类图展示类、字段、方法和 UML 关系。hover 一个类可以看到它的 stereotype 和职责，其余节点会变淡，只保留直接邻居；点击类或关系线可以打开源码。

UML 类图

默认建议一个 artifact 只回答一个问题。如果用户明确要求，一个 graph.html 可以同时包含一张流程图、一张时序图和一张类图，各自一个 tab；重复的图类型会被拒绝。

CodeWalkthrough：把代码变成一门课

CodeWalkthrough 不是“总结一下这个文件”。它会基于代码生成一门小课，设计上围绕三件事：

- 由浅入深——先用一段话建立心智模型，再给全局图，然后是一个贯穿全文的真实例子，最后进入机制、边界和回顾；每个小节只讲一件事。
- 图形化讲解——数据流、状态变化、调用链用内联 SVG/CSS/JS 图和动画表达；代码是展品，不是正文。
- 练习题验证——可选的 3–5 道自测题，支持选项判分或点击查看答案；答案解释原因，并链接回源码。

整篇只用一个贯穿案例，关键结论都带源码链接。产物是单个 walkthrough.html，离线可看。

适合 onboarding、模块讲解、设计评审，或把一次 review 变成可复用的教材。

CodeWalkthrough 演示

安装

Claude Code

claude plugin marketplace add longbowzz/CodeGraph
claude plugin install codegraph@codegraph

在会话里也可以用 /plugin install codegraph@codegraph --marketplace longbowzz/CodeGraph 一步完成。

任意兼容 Agent Skills 的 Agent

npx skills add longbowzz/CodeGraph --skill codegraph

在目标项目里运行。加 -g 安装到全局，加 -a claude-code 跳过 Agent 选择。

DeepSeek Harness

DSH 的 profile 是相互隔离的；桌面 App 的 desktop profile 由 Electron 应用管理，dsh plugin --profile desktop … 会被拒绝。请按你的运行方式安装：

桌面 App：在侧栏打开 插件，选择 添加插件，输入 @longbowzz/dsh-codegraph@0.4.0，安装；如果提示启用 bundle，选择启用。

Web / CLI profile（dsh web 使用 web profile）：

dsh plugin --profile web add -w @longbowzz/dsh-codegraph

--profile web 只影响 dsh web，不会把插件加到桌面 App。如果启动的是其他 CLI 管理的 profile，把 web 换成对应名字。

-w 会把依赖加到 profile 的 workspace root；部分 DSH 构建下 pnpm 要求显式指定。安装后需要完全退出并重新打开 DSH，再新建会话——bundle 和客户端 tab 在启动时加载。

可以检查 CLI profile 是否包含 bundle：

cat ~/.dsh/profiles/web/package.json

dependencies 和 dsh.profile.bundles 里都应该有 @longbowzz/dsh-codegraph。

这个 bundle 还会注册 codegraph_build、codegraph_walkthrough_build、codegraph_list 三个工具，以及结果卡片和右侧栏的图 / 讲解页 tab。详见 dsh/README.md。

环境要求

- Node.js 18+：运行 Skill 脚本；生成和查看产物不需要运行时 npm install。
- Node.js 22.20+：使用 npx skills CLI 时需要。
- 点击跳源码需要受支持的编辑器（VS Code、Cursor、JetBrains 系列）；没有的话选 Web 编辑器，在页内面板打开源码。
- DeepSeek Harness 0.2.x：使用 DSH bundle 时。

使用

在要分析的项目里直接对 Agent 说：

用 CodeGraph 画一下登录流程的时序图。

用 CodeGraph 画出支付模块的类图。

把这个模块的类图和时序图合并到一张页面里。

用 CodeGraph review 一下 PR #123，标出改动。

用 CodeGraph 为我介绍退款流程，做成一个可交互的网页。

第一次运行可能会问用哪个编辑器。没有安装受支持的编辑器时选 Web。

产物会写到目标项目的 .codegraph/output/ 下。在 DSH 中，结果卡片会在右侧栏打开图或讲解页；其他 Agent 里直接打开它报告的 HTML 文件即可。

注意事项

- Agent 负责写 Mermaid 文本和源码位置表；校验器检查语法、结构、路径和行号，但不能证明标签的业务含义正确——这需要 Agent 阅读代码来保证。
- Review 配色：绿色 = 新增，橙色 = 修改，灰色 = 未变。
- 产物是当前 checkout 的快照；代码改动后需要重新生成。
- 默认建议一个 artifact 只回答一个问题；合并页面最多包含一张流程图、一张时序图和一张类图。
- 类条目可以带可选的 stereotype / summary 元数据；它们用于 hover 卡片，不是点击跳转的必填项。
- CodeWalkthrough 会先确认读者、范围和深度；自测题是可选项，需要明确要求。
- 在 DSH 中，被分析的仓库必须位于 session workspace 内。
- CodeGraph 不是通用的“画个图”触发器。请明确提到 CodeGraph，或要求 CodeWalkthrough，Skill 才会激活。

了解更多

- Agent 规范——完整的画图流程和支持的 Mermaid 子集。
- CodeWalkthrough 规范——信息确认、页面结构和自检。
- DeepSeek Harness 插件包——工具、卡片、标签页和配置。
- 类图示例——把 CodeGraph 自己的构建管线画成 UML 类图。
- CodeWalkthrough 示例内容。
- 有问题或建议？提 Issue。

开发

npm test # parser、validator、diff、HTML 构建、CLI
npm run build:mermaid

浏览器测试需要 Playwright 和 Chromium；入口脚本见 skills/codegraph/scripts。

维护者发版流程见 RELEASING.md。

协议

MIT。见 LICENSE。