dsh-skill-browser 1.9.9 → 1.9.11

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.9.10 — 2026-10-25
+
+### 修复
+- **品牌渐变底文字对比度按「最差端点」判色**：原来用渐变中点算白字对比度，但 `linear-gradient` 实际铺满 g1..g2 整条 ramp，浅色皮肤（04 全息幻彩 / 051 / 113–127 等）的中点达标而浅端只有 3.7–4.4:1。现改为 `worst(ink, g1, g2) = min(cr(ink,g1), cr(ink,g2))`，两个端点都 ≥4.6:1 才用白字，否则翻成近黑或按 0.05 步长压深整条渐变。**128 皮肤 × 两端点 = 256 项全部 ≥4.5:1。**
+
+### 文档（与实装功能对齐）
+- **`locale/zh.json` / `locale/en.json` 的 `meta.description` 重写**：原描述只写到「一级/二级分类 + 启停 + 失效台账」，完全没提 v1.9.0 之后新增的自定义分组、树状/平铺、版本号徽章、调用台账看板、⚡ 热重载、全皮肤自适应配色 —— 与实装功能严重不符。现按真实功能重写。
+- **`README.md`（主 README，英文为主）补全 v1.9.0–v1.9.9 全部功能**：新增「自定义分组」「树状 / 平铺双模式」「版本号徽章」「调用台账看板」「热重载」「性能」「全皮肤自适应配色」七节中文说明 + 对应 4 条英文 Highlights；API 表补 `/rev`、`/reload`、`/groups`（含 11 个 action）、`/ledger/stats`（含 `gran`/`sort` 参数），`/skills` 注明返回 `version` 字段。原来 API 表完全没有分组、统计、热重载这三组接口。
+- **`README-zh.md` 数字口径修正**：AI 分组的大类数公式写的是「技能数 ÷ 8，6~18 组、单组上限 12 个」，而 `lib/groups.js` 实际是 `Math.max(3, Math.min(16, Math.ceil(list.length / 12)))`（技能数 ÷ 12、3~16 个）且 `addSub()` 按 10 个切片、`CLASSIFY_SYSTEM` 要求「每个子类最多 10 个技能」。三处已全部改成 10 / ÷12 / 3~16，第三遍兜底拆组的「超过 12 个」也改为「超过 10 个」。
+- **`package.json` `description` 从「逐版本罗列」改为一份统一功能描述**：原来是把 v1.9.0→v1.9.10 每个版本的新增点串起来，越写越长、且和市场卡片/README 口径各不相同。现在 `package.json` description、`locale/zh.json` `meta.description`、`locale/en.json` `meta.description`、五语言 README 首段**全部指向同一份口径**（含「分组只改视图不动技能文件」「无版本显示暂未编版本号」两条容易被误解的点）。npm 市场的卡片描述取自 `package.json` description，插件管理器/设置页的描述取自 `locale/*.json` 的 `meta`，两边现在一字不差。
+- **`README-es.md` / `README-pt.md` / `README-hi.md` 首段补齐**：原来这三份只有一个 8 行的空壳（只有标题 + 一句旧描述 + 一个跳转链接），连分组、版本号、台账看板、热重载、皮肤自适应都没提。现在各自有一段完整的本地语言功能描述，标题统一为 `Skill Browser`。
+
+### 校验
+- **`scripts/audit-contrast.mjs`（新写，随包发布，唯一权威口径）**：128 皮肤 × 18 组前景/背景组合 = **2304 项，0 项不达标**。与旧临时脚本的差别：
+  - 语义变量直接从真实调用链取 —— 切皮肤后读 `<style id="dsb-skin-style">` 的 `textContent`，不另存一份「期望值」，杜绝审计与实现各算一套的假绿。
+  - 背景一律取**实际叠层色**：`card = chipBg over panel`、`surface = --dsb-surface`（吸顶表头不透明底实算值）。
+  - 渐变底按**两个端点分别校验**：品牌渐变 `--dsb-onbrand-bg1/2`、分组大类行 `--dsb-tile1/2`（叠 `--dsb-shade` 后）。只测中点会漏掉浅端。
+  - 踩过的坑写进脚本注释：DOM stub 的 `localStorage` 必须可读写，否则 `SKIN.setSkin(id)` 记不住，128 款皮肤全按 01 号深色皮肤算 → 20 款浅色皮肤集体假报不达标（首轮就误报 200 项）。
+- `audit_onbrand.mjs`：128 皮肤逐款取 `--dsb-onbrand-bg1/2` 与 `--dsb-onbrand`，两端点对比度 **0 项 < 4.5:1**。
+- `doc_audit2.mjs` / `doc_audit3.mjs` / `route_audit.mjs`：README-zh 16 项功能词全覆盖；README.md 10 项新功能词 + 4 个新路由全在位；实装 17 条路由与文档逐一对应。
+- `scripts/check-bom.mjs`：37 个文本文件 **0 BOM**。
+
+> **口径统一**：此前各版本 CHANGELOG 出现过 `14 组 1792 项`、`17 组 2176 项` 两种数字，那是各阶段临时脚本的覆盖范围（未含吸顶表头底、未拆渐变端点）。自 v1.9.10 起以 `scripts/audit-contrast.mjs` 的 **18 组 2304 项**为准，README-zh / README.md / package.json 描述均已对齐该数字。
+
 ## 1.9.9 — 2026-10-25
 
 ### 新增

