dsh-skill-indexer
让 agent 用一句话意图，从本机所有 SKILL.md 里召回对的技能。
接入面 ——
skill_index 工具 /
/skill-index 命令 /
cordis.patch.yml
一个 DSH host bundle 插件：把本机所有 SKILL.md（默认 ~/.workbuddy/skills + $DSH_HOME/skills）建成两级（大类 → 技能）召回索引，用一句话意图路由到最匹配的技能，命中/低置信/未命中三态回退。接入面：skill_index 模型工具、/skill-index 命令、cordis.patch.yml 配置——纯本地、只读源目录、零第三方运行时依赖。
A DSH host bundle plugin that builds a two-level (category → skill) recall index over every local SKILL.md and routes a natural-language intent to the best-matching skills — three-state (hit / low / miss) fallback, read-only against the source trees, zero third-party runtime deps.
✨ 功能一览
- 🗂️ 两级召回索引：扫描
~/.workbuddy/skills 与 $DSH_HOME/skills，解析 SKILL.md frontmatter（手写 YAML 子集，block scalar 全量解析），抽取触发词/关键词并归纳大类，产出 skills-index.json（UTF-8、无 ASCII 转义、2 空格缩进）。
- 🎯 一句话意图路由：L1 大类打分（关键词覆盖 × IDF，
pos_weight=1/(1+start/10)）命中大类，L2 类内技能排序（词表 = keywords ∪ triggers ∪ name，trigger 命中 ×1.5）；短查询靠单个词即可命中（「把这周的ETF拉出来画个图」→ etf）。
- 🔁 三态回退：
hit 命中 / low 低置信（回退全库 flat top-k）/ miss 未命中（明确告知）；默认 θ1=0.35、θ2=0.12。
- ⚡ 零第三方运行时依赖：scan/parse/extract/classify/index/route 只用
node:fs/path/crypto，唯一外部包是宿主自带的 @deepseek-ai/dsh-tools（defineTool）。
- 🔒 只读 + 哈希增量：不改动技能源目录，索引与
usage.log 只写 dataDir；scan 按内容 hash 对比，未变技能保留 usage_count/last_used，无变更时提示 "(no changes)"。
- 🧩 人工大类覆盖：
categories.yaml 可对指定技能直接指定大类，优先级高于内置词表归纳。
Quick Start
前置
- DSH（DeepSeek Harness）web profile
- Node.js ≥ 18
安装
dsh plugin --profile web add github:NattoCB/dsh-skill-indexer
或手工把 cordis.patch.yml 的 insert 段合并进目标 profile 的 patch，然后 pnpm install。
运行
安装后 host 启动即自动建索引。手动控制：
/skill-index scan # 重建索引（无变更时提示 "no changes"）
/skill-index query 把这周的ETF拉出来画个图 # 意图召回
/skill-index categories # 打印大类表
/skill-index status # 索引状态与各 root 计数
agent 侧直接调用模型工具：
skill_index(query="把这个PDF转成markdown")
# → { state, intent, categories, hits, text }；text 为可直接注入的上下文
开发 / 测试：
npm test # node --test，43/43 通过
npm run demo # 扫描默认 roots 并路由示例意图
Configuration
通过 cordis.patch.yml 的 config 段配置：
| Key | Default | Meaning |
|---|
roots | []（缺省 ~/.workbuddy/skills + $DSH_HOME/skills） | 扫描根目录；路径数组或 [{path, type}] |
theta1 | 0.35 | 命中阈值（max_c ≥ θ1 → hit） |
theta2 | 0.12 | 未命中阈值（max_c < θ2 → miss） |
dataDir | $DSH_HOME/skill-indexer | skills-index.json 与 usage.log 输出目录 |
categoriesYaml | '' | 可选 categories.yaml 人工大类覆盖，优先级最高 |
categories.yaml 示例：
overrides:
git-finish-work: ["git-workflow", "delivery"]
pdf-to-markdown: docs
设计要点
- 匹配原语：子串匹配（英文小写化去标点、中文直接子串），不是 token 集合交集；
idf = ln((N+1)/(df+1)) + 1。
- 确定性：全流程无随机数，同输入字节级一致（除
generated_at）。
id 规则：唯一名 → id = name；跨 root 重名 → name@type（如 pdf-to-markdown@dsh）；categories[].skills 与 skills[].id 引用闭合。- 源规格：skill-indexer PRD v1.1（2026-08-19，本地文档未公开）——两级索引、三态回退、哈希增量与验收标准 A1–A5 / B1–B5 / C1–C4。
- 非目标：无常驻进程、无 HTTP 服务、无 UI、无 embedding/GraphRAG。
已知限制
- 中文关键词按「连续中文串」抽取，长串会粘住短词（如「当面对高杠杆」粘住「高杠杆」），短查询召回偏弱。
- 内置大类词表（10 类）是 MVP 覆盖；跨机部署前建议在目标语料上做
θ1/θ2 网格标定并增补词表。
