技能侧边栏面板 lnyuqian/dsh-skill-sidebar

dsh-skill-sidebar

English：DSH 插件（web 版和桌面版通用），在 DSH 的官方右侧边栏（@deepseek-ai/dsh-client-ui-sidebar-right，DSH 0.1.5-rc.1 新增的可停靠标签页界面）里加一个「技能」标签页。它会扫描本机技能目录（.agents/skills、.codex/skills、.claude/skills、.opencode/skills），列出每个技能，配一句 4–6 个字的短语说明它做什么，还支持一键复制 /skill-name 触发语法、置顶、目录标签、新技能实时重扫、从缓存即时渲染。放进 DeepSeek Harness 桌面客户端（Electron，dsh-app://app/ shell）也能原样运行，只有悬停浮层的位置计算不一样。从 v0.2.0 起，它通过官方两阶段标签页类型 API 注册，不再依赖第三方 betterSidebar 服务；从 v0.3.0 起双 shell 通用（中文说明见下）。

DSH 插件（web 版 / 桌面版通用）：在 DSH 官方右侧边栏（@deepseek-ai/dsh-client-ui-sidebar-right，官方新增的可停靠标签页系统）中新增一个「技能」标签页，列出本机可读取的全部技能，并以简短描述介绍每个技能的功能。桌面版（DeepSeek Harness Desktop，Electron）渲染同一套前端，因此同一份代码两端通用，仅悬停浮层按窗口尺寸自适应。

v0.2.0 起从第三方 dsh-better-sidebar 面板迁移到官方侧边栏；不再依赖 betterSidebar 服务。版本历史见 CHANGELOG.md。

v0.4.0：按插件分类 + 新会话按需加载

要解决的问题（2026-10-12 本机实测）：181 个技能里，157 个会被写进每一个新会话的 <available_skills> 目录里 —— 约 44,010 字符 ≈ 14.9K token，而且目录一变就重发一次；可最近 30 天真正被 skill 工具调用过的只有 21 个。

做法：

| 层 | 内容 |
| 分类 | 按「插件/家族」自动归入 12 个分类（lib/categories.json）：firecrawl-* → 网页检索、wecomcli-* → 企业微信、photon-* → 多媒体生成、dsh-* → DSH 运维… 规则：人工覆盖 > frontmatter category > 名字前缀 > 关键词打分 > 兜底 |
| 标签 | frontmatter tags/keywords + 名字家族 + 来源根；每行显示「分类 · #标签」 |
| 查询 | 分类筛选条（全部/常驻/索引/新装 + 各分类计数）+ 分组列表；搜索支持 tag:xxx、#xxx、分类:xxx、category:xxx、常驻、索引 |
| 自动归类 | 新装/新发现的技能在扫描时自动归类并落盘（policy.json），零手工步骤；可 POST /skillpanel/classify 人工改写 |
| 使用证据 | 实时：订阅 tools/execute 记录 skill 调用；回填：启动后台扫最近 30 天的多帧 zstd 会话日志，挖出历史调用与「曾进目录」的技能 |
| 加载清单 | 常驻 = 30 天内用过 ∪ 顶标（置顶）；30 天内进过目录却没被用过 → 退出新会话目录（转「索引」） |
| 生效方式 | 两级影子：agent 作用域（agent/pre-step 里用该 agent 自己的 skills 实例注册，必命中；v0.4.1 修正）+ 全局层（对启用 host provider 的部署有效）。只关 modelInvocable —— DSH 官方开关，不改 DSH 本体 |
| 索引里仍可用 | 侧栏可见 · /技能名 直接调用 · skill_search 检索并按名加载 |
| skill_search 工具 | 全量索引检索（含被移出目录的技能）；传精确 name 直接拿回完整说明并记为一次使用 |
| 分组与折叠 | 分组头即按钮（▾/▸，回车/空格可切换），折叠状态按设备存 localStorage（dsh-skill-sidebar:cats:v1），缺省全部展开 |
| 索引文档 skills.md | 每次扫描重写 skills.json 同目录的 skills.md：按分类分组、每条含 /技能名、一句话能力、SKILL.md 绝对路径与「常驻 / 索引」标注；接口回传 docPath |
| 自有图标 · 常开面板 | 标签头/面板标题/指南胶囊统一用插件自带 SVG（assets/skill-panel.svg，1024 单位 currentColor 填充）；本面板的关闭 X 被作用域受限的 :has() 规则隐藏，常驻右栏 |

两点对原始规则的改进：

