dsh-router-core 0.2.0 → 0.3.1

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/index.d.ts

@@ -1,6 +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;
@@ -12,7 +13,17 @@ export declare class Router {
     private store;
     /** 模型列表缓存（supplierId → 模型 + 拉取时间）。插件只管拉，不缓存。 */
     private modelsCache;
-    constructor(stateFile?: string, store?: SupplierConfigStore);
+    /** 请求日志出口（面板/宿主 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;
@@ -65,6 +76,11 @@ export declare class Router {
      *  只剥「已知 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[]): {
@@ -90,15 +106,28 @@ 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 处置 → 失败换号；写响应只在成功后发生。
      *
-     * 流式一旦写出响应头就绑死（上游协议如此，9router 同样如此），所以
-     * 「拿到 ok:true 的流」即视为该账号成功，之后出错不再换号——要能回退
-     * 就得在写头前缓冲判定，代价是首字节延迟，目前未做。
+     * 流式**推迟到第一个字节才写响应头**，所以「上游刚连上就断」这种情况
+     * 还能换号重试；一旦写出第一个字节就绑死（HTTP 语义，9router 同样如此），
+     * 之后出错不再换号——要彻底能回退就得在写头前缓冲判定，代价是首字节
+     * 延迟，目前未做。
      */
     private chatWithSupplier;
     /** 测试某供应商的某模型是否可用。

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

@@ -11,7 +11,7 @@ export declare const ROUTER_VIEW_SELECTOR = "[data-dsh-router-view]";
 /** Active-state attribute on <html> that shows the panel. */
 export declare const ROUTER_ACTIVE_ATTR = "data-dsh-router-active";
 /** The panel's visible title (also the sidebar entry label). */
-export declare const ROUTER_TITLE = "\u8DEF\u7531\u7CFB\u7EDF";
+export declare const ROUTER_TITLE = "\u8DEF\u7531";
 /** Same-origin API base the client panel fetches (host half serves it). */
 export declare const ROUTER_API_BASE = "/router/api";
 /** Bearer key env / credential reference protecting /v1/*. */
@@ -44,6 +44,22 @@ export interface RouterModelsResponse {
         context_length?: number;
     }>;
 }
