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 的 cwd>/.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. 模板沉淀：三层漏斗，同名幂等
不是每轮对话都值得存。沉淀由三层把关：
- 代码层硬门槛 —— 这一轮必须真实改过代码且工具调用数达标，纯问答/只读诊断直接拦下，不提示不打扰
- 复用价值三问（模型自检）—— 下次还会用吗？结论跨项目成立吗？用户会反复提吗？任一为否就跳过
- 任务链合并 —— 一条任务链只沉淀一次，中途的小修小补并进最终那份
漏了也有兜底：下次再提编程需求时，插件会提醒"上一轮改过代码却没沉淀"。你也可以直接说 "把这次沉淀成模板"，无条件触发。
模板同名幂等：同类需求再次沉淀是覆盖更新，不会无限堆积。每份模板六个段落——触发场景 / 需求澄清清单 / 标准改法 / 禁区 / 提示词模板 / 验收标准。示例见 templates/example-spring-pagination.md。
4. 项目禁区自动累积
会话里识别到的"不能改"（common/Result.java 别动、Controller 不写业务逻辑……）会累积到该仓库的 profile.md，此后所有同类需求自动注入，不用反复交代。禁区是硬约束，模型不得修改。
5. 召回：零依赖、可解释的关键词指纹
spec_recall 把需求原文拆成加权指纹，和模板库逐份比对打分，超过阈值就注入（默认最多 2 份），连同项目禁区一起。
打分是透明的六维计算，但命中由两道闸共同决定：
- 词汇相似度：
lexical ≥ matchThreshold（默认 0.15）；同分类、标签重叠、同仓库、新鲜度、热度只用于排序（rankScore = 0.9·lexical + 0.1·先验），不参与命中判定
- 主题证据闸：交集里必须有至少 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。
快速验收
装完之后照着发几条，观察行为：
- 明确需求（"index.vue 加 isMainAdmin 字段，开关，默认 0"）→ 直接动手，不追问
- 取值型小改（"改一下这个文案"、"调一下间距"）→
nextStep=implement，只调一次 spec_recall 就动手
- 容器型缺内容（"登录页加个按钮"）→
nextStep=confirm，先用一次 ask_user_question 问清
- L2 模块级（"给订单模块加导出，要 Excel 和 CSV"）→
nextStep=implement，默认值内联，一次召回即动手
- 过短且无锚点（"帮我优化一下那个查询"）→
nextStep=confirm，先问清核心一项
- 整体重构 / 架构级（"把后台项目重写一遍"）→
nextStep=triage，完整先问后查
- 完整需求（路径 + 禁区 + 验收命令）→ 走完 召回 → 体检 → 提炼 → 实现 → 沉淀
模板落盘位置：ls <工作区>/.dsh-spec-forge/projects/<hash>/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。
已知边界
- dsh 还是开发者预览版。 插件锁定的 API 面是
ctx.tools.register / systemPrompt / skills / exec.agent.session。升级 dsh 后失效先 --dump-config 排查。
- 匹配不是向量检索。 关键词指纹对"说法完全不同但语义相同"的需求召回有限，是刻意的零依赖取舍。词面方法还有两道上限：同形不同义（「日志页面」和「用日志定位」）与粘贴长文档（文档里恰好同时出现模板的主题词）——真实语料上命中判定正确率约 60%，这是方法天花板，不是待修 bug。
- 召回效果取决于模板库本身。 真实项目里只有少数高频主题值得沉淀；命中率低通常说明库太窄，补模板要按语料频次来，不凭印象。
- 沉淀时机有三层保障但非绝对，理论上仍可能漏——漏了会提醒，或直接说"把这次沉淀成模板"。
- 分级是启发式，且部分约束是软约束。 判据基于正则信号，生僻表述可能漏检——漏检一律回退 L2（按默认执行），不会默认 L1 瞎干；"提问前不许扫工作区"这类急停规则写在模型可见的文本里，实测有效但模型仍可能违背。
- 插件与宿主同进程同权限。 只读写数据目录，不联网、不执行 shell、不读凭据；源码公开，装前可自行审查。
卸载
dsh plugin --profile web remove dsh-spec-forge
# 若声明了 dsh.bundle.patch，还需清理 profile 的 cordis.patch.yml 对应行
dsh web # 重启生效
模板数据在插件目录之外，卸载不删沉淀。
更多文档
许可证
MIT
