dsh-skill-manager · 插件文档

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

简介

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

能力清单

| 能力 | 说明 | |---|---| | 侧边栏入口 | 「Skills」按钮，与 dsh-ssh / dsh-task-board 入口共存，折叠侧边栏时只显图标 | | 技能列表 | 会话视角：名称、描述（截断）、来源、调用策略状态；分组为「全局 Skill / 局部 Skill」；支持按名称/描述搜索 | | 自定义开关 | 每行一个 toggle；禁用/启用即时持久化 | | 添加技能 | 每组标题栏「+」按钮：表单模式（name/description/whenToUse/正文）或源码模式（完整 SKILL.md 文本），可导入本地 .md 文件 | | 编辑技能 | 可写技能（user-dsh / user-agents / project-dsh / project-agents）行内「笔」按钮：表单或源码视图编辑，frontmatter 其它字段（metadata、disable-model-invocation 等）保留 | | 删除技能 | 可写技能行内「垃圾桶」按钮，删除前二次确认 | | 只读标记 | custom / bundled / runtime 来源的技能标「只读」，隐藏编辑/删除 | | 目录热刷新 | 任意变更（开关/增删改）后调用 skill 注册表失效通知，下一轮对话目录自动更新，无需新建会话 | | 状态持久化 | ~/.dsh/dsh-skill-manager.json（{ version, disabled: { name: {description, whenToUse, source, provider, disabledAt} } }） |

形态与架构

• 形态：树外 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. 安装：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 @dsh-external/dsh-skill-manager 后重启。

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 落盘、原文保存。

源码与版本

| 版本 | 变更说明 | 状态 | |---|---|---| | 0.1.0 | 初版：侧边栏入口、列表、开关、遮蔽 Provider、持久化 | 当前 |

构建：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 聚合包成员。

变更日志

| 日期 | 版本 | 变更 | |---|---|---| | 2026-08-14 | 0.1.0 | 初版实现与安装验证 | | 2026-08-14 | 0.2.0 | 会话视角 + 全局/局部分组；技能增删改（+ 添加/导入、笔 编辑、垃圾桶 删除二次确认） |