dsh-skills-reference

dsh-skills-reference

DSH 插件：跨工作区 skill 引用。源工作区拥有 skill，其它工作区声明引用，一处更新处处复用，无需手动复制。

面向 DSH 0.2.0-rc.2（web 端与桌面端同一运行时）。

功能

• 引用声明：在工作区本地 .dsh/skill-references.yml 声明「展示名 + 源工作区根路径」。
• 引用注册：复用官方 dsh-skill-filesystem 发现机制，把源工作区 .dsh/skills 整体注册进当前会话；源目录变化即时失效重发现，无需重启。
• 可视化面板：输入框工具行「skill」入口（权限选择器右侧），图形化查看 / 添加 / 删除引用，预览已生效 skill 清单并逐个启停。

引用语义

• 纯跟随（只读，改动回源工作区统一改，本地不派生）。
• 目录级引用 + 单 skill 白名单：声明条目可带 skills 列表，只有列表内的 skill 生效；缺省或空列表表示该源全量生效。
• 同名冲突时引用源优先；被停用的引用源 skill 不占名，本地同名因此可回退。

安装

走插件管理器（一键安装）

插件页安装以下任一来源：

• registry 名：dsh-skills-reference
• GitHub：github:TheChengXi/dsh-skills-reference

安装成功后包名被追加进 profile 的 dsh.profile.bundles，包内 cordis.patch.yml 负责把插件行插入组合，host 半与 client 半随之加载。通常无需重启进程。

本插件的构建产物随仓库提交（lib/**），因此从 GitHub 安装不需要放行任何构建脚本，装完即用。

本地开发：同步到 profile

pnpm run sync    # 构建并同步 lib/ 与 package.json 到 web profile，之后重启 DSH 生效

目标 profile 根默认 ~/.dsh/profiles/web，可用 DSH_PROFILE_NAME 换 profile，或用 DSH_PROFILE_DIR 直接给出 profile 根目录（在 DSH 会话内它已被注入为当前 profile 根）。插件目录恒为 <profile 根>/node_modules/dsh-skills-reference——不要把 DSH_PROFILE_DIR 指到插件目录本身，那会把 package.json 写到 profile 根并覆盖 profile 清单。

web profile 若已有手工的 skill-reference patch 行，不要再把本包加入 dsh.profile.bundles，否则同一 id 会被插入两次。

用法

声明文件

- name: skill-hub
  path: D:\workspaces\skill-hub

path 填写源工作区根目录（该目录里能直接看到 .dsh 文件夹），插件会自动取 <path>/.dsh/skills。

⚠️ 常见错误：把 path 选到 .dsh、.dsh/skills 或单个 skill 目录，会被拼成 <path>/.dsh/skills 而找不到。选中「能看到 .dsh 的那个目录」就对了。

面板操作

在目标工作区打开会话 → 输入框工具行点「skill」→ 面板内「添加引用」用目录选择器选源工作区根 → 保存。写后立即生效，无需重启。

开发

pnpm run build   # tsc 编译 host（lib/*.js 与 *.d.ts）+ esbuild 打包 client（lib/client.js）
pnpm run test    # 单测
pnpm run typecheck

改动源码后必须重新构建并提交 lib/：插件从 GitHub 分发，产物不入库就装不起来（pnpm 对 git 依赖只执行 prepare，且该脚本在 pnpm 10.26+ 默认被拦截）。

运行时版本对齐

插件面向 DSH 0.2.0-rc.2。安装与启动时，DSH 会按 semver.satisfies(运行时版本, peer 范围) 校验 peerDependencies 里 @deepseek-ai/dsh* 的项，不匹配即拒绝安装并回滚 profile 清单。

web 端运行时升级

若 web 端仍是 0.1.5-rc.3，需先升级再使用本版本（0.2.0 起 Typert 契约以 codec.create() 取代 codec.schema，旧运行时上插件无法加载）：

npm i -g @deepseek-ai/dsh@0.2.0-rc.2

升级后自行重启 DSH 生效。

测试

pnpm run test 覆盖数据层、发现 provider、RPC 契约、来源巡检与面板状态机；其中 test/skill-enablement.test.ts 用真实文件系统验证白名单过滤与 get 委派。

手工走查：源工作区建 .dsh/skills/alpha/SKILL.md，引用工作区在面板里声明该源，验证发现 / 实时更新 / 同名冲突 / 面板增删 / 预览即时刷新 / 单 skill 启停（保存后落盘生效）。