dsh-skill-hub 0.3.13 → 0.3.15

package/src/client/slash-dots.tsx

@@ -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
@@ -19,13 +20,12 @@
  */
 
 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'
 // Type-only: pulls the Context merge for ctx.inputTriggers.
 import type {} from '@deepseek-ai/dsh-client-ui-input-trigger/client'
 // Type-only: pulls the connection/reset event.
 import type {} from '@deepseek-ai/dsh-client-connection/client'
-import type { InputTriggerCandidate, InputTriggerServiceContract, InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
-import { createElement } from 'react'
+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'
 import { DEFAULT_DOT_MODEL_COLOR, DEFAULT_DOT_USER_COLOR } from './panel/format.ts'
@@ -92,37 +92,11 @@ async function modelInvocableMap(api: SkillHubApi): Promise<Map<string, boolean>
 }
 
 /**
- * One menu-row dot element. Inline span so it needs no CSS module; the
- * candidate menu centers it inside its 16×16 leading icon slot.
- * @param color - the dot's background color.
- * @returns a React node (memory-only, never crosses the Host boundary).
- */
-function dotIcon(color: string): InputTriggerCandidate['icon'] {
-  return createElement('span', {
-    'aria-hidden': true,
-    style: {
-      display: 'inline-block',
-      width: 6,
-      height: 6,
-      borderRadius: 3,
-      background: color,
-      flex: 'none',
-    },
-  }) as unknown as InputTriggerCandidate['icon']
-}
-
-/**
- * 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.
- */
-/**
- * DOM 兜底：在 alpha.2 新版 MenuView（icon 仅枚举）下通过直接操作
- * 已渲染的 `[role="option"]` 列表注入彩色点，绕过 `icon` 限制。
- * 旧版仍走 `icon` 注入，此处仅为新版。
+ * 通过直接操作已渲染的 `[role="option"]` 列表注入彩色点，
+ * 绕过 MenuView 对 `icon` 的枚举限制。
+ * @param modelByName - 技能名 → 模型可调用性；不在表内的候选不注点。
+ * @param modelColor - 模型可调用技能的点色。
+ * @param userColor - 仅用户可调用技能的点色。
  */
 function injectDotsViaDOM(modelByName: Map<string, boolean>, modelColor: string, userColor: string): void {
   if (typeof document === 'undefined' || typeof requestAnimationFrame === 'undefined') return
@@ -145,7 +119,7 @@ function injectDotsViaDOM(modelByName: Map<string, boolean>, modelColor: string,
       // 仅对技能生效：非技能候选（/command、@file 等）不在 catalog，不注点
       if (!modelByName.has(name)) continue
       const color = (modelByName.get(name) ?? true) ? modelColor : userColor
-      // 复刻旧版 icon 槽：16×16 容器居中 6px 点，与升级前 `dotIcon` 在 `itemIcon` 内的效果一致
+      // 布局对齐菜单行原有的 icon 槽：16×16 容器居中 6px 点
       const wrapper = document.createElement('span')
       wrapper.setAttribute('data-skill-dot', '')
       wrapper.setAttribute('aria-hidden', 'true')
@@ -163,37 +137,33 @@ function injectDotsViaDOM(modelByName: Map<string, boolean>, modelColor: string,
       dot.style.background = color
       dot.style.flex = 'none'
       wrapper.appendChild(dot)
-      // 新版无 icon 槽，直接插在名称前，与旧版 `itemIcon` 位置一致
+      // 直接插在名称前，与菜单行原有 icon 槽的位置一致
       nameEl.parentElement?.insertBefore(wrapper, nameEl)
     }
   }
   requestAnimationFrame(() => setTimeout(run, 0))
 }
 
