dsh-skill-hub 0.0.1 → 0.2.0

package/src/client/SkillHubSettingsCard.tsx

@@ -0,0 +1,161 @@
+/**
+ * The dsh-skill-hub plugin settings card: bridges the hub's own config route
+ * (ApiConfigScope → /api/skill-hub/config) onto the family-style staged card
+ * form (enabled master switch + agent announcement). Registered into the
+ * official `settings.plugin.item` slot so the plugin shows up in Settings →
+ * 插件. The scope is a FormScope, so the card never touches the settings
+ * service (the host refuses third-party namespaces).
+ */
+
+import type { ReactElement } from 'react'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { ColorField, PluginSettingsCard, SwitchField } from './settings-card.tsx'
+import { booleanField, CardForm, colorField, type CardShell, type FieldState, type FormScope } from './settings-form.ts'
+import { DEFAULT_DOT_MODEL_COLOR, DEFAULT_DOT_USER_COLOR } from './api-config-scope.ts'
+
+/** The card's projected state. */
+export interface SkillHubSettingsState extends CardShell {
+  enabled: FieldState
+  announceToAgent: FieldState
+  dotModelColor: FieldState
+  dotUserColor: FieldState
+  showUseCount: FieldState
+  showUseTime: FieldState
+  showGroupSummary: FieldState
+}
+
+/** Props the slot renderer receives (locale copy + injected form actions). */
+export interface SkillHubSettingsCardProps {
+  t: (key: string) => string
+  useSkillHubSettingsCard: <T>(selector: (snapshot: SkillHubSettingsState) => T) => T
+  save: () => void
+  discard: () => void
+  edit: (field: string, text: string) => void
+  resetField: (field: string) => void
+}
+
+/** Bridges the hub's config scope onto the card's staged form. */
+export class SkillHubSettingsCardController {
+  private readonly form: CardForm
+  private readonly store: SnapshotStore<SkillHubSettingsState>
+
+  /** @param scope - the hub config scope the card edits (ApiConfigScope). */
+  constructor(scope: FormScope) {
+    this.form = new CardForm(scope, [booleanField('enabled'), booleanField('announceToAgent'), colorField('dotModelColor'), colorField('dotUserColor'), booleanField('showUseCount'), booleanField('showUseTime'), booleanField('showGroupSummary')])
+    this.store = this.form.bind(() => this.projection())
+  }
+
+  private projection(): SkillHubSettingsState {
+    return {
+      ...this.form.shell(),
+      enabled: this.form.field('enabled'),
+      announceToAgent: this.form.field('announceToAgent'),
+      dotModelColor: this.form.field('dotModelColor'),
+      dotUserColor: this.form.field('dotUserColor'),
+      showUseCount: this.form.field('showUseCount'),
+      showUseTime: this.form.field('showUseTime'),
+      showGroupSummary: this.form.field('showGroupSummary'),
+    }
+  }
+
+  /**
+   * Build the face the card's slot registration injects.
+   * @returns the card's snapshot hook and its form actions.
+   */
+  inject(): { hooks: { skillHubSettingsCard: SnapshotStore<SkillHubSettingsState> } } & ReturnType<CardForm['actions']> {
+    return {
+      hooks: { skillHubSettingsCard: this.store },
+      ...this.form.actions(),
+    }
+  }
+}
+
+/**
+ * Render the dsh-skill-hub card.
+ * @param props - locale copy, the card snapshot, and its form actions.
+ * @returns the card.
+ */
+export function SkillHubSettingsCard(props: SkillHubSettingsCardProps): ReactElement {
+  const { t } = props
+  const state = props.useSkillHubSettingsCard((snapshot) => snapshot)
+  const disabled = !state.writable
+  const fieldProps = {
+    overriddenLabel: t('settings.overridden'),
+    resetLabel: t('settings.reset'),
+    disabled,
+  }
+  return (
+    <PluginSettingsCard
+      t={t}
+      titleKey='settings.title'
+      descriptionKey='settings.description'
+      state={state}
+      onSave={props.save}
+      onDiscard={props.discard}
+    >
+      <SwitchField
+        label={t('settings.enabled')}
+        hint={t('settings.enabledHint')}
+        {...fieldProps}
+        {...state.enabled}
+        onEdit={(text) => { props.edit('enabled', text) }}
+        onReset={() => { props.resetField('enabled') }}
+      />
+      <SwitchField
+        label={t('settings.announceToAgent')}
+        hint={t('settings.announceToAgentHint')}
+        {...fieldProps}
+        {...state.announceToAgent}
+        onEdit={(text) => { props.edit('announceToAgent', text) }}
+        onReset={() => { props.resetField('announceToAgent') }}
+      />
+      <ColorField
+        id='skill-hub-dot-model-color'
+        label={t('settings.dotModelColor')}
+        hint={t('settings.dotModelColorHint')}
+        inheritLabel={t('settings.inherit')}
+        defaultColor={DEFAULT_DOT_MODEL_COLOR}
+        {...fieldProps}
+        {...state.dotModelColor}
+        onEdit={(text) => { props.edit('dotModelColor', text) }}
+        onReset={() => { props.resetField('dotModelColor') }}
+      />
+      <ColorField
+        id='skill-hub-dot-user-color'
+        label={t('settings.dotUserColor')}
+        hint={t('settings.dotUserColorHint')}
+        inheritLabel={t('settings.inherit')}
+        defaultColor={DEFAULT_DOT_USER_COLOR}
+        {...fieldProps}
+        {...state.dotUserColor}
+        onEdit={(text) => { props.edit('dotUserColor', text) }}
+        onReset={() => { props.resetField('dotUserColor') }}
+      />
+      <SwitchField
+        label={t('settings.showUseCount')}
+        hint={t('settings.showUseCountHint')}
+        {...fieldProps}
+        {...state.showUseCount}
+        onEdit={(text) => { props.edit('showUseCount', text) }}
+        onReset={() => { props.resetField('showUseCount') }}
+      />
+      <SwitchField
+        label={t('settings.showUseTime')}
+        hint={t('settings.showUseTimeHint')}
+        {...fieldProps}
+        {...state.showUseTime}
+        onEdit={(text) => { props.edit('showUseTime', text) }}
+        onReset={() => { props.resetField('showUseTime') }}
+      />
+      <SwitchField
+        label={t('settings.showGroupSummary')}
+        hint={t('settings.showGroupSummaryHint')}
+        {...fieldProps}
+        {...state.showGroupSummary}
+        onEdit={(text) => { props.edit('showGroupSummary', text) }}
+        onReset={() => { props.resetField('showGroupSummary') }}
+      />
+    </PluginSettingsCard>
+  )
+}
+

