技能召回提示 Gavin237/dsh-capability-hint

dsh-capability-hint

让“装了但想不起来用”的技能真正被调用。

在每轮第一步（agent/pre-step，step === 1）注入一行「本轮可能适用：X」的能力提示。

为什么要它（意义）

一个实测出来的问题

技能越装越多，但真正被调用的永远是硬驱动的那几个。

实测两个 harness、共 5.5 个月的真实会话（DSH 76 会话 / WorkBuddy 461 会话）：

| | DSH（1 个月） | WorkBuddy（4.5 个月） |
| 工具调用总数 | ~7,700 | 18,685 |
| skill 调用 | 41 次 | 224 次 |
| 技能占比 | 0.4% | 1.20% |

技能目录里实际加载 338 条，一个月只用过 16 条 —— ≥87% 零调用。

为什么？技能分两种

| 类型 | 例子 | 用量 | 为什么 |
| 任务强制必需 | feishu-doc、docx、浏览器自动化 | 高 | 不调用就做不了事 |
| 业务专用 | 绑定某条产线/项目的技能 | 最高 | 任务一出现就必须用 |
| 通用方法论 | brainstorming、systematic-debugging | ≈0 | 不用也能把活干完 |

“不调用就做不了事”的技能在用；“调用了才更好”的方法论技能，死了。

它们没有硬需求驱动，只能靠主动召回 —— 而主动召回不存在。本插件补的就是这一层。

它带来的实际变化

- 对模型：每轮第一步多一行字，把该用的方法论技能摆到眼前
- 对人：拿到一个可证伪的指标（默认调用率），而不是靠感觉判断技能该留该退

怎么用

第 1 步：装

pnpm pack
dsh plugin --profile web add ./dsh-capability-hint-0.1.0.tgz -w

重启 dsh web 生效。

第 2 步：⚠️ 加你自己的触发规则（最重要的一步）

内置规则只有 3 条（src/rules.ts 的 BUILTIN_RULES）：

| 技能 | 触发的词 |
| brainstorming | 设计 / 方案 / 怎么做 / 想做个 / 打算做 / brainstorm |
| systematic-debugging | 报错 / 失败 / 不工作 / 排查 / debug / 坏掉 |
| writing-plans | 实施计划 / 分步骤 / 落地计划 / plan |

没命中这 3 条中的任意一条，就什么都不会注入 —— 这是设计，不是故障。

所以真正要用起来，必须按你自己的技能库改这张表：