1. 新装技能 7 天试用期：纯使用过滤会死锁（没用过 → 不列 → 永远用不上），新装/新改的 SKILL.md 先常驻。
2. 证据不足不生效：usage 与 advertised 都为空时（全新机器）整条策略 degraded，只统计不改行为。

v0.4.1 重要修正（分层陷阱）：技能注册表是 host + 按作用域分层的，更近的层直接胜出（rank 只在同层内比较）。
本机 standard agent preset 自带 skill-filesystem（全局那个被 dsh-web-app patch 禁用了），所以只注册进全局层的影子会被 preset 层盖掉 —— 表现为「策略算得对、目录一条没少、skill 工具照样能加载索引技能」。
v0.4.1 起改为在 agent/pre-step 里用 该 agent 作用域自己的 skills 实例注册（agent.ctx.get('skills')），并新增自查：注册后按该 agent 视角读一次注册表，结果见 /skillpanel/skills 的 shadow 字段（effective 应为 true）。

开关：DSH_SKILL_POLICY=on|dry|off（默认 on）、DSH_SKILL_WINDOW_DAYS=30、 DSH_SKILL_GRACE_DAYS=7、DSH_SKILL_MINE=on|off、DSH_SKILL_SESSIONS_DIR。

自检：npm test —— test-policy.mjs（55）· test-client.mjs · test-host.mjs · test-desktop.mjs（59）· test-registry-shadow.mjs（12，对着真实注册表验证影子机制）。

注意：宿主 half 的改动要重启 DSH 才生效（link: 安装）；重启后新会话的技能目录只列「常驻」那一份，侧栏页脚会显示「加载清单：30 天内用过 + 顶标常驻 · N 常驻 / M 索引」。

功能

