arch-doc：DSH 插件與代碼庫架構文檔生成器

前言¶

在使用 DeepSeek Harness（DSH）進行智能體開發或調試時，讓模型快速理解一個陌生代碼庫的結構是一項基礎需求。傳統方式依賴閱讀文件或手動整理，效率低且容易遺漏關鍵信息。DSH 生態中的 arch-doc 插件通過“掃描器提取事實 + 模板填充”的模式，自動生成包含模塊職責、依賴關係和入口點的架構文檔。

插件介紹¶

arch-doc 是由 duyanta123 維護的一個 DSH 技能插件。它的核心作用是分析代碼庫，並生成結構化的架構文檔。該插件通過提取硬事實（如語言、目錄、依賴、入口點），結合 LLM 的模板填充，輸出一份包含項目類型、模塊劃分、依賴關係和運行方法的文檔。

許可證：MIT
倉庫地址：https://github.com/duyanta123/arch-doc
插件目錄：https://www.skillhub.cn/plugins/duyanta123/arch-doc

核心功能¶

該插件主要完成以下工作：

硬事實提取：識別項目使用的語言、目錄結構、內部與外部依賴以及入口點。
項目檢測：判斷項目類型（如 CLI/Web/Worker）、構建系統和倉庫類型（單體/多模塊）。
模塊分析：確定模塊的劃分方式及每個模塊的職責。
入口點識別：檢測應用是作爲 CLI、Web 服務、Worker、Scheduler 還是庫運行的。
可視化輸出：生成 Mermaid 格式的模塊依賴圖。
結構化數據：輸出 JSON 格式的機器可讀分析結果。

安裝與啓用¶

安裝該插件需要使用官方提供的命令。注意，雖然 GitHub 倉庫名爲 arch-doc，但 npm 包名被反佔庫名規則修改爲 dsh-arch-doc。

1. 作爲 DSH 插件安裝¶

推薦通過 DSH 的插件管理器安裝指定版本：

dsh plugin --profile web add "github:duyanta123/arch-doc#v0.1.4"

2. 作爲 npm 包安裝¶

也可以直接通過 npm 安裝：

npm install dsh-arch-doc

安裝完成後，需要重啓對應的 profile 以加載插件。

典型用法¶

安裝完成後，可以在 DSH 中通過自然語言指令調用該技能，也可以直接運行獨立腳本。

1. 作爲 DSH 技能使用¶

在對話中下達指令，讓智能體分析指定路徑的代碼庫：

Use arch-doc to analyze /path/to/repo

智能體會執行掃描，提取事實，並生成文檔。

2. 作爲獨立 CLI 運行¶

插件提供了獨立的 Node.js 腳本，支持分步執行或全量掃描。

運行全量掃描：

node scripts/arch-profile.mjs <repo_path> --all

分步執行特定任務：

# 僅探測項目類型
node scripts/arch-profile.mjs <repo_path> --probe

# 僅掃描目錄和模塊職責
node scripts/arch-profile.mjs <repo_path> --scan --max-depth 3

# 僅提取依賴關係
node scripts/arch-profile.mjs <repo_path> --deps

# 僅檢測入口點
node scripts/arch-profile.mjs <repo_path> --entry

常用參數：

--max-depth <N>：限制目錄掃描深度（1-10），默認爲 3。
--language <L>：指定語言提示（python/javascript/typescript/go/java/generic）。
--include-dirs / --exclude-dirs：指定分析或排除的目錄。

適用場景與注意¶

適用場景¶

快速上手遺留系統：在接手新項目時，快速生成架構概覽。
混合棧項目分析：識別不同語言模塊之間的依賴關係。
文檔自動化：維護項目文檔，確保其與代碼結構同步。

注意事項¶

安全邊界：
- 掃描過程是只讀的，不會執行目標倉庫的代碼，也不會寫入源碼。
- 掃描器本身零依賴，不調用子進程，不訪問網絡。
- 輸出僅限於目標倉庫下的 docs/ 目錄，生成三個文件。
Mermaid 渲染限制：
生成的 Mermaid 圖表文件（.mmd）在瀏覽器通過 file:// 協議打開時可能無法渲染。建議使用 Typora 等本地編輯器，或將源碼粘貼到 mermaid.live 等在線工具查看。
混合棧項目：
對於同時包含多種語言的項目，插件會根據構建文件優先級判斷主語言（例如 Go+Node 項目中 go.mod 優先級高於 JS 配置文件）。

短結尾¶

arch-doc 作爲一個輕量級、零依賴的架構分析工具，通過將掃描邏輯與文檔生成邏輯分離，爲 DSH 智能體提供了可靠的代碼庫理解能力。它生成的結構化文檔和依賴圖，能顯著降低代碼庫的閱讀門檻。