package/README-es.md

@@ -1,6 +1,6 @@
 # Skill Browser
 
-> Browse, search and inspect the local skill library, with per-skill detail pages and quick routing.
+> Panel de bola flotante que convierte tu biblioteca de skills local en un activo navegable, buscable y gobernable: categorías de uno/dos niveles más grupos personalizados (vistas de árbol y plana, grupos manuales, agrupación instantánea por palabras clave, agrupación automática con IA y portadas generadas por IA — agrupar solo cambia la vista y nunca mueve archivos de skills), insignias de versión por skill con reserva "aún sin versión", habilitar/deshabilitar por tarjeta / por categoría / toda la biblioteca con copias de seguridad automáticas, y visor completo de SKILL.md. Un panel de libro de llamadas añade rangos de fechas, granularidad día/semana/mes/año, clasificaciones, gráfico de tendencia y detalles de fallos, alimentado automáticamente por el evento nativo tools/result. Recarga en caliente con un clic, 128 skins adaptables al contraste, raíz de skills configurable y bola arrastrable y restaurable.
 
 > Full documentation: [English README](./README.md)
 

package/README-hi.md

@@ -1,6 +1,6 @@
 # Skill Browser
 
-> Browse, search and inspect the local skill library, with per-skill detail pages and quick routing.
+> फ्लोटिंग-बॉल पैनल जो आपकी लोकल स्किल लाइब्रेरी को ब्राउज़ करने, खोजने और प्रबंधित करने योग्य संपत्ति बनाता है: एक/दो-स्तरीय श्रेणियाँ और कस्टम समूह (ट्री/फ्लैट व्यू, मैन्युअल समूह, तुरंत कीवर्ड ग्रुपिंग, AI ऑटो-ग्रुपिंग और AI कवर — ग्रुपिंग केवल व्यू बदलती है, स्किल फ़ाइलें कभी नहीं हिलतीं), प्रति-स्किल वर्ज़न बैज जिसमें "अभी वर्ज़न नहीं" फ़ॉलबैक है, प्रति-कार्ड / प्रति-श्रेणी / पूरी लाइब्रेरी के लिए स्वचालित बैकअप के साथ चालू-बंद, और पूरा SKILL.md व्यूअर। कॉल-लेजर डैशबोर्ड में तिथि सीमा, दिन/सप्ताह/माह/वर्ष ग्रैन्युलैरिटी, रैंकिंग, ट्रेंड चार्ट और विफलता विवरण जुड़ते हैं, जो होस्ट के tools/result इवेंट से स्वचालित रूप से भरते हैं। एक-क्लिक हॉट रीलोड, सभी 128 स्किन कंट्रास्ट-अनुकूल, कॉन्फ़िगर करने योग्य स्किल रूट, खींचने योग्य और रीसेट करने योग्य बॉल।
 
 > Full documentation: [English README](./README.md)
 

package/README-pt.md

@@ -1,6 +1,6 @@
 # Skill Browser
 
