dsh-skill-hub 0.3.18 → 0.3.20

package/lib/index.js

@@ -83,29 +83,30 @@ const HUB_CONFIG_DEFAULTS = {
 	statsScanMinutes: 5
 };
 /**
-* Resolve the effective hub config: saved sidecar overrides win over the
-* cordis composition entry (the web card owns runtime config), missing
-* booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
-* (saved first, then base) only when set. Numeric stats knobs are clamped to
-* their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
+* Fill a raw settings value into the effective hub config: schema defaults for
+* anything missing, and the numeric stats knobs clamped to sane ranges
+* (window ≥ 0, scan interval ≥ 1 minute).
+*
+* There is deliberately no "saved sidecar layer" parameter. Until dsh 0.1.7 the
+* hub kept its own runtime overrides in the sidecar and merged them here; the
+* settings namespace is now the only user layer (`updateConfig` writes through
+* `ctx.settings.mutate`), so a merge against a sidecar layer could never
+* observe anything but `{}` — see the git history of `resolveHubConfig`.
 */
-function resolveHubConfig(saved, base = {}) {
-	const dotModelColor = saved.dotModelColor !== void 0 ? saved.dotModelColor : base.dotModelColor;
-	const dotUserColor = saved.dotUserColor !== void 0 ? saved.dotUserColor : base.dotUserColor;
-	const githubToken = saved.githubToken !== void 0 ? saved.githubToken : base.githubToken;
-	const windowDays = clampNumber(saved.statsWindowDays ?? base.statsWindowDays, 0) ?? HUB_CONFIG_DEFAULTS.statsWindowDays;
-	const scanMinutes = clampNumber(saved.statsScanMinutes ?? base.statsScanMinutes, 1) ?? HUB_CONFIG_DEFAULTS.statsScanMinutes;
+function resolveHubConfig(base = {}) {
+	const windowDays = clampNumber(base.statsWindowDays, 0) ?? HUB_CONFIG_DEFAULTS.statsWindowDays;
+	const scanMinutes = clampNumber(base.statsScanMinutes, 1) ?? HUB_CONFIG_DEFAULTS.statsScanMinutes;
 	return {
-		enabled: saved.enabled ?? base.enabled ?? HUB_CONFIG_DEFAULTS.enabled,
-		announceToAgent: saved.announceToAgent ?? base.announceToAgent ?? HUB_CONFIG_DEFAULTS.announceToAgent,
-		showUseCount: saved.showUseCount ?? base.showUseCount ?? HUB_CONFIG_DEFAULTS.showUseCount,
-		showUseTime: saved.showUseTime ?? base.showUseTime ?? HUB_CONFIG_DEFAULTS.showUseTime,
-		showGroupSummary: saved.showGroupSummary ?? base.showGroupSummary ?? HUB_CONFIG_DEFAULTS.showGroupSummary,
+		enabled: base.enabled ?? HUB_CONFIG_DEFAULTS.enabled,
+		announceToAgent: base.announceToAgent ?? HUB_CONFIG_DEFAULTS.announceToAgent,
+		showUseCount: base.showUseCount ?? HUB_CONFIG_DEFAULTS.showUseCount,
+		showUseTime: base.showUseTime ?? HUB_CONFIG_DEFAULTS.showUseTime,
+		showGroupSummary: base.showGroupSummary ?? HUB_CONFIG_DEFAULTS.showGroupSummary,
 		statsWindowDays: windowDays,
 		statsScanMinutes: scanMinutes,
-		...dotModelColor !== void 0 ? { dotModelColor } : {},
-		...dotUserColor !== void 0 ? { dotUserColor } : {},
-		...githubToken !== void 0 ? { githubToken } : {}
+		...base.dotModelColor !== void 0 ? { dotModelColor: base.dotModelColor } : {},
+		...base.dotUserColor !== void 0 ? { dotUserColor: base.dotUserColor } : {},
+		...base.githubToken !== void 0 ? { githubToken: base.githubToken } : {}
 	};
 }
 /** Clamp a numeric override into a valid value; undefined/invalid stays undefined. */
@@ -1373,6 +1374,26 @@ function rootOfPath(path, home = dshHome()) {
 	}
 }
 //#endregion