- 官方侧边栏标签页：走官方两段式注册 —— 先在 ctx.sidebarRightTabs.register 声明页面类型（kind: 'skills'，priority: 'extension'），再在 sidebar.right.pane.tab / sidebar.right.pane.tab.title 两个 keyed 座位下以定义 id 注册主体与标签头。图标为插件自带的 SVG（assets/skill-panel.svg：斜杠 + 火花，内联为 currentColor 填充图标，随明暗主题变化）。
- 指南页入口：类型自带一个 guide 条目，官方侧边栏的「开始」指南页出现「技能」胶囊，点击即以 replaceTab 打开技能页（与官方「工作区文件」同样的公开路径）。
- 默认自动打开：官方侧边栏默认折叠且为空，openTab 会在同一步展开右栏；本插件在每个新会话打开一次（AUTO_OPEN = true，lib/client.js 顶部一个常量即可关闭）。侧边栏座位未挂载时命令会抛错，故做了有界重试（250ms 起，最多 60 次）；关闭标签页后本次页面加载内不再自动打开。
- 隐藏关闭按钮（常开）：本面板标签页自己的关闭 X 被隐藏
（[data-dockkit-tab]:has([data-dsh-skills-chip]) [data-dockkit-tab-close]{display:none!important}），
面板保持常开；其他标签页的关闭按钮不受影响。
- 紧凑排版：每个技能两行展示 —— 第一行技能名（+ 目录标签 + 操作按钮），第二行 4-6 字功能短语；行与行之间以细分隔线隔开，鼠标悬停任意技能行弹出浮层显示完整功能描述。
- 目录标签：非公共目录（.codex / .claude / .opencode）的技能名后跟 #目录 小标签；公共目录 .agents 不加。
- 复制（一键调用）：每行「复制」按钮，点击复制 /技能名（带斜杠，DSH 输入框的技能触发语法），粘贴到输入框即可触发该技能。
- 置顶 / 取消置顶（顶标）：每行 12px 图钉按钮；点击置顶后该技能排到列表最前（图标变主题色实心），再点取消。v0.4.0 起置顶同时写回宿主 ~/.dsh/storages/dsh-skill-sidebar/policy.json（POST /skillpanel/pins）—— 因为它同时决定「新会话常驻清单」；浏览器 localStorage（dsh-skill-sidebar:pins:v1）只作首帧回退。
- 目录扩展扫描：扫描本机 4 个技能目录 —— .agents/skills（公共）、.codex/skills、.claude/skills、.opencode/skills（后三个均可用环境变量 DSH_CODEX_SKILL_DIR / DSH_CLAUDE_SKILL_DIR / DSH_OPENCODE_SKILL_DIR 覆盖）；同名技能以 .agents 优先去重（.claude 的 junction 软链接不重复显示）。各目录类型均支持 $DSH_SKILL_DIRS 追加。
- 短语来源：插件自带 lib/phrases.json（为中文技能手写的 4-6 字短语清单）与 lib/skills-zh.json（为英文 SKILL.md 技能提供的中文短语 + 一句话中文说明，随包分发）；两者都没有的新安装技能自动用规则从描述中拆分生成短语（按标点切分、取每段前 6 字、去重、最多 6 条）。解析自动处理 UTF-8 BOM 与 GBK 编码文件。
- 中文化（v0.3.0）：本机多数技能的 SKILL.md 是英文，规则短语只能截出 Use when、adding A 这类片段。现在列表第二行显示随包的中文短语（如 网页搜索，整页抓取，资料检索），悬停浮层把中文说明排在最前、英文原文与 whenToUse 保留在后；技能名保持英文原样，因为它就是 /技能名 的调用标识。中文技能沿用 phrases.json 的手写短语，不受影响。
中文表同时由 scripts/sync-zh.mjs 内联进客户端 bundle（lib/client.js 的 @zh-inline 段）：客户端 bundle 走 client-hmr 即时重载，而宿主半侧只有重启应用才会重新加载，内联让两端都在改表后立刻显示中文；宿主重启后服务端数据自带 zh，客户端合并是幂等的（两侧同源于 lib/skills-zh.json，一致性由测试断言）。搜索也覆盖中文说明与短语。
- 分类分组 + 折叠（v0.4.0，并入上游设计）：面板按分类分组，每个分类头可点击折叠/展开（dsh-skill-sidebar:cats:v1 按设备记忆，缺省全部展开；折叠时不挂载行）。
- 技能索引文档（v0.4.0，并入上游设计）：每次扫描后重写 skills.md（与 skills.json 同目录），按分类分组，每条含 /技能名、一句话能力、SKILL.md 绝对路径与「常驻 / 索引」标注，方便智能体先读文档再按名加载；接口回传 docPath。
- 立即列出，无需等待：服务端把技能列表直接注入页面（window.__DSH_SKILLS__），同时持久化到浏览器 localStorage 与会话缓存文件，再次启动打开选项卡即可瞬间渲染，无需网络往返。桌面版例外：Electron 直接读取打包好的前端（dsh-app://app/ 由 serveWebDocument 提供），不经过 webServer 的 index 变换管道，因此该首屏注入在桌面端不生效 —— 桌面端首屏来自 localStorage 快照与实时目录，随后由 /skillpanel/skills 补齐（功能不受影响，只是没有"零请求"那一层）。
- 自动添加新技能：4 个技能目录被 fs.watch 监听（含父目录），新技能安装后自动重新扫描；标签页可见期间每 30 秒后台刷新一次实时目录；缓存随目录集合变化自动失效重扫。
- 每周一重新读取：周一时服务端强制对全部技能做一次全量重读；此后每 6 小时校验一次，若缓存早于当天则再次刷新。
- 桌面版（v0.3.0）：同一份代码在 DeepSeek Harness 桌面版里运行 —— 页面挂在 dsh-app://app/ 协议下，相对 fetch('/skillpanel/skills') 由 Electron 主进程带认证 cookie 转发给本地 webserver，槽位注册与数据通道与 web 版完全一致；仅悬停浮层按窗口尺寸自适应（左右夹紧、上下翻转、限高，超出空间的描述截断为省略号），长技能名在窄栏里省略显示而不是把操作按钮挤出可视区，页脚显示当前运行外壳（桌面版 / 浏览器）。

桌面版（DeepSeek Harness Desktop）

桌面版是 Electron 外壳 + 内置本地 webserver，渲染同一套 Web 前端，插件通过 ~/.dsh/profiles/desktop 这个独立 profile 装载（与 profiles/web 互不影响）。

| 项目 | web 版 | 桌面版 |
| profile | $DSH_HOME/profiles/web | $DSH_HOME/profiles/desktop（由 Electron 独占管理） |
| 页面来源 | http://127.0.0.1:<port>（浏览器访问） | dsh-app://app/（Electron 窗口） |
| 插件安装 | dsh plugin --profile web add … | 应用内插件管理（设置 → 插件）或 install-desktop.ps1 |
| 侧边栏契约 | 官方 sidebar.right.pane.tab(.title) + sidebarRightTabs | 完全相同 |
| 数据通道 | fetch('/skillpanel/skills') | 相同（dsh-app:// 下由主进程代理并带认证 cookie） |
| 首屏注入 | webServer.tapIndex → window.__DSH_SKILLS__ | 不生效（Electron 直接读打包前端）；首屏用 localStorage 快照 + 实时目录 |
| 差异 | — | 窗口通常更小 → 浮层几何自适应、窄栏技能名省略 |