-> Browse, search and inspect the local skill library, with per-skill detail pages and quick routing.
+> Painel de bola flutuante que transforma sua biblioteca local de skills em um ativo navegável, pesquisável e gerenciável: categorias de um/dois níveis mais grupos personalizados (visões em árvore e plana, grupos manuais, agrupamento instantâneo por palavras-chave, agrupamento automático com IA e capas geradas por IA — agrupar só altera a visão e nunca move arquivos de skills), selos de versão por skill com fallback "ainda sem versão", habilitar/desabilitar por cartão / por categoria / toda a biblioteca com backups automáticos, e visualizador completo de SKILL.md. Um painel de registro de chamadas adiciona intervalos de datas, granularidade dia/semana/mês/ano, rankings, gráfico de tendência e detalhes de falhas, alimentado automaticamente pelo evento nativo tools/result. Recarga a quente com um clique, 128 skins adaptáveis ao contraste, raiz de skills configurável e bola arrastável e restaurável.
 
 > Full documentation: [English README](./README.md)
 

package/README-zh.md

@@ -1,6 +1,6 @@
 # dsh-skill-browser
 
-> 浏览、检索与查看本地技能库，提供技能详情页与快速路由。
+> 悬浮球打开面板，把本机技能库变成可浏览、可检索、可治理的资产：两级分类 + 自定义分组（树状/平铺双模式、手动建组、⚡ 关键词分组、🤖 AI 自动分组与 AI 封面，**分组只改视图，不动技能文件**）、版本号徽章（无版本显示「暂未编版本号」）、单卡/分类/全库启停（自动备份）、SKILL.md 全文查看；内置调用台账看板（起止日期 + 日/周/月/年 + 排行榜 + 趋势图 + 失效明细），监听 `tools/result` 自动登记每次技能调用结果。⚡ 一键热重载，128 款皮肤全量自适应配色，技能库位置可配置，悬浮球可拖拽可复位。
 
 > 完整文档以 [English README](./README.md) 为准，本页提供中文导读与关键信息速查。
 
@@ -20,7 +20,7 @@
 - `--dsb-soft` / `--dsb-line` / `--dsb-hover`：分隔线、悬停底色
 - `--dsb-scheme`：`light` / `dark`，驱动原生 `<input type="date">` 日历弹窗配色
 
-切换皮肤后无需刷新，配色随皮肤即时重算。128 款皮肤 × 17 组前景/背景组合共 2176 项已全量校验，0 项不达标。
+切换皮肤后无需刷新，配色随皮肤即时重算。128 款皮肤 × 18 组前景/背景组合共 2304 项已全量校验，0 项不达标（`scripts/audit-contrast.mjs` 可随时复跑）。
 
 > **v1.9.5**：排行榜表头是吸顶的，底色改用语义变量 `--dsb-surface`（行/卡片真实不透明底色），滚动时不会再和行文字重叠。
 >
@@ -108,9 +108,9 @@ AI 分组与关键词分组是并列的两条路：想快、想稳定就用 ⚡
 
 v1.9.2 起改为**三遍覆盖式分类**，解决「只分了 Fluent、其他技能全丢进一个杂项筐」的问题：
 
-1. **第一遍**：全量技能交给模型，分组数按规模自动定（技能数 ÷ 8，6~18 组），单组上限 12 个，提示词明确禁止「通用工具 / 其他 / 杂项 / 综合」这类筐，并要求各领域拆分粒度一致。
+1. **第一遍**：全量技能交给模型，大类数按规模自动定（技能数 ÷ 12 向上取整，3~16 个，允许 ±2），每个大类下分 1~6 个子类，单个子类上限 10 个技能，提示词明确禁止「通用工具 / 其他 / 杂项 / 综合」这类筐，并要求各领域拆分粒度一致。
 2. **第二遍**：把模型漏掉的技能单独再问一次，并要求避开第一遍已建的分组名，让它们得到真正的语义分组，而不是一个「其他」大筐。
-3. **第三遍（不调模型）**：仍未覆盖的技能按自身分类标签兜底成组，超过 12 个自动拆成 `名称 1` / `名称 2`。
+3. **第三遍（不调模型）**：仍未覆盖的技能按自身分类标签兜底成组，单个子类超过 10 个技能时自动拆成 `名称 1` / `名称 2`。
 
 因此 AI 分组后**不会再出现「未分组」堆积**，全部技能都会落到某个组里。
 

