前言¶

在開發 DeepSeek Harness (DSH) 智能體時，讓 Agent 理解代碼庫結構是一項常見需求。通常的做法是讓 LLM 直接閱讀大量代碼，或者搭建爬蟲服務，前者成本高且速度慢，後者需要維護額外服務。

dsh-repo-analyzer 是一個本地倉庫智能插件，旨在通過靜態分析提供棧檢測、依賴地圖和模塊引用信息。它不依賴外部服務，所有計算都在當前文件系統上運行。

核心功能¶

插件提供三個主要工具：

• repo_scan：掃描倉庫。識別技術棧、校驗 manifest 文件、識別擴展名和系統文件、列出目錄層級清單。
• repo_deps：分析依賴。解析 package.json、pyproject.toml、go.mod、Cargo.toml，支持查詢單個依賴、定位文件及可用工具的配置文件。
• repo_refs：本地模塊引用。支持 import/require 解析，識別最常用的模塊節點和文件夾依賴。

安裝與啓用¶

使用官方命令安裝：

dsh plugin --profile <name> add dsh-repo-analyzer

安裝後，插件會自動加載到指定的 profile 中。

配置項¶

插件支持以下配置項（YAML 格式）：

- insert:
    - id: dsh-repo-analyzer
      name: dsh-repo-analyzer
      config:
        root: '.'            # 倉庫根目錄，指向 agent 的 cwd
        maxDepth: 4          # 目錄遍歷深度限制，0 表示不限制
        maxFiles: 20000      # 單次解析文件數量上限
        maxFileBytes: 1048576
        exclude:             # 需要排除的路徑（默認已包含 node_modules/.git/dist 等）
          - node_modules
          - .git
          - lib

典型用法¶

1. 獲取倉庫清單：使用 repo_scan 獲取倉庫的技術棧清單和目錄結構。
2. 查詢依賴引用：使用 repo_deps 查詢某個依賴（如 lodash）有哪些文件被引用，並評估其影響範圍。
3. 定位模塊：使用 repo_refs 導出引用圖，分析模塊依賴關係，告訴用戶這個模塊最適合放在哪個目錄。

技術實現細節¶

• 全本地運行：依賴 manifest 文件（package.json 等）的存在概率較高。
• 依賴解析：package.json 使用 JSON.parse 解析，pyproject.toml / go.mod / Cargo.toml 使用正則解析，並忽略無效值。
• 引用圖：對 .ts/.tsx/.js/.jsx/.mjs/.cjs/.py 下的 import/require 進行掃描，將引用轉換爲文件路徑，並按目錄分組。
• 安全驗證：所有用戶輸入路徑都經過 resolveWithin 驗證（默認在 root 下），防止鏈式鏈接文件攻擊。

結語¶

該插件適合需要在本地進行代碼庫分析的場景，能幫助智能體快速建立對代碼結構的認知。

插件目錄
GitHub 倉庫