dsh-skill-hub 0.3.6 → 0.3.8

package/README.md

@@ -13,38 +13,45 @@
   <img src="https://raw.githubusercontent.com/cheshireez/dsh-skill-hub/main/promo/real-skill-hub.png" alt="dsh-skill-hub panel" width="640">
 </p>
 
-In-GUI skill hub for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — browse the full `ctx.skills` catalog, toggle skills, inspect bodies, diagnose missing skills, install from the market, and scaffold new ones.
+In-GUI skill hub for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — browse the full `ctx.skills` catalog, toggle skills, inspect bodies, fix discovery issues, install from the market, and scaffold new ones.
 
 > Host runs in the dsh process via official SDKs only; browser renders through official slots. No dsh source changes.
 
-## Why not just the read-only browser?
+## Quick start
 
-[dsh-skill-manager](https://www.npmjs.com/package/dsh-skill-manager) browses, [dsh-skill-importer](https://github.com/saitamahang/dsh-skill-importer) / [dsh-find-skill](https://github.com/Moximxxx/dsh-find-skill) import. **This plugin is the manager in between.**
+```bash
+dsh plugin --profile web add dsh-skill-hub
+# restart dsh web → Settings → 技能 → Market → scan → import
+```
 
-| Capability | read-only browser | **dsh-skill-hub** |
-| --- | --- | --- |
-| Catalog | user roots, self-scanned | `ctx.skills` registry: project / custom / user / bundled + third-party |
-| Workspace | ❌ | ✅ `.dsh/skills` & `.agents/skills` (read-only, merged by default) |
-| Toggle | ❌ | ✅ rename `SKILL.md` (never delete), tri-state group switches + drag reorder |
-| Diagnostics / scaffold | ❌ | ✅ missing frontmatter checks / `~/.dsh/skills` wizard |
-| Source tracking | ❌ | ✅ repo + commit, check/sync/trash (restores source & scene) |
-| Market | ❌ | ✅ built-in + custom repos, any top-level root, badges + update-all |
-| Stats | ❌ | ✅ call counts from session logs (14-day window, incremental cache) |
+Requires `Node ^22.19 || >=24` + dsh web (`0.1.2-alpha.5`, `0.1.x` forward compatible).
 
 ## Features
 
-- **Catalog** — search + source filter + flat/grouped in one row; groups = scenes (tags) + source collections; workspace tree merged by default.
-- **Switches** — per-skill and per-group toggles; conflict dialog (close all / keep on) → mixed state; only `~/.dsh/skills` & `~/.agents/skills` are writable.
-- **Reorder & edit** — drag handle on every group header (persists in `~/.dsh/dsh-skill-hub.json`); Edit toggle reveals reorder/delete without cluttering the read view.
-- **Market** — unified list (built-in Add → becomes source row); scan any root with `SKILL.md` (no allowlist), async import with `{jobId, totalBytes}` progress & cancel; Check all / Update all (failures non-fatal, daily auto-check).
-- **Stats** — per-skill `count` + `lastUsed`, group summaries; configurable window/interval live from the settings card.
+**Settings → 技能** — 3 tabs: **Sources** (skills, flat/grouped + project tree), **Scenes** (custom tag groups), **Market** (install + update).
 
-## Quick start
+- **Browse** — every root of the `ctx.skills` registry: project / user / bundled + third-party providers. Search across name, description, `displayName`; filter by source and invocation (model / user); sort by name, added time, or usage. Same-name skills from different sources get a duplicate badge instead of silently hiding.
+- **Toggle** — per-skill switches and per-group tri-state switches with a conflict dialog (close all / keep on). Disabling renames the discovery file (never deletes); disabled skills stay inspectable and re-enableable from their detail page. Only `~/.dsh/skills` & `~/.agents/skills` are writable; everything else is read-only.
+- **Organize** — scenes (tags) plus auto-aggregated source collections, all drag-reorderable and persisted in `~/.dsh/dsh-skill-hub.json`. Edit mode reveals delete/reorder without cluttering the read view.
+- **Diagnose & fix** — files the provider skips (missing frontmatter, bad YAML, name mismatch, short description) show up with reasons; auto-fixable ones (e.g. unquoted `:` in descriptions) get a one-click Fix button.
+- **Scaffold** — new-skill wizard writing to `~/.dsh/skills` or `~/.agents/skills` (`SKILL.md` template below).
+- **Market** — built-in curated repos plus custom `owner/repo` sources. Any top-level directory containing `SKILL.md` scans as a root (no allowlist). Async import with byte-level progress and cancel. Each source pins a version — click the ref badge to switch between releases, branches, or a custom ref.
+- **Track updates** — imported skills record a repo + commit snapshot. Check all / update-all, per-source badges (installed / updatable / deleted upstream / new release). Sync overwrites local edits (with confirm); upstream deletions move into a restorable trash that keeps source and scene membership.
+- **Stats** — per-skill call counts + last-used times from session logs (incremental cache), group summaries; window and scan interval live-configurable from the settings card.
+- **Settings card** — master switch, announce-to-agent, invocation dot colors, usage display toggles, stats window/interval; plus a self-update check against GitHub releases.
 
-```bash
-dsh plugin --profile web add dsh-skill-hub
-# restart dsh web → Settings → 技能 → Market → scan → import
-```
+## Why not just the read-only browser?
+
+[dsh-skill-manager](https://www.npmjs.com/package/dsh-skill-manager) browses, [dsh-skill-importer](https://github.com/saitamahang/dsh-skill-importer) / [dsh-find-skill](https://github.com/Moximxxx/dsh-find-skill) import. **This plugin manages.**
+
+| Capability | read-only browser | **dsh-skill-hub** |
+| --- | --- | --- |
+| Catalog | user roots, self-scanned | `ctx.skills` registry, all roots + third-party |
+| Toggle | ❌ | ✅ per-skill + per-group, never deletes |
+| Diagnostics | ❌ | ✅ reasons + one-click fix |
+| Market | ❌ | ✅ built-in + custom, version pins, update-all |
+| Source tracking | ❌ | ✅ check/sync/trash with restore |
+| Stats | ❌ | ✅ counts + last-used |
 
 Scaffold format (`SKILL.md`):
 
@@ -57,8 +64,6 @@ description: One line when the agent should use this skill.
 Body...
 ```
 
-Requires `Node ^22.19 || >=24` + dsh web (`0.1.0-rc.7` / `0.1.1-rc.2`, `0.1.x` forward compatible).
-
 ## How it works
 
 ```text
@@ -70,40 +75,25 @@ GitHub repo ──scan/import──▶ ~/.dsh/skills
                     /api/skill-hub/* ──▶ Panel (Settings → 技能)
 ```
 
-| File | Role |
-| --- | --- |
-| `src/index.ts` | inject `[webServer, skills, systemPrompt, settings]`, settings namespace, announcement |
-| `src/routes.ts` | `/api/skill-hub/*` fences + handlers (async import, reorder) |
-| `src/store.ts` | `~/.dsh/dsh-skill-hub.json` v4 (disabled/tags/sources/market/trash/stats/order) |
-| `src/repo.ts` | discovery / import / diff (any top-level `SKILL.md`) |
-| `src/skillfs.ts` | toggle/trash/scaffold/diagnostics |
-| `src/client/` | panel (`useSkillHub` + thin views), CSS Modules |
-
-Host uses only `ctx.skills.snapshot/get`, `ctx.webServer.register`, `ctx.systemPrompt.section`.
-
-## Usage
-
-**Settings → 技能** — 3 tabs: **Sources** (flat/grouped + project tree + drag), **Scenes** (tags, drag), **Market** (unified list). Header workspace field pins to one cwd; trash & diagnostics are always visible.
-
-**Settings → 插件 → Skill Hub** — master switch, announce to agent, dot colors, `showUseCount/showUseTime/showGroupSummary`, stats window (days, default 14, `0`=all) & interval (min, default 5).
+Host uses only `ctx.skills.snapshot/get`, `ctx.webServer.register`, `ctx.systemPrompt.section`. Loopback-only routes (`127.0.0.1`/`localhost`), JSON.
 
 ## HTTP API
 
-Loopback-only (`127.0.0.1`/`localhost`), JSON.
-
 | Endpoint | Method | Purpose |
 | --- | --- | --- |
-| `/api/skill-hub/catalog?cwd=` | GET | catalog + disabled + diagnostics |
-| `/api/skill-hub/skill?name=&cwd=` | GET | skill body |
+| `/api/skill-hub/catalog?cwd=` | GET | skills + disabled + diagnostics + duplicates |
+| `/api/skill-hub/skill?name=&cwd=` | GET | skill body (works for disabled too) |
 | `/api/skill-hub/skill/delete` | POST | move to trash (snapshots source+scenes) |
 | `/api/skill-hub/toggle` | POST | `{name, enabled}` |
 | `/api/skill-hub/toggle-batch` | POST | `{names, enabled}` |
 | `/api/skill-hub/create` | POST | `{name, description?, root?}` |
+| `/api/skill-hub/diagnostic/fix` | POST | `{path}` auto-fix frontmatter |
 | `/api/skill-hub/stats` | GET | invocation counts |
 | `/api/skill-hub/config` | GET/POST | runtime config (`null` clears) |
 | `/api/skill-hub/groups` | GET | tags + collections + orders |
-| `/api/skill-hub/tag` etc. | POST | create/rename, delete, set members, reorder (`/tag/reorder`, `/collections/reorder`, `/source-groups/reorder`) |
-| `/api/skill-hub/market` etc. | GET/POST | list/add/delete/pin/check/sync market sources |
+| `/api/skill-hub/tag` etc. | POST | create/rename, delete, set members, reorder |
+| `/api/skill-hub/market` etc. | GET/POST | list/add/delete/pin/check/sync sources |
+| `/api/skill-hub/market/source/versions?repo=` | GET | releases + branches for the version picker |
 | `/api/skill-hub/repo?repo=` | GET | discover (any root) |
 | `/api/skill-hub/repo/import` | POST | async job `{jobId, total, totalBytes}` |
 | `/api/skill-hub/repo/import/progress?jobId=` | GET | poll job |
@@ -115,16 +105,16 @@ Loopback-only (`127.0.0.1`/`localhost`), JSON.
 
 ```bash
 npm run typecheck  # tsc --noEmit
-npm test           # 174 tests, 9 suites
+npm test           # 176 tests, 9 suites
 npm run build      # tsc + tsdown → lib/index.js + lib/client.js
 ```
 
-> Don't run two `dsh web` on the same `$DSH_HOME` + cwd — rc has no session-log lock (`seq gap` corruption). Use separate `DSH_HOME`.
+> Don't run two `dsh web` on the same `$DSH_HOME` + cwd — no session-log lock (`seq gap` corruption). Use separate `DSH_HOME`.
 
 ## Troubleshooting
 
-- `duplicate loader entry id: skill-hub` — remove duplicate install (keep one `dsh plugin add` method).
-- Skill missing — check diagnostics (frontmatter / name mismatch / short description).
+- `duplicate loader entry id: skill-hub` — remove the duplicate install (keep one `dsh plugin add` method).
+- Skill missing — check the diagnostics section (frontmatter / name mismatch / short description).
 - Dots missing in `/` menu — dsh internals changed; catalog still works.
 
 ## Community

package/README.zh.md

@@ -13,38 +13,45 @@
   <img src="https://raw.githubusercontent.com/cheshireez/dsh-skill-hub/main/promo/real-skill-hub.png" alt="dsh-skill-hub 面板" width="640">
 </p>
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的图形化技能中枢 — 在 Web GUI 里浏览 `ctx.skills` 全量目录，开关技能、查看正文、诊断缺失、从市场安装、一键新建。
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的图形化技能中枢 — 在 Web GUI 里浏览 `ctx.skills` 全量目录，开关技能、查看正文、修复发现问题、从市场安装、一键新建。
 
 > 宿主只用官方 SDK，浏览器通过官方槽位渲染，不改 dsh 源码。
 
-## 为什么还需要一个管理器？
+## 快速开始
 
-[dsh-skill-manager](https://www.npmjs.com/package/dsh-skill-manager) 只读浏览，[dsh-skill-importer](https://github.com/saitamahang/dsh-skill-importer) / [dsh-find-skill](https://github.com/Moximxxx/dsh-find-skill) 只做导入。**本插件是可管理的全量目录。**
+```bash
+dsh plugin --profile web add dsh-skill-hub
+# 重启 dsh web → 设置 → 技能 → 市场 → 扫描 → 导入
+```
 
-| 能力 | 只读浏览器 | **dsh-skill-hub** |
-| --- | --- | --- |
-| 目录 | 自扫盘、仅用户根 | `ctx.skills`：项目/自定义/用户/内置 + 第三方 |
-| 工作区 | ❌ | ✅ `.dsh/skills` & `.agents/skills`（默认合并，只读） |
-| 开关 | ❌ | ✅ 重命名 `SKILL.md`（不删除），分组三态开关 + 拖拽排序 |
-| 诊断/新建 | ❌ | ✅ frontmatter 诊断 / `~/.dsh/skills` 向导 |
-| 来源跟踪 | ❌ | ✅ repo+commit，检查/同步/回收站（恢复保留来源与场景） |
-| 市场 | ❌ | ✅ 内置+自定义，任意顶层根目录，徽章+一键全更 |
-| 统计 | ❌ | ✅ 会话日志调用次数（14 天窗口，增量缓存） |
+要求 `Node ^22.19 || >=24` + dsh web（`0.1.2-alpha.5`，兼容后续 `0.1.x`）。
 
 ## 功能
 
-- **目录** — 搜索+来源筛选+平铺/分组一行完成；分组=场景（tag）+ 来源集合；工作区默认合并为项目树。
-- **开关** — 单技能/整组开关；冲突弹窗（全部关闭/保留开启→半开态）；仅 `~/.dsh/skills` & `~/.agents/skills` 可写。
-- **排序与编辑** — 分组头拖拽手柄（持久化到 `~/.dsh/dsh-skill-hub.json`）；编辑开关收敛排序/删除控件。
-- **市场** — 统一列表（内置 Add → 变来源行）；任意含 `SKILL.md` 的顶层目录视为根（无白名单），异步导入 `{jobId, totalBytes}` 轮询+取消；检查全部/全部更新（单源失败不影响全局，每日自动检查一次）。
-- **统计** — 每技能 `count` + `lastUsed`，分组头汇总；窗口/间隔在设置卡片实时可调。
+**设置 → 技能** — 3 个 tab：**来源**（技能，平铺/分组+项目树）、**场景**（自定义分组）、**市场**（安装与更新）。
 
-## 快速开始
+- **浏览** — `ctx.skills` 注册表全量：项目/用户/内置+第三方。按名称、描述、`displayName` 搜索；按来源、按调用方式（模型/用户）筛选；按名称/添加时间/调用次数排序。不同来源的同名技能挂重名徽标，不再静默隐藏。
+- **开关** — 单技能开关 + 整组三态开关，跨组冲突弹窗（全部关闭/保留开启）。禁用只重命名发现文件（不删除）；禁用的技能仍可查看正文、可一键重新启用。仅 `~/.dsh/skills` 与 `~/.agents/skills` 可写，其余只读。
+- **整理** — 场景（tag）+ 自动聚合的来源集合，全部可拖拽排序并持久化到 `~/.dsh/dsh-skill-hub.json`。编辑模式收敛删除/排序控件，阅读视图保持干净。
+- **诊断与修复** — provider 跳过的文件给出原因（缺 frontmatter、YAML 非法、名称不一致、描述过短）；可自动修复的（如描述里未加引号的 `:`）一键 Fix 落盘。
+- **新建** — 新技能向导，写入 `~/.dsh/skills` 或 `~/.agents/skills`（`SKILL.md` 模板见下）。
+- **市场** — 内置精选仓库 + 自定义 `owner/repo`。任何含 `SKILL.md` 的顶层目录都可扫描（无白名单）。异步导入，字节级进度+取消。每个源钉一个版本 —— 点 ref 徽标可在发布版/分支/手输之间切换。
+- **跟踪更新** — 导入的技能记录 repo+commit 快照。检查全部/一键全更；每源徽章（已装/可更新/上游已删/新版本）。同步覆盖本地修改（先确认）；上游删除跟进移入回收站，恢复保留来源与场景归属。
+- **统计** — 会话日志的调用次数+最近使用，分组头汇总；窗口与扫描间隔在设置卡片实时可调。
+- **设置卡片** — 总开关、向 Agent 公告、调用圆点颜色、用量显示开关、统计窗口/间隔；附带插件自更新检查（对 GitHub releases）。
 
-```bash
-dsh plugin --profile web add dsh-skill-hub
-# 重启 dsh web → 设置 → 技能 → 市场 → 扫描 → 导入
-```
+## 为什么还需要一个管理器？
+
+[dsh-skill-manager](https://www.npmjs.com/package/dsh-skill-manager) 只读浏览，[dsh-skill-importer](https://github.com/saitamahang/dsh-skill-importer) / [dsh-find-skill](https://github.com/Moximxxx/dsh-find-skill) 只做导入。**本插件负责管理。**
+
+| 能力 | 只读浏览器 | **dsh-skill-hub** |
+| --- | --- | --- |
+| 目录 | 自扫盘、仅用户根 | `ctx.skills` 全量+第三方 |
+| 开关 | ❌ | ✅ 单技能+整组，从不删除 |
+| 诊断 | ❌ | ✅ 原因+一键修复 |
+| 市场 | ❌ | ✅ 内置+自定义，版本钉选，一键全更 |
+| 来源跟踪 | ❌ | ✅ 检查/同步/回收站可恢复 |
+| 统计 | ❌ | ✅ 次数+最近使用 |
 
 `SKILL.md` 模板：
 
@@ -57,8 +64,6 @@ description: 一句话说明何时使用。
 正文...
 ```
 
-要求 `Node ^22.19 || >=24` + dsh web（`0.1.0-rc.7` / `0.1.1-rc.2`，兼容后续 `0.1.x`）。
-
 ## 工作原理
 
 ```text
@@ -70,40 +75,25 @@ GitHub 仓库 ──扫描/导入──▶ ~/.dsh/skills
                   /api/skill-hub/* ──▶ 面板（设置 → 技能）
 ```
 
-| 文件 | 职责 |
-| --- | --- |
-| `src/index.ts` | inject `[webServer, skills, systemPrompt, settings]`，设置命名空间，公告 |
-| `src/routes.ts` | `/api/skill-hub/*` 围栏+处理（异步导入、拖拽排序） |
-| `src/store.ts` | `~/.dsh/dsh-skill-hub.json` v4（禁用/tags/sources/market/trash/统计/排序） |
-| `src/repo.ts` | 发现/导入/比对（任意顶层 `SKILL.md`） |
-| `src/skillfs.ts` | 开关/回收站/脚手架/诊断 |
-| `src/client/` | 面板（`useSkillHub` + 薄视图），CSS Modules |
-
-宿主仅用 `ctx.skills.snapshot/get`、`ctx.webServer.register`、`ctx.systemPrompt.section`。
-
-## 使用
-
-**设置 → 技能** — 三个 tab：**来源**（平铺/分组+项目树+拖拽）、**场景**（tag，分组开关+拖拽）、**市场**（统一列表）。顶部工作区路径可固定到单个 cwd；回收站与诊断常驻。
-
-**设置 → 插件 → Skill Hub** — 总开关、向 Agent 公告、圆点颜色、`show*` 三开关、统计窗口（天，默认 14，`0`=全部）与间隔（分钟，默认 5）。
+宿主仅用 `ctx.skills.snapshot/get`、`ctx.webServer.register`、`ctx.systemPrompt.section`。路由仅回环（`127.0.0.1`/`localhost`），JSON。
 
 ## HTTP API
 
-仅回环（`127.0.0.1`/`localhost`），JSON。
-
 | 端点 | 方法 | 用途 |
 | --- | --- | --- |
-| `/api/skill-hub/catalog?cwd=` | GET | 目录+禁用+诊断 |
-| `/api/skill-hub/skill?name=&cwd=` | GET | 技能正文 |
+| `/api/skill-hub/catalog?cwd=` | GET | 技能+禁用+诊断+重名 |
+| `/api/skill-hub/skill?name=&cwd=` | GET | 技能正文（禁用的也可） |
 | `/api/skill-hub/skill/delete` | POST | 移入回收站（快照来源+场景） |
 | `/api/skill-hub/toggle` | POST | `{name, enabled}` |
 | `/api/skill-hub/toggle-batch` | POST | `{names, enabled}` |
 | `/api/skill-hub/create` | POST | `{name, description?, root?}` |
+| `/api/skill-hub/diagnostic/fix` | POST | `{path}` 自动修 frontmatter |
 | `/api/skill-hub/stats` | GET | 调用次数 |
 | `/api/skill-hub/config` | GET/POST | 运行时配置（`null` 清除） |
 | `/api/skill-hub/groups` | GET | tags+集合+排序 |
-| `/api/skill-hub/tag` 等 | POST | 新建/重命名、删除、设成员、排序（`/tag/reorder`、`/collections/reorder`、`/source-groups/reorder`） |
+| `/api/skill-hub/tag` 等 | POST | 新建/重命名、删除、设成员、排序 |
 | `/api/skill-hub/market` 等 | GET/POST | 市场源 列表/添加/删除/钉 ref/检查/同步 |
+| `/api/skill-hub/market/source/versions?repo=` | GET | 版本选择器的 releases+branches |
 | `/api/skill-hub/repo?repo=` | GET | 发现（任意根） |
 | `/api/skill-hub/repo/import` | POST | 异步任务 `{jobId, total, totalBytes}` |
 | `/api/skill-hub/repo/import/progress?jobId=` | GET | 轮询进度 |
@@ -115,16 +105,16 @@ GitHub 仓库 ──扫描/导入──▶ ~/.dsh/skills
 
 ```bash
 npm run typecheck  # tsc --noEmit
-npm test           # 174 tests, 9 suites
+npm test           # 176 tests, 9 suites
 npm run build      # tsc + tsdown → lib/index.js + lib/client.js
 ```
 
-> 同一 `$DSH_HOME` + cwd 下勿开两个 `dsh web` — rc 无会话日志锁，会 `seq gap` 损坏。换 `DSH_HOME` 或先关旧实例。
+> 同一 `$DSH_HOME` + cwd 下勿开两个 `dsh web` — 无会话日志锁，会 `seq gap` 损坏。换 `DSH_HOME` 或先关旧实例。
 
 ## 故障排查
 
 - `duplicate loader entry id: skill-hub` — 删掉重复安装（只留一种 `dsh plugin add`）。
-- 技能不出现 — 看诊断（缺 frontmatter / 名称不一致 / 描述过短）。
+- 技能不出现 — 看诊断区（缺 frontmatter / 名称不一致 / 描述过短）。
 - `/` 菜单圆点消失 — dsh 内部触发源变更，目录功能不受影响。
 
 ## 社区