dsh-SkillsManagePlugins

---

这是什么？

DeepSeek Harness (DSH) 的 Skill 是放在目录里的 Markdown 指令文件（SKILL.md + 可选 frontmatter），DSH 的 AI 代理会按需加载它们来获得任务专用能力。但随着 Skill 越来越多，管理它们本身成了一个问题：

• 散落在不同目录，没有统一视图
• 编辑要手写 YAML frontmatter，格式错了 DSH 就不认
• 改名只改文件夹、忘了同步 frontmatter 的 name，Skill 悄悄失效

dsh-skills-manager 把这一切搬进 DSH Web 界面：以对话视图标签页的形式（和内置的「对话 / 轨迹」同一接缝，即 conversation.view），在会话中栏提供完整的可视化 CRUD。

✨ 功能特性

📸 截图

（截图待补充 —— 欢迎贡献！）

🚀 安装

前置依赖：DSH Web / Desktop ≥ 0.1.7-rc.2（含最新桌面版 0.2.0-rc.2）。管理器是会话中栏的一个视图标签页，不需要、也不再接入任何第三方侧边栏插件（dsh-better-sidebar / dsh-sidebar）。

已在 DSH Desktop 0.2.0-rc.2 实测：插件图加载、标签注册、/skills API 全链路（roots.info / list / get / create / update / delete / library.*）均通过。详细变更见 CHANGELOG.md。

# ① 从 GitHub 安装（推荐）
npx -p @deepseek-ai/dsh dsh plugin --profile <name> add github:z-col/dsh-SkillsManagePlugins

# ② 从本地路径安装（开发）
npx -p @deepseek-ai/dsh dsh plugin --profile web add /path/to/SkillsManagePlugins

无需构建脚本：仓库直接提交构建产物 lib/（host + client bundle），所以 add 开箱即用 —— 不会触发 pnpm ≥10 对 git 依赖构建脚本的拦截，也不需要 onlyBuiltDependencies 白名单。

⚠️ 不要执行 add dsh-skills-manager：npm 上的同名包属于第三方（Xichun123/dsh-skills-manager），与本项目无关。

安装后重启目标 profile（host 代码与 client bundle 变化需要重启），然后刷新浏览器页面。

🎮 使用方法

1. 打开任意一个已有内容的会话（新会话的空白页不显示视图标签栏）
2. 会话标题栏下方的标签栏里，对话 / 轨迹 右侧多出一个 Skills 管理器 标签
3. 点击标签 → 中栏就地切换为 Skills 管理器；点回「对话」即回到聊天
4. 管理器顶部可切换 Skill 库 / 全局 / 项目级 三个 tab

💡 新建 Skill 不在面板内提供：把 SKILL.md 目录放进 ~/.dsh/skill-library/<name>/ 即可出现在库中（或在全局/项目级直接建目录，打开 Skill 库会自动导入为原件）。

📦 三级模型速览

~/.dsh/skill-library/<name>/    ← Skill 库（唯一权威原件）
~/.dsh/skills/<name>/           ← 全局（副本 = 所有会话可用）
<项目>/.dsh/skills/<name>/      ← 项目级（副本 = 该项目可用，可同时存在于多个项目）
~/.dsh/skills-manager/index.json ← 项目索引（记录见过的项目，供库聚合与分发）

• 移至 = 拷贝：把库原件复制到目标层级（库原件保留）；同一 Skill 可同时存在于全局和多个项目。
• 某项目会话里，项目副本优先于全局同名副本（DSH rank：项目 100 < 全局 400），其它项目不受影响 —— 这是「一个 Skill 分发到多个项目」的底层保障。
• 首次打开 Skill 库时自动执行迁移：全局与已记录项目里的旧 Skill 会被拷入库（原件保留 = 视为已分发），老数据零丢失。
• 已知取舍：分发是拷贝，改库原件不会自动同步到副本 —— 对已存在副本的位置再点一次「移至」即可用库原件覆盖刷新。

💡 所有修改都实时落盘，DSH 的 skill 监听器会自动刷新目录，无需重启即可生效（host 代码变更除外）。

🔍 工作原理

