dsh-spec-forge

dsh-spec-forge · 需求锻造

一个 DeepSeek Harness（dsh）插件。它管两件事：动手前把模糊需求问清楚，做完后把经验存下来，下次遇到同类需求时自动顶上来。

实测于 @deepseek-ai/dsh 0.1.2-alpha.4（Windows + Web profile）。dsh 仍是 developer preview，插件已锁定其 API 面；升级 dsh 后如失效，先看 CHANGELOG。

它解决什么

痛点 · 这个插件的做法 需求说不清就开工，做完才发现理解错了 · 收到需求先分级：该问的只问一次，不该问的直接动手 同一套规矩每次都要重新交代 · 识别到的禁区自动累积进项目档案，此后每轮自动注入 同一个套路每次都从零描述 · 把套路沉淀成明文模板，同类需求自动召回 调教好的提示词关掉对话就没了 · 模板是你能看能改的 Markdown，可以进 Git

模板库存在磁盘上（默认 /.dsh-spec-forge/），不是黑盒。

主要功能

1. 需求分级：三级响应 + 三态路由

spec_recall 收到需求后返回一个 nextStep，模型严格按它执行，不自作主张加步骤：

nextStep · 什么时候 · 做什么 implement · 需求够明确：单字段 CRUD、取值型小改（改文案/调间距/改按钮样式/改默认值）、带参考物的自包含新建、普通 L2 模块级改动，或你说了"直接做/不用问" · 一个问题都不问，直接给执行清单 + 默认值（L2 默认值随召回内联），疑虑标 // TODO: [待确认] confirm · 需求只给了"容器"却没说是什么：加个按钮 / 加个路由 / 加一列 / 加个菜单项；或过短且无任何锚点 · 用一次 `ask_user_question` 问清再动手（每题给候选 + 推荐默认），不走体检 triage · 仅 L3：整体重构 / 架构变更 / 迁移 / 跨模块 · 四维体检后完整 Grill-me 追问

分级只看两件事：范围（改动多大）与信息完备度（有没有说清要做的对象是什么）。 判据一句话：

缺「新增物的身份/用途」必问；缺「已有物的属性取值」自决。

所以「改一下文案」「调一下间距」一步直达，而「登录页加个按钮」会先问一次——加什么按钮、点了做什么，那是产品决策，替你挑一个就是猜。

而且这个判定不等模型读完工具返回值：插件在请求发出前就用同一套判据算好，并以一条 system-reminder 直接注入 （dsh 的 agent/pre-step，等价于 Claude Code 的 UserPromptSubmit）。命中 implement/confirm 时注入， triage 与普通对话不注入——不该花的 token 一分不花。关掉它用 preStepRouting: false。

2. 需求体检：四维完整度 + 保守默认

spec_triage 检查四个维度（要实现什么 / 怎么改 / 哪些不能改 / 上下文），并给出可直接执行的报告：

• L1 → 执行清单（不追问）
• L2 → 默认值清单，按默认执行、不列问题；只有需求确实过短、缺一半以上维度、且没有任何可推断锚点时才转一次性追问
• L3 → 完整追问清单

L1/L2 背后有一张保守默认表兜底：列表默认不展示新列、默认不加业务校验、默认后端接口已就绪——宁可少做也不瞎猜。

3. 模板沉淀：三层漏斗，同名幂等

不是每轮对话都值得存。沉淀由三层把关：

1. 代码层硬门槛 —— 这一轮必须真实改过代码且工具调用数达标，纯问答/只读诊断直接拦下，不提示不打扰
2. 复用价值三问（模型自检）—— 下次还会用吗？结论跨项目成立吗？用户会反复提吗？任一为否就跳过
3. 任务链合并 —— 一条任务链只沉淀一次，中途的小修小补并进最终那份

漏了也有兜底：下次再提编程需求时，插件会提醒"上一轮改过代码却没沉淀"。你也可以直接说 "把这次沉淀成模板"，无条件触发。

模板同名幂等：同类需求再次沉淀是覆盖更新，不会无限堆积。每份模板六个段落——触发场景 / 需求澄清清单 / 标准改法 / 禁区 / 提示词模板 / 验收标准。示例见 templates/example-spring-pagination.md。

4. 项目禁区自动累积

会话里识别到的"不能改"（common/Result.java 别动、Controller 不写业务逻辑……）会累积到该仓库的 profile.md，此后所有同类需求自动注入，不用反复交代。禁区是硬约束，模型不得修改。

5. 召回：零依赖、可解释的关键词指纹

spec_recall 把需求原文拆成加权指纹，和模板库逐份比对打分，超过阈值就注入（默认最多 2 份），连同项目禁区一起。

打分是透明的六维计算，但命中由两道闸共同决定：