+/** 一键签到：单个供应商的汇总结果（`/suppliers/:id/checkin` 的响应体）。 */
+export interface RouterCheckinResponse {
+    ok: boolean;
+    error?: string;
+    total: number;
+    /** 真正 claim 成功的链接数。 */
+    succeeded: number;
+    /** 今日已签到的链接数（幂等成功）。 */
+    already: number;
+    results?: Array<{
+        uid: string;
+        ok: boolean;
+        status?: string;
+        message?: string;
+    }>;
+}
 /** `/router/api/health` response. */
 export interface RouterHealthResponse {
     ok: boolean;
@@ -136,3 +152,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

@@ -10,10 +10,24 @@ export interface SupplierConfig {
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-router-core",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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": {
@@ -33,7 +33,10 @@
       "inject": [
         "react",
         "react-dom",
-        "cordis"
+        "cordis",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-locale"
       ],
       "platform": "web"
     }
@@ -45,20 +48,25 @@
     "lib/types/**/*.d.ts",
     "src",
     "cordis.patch.yml",
+    "docs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown && npm run build:client",
+    "build": "node scripts/check-css.mjs && rm -rf lib && tsc -p tsconfig.build.json && tsdown && npm run build:client",
     "build:client": "DSH_CLIENT_ID=dsh-router DSH_CLIENT_FILE=client.js vite build -c client/vite.config.ts && DSH_CLIENT_ID=dsh-external/dsh-router DSH_CLIENT_FILE=client-registry.js vite build -c client/vite.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "node --test \"src/**/*.test.ts\"",
     "bundle": "tsdown",
-    "watch": "tsdown --watch"
+    "watch": "tsdown --watch",
+    "check:css": "node scripts/check-css.mjs"
   },
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "*",
+    "@deepseek-ai/dsh-client-runtime": "*",
+    "@deepseek-ai/dsh-client-ui-slots": "*",
     "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0",
@@ -67,6 +75,15 @@
   "peerDependenciesMeta": {
     "cordis": {
       "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-runtime": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/client/CheckinCard.tsx

@@ -0,0 +1,180 @@
+/**
+ * 概览的「签到」汇总卡：一键签到所有支持签到的供应商 + 显示今天点过没。
+ *
+ * **「今日已签到」的口径（天花板，刻意不撒谎）**：这里只知道「今天在这个浏览器
+ * 点过这个按钮没」，存在 localStorage，**不知道上游是不是真的签上了**。真凭据是
+ * 上游的 `checked_in`，但那得逐个链接查（traywork 侧实测：积分不可信、
+ * 只有 checked_in 算数），而当前契约里没有「查签到状态」这个能力。
+ * 所以卡片文案是「今日已点」而不是「已签到」，悬停说明里写清这一点。
+ *
+ * 要真状态的升级路径：给 supplier 契约加 `checkinStatus?()`，核心加一条
+ * `/suppliers/:id/checkin/status` 汇总路由，这里改成读它即可（卡片不用改）。
+ */
+import { useEffect, useState } from 'react'
+import {
+  ROUTER_API_BASE,
+  type RouterCheckinResponse,
+  type RouterHealthResponse,
+} from '../shared.ts'
+
+/* ---------------- SVG 图标 ---------------- */
+
+function Icon({ d, size = 14 }: { d: string; size?: number }): JSX.Element {
+  return (
+    <svg viewBox="0 0 24 24" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d={d} />
+    </svg>
+  )
+}
+
+const I = {
+  check: 'M4 12.5l5 5L20 6.5',
+  loading: 'M12 3a9 9 0 1 0 9 9',
+}
+
+/** localStorage key：值 = 本地日期 YYYY-MM-DD。 */
+const CHECKIN_STAMP_KEY = 'dsh-router:checkin-stamp'
+
+/** 本地日切（跟用量统计的 localDateKey 同口径，别用 UTC）。 */
+function todayKey(ts = Date.now()): string {
+  const d = new Date(ts)
+  const p = (n: number): string => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`
+}
+
+function readStamp(): string | null {
+  try {
+    return localStorage.getItem(CHECKIN_STAMP_KEY)
+  } catch {
+    // 隐私模式 / 存储被禁：退化为「不记得」，不影响签到本身能用
+    return null
+  }
+}
+
+function writeStamp(): void {
+  try {
+    localStorage.setItem(CHECKIN_STAMP_KEY, todayKey())
+  } catch { /* 存不了就只影响这个提示，签到照常 */ }
+}
+
+interface CheckinCardProps {
+  /** 供应商健康快照（用来筛出支持 checkinNow 的）。 */
+  health: RouterHealthResponse | null
+  /** 签完回调，让概览刷新快照（积分会变）。 */
+  onRefresh: () => void
+}
+
+/** 可签到的供应商（能力 checkinNow）。 */
+function checkinable(health: RouterHealthResponse | null): Array<{ id: string; name: string }> {
+  return (health?.suppliers ?? [])
+    .filter((s) => (s.capabilities ?? []).includes('checkinNow'))
+    .map((s) => ({ id: s.id, name: s.name }))
+}
+
+export function CheckinCard({ health, onRefresh }: CheckinCardProps): JSX.Element {
+  const [busy, setBusy] = useState(false)
+  const [stamp, setStamp] = useState<string | null>(null)
+  const [result, setResult] = useState<string>('')
+  const [error, setError] = useState<string>('')
+
+  // 挂载时读一次；跨天自动失效因为存的是日期串
+  useEffect(() => { setStamp(readStamp()) }, [])
+
+  const targets = checkinable(health)
+  const clickedToday = stamp === todayKey()
+
+  const run = async (): Promise<void> => {
+    if (busy || targets.length === 0) return
+    setBusy(true)
+    setError('')
+    setResult('')
+    let okCount = 0
+    let alreadyCount = 0
+    let totalCount = 0
+    const failures: string[] = []
+    // 顺序发：签到是有副作用的上游调用，并发会把上游风控招来（见 traework 9074）
+    for (const t of targets) {
+      try {
+        const res = await fetch(`${ROUTER_API_BASE}/suppliers/${t.id}/checkin`, { method: 'POST', cache: 'no-store' })
+        const data = await res.json() as RouterCheckinResponse
+        if (data.error !== undefined) {
+          failures.push(`${t.name}：${data.error}`)
+          continue
+        }
+        okCount += data.succeeded
+        alreadyCount += data.already
+        totalCount += data.total
+        if (!data.ok) {
+          const first = (data.results ?? []).find((r) => r.status !== 'ok' && r.status !== 'already')
+          failures.push(`${t.name}：${first?.message ?? '有链接签到失败'}`)
+        }
+      } catch (err) {
+        failures.push(`${t.name}：${(err as Error).message}`)
+      }
+    }
+    // 只要发出去过就记「今日已点」——点过就是点过，成败另说（文案也这么说）
+    writeStamp()
+    setStamp(todayKey())
+    const parts = [`${okCount}/${totalCount} 成功`]
+    if (alreadyCount > 0) parts.push(`${alreadyCount} 今日已签`)
+    setResult(parts.join(' · '))
+    if (failures.length > 0) setError(failures.join('；'))
+    onRefresh()
+    setBusy(false)
+  }
+
+  /**
+   * 第三行文案：所有状态/结果都压在这一行里，行数恒定。
+   * 优先级：失败 > 本次结果 > 今日已点 > 默认供应商数。
+   * 失败时截断显示（全量挂 title），不换行。
+   */
+  const hintText = (): string => {
+    if (targets.length === 0) return '没有支持签到的供应商'
+    if (busy) return '签到中…'
+    if (error !== '') return `失败 · ${error}`
+    if (result !== '') return result
+    return clickedToday ? `今日已点 · ${targets.length} 个供应商` : `${targets.length} 个供应商`
+  }
+
+  /** 悬停说明：成功/失败都在这儿补全，正文只放得下一行 */
+  const hintTitle = (): string => {
+    if (targets.length === 0) return '没有供应商实现了 checkinNow 能力'
+    const lines = [`对 ${targets.length} 个支持签到的供应商逐个签到：${targets.map((t) => t.name).join('、')}`]
+    if (clickedToday) lines.push('今天在这个浏览器点过签到（不代表上游一定签上了）')
+    if (result !== '') lines.push(`上次结果：${result}`)
+    if (error !== '') lines.push(`失败：${error}`)
+    return lines.join('\n')
+  }
+
+  return (
+    <div
+      className={`dshr-statCard dshr-statCard-checkin${clickedToday ? ' dshr-statCard-done' : ''}`}
+      title={hintTitle()}
+    >
+      <span className="dshr-statLabel">签到</span>
+      {targets.length === 0
+        ? (
+          <span className="dshr-statValue">—</span>
+        )
+        : (
+          <button
+            type="button"
+            className={`dshr-checkinButton${busy ? ' dshr-checkinButton-busy' : ''}`}
+            onClick={() => { void run() }}
+            disabled={busy}
+            title={hintTitle()}
+          >
+            <span className={busy ? 'dshr-spin' : undefined}>
+              <Icon d={busy ? I.loading : I.check} size={14} />
+            </span>
+            {busy ? '签到中…' : '一键签到'}
+          </button>
+        )}
+      {/* 恒定第三行：状态/结果全塞进 hint，不成功后多出一行
+          —— 汇总卡是 3 行结构（label / value / hint），多一行就跟邻卡不齐 */}
+      <span className={`dshr-statHint${error !== '' ? ' dshr-statHint-err' : ''}`} title={error !== '' ? error : undefined}>
+        {hintText()}
+      </span>
+    </div>
+  )
+}