dsh-router-core 0.3.11 → 0.3.13

package/lib/types/llm/adapter.d.ts

@@ -38,6 +38,15 @@ export declare class RouterAdapter extends LlmAdapter {
         name: string;
     };
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * 只收文本。`resolveModel` 声明 `inputModalities: ['text']` 是**必须**的：
+     * 0.1.5 的 runtime 只在 `inputModalities` 存在且不含 `image` 时才把 image 块
+     * 投影成占位文本（见 dsh-llm adapterStream 的 projectImagesForTextModel）。
+     * 不声明 = "unknown" = 不投影，而 wireMessages 只读 text 块 → 图片**静默
+     * 丢失**，模型看到一条没有图片的用户消息却毫无提示。声明后由 runtime 统一
+     * 投影，我们仍只处理文本。
+     */
+    private static readonly INPUT_MODALITIES;
     resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }

package/lib/types/router/account-pool.d.ts

@@ -31,6 +31,14 @@ export declare class AccountPool {
     /** uid → 连接级禁用 / 手动暂停。 */
     private byUid;
     private rrCursor;
+    /** (supplier, model) → 当前驻留的号（只有**无亲和**的回退路径用它）。 */
+    private blocks;
+    /** (supplier, model, uid) → 该号的缓存质量样本（降权判据，跨驻留累计）。 */
+    private samples;
+    /** (supplier, model, uid) → 缓存无效降权。 */
+    private demoted;
+    /** (supplier, model) → Map<前缀指纹, uid>：前缀亲和的选号记忆（LRU 封顶）。 */
+    private affinity;
     constructor(supplierId?: string);
     private key;
     private entry;
@@ -46,13 +54,61 @@ export declare class AccountPool {
     private healthy;
     /**
      * 按策略为「某个模型」选一个健康账号。
+     *
+     * round-robin = **前缀亲和定号 + 块统计只用来判定缓存无效**：
+     *
+     *  1. 算请求的前缀指纹（messages 前几条），查绑定表 → 命中且该号健康 → 用它。
+     *     这是第一优先：同一个会话的连续请求**永远落回同一个号**，前缀在该号的
+     *     缓存里只写一份。块轮询治不了跨会话驱逐（多会话大前缀在同一号互踩，
+     *     实测 3 会话 3.8% vs 单会话 82.5%），亲和才是根治。
+     *  2. 新指纹（或绑定的号不健康）→ 按游标挑一个号并**记下绑定**，之后就固定。
+     *     新会话用游标分发，所以不同会话天然散到不同号上（均衡）。
+     *  3. 块统计不再驱动轮转（亲和已经保证驻留，再轮转只会把会话踢出已热前缀），
+     *     只保留 `BLOCK_MAX` 次不达标 → 降权该号（缓存无效，可恢复）。
+     *
+     * 亲和失效（拿不到 messages / 指纹算不出）时**回退到块轮询**，行为与之前一致。
+     * 设计见 docs/pool-sticky-block.md §8。
+     *
      * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
      * @param poolOrder 用户在面板拖出来的顺序（核心管）
-     * @param strategy fallback 取第一个健康 / round-robin 轮转健康号
+     * @param strategy fallback 取第一个健康 / round-robin 前缀亲和
      * @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
+     * @param messages 请求体的 messages（可选；给了才能算前缀指纹）
      * @returns 选中的 uid；无健康账号返回 undefined
      */
-    pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string, modelId: string): string | undefined;
+    pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string, modelId: string, messages?: unknown): string | undefined;
+    /** 记下「前缀指纹 → 号」的绑定（LRU：超上限丢最久未用的）。 */
+    private bind;
+    /** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
+    private isDemoted;
+    /**
+     * 驻留是否还应留在当前号上（**只用于无亲和的回退路径**）。
+     *
+     * OR 语义（用户拍板）：`留守 = 计数 < N OR 命中率 < M`。
+     * 单一账号内部：一个号先被轮到（冷启动/热），然后
+     *   - 命中率**爬上去**（>= M，缓存热了）→ 让位，轮到下一个号（均衡）
+     *   - 命中率**没上去**（冷启动/短块）→ 留守，继续热（不急着跳）
+     *   - 轮次**实在太多**（计数 >= N_max）→ 也换（防死守 + 保均衡下限）
+     *
+     * 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
+     * 见文档 §3）。换号由「命中达标 OR 份额用够」触发，都不是「命中率低」。
+     */
+    private blockKeeps;
+    /**
+     * 记录一次成功请求的缓存命中情况（降权判据的反馈信号）。
+     *
+     * 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错降权。
+     * 统计按 (model, uid) 记，**不管这个号是不是「当前驻留」**——亲和开启后
+     * 多个会话各绑各的号交错服务，按驻留记会漏掉大部分真实反馈。
+     * @param uid 实际服务的号
+     * @param modelId 模型（块粒度）
+     * @param cachedTokens 上游报的命中 token 数；0 = 全量重算
+     */
+    noteCache(uid: string, modelId: string, cachedTokens: number): void;
+    /** 故障切走时作废当前驻留：换号后前缀归属变了，驻留计数不能沿用。 */
+    dropBlock(modelId: string): void;
+    /** 块状态键：与冷却同粒度 (supplier, model)，不含 uid。 */
+    private blockKey;
     /** 记录一次失败：按状态处置（冷却/禁用/退避），落在「(模型, 连接)」这个冷却单元上。 */
     noteFailure(uid: string, modelId: string, state: AccountState, message: string): void;
     /** 记录一次成功：清零「该模型」的限流退避等级（好号不背历史惩罚）。不解除禁用。 */

