dsh-plugin 1.1.2 → 1.2.0

package/src/client/hooks/useCatalog.ts

@@ -5,24 +5,37 @@
  *
  * Catalog data + view state for the Plugin Hub section.
  *
- * Owns the online-data pipeline (live fetch from dsh-plugin.org), the local
+ * Owns the online-data pipeline (live fetch from api.dsh-plugin.org), the local
  * installed-plugin table, and the filter/search/sort/install-status view
  * state, exposing the derived visible list and per-category counts.
  */
 import { useEffect, useMemo, useState } from 'react'
 import type { HubPlugin, LocaleId } from '../types.ts'
-import { HUB_ABOUT_URL, HUB_REPO, HUB_UPDATE_URL, normalize, PLUGIN_VERSION, repoFromInstallTarget } from '../lib/catalog.ts'
-import type { HubAboutInfo, HubUpdateInfo } from '../lib/catalog.ts'
-import type { SortKey } from '../lib/catalog.ts'
+import { HUB_REPO, PLUGIN_VERSION } from '../logic/constants.ts'
+import type { HubAboutInfo, HubUpdateInfo } from '../types.ts'
+import type { SortKey } from '../logic/constants.ts'
+import { fetchCatalog, fetchStats } from '../data/catalog.ts'
+import { fetchHubAbout, fetchHubUpdate } from '../data/hub.ts'
+import { fetchInstalled } from '../data/host.ts'
+import {
+  hasUpdateOf, installedItemsOf, installedNameOf, installedVersionOf,
+} from '../logic/installed.ts'
+import type { InstalledItem, InstalledVersionSignal } from '../logic/installed.ts'
 
-const PLUGINS_URL = (lang: LocaleId) => `https://dsh-plugin.org/api/plugins.${lang}.json`
-const STATS_URL = 'https://dsh-plugin.org/api/stats.json'
 /** 插件市场自身仓库：DSH-Plugin Hub 不显示在目录里（自己不进自己的插件列表） */
 const SELF_REPO = 'dshplugin/dsh-plugin-hub'
 
