victorzhong0110 / dsh-code-reference

dsh-code-reference

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

除"内容级"复用（相似的函数/组件/项目）外，还支持架构级复用：扫描本地已有的业务系统，判断新系统的整体架构能否直接复用（例如要做图书馆检索系统时，本地某个政务文件管理系统可能与其共享"检索与索引/用户与权限/文档与存储/管理后台"等能力，可直接以它为骨架）。

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

核心工作流

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

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

工具清单

工具	用途
reuse_survey	主流程：调查（本地文件 + 本地系统架构 + 开源）→ 价值权衡 → 询问用户是否复用（或 auto 模式直接决策）
architecture_reuse_search	架构级复用：提取需求业务能力标签（15 类），扫描本地系统画像（能力矩阵/规模/语言），按架构相似度排序输出
local_code_reuse_search	本地代码库（公司/项目）中检索可复用的函数/类/组件/模块
github_reference_search	GitHub 仓库检索（star 排序、许可证、README）
github_repo_reference	GitHub 仓库元数据 + README + 关键文件
gitlab_reference_search	GitLab.com 项目检索
gitee_reference_search	Gitee（码云）仓库检索
npm_reference_search	npm 包检索（依赖选型）
reuse_value_assessment	独立的价值评估：复用 vs 从零实现的成本对比决策
code_architecture_review	架构自检：循环依赖/超大模块/扇入扇出热点

架构级复用（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.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"；把扫描根目录严格限定在当前仓库；只把它当"候选发现器"，不信任绝对评分。

安全默认说明：仓库自带的 .code-reference-policy.json 未设置 remoteSearch（代码缺省为 true，个人试用即可外发需求关键词）。企业环境必须使用上方模板（remoteSearch: false + requireTests: true）并纳入代码审查。

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.2.1 --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.2.1）
git clone --branch v4.2.1 --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 <commit-sha>

校验文件完整性（仓库根目录 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 服务协作）

插件	职责	文件
code-ref-core	共享服务（HTTP 请求、本地扫描、系统画像与架构相似度、候选评估、政策、决策引擎；v4.1 起为依赖注入工厂 + 顶层纯函数，可单测）	plugins/core.mjs
code-ref-tools	7 个检索/架构工具 + 架构自检	plugins/tools.mjs
code-ref-decision	复用价值评估 + 复用调查询问（含系统骨架候选）+ 工程规范提示词	plugins/decision.mjs

注意事项

• 隐私：远程搜索会把需求关键词发往 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 环境端到端测试、长期兼容性验证和更多实际项目反馈。

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

许可证

MIT