dsh-skill-browser 1.9.9 → 1.9.10

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

@@ -4,9 +4,10 @@
 
 **Turn your skill library into something you can see, search, and govern.**
 
-在 DeepSeek Harness（DSH）桌面端 / 网页端里直接浏览本机技能库，并**自动登记技能失效台账**。一个悬浮球入口，点开即见：技能目录、两级分类浏览、实时搜索、SKILL.md 全文查看；内置「失效台账」页，自动记录每次技能调用的结果。
+在 DeepSeek Harness（DSH）桌面端 / 网页端里用一个悬浮球打开面板，把本机技能库变成可浏览、可检索、可治理的资产：两级分类 + **自定义分组**（树状/平铺双模式、手动建大类与子类、⚡ 关键词分组、🤖 AI 自动分组与 AI 封面，**分组只是视图归档，绝不移动任何技能文件**）、**版本号徽章**（无版本显示「暂未编版本号」）、单卡 / 分类 / 全库启停（自动备份 `.bak-toggle`）、SKILL.md 全文查看；内置 **调用台账看板**（起止日期 + 日/周/月/年 + 排行榜 + 趋势图 + 失效明细），监听 DSH 官方 `tools/result` 事件自动登记每次技能调用结果。面板 ⚡ 一键热重载，**128 款皮肤全量自适应配色**（对比度实算），技能库位置可配置，悬浮球可拖拽可复位。
+
+Open a floating-ball panel inside DeepSeek Harness (DSH) and turn your local skill library into something you can browse, search and govern: one/two-level categories plus **custom groups** (tree/flat views, manual parent/child groups, ⚡ instant keyword grouping, 🤖 AI auto-grouping with AI-generated covers — **grouping is view-only and never moves a skill file**), **version badges** (falling back to "no version yet"), per-card / per-category / library-wide enable-disable with automatic `.bak-toggle` backups, and a full SKILL.md viewer. A **call-ledger dashboard** adds date ranges, day/week/month/year granularity, rankings, a trend chart and failure details, fed automatically by DSH's native `tools/result` event. One-click ⚡ hot reload, **all 128 ball skins contrast-adaptive**, configurable skill root, draggable and resettable ball.
 
-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)
 
@@ -26,10 +27,17 @@ Did that skill actually work? The plugin listens to DSH's native `tools/result`
 - **悬浮球 🧩**：固定在屏幕角落，点击开关面板；可拖拽换位置（位置记忆），Alt+点击收起成小圆点
 - **技能库位置自己定**：首次使用在面板 ⚙ 设置里选择技能库文件夹（弹系统目录选择框），或手动粘贴路径；未配置时自动探测官方默认根 `~/.dsh/skills`。**插件不含任何预设路径**
 - **一级/二级分类**：按技能目录名模式自动归类（Fluent/CFD 仿真、DSH 工具链、多端协同、Excel/表格、文档处理、图片/视觉、语音/媒体、数据/可视化、开发/技能治理等 15 个一级分类与 Fluent/DSH 域二级分类）
+- **自定义分组（v1.9.0 起，v1.9.8 支持树状/平铺双模式）**：分组栏可手动新建「大类 → 子类」两级分组，也可用「⚡ 关键词分组」（本地正则，零 token、毫秒级、结果确定）或「🤖 AI 自动分组」（读技能清单让模型出方案）自动建组。AI / 关键词都**只出方案不落盘**，方案弹层里确认「替换」或「追加」才写入 `groups.json`。**分组只是视图归档，绝不移动、不重命名任何技能文件。**
+- **树状 / 平铺双模式**：树状模式下每个大类独占一整行，子类常驻缩进挂在下方并用 `├─` / `└─` 树杈连接，一眼看清「Fluent 下面有画网格 / 后处理 / SpaceClaim 几何操作」；平铺模式保留旧版卡片墙。选择持久化到 `localStorage.dsh-skill-browser-gmode`。
+- **版本号徽章（v1.9.0 起）**：技能名右侧显示版本号（优先 SKILL.md frontmatter 的 `version`，其次同目录 `package.json` 的 `version`），没有版本号则显示「暂未编版本号」。
 - **技能启停**（v1.7.0 起）：单个技能卡片开关 / 分类级聚合滑块 / 全库批量启停（带确认菜单）。停用即改写该技能 `SKILL.md` frontmatter 的 `disable-model-invocation`，改写前自动备份为 `.bak-toggle`，停用卡灰显并带徽章；随时可一键恢复
 - **中文简介**：技能简介直接取自各技能 SKILL.md frontmatter 的 description（v1.5.0 起插件不内置任何技能名清单/字典，避免泄漏技能库构成，也保证所有人看到的是自己技能库的准确描述）
 - **搜索**：按技能名 / 中文简介 / 原始描述实时过滤
 - **详情**：点击卡片查看 SKILL.md 全文，可一键复制
