@eddyskywalker/dsh-chatgpt-subscription 0.32.0 → 0.34.0

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

@@ -0,0 +1,119 @@
+/**
+ * Qoder（订阅）线路的 web 路由。
+ *
+ * 路由表与客户端 \`src/client/qoder/api.ts\` 里那一份是**同一个约定**，两边必须逐条对上：
+ *
+ * \`\`\`
+ * GET  /status           -> QoderStatusDto（页面的唯一读口）
+ * POST /settings         QoderSettingsUpdateDto -> QoderStatusDto
+ * POST /accounts         { action, accountId } / { action:'strategy', strategy } -> QoderStatusDto
+ * POST /login/start      { region } -> QoderLoginFlowStatus（设备流，仅全球区）
+ * GET  /login/status     -> QoderLoginFlowStatus
+ * POST /login/cancel     { } -> QoderLoginFlowStatus
+ * POST /login/manual     { region, token } -> QoderStatusDto（请求体带 PAT，不在冻结契约里）
+ * POST /adopt            { } -> QoderAdoptResultDto（裸 DTO；失败永不阻断）
+ * POST /connection/test  { } -> QoderConnectionDto（裸 DTO）
+ * POST /quota            { } -> QoderStatusDto（强制刷新额度）
+ * POST /catalog/refresh  { } -> QoderStatusDto
+ * \`\`\`
+ *
+ * 信封：除 \`/adopt\` 与 \`/connection/test\` 外一律 \`{ ok, value }\`（客户端的
+ * \`createLineApi\` 会把信封拆掉；那两条路由的契约把 DTO 定在顶层，所以它们直接返回 DTO）。
+ *
+ * 同源校验不可省：每个 POST 都过 \`isSameOriginMutation\`，与兄弟线路同一份实现。
+ *
+ * 本文件**不持有任何凭据，也不算任何用量**：落盘与刷新交给 token-store / account-pool /
+ * oauth / adopt，上游 I/O 交给 client.ts，缓存用量的累计是 adapter.ts 的累计器。
+ * 它只做三件事：读设置、组装状态面、把同源的 POST 翻译成对上面那些模块的一次调用。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AccountRotationStrategy } from '../../shared/account-pool-contracts.ts';
+import { type QoderAccountSummaryDto, type QoderCacheStatsDto, type QoderQuotaSnapshotDto, type QoderRegion, type QoderStatusDto } from '../../shared/qoder-contracts.ts';
+import { type QoderAccountPool } from './account-pool.ts';
+import { type QoderModelEntry } from './model-catalog.ts';
+import { QoderModelSettingsStore, type QoderModelSettings, type QoderPreferenceStore, type QoderSettingsPatch } from './token-store.ts';
+/** 一个请求寻址的子路径（剥掉契约前缀）。 */
+export declare function qoderSubPathOf(requestUrl: string): string;
+/**
+ * 设置来源：register 后端与文件后端形状不同，这里收敛成一个（与 step-code 同形）。
+ */
+export interface QoderSettingsSource {
+    status(): QoderModelSettings | Promise<QoderModelSettings>;
+    update(patch: QoderSettingsPatch): Promise<QoderModelSettings>;
+}
+/** 设置来源：register 后端优先，没有就落回凭据旁边的 JSON 文件。 */
+export declare function qoderSettingsSource(preferences: QoderPreferenceStore | undefined, fallback: QoderModelSettingsStore): QoderSettingsSource;
+export interface QoderRouteOptions {
+    fetchFn?: typeof fetch;
+    /** 本插件是否正在服务这条 Provider 路由；每次状态都重新读。 */
+    serving?: boolean | (() => boolean);
+    /** 路由被别的适配器占用时的诊断文案；每次状态都重新读。 */
+    conflict?: string | null | (() => string | null);
+    /** 号池；本进程装了才有。 */
+    accountPool?: QoderAccountPool;
+    /** 环境变量读取处；缺省 process.env，且**调用时**读取。 */
+    env?: NodeJS.ProcessEnv;
+}
+/** 号池切片的收紧形状（本线路状态面实际持有的那一部分）。 */
+export interface QoderPoolSlice {
+    accounts: QoderAccountSummaryDto[];
+    rotationStrategy: AccountRotationStrategy;
+    activeAccountId?: string;
+}
+export interface QoderStatusSources {
+    options: QoderRouteOptions;
+    settings: QoderSettingsSource;
+    /** 下一次登录要用的区域。 */
+    region: QoderRegion;
+    /** 号池切片：唯一装配它的地方是 account-pool 的 qoderPoolStatusSlice（这里只收紧形状）。 */
+    pool: QoderPoolSlice;
+    /** 本次读到的账号（卡片渲染用，不带任何凭据）。 */
+    account: QoderAccountSummaryDto | null;
+    /** 这个部署当前的模型目录（缓存读，轮询不联网）。 */
+    catalog: readonly QoderModelEntry[];
+    /** 本进程为当前账号记住的额度快照。 */
+    quota: QoderQuotaSnapshotDto | null;
+    /** 本次应答背后是否正在刷新额度。 */
+    quotaRefreshing: boolean;
+    /** 本次应答背后是否正在刷新模型目录（客户端据此排一次补读）。 */
+    catalogRefreshing: boolean;
+    /** 上一次额度读失败的原因；没有快照可渲染时为 null。 */
+    quotaError: string | null;
+    /** 本进程累计的缓存用量；尚无样本时为 undefined（客户端据此渲染占位符）。 */
+    cacheStats: QoderCacheStatsDto | undefined;
+}
+/**
+ * 组装 \`QoderStatusDto\`。
+ *
+ * 号池读不出来不能带倒整张卡：连接那一半仍然值得渲染，只是账号列表是空的。
+ */
+export declare function getQoderStatus(sources: QoderStatusSources): Promise<QoderStatusDto>;
+/**
+ * 注册本线路的路由。
+ *
+ * 本文件不持有凭据：账号的落盘与轮转在号池，凭据由号池镜像。
+ * 设置的唯一写入点是 \`POST /settings\`。
+ */
+export declare function registerQoderRoutes(ctx: Context, settings: QoderSettingsSource, options?: QoderRouteOptions): () => void;
+/**
+ * 插件启动时的一次目录预热（**非阻塞**，调用方不许 await）。
+ *
+ * 解决的问题见 client.ts 的 {@link warmQoderModelCatalog}：`cachedCatalog` 是进程内
+ * 的，宿主重启后它是空的，而磁盘快照里明明躺着上一次的真实目录；在用户第一次打开
+ * 设置页之前，`adapter.listModels` 读到的就是随包兜底表（15 条缺省模型），模型
+ * 选择器于是先把这一大片假模型摊出来，点一下设置页才恢复正常。
+ *
+ * 这里是**宿主侧的那一层**，它做三件 client.ts 不该知道的事：
+ *
+ * 1. **凭据从号池来**（`getQuotaReadTarget`，与 `refreshCatalog` 同一个入口）：
+ *    目录是区域的属性，而哪个区域要看池里当前该展示的那一行。没有池、池里没有账号、
+ *    取凭据失败——三种情况都安静返回，不预热，**不报错**。
+ * 2. **对比预热前后的指纹**，只有目录真的换了才发 `llm/adapters-updated`：这条与
+ *    `refreshCatalogAndAnnounce` 是同一条判词（client.ts 的 qoderCatalogFingerprint），
+ *    否则「目录变了没有」会在两条路径上给出两个答案。绝大多数启动里快照与上游一致，
+ *    一次事件都不发。没有快照时变化当场就发生；有快照时预热不等网络，变化是晚到的，
+ *    由 {@link observeQoderCatalogChange} 补发（两边都以同一份指纹为基线，不会重复）。
+ * 3. **全程吞错**：预热是尽力而为，它没有资格让插件装载或首次状态应答失败。
+ */
+export declare function warmQoderCatalogOnStartup(ctx: Context, options?: QoderRouteOptions): Promise<void>;
+//# sourceMappingURL=routes.d.ts.map

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

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