+//#region src/concurrency.ts
+/**
+* 并发工具：有界并发的 map。原先 repo.ts 与 stats.ts 各有一份实现，
+* 这里统一为一份（采用 stats 版本的 limit 夹取，调用点 limit≥1 行为不变）。
+*/
+/** Run an async worker over items with a bounded concurrency, preserving index order. */
+async function mapConcurrent(items, limit, worker) {
+	const results = new Array(items.length);
+	let cursor = 0;
+	const runners = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
+		while (cursor < items.length) {
+			const index = cursor;
+			cursor += 1;
+			results[index] = await worker(items[index], index);
+		}
+	});
+	await Promise.all(runners);
+	return results;
+}
+//#endregion
 //#region src/skillfs/scan.ts
 /**
 * Scan one skills root for discovery files: directory bundles (SKILL.md)
@@ -1475,7 +1496,7 @@ async function readSkillInterface(directory) {
 	const hexColor = (value) => {
 		if (typeof value !== "string") return void 0;
 		const trimmed = value.trim();
-		return /^#[0-9a-fA-F]{6}$/.test(trimmed) ? trimmed : void 0;
+		return HEX_COLOR_RE.test(trimmed) ? trimmed : void 0;
 	};
 	const iconPath = (value) => {
 		if (typeof value !== "string" || value.trim() === "") return void 0;
@@ -1515,37 +1536,38 @@ async function findProjectRoot(cwd) {
 	return resolve(cwd);
 }
 /**
-* Scan one writable root for files the provider ignores, so the GUI can
-* show why a skill never appears — a
-* missing frontmatter must be visible, not silent). .disabled files belong
-* to the hub and are skipped.
+* Scan one writable root for files the provider ignores, so the GUI can show
+* why a skill never appears — a missing frontmatter, a name that disagrees
+* with the discovery path, and the like must be visible, not silent. Files the
+* hub itself disabled (`.disabled`) are skipped: they are a toggle state, not
+* a defect.
 */
 async function scanDiagnostics(root, home = dshHome()) {
-	const diagnostics = [];
-	for (const entry of await listSkillEntries(root, home)) {
+	return (await mapConcurrent(await listSkillEntries(root, home), 8, async (entry) => {
+		const found = [];
 		let text;
 		try {
 			text = await readFile(entry.path, "utf8");
 		} catch (error) {
-			if (error.code !== "ENOENT") diagnostics.push({
+			if (error.code !== "ENOENT") found.push({
 				path: entry.path,
 				root,
 				reason: "unreadable: " + errorText(error)
 			});
-			continue;
+			return found;
 		}
 		const parsed = parseFrontmatter(text);
 		if ("error" in parsed) {
 			const fixable = repairFrontmatterFileText(text) !== null;
-			diagnostics.push({
+			found.push({
 				path: entry.path,
 				root,
 				reason: parsed.error,
 				...fixable ? { fixable: true } : {}
 			});
-			continue;
+			return found;
 		}
-		if (repairFrontmatterFileText(text) !== null) diagnostics.push({
+		if (repairFrontmatterFileText(text) !== null) found.push({
 			path: entry.path,
 			root,
 			reason: "frontmatter contains unquoted colon/bracket (auto-repaired in memory; click Fix to persist)",
@@ -1553,18 +1575,18 @@ async function scanDiagnostics(root, home = dshHome()) {
 		});
 		const { value } = parsed;
 		const pathName = entry.kind === "directory" ? basename(entry.directory) : basename(entry.path, ".md");
-		if (value.name !== pathName) diagnostics.push({
+		if (value.name !== pathName) found.push({
 			path: entry.path,
 			root,
 			reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)`
 		});
-		if (value.description.length < 10) diagnostics.push({
+		if (value.description.length < 10) found.push({
 			path: entry.path,
 			root,
 			reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill`
 		});
-	}
-	return diagnostics;
+		return found;
+	})).flat();
 }
 //#endregion
 //#region src/skillfs.ts
@@ -1624,14 +1646,18 @@ async function enableSkill(disabledPath) {
 	return original;
 }
 /**
-* Move a skill (directory bundle or flat .md file) into the root's trash.
-* The skill stays recoverable: the source is renamed into
-* <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
-* SKILL.md path and moved as a whole directory.
+* Move one already-resolved skill (a bundle directory or a flat .md file) into
+* its root's trash as `<root>/.trash/<name>-<timestamp>`.
+*
+* The layout is the restore contract, not an implementation detail:
+* `restoreSkill` renames the entry back and only proves the parent is `.trash`,
+* and `clearTrash` deletes in place. Every producer of a trash entry must go
+* through here — skill delete, the hub-disabled whole-group delete, and repo
+* import's placeholder replacement all move skills for the same recovery flow.
+*
 * @returns the trashed path plus the original path that was moved.
 */
-async function trashSkill(sourcePath) {
-	const source = basename(sourcePath) === "SKILL.md" ? dirname(sourcePath) : sourcePath;
+async function moveIntoTrash(source) {
 	const trashDir = join(dirname(source), ".trash");
 	await mkdir(trashDir, { recursive: true });
 	const target = join(trashDir, basename(source) + "-" + Date.now());
@@ -1641,6 +1667,16 @@ async function trashSkill(sourcePath) {
 		source
 	};
 }
+/**
+* Move a skill (directory bundle or flat .md file) into the root's trash.
+* The skill stays recoverable: the source is renamed into
+* <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
+* SKILL.md path and moved as a whole directory.
+* @returns the trashed path plus the original path that was moved.
+*/
+async function trashSkill(sourcePath) {
+	return moveIntoTrash(basename(sourcePath) === "SKILL.md" ? dirname(sourcePath) : sourcePath);
+}
 /** Restore a trashed skill (directory or flat file) to its original location. */
 async function restoreSkill(entry, home = dshHome()) {
 	if (basename(dirname(entry.path)) !== ".trash") throw new TypeError("not a trashed skill path: " + entry.path);
@@ -1663,14 +1699,29 @@ function skillFileKind(path) {
 	if (basename(path) === "SKILL.md") return "directory";
 	if (path.endsWith(".md")) return "flat";
 }
-/** Repair one file on disk when its frontmatter is auto-fixable. Returns the new text. */
+/**
+* Repair one file on disk when its frontmatter is auto-fixable. Returns the new text.
+*
+* The write is atomic (sibling temp file + rename), matching the sidecar's
+* persist path: this rewrites a real skill file in place, and a crash midway
+* through a plain write would leave a truncated SKILL.md — exactly the failure
+* the store layer already guards against. The `.tmp` sibling is never picked
+* up by discovery (only `SKILL.md` and `*.md` are scanned).
+*/
 async function fixDiagnosticFile(path, home = dshHome()) {
 	if (rootOfPath(path, home) === void 0) throw new TypeError("not a hub writable skill path: " + path);
 	const repairedText = repairFrontmatterFileText(await readFile(path, "utf8"));
 	if (repairedText === null) throw new TypeError("diagnostic is not auto-fixable: " + path);
 	const parsed = parseFrontmatter(repairedText);
 	if ("error" in parsed) throw new TypeError("repaired frontmatter still invalid: " + parsed.error);
-	await writeFile(path, repairedText, "utf8");
+	const tmp = path + ".tmp";
+	await writeFile(tmp, repairedText, "utf8");
+	try {
+		await rename(tmp, path);
+	} catch (error) {
+		await rm(tmp, { force: true }).catch(() => {});
+		throw error;
+	}
 	return path;
 }
 //#endregion
@@ -1913,15 +1964,27 @@ function etagCacheSet(url, etag, json) {
 	});
 }
 /**
+* When the response shows an exhausted GitHub rate limit, the instant it
+* resets; otherwise undefined. Shared by the repo fetch layer and the plugin's
+* own update check so both agree on what counts as a rate-limit rejection
+* (403/429 + `x-ratelimit-remaining: 0` + a parseable `x-ratelimit-reset`)
+* instead of each re-deriving it from the headers.
+*/
+function rateLimitResetAt(response) {
+	if (response.status !== 403 && response.status !== 429) return void 0;
+	if (response.headers.get("x-ratelimit-remaining") !== "0") return void 0;
+	const reset = response.headers.get("x-ratelimit-reset");
+	if (reset === null) return void 0;
+	const at = /* @__PURE__ */ new Date(Number(reset) * 1e3);
+	return Number.isNaN(at.getTime()) ? void 0 : at;
+}
+/**
 * Build a RepoFetchError; when the response shows an exhausted rate limit,
 * report the reset time instead of a bare HTTP status.
 */
 function fetchError(context, response, fallbackStatus = 502) {
-	const remaining = response.headers.get("x-ratelimit-remaining");
-	const reset = response.headers.get("x-ratelimit-reset");
-	if (response.status === 403 || response.status === 429) {
-		if (remaining === "0" && reset !== null) return new RepoFetchError("github rate limit reached (anonymous quota exhausted); retry after " + (/* @__PURE__ */ new Date(Number(reset) * 1e3)).toLocaleTimeString() + " or set GITHUB_TOKEN", 403);
-	}
+	const resetAt = rateLimitResetAt(response);
+	if (resetAt !== void 0) return new RepoFetchError("github rate limit reached (anonymous quota exhausted); retry after " + resetAt.toLocaleTimeString() + " or set GITHUB_TOKEN", 403);
 	return new RepoFetchError(context + " (HTTP " + response.status + ")", response.status === 404 ? 404 : fallbackStatus);
 }
 /** 是否限流/中断类错误（调用方可直接透出，不再包装）。 */
@@ -1951,10 +2014,9 @@ async function fetchJson(url, fetchImpl, context, headers = apiHeaders()) {
 	}
 }
 /**
-* Load repo metadata and the recursive git tree at the given ref. The meta
-* request always resolves the default branch (used when ref is absent); the
-* tree is fetched at `ref ?? default_branch` so an explicit branch/tag scans
-* the exact same content a later download would fetch.
+* Load one JSON document from the GitHub API, reusing an ETag when the URL was
+* fetched before. `fetchImpl`/`context` exist so callers can stub the transport
+* and shape the error text; the payload is whatever the endpoint returned.
 */
 async function fetchJsonCached(url, fetchImpl, context) {
 	const cached = etagCache.get(url);
@@ -2081,26 +2143,6 @@ async function loadRepoTreeAt(repo, treeSha, fetchImpl = fetch) {
 	return Array.isArray(record.tree) ? record.tree : [];
 }
 //#endregion
-//#region src/concurrency.ts
-/**
-* 并发工具：有界并发的 map。原先 repo.ts 与 stats.ts 各有一份实现，
-* 这里统一为一份（采用 stats 版本的 limit 夹取，调用点 limit≥1 行为不变）。
-*/
-/** Run an async worker over items with a bounded concurrency, preserving index order. */
-async function mapConcurrent(items, limit, worker) {
-	const results = new Array(items.length);
-	let cursor = 0;
-	const runners = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
-		while (cursor < items.length) {
-			const index = cursor;
-			cursor += 1;
-			results[index] = await worker(items[index], index);
-		}
-	});
-	await Promise.all(runners);
-	return results;
-}
-//#endregion
 //#region src/repo/install.ts
 /**
 * 技能目录下载与落地：单文件下载（raw 优先、contents 兜底）、整目录
@@ -2133,7 +2175,7 @@ async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch, signal) {
 	}
 	if (response === null || !response.ok) {
 		if (signal?.aborted) throw new DOMException("aborted", "AbortError");
-		const apiUrl = `https://api.github.com/repos/${repo}/contents/${encodedPath}`;
+		const apiUrl = `https://api.github.com/repos/${repo}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`;
 		try {
 			response = await fetchImpl(apiUrl, {
 				headers: {
@@ -2352,9 +2394,14 @@ function isWritableSource(source) {
 }
 /** The resolved hub config a route sees (the shared resolver fills defaults). */
 function configOf(deps) {
-	return resolveHubConfig({}, deps.config?.() ?? {});
+	return resolveHubConfig(deps.config?.() ?? {});
 }
-/** The raw saved config layer a route reports (empty when the owner omits it). */
+/**
+* The raw saved config layer as persisted in the sidecar, reported for display
+* only. Since dsh 0.1.7 the settings namespace is the one user layer, so this
+* is legacy data: nothing writes it any more and the effective config above
+* never merges it.
+*/
 function savedOf(deps) {
 	return deps.saved?.() ?? {};
 }
@@ -2502,9 +2549,8 @@ async function checkLatestRelease(repo = UPDATE_REPO, fetchImpl = fetch) {
 	}
 	if (response.status === 404) return failure("no release published yet");
 	if (!response.ok) {
-		const remaining = response.headers.get("x-ratelimit-remaining");
-		const reset = response.headers.get("x-ratelimit-reset");
-		if ((response.status === 403 || response.status === 429) && remaining === "0" && reset !== null) return failure("github rate limit reached; retry after " + (/* @__PURE__ */ new Date(Number(reset) * 1e3)).toLocaleTimeString() + " or set GITHUB_TOKEN");
+		const resetAt = rateLimitResetAt(response);
+		if (resetAt !== void 0) return failure("github rate limit reached; retry after " + resetAt.toLocaleTimeString() + " or set GITHUB_TOKEN");
 		return failure("GitHub HTTP " + response.status);
 	}
 	let payload;
@@ -2539,10 +2585,18 @@ async function checkLatestRelease(repo = UPDATE_REPO, fetchImpl = fetch) {
 * routes 共享层 · 目录装配：已知工作区清单、完整目录响应（时间戳/interface
 * 元数据/重名诊断）与详情映射。从 helpers.ts 原样搬出，行为不变。
 */
-/** 目录中存在的技能名集合（tag 成员校验用）：启用目录 ∪ 已禁用名单，避免成员因禁用而丢失。 */
-async function knownSkillNames(deps) {
+/**
+* 目录中存在的技能名集合。默认（`includeDisabled` 未显式关闭）为「启用目录 ∪
+* 已禁用名单」——tag 成员校验用：技能被禁用后不该从 tag 里掉出去。
+*
+* 导入去重必须传 `{ includeDisabled: false }`：禁用只意味着「暂不启用」，把它
+* 算作「已存在」会让一次禁用产生「永久占名」的副作用，真技能再也导不进来
+* （issue #16）。
+*/
+async function knownSkillNames(deps, options) {
 	const snapshot = await deps.skills.snapshot();
 	const names = new Set(snapshot.skills.map((skill) => skill.name));
+	if (options?.includeDisabled === false) return names;
 	for (const disabled of await deps.store.listDisabled()) names.add(disabled.name);
 	return names;
 }
@@ -2684,7 +2738,8 @@ async function buildCatalog(deps, cwd) {
 		if (iface !== void 0) applyInterface(row, iface);
 		return row;
 	});
-	const diagnostics = [...await scanDiagnostics("user-dsh", home), ...await scanDiagnostics("user-agents", home)];
+	const [userDshDiagnostics, userAgentsDiagnostics] = await Promise.all([scanDiagnostics("user-dsh", home), scanDiagnostics("user-agents", home)]);
+	const diagnostics = [...userDshDiagnostics, ...userAgentsDiagnostics];
 	return {
 		ok: true,
 		pluginVersion: CURRENT_VERSION,
@@ -2873,15 +2928,7 @@ function catalogRoutes(deps) {
 							writeError(res, 409, "disabled skill path is outside the hub writable roots");
 							return;
 						}
-						const sourceToTrash = disabled.path.endsWith("SKILL.md.disabled") ? dirname(disabled.path) : disabled.path;
-						const trashDir = join(dirname(sourceToTrash), ".trash");
-						await mkdir(trashDir, { recursive: true });
-						const target = join(trashDir, basename(sourceToTrash) + "-" + Date.now());
-						await rename(sourceToTrash, target);
-						trashResult = {
-							path: target,
-							source: sourceToTrash
-						};
+						trashResult = await moveIntoTrash(disabled.path.endsWith("SKILL.md.disabled") ? dirname(disabled.path) : disabled.path);
 					} else {
 						writeError(res, resolved.status, resolved.error);
 						return;
@@ -3295,6 +3342,7 @@ function marketRoutes(deps) {
 			}
 			try {
 				const latestTag = await getLatestReleaseTag(source.repo);
+				lastMarketCheck.set(source.repo, now);
 				if (source.ref === void 0) {
 					results.push({
 						...base,
@@ -3305,7 +3353,6 @@ function marketRoutes(deps) {
 					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({
@@ -3350,9 +3397,11 @@ function marketRoutes(deps) {
 					return;
 				}
 				const ref = parsed.ref;
+				const slug = repoSlug(parsed);
 				writeJson(res, 200, {
 					ok: true,
-					repos: await deps.store.addMarketSource(repoSlug(parsed), ref)
+					repo: slug,
+					repos: await deps.store.addMarketSource(slug, ref)
 				});
 			}
 		},
@@ -3531,6 +3580,31 @@ function marketRoutes(deps) {
 * 仓库导入域路由：repo 发现 / repoImport 异步导入任务 / progress 轮询 /
 * cancel 取消。从 routes.ts 原样搬出，handler 逻辑不变。
 */
+/**
+* 导入去重只认「已启用」的目录，但磁盘上仍可能躺着一个已禁用的同名占位 ——
+* 禁用只是把 SKILL.md 改名成 SKILL.md.disabled，目录本身还在。这种占位不该
+* 堵住真技能：把它连同禁用记录一起移入回收站让位（issue #16）。
+*
+* 只有「禁用记录确实指向 `targetRoot/<name>` 的整目录禁用」才处理，且该目录
+* 必须已经没有 SKILL.md；其余不确定情形一律返回 false，交回原本的「跳过」。
+*/
+async function clearDisabledPlaceholder(deps, targetRoot, name) {
+	const record = await deps.store.getDisabled(name);
+	if (record === void 0) return false;
+	const dir = join(targetRoot, name);
+	const sourceToTrash = record.path.endsWith("SKILL.md.disabled") ? dirname(record.path) : record.path;
+	if (sourceToTrash !== dir) return false;
+	if (await pathExists(join(dir, "SKILL.md"))) return false;
+	const { path: target } = await moveIntoTrash(sourceToTrash);
+	await deps.store.addTrash({
+		name,
+		path: target,
+		movedAt: Date.now(),
+		sourcePath: sourceToTrash
+	});
+	await deps.store.removeDisabled(name);
+	return true;
+}
 /** 仓库导入域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 function repoImportRoutes(deps) {
 	return [
@@ -3576,7 +3650,7 @@ function repoImportRoutes(deps) {
 					ok: true,
 					repo,
 					ref: resolvedRef,
-					entries: discoverRepoEntries(tree, repo, await knownSkillNames(deps)),
+					entries: discoverRepoEntries(tree, repo, await knownSkillNames(deps, { includeDisabled: false })),
 					...truncated ? { truncated: true } : {}
 				});
 			}
@@ -3600,7 +3674,7 @@ function repoImportRoutes(deps) {
 				const repo = repoSlug(parsed);
 				const requestedRef = readString(body, "ref");
 				const { ref: resolvedRef, tree } = await loadRepoTree(repo, requestedRef !== "" ? requestedRef : parsed.ref);
-				const entries = discoverRepoEntries(tree, repo, await knownSkillNames(deps));
+				const entries = discoverRepoEntries(tree, repo, await knownSkillNames(deps, { includeDisabled: false }));
 				const byPath = new Map(entries.map((entry) => [entry.path, entry]));
 				const selected = paths.map((path) => byPath.get(path)).filter((entry) => entry !== void 0);
 				if (selected.length === 0) {
@@ -3633,6 +3707,7 @@ function repoImportRoutes(deps) {
 					imported: [],
 					skipped: [],
 					failed: [],
+					replaced: [],
 					status: "running",
 					controller,
 					createdAt: now
@@ -3659,13 +3734,22 @@ function repoImportRoutes(deps) {
 							continue;
 						}
 						if (await pathExists(join(targetRoot, entry.name))) {
-							job.skipped.push({
-								name: entry.name,
-								reason: "exists"
-							});
-							job.downloadedBytes += entry.totalBytes;
-							job.done += 1;
-							continue;
+							let cleared = false;
+							try {
+								cleared = await clearDisabledPlaceholder(deps, targetRoot, entry.name);
+							} catch {
+								cleared = false;
+							}
+							if (!cleared) {
+								job.skipped.push({
+									name: entry.name,
+									reason: "exists"
+								});
+								job.downloadedBytes += entry.totalBytes;
+								job.done += 1;
+								continue;
+							}
+							job.replaced.push(entry.name);
 						}
 						if (controller.signal.aborted) break;
 						const files = collectRepoSkillFiles(tree, entry.dir);
@@ -3748,6 +3832,7 @@ function repoImportRoutes(deps) {
 					imported: [...job.imported],
 					skipped: [...job.skipped],
 					failed: [...job.failed],
+					...job.replaced.length > 0 ? { replaced: [...job.replaced] } : {},
 					...job.error !== void 0 ? { error: job.error } : {}
 				});
 			}
@@ -4729,7 +4814,7 @@ function apply(ctx, config) {
 		}
 		return out;
 	};
-	const current = () => resolveHubConfig({}, readConfig());
+	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();

package/lib/types/client/api.d.ts

@@ -2,7 +2,7 @@
  * Browser-side API client for the /api/skill-hub route family. The only
  * data access path the panel uses — plain fetch, same origin.
  */
-import { type CatalogResponse, type ConfigResponse, type CreateRequest, type CreateResponse, type DiagnosticFixResponse, type GroupsResponse, type MarketCheckResponse, type MarketSourcesResponse, type MarketSourceVersionsResponse, type MarketStatsResponse, type MarketSyncResponse, type RepoDiscoverResponse, type RepoImportCancelResponse, type RepoImportProgressResponse, type RepoImportResponse, type SkillDetail, type SkillDeleteResponse, type SkillTag, type SourceCheckResponse, type SourceDeleteResponse, type SourceRestoreResponse, type SourceTrashClearResponse, type SourcesResponse, type SourceSyncResponse, type StatsResponse, type TagSaveRequest, type ToggleBatchResponse, type UpdateCheckResponse } from '../protocol.ts';
+import { type CatalogResponse, type ConfigResponse, type CreateRequest, type CreateResponse, type DiagnosticFixResponse, type GroupsResponse, type MarketCheckResponse, type MarketSourceAddResponse, type MarketSourcesResponse, type MarketSourceVersionsResponse, type MarketStatsResponse, type MarketSyncResponse, type RepoDiscoverResponse, type RepoImportCancelResponse, type RepoImportProgressResponse, type RepoImportResponse, type SkillDetail, type SkillDeleteResponse, type SkillTag, type SourceCheckResponse, type SourceDeleteResponse, type SourceRestoreResponse, type SourceTrashClearResponse, type SourcesResponse, type SourceSyncResponse, type StatsResponse, type TagSaveRequest, type ToggleBatchResponse, type UpdateCheckResponse } from '../protocol.ts';
 /** Error carrying the route's JSON error message. */
 export declare class SkillHubApiError extends Error {
     constructor(message: string);
@@ -31,8 +31,8 @@ export declare class SkillHubApi {
     toggleBatch(names: string[], enabled: boolean): Promise<ToggleBatchResponse>;
     /** The user's added market sources. */
     market(): Promise<MarketSourcesResponse>;
-    /** Add a market source repo; resolves with the fresh list. */
-    addMarketSource(repo: string): Promise<MarketSourcesResponse>;
+    /** Add a market source repo; resolves with the fresh list plus the resolved slug. */
+    addMarketSource(repo: string): Promise<MarketSourceAddResponse>;
     /** Remove a market source repo; resolves with the fresh list. */
     removeMarketSource(repo: string): Promise<MarketSourcesResponse>;
     /** Stars + downloads per market source (hourly server-side cache; refresh=1 refetches stale entries). */

package/lib/types/client/locales/market.d.ts

@@ -70,6 +70,7 @@ export declare const zhMarket: {
     readonly 'repo.files': "{count} 个文件 · {size}";
     readonly 'repo.imported': "导入成功 {count} 个";
     readonly 'repo.skippedExisting': "跳过已存在 {count} 个";
+    readonly 'repo.replaced': "已替换禁用占位 {count} 个（旧目录已移入回收站）";
     readonly 'repo.failed': "失败 {count} 个";
     readonly 'repo.cancel': "取消";
     readonly 'repo.cancelled': "已取消 · 已导入 {imported}/{total} 已保留，临时文件已清理";

package/lib/types/client/locales.d.ts

@@ -153,6 +153,7 @@ export declare const zh: {
     readonly 'repo.files': "{count} 个文件 · {size}";
     readonly 'repo.imported': "导入成功 {count} 个";
     readonly 'repo.skippedExisting': "跳过已存在 {count} 个";
+    readonly 'repo.replaced': "已替换禁用占位 {count} 个（旧目录已移入回收站）";
     readonly 'repo.failed': "失败 {count} 个";
     readonly 'repo.cancel': "取消";
     readonly 'repo.cancelled': "已取消 · 已导入 {imported}/{total} 已保留，临时文件已清理";

package/lib/types/protocol/config.d.ts

@@ -83,13 +83,17 @@ export declare const HUB_CONFIG_DEFAULTS: {
     readonly statsScanMinutes: 5;
 };
 /**
- * Resolve the effective hub config: saved sidecar overrides win over the
- * cordis composition entry (the web card owns runtime config), missing
- * booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
- * (saved first, then base) only when set. Numeric stats knobs are clamped to
- * their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
+ * Fill a raw settings value into the effective hub config: schema defaults for
+ * anything missing, and the numeric stats knobs clamped to sane ranges
+ * (window ≥ 0, scan interval ≥ 1 minute).
+ *
+ * There is deliberately no "saved sidecar layer" parameter. Until dsh 0.1.7 the
+ * hub kept its own runtime overrides in the sidecar and merged them here; the
+ * settings namespace is now the only user layer (`updateConfig` writes through
+ * `ctx.settings.mutate`), so a merge against a sidecar layer could never
+ * observe anything but `{}` — see the git history of `resolveHubConfig`.
  */
-export declare function resolveHubConfig(saved: Partial<HubConfig>, base?: Partial<HubConfig>): HubConfig;
+export declare function resolveHubConfig(base?: Partial<HubConfig>): HubConfig;
 /**
  * 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
@@ -112,7 +116,13 @@ export interface ConfigResponse {
     /** True when a GitHub token is in effect (saved override or the base/env layer). */
     githubTokenSet: boolean;
 }
-/** POST /api/skill-hub/config — a partial patch; omitted fields keep their values. */
+/**
+ * POST /api/skill-hub/config — a partial patch; omitted fields keep their values.
+ *
+ * Only the fields the handler actually parses belong here: the stats knobs are
+ * owned by the settings namespace (`statsWindowDays` / `statsScanMinutes` are
+ * still part of {@link HubSettingsValue}), not by this route.
+ */
 export interface ConfigRequest {
     /** Set the field; null clears the saved override so it re-inherits the default. */
     enabled?: boolean | null;
@@ -128,10 +138,6 @@ export interface ConfigRequest {
     dotModelColor?: string | null;
     /** Set the dot color; null clears the saved override so it re-inherits the default. */
     dotUserColor?: string | null;
-    /** 统计滚动窗口天数（0 = 全部历史）；null 清除覆盖回默认。 */
-    statsWindowDays?: number | null;
-    /** 自动统计扫描间隔（分钟）；null 清除覆盖回默认。 */
-    statsScanMinutes?: number | null;
     /** Set the GitHub token; null/empty clears it back to anonymous. */
     githubToken?: string | null;
 }

package/lib/types/protocol/market.d.ts

@@ -23,6 +23,17 @@ export interface MarketSourceResponse {
     ok: true;
     repos: MarketSourceRecord[];
 }
+/**
+ * POST /api/skill-hub/market/source — same list, plus the slug the host
+ * resolved from the input. Clients must scan *this* slug rather than assume
+ * the acted-on source sits at some position in `repos`: re-adding a repo the
+ * user already tracks only updates its `ref` in place and never reorders the
+ * list.
+ */
+export interface MarketSourceAddResponse extends MarketSourceResponse {
+    /** Normalized `owner/repo` the host recorded for the submitted input. */
+    repo: string;
+}
 /** POST /api/skill-hub/market/source/ref — pin a market source to an explicit ref. */
 export interface MarketSourceRefRequest {
     repo: string;

package/lib/types/protocol/repo.d.ts

@@ -96,6 +96,12 @@ export interface RepoImportProgressResponse {
         name: string;
         error: string;
     }>;
+    /**
+     * 本次导入中「让位的已禁用同名占位」名字（issue #16）：这些条目的旧目录已
+     * 移入回收站，新技能随后落地。旧目录挪走即计入，下载失败时也在列。老客户端
+     * 不认这个字段时忽略即可，故为可选。
+     */
+    replaced?: string[];
     /** error 状态时的原因 */
     error?: string;
 }

package/lib/types/protocol.d.ts

@@ -12,7 +12,7 @@ export type { WritableRoot, HubInvocation, CatalogSkill, DisabledSkill, Diagnost
 export type { SkillStat, StatsResponse, SkillStatsCheckpoint } from './protocol/stats.ts';
 export type { ErrorResponse, HubConfig, HubSettingsValue, RedactedHubConfig, ConfigResponse, ConfigRequest } from './protocol/config.ts';
 export { HUB_CONFIG_DEFAULTS, HUB_ENTRY_ID, HEX_COLOR_RE, GITHUB_TOKEN_RE, resolveHubConfig, redactGithubToken } from './protocol/config.ts';
-export type { MarketSourceRecord, MarketSourcesResponse, MarketSourceRequest, MarketSourceResponse, MarketSourceRefRequest, MarketSourceVersionsResponse, MarketStatsSnapshot, MarketStatsResponse, MarketCheckResponse, MarketSyncResponse, } from './protocol/market.ts';
+export type { MarketSourceRecord, MarketSourcesResponse, MarketSourceRequest, MarketSourceAddResponse, MarketSourceResponse, MarketSourceRefRequest, MarketSourceVersionsResponse, MarketStatsSnapshot, MarketStatsResponse, MarketCheckResponse, MarketSyncResponse, } from './protocol/market.ts';
 export type { RepoSkillEntry, RepoRoot, RepoDiscoverResponse, RepoImportRequest, RepoImportResponse, RepoImportProgressResponse, RepoImportCancelRequest, RepoImportCancelResponse, UpdateCheckResponse, } from './protocol/repo.ts';
 export type { SkillTag, CollectionGroup, GroupsResponse, TagSaveRequest, TagSaveResponse, TagDeleteRequest, TagDeleteResponse, TagMembersRequest, TagMembersResponse, TagReorderRequest, TagReorderResponse, CollectionReorderRequest, CollectionReorderResponse, SourceGroupReorderRequest, SourceGroupReorderResponse, } from './protocol/groups.ts';
 export type { SourceRecord, TrashEntry, SourcesResponse, SourceCheckRequest, SourceCheckResult, SourceCheckResponse, SourceSyncRequest, SourceSyncResponse, SourceDeleteRequest, SourceDeleteResponse, SourceRestoreRequest, SourceRestoreResponse, SourceTrashClearResponse, } from './protocol/sources.ts';