hiwork-core 0.0.2 → 0.0.6

package/lib/types/ai-router-client.d.ts

@@ -1,4 +1,4 @@
-import type { LoginErrorCode } from './types.ts';
+import type { DeviceSession, LoginErrorCode } from './types.ts';
 /** 网关错误：携带稳定 code，供编排层映射。 */
 export declare class GatewayError extends Error {
     readonly code: LoginErrorCode;
@@ -10,6 +10,16 @@ export interface GatewayUser {
     username: string;
     display_name?: string;
 }
+/**
+ * 客户端设备身份：表单登录按 `X-HiWork-*` 头上报（网关 Task A8 落库到 sessions 表），
+ * 浏览器授权登录则作为授权 URL 的查询参数。`deviceId` 是唯一必需项，其余缺失即不发。
+ */
+export interface DeviceIdentity {
+    deviceId: string;
+    deviceName?: string;
+    platform?: string;
+    appVersion?: string;
+}
 /** GET /api/me/key 的 budgets 项（含额度字段，可选因网关可能缺省）。 */
 export interface GatewayBudget {
     model_name: string;
@@ -56,31 +66,273 @@ export interface GatewayKey {
     max_concurrency?: number;
     key_masked?: string;
 }
+/**
+ * 用量统计的时间窗口。缺省（不传）时由网关按 `24h` 处理；`today`/`yesterday`/`mtd`
+ * 按自然边界切分（`mtd` = 本月 1 日 00:00 → 现在），网关自行决定聚合粒度
+ * （`group_by` 随响应返回）。
+ *
+ * 注意：`mtd` 需要网关侧支持（`meRange` 的 `case "mtd"`）；旧网关不认该值时按缺省
+ * 回退成 `24h` 并在响应 `range` 里回填 `24h`——调用方必须用响应的 `range` 自证
+ * （见 `src/client/usage-data.ts` 的旧网关守卫），不得拿 24 小时的数字冒充本月。
+ */
+export type GatewayUsageRange = 'today' | 'yesterday' | '24h' | '7d' | '30d' | 'mtd';
+/** GET /api/me/analytics/summary 的按模型汇总项（网关 KeyModelSummaryStat）。 */
+export interface GatewayModelSummary {
+    model: string;
+    request_count: number;
+    total_tokens: number;
+    total_cost: number;
+    cache_hit_rate: number;
+}
+/** GET /api/me/analytics/summary 响应。 */
+export interface GatewaySummaryResponse {
+    /** 网关实际生效的时间窗口（请求未指定时网关回填）。 */
+    range: string;
+    items: GatewayModelSummary[];
+}
+/** 趋势点（GET /api/me/analytics/trends 的 trends 项）。 */
+export interface GatewayTrendPoint {
+    /** 桶起点，RFC3339。 */
+    period: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    request_count: number;
+    total_cost: number;
+}
+/** GET /api/me/analytics/trends 响应。 */
+export interface GatewayTrendsResponse {
+    range: string;
+    /** 聚合粒度：`hour` | `day`（由网关按 range 决定）。 */
+    group_by: string;
+    trends: GatewayTrendPoint[];
+}
+/** 趋势点的子拆分（model-trends 按模型拆分时出现）。 */
+export interface GatewayTrendBreakdown {
+    name: string;
+    total_tokens: number;
+    request_count: number;
+    total_cost: number;
+}
+/** 按模型拆分的趋势点：在趋势点基础上多一层 breakdown。 */
+export interface GatewayModelTrendPoint extends GatewayTrendPoint {
+    breakdown?: GatewayTrendBreakdown[];
+}
+/** GET /api/me/analytics/model-trends 响应。 */
+export interface GatewayModelTrendsResponse {
+    range: string;
+    group_by: string;
+    trends: GatewayModelTrendPoint[];
+}
+/** GET /api/me/key/recharges 的一项（网关 models.RechargeRecord 的 JSON 投影）。 */
+export interface GatewayRecharge {
+    id: string;
+    virtual_key_id: string;
+    model_name: string;
+    /** 充值金额（元）。 */
+    amount: number;
+    /** 充值类型（网关自定义枚举，如 manual / auto_rule）。 */
+    type: string;
+    operator: string;
+    note: string;
+    /** 自动充值来源规则 id；非自动充值为 null。 */
+    rule_id?: string | null;
+    created_at: string;
+}
+/**
+ * POST /api/me/cost-estimate 的请求项。
+ * `input_tokens` 是**不含 cache** 的输入 token（与 DSH `uncachedInputTokens` 同口径），
+ * 折算成网关计费口径的 `prompt_tokens` 只在网关侧做——客户端不做任何算术。
+ */
+export interface GatewayCostEstimateItem {
+    /** 网关协议名（openai_chat_completions / anthropic_messages / openai_responses，见 spec §6.2 词汇表）。 */
+    route: string;
+    /** 客户端请求的模型名（source_model）。 */
+    model: string;
+    /** 不含 cache 的输入 token。 */
+    input_tokens: number;
+    output_tokens: number;
+    /** 缺省视同 0。 */
+    cache_read_tokens?: number;
+    /** 缺省视同 0。 */
+    cache_write_tokens?: number;
+    /** 计价时刻（RFC3339）；缺省由网关取 now。 */
+    at?: string;
+}
+/** 未计价原因（`priced: false` 时出现）。 */
+export type GatewayCostEstimateReason = 'model_not_available' | 'no_channel' | 'price_not_found';
+/** 本次实际生效的单价（网关只回这一条渠道价，不回价格表）。 */
+export interface GatewayCostEstimatePrice {
+    input: number;
+    output: number;
+    cache: number;
+    cache_write: number;
+}
+/** POST /api/me/cost-estimate 的响应项。单项失败不影响整批（整体仍 200）。 */
+export interface GatewayCostEstimateResult {
+    route: string;
+    model: string;
+    /** 未计价时为 0。 */
+    cost: number;
+    channel: string;
+    /** 候选渠道 ≥2 时按近 30 天流量加权，为 false（UI 需标注「估算」）。 */
+    channel_resolved: boolean;
+    price?: GatewayCostEstimatePrice;
+    priced_at?: string;
+    priced: boolean;
+    reason?: GatewayCostEstimateReason;
+}
+/** POST /api/me/cost-estimate 响应。 */
+export interface GatewayCostEstimateResponse {
+    items: GatewayCostEstimateResult[];
+    total_cost: number;
+}
+/** GET /api/me/daily-quote 的条目（可选字段网关 omitempty；body 为弹窗正文段落）。 */
+export interface GatewayDailyQuoteItem {
+    id: number;
+    content: string;
+    subtitle?: string;
+    title?: string;
+    source?: string;
+    body?: string[];
+}
+/**
+ * GET /api/me/daily-quote 响应：`date` 为东八区当日（YYYY-MM-DD，客户端弹窗直接展示），
+ * `poolSize` 为启用池大小；池空时 `item` 为 null。
+ */
+export interface GatewayDailyQuoteResponse {
+    date: string;
+    poolSize: number;
+    item: GatewayDailyQuoteItem | null;
+}
+/** GET /api/me/daily-quote/random 响应：启用池随机条目（池空为 null）。 */
+export interface GatewayDailyQuoteRandomResponse {
+    item: GatewayDailyQuoteItem | null;
+}
 /** 网关客户端端口：orchestration 只依赖此接口。 */
 export interface GatewayClient {
-    login(username: string, password: string): Promise<{
+    /**
+     * 表单登录（loginMode=form 的回退路径）。
+     * `device` 为可选设备信息：已知时随请求上报 `X-HiWork-*` 头（供网关记录登录设备），
+     * 未知则不发——**设备信息缺失绝不能让登录失败**。
+     */
+    login(username: string, password: string, device?: DeviceIdentity): Promise<{
+        sessionCookie: string;
+        user: GatewayUser;
+    }>;
+    /**
+     * 浏览器授权登录：用一次性 code + PKCE verifier 换取会话（返回形状与 login 一致）。
+     * 必选——所有网关客户端都必须实现，调用方无需判空。
+     */
+    exchangeCode(input: {
+        code: string;
+        codeVerifier: string;
+        deviceId: string;
+    }): Promise<{
         sessionCookie: string;
         user: GatewayUser;
     }>;
+    /** 当前账号的登录设备列表。 */
+    listSessions(sessionCookie: string): Promise<DeviceSession[]>;
+    /** 远程吊销指定会话（204 成功；404 表示该会话已不存在）。 */
+    revokeSession(sessionCookie: string, sessionId: string): Promise<void>;
     getMyKey(sessionCookie: string, keyId?: string): Promise<GatewayKeyResponse>;
     getMyKeys(sessionCookie: string): Promise<GatewayKey[]>;
+    /** 按模型聚合的用量汇总（权威账单口径）。 */
+    getMySummary(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewaySummaryResponse>;
+    /** token/费用走势（网关按 range 决定 group_by）。 */
+    getMyTrends(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewayTrendsResponse>;
+    /** 按模型拆分的走势（每点含 breakdown）。 */
+    getMyModelTrends(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewayModelTrendsResponse>;
+    /** 当前 Key 的充值台账（可按模型过滤）。 */
+    getMyKeyRecharges(sessionCookie: string, keyId?: string, modelName?: string): Promise<GatewayRecharge[]>;
+    /** 网关权威计价：只回金额与生效单价，客户端不做任何算式。 */
+    estimateCost(sessionCookie: string, items: GatewayCostEstimateItem[]): Promise<GatewayCostEstimateResponse>;
     logout(sessionCookie: string): Promise<void>;
 }
+/**
+ * 构造浏览器授权页 URL（GET /api/auth/authorize）。
+ * 全部参数按 encodeURIComponent 转义——`redirect_uri` 的 `hiwork://` 必须编码成
+ * `hiwork%3A%2F%2Fauth%2Fcallback`，否则查询串会被网关按 `//` 截断。
+ */
+export declare function buildAuthorizeURL(opts: {
+    baseURL: string;
+    clientId?: string;
+    redirectUri?: string;
+    codeChallenge: string;
+    state: string;
+    deviceId: string;
+    deviceName: string;
+    platform: string;
+    appVersion: string;
+}): string;
 /** fetch + 解析 ai-router HTTP 面。零 dsh 依赖。 */
 export declare class AiRouterClient implements GatewayClient {
     private readonly baseURL;
     private readonly timeoutMs;
     constructor(baseURL: string, timeoutMs?: number);
-    login(username: string, password: string): Promise<{
+    login(username: string, password: string, device?: DeviceIdentity): Promise<{
+        sessionCookie: string;
+        user: GatewayUser;
+    }>;
+    /**
+     * POST /api/auth/token：用一次性 code + PKCE verifier 换取会话。
+     * 返回 `session_id=<sid>`（与 login 同形状，编排层可直接复用），user 原样返回。
+     * 任何日志/异常信息都不得包含 code / code_verifier / session_id 明文。
+     */
+    exchangeCode(input: {
+        code: string;
+        codeVerifier: string;
+        deviceId: string;
+    }): Promise<{
         sessionCookie: string;
         user: GatewayUser;
     }>;
+    /** GET /api/auth/sessions：当前账号的登录设备列表。 */
+    listSessions(sessionCookie: string): Promise<DeviceSession[]>;
+    /** DELETE /api/auth/sessions/:id：远程吊销指定会话（204 成功；404 表示已不存在）。 */
+    revokeSession(sessionCookie: string, sessionId: string): Promise<void>;
     getMyKey(sessionCookie: string, keyId?: string): Promise<GatewayKeyResponse>;
     /** GET /api/me/keys：当前用户全部虚拟 Key 的轻量列表（多 Key 选择器数据源）。 */
     getMyKeys(sessionCookie: string): Promise<GatewayKey[]>;
     logout(sessionCookie: string): Promise<void>;
+    /** GET /api/me/analytics/summary：按模型聚合的用量汇总。 */
+    getMySummary(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewaySummaryResponse>;
+    /** GET /api/me/analytics/trends：token/费用走势。 */
+    getMyTrends(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewayTrendsResponse>;
+    /** GET /api/me/analytics/model-trends：按模型拆分的走势。 */
+    getMyModelTrends(sessionCookie: string, keyId?: string, range?: GatewayUsageRange): Promise<GatewayModelTrendsResponse>;
+    /** GET /api/me/key/recharges：当前 Key 的充值台账（可按模型过滤）。 */
+    getMyKeyRecharges(sessionCookie: string, keyId?: string, modelName?: string): Promise<GatewayRecharge[]>;
+    /** GET /api/me/daily-quote：当日条目（服务端东八区取模轮换，全网同一天同一条）。 */
+    getMyDailyQuote(sessionCookie: string): Promise<GatewayDailyQuoteResponse>;
+    /** GET /api/me/daily-quote/random：换一句（exclude 为当前条目 id；非法值由网关按缺省处理）。 */
+    getMyDailyQuoteRandom(sessionCookie: string, excludeId?: number): Promise<GatewayDailyQuoteRandomResponse>;
+    /**
+     * POST /api/me/cost-estimate：网关权威计价。请求体里的四个 token 桶原样上报，
+     * `input_tokens` 不含 cache；任何折算与单价计算都在网关侧完成。
+     */
+    estimateCost(sessionCookie: string, items: GatewayCostEstimateItem[]): Promise<GatewayCostEstimateResponse>;
+    /**
+     * /api/me 自助端点的 GET 公共路径：网络异常 → GATEWAY_UNREACHABLE，
+     * 401/403/400 映射为稳定 code，响应体非 JSON 时不把原文带进异常。
+     */
+    private getMeJson;
+    /**
+     * 浏览器授权相关端点专用：网络层异常（连接失败 / 超时 / DNS）统一映射为
+     * GATEWAY_UNREACHABLE，避免裸 fetch 错误漏到编排层。
+     * login 等既有方法不经过此处，行为保持不变。
+     */
+    private requestOrUnreachable;
     private request;
 }
+/**
+ * 设备信息 → 请求头。四个字段一律先清洗：
+ * `deviceId` 不可信（见 {@link safeDeviceId}）时一个头都不发；其余字段经
+ * {@link headerSafeValue} 清洗后为空则该头跳过、其余照发。
+ * 任何异常输入都不得让登录失败——本函数总是返回可安全交给 `Headers` 的对象。
+ */
+export declare function deviceHeaders(device?: DeviceIdentity): Record<string, string>;
 /**
  * 从 Set-Cookie 头解析 session_id：遍历全部 Set-Cookie（网关可能先下发 CSRF 等其他 cookie）；
  * 旧运行时回退 get('set-cookie') 时可能拿到逗号合并串，故分隔符同时接受 `,` 与 `;`。

package/lib/types/browser-login.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 浏览器授权登录（`hiwork://` + PKCE）的宿主侧编排：发起与回调兑换。
+ *
+ * 接缝（与 pendingLogin / refreshRequest 同一机制，**不引入新的 RPC 通道**）：
+ * - 客户端写 `browserLoginRequest: { at }` 请求发起浏览器登录；
+ * - 宿主发起后把授权 URL 回写为 `browserLogin: { authorizeUrl, startedAt }` 并清掉
+ *   `browserLoginRequest`，由渲染端（client 半边）负责 `window.open(authorizeUrl)`；
+ * - 桌面端收到 `hiwork://auth/callback` 后经 IPC 调 `completeBrowserLogin({ code, state })`。
+ *
+ * 安全约束（见 spec §5.2）：PKCE S256 是核心防线，state 严格相等才兑换，code 一次性，
+ * 任何日志都不得输出 code / code_verifier / code_challenge / session_id 明文。
+ */
+import { type DeviceIdentity, type GatewayClient } from './ai-router-client.ts';
+import { type AiRouterNamespaceValue, type AiRouterStatePort, type CredentialsPort, type DefaultModelPort, type PiAiPort } from './provision-session.ts';
+import type { LoginError } from './types.ts';
+/** 待完成授权请求的有效期：超过 10 分钟的回调一律拒绝（授权页/一次性 code 早已失效）。 */
+export declare const BROWSER_LOGIN_TTL_MS: number;
+/** 设备 id 在 credentials 里的兜底 ref（桌面端 Task C3 未推来时的本地持久化）。 */
+export declare const DEVICE_ID_REF = "hiwork_device_id";
+/** 缺 baseURL 时写进 lastError 的稳定错误（发起与分发两侧共用同一文案）。 */
+export declare const NO_BASE_URL_ERROR: LoginError;
+/** 发起浏览器登录所需的最小端口。 */
+export interface BrowserLoginStartPorts {
+    credentials: CredentialsPort;
+    state: AiRouterStatePort;
+    value: AiRouterNamespaceValue;
+    /** 时钟注入（测试用）；缺省 Date.now。 */
+    now?: () => number;
+    /** 告警出口；缺省静默。 */
+    log?: (message: string) => void;
+}
+/** 浏览器登录编排的公共端口（发起与回调共用；测试可注入时钟与告警出口）。 */
+export interface BrowserLoginPorts extends BrowserLoginStartPorts {
+    piAi: PiAiPort;
+    /** 供给成功后校正默认模型；可选以便测试直接构造 opts。 */
+    defaultModel?: DefaultModelPort;
+    /** 供给成功后触发（默认工作区 ensure 等）；可选以便测试直接构造 opts。 */
+    ensureWorkspace?: () => Promise<void>;
+}
+/** 发起成功的返回值：授权页 URL 与本次 state（state 仅用于回调校验，不得写日志）。 */
+export interface StartBrowserLoginResult {
+    authorizeUrl: string;
+    state: string;
+}
+/**
+ * 接收桌面端经 IPC 推来的设备信息（Task B3 的 `hiwork:device-info` 调用）。
+ * deviceId 为空/纯空白视为无效并忽略（保留既有缓存）；deviceName / appVersion 可选。
+ * `appVersion` 是**桌面端版本**（网关把它记进会话并在授权页展示），缺失时才回退到插件版本。
+ */
+export declare function setDeviceInfo(info: {
+    deviceId: string;
+    deviceName?: string;
+    appVersion?: string;
+}): void;
+/** 清空模块级状态（IPC 设备缓存 + 待完成授权）；供测试与插件卸载使用。 */
+export declare function resetBrowserLoginState(): void;
+/**
+ * 解析本次登录要上报的设备身份：IPC 推来的值 → credentials 里的 `hiwork_device_id`
+ * → 都没有则生成 UUID 并持久化。**永远返回非空 deviceId**，调用方不必判空。
+ */
+export declare function resolveDeviceInfo(credentials: CredentialsPort): Promise<DeviceIdentity>;
+/**
+ * PKCE S256：`base64url(sha256(verifier))`（RFC 7636 §4.2）。导出以便单测用官方测试向量核对。
+ */
+export declare function pkceChallenge(codeVerifier: string): string;
+/**
+ * 发起浏览器授权登录：生成 PKCE 与 state、暂存 pendingAuth、拼授权 URL 并回写命名空间。
+ * @returns 授权 URL 与 state；缺 baseURL 时写 lastError 并返回 undefined。
+ */
+export declare function startBrowserLogin(opts: BrowserLoginStartPorts): Promise<StartBrowserLoginResult | undefined>;
+/**
+ * 宿主启动时对账持久化的等待态。
+ *
+ * PKCE 的 code_verifier 只活在内存的 `pendingAuth` 里，**不落任何持久化**；而等待态
+ * `browserLogin` 是持久化的。宿主一旦重启（应用重开、DSH 崩溃重启、开发期 HMR），
+ * 两者就永久错位：所有回调都被 `completeBrowserLogin` 的「没有待完成的授权请求」丢弃，
+ * 界面却仍按持久化的 `browserLogin` 停在「等待完成授权」，用户只能靠「取消」脱困。
+ *
+ * 因此启动即把这种**不可能完成**的等待态收尾成失败：写一条 lastError 并清掉等待字段，
+ * 让用户回到登录入口重新发起。没有等待态时不动任何状态。
+ */
+export declare function reconcileStaleBrowserLogin(state: AiRouterStatePort, value: Pick<AiRouterNamespaceValue, 'browserLogin'>): Promise<void>;
+/**
+ * 处理 `hiwork://auth/callback`：校验 state → 兑换一次性 code → 写会话凭据 → 复用供给尾部。
+ *
+ * 一次性语义：state **已匹配**的路径（超时 / error / 缺 code / 兑换失败 / 成功）一律在
+ * finally 里清空 pendingAuth，重复回调只生效一次。
+ *
+ * 安全例外：state 不匹配的回调是**纯丢弃**——它可能来自攻击者伪造，因此不得写状态、不得
+ * 清 pendingAuth、不得触碰凭据（见下方早返回，该路径刻意绕过 finally）。否则一次伪造回调
+ * 就能让随后真实的回调被当成「无待完成授权」而忽略，等于无凭据即可打断用户登录。
+ */
+export declare function completeBrowserLogin(input: {
+    code?: string;
+    state?: string;
+    error?: string;
+}, opts: BrowserLoginPorts & {
+    gateway: GatewayClient;
+}): Promise<LoginError | null>;

package/lib/types/client/account-cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 账号 / Key 身份变化 → 清空用量类缓存。
+ *
+ * 为什么需要它：`UsageDataStore` 与 `SessionCostStore` 的缓存键分别只含
+ * `keyId+range` 与 `sessionId+turn+items`，**不含账号**。同一台机器上换账号（或换 Key）
+ * 后查看**同一个本地会话**，5 分钟 TTL 内会命中上一账号的估算金额——网关的可用模型与
+ * 单价是按 Key 解析的，串号就是错钱。
+ *
+ * 身份来源是 ai-router 设置卡片的状态快照（`controller.inject().hooks.aiRouterCard`）：
+ *  - 登出：Host 的 `runLogout` 会 unset `username` / `keyId`（`src/orchestration.ts`），
+ *    身份摘要随之变化 → 清空；
+ *  - 换账号 / 换 Key：`username` 或 `activeKeyId` 变化 → 清空。
+ *
+ * 本模块不 import 任何 `@deepseek-ai/*` 运行时值，只按结构声明所需的最小面，
+ * 便于单测直接驱动。
+ */
+/** 身份摘要的输入（`AiRouterCardState` 的子集）。 */
+export interface AccountIdentityState {
+    username?: string | undefined;
+    /** 当前生效 Key（显式 keyId，缺省取 keys 第一项）。 */
+    activeKeyId?: string | undefined;
+}
+/** 快照源（结构兼容 `SnapshotStore`，只用到读与订阅）。 */
+export interface AccountIdentitySource {
+    getSnapshot(): AccountIdentityState;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * 身份摘要：账号 + 当前 Key。两者任一变化都意味着「金额的解释口径变了」。
+ * 未登录时两者都是空串——登出（从有值变空）同样会被判为变化。
+ * @param state - 卡片状态子集。
+ * @returns 稳定摘要串。
+ */
+export declare function accountIdentityOf(state: AccountIdentityState): string;
+/**
+ * 订阅身份变化；变化时调一次 `onChange`（不传新值——调用方只需清缓存）。
+ *
+ * 语义：
+ *  - 只比较 {@link accountIdentityOf}，同一身份重复通知不触发；
+ *  - 立即读取一次当前身份作为基线（订阅前已登录的账号不会被当成「变化」）；
+ *  - 返回幂等的取消订阅函数（`ctx.effect` 的清理面）。
+ * @param source - 卡片状态快照源。
+ * @param onChange - 身份变化回调（清空缓存）。
+ * @returns 取消订阅。
+ */
+export declare function observeAccountChange(source: AccountIdentitySource, onChange: () => void): () => void;

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

@@ -15,6 +15,13 @@ export declare const AI_ROUTER_NS = "ai-router";
 export declare const AI_ROUTER_SECTION_LABEL = "\u7F51\u5173\u6A21\u578B";
 /** 登录中临时密码的凭据 ref：与 src/provision.ts 拼写一致。 */
 export declare const PENDING_PASSWORD_REF = "AI_ROUTER_PENDING_PASSWORD";
+/**
+ * 登录方式：由 Host 从 `GET /api/client/policy` 投影（见 spec §5.4）。
+ * - `browser`：浏览器授权登录为主，表单只作为故障回退；
+ * - `both`：浏览器授权为主 + 折叠的账号密码表单（缺省值）；
+ * - `form`：完全回退到表单登录（浏览器流故障时的紧急止血）。
+ */
+export type LoginMode = 'browser' | 'form' | 'both';
 /** 卡片编辑的 ai-router 配置段子集。 */
 export interface AiRouterCardSettings {
     baseURL?: string;
@@ -40,6 +47,17 @@ export interface AiRouterCardSettings {
     lastError?: LoginError;
     budgets?: GatewayBudgetView[];
     keys?: GatewayKeyView[];
+    /** 网关策略下发的登录方式；缺省或非法值一律按 `both`。 */
+    loginMode?: LoginMode;
+    /** 客户端写：请求 Host 发起浏览器授权登录（Host 完成后清掉本字段）。 */
+    browserLoginRequest?: {
+        at: string;
+    };
+    /** Host 回写：待打开的授权页 URL 与发起时间（渲染层据此 `window.open`）。 */
+    browserLogin?: {
+        authorizeUrl: string;
+        startedAt: string;
+    };
 }
 /** 单个模型的额度视图（client 侧结构类型，不 import Host）。 */
 export interface GatewayBudgetView {
@@ -71,6 +89,12 @@ export interface AiRouterCardState {
     keys: GatewayKeyView[] | undefined;
     /** 当前生效 Key：显式 keyId，缺省取 keys 第一项（与网关默认一致）。 */
     activeKeyId: string | undefined;
+    /** 登录方式（投影后永不为 undefined；缺省/非法值归一为 both）。 */
+    loginMode: LoginMode;
+    /** 授权页 URL：有值即等待浏览器授权中。 */
+    browserLoginUrl: string | undefined;
+    /** 是否等待浏览器授权（含请求已发出、URL 未回写的窗口期）。 */
+    browserLoginPending: boolean;
 }
 /** 卡片动作与快照（slot 注入面）。 */
 export interface AiRouterCardFace {
@@ -82,6 +106,12 @@ export interface AiRouterCardFace {
         refresh(): Promise<void>;
         logout(): Promise<void>;
         selectKey(keyId: string): Promise<void>;
+        /** 发起浏览器授权登录（写 browserLoginRequest 请求字段）。 */
+        startBrowserLogin(): Promise<void>;
+        /** 取消浏览器授权登录等待态（清掉请求字段与回写的授权 URL）。 */
+        cancelBrowserLogin(): Promise<void>;
+        /** 重新打开当前授权页；无 URL 时 no-op。 */
+        reopenBrowserLogin(): void;
     };
 }
 /**
@@ -90,6 +120,40 @@ export interface AiRouterCardFace {
  * 实现方抛错，控制器把失败交给登录弹窗展示。
  */
 export type CredentialStorePort = (ref: string, value: string) => Promise<void>;
+/**
+ * 归一化登录方式：只有明确的 `browser` / `form` 才生效，其余（缺省、旧 Host 未下发、
+ * 非法值）一律按 `both`——fail-open，宁可多给一个入口，也不把用户锁在门外（spec §5.4）。
+ */
+export declare function normalizeLoginMode(value: unknown): LoginMode;
+/**
+ * Host 回写的授权页 URL：只有非空 http(s) 才算就绪。命名空间值可能被任意写入，
+ * 因此这里就把非 http(s)（`javascript:` 等）挡掉，投影与打开两处口径一致。
+ */
+export declare function authorizeUrlOf(value: AiRouterCardSettings | undefined): string | undefined;
+/**
+ * 是否处于浏览器登录等待态：授权 URL 已回写，或请求已发出但 Host 尚未回写。
+ * 后一种窗口期也算等待，避免用户重复点击发起第二次授权。
+ */
+export declare function browserLoginPendingOf(value: AiRouterCardSettings | undefined): boolean;
+/**
+ * 浏览器登录的投影视图（登录门禁与卡片共用）：`form` 模式下一律不暴露浏览器登录
+ * 入口——连残留的授权 URL 也一并抹掉，避免渲染层对旧 URL 再 `window.open` 一次。
+ */
+export declare function browserLoginViewOf(value: AiRouterCardSettings | undefined): {
+    loginMode: LoginMode;
+    browserLoginUrl: string | undefined;
+    browserLoginPending: boolean;
+};
+/**
+ * 打开授权页（渲染层职责）：桌面端 `shell.openExternal` 路由接管 https 外链，桌面端无需改动。
+ * 命名空间值可被任意写入，因此只放行 http(s)，其余静默忽略。
+ * @param url - Host 回写的授权页 URL；缺省 / 非法时为 no-op。
+ */
+export declare function openAuthorizeUrl(url: string | undefined): void;
+/** 请求 Host 发起浏览器授权登录（Host 生成 PKCE 后回写 `browserLogin`）。 */
+export declare function requestBrowserLogin(scope: SettingsScope<AiRouterCardSettings>): Promise<void>;
+/** 取消 / 结束浏览器登录等待态：清掉请求字段与 Host 回写的授权 URL。 */
+export declare function clearBrowserLogin(scope: SettingsScope<AiRouterCardSettings>): Promise<void>;
 /** 桥接 `ai-router` 作用域到卡片状态与动作。 */
 export declare class AiRouterCardController {
     private readonly scope;
@@ -102,4 +166,8 @@ export declare class AiRouterCardController {
     private selectKey;
     private refresh;
     private logout;
+    private startBrowserLogin;
+    private cancelBrowserLogin;
+    /** 重新打开授权页：URL 取自最近一次投影，缺省 no-op（登录门禁另有自动打开）。 */
+    private reopenBrowserLogin;
 }

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

@@ -1,16 +1,24 @@
 /**
- * 新建任务空白会话 hero 页的「每日卡片 v2 · 置顶精简版」（自 hiwork-dsh-ui 迁移）：
- * 把《海普发展纲领》当日条目以「灰小字前缀 + 蓝渐变大字主体」一行展示在 hero 标题
- * （headline）上方，点击后弹出一次性模态窗展示 归属链/日期/整句标题/逐字原文段落。
- * 主行下方带一枚「换一句」文字按钮：临时预览排除当前条目的随机条目（不改 dataset.day，
- * 故 rAF 观察循环不会重置它），仅当日历日变更时按既有逻辑重建回当日条目。
- * 只插入插件自有（dcu 标记）节点：不搬移/不改写任何宿主节点；宿主重建 hero 时自动重挂；
- * 非 hero / 槽位缺失时自动清残留（含弹窗）。
+ * 新建任务空白会话 hero 页的「每日一句」卡片（服务端下发）：
+ * 把网关当日条目以「灰小字前缀 + 蓝渐变大字主体」一行展示在 hero 标题（headline）
+ * 上方，点击后弹出一次性模态窗展示 出处/日期/标题/正文段落 + 「知道了」。
+ * 主行下方带一枚「换一句」文字按钮：临时预览排除当前条目的随机条目（不改
+ * dataset.date，故 rAF 观察循环不会重置它），仅当日历日变更时按既有逻辑重建回当日条目。
+ *
+ * 数据经 {@link DailyQuoteSource}（`/hiwork-daily` loopback RPC + 全天缓存）异步获取：
+ * 数据未就绪或当日无可展示内容（池空 / RPC 失败）的帧不插卡片；hero 页是装饰位，
+ * 任何失败都不出错误 UI、不打断主流程。问候语轮换（decorateHeroGreeting）不受影响、
+ * 照常每帧执行。
  *
  * dcu 标记与 hiwork-dsh-ui 保持同名：两插件同环境共存时互认对方已挂的卡片，
  * decorateDailyCard 的幂等检查只会让先挂者生效，不会双挂载。
  */
-import { type DailyItem } from './daily-items.ts';
+import { type DailyQuoteView, type DailyTodayView } from './daily-data.ts';
+/** 每日一句取数面（结构兼容 daily-data 的 DailyDataStore，便于测试伪造）。 */
+export interface DailyQuoteSource {
+    getToday(): Promise<DailyTodayView | null>;
+    getRandom(excludeId?: number): Promise<DailyQuoteView | null>;
+}
 export declare const DAILY_CARD_STYLE_ID = "dcu-daily-card-style";
 export declare const DAILY_CARD_STYLE = "\n[data-dcu-daily-card]{box-sizing:border-box;display:flex;flex-direction:column;align-items:center;width:100%;max-width:min(880px,100%);margin:6px auto 44px;cursor:pointer;user-select:none;text-align:center}\n[data-dcu-daily-prefix]{display:inline-flex;align-items:center;gap:14px;font-size:20px;line-height:1.4;font-weight:500;letter-spacing:.22em;text-indent:.22em;color:rgba(24,24,27,.35);white-space:nowrap}\n[data-dcu-daily-prefix]::before,[data-dcu-daily-prefix]::after{content:\"\";display:inline-block;width:44px;height:2px;border-radius:1px;background:currentColor;opacity:.5}\n[data-dcu-daily-prefix][hidden]{display:none}\n[data-dcu-daily-main]{margin-top:6px;font-size:64px;line-height:1.25;font-weight:650;letter-spacing:.005em;background:linear-gradient(100deg,#2f6bf0,#1d4ed8 45%,#0e7fc2);-webkit-background-clip:text;background-clip:text;color:transparent;transition:filter .18s ease}\n[data-dcu-daily-card]:hover [data-dcu-daily-main]{filter:brightness(1.12)}\n[data-dcu-daily-card]:focus-visible{outline:2px solid var(--dsw-alias-button-info-fill,#4c8dff);outline-offset:4px;border-radius:6px}\n[data-dcu-daily-shuffle]{flex:none;display:inline-flex;align-items:center;justify-content:center;gap:5px;margin-top:10px;padding:3px 10px;border-radius:8px;color:var(--dsw-alias-label-tertiary,#71717a);font-size:13px;line-height:20px;letter-spacing:.08em;text-indent:.08em;cursor:pointer;transition:color .18s ease}\n[data-dcu-daily-shuffle] svg{flex:none;width:13px;height:13px;transition:transform .45s ease}\n[data-dcu-daily-shuffle]:hover svg{transform:rotate(360deg)}\n[data-dcu-daily-shuffle]:hover{color:var(--dsw-alias-label-secondary,#3f3f46)}\n[data-dcu-daily-shuffle]:focus-visible{outline:2px solid var(--dsw-alias-button-info-fill,#4c8dff);outline-offset:2px}\nbody[data-ds-dark-theme] [data-dcu-daily-prefix]{color:rgba(242,244,248,.38)}\nbody[data-ds-dark-theme] [data-dcu-daily-main]{background:linear-gradient(100deg,#6b9bff,#3d7bff 45%,#4cc3ff);-webkit-background-clip:text;background-clip:text;color:transparent}\nbody[data-ds-dark-theme] [data-dcu-daily-shuffle]{color:var(--dsw-alias-label-tertiary,#9ba3b4)}\nbody[data-ds-dark-theme] [data-dcu-daily-shuffle]:hover{color:var(--dsw-alias-label-secondary,#a6adb8)}\n[data-dcu-daily-modal]{position:fixed;inset:0;z-index:2147483000;display:flex;align-items:center;justify-content:center;padding:24px;background:rgba(15,17,23,.55)}\n[data-dcu-daily-modal-box]{box-sizing:border-box;width:min(620px,100%);max-height:88vh;overflow:auto;border-radius:18px;border:1px solid var(--dsw-alias-border-subtle,rgba(24,24,27,.12));background:var(--dsw-alias-background-primary,#ffffff);box-shadow:0 24px 64px rgba(0,0,0,.28);padding:24px 28px;color:var(--dsw-alias-label-primary,#18181b)}\n[data-dcu-daily-modal-meta]{display:flex;align-items:center;justify-content:space-between;gap:12px;color:var(--dsw-alias-label-tertiary,#71717a);font-size:12.5px;line-height:18px;letter-spacing:.02em}\n[data-dcu-daily-modal-title]{margin-top:14px;font-size:24px;line-height:1.45;font-weight:650;color:var(--dsw-alias-label-primary,#18181b)}\n[data-dcu-daily-modal-body]{margin-top:16px;color:var(--dsw-alias-label-secondary,#3f3f46);font-size:14.5px;line-height:1.95}\n[data-dcu-daily-modal-body] > p{margin:0 0 10px}\n[data-dcu-daily-modal-body] > p:last-child{margin-bottom:0}\n[data-dcu-daily-modal-close]{appearance:none;margin-top:20px;padding:7px 18px;border:1px solid var(--dsw-alias-border-strong,rgba(24,24,27,.2));border-radius:9px;background:var(--dsw-alias-button-secondary-fill,transparent);color:var(--dsw-alias-label-secondary,#3f3f46);font-size:13px;line-height:20px;cursor:pointer}\n[data-dcu-daily-modal-close]:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(24,24,27,.06))}\n[data-dcu-daily-modal-close]:focus-visible{outline:2px solid var(--dsw-alias-button-info-fill,#4c8dff);outline-offset:2px}\nbody[data-ds-dark-theme] [data-dcu-daily-modal]{background:rgba(0,0,0,.62)}\nbody[data-ds-dark-theme] [data-dcu-daily-modal-box]{border-color:var(--dsw-alias-border-subtle,rgba(255,255,255,.12));background:var(--dsw-alias-background-primary,#10131b);color:var(--dsw-alias-label-primary,#f2f4f8)}\nbody[data-ds-dark-theme] [data-dcu-daily-modal-meta]{color:var(--dsw-alias-label-tertiary,#9ba3b4)}\nbody[data-ds-dark-theme] [data-dcu-daily-modal-title]{color:var(--dsw-alias-label-primary,#f2f4f8)}\nbody[data-ds-dark-theme] [data-dcu-daily-modal-body]{color:var(--dsw-alias-label-secondary,#a6adb8)}\nbody[data-ds-dark-theme] [data-dcu-daily-modal-close]{border-color:var(--dsw-alias-border-subtle,rgba(255,255,255,.16));color:var(--dsw-alias-label-secondary,#a6adb8)}\nbody[data-ds-dark-theme] [data-dcu-daily-modal-close]:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.08))}\n@media (prefers-reduced-motion: reduce){[data-dcu-daily-card] [data-dcu-daily-main],[data-dcu-daily-shuffle],[data-dcu-daily-shuffle] svg,[data-dcu-daily-modal-box]{transition:none}}\n";
 export declare function ensureDailyCardStyle(doc: Document): void;
@@ -20,20 +28,21 @@ export declare function ensureDailyCardStyle(doc: Document): void;
  */
 export declare function findDailyCardMount(doc: Document): HTMLElement | null;
 /**
- * 「随机换一条」抽取：从 75 条池中随机取一条，命中 exclude 时按池长模长顺移重掷，
- * 保证永不等于当前展示条目（75 条池必有另一条，循环至多绕一圈即终止）。
- */
-export declare function pickRandomItem(exclude: DailyItem): DailyItem;
-/**
- * 幂等装饰：hero + headline 缺失 → 只清残留；已有时当日卡片紧邻同一条 headline → 不动；
- * 否则清掉旧卡片后把当日主行作为 headline 的前一个兄弟插入（不搬移任何宿主节点）。
+ * 幂等装饰：hero + headline 缺失 → 只清残留；否则取当日缓存数据异步落位——
+ *  - 数据未就绪（悬而未决）→ 本帧不动，等数据就绪的微任务再插；
+ *  - 当日无可展示内容（null：池空 / RPC 失败）→ 清掉残留卡片（如昨日内容），不插新卡；
+ *  - 已有卡片且 dataset.date 与缓存 date 一致 → 不动（「换一句」的随机预览因此不被重置）；
+ *  - 其余 → 清掉旧卡片后把当日主行作为 headline 的前一个兄弟插入（不搬移任何宿主节点）。
+ *
+ * 落位前重新校验 hero / headline 仍在场（异步间隙宿主可能已切页或重建 DOM）。
  */
-export declare function decorateDailyCard(doc: Document): void;
+export declare function decorateDailyCard(doc: Document, quotes: DailyQuoteSource): void;
 /** 清理非 hero / 槽位变化后残留的卡片节点，以及任何仍在打开的弹窗。 */
 export declare function removeStaleDailyCard(doc: Document): void;
 /**
- * 观察新建任务 hero 页并装饰同页组件：每日卡片 + hero 问候语轮换（见 hero-greeting.ts）。
- * DOM 变更按帧合并，避免流式输出时每个 token 都全文档扫描；页面完全空闲跨午夜时
- * MutationObserver 不会触发，靠周期轮询兜底换日。返回卸载清理函数。
+ * 观察新建任务 hero 页并装饰同页组件：每日一句（服务端下发）+ hero 问候语轮换
+ * （见 hero-greeting.ts）。DOM 变更按帧合并，避免流式输出时每个 token 都全文档扫描；
+ * 页面完全空闲跨午夜时 MutationObserver 不会触发，靠周期轮询兜底换日（本地日变更
+ * 触发重新拉取，服务端日期随之更新）。返回卸载清理函数。
  */
-export declare function observeHeroDecorations(doc?: Document): () => void;
+export declare function observeHeroDecorations(doc: Document, quotes: DailyQuoteSource): () => void;