dsh-plugin-skill-autoroute · 技能自动路由

收到用户指令后，自动做一次技能路由：在 Host 侧按当前指令扫描实时技能目录，产出候选排名，并向该步注入恰好一条路由提示。 三种模式：候选简报（默认）／自动加载技能正文／强制调用 skill-router。

本机技能库有 47 个技能，但 skill 工具是被动的——模型得自己想起来去查。这个插件把「路由这一步」变成确定性动作：不再依赖模型是否记得，也不再依赖用户是否明说「该用哪个技能」。

1. 它到底做了什么

每条用户指令（source.kind === 'user'）的第一步，插件会：

1. 从 agent/pre-step 拿到这一步将要进入模型的消息；
2. 读 Host 的 skills 服务（list()），拿到当前作用域可见的技能目录；
3. 用确定性算法（不是 LLM 调用）给技能打分并排序；
4. 把一条合成 user 消息追加到这一步：

同一批指令只路由一次；轮次中途的新指令（steering）算新的一批。无关指令保持沉默（不硬凑候选），这与本地 skill-router 的静默规则一致。

注入的消息带生产者标签 { kind: 'skill-autoroute' }，因此不会被本插件自己的触发过滤器误认成用户指令，也不会被后续步骤重复路由。

需要先装 skill-selector / skill-router 吗

不需要。 路由能力（打分、中文桥接词典、同域政策表）已经内化在插件里，默认的 brief 模式完全自给，一个 router skill 都不依赖。

routerSkills 是候选列表、取第一个已安装的，所以 ['skill-selector', 'skill-router'] 在本机两种命名下都能用：

- id: dsh-plugin-skill-autoroute
  config:
    mode: router
    routerSkills: ['skill-selector', 'skill-router']

技能正文（SKILL.md）刻意不打包进插件：内容永远由宿主的 skills 服务实时提供（@deepseek-ai/dsh-skill-filesystem 的 customSkillDirs，或 @nanmicoder/dsh-skills-hub 的 skillsRoot 指向的那个技能根），避免插件内出现第二份会漂移的策略副本。

2. 挂载点（为什么这样接）

无客户端半边：注入内容走正常对话记录，界面无需改布局。消息构造优先用 Host 的 createUserMessage；若运行时无法解析 @deepseek-ai/dsh-llm，则使用结构等价的本地构造器（同字段、uuid id、deepFreeze），不会让插件整体失效。

3. 配置

写在 profile 的 patch 层（<DSH_PROFILE_DIR>/cordis.patch.yml），后面的层覆盖前面的层；改完记得按 §5.4 toggle 一次该行，否则运行中的 Host 不会重读文件：

- id: dsh-plugin-skill-autoroute
  config:
    mode: brief          # off | brief | load | router
    routerSkills: ['skill-selector', 'skill-router']
    candidates: 3        # 简报里列几个候选（1–25）
    catalogLimit: 400    # 一次路由最多扫描多少技能
    explain: true        # false = 去掉「命中词」行，简报更省 token
    minScore: 0.28
    loadMinScore: 0.55
    locale: zh           # zh | en
    debug: true          # 每次路由决策打一条 Host 日志

切换模式只需改一行 mode。想要「完全不用模型再决定」就用 load（插件自己选中并注入正文）；想要字面意义的「自动调用一次 skill-select/skill-router」就用 router。

4. 路由算法（可复核，不是黑盒）

fieldWeight(词) = 4（名称/别名） | 2（when_to_use） | 1（description）
idfFactor(词)   = 0.6 + 0.4 × idf(词)/maxIdf      // 稀有词命中更值钱
evidence(词)    = 查询词权重 × fieldWeight × idfFactor
strength        = max(显式点名 8, evidence × 政策系数, 本地优先表下限 3.2) + 意图加分 4.5
排序            = strength 降序
展示分          = 1 - exp(-strength / 3.2)

• 中→英桥接词典（lib/lexicon.js，约 180 条）：技能名和描述以英文为主、指令以中文为主，纯词面匹配几乎打不中（评审 永远遇不到 review）。词典让中文 n-gram 额外投出英文证据词，权重 ×0.85。可用 lexicon 配置追加。
• 本地政策层（lib/local-policy.js）：把 skill-router/references/local-overrides.md 的规则落成代码——元技能族在业务题降权、在元指令按意图提升；PDF/PPTX 作为交付格式时把同名技能整个剔除（F1/F2）；同域优先表（评审工程 / 碎片重排 / 成片流水线 / 转写 / 插件盘点…）给出加成或直接播种候选（中文「转成中文字幕」与 openai-whisper 零词面交集，只能靠政策播种）。
• 指针不越界：政策表只会提升/播种已安装的技能；名字解析不到就什么也不做。
• 静默规则：没有任何候选达到 minScore 时不注入，避免把噪音塞进上下文。

