dsh-router-core 0.3.11 → 0.3.12

package/src/client/ExtTab.tsx

@@ -0,0 +1,143 @@
+/**
+ * 扩展 (Ext) 页 —— 列出所有注册进 `router.ext` 的扩展插件,每个一个开关。
+ *
+ * 数据来自 `/router/api/ext`:核心把自己存的开关(`ext.json`)+ 扩展器报的
+ * 运行时事实(`ready` / `detail`)合并后给面板。扩展器只实现具体能力(如 RTK),
+ * 开关与渲染都在核心。
+ *
+ * 布局贴近 EndpointTab 的「Require API key」开关行:每个扩展器一张卡片。
+ * 未装任何扩展 → 空状态提示。
+ */
+import { useEffect, useRef, useState } from 'react'
+import { ROUTER_API_BASE, type RouterExtItem, type RouterExtResponse } from '../shared.ts'
+
+function Icon({ d, size = 18 }: { d: string; size?: number }): JSX.Element {
+  return (
+    <svg viewBox="0 0 24 24" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d={d} />
+    </svg>
+  )
+}
+
+const I = {
+  bolt: 'M13 2L4 14h6l-1 8 9-12h-6l1-8z',
+  puzzle: 'M4 7h3a2 2 0 0 1 4 0h5a1 1 0 0 1 1 1v4a2 2 0 0 0 0 4v4H8v-3a2 2 0 0 1 0-4H4V7z',
+}
+
+export function ExtTab(): JSX.Element {
+  const [items, setItems] = useState<RouterExtItem[]>([])
+  const [loaded, setLoaded] = useState(false)
+  const [error, setError] = useState('')
+  const mounted = useRef(true)
+
+  useEffect(() => {
+    mounted.current = true
+    void load()
+    return () => { mounted.current = false }
+  }, [])
+
+  const load = async (): Promise<void> => {
+    try {
+      const response = await fetch(`${ROUTER_API_BASE}/ext`, { cache: 'no-store' })
+      const data = await response.json() as RouterExtResponse
+      if (mounted.current) {
+        setError(data.ok ? '' : (data.error ?? '加载扩展失败'))
+        setItems(data.enhancers ?? [])
+        setLoaded(true)
+      }
+    } catch (err) {
+      if (mounted.current) {
+        setError((err as Error).message)
+        setLoaded(true)
+      }
+    }
+  }
+
+  const toggle = async (item: RouterExtItem, value: boolean): Promise<void> => {
+    // 乐观更新
+    setItems(prev => prev.map(i => i.id === item.id ? { ...i, enabled: value } : i))
+    setError('')
+    try {
+      const response = await fetch(`${ROUTER_API_BASE}/ext`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ id: item.id, enabled: value }),
+        cache: 'no-store',
+      })
+      const data = await response.json() as RouterExtResponse
+      if (mounted.current && data.enhancers) {
+        setItems(data.enhancers)
+      } else if (mounted.current && !data.ok) {
+        setError(data.error ?? '切换失败')
+        setItems(prev => prev.map(i => i.id === item.id ? { ...i, enabled: !value } : i))
+      }
+    } catch (err) {
+      if (mounted.current) {
+        setError((err as Error).message)
+        setItems(prev => prev.map(i => i.id === item.id ? { ...i, enabled: !value } : i))
+      }
+    }
+  }
+
+  return (
+    <div className="dshr-tabBody">
+      {error !== '' && (
+        <div className="dshr-alert"><strong>出错了</strong><span>{error}</span></div>
+      )}
+
+      {!loaded ? (
+        <div className="dshr-empty">加载中…</div>
+      ) : items.length === 0 ? (
+        <div className="dshr-keyEmpty">
+          <span className="dshr-keyEmptyIcon"><Icon d={I.puzzle} size={30} /></span>
+          <p className="dshr-keyEmptyTitle">暂无扩展</p>
+          <p className="dshr-keyEmptyDesc">
+            安装扩展插件(如 <code>dsh-router-ext-rtk</code>)后,这里会出现开关
+          </p>
+        </div>
+      ) : (
+        items.map(item => {
+          const notReady = item.ready === false
+          return (
+            <section key={item.id} className="dshr-card">
+              <div className="dshr-cardHead">
+                <span className="dshr-cardIcon"><Icon d={I.bolt} /></span>
+                <div className="dshr-cardTitle">{item.name}</div>
+                {/* 开关放标题行最右端:.dshr-cardAction 是现成的
+                    margin-left:auto(EndpointTab 的「创建 Key」就靠它),复用不新增。
+                    不可用时禁开——禁了就无从开启成功。 */}
+                <button
+                  type="button"
+                  className={`dshr-toggle dshr-cardAction ${item.enabled ? 'dshr-toggle-on' : ''}`}
+                  role="switch"
+                  aria-checked={!!item.enabled}
+                  disabled={notReady && !item.enabled}
+                  onClick={() => void toggle(item, !item.enabled)}
+                  title={notReady && !item.enabled
+                    ? '当前不可用,无法开启'
+                    : item.enabled ? `关闭 ${item.name}` : `开启 ${item.name}`}
+                >
+                  <span className="dshr-toggleKnob" />
+                </button>
+              </div>
+
+              {/* 内容区：说明 + 未就绪红字（左对齐、与卡片图标对齐） */}
+              <div className="dshr-extBody">
+                {item.description !== undefined && item.description !== '' && (
+                  <div className="dshr-muted">{item.description}</div>
+                )}
+                {notReady && (
+                  <div className="dshr-ext-error">
+                    {item.detail !== undefined && item.detail !== ''
+                      ? item.detail
+                      : '未就绪,无法开启'}
+                  </div>
+                )}
+              </div>
+            </section>
+          )
+        })
+      )}
+    </div>
+  )
+}