+- **调用台账看板（v1.9.1 起）**：台账页从「原始流水」升级为看板——起止日期筛选 + 今天/近 7 天/近 30 天/本月/上月/今年/全部七个快捷区间 + 日/周/月/年四种粒度 + 6 张指标卡（调用次数 / 活跃技能 / 活跃天数 / 成功率 / 失败 / 日均）+ 纯 CSS 趋势柱 + 排行榜（可按调用、失败、成功率、最后调用、技能名排序，带版本号与迷你占比条）。原始流水（人工台账 + 自动登记）折叠在下方。
+- **热重载（v1.9.4 起）**：面板头部 ⚡ 按钮调用 `POST /reload`，插件重新加载自己的 host 半代码（`?v=<ts>` 绕开 ESM 缓存）并递增代号，前端轮询 `GET /rev` 等到代号变化后自动刷新界面——**改完代码不用重启桌面端**。
+- **性能（v1.9.6 起）**：技能卡片分片渲染（一次 60 张，滚到底自动追加），原始流水分片渲染（一次 120 行），jsonl 走尾部增量读取，`/ledger/stats` 缓存键并入 jsonl 的 size+mtime，详情页默认只回最近 200 条。
+- **全皮肤自适应配色（v1.9.2 / v1.9.5 / v1.9.9 三轮加固）**：面板所有新增控件（分组栏、版本徽章、台账看板、吸顶表头）颜色全部走语义变量（`--dsb-brand` / `--dsb-dim` / `--dsb-ok` / `--dsb-fail` / `--dsb-warn` / `--dsb-surface` / `--dsb-onbrand` 等），按当前皮肤实际叠层背景实算对比度，128 款皮肤 × 18 组前景/背景组合共 2304 项全部达标。
 - **失效台账**（人工 / 自动分开显示）：
   - **👤 人工台账**：解析台账 md 的统计表与失败明细（人工维护区，插件永不改动）
   - **🤖 自动登记**：插件监听 DSH 官方 `tools/result` 事件，自动记录每次 `skill` 工具调用结果——成功记「生效✅」、加载失败记「未生效❌」（含错误信息）
@@ -46,6 +54,9 @@ Did that skill actually work? The plugin listens to DSH's native `tools/result`
 - 🧩 **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…).
+- 🗂 **Custom groups** (since v1.9.0; tree/flat dual view since v1.9.8) — create your own two-level `domain → sub` groups by hand, or let **⚡ keyword grouping** (local regex, zero tokens, millisecond, deterministic) / **🤖 AI auto-grouping** build them for you. Both only produce a *plan*; nothing is written to `groups.json` until you confirm **Replace** or **Merge**. **Groups are a view-only archive — no skill file is ever moved or renamed.**
+- 🌳 **Tree / flat views** — tree mode gives every domain its own full-width row with its sub-groups permanently indented underneath, joined by `├─` / `└─` branches, so "Fluent → meshing / post-processing / SpaceClaim geometry" is visible at a glance. Choice persisted in `localStorage.dsh-skill-browser-gmode`.
+- 🏷 **Version badges** (since v1.9.0) — the skill's version sits right next to its name (frontmatter `version`, else the sibling `package.json` `version`), showing "not versioned yet" when absent.
 - 🔘 **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.
