hiwork-core 0.0.2 → 0.0.6

package/lib/types/client/daily-data.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 「每日一句」的客户端取数层：经 `/hiwork-daily` loopback RPC 拉取网关当日条目，
+ * 成功结果按服务端日期做全天缓存、失败 5 分钟 TTL 防抖、随机条目永不入缓存。
+ *
+ * 铁律：
+ *  - 客户端**不持有**会话 cookie，也**不直接 fetch 网关**——一切经 Host 频道；
+ *  - `null` 即「暂无可展示内容」（数据未就绪 / RPC 失败 / 当日池空一律归一为 null），
+ *    视图对各种情况一视同仁：不插卡片、不出任何错误 UI；
+ *  - rAF 观察循环在流式输出时逐帧触发，**任何未定状态都不得重复打网关**：
+ *    成功按服务端 `date` 缓存全天（含「池空」这种 `item:null` 的成功）、失败 5 分钟内
+ *    直接短路、并发请求合并复用同一次 RPC。
+ *
+ * client bundle 纯度：本文件不 import 任何 `@deepseek-ai/*` 运行时值，也不 import
+ * Host 代码（网关 JSON 字段在这里按结构重声明，字段名与网关一致）。
+ */
+/** RPC 频道；必须与 Host `src/daily-rpc.ts` 的 `DAILY_RPC_CHANNEL` 一致（由测试锁定）。 */
+export declare const DAILY_CHANNEL = "/hiwork-daily";
+/** 端点白名单；必须与 Host `DAILY_RPC_ENDPOINTS` 一致（由测试锁定）。 */
+export declare const DAILY_ENDPOINTS: readonly ["today", "random"];
+export type DailyEndpoint = (typeof DAILY_ENDPOINTS)[number];
+/** 失败防抖 TTL：5 分钟——观察循环逐帧触发，绝不逐帧重试网关。 */
+export declare const DAILY_FAILURE_TTL_MS: number;
+/**
+ * 单条每日一句的视图形状（网关 JSON 按结构重声明后的归一结果）：
+ * 可选字段缺省一律归一为空串 / 空数组，视图据此隐藏对应区块。
+ */
+export interface DailyQuoteView {
+    id: number;
+    /** 卡片主行（蓝渐变大字）。 */
+    content: string;
+    /** 卡片主行上方小字；空串 = 缺省（隐藏）。 */
+    subtitle: string;
+    /** 弹窗标题；空串 = 缺省（弹窗只展示 content）。 */
+    title: string;
+    /** 弹窗 meta 出处；空串 = 缺省（隐藏）。 */
+    source: string;
+    /** 弹窗正文段落；空数组 = 缺省（隐藏整块）。 */
+    body: readonly string[];
+}
+/** 当日条目视图：附带服务端东八区日期（YYYY-MM-DD，弹窗与跨日重建判断直接使用）。 */
+export interface DailyTodayView extends DailyQuoteView {
+    date: string;
+}
+/** 宿主 loopback RPC 调用面（结构兼容 `ctx.connection.rpc`）。 */
+export interface DailyRpcPort {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/** 带稳定 code 的取数错误（message 已由 Host 消毒，可直接展示）。 */
+export declare class DailyRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** 组件消费的最小取数面（便于视图与测试注入假实现）。 */
+export interface DailyQuoteLoader {
+    getToday(): Promise<DailyQuoteView | null>;
+    getRandom(excludeId?: number): Promise<DailyQuoteView | null>;
+}
+/**
+ * 解开 DSH Connection 的结果信封。
+ * 宿主返回 `{ok:true,value}` / `{ok:false,error:{code,message}}`；形状不合法时抛
+ * 通用失败，绝不把未知结构当数据渲染。
+ */
+export declare function unwrapDailyResult<T>(value: unknown): T;
+/**
+ * 结构化校验单条条目：id 必须是正整数、content 必填；可选字段缺省归一为空串 / 空数组。
+ * 形状非法返回 undefined（调用方按「本次失败」处理，绝不渲染未知结构）。
+ */
+export declare function parseQuoteItem(value: unknown): DailyQuoteView | undefined;
+/**
+ * 结构化校验 today 响应：`date` 必须是 YYYY-MM-DD、`item` 为 null（池空）或合法条目。
+ * 形状非法返回 undefined（按失败处理）。
+ */
+export declare function parseTodayResponse(value: unknown): {
+    date: string;
+    item: DailyQuoteView | null;
+} | undefined;
+/** 结构化校验 random 响应：`item` 为 null 或合法条目；形状非法返回 undefined。 */
+export declare function parseRandomResponse(value: unknown): {
+    item: DailyQuoteView | null;
+} | undefined;
+/**
+ * 本地日历日的纪元日数（跨日检测的唯一时钟）：观察循环的 60 秒轮询与本仓库的
+ * 缓存过期判断共用同一公式，跨午夜时由任一侧触发重拉。
+ */
+export declare function localDayIndex(date?: Date): number;
+/**
+ * 每日一句取数仓库：全天缓存 + 失败防抖 + 并发合并；随机条目永不入缓存。
+ */
+export declare class DailyDataStore implements DailyQuoteLoader {
+    private readonly rpc;
+    private entry;
+    private failureAt;
+    private pending;
+    private readonly now;
+    private readonly localDay;
+    private readonly failureTtlMs;
+    constructor(rpc: DailyRpcPort, options?: {
+        now?: (() => number) | undefined;
+        localDay?: (() => number) | undefined;
+        failureTtlMs?: number | undefined;
+    });
+    /** 清空缓存与防抖状态（登出 / 换账号时调用）。 */
+    clear(): void;
+    /**
+     * 当日条目：同一本地日内命中缓存直接返回（不发 RPC）；失败防抖期内返回 null 不
+     * 重复打网关；并发调用合并为同一次 RPC。返回 null 即「暂无可展示内容」。
+     */
+    getToday(): Promise<DailyTodayView | null>;
+    /**
+     * 换一句：排除当前条目的随机条目；**永不入缓存**（与「临时预览」语义一致），
+     * 失败 / 暂无随机条目返回 null（视图保持当前条目、无任何提示）。
+     */
+    getRandom(excludeId?: number): Promise<DailyQuoteView | null>;
+    /** 单次 today 拉取：成功（含池空）写缓存；任何失败进入 5 分钟防抖并返回 null。 */
+    private fetchToday;
+}

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

@@ -1,7 +1,7 @@
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 export type { FeatureRenderContext, FeatureRegistry, HiWorkFeature } from './feature-registry.ts';
 export type { HiWorkCoreClientFace } from './contracts.ts';
-/** 浏览器插件契约（dsh client module system）。connection 随 IApiClient 移除后不再依赖。 */
+/** 浏览器插件契约（dsh client module system）。connection 承载 loopback RPC（见 src/client/usage-data.ts）。 */
 export declare const inject: string[];
 /** 挂载网关模型设置 section（一级 tab）与未登录弹窗。 */
 export declare function apply(ctx: ClientContext): void;

package/lib/types/client/login-gate.d.ts

@@ -1,6 +1,15 @@
 import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { CredentialStorePort } from './controller.ts';
+import type { LoginError } from './types.ts';
 import { type AiRouterCardSettings } from './controller.ts';
+/**
+ * 登录错误文案：把 Host 的稳定错误码翻成用户能理解的说法。
+ * - `GATEWAY_UNREACHABLE` 的 Host 文案会带上 `baseURL` / `HTTP 500` 这类实现细节，统一换成人话；
+ * - `AUTH_FAILED` 的三种成因（一次性 code 过期 / state 校验失败 / 授权被拒）Host 已按成因
+ *   给出中文文案，优先沿用；文案缺失时才用覆盖全部成因的兜底句；
+ * - 其余错误码保持既有行为（原样展示 Host message），不影响 NO_KEY / KEY_* 等既有呈现。
+ */
+export declare function describeLoginError(error: LoginError | undefined): string | undefined;
 export declare function loginGateVisible(snapshot: {
     status: string;
     value?: {

package/lib/types/client/session-cost.d.ts

@@ -0,0 +1,119 @@
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { TurnTailChatData, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client';
+/** 计价端点名；必须与 Host `src/usage-rpc.ts` 的 `USAGE_RPC_ENDPOINTS` 一致（由测试锁定）。 */
+export declare const SESSION_COST_ENDPOINT = "estimate";
+/** 缓存 TTL：5 分钟（与设置页取数一致；同一轮的金额不会随滚动反复请求）。 */
+export declare const SESSION_COST_CACHE_TTL_MS: number;
+/** 悬停说明（设计 §7：明确「按网关价格估算」）。 */
+export declare const SESSION_COST_HINT = "\u6309\u7F51\u5173\u4EF7\u683C\u4F30\u7B97\uFF0C\u4EC5\u4F9B\u53C2\u8003\uFF1B\u4EE5\u300C\u7528\u91CF\u4E0E\u6210\u672C\u300D\u4E2D\u7684\u6743\u5A01\u8D26\u5355\u4E3A\u51C6";
+/** 估算标记（多线路/多模型无法拆分，或渠道未解析）。 */
+export declare const SESSION_COST_ESTIMATED_SUFFIX = "\uFF08\u4F30\u7B97\uFF09";
+/** 提交给 Host `estimate` 端点的单项（`route` 是 **DSH 线路名**，翻译在 Host 侧做）。 */
+export interface SessionCostItem {
+    route: string;
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens?: number;
+    cache_write_tokens?: number;
+    /** 该轮结束时刻（RFC3339）：网关据此取当时的时段价。 */
+    at?: string;
+}
+/** `select` 的返回值（链槽的 `matched` 共享）。 */
+export interface SessionCostMatch {
+    /** 该轮要计价的项目（当前 DSH 契约下恒为 1 项，见文件头注释）。 */
+    items: SessionCostItem[];
+    /** 该轮 turn 号（`TurnTailChatData.turn`），缓存键的一部分。 */
+    turn: number;
+    /** 该轮出现多个 (线路, 模型) 组合 → 金额只能按首条估，UI 必须标注「估算」。 */
+    ambiguous: boolean;
+}
+/** 一次计价的结果（只保留可展示所需的最小字段）。 */
+export interface SessionCostResult {
+    cost: number;
+    channelResolved: boolean;
+}
+/** Host loopback RPC 调用面（结构兼容 `ctx.connection.rpc`）。 */
+export interface SessionCostRpcPort {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/**
+ * 从 turn-tail 数据派生该轮的计价项。
+ *
+ * 入参用 ui-chat 的**真实类型** `TurnTailChatData`：DSH 改字段名时这里先编译失败，
+ * 而不是悄悄取不到用量；运行时仍逐字段校验（宿主 DSH 版本可能与开发依赖不同版本）。
+ *
+ * 返回 `null`（→ 不挂载、不显示任何东西）的情形：无数据、无 `tokenUsage`、
+ * `routes` 缺失/为空/归属不完整、四个桶全为 0（没有可计价的内容）、形状不合法。
+ * @param data - `owner.turn.data.get('turn-tail')` 的原始值。
+ * @returns 计价项 + turn 号 + 归属是否歧义；无法计价时为 null。
+ */
+export declare function sessionCostMatchOf(data: TurnTailChatData | undefined): SessionCostMatch | null;
+/**
+ * 链槽 `conversation.chat.turnTail` 的路由选择器：只有该轮拿得到用量时才占用位置。
+ * @param owner - turn-tail owner（turn / seq / openFile）。
+ * @returns 计价项；取不到用量时 null（框架不挂载组件）。
+ */
+export declare function selectSessionCost(owner: TurnTailOwnerProps): SessionCostMatch | null;
+/** 缓存键：会话 + 轮次 + 计价项内容（滚动/重挂载不会重复请求同一轮）。 */
+export declare function sessionCostKey(sessionId: string, match: Pick<SessionCostMatch, 'turn' | 'items'>): string;
+/**
+ * 归一化 Host `estimate` 的返回值：只接受 `priced:true` 且金额可信的结果。
+ *
+ * `priced:false`（无会话 / 无可用线路 / 网关未计价）与形状非法一律返回 undefined——
+ * 视图据此**不显示任何金额**。
+ * @param value - 信封解开后的值。
+ * @returns 可展示的金额与渠道解析标记；不可展示时 undefined。
+ */
+export declare function normalizeSessionCost(value: unknown): SessionCostResult | undefined;
+/**
+ * 逐轮计价仓库：按 {@link sessionCostKey} 缓存（TTL 5 分钟）+ 在途请求去重。
+ *
+ * 语义：
+ *  - 命中未过期缓存 → 不发 RPC；
+ *  - 同一键已有在途请求 → 复用同一个 Promise（一次挂载/重挂载只发一次）；
+ *  - 只有 `priced:true` 的结果才进缓存：未计价 / 失败不缓存，登录后重挂载即可重试；
+ *  - 任何异常都收敛成 undefined，绝不抛给对话渲染。
+ */
+export declare class SessionCostStore {
+    private readonly rpc;
+    private readonly entries;
+    private readonly pending;
+    private readonly now;
+    private readonly ttlMs;
+    constructor(rpc: SessionCostRpcPort, options?: {
+        now?: (() => number) | undefined;
+        ttlMs?: number | undefined;
+    });
+    /** 当前缓存条目数（测试断言用）。 */
+    get size(): number;
+    /** 清空缓存（登出 / 切换账号）。 */
+    clear(): void;
+    estimate(input: {
+        sessionId: string;
+        turn: number;
+        items: readonly SessionCostItem[];
+        signal?: AbortSignal | undefined;
+    }): Promise<SessionCostResult | undefined>;
+    private request;
+}
+/** 组件注入面：逐轮计价仓库（客户端不持有会话 cookie，也不直连网关）。 */
+export interface SessionCostFace {
+    store: SessionCostStore;
+}
+/**
+ * 链槽组件 props：owner（turn/seq/openFile）+ 会话标准件（`sessionId`）+ 注入面 + `matched`。
+ * `sessionId` 由框架下发（ui-session 的 SessionStandardProps），不在这里重复声明。
+ */
+export type SessionCostProps = PropsRuntime<'conversation.chat.turnTail'> & InjectFace<SessionCostFace> & {
+    matched: SessionCostMatch;
+};
+/**
+ * 渲染一轮的估算金额。
+ *
+ * 三种状态：全部计价且渠道已解析、单组合 → `≈ ¥x`；渠道未解析或该轮多组合 →
+ * `≈ ¥x（估算）`；其余（未计价 / 失败 / 加载中）→ **不渲染任何内容**。
+ * @param props - 链槽 props。
+ * @returns 金额文本节点，或 null（不影响对话渲染）。
+ */
+export declare function SessionCost({ matched, sessionId, store }: SessionCostProps): import("react").JSX.Element | null;

package/lib/types/client/styles.d.ts

@@ -48,10 +48,22 @@ export declare const textInput: CSSProperties;
  * 内容区根节点类名是 CSS module 哈希前缀（如 wSkVaW_root），语义后缀稳定；
  * 用直接子链 `[class*="_centerCol"] > div > [class*="_root"]` 恰好命中会话区
  * 根节点（实测唯一），避免误伤内容区里 10 个嵌套组件的 _root。
+ * 框架底色同理不能只认 `_frame` 后缀：该后缀被 6 个 CSS module 复用（主框架
+ * AppFrame 之外还有会话右侧快速索引 TurnNavigator、附件图 MessageImage、
+ * 提问面板 QuestionComposer/PlanReviewPanel、只读输入框 SubagentReadOnlyComposer），
+ * 裸 `[class*="_frame"]` 会把这些 `.frame` 一起涂成侧栏灰（快速索引原本是透明底）。
+ * 故用 frameSurfaceSelector 的 `:has(> _sidebarCol)` 锁死到 AppFrame 本体——
+ * 只有主框架直接包含侧栏列。
  * 圆角裁切天然成立：会话区根节点自带 overflow:hidden，头部页签/气泡/输入框
  * 都会被裁切；颜色全部走主题变量，亮暗自动切换。
  * 侧栏右缘 0.5px 原生分界线一并归零（与内容区无边框保持一致）。
  */
+/**
+ * 主框架底色的命中选择器：`[class*="_frame"]` 只锁定直接包含侧栏列的 AppFrame。
+ * 不用裸后缀，避免误伤同名 `.frame` 的其他组件（见上方注释）；
+ * 后续要改框架底色，一律复用此选择器。
+ */
+export declare const frameSurfaceSelector = "[class*=\"_frame\"]:has(> [class*=\"_sidebarCol\"])";
 export declare const frameCss: string;
 /**
  * 隐藏宿主动作入口：

package/lib/types/client/types.d.ts

@@ -1,5 +1,5 @@
 /** 稳定错误码，供 settings card 分支渲染。 */
-export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHABLE' | 'NO_KEY_ASSIGNED' | 'SESSION_EXPIRED' | 'KEY_DISABLED' | 'KEY_INVALID';
+export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHABLE' | 'NO_KEY_ASSIGNED' | 'SESSION_EXPIRED' | 'KEY_DISABLED' | 'KEY_INVALID' | 'NOT_FOUND';
 /** 一个稳定的、可安全展示的登录/刷新错误。 */
 export interface LoginError {
     code: LoginErrorCode;

package/lib/types/client/usage-data.d.ts

@@ -0,0 +1,276 @@
+/**
+ * 设置页「用量与成本」的客户端取数层：经 `/hiwork-usage` loopback RPC 拉取网关
+ * 权威账单，做 5 分钟缓存、部分失败保留上次成功数据、全部失败进入降级态。
+ *
+ * 铁律：
+ *  - 客户端**不持有**会话 cookie，也**不直接 fetch 网关**——一切经 Host 频道；
+ *  - 客户端不做任何定价 / 折算公式，只做**展示口径的聚合**（同一份权威数字求和、
+ *    按自然月过滤趋势桶）；
+ *  - 失败绝**不**降级成 0 或占位数字：缺数据的字段一律 `undefined`，由视图渲染 `—`。
+ *
+ * client bundle 纯度：本文件不 import 任何 `@deepseek-ai/*` 运行时值，也不 import
+ * Host 代码（`src/**` 之外的类型在这里按结构重声明，字段名与网关 JSON 一致）。
+ */
+/** RPC 频道；必须与 Host `src/usage-rpc.ts` 的 `USAGE_RPC_CHANNEL` 一致（由测试锁定）。 */
+export declare const USAGE_CHANNEL = "/hiwork-usage";
+/** 端点白名单；必须与 Host `USAGE_RPC_ENDPOINTS` 一致（由测试锁定）。 */
+export declare const USAGE_ENDPOINTS: readonly ["summary", "trends", "model-trends", "recharges", "keys", "key", "estimate"];
+export type UsageEndpoint = (typeof USAGE_ENDPOINTS)[number];
+/** 缓存 TTL：5 分钟（spec §5「结果缓存 5 分钟」）。 */
+export declare const USAGE_CACHE_TTL_MS: number;
+/** 趋势与按模型分布使用的时间窗口（plan Task B2 Step 1：`trends(30d)`）。 */
+export declare const USAGE_TREND_RANGE: "30d";
+/** KPI「今日花费」的窗口：网关按自然日切分。 */
+export declare const USAGE_TODAY_RANGE: "today";
+/** KPI「本月花费 / 本月请求数」的窗口：本月 1 日 00:00 → 现在（网关 `meRange` 的 `mtd`）。 */
+export declare const USAGE_MONTH_RANGE: "mtd";
+/**
+ * 旧网关不支持 `mtd` 时的提示：网关不认该值会按缺省回退成 `24h` 并把 `range` 回填
+ * `24h`，此时本月 KPI 必须显示 `—`——**绝不拿 24 小时的数字冒充本月**。
+ * 文案只讲用户能懂的事，不带接口参数 / 地址等实现细节。
+ */
+export declare const USAGE_MONTH_RANGE_UNSUPPORTED = "\u5F53\u524D\u7F51\u5173\u7248\u672C\u6682\u4E0D\u652F\u6301\u672C\u6708\u7EDF\u8BA1\uFF0C\u672C\u6708\u82B1\u8D39\u4E0E\u8BF7\u6C42\u6570\u4E0D\u53EF\u7528";
+/** 部分失败时的提示文案（保留上次成功数据）。 */
+export declare const USAGE_STALE_TEXT = "\u6570\u636E\u53EF\u80FD\u4E0D\u662F\u6700\u65B0";
+/** 全部失败时的降级文案（不渲染任何数字）。 */
+export declare const USAGE_UNAVAILABLE_TEXT = "\u7528\u91CF\u6570\u636E\u6682\u4E0D\u53EF\u7528";
+/** 加载中提示。 */
+export declare const USAGE_LOADING_TEXT = "\u6B63\u5728\u52A0\u8F7D\u7528\u91CF\u6570\u636E\u2026";
+/** 无任何用量记录时的空态文案。 */
+export declare const USAGE_EMPTY_TEXT = "\u6682\u65E0\u7528\u91CF\u8BB0\u5F55";
+/** 无充值记录时的空态文案。 */
+export declare const USAGE_NO_RECHARGE_TEXT = "\u6682\u65E0\u5145\u503C\u8BB0\u5F55";
+/** 缺失单个数据源时占位符（**不是数字**）。 */
+export declare const USAGE_MISSING_TEXT = "\u2014";
+/** 网关支持的用量时间窗口（`mtd` 需网关侧支持，见 USAGE_MONTH_RANGE_UNSUPPORTED）。 */
+export type UsageRange = 'today' | 'yesterday' | '24h' | '7d' | '30d' | 'mtd';
+/** GET /api/me/analytics/summary 的按模型汇总项。 */
+export interface UsageModelSummary {
+    model: string;
+    request_count: number;
+    total_tokens: number;
+    total_cost: number;
+    cache_hit_rate: number;
+}
+/** GET /api/me/analytics/summary 响应。 */
+export interface UsageSummary {
+    range: string;
+    items: UsageModelSummary[];
+}
+/** 趋势桶（`period` 为 RFC3339）。 */
+export interface UsageTrendPoint {
+    period: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    request_count: number;
+    total_cost: number;
+}
+/** GET /api/me/analytics/trends 响应。 */
+export interface UsageTrends {
+    range: string;
+    group_by: string;
+    trends: UsageTrendPoint[];
+}
+/** 趋势桶的按模型拆分项。 */
+export interface UsageModelTrendBreakdown {
+    name: string;
+    total_tokens: number;
+    request_count: number;
+    total_cost: number;
+}
+/** 按模型拆分的趋势桶。 */
+export interface UsageModelTrendPoint extends UsageTrendPoint {
+    breakdown?: UsageModelTrendBreakdown[];
+}
+/** GET /api/me/analytics/model-trends 响应。 */
+export interface UsageModelTrends {
+    range: string;
+    group_by: string;
+    trends: UsageModelTrendPoint[];
+}
+/** GET /api/me/key/recharges 的一项（充值台账）。 */
+export interface UsageRecharge {
+    id: string;
+    model_name: string;
+    amount: number;
+    type: string;
+    operator: string;
+    note: string;
+    created_at: string;
+}
+/** GET /api/me/keys 的轻量 Key 项（多 Key 切换器数据源）。 */
+export interface UsageKey {
+    id: string;
+    employee_name?: string;
+    team_name?: string;
+    enabled?: boolean;
+    key_masked?: string;
+}
+/** GET /api/me/key 的单个模型额度项（KPI「剩余预算」的权威来源）。 */
+export interface UsageBudget {
+    model_name: string;
+    total_budget?: number | null;
+    consumed_budget?: number | null;
+    remaining_budget?: number | null;
+}
+/** GET /api/me/key 响应的相关子集。 */
+export interface UsageKeyDetail {
+    key: {
+        id: string;
+        enabled?: boolean;
+        employee_name?: string;
+    };
+    budgets: UsageBudget[];
+}
+/** 各端点的最近一次成功响应；未成功过 / 尚未请求时该字段为 undefined。 */
+export interface UsageData {
+    /** `summary(range: 'today')`：KPI「今日花费」。 */
+    summary: UsageSummary | undefined;
+    /**
+     * `summary(range: 'mtd')`：KPI「本月花费 / 本月请求数」。
+     * 旧网关不支持 `mtd` 时这里保持 undefined（守卫见 {@link isMonthRangeSupported}）。
+     */
+    summaryMonth: UsageSummary | undefined;
+    trends: UsageTrends | undefined;
+    modelTrends: UsageModelTrends | undefined;
+    recharges: UsageRecharge[] | undefined;
+    keys: UsageKey[] | undefined;
+    key: UsageKeyDetail | undefined;
+}
+/** 空数据（降级态使用；不含任何数字）。 */
+export declare const EMPTY_USAGE_DATA: UsageData;
+/** 取数结果。 */
+export interface UsageLoadResult {
+    /** 可用数据；`unavailable` 为 true 时是空数据。 */
+    data: UsageData;
+    /** 至少一个端点失败（其余数据仍是上次成功值）。 */
+    stale: boolean;
+    /** 全部端点失败：视图必须显示降级文案，不得渲染任何数字。 */
+    unavailable: boolean;
+    /** 首个失败的可展示错误（code 来自 Host，message 已消毒）。 */
+    error: {
+        code: string;
+        message: string;
+    } | undefined;
+    /** 本次数据的抓取时刻（毫秒）；降级态为 undefined。 */
+    fetchedAt: number | undefined;
+    /** 是否命中缓存（未发起任何 RPC）。 */
+    cached: boolean;
+}
+/** 取数入参。 */
+export interface UsageLoadInput {
+    keyId?: string | undefined;
+    range?: UsageRange | undefined;
+    /** 手动刷新：强制绕过缓存。 */
+    force?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** 组件消费的最小取数面（便于测试注入假实现）。 */
+export interface UsageLoader {
+    load(input?: UsageLoadInput): Promise<UsageLoadResult>;
+}
+/** 宿主 loopback RPC 调用面（结构兼容 `ctx.connection.rpc`）。 */
+export interface UsageRpcPort {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/** 带稳定 code 的取数错误（message 已由 Host 消毒，可直接展示）。 */
+export declare class UsageRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 解开 DSH Connection 的结果信封。
+ * 宿主返回 `{ok:true,value}` / `{ok:false,error:{code,message}}`；形状不合法时抛
+ * 通用失败，绝不把未知结构当数据渲染。
+ */
+export declare function unwrapUsageResult<T>(value: unknown): T;
+/** 任意异常 → 可展示的 `{code, message}`（传输层异常不暴露原始 message）。 */
+export declare function usageErrorOf(error: unknown): {
+    code: string;
+    message: string;
+};
+/** 缓存键：`keyId + range`（spec §5 / plan Task B2）。 */
+export declare function usageCacheKey(keyId: string | undefined, range: UsageRange): string;
+/** 单个端点的请求计划。 */
+interface EndpointPlan {
+    endpoint: UsageEndpoint;
+    field: keyof UsageData;
+    payload: {
+        keyId?: string | undefined;
+        range?: UsageRange | undefined;
+    };
+}
+/**
+ * 并发请求计划：
+ *  - `summary('today')` → 今日花费；`summary('mtd')` → 本月花费 / 请求数（同一端点两次，
+ *    各自独立成败，旧网关的 `mtd` 回退只影响本月 KPI）；
+ *  - 趋势与按模型分布走选定窗口（默认 30 天）；台账 / key 带 keyId；keys 不带。
+ */
+export declare function usageEndpointPlans(input: {
+    keyId?: string | undefined;
+    range: UsageRange;
+}): EndpointPlan[];
+/**
+ * 旧网关守卫：请求了 `range=mtd`，响应 `range` 必须原样回填 `mtd`。
+ * 网关不认该值时按缺省回退成 `24h`（响应 `range='24h'`），此时**不得**把它当本月数字。
+ */
+export declare function isMonthRangeSupported(value: unknown): boolean;
+/**
+ * 用量取数仓库：缓存 + 降级 + 保留上次成功数据。
+ *
+ * 语义：
+ *  - 命中未过期缓存 → 不发任何 RPC（`cached: true`）；
+ *  - 任一端点失败 → 该端点沿用上次成功值，`stale: true`；
+ *  - **全部端点失败** → 返回 `unavailable: true` 且 `data` 为空，并清掉本键缓存
+ *    （下次挂载 / 刷新会重新请求，而不是继续端出旧数字）。
+ */
+export declare class UsageDataStore implements UsageLoader {
+    private readonly rpc;
+    private readonly entries;
+    private readonly now;
+    private readonly ttlMs;
+    constructor(rpc: UsageRpcPort, options?: {
+        now?: (() => number) | undefined;
+        ttlMs?: number | undefined;
+    });
+    /** 当前缓存条目数（测试断言用）。 */
+    get size(): number;
+    /** 清空缓存（例如登出、切换账号）。 */
+    clear(): void;
+    load(input?: UsageLoadInput): Promise<UsageLoadResult>;
+}
+/** 金额格式化：与网关 `formatCost` 同口径（`¥` 前缀、最多 4 位小数）；缺失显示 `—`。 */
+export declare function formatYuan(value: number | undefined | null): string;
+/** KPI「今日花费」：summary(`today`) 的按模型费用合计；summary 缺失时 undefined。 */
+export declare function todayCostOf(summary: UsageSummary | undefined): number | undefined;
+/**
+ * KPI「本月花费 / 本月请求数」：网关 `summary(range: 'mtd')` 的按模型合计
+ * （一次调用同时给出 `total_cost` 与 `request_count`）。
+ *
+ * 客户端**不做**任何自然月过滤——月份边界完全由网关的 `meRange` 决定；响应的 `range`
+ * 必须是 `mtd`，否则视为旧网关回退（KPI 显示 `—`，见 {@link isMonthRangeSupported}）。
+ */
+export declare function monthToDateOf(summary: UsageSummary | undefined): {
+    cost: number;
+    requests: number;
+} | undefined;
+/** KPI「剩余预算」：`/api/me/key` budgets 的剩余额度合计；没有任何数值时 undefined。 */
+export declare function remainingBudgetOf(key: UsageKeyDetail | undefined): number | undefined;
+/** 按模型分布行（金额降序）。 */
+export interface ModelDistributionRow {
+    model: string;
+    totalCost: number;
+    requestCount: number;
+    totalTokens: number;
+}
+/**
+ * 「按模型分布」：把 model-trends 各桶的 breakdown 按模型名合并。
+ * breakdown 缺失 / 为空时返回空数组（视图渲染空态，不编数字）。
+ */
+export declare function modelDistributionOf(modelTrends: UsageModelTrends | undefined): ModelDistributionRow[];
+/** 趋势点（用于柱状图）：按时间升序。 */
+export declare function trendPointsOf(trends: UsageTrends | undefined): UsageTrendPoint[];
+/** 充值台账：按时间倒序（最新在前）。 */
+export declare function rechargesOf(recharges: readonly UsageRecharge[] | undefined): UsageRecharge[];
+export {};

package/lib/types/client/usage-section.d.ts

@@ -0,0 +1,18 @@
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { AiRouterCardState } from './controller.ts';
+import { type UsageKey, type UsageLoader } from './usage-data.ts';
+/** 分区注入面：设置作用域的 Key 选择（默认 Key）+ 取数仓库。 */
+export interface UsageSectionFace {
+    hooks: {
+        aiRouterCard: SnapshotStore<AiRouterCardState>;
+    };
+    usage: UsageLoader;
+}
+export type UsageSectionProps = PropsRuntime<'settings.section'> & InjectFace<UsageSectionFace>;
+/** Key 展示名：掩码优先，回退员工名 / id 前缀，附团队与禁用标记。 */
+export declare function keyLabel(key: UsageKey): string;
+/** 充值类型：网关自定义枚举 → 中文（未知值原样展示）。 */
+export declare function rechargeTypeLabel(type: string): string;
+/** 设置页「用量与成本」分区。 */
+export declare function UsageSection(props: UsageSectionProps): import("react").JSX.Element;

package/lib/types/client-policy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 客户端版本策略（spec §6）：`GET /api/client/policy` 的免登录只读拉取。
+ *
+ * 网关返回的是**最终判定**（`loginMode` 等），插件只做投影不做策略逻辑，因此管理端
+ * 调整 `client.login_mode` 后重启插件即生效，无需发版（spec §6.1）。
+ *
+ * 本模块只负责「拉 + 严格解析」，投影与 fail-open 缺省由 `src/index.ts` 的
+ * `projectLoginMode` 完成：**非 200 / 非 JSON / 枚举非法 / 超时 / 网络异常一律返回
+ * undefined**，调用方据此回退 `DEFAULT_LOGIN_MODE`，绝不把用户锁在门外（spec §5.4 / §6.4）。
+ */
+/**
+ * 登录方式（与 `src/client/controller.ts` 的 `LoginMode` 同值；client 半边不 import
+ * Host 代码，两处各自声明同一联合类型，改取值必须两侧同步）。
+ */
+export type LoginMode = 'browser' | 'form' | 'both';
+/** fail-open 缺省值：策略缺失 / 失败 / 非法时一律按此投影（spec §5.4）。 */
+export declare const DEFAULT_LOGIN_MODE: LoginMode;
+/** 策略端点：域名一律来自 baseURL，不硬编码。 */
+export declare const CLIENT_POLICY_PATH = "/api/client/policy";
+/** 策略拉取默认超时：免登录只读接口，超过 5s 视同不可达（fail-open）。 */
+export declare const CLIENT_POLICY_TIMEOUT_MS = 5000;
+/** 策略响应中本插件消费的部分。 */
+export interface ClientPolicy {
+    loginMode: LoginMode;
+}
+/** 拉取策略所需入参（deviceId 由 `resolveDeviceInfo` 解析，永非空）。 */
+export interface FetchClientPolicyOptions {
+    /** 网关地址；缺省 / 空串直接返回 undefined（不发起请求）。 */
+    baseURL: string | undefined;
+    /** 客户端版本（生产传 `PKG_VERSION`）。 */
+    version: string;
+    /** 平台 / 架构（生产传 `process.platform` / `process.arch`）。 */
+    platform: string;
+    arch: string;
+    deviceId: string;
+    /** 超时毫秒数；缺省 {@link CLIENT_POLICY_TIMEOUT_MS}。 */
+    timeoutMs?: number;
+}
+/**
+ * 拼策略 URL：`{baseURL}/api/client/policy?platform=&arch=&version=&device_id=`。
+ * 参数固定顺序、逐个 `encodeURIComponent`（device_id 可能是任意 ASCII，含 `+/=` 也必须安全）；
+ * 空值参数直接省略（不产生 `version=` 这样的空参数）；baseURL 尾斜杠归一。
+ * @returns 完整 URL；缺 baseURL 时 undefined（调用方据此跳过请求）。
+ */
+export declare function buildClientPolicyURL(opts: FetchClientPolicyOptions): string | undefined;
+/**
+ * 拉取并解析客户端策略。**永不抛异常**：任何失败都返回 undefined（fail-open）。
+ *
+ * 不记录响应原文——策略接口当前无敏感字段，但保持与其他网关调用一致的日志纪律。
+ */
+export declare function fetchClientPolicy(opts: FetchClientPolicyOptions): Promise<ClientPolicy | undefined>;