victorzhong0110/dsh-code-reference

dsh-code-reference

Awesome DSH Plugin

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

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

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

核心工作流

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

- 小任务豁免（模型工作流规则）：改单个按钮、修复空指针/拼写缺陷、变量重命名等小型改动（预估

校验文件完整性（仓库根目录 SHA256SUMS 或 Release 附件）：
bash
shasum -a 256 -c SHA256SUMS

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

1. 把 plugins/ 下三个 .mjs 文件放到任意目录（如 ~/.dsh/plugins/code-reference/）
2. 在 DSH 配置的 patch 层（如 ~/.dsh/profiles/web/cordis.patch.yml）追加：
yaml
- 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 环境长期端到端验证与更多实际项目反馈；不要把社区 Awesome 徽章理解成生产认证。

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

许可证

MIT

成本与预算（面试可讲）

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

| 字段 | 含义 |
| --- | --- |
| localFileBudget | 本地文件扫描上限（survey 路径默认 1200） |
| localTimeBudgetMs | 本地扫描墙钟上限（默认 15000） |
| systemProfileTimeBudgetMs | 系统画像扫描上限（默认 15000） |
| remoteSearch | 本次是否发远程检索 |
| remoteKeywordBatches | 远程关键词批次数上界（有远程时） |

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

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

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

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