安装（桌面版已运行时，无需重启）：

方式一：应用内插件管理 —— 设置 → 插件，或让 DSH 助手用 plugin_manager 工具安装本次开发即用这条路：安装 link 指向本仓库后宿主热重组，右栏立即出现「技能」标签页

方式二：应用完全退出后，用桌面自带的 CLI 载体安装 pwsh -File .\install-desktop.ps1 # link 安装（开发） pwsh -File .\install-desktop.ps1 -Mode Tarball # 从 tgz 安装（分发） pwsh -File .\install-desktop.ps1 -Uninstall # 卸载

在桌面版里确认已生效：

- 右侧边栏出现「技能」标签页（新会话会自动打开一次），或从右栏「开始」指南页点「技能」胶囊进入；
- 列表底部显示「桌面版」与技能来源（本机 / 实时 / 缓存）；
- 服务端缓存落在 $DSH_HOME/storages/dsh-skill-sidebar/skills.json，说明宿主半侧已扫描完成。

桌面版与 web 版共用同一份 lib/：没有平台分叉代码，dsh.client.platform 仍是 "web"（桌面版同样按 web 平台客户端加载，与 dsh-mobile、dsh-quick-prompts 一致）。唯一的实现差异是上面表格里的首屏注入一行：tapIndex 只在浏览器路径上执行。

- 能力分类（≤10 类）：扫描时按规则把每个技能归入一个能力类别（飞书 / Lark、DSH / 插件、检索 / 抓取、图像 / 视觉、视频 / 音频、文档 / 表格、内容 / 发布、自动化 / n8n、开发 / 环境、其他），技能名优先、描述兜底；面板按分类分组，每个分类头可点击折叠 / 展开，折叠状态按设备存 localStorage（默认全部展开）。搜索在各分类内生效、空分类不显示、置顶仍排在各分类最前。
- 技能索引 MD 文档（自动同步）：每次扫描后把全部技能写成 skills.md（与 skills.json 同目录，默认 ~/.dsh/storages/dsh-skill-sidebar/skills.md）：按分类分组，每条含 /技能名 调用语法、一句话能力与 SKILL.md 的绝对路径。启动、装新技能、每周一全量重扫、点面板「刷新」都会重写；~/.dsh/AGENTS.md 已加入「先读该文档再调用技能」的全局规则。

与官方侧边栏的契约

| 项目 | 值 |
| 标签类型 id | dsh-skill-sidebar（同时是主体/标签头注册的 key） |
| 页面 kind | skills（页面类型，不声明 patterns） |
| 优先级 | extension（产品外插件） |
| 指南条目 | order: 20、标题「技能」、一行描述、技能图标 |
| 注册座位 | sidebar.right.pane.tab、sidebar.right.pane.tab.title |
| 插件级 inject | slots、sidebarRightTabs、sidebarRight、connection、sessions |
| dsh.client.inject | @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-sidebar-right |

标签主体的 props：框架注入的 useTabInfo()（tab.visible 控制 30 秒轮询、tab.signal 限定生命周期）、sessionId，以及本插件通过 inject 提供的 ctx。

注：官方默认页规则是「指南条目只有一个时直接打开它」。加入本插件的指南条目后，官方登记了 2 个指南条目（工作区文件 + 技能），因此空面板的默认页由「工作区文件」变为「开始」指南页；两者都能从指南页一键进入。

数据源

- 实时目录：connection.api.skills.list({ sessionId }) —— 当前会话可见的技能（含内置与用户技能），由 DSH 的 skill 注册表实时提供。
- 本机扫描：GET /skillpanel/skills —— 插件服务端直接扫描技能根目录（~/.agents/skills，可用 $DSH_AGENTS_HOME 与 $DSH_SKILL_DIRS 扩展），解析 SKILL.md 的 YAML frontmatter（name / description / whenToUse / tags / category）。每条技能还带 path（SKILL.md 的绝对路径）、category（分类 id）、tags 与加载清单状态（state：resident 进新会话目录 / indexed 按需）；响应体额外给出 policy（加载清单摘要）、categories（分类表与计数）、categoryNames（id → 中文名）、usage 与 docPath（技能索引 MD 的路径）。
- 两份数据按名称求并集合并展示（实时目录优先），因此既能显示会话可调用的技能，也能显示仅用户可调用或机器上其他根目录的技能。

