前言¶
AI 維護的代碼庫面臨一個特定風險：兩個實現相同能力的函數最終會無聲地分叉，因爲靜態檢查器無法檢測到冗餘。該插件旨在在代碼寫入計劃階段（文件創建之前）介入，確定性地找出現有的實現，迫使智能體複用或提取代碼，而不是直接複製。
核心功能¶
該插件提供以下能力：
- 確定性檢索（無 LLM）：基於函數名、文檔字符串和字符串字面量的查詢覆蓋，使用 IDF 加權。
- 預寫重用防火牆：在智能體編寫新代碼之前運行，以檢測重疊。
- 代碼審計能力通道集成：作爲 Auto_code_audit 的能力通道。
- 哈希鎖定候選者檢測：檢測鎖定在 SHA256 中的文件。
- Top-K 候選者檢索：返回評分最高的匹配項。
先決條件與安裝¶
該插件依賴於 Auto_code_audit 檢出和 Python 3.10+ 解釋器。
- 安裝插件：
dsh plugin add github:keyiadiannao/dsh-code-reuse-firewall#master
- 配置插件。在 DSH 配置文件中，設置
auditRoot指向 Auto_code_audit 檢出：
- id: dsh-code-reuse-firewall
config:
auditRoot: 'D:/path/to/Auto_code_audit'
pythonPath: 'python'
maxK: 5
minScore: 0.1
timeoutMs: 30000
使用方法¶
智能體在編寫新代碼之前調用 reuse_check。提示應描述意圖。
示例：請求實現“從 JSON 配置讀取並支持環境變量覆蓋”。
調用示例：
調用 reuse_check：我要實現「從 JSON 配置讀取並支持環境變量覆蓋」，根目錄是 D:/project/src。看看有沒有現成的實現可以複用。
輸出示例：
工具返回前 K 個候選者，包括路徑、分數和按通道劃分的證據：
Existing implementations overlapping "load a JSON config with env overrides":
[0.72] config.py:load_config (src/config.py) (name=0.72 doc=0.10 literal=0.00)
[0.51] util.py:ConfigLoader.load (src/util.py) (name=0.51 doc=0.00 literal=0.00)
如果候選者位於被 SHA256 鎖定的文件中，則會顯示 🔒 LOCKED 標記：
[0.32] lib/protocol.py:_split_hash_payload (lib/protocol.py) (name=0.32) 🔒 LOCKED by configs/generation_b_training_compatibility.json
⚠ 1 candidate(s) are in hash-locked files: REUSE by import, do not copy-and-modify their implementation (editing invalidates frozen results).
注意事項¶
- 證據性質：檢索結果爲建議性證據，而非缺陷判決。智能體必須決定是複用、提取還是編寫新代碼，且不得基於檢索結果刪除或重寫現有代碼。
- 信號強度：由於
reuse_check在代碼存在之前運行，結構匹配信號不可用。它依賴名稱、文檔字符串和字符串字面量。自然語言查詢在英語關鍵詞下效果最好；純中文描述與英語代碼的匹配效果不佳。 - 哈希鎖定：鎖定文件（由 frozen_results 或 configs 中的 SHA256 定義）標記爲 🔒 LOCKED。編輯這些文件會使其引用的凍結結果無效。正確做法是導入代碼，而不是複製和修改實現。
- 當前侷限性：結構相似的代碼檢測（最強信號）需要代碼實際存在；該插件當前不支持
--file/--base模式來檢查特定文件或差異（這是未來的路線圖）。 - 依賴：插件需要一個包含
capability_retrieval.py的 Auto_code_audit 檢出和一個 Python 3.10+ 解釋器。
結尾¶
該插件充當預寫階段的守門員，以防止代碼重複。通過提供基於確定性算法的候選者列表，它使智能體能夠在分叉發生之前做出重用決策。插件詳情見 GitHub：https://github.com/keyiadiannao/dsh-code-reuse-firewall。