package/src/client/api-config-scope.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import type { ConfigRequest, ConfigResponse, HubConfig } from '../protocol.ts'
+import type { SkillHubApi } from './api.ts'
+import { ApiConfigScope } from './api-config-scope.ts'
+
+function deferredReady(scope: ApiConfigScope): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+describe('ApiConfigScope', () => {
+  it('persists the panel display toggles (showUseCount etc.)', async () => {
+    const saved: Partial<HubConfig> = {}
+    const writes: ConfigRequest[] = []
+    const api = {
+      config: async (): Promise<ConfigResponse> => ({
+        ok: true,
+        config: {
+          enabled: true,
+          announceToAgent: true,
+          showUseCount: true,
+          showUseTime: true,
+          showGroupSummary: true,
+        },
+        saved,
+      }),
+      saveConfig: async (patch: ConfigRequest): Promise<ConfigResponse> => {
+        writes.push(patch)
+        for (const [key, value] of Object.entries(patch)) {
+          if (value === null) delete saved[key as keyof HubConfig]
+          else saved[key as keyof HubConfig] = value as never
+        }
+        return {
+          ok: true,
+          config: {
+            enabled: true,
+            announceToAgent: true,
+            showUseCount: saved.showUseCount !== false,
+            showUseTime: saved.showUseTime !== false,
+            showGroupSummary: saved.showGroupSummary !== false,
+          },
+          saved,
+        }
+      },
+    } as unknown as SkillHubApi
+
+    const scope = new ApiConfigScope(api)
+    await deferredReady(scope)
+
+    await scope.set('showUseCount', false)
+    expect(writes).toContainEqual({ showUseCount: false })
+    expect(scope.getSnapshot().value).toMatchObject({ showUseCount: false })
+    expect(scope.getSnapshot().user).toMatchObject({ showUseCount: false })
+
+    await scope.unset('showUseCount')
+    expect(writes).toContainEqual({ showUseCount: null })
+    expect(scope.getSnapshot().user).not.toHaveProperty('showUseCount')
+    expect(scope.getSnapshot().value).toMatchObject({ showUseCount: true })
+  })
+
+  it('ignores unknown fields', async () => {
+    const writes: ConfigRequest[] = []
+    const api = {
+      config: async (): Promise<ConfigResponse> => ({
+        ok: true,
+        config: { enabled: true, announceToAgent: true },
+        saved: {},
+      }),
+      saveConfig: async (patch: ConfigRequest): Promise<ConfigResponse> => {
+        writes.push(patch)
+        return { ok: true, config: { enabled: true, announceToAgent: true }, saved: {} }
+      },
+    } as unknown as SkillHubApi
+
+    const scope = new ApiConfigScope(api)
+    await deferredReady(scope)
+    await scope.set('not-a-field', true)
+    expect(writes).toHaveLength(0)
+  })
+})

