dsh-skill-hub 0.3.7 → 0.3.9

package/lib/types/client/panel/hooks/useSourceFlow.d.ts

@@ -0,0 +1,44 @@
+/**
+ * useSourceFlow — 来源域：来源列表/更新检查/同步确认/跟进删除/回收站恢复/
+ * 清空回收站，以及单个技能/整组的删除确认流。目录与分组的刷新经聚合根
+ * 传入的 reload 回调，不直接碰其他域的 state。
+ */
+import type { SourceCheckResult, SourcesResponse } from '../../../protocol.ts';
+import type { SkillHubApi } from '../../api.ts';
+import type { FlowNotices } from './shared.ts';
+import type { ConfirmDialogState } from '../dialogs.tsx';
+export declare function useSourceFlow(api: SkillHubApi, shared: FlowNotices, 
+/** 目录重载（技能增删后刷新列表，目录域提供）。 */
+reloadCatalog: () => Promise<void>, 
+/** 分组重载（来源/成员变化后刷新，分组域提供）。 */
+reloadGroups: () => Promise<void>): {
+    sourcesState: SourcesResponse | null;
+    sourceCheck: Readonly<Record<string, SourceCheckResult>>;
+    checkingSource: string | null;
+    syncingSource: string | null;
+    confirmDialog: ConfirmDialogState | null;
+    deleteSkillDialog: string | null;
+    deleteGroupDialog: {
+        name: string;
+        skillNames: string[];
+    } | null;
+    confirmClearTrash: boolean;
+    setConfirmDialog: import("react").Dispatch<import("react").SetStateAction<ConfirmDialogState | null>>;
+    setDeleteSkillDialog: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    setDeleteGroupDialog: import("react").Dispatch<import("react").SetStateAction<{
+        name: string;
+        skillNames: string[];
+    } | null>>;
+    setConfirmClearTrash: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    loadSources: () => Promise<void>;
+    checkSources: (repo?: string) => Promise<void>;
+    requestSync: (repo: string, skills: string[]) => void;
+    requestDelete: (repo: string, skills: string[]) => void;
+    runConfirmed: () => Promise<void>;
+    restoreTrash: (name: string) => Promise<void>;
+    clearTrash: () => Promise<void>;
+    requestDeleteSkill: (name: string) => void;
+    runDeleteSkill: () => Promise<void>;
+    requestDeleteGroup: (name: string, skillNames: string[]) => void;
+    runDeleteGroup: () => Promise<void>;
+};

package/lib/types/client/panel/market-format.d.ts

@@ -0,0 +1,6 @@
+/** Market tab number formatting (stars/downloads/bytes/speed). Pure, no deps. */
+/** Compact count for stars/downloads (1234 → 1.2k). */
+export declare function formatCount(n: number): string;
+/** Compact byte size for repo preview rows. */
+export declare function formatBytes(bytes: number): string;
+export declare function formatSpeed(bps?: number): string;

package/lib/types/client/panel/useSkillHub.d.ts

@@ -1,68 +1,36 @@
 /**
- * useSkillHub — the panel's state owner. Everything the skill hub panel
- * knows (catalog, groups, sources, market, dialogs, drafts) plus every
- * async flow lives here; the panel itself only renders. All hooks run
- * unconditionally at the top, so the panel may early-return for the detail
- * and tag-editor views without violating the rules of hooks.
+ * useSkillHub — 面板的状态聚合根：只持有跨域共享的通知状态与纯视图状态，
+ * 各域状态与动作分散在 ./hooks/*，这里按依赖顺序组装（meta → 目录 →
+ * 分组 → 来源 → 市场），轮询与派生组装在此。返回形状与拆分前完全一致，
+ * 所有视图无需改动。All hooks run unconditionally at the top, so the panel
+ * may early-return for the detail and tag-editor views without violating
+ * the rules of hooks.
  */
-import { type FormEvent } from 'react';
-import type { CatalogResponse, CatalogSkill, DisabledSkill, GroupsResponse, HubConfig, MarketSourceRecord, RepoDiscoverResponse, RepoImportProgressResponse, SkillDetail, SkillTag, SourceCheckResult, SourcesResponse, UpdateCheckResponse, WritableRoot } from '../../protocol.ts';
 import type { SkillHubApi } from '../api.ts';
