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