package/README.md

@@ -1,107 +1,114 @@
-# dsh-skill-browser 🧩
+# dsh-skill-browser 🧩 技能浏览器
 
 **把技能库变成看得见、搜得到、管得住的资产。**
 
-**Turn your skill library into something you can see, search, and govern.**
+DeepSeek Harness（DSH）桌面端 / 网页端插件：右下角一个「技」字悬浮球，点开即技能浏览器面板——115+ 技能秒级浏览、树状/平铺双视图、手动 + 关键词 + AI 三种分组、调用台账看板、130 款三球同步皮肤。**分组只是视图归档，绝不移动任何技能文件。**
 
-在 DeepSeek Harness（DSH）桌面端 / 网页端里直接浏览本机技能库，并**自动登记技能失效台账**。一个悬浮球入口，点开即见：技能目录、两级分类浏览、实时搜索、SKILL.md 全文查看；内置「失效台账」页，自动记录每次技能调用的结果。
+![技能浏览面板：分组/平铺/开关/移动](docs/images/panel-browse.png)
 
-Browse your local DSH skill library straight from the GUI, with an **automatic skill-failure ledger**. One floating-ball entry point opens a wall of skill cards — categories, live search, full SKILL.md viewer — plus a ledger page that logs the outcome of every `skill` tool call.
+## 功能一览
 
-![技能浏览器面板](docs/images/skill-browser-panel.png)
+### 🗂 三个 Tab
 
-> 技能浏览页：顶部技能总数与生成时间，搜索框 + 「全部技能」聚合启停滑块（可一键全启用 / 全停用，或点开批量选择），分类标签一行排开，主体是技能卡片墙（技能名 / 中文简介 / 分类 / 修改时间 / 开关）。
-> Browse view: skill count, search box, category chips, and a wall of skill cards.
+| Tab | 内容 |
+|---|---|
+| **技能浏览** | 搜索框 + 分组栏 + 技能卡片墙（名称 / 中文简介 / 版本徽章 / 分类 / 修改时间 / 启停开关 / 移动到分组） |
+| **调用台账** | 统计卡 + 趋势图 + 技能调用排行 + 原始流水 |
+| **快速上手** | 7 步图文引导，黑白线性图标，60 秒上手 |
 
-### 独门功能：技能失效台账 · Signature feature: the failure ledger
+### 📂 技能浏览
 
-技能调用了，可到底生效没有？插件监听 DSH 官方 `tools/result` 事件，**自动登记每一次 skill 工具调用结果**——成功记「生效 ✅」，加载失败记「未生效 ❌」并带上错误信息。人工台账与自动登记分开显示，人工维护区**插件永不改动**。
+- **悬浮球入口**：固定在屏幕角落，点击开关面板；可拖拽换位置（位置记忆），**拖到屏幕顶部也不会丢**（`app-region: no-drag` 保护，配合 DSH 设置页「回到右下角」随时复位）
+- **技能库位置自己定**：⚙ 设置里选文件夹（弹系统目录选择框），或手动粘贴路径；未配置时自动探测官方默认根 `~/.dsh/skills`，**不含任何预设路径**
+- **树状 / 平铺双视图**：树状模式每个大类独占一整行，子类常驻缩进 `├─` / `└─` 挂在下方；平铺模式保留卡片墙。选择持久化记忆
+- **搜索**：按技能名 / 中文简介 / 原始描述实时过滤
+- **版本号徽章**：优先 SKILL.md frontmatter `version`，其次同目录 `package.json`，没有则显示「暂未编版本号」
+- **技能启停**：单卡开关 / 分类级聚合滑块 / 全库批量启停（自动备份 `.bak-toggle`，停用即从模型技能目录摘除，随时可恢复）
+- **详情**：点卡片看 SKILL.md 全文（触发词 / 路径 / 最近调用记录），一键复制
 
-Did that skill actually work? The plugin listens to DSH's native `tools/result` event and **automatically logs every `skill` tool call** — successes "effective ✅", load failures "ineffective ❌" with the error. The manual ledger and the automatic log display separately, and the plugin never touches your manually maintained section.
+### 🗃 分组管理
 