package/src/client/api-config-scope.ts

@@ -0,0 +1,119 @@
+/**
+ * ApiConfigScope — a FormScope-compatible view over the hub's own config
+ * route (/api/skill-hub/config). The host's settings service refuses to
+ * expose third-party namespaces to the web client (dsh-host-apiproxy's
+ * allowlist), so the settings card talks to this plugin-owned route instead
+ * of the settings transport.
+ *
+ * The scope mirrors the settings-scope contract the vendored CardForm
+ * consumes: `value` is the effective config, `base` the built-in defaults,
+ * and `user` the raw saved overrides (a field's presence there marks it
+ * overridden). Writes go straight through saveConfig and re-seed the
+ * snapshot from the route's response, so the card's save-verification
+ * (user layer equals the written value) sees the persisted state.
+ */
+
+import type { HubConfig } from '../protocol.ts'
+import type { SkillHubApi } from './api.ts'
+import type { FormScope } from './settings-form.ts'
+
+/** Model-invocable dot color default. Single source for the TS side; the
+ *  panel's CSS mirrors it via --hub-model (panel.module.css). */
+export const DEFAULT_DOT_MODEL_COLOR = '#2f81f7'
+/** User-invocable dot color default. Single source for the TS side; the
+ *  panel's CSS mirrors it via --hub-user (panel.module.css). */
+export const DEFAULT_DOT_USER_COLOR = '#3fb950'
+
+/** Built-in defaults every field inherits until the user overrides it. */
+const DEFAULTS: HubConfig = {
+  enabled: true,
+  announceToAgent: true,
+  showUseCount: true,
+  showUseTime: true,
+  showGroupSummary: true,
+}
+
+/** Boolean config fields (color fields are strings). */
+const BOOLEAN_FIELDS = new Set<keyof HubConfig>([
+  'enabled', 'announceToAgent', 'showUseCount', 'showUseTime', 'showGroupSummary',
+])
+
+/** Config fields the card edits (used to guard set/unset field names). */
+const FIELDS = new Set<keyof HubConfig>([
+  'enabled', 'announceToAgent', 'dotModelColor', 'dotUserColor',
+  'showUseCount', 'showUseTime', 'showGroupSummary',
+])
+
+/** FormScope-compatible reactive config handle (see module doc). */
+export class ApiConfigScope implements FormScope {
+  private status: 'loading' | 'ready' | 'unavailable' = 'loading'
+  private value: HubConfig = { ...DEFAULTS }
+  private saved: Partial<HubConfig> = {}
+  private readonly listeners = new Set<() => void>()
+
+  /** @param api - the browser-half API client (shared with the skill panel). */
+  constructor(private readonly api: SkillHubApi) {
+    void this.load()
+  }
+
+  private async load(): Promise<void> {
+    try {
+      const response = await this.api.config()
+      this.value = response.config
+      this.saved = { ...response.saved }
+      this.status = 'ready'
+    } catch {
+      // The route is missing or unreachable (e.g. host half not yet updated):
+      // the card shows its not-exposed state instead of breaking the GUI.
+      this.status = 'unavailable'
+    }
+    this.publish()
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  getSnapshot(): { status: string; writable: boolean; value?: Record<string, unknown>; base?: unknown; user?: unknown } {
+    return {
+      status: this.status,
+      writable: true,
+      value: { ...this.value } as unknown as Record<string, unknown>,
+      base: { ...DEFAULTS },
+      user: { ...this.saved },
+    }
+  }
+
+  /** Write one field through the config route and adopt the persisted state. */
+  async set(field: string, value: unknown): Promise<void> {
+    if (!FIELDS.has(field as keyof HubConfig)) return
+    const patch = BOOLEAN_FIELDS.has(field as keyof HubConfig)
+      ? { [field]: Boolean(value) }
+      : { [field]: typeof value === 'string' ? value : undefined }
+    await this.apply(patch as Partial<HubConfig>)
+  }
+
+  /** Clear one field's override so it re-inherits the default. */
+  async unset(field: string): Promise<void> {
+    if (!FIELDS.has(field as keyof HubConfig)) return
+    await this.apply({ [field]: undefined } as Partial<HubConfig>)
+  }
+
+  /** Persist a patch, then re-seed from the route's fresh response. */
+  private async apply(patch: Partial<HubConfig>): Promise<void> {
+    // null on the wire clears a saved override (see ConfigRequest).
+    const request: Record<string, boolean | string | null> = {}
+    for (const [key, value] of Object.entries(patch)) {
+      request[key] = value === undefined ? null : value
+    }
+    const response = await this.api.saveConfig(request as never)
+    this.value = response.config
+    this.saved = { ...response.saved }
+    this.publish()
+  }
+
+  private publish(): void {
+    for (const listener of this.listeners) listener()
+  }
+}

package/src/client/api.ts

@@ -0,0 +1,327 @@
+/**
+ * Browser-side API client for the /api/skill-hub route family. The only
+ * data access path the panel uses — plain fetch, same origin.
+ */
+import {
+  SKILL_HUB_API,
+  type CatalogResponse,
+  type ConfigRequest,
+  type ConfigResponse,
+  type CreateRequest,
+  type CreateResponse,
+  type MarketCheckResponse,
+  type MarketSourceRefRequest,
+  type MarketSourceRequest,
+  type MarketSourceResponse,
+  type MarketSourcesResponse,
+  type MarketSyncResponse,
+  type RepoDiscoverResponse,
+  type RepoImportRequest,
+  type RepoImportResponse,
+  type SkillDetail,
+  type SkillDetailResponse,
+  type SkillDeleteRequest,
+  type SkillDeleteResponse,
+  type SourceCheckRequest,
+  type SourceCheckResponse,
+  type SourceDeleteRequest,
+  type SourceDeleteResponse,
+  type SourceRestoreRequest,
+  type SourceRestoreResponse,
+  type SourceTrashClearResponse,
+  type SourcesResponse,
+  type SourceSyncRequest,
+  type SourceSyncResponse,
+  type StatsResponse,
+  type ToggleBatchRequest,
+  type ToggleBatchResponse,
+  type UpdateCheckResponse,
+} from '../protocol.ts'
+
+/** Error carrying the route's JSON error message. */
+export class SkillHubApiError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SkillHubApiError'
+  }
+}
+
+/** Parse a JSON response or throw a SkillHubApiError. */
+async function readJson<T>(response: Response): Promise<T> {
+  let body: unknown
+  try {
+    body = await response.json()
+  } catch {
+    throw new SkillHubApiError('HTTP ' + response.status + ': invalid JSON response')
+  }
+  if (!response.ok) {
+    const message = typeof body === 'object' && body !== null && typeof (body as { error?: unknown }).error === 'string'
+      ? (body as { error: string }).error
+      : 'HTTP ' + response.status
+    throw new SkillHubApiError(message)
+  }
+  return body as T
+}
+
+/**
+ * Fetch with a hard timeout: a hung connection (proxy, stalled keep-alive,
+ * host wedged) must never leave the panel stuck on "loading" forever — it
+ * fails fast and surfaces the error banner instead.
+ */
+async function fetchWithTimeout(input: RequestInfo | URL, init?: RequestInit, ms = 10_000): Promise<Response> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), ms)
+  try {
+    return await fetch(input, { ...init, signal: controller.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** The browser half's only data entry point. */
+export class SkillHubApi {
+  async catalog(): Promise<CatalogResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.catalog)
+    return readJson<CatalogResponse>(response)
+  }
+
+  async skill(name: string): Promise<SkillDetail> {
+    const url = SKILL_HUB_API.skill + '?name=' + encodeURIComponent(name)
+    const response = await fetchWithTimeout(url)
+    const body = await readJson<SkillDetailResponse>(response)
+    return body.skill
+  }
+
+  /** Move one writable skill into the restorable trash. */
+  async deleteSkill(name: string): Promise<SkillDeleteResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.skillDelete, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name } satisfies SkillDeleteRequest),
+    })
+    return readJson<SkillDeleteResponse>(response)
+  }
+
+  /** Toggle one skill; resolves with the fresh catalog from the route. */
+  async toggle(name: string, enabled: boolean): Promise<CatalogResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.toggle, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name, enabled } satisfies import('../protocol.ts').ToggleRequest),
+    })
+    const body = await readJson<import('../protocol.ts').ToggleResponse>(response)
+    return body.catalog
+  }
+
+  async create(payload: CreateRequest): Promise<CreateResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.create, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    return readJson<CreateResponse>(response)
+  }
+
+  async stats(): Promise<StatsResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.stats)
+    return readJson<StatsResponse>(response)
+  }
+
+  /** Toggle a whole group in one write; resolves with the fresh catalog + failures. */
+  async toggleBatch(names: string[], enabled: boolean): Promise<ToggleBatchResponse> {
+    const payload: ToggleBatchRequest = { names, enabled }
+    const response = await fetchWithTimeout(SKILL_HUB_API.toggleBatch, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    return readJson<ToggleBatchResponse>(response)
+  }
+
+  /** The user's added market sources (codex-style repo slugs). */
+  async market(): Promise<MarketSourcesResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.market)
+    return readJson<MarketSourcesResponse>(response)
+  }
+
+  /** Add a market source repo; resolves with the fresh list. */
+  async addMarketSource(repo: string): Promise<MarketSourcesResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.marketSource, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ repo } satisfies MarketSourceRequest),
+    })
+    return readJson<MarketSourceResponse>(response)
+  }
+
+  /** Remove a market source repo; resolves with the fresh list. */
+  async removeMarketSource(repo: string): Promise<MarketSourcesResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.marketSourceDelete, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ repo } satisfies MarketSourceRequest),
+    })
+    return readJson<MarketSourceResponse>(response)
+  }
+
+  /** Check every market source for updates (throttled server-side). */
+  async marketCheck(): Promise<MarketCheckResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.marketCheck)
+    return readJson<MarketCheckResponse>(response)
+  }
+
+  /** Align a market source to its pinned ref; resolves with tracked skills. */
+  async marketSync(repo: string): Promise<MarketSyncResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.marketSync, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ repo }),
+    })
+    return readJson<MarketSyncResponse>(response)
+  }
+
+  /** Pin a market source to an explicit ref (branch picker). */
+  async setMarketSourceRef(repo: string, ref: string): Promise<MarketSourcesResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.marketSourceRef, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ repo, ref } satisfies MarketSourceRefRequest),
+    })
+    return readJson<MarketSourceResponse>(response)
+  }
+
+  /** Check the hub's own latest GitHub release. */
+  async updateCheck(): Promise<UpdateCheckResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.update)
+    return readJson<UpdateCheckResponse>(response)
+  }
+
+  /** Discover importable skills in a GitHub repo. */
+  async repoDiscover(repo: string): Promise<RepoDiscoverResponse> {
+    const url = SKILL_HUB_API.repo + '?repo=' + encodeURIComponent(repo)
+    const response = await fetchWithTimeout(url)
+    return readJson<RepoDiscoverResponse>(response)
+  }
+
+  /** Install selected repo skills into the user-dsh root (records the source). */
+  async repoImport(repo: string, paths: string[], ref?: string): Promise<RepoImportResponse> {
+    const payload: RepoImportRequest = { repo, paths, ...(ref !== undefined && ref !== '' ? { ref } : {}) }
+    const response = await fetchWithTimeout(SKILL_HUB_API.repoImport, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    return readJson<RepoImportResponse>(response)
+  }
+
+  /** Read the hub's runtime config (effective values + saved overrides). */
+  async config(): Promise<ConfigResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.config)
+    return readJson<ConfigResponse>(response)
+  }
+
+  /** Patch the hub's runtime config (null clears a saved override). */
+  async saveConfig(patch: ConfigRequest): Promise<ConfigResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.config, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(patch),
+    })
+    return readJson<ConfigResponse>(response)
+  }
+
+  /** 用户 tag 分组 + 系统集合组 + origin 映射。 */
+  async groups(): Promise<import('../protocol.ts').GroupsResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.groups)
+    return readJson<import('../protocol.ts').GroupsResponse>(response)
+  }
+
+  /** 新建（无 id）或重命名（带 id）一个 tag 分组；返回全部 tag。 */
+  async saveTag(payload: import('../protocol.ts').TagSaveRequest): Promise<import('../protocol.ts').SkillTag[]> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.tag, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    const body = await readJson<import('../protocol.ts').TagSaveResponse>(response)
+    return body.tags
+  }
+
+  /** 删除一个 tag 分组；返回全部 tag。 */
+  async deleteTag(id: string): Promise<import('../protocol.ts').SkillTag[]> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.tagDelete, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id } satisfies import('../protocol.ts').TagDeleteRequest),
+    })
+    const body = await readJson<import('../protocol.ts').TagDeleteResponse>(response)
+    return body.tags
+  }
+
+  /** 直接设置某 tag 的完整成员列表；返回全部 tag。 */
+  async setTagMembers(id: string, skillNames: string[]): Promise<import('../protocol.ts').SkillTag[]> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.tagMembers, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id, skillNames } satisfies import('../protocol.ts').TagMembersRequest),
+    })
+    const body = await readJson<import('../protocol.ts').TagMembersResponse>(response)
+    return body.tags
+  }
+
+  /** 来源列表 + 派生 origin 映射 + 集合组 + 回收站。 */
+  async sources(): Promise<SourcesResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.sources)
+    return readJson<SourcesResponse>(response)
+  }
+
+  /** 检查指定（或全部）来源的上游更新。 */
+  async checkSources(repo?: string): Promise<SourceCheckResponse> {
+    const payload: SourceCheckRequest = repo !== undefined ? { repo } : {}
+    const response = await fetchWithTimeout(SKILL_HUB_API.sourceCheck, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    return readJson<SourceCheckResponse>(response)
+  }
+
+  /** 同步一个来源的所选（或全部）技能到上游最新版本。 */
+  async syncSource(repo: string, skills?: string[]): Promise<SourceSyncResponse> {
+    const payload: SourceSyncRequest = skills !== undefined ? { repo, skills } : { repo }
+    const response = await fetchWithTimeout(SKILL_HUB_API.sourceSync, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    return readJson<SourceSyncResponse>(response)
+  }
+
+  /** 跟进上游删除：把所选技能移入回收站。 */
+  async confirmDeleteSource(repo: string, skills: string[]): Promise<SourceDeleteResponse> {
+    const payload: SourceDeleteRequest = { repo, skills }
+    const response = await fetchWithTimeout(SKILL_HUB_API.sourceDelete, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    return readJson<SourceDeleteResponse>(response)
+  }
+
+  /** 从回收站恢复一个技能。 */
+  async restoreSource(name: string): Promise<SourceRestoreResponse> {
+    const payload: SourceRestoreRequest = { name }
+    const response = await fetchWithTimeout(SKILL_HUB_API.sourceRestore, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    return readJson<SourceRestoreResponse>(response)
+  }
+
+  /** Permanently delete every skill currently in the trash. */
+  async clearTrash(): Promise<SourceTrashClearResponse> {
+    const response = await fetchWithTimeout(SKILL_HUB_API.sourceTrashClear, { method: 'POST' })
+    return readJson<SourceTrashClearResponse>(response)
+  }
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,5 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+