package/src/client/RouterView.tsx

@@ -1,9 +1,10 @@
 /**
  * 路由系统 (Routing System) panel — a simplified 9router.
  *
- * Four tabs fed by the host half (/router/api/*), mirroring 9router's
+ * Five tabs fed by the host half (/router/api/*), mirroring 9router's
  * dashboard: 概览 (usage), 供应商 (supplier cards → detail: accounts +
  * add-account + models), 组合 (combo fallback chains),
+ * 扩展 (extension plugins — one toggle each, self-checked),
  * 端点与密钥 (endpoint URL + API keys + auth).
  *
  * **挂载在「设置」里**（`settings.section` 座位），所以布局规则跟中心栏劫持时期不同：
@@ -27,8 +28,9 @@ import { SupplierDetail } from './SupplierDetail.tsx'
 import { EndpointTab } from './EndpointTab.tsx'
 import { CombosTab } from './CombosTab.tsx'
 import { StatsTab } from './StatsTab.tsx'
+import { ExtTab } from './ExtTab.tsx'
 
-type TabId = 'overview' | 'suppliers' | 'combos' | 'endpoint'
+type TabId = 'overview' | 'suppliers' | 'combos' | 'endpoint' | 'ext'
 
 interface Snapshot {
   health: RouterHealthResponse | null
@@ -142,6 +144,9 @@ export function RouterView({ onBack }: RouterViewProps): JSX.Element {
         <button type="button" role="tab" aria-selected={tab === 'combos'} className={`dshr-tab${tab === 'combos' ? ' dshr-tab-on' : ''}`} onClick={() => setTab('combos')}>
           组合 <span className="dshr-navCount">{combos.length}</span>
         </button>
+        <button type="button" role="tab" aria-selected={tab === 'ext'} className={`dshr-tab${tab === 'ext' ? ' dshr-tab-on' : ''}`} onClick={() => setTab('ext')}>
+          扩展
+        </button>
         <button type="button" role="tab" aria-selected={tab === 'endpoint'} className={`dshr-tab${tab === 'endpoint' ? ' dshr-tab-on' : ''}`} onClick={() => setTab('endpoint')}>
           端点与密钥
         </button>
@@ -205,6 +210,9 @@ export function RouterView({ onBack }: RouterViewProps): JSX.Element {
 
         {/* ---------------- 端点与密钥 ---------------- */}
         {tab === 'endpoint' && <EndpointTab />}