1. 词汇相似度：lexical ≥ matchThreshold（默认 0.15）；同分类、标签重叠、同仓库、新鲜度、热度只用于排序（rankScore = 0.9·lexical + 0.1·先验），不参与命中判定
2. 主题证据闸：交集里必须有至少 2 个有区分度的词才放行。容器词（列表/表单/详情页）、动作词（提交/新增/接口）、平台标签（miniprogram/wxml/vue）、否定与状态词（无法/不可/检查/生效）都不算证据；唯一例外是单个 ASCII 技术标识符（switch 这类）且作者在模板 name/tags 里声明过它

0.7.0 的口径变更：旧版把先验项无条件加进总分（合计最多 0.38），阈值 0.35 意味着

词汇证据只需贡献 0.06~0.09 —— 无关模板实测能拿 0.333，而真该命中的模板常被挡在门外。

现在「匹配度」显示的就是词汇分，可以直接和阈值比较，不会再出现「分数低于阈值却命中」。

0.7.3–0.7.5 的口径变更：路径在 tokenize 层直接不产出 token（模板是通用主题的载体，

路径是项目专有的）；取消单证据通道 —— 真实语料回放发现单证据词的判定正确率只有 1/20

（「日志页面」的 日志 和「用日志定位」的 日志 是两回事），一律要求 ≥2 个证据词。

用真实语料验收，别只看合成基准。某前端项目群 239 条真实需求逐条回放（长文本、贴接口 JSON、贴报错都有）：

口径 · 数值 合成基准（19 条真实需求 + 17 条弱证据护栏） · 召回 19/19，假阳性 0 人工标注审核（23 条） · 召回 87.5%，假阳性 8.3% 真实语料命中率 · 11.7%（28/239；补齐高频主题模板前是 4.6%） 同项目跨主题假阳性 · 7.1%（硬门禁，不得上升）

诚实边界：真实语料的判定正确率约 60% —— 词面方法分不清「用户的话」和「粘贴的文档内容」， 也分不清同形不同义的词。这不是要修到 100% 的 bug，而是这类检索的天花板； 不追 100% 召回 —— 追到 100% 通常意味着把业务词当主题锚点，通用查询反而被带偏。 每条断言的来源、证据与复现路径见 docs/VERIFIABILITY.md。

这仍然不是向量检索，而是零依赖、零成本、可解释的关键词指纹。对"说法完全不同但语义相同"的需求召回有限——这是刻意的取舍。公式、各维度含义与阈值标定依据见 docs/design.md。

输入清洗：接口 JSON / 堆栈 / 数据对不会淹掉需求（0.7.1 → 0.7.4）

真实需求里约 38% 会把接口返回或错误堆栈整段粘进来（实测最长 21K 字）。spec_recall 会先剥掉 代码块、堆栈行、内部路径、内联 JSON，以及「标识符 + 时间戳/数字」的数据对 （checkInTime 2026-10-19T23:50:00 这类），再回填字段名（排除 id/status/data 这类通用键，最多 8 个）。 字段名是"改哪个字段"的唯一线索，不能跟着 JSON 一起丢掉；但也不能全收——全收会把向量撑大、反向拉低命中。 覆盖率分母与证据判定用同一套过滤口径，需求写得越详细分数越低的反向问题已修掉 （实测同一主题：短句 0.658 → 贴原文 0.298，修复后 0.599）。

原文直接传，不要手工删 JSON：清洗与字段提取在插件内部完成，手工删会丢掉字段名。

升级到 0.7.5 后重建一次指纹

0.7.1 起指纹生成方式多次变更（同义词归一、领域词提权、分级配额、tags 配额 16、路径不产出 token）， 存量模板不会自动更新：

npm run rebuild -- --dry-run   # 先看每份模板的 token 变化
npm run rebuild                # 写回，保留 hitCount / created / lastUsed

6. 成本控制：少往返 + 大文件纪律

• 少往返 —— 简单需求从 3 次工具往返降到 1 次。用真实模板库回放 7 条样本，合计调用 22 → 14 次（−36%），简单需求全部 3 → 1 次（−67%）
• 常驻开销透明 —— 常驻提示段约 489 token，四个工具定义约 2237 token，只出现在发往模型的完整请求里（npm run token-audit 实测）
• 真正的成本大头是整读大文件 —— 一次实测里，两个 >100K 字符的文件被整读后，在其后约 73 步被反复重计，占整轮约 50%。所以「大文件纪律」写进了常驻提示与 Skill：>20K 字符的文件禁止整读，先 grep 定位再分段读；确需整读先落要点摘要

完整成本归因见 docs/design.md。

一次任务长什么样

收到编程需求
     ↓
