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 失败的先例——测试绿不等于树是健全的。