// src/rules.ts
export const BUILTIN_RULES: Rule[] = [
{
skill: 'your-skill-name', // 必须与技能目录里的名字逐字一致
triggers: ['关键词1', '关键词2'], // 小写；中文直接写，匹配是子串比对
note: '为什么要有这条规则', }, // …继续加 ]

加规则的三条要领：

1. 只对“方法论层”技能建规则。 任务必需型（不调用就做不了事）不需要提示——它们自己会被想起来。给它们加规则只是噪音。
2. 触发词要写得“宽”。 漏掉一次真命中的代价，比多提示一行的代价大得多——本插件的取舍原则是宁可多提示一行，不可漏掉一个。
3. 别写太松的词。 如 plan 会命中 explain/plane。宽松是要有下限的。

改完 pnpm build，重启生效。

第 3 步：验证它真的在工作

新开一个会话，发一条含触发词的消息：

帮我做个设计方案

会话里应出现（接在你那条消息后面的 user 消息，不是系统提示）：

[能力提示] 本轮可能适用：brainstorming

第 4 步：看指标

const entries = ctx['dsh-capability-hint'].entries() // readonly LedgerEntry[]
const report = defaultInvocationRate([...entries]) // RateReport[]

rate 最低的排在最前 —— 最死的技能先暴露，这正是退役决策要看的。

⚠️ 读这个指标前必看：rate 的分子分母是两个不同计数单位，只有 rate === 0 可以安全解读为“从未被调用”。
且当前无持久化，重启即归零 —— 见 I3。

怎么关掉

cordis.yml（或 profile 的插件配置节） dsh-capability-hint: enabled: false

监听器仍注册（开销极低），但不注入任何消息、不记台账。改回 true 即恢复，无需重装。

彻底移除：dsh plugin --profile web remove dsh-capability-hint。

它不做什么

| 不做 | 说明 |
| 不替换技能目录 | 不重写 tool-skill、不改目录渲染、不删任何技能。目录瘦身交给官方配置（catalogDescriptionMaxLength），不写代码。 |
| 不改决策 | 提示是追加，不是拦截：先 await next() 拿到下游决策，只在 kind === 'enter' 时把一行提示排到 messages 末尾。既有消息一条不丢、不改、不重排。下游返回 reject 时原样透传，不追加。 |
| 不调 LLM | 全流程零模型调用。匹配是纯字符串子串比对（matchCapabilities），渲染是纯函数（renderHint）。 |
| 不重复注入 | 只在 step === 1（每轮第一次 proposal）匹配；且排除 source.plugin === name 的消息，插件永不可能匹配自己的输出。 |
为什么走 PreStepDecision 而不是 agent.inject()

注：本节最初把这条选择写成“对实施计划 Global Constraints 的显式偏离”。该表述过严—— spec 明确把 返回 {kind:'enter', messages:[...原消息, 提示]} 列为已验证能力（§12.6）。
它偏离的是计划里更严的措辞，不是 spec 的要求。保留本节是因为推理过程本身有价值：为什么另一条通道不够用。

agent.inject() 写的是 next-step 收件箱，而驱动在 preStep 里已经先
claim() 掉了本步批次、之后才派发 waterfall。官方文档
（docs/subsystems/core.md:139-144）原文即：“A running driver claims it at the nearest later step boundary… It may miss a request whose pre-step already claimed its batch.”

后果是提示必然晚一步到达 —— 该用它来选能力的那个模型调用看不到它，插件的前提目的落空。
能够落进本步的唯一机制就是 enter 决策的 messages。这条约束原本要防的是“干扰 tool-skill 的目录通道”和“操纵步骤决策”，而追加一行消息既不干扰目录（tool-skill 走的是 agent.inject()，另一个通道），也不改变进入/拒绝的决策本身。

其它明确不做：

- ❌ 不自动淘汰技能——只出报告供人判断，删除技能始终是人的动作。
- ❌ 不写 MEMORY.md / 技能库——纯内存台账，无持久化（见下）。
- ❌ 不做 agent/turn-stopping 强制作废——第一版只做零成本提示。
- ❌ 不追求覆盖全部能力——先覆盖 20–30 个高频的。

配置项

插件通过 Config schema（src/config.ts）声明，harness 在加载期校验：非法值会响亮失败，不会静默降级。

| 字段 | 类型 | 默认值 | 说明 |
| enabled | boolean | true | 总开关。关掉后监听器仍在，但从不注入。 |
| maxHintsPerTurn | number | 3 | 单轮最多提示几个能力（防止提示本身变成噪音）。 |
| hintPrefix | string | "[能力提示]" | 提示行的前缀标记。 |
| rulesPath | string | "hermes-intake-rules.json" | 触发规则表路径（绝对路径或相对包根）。 |
| excludeSkills | string[] | [] | 永不提示的技能名（黑名单，优先级高于规则表）。 |

注：maxHintsPerTurn 指按规则表顺序截断，不是按重要性排序。若在意命中顺序，需自行调整规则表里的排列。

另注：rulesPath 目前是声明而未消费的字段——apply() 用的是内置的 BUILTIN_RULES（src/rules.ts），尚未从该路径加载。改这个值当前不会改变行为。

安装

从仓库本地打包安装
pnpm pack
dsh plugin --profile web add ./dsh-capability-hint-0.1.0.tgz -w

package.json 的 files 白名单为 ["lib", "cordis.patch.yml"]，因此 tarball 只含构建产物与 bundle patch；lib/ 由 prepare 脚本（tsdown）在安装时重新构建。

如何关掉

最轻的方式——保持安装、只关注入：

cordis.yml（或 profile 的插件配置节） dsh-capability-hint: enabled: false

此时监听器仍注册（开销极低），但 apply() 里的分支不再进入，不注入任何消息、不记 applicable 台账。这是最可逆的关法：改回 true 即恢复，无需重装。

彻底移除：dsh plugin --profile web remove dsh-capability-hint，或直接删掉 cordis.patch.yml 引入的那一行。

停用条件（spec §10）

任一触发即停止，不追加投入：

| 条件 | 判据 |
| 机制无效 | 4 周观察期内，所有能力的默认调用率均无上升 |
| 匹配失效 | 提示被采纳比例 < 20%（提示基本是错的） |
| 成本失控 | 单轮新增 token 显著超出预算，或影响会话响应 |
| 已被覆盖 | DSH 官方或社区出现等价机制（先查再建） |

读这个指标时的诚实限定

defaultInvocationRate() 的 rate = invoked / applicable，分子分母是两个不同的
计数单位：分母是“适用判定条目数”，分子是“被调用次数”。一轮里同一技能命中两次会记 2 条 applicable；一个技能 3 轮适用、在第 1 轮调用 3 次，rate 会显示 1。

只有 rate === 0 可以安全解读为“从未被调用”。 更高的值不可当作“按轮次命中率”。

怎么读到这些条目（I2）

apply() 的返回值只有直接调用 apply 的人拿得到，运行中的 harness 不持有它。
因此台账同时通过 ctx.provide 注册为 ctx 服务名 dsh-capability-hint：

const entries = ctx['dsh-capability-hint'].entries() // readonly LedgerEntry[]
const report = defaultInvocationRate([...entries]) // RateReport[]

两条路径指向同一个对象、同一个生命周期（ctx.provide 在插件卸载时自动注销）。
服务名常量导出为 LEDGER_SERVICE。

一个仍未关闭的盲区：invoked 分子 observeToolCall 按 toolName === 'skill' + args.name 识别调用，该形状是读源码核实的，不是跑出来的：invoked 分子没有任何真实 harness 会话的端到端验证。

已核实的部分：tools/result 是真实的 emit 事件（签名 docs/subsystems/tools.md:714）， exec.arguments 是注册表已解析并深冻结的对象（dsh-tools/lib/types/index.d.ts:204-205），工具模型可见名 skill 与 dsh-tool-skill/lib/index.js:60-66 一致。因此“工具名被加载器换掉”这一具体假设风险较低 —— 它不是主导原因。

真正主导的原因是时机与分母（本次已修）：修复前提示晚一步到达，且分母会因每步重新自触发而膨胀，导致每一次判定都对应不到任何真实的调用机会。修复之后，剩下的风险按可能性排序：

1. 会话内观测窗口太短 —— 4 周观察期的数据被进程重启切成碎片（见下 I3）。
2. lastTurn 归属 —— tools/result 载荷里没有 turn，位次只能沿用本实例最近一次 agent/pre-step 观测到的轮次；跨实例/中途加载时会退化成哨兵 0。
3. 技能确实没被调用 —— 也就是插件真的没起作用。

看到全 0 报告时，先排除第 1、2 条，再下“该退役”的结论。

I3：没有持久化，所以 4 周停用条件是当前不可证伪的（待裁决）

spec 把台账映射到 ctx.storage，并要求跨周聚合（上表的停用条件是 4 周观察窗）。
本次有意不实现持久化，后果必须说清楚：

- 台账是进程内的。harness 重启 = 分母归零，历史一并消失。
- 因此 “4 周观察期内所有能力默认调用率均无上升”这条停用条件，以当前实现无法判定 ——没有一个能活过重启的分母，你永远只能看到“本次会话”的切片。
- 这不影响插件本身的可用性（提示照常工作），只影响退役判据的可执行性。

这被标记为需要人裁决的决策（实现 ctx.storage 持久化，还是把观察窗缩短到单次会话）。在裁决之前，请只把台账当作会话级诊断，不要据此做退役判断。

开发

pnpm test # vitest
pnpm typecheck # tsc --noEmit
pnpm build # tsdown → lib/

三个都要过。本项目有过 pnpm test 全绿而 pnpm typecheck 失败的先例——测试绿不等于树是健全的。