5. 安装与验证

5.1 安装（推荐走 plugin_manager）

plugin_manager install_bundle → target: link:<path-to-this-repo>

或手工（等价）：

# <DSH_PROFILE_DIR>/package.json → dependencies
"dsh-plugin-skill-autoroute": "link:<path-to-this-repo>"
# <DSH_PROFILE_DIR>/package.json → dsh.profile.bundles 追加 "dsh-plugin-skill-autoroute"

然后 pnpm install（或让 plugin_manager 代跑）并重启 DSH；cordis.yml 不用改（该文件是生成物，patch 层才是编辑点）。

5.2 离线验证（无需重启）

要求 Node ≥ 22（node --test 自带 glob 展开）。技能根默认取当前目录下的 .agents/skills，可用 SKILL_AUTOROUTE_ROOT 覆盖。

# 33 个单元/回归测试（真实技能池不存在时，两个准确率套件会自行跳过）
node --test "test/*.test.mjs"

# 单条指令看排名与将注入的文案
node scripts/route.mjs "把这次的会议录音做成可继续修改的评审工程，加字幕和候选标记" --notice --root test/fixtures/skills

# 批量跑校准集 / 留出集（期望值写在 fixtures 里；需要有对应技能的真实技能池）
$env:SKILL_AUTOROUTE_ROOT = '<your skill root>'
node scripts/route.mjs --batch test/fixtures/calibration.txt
node scripts/route.mjs --batch test/fixtures/holdout.txt

scripts/route.mjs 走的是生产同一条打分路径（同 lib/router.js），只是目录来自文件系统而不是 Host 服务；test/fixtures/skills/ 是随仓库提交的小型固定池，CI 用它做确定性回归。

5.3 上线后怎么确认在工作

• Host 日志：[skill-autoroute] armed (mode=..., candidates=..., catalogLimit=..., ...)；debug: true 时每次决策一条。
• 只在可被模型调用的技能里选（SkillInvocationPolicy.modelInvocable）；若该组合没有注册 skill 工具，挂载时会打一条 warning。
• 对话记录里出现 role=user、来源 skill-autoroute 的一条消息（form: notice 或 instructions）。
• mode: router 时，模型下一步应当出现一次 skill(name="skill-router") 调用。

权威结论见 docs/verification.md（含本机实测数据与命令输出）。

5.4 改动如何生效（2026-10-07 实测，别踩坑）

结论：调参/换模式 = toggle 即可；改算法/词表代码 = 重启一次。

5.5 发布（维护者）

流程写在 RELEASING.md：CI 每次 push 都会跑契约检查（scripts/verify-bundle.mjs，专抓「装得上但什么都不加载」那类缺陷）并构建一次发布包；只有打 v* tag（或手动触发 Release workflow，默认草稿）才会真正发布 Release 资产。

6. 已知限制

1. 只读全局技能层：ctx.skills.list() 未带 scope，因此 agent preset 私有层注册的技能不会进入候选。本机技能都来自 Host 层（@deepseek-ai/dsh-skill-filesystem + @nanmicoder/dsh-skills-hub），故当前无影响；插件读的是 Host 服务而不是磁盘，所以运行时会看到 49 项（磁盘目录 47 项 + 2 个非文件系统来源）。
2. 不做 LLM 路由：确定性、零额外模型调用、可离线回归；代价是中文词典和同域优先表需要人工维护（新增技能/新说法时补词）。
3. 显式点名优先：用户明确说了某个技能名时会压过意图判断（例如同时说「Obsidian」和「出版包」时给出 obsidian）。这是 resolution-order.md「用户点名优先」的取舍，可用 pins 或 rulesEnabled: false 调整。
4. 每批指令一次：同一批消息（同一组 message id）只路由一次，之后不再重复注入；轮次中途的新指令会产生新的一批。
5. 准确率是测出来的，不是声称的：留出集 11/12 首选、12/12 入选；细节与未命中项见 docs/verification.md。

7. 卸载

plugin_manager remove_bundle → dsh-plugin-skill-autoroute

或从 profile package.json 的 dependencies / dsh.profile.bundles 移除后 pnpm install，并删掉 patch 层里的 - insert: 行。