-export 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 function wrapSkillSource(source: InputTriggerSource, api: SkillHubApi, scope: ConfigForm<HubSettingsValue>): () => void {
   const original = source.candidates
   source.candidates = async (session, req) => {
     const items = await original(session, req)
     if (req.signal.aborted) return items
-    // Dual-compat: 0.1.2-alpha.2 的 MenuView 将 icon 收窄为 'file'|'folder'|'session'
-    // 并通过 ReferenceIcon 渲染，旧版的自定义 ReactElement 点已无法展示。
-    // 以 `drilled` 是否存在探测新版（alpha.2 必有，rc 无）。
-    const isNewHost = req !== null && typeof req === 'object' && 'drilled' in (req as unknown as Record<string, unknown>)
     const modelByName = await modelInvocableMap(api)
     if (req.signal.aborted) return items
     const snapshot = scope.getSnapshot()
     const modelColor = snapshot.value?.dotModelColor ?? DEFAULT_DOT_MODEL_COLOR
     const userColor = snapshot.value?.dotUserColor ?? DEFAULT_DOT_USER_COLOR
-    if (isNewHost) {
-      // 新版：不通过 icon（枚举限制），改为 DOM 注入
-      injectDotsViaDOM(modelByName, modelColor, userColor)
-      return items
-    }
-    // 旧版：保持原有 icon 注入
-    return items.map((item) => ({
-      ...item,
-      icon: dotIcon((modelByName.get(item.name) ?? true) ? modelColor : userColor),
-    }))
+    injectDotsViaDOM(modelByName, modelColor, userColor)
+    return items
   }
   return () => {
     source.candidates = original
@@ -214,7 +184,7 @@ export function wrapSkillSource(source: InputTriggerSource, api: SkillHubApi, sc
 export function setupSkillSlashDots(
   ctx: ClientContext,
   api: SkillHubApi,
-  scope: SettingsScope<HubSettingsValue>,
+  scope: ConfigForm<HubSettingsValue>,
 ): () => void {
   const inputTriggers = ctx.get('inputTriggers')
   if (inputTriggers === undefined) return () => {}

package/src/index.ts

@@ -7,16 +7,19 @@
  * source changes.
  */
 
-import type { Context } from '@deepseek-ai/cordis'
+import type { Context, Volatile } from '@deepseek-ai/cordis'
 import type { SkillProviderControl } from '@deepseek-ai/dsh-skill'
-import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
-import z from 'schemastery'
+import type { SettingsForms, SettingsNamespace, SettingsPathOp } from '@deepseek-ai/dsh-settings'
+// dsh's own fork, NOT the plain `schemastery` package: `.volatile()` (and the
+// loader's `fiber.runtime.Config` handling) only exist here. Every official
+// plugin imports it under this name.
+import z from '@deepseek-ai/schemastery'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-skill'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-session-query'
 import type {} from '@deepseek-ai/dsh-settings'
-import { HUB_CONFIG_DEFAULTS, HEX_COLOR_RE, type HubConfig, type HubSettingsValue } from './protocol.ts'
+import { HUB_CONFIG_DEFAULTS, HUB_ENTRY_ID, HEX_COLOR_RE, resolveHubConfig, type HubConfig } from './protocol.ts'
 import { SkillHubProvider } from './provider.ts'
 import { makeRoutes } from './routes.ts'
 import { createSkillStatsReader, asPersistenceSeam, type SessionPersistenceLike, type SessionQueryLike, type SkillStatsReader } from './stats.ts'
@@ -30,87 +33,140 @@ import { homedir } from 'node:os'
 /** Stable cordis plugin name (matches cordis.patch.yml insert id). */
 export const name = 'skill-hub'
 
-/** Services required before the skill-hub surfaces can mount. */
-export const inject = ['webServer', 'skills', 'systemPrompt', 'settings']
+/** 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 const inject = ['webServer', 'skills', 'systemPrompt']
 
-/** 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 const Config: z<Config> = z.object({
-  announceToAgent: z.boolean().default(HUB_CONFIG_DEFAULTS.announceToAgent),
-  enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled),
-  showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount),
-  showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime),
-  showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary),
-  statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays),
-  statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes),
+/**
+ * The durable field schemas, plain (non-volatile) so the same definitions can
+ * back both the live view below and the wire form the settings page renders
+ * from `.toJSON()`. `description` is what the auto-generated page shows with
+ * each row; `role('secret')` makes the settings layer redact the value on
+ * every wire read.
+ */
+const ConfigFields = {
+  enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled).description('关闭后技能中枢的路由、入口与公告全部下线。'),
+  announceToAgent: z.boolean().default(HUB_CONFIG_DEFAULTS.announceToAgent).description('在系统提示中加入本插件说明，用户提到技能管理时 Agent 知道如何协作。'),
+  dotModelColor: z.string().pattern(HEX_COLOR_RE).description('技能行与聊天「/」菜单中「模型可调」圆点的颜色（#rrggbb）。'),
+  dotUserColor: z.string().pattern(HEX_COLOR_RE).description('技能行与聊天「/」菜单中「仅用户可调」圆点的颜色（#rrggbb）。'),
+  showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount).description('在技能名旁显示调用次数。'),
+  showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime).description('在技能名行显示最近调用时间。'),
+  showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary).description('在分组标题后汇总调用次数与最近调用时间。'),
+  statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays).description('只统计最近 N 天的使用次数；0 = 全部历史。'),
+  statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes).description('后台扫描会话日志的间隔（分钟，最小 1）。'),
+  githubToken: z.string().role('secret').description('市场/来源走 GitHub API：匿名每小时 60 次，填 token 后 5000 次。留空即匿名（或跟随 GITHUB_TOKEN 环境变量）。'),
+}
+
+/**
+ * The live plugin config the settings page edits. Field order here is the row
+ * order the auto-generated page renders.
+ */
+export const Config = z.object({
+  enabled: ConfigFields.enabled.volatile(),
+  announceToAgent: ConfigFields.announceToAgent.volatile(),
+  dotModelColor: ConfigFields.dotModelColor.volatile(),
+  dotUserColor: ConfigFields.dotUserColor.volatile(),
+  showUseCount: ConfigFields.showUseCount.volatile(),
+  showUseTime: ConfigFields.showUseTime.volatile(),
+  showGroupSummary: ConfigFields.showGroupSummary.volatile(),
+  statsWindowDays: ConfigFields.statsWindowDays.volatile(),
+  statsScanMinutes: ConfigFields.statsScanMinutes.volatile(),
+  githubToken: ConfigFields.githubToken.volatile(),
 })
 
 /**
- * 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 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 const CONFIG_NAMESPACE = 'dsh-skill-hub' as SettingsNamespace
+export const ENTRY_ID = HUB_ENTRY_ID as SettingsNamespace
 
-/** Schema of the hub's settings namespace: the card's fields (booleans + optional dot colors). */
-export const HubSettingsSchema: z<HubSettingsValue> = z.object({
-  enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled),
-  announceToAgent: z.boolean().default(HUB_CONFIG_DEFAULTS.announceToAgent),
-  showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount),
-  showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime),
-  showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary),
-  dotModelColor: z.string().pattern(HEX_COLOR_RE),
-  dotUserColor: z.string().pattern(HEX_COLOR_RE),
-  githubToken: z.string(),
-  statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays),
-  statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes),
-})
+/** Every config field, in the order the settings page renders them (used to walk the volatile refs). */
+const CONFIG_FIELDS = [
+  'enabled',
+  'announceToAgent',
+  'dotModelColor',
+  'dotUserColor',
+  'showUseCount',
+  'showUseTime',
+  'showGroupSummary',
+  'statsWindowDays',
+  'statsScanMinutes',
+  'githubToken',
+] as const
 
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 152
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
 export const SKILL_HUB_GUIDANCE = [
-  '本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；设置 → 插件列表中有本插件的配置卡片（启用/公告开关）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由仅回环可访问。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。',
-  'The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → "Skills" is the management page; Settings → Plugins lists this plugin\'s configuration card (enable / announcement toggles). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with "check all" and "update all" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics; new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; routes are loopback-only. When the user mentions "skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill", this plugin is what they mean — collaborate accordingly.'
+  '本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；本插件的配置页（启用/公告开关、圆点颜色、GitHub token、统计窗口）在插件管理页——侧边栏「插件」→ 本插件，是本插件自己注册的配置卡片（默认折叠，点标题展开）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由仅回环可访问。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。',
+  'The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → "Skills" is the management page; the plugin\'s configuration page (enable / announcement toggles, dot colors, GitHub token, stats window) is registered by the plugin itself on its own page in the Plugins manager (sidebar → 插件 → the plugin; collapsed until you expand the title). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with "check all" and "update all" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics; new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; routes are loopback-only. When the user mentions "skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill", this plugin is what they mean — collaborate accordingly.'
 ].join('\n\n')
 
 /**
  * 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 function apply(ctx: Context, config?: Config): void {
-  // The hub's runtime configuration lives in dsh's own settings service:
-  // since rc.7 the host serves every registered settings namespace to the
-  // web client (dsh-host-apiproxy's allowlist is gone), so the browser card
-  // and the config route edit this namespace through the official settings
-  // transport, and the host consumes the very same resolved value — one
-  // source of truth. The cordis composition entry seeds the base layer; the
-  // sidecar config survives only as a one-time migration source below.
-  const base = config ?? {}
-  const settingsScope = ctx.settings.register(CONFIG_NAMESPACE, HubSettingsSchema, { base })
-  // The effective resolved config, read live from the settings namespace
-  // (schema defaults, then the composition base, then the user layer).
-  const current = (): HubConfig => settingsScope.get()
+  /**
+   * Read the runtime config out of our own volatile config refs.
+   *
+   * This is the whole point of `volatile()`: the Loader updates those values
+   * **in place** (`ConfigEditor.edit` → `resolveConfig(fiber.runtime, next)` →
+   * `updateVolatile`) without rebuilding the fiber, so a held reference always
+   * answers `.get()` with the current value. Consequences worth remembering:
+   *   - no `settings.describe()` per request (it walks and projects every entry
+   *     in the profile — the reason this used to be slow);
+   *   - no subscription or watcher is needed for *reading*;
+   *   - the plugin keeps working when the Settings service is absent
+   *     (issue #11: business logic must not depend on Settings).
+   */
+  const readConfig = (): Partial<HubConfig> => {
+    const out: Record<string, unknown> = {}
+    for (const field of CONFIG_FIELDS) {
+      const ref = (config as unknown as Record<string, { get?: () => unknown } | undefined> | undefined)?.[field]
+      const value = ref !== undefined && typeof ref.get === 'function' ? ref.get() : ref
+      if (value !== undefined) out[field] = value
+    }
+    return out as Partial<HubConfig>
+  }
+  const current = (): HubConfig => resolveHubConfig({}, readConfig())
+
+  /** The Settings service, when this deployment mounts it. Absent ⇒ no user layer to read or write. */
+  const settingsOf = (): SettingsForms | undefined => ctx.get('settings') as SettingsForms | undefined
 
   const store = new SkillHubStore()
   let disposeRoutes: (() => void) | undefined
