dsh-skill-hub 0.3.13 → 0.3.15

package/lib/index.js

@@ -1,13 +1,33 @@
 import { createRequire } from "node:module";
-import z from "schemastery";
+import z from "@deepseek-ai/schemastery";
 import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
-import { dump, load } from "js-yaml";
 import { isSkillName } from "@deepseek-ai/dsh-skill";
+import { dump, load } from "js-yaml";
 import { randomUUID } from "node:crypto";
 //#region src/protocol/api.ts
-/** Browser-facing base paths of the skill-hub API family. */
+/**
+* Root path of the skill-hub API family. The host also registers this as its
+* 404 catch-all prefix, so a mistyped path answers with a plain 404 naming the
+* path instead of falling through to the SPA fallback (which answers 401 and
+* reads like an auth problem).
+*/
+const SKILL_HUB_API_ROOT = "/api/skill-hub";
+/**
+* Deprecated path of the market update check, kept routable for one release
+* after the naming unification below. A browser tab that loaded the previous
+* client bundle keeps calling it until it reloads; delete this (and its route
+* in routes/market.ts) in the next minor.
+*/
+const SKILL_HUB_API_DEPRECATED_MARKET_CHECK = "/api/skill-hub/market/check";
+/**
+* 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 +41,7 @@ const SKILL_HUB_API = {
 	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",
@@ -48,6 +68,14 @@ const SKILL_HUB_API = {
 //#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";
+/**
 * Hub config defaults — the single source every layer reads: the cordis
 * schema (index.ts), the host's saved-override merge, and the routes'
 * fallback view. Changing a default here changes all three.
@@ -92,6 +120,16 @@ function clampNumber(value, min) {
 	if (typeof value !== "number" || !Number.isFinite(value) || value < min) return void 0;
 	return Math.floor(value);
 }
+/**
+* Drop the GitHub token from a config-shaped object. Returns a copy, so the
+* caller's own config layer keeps the token. Shared by the config route's GET
+* and POST responses — neither may echo it back.
+*/
+function redactGithubToken(value) {
+	const copy = { ...value };
+	delete copy.githubToken;
+	return copy;
+}
 /** HEX color validation shared by host routes and the settings card. */
 const HEX_COLOR_RE = /^#[0-9a-f]{6}$/i;
 /** GitHub token validation shared by host routes and the settings card. */
@@ -177,6 +215,18 @@ var StoreError = class extends Error {
 	}
 };
 //#endregion
