# dsh-skill-explorer · DeepSeek Harness (DSH) Skill 技能与工具资源可视化浏览器
[English](README.md) | 中文
DeepSeek Harness（DSH）官方 Web GUI 与桌面客户端专属技能中心与 Skill 管理面板
按来源层级浏览 · 一键启闭模型调用 · 可视化新建/编辑 SKILL.md · 安全回收站 · 零侵入管理
DSH Web GUI 与官方桌面客户端的**技能中心**：按来源分级浏览已加载的全部 skill，启用/禁用模型调用，创建新技能，删除技能（移入可恢复的回收站）。
## 功能
- 侧边栏「技能中心」一行（位于 shell 自己的面板列表，与插件、定时、任务看板
并列），打开的是**原生中栏页面**，带页签栏。该行负责打开面板，打开任意会话
（或新建对话）即让中栏回到会话正文，与官方插件页、定时任务页一致；页面自身
不再提供「返回会话」控件。
- **技能 tab**：按来源分级展示（系统内置 / 项目 `.dsh/skills` / 项目
`.agents/skills` / 自定义目录 / 用户 `~/.dsh/skills` / 用户
`~/.agents/skills` / 运行时注册），顶部搜索框按技能名或描述即时过滤
（名称命中排在前面，Esc 清空），并与工作区选择叠加生效；
每行显示描述、适用场景、可调用标记、启用/禁用开关（改写 SKILL.md
frontmatter 的 `disable-model-invocation`，模型目录热刷新；插件提供的文件
没有这条可写路径，其开关改由面板自己的存储记录）、复制为模板入口（把该技能复制为
创建表单的起点）、编辑入口与删除按钮
（文件移入 `.trash`，可恢复）；加载进行中隐藏刷新按钮。
- **筛选与来源折叠**：搜索框与三个筛选维度叠加——要显示的来源分组、启用/禁用
状态、行的标记（「由插件提供」/「无本地文件」/「软链接」）——由一个工具栏
开关统一展开，开关上显示当前有几个维度在收窄列表。每个来源分组的标题可
展开/收起；首次使用时只展开项目与用户根，因此全局来源不会一次铺满所有行。
筛选维度与折叠决定都是存在 `localStorage` 的视图偏好；拒绝存储的浏览器
只是不记忆它们。
- **导入 tab**：从宿主机上的目录或浏览器读取的 `.zip` 压缩包批量创建技能。
每个候选都按官方接受规则校验，并按与列表相同的来源 rank 裁决，因此更强来源
已提供的同名候选会报告为跳过，而不是创建一个模型收不到的文件。导入只新建
文件：已有技能不会被覆盖。
- **创建 tab**：表单创建新技能，可写入用户根（`~/.dsh/skills`）或项目根
（`.dsh/skills`），生成标准 SKILL.md。
- **编辑 tab**：从行内编辑入口打开，先经宿主读取该技能（列表只带元数据），
再就地改写描述、适用场景与正文；技能名、位置与启用状态保持不变。
- 数据来自按官方 dsh-skill-filesystem 根约定的文件系统扫描，并与
`ctx.skills` 注册表（bundled / runtime 条目）合并。扫描既读本插件自己的
`customSkillDirs`，也读每一条在用的 `skill-filesystem` loader 行的同名
配置，因此官方文档推荐的配法（写在 profile patch 的 provider 行上）同样可管理。
本插件不改变 skill 的加载/注入语义——纯 GUI 管理层。
- 写路由无法操作的技能会按它实际的本地形态打标，而不是静默缺失控件：
插件 provider 报告了真实指令文件（官方 `SkillSummary.path`）的技能显示为
**「由插件提供」**——文件确实存在，只是不在本面板扫描的技能根目录下；
只有完全没有文件的注册项才显示为 **「无本地文件」**。两者都不带可写路径，
因此都不会出现必然 404 的编辑/删除控件。**「由插件提供」**的行带有启用/
禁用开关（#1854）：文件属于 provider，因此宿主把开关记在面板自己的存储里，
该行显示为已停用（见「已知限制」）；只有**「无本地文件」**的行完全没有开关。
- 只有官方 provider 会加载的技能才被列出：SKILL.md 必须声明非空的 `name`
与 `description`，且 name 满足官方技能名文法。被官方 provider 丢弃的文件
在面板里同样不出现，面板不会展示模型收不到的技能。
- 同名技能按官方来源 rank 决出胜者（项目 `.dsh/skills` 100、项目
`.agents/skills` 200、运行时 250、自定义目录 300、用户 `~/.dsh/skills`
400、用户 `~/.agents/skills` 500、内置 600），因此面板所示与模型所得是
同一个技能。
## 安装
### 从 npm（推荐）
```sh
dsh plugin --profile web add @linxin666/dsh-client-ui-skill-explorer@latest
```
### 从仓库（开发）
```sh
git clone https://github.com/zhu1090093659/dsh-web.git
cd dsh-web
pnpm install
pnpm -r build
dsh plugin --profile web add link:$(pwd)/packages/dsh-skill-explorer
```
安装后重启 `dsh web`，侧边栏出现「技能中心」入口。
## 路由
| 路由 | 方法 | 说明 |
| --- | --- | --- |
| `/api/dsh-skill-explorer/list` | GET | 分级技能列表 |
| `/api/dsh-skill-explorer/read` | GET | 单个技能的可编辑字段与正文（`?name=&path=`） |
| `/api/dsh-skill-explorer/set-enabled` | POST | 启用/禁用（改写 frontmatter） |
| `/api/dsh-skill-explorer/set-provider-enabled` | POST | 启用/禁用插件提供的技能（记入面板自己的存储） |
| `/api/dsh-skill-explorer/create` | POST | 创建技能（user/project 根） |
| `/api/dsh-skill-explorer/import` | POST | 从目录或 .zip 压缩包批量创建技能 |
| `/api/dsh-skill-explorer/update` | POST | 原地修改已有技能（名称与位置不变） |
| `/api/dsh-skill-explorer/delete` | POST | 删除（移入 .trash） |
| `/api/dsh-skill-explorer/health` | GET | 健康检查 |
## 安全模型
- 全部 `/api/dsh-skill-explorer/*` 路由默认仅限 loopback（插件家族共享围栏：
loopback 套接字 + Host 头 + 浏览器同源标记）：未配对的局域网客户端在任何
技能文件访问前即收到 `403 forbidden: loopback-only`。经由宿主 `connection`
服务接纳的反向代理或入口部署（`--trusted-host`、有效签名浏览器会话）可直接
通行。同时装了 `dsh-remote-web-ui` 时，有效的已配对设备 cookie 是额外放行路径
（与 `api/gate` 检查同一枚 cookie）；未配对与已撤销设备仍 403。技能中心不硬依赖
远程插件。
- 写路由仅把面板展示的路径作为身份声明；执行修改前，最新文件系统扫描必须解析到
同名且路径完全一致的技能。任意路径与过期的同名回退都会被拒绝，因此项目技能
消失后，尚未执行的操作不会改到同名的用户级或自定义技能。read 路由走同一套
解析，因此也无法用来读取任意路径。该解析所用扫描按与 list 路由完全相同的顺序
确定工作区（显式覆盖、活动会话工作区、进程 cwd），因此写操作不会重新扫描到与
面板展示不同的项目根。
- update 路由原地改写已有 SKILL.md，不改技能名与位置，并原样保留当前的
`disable-model-invocation` 值，因此编辑不会静默把已禁用的技能重新启用。
与删除同理，链接技能在该路由上被拒绝（见下）。
- 插件技能开关路由把每条记录以 `(provider, 技能名)` 组合写入
`$DSH_HOME/dsh-skill-explorer/provider-toggles.json`（临时文件 + fsync +
rename 原子落盘；损坏、异构或超限的文档降级为「什么都没停用」）。该路由
既不接收也不写入路径：客户端只发送身份，不发送位置。停用要求最新一次收集
仍能把该组合解析为 `provider-file` 行，因此存储里只可能出现面板确实展示过
的身份；启用只做删除记录，故无条件放行——插件卸载后残留的记录仍可清除。
两个方向都是幂等的，重复点击或重试不会堆出重复记录。
- 导入路由是唯一会读取技能根之外内容的创建入口，其读取面很窄：用户指定的
宿主机目录只扫描一层 `<名称>/SKILL.md` 或 `<名称>.md`，其中的符号链接与
点目录被跳过而非跟随；压缩包则由浏览器读取后提交。写入只新建文档所述
用户/项目根下的 `<技能根>/<名称>/SKILL.md`，绝不改写已有文件；请求有上限
（压缩包 4MB、条目 512、单个 SKILL.md 64KB、展开文本 4MB）。损坏或不支持的
压缩包（zip64、加密条目、未知压缩方法、越出压缩包的路径）以 400 加原因
作答，且每条拒绝都会点名出问题的条目。
- 技能内容是用户自写的 markdown；创建表单限制内容 64KB，编辑与导入路由
同样执行该上限。
- 面板用文本节点渲染技能描述（无 HTML 注入）。
- 扫描跟随符号链接：skill 根里的符号链接目录 / `.md` 单文件链接会被当作
普通技能列出。链接属于用户的挂载意图，因此不校验链接目标是否落在某个
skill 根内；项目根（可能来自 clone 的仓库）里的符号链接被视为该项目内容，
其指向目录中的 `SKILL.md` 会被读取并展示——这是预期信任边界。链接技能可
列表、可启用/禁用（改写目标自身的 frontmatter），但**不可删除、也不可编辑**：
删除会把链接目标的 `SKILL.md` 移出原位、越出当前 skill 根，原地改写同样会
越出该根，因此对链接技能隐藏删除与编辑按钮，并在 delete / update 路由上
拒绝（400）。写操作仍受 loopback 围栏与「仅信任最新
扫描路径」约束。
## 已知限制
- 项目技能跟随面板显示的 workspace：list 路由接受显式 `?cwd=` 覆盖，
创建表单会发送当前显示的 workspace；项目根为该 workspace 最近的
`.git` 祖先。写路由解析与 list 路由相同的 workspace，因此即使宿主进程 cwd
在别处，项目技能仍可管理。
- frontmatter 解析为零依赖轻量实现（块标量、布尔、input 嵌套块）；不支持的
生僻 YAML 特性以官方 dsh-skill-filesystem 提供方为准。
- 面板覆盖它扫描的文件系统根，加上 `ctx.skills` 注册表的全局层（bundled 与
runtime 条目）。配在 host 平面 `skill-filesystem` 行上的 `customSkillDirs`
会被扫描，因为宿主会读取该行配置；仅通过**某个 agent preset 自己的**
`customSkillDirs` 或 preset 作用域提供方到达 agent 的技能不在此覆盖范围内，
因为面板读取注册表时不带 viewing scope。因此面板里没有的技能，不一定模型也没有：
会话能加载什么，以官方 `skill` 工具目录为准。
- **「由插件提供」**行的开关是**仅本面板生效**的视图决定：它改变的是本面板
列出的可调用状态，宿主注册表照旧加载该技能，模型仍会收到它。要真正让这类
技能不再进入模型，需要在它的 provider 获取它的位置（插件配置或随包文件）
移除或停用它。
- 链接技能不可删除、不可编辑（见安全模型）；启用/禁用对链接技能正常（改写目标
`SKILL.md` frontmatter）。目录型与「单文件」链接都能正常列出；「单文件」
符号链接（指向单个 `.md`）在原子改写（rename）时会被替换为一个普通文件
（链接不再保留），目标文件本身不受影响。
- 目录导入只读取一层、不递归：嵌套的目录树需要指向真正存放技能的那个目录。
`.zip` 导入接受任意深度的 `SKILL.md`，因此「把技能目录压缩成包」可用，但压缩包里的
其他文件会被忽略，而不会作为资源一并复制。
- 导入的同名技能若已在同级或更强来源解析，会报告为跳过（`exists` / `shadowed`）
而不是替换该技能；要把这样的名字导入进来，需要先给候选改名。
- 折叠与筛选偏好按浏览器配置保存，能跨面板重挂载与页面刷新，但不跨浏览器
或无痕窗口。
## 数据遥测
浏览器半区每个 UTC 日向 dsh-market.com 发送一次匿名安装心跳：仅含一个 localStorage 随机 ID 与本包名，无其他数据。服务端只存储该 ID 的加盐哈希，不存 IP，且只暴露聚合计数。完整契约见 [docs/telemetry.md](../../docs/telemetry.md)。
## License
BSD-3-Clause。