缓存与刷新策略

| 项目 | 位置 | 策略 |
| 服务端缓存 | $DSH_HOME/storages/dsh-skill-sidebar/skills.json（可用 $DSH_SKILL_CACHE_DIR 覆盖） | 启动时若非周一且 7 天内已扫描则直接使用；否则重扫 |
| 技能索引文档 | $DSH_HOME/storages/dsh-skill-sidebar/skills.md（跟随 $DSH_SKILL_CACHE_DIR） | 每次落盘缓存时一起重写：按分类分组，列出 /技能名、能力短语与 SKILL.md 绝对路径 |
| 分类折叠状态 | localStorage dsh-skill-sidebar:cats:v1 | 按设备记住每个分类的折叠状态（默认全部展开） |
| 浏览器缓存 | localStorage dsh-skill-sidebar:cache:v1 | 打开选项卡立即渲染，后台再刷新 |
| 自动添加 | fs.watch（500ms 防抖）+ 5 分钟轮询兜底 | 新技能出现即重扫 |
| 每周一 | 服务端 6 小时定时器 + 客户端周一强制刷新 | 全量重读 |

路由

- GET /skillpanel/skills —— 返回 { ok, skills, categories, docPath, scannedAt, source, policy }；skills[] 每项含 name / description / phrases / source / path / category（+ 可选 whenToUse）
- GET /skillpanel/skills/refresh —— 立即重扫、重写技能索引文档，并返回最新列表

两条路由均使用与 /api 网关相同的浏览器信任围栏（loopback Host 或 connection 行的 trustedHosts）。

安装 / 卸载

web 版：把 <本包绝对路径> 换成本仓库在本机的路径（link: 安装，改源码后重启即生效）
dsh plugin --profile web add link:<本包绝对路径>

web 版卸载
dsh plugin --profile web remove dsh-skill-sidebar

桌面版（desktop profile 由 Electron 独占管理，全局 dsh CLI 会拒绝操作）：应用运行中 → 设置 → 插件（或 DSH 助手用 plugin_manager 工具），无需重启应用已退出 → 用本仓库脚本 pwsh -File .\install-desktop.ps1 # link 安装 pwsh -File .\install-desktop.ps1 -Uninstall # 卸载

web 版安装/卸载后需重启 dsh web 并硬刷新（Ctrl/Cmd+Shift+R）；桌面版通过应用内插件管理安装是热生效的（宿主重组后页面按需加载新 bundle），用脚本安装则在启动桌面版后生效。依赖以 link: 形式指向本目录，改动源码后重启/重载即可生效（无需重新安装）。

平台支持

| 平台 | 状态 |
| Windows 11 + DSH web（浏览器） | ✅ 已验证（DSH 0.2.0-rc.2） |
| Windows 11 + DeepSeek Harness 桌面版 | ✅ 已验证（desktop profile；两段式注册与 host 路由实测生效） |
| macOS | ⚠️ 未测试 |

插件只用 Node 的跨平台 API（node:path 的 join()、node:os 的 homedir()）与 DSH_HOME / DSH_AGENTS_HOME / DSH_SKILL_DIRS / DSH_SKILL_CACHE_DIR 等环境变量定位文件：没有平台专有路径，也不假设路径分隔符（技能根目录一律用 join() 拼接）。客户端部分只在 Web 运行时（浏览器或桌面版 Electron 渲染进程）里运行，与操作系统无关，也不区分两种外壳 —— 只有浮层几何按窗口尺寸自适应。
可选的请求跟踪日志默认关闭，需显式设置 DSH_SKILL_SIDEBAR_TRACE（见「路由」）。

开发

客户端契约测试（官方两段式注册、自动打开重试、主体渲染、合并/缓存/置顶）
node test-client.mjs

服务端逻辑测试（frontmatter 解析、扫描、路由、watcher、缓存）
node test-host.mjs

桌面版适配测试（外壳识别、浮层几何、桌面端槽位注册端到端）
node test-desktop.mjs

改了 lib/skills-zh.json 之后，把它重新内联进客户端 bundle（否则客户端仍是旧表）
node scripts/sync-zh.mjs

三套一起
npm test

lib/client.js 使用 DSH 客户端模块表格式（window.__ModuleLoader__.load），手写无需构建；lib/index.js 为纯 Node ESM，无第三方依赖。