hiwork-core 0.0.3 → 0.0.7

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>;

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

@@ -0,0 +1,110 @@
+/**
+ * `/hiwork-daily` loopback RPC 的 Host 实现（新建任务 hero 页「每日一句」的唯一取数口）。
+ *
+ * 设计要点（与 `src/usage-rpc.ts` 完全同构）：
+ *  - 只注册一个 channel，endpoint 白名单在 {@link DAILY_RPC_ENDPOINTS}，未知 endpoint
+ *    直接 `bad-request`；
+ *  - payload 严格校验：`today` 只接受空对象，`random` 只接受 `{ excludeId?: 正整数 }`，
+ *    任何其它字段 / 类型不符一律 `bad-request`；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方只拿到端点原始响应，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - 网关 `GatewayError` 的稳定 code 原样透传，但 message 先经
+ *    {@link displayDailyGatewayMessage} 消毒——baseURL / HTTP 状态码这类实现细节不进 UI；
+ *  - 其余异常收敛为通用失败（code `internal`），Host 只记日志、不把堆栈或原始消息
+ *    交给客户端。
+ *
+ * 消毒逻辑是**同构复制**而非复用 usage-rpc 的导出：后者的兜底文案是用量域的
+ * （「用量数据暂时无法获取…」），复用会让每日一句的失败吐出错误域的文案；且本仓库的
+ * 频道模块本就各自自带一份同实现（usage-rpc 与 hiwork-automation 的 rpc.ts 亦然），
+ * 保持模块自包含。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link DailyRpcContext} 端口，
+ * 便于单测直接伪造。
+ */
+import { type GatewayDailyQuoteRandomResponse, type GatewayDailyQuoteResponse } from './ai-router-client.ts';
+/** RPC 频道；必须与 client 半边 `src/client/daily-data.ts` 的 `DAILY_CHANNEL` 一致（由测试锁定）。 */
+export declare const DAILY_RPC_CHANNEL = "/hiwork-daily";
+/** 端点白名单：当日条目 + 换一句（随机）。 */
+export declare const DAILY_RPC_ENDPOINTS: readonly ["today", "random"];
+export type DailyRpcEndpoint = (typeof DAILY_RPC_ENDPOINTS)[number];
+/** 端点入参：只有 `random` 带可选 `excludeId`（当前展示条目 id，正整数）。 */
+export interface DailyRpcPayload {
+    excludeId?: number | undefined;
+}
+/** 客户端可安全展示的失败。 */
+export interface DailyRpcFailure {
+    code: string;
+    message: string;
+    /** DSH Connection 信封要求 `details` 是对象；协议层没有额外细节时补空对象。 */
+    details: object;
+}
+/** 端点结果信封（与 DSH Connection 的 `ConnectionRpcResult` 同形）。 */
+export type DailyRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: DailyRpcFailure;
+};
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export declare class DailyRequestError extends Error {
+    readonly code: 'bad-request';
+    constructor(code: 'bad-request', message: string);
+}
+/** Host 侧 RPC 依赖的最小上下文（结构兼容 cordis Context，便于单测伪造）。 */
+export interface DailyRpcConnection {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+            authority: 'loopback';
+        }): () => Promise<void> | void;
+    };
+}
+export interface DailyRpcContext {
+    readonly connection: DailyRpcConnection;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/** 网关客户端的每日一句子集：只声明本频道真正调用的方法（结构兼容 `GatewayClient` 实例）。 */
+export interface DailyGatewayPort {
+    getMyDailyQuote(sessionCookie: string): Promise<GatewayDailyQuoteResponse>;
+    getMyDailyQuoteRandom(sessionCookie: string, excludeId?: number): Promise<GatewayDailyQuoteRandomResponse>;
+}
+/** Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关客户端。 */
+export interface DailyRpcDeps {
+    /**
+     * 解析网关会话 cookie。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用，绝不出现在 RPC 响应里。**
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关客户端；baseURL 未配置时返回 undefined。 */
+    gateway(): DailyGatewayPort | undefined;
+    /** Host 日志出口（只记事件与错误类型，不记会话值）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 通用失败文案：不暴露任何网关细节。 */
+export declare const DAILY_GENERIC_FAILURE_MESSAGE = "\u6BCF\u65E5\u4E00\u53E5\u6682\u65F6\u65E0\u6CD5\u83B7\u53D6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/** 未登录 / 会话失效的统一文案（与用量频道的 `SESSION_EXPIRED` 口径一致）。 */
+export declare const DAILY_SESSION_EXPIRED_MESSAGE = "\u767B\u5F55\u72B6\u6001\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55";
+/**
+ * 网关 message 消毒（与 `usage-rpc.ts` 的 `displayGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export declare function displayDailyGatewayMessage(code: string, message: unknown): string;
+/**
+ * payload 校验：`today` 只放行空对象，`random` 只放行 `{ excludeId?: 正整数 }`；
+ * 其余字段 / 类型不符一律 `bad-request`。
+ */
+export declare function parseDailyPayload(endpoint: DailyRpcEndpoint, raw: unknown): DailyRpcPayload;
+/** 是否为白名单端点。 */
+export declare function isDailyRpcEndpoint(endpoint: string): endpoint is DailyRpcEndpoint;
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export declare function handleDailyEndpoint(endpoint: string, rawPayload: unknown, deps: DailyRpcDeps, signal?: AbortSignal): Promise<DailyRpcResult<unknown>>;
+/**
+ * 注册 `/hiwork-daily` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export declare function registerDailyRpc(ctx: DailyRpcContext, deps: DailyRpcDeps): () => Promise<void>;

package/lib/types/default-model.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 默认模型校正。
+ *
+ * `agent-default-model` 是 dsh 的默认模型选择（provider + model），dsh-base 的组合默认值
+ * 指向官方 DeepSeek 提供方（`deepseek-official/deepseek-v4-flash`）。本产品停用了官方提供方、
+ * 只供给网关线路，所以全新安装或提供方/模型变动后，这个默认值可能指向一个不再注册的
+ * provider 或已下架的 model —— 新会话第一次发请求会 UNKNOWN_MODEL，用户必须先去模型选择器
+ * 手动选一次。供给成功后在这里校正它：当前选择仍可路由就不动，否则回落到兜底线路的第一个模型。
+ *
+ * 不写 composition 配置、只写用户层，所以用户自己选过的模型只要仍然可用就不会被覆盖。
+ */
+import type { RouteModels } from './provision.ts';
+/** dsh-agent-default-model 的 settings 命名空间。 */
+export declare const DEFAULT_MODEL_NS = "agent-default-model";
+/** 一次默认模型选择。 */
+export interface DefaultModelSelection {
+    provider: string;
+    model: string;
+}
+/** 校正默认模型所需的端口（便于单测注入假实现）。 */
+export interface DefaultModelPorts {
+    /** `agent-default-model` 命名空间是否已注册；未注册的 profile 直接跳过。 */
+    available(): boolean;
+    /** 读当前默认选择；字段缺失或命名空间未注册时 undefined。 */
+    read(): DefaultModelSelection | undefined;
+    /** 非本插件线路的提供方：已注册且确实含该模型时为 true。 */
+    isRoutableElsewhere(selection: DefaultModelSelection): Promise<boolean>;
+    /** 写入校正后的选择（同时清掉可能不再合法的 reasoningEffort）。 */
+    write(selection: DefaultModelSelection): Promise<void>;
+}
+/**
+ * 供给成功后校正默认模型。
+ * @param routeModels - 本次供给出的各线路模型归属。
+ * @param ports - settings / llm 端口。
+ * @returns 实际写入的新选择；无需变更时 undefined。
+ */
+export declare function ensureDefaultModel(routeModels: RouteModels, ports: DefaultModelPorts): Promise<DefaultModelSelection | undefined>;

package/lib/types/index.d.ts

@@ -6,7 +6,14 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { type SettingsProvider } from '@deepseek-ai/dsh-settings';
+import { fetchClientPolicy, type ClientPolicy, type LoginMode } from './client-policy.ts';
+import { type CredentialsPort, type DefaultModelPort, type AiRouterStatePort } from './orchestration.ts';
 export declare const name = "hiwork-core";
+/**
+ * 必需服务：`connection` 承载设置页「用量与成本」的 loopback RPC 频道
+ * （`/hiwork-usage`，见 `src/usage-rpc.ts`）；其余三项是既有登录 / 供给依赖。
+ */
 export declare const inject: string[];
 /** 插件配置 + 运行时状态字段（全部可选；写操作按此 schema 校验）。 */
 export interface Config {
@@ -34,6 +41,21 @@ export interface Config {
     logoutRequest?: {
         at: string;
     };
+    /** 客户端请求发起浏览器授权登录（宿主发起后清掉，见 src/browser-login.ts）。 */
+    browserLoginRequest?: {
+        at: string;
+    };
+    /** 已发起的浏览器授权：授权页 URL + 发起时间，渲染端负责 window.open。 */
+    browserLogin?: {
+        authorizeUrl: string;
+        startedAt: string;
+    };
+    /**
+     * 登录方式：Host 从 `GET /api/client/policy` 投影（spec §5.4 / §6.1）。
+     * 取值与 `src/client/controller.ts` 的 `LoginMode` 一致，**不得改**；缺省 / 拉取失败
+     * 一律写 `both`（fail-open，绝不把用户锁在门外）。
+     */
+    loginMode?: LoginMode;
     budgets?: Array<{
         model_name: string;
         total_budget?: number | null;
@@ -50,4 +72,95 @@ export interface Config {
     }>;
 }
 export declare const Config: z<Config>;
+/** 校正默认模型要用到的 llm 注册表部分（便于单测注入假实现）。 */
+export interface LlmRouteRegistry {
+    listProviders(): readonly {
+        id: string;
+    }[];
+    listModels(provider: string): Promise<readonly {
+        id: string;
+    }[]>;
+}
+/**
+ * 组装默认模型端口：settings 读写 + llm 注册表的「提供方/模型是否还在」判断。
+ * 导出以便单测覆盖接线（编排只依赖 `DefaultModelPort` 接口）。
+ * @param opts.settings - settings 服务（读写 agent-default-model 用户层）。
+ * @param opts.llm - llm 注册表；缺省时其它提供方一律视为不可路由。
+ * @param opts.log - 校正成功时的日志出口。
+ * @returns 供编排调用的默认模型端口。
+ */
+export declare function createDefaultModelPort(opts: {
+    settings: SettingsProvider;
+    llm: LlmRouteRegistry | undefined;
+    log?: (message: string) => void;
+}): DefaultModelPort;
+/**
+ * IPC 消息源最小面：Node 的 `process` 结构上满足（`on`/`off` 的 `'message'` 重载），
+ * 测试注入假对象——**不把 `process.on` 写死在不可测的地方**。
+ */
+export interface IpcMessageSource {
+    on(event: 'message', listener: (message: unknown) => void): unknown;
+    off(event: 'message', listener: (message: unknown) => void): unknown;
+}
+/** 注册 IPC 监听所需端口（生产由 apply 用真实 process 与既有 ports 装配）。 */
+export interface IpcCallbackPorts {
+    /** 消息源（生产传 `process`）。 */
+    source: IpcMessageSource;
+    /** 处理一条已通过校验的授权回调（生产为 `completeBrowserLogin`）。 */
+    complete: (input: {
+        code?: string;
+        state?: string;
+        error?: string;
+    }) => Promise<unknown>;
+    /** 记录桌面端推来的设备信息（生产为 `setDeviceInfo`）。 */
+    setDevice: (info: {
+        deviceId: string;
+        deviceName?: string;
+        appVersion?: string;
+    }) => void;
+    /** 把设备 id 持久化到 credentials 的 `hiwork_device_id`（生产为 `ports.credentials.set`）。 */
+    persistDeviceId: (deviceId: string) => Promise<void>;
+    /**
+     * 告警出口；缺省静默。**只记事件与字段名，绝不记 code / state / deviceId 的值**，
+     * 也绝不记完整回调 URL。
+     */
+    log?: (message: string) => void;
+}
+/**
+ * 注册桌面端 IPC 消息监听（`process.on('message', …)`），返回幂等 disposer。
+ *
+ * 分派规则：只处理 `hiwork:auth-callback` 与 `hiwork:device-info` 两种信封，其余一律
+ * 静默忽略（DSH 自有消息 / 其他插件消息不得被本插件触碰）。
+ *
+ * 并发守卫：`complete` 是异步的，连续到达的多条回调**只执行第一条，后到的直接忽略
+ * （不排队）**。理由——授权回调是一次性的（一个 code 只能兑换一次），排队执行会让
+ * 真实回调完成后仍去兑换已消费的 code，并给伪造的迟到消息改写 `lastError` 的机会；
+ * 忽略既最安全，也与 `completeBrowserLogin` 自身的「一次性」语义一致。
+ * 该守卫只约束授权回调：`hiwork:device-info` 同步处理 + 后台持久化，**不受阻塞**。
+ */
+export declare function registerIpcMessageHandler(ports: IpcCallbackPorts): () => void;
+/**
+ * 拉取客户端策略并把 `loginMode` 投影进 ai-router 命名空间（spec §5.4 / §6.1）。
+ *
+ * fail-open 是硬要求：缺 baseURL / 设备信息取不到 / 网络失败 / 响应非法一律投影
+ * `DEFAULT_LOGIN_MODE`（`both`），**且只写 `loginMode` 一个字段**——不碰 lastError、
+ * 不碰任何登录请求字段，策略拉取失败绝不影响登录与供给。**本函数永不抛异常**。
+ *
+ * @returns 最终投影的登录方式（测试与调用方均可断言）。
+ */
+export declare function projectLoginMode(opts: {
+    baseURL: string | undefined;
+    credentials: CredentialsPort;
+    state: AiRouterStatePort;
+    /** 客户端版本；缺省 `PKG_VERSION`。 */
+    version?: string;
+    /** 平台 / 架构；缺省 `process.platform` / `process.arch`。 */
+    platform?: string;
+    arch?: string;
+    /** 策略拉取超时；缺省由 fetchClientPolicy 决定。 */
+    timeoutMs?: number;
+    /** 策略拉取实现（测试注入）；缺省 `fetchClientPolicy`。 */
+    fetchPolicy?: (input: Parameters<typeof fetchClientPolicy>[0]) => Promise<ClientPolicy | undefined>;
+    log?: (message: string) => void;
+}): Promise<LoginMode>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/types/orchestration.d.ts

@@ -1,64 +1,16 @@
-import { type GatewayBudget, type GatewayClient, type GatewayKey } from './ai-router-client.ts';
+import { 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';
-/** 凭据端口：对 ctx.credentials 的抽象，便于测试。 */
-export interface CredentialsPort {
-    resolve(ref: string): Promise<{
-        value: string;
-    } | undefined>;
-    set(ref: string, value: string): Promise<void>;
-    unset(ref: string): Promise<void>;
-}
-/** pi-ai 配置端口：写/清协议路由集合（多路由按协议拆分）。 */
-export interface PiAiPort {
-    applyAiRouterProfiles(profiles: Record<string, Record<string, unknown>> | null): Promise<void>;
-}
-/** 对 ai-router 状态段的一次补丁。 */
-export interface AiRouterStatePatch {
-    set?: Record<string, unknown>;
-    unset?: readonly string[];
-}
-/** ai-router 状态端口：Host 的唯一写者。 */
-export interface AiRouterStatePort {
-    patch(patch: AiRouterStatePatch): Promise<void>;
-}
-/** ai-router 命名空间解析后的值（相关字段）。 */
-export interface AiRouterNamespaceValue {
-    baseURL?: string;
-    keyId?: string;
-    username?: string;
-    /** 登录账号的显示名（网关 LDAP displayName，如中文名）；缺省时 UI 回退 username。 */
-    displayName?: string;
-    pendingLogin?: {
-        username: string;
-        passwordRef: string;
-    };
-    rememberPassword?: boolean;
-    refreshRequest?: {
-        at?: string;
-    };
-    logoutRequest?: {
-        at?: string;
-    };
-    /** 最近一次拉取到的各模型额度（登录/刷新时写入）。 */
-    budgets?: readonly GatewayBudget[];
-    /** 最近一次拉取到的当前用户全部虚拟 Key（多 Key 选择器数据源）。 */
-    keys?: readonly GatewayKey[];
-}
-/**
- * 归一化 budgets：过滤空模型名与已下架模型（model_status === 'inactive'，已不可调用，
- * 不进入额度展示），保留额度字段。状态缺省（旧网关）视同 active，正常保留。
- */
-export declare function computeBudgets(budgets: readonly GatewayBudget[]): GatewayBudget[];
-/** 归一化 keys：过滤无 id 项，只保留选择器需要的字段。 */
-export declare function computeKeys(keys: readonly GatewayKey[]): GatewayKey[];
-/** 任意抛错 → 稳定 LoginError；GatewayError 原样，其余归为 GATEWAY_UNREACHABLE。 */
-export declare function toLoginError(error: unknown, fallback: string): LoginError;
+export { computeBudgets, computeKeys, provisionSession, toLoginError } from './provision-session.ts';
+export type { AiRouterNamespaceValue, AiRouterStatePatch, AiRouterStatePort, CredentialsPort, DefaultModelPort, PiAiPort, } from './provision-session.ts';
 /** 执行一次登录：拉 Key + budgets → 写凭据 → 写 pi-ai 配置 → 写状态。 */
 export declare function runLogin(opts: {
     gateway: GatewayClient;
     credentials: CredentialsPort;
     piAi: PiAiPort;
     state: AiRouterStatePort;
+    /** 供给成功后校正默认模型；可选以便既有测试直接构造 opts。 */
+    defaultModel?: DefaultModelPort;
     /** 登录成功尾部触发（默认工作区 ensure 等）；可选以便既有测试直接构造 opts。 */
     ensureWorkspace?: () => Promise<void>;
     value: AiRouterNamespaceValue;
@@ -69,6 +21,8 @@ export declare function runRefresh(opts: {
     credentials: CredentialsPort;
     piAi: PiAiPort;
     state: AiRouterStatePort;
+    /** 供给成功后校正默认模型；可选以便既有测试直接构造 opts。 */
+    defaultModel?: DefaultModelPort;
     /** 透传给重登路径 runLogin 的可选端口。 */
     ensureWorkspace?: () => Promise<void>;
     value: AiRouterNamespaceValue;
@@ -80,12 +34,31 @@ export declare function runLogout(opts: {
     piAi: PiAiPort;
     state: AiRouterStatePort;
 }): Promise<void>;
-/** 分发一次 ai-router 命名空间变更：三个请求字段至多存在一个。 */
+/**
+ * 浏览器授权登录的发起：生成 PKCE 与 state，回写 `browserLogin` 供渲染端 window.open。
+ * 见 browser-login.ts；此处只做分发与错误码归一。
+ */
+export declare function handleBrowserLoginRequest(opts: {
+    credentials: CredentialsPort;
+    state: AiRouterStatePort;
+    value: AiRouterNamespaceValue;
+    /** 告警出口（state 不匹配等安全事件）；缺省静默。 */
+    log?: (message: string) => void;
+    /** 时钟注入（测试用）；缺省 Date.now。 */
+    now?: () => number;
+}): Promise<LoginError | null>;
+/** 分发一次 ai-router 命名空间变更：请求字段至多存在一个。 */
 export declare function handleAiRouterSectionChange(opts: {
     gateway: GatewayClient;
     credentials: CredentialsPort;
     piAi: PiAiPort;
     state: AiRouterStatePort;
+    /** 供给成功后校正默认模型；可选以便既有测试直接构造 opts。 */
+    defaultModel?: DefaultModelPort;
     ensureWorkspace?: () => Promise<void>;
     value: AiRouterNamespaceValue;
+    /** 告警出口（浏览器授权 state 不匹配等）；缺省静默。 */
+    log?: (message: string) => void;
+    /** 时钟注入（测试用）；缺省 Date.now。 */
+    now?: () => number;
 }): Promise<LoginError | null>;

package/lib/types/provision-session.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 会话供给的共享契约与实现：端口接口、状态字段形状、归一化与错误映射，
+ * 以及「会话已建立后」的供给尾部 `provisionSession`。
+ *
+ * 本模块被 `orchestration.ts`（表单登录 / 刷新 / 登出）与 `browser-login.ts`
+ * （浏览器授权登录）各自直接 import，**它自身不 import 这两者**，因此不存在循环依赖
+ * （打包产物里也不会出现模块级 TDZ 风险）。
+ */
+import { type GatewayBudget, type GatewayClient, type GatewayKey, type GatewayUser } from './ai-router-client.ts';
+import type { RouteModels } from './provision.ts';
+import type { LoginError } from './types.ts';
+/** 凭据端口：对 ctx.credentials 的抽象，便于测试。 */
+export interface CredentialsPort {
+    resolve(ref: string): Promise<{
+        value: string;
+    } | undefined>;
+    set(ref: string, value: string): Promise<void>;
+    unset(ref: string): Promise<void>;
+}
+/** pi-ai 配置端口：写/清协议路由集合（多路由按协议拆分）。 */
+export interface PiAiPort {
+    applyAiRouterProfiles(profiles: Record<string, Record<string, unknown>> | null): Promise<void>;
+}
+/** 默认模型端口：供给成功后校正 agent-default-model（见 src/default-model.ts）。 */
+export interface DefaultModelPort {
+    ensure(routeModels: RouteModels): Promise<void>;
+}
+/** 对 ai-router 状态段的一次补丁。 */
+export interface AiRouterStatePatch {
+    set?: Record<string, unknown>;
+    unset?: readonly string[];
+}
+/** ai-router 状态端口：Host 的唯一写者。 */
+export interface AiRouterStatePort {
+    patch(patch: AiRouterStatePatch): Promise<void>;
+}
+/** ai-router 命名空间解析后的值（相关字段）。 */
+export interface AiRouterNamespaceValue {
+    baseURL?: string;
+    keyId?: string;
+    username?: string;
+    /** 登录账号的显示名（网关 LDAP displayName，如中文名）；缺省时 UI 回退 username。 */
+    displayName?: string;
+    pendingLogin?: {
+        username: string;
+        passwordRef: string;
+    };
+    rememberPassword?: boolean;
+    refreshRequest?: {
+        at?: string;
+    };
+    logoutRequest?: {
+        at?: string;
+    };
+    /** 客户端请求发起浏览器授权登录（渲染端写；宿主发起后清掉）。 */
+    browserLoginRequest?: {
+        at?: string;
+    };
+    /** 已发起的浏览器授权：授权页 URL + 发起时间，渲染端负责 window.open。 */
+    browserLogin?: {
+        authorizeUrl: string;
+        startedAt: string;
+    };
+    /** 最近一次拉取到的各模型额度（登录/刷新时写入）。 */
+    budgets?: readonly GatewayBudget[];
+    /** 最近一次拉取到的当前用户全部虚拟 Key（多 Key 选择器数据源）。 */
+    keys?: readonly GatewayKey[];
+}
+/**
+ * 归一化 budgets：过滤空模型名与已下架模型（model_status === 'inactive'，已不可调用，
+ * 不进入额度展示），保留额度字段。状态缺省（旧网关）视同 active，正常保留。
+ */
+export declare function computeBudgets(budgets: readonly GatewayBudget[]): GatewayBudget[];
+/** 归一化 keys：过滤无 id 项，只保留选择器需要的字段。 */
+export declare function computeKeys(keys: readonly GatewayKey[]): GatewayKey[];
+/** 任意抛错 → 稳定 LoginError；GatewayError 原样，其余归为 GATEWAY_UNREACHABLE。 */
+export declare function toLoginError(error: unknown, fallback: string): LoginError;
+/**
+ * 会话已建立后的共享供给尾部：拉 Key → 写凭据 → 写 pi-ai 配置 → 校正默认模型 → 写状态 →
+ * ensure 工作区。表单登录（orchestration.ts 的 runLogin）与浏览器授权登录
+ * （browser-login.ts）共用同一段，保证两条登录路径的供给结果逐字段等价。
+ */
+export declare function provisionSession(opts: {
+    gateway: GatewayClient;
+    credentials: CredentialsPort;
+    piAi: PiAiPort;
+    state: AiRouterStatePort;
+    /** 供给成功后校正默认模型；可选以便既有测试直接构造 opts。 */
+    defaultModel?: DefaultModelPort;
+    /** 供给成功后触发（默认工作区 ensure 等）；可选以便既有测试直接构造 opts。 */
+    ensureWorkspace?: () => Promise<void>;
+    /** 本次供给使用的网关根地址（调用方已确认非空）。 */
+    baseURL: string;
+    /** ai-router 命名空间解析值（读 keyId）。 */
+    value: AiRouterNamespaceValue;
+    /** 已建立的网关会话 cookie。 */
+    sessionCookie: string;
+    /** 登录响应里的用户信息（写 displayName）。 */
+    user: GatewayUser;
+    /** 写入状态的账号名；缺省则不写（浏览器登录在网关未回传用户名时保留旧值）。 */
+    username?: string | undefined;
+    /** 成功时一并清掉的请求字段（表单登录 pendingLogin / 浏览器登录 browserLoginRequest）。 */
+    requestUnset?: readonly string[];
+    /** API_KEY 写好后触发的表单专属凭据整理（记住密码 / 临时密码）；浏览器登录不传。 */
+    onApiKeyWritten?: () => Promise<void>;
+}): Promise<void>;

package/lib/types/provision.d.ts

@@ -10,15 +10,23 @@ export declare const REMEMBERED_PASSWORD_REF = "AI_ROUTER_REMEMBERED_PASSWORD";
 /**
  * 注册到 llm-pi-ai 的协议路由表：路由名 → pi-ai 协议。
  * 网关按「入站协议 + 模型」匹配模型映射（internal/service/provider_service.go），
- * 而 pi-ai 的 `api` 是路由级的 —— 因此每个协议一条路由，模型按映射归属到对应路由，
+ * 而 pi-ai 的 `api` 是路由级的 —— 因此每个协议一条路由，模型按映射进入对应路由，
  * 切模型时 dsh 自动落到讲该协议的路由，协议随模型走。
- * 主路由固定用 Responses 协议（/v1/responses），OpenAI 兼容模型统一落到它。
+ *
+ * 路由名固定为「线路C/M/R」，后缀即该路由讲的协议首字母（同一模型可出现在多条线路里）：
+ * - 线路C `ai-router-chat`：openai-completions（chat/completions，兜底协议）
+ * - 线路M `ai-router-anthropic`：anthropic-messages
+ * - 线路R `ai-router`：openai-responses（key 与协议保持不变，兼容既有
+ *   `agent-default-model: provider: ai-router`）
  */
 export declare const PROVIDER_ROUTES: {
-    readonly 'ai-router': "openai-responses";
+    readonly 'ai-router-chat': "openai-completions";
     readonly 'ai-router-anthropic': "anthropic-messages";
+    readonly 'ai-router': "openai-responses";
 };
 export type ProviderRouteName = keyof typeof PROVIDER_ROUTES;
+/** 各线路的模型归属（`computeRouteModels` 的输出）；空线路不出现。 */
+export type RouteModels = Partial<Record<ProviderRouteName, ModelDescriptor[]>>;
 /** 预算项的只读视图：模型名 + 可选目录状态（inactive = 已下架，不可调用）。 */
 export interface BudgetItem {
     model_name: string;
@@ -39,10 +47,27 @@ export interface ModelDescriptor {
     id: string;
     input: readonly PiAiModality[];
 }
-/** 固定写入顺序：先主路由（兼容 agent-default-model 的 provider: ai-router）。 */
+/** 固定写入顺序：线路C → 线路M → 线路R（按后缀字母序，与模型选择器的分组顺序一致）。 */
 export declare const PROVIDER_ROUTE_NAMES: readonly ProviderRouteName[];
-/** 旧版独立 responses 路由（现已并入主路由）；仅用于升级时清理残留 provider。 */
+/** 旧版独立 responses 路由（现已并入线路R）；仅用于升级时清理残留 provider。 */
 export declare const LEGACY_PROVIDER_ROUTE_NAMES: readonly string[];
+/**
+ * 网关模型映射协议名（下划线式），即 `models.ProtocolType` 的取值集合
+ * （spec §6.2 词汇表）。计价端点 `POST /api/me/cost-estimate` 的 `route` 用这套名字，
+ * 而 DSH 会话里的 `routes[].provider` 是**线路名**（连字符式）——两者在 Host 侧用
+ * {@link routeToProtocol} 翻译，客户端不需要知道网关协议名。
+ */
+export declare const GATEWAY_PROTOCOLS: readonly ["openai_chat_completions", "anthropic_messages", "openai_responses"];
+export type GatewayProtocol = (typeof GATEWAY_PROTOCOLS)[number];
+/**
+ * 线路名 → 网关协议名（{@link GATEWAY_PROTOCOL_TO_ROUTE} 的反查，单点真相）。
+ *
+ * 未知线路与遗留线路（`ai-router-responses`，升级时已清理）一律返回 `undefined`——
+ * 调用方必须**丢弃**该轮而不是上报：网关对 `route` 做严格相等匹配，非法值会让整批 400。
+ * @param route - DSH 线路名（会话 `routes[].provider` 的取值）。
+ * @returns 网关协议名；不在映射内时为 undefined。
+ */
+export declare function routeToProtocol(route: string): GatewayProtocol | undefined;
 /**
  * 从 budgets 归一化出去重、非空的模型 id 列表。已下架模型（model_status === 'inactive'，
  * 网关 PreCheck 直接 402）不在「能成功调用」集合内，剔除；状态缺省（旧网关）视同 active。
@@ -59,12 +84,26 @@ export declare function parseModalities(raw: string | undefined): PiAiModality[]
 /** 由 budgets 构造每模型描述符（已剔除下架模型；模态按 budget 的 input_modalities 解析）。 */
 export declare function computeModelDescriptors(budgets: readonly BudgetItem[]): ModelDescriptor[];
 /**
- * 按网关模型映射把预算内模型拆到各协议路由：
- * 每个模型归属「优先级最高且映射命中（精确或通配）的协议」；
- * 无任何映射命中的模型落到主路由（默认 responses，网关侧仍有 `*` 兜底，保持预算内模型均可选）。
+ * 按网关模型映射把预算内模型拆到各协议路由（一条路由一个协议）：
+ * 模型进入**每一条**「映射命中（精确或通配）的协议」对应的线路 —— 按协议分组，不按模型唯一归属，
+ * 所以同一个模型可以同时出现在多条线路里（例如既声明了 responses 又声明了 anthropic 映射的模型，
+ * 线路R 和线路M 都会列出它），不做去重：用户从哪条线路选它，请求就走那条线路的协议。
+ * 无任何映射命中的模型落到兜底线路 chat/completions：网关的裸 `*` 兜底映射通常声明在该协议下，
+ * 用 responses 入站反而匹配不到任何映射（网关按入站协议过滤映射）。
  * 返回每模型描述符（含 DSH 可接受的 input 模态），供 profile 注入。
  */
-export declare function computeRouteModels(budgets: readonly BudgetItem[], mapping: readonly GatewayModelMapping[]): Partial<Record<ProviderRouteName, ModelDescriptor[]>>;
+export declare function computeRouteModels(budgets: readonly BudgetItem[], mapping: readonly GatewayModelMapping[]): RouteModels;
+/**
+ * 兜底默认模型：按线路顺序 C→M→R 取第一条非空线路的第一个模型。
+ * 线路C 讲的 chat/completions 最通用（网关的裸 `*` 兜底映射也声明在该协议下），
+ * 因此优先；模型顺序沿用网关 `/api/me/key` 的 budgets 顺序。
+ * @param routeModels - 各线路的模型归属。
+ * @returns 兜底选择；所有线路都为空时 undefined。
+ */
+export declare function pickFallbackDefaultModel(routeModels: RouteModels): {
+    provider: ProviderRouteName;
+    model: string;
+} | undefined;
 /**
  * 各协议的 pi-ai baseURL：OpenAI 系 SDK 把 baseURL 视为根（追加 chat/completions、
  * responses），补 `/v1`；Anthropic SDK 自带 `v1/` 前缀，必须传裸 base，

package/lib/types/types.d.ts

@@ -1,4 +1,15 @@
 /** 稳定错误码/错误类型的定义在 src/client/types.ts（client 半边声明构建的 rootDir 内）。
- *  此处仅为 Host 半边（orchestration / ai-router-client）提供同源的类型再导出，
+ *  此处为 Host 半边（orchestration / ai-router-client）提供同源的类型再导出 + 宿主专属类型，
  *  避免两份定义漂移；声明构建时各自 emit 到 lib/types 对应位置。 */
 export type { LoginError, LoginErrorCode } from './client/types.ts';
+/** GET /api/auth/sessions 的一项：当前账号的一台登录设备（网关 sessions 表投影）。 */
+export interface DeviceSession {
+    id: string;
+    device_name: string;
+    platform: string;
+    app_version: string;
+    client_ip: string;
+    created_at: string;
+    last_seen_at?: string | null;
+    current: boolean;
+}