前言¶
在 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。