+
+        {/* ---------------- 增强 (扩展插件) ---------------- */}
+        {tab === 'ext' && <ExtTab />}
       </div>
     </div>
   )

package/src/client/router.css

@@ -910,6 +910,25 @@ html[data-dsh-router-active]:not([data-dsh-taskboard-active]):not([data-dsh-ssh-
 
 .dshr-toggle-on .dshr-toggleKnob { transform: translateX(14px); }
 
+/* 开关禁用态：不可用(未就绪)且未开启时,灰显 + 不可点 */
+.dshr-toggle:disabled {
+  cursor: default;
+  opacity: .45;
+}
+
+/* 扩展页：未就绪问题描述(红字) */
+.dshr-ext-error {
+  color: var(--rs-danger);
+  font-size: 11px;
+  margin-top: 4px;
+}
+
+/* 扩展卡片内容区：文字左对齐，左侧留白与标题行的图标位对齐 */
+.dshr-extBody {
+  padding: 10px 14px 12px 48px;
+  text-align: left;
+}
+
 /* 操作按钮组 */
 .dshr-ops {
   display: flex;

package/src/ext/contract.ts

@@ -0,0 +1,115 @@
+/**
+ * 扩展 (Ext) 通用契约 —— dsh-router 的「扩展插件」扩展点（不是供应商）。
+ *
+ * 分工（2026-09 重构：核心只做管理，不做拦截）：
+ *   - **dsh-router 核心 = 管理面**：持有 `router.ext` 注册表（发现）、渲染面板与
+ *     `/router/api/ext`（展示）、代存开关与插件数据（`router.extStore` →
+ *     `<dataDir>/ext.json`）。核心**不挂 `tools/execute`、不裁决、不改写**。
+ *   - **扩展插件 = 执行面**：自己挂监听、自己问 `isEnabled`、自己按 ready 裁决、
+ *     自己短路执行。怎么改一条命令是插件的**私事**，不在本契约里。
+ *
+ * 为什么把拦截从核心挪走：
+ *   `tools/execute` 是任何插件都能自己挂的 around-dispatch waterfall（插件 ctx 不在
+ *   agent scope 下就能收到全部派发）。核心代挂只在一个消费者（rtk）时是纯亏损：为留
+ *   40 行委派逻辑，付了共享表 + inject 广播 + 契约两处同步的代价。核心归位成管理面
+ *   后，扩展插件与 dsh-router 只在**注册表 + 存储**两处耦合。
+ *
+ * ponytail: 天花板 —— 核心代挂原本顺带解决「多个扩展插件各自挂监听会互相踩 / 顺序
+ *   不可控」。这个保护现在没了；目前只有 rtk 一家消费，无所谓。**第二家 ext 出现时
+ *   要重新收敛顺序**（升级路径：核心暴露一个按顺序委派的共享工具方法，而不是收回拦截）。
+ *
+ * 契约要点：
+ *   - 扩展器只有**声明**（id / name / description）+ `getState()`；核心拿这些渲染面板。
+ *   - `getState()` 只报**运行时事实**（ready 是否可用、detail 说明），不报开关。
+ *   - **开关与数据归核心持久化**（`router.extStore` → `<dataDir>/ext.json`），插件不自己
+ *     file IO —— 落盘位置由核心锚定（不跟 cwd 跑），读写经核心，插件无状态。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+/** 扩展器唯一 id（注册键）。 */
+export type ExtId = string
+
+/**
+ * 扩展器当前状态（**运行时事实**，由插件现算，不持久化）。
+ *
+ * 注意：`enabled` 不在这里 —— 开关状态归核心持久化（`<dataDir>/ext.json`），
+ * 插件只负责做事 + 报自己是否可用。核心把两者合并后再给面板用。
+ */
+export interface ExtState {
+  /** 运行时是否就绪（如 RTK 二进制是否可用）；false 时即使开启也不生效。 */
+  ready: boolean
+  /** 不就绪时的一句话说明（如「本机未装 rtk」），面板红字显示。 */
+  detail?: string
+}
+
+/**
+ * 注册到 `router.ext` 表的扩展器实现。核心（面板/API）只认这几个成员，
+ * 插件可以携带更多内部状态。
+ */
+export interface RouterExt {
+  /** 扩展器 id，也是 `router.ext` 表里的注册键。 */
+  readonly id: ExtId
+  /** 面板显示名（如「RTK」）。 */
+  readonly name: string
+  /** 面板副标题说明。 */
+  readonly description?: string
+  /** 当前运行时状态（ready + 不就绪时的说明）。 */
+  getState(): ExtState
+  /** 卸载清理（表删除时由 dsh-router 调用，可选）。 */
+  dispose?(): void
+}
+
+/** 面板/API 用的一条扩展器信息 = 核心存的开关 + 插件报的运行时事实。 */
+export interface ExtInfo {
+  id: string
+  name: string
+  description?: string
+  /** 核心持久化的开关（默认关）。 */
+  enabled: boolean
+  /** 插件报的运行时就绪状态。 */
+  ready: boolean
+  /** 不就绪时的说明（面板红字）。 */
+  detail?: string
+}
+
+/** `router.ext` 共享聚合表：`{ [extId]: RouterExt }`（同一 live 对象可追加）。 */
+export interface RouterExtService {
+  [extId: string]: RouterExt
+}
+
+/**
+ * 扩展的存储面（核心 provide，插件 inject）。
+ *
+ * 插件**不自己 file IO**：落盘位置由核心用 `dataDirOf(ctx.baseUrl)` 锚定（不跟
+ * process.cwd() 跑），读写都经核心，同一文件、同一次原子写。
+ *
+ * 落盘形状：`<dataDir>/ext.json` = `{ "<id>": { "enabled": boolean, "data": unknown } }`
+ */
+export interface ExtStoreService {
+  /** 是否开启（未记录过 = 默认关）。 */
+  isEnabled(id: string): boolean
+  /** 置开关（面板/API 调）。 */
+  setEnabled(id: string, enabled: boolean): void
+  /** 读插件自己的数据块（没有 = undefined）。 */
+  readData<T = unknown>(id: string): T | undefined
+  /** 写插件自己的数据块（覆盖；与 enabled 同文件原子落盘）。 */
+  writeData(id: string, value: unknown): void
+}
+
+/** 读取当前 router.ext 表（同一 live 对象，可追加）——扩展插件用它注册自己。 */
+export function currentExts(ctx: Context): RouterExtService | undefined {
+  const c = ctx as unknown as {
+    get?: (key: string) => unknown
+    router?: { ext?: RouterExtService }
+  }
+  return (c.get?.('router.ext') ?? c.router?.ext) as RouterExtService | undefined
+}
+
+/** 读取扩展存储服务——扩展插件用它读开关、读写自己存的数据。 */
+export function currentExtStore(ctx: Context): ExtStoreService | undefined {
+  const c = ctx as unknown as {
+    get?: (key: string) => unknown
+    router?: { extStore?: ExtStoreService }
+  }
+  return (c.get?.('router.extStore') ?? c.router?.extStore) as ExtStoreService | undefined
+}

package/src/ext/store.test.ts

@@ -0,0 +1,144 @@
+/**
+ * 扩展开关存储测试 —— 开关状态归核心持久化(`<dataDir>/ext.json`)。
+ *
+ * 锁定的契约:
+ *   - 默认关(没记录过 = 关)
+ *   - 开启 → 落盘,新实例(模拟重启)读到
+ *   - 按 id 隔离,互不影响
+ *   - 坏数据读盘不炸
+ *   - 重复设同值不写盘
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ExtStore } from './store.ts'
+
+/** 每个用例一个独立数据目录(stateFile 推导出 ext.json)。 */
+function tempStore(preload?: unknown): { store: ExtStore; file: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'dshr-ext-'))
+  const stateFile = join(dir, 'state.json')
+  if (preload !== undefined) writeFileSync(join(dir, 'ext.json'), JSON.stringify(preload))
+  return { store: new ExtStore(stateFile), file: join(dir, 'ext.json') }
+}
+
+test('默认关', () => {
+  const { store } = tempStore()
+  assert.equal(store.isEnabled('rtk'), false)
+})
+
+test('开启 → 落盘,重开还在', () => {
+  const { store, file } = tempStore()
+  store.setEnabled('rtk', true)
+  const raw = JSON.parse(readFileSync(file, 'utf8')) as { rtk?: { enabled: boolean } }
+  assert.equal(raw.rtk?.enabled, true)
+  // 新实例 = 模拟重启
+  assert.equal(new ExtStore(join(file, '..', 'state.json')).isEnabled('rtk'), true)
+})
+
+test('关回去 → 落盘 false', () => {
+  const { store, file } = tempStore()
+  store.setEnabled('rtk', true)
+  store.setEnabled('rtk', false)
+  assert.equal(new ExtStore(join(file, '..', 'state.json')).isEnabled('rtk'), false)
+})
+
+test('按 id 隔离,互不影响', () => {
+  const { store } = tempStore()
+  store.setEnabled('rtk', true)
+  assert.equal(store.isEnabled('rtk'), true)
+  assert.equal(store.isEnabled('other'), false)
+})
+
+test('坏数据读盘不炸,当没配置过', () => {
+  const { store: s1 } = tempStore({ rtk: { enabled: 'yes' } })
+  assert.equal(s1.isEnabled('rtk'), false)
+  const { store: s2 } = tempStore({ rtk: null })
+  assert.equal(s2.isEnabled('rtk'), false)
+  const { store: s3 } = tempStore([])
+  assert.equal(s3.isEnabled('rtk'), false)
+})
+
+/** 造一个带旧 enhance.json 的目录(模拟升级前的状态)。 */
+function legacyStore(enabled: boolean): { store: ExtStore; file: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'dshr-ext-legacy-'))
+  writeFileSync(join(dir, 'enhance.json'), JSON.stringify({ enabled }))
+  const stateFile = join(dir, 'state.json')
+  return { store: new ExtStore(stateFile), file: join(dir, 'ext.json') }
+}
+
+test('迁移:旧 enhance.json 开着 → 新 ext.json 里 rtk 开', () => {
+  const { store, file } = legacyStore(true)
+  assert.equal(store.isEnabled('rtk'), true)
+  const raw = JSON.parse(readFileSync(file, 'utf8')) as { rtk?: { enabled: boolean } }
+  assert.equal(raw.rtk?.enabled, true)
+})
+
+test('迁移:旧文件关着 → 不迁移(保持默认关)', () => {
+  const { store, file } = legacyStore(false)
+  assert.equal(store.isEnabled('rtk'), false)
+  assert.equal(existsSync(file), false)
+})
+
+test('迁移:已有新配置时不覆盖', () => {
+  const { store: s1, file } = tempStore()
+  s1.setEnabled('rtk', false)
+  // 往同目录塞一个「开着」的旧文件,不应覆盖已经明确存过的新配置
+  writeFileSync(join(file, '..', 'enhance.json'), JSON.stringify({ enabled: true }))
+  const s2 = new ExtStore(join(file, '..', 'state.json'))
+  assert.equal(s2.isEnabled('rtk'), false)
+})
+
+test('空 id 不落盘(连文件都不建)', () => {
+  const { store, file } = tempStore()
+  store.setEnabled('', true)
+  assert.equal(store.isEnabled(''), false)
+  assert.equal(existsSync(file), false, '空 id 应直接拒绝,不创建文件')
+})
+
+// ---- data 槽:给插件的通用抽屉(2026-09 加) ----
+
+test('data:没存过 → undefined;写后能读回', () => {
+  const { store } = tempStore()
+  assert.equal(store.readData('rtk'), undefined)
+  store.writeData('rtk', { hits: 3 })
+  assert.deepEqual(store.readData('rtk'), { hits: 3 })
+})
+
+test('data:落盘 + 重启还在(与 enabled 同一文件)', () => {
+  const { store, file } = tempStore()
+  store.setEnabled('rtk', true)
+  store.writeData('rtk', { hits: 3 })
+  const raw = JSON.parse(readFileSync(file, 'utf8')) as { rtk?: { enabled: boolean; data?: { hits: number } } }
+  assert.equal(raw.rtk?.enabled, true)
+  assert.deepEqual(raw.rtk?.data, { hits: 3 })
+  const revived = new ExtStore(join(file, '..', 'state.json'))
+  assert.equal(revived.isEnabled('rtk'), true)
+  assert.deepEqual(revived.readData('rtk'), { hits: 3 })
+})
+
+test('data:写 data 不冲掉 enabled,置 enabled 不冲掉 data', () => {
+  const { store, file } = tempStore()
+  store.setEnabled('rtk', true)
+  store.writeData('rtk', { hits: 1 })
+  assert.equal(store.isEnabled('rtk'), true, '写 data 不能把开关冲掉')
+  store.setEnabled('rtk', false)
+  assert.deepEqual(store.readData('rtk'), { hits: 1 }, '置开关不能把 data 冲掉')
+  const revived = new ExtStore(join(file, '..', 'state.json'))
+  assert.equal(revived.isEnabled('rtk'), false)
+  assert.deepEqual(revived.readData('rtk'), { hits: 1 })
+})
+
+test('data:按 id 隔离', () => {
+  const { store } = tempStore()
+  store.writeData('rtk', { hits: 1 })
+  assert.deepEqual(store.readData('other'), undefined)
+})
+
+test('data:空 id 不落盘', () => {
+  const { store, file } = tempStore()
+  store.writeData('', { x: 1 })
+  assert.equal(store.readData(''), undefined)
+  assert.equal(existsSync(file), false)
+})