+/** 市场各排序的默认方向：全部按倒序（Star/Fork 多、更新/收录近的在前） */
+const SORT_DEFAULT_DIR: Record<SortKey, 'asc' | 'desc'> = {
+  sortStars: 'desc', sortForks: 'desc', sortUpdated: 'desc', sortNewest: 'desc',
+}
+
 export function useCatalog(lang: LocaleId) {
   /** 目录插件（仅保留人工验证通过的条目） */
   const [plugins, setPlugins] = useState<HubPlugin[] | null>(null)
+  /** Hub 自身目录条目（dshplugin/dsh-plugin-hub）：目录过滤会排除自身（不进插件列表），
+   *  此处单独保留，供头部「可更新」徽标 → 「直接更新」覆盖重装使用。 */
+  const [hubPlugin, setHubPlugin] = useState<HubPlugin | null>(null)
   /** 收录/精选统计（官网 /api/stats.json 实时拉取） */
   const [stats, setStats] = useState<{ total: number; verified: number } | null>(null)
   const [failed, setFailed] = useState(false)
@@ -30,44 +43,51 @@ export function useCatalog(lang: LocaleId) {
   const [category, setCategory] = useState('all')
   const [query, setQuery] = useState('')
   const [sort, setSort] = useState<SortKey>('sortStars')
-  /** 列表安装状态筛选：全部 / 已安装 / 未安装（分段按钮，单列表内切换，不引入第二个列表） */
-  const [installedFilter, setInstalledFilter] = useState<'all' | 'installed' | 'notInstalled'>('all')
+  /** 当前排序方向：点同一个排序按钮切换 正序/倒序；点新排序用该排序的默认方向（与已安装视图一致） */
+  const [sortDir, setSortDir] = useState<'asc' | 'desc'>('desc')
+
+  /** 点击排序按钮：同一按钮切换正/倒序，新按钮用默认方向 */
+  function toggleSort(key: SortKey) {
+    if (key === sort) setSortDir((d) => (d === 'asc' ? 'desc' : 'asc'))
+    else { setSort(key); setSortDir(SORT_DEFAULT_DIR[key]) }
+  }
   /** 当前 profile 已安装插件：npm 包名 -> manifest spec（来自宿主本地路由） */
   const [installed, setInstalled] = useState<Record<string, string>>({})
   /** 安装时记录的目录信号：repo(小写) -> { version, updatedAt }（来自宿主本地路由）；
    *  npmPackage 为 npm 优先通道反查命中的包名映射（目录数据未下发时客户端靠它把依赖 key 匹配回仓库） */
-  const [versions, setVersions] = useState<Record<string, { version: string; updatedAt: string; npmPackage?: string }>>({})
-  /** Hub 自我更新信息：来自 CF Worker 版本控制中心（hub.dsh-plugin.org），与目录数据解耦 */
+  const [versions, setVersions] = useState<Record<string, InstalledVersionSignal>>({})
+  /** 每个依赖在系统上的安装目录（profile/node_modules/<包名>），详情视图展示用 */
+  const [installPaths, setInstallPaths] = useState<Record<string, string> | null>(null)
+  /** 已加载进运行中 loader 的包名（官方 ctx.loader 对账）：装完未重启的新插件不在其中 */
+  const [loadedNames, setLoadedNames] = useState<string[] | null>(null)
+  /** 真正的 dsh 插件包名（包内声明 dsh 配置 / 在 profile bundles 清单）：非 dsh 插件不提示「待重启」 */
+  const [dshCapableNames, setDshCapableNames] = useState<string[] | null>(null)
+  /** Hub 自我更新信息：来自接口中心 Pages（api.dsh-plugin.org），与目录数据解耦 */
   const [hubUpdateInfo, setHubUpdateInfo] = useState<HubUpdateInfo | null>(null)
-  /** 头部「关注我们」弹窗内容（平台介绍 + 反馈群二维码）：来自同款 Worker /about，Markdown 推送非写死 */
+  /** 头部「关注我们」弹窗内容（平台介绍 + 反馈群二维码）：来自接口中心 /about，Markdown 推送非写死 */
   const [hubAboutInfo, setHubAboutInfo] = useState<HubAboutInfo | null>(null)
 
   // 拉取目录 + 统计。在线 API 已只返回 verified；再过滤一次，保证只展示人工验证通过的插件。
   useEffect(() => {
     let cancelled = false
     setPlugins(null)
+    setHubPlugin(null)
     setStats(null)
     setFailed(false)
-    const fetchData = (url: string): Promise<unknown> =>
-      fetch(url, { cache: 'no-store' }).then((res) => {
-        if (!res.ok) throw new Error(String(res.status))
-        return res.json()
-      })
     // 目录数据直拉：hub 自身版本由独立 Worker 版本控制中心管理，不再依赖主站版本号接口；
     // 数据接口 CDN 缓存 1 小时，发布新数据后最长 1 小时全网生效。
-    const load = () =>
-      Promise.all([fetchData(PLUGINS_URL(lang)), fetchData(STATS_URL)])
+    const load = () => Promise.all([fetchCatalog(lang), fetchStats()])
     load()
-      .then(([data, s]) => {
+      .then(([list, stats]) => {
         if (cancelled) return
-        const list = (Array.isArray(data) ? data : []).map((item) => normalize(item as Record<string, unknown>))
         // 插件市场不显示自己：DSH-Plugin Hub 从目录里排除自身条目，
         // 防止「自己出现在自己的插件列表里、还能自己安装自己」；统计计数同步减 1 保持与列表一致。
         // 主站数据已同步排除自身，此处为 CDN 缓存期的兜底。
         const hadSelf = list.some((p) => p.source?.repo === SELF_REPO)
+        // 过滤前单独保留 hub 自身条目：它不进目录列表，但「可更新」徽标的直接更新需要它作为重装目标
+        setHubPlugin(list.find((p) => p.source?.repo === SELF_REPO) ?? null)
         setPlugins(list.filter((p) => p.compatibility?.status === 'verified' && p.source?.repo !== SELF_REPO))
-        const stats = s as { total?: number; verified?: number }
-        if (stats && typeof stats.total === 'number' && typeof stats.verified === 'number') {
+        if (stats) {
           setStats(hadSelf
             ? { total: stats.total - 1, verified: stats.verified - 1 }
             : { total: stats.total, verified: stats.verified })
@@ -83,15 +103,13 @@ export function useCatalog(lang: LocaleId) {
 
   /** 刷新当前 profile 已安装插件表；宿主未挂本地路由时静默降级为空表。 */
   const refreshInstalled = async () => {
-    try {
-      const res = await fetch('/dsh-plugin-hub/installed', { cache: 'no-store' })
-      if (!res.ok) return
-      const data = await res.json() as { installed?: Record<string, string>; versions?: Record<string, { version: string; updatedAt: string; npmPackage?: string }> }
-      setInstalled(data.installed ?? {})
-      setVersions(data.versions ?? {})
-    } catch {
-      // host without the plugin's server routes — keep the empty table
-    }
+    const data = await fetchInstalled()
+    if (data === null) return
+    setInstalled(data.installed)
+    setVersions(data.versions)
+    setInstallPaths(data.paths)
+    setLoadedNames(data.loaded)
+    setDshCapableNames(data.dshCapable)
   }
 
   // 首次进入拉取已安装表（依赖宿主 webServer 服务）
@@ -102,16 +120,7 @@ export function useCatalog(lang: LocaleId) {
   // 失败静默降级为 null（徽标不出现，不影响目录本身加载）。
   useEffect(() => {
     let cancelled = false
-    fetch(HUB_UPDATE_URL, { cache: 'no-store' })
-      .then((res): Promise<HubUpdateInfo | null> => (res.ok ? res.json() : Promise.resolve(null)))
-      .then((data) => {
-        if (cancelled || !data) { if (!cancelled) setHubUpdateInfo(null); return }
-        const version = typeof data.version === 'string' && data.version.length > 0 ? data.version : null
-        setHubUpdateInfo(version === null
-          ? null
-          : { version, publishedAt: data.publishedAt ?? null, notes: data.notes ?? null })
-      })
-      .catch(() => { if (!cancelled) setHubUpdateInfo(null) })
+    void fetchHubUpdate().then((info) => { if (!cancelled) setHubUpdateInfo(info) })
     return () => { cancelled = true }
   }, [reloadKey])
 
@@ -119,62 +128,28 @@ export function useCatalog(lang: LocaleId) {
   // 客户端下次进入拉 /about 即可看到最新，非写死。失败静默为 null（弹窗展示兜底文案，不阻塞）。
   useEffect(() => {
     let cancelled = false
-    fetch(HUB_ABOUT_URL, { cache: 'no-store' })
-      .then((res): Promise<HubAboutInfo | null> => (res.ok ? res.json() : Promise.resolve(null)))
-      .then((data) => {
-        if (cancelled) return
-        if (!data || data.content === null || data.content === undefined) { setHubAboutInfo(null); return }
-        const content = typeof data.content === 'string' || typeof data.content === 'object' ? data.content : null
-        setHubAboutInfo(content === null
-          ? null
-          : { content, updatedAt: data.updatedAt ?? null })
-      })
-      .catch(() => { if (!cancelled) setHubAboutInfo(null) })
+    void fetchHubAbout().then((info) => { if (!cancelled) setHubAboutInfo(info) })
     return () => { cancelled = true }
   }, [reloadKey])
 
   /** 插件是否已安装：匹配 Git spec 中的 owner/repo，或 npm 通道安装的依赖包名；命中返回 npm 包名。 */
-  const installedName = (p: HubPlugin): string | null => {
-    const repo = p.source?.repo
-    if (!repo) return null
-    const needle = repo.toLowerCase()
-    for (const [name, spec] of Object.entries(installed)) {
-      if (repoFromInstallTarget(spec).toLowerCase() === needle) return name
-    }
-    // npm 通道安装：profile 依赖 key 直接是 npm 包名。包名来源两处——目录数据（npmPackage），
-    // 或服务端 npm 优先反查持久化的映射（versions[repo].npmPackage，覆盖组织 scope 与 GitHub
-    // 用户名不一致、目录未下发包名的场景）；命中任一并依赖 key 真实存在即视为已安装
-    const pkg = ((p.source?.npmPackage || versions[repo.toLowerCase()]?.npmPackage) ?? '').toLowerCase()
-    if (pkg) {
-      for (const name of Object.keys(installed)) {
-        if (name.toLowerCase() === pkg) return name
-      }
-    }
-    return null
-  }
+  const installedName = (p: HubPlugin): string | null => installedNameOf(p, installed, versions)
 
   /** 该插件安装时记录的目录版本（无记录/未安装 → null）。 */
-  const installedVersion = (p: HubPlugin): string | null => {
-    const repo = p.source?.repo
-    if (!repo) return null
-    return versions[repo.toLowerCase()]?.version ?? null
-  }
+  const installedVersion = (p: HubPlugin): string | null => installedVersionOf(p, versions)
 
   /**
    * 是否有更新：仅对已安装插件有意义。
    * 双信号判定——有 release 版本的比版本；无版本（repo 不打 tag）的比仓库最近更新时间
    * （repoUpdatedAt，ISO 字符串字典序 = 时间序），更新时间变新说明有新提交。
    */
-  const hasUpdate = (p: HubPlugin): boolean => {
-    if (installedName(p) === null) return false
-    const repo = p.source?.repo
-    if (!repo) return false
-    const rec = versions[repo.toLowerCase()]
-    if (!rec) return false
-    if (p.version) return p.version !== rec.version
-    const current = p.dates?.repoUpdatedAt
-    return Boolean(current && rec.updatedAt && current > rec.updatedAt)
-  }
+  const hasUpdate = (p: HubPlugin): boolean => hasUpdateOf(p, installed, versions)
+
+  /** 已安装项统一列表（目录元数据 + 运行时信息合并）：驱动「已安装」tab。 */
+  const installedItems = useMemo<InstalledItem[]>(
+    () => installedItemsOf(plugins, installed, versions, installPaths, loadedNames, dshCapableNames),
+    [plugins, installed, versions, installPaths, loadedNames, dshCapableNames],
+  )
 
   /**
    * Hub 自身是否有可用更新：Hub 就是当前运行的应用（始终已安装，无需 installedName 命中）。
@@ -195,31 +170,11 @@ export function useCatalog(lang: LocaleId) {
     return plugins.filter((p) => p.category === category)
   }, [plugins, category])
 
-  /** 当前分类下已安装插件数：已安装/未安装按钮上的计数跟随分类，不再用全局口径。 */
-  const installedCountInCategory = useMemo(() => {
-    return categoryPlugins.reduce((n, p) => n + (installedName(p) !== null ? 1 : 0), 0)
-  }, [categoryPlugins, installed])
-
-  /** 当前分类下未安装插件数。 */
-  const notInstalledCountInCategory = Math.max(0, categoryPlugins.length - installedCountInCategory)
-
-  // 自动重置：切换分类（或已安装表变化）后，若当前安装状态筛选在新分类下无结果，
-  // 自动退回「全部」，避免列表空置死胡同、也避免 0 计数按钮被误触。
-  useEffect(() => {
-    if (installedFilter === 'all') return
-    const count = installedFilter === 'installed'
-      ? installedCountInCategory
-      : notInstalledCountInCategory
-    if (count === 0) setInstalledFilter('all')
-  }, [installedFilter, installedCountInCategory, notInstalledCountInCategory])
-
   const visible = useMemo(() => {
     if (!plugins) return []
     const q = query.trim().toLowerCase()
     const list = plugins.filter((p) => {
       if (category !== 'all' && p.category !== category) return false
-      if (installedFilter === 'installed' && installedName(p) === null) return false
-      if (installedFilter === 'notInstalled' && installedName(p) !== null) return false
       if (!q) return true
       return (
         (p.displayName ?? '').toLowerCase().includes(q) ||
@@ -227,13 +182,15 @@ export function useCatalog(lang: LocaleId) {
         (p.topics ?? []).some((topic) => topic.toLowerCase().includes(q))
       )
     })
+    const dir = sortDir === 'asc' ? 1 : -1
     return [...list].sort((a, b) => {
-      if (sort === 'sortStars') return (b.stats?.stargazers_count ?? 0) - (a.stats?.stargazers_count ?? 0)
-      if (sort === 'sortForks') return (b.stats?.forks_count ?? 0) - (a.stats?.forks_count ?? 0)
-      if (sort === 'sortNewest') return (b.dates?.addedAt ?? '').localeCompare(a.dates?.addedAt ?? '')
-      return (b.dates?.repoUpdatedAt ?? '').localeCompare(a.dates?.repoUpdatedAt ?? '')
+      // 比较器统一用「升序写法」再乘 dir：desc 时 dir=-1 翻成降序（Star/Fork 最多、更新/收录最近在前）
+      if (sort === 'sortStars') return ((a.stats?.stargazers_count ?? 0) - (b.stats?.stargazers_count ?? 0)) * dir
+      if (sort === 'sortForks') return ((a.stats?.forks_count ?? 0) - (b.stats?.forks_count ?? 0)) * dir
+      if (sort === 'sortNewest') return (a.dates?.addedAt ?? '').localeCompare(b.dates?.addedAt ?? '') * dir
+      return (a.dates?.repoUpdatedAt ?? '').localeCompare(b.dates?.repoUpdatedAt ?? '') * dir
     })
-  }, [plugins, category, query, sort, installed, installedFilter])
+  }, [plugins, category, query, sort, sortDir, installed])
 
   /** Per-category plugin counts shown on the category chips. */
   const categoryCounts = useMemo(() => {
@@ -246,10 +203,12 @@ export function useCatalog(lang: LocaleId) {
 
   return {
     plugins,
+    hubPlugin,
     stats,
     failed,
     reload: () => setReloadKey((k) => k + 1),
     installed,
+    installedItems,
     installedName,
     installedVersion,
     hasUpdate,
@@ -262,13 +221,10 @@ export function useCatalog(lang: LocaleId) {
     query,
     setQuery,
     sort,
-    setSort,
-    installedFilter,
-    setInstalledFilter,
+    sortDir,
+    toggleSort,
     visible,
     total: plugins?.length ?? 0,
-    installedCountInCategory,
-    notInstalledCountInCategory,
     categoryCounts,
   }
 }

package/src/client/hooks/useIncrementalList.ts

@@ -0,0 +1,46 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Incremental list: renders only the first batch of a (potentially huge)
+ * result set and appends the next batch whenever the end sentinel scrolls
+ * into view, so the plugin center never mounts thousands of cards at once.
+ * The items reference is the list identity — category / search / sort
+ * changes produce a new array, which resets the window to the first batch.
+ */
+import { useEffect, useRef, useState } from 'react'
+
+/** 首批渲染条数 & 每次滚到底追加的增量（单卡约 80px 高，100 条已远超一屏） */
+const PAGE_SIZE = 100
+/** 哨兵进入视口底部前 800px 就提前加载下一批，滚到底时无感知衔接 */
+const PRELOAD_MARGIN = '800px 0px'
+
+export function useIncrementalList<T>(items: T[]) {
+  const [limit, setLimit] = useState(PAGE_SIZE)
+  const sentinelRef = useRef<HTMLDivElement | null>(null)
+
+  // 筛选/分类/排序变化 → items 引用变化 → 窗口重置回首批
+  useEffect(() => {
+    setLimit(PAGE_SIZE)
+  }, [items])
+
+  // 哨兵进入视口（含预加载区）→ 追加下一批；已全部渲染则不再观察
+  useEffect(() => {
+    const el = sentinelRef.current
+    if (!el || limit >= items.length) return
+    const io = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) setLimit((cur) => Math.min(cur + PAGE_SIZE, items.length))
+      }
+    }, { rootMargin: PRELOAD_MARGIN })
+    io.observe(el)
+    return () => io.disconnect()
+  }, [items.length, limit])
+
+  return {
+    shown: items.slice(0, limit),
+    hasMore: limit < items.length,
+    sentinelRef,
+  }
+}

package/src/client/hooks/useLanguage.ts

@@ -0,0 +1,40 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Language state for the section: follows the host (system) locale by
+ * default, with an optional manual toggle that wins until the user changes
+ * it back. Exposes the localized dictionary lookup `t()` plus the zh/en
+ * language flag and the /zh/ URL path prefix.
+ */
+import { useState } from 'react'
+import type { LocaleId, SectionProps } from '../types.ts'
+import { en, zh } from '../locales.ts'
+import { langPathOf } from '../logic/urls.ts'
+
+export function useLanguage(locale: SectionProps['locale']) {
+  /** 界面语言：默认跟随宿主（系统）语言；右上角按钮可手动切换，切换后以手动选择为准 */
+  const [manualLang, setManualLang] = useState<LocaleId | null>(null)
+  const lang: LocaleId = manualLang ?? locale.getSnapshot().active
+  const langKey: LocaleId = lang === 'en' ? 'en' : 'zh'
+  // dsh-plugin.org keeps zh pages under the /zh/ prefix; en is the root.
+  const langPath = langPathOf(lang)
+
+  // 界面语言跟随宿主（系统）locale 自动切换；宿主的 t() 绑定宿主 locale，
+  // 这里基于本地字典自建翻译函数，与宿主 locale 保持一致。
+  // （settings.section 的导航 label 仍在 apply 里用宿主 t()，跟随宿主语言。）
+  const dict: Record<string, string> = langKey === 'en' ? en : zh
+  const t = (key: string, params?: Record<string, string | number>): string => {
+    const raw = dict[key] ?? key
+    return params ? raw.replace(/\{(\w+)\}/g, (_, k) => String(params[k] ?? '')) : raw
+  }
+
+  return {
+    lang,
+    langKey,
+    langPath,
+    t,
+    toggleLang: () => setManualLang(lang === 'en' ? 'zh' : 'en'),
+  }
+}

package/src/client/hooks/useSettings.ts

@@ -0,0 +1,90 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Hub settings state: loaded once from the host's local /settings route
+ * (persisted at ~/.dsh/profiles/<profile>/hub-settings.json), updated
+ * optimistically. Every change POSTs the patch immediately so a toggled
+ * switch survives a reload; a host without the server routes falls back to
+ * the defaults and keeps working (settings simply do not persist).
+ */
+import { useCallback, useEffect, useState } from 'react'
+
+export interface HubSettings {
+  /** 启动时检查目录插件更新，发现可更新时在通知中心提示（安装不自动进行） */
+  checkUpdatesOnStart: boolean
+  /** npm 镜像源 registry 地址（空串 = 官方 https://registry.npmjs.org） */
+  npmRegistry: string
+  /** HTTP(S) 代理地址，用于 npm / git / 目录请求（空串 = 直连） */
+  proxy: string
+  /** 启用命令行安装 NPM 包（默认开） */
+  enableNpmInstall: boolean
+  /** 启用命令行安装 GitHub 源码（默认开） */
+  enableGitInstall: boolean
+  /** 启用命令行粘贴 dsh plugin 命令安装（默认开） */
+  enableDshInstall: boolean
+  /** 日志存放位置覆盖（空串 = 默认 ~/.dsh/profiles/<profile>/hub.log） */
+  logPath: string
+}
+
+export const DEFAULT_SETTINGS: HubSettings = {
+  checkUpdatesOnStart: true,
+  npmRegistry: '',
+  proxy: '',
+  enableNpmInstall: true,
+  enableGitInstall: true,
+  enableDshInstall: true,
+  logPath: '',
+}
+
+async function loadRemote(): Promise<HubSettings> {
+  try {
+    const res = await fetch('/dsh-plugin-hub/settings', { cache: 'no-store' })
+    if (!res.ok) throw new Error(`settings ${res.status}`)
+    const data = await res.json() as Partial<HubSettings>
+    return { ...DEFAULT_SETTINGS, ...data }
+  } catch {
+    return DEFAULT_SETTINGS
+  }
+}
+
+export function useSettings() {
+  const [settings, setSettings] = useState<HubSettings>(DEFAULT_SETTINGS)
+  /** 服务端配置是否已加载：更新策略等启动期逻辑须等真实值，避免用默认值误触发 */
+  const [ready, setReady] = useState(false)
+
+  useEffect(() => {
+    let alive = true
+    void loadRemote().then((s) => {
+      if (!alive) return
+      setSettings(s)
+      setReady(true)
+    })
+    return () => { alive = false }
+  }, [])
+
+  /** 部分更新：本地立即生效（乐观），同时 POST 持久化；持久化失败静默（本次会话仍生效）。 */
+  const update = useCallback((patch: Partial<HubSettings>) => {
+    setSettings((prev) => ({ ...prev, ...patch }))
+    void fetch('/dsh-plugin-hub/settings', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(patch),
+      cache: 'no-store',
+    }).catch(() => { /* 宿主未挂路由：仅本次会话生效 */ })
+  }, [])
+
+  /** 重置为默认设置：本地立即回默认，同时通知服务端删除设置文件；失败静默。 */
+  const reset = useCallback(() => {
+    setSettings({ ...DEFAULT_SETTINGS })
+    void fetch('/dsh-plugin-hub/settings/reset', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: '{}',
+      cache: 'no-store',
+    }).catch(() => { /* 宿主未挂路由：仅本次会话回默认 */ })
+  }, [])
+
+  return { settings, ready, update, reset }
+}