dsh-code-reference

DeepSeek Harness (DSH) 代码参考检索与工程规范插件：在厘清需求之后自动调查本地与开源的可复用代码，把"候选清单 + 价值权衡"呈现给用户并询问是否需要复用（可选择复用哪个候选/改造/不复用直接开发）；也支持配置为不询问、直接优先复用。

除"内容级"复用（相似的函数/组件/项目）外，还支持架构骨架候选（常称「架构级复用」）：用能力标签重叠扫描本地业务目录，提出「或许能当骨架」的候选。不是自动证明架构等价——是否采纳必须人工确认。

> 定位：候选发现器，不是自动决策器。 所有匹配度与架构相似度均为关键词/文件名/能力标签重叠的启发式信号，用于生成候选清单供用户选择；数据模型、边界与非功能需求兼容性必须由人工确认。

核心工作流

用户提出开发需求（新组件 / 新项目 / 大型重构）
→ 澄清需求（范围/语言/约束）
→ reuse_survey：自动调查（本地代码库 + 本地系统架构画像 + GitHub 等开源平台）并评估价值权衡
→ 向用户呈现候选清单 + 价值对比，询问是否复用
（用户选择：以本地系统为骨架 / 复用某个本地候选 / 复用某个开源项目 / 改造 / 直接开发）
→ 按用户选择执行（复用 → 改造 → 引入依赖 → 从零实现）

• 小任务豁免（模型工作流规则）：改单个按钮、修复空指针/拼写缺陷、变量重命名等小型改动（预估 <50 行且不引入新组件/新项目）不触发调查与询问，直接修改；需要程序化强制跳过时给 reuse_survey 传 scope="skip"（返回 mode="minor-skip"，不调查不询问）
• 默认询问：reuse_survey 调查后弹出选项（系统骨架 / 本地候选 / 开源候选 / 不复用直接开发），用户决定
• 可选不询问：公司政策文件配置 "reuseMode": "auto"（或工具传 ask=false），跳过询问直接采用评估推荐（优先复用）
• 不做强制拦截：系统不会阻止写文件，复用与否由用户与模型协商决定

工具清单

架构级复用（v4 新增）

• 15 类业务能力词典（中英文关键词）：检索与索引 / 元数据与分类 / 用户与权限 / 审批与流程 / 导入导出与批处理 / 报表与统计 / 审计与日志 / 文档与存储 / 资源与借还 / 订单与交易 / 通知与消息 / API 与服务化 / 任务与待办 / 组织与机构 / 管理后台
• 系统画像：扫描 root 下每个顶层业务目录，生成能力矩阵、文件数、行数、语言
• 相似度 = 需求能力标签与系统能力标签的重叠比例，仅为候选信号；reuse_survey 将相似度 ≥60 的系统列为骨架候选，是否采纳需人工确认
• 选定骨架后建议用 code_architecture_review 检查该系统依赖结构是否健康

复用价值判断标准

只有当复用的总成本（改造工作量 + 质量风险 + 集成成本）显著低于从零实现时才复用：

• 量化维度：需求匹配度（0-100，内容 70% + 名称 30%）、代码规模/复杂度、注释比、测试覆盖信号、维护活跃度、许可证、star
• 决策四档：reuse（直接复用）/ adapt（改造复用）/ dependency（引入依赖）/ rewrite（自制）
• 阈值可调：reuseThreshold(默认70) / adaptThreshold(默认40) / remoteThreshold(默认50) / smallLines(300) / mediumLines(800) / maxComplexityPercent(12)

公司政策（.code-reference-policy.json）

自动查找顺序：显式 policyPath → 工作区根 → 本地候选目录向上 3 层。支持字段：

{
"allowedLicenses": ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "MPL-2.0", "Unlicense", "0BSD"],
"blockedLanguages": [],
"requireTests": false,
"minCommentRatio": 0,
"reuseMode": "ask",
"remoteSearch": true
}

• reuseMode: "ask"（默认）：调查后询问用户；"auto"：不询问，直接采用评估推荐决策（优先复用）
• remoteSearch: true（默认）：reuse_survey 同时检索 GitHub/npm（会把需求关键词发往对应平台）；企业设 false 则只做本地调查
• 政策检查进入评估：许可证不在白名单 → 排除依赖；许可证未知 → 默认阻断（已配置白名单时，未知许可证无法确认合规，必须人工确认后才能放行，绝不显示"已通过"）；语言在黑名单 → 候选不可用；要求测试但候选无测试 → 复用降级为"改造 + 补测试"

部署级政策（可信上限）

工作区自带的 .code-reference-policy.json 属于仓库内容，不可信：任何仓库都能往里面写 "reuseMode": "auto" 或 "remoteSearch": true。企业强制政策应通过部署级配置注入：

export DSH_CODE_REFERENCE_POLICY=/etc/dsh/code-reference-policy.json   # 部署级可信政策（JSON 文件路径）

部署级政策是不可放宽的上限，工作区政策只能收紧：

部署级文件缺失或无法读取时，评估结果会给出明确提示（不静默降级）。未配置部署级政策时，行为与旧版一致（工作区政策直接生效）。

企业环境建议配置

仓库附带企业模板 .code-reference-policy.enterprise.json，复制为 .code-reference-policy.json 即可：

{
"allowedLicenses": ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "MPL-2.0", "Unlicense", "0BSD"],
"blockedLanguages": [],
"requireTests": true,
"minCommentRatio": 0,
"reuseMode": "ask",
"remoteSearch": false
}