+//#region src/protocol/repo.ts
+/** Top-level directory pattern for a skill root: visible, non-dot, safe chars. First char must be alphanum. */
+const REPO_ROOT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/**
+* True when a value is a usable root: a visible safe top-level directory name,
+* or the empty string for the repo root. Guards the persisted store against
+* corrupt roots without rewriting the repo-root sentinel.
+*/
+function isValidRepoRoot(value) {
+	return typeof value === "string" && (value === "" || REPO_ROOT_RE.test(value));
+}
+//#endregion
 //#region src/store/migrate.ts
 /**
 * Normalize an arbitrary parsed sidecar document to the current schema.
@@ -269,7 +319,7 @@ function hydrateMigratedState(migrated) {
 		const source = entry;
 		if (source !== null && typeof source === "object" && typeof source.repo === "string" && source.repo !== "" && Array.isArray(source.skills)) {
 			const manifest = source.manifest;
-			const rawRoot = typeof source.root === "string" && source.root !== "" && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(source.root) ? source.root : "skills";
+			const rawRoot = isValidRepoRoot(source.root) ? source.root : "skills";
 			sourcesByRepo.set(source.repo, {
 				repo: source.repo,
 				...typeof source.ref === "string" && source.ref !== "" ? { ref: source.ref } : {},
@@ -300,7 +350,7 @@ function hydrateMigratedState(migrated) {
 				path: item.path,
 				movedAt: typeof item.movedAt === "number" ? item.movedAt : 0,
 				...typeof item.sourcePath === "string" && item.sourcePath !== "" ? { sourcePath: item.sourcePath } : {},
-				...origin !== null && typeof origin === "object" && typeof origin.repo === "string" && origin.repo !== "" && typeof origin.root === "string" && origin.root !== "" && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(origin.root) ? { origin: {
+				...origin !== null && typeof origin === "object" && typeof origin.repo === "string" && origin.repo !== "" && isValidRepoRoot(origin.root) ? { origin: {
 					repo: origin.repo,
 					root: origin.root,
 					...typeof origin.ref === "string" && origin.ref !== "" ? { ref: origin.ref } : {},
@@ -393,6 +443,250 @@ function hydrateMigratedState(migrated) {
 		sourceGroupOrder
 	};
 }
+/** True when a root denotes the repo root itself (the repo is the skill dir). */
+function isRepoRoot(root) {
+	return root === "";
+}
+/**
+* The tree prefix delimiting a skill directory: empty for the repo-root skill
+* (it owns the whole tree), otherwise `<dir>/`. Single source for collect,
+* manifest, diff and the store's baseline cleanup, so they can never disagree.
+*/
+function skillDirPrefix(dir) {
+	return isRepoRoot(dir) ? "" : dir + "/";
+}
+/**
+* A path inside a skill directory, as it appears in the repo tree. Both
+* directions of this mapping matter: repo paths are always '/'-joined (never
+* node:path's OS separator, these are GitHub paths shown in the UI), and the
+* repo-root case must not grow a leading slash.
+*/
+function skillPathIn(dir, relative) {
+	return skillDirPrefix(dir) + relative;
+}
+/** The SKILL.md path inside a skill directory. */
+function skillFileAt(dir) {
+	return skillPathIn(dir, "SKILL.md");
+}
+/**
+* Top-level dot entries are repo tooling, never part of a skill: `.github/`,
+* `.claude-plugin/`, `.gitignore`. Only the repo-root skill can reach them,
+* since its prefix is empty and would otherwise sweep in the whole repo.
+* Nested skill dirs cannot start with a dot (ROOT_RE), so this is a no-op
+* for them.
+*/
+function isRepoTooling(path) {
+	return path.startsWith(".");
+}
+/** Every tree blob belonging to a skill directory, sorted by path. */
+function skillTreeFiles(tree, dir) {
+	const prefix = skillDirPrefix(dir);
+	return tree.filter((item) => item.type === "blob" && item.path.startsWith(prefix) && !isRepoTooling(item.path)).map((item) => ({
+		path: item.path,
+		size: typeof item.size === "number" ? item.size : 0
+	})).sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+* A repo file's path relative to its skill directory — the path it is written
+* to under the skill's own directory. `dir === ''` means the repo file path
+* *is* the relative path; slicing `dir.length + 1` would eat its first
+* character.
+*/
+function relativeToSkillDir(dir, path) {
+	return isRepoRoot(dir) ? path : path.slice(dir.length + 1);
+}
+/** `owner/repo` slug for a parsed reference. */
+function repoSlug(ref) {
+	return `${ref.owner}/${ref.repo}`;
+}
+/**
+* Normalize a GitHub URL or `owner/repo`/`owner/repo@ref` input.
+* Only github.com URLs are accepted in v1.
+*/
+function normalizeRepoInput(input) {
+	let value = input.trim();
+	if (value === "") return null;
+	let ref;
+	const urlMatch = /^https?:\/\/github\.com\/([^/]+)\/([^/#?@]+)(?:\/tree\/([^/?#]+))?/.exec(value);
+	if (urlMatch !== null) {
+		value = `${urlMatch[1]}/${urlMatch[2]}`;
+		ref = urlMatch[3];
+	} else {
+		if (/^https?:\/\//.test(value)) return null;
+		const at = value.indexOf("@");
+		if (at !== -1) {
+			ref = value.slice(at + 1).trim();
+			value = value.slice(0, at).trim();
+		}
+	}
+	value = value.replace(/\.git$/, "").replace(/\/+$/, "");
+	const parts = value.split("/").filter(Boolean);
+	if (parts.length < 2) return null;
+	const owner = parts[0];
+	const repo = parts[1];
+	if (owner === "" || repo === "" || owner.includes("..") || repo.includes("..")) return null;
+	return {
+		owner,
+		repo,
+		...ref !== void 0 && ref !== "" ? { ref } : {}
+	};
+}
+/** Collect every file inside a skill directory, including SKILL.md itself. */
+function collectRepoSkillFiles(tree, dir) {
+	return skillTreeFiles(tree, dir);
+}
+/**
+* Compute an origin collection name. Multiple roots split by root, one root
+* keeps the repo slug. The repo-root skill's name *is* the repo slug, so it
+* never gets a trailing-slash suffix (`owner/repo/`).
+*/
+function originForRoot(repo, rootsPresent, root) {
+	if (rootsPresent.size <= 1) return repo;
+	return isRepoRoot(root) ? repo : `${repo}/${root}`;
+}
+/** Discover importable skills from a repo tree. Invalid names are ignored. Roots are auto-derived from the top-level directory of each SKILL.md. */
+function discoverRepoEntries(tree, repo, existingNames = /* @__PURE__ */ new Set()) {
+	const candidates = [];
+	const rootsPresent = /* @__PURE__ */ new Set();
+	const repoName = repo.slice(repo.lastIndexOf("/") + 1);
+	if (isSkillName(repoName) && tree.some((item) => item.type === "blob" && item.path === "SKILL.md")) {
+		rootsPresent.add("");
+		candidates.push({
+			root: "",
+			dir: "",
+			name: repoName,
+			path: "SKILL.md"
+		});
+	}
+	for (const item of tree) {
+		if (item.type !== "blob") continue;
+		const slash = item.path.indexOf("/");
+		if (slash === -1) continue;
+		if (!item.path.endsWith("/SKILL.md")) continue;
+		const root = item.path.slice(0, slash);
+		if (!REPO_ROOT_RE.test(root)) continue;
+		const dir = item.path.slice(0, -9);
+		if (dir === root || dir.length <= root.length + 1) continue;
+		const name = dir.slice(dir.lastIndexOf("/") + 1);
+		if (!isSkillName(name)) continue;
+		rootsPresent.add(root);
+		candidates.push({
+			root,
+			dir,
+			name,
+			path: item.path
+		});
+	}
+	return candidates.map((candidate) => {
+		const files = collectRepoSkillFiles(tree, candidate.dir);
+		return {
+			name: candidate.name,
+			dir: candidate.dir,
+			path: candidate.path,
+			root: candidate.root,
+			origin: originForRoot(repo, rootsPresent, candidate.root),
+			fileCount: files.length,
+			totalBytes: files.reduce((sum, file) => sum + file.size, 0),
+			existing: existingNames.has(candidate.name)
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* Build a path→size manifest for one skill directory from a repo tree.
+* Shares `skillTreeFiles` with collectRepoSkillFiles: a manifest that
+* disagreed with the collected file set would make every update diff report
+* "changed" forever.
+*/
+function skillManifest(tree, dir) {
+	const manifest = {};
+	for (const file of skillTreeFiles(tree, dir)) manifest[file.path] = file.size;
+	return manifest;
+}
+/**
+* The real upstream directory of one tracked skill. Source records keep only
+* the short name and top-level root (e.g. root "skills", name "ask-matt"),
+* but upstream repos may nest skills under category directories
+* (skills/engineering/ask-matt/) or move them between categories. Resolution
+* order: exact match under the top-level root in the upstream tree, then the
+* manifest's recorded blob path, then any same-name skill in the tree, then
+* the flat root/name fallback. Passing the tree paths makes the lookup
+* resilient to incomplete manifests and upstream moves.
+*
+* A repo-root record (root '') has no directory to resolve: its SKILL.md is a
+* bare top-level path, so every nested lookup below would miss and the final
+* fallback would hand back a bogus '/name'. Answer before them — including
+* when the upstream SKILL.md is gone, so diffRemoteSkills reports a deletion
+* instead of hunting for a skill that was never nested.
+*/
+function skillDirOf(source, name, treePaths) {
+	if (isRepoRoot(source.root)) return "";
+	if (treePaths !== void 0) {
+		const rootPrefix = source.root + "/";
+		const found = treePaths.find((path) => path.startsWith(rootPrefix) && path.endsWith("/" + name + "/SKILL.md"));
+		if (found !== void 0) return found.slice(0, found.lastIndexOf("/"));
+	}
+	const manifest = source.manifest ?? {};
+	const fromManifest = Object.keys(manifest).find((path) => path.endsWith("/" + name + "/SKILL.md"));
+	if (fromManifest !== void 0) return fromManifest.slice(0, fromManifest.lastIndexOf("/"));
+	if (treePaths !== void 0) {
+		const found = treePaths.find((path) => path.endsWith("/" + name + "/SKILL.md"));
+		if (found !== void 0) return found.slice(0, found.lastIndexOf("/"));
+	}
+	return source.root + "/" + name;
+}
+/**
+* Diff one source record against an upstream tree at treeSha: which tracked
+* skills disappeared (no SKILL.md blob) and which changed (manifest baseline
+* differs, or no baseline exists — treated as changed). Pure over the tree.
+* The remote side is read through skillManifest, so the diff compares like
+* with like against the baseline recorded at import time.
+*/
+function diffRemoteSkills(tree, source) {
+	const treePaths = tree.filter((item) => item.type === "blob").map((item) => item.path);
+	const updated = [];
+	const deleted = [];
+	const baseline = source.manifest ?? {};
+	for (const name of source.skills) {
+		const dir = skillDirOf(source, name, treePaths);
+		const prefix = skillDirPrefix(dir);
+		const remote = skillManifest(tree, dir);
+		if (!Object.hasOwn(remote, skillFileAt(dir))) {
+			deleted.push(name);
+			continue;
+		}
+		const baselineEntries = Object.entries(baseline).filter(([path]) => path.startsWith(prefix));
+		if (baselineEntries.length === 0) {
+			updated.push(name);
+			continue;
+		}
+		let differs = baselineEntries.length !== Object.keys(remote).length;
+		if (!differs) {
+			for (const [path, size] of baselineEntries) if (remote[path] !== size) {
+				differs = true;
+				break;
+			}
+		}
+		if (differs) updated.push(name);
+	}
+	return {
+		updated,
+		deleted
+	};
+}
+/** Minimal RepoSkillEntry for a tracked skill name (sync re-downloads by name). */
+function repoSkillEntry(name, root, repo) {
+	const dir = isRepoRoot(root) ? "" : root + "/" + name;
+	return {
+		name,
+		dir,
+		path: skillFileAt(dir),
+		root,
+		origin: repo,
+		fileCount: 0,
+		totalBytes: 0,
+		existing: false
+	};
+}
 //#endregion
 //#region src/store/store.ts
 /** Sidecar state owner. */
@@ -725,14 +1019,18 @@ var SkillHubStore = class {
 	* When `dir` is given, every baseline path under that skill directory is
 	* dropped first, so files the upstream removed never linger in the
 	* baseline and skew later update diffs.
+	*
+	* `dir` may be '' — a skill whose SKILL.md sits at the repo root. Its prefix
+	* is empty, so the whole baseline is replaced: that skill owns the tree, and
+	* keeping stale paths would make every later diff report "changed" forever.
 	*/
 	async mergeSourceManifest(repo, manifest, dir) {
 		await this.ensureLoaded();
 		const existing = this.sourcesByRepo.get(repo);
 		if (existing === void 0 || Object.keys(manifest).length === 0) return;
 		const base = { ...existing.manifest ?? {} };
-		if (dir !== void 0 && dir !== "") {
-			const prefix = dir + "/";
+		if (dir !== void 0) {
+			const prefix = skillDirPrefix(dir);
 			for (const path of Object.keys(base)) if (path.startsWith(prefix)) delete base[path];
 		}
 		this.sourcesByRepo.set(repo, {
@@ -1584,10 +1882,27 @@ function setGithubToken(token) {
 function githubAuthHeaders() {
 	return githubToken === "" ? {} : { authorization: "Bearer " + githubToken };
 }
+/**
+* 传输层：显式要求服务端返回未压缩实体。
+*
+* 为什么必须加：dsh 会把**启动环境**里的 `HTTP_PROXY`/`HTTPS_PROXY` 装成
+* undici 的全局 dispatcher（`@deepseek-ai/dsh-http-proxy`），插件里的 `fetch`
+* 因此走该代理。实测本机 Clash：经代理返回的响应会**丢掉 `content-encoding`
+* 与 `content-type` 头，而 body 仍是 gzip**；undici 只依据 `content-encoding`
+* 决定是否解压，于是 `response.json()` 拿到 gzip 二进制并抛错，被上层的
+* catch 映射成 `invalid github response for <url>` —— 看起来像 GitHub 坏了。
+* 实测对照（同一 URL、同一代理）：默认 1331 字节解析失败，声明 identity 后
+* 5245 字节解析成功。
+*
+* 代价是不走压缩（我们的响应体都很小），换来的是**无论中间代理是否改写头部
+* 都能正确取到实体**，且用户无需为插件调整启动命令。
+*/
+const NO_COMPRESSION = { "accept-encoding": "identity" };
 /** JSON API 默认请求头（含鉴权）。 */
 function apiHeaders() {
 	return {
 		accept: "application/vnd.github+json",
+		...NO_COMPRESSION,
 		...githubAuthHeaders()
 	};
 }
@@ -1677,184 +1992,6 @@ async function fetchJsonCached(url, fetchImpl, context) {
 	};
 }
 //#endregion
-//#region src/repo/discovery.ts
-/**
-* 仓库技能发现：从 GitHub 仓库树推断技能根目录、列出可导入技能、
-* 生成目录清单并做上游差异比对。纯函数为主，便于单测。
-* 从 repo.ts 抽出。
-*/
-/** Top-level directory pattern for a skill root: visible, non-dot, safe chars. First char must be alphanum. */
-const ROOT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-/** `owner/repo` slug for a parsed reference. */
-function repoSlug(ref) {
-	return `${ref.owner}/${ref.repo}`;
-}
-/**
-* Normalize a GitHub URL or `owner/repo`/`owner/repo@ref` input.
-* Only github.com URLs are accepted in v1.
-*/
-function normalizeRepoInput(input) {
-	let value = input.trim();
-	if (value === "") return null;
-	let ref;
-	const urlMatch = /^https?:\/\/github\.com\/([^/]+)\/([^/#?@]+)(?:\/tree\/([^/?#]+))?/.exec(value);
-	if (urlMatch !== null) {
-		value = `${urlMatch[1]}/${urlMatch[2]}`;
-		ref = urlMatch[3];
-	} else {
-		if (/^https?:\/\//.test(value)) return null;
-		const at = value.indexOf("@");
-		if (at !== -1) {
-			ref = value.slice(at + 1).trim();
-			value = value.slice(0, at).trim();
-		}
-	}
-	value = value.replace(/\.git$/, "").replace(/\/+$/, "");
-	const parts = value.split("/").filter(Boolean);
-	if (parts.length < 2) return null;
-	const owner = parts[0];
-	const repo = parts[1];
-	if (owner === "" || repo === "" || owner.includes("..") || repo.includes("..")) return null;
-	return {
-		owner,
-		repo,
-		...ref !== void 0 && ref !== "" ? { ref } : {}
-	};
-}
-/** Collect every file inside a skill directory, including SKILL.md itself. */
-function collectRepoSkillFiles(tree, dir) {
-	const prefix = dir + "/";
-	return tree.filter((item) => item.type === "blob" && item.path.startsWith(prefix)).map((item) => ({
-		path: item.path,
-		size: typeof item.size === "number" ? item.size : 0
-	})).sort((a, b) => a.path.localeCompare(b.path));
-}
-/** Compute an origin collection name. Multiple roots split by root, one root keeps the repo slug. */
-function originForRoot(repo, rootsPresent, root) {
-	return rootsPresent.size > 1 ? `${repo}/${root}` : repo;
-}
-/** Discover importable skills from a repo tree. Invalid names are ignored. Roots are auto-derived from the top-level directory of each SKILL.md. */
-function discoverRepoEntries(tree, repo, existingNames = /* @__PURE__ */ new Set()) {
-	const candidates = [];
-	const rootsPresent = /* @__PURE__ */ new Set();
-	for (const item of tree) {
-		if (item.type !== "blob") continue;
-		const slash = item.path.indexOf("/");
-		if (slash === -1) continue;
-		if (!item.path.endsWith("/SKILL.md")) continue;
-		const root = item.path.slice(0, slash);
-		if (!ROOT_RE.test(root)) continue;
-		const dir = item.path.slice(0, -9);
-		if (dir === root || dir.length <= root.length + 1) continue;
-		const name = dir.slice(dir.lastIndexOf("/") + 1);
-		if (!isSkillName(name)) continue;
-		rootsPresent.add(root);
-		candidates.push({
-			root,
-			dir,
-			name,
-			path: item.path
-		});
-	}
-	return candidates.map((candidate) => {
-		const files = collectRepoSkillFiles(tree, candidate.dir);
-		return {
-			name: candidate.name,
-			dir: candidate.dir,
-			path: candidate.path,
-			root: candidate.root,
-			origin: originForRoot(repo, rootsPresent, candidate.root),
-			fileCount: files.length,
-			totalBytes: files.reduce((sum, file) => sum + file.size, 0),
-			existing: existingNames.has(candidate.name)
-		};
-	}).sort((a, b) => a.name.localeCompare(b.name));
-}
-/** Build a path→size manifest for one skill directory from a repo tree. */
-function skillManifest(tree, dir) {
-	const prefix = dir + "/";
-	const manifest = {};
-	for (const item of tree) if (item.type === "blob" && item.path.startsWith(prefix)) manifest[item.path] = typeof item.size === "number" ? item.size : 0;
-	return manifest;
-}
-/**
-* The real upstream directory of one tracked skill. Source records keep only
-* the short name and top-level root (e.g. root "skills", name "ask-matt"),
-* but upstream repos may nest skills under category directories
-* (skills/engineering/ask-matt/) or move them between categories. Resolution
-* order: exact match under the top-level root in the upstream tree, then the
-* manifest's recorded blob path, then any same-name skill in the tree, then
-* the flat root/name fallback. Passing the tree paths makes the lookup
-* resilient to incomplete manifests and upstream moves.
-*/
-function skillDirOf(source, name, treePaths) {
-	if (treePaths !== void 0) {
-		const rootPrefix = source.root + "/";
-		const found = treePaths.find((path) => path.startsWith(rootPrefix) && path.endsWith("/" + name + "/SKILL.md"));
-		if (found !== void 0) return found.slice(0, found.lastIndexOf("/"));
-	}
-	const manifest = source.manifest ?? {};
-	const fromManifest = Object.keys(manifest).find((path) => path.endsWith("/" + name + "/SKILL.md"));
-	if (fromManifest !== void 0) return fromManifest.slice(0, fromManifest.lastIndexOf("/"));
-	if (treePaths !== void 0) {
-		const found = treePaths.find((path) => path.endsWith("/" + name + "/SKILL.md"));
-		if (found !== void 0) return found.slice(0, found.lastIndexOf("/"));
-	}
-	return source.root + "/" + name;
-}
-/**
-* Diff one source record against an upstream tree at treeSha: which tracked
-* skills disappeared (no SKILL.md blob) and which changed (manifest baseline
-* differs, or no baseline exists — treated as changed). Pure over the tree.
-*/
-function diffRemoteSkills(tree, source) {
-	const blobs = /* @__PURE__ */ new Map();
-	for (const item of tree) if (item.type === "blob") blobs.set(item.path, typeof item.size === "number" ? item.size : 0);
-	const treePaths = [...blobs.keys()];
-	const updated = [];
-	const deleted = [];
-	for (const name of source.skills) {
-		const prefix = skillDirOf(source, name, treePaths) + "/";
-		const remote = /* @__PURE__ */ new Map();
-		for (const [path, size] of blobs) if (path.startsWith(prefix)) remote.set(path, size);
-		if (!remote.has(prefix + "SKILL.md")) {
-			deleted.push(name);
-			continue;
-		}
-		const baseline = source.manifest ?? {};
-		const baselineEntries = Object.entries(baseline).filter(([path]) => path.startsWith(prefix));
-		if (baselineEntries.length === 0) {
-			updated.push(name);
-			continue;
-		}
-		let differs = baselineEntries.length !== remote.size;
-		if (!differs) {
-			for (const [path, size] of baselineEntries) if (remote.get(path) !== size) {
-				differs = true;
-				break;
-			}
-		}
-		if (differs) updated.push(name);
-	}
-	return {
-		updated,
-		deleted
-	};
-}
-/** Minimal RepoSkillEntry for a tracked skill name (sync re-downloads by name). */
-function repoSkillEntry(name, root, repo) {
-	return {
-		name,
-		dir: root + "/" + name,
-		path: root + "/" + name + "/SKILL.md",
-		root,
-		origin: repo,
-		fileCount: 0,
-		totalBytes: 0,
-		existing: false
-	};
-}
-//#endregion
 //#region src/repo/api.ts
 /**
 * GitHub 仓库读取：仓库树、发布标签、星标/下载量、分支与提交查询。
@@ -1991,7 +2128,10 @@ async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch, signal) {
 	let response = null;
 	try {
 		response = await fetchImpl(rawUrl, {
-			headers: githubAuthHeaders(),
+			headers: {
+				...NO_COMPRESSION,
+				...githubAuthHeaders()
+			},
 			...signal !== void 0 ? { signal } : {}
 		});
 	} catch (error) {
@@ -2005,6 +2145,7 @@ async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch, signal) {
 			response = await fetchImpl(apiUrl, {
 				headers: {
 					accept: "application/vnd.github.raw",
+					...NO_COMPRESSION,
 					...githubAuthHeaders()
 				},
 				...signal !== void 0 ? { signal } : {}
@@ -2036,7 +2177,7 @@ async function downloadRepoSkill(repo, ref, entry, files, targetRoot, fetchImpl
 	try {
 		await mapConcurrent(files, 6, async (file) => {
 			if (signal?.aborted) throw new DOMException("aborted", "AbortError");
-			const relative = file.path.slice(entry.dir.length + 1);
+			const relative = relativeToSkillDir(entry.dir, file.path);
 			if (relative === "" || relative.includes("..")) throw new RepoFetchError("unsafe repo path: " + file.path);
 			const target = join(tempDir, relative);
 			const buffer = await downloadGitHubFile(repo, ref, file.path, fetchImpl, signal);
@@ -2074,7 +2215,7 @@ async function downloadRepoSkill(repo, ref, entry, files, targetRoot, fetchImpl
 					force: true
 				});
 			} catch (secondError) {
-				console.warn(`[skill-hub] cleanup tempDir failed ${tempDir}:`, errorText(secondError), "first:", errorText(firstError));
+				console.warn(`[dsh-skill-hub] cleanup tempDir failed ${tempDir}:`, errorText(secondError), "first:", errorText(firstError));
 			}
 		}
 	}
@@ -2102,10 +2243,10 @@ async function cleanupLeftoverImportDirs(targetRoot) {
 			});
 			cleaned += 1;
 		} catch (error) {
-			console.warn(`[skill-hub] startup cleanup failed ${full}:`, errorText(error));
+			console.warn(`[dsh-skill-hub] startup cleanup failed ${full}:`, errorText(error));
 		}
 	}
-	if (cleaned > 0) console.warn(`[skill-hub] startup cleaned ${cleaned} leftover import temp dir(s) in ${targetRoot}`);
+	if (cleaned > 0) console.warn(`[dsh-skill-hub] startup cleaned ${cleaned} leftover import temp dir(s) in ${targetRoot}`);
 	return cleaned;
 }
 /** Loopback literal check plus browser same-origin markers. */
@@ -2362,10 +2503,7 @@ async function checkLatestRelease(repo = UPDATE_REPO, fetchImpl = fetch) {
 	const url = `https://api.github.com/repos/${repo}/releases/latest`;
 	let response;
 	try {
-		response = await fetchImpl(url, { headers: {
-			accept: "application/vnd.github+json",
-			...githubAuthHeaders()
-		} });
+		response = await fetchImpl(url, { headers: apiHeaders() });
 	} catch (error) {
 		return failure(errorText(error));
 	}
@@ -2598,7 +2736,7 @@ function toDetail(skill) {
 */
 function createRoute(deps, spec) {
 	return {
-		kind: "exact",
+		kind: spec.kind ?? "exact",
 		path: spec.path,
 		handler: async (req, res) => {
 			if (!isLoopbackRequest(req)) {
@@ -2962,6 +3100,21 @@ function catalogRoutes(deps) {
 * 配置域路由：config（总开关开着也可用，设置卡自救入口）/ update 自身更新
 * 检查 / diagnosticFix。从 routes.ts 原样搬出，handler 逻辑不变。
 */
+/**
+* Build a config payload for either method. The GitHub token never goes out:
+* the effective config and the raw saved overrides are both stripped, and its
+* presence is reported as a plain boolean instead.
+*/
+function configResponse(config, saved) {
+	const token = config.githubToken;
+	return {
+		ok: true,
+		pluginVersion: CURRENT_VERSION,
+		config: redactGithubToken(config),
+		saved: redactGithubToken(saved),
+		githubTokenSet: token !== void 0 && token !== ""
+	};
+}
 /** 配置域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 function configRoutes(deps) {
 	return [
@@ -2972,12 +3125,7 @@ function configRoutes(deps) {
 			skipGate: true,
 			handler: async ({ req, res, body }) => {
 				if (req.method === "GET") {
-					writeJson(res, 200, {
-						ok: true,
-						pluginVersion: CURRENT_VERSION,
-						config: configOf(deps),
-						saved: savedOf(deps)
-					});
+					writeJson(res, 200, configResponse(configOf(deps), savedOf(deps)));
 					return;
 				}
 				const raw = body;
@@ -3038,12 +3186,7 @@ function configRoutes(deps) {
 					else merged[key] = value;
 					config = merged;
 				} else config = await deps.updateConfig(patch);
-				writeJson(res, 200, {
-					ok: true,
-					pluginVersion: CURRENT_VERSION,
-					config,
-					saved: savedOf(deps)
-				});
+				writeJson(res, 200, configResponse(config, savedOf(deps)));
 			}
 		},
 		{
@@ -3133,11 +3276,65 @@ async function replaceSkillDir(targetDir, download) {
 //#region src/routes/market.ts
 /**
 * 市场域路由：market 列表 / source 增删 / ref 锁定 / versions 选择器 /
-* check 更新检查 / stats 星标统计 / sync 对齐版本。从 routes.ts 原样搬出，
-* handler 逻辑不变。
+* source/check 更新检查 / stats 星标统计 / source/sync 对齐版本。
+* 从 routes.ts 原样搬出，handler 逻辑不变。
 */
 /** 市场域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 function marketRoutes(deps) {
+	const checkMarketSources = async ({ res }) => {
+		const sources = await deps.store.listMarketSources();
+		if (lastMarketCheck.size > 500) lastMarketCheck.clear();
+		const results = [];
+		for (const source of sources) {
+			const base = {
+				repo: source.repo,
+				...source.ref !== void 0 ? { ref: source.ref } : {}
+			};
+			const now = Date.now();
+			if (now - (lastMarketCheck.get(source.repo) ?? 0) < 3e5) {
+				results.push({
+					...base,
+					updateAvailable: false,
+					commitSha: source.commitSha ?? "",
+					throttled: true
+				});
+				continue;
+			}
+			try {
+				const latestTag = await getLatestReleaseTag(source.repo);
+				if (source.ref === void 0) {
+					results.push({
+						...base,
+						updateAvailable: false,
+						commitSha: source.commitSha ?? "",
+						...latestTag !== void 0 ? { latestTag } : {}
+					});
+					continue;
+				}
+				const latest = await getLatestCommit(source.repo, source.ref);
+				lastMarketCheck.set(source.repo, now);
+				const commitMoved = source.commitSha !== void 0 && latest.commitSha !== source.commitSha;
+				const newRelease = latestTag !== void 0 && latestTag !== source.ref;
+				results.push({
+					...base,
+					updateAvailable: commitMoved || newRelease,
+					commitSha: latest.commitSha,
+					...newRelease ? { latestTag } : {}
+				});
+			} catch (error) {
+				results.push({
+					...base,
+					updateAvailable: false,
+					commitSha: source.commitSha ?? "",
+					error: errorText(error)
+				});
+			}
+		}
+		writeJson(res, 200, {
+			ok: true,
+			results
+		});
+	};
 	return [
 		{
 			path: SKILL_HUB_API.market,
@@ -3235,60 +3432,12 @@ function marketRoutes(deps) {
 		{
 			path: SKILL_HUB_API.marketCheck,
 			methods: ["GET"],
-			handler: async ({ res }) => {
-				const sources = await deps.store.listMarketSources();
-				if (lastMarketCheck.size > 500) lastMarketCheck.clear();
-				const results = [];
-				for (const source of sources) {
-					const base = {
-						repo: source.repo,
-						...source.ref !== void 0 ? { ref: source.ref } : {}
-					};
-					const now = Date.now();
-					if (now - (lastMarketCheck.get(source.repo) ?? 0) < 3e5) {
-						results.push({
-							...base,
-							updateAvailable: false,
-							commitSha: source.commitSha ?? "",
-							throttled: true
-						});
-						continue;
-					}
-					try {
-						const latestTag = await getLatestReleaseTag(source.repo);
-						if (source.ref === void 0) {
-							results.push({
-								...base,
-								updateAvailable: false,
-								commitSha: source.commitSha ?? "",
-								...latestTag !== void 0 ? { latestTag } : {}
-							});
-							continue;
-						}
-						const latest = await getLatestCommit(source.repo, source.ref);
-						lastMarketCheck.set(source.repo, now);
-						const commitMoved = source.commitSha !== void 0 && latest.commitSha !== source.commitSha;
-						const newRelease = latestTag !== void 0 && latestTag !== source.ref;
-						results.push({
-							...base,
-							updateAvailable: commitMoved || newRelease,
-							commitSha: latest.commitSha,
-							...newRelease ? { latestTag } : {}
-						});
-					} catch (error) {
-						results.push({
-							...base,
-							updateAvailable: false,
-							commitSha: source.commitSha ?? "",
-							error: errorText(error)
-						});
-					}
-				}
-				writeJson(res, 200, {
-					ok: true,
-					results
-				});
-			}
+			handler: checkMarketSources
+		},
+		{
+			path: SKILL_HUB_API_DEPRECATED_MARKET_CHECK,
+			methods: ["GET"],
+			handler: checkMarketSources
 		},
 		{
 			path: SKILL_HUB_API.marketStats,
@@ -3511,7 +3660,7 @@ function repoImportRoutes(deps) {
 					for (const entry of selected) {
 						if (controller.signal.aborted) break;
 						job.current = entry.name;
-						job.currentFile = entry.dir + "/SKILL.md";
+						job.currentFile = entry.path;
 						if (entry.existing) {
 							job.skipped.push({
 								name: entry.name,
@@ -3535,7 +3684,7 @@ function repoImportRoutes(deps) {
 						try {
 							const result = await downloadRepoSkill(repo, resolvedRef, entry, files, targetRoot, fetch, controller.signal, (bytes, file) => {
 								job.downloadedBytes += bytes;
-								job.currentFile = entry.dir + "/" + file;
+								job.currentFile = skillPathIn(entry.dir, file);
 							});
 							await deps.store.addSourceSkill(repo, entry.root, commitSha, resolvedRef, entry.name);
 							await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir);
@@ -3913,7 +4062,7 @@ function sourceRoutes(deps) {
 					try {
 						const entry = repoSkillEntry(name, source.root, repo);
 						entry.dir = skillDirOf(source, name, tree.map((item) => item.path));
-						entry.path = entry.dir + "/SKILL.md";
+						entry.path = skillFileAt(entry.dir);
 						const files = collectRepoSkillFiles(tree, entry.dir);
 						if (files.length === 0) {
 							failed.push({
@@ -4100,17 +4249,25 @@ function sourceRoutes(deps) {
 /**
 * Build every /api/skill-hub route.
 * @param deps - skill registry view + sidecar store.
-* @returns the exact-path routes.
+* @returns the exact-path routes plus the family's 404 catch-all.
 */
 function makeRoutes(deps) {
-	return [
+	return [...[
 		...catalogRoutes(deps),
 		...configRoutes(deps),
 		...marketRoutes(deps),
 		...repoImportRoutes(deps),
 		...groupRoutes(deps),
 		...sourceRoutes(deps)
-	].map((spec) => createRoute(deps, spec));
+	].map((spec) => createRoute(deps, spec)), createRoute(deps, {
+		kind: "prefix",
+		path: SKILL_HUB_API_ROOT,
+		methods: ["GET", "POST"],
+		skipGate: true,
+		handler: async ({ res, url }) => {
+			writeError(res, 404, "unknown skill-hub route: " + url.pathname + " (see SKILL_HUB_API in src/protocol/api.ts)");
+		}
+	})];
 }
 //#endregion
 //#region src/stats/scan.ts
@@ -4493,56 +4650,100 @@ async function reconcileDisabledSkills(store, home = dshHome()) {
 //#region src/index.ts
 /** Stable cordis plugin name (matches cordis.patch.yml insert id). */
 const name = "skill-hub";
-/** Services required before the skill-hub surfaces can mount. */
+/** Services required before the skill-hub surfaces can mount. `settings` is deliberately NOT here: the plugin reads its own volatile config refs and only reaches for the settings service when it is present (issue #11). */
 const inject = [
 	"webServer",
 	"skills",
-	"systemPrompt",
-	"settings"
+	"systemPrompt"
 ];
+/**
+* The durable field schemas, plain (non-volatile) so the same definitions can
+* back both the live view below and the wire form the settings page renders
+* from `.toJSON()`. `description` is what the auto-generated page shows with
+* each row; `role('secret')` makes the settings layer redact the value on
+* every wire read.
+*/
+const ConfigFields = {
+	enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled).description("关闭后技能中枢的路由、入口与公告全部下线。"),
+	announceToAgent: z.boolean().default(HUB_CONFIG_DEFAULTS.announceToAgent).description("在系统提示中加入本插件说明，用户提到技能管理时 Agent 知道如何协作。"),
+	dotModelColor: z.string().pattern(HEX_COLOR_RE).description("技能行与聊天「/」菜单中「模型可调」圆点的颜色（#rrggbb）。"),
+	dotUserColor: z.string().pattern(HEX_COLOR_RE).description("技能行与聊天「/」菜单中「仅用户可调」圆点的颜色（#rrggbb）。"),
+	showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount).description("在技能名旁显示调用次数。"),
+	showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime).description("在技能名行显示最近调用时间。"),
+	showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary).description("在分组标题后汇总调用次数与最近调用时间。"),
+	statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays).description("只统计最近 N 天的使用次数；0 = 全部历史。"),
+	statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes).description("后台扫描会话日志的间隔（分钟，最小 1）。"),
+	githubToken: z.string().role("secret").description("市场/来源走 GitHub API：匿名每小时 60 次，填 token 后 5000 次。留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。")
+};
+/**
+* The live plugin config the settings page edits. Field order here is the row
+* order the auto-generated page renders.
+*/
 const Config = z.object({
-	announceToAgent: z.boolean().default(HUB_CONFIG_DEFAULTS.announceToAgent),
-	enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled),
-	showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount),
-	showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime),
-	showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary),
-	statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays),
-	statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes)
+	enabled: ConfigFields.enabled.volatile(),
+	announceToAgent: ConfigFields.announceToAgent.volatile(),
+	dotModelColor: ConfigFields.dotModelColor.volatile(),
+	dotUserColor: ConfigFields.dotUserColor.volatile(),
+	showUseCount: ConfigFields.showUseCount.volatile(),
+	showUseTime: ConfigFields.showUseTime.volatile(),
+	showGroupSummary: ConfigFields.showGroupSummary.volatile(),
+	statsWindowDays: ConfigFields.statsWindowDays.volatile(),
+	statsScanMinutes: ConfigFields.statsScanMinutes.volatile(),
+	githubToken: ConfigFields.githubToken.volatile()
 });
 /**
-* Settings namespace hosting the hub's runtime config. Since dsh rc.7 the
-* host serves every registered settings namespace to the web client (the
-* dsh-host-apiproxy allowlist is gone), so the browser card and the settings
-* page edit this namespace through the official settings transport, and the
-* plugin consumes the same resolved value — one source of truth.
+* The settings namespace this plugin's config lives under, narrowed to the
+* settings package's branded type. The browser half resolves the same form
+* through `ctx.configForms.get(HUB_ENTRY_ID)`.
 */
-const CONFIG_NAMESPACE = "dsh-skill-hub";
-/** Schema of the hub's settings namespace: the card's fields (booleans + optional dot colors). */
-const HubSettingsSchema = z.object({
-	enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled),
-	announceToAgent: z.boolean().default(HUB_CONFIG_DEFAULTS.announceToAgent),
-	showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount),
-	showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime),
-	showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary),
-	dotModelColor: z.string().pattern(HEX_COLOR_RE),
-	dotUserColor: z.string().pattern(HEX_COLOR_RE),
-	githubToken: z.string(),
-	statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays),
-	statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes)
-});
+const ENTRY_ID = HUB_ENTRY_ID;
+/** Every config field, in the order the settings page renders them (used to walk the volatile refs). */
+const CONFIG_FIELDS = [
+	"enabled",
+	"announceToAgent",
+	"dotModelColor",
+	"dotUserColor",
+	"showUseCount",
+	"showUseTime",
+	"showGroupSummary",
+	"statsWindowDays",
+	"statsScanMinutes",
+	"githubToken"
+];
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 152;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const SKILL_HUB_GUIDANCE = ["本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；设置 → 插件列表中有本插件的配置卡片（启用/公告开关）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由仅回环可访问。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。", "The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → \"Skills\" is the management page; Settings → Plugins lists this plugin's configuration card (enable / announcement toggles). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with \"check all\" and \"update all\" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics; new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; routes are loopback-only. When the user mentions \"skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill\", this plugin is what they mean — collaborate accordingly."].join("\n\n");
+const SKILL_HUB_GUIDANCE = ["本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；本插件的配置页（启用/公告开关、圆点颜色、GitHub token、统计窗口）在插件管理页——侧边栏「插件」→ 本插件，是本插件自己注册的配置卡片（默认折叠，点标题展开）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由仅回环可访问。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。", "The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → \"Skills\" is the management page; the plugin's configuration page (enable / announcement toggles, dot colors, GitHub token, stats window) is registered by the plugin itself on its own page in the Plugins manager (sidebar → 插件 → the plugin; collapsed until you expand the title). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with \"check all\" and \"update all\" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics; new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; routes are loopback-only. When the user mentions \"skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill\", this plugin is what they mean — collaborate accordingly."].join("\n\n");
 /**
 * Mount the skill hub routes and announcement.
 * @param ctx - host plugin context carrying webServer/skills/systemPrompt/settings.
-* @param config - resolved plugin config (schema defaults applied by the loader).
 */
 function apply(ctx, config) {
-	const base = config ?? {};
-	const settingsScope = ctx.settings.register(CONFIG_NAMESPACE, HubSettingsSchema, { base });
-	const current = () => settingsScope.get();
+	/**
+	* Read the runtime config out of our own volatile config refs.
+	*
+	* This is the whole point of `volatile()`: the Loader updates those values
+	* **in place** (`ConfigEditor.edit` → `resolveConfig(fiber.runtime, next)` →
+	* `updateVolatile`) without rebuilding the fiber, so a held reference always
+	* answers `.get()` with the current value. Consequences worth remembering:
+	*   - no `settings.describe()` per request (it walks and projects every entry
+	*     in the profile — the reason this used to be slow);
+	*   - no subscription or watcher is needed for *reading*;
+	*   - the plugin keeps working when the Settings service is absent
+	*     (issue #11: business logic must not depend on Settings).
+	*/
+	const readConfig = () => {
+		const out = {};
+		for (const field of CONFIG_FIELDS) {
+			const ref = config?.[field];
+			const value = ref !== void 0 && typeof ref.get === "function" ? ref.get() : ref;
+			if (value !== void 0) out[field] = value;
+		}
+		return out;
+	};
+	const current = () => resolveHubConfig({}, readConfig());
+	/** The Settings service, when this deployment mounts it. Absent ⇒ no user layer to read or write. */
+	const settingsOf = () => ctx.get("settings");
 	const store = new SkillHubStore();
 	let disposeRoutes;
 	let disposeSection;
@@ -4550,14 +4751,26 @@ function apply(ctx, config) {
 	let providerControl;
 	let stats;
 	const saved = () => {
-		return ctx.settings.describe().find((entry) => entry.ns === "dsh-skill-hub")?.user ?? {};
+		return (settingsOf()?.describe().find((entry) => entry.ns === ENTRY_ID))?.user ?? {};
 	};
 	const updateConfig = async (patch) => {
-		const user = { ...saved() };
-		for (const [key, value] of Object.entries(patch)) if (value === void 0) delete user[key];
-		else user[key] = value;
-		await settingsScope.replace(user);
-		return settingsScope.get();
+		const ops = [];
+		for (const [field, value] of Object.entries(patch)) if (value === void 0) ops.push({
+			op: "unset",
+			path: [field]
+		});
+		else ops.push({
+			op: "set",
+			path: [field],
+			value
+		});
+		const settings = settingsOf();
+		if (settings === void 0) throw new Error("this deployment does not mount the settings service; config is read-only");
+		if (ops.length > 0) {
+			await settings.mutate(ENTRY_ID, ops);
+			sync();
+		}
+		return current();
 	};
 	const sync = () => {
 		if (disposeSection !== void 0) {
@@ -4582,6 +4795,7 @@ function apply(ctx, config) {
 				return new SkillHubProvider(control);
 			}), "dsh-skill-hub: provider");
 		}
+		ctx.logger.info(`[dsh-skill-hub] surfaces synced: enabled=${value.enabled} announceToAgent=${value.announceToAgent}`);
 		if (disposeRoutes !== void 0) {
 			disposeRoutes();
 			disposeRoutes = void 0;
@@ -4604,9 +4818,6 @@ function apply(ctx, config) {
 		}, "dsh-skill-hub: routes");
 	};
 	sync();
-	ctx.effect(() => settingsScope.watch(() => {
-		sync();
-	}), "dsh-skill-hub: settings config watch");
 	(async () => {
 		const home = dshHome();
 		const agentsHome = process.env.DSH_AGENTS_HOME ?? join(homedir(), ".agents");
@@ -4626,7 +4837,10 @@ function apply(ctx, config) {
 	(async () => {
 		try {
 			const legacy = await store.getConfig();
-			if (Object.keys(legacy).length > 0 && Object.keys(saved()).length === 0) await settingsScope.update(legacy);
+			if (Object.keys(legacy).length > 0 && Object.keys(saved()).length === 0) {
+				const settings = settingsOf();
+				if (settings !== void 0) await settings.update(ENTRY_ID, legacy);
+			}
 		} catch (error) {
 			ctx.logger.warn("[dsh-skill-hub] sidecar config migration into the settings namespace failed", error);
 		}
@@ -4706,4 +4920,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { CONFIG_NAMESPACE, Config, HubSettingsSchema, SKILL_HUB_GUIDANCE, apply, inject, name };
+export { Config, ENTRY_ID, SKILL_HUB_GUIDANCE, apply, inject, name };