@longbowzz/dsh-codegraph

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

CodeGraph

[English](README.md) · [中文](README.zh-CN.md)

把一段代码流程变成可点击的图，或一篇可交互的长文讲解——由 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，离线可用。

演示

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

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

图表

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

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

类图展示类、字段、方法和 UML 关系。hover 一个类可以看到它的 stereotype

和职责，其余节点会变淡，只保留直接邻居；点击类或关系线可以打开源码。

默认建议一个 artifact 只回答一个问题。如果用户明确要求，一个 graph.html

可以同时包含一张流程图、一张时序图和一张类图，各自一个 tab；重复的图类型会被拒绝。

CodeWalkthrough：把代码变成一门课

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

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

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

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

安装

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 plugin --profile web add -w @longbowzz/dsh-codegraph

-w 会把依赖加到 profile 的 workspace root；部分 DSH 构建下 pnpm 要求显式指定。这个 bundle 还会注册 codegraph_build、codegraph_walkthrough_build、codegraph_list 三个工具，以及结果卡片和右侧栏的图 / 讲解页 tab。详见 [dsh/README.md](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 规范](skills/codegraph/SKILL.md)——完整的画图流程和支持的 Mermaid 子集。
• [CodeWalkthrough 规范](skills/codegraph/references/walkthrough.md)——信息确认、页面结构和自检。
• [DeepSeek Harness 插件包](dsh/README.md)——工具、卡片、标签页和配置。
• [类图示例](skills/codegraph/examples/class-diagram/)——把 CodeGraph 自己的构建管线画成 UML 类图。
• [CodeWalkthrough 示例内容](skills/codegraph/examples/walkthrough-sample.html)。
• 有问题或建议？提 Issue。

开发

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

浏览器测试需要 Playwright 和 Chromium；入口脚本见

[skills/codegraph/scripts](skills/codegraph/scripts)。

协议

MIT。见 [LICENSE](LICENSE)。