┌─ Host 半（lib/index.js）───────────────────────────────┐
│  /skills/api/*  JSON API（webServer prefix 路由）       │
│  · 浏览器信任围栏：Host-header 回环或 trustedHosts      │
│  · 会话作用域：sessionId → 会话 header.cwd → 项目根     │
│  · 全部文件操作限定在已知 skill 根内（路径围栏）     │
│  方法：roots.info / skills.list / skills.get /          │
│        skills.create（库中新建+可选立即分发）/    │
│        skills.update（原子）/ skills.delete（全链路）/   │
│        skills.rename（全链路）/ skills.recycle（单层回收）│
│        skills.library.list / .assign / .recycle / .sync │
│        skills.openFolder（按 root 打开对应目录）         │
└─────────────────────────────────────────────────────────┘
┌─ Client 半（lib/client.js）────────────────────────────┐
│  · ctx.slots.inject('conversation.view')                 │
│    → 视图标签页 id='skills', order=20（对话 0 / 轨迹 10）│
│    （与内置「对话 / 轨迹」同一接缝；replaceRisk: none）  │
│  · 会话作用域由会话级 seat 的 inject 提供（sessionId）   │
│  · 面板内 Skill 库/全局/项目级可切换                     │
│  · 全部文案走 DSH locale 系统（zh/en）                   │
└─────────────────────────────────────────────────────────┘

复用的官方服务：ctx.skills 注册表（dsh-skill + dsh-skill-filesystem 已在 base bundle 启用，负责扫描与变化监听）。本插件直接读写文件系统，与官方 provider 的 frontmatter 契约保持一致（name/description 必填、kebab-case 名称）。同名 Skill 在全局与项目级并存时，DSH 以 rank 低的项目副本为准（dsh-skill-filesystem rank 100 < 全局 rank 400），这正是多项目分发安全性的依据。

📁 项目结构

SkillsManagePlugins/
├── src/
│   ├── index.ts              # Host 半：/skills JSON API
│   ├── skill-fs.ts           # Skill 文件系统操作（扫描/解析/CRUD/重命名）
│   ├── trust-fence.ts        # 浏览器信任围栏（与 /api 网关一致）
│   ├── wire.ts               # JSON API 信封工具
│   ├── context-types.ts      # 双面 Context 类型声明
│   └── client/
│       ├── index.tsx         # Client 半入口（注册 conversation.view 标签页）
│       ├── SkillsView.tsx    # 标签页正文（会话作用域的视图外壳）
│       ├── SkillsPanel.tsx   # 管理面板视图（列表/详情）
│       ├── api.ts            # client → host API 桥接
│       ├── state.ts          # 面板状态 store
│       └── locales.ts        # zh/en 文案
├── tests/                    # 单元 + 真实组合集成测试（50 项）
├── cordis.patch.yml          # profile bundle 挂载行
├── tsdown.config.ts          # 双产物构建（host ESM + client CJS）
└── package.json

🛠️ 开发

pnpm install
pnpm typecheck   # 双面（host + client）类型检查
pnpm test        # 单元 + 真实组合（真实 cordis + WebServer + 真实 HTTP）集成测试
pnpm build       # tsc 声明 + tsdown 双产物（lib/index.js + lib/client.js）
pnpm watch       # client bundle 热构建（配合 dev:web 的 HMR 链）

⚠️ lib/ 随仓库发布（GitHub 安装无需构建）。改完 src/ 必须 pnpm build 并把 lib/ 一起提交，否则从 GitHub 安装的人拿到的是旧产物。

构建产物：

• lib/index.js — host 半（/skills JSON API，fenced）
• lib/client.js — 浏览器半（window.__ModuleLoader__.load 包装的 CJS 闭包）
• lib/types/** — 双面声明

✅ 验证矩阵

• pnpm typecheck — host/client 双面类型检查通过
• pnpm test — 56 项：skill 文件系统单元测试（扫描/解析/CRUD/围栏/库的分配·回收·同步·全链路重命名删除·迁移）+ 真实组合集成测试（真实 cordis + WebServer + 真实 HTTP，覆盖 create/read/update/rename/delete、库分配/回收/同步、404、403 跨站围栏、三级根）+ client 接线测试（conversation.view 单缝注册、会话注入、标签语言跟随、fiber 释放）+ 视图渲染测试（注入的会话作用域直接渲染管理器，不落入「暂无会话」）+ profile 装载守卫（dsh peer 范围在 0.1.7/0.2.0 上均无需豁免即满足，防止 bundle 被静默跳过）
• pnpm build — 双产物构建通过，client bundle 纯度门（无 Node builtin、无越界 @deepseek-ai 值导入）
• 安装后 dsh --profile <name> --dump-config 应出现 dsh-skills-manager 行
• 真实桌面版（0.2.0-rc.2）实测：客户端插件图包含本插件且 bundle 由 host 下发；/skills/api/* 用真实会话 id 跑通 roots.info（按会话 header.cwd 解析项目根）/ skills.list / skills.get / skills.create / skills.update（原子写）/ skills.delete / skills.library.list；空 sessionId 返回干净 400

🔌 兼容性

v1 → v2 的入口变化（侧边栏面板 → 会话视图标签页）与 0.2.0 修复细节见 CHANGELOG.md。

📝 更新日志

见 CHANGELOG.md —— v2.0.0：支持最新桌面版（0.2.0-rc.2），修复「点击后提示先打开一个会话」，入口改为「对话 / 轨迹」旁的视图标签页。

❓ FAQ

Q: 为什么列表里看不到某个 Skill？ A: 官方解析器会跳过 frontmatter 缺失/无效（缺 name 或 description、名称不是 kebab-case）的文件。打开对应 SKILL.md 补全 frontmatter 即可。

Q: 为什么不做成侧边栏里的常驻面板？ A: DSH 0.2 原生左栏（ui-sidebar）只给插件开放导航类接缝——sidebar.panellist（图标行 → 内容固定在中间栏）、sidebar.workspaces（被会话浏览器独占，替换它等于删掉会话列表）、settings / footer.action；没有「插件内容常驻左栏」的席位。因此管理器做成会话中栏的视图标签页（conversation.view，和内置「对话 / 轨迹」同栏），这也是官方唯一为「随会话切换的内容面板」提供的接缝，且会话作用域由接缝自带。

Q: 为什么新会话（空白页）看不到这个标签？ A: 会话空白时中栏显示 Hero 起始页，官方会隐藏整个视图标签栏（轨迹 同样如此）；发出第一条消息后标签栏出现。

Q: 支持哪些 Skill 形态？ A: 目录型（<name>/SKILL.md）与扁平型（<name>.md）都支持。

📄 License

MIT