@@ -88,10 +99,14 @@ DSH 桌面端内置**供应链安全策略**（minimumReleaseAge）：刚发布
 | 路由 | 说明 |
 |---|---|
 | `GET /dsh-skill-browser/health` | 健康检查（含 root 与识别来源） |
+| `GET /dsh-skill-browser/rev` | 当前加载代号与版本（热重载探针） |
+| `POST /dsh-skill-browser/reload` | 热重载 host 半代码，返回新代号（v1.9.4） |
 | `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`）。POST 的 `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>` | 该技能的人工明细 + 全部自动记录 |

package/lib/client.js

@@ -3157,23 +3157,29 @@ window.__ModuleLoader__.load({
       // #12151c) until white text clears 4.6:1, then emit --dsb-onbrand-bg1/2.
       // Every active-state background uses those instead of the raw stA/stD.
       var g1 = skinRgb(v.stA) || [91, 108, 255, 1], g2 = skinRgb(v.stP || v.stD) || g1;
-      var gmid = skinMix(g1, g2, 0.5);
-      var whiteOnMid = skinCr([255, 255, 255], gmid);
-      var darkOnMid = skinCr([18, 21, 28], gmid);
-      if (whiteOnMid >= 4.6) {
+      // v1.9.10: judge the gradient by its WORST ENDPOINT, not its midpoint.
+      // A linear-gradient paints g1..g2, so the label sits on the whole ramp;
+      // checking only the midpoint let 04/051/113-127 pass at the middle while
+      // their light end was still 3.7-4.4:1 against white text.
+      var worst = function (ink, a1, a2) {
+        return Math.min(skinCr(ink, a1), skinCr(ink, a2));
+      };
+      var W = [255, 255, 255], K = [18, 21, 28];
+      if (worst(W, g1, g2) >= 4.6) {
         d["--dsb-onbrand"] = "#ffffff";
         d["--dsb-onbrand-bg1"] = skinHex(g1);
         d["--dsb-onbrand-bg2"] = skinHex(g2);
-      } else if (darkOnMid >= 4.6) {
+      } else if (worst(K, g1, g2) >= 4.6) {
         d["--dsb-onbrand"] = "#12151c";
         d["--dsb-onbrand-bg1"] = skinHex(g1);
         d["--dsb-onbrand-bg2"] = skinHex(g2);
       } else {
-        // Neither extreme works → darken the gradient step by step.
-        var ink = [18, 21, 28, 1], a1 = g1, a2 = g2, t = 0;
-        for (t = 0.1; t <= 0.95; t += 0.05) {
-          a1 = skinMix(g1, ink, t); a2 = skinMix(g2, ink, t);
-          if (skinCr([255, 255, 255], skinMix(a1, a2, 0.5)) >= 4.6) break;
+        // Neither extreme works → darken the ramp until white clears 4.6 at
+        // BOTH ends.
+        var ink = [18, 21, 28, 1], a1 = g1, a2 = g2, tt = 0;
+        for (tt = 0.1; tt <= 0.95; tt += 0.05) {
+          a1 = skinMix(g1, ink, tt); a2 = skinMix(g2, ink, tt);
+          if (worst(W, a1, a2) >= 4.6) break;
         }
         d["--dsb-onbrand"] = "#ffffff";
         d["--dsb-onbrand-bg1"] = skinHex(a1);

package/lib/index.js

@@ -46,7 +46,7 @@ var listGroups = grMod.listGroups, createGroup = grMod.createGroup,
 var keywordClassify = kwMod.keywordClassify;
 
 var PREFIX = "/dsh-skill-browser";
-export var VERSION = "1.9.9";
+export var VERSION = "1.9.10";
 var CACHE_TTL_MS = 30 * 1000;
 var DIAG_FILE = join(homedir(), ".dsh", "data", "dsh-skill-browser", "diag.log");
 var CONFIG_FILE = join(homedir(), ".dsh", "data", "dsh-skill-browser", "config.json");

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Skill Browser",
-    "description": "Open a floating-ball panel to browse, search and inspect your local skill library with one/two-level categories and full SKILL.md viewer; enable or disable skills per card, per category or library-wide with automatic backups; auto-log every skill call in a failure ledger. Configurable skill root (native directory chooser), draggable ball with one-click reset."
+    "description": "One floating ball opens a panel that turns your local skill library into something you can browse, search and govern: one/two-level categories plus custom groups (tree/flat views, manual groups, instant keyword grouping, AI auto-grouping with AI covers — grouping is view-only and never moves skill files), per-skill version badges with a \"no version yet\" fallback, per-card / per-category / library-wide enable-disable with automatic backups, and a full SKILL.md viewer. A call-ledger dashboard adds date ranges, day/week/month/year granularity, rankings, trend chart and failure details, fed automatically by the host's tools/result event. One-click hot reload, all 128 ball skins contrast-adaptive, configurable skill root, draggable and resettable ball."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "技能浏览器",
-    "description": "以悬浮球打开技能面板，按一级/二级分类检索本机技能库，查看 SKILL.md 全文，单个/分类级/全库批量启停技能（自动备份），并自动登记技能调用失效台账；技能库位置可配置（原生目录选择框），悬浮球可拖拽、可一键复位。"
+    "description": "技能浏览器：悬浮球打开面板，把本机技能库变成可浏览、可检索、可治理的资产——两级分类 + 自定义分组（树状/平铺双模式、手动建组、⚡关键词分组、🤖AI 自动分组与 AI 封面，分组只改视图不动技能文件）、版本号徽章（无版本显示「暂未编版本号」）、单卡/分类/全库启停（自动备份）、SKILL.md 全文查看；调用台账看板（起止日期 + 日/周/月/年 + 排行榜 + 趋势图 + 失效明细），监听 tools/result 自动登记每次技能调用结果。⚡ 一键热重载，128 款皮肤全量自适应配色，技能库位置可配置，悬浮球可拖拽可复位。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-skill-browser",
-  "version": "1.9.9",
-  "description": "技能浏览器：把 ~/.dsh/skills 里的技能做成可视化面板（搜索/分类/启停/详情/调用台账）。v1.9.0 自定义分组+版本号+AI 分组+AI 封面；v1.9.1 调用台账看板；v1.9.2 全皮肤自适应配色；v1.9.3 两级分组+滚动条+悬浮球层级；v1.9.4 面板⚡热重载；v1.9.5 吸顶表头不透明；v1.9.6 详情层隔离+分片渲染+增量读取；v1.9.7 关键词快速分组；v1.9.8 树状/平铺双模式分组栏；v1.9.9 零配置模型自动发现+全皮肤文字可见性加固。",
+  "version": "1.9.10",
+  "description": "技能浏览器：悬浮球打开面板，把本机技能库变成可浏览、可检索、可治理的资产——两级分类 + 自定义分组（树状/平铺双模式、手动建组、⚡关键词分组、🤖AI 自动分组与 AI 封面，分组只改视图不动技能文件）、版本号徽章（无版本显示「暂未编版本号」）、单卡/分类/全库启停（自动备份）、SKILL.md 全文查看；调用台账看板（起止日期 + 日/周/月/年 + 排行榜 + 趋势图 + 失效明细），监听 tools/result 自动登记每次技能调用结果。⚡ 一键热重载，128 款皮肤全量自适应配色，技能库位置可配置，悬浮球可拖拽可复位。",
   "type": "module",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -31,7 +31,8 @@
     "README-zh.md",
     "README-es.md",
     "README-pt.md",
-    "README-hi.md"
+    "README-hi.md",
+    "scripts"
   ],
   "license": "MIT",
   "keywords": [

package/scripts/audit-contrast.mjs

@@ -0,0 +1,215 @@
+// 全皮肤对比度总审计（唯一权威口径）
+//
+// 用法：node scripts/audit-contrast.mjs [--verbose]
+// 退出码：0 = 全部达标；1 = 有不达标项（明细打印到 stdout）
+//
+// 口径说明：
+//   - 皮肤目录（128 款）来自 lib/client.js 内联的 window.__DSH_BALL_SKINS。
+//   - 语义变量来自真实调用链：applySkinNow() 把 skinBallCss() + skinPanelCss()
+//     写进 <style id="dsb-skin-style">，本脚本切皮肤后直接从该 style 的
+//     textContent 里解析 --dsb-* 实际值 —— 不复制一份「期望值」，
+//     避免审计与生产实现各算一套、出现假绿。
+//   - 背景一律取「实际叠层后的颜色」：
+//       panel   = pbgA || bgA
+//       card    = chipBg over panel   （卡片/排行行真实底色）
+//       surface = --dsb-surface       （吸顶表头不透明底色，实算值）
+//       gtile1/2= shade over tile1/2  （分组大类行是线性渐变，两个端点分别校验）
+//       obg1/2  = --dsb-onbrand-bg1/2 （品牌渐变两个端点，只测中点会漏浅端）
+//   - 渐变底必须按最差端点判定，这是 v1.9.10 修的 bug：
+//     中点达标但浅端只有 3.7–4.4:1，实际渲染出来白字就是看不清。
+import fs from "node:fs";
+import vm from "node:vm";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLIENT = join(HERE, "..", "lib", "client.js");
+const VERBOSE = process.argv.includes("--verbose");
+
+// ---------- 最小 DOM stub：只为让 client.js 的 factory 跑完并产出 style ----------
+const registry = {};
+function mkEl(tag) {
+  const el = {
+    tagName: tag, __ev: {}, style: {}, dataset: {}, children: [], options: { length: 0 },
+    classList: {
+      _s: new Set(),
+      add(c) { this._s.add(c); }, remove(c) { this._s.delete(c); },
+      toggle(c, v) { v ? this._s.add(c) : this._s.delete(c); }, contains(c) { return this._s.has(c); }
+    },
+    _html: "", textContent: "", id: "", className: "", title: "",
+    getAttribute(k) { return this[k] == null ? null : this[k]; },
+    setAttribute(k, v) { if (k === "id") { this.id = v; registry[v] = this; } this[k] = v; },
+    removeAttribute(k) { delete this[k]; }, hasAttribute(k) { return this[k] != null; },
+    appendChild(c) { this.children.push(c); if (c && c.id) registry[c.id] = c; return c; },
+    insertBefore(c) { this.children.push(c); if (c && c.id) registry[c.id] = c; return c; },
+    removeChild(c) { const i = this.children.indexOf(c); if (i >= 0) this.children.splice(i, 1); return c; },
+    remove() { }, addEventListener(t, f) { (this.__ev[t] = this.__ev[t] || []).push(f); }, removeEventListener() { },
+    querySelector() { return null; }, querySelectorAll() { return []; }, closest() { return null; },
+    focus() { }, blur() { }, click() { },
+    getBoundingClientRect() { return { left: 10, top: 10, right: 110, bottom: 40, width: 100, height: 30 }; },
+    contains() { return false; }
+  };
+  Object.defineProperty(el, "innerHTML", {
+    get() { return this._html; },
+    set(v) {
+      this._html = String(v);
+      const re = /id="([A-Za-z0-9_-]+)"/g; let m;
+      while ((m = re.exec(this._html))) if (!registry[m[1]]) registry[m[1]] = mkEl("div");
+    }
+  });
+  return el;
+}
+
+const sandbox = {
+  console: { log() { }, warn() { }, error() { } }, // 屏蔽 client.js 的 mounted 日志
+  JSON, Math, Date, String, Number, Object, Array, RegExp, parseInt, parseFloat, isNaN, Boolean,
+  setTimeout: (f) => { try { f(); } catch (e) { } }, clearTimeout() { },
+  setInterval: () => 0, clearInterval() { },
+  fetch: () => Promise.reject(new Error("audit: no network")),
+  // 必须可读写：SKIN.setSkin(id) 靠 localStorage 记住选择，写不进去就会一直用 01 号皮肤，
+  // 导致 128 款皮肤全按深色算 → 20 款浅色皮肤集体假报不达标（踩过）。
+  localStorage: {
+    _d: {},
+    getItem(k) { return this._d[k] ?? null; },
+    setItem(k, v) { this._d[k] = String(v); },
+    removeItem(k) { delete this._d[k]; }
+  },
+  CustomEvent: function (n, o) { this.type = n; this.detail = o && o.detail; },
+  document: {
+    head: mkEl("head"), body: mkEl("body"), documentElement: mkEl("html"),
+    createElement: mkEl,
+    getElementById: (i) => registry[i] || null,
+    querySelector: (s) => (s && s.startsWith("#") ? registry[s.slice(1)] || null : null),
+    querySelectorAll: () => [], addEventListener() { }, removeEventListener() { }
+  },
+  location: { reload() { }, href: "http://127.0.0.1/" },
+  navigator: { userAgent: "node" }
+};
+sandbox.window = sandbox; sandbox.self = sandbox; sandbox.globalThis = sandbox;
+sandbox.dispatchEvent = function () { };
+vm.createContext(sandbox);
+
+const mod = { id: "dsh-skill-browser", exports: {} };
+sandbox.__ModuleLoader__ = { load(o) { mod.exports = o.factory((n) => require(n)); } };
+vm.runInContext(fs.readFileSync(CLIENT, "utf8"), sandbox);
+mod.exports.apply({
+  slots: { register() { }, inject() { }, slot() { } },
+  locale: { register() { }, t: (k) => k },
+  settings: { register() { } },
+  effect(f) { return f && f(); },
+  logger: { info() { }, warn() { }, error() { } },
+  get: () => null, on() { }
+});
+
+const SKIN = sandbox.window.__DSH_BALL_SKINS;
+if (!SKIN) { console.error("FATAL: window.__DSH_BALL_SKINS 未挂载，皮肤目录没加载成功"); process.exit(2); }
+const ids = Object.keys(SKIN.BY_ID);
+
+// ---------- 颜色工具（与 lib/client.js 的 skinRgb/skinCr 同口径，但独立实现以交叉校验） ----------
+function rgb(c) {
+  if (c == null) return null;
+  const s = String(c).trim(); let m;
+  if ((m = /^#([0-9a-f]{3})$/i.exec(s))) return [parseInt(m[1][0] + m[1][0], 16), parseInt(m[1][1] + m[1][1], 16), parseInt(m[1][2] + m[1][2], 16), 1];
+  if ((m = /^#([0-9a-f]{6})$/i.exec(s))) return [parseInt(s.slice(1, 3), 16), parseInt(s.slice(3, 5), 16), parseInt(s.slice(5, 7), 16), 1];
+  // 100 款派生皮肤的颜色是 hsl()/hsla() 字符串，不解析 hsl 会全部落空 → 假绿/假红。
+  if ((m = /^hsla?\(\s*(-?[\d.]+)(?:deg)?[,\s]+([\d.]+)%[,\s]+([\d.]+)%(?:[,\s/]+([\d.]+))?/i.exec(s))) {
+    const h = ((parseFloat(m[1]) % 360) + 360) % 360, sat = parseFloat(m[2]) / 100, l = parseFloat(m[3]) / 100;
+    const a = m[4] == null ? 1 : parseFloat(m[4]);
+    const cc = (1 - Math.abs(2 * l - 1)) * sat, x = cc * (1 - Math.abs(((h / 60) % 2) - 1)), mm = l - cc / 2;
+    let r = 0, g = 0, b = 0;
+    if (h < 60) { r = cc; g = x; } else if (h < 120) { r = x; g = cc; } else if (h < 180) { g = cc; b = x; }
+    else if (h < 240) { g = x; b = cc; } else if (h < 300) { r = x; b = cc; } else { r = cc; b = x; }
+    return [Math.round((r + mm) * 255), Math.round((g + mm) * 255), Math.round((b + mm) * 255), a];
+  }
+  if ((m = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:[,\s/]+([\d.]+))?/i.exec(s))) return [+m[1], +m[2], +m[3], m[4] == null ? 1 : +m[4]];
+  return null;
+}
+const lum = (r) => {
+  const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+  return 0.2126 * f(r[0]) + 0.7152 * f(r[1]) + 0.0722 * f(r[2]);
+};
+const cr = (a, b) => { const l1 = lum(a), l2 = lum(b); return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05); };
+const over = (fg, bg) => { const a = fg[3]; return [fg[0] * a + bg[0] * (1 - a), fg[1] * a + bg[1] * (1 - a), fg[2] * a + bg[2] * (1 - a), 1]; };
+
+function varsOf(id) {
+  SKIN.setSkin(id); // 触发 __dshBallSkinHooks → applySkinNow() 重算 style
+  const css = (registry["dsb-skin-style"] || {}).textContent || "";
+  const out = {}; let m;
+  const re = /--dsb-([a-z0-9-]+):([^;}]+)/g;
+  while ((m = re.exec(css))) out["--dsb-" + m[1]] = m[2].trim();
+  return out;
+}
+
+// 检查表：[说明, 前景来源(变量名或皮肤原生 key), 背景 key, 最低对比度]
+// 4.5 = WCAG AA 正常文字；3.0 = 大号文字 / 非文字图形（图标、趋势柱、迷你条）
+const CHECKS = [
+  ["正文 ptx / 面板", "ptx", "panel", 4.5],
+  ["卡片名 dsb-brand / 卡片底", "--dsb-brand", "card", 4.5],
+  ["排行名 dsb-brand / 行底", "--dsb-brand", "row", 4.5],
+  ["指标大数字 brand-strong / 卡片底", "--dsb-brand-strong", "card", 3.0],
+  ["次要小字 dsb-dim / 面板", "--dsb-dim", "panel", 4.5],
+  ["次要小字 dsb-dim / 卡片底", "--dsb-dim", "card", 4.5],
+  ["吸顶表头 dsb-dim / 不透明表头底", "--dsb-dim", "surface", 4.5],
+  ["成功绿 dsb-ok / 卡片底", "--dsb-ok", "card", 3.0],
+  ["失败红 dsb-fail / 卡片底", "--dsb-fail", "card", 3.0],
+  ["警告黄 dsb-warn / 卡片底", "--dsb-warn", "card", 3.0],
+  ["激活态文字 onbrand / 品牌渐变起点", "--dsb-onbrand", "obg1", 4.5],
+  ["激活态文字 onbrand / 品牌渐变终点", "--dsb-onbrand", "obg2", 4.5],
+  ["分组卡名 oncard / 分组卡底(渐变起点)", "--dsb-oncard", "gtile1", 4.5],
+  ["分组卡名 oncard / 分组卡底(渐变终点)", "--dsb-oncard", "gtile2", 4.5],
+  ["分组计数 oncard-dim / 分组卡底(起点)", "--dsb-oncard-dim", "gtile1", 3.0],
+  ["分组计数 oncard-dim / 分组卡底(终点)", "--dsb-oncard-dim", "gtile2", 3.0],
+  ["趋势柱 bar1 / 面板", "--dsb-bar1", "panel", 3.0],
+  ["趋势柱 bar2 / 面板", "--dsb-bar2", "panel", 3.0]
+];
+
+const fails = [];
+for (const id of ids) {
+  const V = varsOf(id);
+  const base = SKIN.BY_ID[id].vars;
+  const panel = rgb(base.pbgA || base.bgA);
+  const chip = rgb(base.chipBg);
+  const card = chip ? over(chip, panel) : panel;
+  const surface = rgb(V["--dsb-surface"]) || card;
+  const gt1 = rgb(V["--dsb-tile1"]) || [58, 67, 112, 1];
+  const gt2 = rgb(V["--dsb-tile2"]) || [35, 42, 69, 1];
+  const gshade = rgb(V["--dsb-shade"]) || [8, 10, 18, 0.42];
+  const BG = {
+    panel, card, row: card, surface,
+    gtile1: over(gshade, gt1), gtile2: over(gshade, gt2),
+    obg1: rgb(V["--dsb-onbrand-bg1"]), obg2: rgb(V["--dsb-onbrand-bg2"])
+  };
+
+  for (const [name, key, bgKey, min] of CHECKS) {
+    const fgStr = key.startsWith("--") ? V[key] : base[key];
+    if (!fgStr) { fails.push({ id, name, why: "变量缺失 " + key }); continue; }
+    const fg = rgb(fgStr), bg = BG[bgKey];
+    if (!fg || !bg) { fails.push({ id, name, why: "无法解析 " + fgStr + " / " + bgKey }); continue; }
+    const eff = fg[3] < 1 ? over(fg, bg) : fg;
+    const v = cr(eff, bg);
+    if (v < min) fails.push({ id, name, v: +v.toFixed(2), min, fg: fgStr, bgKey });
+    else if (VERBOSE) console.log(`ok  ${id} ${SKIN.BY_ID[id].name}  ${name}  ${v.toFixed(2)}:1`);
+  }
+}
+
+const light = ids.filter((i) => {
+  const b = SKIN.BY_ID[i].vars;
+  const p = rgb(b.pbgA || b.bgA);
+  return p && lum(p) > 0.45;
+}).length;
+
+console.log(`皮肤: ${ids.length}（浅色 ${light}）  检查组: ${CHECKS.length}  总项: ${ids.length * CHECKS.length}`);
+console.log(`不达标: ${fails.length}`);
+if (fails.length) {
+  const byName = {};
+  for (const f of fails) (byName[f.name] = byName[f.name] || []).push(f);
+  for (const n of Object.keys(byName)) {
+    console.log(`\n[${n}] ${byName[n].length} 款`);
+    for (const f of byName[n].slice(0, 8)) {
+      console.log(`   ${f.id} ${SKIN.BY_ID[f.id].name}  ${f.v ?? f.why}${f.min ? " < " + f.min : ""}  (fg=${f.fg || "-"} bg=${f.bgKey || "-"})`);
+    }
+  }
+  process.exit(1);
+}

package/scripts/check-bom.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// 防 BOM 回归：扫描仓库内所有文本文件，发现 UTF-8 BOM 立即报错退出。
+// 背景：v1.9.2 改造时 package.json / lib/index.js 被写入 BOM，导致宿主 JSON.parse 失败、
+// 市场判定「该包不可用」、整包不激活、悬浮球消失。此脚本作为发布前硬门禁。
+// 用法：node scripts/check-bom.mjs [--fix]
+
+import fs from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1")), "..");
+const FIX = process.argv.includes("--fix");
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "coverage"]);
+
+function walk(dir, out) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else out.push(p);
+  }
+  return out;
+}
+
+const files = walk(ROOT, []).filter((p) =>
+  /\.(json|js|mjs|cjs|ts|yml|yaml|md|txt|ps1|html|css|svg)$/i.test(p)
+);
+
+const bad = [];
+for (const p of files) {
+  const b = fs.readFileSync(p);
+  if (b.length >= 3 && b[0] === 0xef && b[1] === 0xbb && b[2] === 0xbf) {
+    bad.push(p);
+    if (FIX) {
+      fs.writeFileSync(p, b.subarray(3));
+      console.log("FIXED  " + path.relative(ROOT, p));
+    }
+  }
+}
+
+if (bad.length === 0) {
+  console.log("OK: " + files.length + " 个文本文件，0 个带 UTF-8 BOM");
+  process.exit(0);
+}
+
+if (!FIX) {
+  console.error("FAIL: 发现 " + bad.length + " 个带 UTF-8 BOM 的文件（会导致宿主 JSON.parse 失败、插件被判不可用）：");
+  for (const p of bad) console.error("  " + path.relative(ROOT, p));
+  console.error("修复：node scripts/check-bom.mjs --fix");
+  process.exit(1);
+}
+console.log("已修复 " + bad.length + " 个文件");