dsh-skill-hub 0.3.20 → 0.3.22

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

@@ -21,7 +21,7 @@ export declare const zhSettings: {
     readonly 'settings.statsScanMinutes': "自动统计间隔（分钟）";
     readonly 'settings.statsScanMinutesHint': "后台扫描会话日志的间隔，最小 1 分钟；扫描耗时会自动拉长间隔。";
     readonly 'settings.githubToken': "GitHub Token";
-    readonly 'settings.githubTokenHint': "市场/来源走 GitHub API，匿名每小时 60 次，填 token 后 5000 次。细粒度 token 无需任何权限。明文存本地设置，仅回环可读；留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。";
+    readonly 'settings.githubTokenHint': "市场/来源走 GitHub API，匿名每小时 60 次，填 token 后 5000 次。细粒度 token 无需任何权限。明文存本地设置，仅经 dsh 的 /api 信任栅栏可读（回环 / 绑定地址 / --trusted-host）；留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。";
     readonly 'settings.githubTokenPlaceholder': "ghp_… / github_pat_…（留空为匿名）";
     readonly 'settings.inherit': "继承";
     readonly 'settings.overridden': "已覆盖";

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

@@ -26,7 +26,7 @@ export declare const zh: {
     readonly 'settings.statsScanMinutes': "自动统计间隔（分钟）";
     readonly 'settings.statsScanMinutesHint': "后台扫描会话日志的间隔，最小 1 分钟；扫描耗时会自动拉长间隔。";
     readonly 'settings.githubToken': "GitHub Token";
-    readonly 'settings.githubTokenHint': "市场/来源走 GitHub API，匿名每小时 60 次，填 token 后 5000 次。细粒度 token 无需任何权限。明文存本地设置，仅回环可读；留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。";
+    readonly 'settings.githubTokenHint': "市场/来源走 GitHub API，匿名每小时 60 次，填 token 后 5000 次。细粒度 token 无需任何权限。明文存本地设置，仅经 dsh 的 /api 信任栅栏可读（回环 / 绑定地址 / --trusted-host）；留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。";
     readonly 'settings.githubTokenPlaceholder': "ghp_… / github_pat_…（留空为匿名）";
     readonly 'settings.inherit': "继承";
     readonly 'settings.overridden': "已覆盖";

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

@@ -57,7 +57,7 @@ export type HubSettingsValue = {
     statsWindowDays?: number;
     /** 自动统计扫描间隔（分钟）。 */
     statsScanMinutes?: number;
-    /** GitHub token（明文存本地设置文档，仅回环可读；缺省为匿名）。 */
+    /** GitHub token（明文存本地设置文档，仅经 dsh 的 /api 信任栅栏可读；缺省为匿名）。 */
     githubToken?: string;
 };
 /**

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

@@ -134,6 +134,11 @@ export interface SourceTrashClearResponse {
         name: string;
         error: string;
     }>;
+    /**
+     * `.trash` 里没有对应记录的残留目录（同名技能先后两次入站时，旧记录被覆盖，
+     * 目录却留了下来）。清空回收站时一并回收，这里上报它们的路径；没有则省略。
+     */
+    orphans?: string[];
 }
 /** 项目级技能来源（它们有 workspace 归属，不属于「个人」组）。 */
 export declare function isProjectSource(source: string): boolean;

package/lib/types/reconcile.d.ts

@@ -15,6 +15,10 @@ export interface DisabledReconcileStore {
     listDisabled(): Promise<DisabledSkill[]>;
     addDisabled(entry: DisabledSkill): Promise<void>;
 }
+/** Narrow store view used by the reverse reconcile (adds record removal). */
+export interface DisabledPruneStore extends DisabledReconcileStore {
+    removeDisabled(name: string): Promise<void>;
+}
 /**
  * Add sidecar disabled records for every `.disabled` discovery file that has
  * none yet. Existing records (matched by path or by name) win, so this never
@@ -22,3 +26,23 @@ export interface DisabledReconcileStore {
  * in the diagnostics scan instead). Returns the records added.
  */
 export declare function reconcileDisabledSkills(store: DisabledReconcileStore, home?: string): Promise<DisabledSkill[]>;
+/** 反向对账的结果：修好路径的记录 + 被清掉的死记录。 */
+export interface DisabledPruneResult {
+    /** 记录还在、但 path 指向的文件已不在：已改指向现存的 `.disabled` 文件。 */
+    repaired: DisabledSkill[];
+    /** 文件与禁用占位都已不存在：记录已删除，名字被释放。 */
+    removed: string[];
+}
+/**
+ * 反向对账：`reconcileDisabledSkills` 只处理「磁盘有 `.disabled`、sidecar 没记录」。
+ * 反方向（sidecar 有记录、磁盘上那个文件已经不在了）以前永不清理，于是留下一条
+ * 干掉不掉的记录：`/toggle` 启用会 rename 失败，`/create` 被 409 挡住，`/skill/delete`
+ * 也 rename 失败 —— 名字被永久锁死（issue #16 类，实测 G5）。
+ *
+ * 两种处理，都不动启用态技能：
+ * - 名字在该 root 下仍有 `.disabled` 占位（目录包或扁平形态）→ 把记录指向真实文件；
+ * - 一个都没有 → 删记录，把名字还给用户。
+ *
+ * 只处理合法可写 root 的记录；root 值异常（历史损坏数据）时原样保留，不擅自删。
+ */
+export declare function pruneStaleDisabledSkills(store: DisabledPruneStore, home?: string): Promise<DisabledPruneResult>;

package/lib/types/routes/deps.d.ts

@@ -1,11 +1,12 @@
 /**
  * routes 共享层 · 依赖视图：路由依赖接口、配置解析与可写技能解析（HTTP
- * 围栏在 ./http.ts）。从 helpers.ts 原样搬出，行为不变。
+ * 围栏在 ./http.ts）。
  */
 import type { ServerResponse } from 'node:http';
 import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill';
 import { type HubConfig, type WritableRoot } from '../protocol.ts';
 import { type SkillHubStore } from '../store.ts';
+import { type RouteFence } from './http.ts';
 /** Sources the hub may toggle (the user-level filesystem roots). */
 export declare function isWritableSource(source: string): source is WritableRoot;
 /** Lookup options the hub forwards to the registry (cwd selects project roots). */
@@ -22,6 +23,12 @@ export interface SkillHubRouteDeps {
         get(name: string, options?: SkillLookupLike): Promise<SkillDefinition | undefined>;
     };
     store: SkillHubStore;
+    /**
+     * Request fence for the whole family: returns the rejection status (401/403)
+     * or `undefined` to proceed. Production passes the host's own `/api` fence
+     * (`ctx.connection.requestRejection`); absent falls back to literal loopback.
+     */
+    fence?: RouteFence;
     /** DSH home override (tests isolate the writable roots; defaults to ~/.dsh). */
     home?: string;
     /** Invalidate the registry catalog cache after hub-driven mutations. */

package/lib/types/routes/helpers.d.ts

@@ -1,15 +1,15 @@
 /**
- * routes 共享层：请求围栏（回环信任/方法/总开关/JSON 体）、统一错误映射、
- * 可写技能解析、目录/分组数据装配。handler 只写业务，从这里 import。
- * 从 routes.ts 原样搬出，行为不变。
- * 本文件是聚合出口（barrel）：实现按域拆到 ./http.ts（围栏/错误映射/读体）、
+ * routes 共享层：请求栅栏（宿主 /api 信任模型 → 方法 → 总开关 → JSON 体）、
+ * 统一错误映射、可写技能解析、目录/分组数据装配。handler 只写业务，从这里 import。
+ * 本文件是聚合出口（barrel）：实现按域拆到 ./http.ts（栅栏/错误映射/读体）、
  * ./deps.ts（依赖视图/可写解析）、./collection.ts（集合装配）、
  * ./catalog-data.ts（目录装配）；对外导出面保持不变。
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { WebRoute, WebRouteKind } from '@deepseek-ai/dsh-host-webserver';
 import { type SkillHubRouteDeps } from './deps.ts';
-export { MAX_JSON_BODY_BYTES, STORE_ERROR_STATUS, isLoopbackRequest, pathExists, queryParam, readJsonBody, readString, readStrings, writeError, writeJson, writeRouteError, } from './http.ts';
+export { MAX_JSON_BODY_BYTES, STORE_ERROR_STATUS, isLoopbackRequest, loopbackOnlyFence, pathExists, queryParam, readJsonBody, readString, readStrings, writeError, writeJson, writeRouteError, } from './http.ts';
+export type { RouteFence } from './http.ts';
 export { configOf, disabledGate, homeOf, isWritableSource, resolveWritableSkill, savedOf, } from './deps.ts';
 export type { SkillHubRouteDeps, SkillLookupLike, WritableSkill, WritableSkillRefusal, WritableSkillResult, } from './deps.ts';
 export { buildCollections, buildGroups } from './collection.ts';
@@ -45,8 +45,13 @@ export interface RouteSpec {
 }
 /**
  * Wrap one handler in the shared request fences. Order matches the
- * original per-handler prologue: loopback trust → HTTP method → master
+ * original per-handler prologue: trust fence → HTTP method → master
  * switch → JSON body. The outer catch maps errors onto the JSON error
  * body (preserving RepoFetchError status codes).
+ *
+ * The trust fence is the host's `/api` model (`deps.fence`) whenever the
+ * composition mounts Connection, so a reverse-proxied deployment is judged by
+ * the same authorities dsh already trusts; without that service the historical
+ * literal-loopback check stands in.
  */
 export declare function createRoute(deps: SkillHubRouteDeps, spec: RouteSpec): WebRoute;

package/lib/types/routes/http.d.ts

@@ -1,12 +1,37 @@
 /**
- * routes 共享层 · HTTP 围栏：回环信任检查、JSON 响应与错误映射、请求体读取、
- * 查询/字段读取与文件存在性检查。从 helpers.ts 原样搬出，行为不变。
+ * routes 共享层 · HTTP 围栏：请求信任栅栏（复用宿主 `/api` 模型，见 RouteFence）、
+ * JSON 响应与错误映射、请求体读取、查询/字段读取与文件存在性检查。
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 /** Cap on JSON request bodies (toggle/create payloads are tiny). */
 export declare const MAX_JSON_BODY_BYTES: number;
 /** Loopback literal check plus browser same-origin markers. */
 export declare function isLoopbackRequest(request: IncomingMessage): boolean;
+/**
+ * The route family's request fence: the HTTP status a request is rejected
+ * with (`401` unauthenticated / `403` untrusted authority), or `undefined`
+ * when it may reach the handler.
+ *
+ * dsh owns **one** browser-trust model for the whole `/api` tree — loopback,
+ * the listener's own bind address, every `--trusted-host` authority, then the
+ * browser session — and publishes it as `ctx.connection.requestRejection`,
+ * whose contract is written for exactly this case ("apply Connection's
+ * Host/Origin checks ... to another Web route"). Our paths are exact routes
+ * registered beside the shared `/api` prefix, so the host's own fence never
+ * sees them; asking its entry point instead of re-deriving the rule keeps a
+ * single trust model rather than a second, stricter one. Issue #17 is what the
+ * second one cost: behind a reverse proxy the literals checkable in this file
+ * are the gateway address and the public domain, so every route answered 403
+ * while the rest of the GUI worked.
+ */
+export type RouteFence = (request: IncomingMessage) => number | undefined;
+/**
+ * Fallback fence for a host that mounts no Connection service (unit tests, and
+ * any composition serving the webserver alone): the historical literal-loopback
+ * check, so a missing service degrades to the previous behaviour instead of an
+ * open or a dead route family.
+ */
+export declare function loopbackOnlyFence(request: IncomingMessage): number | undefined;
 /** One JSON response. */
 export declare function writeJson(res: ServerResponse, status: number, body: unknown): void;
 /** One JSON error response. */

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

@@ -54,5 +54,25 @@ export declare const importJobs: Map<string, ImportJob>;
 export declare const IMPORT_JOB_TTL_MS: number;
 export declare const IMPORT_JOB_MAX = 100;
 export declare function gcImportJobs(): void;
-/** Replace one skill directory with a fresh download; restores the old dir on failure. */
-export declare function replaceSkillDir(targetDir: string, download: () => Promise<void>): Promise<void>;
+/**
+ * Replace whatever currently occupies a skill slot with a fresh download;
+ * restores the previous state on failure.
+ *
+ * `target` is the entry to move aside — a bundle **directory** or a flat
+ * `<name>.md` file, whichever the download is replacing (the rename/rm below
+ * are form-neutral). The backup is dot-prefixed (discovery skips dot entries),
+ * so even a failed cleanup can never register as a duplicate skill.
+ */
+export declare function replaceInPlace(target: string, download: () => Promise<unknown>): Promise<void>;
+/**
+ * 让位：把一个名字下的「非启用态占位」移入回收站并清掉它的 sidecar 禁用记录。
+ * 只动这两类，**启用的技能一律不碰**：
+ * - 禁用发现文件（`<name>/SKILL.md.disabled` 或 `<name>.md.disabled`，两种形态都认）；
+ * - 同名目录存在但既无 `SKILL.md` 也无 `SKILL.md.disabled`（导入中断/手工删除的空壳）。
+ *
+ * 回收站按名字索引，所以多形态只会记下最后一条的恢复指针；其余的那份会在
+ * 「清空回收站」时被孤儿回收扫掉（见 sourceTrashClear）。
+ *
+ * @returns 被移入回收站的路径列表，没有可让位的东西时 undefined。
+ */
+export declare function retireNamePlaceholders(deps: SkillHubRouteDeps, base: string, name: string): Promise<string[] | undefined>;

package/lib/types/routes.d.ts

@@ -3,20 +3,45 @@
  * official registry + hub-disabled skills + discovery diagnostics), skill
  * detail, enable/disable toggle, new-skill scaffold, user groups (tags +
  * origin collections), and upstream source tracking (check/sync/follow
- * upstream deletion into a restorable trash). Every route carries a
- * loopback-only trust fence — these endpoints rename files under the user's
- * skill roots, so LAN-exposed dsh web deployments must not serve them.
+ * upstream deletion into a restorable trash). Every route carries the host's
+ * own `/api` trust fence (loopback, the listener's bind address, each
+ * `--trusted-host` authority, then the browser session) — these endpoints
+ * rename files under the user's skill roots, so they must never be laxer than
+ * the GUI around them (issue #17).
  *
  * 按域拆分后的聚合入口：各域 handler 在 ./routes/<domain>.ts，共享围栏在
  * ./routes/helpers.ts，节流/任务状态在 ./routes/route-state.ts。
  * 老 `from './routes.ts'`（makeRoutes + SkillHubRouteDeps）保持可用。
  */
+import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import { type SkillHubRouteDeps } from './routes/helpers.ts';
+import { type RouteFence } from './routes/http.ts';
 export type { SkillHubRouteDeps, SkillLookupLike } from './routes/helpers.ts';
+export type { RouteFence } from './routes/http.ts';
+/**
+ * Build the family's trust fence from the host's `/api` model.
+ *
+ * `ctx.connection.requestRejection` is the documented hook for fencing another
+ * Web route; with no Connection service (a webserver-only composition, or a
+ * unit test) the literal-loopback check stands in, so the fallback is the old
+ * behaviour rather than an open route family.
+ *
+ * The service is read **per request**, not once at mount: plugins start in
+ * composition order, so a one-shot read at `apply()` time would latch the
+ * fallback whenever this plugin happens to come up before Connection. A
+ * persistent absence is almost certainly an upstream composition change rather
+ * than a transient startup order, so the first miss fires `onMissing` once —
+ * without that signal the fallback would silently reproduce issue #17 after
+ * any future upstream rename of the service.
+ * @param read - resolves `ctx.connection`, or `undefined` when absent.
+ * @param onMissing - called once, the first time the service reads absent.
+ * @returns the fence every route in this family runs first.
+ */
+export declare function hostTrustFence(read: () => HostConnectionHandle | undefined, onMissing?: () => void): RouteFence;
 /**
  * Build every /api/skill-hub route.
- * @param deps - skill registry view + sidecar store.
+ * @param deps - skill registry view + sidecar store + trust fence.
  * @returns the exact-path routes plus the family's 404 catch-all.
  */
 export declare function makeRoutes(deps: SkillHubRouteDeps): WebRoute[];

package/lib/types/skillfs/scan.d.ts

@@ -46,3 +46,29 @@ export declare function findProjectRoot(cwd: string): Promise<string>;
  * a defect.
  */
 export declare function scanDiagnostics(root: WritableRoot, home?: string): Promise<DiagnosticEntry[]>;
+/**
+ * 某个名字在一个 root 下现存的禁用发现文件（两种形态都认），没有则 undefined。
+ * 目录包形态优先（`<name>/SKILL.md.disabled`），其次扁平 `<name>.md.disabled`。
+ * 单点定义「禁用态在磁盘上长什么样」，避免各处再拼一次路径（issue #16 类）。
+ */
+export declare function disabledOccupancyIn(base: string, name: string): Promise<string | undefined>;
+/**
+ * 一个名字在某个 root 下的全部磁盘占位。技能名是系统里唯一的身份，但同一个名字
+ * 可以被两种形态（目录包 `<name>/SKILL.md` / 扁平 `<name>.md`）× 两种状态
+ * （启用 / `.disabled` 改名）占据，而且两种形态可以**同时存在** —— 注册表只会
+ * 给出其中一个，另一个静默不可达。所有按名字操作文件的路径都应该从这里取值，
+ * 而不是各自拼一次路径（issue #16 类的根因）。
+ *
+ * 两个数组都按「目录包优先」排序：目录包是 hub 自己写入的形态（导入、创建、
+ * 同步都建目录包），冲突时它是更「权威」的那份。
+ */
+export interface NameOccupancy {
+    /** 启用态发现文件（目录包 `<name>/SKILL.md` 在前，扁平 `<name>.md` 在后）。 */
+    enabled: string[];
+    /** 禁用态发现文件（`<name>/SKILL.md.disabled` 在前，`<name>.md.disabled` 在后）。 */
+    disabled: string[];
+    /** `<name>/` 存在，但既没有 `SKILL.md` 也没有 `SKILL.md.disabled`（空壳/残留目录）。 */
+    bareDir?: string;
+}
+/** 读一个名字在某个 skills root 下的全部占位。只读，不修改磁盘。 */
+export declare function occupancyOf(base: string, name: string): Promise<NameOccupancy>;

package/lib/types/skillfs.d.ts

@@ -45,11 +45,19 @@ export declare function moveIntoTrash(source: string): Promise<{
     path: string;
     source: string;
 }>;
+/**
+ * The filesystem entry behind a discovery file: a directory bundle is addressed
+ * by its `SKILL.md` (or `SKILL.md.disabled`) and moved as a whole directory, a
+ * flat `<name>.md` file is moved as itself. Single definition of that mapping —
+ * delete, restore, sync-replace and placeholder retirement must all agree on it,
+ * or one of them moves a bundle's discovery file and leaves an empty directory.
+ */
+export declare function trashSourceOf(discoveryPath: string): string;
 /**
  * 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.
+ * SKILL.md (or SKILL.md.disabled) path and moved as a whole directory.
  * @returns the trashed path plus the original path that was moved.
  */
 export declare function trashSkill(sourcePath: string): Promise<{

package/lib/types/store/migrate.d.ts

@@ -31,7 +31,7 @@ export interface HydratedState {
     tagsById: Map<string, SkillTag>;
     sourcesByRepo: Map<string, SourceRecord>;
     marketSources: MarketSourceRecord[];
-    trashByName: Map<string, TrashEntry>;
+    trashByPath: Map<string, TrashEntry>;
     skillStats: SkillStatsCheckpoint | undefined;
     marketStats: MarketStatsSnapshot | undefined;
     collectionOrder: string[];

package/lib/types/store/store.d.ts

@@ -7,7 +7,7 @@ export declare class SkillHubStore {
     private tagsById;
     private sourcesByRepo;
     private marketSources;
-    private trashByName;
+    private trashByPath;
     private skillStats;
     private marketStats;
     private collectionOrder;
@@ -119,12 +119,17 @@ export declare class SkillHubStore {
     setMarketSourceCommit(repo: string, commitSha: string): Promise<void>;
     /** All trashed skills, newest first. */
     listTrash(): Promise<TrashEntry[]>;
-    /** One trash entry by skill name (undefined when absent). */
+    /** One trash entry by skill name — the newest when a name has several. */
     getTrash(name: string): Promise<TrashEntry | undefined>;
-    /** Record a trashed skill. */
+    /**
+     * Record a trashed skill, keyed by its trashed path. Keying by name used to
+     * silently drop the previous record when the same name landed in the trash
+     * twice (a re-delete, or the two on-disk discovery forms), orphaning its
+     * directory with nothing left pointing at it.
+     */
     addTrash(entry: TrashEntry): Promise<void>;
-    /** Remove a trash record (after restore). */
-    removeTrash(name: string): Promise<void>;
+    /** Remove a trash record by its trashed path (after restore or permanent clear). */
+    removeTrash(path: string): Promise<void>;
     /** The persisted usage-statistics checkpoint (undefined until first saved). */
     getSkillStatsState(): Promise<SkillStatsCheckpoint | undefined>;
     /** Persist a usage-statistics checkpoint (after every completed scan; cadence follows the scan TTL). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-hub",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "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": {

package/src/client/locales/settings.ts

@@ -21,7 +21,7 @@ export const zhSettings = {
   'settings.statsScanMinutes': '自动统计间隔（分钟）',
   'settings.statsScanMinutesHint': '后台扫描会话日志的间隔，最小 1 分钟；扫描耗时会自动拉长间隔。',
   'settings.githubToken': 'GitHub Token',
-  'settings.githubTokenHint': '市场/来源走 GitHub API，匿名每小时 60 次，填 token 后 5000 次。细粒度 token 无需任何权限。明文存本地设置，仅回环可读；留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。',
+  'settings.githubTokenHint': '市场/来源走 GitHub API，匿名每小时 60 次，填 token 后 5000 次。细粒度 token 无需任何权限。明文存本地设置，仅经 dsh 的 /api 信任栅栏可读（回环 / 绑定地址 / --trusted-host）；留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。',
   'settings.githubTokenPlaceholder': 'ghp_… / github_pat_…（留空为匿名）',
   'settings.inherit': '继承',
   'settings.overridden': '已覆盖',
@@ -59,7 +59,7 @@ export const enSettings: Record<keyof typeof zhSettings, string> = {
   'settings.statsScanMinutes': 'Auto stats interval (minutes)',
   'settings.statsScanMinutesHint': 'How often the background session-log scan runs (min 1); heavy scans automatically stretch it.',
   'settings.githubToken': 'GitHub token',
-  'settings.githubTokenHint': 'Market/sources use the GitHub API: 60 req/h anonymous, 5000/hr with a token. A fine-grained token needs no permissions. Stored plaintext in local settings, loopback-only; empty means anonymous (or GITHUB_TOKEN env).',
+  'settings.githubTokenHint': 'Market/sources use the GitHub API: 60 req/h anonymous, 5000/hr with a token. A fine-grained token needs no permissions. Stored plaintext in local settings, reachable only through dsh\'s /api trust fence (loopback / bind address / --trusted-host); empty means anonymous (or GITHUB_TOKEN env).',
   'settings.githubTokenPlaceholder': 'ghp_… / github_pat_… (empty = anonymous)',
   'settings.inherit': 'Inherit',
   'settings.overridden': 'Overridden',

package/src/index.ts

@@ -14,6 +14,8 @@ import type { SettingsForms, SettingsNamespace, SettingsPathOp } from '@deepseek
 // loader's `fiber.runtime.Config` handling) only exist here. Every official
 // plugin imports it under this name.
 import z from '@deepseek-ai/schemastery'
+// Type-only, for the `ctx.connection` augmentation (the `/api` trust fence).
+import type {} from '@deepseek-ai/dsh-client-connection'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-skill'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -21,10 +23,10 @@ import type {} from '@deepseek-ai/dsh-session-query'
 import type {} from '@deepseek-ai/dsh-settings'
 import { HUB_CONFIG_DEFAULTS, HUB_ENTRY_ID, HEX_COLOR_RE, resolveHubConfig, type HubConfig } from './protocol.ts'
 import { SkillHubProvider } from './provider.ts'
-import { makeRoutes } from './routes.ts'
+import { hostTrustFence, makeRoutes } from './routes.ts'
 import { createSkillStatsReader, asPersistenceSeam, type SessionPersistenceLike, type SessionQueryLike, type SkillStatsReader } from './stats.ts'
 import { SkillHubStore } from './store.ts'
-import { reconcileDisabledSkills } from './reconcile.ts'
+import { reconcileDisabledSkills, pruneStaleDisabledSkills } from './reconcile.ts'
 import { cleanupLeftoverImportDirs, setGithubToken } from './repo.ts'
 import { dshHome } from './store.ts'
 import { join } from 'node:path'
@@ -132,8 +134,8 @@ const SECTION_ORDER = 152
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
 export 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.'
+  '本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；本插件的配置页（启用/公告开关、圆点颜色、GitHub token、统计窗口）在插件管理页——侧边栏「插件」→ 本插件，是本插件自己注册的配置卡片（默认折叠，点标题展开）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由受 dsh 自身的 /api 信任栅栏保护（回环、监听器绑定地址、--trusted-host 声明的 authority，外加浏览器会话认证），因此反代部署下与 GUI 同一套放行规则。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。',
+  '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; the routes sit behind dsh\'s own /api trust fence (loopback, the listener\'s bind address, any --trusted-host authority, plus browser-session authentication), so a reverse-proxied deployment is judged exactly like the GUI around it. 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')
 
 /**
@@ -262,6 +264,16 @@ export function apply(ctx: Context, config?: Config): void {
         const disposers = makeRoutes({
           skills: ctx.skills,
           store,
+          // The host's own `/api` trust fence (loopback ∪ bind address ∪
+          // --trusted-host ∪ browser session). Read per request: Connection
+          // may be provided after this plugin starts, and a one-shot read here
+          // would latch the literal-loopback fallback for the whole process.
+          // A *persistent* absence means the upstream composition changed —
+          // say so once instead of silently re-creating issue #17.
+          fence: hostTrustFence(
+            () => ctx.get('connection'),
+            () => ctx.logger.warn('[dsh-skill-hub] Connection service absent: routes fall back to literal-loopback; reverse-proxy deployments will 403 until it mounts'),
+          ),
           invalidate: () => { providerControl?.invalidate() },
           stats,
           config: current,
@@ -307,6 +319,16 @@ export function apply(ctx: Context, config?: Config): void {
     } catch (error) {
       ctx.logger.warn('[dsh-skill-hub] startup disabled-skill reconcile failed', error)
     }
+    // 反向对账：记录还在、文件已不在 → 修路径或删记录。不做这一步，那条记录会
+    // 把名字永久锁死（启用/新建/删除三条路都失败）。
+    try {
+      const pruned = await pruneStaleDisabledSkills(store, home)
+      if (pruned.repaired.length > 0 || pruned.removed.length > 0) {
+        ctx.logger.info(`[dsh-skill-hub] startup pruned disabled records: repaired ${pruned.repaired.length} (${pruned.repaired.map((entry) => entry.name).join(', ') || '-'}), removed ${pruned.removed.length} (${pruned.removed.join(', ') || '-'})`)
+      }
+    } catch (error) {
+      ctx.logger.warn('[dsh-skill-hub] startup disabled-record prune failed', error)
+    }
   })()
 
   void (async () => {

package/src/protocol/config.ts

@@ -60,7 +60,7 @@ export type HubSettingsValue = {
   statsWindowDays?: number
   /** 自动统计扫描间隔（分钟）。 */
   statsScanMinutes?: number
-  /** GitHub token（明文存本地设置文档，仅回环可读；缺省为匿名）。 */
+  /** GitHub token（明文存本地设置文档，仅经 dsh 的 /api 信任栅栏可读；缺省为匿名）。 */
   githubToken?: string
 }
 

package/src/protocol/sources.ts

@@ -138,6 +138,11 @@ export interface SourceTrashClearResponse {
   deleted: string[]
   /** 未能删除的技能（保留在回收站中）。 */
   failed: Array<{ name: string; error: string }>
+  /**
+   * `.trash` 里没有对应记录的残留目录（同名技能先后两次入站时，旧记录被覆盖，
+   * 目录却留了下来）。清空回收站时一并回收，这里上报它们的路径；没有则省略。
+   */
+  orphans?: string[]
 }
 
 /** 项目级技能来源（它们有 workspace 归属，不属于「个人」组）。 */

package/src/reconcile.test.ts

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { reconcileDisabledSkills } from './reconcile.ts'
+import { pruneStaleDisabledSkills, reconcileDisabledSkills } from './reconcile.ts'
 import { SkillHubStore, statePath } from './store.ts'
 
 describe('reconcileDisabledSkills', () => {
@@ -73,4 +73,77 @@ describe('reconcileDisabledSkills', () => {
     expect(await reconcileDisabledSkills(store, home)).toEqual([])
     expect(await store.listDisabled()).toHaveLength(1)
   })
+
+  it('reconciles a root-level SKILL.md.disabled (a flat skill literally named SKILL)', async () => {
+    // scanRoot 会把根级 SKILL.md 文件当一个扁平技能，它的禁用对应物就不能被漏掉。
+    await writeFile(join(home, 'skills', 'SKILL.md.disabled'), '---\nname: root-flat\ndescription: Root flat\n---', 'utf8')
+    const added = await reconcileDisabledSkills(store, home)
+    expect(added.map((entry) => entry.name)).toEqual(['root-flat'])
+    expect((await store.getDisabled('root-flat'))?.path).toBe(join(home, 'skills', 'SKILL.md.disabled'))
+  })
+})
+
+describe('pruneStaleDisabledSkills', () => {
+  let dir: string
+  let home: string
+  let agentsHome: string
+  let previousAgentsHome: string | undefined
+  let store: SkillHubStore
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-prune-'))
+    home = join(dir, 'home')
+    agentsHome = join(dir, 'agents')
+    await mkdir(join(home, 'skills'), { recursive: true })
+    await mkdir(join(agentsHome, 'skills'), { recursive: true })
+    previousAgentsHome = process.env.DSH_AGENTS_HOME
+    process.env.DSH_AGENTS_HOME = agentsHome
+    store = new SkillHubStore(statePath(home))
+  })
+
+  afterEach(async () => {
+    if (previousAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME
+    else process.env.DSH_AGENTS_HOME = previousAgentsHome
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('drops a record whose file is gone and frees the name', async () => {
+    await store.addDisabled({ name: 'ghost', description: 'x', path: join(home, 'skills', 'ghost', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result).toEqual({ repaired: [], removed: ['ghost'] })
+    expect(await store.listDisabled()).toEqual([])
+  })
+
+  it('repoints a record to the surviving flat placeholder instead of dropping it', async () => {
+    // 记录指目录形态，磁盘上只剩扁平形态（导入让位过一次的典型残留）。
+    await writeFile(join(home, 'skills', 'code-review.md.disabled'), '---\nname: code-review\ndescription: stub\n---', 'utf8')
+    await store.addDisabled({ name: 'code-review', description: 'stub', path: join(home, 'skills', 'code-review', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result.removed).toEqual([])
+    expect(result.repaired.map((entry) => entry.path)).toEqual([join(home, 'skills', 'code-review.md.disabled')])
+    expect((await store.getDisabled('code-review'))?.path).toBe(join(home, 'skills', 'code-review.md.disabled'))
+  })
+
+  it('repoints to the bundle placeholder when that is the surviving form', async () => {
+    await mkdir(join(home, 'skills', 'paused'))
+    await writeFile(join(home, 'skills', 'paused', 'SKILL.md.disabled'), '---\nname: paused\ndescription: b\n---', 'utf8')
+    await store.addDisabled({ name: 'paused', description: 'b', path: join(home, 'skills', 'paused.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result.repaired.map((entry) => entry.path)).toEqual([join(home, 'skills', 'paused', 'SKILL.md.disabled')])
+  })
+
+  it('leaves records whose file still exists alone, and is idempotent', async () => {
+    await writeFile(join(home, 'skills', 'alive.md.disabled'), '---\nname: alive\ndescription: x\n---', 'utf8')
+    await store.addDisabled({ name: 'alive', description: 'x', path: join(home, 'skills', 'alive.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    expect(await pruneStaleDisabledSkills(store, home)).toEqual({ repaired: [], removed: [] })
+    expect(await pruneStaleDisabledSkills(store, home)).toEqual({ repaired: [], removed: [] })
+    expect(await store.listDisabled()).toHaveLength(1)
+  })
+
+  it('prunes records from the other writable root too', async () => {
+    await store.addDisabled({ name: 'agent-ghost', description: 'x', path: join(agentsHome, 'skills', 'agent-ghost', 'SKILL.md.disabled'), root: 'user-agents', disabledAt: 1 })
+    await writeFile(join(agentsHome, 'skills', 'agent-ghost.md.disabled'), '---\nname: agent-ghost\ndescription: x\n---', 'utf8')
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result.repaired.map((entry) => entry.path)).toEqual([join(agentsHome, 'skills', 'agent-ghost.md.disabled')])
+  })
 })