前言¶

在 DSH 里读代码、讲流程，常见做法是口头描述或贴静态 Mermaid 图：图和仓库很快脱节，节点也跳不到具体行号。PR 评审时「改了什么」往往还要对照 diff 自己脑补。CodeGraph 是 longbowzz 维护的 Agent Skill 与 DSH 客户端 bundle，让智能体读仓库后产出单文件 HTML——流程图、时序图、UML 类图，或长页交互讲解（CodeWalkthrough），元素可点击回到编辑器或页内源码面板，并支持按 PR / commit / diff 高亮增删改。

这是什么¶

CodeGraph 面向 Claude Code、DeepSeek Harness、Cursor 等兼容 Agent Skills 的环境：你描述要看的流程或模块，智能体读代码、写 Mermaid 与源码位置表，经校验后打包成无需服务器、无需 viewer 端 npm install 的离线 HTML。在 DSH 中，bundle 名 @longbowzz/dsh-codegraph（当前资料版本 0.4.0），分类为客户端，提供右侧栏图表/讲解 Tab 与结果卡片。仓库：https://github.com/longbowzz/CodeGraph；社区目录：https://www.skillhub.cn/plugins/longbowzz/CodeGraph。

核心功能¶

图表与源码联动¶

• Click to source：点击节点、边、时序消息、类或关系线，在 VS Code、Cursor、JetBrains 等支持的编辑器中打开对应行；也可选 Web 在页内面板查看。
• Diagrams：单页 graph.html 支持 flowchart、sequence diagram、UML class diagram；缩放、平移、悬停；默认可聚焦一个问题，按需可在同一 HTML 中用 Tab 组合各一种流程图、时序图、类图（同类型重复会被拒绝）。
• Review 模式：指向 PR、commit 或 base..head 范围时，绿色=新增、橙色=修改、灰色=未变，变更在图中高亮。

CodeWalkthrough¶

不是文件摘要，而是从代码生成的短「课程」：由浅入深（心智模型 → 总览图 → 贯穿示例 → 机制与边界 → 回顾）、视觉优先（内联 SVG/CSS/JS）、可选 3–5 题自测（需主动要求）。输出单文件 walkthrough.html，离线可用。

DSH 侧能力¶

bundle 注册工具 codegraph_build、codegraph_walkthrough_build、codegraph_list，以及结果卡片与右侧 graph/walkthrough Tab。产物默认写在目标仓库 .codegraph/output/。

安装与启用¶

插件在当前 DSH 进程权限下运行；安装前建议自行查看 GitHub 源码与 MIT 许可证。要求 DeepSeek Harness 0.2.x（engines.dsh: >=0.2.0-0 <0.3.0-0）；Skill 脚本需 Node.js 18+。

DSH 各 profile 相互隔离；Desktop 的 desktop profile 不能通过 dsh plugin --profile desktop … 管理，需按你实际使用方式安装。

Desktop 应用： 侧栏打开 Plugins → Add plugin → 输入 @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，不会装到 Desktop。若使用其他 CLI 管理的 profile，将 web 换成对应名称。-w 将 bundle 加到 profile 工作区根目录；部分 DSH 构建上 pnpm 需要此标志。安装后退出并重新打开 DSH，新开 session（bundle 与客户端 Tab 在启动时加载）。

验证 CLI profile 是否包含 bundle：

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

dependencies 与 dsh.profile.bundles 中应出现 @longbowzz/dsh-codegraph。

典型用法¶

在要分析的仓库里直接对智能体说明意图（需提到 CodeGraph 或 CodeWalkthrough 以激活 skill）。首次运行可能询问编辑器；无本地 IDE 时可选 Web。

示例（摘自官方 README）：

Use CodeGraph to draw the login flow as a sequence diagram.

Use CodeGraph to draw the class model of the payment module.

Combine a class diagram and a sequence diagram for this module.

Review PR #123 with CodeGraph — highlight what changed.

Use CodeGraph to explain the refund flow as an interactive webpage.

DSH 中结果卡片可在右侧栏打开图表或 walkthrough；其他环境用浏览器打开报告中的 HTML。注意：被分析的仓库须留在 session workspace 内；代码变更后需重新生成，产物是当前 checkout 的快照。

适用场景与注意¶

适合 onboarding、模块讲解、设计评审留档，以及 PR 可视化。智能体负责语义与 Mermaid/位置表，校验器检查语法、结构与路径，不能保证标签与业务含义完全一致。Walkthrough 会先问若干 intake 问题；自测为可选。这不是泛化的「画个图」指令，需明确调用 CodeGraph。

更细的 Agent 契约见仓库 skills/codegraph/SKILL.md、Walkthrough 见 skills/codegraph/references/walkthrough.md、DSH bundle 说明见 dsh/README.md。

结尾¶

CodeGraph 把「看图」和「看代码」收成一份离线 HTML，并在 DSH 里用客户端 Tab 直接预览。目录页：https://www.skillhub.cn/plugins/longbowzz/CodeGraph；源码与 issue：https://github.com/longbowzz/CodeGraph。