dsh-router-core 0.1.0 → 0.3.0

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

@@ -14,6 +14,8 @@ export interface RouterAdapterSource {
         name?: string;
     }>>;
 }
+/** openai SSE payload → DSH StreamChunk 流。导出以便单测锁死 usage 契约。 */
+export declare function translateSse(payloads: Iterable<string>): AsyncGenerator<StreamChunk>;
 /**
  * DSH adapter：provider `router`。模型目录 = 组合；stream 转发到本插件
  * /v1/chat/completions（组合路由在 /v1 内完成）。

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

@@ -0,0 +1,41 @@
+/**
+ * 账号池 —— dsh-router 核心策略：选号、冷却、禁用、错误累计、遍历回退。
+ *
+ * 供应商插件只管「对单个账号调通上游」，账号层面的策略全在这里：
+ *   - 按 poolOrder 排序（未配置的按插件报告顺序追加）
+ *   - 按 poolStrategy 选号：fallback = 取第一个健康；round-robin = 轮转健康号
+ *   - 失败按插件报的 AccountState 处置（冷却/禁用/错误累计），攒够阈值自动冷却
+ *
+ * 天花板：冷却/禁用/错误计数都是**内存态**，重启归零（与旧插件行为一致，
+ * 插件的持久化只存凭证与积分，不存健康）。要跨重启保留得落盘，届时加一个
+ * stateFile 即可，接口不用变。
+ */
+import type { AccountState, SupplierAccountNow } from '../suppliers/contract.ts';
+export declare class AccountPool {
+    private entries;
+    private rrCursor;
+    private entry;
+    /** 是否可服务：未禁用且不在冷却中。 */
+    private healthy;
+    /**
+     * 按策略选一个健康账号。
+     * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
+     * @param poolOrder 用户在面板拖出来的顺序（核心管）
+     * @returns 选中的 uid；无健康账号返回 undefined
+     */
+    pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string): string | undefined;
+    /** 记录一次失败：按状态处置（冷却/禁用/错误累计）。 */
+    noteFailure(uid: string, state: AccountState, message: string): void;
+    /** 记录一次成功：清零连续错误。 */
+    noteSuccess(uid: string): void;
+    /** 手动冷却（面板/管理用途）。 */
+    cooldown(uid: string, ms: number, reason: string): void;
+    /** 把核心的冷却/禁用/错误累计叠加到插件报告的「现在状态」上，产出面板态。 */
+    decorate(accounts: SupplierAccountNow[]): Array<SupplierAccountNow & {
+        cooling: boolean;
+        disabled: boolean;
+        err_count: number;
+        until?: string;
+        reason?: string;
+    }>;
+}

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

@@ -1,5 +1,7 @@
 import type { ServerResponse } from 'node:http';
 import type { Supplier, ChatRequest, ModelInfo, ModelWithEnabled, SupplierStatus, Combo } from './types.ts';
