@eddyskywalker/dsh-chatgpt-subscription 0.31.0 → 0.33.0

package/lib/types/host/qoder/adapter.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Qoder（订阅）线路的 DSH 适配器。
+ *
+ * 形状与 Step Code / GLM 同构（\`extends LlmAdapter\`：listModels / resolveModel /
+ * prepareCall / stream / catalog / credentialFor），但它**不碰任何协议细节**：
+ *
+ * - 请求体、流解析、用量与错误分类全部来自 \`./mapper.ts\`；
+ * - COSY 签名与 body 编码全部来自 \`./cosy.ts\`；
+ * - URL 与目录缓存全部来自 \`./client.ts\`；
+ * - 目录的归一化全部来自 \`./model-catalog.ts\`。
+ *
+ * 也就是说本文件只回答三件事：**这一行请求用哪个目录行**、**用哪把凭据**、
+ * **失败之后换不换账号**。任何一份签名、编码或 JSON 解析在这里出现第二遍，
+ * 就等于给线路造了第二条会漂移的真相。
+ *
+ * 三处刻意如此：
+ *
+ * 1. **凭据只在 \`credentialFor()\` 一处取。** 有号池时轮转（核心自己处理刷新），
+ *    没有池时读单凭据存储（无头 host 与测试的形态）。
+ * 2. **请求路径不联网。** 目录只读 \`client.ts\` 的进程内缓存，随包目录兜底；
+ *    实时目录是 \`/catalog/refresh\` 与登录/adopt 的产物。
+ * 3. **缓存用量在本进程累计。** 累计器住在本文件（流的末端是唯一知道用量帧的地方），
+ *    \`/status\` 由 \`readQoderCacheStats()\` 读它；路由不另算第二套口径。
+ */
+import { LlmAdapter, type GenerateOptions, type LlmModelInfo, type LlmProviderInfo, type LlmResolvedModelInfo, type PreparedAdapterCall, type ResolvedRetryPolicy, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import { type AttachmentImageReader } from '../common/request-images.ts';
+import { clearCachedQoderModelCatalog, type QoderUpstreamCredential } from './client.ts';
+import { type QoderModelEntry } from './model-catalog.ts';
+import { QoderCredentialStore, QoderModelSettingsStore, type QoderPreferenceStore } from './token-store.ts';
+import type { QoderAccountPool } from './account-pool.ts';
+import { PROVIDER_ID, PROVIDER_NAME } from './types.ts';
+import type { QoderCacheStatsDto, QoderRegion } from '../../shared/qoder-contracts.ts';
+/**
+ * 这条路由的瞬时故障重试策略，与兄弟线路逐字一致。
+ *
+ * 刻意不在集合里：AUTH（被拒的 token 每次都一样，而它只能重新授权）、
+ * PROVIDER_ERROR（400 或套餐拒绝）、ABORTED（调用方自己取消）。
+ */
+export declare const QODER_RETRY_POLICY_CONFIG: {
+    mode: 'normal';
+    maxRetries: number;
+    retryableCodes: string[];
+    backoff: {
+        initialDelayMs: number;
+        maxDelayMs: number;
+        jitterRatio: number;
+    };
+};
+/** 上游没有给 Retry-After 时，一次 429 按 5 分钟冷却。 */
+export declare const QODER_POOL_COOLDOWN_MS: number;
+/**
+ * 这个部署能调的模型：**进程内缓存优先、随包目录兜底，请求路径上绝不联网**。
+ *
+ * 实时目录只由 \`/catalog/refresh\` 与登录/adopt 产生（见 routes.ts）；
+ * 让每一次模型解析都去打上游只会把设置页变成一条压测。
+ */
+export declare function cachedQoderModelCatalog(region: QoderRegion): readonly QoderModelEntry[];
+/** 设置卡片渲染的模型总数（hub 概览与状态共用同一份读数；取两区随包表的较大者）。 */
+export declare function qoderCatalogSize(): number;
+/** 记下一次请求的用量（流读到终止帧之后调用）。 */
+export declare function rememberQoderCacheUsage(usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}): void;
+/**
+ * 卡片要的那份切片；**尚无样本时返回 undefined**。
+ *
+ * 「还没有样本」与「样本全都没命中」必须能被区分：契约里 \`cacheStats\` 是可选的，
+ * 客户端把缺失渲染成占位符、把 0 渲染成真实的 0%，所以这里绝不下发一个全 0 的对象。
+ */
+export declare function readQoderCacheStats(): QoderCacheStatsDto | undefined;
+/** 一行请求要用的凭据：发请求只需要 client.ts 认得的那份切片。 */
+export interface QoderPickedCredential {
+    /** 号池里的账号 id；无池（单凭据路径）时为 null。 */
+    accountId: string | null;
+    credentials: QoderUpstreamCredential;
+}
+export interface QoderAdapterOptions {
+    fetchFn?: typeof fetch;
+    attachments?: AttachmentImageReader;
+    /** 多账号号池；缺省走单凭据路径（无头 host 与测试）。 */
+    accountPool?: QoderAccountPool;
+}
+/**
+ * Qoder（订阅）线路的 LlmAdapter 实现。
+ *
+ * 请求面只有一个：COSY 签名的 SSE 对话端点（两区同一协议面，区域由凭据决定），
+ * 所以本文件里**没有**协议面判定——URL 由 client.ts 从凭据的区域得出。
+ */
+export declare class QoderAdapter extends LlmAdapter {
+    private readonly store;
+    private readonly modelSettings;
+    private readonly preferences;
+    private readonly accountPool;
+    private readonly options;
+    constructor(store?: QoderCredentialStore, modelSettings?: QoderModelSettingsStore, preferences?: QoderPreferenceStore, options?: QoderAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(): ResolvedRetryPolicy;
+    imageRequestPricing(): undefined;
+    imageRequestTarget(_provider: string, _model: string, image: ImageAttachmentRef): {
+        width: number;
+        height: number;
+        maxBytes: number;
+    };
+    private settings;
+    /** 这个部署的目录行（缓存优先，请求路径不联网）。 */
+    private catalog;
+    /**
+     * 这一行请求用哪份凭据。
+     *
+     * 有池时轮转（核心自己做刷新）；没有池时读单凭据存储（无头 host 与测试的形态）。
+     */
+    private credentialFor;
+    listModels(provider?: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * 一次请求的完整往返：选账号 → 定目录行 → 编码+签名 → 发 → 解析信封流。
+     *
+     * 账号轮转的循环只有一处：一次 429 或一次 AUTH 会把那个账号移出本次请求，
+     * 由另一个账号来发**同一份**请求体。没有池时这个循环只跑一次。
+     *
+     * 编码与签名的顺序是协议事实（inference-protocol.md §3-§4）：先 JSON.stringify
+     * 一次拿到字节，codec 编码这同一份字节，签名覆盖编码后的字符串——任何中间的
+     * 一道 re-marshal 都会让签名的字节与发送的字节漂移。
+     */
+    private requestStream;
+}
+export { clearCachedQoderModelCatalog, PROVIDER_ID, PROVIDER_NAME };
+//# sourceMappingURL=adapter.d.ts.map

package/lib/types/host/qoder/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/host/qoder/adapter.ts"],"names":[],"mappings":"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"}

package/lib/types/host/qoder/adopt.d.ts

@@ -0,0 +1,146 @@
+/**
+ * adopt：只读导入本机已登录的 qodercli 客户端登录态。
+ *
+ * 上游落盘事实全部来自 qodercli2api \`docs/oauth.md\` §4（格式由它的 frozen fixture
+ * \`credential.json\` 逐字节锁定，\`test/qoder-adopt.test.ts\` 用同一 fixture 驱动）：
+ *
+ * - 路径：\`~/.qoder/.auth/machine_id\`（36 字符 UUID）与 \`~/.qoder/.auth/user\`；
+ * - 信封：strict standard padded Base64；明文是 UserInfo 的 UTF-8 JSON；
+ * - key：\`machine_id\` 前 16 个字符的 **raw UTF-8 字节**（不是 hex/base64 解码值）；
+ * - cipher：AES-128-CBC，IV 与 key 相同，PKCS#7 严格校验；
+ * - 兼容：去除外围空白后以 \`{\` 开头的内容按明文 JSON 解析。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 1 —— 本模块永不写入。它是 reader，而且只是 reader。
+ * ---------------------------------------------------------------------------
+ * 不得创建、修改、移动或删除任何属于 qodercli 的文件。保证是**结构性**的：
+ * 本模块从 node:fs/promises **按名**只导入 readFile 与 stat 两个函数
+ * （与 step-code 的 adopt.ts 同一条规则、同一个理由）。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 2 —— 存在性与内容分成两个函数。
+ * ---------------------------------------------------------------------------
+ * \`qoderAdoptPresence()\` 便宜到可以在插件启动时调用，只 stat、从不 open；
+ * \`adoptQoderSignIn()\` 才是完整读取，且只在用户显式选择之后才被调用。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 3 —— 认不出来的形状永远给一个**值**，永远不给异常。
+ * ---------------------------------------------------------------------------
+ * 没有文件、读不了、解密失败、不是 JSON、里面没有 token、两区都不认——全部落在
+ * QoderAdoptResultDto 的 reason 枚举里。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 4 —— **区域不猜，是探出来的**。
+ * ---------------------------------------------------------------------------
+ * 区域是凭据的属性，而 qodercli 的凭据文件**不记录区域**（格式里没有这个字段）。
+ * 所以 adopt 拿解密后的 token 对两区的 userinfo 各探一次（只读 GET），哪区认
+ * 就是哪区；两区都不认（token 已失效或被撤销）归为 \`region-unresolved\`——
+ * 让用户重新登录，而不是替他决定一个必然 401 的区域（计划 §9 风险 5）。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 5 —— 快照，不是活凭据。
+ * ---------------------------------------------------------------------------
+ * adopt 进来的是一份**快照**：qodercli 那边之后的刷新不会流回来；本插件拿着
+ * 快照里的 refresh_token 走自己的刷新链，两边从此各刷各的。
+ */
+import { type QoderAdoptResultDto } from '../../shared/qoder-contracts.ts';
+import { QODER_CLI_CREDENTIAL_SOURCE, type QoderCredentials } from './token-store.ts';
+/** 显式指定 qodercli 凭据文件路径的环境变量（测试与嵌入式宿主的口子；非官方变量）。 */
+export declare const QODER_AUTH_PATH_ENV = "QODER_CLI_AUTH_PATH";
+/** 显式指定 qodercli machine_id 路径的环境变量（同上）。 */
+export declare const QODER_MACHINE_ID_PATH_ENV = "QODER_CLI_MACHINE_ID_PATH";
+/** qodercli 的家目录（HOME / USERPROFILE 再退到 os.homedir()，与兄弟线路同一口径）。 */
+export declare function qoderCliHomeDir(env?: NodeJS.ProcessEnv): string;
+/** qodercli 的凭据文件路径。 */
+export declare function qoderCliAuthPath(env?: NodeJS.ProcessEnv): string;
+/** qodercli 的 machine_id 文件路径。 */
+export declare function qoderCliMachineIdFilePath(env?: NodeJS.ProcessEnv): string;
+/** adopt 成功时带走的凭据：凭据 + 它是从哪个文件捡来的。 */
+export interface QoderAdoptedCredential {
+    /** 池里的判别式，恒为 true。 */
+    readonly adopted: true;
+    /** 来源标识，供卡片与池记录。 */
+    readonly source: typeof QODER_CLI_CREDENTIAL_SOURCE;
+    /** 读到的确切路径，卡片可以把它显示给用户。 */
+    readonly sourcePath: string;
+    /** 本线路的凭据形态。 */
+    readonly credentials: QoderCredentials;
+}
+/** adopt 失败原因，直接取自冻结契约的 QoderAdoptResultDto['reason']，不另立一套。 */
+export type QoderAdoptReason = NonNullable<QoderAdoptResultDto['reason']>;
+/**
+ * 每个失败原因对应的一句可照做的下一步。
+ *
+ * 五个取值各自的下一步不同，所以分开写而不是拼一句「导入失败」。
+ */
+export declare const ADOPT_REASON_HINTS: Readonly<Record<QoderAdoptReason, string>>;
+/** 解析一份已解密的 UserInfo 的结论：要么带凭据材料，要么带一个 reason。 */
+export type QoderAdoptParse = {
+    readonly ok: true;
+    readonly material: QoderAdoptMaterial;
+} | {
+    readonly ok: false;
+    readonly reason: QoderAdoptReason;
+};
+/**
+ * 从 UserInfo 里读出的凭据材料（区域还没定：格式里没有这个字段，见规则 4）。
+ */
+export interface QoderAdoptMaterial {
+    accessToken: string;
+    refreshToken: string | null;
+    expiresAt: number;
+    uid: string | null;
+    email: string | null;
+    accountName: string | null;
+    organizationId: string | null;
+    organizationTags: string[];
+    dataPolicyAgreed: boolean;
+}
+/**
+ * 把一份已解密的 UserInfo JSON 解析成凭据材料。
+ *
+ * 纯函数、导出：格式规则可以脱离文件系统与网络被测试。
+ *
+ * 字段逐字按 qodercli2api 的 fixture 与 pi-provider 的 UserInfo 形状读取，全部按
+ * 「可能缺失」处理（计划 §9 风险 5：这份载荷没有逐字 schema）：
+ *
+ * - \`access_token\`（fixture 明文里有）优先，\`security_oauth_token\` 兜底
+ *   （docs/oauth.md §6：OpenAPI 鉴权用 \`security_oauth_token ?? access_token\`）；
+ * - \`refresh_token\`、\`uid\`、\`name\`、\`email\`、\`organization_id\`、
+ *   \`organization_tags\`、\`data_policy_agreed\`、\`expire_time\` 都可能没有。
+ */
+export declare function parseQoderAdoptedUserInfo(value: unknown): QoderAdoptParse;
+/**
+ * 本机有没有可导入的 qodercli 登录态（凭据文件 + machine_id 都在才算）。
+ *
+ * 启动路径安全：它**从不**打开候选文件去读（同 step-code adopt 的那条规则）。
+ */
+export declare function qoderAdoptPresence(env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** 一次 adopt 的结论：给卡片的切片 + （成功时）真正要落盘的凭据。 */
+export interface QoderAdoptOutcome {
+    /** 卡片渲染用；不含任何凭据。 */
+    readonly result: QoderAdoptResultDto;
+    /** 成功时才有：带来源标记的凭据，交给号池或凭据存储落盘。 */
+    readonly adopted?: QoderAdoptedCredential;
+    /** 实际读到的文件（设置卡片要把它显示出来）。 */
+    readonly sourcePath?: string;
+}
+export interface QoderAdoptOptions {
+    /** 环境变量读取处；缺省 process.env，且**调用时**读取。 */
+    env?: NodeJS.ProcessEnv;
+    /** 区域探测的请求缝（测试注入 mock fetch）。 */
+    fetchFn?: typeof fetch;
+}
+/**
+ * 只读导入本机 qodercli 登录态。
+ *
+ * **只在用户显式 opt in 之后调用**（见模块头规则 2）。永不抛出、永不拒绝。
+ *
+ * 区域探测（规则 4）：拿解密后的 token 依次对 global、cn 的 userinfo 发只读 GET，
+ * 第一个认账的区域获胜；两区都不认 → \`region-unresolved\`。探测只认「请求成功」，
+ * 任何网络/鉴权失败都记为不认账——探测的目的是定位，不是诊断。
+ */
+export declare function adoptQoderSignIn(options?: QoderAdoptOptions): Promise<QoderAdoptOutcome>;
+/** 只要那张给卡片的切片（不带走凭据）。 */
+export declare function readQoderAdoptResult(options?: QoderAdoptOptions): Promise<QoderAdoptResultDto>;
+//# sourceMappingURL=adopt.d.ts.map

package/lib/types/host/qoder/adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../../../../src/host/qoder/adopt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAMH,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iCAAiC,CAAA;AAQxC,OAAO,EAAsB,2BAA2B,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAMzG,oDAAoD;AACpD,eAAO,MAAM,mBAAmB,wBAAwB,CAAA;AAExD,4CAA4C;AAC5C,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AAEpE,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG5E;AAED,wBAAwB;AACxB,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAI7E;AAED,kCAAkC;AAClC,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAItF;AAcD,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACrC,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,oBAAoB;IACpB,QAAQ,CAAC,MAAM,EAAE,OAAO,2BAA2B,CAAA;IACnD,2BAA2B;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,gBAAgB;IAChB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAA;CACvC;AAED,gEAAgE;AAChE,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAA;AAEzE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAWzE,CAAA;AAED,kDAAkD;AAClD,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAA;AAE7D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAqBzE;AAeD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/F;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IACpC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAA;IACzC,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,iCAAiC;IACjC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAuF5B;AAED,yBAAyB;AACzB,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAE9B"}

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

@@ -0,0 +1,189 @@
+/**
+ * Qoder（订阅）线路的上游 I/O：模型目录 + 额度 + userinfo + PAT 兑换 + 令牌刷新。
+ *
+ * 本文件只做两件事：**把请求发到上游**，以及**把上游的载荷翻译成本线路的形状**。
+ * 对话传输（编码 body、拆信封流）不在这里——那是 mapper.ts / adapter.ts 的活。
+ *
+ * ---------------------------------------------------------------------------
+ * 三条必须记住的上游事实（逐字证据在每处注释里）
+ * ---------------------------------------------------------------------------
+ *
+ * 1. **目录与对话都要 COSY 签名。** 模型列表是一个带 COSY 头的 GET（无 body；
+ *    签名里 body 分量是空串）。OpenAPI 面（PAT 兑换 / userinfo / 额度 / 设备轮询）
+ *    是 plain Bearer，不签名（pi-provider 的全部 openapi 调用一致）。
+ * 2. **COSY 版本落后会拿到缩减目录。** 版本每日跟随 Qoder CLI 的 release feed
+ *    （pi-provider cosy-version.ts 同一设计），失败回落随包版本。
+ * 3. **额度失败绝不影响模型请求。** 额度是非公开个人端点（计划 §5、§9 风险 1），
+ *    它的一切都返回**值**（QoderQuotaRead），没有一条路径把错误抛给调用方之外的边界。
+ *
+ * ---------------------------------------------------------------------------
+ * 注入缝
+ * ---------------------------------------------------------------------------
+ * 每个网络函数都接受 fetchFn（默认 fetch）与 env（默认 process.env），且 env
+ * **在调用时**读取（不是模块加载时），这样单测不碰真实网络也不碰真实凭据。
+ */
+import type { QoderQuotaSnapshotDto, QoderRegion } from '../../shared/qoder-contracts.ts';
+import { type QoderCosyIdentity } from './cosy.ts';
+import { type QoderModelEntry } from './model-catalog.ts';
+export interface QoderRequestOptions {
+    /** 测试缝。默认 fetch。 */
+    fetchFn?: typeof fetch;
+    signal?: AbortSignal;
+    /** 环境变量读取处。默认 process.env，且**调用时**读取。 */
+    env?: NodeJS.ProcessEnv;
+}
+/** 错误详情去控制字符并截断（卡片与日志共用同一口径）。 */
+export declare function qoderErrorDetail(text: string, limit?: number): string;
+/**
+ * 本线路发上游请求需要的那份凭据切片。
+ *
+ * 这是**号池凭据的结构化超集**：account-pool.ts 的 QoderCredentials 加了来源与
+ * 落盘字段，而本文件的每个函数都能直接吃号池交出来的凭据，而不必认识池。
+ */
+export interface QoderUpstreamCredential {
+    readonly accessToken: string;
+    readonly region: QoderRegion;
+    readonly uid: string | null;
+    readonly email: string | null;
+    readonly accountName: string | null;
+    readonly organizationId?: string | null;
+    readonly organizationTags?: readonly string[];
+    readonly dataPolicyAgreed?: boolean;
+}
+/**
+ * 凭据切片 → COSY 身份。
+ *
+ * UserInfo 的字段顺序**固定**（uid / security_oauth_token / name / aid / email，
+ * 逐字 pi-provider \`cosy.ts\` 的 UserInfo 形状）：它原样进 AES 明文，而官方算法
+ * 对 raw 字符串原样处理（docs/oauth.md §5），所以这里手写键序而不是 JSON.stringify
+ * 一个对象——后者的键序是实现细节，不是协议事实。
+ */
+export declare function qoderCosyIdentityOf(credentials: QoderUpstreamCredential, env?: NodeJS.ProcessEnv): QoderCosyIdentity;
+/** OpenAPI 面请求的头（plain Bearer，不签名；逐字 pi-provider pat.ts 的头集）。 */
+export declare function qoderOpenapiHeaders(credentials: {
+    accessToken: string;
+}): Record<string, string>;
+/** 一个值是不是合法的 x.y.z 版本串。 */
+export declare function isQoderCliVersion(value: unknown): value is string;
+/** x.y.z 的数字比较。 */
+export declare function compareQoderCliVersions(a: string, b: string): number;
+/**
+ * 当前签名用的 COSY 版本：缓存里更新的 CLI release 优先，否则随包回落。
+ * 同步且**无网络**；刷新发生在 {@link refreshQoderCosyVersion}。
+ */
+export declare function getQoderCosyVersion(): string;
+/**
+ * 跟随 Qoder CLI 的最新 release（每日最多一次，失败完全容忍）。
+ *
+ * 逐字 pi-provider \`refreshGatewayCosyVersion\` 的设计：网关给 COSY 版本落后的客户端
+ * 发**缩减的**模型目录，所以签名身份要跟着 CLI 走；但任何失败（离线、坏载荷、更旧的
+ * tag）都回落到既有版本——签名绝不依赖这次 fetch 成功。
+ */
+export declare function refreshQoderCosyVersion(options?: QoderRequestOptions & {
+    force?: boolean;
+}): Promise<void>;
+/** 测试用：清掉进程内版本缓存。 */
+export declare function clearQoderCosyVersionCache(): void;
+/** 模型列表 URL。 */
+export declare function qoderModelListUrl(region: QoderRegion, env?: NodeJS.ProcessEnv): string;
+/** 对话 URL（adapter 用；拼在这里，全局只有这一处）。 */
+export declare function qoderChatUrl(region: QoderRegion, env?: NodeJS.ProcessEnv): string;
+/**
+ * 目录里的一条模型（host 内部形状 = 能力行；只含端点真的报了的字段装配出来的结果）。
+ * 与 step-code 的 StepCodeCatalogEntry 不同：本线路的解析直接产出能力行
+ * （{@link parseQoderModelListing}），缓存里放的就是它。
+ */
+export type QoderCatalogEntry = QoderModelEntry;
+/** 无凭据 / 失败 / 离线时目录为空：调用方回落随包表，而不是抛错。 */
+export declare function fetchQoderModelCatalog(credentials: QoderUpstreamCredential, options?: QoderRequestOptions): Promise<QoderCatalogEntry[]>;
+/** 本进程当前记住的目录（纯内存读，不触发任何网络请求）。 */
+export declare function getCachedQoderModelCatalog(region?: QoderRegion): readonly QoderCatalogEntry[];
+/** 清掉内存目录、快照 scope 与在飞的去重。 */
+export declare function clearCachedQoderModelCatalog(): void;
+/**
+ * TTL 缓存 + in-flight 去重 + 磁盘快照的目录读取（三层各解决一件事，
+ * 照抄 step-code/client.ts 的同名结构）：
+ *
+ * - **TTL**：目录不是快变数据；
+ * - **in-flight 去重**：同一个区域上并发的两个调用共用一次请求；
+ * - **磁盘快照**（catalog-snapshot.ts）：冷启动不等网络；快照按区域分文件。
+ *
+ * force: true 跳过缓存与快照直接重取（设置卡片的「刷新」按钮用）。
+ */
+export declare function loadQoderModelCatalog(credentials: QoderUpstreamCredential, options?: QoderRequestOptions & {
+    force?: boolean;
+}): Promise<QoderCatalogEntry[]>;
+/** 上游 userinfo 的账号事实。 */
+export interface QoderUserInfo {
+    userID: string;
+    email: string;
+    name: string;
+    organizationId?: string;
+    organizationTags?: string[];
+    dataPolicyAgreed?: boolean;
+}
+/**
+ * GET {openapi}/api/v1/userinfo（Bearer job token；best-effort 字段读取，
+ * 逐字 pi-provider pat.ts \`fetchUserInfo\` 的字段名）。
+ *
+ * 失败**抛错**（与目录不同）：调用方是登录/刷新路径，一把读不出 userinfo 的 token
+ * 在 CN 会被推理面拒成「Login expired」（105），让调用方知道比静默兜底诚实。
+ */
+export declare function fetchQoderUserInfo(accessToken: string, region: QoderRegion, options?: QoderRequestOptions): Promise<QoderUserInfo>;
+/** PAT 兑换的返回值。 */
+export interface QoderJobTokenExchange {
+    /** 短期 job token（\`jt-...\`）。 */
+    token: string;
+    /** job refresh token（\`jrt-...\`）；上游没给时为 null。 */
+    refreshToken: string | null;
+    /** 过期时刻（Unix 毫秒，已含安全边）。 */
+    expiresAt: number;
+}
+/**
+ * POST {openapi}/api/v1/jobToken/exchange，体 \`{"personal_token":"<pt-...>"}\`。
+ *
+ * PAT 不能直接鉴权，必须先兑换（docs.qoder.com/cli/authentication + pi-provider pat.ts）。
+ * 失败抛错（登录路径要如实告诉用户 PAT 被拒）。
+ */
+export declare function exchangeQoderJobToken(personalToken: string, region: QoderRegion, options?: QoderRequestOptions): Promise<QoderJobTokenExchange>;
+/**
+ * POST {center}/algo/api/v3/user/refresh_token（Bearer access + \`{"refreshToken"}\`）。
+ *
+ * 逐字 pi-provider \`refreshQoderTokenForMode\` 的请求形状（live 验证）。
+ * 失败抛错由调用方（号池的 refresh 钩子）分类。
+ */
+export declare function refreshQoderAccessToken(credentials: {
+    accessToken: string;
+    refreshToken: string;
+}, region: QoderRegion, options?: QoderRequestOptions): Promise<QoderJobTokenExchange>;
+/** 一次额度读取的结果；失败以值返回而不是抛出（路由据此下发 quotaError）。 */
+export type QoderQuotaRead = {
+    ok: true;
+    snapshot: QoderQuotaSnapshotDto;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 归一化一份额度载荷。
+ *
+ * 一只桶都不认识时返回 undefined（上游改版或账号没有套餐）——快照不下发，
+ * 卡片显示「读不出来」而不是一张全空的卡。缺失的数字保持缺失，**绝不发明**
+ * （技能规约「零不是未知」）。
+ */
+export declare function normalizeQoderQuotaSnapshot(value: unknown, region: QoderRegion, fetchedAt?: number): QoderQuotaSnapshotDto | undefined;
+/** 某账号最近一次读到的额度快照（纯内存读；号池装配摘要时用）。 */
+export declare function getCachedQoderQuotaFor(accountId: string): QoderQuotaSnapshotDto | undefined;
+/** 测试与登出用：清掉内存额度缓存。 */
+export declare function clearCachedQoderQuota(): void;
+/**
+ * GET {openapi}/api/v2/quota/usage（Bearer job token）。
+ *
+ * ⚠ 非公开个人端点（计划 §5、§9 风险 1）。TTL 缓存 + 在飞去重；失败以值返回。
+ * \`cacheKey\` 是号池账号 id：快照记在**账号**名下，额度跟着账号走。
+ */
+export declare function loadQoderQuota(credentials: QoderUpstreamCredential, options?: QoderRequestOptions & {
+    force?: boolean;
+    cacheKey?: string;
+}): Promise<QoderQuotaRead>;
+//# sourceMappingURL=client.d.ts.map

package/lib/types/host/qoder/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/host/qoder/client.ts"],"names":[],"mappings":"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"}