-import { type SortKey, type GroupSwitchState } from '../grouping.ts';
-import type { BranchChoiceState, ConfirmDialogState, ConflictDialogState, MarketSyncDialogState, VersionChoiceState } from './dialogs.tsx';
-/** One-shot self-update check state. */
-type UpdateState = {
-    status: 'idle';
-} | {
-    status: 'checking';
-} | {
-    status: 'ready';
-    data: UpdateCheckResponse;
-} | {
-    status: 'error';
-    message: string;
-};
-/** Repo scanner/import state (drives the market source preview). */
-type RepoDiscoverState = {
-    status: 'idle';
-} | {
-    status: 'scanning';
-} | {
-    status: 'ready';
-    data: RepoDiscoverResponse;
-} | {
-    status: 'error';
-    message: string;
-};
-/** Market sources list state. */
-type MarketState = {
-    status: 'loading' | 'ready' | 'error';
-    repos: MarketSourceRecord[];
-};
 /** The hook's result: the panel's complete state + action surface. */
 export type SkillHubState = ReturnType<typeof useSkillHub>;
 export declare function useSkillHub(api: SkillHubApi): {
-    catalog: CatalogResponse | null;
+    catalog: import("../../protocol.ts").CatalogResponse | null;
     loading: boolean;
     loadError: string | null;
     successBanner: string | null;
-    updateState: UpdateState;
-    repoDiscoverState: RepoDiscoverState;
+    updateState: import("./hooks/shared.ts").UpdateState;
+    repoDiscoverState: import("./hooks/shared.ts").RepoDiscoverState;
     scanningRepo: string | null;
     repoSelected: ReadonlySet<string>;
     repoImporting: boolean;
-    repoResult: RepoImportProgressResponse | null;
+    repoResult: import("../../protocol.ts").RepoImportProgressResponse | null;
     importJobId: string | null;
     search: string;
     workspace: string;
-    detail: SkillDetail | null;
+    detail: import("../../protocol.ts").SkillDetail | null;
     detailLoading: boolean;
     busyNames: ReadonlySet<string>;
     batchBusy: boolean;
     showForm: boolean;
     formName: string;
     formDesc: string;
-    formRoot: WritableRoot;
+    formRoot: import("../../protocol.ts").WritableRoot;
     formBusy: boolean;
     formMessage: {
         kind: "error" | "success";
@@ -72,13 +40,13 @@ export declare function useSkillHub(api: SkillHubApi): {
         count: number;
         lastUsed?: number;
     }>;
-    hubConfig: HubConfig | null;
+    hubConfig: import("../../protocol.ts").HubConfig | null;
     tab: "sources" | "scenes" | "market";
     skillView: "flat" | "groups";
     sourceFilter: string;
     invocationFilter: "user" | "model" | "all";
-    sortKey: SortKey;
-    marketState: MarketState;
+    sortKey: import("../grouping.ts").SortKey;
+    marketState: import("./hooks/shared.ts").MarketState;
     marketCheck: Readonly<Record<string, {
         repo: string;
         ref?: string;
@@ -88,19 +56,23 @@ export declare function useSkillHub(api: SkillHubApi): {
         throttled?: boolean;
         error?: string;
     }>>;
-    branchChoice: BranchChoiceState | null;
+    marketStats: Readonly<Record<string, {
+        stars: number;
+        downloads: number;
+    }>>;
+    branchChoice: import("./dialogs.tsx").BranchChoiceState | null;
     branchBusy: boolean;
-    marketSyncDialog: MarketSyncDialogState | null;
+    marketSyncDialog: import("./dialogs.tsx").MarketSyncDialogState | null;
     syncingMarket: string | null;
     syncBusy: boolean;
     newSourceName: string;
-    groupsState: GroupsResponse | null;
-    sourcesState: SourcesResponse | null;
-    sourceCheck: Readonly<Record<string, SourceCheckResult>>;
+    groupsState: import("../../protocol.ts").GroupsResponse | null;
+    sourcesState: import("../../protocol.ts").SourcesResponse | null;
+    sourceCheck: Readonly<Record<string, import("../../protocol.ts").SourceCheckResult>>;
     checkingSource: string | null;
     syncingSource: string | null;
-    conflictDialog: ConflictDialogState | null;
-    confirmDialog: ConfirmDialogState | null;
+    conflictDialog: import("./dialogs.tsx").ConflictDialogState | null;
+    confirmDialog: import("./dialogs.tsx").ConfirmDialogState | null;
     deleteSkillDialog: string | null;
     deleteGroupDialog: {
         name: string;
@@ -108,7 +80,7 @@ export declare function useSkillHub(api: SkillHubApi): {
     } | null;
     confirmClearTrash: boolean;
     updateAllDialog: boolean;
-    editingTag: SkillTag | null;
+    editingTag: import("../../protocol.ts").SkillTag | null;
     editName: string;
     membersDraft: ReadonlySet<string>;
     newTagName: string;
@@ -118,25 +90,25 @@ export declare function useSkillHub(api: SkillHubApi): {
     subdividedProjects: ReadonlySet<string>;
     showLegend: boolean;
     editMode: boolean;
-    versionDialog: VersionChoiceState | null;
+    versionDialog: import("./dialogs.tsx").VersionChoiceState | null;
     versionBusy: boolean;
     actionNames: Set<string>;
     viewNames: Set<string>;
     normalized: string;
     origins: Record<string, string>;
     sourceOptions: string[];
-    filtered: CatalogSkill[];
-    sorted: CatalogSkill[];
+    filtered: import("../../protocol.ts").CatalogSkill[];
+    sorted: import("../../protocol.ts").CatalogSkill[];
     shortenedCount: number;
     setLoadError: import("react").Dispatch<import("react").SetStateAction<string | null>>;
     setSuccessBanner: import("react").Dispatch<import("react").SetStateAction<string | null>>;
     setSearch: import("react").Dispatch<import("react").SetStateAction<string>>;
     setWorkspace: import("react").Dispatch<import("react").SetStateAction<string>>;
-    setDetail: import("react").Dispatch<import("react").SetStateAction<SkillDetail | null>>;
+    setDetail: import("react").Dispatch<import("react").SetStateAction<import("../../protocol.ts").SkillDetail | null>>;
     setShowForm: import("react").Dispatch<import("react").SetStateAction<boolean>>;
     setFormName: import("react").Dispatch<import("react").SetStateAction<string>>;
     setFormDesc: import("react").Dispatch<import("react").SetStateAction<string>>;
-    setFormRoot: import("react").Dispatch<import("react").SetStateAction<WritableRoot>>;
+    setFormRoot: import("react").Dispatch<import("react").SetStateAction<import("../../protocol.ts").WritableRoot>>;
     setFormMessage: import("react").Dispatch<import("react").SetStateAction<{
         kind: "error" | "success";
         text: string;
@@ -146,12 +118,12 @@ export declare function useSkillHub(api: SkillHubApi): {
     setSkillView: import("react").Dispatch<import("react").SetStateAction<"flat" | "groups">>;
     setSourceFilter: import("react").Dispatch<import("react").SetStateAction<string>>;
     setInvocationFilter: import("react").Dispatch<import("react").SetStateAction<"user" | "model" | "all">>;
-    setSortKey: import("react").Dispatch<import("react").SetStateAction<SortKey>>;
-    setBranchChoice: import("react").Dispatch<import("react").SetStateAction<BranchChoiceState | null>>;
-    setMarketSyncDialog: import("react").Dispatch<import("react").SetStateAction<MarketSyncDialogState | null>>;
+    setSortKey: import("react").Dispatch<import("react").SetStateAction<import("../grouping.ts").SortKey>>;
+    setBranchChoice: import("react").Dispatch<import("react").SetStateAction<import("./dialogs.tsx").BranchChoiceState | null>>;
+    setMarketSyncDialog: import("react").Dispatch<import("react").SetStateAction<import("./dialogs.tsx").MarketSyncDialogState | null>>;
     setNewSourceName: import("react").Dispatch<import("react").SetStateAction<string>>;
-    setConflictDialog: import("react").Dispatch<import("react").SetStateAction<ConflictDialogState | null>>;
-    setConfirmDialog: import("react").Dispatch<import("react").SetStateAction<ConfirmDialogState | null>>;
+    setConflictDialog: import("react").Dispatch<import("react").SetStateAction<import("./dialogs.tsx").ConflictDialogState | null>>;
+    setConfirmDialog: import("react").Dispatch<import("react").SetStateAction<import("./dialogs.tsx").ConfirmDialogState | null>>;
     setDeleteSkillDialog: import("react").Dispatch<import("react").SetStateAction<string | null>>;
     setDeleteGroupDialog: import("react").Dispatch<import("react").SetStateAction<{
         name: string;
@@ -159,23 +131,23 @@ export declare function useSkillHub(api: SkillHubApi): {
     } | null>>;
     setConfirmClearTrash: import("react").Dispatch<import("react").SetStateAction<boolean>>;
     setUpdateAllDialog: import("react").Dispatch<import("react").SetStateAction<boolean>>;
-    setEditingTag: import("react").Dispatch<import("react").SetStateAction<SkillTag | null>>;
+    setEditingTag: import("react").Dispatch<import("react").SetStateAction<import("../../protocol.ts").SkillTag | null>>;
     setEditName: import("react").Dispatch<import("react").SetStateAction<string>>;
     setMembersDraft: import("react").Dispatch<import("react").SetStateAction<ReadonlySet<string>>>;
     setNewTagName: import("react").Dispatch<import("react").SetStateAction<string>>;
     setEditSearch: import("react").Dispatch<import("react").SetStateAction<string>>;
     setShowLegend: import("react").Dispatch<import("react").SetStateAction<boolean>>;
     setEditMode: import("react").Dispatch<import("react").SetStateAction<boolean>>;
-    setVersionDialog: import("react").Dispatch<import("react").SetStateAction<VersionChoiceState | null>>;
+    setVersionDialog: import("react").Dispatch<import("react").SetStateAction<import("./dialogs.tsx").VersionChoiceState | null>>;
     toggleGroupCollapse: (key: string) => void;
     toggleSubdivide: (key: string) => void;
     checkUpdate: () => Promise<void>;
     loadMarket: () => Promise<void>;
     openDetail: (name: string) => Promise<void>;
-    toggle: (skill: CatalogSkill, enabled: boolean) => Promise<void>;
-    enableDisabled: (record: DisabledSkill) => Promise<void>;
+    toggle: (skill: import("../../protocol.ts").CatalogSkill, enabled: boolean) => Promise<void>;
+    enableDisabled: (record: import("../../protocol.ts").DisabledSkill) => Promise<void>;
     batchToggleNames: (names: string[], enabled: boolean) => Promise<void>;
-    toggleGroup: (key: string, name: string, view: GroupSwitchState) => void;
+    toggleGroup: (key: string, name: string, view: import("../grouping.ts").GroupSwitchState) => void;
     resolveConflict: (closeAll: boolean) => Promise<void>;
     runConfirmed: () => Promise<void>;
     checkSources: (repo?: string) => Promise<void>;
@@ -192,7 +164,7 @@ export declare function useSkillHub(api: SkillHubApi): {
     runDeleteSkill: () => Promise<void>;
     requestDeleteGroup: (name: string, skillNames: string[]) => void;
     runDeleteGroup: () => Promise<void>;
-    createTag: (event: FormEvent) => Promise<void>;
+    createTag: (event: import("react").FormEvent) => Promise<void>;
     deleteTag: (id: string) => Promise<void>;
     saveTag: (id: string, name: string, memberNames: string[] | null) => Promise<void>;
     reorderTags: (orderedIds: string[]) => Promise<void>;
@@ -208,9 +180,9 @@ export declare function useSkillHub(api: SkillHubApi): {
     cancelImport: () => Promise<void>;
     clearScan: () => void;
     checkMarket: () => Promise<void>;
+    loadMarketStats: () => Promise<void>;
     syncMarketSource: (repo: string) => Promise<void>;
     confirmMarketSync: () => Promise<void>;
     updateAll: () => Promise<void>;
-    create: (event: FormEvent) => Promise<void>;
+    create: (event: import("react").FormEvent) => Promise<void>;
 };
-export {};

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

@@ -65,6 +65,26 @@ export interface ColorFieldProps {
     onReset: () => void;
 }
 export declare function ColorField(props: ColorFieldProps): ReactElement;
+/**
+ * One staged secret field: a password input that never echoes the stored
+ * value. Shows a "set" state via the overridden badge; Reset unsets it.
+ */
+export interface SecretFieldProps {
+    id: string;
+    label: string;
+    hint: string;
+    /** Placeholder shown while empty (never the stored token). */
+    placeholder: string;
+    overriddenLabel: string;
+    resetLabel: string;
+    disabled: boolean;
+    text: string;
+    overridden: boolean;
+    invalid?: boolean;
+    onEdit: (text: string) => void;
+    onReset: () => void;
+}
+export declare function SecretField(props: SecretFieldProps): ReactElement;
 /** One staged numeric field: a numeric draft text input with inherit/reset semantics. */
 export interface NumberFieldProps {
     id: string;

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

@@ -23,6 +23,12 @@ export interface FieldSpec {
 export declare function booleanField(field: string): FieldSpec;
 /** A #rrggbb color field, edited through hex draft text. */
 export declare function colorField(field: string): FieldSpec;
+/**
+ * A secret field (API token): the stored value is never echoed back into the
+ * draft (format always yields ''), so typing is always a fresh set and Reset
+ * always unsets. An empty draft stages nothing.
+ */
+export declare function secretField(field: string): FieldSpec;
 /**
  * A numeric field with range clamping. Integer by default: a fractional draft
  * is truncated so "5.5 分钟" cannot sneak past an integer-only schema.

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

@@ -0,0 +1,38 @@
+/** Browser-facing base paths of the skill-hub API family. */
+export declare const SKILL_HUB_API: {
+    readonly catalog: "/api/skill-hub/catalog";
+    readonly skill: "/api/skill-hub/skill";
+    readonly skillDelete: "/api/skill-hub/skill/delete";
+    readonly toggle: "/api/skill-hub/toggle";
+    readonly toggleBatch: "/api/skill-hub/toggle-batch";
+    readonly create: "/api/skill-hub/create";
+    readonly stats: "/api/skill-hub/stats";
+    readonly config: "/api/skill-hub/config";
+    readonly market: "/api/skill-hub/market";
+    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 marketSync: "/api/skill-hub/market/source/sync";
+    readonly repo: "/api/skill-hub/repo";
+    readonly repoImport: "/api/skill-hub/repo/import";
+    readonly repoImportProgress: "/api/skill-hub/repo/import/progress";
+    readonly repoImportCancel: "/api/skill-hub/repo/import/cancel";
+    readonly update: "/api/skill-hub/update";
+    readonly groups: "/api/skill-hub/groups";
+    readonly tag: "/api/skill-hub/tag";
+    readonly tagDelete: "/api/skill-hub/tag/delete";
+    readonly tagMembers: "/api/skill-hub/tag/members";
+    readonly tagReorder: "/api/skill-hub/tag/reorder";
+    readonly collectionReorder: "/api/skill-hub/collections/reorder";
+    readonly sourceGroupReorder: "/api/skill-hub/source-groups/reorder";
+    readonly sources: "/api/skill-hub/sources";
+    readonly sourceCheck: "/api/skill-hub/sources/check";
+    readonly sourceSync: "/api/skill-hub/sources/sync";
+    readonly sourceDelete: "/api/skill-hub/sources/delete";
+    readonly sourceRestore: "/api/skill-hub/sources/restore";
+    readonly sourceTrashClear: "/api/skill-hub/sources/trash/clear";
+    readonly diagnosticFix: "/api/skill-hub/diagnostic/fix";
+    readonly marketSourceVersions: "/api/skill-hub/market/source/versions";
+    readonly marketStats: "/api/skill-hub/market/stats";
+};

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

@@ -0,0 +1,155 @@
+/** User-level roots the hub may write to (matches dsh-skill-filesystem ranks 400/500). */
+export type WritableRoot = 'user-dsh' | 'user-agents';
+/** Invocation policy resolved by the registry, re-spelled for the wire. */
+export interface HubInvocation {
+    /** Whether model-facing catalogs may load this skill. */
+    modelInvocable: boolean;
+    /** Whether human-facing command catalogs may load this skill. */
+    userInvocable: boolean;
+}
+/** One enabled skill row in the catalog. */
+export interface CatalogSkill {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    invocation: HubInvocation;
+    provider: string;
+    /** Whether the hub may toggle this skill (user-level filesystem skills only). */
+    writable: boolean;
+    /** 技能来源标识（user-dsh/user-agents/project-dsh/project-agents/...）。 */
+    source: string;
+    /** SKILL.md creation time (epoch ms); used for "added" sorting. Absent when unknown. */
+    addedAt?: number;
+    /** SKILL.md last-modified time (epoch ms); used for "updated" display. Absent when unknown. */
+    updatedAt?: number;
+    /** 项目技能的所属工作区路径（仅 project-dsh/project-agents 来源携带）。 */
+    workspace?: string;
+    /** 工作区显示标题（来自 workspace.json；无则回退为路径）。 */
+    workspaceTitle?: string;
+    /** UI metadata from agents/openai.yaml (mirrors codex SkillInterface). */
+    displayName?: string;
+    shortDescription?: string;
+    brandColor?: string;
+    iconSmall?: string;
+    iconLarge?: string;
+    defaultPrompt?: string;
+}
+/** One disabled skill tracked by the hub sidecar (SKILL.md renamed away). */
+export interface DisabledSkill {
+    name: string;
+    description: string;
+    /** Absolute path of the renamed file (SKILL.md.disabled / <name>.md.disabled). */
+    path: string;
+    root: WritableRoot;
+    disabledAt: number;
+}
+/** One discovery diagnostic: a file the filesystem provider skips, with the reason. */
+export interface DiagnosticEntry {
+    path: string;
+    root: string;
+    reason: string;
+    /** Whether this diagnostic can be auto-fixed (e.g. unquoted colon). */
+    fixable?: boolean;
+}
+/** POST /api/skill-hub/diagnostic/fix — repair a fixable diagnostic in place. */
+export interface DiagnosticFixRequest {
+    path: string;
+}
+export interface DiagnosticFixResponse {
+    ok: true;
+    path: string;
+}
+/** GET /api/skill-hub/catalog */
+export interface CatalogResponse {
+    ok: true;
+    /** 已安装插件自身的版本号（package.json version），面板标题旁显示。 */
+    pluginVersion: string;
+    /** Whether discovery completed within a stable catalog revision. */
+    complete: boolean;
+    /** Sorted winning summaries of every enabled skill (all roots + providers). */
+    skills: CatalogSkill[];
+    /** Skills the hub has toggled off (kept outside provider discovery). */
+    disabled: DisabledSkill[];
+    /** Files in the writable roots the provider ignores, with reasons. */
+    diagnostics: DiagnosticEntry[];
+    /** Skill names that appeared in multiple roots (first wins, others hidden). Mirrors codex name_counts. */
+    duplicateNames?: string[];
+}
+/** GET /api/skill-hub/skill */
+export interface SkillDetail {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    invocation: HubInvocation;
+    provider: string;
+    /** Absolute file path when the skill came from disk. */
+    path?: string;
+    /** SKILL.md creation time (epoch ms); absent when the file is unreadable. */
+    addedAt?: number;
+    /** SKILL.md last-modified time (epoch ms); absent when the file is unreadable. */
+    updatedAt?: number;
+    /** Markdown instruction body. */
+    content: string;
+    displayName?: string;
+    shortDescription?: string;
+    brandColor?: string;
+    iconSmall?: string;
+    iconLarge?: string;
+    defaultPrompt?: string;
+}
+export interface SkillDetailResponse {
+    ok: true;
+    skill: SkillDetail;
+}
+/** POST /api/skill-hub/skill/delete — 把单个技能移入回收站（可恢复）。 */
+export interface SkillDeleteRequest {
+    name: string;
+}
+/** POST /api/skill-hub/skill/delete */
+export interface SkillDeleteResponse {
+    ok: true;
+    name: string;
+    /** 移入回收站后的路径（目录或文件）。 */
+    path: string;
+}
+/** POST /api/skill-hub/toggle */
+export interface ToggleRequest {
+    /** Kebab-case skill name. */
+    name: string;
+    /** true re-enables a hub-disabled skill; false disables an enabled one. */
+    enabled: boolean;
+}
+export interface ToggleResponse {
+    ok: true;
+    /** Fresh catalog after the mutation (the filesystem provider may lag a beat). */
+    catalog: CatalogResponse;
+}
+/** POST /api/skill-hub/toggle-batch — one group of skills, one write. */
+export interface ToggleBatchRequest {
+    names: string[];
+    enabled: boolean;
+}
+/** POST /api/skill-hub/toggle-batch */
+export interface ToggleBatchResponse {
+    ok: true;
+    catalog: CatalogResponse;
+    /** Per-name failures (unknown/read-only skills); empty means all landed. */
+    failures: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** POST /api/skill-hub/create */
+export interface CreateRequest {
+    /** Kebab-case skill name (validated with the official isSkillName grammar). */
+    name: string;
+    /** Optional one-line routing description for the frontmatter. */
+    description?: string;
+    /** Target user root; defaults to user-dsh (~/.dsh/skills). */
+    root?: WritableRoot;
+}
+export interface CreateResponse {
+    ok: true;
+    path: string;
+    root: WritableRoot;
+}

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

@@ -0,0 +1,113 @@
+/** JSON error body shared by every route. */
+export interface ErrorResponse {
+    error: string;
+}
+/** The skill hub's own runtime configuration, edited from the settings card. */
+export interface HubConfig {
+    /** Master switch: routes, provider, and announcement all go live with this. */
+    enabled: boolean;
+    /** When true, a system-prompt section announces the hub to every agent. */
+    announceToAgent: boolean;
+    /** Model-invocable dot color (#rrggbb); absent means the panel default. */
+    dotModelColor?: string;
+    /** User-invocable dot color (#rrggbb); absent means the panel default. */
+    dotUserColor?: string;
+    /** Show per-skill invocation count chip. Default true. */
+    showUseCount?: boolean;
+    /** Show per-skill last-used relative time. Default true. */
+    showUseTime?: boolean;
+    /** Show group-header usage summaries (count + last used). Default true. */
+    showGroupSummary?: boolean;
+    /** 统计滚动窗口天数：只统计最近 N 天的使用；0 = 全部历史。默认 0。 */
+    statsWindowDays?: number;
+    /** 自动统计扫描间隔（分钟，最小 1）。默认 5。 */
+    statsScanMinutes?: number;
+    /**
+     * GitHub personal access token for market/source API calls (anonymous quota
+     * is 60 req/h, authed 5000/hr). Stored in the local settings doc; absent
+     * means anonymous. Never logged.
+     */
+    githubToken?: string;
+}
+/**
+ * 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
+ * browser-side settings scope snapshot is index-compatible with the card
+ * form's record shape.
+ */
+export type HubSettingsValue = {
+    enabled: boolean;
+    announceToAgent: boolean;
+    showUseCount: boolean;
+    showUseTime: boolean;
+    showGroupSummary: boolean;
+    /** Model-invocable dot color (#rrggbb); absent means the panel default. */
+    dotModelColor?: string;
+    /** User-invocable dot color (#rrggbb); absent means the panel default. */
+    dotUserColor?: string;
+    /** 统计滚动窗口天数（0 = 全部历史）。 */
+    statsWindowDays?: number;
+    /** 自动统计扫描间隔（分钟）。 */
+    statsScanMinutes?: number;
+    /** GitHub token（明文存本地设置文档，仅回环可读；缺省为匿名）。 */
+    githubToken?: string;
+};
+/**
+ * Hub config defaults — the single source every layer reads: the cordis
+ * schema (index.ts), the host's saved-override merge, and the routes'
+ * fallback view. Changing a default here changes all three.
+ */
+export declare const HUB_CONFIG_DEFAULTS: {
+    readonly enabled: true;
+    readonly announceToAgent: true;
+    readonly showUseCount: true;
+    readonly showUseTime: true;
+    readonly showGroupSummary: true;
+    readonly statsWindowDays: 14;
+    readonly statsScanMinutes: 5;
+};
+/**
+ * Resolve the effective hub config: saved sidecar overrides win over the
+ * cordis composition entry (the web card owns runtime config), missing
+ * booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
+ * (saved first, then base) only when set. Numeric stats knobs are clamped to
+ * their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
+ */
+export declare function resolveHubConfig(saved: Partial<HubConfig>, base?: Partial<HubConfig>): HubConfig;
+/** HEX color validation shared by host routes and the settings card. */
+export declare const HEX_COLOR_RE: RegExp;
+/** GET /api/skill-hub/config */
+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>;
+}
+/** POST /api/skill-hub/config — a partial patch; omitted fields keep their values. */
+export interface ConfigRequest {
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    enabled?: boolean | null;
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    announceToAgent?: boolean | null;
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    showUseCount?: boolean | null;
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    showUseTime?: boolean | null;
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    showGroupSummary?: boolean | null;
+    /** Set the dot color; null clears the saved override so it re-inherits the default. */
+    dotModelColor?: string | null;
+    /** Set the dot color; null clears the saved override so it re-inherits the default. */
+    dotUserColor?: string | null;
+    /** 统计滚动窗口天数（0 = 全部历史）；null 清除覆盖回默认。 */
+    statsWindowDays?: number | null;
+    /** 自动统计扫描间隔（分钟）；null 清除覆盖回默认。 */
+    statsScanMinutes?: number | null;
+    /** Set the GitHub token; null/empty clears it back to anonymous. */
+    githubToken?: string | null;
+}
+/** GitHub token validation shared by host routes and the settings card. */
+export declare const GITHUB_TOKEN_RE: RegExp;