----
+- **手动新建分组**：「+ 新建分组」建大类 → 子类两级；技能卡片菜单里「移动」到分组
+- **⚡ 关键词分组**：本地正则按触发词自动归类，零 token、毫秒级、结果确定
+- **🤖 AI 自动分组**：读技能清单让模型出方案（模型可选），AI 封面自动配图
+- 三种方式都**只出方案不落盘**，弹层里确认「替换 / 追加」才写入 `groups.json`
+- **存在自定义分组时，默认分类行自动隐藏**，视图更干净
 
-## 功能
+### 📋 调用台账
 
-- **悬浮球 🧩**：固定在屏幕角落，点击开关面板；可拖拽换位置（位置记忆），Alt+点击收起成小圆点
-- **技能库位置自己定**：首次使用在面板 ⚙ 设置里选择技能库文件夹（弹系统目录选择框），或手动粘贴路径；未配置时自动探测官方默认根 `~/.dsh/skills`。**插件不含任何预设路径**
-- **一级/二级分类**：按技能目录名模式自动归类（Fluent/CFD 仿真、DSH 工具链、多端协同、Excel/表格、文档处理、图片/视觉、语音/媒体、数据/可视化、开发/技能治理等 15 个一级分类与 Fluent/DSH 域二级分类）
-- **技能启停**（v1.7.0 起）：单个技能卡片开关 / 分类级聚合滑块 / 全库批量启停（带确认菜单）。停用即改写该技能 `SKILL.md` frontmatter 的 `disable-model-invocation`，改写前自动备份为 `.bak-toggle`，停用卡灰显并带徽章；随时可一键恢复
-- **中文简介**：技能简介直接取自各技能 SKILL.md frontmatter 的 description（v1.5.0 起插件不内置任何技能名清单/字典，避免泄漏技能库构成，也保证所有人看到的是自己技能库的准确描述）
-- **搜索**：按技能名 / 中文简介 / 原始描述实时过滤
-- **详情**：点击卡片查看 SKILL.md 全文，可一键复制
-- **失效台账**（人工 / 自动分开显示）：
-  - **👤 人工台账**：解析台账 md 的统计表与失败明细（人工维护区，插件永不改动）
-  - **🤖 自动登记**：插件监听 DSH 官方 `tools/result` 事件，自动记录每次 `skill` 工具调用结果——成功记「生效✅」、加载失败记「未生效❌」（含错误信息）
-  - **登记口令**：技能触发失败时，在对话里对 AI 说「触发失败，登记」或「登记失败：技能名 原因」，AI 调用上报接口写入台账
-- **台账智能发现**：初始化时全库搜索台账文件（文件名含「失效台账 / 失败台账 / 生效-失效」等关键词，约定路径 `skill-master/references/` 优先）；搜到就复用，没搜到才创建默认台账 + `skill-master` 技能骨架（幂等，已有人工内容绝不覆盖）
-- **推荐插件**：面板 ⚙ 设置展开区（技能库位置下方）保留 3 张推荐卡（照片显示器 dsh-chat-image-lightbox、字体插件 dsh-font-enhancer、Todo 悬浮球 dsh-todo-float-ball）；DSH 设置页有 4 条推荐记录；v1.5.3 起技能列表每页末尾不再显示推荐（用户反馈心烦）
-- **DSH 设置页分区「悬浮球导航」**：在 DSH 设置中即可控制 🧩 技能球 / 🔤 字体球（若安装了字体插件）/ 📋 Todo 悬浮球（若安装了 todo 插件）的显示与隐藏；v1.5.3 新增「🎯 一键恢复悬浮球默认位置（右下角）」按钮——悬浮球被拖出屏幕外卡住时点一下立即复位（清位置记忆/收起状态，无需重启）
-
-## 🎨 三球共享 128 皮肤
-与 dsh-todo-float-ball / dsh-font-enhancer 共享同一套 128 款皮肤目录（window.__DSH_BALL_SKINS，localStorage key dsh-ball-skin）。任一处切换，三个悬浮球与其展开面板实时同步；「原版（仅本球）」可让技能球单独回到原始星云紫。v1.8.x：全部面板控件（含技能详情正文、tab、开关、批量菜单）跟随皮肤，浅色主题文字对比度 WCAG 达标。
-
-## Highlights (English)
-
-- 🧩 **Floating-ball entry** — pinned to a screen corner, click to toggle the panel; draggable with position memory, Alt+click to collapse to a dot.
-- 📂 **Configurable skill root** — pick the folder via the native directory chooser in ⚙ settings, or paste a path; auto-detects the official `~/.dsh/skills` root when unset. **No hard-coded paths shipped.**
-- 📚 **Two-level categories** — auto-classified from skill directory names (15 top-level categories: Fluent/CFD simulation, DSH toolchain, multi-client collaboration, Excel/spreadsheets, document processing, image/vision, voice/media, data/visualisation, dev/skill governance…).
-- 🔘 **Skill enable/disable** (since v1.7.0) — per-card switch, category-level aggregate slider, and whole-library batch toggle with a confirmation menu. Disabling rewrites the skill's `SKILL.md` frontmatter `disable-model-invocation` after backing it up to `.bak-toggle`; disabled cards grey out with a badge and can be restored at any time.
-- 🇨🇳 **Chinese summaries** — taken straight from each skill's `SKILL.md` frontmatter `description`. Since v1.5.0 the plugin ships **no built-in skill dictionary**, so you always see an accurate description of *your own* library.
-- 🔍 **Live search** — filter by skill name, Chinese summary, or raw description.
-- 📄 **Full-text viewer** — click a card for the complete `SKILL.md`, with one-click copy.
-- 🤖 **Automatic failure ledger** — driven by the native `tools/result` event; manual and automatic records shown separately, manual content never modified.
-- 📋 **Ledger auto-discovery** — scans the whole library for an existing ledger (filename keywords, with `skill-master/references/` preferred) and reuses it; creates a default one only if absent. Idempotent, never overwrites manual content.
-- ⚙️ **Settings integration** — toggle the skill 🧩 / font 🔤 balls from DSH settings, plus a **🎯 reset-to-default-position** button that un-sticks a ball dragged off-screen (no restart needed).
-- 🎨 **128 shared ball skins** — synced live with `dsh-todo-float-ball` and `dsh-font-enhancer`; all panel controls are themed with WCAG-compliant contrast in light themes.
-
-## 安装（desktop profile）
-
-1. 把本目录完整复制到 `~/.dsh/profiles/desktop/node_modules/dsh-skill-browser`（真实目录，不要 junction/link）
-2. 在 `~/.dsh/profiles/desktop/package.json` 的 `dsh.profile.bundles` 数组加 `"dsh-skill-browser"`
-   （**不要**加进 `dependencies`——本插件零 npm 依赖，加进去反而可能在其他插件安装/更新时造成解析问题）
-3. 重启 DSH，右下角出现 🧩 悬浮球；打开 ⚙ 设置选择你的技能库文件夹即可
+插件监听 DSH 官方 `tools/result` 事件，**自动登记每一次 skill 工具调用结果**（成功「生效 ✅」/ 失败「未生效 ❌」含错误信息），人工台账与自动登记分开显示、人工维护区永不改动。
+
+看板提供：起止日期 + 今天 / 近 7 天 / 近 30 天 / 本月 / 上月 / 今年 / 全部七个快捷区间 + 日/周/月/年四种粒度 + 6 张统计卡（调用次数 / 活跃技能 / 活跃天数 / 成功率 / 失败 / 日均）+ 趋势图 + 排行榜（按调用、失败、成功率、最后调用、技能名排序，带版本号与迷你占比条）。实测规模参考：**1141 次调用、95.2% 成功率、122 个活跃技能**的全库统计秒级出图。
+
+![调用台账：统计卡 + 趋势图 + 排行榜](docs/images/panel-ledger.png)
+
+### 🎨 130 款皮肤（三球同步）
+
+- 与 dsh-todo-float-ball / dsh-font-enhancer 共享同一套皮肤系统，任一处切换三个悬浮球与面板实时同步
+- 内置「跟随系统（深/浅自动）」+ 官方深色 + 官方浅色等 130 款，全部面板控件按当前皮肤**实算对比度**配色，浅色主题 WCAG 达标
+- 皮肤菜单 **6 列宽屏布局**，130 款一屏尽览；设置页提供「三球皮肤同步」开关
+- 头部按钮全部为**黑白线性 SVG 图标**（皮肤 / 设置 / 热重载 ⚡ / 刷新 ↻ / 关闭 / GitHub Star），任何皮肤下清晰可读
 