spec_recall ── 翻模板库 + 项目禁区，给出 nextStep
     ↓
  implement（直接动手） / confirm（问一次） / triage（仅 L3，先体检）
     ↓
   写代码（大文件先 grep 定位）
     ↓
spec_retro ── 过得了复用价值三问才沉淀 → 下次同类需求被自动召回

安装

前置：dsh 可用、Node 22+、pnpm 在 PATH 上（dsh plugin 内部转发 pnpm）。

dsh plugin --profile web add github:<你的账号>/dsh-spec-forge
dsh web   # 必须重启，插件才会组合进插件树

验证装上了（--dump-config 只合成插件树、不启动服务，是排障第一招）：

# Bash / Git Bash
pnpm dsh --profile web --dump-config | grep spec-forge

# PowerShell
pnpm dsh --profile web --dump-config | Select-String spec-forge

出现 # == dsh-spec-forge 段即成功。本地源码调试、以及 --patch 加载的坑见 docs/operations.md。

快速验收

装完之后照着发几条，观察行为：

1. 明确需求（"index.vue 加 isMainAdmin 字段，开关，默认 0"）→ 直接动手，不追问
2. 取值型小改（"改一下这个文案"、"调一下间距"）→ nextStep=implement，只调一次 spec_recall 就动手
3. 容器型缺内容（"登录页加个按钮"）→ nextStep=confirm，先用一次 ask_user_question 问清
4. L2 模块级（"给订单模块加导出，要 Excel 和 CSV"）→ nextStep=implement，默认值内联，一次召回即动手
5. 过短且无锚点（"帮我优化一下那个查询"）→ nextStep=confirm，先问清核心一项
6. 整体重构 / 架构级（"把后台项目重写一遍"）→ nextStep=triage，完整先问后查
7. 完整需求（路径 + 禁区 + 验收命令）→ 走完 召回 → 体检 → 提炼 → 实现 → 沉淀

模板落盘位置：ls /.dsh-spec-forge/projects//templates/

配置

全部参数都有默认值，一般不用动。要调（比如改命中阈值 matchThreshold、换模板库位置 storageRoot）就改 profile 目录的 cordis.patch.yml：

# 顶层数组；⚠️ id 定向补丁会「整体替换」该行 config，必须完整重述所有字段
# 下面就是全部 12 个参数的默认值（tests/contract.test.js 会检查示例是否漏项）
- id: spec-forge
  config:
    autoRecall: true
    autoRetro: true
    matchThreshold: 0.15
    maxInjectTemplates: 2
    injectMaxChars: 4000
    preStepRouting: true
    defaultScope: project
    storageHome: ''
    storageRoot: workspace
    retroMinToolCalls: 2
    retroRequireCodeChange: true
    strictDistill: true

参数全表、写法细节与坑见 `docs/operations.md`。

已知边界

1. dsh 还是开发者预览版。 插件锁定的 API 面是 ctx.tools.register / systemPrompt / skills / exec.agent.session。升级 dsh 后失效先 --dump-config 排查。
2. 匹配不是向量检索。 关键词指纹对"说法完全不同但语义相同"的需求召回有限，是刻意的零依赖取舍。词面方法还有两道上限：同形不同义（「日志页面」和「用日志定位」）与粘贴长文档（文档里恰好同时出现模板的主题词）——真实语料上命中判定正确率约 60%，这是方法天花板，不是待修 bug。
3. 召回效果取决于模板库本身。 真实项目里只有少数高频主题值得沉淀；命中率低通常说明库太窄，补模板要按语料频次来，不凭印象。
4. 沉淀时机有三层保障但非绝对，理论上仍可能漏——漏了会提醒，或直接说"把这次沉淀成模板"。
5. 分级是启发式，且部分约束是软约束。 判据基于正则信号，生僻表述可能漏检——漏检一律回退 L2（按默认执行），不会默认 L1 瞎干；"提问前不许扫工作区"这类急停规则写在模型可见的文本里，实测有效但模型仍可能违背。
6. 插件与宿主同进程同权限。 只读写数据目录，不联网、不执行 shell、不读凭据；源码公开，装前可自行审查。

卸载

dsh plugin --profile web remove dsh-spec-forge
# 若声明了 dsh.bundle.patch，还需清理 profile 的 cordis.patch.yml 对应行
dsh web   # 重启生效

模板数据在插件目录之外，卸载不删沉淀。

更多文档

• docs/design.md —— 分级判据、召回打分公式与阈值标定、成本归因
• docs/VERIFIABILITY.md —— 判定链断言可复核表：每条断言给来源、证据、复现路径，以及实测指标、已知边界与「试过但回退」的负结果
• docs/operations.md —— 存储模式与迁移、配置全表、排障、测试与验收、发布流程
• CHANGELOG.md —— 逐版本变更记录

许可证

MIT