package/lib/types/router/prefix-affinity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 算请求的前缀指纹。
+ * @param messages OpenAI 请求体的 `messages` 字段（未校验，来自外部输入）
+ * @returns 指纹字符串；**空串 = 算不出来（无亲和，回退到块轮询）**
+ */
+export declare function prefixFingerprint(messages: unknown): string;

package/lib/types/router/usage-store.d.ts

@@ -15,6 +15,14 @@ export interface UsageRecord {
     durationMs: number;
     /** 首字节延迟（ms）；非流式为 0。 */
     ttfbMs: number;
+    /**
+     * 实际服务的账号 uid（成功时回填）。
+     *
+     * 有了它才能把命中率按**号**下钻——prompt cache 是 per-account 命名空间，
+     * 只看供应商/模型无法判断「是某个号的缓存没热，还是策略在乱切号」。
+     * 块轮询（docs/pool-sticky-block.md）的调参完全依赖这个归因。
+     */
+    uid?: string;
     /** 失败原因（ok=false 时）。 */
     error?: string;
 }

package/lib/types/shared.d.ts

@@ -132,6 +132,24 @@ export interface RouterSettingsResponse {
     error?: string;
     requireApiKey?: boolean;
 }
+/** 一条扩展器（`/router/api/ext`）。 */
+export interface RouterExtItem {
+    id: string;
+    name: string;
+    description?: string;
+    /** 是否启用改写（面板开关）。 */
+    enabled?: boolean;
+    /** 运行时是否就绪（如 RTK 二进制是否可用）。 */
+    ready?: boolean;
+    /** 一句话状态说明（如「本机未装 rtk」）。 */
+    detail?: string;
+}
+/** `/router/api/ext` response（扩展插件列表 + 开关）。 */
+export interface RouterExtResponse {
+    ok: boolean;
+    error?: string;
+    enhancers?: RouterExtItem[];
+}
 /** 供应商模型（含启用状态）。 */
 export interface RouterSupplierModel {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-router-core",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "DSH plugin: a simplified 9router (AI routing gateway). Adds a 路由系统 (Routing System) sidebar entry beside 记忆系统; the panel shows suppliers, account pool, combos, and endpoint/API keys.",
   "type": "module",
   "repository": {
@@ -66,9 +66,9 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
@@ -85,7 +85,7 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.5-rc.1",
     "@types/node": "^26.4.1",
     "@types/react": "~19.2.18",
     "@types/react-dom": "~19.2.7",

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/SupplierDetail.tsx

@@ -908,7 +908,7 @@ export function SupplierDetail({ supplier, accounts, statusLoading, onBack, onRe
             </>
             <>
               <label className="dshr-fieldLabel">连接池策略</label>
-              <p className="dshr-muted">回退 = 按连接池顺序取第一个健康链接；轮询 = 轮流使用健康链接。</p>
+              <p className="dshr-muted">回退 = 按连接池顺序取第一个健康链接；轮询 = 按会话前缀粘住同一链接（前缀亲和，多会话不打架），拿不到会话信息时退回块轮转。</p>
               <select
                 className="dshr-select dshr-input"
                 value={poolStrategy}

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)
+})