hiwork-core 0.0.2 → 0.0.6

package/lib/types/usage-rpc.d.ts

@@ -0,0 +1,196 @@
+/**
+ * `/hiwork-usage` loopback RPC 的 Host 实现（设置页「用量与成本」的唯一取数口）。
+ *
+ * 设计要点（与 hiwork-automation 的 `src/rpc.ts` 同构）：
+ *  - 只注册一个 channel，endpoint 白名单在 {@link USAGE_RPC_ENDPOINTS}，未知 endpoint
+ *    直接 `bad-request`；
+ *  - payload 只允许 `{ keyId?, range? }`，任何其它字段 / 非法 range 一律 `bad-request`；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方只拿到端点原始响应，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - 网关 `GatewayError` 的稳定 code 原样透传，但 message 先经
+ *    {@link displayGatewayMessage} 消毒——baseURL / HTTP 状态码这类实现细节不进 UI
+ *    （沿用 `src/client/login-gate.tsx` 的既有处理思路）；
+ *  - 其余异常收敛为通用失败（code `internal`），Host 只记日志、不把堆栈或原始消息
+ *    交给客户端。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link UsageRpcContext} 端口，
+ * 便于单测直接伪造。
+ */
+import { type GatewayCostEstimateItem, type GatewayCostEstimateReason, type GatewayCostEstimateResponse, type GatewayCostEstimateResult, type GatewayKey, type GatewayKeyResponse, type GatewayModelTrendsResponse, type GatewayRecharge, type GatewaySummaryResponse, type GatewayTrendsResponse, type GatewayUsageRange } from './ai-router-client.ts';
+/** RPC 频道；必须与 client 半边 `src/client/usage-data.ts` 的 `USAGE_CHANNEL` 一致（由测试锁定）。 */
+export declare const USAGE_RPC_CHANNEL = "/hiwork-usage";
+/**
+ * 端点白名单。
+ *
+ * 前五项是 spec / plan 约定的端点；`key` 是**追加项**——KPI 的「剩余预算」只能取
+ * 网关权威的 `/api/me/key` budgets（`/api/me/keys` 是轻量列表、不含任何额度字段）；
+ * `estimate` 是阶段 2 的逐轮计价端点（Task B3），见 {@link handleEstimateEndpoint}。
+ */
+export declare const USAGE_RPC_ENDPOINTS: readonly ["summary", "trends", "model-trends", "recharges", "keys", "key", "estimate"];
+export type UsageRpcEndpoint = (typeof USAGE_RPC_ENDPOINTS)[number];
+/**
+ * 网关支持的用量时间窗口（与 `GatewayUsageRange` 同源，避免客户端伪造值）。
+ * `mtd`（本月 1 日 → 现在）需要网关侧支持；旧网关会按缺省回退成 `24h` 并在响应
+ * 的 `range` 里回填 `24h`，客户端据此判定「本月 KPI 不可用」。
+ */
+export declare const USAGE_RPC_RANGES: readonly GatewayUsageRange[];
+/** 端点入参：只允许 Key 与时间窗口，range 缺省由网关决定。 */
+export interface UsageRpcPayload {
+    keyId?: string | undefined;
+    range?: GatewayUsageRange | undefined;
+}
+/** 客户端可安全展示的失败。 */
+export interface UsageRpcFailure {
+    code: string;
+    message: string;
+    /** DSH Connection 信封要求 `details` 是对象；协议层没有额外细节时补空对象。 */
+    details: object;
+}
+/**
+ * `estimate` 端点的入参项：**线路名**（DSH `routes[].provider`）+ 模型 + 四个 token 桶。
+ *
+ * 线路名→协议名的翻译在 Host 侧（{@link routeToProtocol}）完成；token 桶是 DSH 原生
+ * 排他语义（`input_tokens` 不含 cache），折算成网关 `prompt_tokens` 由网关负责。
+ */
+export interface UsageEstimateItem {
+    /** DSH 线路名（`ai-router-chat` / `ai-router-anthropic` / `ai-router`）。 */
+    route: string;
+    model: string;
+    /** 不含 cache 的输入 token。 */
+    input_tokens: number;
+    output_tokens: number;
+    /** 缺省视同 0（DSH 未能对全部尝试给出该桶时缺省）。 */
+    cache_read_tokens?: number;
+    cache_write_tokens?: number;
+    /** 计价时刻（RFC3339）；缺省由网关取 now。 */
+    at?: string;
+}
+/** `estimate` 端点的响应：整轮汇总后的**单个**金额（客户端不做求和）。 */
+export interface UsageEstimateResult {
+    /** 已计价项之和；`priced:false` 时为 0（调用方不得展示该值）。 */
+    cost: number;
+    /** 全部项都已计价且金额可信。任一项不可计价 → false。 */
+    priced: boolean;
+    /** 所有已计价项的 `channel_resolved` 逻辑与；`priced:false` 时为 false。 */
+    channelResolved: boolean;
+    /** `priced:false` 时的原因（可展示与否由客户端决定）。 */
+    reason?: UsageEstimateReason | undefined;
+}
+/**
+ * `priced:false` 的原因。
+ *
+ * 前五项是 Host 侧自己产生的降级原因（都不抛异常、都不是错误信封）；后三项直接来自
+ * 网关单项结果（{@link GatewayCostEstimateReason}）。
+ */
+export type UsageEstimateReason = 'no_session' | 'no_route' | 'too_many_items' | 'incomplete' | 'invalid_cost' | 'unpriced' | GatewayCostEstimateReason;
+/** 网关契约的单批上限（spec §6.2「items 最多 50 项」）。 */
+export declare const USAGE_ESTIMATE_MAX_ITEMS = 50;
+/** 端点结果信封（与 DSH Connection 的 `ConnectionRpcResult` 同形）。 */
+export type UsageRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: UsageRpcFailure;
+};
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export declare class UsageRequestError extends Error {
+    readonly code: 'bad-request';
+    constructor(code: 'bad-request', message: string);
+}
+/** Host 侧 RPC 依赖的最小上下文（结构兼容 cordis Context，便于单测伪造）。 */
+export interface UsageRpcConnection {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+            authority: 'loopback';
+        }): () => Promise<void> | void;
+    };
+}
+export interface UsageRpcContext {
+    readonly connection: UsageRpcConnection;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * 网关客户端的用量子集：只声明本频道真正调用的方法（结构兼容 `GatewayClient`），
+ * 单测因此不需要伪造整个客户端。
+ */
+export interface UsageGatewayPort {
+    getMySummary(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewaySummaryResponse>;
+    getMyTrends(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewayTrendsResponse>;
+    getMyModelTrends(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewayModelTrendsResponse>;
+    getMyKeyRecharges(sessionCookie: string, keyId?: string, modelName?: string): Promise<GatewayRecharge[]>;
+    getMyKeys(sessionCookie: string): Promise<GatewayKey[]>;
+    getMyKey(sessionCookie: string, keyId?: string): Promise<GatewayKeyResponse>;
+    /** 网关权威计价（`route` 已是协议名）；只回金额与生效单价。 */
+    estimateCost(sessionCookie: string, items: GatewayCostEstimateItem[]): Promise<GatewayCostEstimateResponse>;
+}
+/** Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关客户端。 */
+export interface UsageRpcDeps {
+    /**
+     * 解析网关会话 cookie（`AI_ROUTER_SESSION`）。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用，绝不出现在 RPC 响应里。**
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关客户端；baseURL 未配置时返回 undefined。 */
+    gateway(): UsageGatewayPort | undefined;
+    /** Host 日志出口（只记事件与错误类型，不记会话值）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 通用失败文案：不暴露任何网关细节。 */
+export declare const USAGE_GENERIC_FAILURE_MESSAGE = "\u7528\u91CF\u6570\u636E\u6682\u65F6\u65E0\u6CD5\u83B7\u53D6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/** 未登录 / 会话失效的统一文案（与登录弹窗的 `SESSION_EXPIRED` 口径一致）。 */
+export declare const USAGE_SESSION_EXPIRED_MESSAGE = "\u767B\u5F55\u72B6\u6001\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55";
+/**
+ * 网关 message 消毒：含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，
+ * 其余（网关自己写好的中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export declare function displayGatewayMessage(code: string, message: unknown): string;
+/** payload 校验：只放行 `{ keyId?, range? }`，其余字段 / 非法值一律 `bad-request`。 */
+export declare function parseUsagePayload(raw: unknown): UsageRpcPayload;
+/** 是否为白名单端点。 */
+export declare function isUsageRpcEndpoint(endpoint: string): endpoint is UsageRpcEndpoint;
+/**
+ * `estimate` 端点 payload 校验：只放行 `{ items: [...] }`，形状非法一律 `bad-request`。
+ *
+ * **不在这里做数量上限**：条数取决于会话里出现的 (线路, 模型) 组合（数据），不是协议形状；
+ * 超限在 {@link handleEstimateEndpoint} 里降级为 `priced:false`（reason `too_many_items`），
+ * 免得把「本轮金额看不到」变成一条错误。
+ */
+export declare function parseEstimatePayload(raw: unknown): UsageEstimateItem[];
+/**
+ * 严格 RFC3339 校验（与网关 `time.Parse(time.RFC3339, ...)` 对齐）：
+ * `YYYY-MM-DDThh:mm:ss[.fff](Z|±hh:mm)`，且各字段必须在真实取值范围内。
+ *
+ * **不能只靠 `Date.parse`**：Node 接受 `2026/09/10 03:16`、`Sep 10, 2026` 这类宽松格式
+ * （网关一律 400）；而且 V8 会把 `2026-02-31T00:00:00Z` **滚动**成 3 月 3 日而不是报错，
+ * 所以日历合法性必须自己算。放过去任何一条就是整批金额消失。
+ * @param value - 客户端下发的 `at`。
+ * @returns 是否为网关可接受的 RFC3339 时间。
+ */
+export declare function isRfc3339(value: string): boolean;
+/**
+ * 汇总网关逐项结果（Host 侧求和，客户端零算术）。
+ *
+ * 语义：
+ *  - 任一项 `priced:false` → 整体 `priced:false`（金额不可信，客户端不得显示）；
+ *  - `channelResolved` = 所有已计价项 `channel_resolved` 的**逻辑与**；
+ *  - `cost` = 已计价项之和；
+ *  - 返回条数与请求条数不一致 → `incomplete`（宁可不出金额，也不出一个少算的金额）；
+ *  - 金额非有限数 / 负数 → `invalid_cost`。
+ */
+export declare function summarizeEstimate(results: readonly GatewayCostEstimateResult[], expected: number): UsageEstimateResult;
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ *
+ * `estimate` 走独立分支（{@link handleEstimateEndpoint}）：它自带降级语义
+ * （无会话 / 无可用线路 → 成功信封里的 `priced:false`），且**不走** `callEndpoint`
+ * 的「原样透传网关响应」路径——金额必须在 Host 侧汇总。
+ */
+export declare function handleUsageEndpoint(endpoint: string, rawPayload: unknown, deps: UsageRpcDeps, signal?: AbortSignal): Promise<UsageRpcResult<unknown>>;
+/**
+ * 注册 `/hiwork-usage` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export declare function registerUsageRpc(ctx: UsageRpcContext, deps: UsageRpcDeps): () => Promise<void>;

package/lib/usage-rpc.js

@@ -0,0 +1,386 @@
+/**
+ * `/hiwork-usage` loopback RPC 的 Host 实现（设置页「用量与成本」的唯一取数口）。
+ *
+ * 设计要点（与 hiwork-automation 的 `src/rpc.ts` 同构）：
+ *  - 只注册一个 channel，endpoint 白名单在 {@link USAGE_RPC_ENDPOINTS}，未知 endpoint
+ *    直接 `bad-request`；
+ *  - payload 只允许 `{ keyId?, range? }`，任何其它字段 / 非法 range 一律 `bad-request`；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方只拿到端点原始响应，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - 网关 `GatewayError` 的稳定 code 原样透传，但 message 先经
+ *    {@link displayGatewayMessage} 消毒——baseURL / HTTP 状态码这类实现细节不进 UI
+ *    （沿用 `src/client/login-gate.tsx` 的既有处理思路）；
+ *  - 其余异常收敛为通用失败（code `internal`），Host 只记日志、不把堆栈或原始消息
+ *    交给客户端。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link UsageRpcContext} 端口，
+ * 便于单测直接伪造。
+ */
+import { GatewayError, } from "./ai-router-client.js";
+import { routeToProtocol } from "./provision.js";
+/** RPC 频道；必须与 client 半边 `src/client/usage-data.ts` 的 `USAGE_CHANNEL` 一致（由测试锁定）。 */
+export const USAGE_RPC_CHANNEL = '/hiwork-usage';
+/**
+ * 端点白名单。
+ *
+ * 前五项是 spec / plan 约定的端点；`key` 是**追加项**——KPI 的「剩余预算」只能取
+ * 网关权威的 `/api/me/key` budgets（`/api/me/keys` 是轻量列表、不含任何额度字段）；
+ * `estimate` 是阶段 2 的逐轮计价端点（Task B3），见 {@link handleEstimateEndpoint}。
+ */
+export const USAGE_RPC_ENDPOINTS = ['summary', 'trends', 'model-trends', 'recharges', 'keys', 'key', 'estimate'];
+/**
+ * 网关支持的用量时间窗口（与 `GatewayUsageRange` 同源，避免客户端伪造值）。
+ * `mtd`（本月 1 日 → 现在）需要网关侧支持；旧网关会按缺省回退成 `24h` 并在响应
+ * 的 `range` 里回填 `24h`，客户端据此判定「本月 KPI 不可用」。
+ */
+export const USAGE_RPC_RANGES = ['today', 'yesterday', '24h', '7d', '30d', 'mtd'];
+/** 网关契约的单批上限（spec §6.2「items 最多 50 项」）。 */
+export const USAGE_ESTIMATE_MAX_ITEMS = 50;
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export class UsageRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'UsageRequestError';
+    }
+}
+/** 各稳定错误码的用户可见文案（网关 message 含实现细节时用它兜底）。 */
+const GATEWAY_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: '登录状态已过期，请重新登录',
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    NO_KEY_ASSIGNED: '当前账号尚未被分配虚拟 KEY，请联系管理员',
+    KEY_INVALID: '所选 KEY 无效或已被删除，请重新选择 KEY',
+    RATE_LIMITED: '请求过于频繁，请稍后再试',
+    NOT_FOUND: '网关未找到对应的数据',
+    AUTH_FAILED: '登录状态异常，请重新登录',
+};
+/** 通用失败文案：不暴露任何网关细节。 */
+export const USAGE_GENERIC_FAILURE_MESSAGE = '用量数据暂时无法获取，请稍后重试';
+/** 未登录 / 会话失效的统一文案（与登录弹窗的 `SESSION_EXPIRED` 口径一致）。 */
+export const USAGE_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+/**
+ * 网关 message 消毒：含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，
+ * 其余（网关自己写好的中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export function displayGatewayMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return GATEWAY_MESSAGE_FALLBACK[code] ?? USAGE_GENERIC_FAILURE_MESSAGE;
+    const leaksImplementationDetail = /https?:\/\//i.test(text)
+        || /\bHTTP\s*\d{3}\b/i.test(text)
+        || /\bbaseURL\b/i.test(text);
+    if (leaksImplementationDetail)
+        return GATEWAY_MESSAGE_FALLBACK[code] ?? USAGE_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+/** payload 校验：只放行 `{ keyId?, range? }`，其余字段 / 非法值一律 `bad-request`。 */
+export function parseUsagePayload(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new UsageRequestError('bad-request', '用量请求参数不合法。');
+    }
+    const record = raw;
+    for (const key of Object.keys(record)) {
+        if (key !== 'keyId' && key !== 'range') {
+            throw new UsageRequestError('bad-request', `用量请求包含未知字段 '${key}'。`);
+        }
+    }
+    const payload = {};
+    const rawKeyId = record['keyId'];
+    if (rawKeyId !== undefined) {
+        if (typeof rawKeyId !== 'string')
+            throw new UsageRequestError('bad-request', '用量请求的 keyId 必须是字符串。');
+        const keyId = rawKeyId.trim();
+        if (keyId !== '')
+            payload.keyId = keyId;
+    }
+    const rawRange = record['range'];
+    if (rawRange !== undefined) {
+        if (typeof rawRange !== 'string' || !USAGE_RPC_RANGES.includes(rawRange)) {
+            throw new UsageRequestError('bad-request', `用量请求的 range 不合法（可用值：${USAGE_RPC_RANGES.join(' / ')}）。`);
+        }
+        payload.range = rawRange;
+    }
+    return payload;
+}
+/** 是否为白名单端点。 */
+export function isUsageRpcEndpoint(endpoint) {
+    return USAGE_RPC_ENDPOINTS.includes(endpoint);
+}
+/** `estimate` 入参项允许的字段（其余一律 `bad-request`）。 */
+const ESTIMATE_ITEM_KEYS = [
+    'route', 'model', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'at',
+];
+/**
+ * `estimate` 端点 payload 校验：只放行 `{ items: [...] }`，形状非法一律 `bad-request`。
+ *
+ * **不在这里做数量上限**：条数取决于会话里出现的 (线路, 模型) 组合（数据），不是协议形状；
+ * 超限在 {@link handleEstimateEndpoint} 里降级为 `priced:false`（reason `too_many_items`），
+ * 免得把「本轮金额看不到」变成一条错误。
+ */
+export function parseEstimatePayload(raw) {
+    if (raw === undefined || raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new UsageRequestError('bad-request', '计价请求参数不合法。');
+    }
+    const record = raw;
+    for (const key of Object.keys(record)) {
+        if (key !== 'items')
+            throw new UsageRequestError('bad-request', `计价请求包含未知字段 '${key}'。`);
+    }
+    const rawItems = record['items'];
+    if (!Array.isArray(rawItems))
+        throw new UsageRequestError('bad-request', '计价请求的 items 必须是数组。');
+    if (rawItems.length === 0)
+        throw new UsageRequestError('bad-request', '计价请求的 items 不能为空。');
+    return rawItems.map((item, index) => parseEstimateItem(item, index));
+}
+/** 单项校验：必填 `route` / `model` / `input_tokens` / `output_tokens`，token 必须是非负整数。 */
+function parseEstimateItem(raw, index) {
+    const position = index + 1;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new UsageRequestError('bad-request', `计价请求第 ${position} 项必须是对象。`);
+    }
+    const record = raw;
+    for (const key of Object.keys(record)) {
+        if (!ESTIMATE_ITEM_KEYS.includes(key)) {
+            throw new UsageRequestError('bad-request', `计价请求第 ${position} 项包含未知字段 '${key}'。`);
+        }
+    }
+    const item = {
+        route: requiredText(record['route'], position, 'route'),
+        model: requiredText(record['model'], position, 'model'),
+        input_tokens: tokenCount(record['input_tokens'], position, 'input_tokens'),
+        output_tokens: tokenCount(record['output_tokens'], position, 'output_tokens'),
+    };
+    const cacheRead = optionalTokenCount(record['cache_read_tokens'], position, 'cache_read_tokens');
+    if (cacheRead !== undefined)
+        item.cache_read_tokens = cacheRead;
+    const cacheWrite = optionalTokenCount(record['cache_write_tokens'], position, 'cache_write_tokens');
+    if (cacheWrite !== undefined)
+        item.cache_write_tokens = cacheWrite;
+    const at = record['at'];
+    if (at !== undefined) {
+        if (typeof at !== 'string' || !isRfc3339(at)) {
+            throw new UsageRequestError('bad-request', `计价请求第 ${position} 项的 at 必须是 RFC3339 时间。`);
+        }
+        item.at = at;
+    }
+    return item;
+}
+/**
+ * 严格 RFC3339 校验（与网关 `time.Parse(time.RFC3339, ...)` 对齐）：
+ * `YYYY-MM-DDThh:mm:ss[.fff](Z|±hh:mm)`，且各字段必须在真实取值范围内。
+ *
+ * **不能只靠 `Date.parse`**：Node 接受 `2026/09/10 03:16`、`Sep 10, 2026` 这类宽松格式
+ * （网关一律 400）；而且 V8 会把 `2026-02-31T00:00:00Z` **滚动**成 3 月 3 日而不是报错，
+ * 所以日历合法性必须自己算。放过去任何一条就是整批金额消失。
+ * @param value - 客户端下发的 `at`。
+ * @returns 是否为网关可接受的 RFC3339 时间。
+ */
+export function isRfc3339(value) {
+    const match = RFC3339_PATTERN.exec(value);
+    if (match === null)
+        return false;
+    const field = (index) => Number(match[index] ?? Number.NaN);
+    const year = field(1);
+    const month = field(2);
+    const day = field(3);
+    const hour = field(4);
+    const minute = field(5);
+    const second = field(6);
+    if (![year, month, day, hour, minute, second].every((part) => Number.isInteger(part)))
+        return false;
+    if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month))
+        return false;
+    if (hour > 23 || minute > 59 || second > 59)
+        return false;
+    // 偏移量只在非 Z 时出现；Go 同样拒绝超出 ±23:59 的偏移。
+    if (match[7] !== undefined) {
+        const offsetHour = field(8);
+        const offsetMinute = field(9);
+        if (!Number.isInteger(offsetHour) || !Number.isInteger(offsetMinute))
+            return false;
+        if (offsetHour > 23 || offsetMinute > 59)
+            return false;
+    }
+    return true;
+}
+/** 严格 RFC3339 形状（大小写敏感：Go 的 `time.RFC3339` 只认大写 `T` / `Z`）。 */
+const RFC3339_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/;
+/** 该年该月的天数（不用 `Date`：它对 0–99 年有 1900 偏移）。 */
+function daysInMonth(year, month) {
+    if (month === 2)
+        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+    return [31, 0, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
+}
+function requiredText(value, position, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new UsageRequestError('bad-request', `计价请求第 ${position} 项的 ${field} 不能为空。`);
+    }
+    return value.trim();
+}
+function tokenCount(value, position, field) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new UsageRequestError('bad-request', `计价请求第 ${position} 项的 ${field} 必须是非负整数。`);
+    }
+    return value;
+}
+function optionalTokenCount(value, position, field) {
+    return value === undefined ? undefined : tokenCount(value, position, field);
+}
+/** 未计价的统一结果（金额恒为 0，调用方**不得**展示）。 */
+function unpriced(reason) {
+    return { cost: 0, priced: false, channelResolved: false, reason };
+}
+/**
+ * 汇总网关逐项结果（Host 侧求和，客户端零算术）。
+ *
+ * 语义：
+ *  - 任一项 `priced:false` → 整体 `priced:false`（金额不可信，客户端不得显示）；
+ *  - `channelResolved` = 所有已计价项 `channel_resolved` 的**逻辑与**；
+ *  - `cost` = 已计价项之和；
+ *  - 返回条数与请求条数不一致 → `incomplete`（宁可不出金额，也不出一个少算的金额）；
+ *  - 金额非有限数 / 负数 → `invalid_cost`。
+ */
+export function summarizeEstimate(results, expected) {
+    if (results.length !== expected)
+        return unpriced('incomplete');
+    let cost = 0;
+    let channelResolved = true;
+    for (const result of results) {
+        if (result?.priced !== true)
+            return unpriced(result?.reason ?? 'unpriced');
+        const value = result.cost;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+            return unpriced('invalid_cost');
+        cost += value;
+        if (result.channel_resolved !== true)
+            channelResolved = false;
+    }
+    return { cost, priced: true, channelResolved };
+}
+/**
+ * `estimate` 端点：逐轮计价并汇总，**永不抛异常**（异常由调用方的信封统一收敛）。
+ *
+ * 流程（Task B3）：
+ *  1. 无会话 → `{priced:false, reason:'no_session'}`（成功信封，不是错误）；
+ *  2. 逐项 `routeToProtocol(route)`，未知 / 遗留线路（`ai-router-responses`）**丢弃**该轮；
+ *     全部被丢弃 → `{priced:false, reason:'no_route'}`；
+ *  3. 条数超过网关契约（≤50）→ `{priced:false, reason:'too_many_items'}`；
+ *  4. 调网关 `estimateCost`，Host 侧用 {@link summarizeEstimate} 求和后返回单值。
+ */
+async function handleEstimateEndpoint(items, deps, signal) {
+    const sessionCookie = await deps.resolveSession();
+    if (sessionCookie === undefined || sessionCookie === '')
+        return { ok: true, value: unpriced('no_session') };
+    if (isAborted(signal))
+        return failure('cancelled', '用量请求已取消。');
+    if (items.length > USAGE_ESTIMATE_MAX_ITEMS)
+        return { ok: true, value: unpriced('too_many_items') };
+    const gatewayItems = [];
+    for (const item of items) {
+        const protocol = routeToProtocol(item.route);
+        if (protocol === undefined)
+            continue;
+        gatewayItems.push({
+            route: protocol,
+            model: item.model,
+            input_tokens: item.input_tokens,
+            output_tokens: item.output_tokens,
+            ...(item.cache_read_tokens === undefined ? {} : { cache_read_tokens: item.cache_read_tokens }),
+            ...(item.cache_write_tokens === undefined ? {} : { cache_write_tokens: item.cache_write_tokens }),
+            ...(item.at === undefined ? {} : { at: item.at }),
+        });
+    }
+    if (gatewayItems.length === 0)
+        return { ok: true, value: unpriced('no_route') };
+    const gateway = deps.gateway();
+    if (gateway === undefined) {
+        return failure('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+    }
+    if (isAborted(signal))
+        return failure('cancelled', '用量请求已取消。');
+    const response = await gateway.estimateCost(sessionCookie, gatewayItems);
+    const results = response?.items;
+    if (!Array.isArray(results)) {
+        deps.log?.("hiwork-core: 计价 RPC 收到无效响应（items 不是数组）");
+        return failure('internal', USAGE_GENERIC_FAILURE_MESSAGE);
+    }
+    return { ok: true, value: summarizeEstimate(results, gatewayItems.length) };
+}
+/** 取消判定（用函数包一层，避免 TS 把属性窄化固化到 `await` 之后）。 */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ *
+ * `estimate` 走独立分支（{@link handleEstimateEndpoint}）：它自带降级语义
+ * （无会话 / 无可用线路 → 成功信封里的 `priced:false`），且**不走** `callEndpoint`
+ * 的「原样透传网关响应」路径——金额必须在 Host 侧汇总。
+ */
+export async function handleUsageEndpoint(endpoint, rawPayload, deps, signal) {
+    try {
+        if (isAborted(signal))
+            return failure('cancelled', '用量请求已取消。');
+        if (!isUsageRpcEndpoint(endpoint)) {
+            throw new UsageRequestError('bad-request', `未知的用量端点 '${endpoint}'`);
+        }
+        if (endpoint === 'estimate')
+            return await handleEstimateEndpoint(parseEstimatePayload(rawPayload), deps, signal);
+        const payload = parseUsagePayload(rawPayload);
+        const sessionCookie = await deps.resolveSession();
+        if (sessionCookie === undefined || sessionCookie === '') {
+            return failure('SESSION_EXPIRED', USAGE_SESSION_EXPIRED_MESSAGE);
+        }
+        const gateway = deps.gateway();
+        if (gateway === undefined) {
+            return failure('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+        }
+        if (isAborted(signal))
+            return failure('cancelled', '用量请求已取消。');
+        const value = await callEndpoint(gateway, sessionCookie, endpoint, payload);
+        return { ok: true, value };
+    }
+    catch (error) {
+        if (error instanceof UsageRequestError)
+            return failure(error.code, error.message);
+        if (error instanceof GatewayError) {
+            // code 原样透传（稳定契约），message 消毒后再给客户端。
+            return failure(error.code, displayGatewayMessage(error.code, error.message));
+        }
+        deps.log?.(`hiwork-core: 用量 RPC '${endpoint}' 失败（${error instanceof Error ? error.name : typeof error}）`);
+        return failure('internal', USAGE_GENERIC_FAILURE_MESSAGE);
+    }
+}
+/** 单端点转发：返回网关原始响应，**不做任何字段重包装**（`estimate` 不走这里）。 */
+async function callEndpoint(gateway, sessionCookie, endpoint, payload) {
+    switch (endpoint) {
+        case 'summary':
+            return await gateway.getMySummary(sessionCookie, payload.keyId, payload.range);
+        case 'trends':
+            return await gateway.getMyTrends(sessionCookie, payload.keyId, payload.range);
+        case 'model-trends':
+            return await gateway.getMyModelTrends(sessionCookie, payload.keyId, payload.range);
+        case 'recharges':
+            return await gateway.getMyKeyRecharges(sessionCookie, payload.keyId);
+        case 'keys':
+            return await gateway.getMyKeys(sessionCookie);
+        case 'key':
+            return await gateway.getMyKey(sessionCookie, payload.keyId);
+    }
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * 注册 `/hiwork-usage` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export function registerUsageRpc(ctx, deps) {
+    const handler = (endpoint, payload, signal) => handleUsageEndpoint(endpoint, payload, deps, signal);
+    const remove = ctx.connection.rpc.handle(USAGE_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => { await remove(); };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiwork-core",
-  "version": "0.0.2",
+  "version": "0.0.6",
   "type": "module",
   "description": "HiWork 企业统一登录与模型自动供给插件（ai-router 网关登录，Web 表单，无 CLI 认证）",
   "license": "UNLICENSED",
@@ -33,7 +33,8 @@
         "@deepseek-ai/dsh-client-ui-slots",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-api-remotes",
-        "@deepseek-ai/dsh-client-ui-primitives"
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-chat"
       ]
     }
   },
@@ -44,8 +45,11 @@
     "@deepseek-ai/cordis": "4.0.2",
     "@deepseek-ai/dsh-api-remotes": "0.1.2-rc.1",
     "@deepseek-ai/dsh-client-store": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-session": "0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-settings": "0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-sidebar": "0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1",