技能管理器 lijian-ui/dsh-skill-manage

dsh-skill-manage · 技能管理插件

为 DeepSeek Harness (dsh) 提供技能管理：在设置面板里列表 / 启用 / 停用 / 删除 / 添加 .zip 技能，并通过 agent 可调用的 skill_manage 工具，让 LLM 在会话中直接创建 / 修改 / 删除技能文件。同时支持 dsh web 端与官方桌面端。

功能概览

| 功能 | 说明 |
| 技能列表 | 按作用域（全局 / 工作区）分组展示所有技能，支持搜索 |
| 启用 / 停用 | 滑块按钮热切换，无需重启即可生效 |
| 删除技能 | 永久删除技能文件，带自定义确认弹窗 |
| 添加技能 | 选择 .zip 压缩包，自动解压安装到全局技能目录（~/.dsh/skills） |
| 技能详情 | Markdown 渲染技能内容，展示 frontmatter 元数据表格 |
| Agent 工具 skill_manage | LLM 可调用工具：通过工具调用创建 / 修改 / 删除技能，支持 global 或 workspace 作用域 |

背景

dsh 官方目前没有 skill 启用/停用控制功能——无 CLI 命令、无设置页 UI、无 slash 命令、无配置文件字段、无 API 方法。官方仅提供 frontmatter 的 disable-model-invocation 和 user-invocable 两个静态字段，需手动编辑文件，且 skill 仍被发现加载，只是从特定接口隐藏。

本插件通过 .disabled 文件重命名机制实现真正的开关控制：将 SKILL.md 重命名为 SKILL.md.disabled，dsh 官方 provider 只识别 .md 结尾的文件，.disabled 文件会被忽略，从而实现"停用"。

0.2.0 破坏性变更

本版本对下游使用者包含破坏性变更：

- typert RPC 契约对齐官方 create 工厂。host/client 编解码改为 create: () => schema（自 dsh 0.1.6-alpha.1 起要求）。不再兼容旧的仅 schema 契约（如 dsh-desktop 0.5.0）。
- 依赖改为 peerDependencies 并开放范围。所有 @deepseek-ai/ 包（含 cordis 与各 dsh-）现均为 peerDependencies 且使用 ^ 范围，运行时绑定宿主的 dsh 版本，而非锁定某个精确构建。本地构建的精确版本保留在 devDependencies。这也满足桌面端插件图校验器——它拒收声明在 dependencies 里的共享包。
- 天然跨端。同一份 bundle 在 dsh web 端与官方桌面端都能运行，无需为某端重写。（注意：插件按 profile 安装；装进 web profile 不会在 desktop profile 出现，反之亦然——那是 profile 隔离，不是不兼容。）

安装

前置条件

- DeepSeek Harness (dsh) web 端或官方桌面端，dsh >= 0.1.6-alpha.1
- Node.js >= 18（仅本地开发需要）

通过 dsh 安装

dsh plugin --profile web add @lijian-ui/dsh-skill-manage

--profile 为必填，指定安装到哪个 profile（web 或 desktop）。插件按 profile 隔离：装进 web 不会在 desktop 出现，反之亦然。安装后重启应用。

本地开发

进入插件目录
cd extensions/dsh-skill-manage

安装依赖
npm install

构建
npm run build

监听模式
npm run watch

类型检查
npm run typecheck

构建产物在 lib/ 目录下，通过 junction 自动同步到 node_modules/@lijian-ui/dsh-skill-manage。每次构建后需重启应用加载新 bundle。

使用方式

1. 打开 dsh（web 或桌面）
2. 进入 设置 → 技能管理
3. 在技能列表中：
- 点击滑块按钮启用/停用技能
- 点击删除按钮永久删除技能
- 点击技能卡片查看详情
- 使用搜索框过滤技能
- 点击"添加技能"并选择 .zip 压缩包，导入到全局技能目录

Agent 工具 skill_manage

插件同时注册了一个名为 skill_manage 的 agent 可调用工具，LLM 可在会话中创建、修改或删除技能。

| 参数 | 类型 | 必填 | 说明 |
| action | create \| modify \| delete | 是 | 操作类型 |
| name | string | 是 | 技能名（仅小写字母、数字与连字符，如 my-skill） |
| description | string | 仅 create | 技能描述 |
| when_to_use | string | 否 | 技能触发时机说明 |
| content | string | 仅 create | 技能正文（Markdown） |
| scope | global \| workspace | 否（默认 global） | 写入位置：global → ~/.dsh/skills；workspace → /.dsh/skills |

