dsh-skill-hub 0.3.13 → 0.3.15

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

@@ -2,8 +2,10 @@
  * The dsh-skill-hub plugin settings card: bridges the hub's settings
  * namespace (bound through the official settings transport) onto the
  * family-style staged card form (enabled master switch + agent announcement).
- * Registered into the official `settings.plugin.item` slot keyed by that
- * namespace, so the plugin shows up in Settings → 插件 on dsh rc.7+.
+ * Registered into `plugins.bundle.config` under the bundle's package name, so
+ * the Plugins manager renders it on dsh-skill-hub's own page. That slot is
+ * dispatched with `view: 'page'` only, so the card always renders its full
+ * form (no `summary` one-liner variant).
  */
 import { type ReactElement } from 'react';
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
@@ -34,7 +36,7 @@ export interface SkillHubSettingsCardFace {
     resetField: (field: string) => void;
 }
 /** Props the slot renderer binds (locale copy + injected form actions). */
-export type SkillHubSettingsCardProps = PropsRuntime<'settings.plugin.item'> & PropsLocale<'dsh-skill-hub'> & InjectFace<SkillHubSettingsCardFace>;
+export type SkillHubSettingsCardProps = PropsRuntime<'plugins.bundle.config'> & PropsLocale<'dsh-skill-hub'> & InjectFace<SkillHubSettingsCardFace>;
 /** Bridges the hub's config scope onto the card's staged form. */
 export declare class SkillHubSettingsCardController {
     private readonly form;

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

@@ -2,11 +2,10 @@
  * Vendored UI icons for dsh-skill-hub.
  *
  * These were originally imported from `@deepseek-ai/dsh-client-ui-primitives`.
- * That package is still published for the rc.7/rc.2 SDK families, but newer dsh
- * web builds no longer expose it as a standalone plugin module — they keep a
- * static compatibility module instead. Vendoring the few tiny outline icons the
- * hub uses makes the browser half self-contained and equally compatible with
- * older and newer dsh hosts.
+ * That package is not exposed as a standalone plugin module by the dsh web
+ * build this plugin targets — dsh keeps a static compatibility module instead.
+ * Vendoring the few tiny outline icons the hub uses keeps the browser half
+ * self-contained and independent of how that module is packaged.
  *
  * SVG paths are copied verbatim from dsh-client-ui-primitives (MIT licensed)
  * so the visuals remain pixel-identical to the dsh icon family.

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

@@ -2,16 +2,17 @@
  * Browser-half entry for the dsh-skill-hub plugin — runs inside the dsh
  * web GUI.
  *
- * Registers the dsh-skill-hub locale dictionaries and mounts two Settings
- * surfaces, both through official slots (no DOM injection):
- *  - a plugin-management card in the `settings.plugin.item` slot (Settings →
- *    插件 → 可配置插件列表), keyed by the hub's settings namespace and bound
- *    through the official settings transport (dsh rc.7 serves every
- *    registered namespace to the web client, and the tab dispatches cards by
- *    namespace) — the family-bucket card pattern (PluginSettingsCard +
- *    CardForm vendored from dsh-task-board);
+ * Registers the dsh-skill-hub locale dictionaries and mounts:
  *  - a top-level Settings section (Settings → 技能) hosting the skill hub
- *    panel: catalog, search, enable/disable, diagnostics, new-skill form.
+ *    panel: catalog, search, enable/disable, diagnostics, new-skill form;
+ *  - the chat "/" menu skill dots, colored from the same config the panel reads.
+ *
+ *  - a configuration card in the `plugins.bundle.config` slot, keyed by the
+ *    BUNDLE PACKAGE NAME, rendered on the plugin's own page in the Plugins
+ *    manager (sidebar → 插件 → dsh-skill-hub). dsh 0.1.7 has no auto-generated
+ *    config page: the manager only renders that section for bundles that
+ *    register this slot, and the card writes through the shared config form
+ *    (`ctx.configForms.get(skill-hub)`), the same form the host routes read.
  *
  * Failure policy: mounting problems are logged, never thrown — the web
  * shell fails the whole boot when a plugin apply throws, and an external
@@ -37,9 +38,9 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 /**
  * Required services (fiber inject waiting — the runtime must be up first).
  * `connection`/`remote` are the settings transport's own prerequisites
- * (`ctx.settingsScope.bind` resolves them on the caller's fiber), and
- * `settingsScope` is the namespace-scope binder itself; mirror the official
- * settings-plugins inject list.
+ * (`ctx.configForms.get` resolves them on the caller's fiber), and
+ * `configForms` is the shared settings-form service itself; mirror the
+ * official settings-plugins inject list.
  */
 export declare const inject: string[];
 /** Type-only surface (export discipline: no value exports beyond the plugin contract). */

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

@@ -74,6 +74,7 @@ export declare const zhMarket: {
     readonly 'repo.cancel': "取消";
     readonly 'repo.cancelled': "已取消 · 已导入 {imported}/{total} 已保留，临时文件已清理";
     readonly 'repo.importingCurrent': "正在导入: {name} ({done}/{total})";
+    readonly 'repo.root.self': "仓库根";
     readonly 'repo.root.skills': "skills";
     readonly 'repo.root.designTemplates': "design-templates";
     readonly 'repo.root.generic': "{root}";

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

@@ -157,6 +157,7 @@ export declare const zh: {
     readonly 'repo.cancel': "取消";
     readonly 'repo.cancelled': "已取消 · 已导入 {imported}/{total} 已保留，临时文件已清理";
     readonly 'repo.importingCurrent': "正在导入: {name} ({done}/{total})";
+    readonly 'repo.root.self': "仓库根";
     readonly 'repo.root.skills': "skills";
     readonly 'repo.root.designTemplates': "design-templates";
     readonly 'repo.root.generic': "{root}";

package/lib/types/client/settings-form.d.ts

@@ -54,7 +54,12 @@ export interface FieldState {
     overridden: boolean;
     invalid: boolean;
 }
-/** The settings scope face the form consumes (subset of SettingsScope<T>). */
+/**
+ * The settings-form face this card consumes. Declared structurally rather than
+ * imported so the card stays independent of the settings package's generics:
+ * the browser half passes it `ctx.configForms.get<HubSettingsValue>(HUB_ENTRY_ID)`,
+ * which satisfies this shape (ConfigForm<T>).
+ */
 export interface FormScope {
     subscribe(listener: () => void): () => void;
     getSnapshot(): {
@@ -64,8 +69,9 @@ export interface FormScope {
         base?: unknown;
         user?: unknown;
     };
-    set(field: string, value: unknown): Promise<void>;
-    unset(field: string): Promise<void>;
+    /** Both write paths report host acceptance (ConfigForm.set/unset contract). */
+    set(field: string, value: unknown): Promise<boolean>;
+    unset(field: string): Promise<boolean>;
 }
 /** Stages one card's edits and writes them through the settings transport. */
 export declare class CardForm {

package/lib/types/client/slash-dots.d.ts

@@ -2,14 +2,15 @@
  * Slash-menu skill dots: puts the invocation-status dot (model-callable blue /
  * user-only green) in front of every skill candidate in the chat `/` menu.
  *
- * Mechanism (mirrors how dsh-at-file fills the menu icon slot): the candidate
- * menu's rows already render an optional `icon` slot (`MenuView` renders
- * `item.icon` in a 16×16 leading span when it's defined), but the core `/skill`
- * source (`dsh-client-ui-skill`) returns candidates without `icon`. This module
- * wraps that source's `candidates` and stamps each row with a colored dot,
- * reusing the same settings (dotModelColor / dotUserColor) and the same
- * `modelInvocable` classification the panel legend uses — so the chat menu and
- * the Settings → 技能 panel stay in sync, and editing the color updates both.
+ * Mechanism: hooks the `/skill` source's `candidates` so the hub learns which
+ * rows are skill candidates and how each one classifies for model invocation,
+ * then injects the dot straight into the rendered option rows. The menu's
+ * `icon` slot is unusable for this — `MenuView` narrowed `icon` to an enum
+ * ('file' | 'folder' | 'session') and renders it through `ReferenceIcon`, so a
+ * custom element never reaches the DOM. Colors come from the same settings
+ * (dotModelColor / dotUserColor) and the same `modelInvocable` classification
+ * the panel legend uses — so the chat menu and the Settings → 技能 panel stay
+ * in sync, and editing the color updates both.
  *
  * The skill source is registered by the core plugin under the `name` "skill"
  * on the `/` trigger; re-registering the same name would throw, so this wraps
@@ -18,7 +19,7 @@
  * / `sessionOf` — the lookup below is defensive: it never throws).
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { InputTriggerServiceContract, InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
 import type { HubSettingsValue } from '../protocol.ts';
 import type { SkillHubApi } from './api.ts';
@@ -35,7 +36,15 @@ export declare function findSkillSource(service: InputTriggerServiceContract): I
  * catalog wins after reconnect; exported for deterministic unit tests.
  */
 export declare function resetModelCache(): void;
-export declare function wrapSkillSource(source: InputTriggerSource, api: SkillHubApi, scope: SettingsScope<HubSettingsValue>): () => void;
+/**
+ * Wrap the core skill source so every menu row carries the invocation dot.
+ * Exported for unit tests; production wiring goes through setupSkillSlashDots.
+ * @param source - the registered `/skill` source.
+ * @param api - hub browser API for the modelInvocable lookup.
+ * @param scope - hub settings scope for the dot colors.
+ * @returns a disposer restoring the original candidates.
+ */
+export declare function wrapSkillSource(source: InputTriggerSource, api: SkillHubApi, scope: ConfigForm<HubSettingsValue>): () => void;
 /**
  * Mount the slash-menu dots on the registered `/skill` source. Idempotent and
  * defensive: if the core source isn't registered yet (or the registry shape
@@ -47,4 +56,4 @@ export declare function wrapSkillSource(source: InputTriggerSource, api: SkillHu
  * @param scope - hub settings scope for dot colors.
  * @returns a cleanup function for `ctx.effect`.
  */
-export declare function setupSkillSlashDots(ctx: ClientContext, api: SkillHubApi, scope: SettingsScope<HubSettingsValue>): () => void;
+export declare function setupSkillSlashDots(ctx: ClientContext, api: SkillHubApi, scope: ConfigForm<HubSettingsValue>): () => void;

package/lib/types/index.d.ts

@@ -6,47 +6,82 @@
  * the skill hub panel. Everything rides official NPM SDK packages — no dsh
  * source changes.
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
-import z from 'schemastery';
-import { type HubSettingsValue } from './protocol.ts';
+import z from '@deepseek-ai/schemastery';
 /** Stable cordis plugin name (matches cordis.patch.yml insert id). */
 export declare const name = "skill-hub";
-/** Services required before the skill-hub surfaces can mount. */
+/** Services required before the skill-hub surfaces can mount. `settings` is deliberately NOT here: the plugin reads its own volatile config refs and only reaches for the settings service when it is present (issue #11). */
 export declare const inject: string[];
-/** Plugin config, validated by the same-named schemastery schema. */
+/**
+ * Plugin config, validated by the same-named schemastery schema.
+ *
+ * dsh 0.1.7 replaced the "plugin registers a settings namespace" model with
+ * "the Loader entry's Config IS the settings namespace", so this one schema is
+ * both the composition config and the settings page. Every field is volatile:
+ * the Loader re-resolves volatile values in place and re-enters apply()
+ * instead of rebuilding the fiber, and only volatile fields are writable
+ * through the settings transport.
+ */
 export interface Config {
     /** When true (default), a system-prompt section announces the hub to every agent. */
-    announceToAgent?: boolean;
+    announceToAgent: Volatile<boolean>;
     /** Master switch for the plugin (routes, prompt section). */
-    enabled?: boolean;
+    enabled: Volatile<boolean>;
     /** Show per-skill invocation count chip. Default true. */
-    showUseCount?: boolean;
+    showUseCount: Volatile<boolean>;
     /** Show per-skill last-used relative time. Default true. */
-    showUseTime?: boolean;
+    showUseTime: Volatile<boolean>;
     /** Show group-header usage summaries (count + last used). Default true. */
-    showGroupSummary?: boolean;
-    /** 统计滚动窗口天数：只统计最近 N 天的使用；0 = 全部历史。默认 0。 */
-    statsWindowDays?: number;
-    /** 自动统计扫描间隔（分钟，最小 1）。默认 5。 */
-    statsScanMinutes?: number;
+    showGroupSummary: Volatile<boolean>;
+    /** 模型可调圆点颜色（#rrggbb）；缺省用面板默认色。 */
+    dotModelColor: Volatile<string | undefined>;
+    /** 用户可调圆点颜色（#rrggbb）；缺省用面板默认色。 */
+    dotUserColor: Volatile<string | undefined>;
+    /** GitHub token；`role('secret')` 让 settings 层统一脱敏，缺省为匿名。 */
+    githubToken: Volatile<string | undefined>;
+    /** 统计滚动窗口天数：只统计最近 N 天的使用；0 = 全部历史。 */
+    statsWindowDays: Volatile<number>;
+    /** 自动统计扫描间隔（分钟，最小 1）。 */
+    statsScanMinutes: Volatile<number>;
 }
-export declare const Config: z<Config>;
 /**
- * Settings namespace hosting the hub's runtime config. Since dsh rc.7 the
- * host serves every registered settings namespace to the web client (the
- * dsh-host-apiproxy allowlist is gone), so the browser card and the settings
- * page edit this namespace through the official settings transport, and the
- * plugin consumes the same resolved value — one source of truth.
+ * The live plugin config the settings page edits. Field order here is the row
+ * order the auto-generated page renders.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+    announceToAgent: z<boolean, boolean, "volatile-defined">;
+    dotModelColor: z<string, string, "volatile">;
+    dotUserColor: z<string, string, "volatile">;
+    showUseCount: z<boolean, boolean, "volatile-defined">;
+    showUseTime: z<boolean, boolean, "volatile-defined">;
+    showGroupSummary: z<boolean, boolean, "volatile-defined">;
+    statsWindowDays: z<number, number, "volatile-defined">;
+    statsScanMinutes: z<number, number, "volatile-defined">;
+    githubToken: z<string, string, "volatile">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+    announceToAgent: z<boolean, boolean, "volatile-defined">;
+    dotModelColor: z<string, string, "volatile">;
+    dotUserColor: z<string, string, "volatile">;
+    showUseCount: z<boolean, boolean, "volatile-defined">;
+    showUseTime: z<boolean, boolean, "volatile-defined">;
+    showGroupSummary: z<boolean, boolean, "volatile-defined">;
+    statsWindowDays: z<number, number, "volatile-defined">;
+    statsScanMinutes: z<number, number, "volatile-defined">;
+    githubToken: z<string, string, "volatile">;
+}>>, "plain">;
+/**
+ * The settings namespace this plugin's config lives under, narrowed to the
+ * settings package's branded type. The browser half resolves the same form
+ * through `ctx.configForms.get(HUB_ENTRY_ID)`.
  */
-export declare const CONFIG_NAMESPACE: SettingsNamespace;
-/** Schema of the hub's settings namespace: the card's fields (booleans + optional dot colors). */
-export declare const HubSettingsSchema: z<HubSettingsValue>;
+export declare const ENTRY_ID: SettingsNamespace;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
 export declare const SKILL_HUB_GUIDANCE: string;
 /**
  * Mount the skill hub routes and announcement.
  * @param ctx - host plugin context carrying webServer/skills/systemPrompt/settings.
- * @param config - resolved plugin config (schema defaults applied by the loader).
  */
 export declare function apply(ctx: Context, config?: Config): void;

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

@@ -1,4 +1,24 @@
-/** Browser-facing base paths of the skill-hub API family. */
+/**
+ * Root path of the skill-hub API family. The host also registers this as its
+ * 404 catch-all prefix, so a mistyped path answers with a plain 404 naming the
+ * path instead of falling through to the SPA fallback (which answers 401 and
+ * reads like an auth problem).
+ */
+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.
+ *
+ * Naming rule: a path's segments mirror its scope. Market sources own the
+ * `/market/source/*` subtree — add, delete, ref, versions, check, sync — so
+ * the update check and the sync that acts on its result sit side by side.
+ */
 export declare const SKILL_HUB_API: {
     readonly catalog: "/api/skill-hub/catalog";
     readonly skill: "/api/skill-hub/skill";
@@ -12,7 +32,7 @@ export declare const SKILL_HUB_API: {
     readonly marketSource: "/api/skill-hub/market/source";
     readonly marketSourceDelete: "/api/skill-hub/market/source/delete";
     readonly marketSourceRef: "/api/skill-hub/market/source/ref";
-    readonly marketCheck: "/api/skill-hub/market/check";
+    readonly marketCheck: "/api/skill-hub/market/source/check";
     readonly marketSync: "/api/skill-hub/market/source/sync";
     readonly repo: "/api/skill-hub/repo";
     readonly repoImport: "/api/skill-hub/repo/import";

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

@@ -29,6 +29,14 @@ export interface HubConfig {
      */
     githubToken?: string;
 }
+/**
+ * HubConfig minus the GitHub token: the shape of every config payload that
+ * leaves the host over HTTP. The token is write-only there — a response
+ * pasted into an issue or a screenshot would otherwise hand the credential
+ * over, so callers read `ConfigResponse.githubTokenSet` when they only need
+ * to know whether one is in effect.
+ */
+export type RedactedHubConfig = Omit<HubConfig, 'githubToken'>;
 /**
  * The resolved shape of the hub's settings namespace (schema defaults, then
  * the composition base, then the user layer). Kept as a type alias so the
@@ -52,6 +60,14 @@ export type HubSettingsValue = {
     /** GitHub token（明文存本地设置文档，仅回环可读；缺省为匿名）。 */
     githubToken?: string;
 };
+/**
+ * This plugin's Loader entry id — the settings namespace dsh serves its config
+ * under. It is cordis.patch.yml's insert id, NOT the package name, and it is
+ * shared by contract because the browser half addresses the same form through
+ * `ctx.configForms.get(HUB_ENTRY_ID)` while the host half writes through
+ * `ctx.settings.update(HUB_ENTRY_ID, …)`.
+ */
+export declare const HUB_ENTRY_ID = "skill-hub";
 /**
  * Hub config defaults — the single source every layer reads: the cordis
  * schema (index.ts), the host's saved-override merge, and the routes'
@@ -74,6 +90,14 @@ export declare const HUB_CONFIG_DEFAULTS: {
  * their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
  */
 export declare function resolveHubConfig(saved: Partial<HubConfig>, 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
+ * and POST responses — neither may echo it back.
+ */
+export declare function redactGithubToken<T extends {
+    githubToken?: string;
+}>(value: T): Omit<T, 'githubToken'>;
 /** HEX color validation shared by host routes and the settings card. */
 export declare const HEX_COLOR_RE: RegExp;
 /** GET /api/skill-hub/config */
@@ -81,10 +105,12 @@ export interface ConfigResponse {
     ok: true;
     /** 已安装插件自身的版本号（package.json version），设置卡标题旁显示。 */
     pluginVersion: string;
-    /** Effective configuration (saved overrides merged over the defaults). */
-    config: HubConfig;
-    /** Raw user overrides persisted in the sidecar (absent fields inherit defaults). */
-    saved: Partial<HubConfig>;
+    /** Effective configuration (saved overrides merged over the defaults), token stripped. */
+    config: RedactedHubConfig;
+    /** Raw user overrides persisted in the sidecar (absent fields inherit defaults), token stripped. */
+    saved: Partial<RedactedHubConfig>;
+    /** 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. */
 export interface ConfigRequest {

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

@@ -64,7 +64,7 @@ export interface MarketStatsResponse {
         error?: string;
     }>;
 }
-/** GET /api/skill-hub/market/check — update check over market sources. */
+/** GET /api/skill-hub/market/source/check — update check over market sources. */
 export interface MarketCheckResponse {
     ok: true;
     results: Array<{

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

@@ -17,8 +17,25 @@ export interface RepoSkillEntry {
     /** Whether a same-named skill already exists locally. */
     existing: boolean;
 }
-/** Skill root in a GitHub repo: the top-level directory that contains skills (e.g. skills, design-templates, templates). Auto-derived from SKILL.md locations, not hard-coded. */
+/**
+ * Skill root in a GitHub repo: the top-level directory that contains skills
+ * (e.g. skills, design-templates, templates). Auto-derived from SKILL.md
+ * locations, not hard-coded.
+ *
+ * The empty string is the repo root itself — a skill whose SKILL.md sits at
+ * the top of the tree (a Claude Code plugin manifest may declare
+ * `"skills": ["./"]`). It is a legal value, not a missing one, so state
+ * sanitizers must accept it instead of coercing it to a default root.
+ */
 export type RepoRoot = string;
+/** Top-level directory pattern for a skill root: visible, non-dot, safe chars. First char must be alphanum. */
+export declare const REPO_ROOT_RE: RegExp;
+/**
+ * True when a value is a usable root: a visible safe top-level directory name,
+ * or the empty string for the repo root. Guards the persisted store against
+ * corrupt roots without rewriting the repo-root sentinel.
+ */
+export declare function isValidRepoRoot(value: unknown): value is RepoRoot;
 /** GET /api/skill-hub/repo — discover importable skills in a GitHub repo. */
 export interface RepoDiscoverResponse {
     ok: true;

package/lib/types/protocol.d.ts

@@ -7,11 +7,11 @@
  * 按域拆分后的重导出入口：老 `from './protocol.ts'` 写法保持可用，
  * 新代码可按需直引 `from './protocol/<domain>.ts'`。
  */
-export { SKILL_HUB_API } from './protocol/api.ts';
+export { SKILL_HUB_API, SKILL_HUB_API_ROOT, SKILL_HUB_API_DEPRECATED_MARKET_CHECK } 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, ConfigResponse, ConfigRequest } from './protocol/config.ts';
-export { HUB_CONFIG_DEFAULTS, HEX_COLOR_RE, GITHUB_TOKEN_RE, resolveHubConfig } from './protocol/config.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 { 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';

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

@@ -2,9 +2,48 @@
  * 仓库技能发现：从 GitHub 仓库树推断技能根目录、列出可导入技能、
  * 生成目录清单并做上游差异比对。纯函数为主，便于单测。
  * 从 repo.ts 抽出。
+ *
+ * 路径语义集中在几个内部函数上：`skillDirPrefix`（技能目录在树里的前缀）、
+ * `isRepoTooling`（永不属于技能的仓库基建）、`skillFileAt`（目录内的
+ * SKILL.md 路径）。collect / manifest / diff 三处必须共用它们，否则差异
+ * 比对会永远报「有更新」。
  */
-import type { RepoSkillEntry } from '../protocol.ts';
+import type { RepoRoot, RepoSkillEntry } from '../protocol.ts';
 import type { RepoFile, RepoRef, RepoTreeItem } from './types.ts';
+/**
+ * Sentinel root for a skill whose SKILL.md sits directly at the repository
+ * root instead of under a top-level directory. That layout is legal and used
+ * upstream (a Claude Code plugin manifest may declare `"skills": ["./"]`),
+ * and the empty string is the representation that composes with plain prefix
+ * arithmetic: an empty prefix *is* the repo root. Every path helper below
+ * special-cases it, because `'' + '/' + name` would produce a bogus absolute
+ * `/name` that matches no tree path.
+ */
+export declare const REPO_ROOT: RepoRoot;
+/** True when a root denotes the repo root itself (the repo is the skill dir). */
+export declare function isRepoRoot(root: string): boolean;
+/**
+ * The tree prefix delimiting a skill directory: empty for the repo-root skill
+ * (it owns the whole tree), otherwise `<dir>/`. Single source for collect,
+ * manifest, diff and the store's baseline cleanup, so they can never disagree.
+ */
+export declare function skillDirPrefix(dir: string): string;
+/**
+ * A path inside a skill directory, as it appears in the repo tree. Both
+ * directions of this mapping matter: repo paths are always '/'-joined (never
+ * node:path's OS separator, these are GitHub paths shown in the UI), and the
+ * repo-root case must not grow a leading slash.
+ */
+export declare function skillPathIn(dir: string, relative: string): string;
+/** The SKILL.md path inside a skill directory. */
+export declare function skillFileAt(dir: string): string;
+/**
+ * A repo file's path relative to its skill directory — the path it is written
+ * to under the skill's own directory. `dir === ''` means the repo file path
+ * *is* the relative path; slicing `dir.length + 1` would eat its first
+ * character.
+ */
+export declare function relativeToSkillDir(dir: string, path: string): string;
 /** `owner/repo` slug for a parsed reference. */
 export declare function repoSlug(ref: RepoRef): string;
 /**
@@ -14,11 +53,20 @@ export declare function repoSlug(ref: RepoRef): string;
 export declare function normalizeRepoInput(input: string): RepoRef | null;
 /** Collect every file inside a skill directory, including SKILL.md itself. */
 export declare function collectRepoSkillFiles(tree: readonly RepoTreeItem[], dir: string): RepoFile[];
-/** Compute an origin collection name. Multiple roots split by root, one root keeps the repo slug. */
+/**
+ * Compute an origin collection name. Multiple roots split by root, one root
+ * keeps the repo slug. The repo-root skill's name *is* the repo slug, so it
+ * never gets a trailing-slash suffix (`owner/repo/`).
+ */
 export declare function originForRoot(repo: string, rootsPresent: ReadonlySet<string>, root: string): string;
 /** Discover importable skills from a repo tree. Invalid names are ignored. Roots are auto-derived from the top-level directory of each SKILL.md. */
 export declare function discoverRepoEntries(tree: readonly RepoTreeItem[], repo: string, existingNames?: ReadonlySet<string>): RepoSkillEntry[];
-/** Build a path→size manifest for one skill directory from a repo tree. */
+/**
+ * Build a path→size manifest for one skill directory from a repo tree.
+ * Shares `skillTreeFiles` with collectRepoSkillFiles: a manifest that
+ * disagreed with the collected file set would make every update diff report
+ * "changed" forever.
+ */
 export declare function skillManifest(tree: readonly RepoTreeItem[], dir: string): Record<string, number>;
 /**
  * The real upstream directory of one tracked skill. Source records keep only
@@ -29,6 +77,12 @@ export declare function skillManifest(tree: readonly RepoTreeItem[], dir: string
  * manifest's recorded blob path, then any same-name skill in the tree, then
  * the flat root/name fallback. Passing the tree paths makes the lookup
  * resilient to incomplete manifests and upstream moves.
+ *
+ * A repo-root record (root '') has no directory to resolve: its SKILL.md is a
+ * bare top-level path, so every nested lookup below would miss and the final
+ * fallback would hand back a bogus '/name'. Answer before them — including
+ * when the upstream SKILL.md is gone, so diffRemoteSkills reports a deletion
+ * instead of hunting for a skill that was never nested.
  */
 export declare function skillDirOf(source: {
     root: string;
@@ -38,6 +92,8 @@ export declare function skillDirOf(source: {
  * Diff one source record against an upstream tree at treeSha: which tracked
  * skills disappeared (no SKILL.md blob) and which changed (manifest baseline
  * differs, or no baseline exists — treated as changed). Pure over the tree.
+ * The remote side is read through skillManifest, so the diff compares like
+ * with like against the baseline recorded at import time.
  */
 export declare function diffRemoteSkills(tree: readonly RepoTreeItem[], source: {
     root: string;

package/lib/types/repo/github-client.d.ts

@@ -12,6 +12,22 @@ export declare class RepoFetchError extends Error {
 export declare function setGithubToken(token: string | undefined): void;
 /** Authorization header for api.github.com / raw.githubusercontent.com calls. */
 export declare function githubAuthHeaders(): Record<string, string>;
+/**
+ * 传输层：显式要求服务端返回未压缩实体。
+ *
+ * 为什么必须加：dsh 会把**启动环境**里的 `HTTP_PROXY`/`HTTPS_PROXY` 装成
+ * undici 的全局 dispatcher（`@deepseek-ai/dsh-http-proxy`），插件里的 `fetch`
+ * 因此走该代理。实测本机 Clash：经代理返回的响应会**丢掉 `content-encoding`
+ * 与 `content-type` 头，而 body 仍是 gzip**；undici 只依据 `content-encoding`
+ * 决定是否解压，于是 `response.json()` 拿到 gzip 二进制并抛错，被上层的
+ * catch 映射成 `invalid github response for <url>` —— 看起来像 GitHub 坏了。
+ * 实测对照（同一 URL、同一代理）：默认 1331 字节解析失败，声明 identity 后
+ * 5245 字节解析成功。
+ *
+ * 代价是不走压缩（我们的响应体都很小），换来的是**无论中间代理是否改写头部
+ * 都能正确取到实体**，且用户无需为插件调整启动命令。
+ */
+export declare const NO_COMPRESSION: Record<string, string>;
 /** JSON API 默认请求头（含鉴权）。 */
 export declare function apiHeaders(): Record<string, string>;
 /**

package/lib/types/repo.d.ts

@@ -4,13 +4,16 @@
  * Kept dependency-free and mostly pure so the root/origin rules are easy to
  * test. Roots are auto-derived: any top-level directory that contains a
  * `**\/SKILL.md` (e.g. `skills/**`, `design-templates/**`, `templates/**`,
- * `workflows/**`) is treated as a skill root. No hard-coded allowlist.
+ * `workflows/**`) is treated as a skill root. No hard-coded allowlist. A
+ * `SKILL.md` at the repo root is the empty-string root (`REPO_ROOT`): the
+ * whole repo is one skill, named after the repo, with top-level dot entries
+ * treated as repo tooling rather than skill content.
  *
  * The implementation now lives under `./repo/` (types, discovery, api,
  * install) and this module is a barrel that re-exports it.
  */
-export { RepoFetchError, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, setGithubToken } from './repo/github-client.ts';
+export { NO_COMPRESSION, RepoFetchError, apiHeaders, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, setGithubToken } from './repo/github-client.ts';
 export type { RepoRef, RepoTreeItem, RepoFile } from './repo/types.ts';
-export { repoSlug, normalizeRepoInput, collectRepoSkillFiles, originForRoot, discoverRepoEntries, skillManifest, skillDirOf, diffRemoteSkills, repoSkillEntry, } from './repo/discovery.ts';
+export { REPO_ROOT, isRepoRoot, repoSlug, normalizeRepoInput, collectRepoSkillFiles, originForRoot, discoverRepoEntries, skillManifest, skillDirOf, skillFileAt, skillPathIn, relativeToSkillDir, diffRemoteSkills, repoSkillEntry, } from './repo/discovery.ts';
 export { loadRepoTree, getLatestReleaseTag, getRepoStats, listRepoReleases, listRepoBranches, getLatestCommit, loadRepoTreeAt, } from './repo/api.ts';
 export { downloadGitHubFile, downloadRepoSkill, cleanupLeftoverImportDirs } from './repo/install.ts';

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

@@ -7,7 +7,7 @@
  * ./catalog-data.ts（目录装配）；对外导出面保持不变。
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+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 { configOf, disabledGate, homeOf, isWritableSource, resolveWritableSkill, savedOf, } from './deps.ts';
@@ -28,6 +28,13 @@ export type RouteHandler = (context: RouteContext) => Promise<void>;
 /** One declarative route: path + accepted methods + the business handler. */
 export interface RouteSpec {
     path: string;
+    /**
+     * Match kind: 'exact' (default) matches the pathname verbatim; 'prefix'
+     * matches the path and everything beneath it. The webserver consults the
+     * exact table first and then resolves prefixes longest-first, so a prefix
+     * route is a catch-all that can never shadow a real route.
+     */
+    kind?: WebRouteKind;
     /** Accepted HTTP methods; anything else answers 405. */
     methods: readonly ('GET' | 'POST')[];
     /** POST requests must carry a JSON body (400 when missing/unparseable). */

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

@@ -1,7 +1,7 @@
 /**
  * 市场域路由：market 列表 / source 增删 / ref 锁定 / versions 选择器 /
- * check 更新检查 / stats 星标统计 / sync 对齐版本。从 routes.ts 原样搬出，
- * handler 逻辑不变。
+ * source/check 更新检查 / stats 星标统计 / source/sync 对齐版本。
+ * 从 routes.ts 原样搬出，handler 逻辑不变。
  */
 import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
 /** 市场域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */

package/lib/types/routes.d.ts

@@ -17,6 +17,6 @@ export type { SkillHubRouteDeps, SkillLookupLike } from './routes/helpers.ts';
 /**
  * Build every /api/skill-hub route.
  * @param deps - skill registry view + sidecar store.
- * @returns the exact-path routes.
+ * @returns the exact-path routes plus the family's 404 catch-all.
  */
 export declare function makeRoutes(deps: SkillHubRouteDeps): WebRoute[];