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 段配置：

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 网格标定并增补词表。