+### 📖 快速上手（7 步，黑白线性图标）
 
-## ⚠️ 安装须知 Install Notice
+1. **选技能库位置**（第一步）→ 设置 → 选择文件夹 → 保存自动重扫
+2. **刷新** 让新技能进列表 → 不重启 DSH 立即生效再点**热重载 ⚡**（顺序：先选库 → 再刷新 → 最后热重载）
+3. **搜索与筛选**：关键词 / 树状平铺 / 关键词分组 / AI 自动分组
+4. **看详情 / 启停**：卡片展开全文，可直接禁用/启用
+5. **调用台账**：日期区间 + 粒度 → 排行、失败率与趋势
+6. **分组管理**：新建大类/子类、移动技能；删分组不删技能文件
+7. **认识面板按钮**：皮肤（130 款三球同步）→ 设置 → 热重载 → 刷新 → 关闭 → Star
 
-**发布 24 小时内安装报错？** 这不是插件问题。
+### ⚙ DSH 设置页「悬浮球导航」分区（本插件提供）
 
-DSH 桌面端内置**供应链安全策略**（minimumReleaseAge）：刚发布不到 24 小时的 npm 包会被 pnpm 拒绝安装，防止刚发布的投毒包。报错通常含 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` 字样。
+- 🧩 技能球 / 🔤 字体球 / 📋 Todo 球三球**显隐开关**（未安装的自动标注）
+- **悬浮球皮肤下拉**（130 款分组列出）
+- **「回到右下角」金色按钮**：悬浮球被拖出屏幕外卡住时一键复位，无需重启
+- **作者插件 12 款清单**：字体插件 / 技能浏览器 / Todo 进度球 / 图片灯箱 / 语音提醒 / 文献检索 / QQ 群摘要 / 模型菜单分组 / 对话归档 / 外挂识图 / 文件点击直达 / DeepSeek 网页端
 
-- ✅ **解决：等一天再装**，市场安装自然通过
-- ✅ 插件本体没有任何问题，也无需任何配置
-- ✅ 此策略对所有 DSH 插件一视同仁，是全局安全机制
+## 安装
 
-**推荐清单说明**：两个插件的设置页「悬浮球导航」分区会列出推荐插件（字体插件 / 技能浏览器 / 照片显示器），并实时探测显示「已安装 / 未安装」徽标；未安装的插件可点击 Star 前往仓库安装。
+**方式一：DSH 插件市场 / npm（推荐）**
 
-## 台账自动登记原理
+在 DSH 插件市场搜索 `dsh-skill-browser` 安装，或：
+
+```
+pnpm add dsh-skill-browser
+```
+
+并把 `"dsh-skill-browser"` 加入 profile 的 `dsh.profile.bundles` 数组，重启 DSH，右下角出现 🧩 悬浮球。
+
+**方式二：本地目录安装（desktop profile）**
+
+1. 把本仓库完整复制到 `~/.dsh/profiles/desktop/node_modules/dsh-skill-browser`（真实目录，不要 junction/link）
+2. 在 `~/.dsh/profiles/desktop/package.json` 的 `dsh.profile.bundles` 数组加 `"dsh-skill-browser"`（**不要**加进 `dependencies`——本插件零 npm 依赖）
+3. 重启 DSH，右下角出现 🧩 悬浮球；打开 ⚙ 设置选择你的技能库文件夹即可
 
-- 数据源 1（自动，确定性）：`ctx.on('tools/result', (exec, result) => ...)`，过滤 `exec.name === 'skill'`；`result.isError` 为真记失败，同时记录 `exec.arguments.name`（技能名）与错误文本
-- 数据源 2（手动，语义层）：`POST /ledger/report { skill, note, kind }`，对话 AI 发现用户纠错/技能未达预期时调用
-- 台账文件：初始化时搜索技能库（文件名含「失效台账 / 失败台账 / 生效-失效」等，约定路径优先）；搜到则复用并在插件标记区块内增量写入（**人工内容永不改动**，首次接管自动备份）；没搜到则在 `skill-master/references/技能生效-失效台账.md` 创建默认台账
-- 全量机器可读流水：`<技能库>/skill-master/references/技能失效-自动登记.jsonl`
-- 写盘节流：队列满 5 条或 60 秒批量落盘，绝不阻塞工具调用
+> ⚠️ **发布 24 小时内安装报错？** 这不是插件问题。DSH 桌面端内置供应链安全策略（minimumReleaseAge）：刚发布不到 24 小时的 npm 包会被 pnpm 拒绝安装（报错含 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`）。**等一天再装即可**，无需任何配置。
 
 ## API（宿主端，仅回环可访问）
 
 | 路由 | 说明 |
 |---|---|
 | `GET /dsh-skill-browser/health` | 健康检查（含 root 与识别来源） |
