dsh-skill-manager · 插件文档

> 让 DSH Web GUI 拥有「Skills」面板：查看已安装的技能列表，并用开关自定义每个技能的启用状态。

简介

在 DSH Web GUI 侧边栏提供「Skills」入口，点击打开技能管理面板：列出当前会话可见的全部 Skill（名称、描述、来源），按「全局 / 局部」分组，每个 Skill 带一个开关。关闭开关后，该 Skill 对模型目录（<available_skills>）、skill 工具与用户 /名称 手势全部不可用；重新打开即恢复。开关状态持久化于 ~/.dsh/dsh-skill-manager.json，跨会话、跨重启生效。面板还支持技能的增删改（新增/导入、编辑、删除带二次确认）。

能力清单

形态与架构

• 形态：树外 npm 包（本地 link 安装，@dsh-external/dsh-skill-manager）
• 平台：Host + Client 两端
• 关键依赖：

- Host：ctx.skills（SkillRegistry，inject: ['skills', 'webServer']）、ctx.get('sessions' | 'agents' | 'agentPresets')、agent/created 事件

- Client：react / react-dom/client（平台模块表）、原生 fetch、ctx.sessions（当前会话 id） - 通信：/api/dsh-skill-manager/state 与 /api/dsh-skill-manager/toggle（均为 POST + JSON body { sessionId }，回环 + 同源防护）

会话视图与分组

面板展示的是当前会话可见的技能（与模型目录同源），并自动划分为两组：

• 全局 Skill：不依赖工作区即存在——用户根 ~/.dsh/skills、~/.agents/skills、预设 custom 根、仓库插件注册的技能；
• 局部 Skill：仅当前项目根（.dsh/skills / .agents/skills）出现的技能。

实现上对同一 registry 视图分别以 cwd: undefined（全局）与 cwd: 会话工作目录（全量）各做一次 list()，按名称差集划分，而非硬编码来源字符串。

开关生效机制（遮蔽 Provider）

DSH 的 skill 注册表（@deepseek-ai/dsh-skill）按 scope 分层合并提供方候选，同名以 rank 小者胜。本插件注册一个名为 skill-manager 的提供方：

1. 全局层：通过 host ctx.skills 注册（traceable proxy 使注册落入调用方 ctx 所在层）。 2. 每个活跃 agent 的视图：通过 agent.ctx.get('skills') 的 proxy 注册，落入 agent 层（比 preset standing 层更近，赢过所有 preset 内技能）；agent/created 事件对新 agent 幂等补注册。

对每个被禁用技能，该提供方返回一个占位候选：rank: -1000000000、invocation: { modelInvocable: false, userInvocable: false }、描述为禁用文案（与原文不同 → 目录 digest 变化 → dsh-tool-skill 自动重发目录）。

由此链路原生生效：

• 模型目录渲染 filter(isModelInvocable) → 排除；
• skill 工具报 not available for model invocation；
• /名称 手势注入因 isUserInvocable 为假而跳过；
• 无需修改任何 SKILL.md 文件，对所有来源（filesystem / runtime / bundled）的技能都有效。

切换开关时调用 control.invalidate() 使注册表缓存失效并发出 skills/change，目录在下一轮 agent/pre-step 热刷新。

使用方式

1. 安装（任选其一）： - 从 npm：dsh plugin --profile web add @lanxing/dsh-skill-manager - 本地 link（开发）：dsh plugin --profile web add link:<本目录绝对路径>（含空格路径请用 8.3 短名，如 H:/Projects/DEEPSE~1/plugins/dsh-skill-manager） 2. 重启 dsh web（新 bundle 需进程重启才进入 host 组合）。 3. Web GUI 侧边栏点击「Skills」打开面板：开关禁用/启用；「+」添加（表单或源码/导入）；「笔」编辑；「垃圾桶」删除（二次确认）。任意变更后下一轮对话目录自动更新。 4. 卸载：dsh plugin --profile web remove @lanxing/dsh-skill-manager 后重启。

发布与社区

• npm：@lanxing/dsh-skill-manager（npm publish，prepublishOnly 自动构建）
• GitHub：<https://github.com/Lanxing6480/dsh-skill-manager>
• 社区收录：仓库已打 dsh-plugin topic（github.com/topics/dsh-plugin），由 Oh-My-DSH 等聚合站自动同步

API 一览

| 路由（均 POST，回环 + 同源防护） | payload 要点 | 返回 | |---|---|---| | /api/dsh-skill-manager/state | { sessionId } | { global[], local[], cwd, disabledCount } | | /api/dsh-skill-manager/toggle | { sessionId, name, disable } | 同上 | | /api/dsh-skill-manager/read | { sessionId, name } | { name, source, path, frontmatter, body, raw } | | /api/dsh-skill-manager/create | { sessionId, scope: 'global'\|'local', name, description, whenToUse?, content? } 或 { sessionId, scope, raw } | 最新视图 | | /api/dsh-skill-manager/update | { sessionId, name, description, whenToUse?, content? } 或 { sessionId, name, raw } | 最新视图 | | /api/dsh-skill-manager/delete | { sessionId, name } | 最新视图 |

增删改只作用于可写根：全局 → ~/.dsh/skills/<name>/SKILL.md；局部 → <项目根>/.dsh/skills/<name>/SKILL.md（编辑/删除亦支持 ~/.agents/skills 与项目 .agents/skills）。raw 模式按 frontmatter 里的 name 落盘、原文保存。

源码与版本

构建：pnpm install && pnpm build（tsdown 双面产物 lib/index.js + lib/client.js；构建基础设施复制自 maid-atelier 的 build/tsdown.client.ts）。改源码后重建并重启 DSH 生效。

限制与注意事项

• 对「冷会话」的 / 弹窗：被禁技能在无活跃 agent 的冷会话弹窗里可能仍短暂可见（standing 层无遮蔽），有活跃 agent 的会话不受影响。
• 生效时机：开关切换影响的是下一轮对话的目录；正在进行的轮次不会中途变化。
• 多 agent 视图：每个 agent 的视图单独注册遮蔽；agent 退出后其注册随 fiber 自动清理。
• 状态文件：~/.dsh/dsh-skill-manager.json 为普通 JSON；损坏时自动按空状态启动（已禁用项全部恢复启用）。
• 与 SKILL.md frontmatter 的关系：面板开关不改 skill 文件（经遮蔽 Provider 实现）；文件中已有的 disable-model-invocation / user-invocable 仍独立生效，面板会如实显示其调用策略。编辑功能保留 frontmatter 的其它字段，但不保留注释与字段顺序（yaml 重新序列化）。
• 增删改边界：仅可写根（用户根 + 当前会话的项目根）；DSH 安装目录（custom/bundled）与运行时注册的技能只读，界面标「只读」。
• HTTP 路由：仅接受回环地址 + 同源请求（与 dsh-ssh 路由族同款防护）。

维护位置

• plugins/dsh-skill-manager/（本项目仓库），独立 npm 包，非 dsh-web-ui 聚合包成员。

变更日志