dsh-skill-hub 0.3.17 → 0.3.19

package/lib/index.js

@@ -15,13 +15,6 @@ import { randomUUID } from "node:crypto";
 */
 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
@@ -2140,7 +2133,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: {
@@ -2546,10 +2539,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;
 }
@@ -3434,11 +3435,6 @@ function marketRoutes(deps) {
 			methods: ["GET"],
 			handler: checkMarketSources
 		},
-		{
-			path: SKILL_HUB_API_DEPRECATED_MARKET_CHECK,
-			methods: ["GET"],
-			handler: checkMarketSources
-		},
 		{
 			path: SKILL_HUB_API.marketStats,
 			methods: ["GET"],
@@ -3543,6 +3539,34 @@ 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 trashDir = join(targetRoot, ".trash");
+	await mkdir(trashDir, { recursive: true });
+	const target = join(trashDir, name + "-" + Date.now());
+	await rename(sourceToTrash, target);
+	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 [
@@ -3588,7 +3612,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 } : {}
 				});
 			}
@@ -3612,7 +3636,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) {
@@ -3645,6 +3669,7 @@ function repoImportRoutes(deps) {
 					imported: [],
 					skipped: [],
 					failed: [],
+					replaced: [],
 					status: "running",
 					controller,
 					createdAt: now
@@ -3671,13 +3696,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);
@@ -3760,6 +3794,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 } : {}
 				});
 			}

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/api.d.ts

@@ -5,13 +5,6 @@
  * reads like an auth problem).
  */
 export declare 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.
- */
-export declare const SKILL_HUB_API_DEPRECATED_MARKET_CHECK = "/api/skill-hub/market/check";
 /**
  * Browser-facing base paths of the skill-hub API family.
  *

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

@@ -7,7 +7,7 @@
  * 按域拆分后的重导出入口：老 `from './protocol.ts'` 写法保持可用，
  * 新代码可按需直引 `from './protocol/<domain>.ts'`。
  */
-export { SKILL_HUB_API, SKILL_HUB_API_ROOT, SKILL_HUB_API_DEPRECATED_MARKET_CHECK } from './protocol/api.ts';
+export { SKILL_HUB_API, SKILL_HUB_API_ROOT } from './protocol/api.ts';
 export type { WritableRoot, HubInvocation, CatalogSkill, DisabledSkill, DiagnosticEntry, DiagnosticFixRequest, DiagnosticFixResponse, CatalogResponse, SkillDetail, SkillDetailResponse, SkillDeleteRequest, SkillDeleteResponse, ToggleRequest, ToggleResponse, ToggleBatchRequest, ToggleBatchResponse, CreateRequest, CreateResponse, } from './protocol/catalog.ts';
 export type { SkillStat, StatsResponse, SkillStatsCheckpoint } from './protocol/stats.ts';
 export type { ErrorResponse, HubConfig, HubSettingsValue, RedactedHubConfig, ConfigResponse, ConfigRequest } from './protocol/config.ts';

package/lib/types/routes/catalog-data.d.ts

@@ -6,8 +6,17 @@ import type { SkillDefinition } from '@deepseek-ai/dsh-skill';
 import { type CatalogResponse, type SkillDetail } from '../protocol.ts';
 import { type SkillInterface } from '../skillfs.ts';
 import { type SkillHubRouteDeps } from './deps.ts';
