Skip to content

dsh-codegraph

Verified

@longbowzz/dsh-codegraph · v0.4.0 · MIT · Web UI

CodeGraph and CodeWalkthrough for DeepSeek Harness: source-linked Mermaid diagrams and long-form interactive explainer pages.

Install

dsh plugin add @longbowzz/dsh-codegraph

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

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 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。

环境要求

  • 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 才会激活。

了解更多

开发

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

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

协议

MIT。见 LICENSE。