+| `GET /dsh-skill-browser/rev` | 当前加载代号与版本（热重载探针） |
+| `POST /dsh-skill-browser/reload` | 热重载 host 半代码，返回新代号 |
 | `GET/POST /dsh-skill-browser/config` | 读取/保存运行时配置（skillsDir、ledgerEnabled） |
-| `GET /dsh-skill-browser/skills[?refresh=1]` | 全量技能清单 + 分类元数据 + 总数 |
+| `GET /dsh-skill-browser/skills[?refresh=1]` | 全量技能清单（含 `version`）+ 分类元数据 + 总数 |
 | `GET /dsh-skill-browser/skill?dir=<name>` | 读取某技能 SKILL.md 全文 |
+| `GET/POST /dsh-skill-browser/groups` | 读取/写入两级分组（`groups.json`），action：`create/rename/delete/move/assign/assign-batch/ai-classify/kw-classify/ai-apply/ai-cover/model-info` |
 | `GET /dsh-skill-browser/ledger[?refresh=1]` | 人工台账表 + 自动登记统计与流水 |
+| `GET /dsh-skill-browser/ledger/stats?from=&to=&gran=&sort=&top=` | 调用台账看板聚合（gran=day\|week\|month\|year，sort=calls\|fails\|rate\|last\|name） |
 | `POST /dsh-skill-browser/ledger/report` | 手动上报失败 `{ skill, note, kind }` |
 | `POST /dsh-skill-browser/ledger/flush` | 立即落盘队列中的登记 |
 | `GET /dsh-skill-browser/ledger-detail?skill=<name>` | 该技能的人工明细 + 全部自动记录 |
 | `POST /dsh-skill-browser/pick-dir` | 弹系统目录选择框（Windows） |
