前言¶
DeepSeek Harness (DSH) 採用插件化架構，Agent 的能力擴展通常通過引入外部工具實現。當 Agent 需要對項目代碼進行安全掃描或質量檢查時，直接調用外部命令行工具或編寫自定義解析腳本會增加開發與維護成本。
dsh-code-scan 插件旨在解決這個問題。它通過封裝 semgrep，爲 DSH Agent 提供了一個名爲 code_scan 的單一工具。Agent 只需傳入目錄路徑，插件即可在本地運行安全掃描，並輸出一份按文件、行號和嚴重級別分組的中文 Markdown 報告。
核心功能¶
該插件提供了以下核心能力：
- 單一工具接口：Agent 只需調用
code_scan，傳入目標目錄路徑即可啓動掃描。 - 結構化報告：掃描結果按文件分組，列出具體的行號、嚴重級別（ERROR / WARNING / INFO）以及對應的規則描述。
- 上下文保護：結果默認按嚴重級別優先排序，且限制最多顯示 200 條。這一設計是爲了避免過多的掃描結果撐爆 Agent 的上下文窗口。
- 容錯機制：如果本機未安裝 semgrep 或命令未在 PATH 中，插件會返回友好的中文提示，而不會導致 Agent 調用失敗。
安裝與前提條件¶
使用該插件前，需確保本地環境滿足以下條件：
- 安裝 semgrep：本機需安裝 semgrep 並確保
semgrep命令在系統 PATH 環境變量中。 - 環境隔離（Windows）：在 Windows 系統上，建議使用獨立的虛擬環境安裝 semgrep，以避免污染其他 Python 項目環境。
在滿足上述條件後，執行以下命令安裝插件：
dsh plugin --profile web add dsh-code-scan
安裝完成後，需要重啓 dsh web 進程以使工具生效。
典型用法¶
安裝成功後，在 DSH 的對話界面中，Agent 即可使用 code_scan 工具。
指令示例：
用 code_scan 工具掃描 C:\path\to\your\project
輸出報告示例：
# semgrep 掃描報告
- 掃描目錄：`C:\...\demo`
- 發現問題：共 4 處（ERROR 2 / WARNING 2 / INFO 0）
## C:\...\app.py（2 處）
- [ERROR] 第 8 行 · 規則 `...sqlalchemy-execute-raw-query`：Avoiding SQL string concatenation...
- [WARNING] 第 18 行 · 規則 `...eval-detected`：Detected the use of eval()...
適用場景與注意¶
- 適用人羣：需要爲 DeepSeek Harness Agent 增加代碼安全審計能力的開發者。
- 權限注意：插件以當前 DSH 進程的權限運行，這意味着 Agent 在掃描目錄時需要具備相應的文件讀寫權限。
- 源碼審查：由於 DSH 插件通常在本地執行命令，建議在安裝前查看 GitHub 倉庫源碼以確認許可證與實現邏輯。
總結¶
dsh-code-scan 插件通過簡單的接口封裝，解決了 Agent 集成靜態代碼分析工具的痛點。它將複雜的 semgrep 掃描過程轉化爲結構化的中文 Markdown 報告，既保證了 Agent 的上下文安全，又提供了清晰的可讀性。項目地址：https://github.com/xiaohuang-zaianlian/dsh-code-scan