@@ -126,26 +182,35 @@ export function apply(ctx: Context, config?: Config): void {
   let stats: SkillStatsReader | undefined
 
   // The raw saved config layer (fields the user explicitly overrode); the
-  // config route reports it so callers can mark overridden fields.
+  // config route reports it so callers can mark overridden fields. Empty when
+  // the deployment has no Settings service — the plugin still runs.
   const saved = (): Partial<HubConfig> => {
-    const descriptor = ctx.settings.describe().find((entry) => entry.ns === CONFIG_NAMESPACE)
+    const descriptor = settingsOf()?.describe().find((entry) => entry.ns === ENTRY_ID)
     return (descriptor?.user as Partial<HubConfig> | undefined) ?? {}
   }
 
-  // Persist a config patch, re-point the live config, and re-sync every
-  // surface through the settings transport. A patch value of undefined clears
-  // the saved override (the key leaves the user section, so the field
-  // re-inherits the base/default) — the old sidecar's reset semantics.
-  // Runs inside the config route handler; the watcher below re-syncs the
-  // surfaces once the namespace commits.
+  // Persist a config patch through the settings transport. A patch value of
+  // undefined clears the saved override — expressed as a path `unset`, which
+  // makes the field fall back to its inherited value instead of writing a
+  // literal undefined (the old sidecar's reset semantics). The write reloads
+  // this Loader entry, so apply() re-runs and re-syncs every surface below.
   const updateConfig = async (patch: Partial<HubConfig>): Promise<HubConfig> => {
-    const user: Record<string, unknown> = { ...saved() }
-    for (const [key, value] of Object.entries(patch) as Array<[keyof HubConfig, boolean | string | number | undefined]>) {
-      if (value === undefined) delete user[key]
-      else user[key] = value
+    const ops: SettingsPathOp[] = []
+    for (const [field, value] of Object.entries(patch)) {
+      if (value === undefined) ops.push({ op: 'unset', path: [field] })
+      else ops.push({ op: 'set', path: [field], value })
+    }
+    const settings = settingsOf()
+    if (settings === undefined) throw new Error('this deployment does not mount the settings service; config is read-only')
+    if (ops.length > 0) {
+      await settings.mutate(ENTRY_ID, ops)
+      // A settings write updates this entry's values in place WITHOUT
+      // re-entering apply() (see `current`), so the section / provider / routes
+      // registered from the old values would otherwise keep serving them until
+      // a restart. Re-evaluate here, where we know the write landed.
+      sync()
     }
-    await settingsScope.replace(user)
-    return settingsScope.get()
+    return current()
   }
 
   // Register (or drop) every surface to match the current config. Each
@@ -165,8 +230,8 @@ export function apply(ctx: Context, config?: Config): void {
     }
     const value = current()
     // GitHub auth for market/source API calls: env GITHUB_TOKEN/GH_TOKEN is the
-    // fallback (read at module load); an explicit settings value wins live and
-    // applies without a restart via the settings watcher below.
+    // fallback (read at module load); an explicit settings value wins and is
+    // applied by re-running this sync from updateConfig after the write lands.
     setGithubToken(value.githubToken)
     if (value.announceToAgent) {
       disposeSection = ctx.systemPrompt.section({
@@ -187,6 +252,7 @@ export function apply(ctx: Context, config?: Config): void {
         'dsh-skill-hub: provider',
       )
     }
+    ctx.logger.info(`[dsh-skill-hub] surfaces synced: enabled=${value.enabled} announceToAgent=${value.announceToAgent}`)
     if (disposeRoutes !== undefined) {
       disposeRoutes()
       disposeRoutes = undefined
@@ -210,14 +276,10 @@ export function apply(ctx: Context, config?: Config): void {
     )
   }
 
-  // Initial registration from the composition entry, then re-sync whenever
-  // the settings namespace commits (any writer — the card, the config route,
-  // or the Host document editor).
+  // Initial registration from the composition entry. Later changes — the
+  // settings page, the config route, the Host document editor — rewrite this
+  // Loader entry, which re-enters apply(), so no in-process watcher is needed.
   sync()
-  ctx.effect(
-    () => settingsScope.watch(() => { sync() }),
-    'dsh-skill-hub: settings config watch',
-  )
 
   // One-time migration: an install upgraded from the sidecar-configured
   // build seeds the settings namespace from the saved sidecar config when the
@@ -251,7 +313,8 @@ export function apply(ctx: Context, config?: Config): void {
     try {
       const legacy = await store.getConfig()
       if (Object.keys(legacy).length > 0 && Object.keys(saved()).length === 0) {
-        await settingsScope.update(legacy as Record<string, unknown>)
+        const settings = settingsOf()
+        if (settings !== undefined) await settings.update(ENTRY_ID, legacy as Record<string, unknown>)
       }
     } catch (error) {
       ctx.logger.warn('[dsh-skill-hub] sidecar config migration into the settings namespace failed', error)

package/src/protocol/api.ts

@@ -1,4 +1,26 @@
-/** 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 const SKILL_HUB_API_ROOT = '/api/skill-hub'
+
+/**
+ * Deprecated path of the market update check, kept routable for one release
+ * after the naming unification below. A browser tab that loaded the previous
+ * client bundle keeps calling it until it reloads; delete this (and its route
+ * in routes/market.ts) in the next minor.
+ */
+export const SKILL_HUB_API_DEPRECATED_MARKET_CHECK = '/api/skill-hub/market/check'
+
+/**
+ * Browser-facing base paths of the skill-hub API family.
+ *
+ * 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 const SKILL_HUB_API = {
   catalog: '/api/skill-hub/catalog',
   skill: '/api/skill-hub/skill',
@@ -12,7 +34,7 @@ export const SKILL_HUB_API = {
   marketSource: '/api/skill-hub/market/source',
   marketSourceDelete: '/api/skill-hub/market/source/delete',
   marketSourceRef: '/api/skill-hub/market/source/ref',
-  marketCheck: '/api/skill-hub/market/check',
+  marketCheck: '/api/skill-hub/market/source/check',
   marketSync: '/api/skill-hub/market/source/sync',
   repo: '/api/skill-hub/repo',
   repoImport: '/api/skill-hub/repo/import',

package/src/protocol/config.ts

@@ -31,6 +31,15 @@ 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
@@ -55,6 +64,15 @@ export type HubSettingsValue = {
   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 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'
@@ -103,6 +121,17 @@ function clampNumber(value: unknown, min: number): number | undefined {
   return Math.floor(value)
 }
 
+/**
+ * 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 function redactGithubToken<T extends { githubToken?: string }>(value: T): Omit<T, 'githubToken'> {
+  const copy: Record<string, unknown> = { ...value }
+  delete copy.githubToken
+  return copy as Omit<T, 'githubToken'>
+}
+
 /** HEX color validation shared by host routes and the settings card. */
 export const HEX_COLOR_RE = /^#[0-9a-f]{6}$/i
 
@@ -111,10 +140,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. */

package/src/protocol/market.ts

@@ -69,7 +69,7 @@ export interface MarketStatsResponse {
   }>
 }
 
-/** 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/src/protocol/repo.ts

@@ -18,9 +18,30 @@ export interface RepoSkillEntry {
   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 const REPO_ROOT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+
+/**
+ * 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 function isValidRepoRoot(value: unknown): value is RepoRoot {
+  return typeof value === 'string' && (value === '' || REPO_ROOT_RE.test(value))
+}
+
 /** GET /api/skill-hub/repo — discover importable skills in a GitHub repo. */
 export interface RepoDiscoverResponse {
   ok: true