-| `POST /dsh-skill-browser/toggle` | 单技能启停 `{ dir, enabled }`（改写 SKILL.md frontmatter，自动备份 `.bak-toggle`） |
-| `POST /dsh-skill-browser/toggle-batch` | 批量启停 `{ dirs: [...], enabled }`（分类级聚合滑块与全库批量走这里） |
+| `POST /dsh-skill-browser/toggle` | 单技能启停（改写 frontmatter，自动备份） |
+| `POST /dsh-skill-browser/toggle-batch` | 批量启停 |
 | `GET/POST /dsh-skill-browser/diag` | 诊断信息（扫描耗时、缓存状态、最近错误） |
-| `GET /dsh-skill-browser/orb/<orb-*.html>` | 悬浮球静态资源（皮肤精灵图等） |
+| `GET /dsh-skill-browser/orb/<orb-*.html>` | 悬浮球静态资源 |
 
-技能根目录解析顺序：设置页覆盖（`~/.dsh/data/dsh-skill-browser/config.json`）→ 环境变量 `DSH_SKILLS_DIR` → 插件 config `skillsDir` → `~/.dsh/skills`（官方默认根）。全部未命中时面板提示选择目录。
+技能根目录解析顺序：设置页覆盖（`~/.dsh/data/dsh-skill-browser/config.json`）→ 环境变量 `DSH_SKILLS_DIR` → 插件 config `skillsDir` → `~/.dsh/skills`（官方默认根）。
 
 ## 测试