dsh-router-core 0.3.10 → 0.3.12

package/lib/types/ext/contract.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 扩展 (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 declare function currentExts(ctx: Context): RouterExtService | undefined;
+/** 读取扩展存储服务——扩展插件用它读开关、读写自己存的数据。 */
+export declare function currentExtStore(ctx: Context): ExtStoreService | undefined;

package/lib/types/ext/store.d.ts

@@ -0,0 +1,16 @@
+/** 扩展开关 + 插件数据存储。 */
+export declare class ExtStore {
+    private fp;
+    private byId;
+    constructor(stateFile: string);
+    private migrateLegacy;
+    private load;
+    private save;
+    /** 是否开启(未记录过 = 默认关)。 */
+    isEnabled(id: string): boolean;
+    setEnabled(id: string, enabled: boolean): void;
+    /** 读插件自己存的数据块(没存过 = undefined)。 */
+    readData<T = unknown>(id: string): T | undefined;
+    /** 写插件自己的数据块(覆盖;与 enabled 同一文件落盘)。 */
+    writeData(id: string, value: unknown): void;
+}

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

@@ -9,9 +9,16 @@
 import { LlmAdapter, type GenerateOptions, type LlmModelInfo, type LlmResolvedModelInfo, type StreamChunk } from '@deepseek-ai/dsh-llm';
 /** 模型目录来源：组合。 */
 export interface RouterAdapterSource {
+    /**
+     * 组合列表。`contextWindow` 可选，但**必须尽量给**——自动压缩靠它算阈值
+     * （`dsh-compaction-basic` 在 `context` 缺失时直接抛错并静默关闭自动压缩，
+     * 于是上下文会一路涨到模型硬上限才炸）。
+     * 组合背后是异构供应商时给**最小的那个**（保守，宁可早压缩）。
+     */
     comboModels: () => Promise<Array<{
         id: string;
         name?: string;
+        contextWindow?: number;
     }>>;
 }
 /** openai SSE payload → DSH StreamChunk 流。导出以便单测锁死 usage 契约。 */

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

@@ -31,6 +31,10 @@ export declare class AccountPool {
     /** uid → 连接级禁用 / 手动暂停。 */
     private byUid;
     private rrCursor;
+    /** (supplier, model) → 块轮询驻留状态。 */
+    private blocks;
+    /** (supplier, model, uid) → 缓存无效降权。 */
+    private demoted;
     constructor(supplierId?: string);
     private key;
     private entry;
@@ -46,13 +50,55 @@ export declare class AccountPool {
     private healthy;
     /**
      * 按策略为「某个模型」选一个健康账号。
+     *
+     * round-robin 走**块轮询**：一次轮转内连续服务若干请求，而不是每请求换号。
+     * 设计见 docs/pool-sticky-block.md。要点：
+     *  - 留守 = `计数 < N OR 命中率 < M`(OR,用户拍板):
+     *    命中率达标（缓存热了）→ 换号保均衡；计数到 N → 换号止损。
+     *    单号最多连续服务 N 次，不会因命中率低而死守到 N_max（打架场景关键）。
+     *  - 切号因子的思路：命中率是**留守**条件不是切号条件。反接会正反馈死锁
+     *    （切→cold miss→命中率 0%→触发切号→…），见文档 §3。
+     *  - `N_max` 绝对兜底：命中率永远不达标的号不能无限驻留（防死锁 + 防均衡归零）。
+     *
      * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
      * @param poolOrder 用户在面板拖出来的顺序（核心管）
-     * @param strategy fallback 取第一个健康 / round-robin 轮转健康号
+     * @param strategy fallback 取第一个健康 / round-robin 块轮转健康号
      * @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
      * @returns 选中的 uid；无健康账号返回 undefined
      */
     pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string, modelId: string): string | undefined;
+    /** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
+    private isDemoted;
+    /**
+     * 块是否还应驻留在当前号上。
+     *
+     * OR 语义（用户拍板）：`留守 = 计数 < N OR 命中率 < M`。
+     * 单一账号内部：一个号先被轮到（冷启动/热），然后
+     *   - 命中率**爬上去**（>= M，缓存热了）→ 让位，轮到下一个号（均衡）
+     *   - 命中率**没上去**（冷启动/短块）→ 留守，继续热（不急着跳）
+     *   - 轮次**实在太多**（计数 >= N_max）→ 也换（防死守 + 保均衡下限）
+     *
+     * 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
+     * 见文档 §3）。换号由「命中达标 OR 份额用够」触发，都不是「命中率低」。
+     *
+     * 每个号各自守着「这个会话在自己账号上的那段前缀」，轮流热；
+     * 命中率 = 块的命中占比。单会话下每个号块都从冷到热各付一次,
+     * 收益来自块内连续驻留(缺了它就跟每请求轮询一样)。
+     */
+    private blockKeeps;
+    /**
+     * 记录一次成功请求的缓存命中情况（块轮询的反馈信号）。
+     *
+     * 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错切。
+     * @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/index.d.ts

@@ -66,6 +66,21 @@ export declare class Router {
      * 只有两种情况会真的等:`force`(用户主动刷新)和**从来没有过缓存值**
      * (冷启动,没有旧值可给)。后者只发生一次。
      */
+    /**
+     * 组合的上下文窗口(token):组合内各模型窗口的**最小值**,拿不到就 undefined。
+     *
+     * 只读缓存、绝不打上游:调用方是 llm adapter 的 `resolveModel`,它在每次
+     * 请求前后都可能被调用,不能为了报一个容量去触发按供应商的网络往返。
+     * 冷启动(还没缓存)时给 undefined —— 自动压缩会因此跳过这一轮,下次就
+     * 有了,比撒谎说一个窗口值安全。
+     *
+     * 单位:`ModelInfo.context_length` 存的是 **K**(供应商插件统一
+     * `Math.round(tokens / 1000)`,见 codebuddy plugin),这里换算回 token。
+     *
+     * 取最小而不是最大:组合会按策略 fallback 到任意一个模型,按最窄的声明
+     * 才能让「快满了」这件事在任何一条分支上都成立。
+     */
+    comboContextWindow(combo: Combo): number | undefined;
     modelsOf(supplierId: string, force?: boolean): Promise<ModelWithEnabled[]>;
     /**
      * 真拉一次上游并写缓存。并发调用共享同一个 in-flight promise——

package/lib/types/router/types.d.ts

@@ -62,6 +62,8 @@ export interface Supplier {
     readonly priority: number;
     /** 图标（URL 或 SVG data URI），面板供应商卡片显示。可选。 */
     readonly icon?: string;
+    /** 「添加 API key」弹窗提示文案（缺省前端用通用文案）。可选。 */
+    readonly apiKeyHint?: string;
     status(): SupplierStatus;
     listModels(force?: boolean): Promise<ModelInfo[]> | ModelInfo[];
     /** 面板展示的模型（含启用/自定义标记）。 */

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

@@ -68,6 +68,8 @@ export interface RouterHealthResponse {
         name: string;
         /** 图标（URL 或 SVG data URI）。 */
         icon?: string;
+        /** 「添加 API key」弹窗提示文案（缺省前端用通用文案）。 */
+        apiKeyHint?: string;
         /** 面板能力集合（登录/签到/连接池/模型管理等，按存在性）。 */
         capabilities?: string[];
         /** 来源：内置 / 用户目录 / 外部插件。 */
@@ -130,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/lib/types/suppliers/contract.d.ts

@@ -22,6 +22,21 @@ export interface SupplierEnv {
     store: SupplierConfigStore;
     /** 通用凭证存储（账号凭证，核心统一管）。 */
     credentials: CredentialStore;
+    /**
+     * 迟到的失败上报（可选）——**只在响应已提交之后**才用。
+     *
+     * 流式请求一旦写出第一个字节就绑死（HTTP 语义），此时上游再报错已经换不了
+     * 号、也改不了状态码。但「这个号坏了」这件事对**后续**请求仍然有价值：
+     * 不报上来，它就会继续留在池里被轮转选中，每次都白撞一次同一个错误。
+     *
+     * 核心实现 = `pool.noteFailure(uid, model, state, message)`，按该状态的规则
+     * 冷却/禁用。真实案例：TRAE 免费通道对某账号拒绝某模型时发 HTTP 200 +
+     * 流内 `code=4008`，三个号里两个如此，round-robin 下 2/3 请求直接失败
+     * （2026-09-08 实测）——有了这条通道，坏号被冷一次就退出轮转。
+     *
+     * 插件拿不到也不用兜底：不调用就退化成今天的行为，不影响正确性。
+     */
+    onLateFailure?: (uid: string, model: string, state: AccountState, message: string) => void;
 }
 /** 通用供应商工厂：一个 js 模块 export 它（或 default export 它），loader 调用得到实例。 */
 export type SupplierFactory = (env: SupplierEnv) => SupplierModule;
@@ -93,6 +108,12 @@ export interface SupplierModule {
     readonly priority?: number;
     /** 图标（URL 或 SVG data URI），面板供应商卡片显示。可选。 */
     readonly icon?: string;
+    /**
+     * 「添加 API key」弹窗的提示文案（HTML 未转义前是纯文本）。可选。
+     * 缺省时前端用通用文案。供应商若走 `addApiKey` 且有自己的 key 获取方式，
+     * 应提供它——否则所有供应商弹窗都显示同一句通用提示（如默认会写 OpenRouter）。
+     */
+    readonly apiKeyHint?: string;
     /** 报账号「现在状态」。冷却/禁用/错误累计由核心叠加，插件不算这些。 */
     status(): SupplierStatusNow;
     /** 模型来源。`force=true` 时强制刷新来源（核心「获取模型」按钮调用）。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-router-core",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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": {

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
@@ -54,7 +56,7 @@ interface RouterViewProps {
 
 export function RouterView({ onBack }: RouterViewProps): JSX.Element {
   const [tab, setTab] = useState<TabId>('overview')
-  const [detailSupplier, setDetailSupplier] = useState<{ id: string; name: string; icon?: string } | null>(null)
+  const [detailSupplier, setDetailSupplier] = useState<{ id: string; name: string; icon?: string; apiKeyHint?: string } | null>(null)
   const [snapshot, setSnapshot] = useState<Snapshot>({ health: null, status: null, combos: null })
   const [refreshing, setRefreshing] = useState(false)
   const mounted = useRef(true)
@@ -90,7 +92,7 @@ export function RouterView({ onBack }: RouterViewProps): JSX.Element {
   const combosError = snapshot.combos?.ok === false ? snapshot.combos.error : undefined
 
   /** 渲染一组供应商卡片（内置 / 插件分开）。 */
-  const renderSupplierGroup = (title: string, group: Array<{ id: string; name: string; icon?: string; source?: string }>): ReactNode => {
+  const renderSupplierGroup = (title: string, group: Array<{ id: string; name: string; icon?: string; apiKeyHint?: string; source?: string }>): ReactNode => {
     if (group.length === 0) return null
     return (
       <div className="dshr-supplierGroup">
@@ -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/StatsTab.tsx

@@ -70,10 +70,12 @@ function fmt(n: number | undefined): string {
   return new Intl.NumberFormat().format(n ?? 0)
 }
 
-/** 大数缩写：1.2K / 3.4M（卡片和柱图上放不下完整数字时用）。 */
+/** 大数缩写：1.2K / 3.4M / 5.6B / 7.8T（卡片和柱图上放不下完整数字时用）。 */
 function fmtShort(n: number | undefined): string {
   const v = n ?? 0
-  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`
+  if (v >= 1e12) return `${(v / 1e12).toFixed(1)}T`
+  if (v >= 1e9) return `${(v / 1e9).toFixed(1)}B`
+  if (v >= 1e6) return `${(v / 1e6).toFixed(1)}M`
   if (v >= 10_000) return `${(v / 1000).toFixed(1)}K`
   return fmt(v)
 }

package/src/client/SupplierDetail.tsx

@@ -43,7 +43,7 @@ const I = {
 }
 
 interface SupplierDetailProps {
-  supplier: { id: string; name: string; capabilities?: string[]; icon?: string }
+  supplier: { id: string; name: string; capabilities?: string[]; icon?: string; apiKeyHint?: string }
   accounts: RouterAccount[]
   /** 状态是否还在加载。 */
   statusLoading: boolean
@@ -948,7 +948,7 @@ export function SupplierDetail({ supplier, accounts, statusLoading, onBack, onRe
           {canApiKey
             ? (
               <div className="dshr-modalForm">
-                <p className="dshr-muted">填入 OpenRouter API key（https://openrouter.ai/settings/keys），可起名字区分多个 key。</p>
+                <p className="dshr-muted">{supplier.apiKeyHint ?? '填入 API key，可起名字区分多个 key。'}</p>
                 {error !== '' && <div className="dshr-alert"><strong>出错了</strong><span>{error}</span></div>}
                 <input
                   className="dshr-input"

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/data-dir.test.ts

@@ -0,0 +1,54 @@
+/**
+ * 数据目录解析测试 —— 锁死「落盘位置不跟 cwd 跑」这个 bug。
+ *
+ * 起因：以前写的是相对路径 `data/state.json`，宿主 Node 进程的 cwd 决定它
+ * 落到哪。从别的目录 `dsh web` 启动 → 配置静默写进另一个目录，面板显示空
+ * 配置，用户看到的就是「配置丢了」。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { dataDirOf, profileDirOf } from './data-dir.ts'
+
+/** 一个临时 profile 目录的 file: URL（宿主 `ctx.baseUrl` 的形状）。 */
+function tempProfileUrl(): { url: string; dir: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'dshr-profile-'))
+  writeFileSync(join(dir, 'cordis.yml'), '[]\n') // 让它像个 profile
+  return { url: pathToFileURL(dir).href + '/', dir }
+}
+
+test('有 baseUrl → 数据目录钉在 profile 里（绝对路径）', () => {
+  const { url, dir } = tempProfileUrl()
+  assert.equal(profileDirOf(url), dir)
+  assert.equal(dataDirOf(url), join(dir, 'data'))
+})
+
+test('换 cwd 不影响落盘位置（回归：不跟 process.cwd() 跑）', () => {
+  const { url, dir } = tempProfileUrl()
+  const before = dataDirOf(url)
+  const cwd = process.cwd()
+  try {
+    process.chdir(tmpdir())
+    assert.equal(dataDirOf(url), before)
+  } finally {
+    process.chdir(cwd)
+  }
+  assert.ok(resolve(before).startsWith(resolve(dir)))
+})
+
+test('baseUrl 缺失/异常 → 兜底 $DSH_HOME 的 web profile', () => {
+  const saved = process.env.DSH_HOME
+  const home = mkdtempSync(join(tmpdir(), 'dshr-home-'))
+  try {
+    process.env.DSH_HOME = home
+    assert.equal(profileDirOf(undefined), join(home, 'profiles', 'web'))
+    assert.equal(profileDirOf(''), join(home, 'profiles', 'web'))
+    assert.equal(profileDirOf('http://example.com/x'), join(home, 'profiles', 'web'))
+  } finally {
+    if (saved === undefined) delete process.env.DSH_HOME
+    else process.env.DSH_HOME = saved
+  }
+})