dsh-skill-hub 0.3.14 → 0.3.15

package/CONTRIBUTING.md

@@ -39,7 +39,7 @@ src/client/locales/     dictionaries by view (common/skills/market/sources/detai
 ```bash
 npm install
 npm run typecheck   # tsc --noEmit
-npm test            # vitest (233 tests across 14 suites)
+npm test            # vitest (255 tests across 14 suites)
 npm run build       # tsc declarations + tsdown bundles (lib/index.js + lib/client.js)
 ```
 
@@ -53,8 +53,8 @@ npm run build       # tsc declarations + tsdown bundles (lib/index.js + lib/clie
    live GUI.
 3. **Build** — `npm run build` must produce `lib/index.js` and `lib/client.js`.
 4. **Keep the diff focused** — one logical change per PR, with a clear title and description.
-5. **Documentation** — update `README.md` (including the embedded Chinese collapsible section) when
-   behavior or the API surface changes.
+5. **Documentation** — update `README.md` **and** `README.zh.md` (both ship with the package and are
+   kept in sync) when behavior or the API surface changes.
 
 ## Code style
 
@@ -68,7 +68,9 @@ npm run build       # tsc declarations + tsdown bundles (lib/index.js + lib/clie
 ```bash
 # after a change:
 npm run build
-# restart the dsh web process, then verify Settings → 技能 and Settings → 插件 → Skill Hub
+# restart the dsh web process, then verify both surfaces:
+#   Settings → 技能              — the skill hub panel
+#   sidebar 插件 → dsh-skill-hub  — the plugin's settings card
 ```
 
 When the web profile installs this repo as a link (`"dsh-skill-hub": "link:/path/to/repo"`, the

package/README.md

@@ -24,7 +24,9 @@ dsh plugin --profile web add dsh-skill-hub
 # restart dsh web → Settings → 技能 → Market → scan → import
 ```
 
-Requires `Node ^22.19 || >=24` + dsh web `>=0.1.6-alpha.2 <0.2`.
+Requires `Node ^22.19 || >=24` + dsh web `>=0.1.7-alpha.1 <0.2`.
+
+Two surfaces — the hub panel lives at **Settings → 技能**, and this plugin's own configuration card sits on the plugin's page in the **Plugins manager** (sidebar → 插件 → dsh-skill-hub). The card is registered by the plugin itself into the `plugins.bundle.config` slot — dsh has no auto-generated config page — and covers the master switch, announce-to-agent, dot colors, usage display and the stats window/interval.
 
 ## Features
 
@@ -35,10 +37,10 @@ Requires `Node ^22.19 || >=24` + dsh web `>=0.1.6-alpha.2 <0.2`.
 - **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.
+- **Market** — built-in curated repos plus custom `owner/repo` sources. Any top-level directory containing `SKILL.md` scans as a root (no allowlist), and a `SKILL.md` at the repo root itself scans as a single skill named after the repo (minus repo tooling such as `.github/`). 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.
+- **Settings card** — registered on the plugin's own page in the **Plugins manager** (sidebar → 插件 → dsh-skill-hub; collapsed until you expand the title): master switch, announce-to-agent, invocation dot colors, usage display toggles, stats window/interval.
 
 ## Why not just the read-only browser?
 
@@ -92,7 +94,7 @@ Host uses only `ctx.skills.snapshot/get`, `ctx.webServer.register`, `ctx.systemP
 | `/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 |
-| `/api/skill-hub/market` etc. | GET/POST | list/add/delete/pin/check/sync sources |
+| `/api/skill-hub/market` etc. | GET/POST | list/add/delete/pin sources; `…/source/check` + `…/source/sync` update them |
 | `/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}` |
@@ -100,12 +102,13 @@ Host uses only `ctx.skills.snapshot/get`, `ctx.webServer.register`, `ctx.systemP
 | `/api/skill-hub/repo/import/cancel` | POST | cancel job |
 | `/api/skill-hub/sources` etc. | GET/POST | list/check/sync/delete/restore/clear trash |
 | `/api/skill-hub/update` | GET | plugin latest release |
+| unknown `/api/skill-hub/*` | GET/POST | `404 {error}` naming the path — a typo must not read as an auth failure (the SPA fallback answers 401 for `/api/*` it does not own) |
 
 ## Development
 
 ```bash
 npm run typecheck  # tsc --noEmit
-npm test           # 176 tests, 9 suites
+npm test           # 255 tests, 14 suites
 npm run build      # tsc + tsdown → lib/index.js + lib/client.js
 ```
 
@@ -117,6 +120,7 @@ npm run build      # tsc + tsdown → lib/index.js + lib/client.js
 - Skill missing — check the diagnostics section (frontmatter / name mismatch / short description).
 - Empty source group — its skills were deleted, or their disabled records were lost (sidecar restored/hand-edited). Startup reconciles `.disabled` files on disk; source groups with no visible member are no longer rendered.
 - Dots missing in `/` menu — dsh internals changed; catalog still works.
+- Settings card missing — open the plugin in the Plugins manager (sidebar → 插件 → dsh-skill-hub) and expand the 「技能中枢」 card at the top of the page (collapsed by default). On dsh older than `0.1.7-alpha.1` this plugin does not load at all (the settings API it targets does not exist there).
 
 ## Community
 

package/README.zh.md

@@ -24,7 +24,9 @@ dsh plugin --profile web add dsh-skill-hub
 # 重启 dsh web → 设置 → 技能 → 市场 → 扫描 → 导入
 ```
 
-要求 `Node ^22.19 || >=24` + dsh web `>=0.1.6-alpha.2 <0.2`。
+要求 `Node ^22.19 || >=24` + dsh web `>=0.1.7-alpha.1 <0.2`。
+
+两个界面 —— 管理面板在 **设置 → 技能**；本插件自身的配置卡片在 **插件管理页** 的插件自有页面上（侧边栏「插件」→ dsh-skill-hub）。该卡片由本插件自己注册进 `plugins.bundle.config` 槽位（dsh 没有自动生成的配置页），覆盖总开关、向 Agent 公告、圆点颜色、用量显示与统计窗口/间隔。
 
 ## 功能
 
@@ -35,10 +37,10 @@ dsh plugin --profile web add dsh-skill-hub
 - **整理** — 场景（tag）+ 自动聚合的来源集合，全部可拖拽排序并持久化到 `~/.dsh/dsh-skill-hub.json`。编辑模式收敛删除/排序控件，阅读视图保持干净。
 - **诊断与修复** — provider 跳过的文件给出原因（缺 frontmatter、YAML 非法、名称不一致、描述过短）；可自动修复的（如描述里未加引号的 `:`）一键 Fix 落盘。
 - **新建** — 新技能向导，写入 `~/.dsh/skills` 或 `~/.agents/skills`（`SKILL.md` 模板见下）。
-- **市场** — 内置精选仓库 + 自定义 `owner/repo`。任何含 `SKILL.md` 的顶层目录都可扫描（无白名单）。异步导入，字节级进度+取消。每个源钉一个版本 —— 点 ref 徽标可在发布版/分支/手输之间切换。
+- **市场** — 内置精选仓库 + 自定义 `owner/repo`。任何含 `SKILL.md` 的顶层目录都可扫描（无白名单）；`SKILL.md` 直接放在仓库根时，整个仓库算一个技能，技能名取仓库名（`.github/` 等仓库基建不计入）。异步导入，字节级进度+取消。每个源钉一个版本 —— 点 ref 徽标可在发布版/分支/手输之间切换。
 - **跟踪更新** — 导入的技能记录 repo+commit 快照。检查全部/一键全更；每源徽章（已装/可更新/上游已删/新版本）。同步覆盖本地修改（先确认）；上游删除跟进移入回收站，恢复保留来源与场景归属。
 - **统计** — 会话日志的调用次数+最近使用，分组头汇总；窗口与扫描间隔在设置卡片实时可调。
-- **设置卡片** — 总开关、向 Agent 公告、调用圆点颜色、用量显示开关、统计窗口/间隔；附带插件自更新检查（对 GitHub releases）。
+- **设置卡片** — 注册在 **插件管理页** 的插件自有页面上（侧边栏「插件」→ dsh-skill-hub，默认折叠，点标题展开）：总开关、向 Agent 公告、调用圆点颜色、用量显示开关、统计窗口/间隔。
 
 ## 为什么还需要一个管理器？
 
@@ -92,7 +94,7 @@ GitHub 仓库 ──扫描/导入──▶ ~/.dsh/skills
 | `/api/skill-hub/config` | GET/POST | 运行时配置（`null` 清除） |
 | `/api/skill-hub/groups` | GET | tags+集合+排序 |
 | `/api/skill-hub/tag` 等 | POST | 新建/重命名、删除、设成员、排序 |
-| `/api/skill-hub/market` 等 | GET/POST | 市场源 列表/添加/删除/钉 ref/检查/同步 |
+| `/api/skill-hub/market` 等 | GET/POST | 市场源 列表/添加/删除/钉 ref；`…/source/check` + `…/source/sync` 检查与同步 |
 | `/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}` |
@@ -100,12 +102,13 @@ GitHub 仓库 ──扫描/导入──▶ ~/.dsh/skills
 | `/api/skill-hub/repo/import/cancel` | POST | 取消任务 |
 | `/api/skill-hub/sources` 等 | GET/POST | 来源 列表/检查/同步/删除/恢复/清空回收站 |
 | `/api/skill-hub/update` | GET | 插件最新发布 |
+| 未知的 `/api/skill-hub/*` | GET/POST | `404 {error}` 且写明路径 —— 拼错路径不该被读成鉴权失败（宿主 SPA fallback 对自己不拥有的 `/api/*` 一律回 401） |
 
 ## 开发
 
 ```bash
 npm run typecheck  # tsc --noEmit
-npm test           # 176 tests, 9 suites
+npm test           # 255 tests, 14 suites
 npm run build      # tsc + tsdown → lib/index.js + lib/client.js
 ```
 
@@ -117,6 +120,7 @@ npm run build      # tsc + tsdown → lib/index.js + lib/client.js
 - 技能不出现 — 看诊断区（缺 frontmatter / 名称不一致 / 描述过短）。
 - 来源组空壳 — 组内技能已被删除、或禁用记录丢失（状态文件被恢复/手改）。启动时自动对账磁盘上的 `.disabled` 文件补记录；无可见成员的来源组不再渲染。
 - `/` 菜单圆点消失 — dsh 内部触发源变更，目录功能不受影响。
+- 找不到配置卡片 — 在插件管理页打开本插件（侧边栏「插件」→ dsh-skill-hub），展开页面顶部的「技能中枢」卡片（默认折叠）。dsh 低于 `0.1.7-alpha.1` 时本插件无法加载（它所用的 settings API 在旧版不存在）。
 
 ## 社区
 

package/lib/client.js

@@ -7,7 +7,13 @@ window.__ModuleLoader__.load({
 		let react = require("react");
 		let react_jsx_runtime = require("react/jsx-runtime");
 		//#region src/protocol/api.ts
-		/** Browser-facing base paths of the skill-hub API family. */
+		/**
+		* Browser-facing base paths of the skill-hub API family.
+		*
+		* Naming rule: a path's segments mirror its scope. Market sources own the
+		* `/market/source/*` subtree — add, delete, ref, versions, check, sync — so
+		* the update check and the sync that acts on its result sit side by side.
+		*/
 		const SKILL_HUB_API = {
 			catalog: "/api/skill-hub/catalog",
 			skill: "/api/skill-hub/skill",
@@ -21,7 +27,7 @@ window.__ModuleLoader__.load({
 			marketSource: "/api/skill-hub/market/source",
 			marketSourceDelete: "/api/skill-hub/market/source/delete",
 			marketSourceRef: "/api/skill-hub/market/source/ref",
-			marketCheck: "/api/skill-hub/market/check",
+			marketCheck: "/api/skill-hub/market/source/check",
 			marketSync: "/api/skill-hub/market/source/sync",
 			repo: "/api/skill-hub/repo",
 			repoImport: "/api/skill-hub/repo/import",
@@ -46,6 +52,16 @@ window.__ModuleLoader__.load({
 			marketStats: "/api/skill-hub/market/stats"
 		};
 		//#endregion
+		//#region src/protocol/config.ts
+		/**
+		* This plugin's Loader entry id — the settings namespace dsh serves its config
+		* under. It is cordis.patch.yml's insert id, NOT the package name, and it is
+		* shared by contract because the browser half addresses the same form through
+		* `ctx.configForms.get(HUB_ENTRY_ID)` while the host half writes through
+		* `ctx.settings.update(HUB_ENTRY_ID, …)`.
+		*/
+		const HUB_ENTRY_ID = "skill-hub";
+		//#endregion
 		//#region src/protocol/sources.ts
 		/** 项目级技能来源（它们有 workspace 归属，不属于「个人」组）。 */
 		function isProjectSource(source) {
@@ -480,6 +496,7 @@ window.__ModuleLoader__.load({
 			"repo.cancel": "取消",
 			"repo.cancelled": "已取消 · 已导入 {imported}/{total} 已保留，临时文件已清理",
 			"repo.importingCurrent": "正在导入: {name} ({done}/{total})",
+			"repo.root.self": "仓库根",
 			"repo.root.skills": "skills",
 			"repo.root.designTemplates": "design-templates",
 			"repo.root.generic": "{root}"
@@ -559,6 +576,7 @@ window.__ModuleLoader__.load({
 			"repo.cancel": "Cancel",
 			"repo.cancelled": "Cancelled · {imported}/{total} kept, temp files cleaned",
 			"repo.importingCurrent": "Importing: {name} ({done}/{total})",
+			"repo.root.self": "Repo root",
 			"repo.root.skills": "Skills",
 			"repo.root.designTemplates": "Templates",
 			"repo.root.generic": "{root}"
@@ -3836,7 +3854,7 @@ window.__ModuleLoader__.load({
 			const visible = visibleCollections(groupsState?.collections ?? [], sourceFiltered, catalog?.disabled ?? [], normalized, sourceFilter, origins);
 			const collections = visible.map((entry) => entry.collection);
 			const uncategorized = sourceFiltered.filter((skill) => origins[skill.name] === void 0 && !isProjectSource(skill.source));
-			const personalDisabled = (catalog?.disabled ?? []).filter((record) => origins[record.name] === void 0).filter((record) => normalized.length === 0 || record.name.toLocaleLowerCase().includes(normalized) || record.description.toLocaleLowerCase().includes(normalized)).filter((record) => sourceFilter === "all" || sourceFilter === "private");
+			const personalDisabled = (catalog?.disabled ?? []).filter((record) => origins[record.name] === void 0).filter((record) => normalized.length === 0 || record.name.toLocaleLowerCase().includes(normalized) || record.description.toLocaleLowerCase().includes(normalized)).filter(() => sourceFilter === "all" || sourceFilter === "private");
 			const allPersonalNames = [...uncategorized.map((s) => s.name), ...personalDisabled.map((r) => r.name)];
 			const hasPersonal = allPersonalNames.length > 0;
 			const defaultTopKeys = [
@@ -4737,8 +4755,11 @@ window.__ModuleLoader__.load({
 		/**
 		* 已知技能根的显示名键；未知根直接显示目录名。
 		* zh 字典里这两项就是目录名本身（与接线前的硬编码文本一致）。
+		* 空串是「技能就在仓库根」的哨兵根（host 侧 REPO_ROOT），目录名无从显示，
+		* 给它一个可读标签，否则筛选按钮会是一片空白。
 		*/
 		function rootLabelKey(root) {
+			if (root === "") return "repo.root.self";
 			if (root === "skills") return "repo.root.skills";
 			if (root === "design-templates") return "repo.root.designTemplates";
 			return "repo.root.generic";
@@ -4899,7 +4920,7 @@ window.__ModuleLoader__.load({
 														" ",
 														counts.get(root) ?? 0
 													]
-												}, root))
+												}, root === "" ? "repo-root" : root))
 											]
 										});
 									})(),
@@ -4989,7 +5010,7 @@ window.__ModuleLoader__.load({
 														}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 															className: panel_module_css_default.rowDesc,
 															children: [
-																entry.dir,
+																entry.dir === "" ? tt("repo.root.self") : entry.dir,
 																" · ",
 																tt("repo.files", {
 																	count: entry.fileCount,
@@ -6917,7 +6938,7 @@ window.__ModuleLoader__.load({
 			const [workspaceDraft, setWorkspaceDraft] = (0, react.useState)("");
 			/** 「筛选」面板开合（来源 + 调用方式收进这里；搜索/排序/视图切换始终可见）。 */
 			const [filtersOpen, setFiltersOpen] = (0, react.useState)(false);
-			const { catalog, loading, loadError, successBanner, updateState, detail, detailLoading, showForm, formName, formDesc, formRoot, formBusy, formMessage, hubConfig, tab, skillView, sourceFilter, sortKey, search, workspace, setWorkspace, sourcesState, tagBusy, batchBusy, busyNames, normalized, origins, sourceOptions, filtered, conflictDialog, confirmDialog, deleteSkillDialog, deleteGroupDialog, confirmClearTrash, branchChoice, branchBusy, marketSyncDialog, syncBusy, editingTag, editName, membersDraft, editSearch, uses, groupsState, sourceCheck, checkingSource, syncingSource, showLegend, editMode, setLoadError, setSuccessBanner, setDetail, setShowForm, setFormName, setFormDesc, setFormRoot, setFormMessage, setTab, setSkillView, setSourceFilter, setSortKey, setSearch, setConflictDialog, setConfirmDialog, setDeleteSkillDialog, setDeleteGroupDialog, setConfirmClearTrash, setBranchChoice, setMarketSyncDialog, setEditingTag, setEditName, setMembersDraft, setEditSearch, setShowLegend, setEditMode, checkUpdate, loadMarket, checkSources, requestSync, requestDelete, restoreTrash, clearTrash, runDeleteSkill, runDeleteGroup, runConfirmed, resolveConflict, confirmBranchChoice, confirmMarketSync, create, saveTag, deleteTag, enableDisabled } = hub;
+			const { catalog, loading, loadError, successBanner, updateState, detail, detailLoading, showForm, formName, formDesc, formRoot, formBusy, formMessage, hubConfig, tab, skillView, sourceFilter, sortKey, search, workspace, setWorkspace, sourcesState, tagBusy, batchBusy, sourceOptions, filtered, conflictDialog, confirmDialog, deleteSkillDialog, deleteGroupDialog, confirmClearTrash, branchChoice, branchBusy, marketSyncDialog, syncBusy, editingTag, editName, membersDraft, editSearch, uses, groupsState, sourceCheck, checkingSource, syncingSource, showLegend, editMode, setLoadError, setSuccessBanner, setDetail, setShowForm, setFormName, setFormDesc, setFormRoot, setFormMessage, setTab, setSkillView, setSourceFilter, setSortKey, setSearch, setConflictDialog, setConfirmDialog, setDeleteSkillDialog, setDeleteGroupDialog, setConfirmClearTrash, setBranchChoice, setMarketSyncDialog, setEditingTag, setEditName, setMembersDraft, setEditSearch, setShowLegend, setEditMode, checkUpdate, loadMarket, checkSources, requestSync, requestDelete, restoreTrash, clearTrash, runDeleteSkill, runDeleteGroup, runConfirmed, resolveConflict, confirmBranchChoice, confirmMarketSync, create, saveTag, deleteTag, enableDisabled } = hub;
 			const { shortenedCount, fixingPaths, clearListFilters } = hub;
 			if (detail !== null) {
 				const disabledRecord = catalog?.disabled.find((record) => record.name === detail.name);
@@ -7564,16 +7585,16 @@ window.__ModuleLoader__.load({
 		/**
 		* Required services (fiber inject waiting — the runtime must be up first).
 		* `connection`/`remote` are the settings transport's own prerequisites
-		* (`ctx.settingsScope.bind` resolves them on the caller's fiber), and
-		* `settingsScope` is the namespace-scope binder itself; mirror the official
-		* settings-plugins inject list.
+		* (`ctx.configForms.get` resolves them on the caller's fiber), and
+		* `configForms` is the shared settings-form service itself; mirror the
+		* official settings-plugins inject list.
 		*/
 		const inject = [
 			"slots",
 			"locale",
 			"connection",
 			"remote",
-			"settingsScope",
+			"configForms",
 			"inputTriggers"
 		];
 		/**
@@ -7587,7 +7608,7 @@ window.__ModuleLoader__.load({
 			}), "dsh-skill-hub: dictionaries");
 			const t = ctx.locale.bind(NS);
 			const api = new SkillHubApi();
-			const scope = ctx.settingsScope.bind({ namespace: NS });
+			const scope = ctx.configForms.get(HUB_ENTRY_ID);
 			const settingsCard = new SkillHubSettingsCardController(scope);
 			ctx.effect(() => setupSkillSlashDots(ctx, api, scope), "dsh-skill-hub: slash dots");
 			ctx.effect(() => ctx.slots.inject("plugins.bundle.config", () => ctx.slots.register({