-/** 目录中存在的技能名集合（tag 成员校验用）：启用目录 ∪ 已禁用名单，避免成员因禁用而丢失。 */
-export declare function knownSkillNames(deps: SkillHubRouteDeps): Promise<Set<string>>;
+/**
+ * 目录中存在的技能名集合。默认（`includeDisabled` 未显式关闭）为「启用目录 ∪
+ * 已禁用名单」——tag 成员校验用：技能被禁用后不该从 tag 里掉出去。
+ *
+ * 导入去重必须传 `{ includeDisabled: false }`：禁用只意味着「暂不启用」，把它
+ * 算作「已存在」会让一次禁用产生「永久占名」的副作用，真技能再也导不进来
+ * （issue #16）。
+ */
+export declare function knownSkillNames(deps: SkillHubRouteDeps, options?: {
+    includeDisabled?: boolean;
+}): Promise<Set<string>>;
 /** 已知工作区条目（dsh 的 workspace.json 表）。 */
 export interface WorkspaceEntry {
     path: string;

package/lib/types/routes/route-state.d.ts

@@ -40,6 +40,11 @@ export interface ImportJob {
         name: string;
         error: string;
     }>;
+    /**
+     * 导入时被移入回收站让位的「已禁用同名占位」名字（issue #16）。占位已挪走
+     * 即计入，即使随后的下载失败也在列 —— 否则用户不知道自己的占位不见了。
+     */
+    replaced: string[];
     status: 'running' | 'done' | 'cancelled' | 'error';
     error?: string;
     controller: AbortController;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-hub",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "In-GUI skill hub for DeepSeek Harness (dsh): browse the full local skill catalog from the official ctx.skills registry (every root + third-party providers), toggle skills on/off, inspect bodies, surface frontmatter diagnostics, and scaffold new skills — plus a codex-style skill market (built-in catalog, upstream update checks, one-click update-all) with tracked source sync. The full manager beyond the read-only dsh-skill-manager browser.",
   "type": "module",
   "engines": {
@@ -65,7 +65,8 @@
         "0.1.7-alpha.2",
         "0.1.7-rc.1",
         "0.1.7-rc.2",
-        "0.2.0-rc.1"
+        "0.2.0-rc.1",
+        "0.2.0-rc.2"
       ]
     },
     "capability": {
@@ -113,20 +114,20 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-query": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-query": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-skill": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
     "@deepseek-ai/schemastery": "^3.18.3",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.20.0",

package/src/client/locales/market.ts

@@ -70,6 +70,7 @@ export const zhMarket = {
   'repo.files': '{count} 个文件 · {size}',
   'repo.imported': '导入成功 {count} 个',
   'repo.skippedExisting': '跳过已存在 {count} 个',
+  'repo.replaced': '已替换禁用占位 {count} 个（旧目录已移入回收站）',
   'repo.failed': '失败 {count} 个',
   'repo.cancel': '取消',
   'repo.cancelled': '已取消 · 已导入 {imported}/{total} 已保留，临时文件已清理',
@@ -151,6 +152,7 @@ export const enMarket: Record<keyof typeof zhMarket, string> = {
   'repo.files': '{count} files · {size}',
   'repo.imported': 'Imported {count}',
   'repo.skippedExisting': 'Skipped existing {count}',
+  'repo.replaced': 'Replaced {count} disabled placeholder(s) — old dir moved to trash',
   'repo.failed': 'Failed {count}',
   'repo.cancel': 'Cancel',
   'repo.cancelled': 'Cancelled · {imported}/{total} kept, temp files cleaned',

package/src/client/panel/RepoScanCard.tsx

@@ -55,7 +55,7 @@ export function RepoScanCard(props: { hub: SkillHubState }): JSX.Element | null
     // 导入后 catalog 已包含新技能，但 scan 快照的 existing 仍为 false，需用实时 catalog + 本次导入结果兜底，避免已导入仍可选
     const installedNames = new Set<string>([
       ...((hub.catalog?.skills ?? []).map((s) => s.name)),
-      ...((hub.catalog?.disabled ?? []).map((d) => d.name)),
+      // 已禁用不算「已存在」：禁用只该影响启用态，不该永久占名堵住导入（issue #16）。
       ...((repoResult?.imported ?? []).map((r) => r.name)),
       ...((repoResult?.skipped ?? []).map((r) => r.name)),
     ])
@@ -174,6 +174,7 @@ export function RepoScanCard(props: { hub: SkillHubState }): JSX.Element | null
   {repoResult !== null && repoResult.status !== 'running' ? (
     <div className={repoResult.status === 'cancelled' ? css.errorBanner + ' ' + css.actionsTop : css.formSuccess + ' ' + css.actionsTop}>
       {repoResult.status === 'cancelled' ? tt('repo.cancelled', { imported: repoResult.imported.length, total: repoResult.total }) : `${tt('repo.imported', { count: repoResult.imported.length })} · ${tt('repo.skippedExisting', { count: repoResult.skipped.length })} · ${tt('repo.failed', { count: repoResult.failed.length })}`}
+      {(repoResult.replaced?.length ?? 0) > 0 ? <span> · {tt('repo.replaced', { count: repoResult.replaced?.length ?? 0 })}</span> : null}
       {repoResult.failed.length > 0 ? <div style={{marginTop:6}}>{repoResult.failed.map(f => `${f.name}: ${f.error}`).join('; ')}</div> : null}
       {repoResult.status === 'error' && repoResult.error ? <div style={{marginTop:6}}>{repoResult.error}</div> : null}
     </div>

package/src/client/panel/panel.module.css

@@ -4,9 +4,17 @@
    on :root, with dark overrides on body[data-ds-dark-theme]). Every var()
    keeps the colour this file used before the token pass as its fallback, so a
    host without the theme package renders exactly as before. Sizes, spacing,
-   radii, fonts and layout are deliberately untouched. */
+   radii, fonts and layout are deliberately untouched.
 
-.panel { padding: 28px 20px 44px; display: flex; flex-direction: column; gap: 14px; max-width: 720px; margin: 0 auto; font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Helvetica Neue', sans-serif; -webkit-font-smoothing: antialiased; color-scheme: light dark; /* Dot colors mirror src/client/SkillHubSettingsCard.tsx (DEFAULT_DOT_MODEL_COLOR / DEFAULT_DOT_USER_COLOR) — CSS cannot import TS, so keep the two in sync. */ --hub-model: #2f81f7; --hub-user: #3fb950; /* Host theme tokens (--dsw-alias-*, dsh-client-ui-theme). Each var() carries the pre-token colour of this file as its fallback, so a missing theme package changes nothing. */ --hub-accent: var(--dsw-alias-state-business-primary, #2f81f7); --hub-text: var(--dsw-alias-label-primary, currentColor); --hub-text-2: var(--dsw-alias-label-secondary, #61666b); --hub-text-3: var(--dsw-alias-label-tertiary, #81858c); --hub-text-4: var(--dsw-alias-label-caption, #adb2b8); --hub-surface: var(--dsw-alias-bg-module-platform, rgba(128,128,128,.06)); --hub-hover: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.08)); --hub-active: var(--dsw-alias-interactive-bg-active, rgba(128,128,128,.16)); --hub-border: var(--dsw-alias-border-l2, rgba(128,128,128,.13)); --hub-border-2: var(--dsw-alias-border-l3, rgba(128,128,128,.2)); --hub-danger: var(--dsw-alias-state-error-primary, #d1242f); --hub-success: var(--dsw-alias-state-success-primary, #3fb950); --hub-warn: var(--dsw-alias-state-warn-primary, #d29922); --hub-on-accent: var(--dsw-alias-label-primary-foreground, #fff); --hub-skeleton: var(--dsw-alias-bg-skeleton, rgba(128,128,128,.1)); }
+   color-scheme is deliberately NOT declared here. The host layout writes the
+   *resolved* scheme to document.documentElement.style.colorScheme; declaring
+   `light dark` locally overrides that and makes native controls (<select>
+   popups, scrollbars) follow the *OS* preference instead — with a manually
+   selected dark theme on a light OS the <option> list renders light while
+   .select inherits light text, i.e. invisible (issue #13). Inheriting from the
+   root keeps both dark paths (manual + system) correct. */
+
+.panel { padding: 28px 20px 44px; display: flex; flex-direction: column; gap: 14px; max-width: 720px; margin: 0 auto; font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Helvetica Neue', sans-serif; -webkit-font-smoothing: antialiased; /* Dot colors mirror src/client/SkillHubSettingsCard.tsx (DEFAULT_DOT_MODEL_COLOR / DEFAULT_DOT_USER_COLOR) — CSS cannot import TS, so keep the two in sync. */ --hub-model: #2f81f7; --hub-user: #3fb950; /* Host theme tokens (--dsw-alias-*, dsh-client-ui-theme). Each var() carries the pre-token colour of this file as its fallback, so a missing theme package changes nothing. */ --hub-accent: var(--dsw-alias-state-business-primary, #2f81f7); --hub-text: var(--dsw-alias-label-primary, currentColor); --hub-text-2: var(--dsw-alias-label-secondary, #61666b); --hub-text-3: var(--dsw-alias-label-tertiary, #81858c); --hub-text-4: var(--dsw-alias-label-caption, #adb2b8); --hub-surface: var(--dsw-alias-bg-module-platform, rgba(128,128,128,.06)); --hub-hover: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.08)); --hub-active: var(--dsw-alias-interactive-bg-active, rgba(128,128,128,.16)); --hub-border: var(--dsw-alias-border-l2, rgba(128,128,128,.13)); --hub-border-2: var(--dsw-alias-border-l3, rgba(128,128,128,.2)); --hub-danger: var(--dsw-alias-state-error-primary, #d1242f); --hub-success: var(--dsw-alias-state-success-primary, #3fb950); --hub-warn: var(--dsw-alias-state-warn-primary, #d29922); --hub-on-accent: var(--dsw-alias-label-primary-foreground, #fff); --hub-skeleton: var(--dsw-alias-bg-skeleton, rgba(128,128,128,.1)); }
 .header { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; }
 .title { font-size: 24px; font-weight: 700; letter-spacing: -0.02em; margin: 0; }
 .hint { font-size: 12px; color: var(--hub-text-3); }

package/src/protocol/api.ts

@@ -6,14 +6,6 @@
  */
 export 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.
- */
-export const SKILL_HUB_API_DEPRECATED_MARKET_CHECK = '/api/skill-hub/market/check'
-
 /**
  * Browser-facing base paths of the skill-hub API family.
  *

package/src/protocol/repo.ts

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

package/src/protocol.ts

@@ -8,7 +8,7 @@
  * 新代码可按需直引 `from './protocol/<domain>.ts'`。
  */
 
-export { SKILL_HUB_API, SKILL_HUB_API_ROOT, SKILL_HUB_API_DEPRECATED_MARKET_CHECK } from './protocol/api.ts'
+export { SKILL_HUB_API, SKILL_HUB_API_ROOT } from './protocol/api.ts'
 export type {
   WritableRoot,
   HubInvocation,

package/src/repo/install.ts

@@ -34,8 +34,11 @@ export async function downloadGitHubFile(repo: string, ref: string, path: string
   }
   if (response === null || !response.ok) {
     if (signal?.aborted) throw new DOMException('aborted', 'AbortError')
-    // Fallback: api.github.com/contents with the raw media type.
-    const apiUrl = `https://api.github.com/repos/${repo}/contents/${encodedPath}`
+    // Fallback: api.github.com/contents with the raw media type. The `?ref=`
+    // is mandatory — without it /contents/ serves the default branch, so a
+    // transient raw failure would silently mix default-branch content into a
+    // tag-pinned import (issue #15).
+    const apiUrl = `https://api.github.com/repos/${repo}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`
     try {
       response = await fetchImpl(apiUrl, { headers: { accept: 'application/vnd.github.raw', ...NO_COMPRESSION, ...githubAuthHeaders() }, ...(signal !== undefined ? { signal } : {}) })
     } catch (error) {

package/src/repo.test.ts

@@ -366,6 +366,26 @@ describe('downloadGitHubFile', () => {
     expect(buffer.toString('utf8')).toContain('name: demo')
     expect(calls.length).toBe(2)
     expect(calls[1]).toContain('api.github.com/repos/example/repo/contents/skills/demo/SKILL.md')
+    expect(calls[1]).toContain('ref=main')
+  })
+
+  // issue #15: the fallback dropped the ref, so /contents/ served the default
+  // branch and a tag/branch-pinned import silently mixed main-branch content.
+  it('keeps the requested ref on the api fallback (never the default branch)', async () => {
+    const calls: string[] = []
+    const ref = 'andibrae/create-top-level-namespace'
+    const fetchImpl = async (url: string) => {
+      calls.push(url)
+      if (url.startsWith('https://raw.githubusercontent.com/')) throw new Error('raw blocked')
+      if (url.includes('/contents/')) return new Response('---\nname: demo\ndescription: x\n---\n\nref body', { status: 200 })
+      return new Response('nope', { status: 599 })
+    }
+    await downloadGitHubFile('example/repo', ref, 'skills/demo/SKILL.md', fetchImpl as typeof fetch)
+    expect(calls[1]).toBe(
+      'https://api.github.com/repos/example/repo/contents/skills/demo/SKILL.md?ref=' + encodeURIComponent(ref),
+    )
+    // The un-ref'd form is exactly what served default-branch content.
+    expect(calls[1]).not.toBe('https://api.github.com/repos/example/repo/contents/skills/demo/SKILL.md')
   })
 
   it('reports the original error when both hosts fail', async () => {

package/src/routes/catalog-data.ts

@@ -17,10 +17,21 @@ import { rootPath, readSkillInterface, scanDiagnostics, type SkillInterface } fr
 import { CURRENT_VERSION } from '../update.ts'
 import { homeOf, isWritableSource, type SkillHubRouteDeps } from './deps.ts'
 
-/** 目录中存在的技能名集合（tag 成员校验用）：启用目录 ∪ 已禁用名单，避免成员因禁用而丢失。 */
-export async function knownSkillNames(deps: SkillHubRouteDeps): Promise<Set<string>> {
+/**
+ * 目录中存在的技能名集合。默认（`includeDisabled` 未显式关闭）为「启用目录 ∪
+ * 已禁用名单」——tag 成员校验用：技能被禁用后不该从 tag 里掉出去。
+ *
+ * 导入去重必须传 `{ includeDisabled: false }`：禁用只意味着「暂不启用」，把它
+ * 算作「已存在」会让一次禁用产生「永久占名」的副作用，真技能再也导不进来
+ * （issue #16）。
+ */
+export async function knownSkillNames(
+  deps: SkillHubRouteDeps,
+  options?: { includeDisabled?: boolean },
+): Promise<Set<string>> {
   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
 }

package/src/routes/market.ts

@@ -6,7 +6,6 @@
 
 import {
   SKILL_HUB_API,
-  SKILL_HUB_API_DEPRECATED_MARKET_CHECK,
   type MarketCheckResponse,
   type MarketSourceResponse,
   type MarketSourcesResponse,
@@ -46,8 +45,7 @@ import {
 export function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
   // Update check over every market source: compares the pinned ref's commit
   // against the recorded baseline and surfaces newer releases. 5-minute
-  // throttle mirrors the source check. Shared by the canonical route and its
-  // deprecated alias, so the two can never drift apart.
+  // throttle mirrors the source check.
   const checkMarketSources: RouteHandler = async ({ res }) => {
     const sources = await deps.store.listMarketSources()
     if (lastMarketCheck.size > 500) lastMarketCheck.clear()
@@ -161,13 +159,6 @@ export function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
       methods: ['GET'],
       handler: checkMarketSources,
     },
-    // Deprecated alias, kept for one release: a browser tab still running the
-    // previous client bundle calls the old path until it reloads.
-    {
-      path: SKILL_HUB_API_DEPRECATED_MARKET_CHECK,
-      methods: ['GET'],
-      handler: checkMarketSources,
-    },
     // ------------------------------------------------------- market/stats
     // Stars + release-asset downloads per market source. Stale-while-revalidate:
     // the base call always answers from cache instantly (stale-flagged past the

package/src/routes/repo-import.ts

@@ -3,8 +3,8 @@
  * cancel 取消。从 routes.ts 原样搬出，handler 逻辑不变。
  */
 
-import { mkdir } from 'node:fs/promises'
-import { join } from 'node:path'
+import { mkdir, rename } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import {
   SKILL_HUB_API,
@@ -44,6 +44,32 @@ import {
 } from './helpers.ts'
 import { gcImportJobs, importJobs, type ImportJob } from './route-state.ts'
 
+/**
+ * 导入去重只认「已启用」的目录，但磁盘上仍可能躺着一个已禁用的同名占位 ——
+ * 禁用只是把 SKILL.md 改名成 SKILL.md.disabled，目录本身还在。这种占位不该
+ * 堵住真技能：把它连同禁用记录一起移入回收站让位（issue #16）。
+ *
+ * 只有「禁用记录确实指向 `targetRoot/<name>` 的整目录禁用」才处理，且该目录
+ * 必须已经没有 SKILL.md；其余不确定情形一律返回 false，交回原本的「跳过」。
+ */
+async function clearDisabledPlaceholder(deps: SkillHubRouteDeps, targetRoot: string, name: string): Promise<boolean> {
+  const record = await deps.store.getDisabled(name)
+  if (record === undefined) 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
+  // 目录里还有 SKILL.md 说明它其实是启用态的真实技能，不动。
+  if (await pathExists(join(dir, 'SKILL.md'))) return false
+  // 与 skill/delete 的回收站语义一致：同级 .trash/ 下按「名字-时间戳」落盘，可恢复。
+  const trashDir = join(targetRoot, '.trash')
+  await mkdir(trashDir, { recursive: true })
+  const target = join(trashDir, name + '-' + Date.now())
+  await rename(sourceToTrash, target)
+  await deps.store.addTrash({ name, path: target, movedAt: Date.now(), sourcePath: sourceToTrash })
+  await deps.store.removeDisabled(name)
+  return true
+}
+
 /** 仓库导入域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
   return [
@@ -86,7 +112,8 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           }
         }
         const { ref: resolvedRef, tree, truncated } = await loadRepoTree(repo, ref)
-        const existing = await knownSkillNames(deps)
+        // 发现态也只看「已启用」：否则已禁用占位会把真技能标成「已存在」并禁掉勾选（issue #16）。
+        const existing = await knownSkillNames(deps, { includeDisabled: false })
         const entries = discoverRepoEntries(tree, repo, existing)
         writeJson(res, 200, { ok: true, repo, ref: resolvedRef, entries, ...(truncated ? { truncated: true } : {}) } satisfies RepoDiscoverResponse)
       },
@@ -108,7 +135,8 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         const requestedRef = readString(body, 'ref')
         const ref = requestedRef !== '' ? requestedRef : parsed.ref
         const { ref: resolvedRef, tree } = await loadRepoTree(repo, ref)
-        const existing = await knownSkillNames(deps)
+        // 导入去重同 discover：已禁用不算「已存在」（issue #16）。
+        const existing = await knownSkillNames(deps, { includeDisabled: false })
         const entries = discoverRepoEntries(tree, repo, existing)
         // truncated tree is still usable for the selected paths the user already picked from the prior discover response
         const byPath = new Map(entries.map((entry) => [entry.path, entry]))
@@ -139,6 +167,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           imported: [],
           skipped: [],
           failed: [],
+          replaced: [],
           status: 'running',
           controller,
           createdAt: now,
@@ -166,11 +195,25 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
               job.done += 1
               continue
             }
+            // 磁盘上有同名目录。若它只是一个已禁用的占位（目录里只剩
+            // SKILL.md.disabled），先把旧目录移入回收站再继续导入；移不动或
+            // 不是这种形态时退回原本的「跳过」（issue #16）。
             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)
@@ -241,6 +284,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           imported: [...job.imported],
           skipped: [...job.skipped],
           failed: [...job.failed],
+          ...(job.replaced.length > 0 ? { replaced: [...job.replaced] } : {}),
           ...(job.error !== undefined ? { error: job.error } : {}),
         } satisfies RepoImportProgressResponse)
       },

package/src/routes/route-state.test.ts

@@ -16,6 +16,7 @@ function job(jobId: string, createdAt: number, status: ImportJob['status'] = 'do
     imported: [],
     skipped: [],
     failed: [],
+    replaced: [],
     status,
     controller: new AbortController(),
     createdAt,

package/src/routes/route-state.ts

@@ -51,6 +51,11 @@ export interface ImportJob {
   imported: Array<{ name: string; origin: string; path: string }>
   skipped: Array<{ name: string; reason: 'exists' }>
   failed: Array<{ name: string; error: string }>
+  /**
+   * 导入时被移入回收站让位的「已禁用同名占位」名字（issue #16）。占位已挪走
+   * 即计入，即使随后的下载失败也在列 —— 否则用户不知道自己的占位不见了。
+   */
+  replaced: string[]
   status: 'running' | 'done' | 'cancelled' | 'error'
   error?: string
   controller: AbortController