package/src/ext/store.ts

@@ -0,0 +1,125 @@
+/**
+ * 扩展存储 —— **开关状态与插件数据都归核心持久化**,插件不自己 file IO。
+ *
+ * 落盘 `<dataDir>/ext.json`,按扩展器 id 存:
+ *   `{ "rtk": { "enabled": true, "data": { ...插件自己的东西... } } }`
+ *
+ * 为什么归核心:跟 `supplier-config.json` 一个道理——开关是用户对**核心面板**的操作,
+ * 不该由扩展插件各自决定存哪、怎么存(否则每个插件长一份互相不一致的实现,核心也无
+ * 从统一裁决「能不能开」)。插件变薄:只报自己是否可用(`ready`)+ 做事。
+ *
+ * `data` 槽是给插件的通用抽屉(2026-09 加):插件不再为了存一点状态而自己开数据目录,
+ * 统一经 `router.extStore` service 读写,落盘位置仍由核心锚定(不跟 cwd 跑)。
+ *
+ * 写法与核心其他存储一致:先写 `.tmp` 再 `rename` 原子覆盖(避免写一半崩掉留坏文件),
+ * 权限 600;持久化失败不阻断。
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+interface ExtFile {
+  [extId: string]: { enabled: boolean; data?: unknown }
+}
+
+interface Entry {
+  enabled: boolean
+  data: unknown
+}
+
+/** 扩展开关 + 插件数据存储。 */
+export class ExtStore {
+  private fp = ''
+  private byId: Record<string, Entry> = {}
+
+  constructor(stateFile: string) {
+    this.fp = stateFile ? join(dirname(stateFile), 'ext.json') : ''
+    this.load()
+    // 一次性迁移:开关早期由扩展插件自己写在 `enhance.json`(单文件、无法按 id 区分),
+    // 现在归核心按 id 存 `ext.json`。把旧值搬过来,避免用户已开的开关掉回关。
+    // 旧文件保留不删(不可逆操作留给人工),迁移只发生在新文件还没有时。
+    this.migrateLegacy()
+  }
+
+  private migrateLegacy(): void {
+    if (this.fp === '') return
+    if (Object.keys(this.byId).length > 0) return // 已有新配置,不覆盖
+    const legacy = join(dirname(this.fp), 'enhance.json')
+    let enabled = false
+    try {
+      const f = JSON.parse(readFileSync(legacy, 'utf8')) as { enabled?: unknown }
+      enabled = f.enabled === true
+    } catch {
+      return // 没有旧文件 / 读不了 → 无需迁移
+    }
+    if (!enabled) return
+    // 旧格式只有一个开关,当时唯一的扩展器就是 rtk。
+    this.byId.rtk = { enabled: true, data: undefined }
+    this.save()
+  }
+
+  private load(): void {
+    if (this.fp === '') return
+    let raw: string
+    try {
+      raw = readFileSync(this.fp, 'utf8')
+    } catch {
+      return
+    }
+    try {
+      const f = JSON.parse(raw) as ExtFile
+      for (const [id, v] of Object.entries(f)) {
+        if (id === '' || v === null || typeof v !== 'object') continue
+        if (typeof v?.enabled !== 'boolean') continue
+        this.byId[id] = { enabled: v.enabled, data: v.data }
+      }
+    } catch {
+      // 损坏则用默认关
+    }
+  }
+
+  private save(): void {
+    if (this.fp === '') return
+    try {
+      const dir = dirname(this.fp)
+      if (dir !== '' && dir !== '.') mkdirSync(dir, { recursive: true })
+      const out: ExtFile = {}
+      for (const [id, e] of Object.entries(this.byId)) {
+        // 没数据的不写 data 键,保持文件干净(旧格式兼容)。
+        out[id] = e.data === undefined ? { enabled: e.enabled } : { enabled: e.enabled, data: e.data }
+      }
+      const raw = JSON.stringify(out, null, 2)
+      const tmp = this.fp + '.tmp'
+      writeFileSync(tmp, raw, { mode: 0o600 })
+      renameSync(tmp, this.fp)
+    } catch {
+      // 持久化失败不阻断
+    }
+  }
+
+  /** 是否开启(未记录过 = 默认关)。 */
+  isEnabled(id: string): boolean {
+    return this.byId[id]?.enabled === true
+  }
+
+  setEnabled(id: string, enabled: boolean): void {
+    if (id === '') return
+    const cur = this.byId[id]
+    if (cur?.enabled === enabled) return
+    this.byId[id] = { enabled, data: cur?.data }
+    this.save()
+  }
+
+  /** 读插件自己存的数据块(没存过 = undefined)。 */
+  readData<T = unknown>(id: string): T | undefined {
+    if (id === '') return undefined
+    return this.byId[id]?.data as T | undefined
+  }
+
+  /** 写插件自己的数据块(覆盖;与 enabled 同一文件落盘)。 */
+  writeData(id: string, value: unknown): void {
+    if (id === '') return
+    const cur = this.byId[id]
+    this.byId[id] = { enabled: cur?.enabled === true, data: value }
+    this.save()
+  }
+}