配套实践：不要用 reuseMode: "auto"；把扫描根目录严格限定在当前仓库；只把它当"候选发现器"，不信任绝对评分；企业环境请同时配置 DSH_CODE_REFERENCE_POLICY 部署级政策，且该文件只允许部署管理员修改。

GitHub API 限流与 Token

未认证的 GitHub 搜索 API 约 10 次/分钟。设置环境变量可显著提高配额（5000 次/小时）：

export DSH_GITHUB_TOKEN=ghp_xxxxxxxx        # 或 GITHUB_TOKEN

插件会自动在 api.github.com 请求上附加 Authorization: Bearer，不会附加给 npm 等其他域名。Token 请勿写入政策文件或提交进 git（参见 SECURITY.md 威胁模型）。

测试与 CI

• 单元测试：node --test test/core.test.mjs test/decision.test.mjs（67 个用例，node:test 零依赖）——core：纯函数、扫描边界（SKIP_DIRS/大小/fileBudget/扩展名）、远程 API mock（Token 携带与隔离、多档重试、端到端评估）；decision：政策优先级（reuseMode/remoteSearch）、询问超时、no-candidates、auto-fallback、用户选择映射、scope="skip" 程序化豁免、宿主加载冒烟
• CI：GitHub Actions（Node 20/22，actions 按 commit SHA 固定）自动运行语法检查 + 单测 + 政策 JSON 校验

安装

一键安装（dsh plugin add，推荐新用户）

本仓库声明了 dsh.bundle manifest，可用 DSH 官方插件机制安装（任何目录下）：

git clone --branch v4.3.0 --depth 1 https://github.com/victorzhong0110/dsh-code-reference.git
dsh plugin --profile web add ./dsh-code-reference

卸载：dsh plugin --profile web remove dsh-code-reference。也可通过 dsh-market 插件市场一键安装。

固定版本（推荐）

永远不要跟随 main 分支。固定到正式 Release 的 tag（带附件 plugins/*.mjs + SHA256SUMS）：

# 方式 A：tag（如 v4.3.0）
git clone --branch v4.3.0 --depth 1 https://github.com/victorzhong0110/dsh-code-reference.git

# 方式 B：固定 commit
git clone https://github.com/victorzhong0110/dsh-code-reference.git
cd dsh-code-reference && git checkout

校验文件完整性（仓库根目录 SHA256SUMS 或 Release 附件）：

shasum -a 256 -c SHA256SUMS

部署级（推荐：所有会话 + 重启后持久生效）

1. 把 plugins/ 下三个 .mjs 文件放到任意目录（如 ~/.dsh/plugins/code-reference/）
2. 在 DSH 配置的 patch 层（如 ~/.dsh/profiles/web/cordis.patch.yml）追加：

- insert:
- id: code-ref-core
name: /绝对路径/core.mjs
- id: code-ref-tools
name: /绝对路径/tools.mjs
- id: code-ref-decision
name: /绝对路径/decision.mjs

3. 重启 DSH，所有会话自动获得工具与复用调查流程

动态级（临时，重启失效）

在会话中用 cordis_define / cordis_run 加载本插件的 host 代码（适用于调试；部署后请勿同时运行，避免工具重名）。

架构（拆分为三个小插件，通过 codeRef 服务协作）

注意事项

• 隐私：远程搜索会把需求关键词发往 GitHub/npm；本地扫描受 root 限制并跳过 node_modules/.git/dist/vendor/tests/site-packages 等目录。本地源文件不会发送给任何检索平台；命中路径、最长 160 字符的代码片段及系统画像会进入当前 Agent/模型上下文（详见 SECURITY.md 威胁模型）
• 远程检索结果为第三方开源项目，复用必须遵守其许可证（license 字段）
• 询问等待上限 90 秒（无真人应答的上下文会自动跳过询问并采用推荐决策）
• reuse_survey 返回 answer.status="unanswered"（未回答/超时）时，模型不得开始写代码，须先报告调查结果等待用户决定

反馈与贡献

当前状态：beta（可用于内部试点）。距离稳定 GA 主要差真实 DSH 环境长期端到端验证与更多实际项目反馈；不要把社区 Awesome 徽章理解成生产认证。

欢迎任何反馈：试用问题、兼容性报告、新平台/新语言支持需求、架构复用场景案例。请发送邮件至 [email protected]，或在 GitHub Issues 中提出。

许可证

MIT

成本与预算（面试可讲）

reuse_survey 成功返回里带 costEstimate 字段（面试可指着 JSON 讲）：

最坏情况口述： 本地扫满 file/time cap +（若开启远程）有限次平台检索；企业模板默认 remoteSearch: false 时远程为 0。这是 cap 叙事，不是美元账单。

代码侧已有扫描上限（可在工具/budget 参数收紧）：

• fileBudget — 单次扫描最多触达的文件数
• timeBudgetMs — 扫描墙钟预算；系统画像默认约 20s 量级可调
• 远程 — 未认证检索有速率限制；配置 DSH_GITHUB_TOKEN 可提高配额；token 只附加到 api.github.com
• 模型上下文 — 命中路径与短片段会进入当前 Agent 上下文（本地源文件不上传检索平台）

最坏情况口述：reuse_survey 在开启远程时 ≈ 本地扫描至 file/time cap + 有限次远程搜索；企业模板默认关闭远程，把外发关死。