package/lib/types/host/qoder/token-store.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Qoder（订阅）线路的凭据 / 模型设置 / 偏好三件套。
+ *
+ * 本线路的凭据与 step-code 相反的那个性质先说清楚，因为它决定了本文件的设计：
+ *
+ * **凭据会过期、可刷新。** Qoder 的 job/device token 带着 `expires_at` / `expires_in`
+ * （pi-provider `pat.ts` / `login.ts`；qodercli2api `docs/oauth.md` §3）。所以：
+ *
+ * - 本文件**有** refresh 相关的一切（过期时刻、提前刷新量、刷新输入的留存）；
+ * - PAT 来源的凭据**留住 PAT 本体**（host-only，绝不进共享契约），因为 PAT 的
+ *   「刷新」就是拿它重新兑换一把 job token（pi-provider `oauth.ts` 的
+ *   `isPatRefresh` 路径同一做法）；
+ * - 号池的 `expiresAt`/`needsRefresh`/`refresh` 钩子都是活的，
+ *   刷新失败按 401/403 → expired、其余 → 瞬时 分类（account-pool.ts）。
+ *
+ * 第二件必须记住的事：**本线路自己拥有它的凭据副本，但从不拥有 qodercli 的文件**。
+ * adopt 只是把 `~/.qoder/.auth/user` 读成一份快照存进本插件自己的凭据存储
+ * （`adopt.ts` 只读、不写、不删）。落盘的 adopt 凭据带 `adopted / source / sourcePath`
+ * 三个判别式字段，与其它线路的 adopt 语义一致。
+ *
+ * 三件套的分工与兄弟线路一致：凭据走 DPAPI / Keychain / Secret Service；
+ * 模型设置是明文 JSON，带写后回读校验；偏好在 harness 还提供 register 接缝时注册进
+ * 设置文档，没有就落回那个 JSON 文件。
+ */
+import type { CredentialStore } from '../token-store.ts';
+import { type ContextWindowOverridePatch } from '../common/context-window-overrides.ts';
+import type { QoderReasoningEffort, QoderRegion } from '../../shared/qoder-contracts.ts';
+import { listModelIds } from './model-catalog.ts';
+/** 本线路在设置文档里注册的命名空间。 */
+export declare const QODER_PREFERENCES_NAMESPACE = "dsh-qoder";
+/**
+ * 这份凭据是从哪条路来的。
+ *
+ * - `device`：浏览器设备流（仅全球区）。
+ * - `pat`：用户手动粘贴的 Personal Access Token 兑换来的 job token。
+ * - `adopt`：从本机 qodercli 客户端读来的登录态快照。
+ *
+ * 它与 `region` 是**两件事**：`region` 决定打哪套端点，`origin` 决定这份东西
+ * 怎么刷新（PAT 重兑换 vs refresh_token）以及本插件能不能对它做任何写操作。
+ */
+export type QoderCredentialOrigin = 'device' | 'pat' | 'adopt';
+/** 本线路读 qodercli 登录态时的来源标记（与兄弟线路的 adopt 判别式同构）。 */
+export declare const QODER_CLI_CREDENTIAL_SOURCE = "qoder-cli";
+/**
+ * 一份可服务请求的 Qoder 凭据。
+ *
+ * 真正发请求只用 `accessToken`（Bearer + COSY 载荷里的 `security_oauth_token`）。
+ * 其余字段分四类：
+ *
+ * - **刷新输入**（`refreshToken` / `expiresAt` / `personalToken`）：过期后续命的原料；
+ * - **非机密的账号事实**（`uid` / `email` / `accountName`）：COSY 载荷与卡片渲染用；
+ * - **路由事实**（`region`）：它唯一决定端点表，见 `./types.ts` 的 `REGION_HOSTS`；
+ * - **COSY 头的条件字段**（`organizationId` / `organizationTags` / `dataPolicyAgreed`）：
+ *   非空才出现在请求头里（inference-protocol.md §2 的 presence 矩阵）；
+ * - adopt 判别式（`adopted` / `source` / `sourcePath`）：见文件头。
+ */
+export interface QoderCredentials {
+    /** 真正发请求用的 job/device token。Host-only，永不过共享边界。 */
+    accessToken: string;
+    /** 刷新令牌（`jrt-...` 或设备流的 refresh_token）；没有时为 null。 */
+    refreshToken: string | null;
+    /** 过期时刻（Unix 毫秒，已含安全边）；上游没给时按兑换时刻 + 24h 兜底。 */
+    expiresAt: number;
+    /** 凭据自述的区域；**端点由它唯一决定**，不另存一份。 */
+    region: QoderRegion;
+    origin: QoderCredentialOrigin;
+    /** 上游账号 id（COSY 的 `Cosy-User`）；缺它 CN 会报「Login expired」（105）。 */
+    uid: string | null;
+    /** 账号邮箱（COSY UserInfo 的 `email`，非机密）；没有时为 null。 */
+    email: string | null;
+    /** 账号显示名（COSY UserInfo 的 `name`）；没有时为 null。 */
+    accountName: string | null;
+    /**
+     * PAT 来源的凭据留住的 PAT 本体（`pt-...`）。
+     *
+     * **Host-only，永远不过共享契约的边界**：它的唯一用途是过期后重新兑换一把
+     * job token（pi-provider 把 PAT 编进 refresh 字段，同一件事）。非 PAT 来源为 null。
+     */
+    personalToken: string | null;
+    /** 组织 id（`Cosy-Organization-Id` 的条件字段）；个人账号为 null。 */
+    organizationId: string | null;
+    /** 组织 tags（`Cosy-Organization-Tags` 的条件字段，逗号连接前的那份数组）。 */
+    organizationTags: string[];
+    /** `Cosy-Data-Policy` 的取值开关：true → `agree`，否则 `disagree`（fixture 的默认）。 */
+    dataPolicyAgreed: boolean;
+    /** 本插件接管这份凭据的时刻（Unix 毫秒）。 */
+    authenticatedAt: number;
+    /** 判别式，取字面量 `true`（与兄弟线路同：一个布尔比一句注释更难被忽略）。 */
+    adopted?: true;
+    /** 恒为 {@link QODER_CLI_CREDENTIAL_SOURCE}。 */
+    source?: typeof QODER_CLI_CREDENTIAL_SOURCE;
+    /** 读的是哪个文件，卡片照它显示。 */
+    sourcePath?: string;
+}
+/**
+ * 校验并归一化一份落盘的凭据。
+ *
+ * 缺的字段一律拒绝而不是补默认值：缺 `accessToken` 的凭据发出去一定是一次 401；
+ * 缺 `uid` 的凭据在 CN 会被报「Login expired」（105）——但它不拒绝：全球区对这个字段
+ * 更宽容，而号池装配侧会在发卡前尽力补齐（oauth.ts 的 userinfo 步骤）。
+ *
+ * `region` 认不出来时**拒绝**而不是回落默认：落盘的凭据总该自述；猜错的代价是
+ * 拿一区的凭据去打另一区的端点，一次明确的鉴权失败，排查成本远高于重新登录。
+ */
+export declare function parseQoderCredentials(value: unknown): QoderCredentials;
+/**
+ * 一份凭据是不是 adopt 快照（号池与适配器据此知道它的上游权威是 qodercli 的文件）。
+ *
+ * 它读的是**凭据对象本身**而不是某个内存标记（同 step-code 的同名函数的理由）。
+ */
+export declare function isAdoptedQoderCredential(credentials: QoderCredentials): boolean;
+/**
+ * 凭据的失效时刻：自述的 `expiresAt`；缺 0 时按「接管时刻 + 24h」补一份诚实的兜底
+ * （pi-provider 的缺省寿命），让号池的刷新钩子有东西可判。
+ */
+export declare function qoderCredentialsExpireAt(credentials: QoderCredentials): number;
+/**
+ * 这份凭据需不需要刷新：`expiresAt - 3600_000 < now` 时刷新
+ * （逐字 qodercli2api `docs/oauth.md` §3 的提前 1 小时）。
+ */
+export declare function qoderCredentialsNeedRefresh(credentials: QoderCredentials, now: number): boolean;
+/**
+ * 兑换/刷新响应里的过期时刻 → Unix 毫秒（已含 5 分钟安全边）。
+ *
+ * 三种形态都收（计划 §9 风险 6）：
+ *
+ * - `expiresAt`：ISO 字符串或 Unix 秒/毫秒——用**量级**分辨（10^10 秒是 2286 年，
+ *   更大的数一定已经是毫秒）；
+ * - `expiresIn`：相对时长。pi-provider 注释说观测到的是**毫秒**，qodercli2api 按秒读；
+ *   同一量级判据两处都兼容（小于 10^7 的值按秒才合理：10^7 秒约 4 个月，
+ *   而一把 job token 的寿命以小时/天计）。
+ */
+export declare function qoderExpiresAtFrom(expiresAt: unknown, expiresIn: unknown, now?: number): number;
+/** 凭据文件路径（本线路自己拥有；号池把主账号镜像到这里）。 */
+export declare function credentialPath(): string;
+/** 模型设置文件路径。 */
+export declare function modelSettingsPath(): string;
+/**
+ * machine id 文件路径（本线路自己持有的那份）。
+ *
+ * adopt 优先读 qodercli 的 `~/.qoder/.auth/machine_id`（解密它的凭据文件必须用那把
+ * 原配 key）；本线路自己发请求用的 machine id 落在这里——不与 qodercli 的混用，
+ * 也不写它的目录（读取顺序见 cosy.ts）。
+ */
+export declare function machineIdPath(): string;
+/**
+ * 加密凭据存储。
+ *
+ * 与兄弟线路同构：写入之后回读比对；按路径排队，避免两个同时落地的写互相丢掉。
+ * 没有明文迁移分支（本线路从未发布过，没有历史文件要迁）。
+ */
+export declare class QoderCredentialStore {
+    private readonly filePath;
+    private readonly backend;
+    constructor(filePath?: string, backend?: CredentialStore<QoderCredentials>);
+    /** 人可读的存储位置说明（Windows DPAPI / macOS Keychain / Linux Secret Service）。 */
+    path(): string;
+    read(): Promise<QoderCredentials | null>;
+    write(credentials: QoderCredentials): Promise<void>;
+    delete(): Promise<void>;
+}
+/**
+ * 本线路设置文档里**用户自己**的那一半。
+ *
+ * 随包目录 `QODER_MODEL_CATALOG_*` 刻意不存：它跟着代码走（同 step-code 的理由）。
+ */
+export interface QoderModelSettings {
+    /** 线路总开关。只有显式 false 才是关闭。 */
+    enabled?: boolean;
+    /**
+     * 用户勾选的模型 id，**三态**：
+     *
+     * - `null` = 不过滤（全部可用）——出厂默认，也是「这条线路没被挑过」的状态；
+     * - `[]` = 用户明确把每一个模型都关掉（一个都不可用）；
+     * - 非空 = 白名单，只有列出的那些可用。
+     *
+     * 为什么必须有第三态：schemastery 会把缺省的 `z.array(z.string())` 归一化成 `[]`，
+     * 一旦「空数组」同时表示「没挑过」，卡片上的「全不选」提交 `[]` 就与「全选」
+     * 完全等价——那是实测出来的真 bug，不是风格问题。
+     */
+    enabledModelIds: string[] | null;
+    /** 逐模型上下文窗口覆盖；缺省用目录声明值。 */
+    contextWindowOverrides: Record<string, number>;
+    /** 会话没指定档位时用的档位；null 表示各模型用自己的默认。 */
+    defaultReasoningEffort: QoderReasoningEffort | null;
+    /** 手动指定下一个请求使用的账号；null 交回号池调度。 */
+    selectedAccountId: string | null;
+    /**
+     * 勾选语义的**迁移标记**：`QODER_SELECTION_VERSION` 表示「这份文档由三态代码写过」。
+     *
+     * 为什么需要它（删掉它等于升级即坏）：三态之前，`defaultQoderModelSettings()` 返回的是
+     * `enabledModelIds: [...DEFAULT_VISIBLE_MODEL_IDS]`，而 qoder 的
+     * `DEFAULT_VISIBLE_MODEL_IDS` 就是 `[]`。所以**每一个老用户的落盘文件里都写着
+     * `"enabledModelIds": []`**，而旧语义下那个 `[]` 的意思是「不过滤（全部可用）」。
+     * 新语义里 `[]` 是「用户明确全关」。两者字面完全一样，只靠 `enabledModelIds`
+     * 本身分不开——没有这个标记，所有老用户升级后都会一个模型都不剩，而他们从没点过
+     * 「全不选」。
+     *
+     * 有了它，读文档时才能区分「旧版本的默认空表」与「用户真的点了全不选」：
+     * 无标记 + `[]` → 迁移成 `null`；有标记 + `[]` → 如实保留。
+     */
+    selectionVersion: number;
+}
+/**
+ * 当前勾选语义的版本号。1 = 三态（null / [] / 白名单）。
+ *
+ * 只增不减：以后若再改语义，把它 +1 并补一条新的迁移分支，而不是复用旧编号。
+ */
+export declare const QODER_SELECTION_VERSION = 1;
+/** 一个设置补丁。 */
+export interface QoderSettingsPatch {
+    enabled?: boolean;
+    /** 三态补丁：`null` 是**值**（回到不过滤），`[]` 也是值（全关），不是「没带这个字段」。 */
+    enabledModelIds?: string[] | null;
+    /** 补丁而不是整张表：`null` 必须能作为一个**值**活下来（卡片的「恢复目录默认」）。 */
+    contextWindowOverrides?: ContextWindowOverridePatch;
+    defaultReasoningEffort?: QoderReasoningEffort | null;
+    selectedAccountId?: string | null;
+}
+/**
+ * 路由与适配器共用的接缝（与 step-code 同一个形状，`status()` 同步的理由也相同）。
+ */
+export interface QoderPreferenceStore {
+    ready(): Promise<void>;
+    status(): QoderModelSettings;
+    update(patch: QoderSettingsPatch): Promise<QoderModelSettings>;
+}
+/** 一次全新安装的设置：全开、无过滤、无覆盖、无指定账号。 */
+export declare function defaultQoderModelSettings(): QoderModelSettings;
+/**
+ * 这份**原始**设置文档是否还停在旧语义上、需要一次迁移落盘。
+ *
+ * 判据只有一条：没有当前版本的迁移标记，且 `enabledModelIds` 是空数组。
+ * 旧版本把「没挑过」写成 `[]`（出厂值就是 `[]`，见 `QoderModelSettings.selectionVersion`
+ * 那段证据），所以这种文档必须被改写成 `null` 并盖上标记。
+ *
+ * 单独抽出来是因为落盘那一侧要先问「要不要迁移」再决定写不写，而
+ * {@link parseQoderModelSettings} 只负责给出解析后的值。
+ */
+export declare function needsQoderSelectionMigration(value: unknown): boolean;
+/**
+ * 归一化一份解析出来的设置文档。什么都不抛：手改过或降级过的文档必须降级成一份
+ * 可用的选择，而不是让整条线路不可用。
+ */
+export declare function parseQoderModelSettings(value: unknown): QoderModelSettings;
+/** 把一个补丁应用到一份设置文档上（register 与文件两个后端共用这一套规则）。 */
+export declare function mergeQoderSettings(current: QoderModelSettings, patch: QoderSettingsPatch): QoderModelSettings;
+/**
+ * 凭据旁边的设置文件（没有 register 接缝的 harness 启动时读的就是它）。
+ * 写入走「临时文件 + rename」，写完立刻回读比对再报告成功。
+ */
+export declare class QoderModelSettingsStore {
+    private readonly filePath;
+    constructor(filePath?: string);
+    path(): string;
+    /**
+     * 读一份设置，**并顺手完成一次性迁移**。
+     *
+     * 迁移必须落盘（否则下一次读到的还是同一份旧文档），所以整个「读 → 判断 → 写回」
+     * 跑在 {@link serialize} 的同一条按路径队列里：与 `updateSettings` 的读-改-写互斥，
+     * 不会出现「迁移写把用户刚提交的选择覆盖回去」这种顺序问题。
+     */
+    read(): Promise<QoderModelSettings>;
+    /** 不做迁移的裸读；只给已经在队列里的调用方用（避免 serialize 自我嵌套死锁）。 */
+    private readRaw;
+    write(settings: QoderModelSettings): Promise<void>;
+    /** 在与凭据写入同一条按路径排队的锁里做「读-改-写」。 */
+    updateSettings(patch: QoderSettingsPatch): Promise<QoderModelSettings>;
+}
+/**
+ * 把模型选择绑到 DSH 设置文档（harness 还提供 register 接缝时），
+ * 否则绑到凭据旁边的 JSON 文件。
+ *
+ * ⚠ `enabledModelIds` 是三态，schema 必须**显式**声明 `null` 这一格并把缺省值定成
+ * `null`：只写 `z.array(z.string())` 时 schemastery 会把缺省归一化成 `[]`，
+ * 那正好把「没挑过」翻译成「用户全关」，卡片上就再也点不出全关了。
+ */
+export declare function registerQoderPreferenceStore(settings?: unknown, fallbackStore?: QoderModelSettingsStore): QoderPreferenceStore;
+export { listModelIds };
+//# sourceMappingURL=token-store.d.ts.map

package/lib/types/host/qoder/token-store.d.ts.map

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