+import { SupplierConfigStore } from '../supplier-config.ts';
+import { UsageStore } from './usage-store.ts';
 /** 路由器。 */
 export declare class Router {
     private suppliers;
@@ -7,7 +9,21 @@ export declare class Router {
     private customCombos;
     /** round-robin 轮转游标（按组合 id 记忆）。 */
     private rrCursors;
-    constructor(stateFile?: string);
+    /** 通用供应商配置（连接池顺序/策略、模型启用、别名）。 */
+    private store;
+    /** 模型列表缓存（supplierId → 模型 + 拉取时间）。插件只管拉，不缓存。 */
+    private modelsCache;
+    /** 请求日志出口（面板/宿主 logger）。 */
+    private log;
+    /** 用量统计（概览看板）。 */
+    usage: UsageStore;
+    constructor(stateFile?: string, store?: SupplierConfigStore, log?: (msg: string) => void);
+    /**
+     * 请求追踪：每次 chat 记一行，回答「这个组合到底用的哪个模型和账号」。
+     * 排查「组合里某个模型不稳定」全靠它——没这个就只能猜。
+     * 格式刻意做成一行 grep 友好：`chat 请求model → supplier/model (uid) 结果 耗时`。
+     */
+    private logChat;
     private loadCombos;
     private saveCombos;
     add(supplier: Supplier): void;
@@ -30,7 +46,22 @@ export declare class Router {
     listModels(): Promise<ModelInfo[]>;
     /** 组合列表（面板用）：用户自定义组合。 */
     combos(): Promise<Combo[]>;
-    /** 可用模型（按供应商分组，仅启用），面板加模型用。 */
+    /**
+     * 取某供应商的模型（核心统一缓存）。
+     *
+     * 模型列表只在这里缓存一次：`/suppliers/:id/models`（供应商详情）和
+     * `/combos`（组合加模型）共用。组合面板**不主动打上游**——它只是读缓存，
+     * 冷启动（缓存还没建）时才拉一次；真正刷新由详情页打开或「获取模型」
+     * 按钮（force）触发。
+     *
+     * 天花板：TTL 60s 是拍的。若上游模型列表变更很频繁，可调小；要彻底实时
+     * 就得让供应商暴露 etag/版本号，目前没有这个需求。
+     */
+    modelsOf(supplierId: string, force?: boolean): Promise<ModelWithEnabled[]>;
+    /** 失效某供应商的模型缓存（增删改模型后调用）。 */
+    invalidateModels(supplierId: string): void;
+    /** 可用模型（按供应商分组，仅启用），面板加模型用。
+     *  各供应商**并行**拉取——串行会把每个上游的延迟累加起来。 */
     supplierModels(): Promise<Array<{
         supplier: {
             id: string;
@@ -41,7 +72,15 @@ export declare class Router {
     }>>;
     private validModels;
     private validStrategy;
-    /** 组合模型统一存裸 id：剥掉 alias/ 前缀（前缀随供应商动态变）。 */
+    /** 组合模型统一存裸 id：剥掉 alias/ 前缀（前缀随供应商动态变）。
+     *  只剥「已知 alias + /」开头的前缀——模型 id 本身可以含斜杠
+     *  （如 nvidia 的 `deepseek-ai/deepseek-v4-flash-0731`），用 lastIndexOf 会把
+     *  命名空间一起吃掉，后面请求必然 404。 */
+    /**
+     * 归一组合模型名为存储格式 `supplierId,modelId`。
+     * 面板提交的是「供应商 id + 模型 id」两两组合（或旧数据的裸 id），
+     * 这里只做清理与校验，不再剥掉前缀——精准调用靠的就是供应商 id。
+     */
     private normalizeModelIds;
     /** 创建组合（name 唯一，非 default）。 */
     createCombo(name: string, strategy: string, models: string[]): {
@@ -67,7 +106,36 @@ export declare class Router {
      * - 否则 → 依次尝试供应商，直到某个返回 true（已写响应）或全部返回 false。
      */
     chatCompletions(req: ChatRequest, res: ServerResponse): Promise<void>;
-    /** 把 model 改写为组合选中的模型名后尝试供应商。 */
+    /** 调指定供应商。
+     *  模型名**原样**传给插件（不在这剥 alias/）——插件自己认得自己的别名
+     *  （如 traework 会剥第一段）。核心在这剥就会剥两次，把模型 id 里的
+     *  命名空间（如 org/name）吃掉。 */
+    private chatWithTarget;
+    /** 把 model 改写为组合选中的模型名后，找对应的供应商 + 账号（策略全在核心）。
+     *
+     *  `model` 形如 `supplierId,modelId`（组合的存储格式）：直接用 supplierId 定位，
+     *  不再挨个问供应商「这是不是你的模型」——精准调用，也避免同名模型串台。
+     *  兼容旧的裸 `modelId`（没有逗号）：降级为遍历，行为同以前。
+     */
     private chatWithModel;
+    /** 按别名找供应商（对外模型全名 = alias/model）。别名唯一，故最多命中一个。 */
+    supplierByAlias(alias: string): Supplier | undefined;
+    /**
+     * 单个供应商内遍历账号（核心策略）：选号 → 调 chatOnce → 按返回的
+     * AccountState 处置 → 失败换号；写响应只在成功后发生。
+     *
+     * 流式**推迟到第一个字节才写响应头**，所以「上游刚连上就断」这种情况
+     * 还能换号重试；一旦写出第一个字节就绑死（HTTP 语义，9router 同样如此），
+     * 之后出错不再换号——要彻底能回退就得在写头前缓冲判定，代价是首字节
+     * 延迟，目前未做。
+     */
+    private chatWithSupplier;
+    /** 测试某供应商的某模型是否可用。
+     *  走真实的账号遍历 + chatOnce 路径：账号池回退/冷却由核心实现，自动生效；
+     *  响应丢弃到 sink，限定单一供应商（不跨供应商回退）。 */
+    testModel(supplierId: string, model: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
     dispose(): void;
 }

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

@@ -3,7 +3,8 @@
  * 每个供应商提供 OpenAI 兼容的 chat/models，并暴露面板状态。
  * 仿 9router：供应商 = 一种"免费/付费"通道；dsh-router 在其上做路由。
  */
-import type { ServerResponse } from 'node:http';
+import type { ChatOnceResult, SupplierAccountNow } from '../suppliers/contract.ts';
+import type { AccountPool } from './account-pool.ts';
 /** 面板展示的账号状态（脱敏）。 */
 export interface SupplierAccount {
     uid: string;
@@ -49,9 +50,8 @@ export interface ChatRequest {
     model: string;
 }
 /**
- * 供应商接口。chatCompletions 直接向 res 写响应（流式 SSE 或 JSON），
- * 成功返回 true；返回 false 表示"该供应商无健康账号可服务"（触发路由器
- * 轮换到下一个供应商）。写响应后不得再改 res。
+ * 供应商接口。核心负责账号池（选号/冷却/禁用/错误累计/遍历回退），
+ * 供应商只对**单个账号**调一次上游并报告结果，不碰 res。
  */
 export interface Supplier {
     readonly id: string;
@@ -68,13 +68,15 @@ export interface Supplier {
     getAlias(): string;
     /** 用户手动添加的模型 id（可选，/v1/models 用它聚合自定义模型）。 */
     customModelIds?(): string[];
-    chatCompletions(req: ChatRequest, res: ServerResponse): Promise<boolean>;
-    /** 测试模型（验证上游真实可用，必要差异化能力）。 */
-    testModel(id: string): Promise<{
-        ok: boolean;
-        error?: string;
-    }>;
+    /** 账号「现在状态」（从 status() 派生，插件只报它观察到的）。空 = 无账号供应商。 */
+    accounts(): SupplierAccountNow[];
+    /** 对单个账号调一次上游。不遍历账号、不管冷却、不写 res。 */
+    chatOnce(uid: string, req: ChatRequest): Promise<ChatOnceResult>;
+    /** 上次 chatOnce 失败原因（诊断用，可选）。 */
+    lastError?(): string | undefined;
     /** 删除链接（清理凭证；内部能力，js 契约不要求实现）。 */
     removeLink?(uid: string): Promise<boolean>;
     dispose(): void;
+    /** 该供应商的账号池（核心持有：选号/冷却/禁用/错误累计）。 */
+    readonly pool: AccountPool;
 }

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

@@ -0,0 +1,93 @@
+import type { Usage } from './usage-tokens.ts';
+/** 一条明细（最近请求的环）。 */
+export interface UsageRecord {
+    ts: number;
+    supplier: string;
+    model: string;
+    /** 客户端原始请求的 model（组合场景下就是组合名）。 */
+    requested: string;
+    ok: boolean;
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+    inputEstimated: boolean;
+    outputEstimated: boolean;
+    durationMs: number;
+    /** 首字节延迟（ms）；非流式为 0。 */
+    ttfbMs: number;
+    /** 失败原因（ok=false 时）。 */
+    error?: string;
+}
+export type Period = 'today' | '24h' | '7d' | '30d';
+/** 本地日期键 `YYYY-MM-DD`（照 9router getLocalDateKey，不按 UTC 切天）。 */
+export declare function localDateKey(ts: number): string;
+/** 用量存储。stateFile 为空时纯内存（测试用），不落盘。 */
+export declare class UsageStore {
+    private fp;
+    private days;
+    private recent;
+    private lifetime;
+    private timer;
+    constructor(stateFile: string);
+    /**
+     * 记一次请求。
+     *
+     * **成功的零 token 请求不记**（照 9router `saveUsageStats` 的闸门：
+     * `in === 0 && out === 0` 直接 return，空请求混进来只会稀释统计）。
+     * **失败请求一定记** —— 不管有没有 token。成功率全靠它，挡掉的话
+     * 失败永远是 0 条，面板会显示 100% 成功，这个数字是骗人的。
+     */
+    record(r: Omit<UsageRecord, 'ts' | 'promptTokens' | 'completionTokens' | 'cachedTokens' | 'inputEstimated' | 'outputEstimated'> & {
+        ts?: number;
+    }, usage: Usage): void;
+    private bump;
+    /** 窗口内的明细（today/24h 路径）。 */
+    private inWindow;
+    /** 汇总 + Top 榜。 */
+    stats(period: Period, now?: number): StatsResult;
+    /** 柱状图数据：today/24h = 24 个小时桶（走明细环），7d/30d = 天桶。 */
+    chart(period: Period, now?: number): ChartBucket[];
+    /** 最近请求明细。 */
+    recentList(limit?: number): UsageRecord[];
+    clear(): void;
+    /** 进程退出前把防抖中的写入落盘。 */
+    flush(): void;
+    private scheduleSave;
+    private load;
+    private save;
+}
+/** 柱状图一桶。 */
+export interface ChartBucket {
+    label: string;
+    requests: number;
+    tokens: number;
+}
+export interface StatsResult {
+    requests: number;
+    ok: number;
+    failed: number;
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+    /** 平均耗时（ms）。 */
+    avgDurationMs: number;
+    /** 平均首字节延迟（ms）；没有 TTFB 记录时为 0。 */
+    avgTtfbMs: number;
+    /** 输入/输出为估算的请求数（面板提示用）。 */
+    estimatedInputs: number;
+    estimatedOutputs: number;
+    /** 累计请求数（不受周期影响）。 */
+    lifetime: number;
+    bySupplier: RankRow[];
+    byModel: RankRow[];
+    byRequested: RankRow[];
+}
+export interface RankRow {
+    name: string;
+    requests: number;
+    ok: number;
+    failed: number;
+    promptTokens: number;
+    completionTokens: number;
+    lastTs: number;
+}

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

@@ -0,0 +1,118 @@
+/**
+ * Token 用量提取 —— 口径照 9router 的 `open-sse/utils/usageTracking.js`。
+ *
+ * 三件事：
+ *   1. **归一化**：上游字段名各不相同（prompt_tokens / input_tokens /
+ *      promptTokenCount …），统一到 OpenAI 口径。
+ *   2. **合并**：流式里 usage 常被拆在多个事件里（Claude 系：
+ *      message_start 给输入+缓存，message_delta 给输出）。所以是
+ *      **字段级 max 合并**，不是覆盖——照 9router 的 `mergeUsage`。
+ *   3. **回退估算**：上游压根不发 usage 时，按字符数/4 估算（照 9router 的
+ *      `estimateInputTokens`/`estimateOutputTokens`），并**分别**标记输入/输出
+ *      哪个是估算的——9router 只有一个 `estimated` 布尔，这里拆开更准，
+ *      面板才知道该给哪个数打「~」。
+ *
+ * 天花板（刻意不做）：
+ *   - 估算就是估算，~4 字符/token 是跨 tokenizer 的粗略平均。
+ *     要准得上真 tokenizer，代价是引入依赖，不值。
+ *   - 不注入 `stream_options.include_usage`：那要改写客户端的请求体，
+ *     个别上游不认这个字段。上游不发我们就估算，不动请求语义。
+ */
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+/** 归一化后的用量（不含估算标记）。 */
+export interface UsageTokens {
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+}
+/** 最终用量：token 数 + 哪些字段是估算的。 */
+export interface Usage extends UsageTokens {
+    /** 输入是估算的（上游没给）。 */
+    inputEstimated: boolean;
+    /** 输出是估算的（上游没给）。 */
+    outputEstimated: boolean;
+}
+/**
+ * 从上游任意形态的 usage 对象提取归一用量。
+ *
+ * `cached_tokens` 口径照 9router 的 `canonicalizeUsage`：OpenAI 系报的
+ * prompt_tokens **已含**缓存，直接透传；Claude 系报的是**不含**缓存的
+ * prompt + 单独的 cache_read，要折进来，否则总输入偏小。
+ * 判别式就是「有没有 cache_read_input_tokens」。
+ *
+ * @returns 归一用量；一个非零字段都没有时返回 null（= 没拿到 usage）
+ */
+export declare function normalizeUsage(raw: unknown): UsageTokens | null;
+/** 字段级 max 合并：后来的同名字段取大者（Claude 把 usage 拆在多个事件里）。 */
+export declare function mergeUsage(prev: UsageTokens | null, next: UsageTokens | null): UsageTokens | null;
+/**
+ * 从流式上游的一帧 JSON 里取 usage。
+ * 覆盖 OpenAI(Chat/Responses)、Claude、Gemini 三种事件形状，照 9router
+ * `extractUsage` 的形态判断（dsh-router 的上游多是 OpenAI SSE，但供应商
+ * 插件可能有直通的原生流，多认几种不亏）。
+ */
+export declare function extractFrameUsage(chunk: unknown): UsageTokens | null;
+/** 估算：~4 字符/token（照 9router 的 estimateInputTokens/estimateOutputTokens）。 */
+export declare function estimateTokens(chars: number): number;
+/**
+ * 非流式响应体取 usage。
+ *
+ * 正常是纯 JSON；但个别供应商客户端要 JSON 却回 SSE（核心会聚合成一次响应，
+ * 见 `aggregateSSE`），所以顺手扫尾部几帧——只扫尾部，不多做。
+ */
+export declare function usageFromJsonBody(body: string): UsageTokens | null;
+/**
+ * 归一用量 → DSH 的 `TokenUsage`（**必须**走这一步再交给 dsh-llm）。
+ *
+ * 为什么不能把上游 usage 原样透传：dsh-llm 的 `TokenUsage` 有两条硬性约定，
+ * 上游的 OpenAI 形态两条都踩：
+ *   1. 字段名是 `inputTokens` / `outputTokens`，不是 `prompt_tokens`；
+ *      名字对不上 → 下游读 `usage.inputTokens` 得 `undefined` → 累加出 `NaN`。
+ *   2. **DISJOINT 口径**：`inputTokens` 只算**未缓存**输入，缓存单列
+ *      `cacheReadTokens`/`cacheWriteTokens`（计费输入 = 三者之和）。
+ *      OpenAI 的 `prompt_tokens` 是**含**缓存的总量，直接当 inputTokens
+ *      就是重复计费。
+ *
+ * 后果不只是「数字不好看」：token-meter 的投影 schema 是
+ * `z.number().int().nonnegative()`，`NaN` 一进去校验就抛，整条
+ * `session.history` RPC 失败 —— 表现为「历史加载失败：history unavailable
+ * for session ... expected number, received NaN」。所以这里是**写入侧**
+ * 的防线：宁可丢掉这一帧 usage，也不能往会话日志里写 NaN。
+ *
+ * 天花板（刻意不做）：不区分 cacheRead/cacheWrite。上游多数只报读不报写，
+ * 拆不开的字段硬拆只会更错；哪天上游稳定给 `cache_creation_input_tokens`
+ * 再补 `cacheWriteTokens`（升级路径就在这）。
+ *
+ * @returns DSH 契约用量；三个数全为 0 时返回 null（= 这一帧没真数据）
+ */
+export declare function toTokenUsage(tokens: UsageTokens | null): TokenUsage | null;
+/** 流结束后汇总出的东西。 */
+export interface StreamUsage {
+    usage: UsageTokens | null;
+    /** 输出内容字符数（上游没给 completion_tokens 时用来估算）。 */
+    outputChars: number;
+    /** 首字节延迟（ms）；一个字节都没收到时为 0。 */
+    ttfbMs: number;
+}
+/**
+ * 边透传边统计：原流**原样**出去，统计在旁边做。
+ *
+ * 为什么不用 `source.tee()`：tee 的两条分支互相牵制，慢的一边会把 buffer 憋住；
+ * 而统计这条分支得读完整个流才出得了 usage，客户端那边却要尽快拿到首字节。
+ * 手动转发是把上游 chunk **即刻**交给下游，统计只攒几个数字，零缓冲、
+ * 首字节延迟不受影响。
+ *
+ * @param source 上游流（插件已转成 OpenAI SSE）
+ * @param startedAt 请求开始时间（`Date.now()`），TTFB 以此为基准
+ */
+export declare function tapStreamUsage(source: ReadableStream<Uint8Array>, startedAt: number): {
+    stream: ReadableStream<Uint8Array>;
+    done: () => Promise<StreamUsage>;
+};
+/**
+ * 补齐估算：上游没给的字段用字符数估，并打标记。
+ *
+ * `requestChars` = 请求体字符数（估输入），`outputChars` = 输出字符数（估输出）。
+ * 上游给了的字段**不覆盖**——估算只填空，不抢真数据。
+ */
+export declare function withEstimates(usage: UsageTokens | null, requestChars: number, outputChars: number): Usage;

package/lib/types/shared.d.ts

@@ -136,3 +136,72 @@ export interface RouterLoginResponse {
     error?: string;
     loginUrl?: string;
 }
+/** 面板周期。 */
+export type RouterPeriod = 'today' | '24h' | '7d' | '30d';
+/** 一条请求明细（面板「最近请求」）。 */
+export interface RouterUsageRecord {
+    ts: number;
+    supplier: string;
+    model: string;
+    /** 客户端原始请求的 model（组合场景下就是组合名）。 */
+    requested: string;
+    ok: boolean;
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+    /** 输入是估算的（上游没发 usage）。 */
+    inputEstimated: boolean;
+    /** 输出是估算的。 */
+    outputEstimated: boolean;
+    durationMs: number;
+    /** 首字节延迟（ms）；非流式为 0。 */
+    ttfbMs: number;
+    error?: string;
+}
+/** Top 榜一行。 */
+export interface RouterRankRow {
+    name: string;
+    requests: number;
+    ok: number;
+    failed: number;
+    promptTokens: number;
+    completionTokens: number;
+    lastTs: number;
+}
+/** `/router/api/stats` response. */
+export interface RouterStatsResponse {
+    ok: boolean;
+    error?: string;
+    period?: RouterPeriod;
+    requests?: number;
+    okCount?: number;
+    failed?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+    cachedTokens?: number;
+    /** 平均耗时（ms）。 */
+    avgDurationMs?: number;
+    /** 平均首字节延迟（ms）。 */
+    avgTtfbMs?: number;
+    /** 输入/输出为估算的请求数（面板据此提示）。 */
+    estimatedInputs?: number;
+    estimatedOutputs?: number;
+    /** 累计请求数（不受周期影响）。 */
+    lifetime?: number;
+    bySupplier?: RouterRankRow[];
+    byModel?: RouterRankRow[];
+    byRequested?: RouterRankRow[];
+    recent?: RouterUsageRecord[];
+}
+/** `/router/api/stats/chart` 一桶。 */
+export interface RouterChartBucket {
+    label: string;
+    requests: number;
+    tokens: number;
+}
+/** `/router/api/stats/chart` response. */
+export interface RouterChartResponse {
+    ok: boolean;
+    error?: string;
+    chart?: RouterChartBucket[];
+}

package/lib/types/supplier-config.d.ts

@@ -1,28 +1,39 @@
 export type PoolStrategy = 'fallback' | 'round-robin';
-export type CheckinRule = 'all' | 'first';
 export interface SupplierConfig {
     alias: string;
     disabled: string[];
     custom: string[];
     poolOrder: string[];
     poolStrategy: PoolStrategy;
-    checkinRule: CheckinRule;
 }
 /** 通用供应商配置存储。 */
 export declare class SupplierConfigStore {
     private fp;
     private bySupplier;
+    /** 全部供应商 id（加载时同步），用于别名唯一性校验。 */
+    private knownIds;
     constructor(stateFile: string);
+    /** 同步已知供应商 id 集合（加载供应商后调用）。 */
+    sync(supplierIds: string[]): void;
+    /** 各供应商当前生效的别名（未设置别名的用供应商 id）。 */
+    effectiveAliases(): Map<string, string>;
     /** 读取某供应商配置(不存在则返回默认并注册)。 */
     get(supplierId: string): SupplierConfig;
-    setAlias(supplierId: string, alias: string): void;
+    /**
+     * 设置别名。别名必须唯一——它是对外模型全名的前缀（alias/model），
+     * 请求时用别名反查供应商，重复就会指错人。空别名表示用供应商 id（默认值）。
+     * @returns 冲突时返回占用的供应商 id
+     */
+    setAlias(supplierId: string, alias: string): {
+        ok: boolean;
+        conflictWith?: string;
+    };
     setModelEnabled(supplierId: string, modelId: string, enabled: boolean): void;
     setAllModelsEnabled(supplierId: string, enabled: boolean, allModelIds: string[]): void;
     addCustomModel(supplierId: string, modelId: string): void;
     removeCustomModel(supplierId: string, modelId: string): void;
     setPoolOrder(supplierId: string, uids: string[]): void;
     setPoolStrategy(supplierId: string, strategy: string): void;
-    setCheckinRule(supplierId: string, rule: string): void;
     private load;
     private saveLocked;
 }

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

@@ -9,8 +9,7 @@
  * 用户自定义供应商 js 放到 `~/.dsh/profiles/web/suppliers/*.js`，重启后自动加载。
  * 内置供应商与用户 js 同构（差异化能力驱动）。
  */
-import type { ServerResponse } from 'node:http';
-import type { ChatRequest, ModelInfo, SupplierAccount, SupplierStatus } from '../router/types.ts';
+import type { ChatRequest, ModelInfo, SupplierAccount } from '../router/types.ts';
 import type { SupplierConfigStore } from '../supplier-config.ts';
 import type { CredentialStore } from '../credential-store.ts';
 /** 供应商配置：loader 注入的运行时环境。 */
@@ -26,6 +25,58 @@ export interface SupplierEnv {
 }
 /** 通用供应商工厂：一个 js 模块 export 它（或 default export 它），loader 调用得到实例。 */
 export type SupplierFactory = (env: SupplierEnv) => SupplierModule;
+/**
+ * 账户此刻的状态 —— 插件**解读**上游信号后的语义状态。
+ *
+ * 插件只报「现在怎么了」，不说「该怎么办」：冷却多久、是否禁用、要不要换号
+ * 都是核心的策略，见 `AccountState` 各值的处置表（docs/suppliers.md）。
+ *
+ * 天花板：目前是固定枚举。若将来某供应商需要更细的语义，再加值而不是放宽成
+ * 字符串——核心的策略表要能穷举。
+ */
+export type AccountState = 'ok' | 'rate_limit' | 'quota' | 'session_dead' | 'unavailable' | 'transport' | 'unknown'
+/**
+ * 这个模型不属于本供应商（不是账号的失败，也不是上游故障）。
+ * 核心据此**跳过整个供应商**换下一个，而不是记在账号头上——
+ * 否则组合里每有一个别人家的模型，就会给无关账号攒一次错误，攒够阈值
+ * 把它冷却掉（历史上正是这个坑）。
+ */
+ | 'no_such_model';
+/** 面板展示的账号此刻状态（插件只报它观察到的部分，冷却/禁用由核心叠加）。 */
+export interface SupplierAccountNow {
+    uid: string;
+    nickname?: string;
+    credits: number;
+    /** 插件观察到的上游状态。 */
+    state: AccountState;
+    /** 状态的人类可读补充（如上游错误串），可选。 */
+    message?: string;
+}
+/** 插件报的供应商状态（accounts 是「现在状态」，非核心加工后的面板态）。 */
+export interface SupplierStatusNow {
+    id: string;
+    name: string;
+    accounts: SupplierAccountNow[];
+}
+/** 一次上游调用的结果。 */
+export type ChatOnceResult = 
+/** 流式：插件已把上游协议转成 OpenAI SSE，核心只负责 pipe 到 res。 */
+{
+    ok: true;
+    stream: ReadableStream<Uint8Array>;
+}
+/** 非流式：核心写 JSON。 */
+ | {
+    ok: true;
+    status: number;
+    body: string;
+}
+/** 失败：核心据此做冷却/禁用/换号。 */
+ | {
+    ok: false;
+    state: AccountState;
+    message: string;
+};
 /** 供应商模块 —— 契约（核心必须，差异化可选）。 */
 export interface SupplierModule {
     /** 供应商唯一 id（小写字母数字 - _）。 */
@@ -36,18 +87,23 @@ export interface SupplierModule {
     readonly priority?: number;
     /** 图标（URL 或 SVG data URI），面板供应商卡片显示。可选。 */
     readonly icon?: string;
-    status(): SupplierStatus;
+    /** 报账号「现在状态」。冷却/禁用/错误累计由核心叠加，插件不算这些。 */
+    status(): SupplierStatusNow;
     /** 模型来源。`force=true` 时强制刷新来源（核心「获取模型」按钮调用）。 */
     listModels(force?: boolean): Promise<ModelInfo[]> | ModelInfo[];
     /** 默认前缀（可被通用层 alias 覆盖）。 */
     getAlias(): string;
-    chatCompletions(req: ChatRequest, res: ServerResponse): Promise<boolean>;
-    /** 测试模型（验证上游真实可用，必要差异化能力）。 */
-    testModel(id: string): Promise<{
-        ok: boolean;
-        error?: string;
-    }>;
+    /**
+     * 对**单个账号**调一次上游。插件不遍历账号、不管冷却、不写 res——
+     * 选号/回退/健康判定全是核心的活。
+     * 无账号供应商（如 opencode）传空 uid，忽略即可。
+     */
+    chatOnce(uid: string, req: ChatRequest): Promise<ChatOnceResult>;
     dispose(): void;
+    /** 上次 chatOnce 失败的原因（诊断用）。
+     *  测试模型由 dsh-router 核心统一走 chatOnce 路径（账号池回退/冷却自动生效），
+     *  插件只需把失败原因暴露出来供核心汇总；不实现则测试失败时只有通用提示。 */
+    lastError?(): string | undefined;
     /** 生成登录链接（加账号）。有它才显示连接池（账号池）。 */
     generateLoginUrl?(): string | {
         ok: boolean;
@@ -79,19 +135,12 @@ export interface SupplierModule {
     removeLink?(uid: string): Promise<boolean>;
     /** 轮询式登录标记：有它 → 面板隐藏「粘贴回调链接」步骤，登录后直接点完成（后台轮询）。 */
     pollLogin?(): boolean;
-    /** 触发签到。签到规则(all/first)是 dsh-router 通用策略,不在此列。 */
-    checkinNow?(): Promise<{
+    /** 单个链接签到。遍历所有链接 + 结果汇总是 dsh-router 核心的活,插件只管一个 uid。
+     *  status: 'ok'(签到成功) / 'already'(今日已签到) / 'error'(失败)。 */
+    checkinNow?(uid: string): Promise<{
         ok: boolean;
-        total: number;
-        succeeded: number;
-        already?: number;
-        error?: string;
-        results?: Array<{
-            uid: string;
-            ok: boolean;
-            status?: string;
-            message?: string;
-        }>;
+        status: string;
+        message?: string;
     }>;
 }
 /** 供应商账号（复用 router 类型，供 loader 包装）。 */