- delete 复用与 GUI 删除相同的文件逻辑。
- workspace 作用域会从会话 cwd 向上寻找含 .git 的目录作为项目根。
- 所有写入都落在 dsh 主技能目录（~/.dsh/skills 或 /.dsh/skills），而 dsh 正是扫描这些目录，因此新建技能会被立即发现。

技能文件约定

| 状态 | 目录型技能 | 平铺型技能 |
| 启用 | /SKILL.md | .md |
| 停用 | /SKILL.md.disabled | .md.disabled |

技能作用域

| 作用域 | 路径 | 说明 |
| 全局 dsh | ~/.dsh/skills/ | 用户全局技能 |
| 全局 agents | ~/.agents/skills/ | agents 全局技能 |
| 工作区 | /.dsh/skills/ | 项目级技能 |
| 内置 | DSH_BUNDLED_SKILL_DIR | 随部署附带，不可修改 |

技术架构

目录结构

extensions/dsh-skill-manage/
├── src/
│ ├── index.ts # Host 端入口（inject: typert, settings, skills, sessions, agents, tools） │ ├── remote.ts # Host 端 RPC 方法（list/setEnabled/deleteSkill/importZip）+ skill_manage 工具注册 │ ├── skill-files.ts # 文件约定（DISABLED_SUFFIX、collectSkillEntries、frontmatter 校验） │ └── client/ │ ├── index.ts # Client 端入口（SECTION_ID、RPC 注册、inject） │ ├── SkillManageSection.tsx # 主设置页组件（卡片列表 + 滑块 + 详情弹窗） │ └── client-i18n.ts # 客户端国际化（中/英） ├── lib/ # 构建产物 ├── docs/ │ └── troubleshooting-and-bugs.md # 踩坑记录与官方 Bug 分析 ├── package.json └── tsdown.config.ts

Host 端（src/remote.ts）

提供以下 RPC 方法：

| 方法 | 功能 |
| list(sessionId) | 列出所有技能（含启用状态） |
| content(name, sessionId) | 获取技能完整内容 |
| setEnabled(name, sessionId, enabled) | 启用/停用技能（文件重命名） |
| deleteSkill(name, sessionId) | 删除技能 |
| importZip(sessionId, payload) | 解压 .zip 压缩包，导入技能到全局技能目录（/skills，默认 ~/.dsh/skills） |
| workspaces() | 列出可用工作区 |
| skill_manage（agent 工具） | LLM 可调用：create / modify / delete 技能（scope：global → ~/.dsh/skills，workspace → /.dsh/skills） |

Client 端（src/client/）

- index.ts：注册设置页 section，通过 ctx.slots.inject 注入到 dsh 设置面板
- SkillManageSection.tsx：React 组件，渲染技能卡片列表、滑块按钮、详情弹窗、删除确认弹窗
- client-i18n.ts：中英文翻译

开关机制

用户点击滑块 → client 乐观更新 UI（立即切换开关状态） → RPC 调用 host 端 setEnabled → host: rename(SKILL.md ↔ SKILL.md.disabled) → dsh chokidar watcher 检测到文件变化 → registry 缓存失效（revision++） → 延迟 800ms 后 ctx.emit('connection/reset') → client 端 fetches Map 清除 → 下次 / 补全重新查询 → 获取最新技能列表

已知问题与解决方案

启用技能后 / 命令补全不刷新

问题：启用技能后，聊天页面的 / 斜杠命令补全不显示新启用的技能。

根因：dsh 官方包 dsh-client-ui-skill 漏订阅了 skills/change 事件，导致 client 端技能列表缓存不会在技能文件变化时自动失效。

我们的解决：在 reloadAfterHot 中延迟 800ms 后调用 ctx.emit('connection/reset')，触发所有模块静默刷新缓存。用户在设置页中操作，不会感知到聊天界面的缓存刷新。

详见 踩坑记录与官方 Bug 分析。

国际化

支持中文和英文两种语言，翻译文件在 src/client/client-i18n.ts 中。语言切换跟随 dsh 桌面端的语言设置。

技术栈

- 语言：TypeScript
- 构建：tsdown (rolldown)
- 前端：React 18
- Markdown 渲染：@deepseek-ai/dsh-client-ui-primitives 的 MarkdownText 组件
- YAML 解析：yaml (frontmatter 解析)
- 文件监听：dsh 官方的 chokidar watcher（自动检测技能文件变化）
- 运行时依赖：fflate、yaml、zod
- 宿主依赖（peer）：全部 @deepseek-ai/ —— cordis ^4.0.0、各 dsh- ^0.1.0、dsh-tools ^0.1.0 —— 开放范围，运行时绑定宿主 dsh 版本

许可证

MIT

相关链接

- 踩坑记录与官方 Bug 分析
- DeepSeek Harness (dsh)