dsh-codearts 0.0.0-stage → 0.3.0

package/lib/index.d.mts

@@ -0,0 +1,697 @@
+import z from "@deepseek-ai/schemastery";
+import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
+import { SettingsNamespace } from "@deepseek-ai/dsh-settings";
+import { Context } from "@deepseek-ai/cordis";
+import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
+//#region src/catalog.d.ts
+/**
+ * CodeArts model catalog.
+ *
+ * 目录有两条来源：
+ *  1. **动态发现**（`src/discovery.ts` + `upstream.fetchModels`）：启动与每小时
+ *     各拉一次，取内置 / 限时福利 / agent-center 三路的并集。这是正常路径。
+ *  2. **静态种子**（`FALLBACK_CODEARTS_MODELS`）：仅在发现失败或尚未登录时兜底。
+ *
+ * 种子的来龙去脉（诚实标注，别把它当权威）：
+ *  - 福利模型的 id 已与真实账号的 `gateway/config` 对齐；
+ *  - 商业模型的 id 可信（来自 codearts2api 的 `seedKnownModels`），但
+ *    `contextWindow` / `maxTokens` / `supportsImages` 是**占位值**，发现成功时
+ *    会被上游真实值覆盖 —— 这正是 `fillFromSeed` 只补缺、不覆盖的原因。
+ *    写错的 contextWindow 只影响 DSH 的上下文计量与截断余量，不影响路由；
+ *    写错的 maxTokens 会直接让请求失败（见 `MEASURED_MAX_TOKENS`）。
+ *
+ * @module dsh-codearts/catalog
+ */
+/** One model the adapter exposes to DSH. */
+interface CodeArtsModelInfo {
+  id: string;
+  name: string;
+  contextWindow: number;
+  maxTokens: number;
+  supportsImages: boolean;
+  /**
+   * 该模型走限时福利（免费套餐）路由。
+   *
+   * 由动态发现填入：福利是按账号授予的，只有拉过 `gateway/config` 才知道某个账号
+   * 到底有没有它。种子里那份静态名单只是冷启动兜底（见 `isBenefitModel`）。
+   */
+  benefit?: boolean;
+}
+/**
+ * Static seed roster. Ids are the *upstream registered* spellings (case
+ * matters — `canonicalModel` in upstream.ts passes these through verbatim).
+ * Updated 2026-09 from codearts2api's known model set.
+ *
+ * maxTokens 注记（2026-09-30 实测，scripts/param-probe.mjs 直连上游二分验证）：
+ * 免费福利 DeepSeek 模型的 max_tokens 服务端硬上限是 **65536**，更大的值
+ * （73728 / 98304 / 131072 / 384000 / 393216）一律流内报
+ * InferHub.001001005.400 "The request param is invalid, Please check it"。
+ * 此前的 384000/393216 是占位值：DSH 会把 catalog 的 maxTokens 作为
+ * max_tokens 原样发给上游，导致所有请求直接失败。
+ */
+declare const FALLBACK_CODEARTS_MODELS: readonly CodeArtsModelInfo[];
+/** Mutable catalog shared by the shim's `/v1/models` and the adapter. */
+declare class CodeArtsCatalog {
+  private models;
+  current(): readonly CodeArtsModelInfo[];
+  set(models: readonly CodeArtsModelInfo[]): void;
+}
+/**
+ * Narrow a catalog to the user's enabled selection (allowlist of model ids).
+ * Same semantics as the codebuddy plugin: absent or empty => serve all.
+ */
+declare function filterEnabledModels(models: readonly CodeArtsModelInfo[], enabled: readonly string[] | undefined): readonly CodeArtsModelInfo[];
+//#endregion
+//#region src/dpop.d.ts
+/**
+ * DPoP（RFC 9449）证明 JWT：ES256 + P-256，供 oauth2/tokens 请求头使用。
+ * 翻译自 codearts2api 的 internal/upstream/dpop.go。
+ *
+ * 关键约束：refresh_token 与首次换取时的 DPoP 公钥绑定，刷新时必须复用同一
+ * 私钥，否则 STS 报 InvalidDPoPHeader。因此该私钥必须随 refresh_token 一起落盘。
+ *
+ * @module dsh-codearts/dpop
+ */
+/** 可持久化的 P-256 DPoP 私钥（JWK 形式，含 d）。 */
+type DPoPPrivateJWK = {
+  kty: string;
+  crv: string;
+  x: string;
+  y: string;
+  d: string;
+};
+//#endregion
+//#region src/oauth.d.ts
+interface OAuthToken {
+  userId: string;
+  userName: string;
+  domainId: string;
+  securityToken: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  expiration: string;
+  refreshToken: string;
+  clientId: string;
+  dpopPrivateKey: DPoPPrivateJWK;
+}
+//#endregion
+//#region src/upstream.d.ts
+declare const SNAP_HOST = "https://snap-access.cn-north-4.myhuaweicloud.com";
+type UpstreamErrorKind = 'hard_credit' | 'soft_rate' | 'session_dead' | 'not_found' | 'server' | 'client';
+interface ChatResultOk {
+  ok: true;
+  /** 已转成 OpenAI 增量 SSE 的 ReadableStream（文本，data: ...\n\n）。 */
+  stream: ReadableStream<Uint8Array>;
+}
+interface ChatResultErr {
+  ok: false;
+  kind: UpstreamErrorKind;
+  status: number;
+  message: string;
+}
+type ChatResult = ChatResultOk | ChatResultErr;
+/** 给 shim 用的凭证（来自 credentialStore.resolve）。 */
+interface CodeArtsResolved {
+  token: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  securityToken: string;
+}
+declare function canonicalModel(id: string): string;
+/** 该模型可用的 max_tokens 上限（实测值与会话内学到的更低值取小）。 */
+declare function maxTokensCeilingFor(id: string): number;
+interface PreparedChatBody {
+  url: string;
+  body: string;
+  model: string;
+  chatId: string;
+  /**
+   * 不用发出去就能判定的失败（目前是「上下文放不下」）。非空时调用方必须直接把它
+   * 回给 DSH —— 上游遇到同类问题只会给一句 "The request param is invalid"，
+   * 那句话里没有模型、没有 token 数，用户无从下手。
+   */
+  error?: string;
+}
+/**
+ * 把 OpenAI 风格 chat body 适配给 CodeArts /api/v2/chat/completions。
+ * 该端点虽是 OpenAI 兼容，但网关按自己的 schema 严格校验参数。所以这里
+ * 不做原样透传，而是：
+ *  1. model 走 canonicalModel（大小写敏感）
+ *  2. max_completion_tokens → max_tokens（华为只认后者），并钳到该模型的上限；
+ *     再按 contextWindow 扣掉 prompt 估算，保证 prompt + max_tokens 装得下
+ *     （两者任一超限，上游都只会流内回 InferHub.001001005.400
+ *     "The request param is invalid, Please check it"，不告诉我们是哪一个）
+ *  3. 丢弃非白名单字段（stream_options / store / logprobs 等虽实测可容忍，
+ *     但按 codearts2api 观察到的真实流量收窄，避免网关后续收紧）
+ *  4. tools[].function 去掉 strict（OpenAI 专有）
+ *  5. 注入 CodeArts 特有字段：chat_id（按对话派生，见 conversationChatId）、
+ *     prompt_cache_key、tool_stream
+ *
+ * @param contextWindow 该模型的上下文窗口（来自 catalog）。传 0 表示不知道，
+ *   此时只做上限钳制、不做「装不下」判断。
+ */
+declare function prepareChatBody(rawJson: string, contextWindow?: number): PreparedChatBody;
+/**
+ * 把上游累计快照 SSE 转换成 OpenAI 增量流。
+ *
+ * 上游行为（reverse-engineering.md §5）：
+ *  - {"type":"answer", ...} 起始
+ *  - {"text": "<累计全文>"} 全文快照（用替换语义）
+ *  - {"delta":{"content":"..."}} 真增量
+ *  - {"text":"[DONE]","error_code":"0"} 结束；error_code != 0 为错误
+ */
+declare function chatStream(credential: CodeArtsResolved, prepared: {
+  url: string;
+  body: string;
+  model: string;
+  chatId?: string;
+}, signal?: AbortSignal): Promise<ChatResult>;
+/** 登录身份（上游对同一账号恒定，可用来当账号的自然键）。 */
+interface CallerIdentity {
+  userId: string;
+  userName: string;
+  domainId: string;
+}
+/** 模型清单的三路来源。任一路失败都不阻断，只有三路全失败才算失败。 */
+type ModelSource = 'builtin' | 'benefit' | 'agent';
+interface ModelDiscoveryResult {
+  /** 合并后的清单（已去重、已排序）。 */
+  models: readonly CodeArtsModelInfo[];
+  /** 本轮成功应答的来源。 */
+  sources: readonly ModelSource[];
+  /** 失败来源及原因（不阻断，供 doctor/日志展示）。 */
+  errors: readonly {
+    source: ModelSource;
+    message: string;
+  }[];
+}
+/**
+ * 动态发现当前账号可用的模型清单（三路合并）。
+ *
+ * 与 codearts2api 的 `Client.FetchModels` 等价：内置、限时福利、agent-center 三路
+ * 各自独立，任一路失败只记进 `errors` 不阻断 —— 福利网关抖动时仍能拿到内置模型。
+ *
+ * 上标的两个「实测 vs 标称」处理（很重要，别照搬标称值）：
+ *  - **maxTokens 钳到该模型的实测上限**（`MEASURED_MAX_TOKENS`）。上游
+ *    `gateway/config` 给福利模型标的是 393216 / 384000，而聊天端点实测超过 65536
+ *    就流内报 InferHub.001001005.400；DSH 会把 catalog 的 maxTokens 原样当
+ *    max_tokens 发出去，照抄标称值等于让每个请求都失败。
+ *  - contextWindow 用发现值（只影响 DSH 的上下文计量与截断余量，不影响路由）。
+ *
+ * @throws 三路全失败，或合并结果为空。
+ */
+declare function fetchModels(credential: CodeArtsResolved, signal?: AbortSignal): Promise<ModelDiscoveryResult>;
+//#endregion
+//#region src/auth.d.ts
+/** 持久化的完整凭证。 */
+interface CodeArtsCredential {
+  token: string;
+  /** 临时 AK/SK（HMAC 签名用）。手动粘贴场景可能为空。 */
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  /** refresh_token（续期用）。 */
+  refreshToken?: string;
+  /** 续期绑定的 DPoP 私钥（JWK）。 */
+  dpopPrivateKey?: OAuthToken['dpopPrivateKey'];
+  /** OAuth client_id（刷新需与登录时一致）。 */
+  clientId?: string;
+  /** STS 过期时间（ISO）。 */
+  expiration?: string;
+  /** 用户标识。 */
+  userId?: string;
+  userName?: string;
+  /** 华为云账号的 domain（`/snap-manager/v1/current/user` 会返回）。 */
+  domainId?: string;
+  /** 可选标注。 */
+  label?: string;
+  /** 存盘时间（epoch ms）。 */
+  storedAt?: number;
+  /** 续期已尝试且失败（多半已过期），需用户重新登录。 */
+  stale?: boolean;
+}
+declare function codeartsAuthPath(home?: string): string;
+interface ResolvedCredential {
+  token: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  securityToken: string;
+}
+declare class CodeArtsCredentialStore {
+  private _current;
+  private _path;
+  /** 正在进行的刷新。并发请求必须共用它，不能各刷一次。 */
+  private _inflight;
+  /**
+   * 凭证代际。重登/清除会推进它，让还在飞的刷新发现自己过期，
+   * 从而不把刷新结果写回去覆盖掉刚拿到的新凭证。
+   */
+  private _gen;
+  /** 作废在飞的刷新；任何直接写凭证的路径都要先调它。 */
+  private invalidateInflight;
+  constructor(path: string);
+  setPath(path: string): void;
+  /** 给 shim 用：返回签名所需全套。 */
+  resolve(): Promise<ResolvedCredential | undefined>;
+  current(): Promise<CodeArtsCredential | undefined>;
+  /** 从 OAuth 登录结果落库。 */
+  setFromOAuth(t: OAuthToken, label?: string): Promise<void>;
+  /** 领取限时福利（幂等）；无 AK/SK 时静默跳过。 */
+  private claimIfPossible;
+  /** 手动粘贴 security_token（降级态，无 AK/SK）。 */
+  set(token: string, label?: string): Promise<void>;
+  clear(): Promise<void>;
+  hasCredential(): Promise<boolean>;
+  /**
+   * 自动续期：若距过期不足 5 分钟且具备 refresh 条件，则刷新并落库。
+   * 返回当前（可能已刷新）凭证。
+   */
+  ensureFresh(): Promise<CodeArtsCredential | undefined>;
+  /** 真正去刷一次；失败则把凭证标成 stale 落库，让卡片提示重新登录。 */
+  private refresh;
+}
+interface CodeArtsAccountSummary {
+  id: string;
+  label?: string;
+  userName?: string;
+  expiration?: string;
+  storedAt?: number;
+  /** 上次续期失败，需要重新登录。 */
+  stale: boolean;
+  /** 带 AK/SK，能产生签名（只有 security_token 的降级凭证不能）。 */
+  signable: boolean;
+}
+declare function codeartsAccountsPath(home?: string): string;
+/** 多账号凭证存储：一个账号一份槽位，共用一个文档文件。 */
+declare class CodeArtsAccountStore {
+  private _doc;
+  private _slots;
+  private _loading;
+  /** 落库串行化：多个账号的续期可能同时想写同一个文档。 */
+  private _writeChain;
+  private readonly path;
+  /** 旧版单凭证文件；新文档不存在时把它收编成第一个账号。 */
+  private readonly legacyPath;
+  constructor(path: string, legacyPath?: string);
+  private loaded;
+  private load;
+  private adopt;
+  private persisterFor;
+  private persistDoc;
+  /** 按展示顺序返回账号摘要。 */
+  list(): Promise<CodeArtsAccountSummary[]>;
+  ids(): Promise<string[]>;
+  credential(id: string): Promise<CodeArtsCredential | undefined>;
+  /** 首个账号——卡片顶部与 CLI 的「当前」。 */
+  current(): Promise<CodeArtsCredential | undefined>;
+  hasCredential(): Promise<boolean>;
+  /** 新增或更新一个账号，返回它的 id。 */
+  upsert(cred: CodeArtsCredential, id?: string): Promise<string>;
+  /**
+   * 从一次 OAuth 登录结果新增/更新账号。
+   *
+   * 「再登录一次」天然就是「添加账号」：同一账号是更新，别的账号就是新增。
+   *
+   * 传了 `identity`（来自 `fetchCallerIdentity` 的稳定 user_id）就用它当账号键 ——
+   * 这正是「对同一个账号重新登录会被当成新账号」的解药；拿不到身份时退回旧行为
+   * （DPoP 公钥当键），也就是每次登录各自成一条。
+   */
+  upsertFromOAuth(t: OAuthToken, label?: string, identity?: CallerIdentity): Promise<string>;
+  /**
+   * 把一条已有账号迁移到它的稳定身份键上（同键则合并）。
+   *
+   * 用在两处：登录后回填身份（老条目已经存在时合并掉），以及 `dsh-codearts identity --fix`
+   * 清理历史遗留的重复条目。合并时保留 `storedAt` 较新的一份凭证，位置沿用目标键原有的顺序。
+   *
+   * @returns 迁移结果：`merged` 表示并入了已存在的那条，`moved` 表示只换了键，`noop` 表示键没变
+   */
+  adoptIdentity(id: string, identity: CallerIdentity): Promise<'merged' | 'moved' | 'noop'>;
+  /** 手工粘贴 security_token（降级态，无 AK/SK）——固定覆盖同一个「手工」账号。 */
+  set(token: string, label?: string): Promise<void>;
+  remove(id: string): Promise<void>;
+  /** 清空全部账号（整体登出）。 */
+  clear(): Promise<void>;
+  /** 给 shim 用：解析某账号的签名材料（内部含续期）。 */
+  resolve(id: string): Promise<ResolvedCredential | undefined>;
+}
+//#endregion
+//#region src/account-pool.d.ts
+interface AccountRuntime {
+  id: string;
+  /** 我们这边正在飞的请求数。 */
+  activeConcurrent: number;
+  maxConcurrent: number;
+  /** 冷却截止时间（epoch ms）；0 表示没在冷却。 */
+  coolUntil: number;
+  /** 撞上游并发上限后的「优先避开」截止时间。 */
+  cappedUntil: number;
+  disabled: boolean;
+  lastError?: string;
+  /** 上次被选中的时间，用于「最久未用优先」。 */
+  lastUsed: number;
+  errorCount: number;
+}
+interface PoolOptions {
+  maxConcurrent?: number;
+  /** 可注入的时钟，便于测试。 */
+  now?: () => number;
+}
+declare class CodeArtsAccountPool {
+  private readonly accounts;
+  private readonly maxConcurrent;
+  private readonly now;
+  constructor(ids: readonly string[], options?: PoolOptions);
+  /** 让池与账号文档对齐：新增的进来，删掉的出去。已有账号的运行时状态保留。 */
+  sync(ids: readonly string[]): void;
+  list(): AccountRuntime[];
+  get(id: string): AccountRuntime | undefined;
+  /** 账号本身可用（没被禁用、不在冷却中）。 */
+  healthy(id: string): boolean;
+  /** 现在就能接活的账号（健康 + 本地还有空槽位），按「最久未用」排序。 */
+  private available;
+  /**
+   * 选一个账号。
+   *
+   * 优先挑没人撞上限的（`cappedUntil` 已过的）；如果全都撞了，就退回其中任意
+   * 一个 —— 排它的队总比直接失败强。都没得选（全禁用/全在冷却）时返回 undefined。
+   */
+  pick(exclude?: ReadonlySet<string>): string | undefined;
+  /** 占一个本地槽位。占用失败（已满/不存在）返回 false。 */
+  acquire(id: string): boolean;
+  /** 释放槽位；重复释放不会把计数压到负数。 */
+  release(id: string): void;
+  /**
+   * 撞到上游并发上限。
+   *
+   * **不冷却账号** —— 账号没坏，只是会话槽位暂时满了（约 52 秒释放）。冷却会
+   * 让它在一分钟内彻底不可用，反而把后续请求也一起误伤（Go 参考里也是这么
+   * 处理的）。这里只记一个「优先避开」的提示，好让并发的请求先去用别的账号。
+   */
+  noteConcurrencyCap(id: string): void;
+  /** 凭据失效等硬错误：直接停用，等用户重新登录。 */
+  disable(id: string, reason: string): void;
+  /** 上游 5xx / 软限流：短时冷却。 */
+  cooldown(id: string, ms: number, reason: string): void;
+  /** 累计错误；达到阈值就冷却。 */
+  noteError(id: string, threshold: number, cooldownMs: number, reason: string): void;
+  /** 一次成功：清掉错误计数与冷却。 */
+  noteSuccess(id: string): void;
+  /** 有没有任何账号可用（含被撞上限提示的）。 */
+  hasUsable(): boolean;
+}
+//#endregion
+//#region src/usage.d.ts
+/**
+ * 用量账本：把聊天流里的 usage 帧累计成「今天用了多少」。
+ *
+ * 为什么还要自己记：账号总额度有积分接口了（见 credits.ts，2026-10 从官方 Agent
+ * 客户端挖出并实测通过），但**本机经插件发出的请求**仍需自己累计 —— 上游不按
+ * 「这台机器」维度给统计。能拿到的真实数据有三样：
+ *   1. 每个请求的 token `usage`（上游在流末尾回一帧 `{choices:[],usage:{...}}`）；
+ *   2. 插件自己知道的账号会话槽位占用（见 account-pool：每账号 3 个并发会话）；
+ *   3. 账号积分/额度（见 credits.ts）。
+ *
+ * 所以这里累计的是**本机经插件发出的请求**，与卡片上的积分区块互补 —— 一个是本机
+ * 级、一个是账号级。官方额度明细在 `codearts.huaweicloud.com/portal/settings/personal-usage`。
+ *
+ * 落盘在 `$DSH_HOME/.codearts-usage.json`，按天存，保留最近 `RETENTION_DAYS` 天。
+ *
+ * @module dsh-codearts/usage
+ */
+/** 用量账本路径：与账号文档同一层（`$DSH_HOME` 或 `~/.dsh`）。 */
+declare function codeartsUsagePath(home?: string): string;
+/** 累计计数。 */
+interface UsageTotals {
+  requests: number;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+/** 上游 usage 帧里我们关心的字段。 */
+interface RawUsage {
+  prompt_tokens?: unknown;
+  completion_tokens?: unknown;
+  total_tokens?: unknown;
+}
+interface UsageSnapshot {
+  /** 今天的合计。 */
+  today: UsageTotals;
+  /** 账本里所有保留天数的合计。 */
+  allTime: UsageTotals;
+  /** 今天按模型的合计，按 totalTokens 降序。 */
+  byModelToday: {
+    id: string;
+    totals: UsageTotals;
+  }[];
+  /** 今天按账号的合计。 */
+  byAccountToday: Record<string, UsageTotals>;
+  /** 账本覆盖的天数（便于「数据从哪天开始」的说明）。 */
+  days: number;
+  /** 最近一次记账时间（epoch ms）。 */
+  lastAt?: number;
+}
+interface UsageTrackerOptions {
+  /** 账本文件路径；省略则只记在内存里（测试用）。 */
+  path?: string;
+  /** 可注入的时钟。 */
+  now?: () => number;
+  /** 落盘防抖毫秒数（流式请求里每帧都写盘太浪费）。 */
+  saveDebounceMs?: number;
+}
+/**
+ * 用量账本。
+ *
+ * 记账分两步，因为一次请求可能只有其一：
+ *  - `noteRequest()` 在请求发出时调用（拿不到 usage 的流也要计入请求数）；
+ *  - `noteUsage()` 在收到 usage 帧时调用（补 token 数）。
+ */
+declare class CodeArtsUsageTracker {
+  private days;
+  private lastAt;
+  private loaded;
+  private loading;
+  private saveTimer;
+  private saving;
+  private readonly path;
+  private readonly now;
+  private readonly saveDebounceMs;
+  constructor(options?: UsageTrackerOptions);
+  /** 读账本（懒加载，只读一次）。 */
+  load(): Promise<void>;
+  private readFile;
+  private day;
+  private bucket;
+  /** 记一次请求（不等到 usage 帧）。 */
+  noteRequest(accountId: string, model: string, at?: number): void;
+  /** 记一次 usage 帧。 */
+  noteUsage(accountId: string, model: string, raw: RawUsage | undefined, at?: number): void;
+  /** 丢弃保留期之外的天（按日期键比较即可，YYYY-MM-DD 是字典序）。 */
+  private prune;
+  /** 当前快照（卡片与 CLI 都读它）。 */
+  snapshot(at?: number): UsageSnapshot;
+  private scheduleSave;
+  /** 立即落盘（关停时调用，别丢最后几秒的账）。 */
+  flush(): Promise<void>;
+  private save;
+}
+//#endregion
+//#region src/shim.d.ts
+interface ShimLogger {
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+interface CodeArtsShim {
+  ready: Promise<void>;
+  baseUrl(): string;
+  token(): string;
+  close(): Promise<void>;
+}
+interface CodeArtsShimOptions {
+  store: CodeArtsAccountStore;
+  catalog: CodeArtsCatalog;
+  /** 账号池。不传则内部自建一个，并在每次请求前与账号文档对齐。 */
+  pool?: CodeArtsAccountPool;
+  /** 用量账本。给了就在转发流的同时把 usage 帧记下来（卡片上的「今日用量」）。 */
+  usage?: CodeArtsUsageTracker;
+  logger?: ShimLogger;
+}
+declare function createCodeArtsShim(options: CodeArtsShimOptions): CodeArtsShim;
+//#endregion
+//#region src/adapter.d.ts
+/** Provider route this bundle owns. Keep in sync with cordis.patch.yml. */
+declare const CODEARTS_PROVIDER = "codearts";
+interface CodeArtsAdapterOptions {
+  shim: CodeArtsShim;
+  catalog: CodeArtsCatalog;
+  enabledModels?: () => readonly string[] | undefined;
+  resolveAttachments?: () => AttachmentStore | undefined;
+}
+interface CodeArtsAdapter {
+  adapter: PiAiAdapter;
+  invalidate: () => void;
+}
+declare function createCodeArtsAdapter(options: CodeArtsAdapterOptions): CodeArtsAdapter;
+//#endregion
+//#region src/credits.d.ts
+/** 福利网关：token 余额接口在这里（与 benefit/claim、gateway/config 同一个 host）。 */
+declare const BENEFIT_GATEWAY_HOST = "https://opengw.developer.huaweicloud.com";
+/** 一类积分（总量/已用/剩余/即将过期）。上游给不出的字段留 undefined。 */
+interface CodeArtsCreditCategory {
+  total: number;
+  used: number;
+  remain: number;
+  /** 会在本周期结束时作废的部分。 */
+  expiring: number;
+}
+/** 积分快照（来自 statistics/plugin）。 */
+interface CodeArtsCredits {
+  /** 套餐显示名，例如「体验版」。 */
+  planName: string;
+  /** 套餐英文名（中文缺失时的兜底）。 */
+  planNameEn: string;
+  /** 上游给的 spec_code，例如 codearts.agent.individual.trial。 */
+  specCode: string;
+  /** normal → active、closed → expired、freeze → frozen。 */
+  planStatus: 'active' | 'expired' | 'frozen' | 'unknown';
+  /** 是否按积分计费（false 表示 token 套餐）。 */
+  isCreditPackage: boolean;
+  /** 变更/购买套餐的官方页面。 */
+  packageUrl?: string;
+  /** 额度周期起止（end 就是「限额重置日期」）。 */
+  periodStart?: string;
+  periodEnd?: string;
+  /** 总积分（usageTotalPackageCredit）。 */
+  total: CodeArtsCreditCategory;
+  /** 赠送积分（usageBonusPackageCredit）。 */
+  bonus?: CodeArtsCreditCategory;
+  /** 基础套餐积分（usageBasicPackageCredit）。 */
+  basic?: CodeArtsCreditCategory;
+  /** 按需积分（usageOnDemandPackageCredit）。 */
+  onDemand?: CodeArtsCreditCategory;
+  /** 抓取时刻（毫秒）。 */
+  fetchedAt: number;
+}
+/** token 额度快照（来自 tokens/balance）。 */
+interface CodeArtsTokenQuota {
+  dailyLimit: number;
+  dailyUsed: number;
+  monthlyLimit: number;
+  monthlyUsed: number;
+  /** 剩余额度。 */
+  balance: number;
+  /** 总额度。 */
+  quota: number;
+}
+interface CodeArtsCreditSnapshot {
+  credits: CodeArtsCredits;
+  /** 拿不到（接口失败/不支持）时为 undefined，不影响积分本身。 */
+  tokens?: CodeArtsTokenQuota;
+}
+/** 缓存里的一个结果：成功给值，失败给消息 —— 失败也要能被卡片看见。 */
+type CodeArtsCreditState = {
+  phase: 'ok';
+  value: CodeArtsCreditSnapshot;
+  at: number;
+} | {
+  phase: 'error';
+  message: string;
+  at: number;
+};
+/**
+ * 解析 `GET /snap-manager/v1/statistics/plugin` 的响应。
+ *
+ * 返回 undefined 表示这不是一份能用的积分文档（上游改了形状/账号没有积分体系）——
+ * 调用方据此报「积分不可用」，而不是显示一排 0 假装是真的。
+ */
+declare function parseCreditStatistics(raw: unknown): CodeArtsCredits | undefined;
+/** 解析 `GET /api/v1/user/tokens/balance` 的响应（`result` 里是额度口径）。 */
+declare function parseTokenBalance(raw: unknown): CodeArtsTokenQuota | undefined;
+/**
+ * 拉一次积分与 token 额度。
+ *
+ * 积分是主口径：它失败就整体失败（卡片要能看见原因）。token 额度是附带的，
+ * 它失败只让 `tokens` 缺席 —— 别让一个次要接口把主数字一起拖没。
+ */
+declare function fetchCredits(credential: CodeArtsResolved, signal?: AbortSignal): Promise<CodeArtsCreditSnapshot>;
+interface CreditCacheOptions {
+  ttlMs?: number;
+  failureTtlMs?: number;
+  /** 便于测试注入。 */
+  load?: (credential: CodeArtsResolved, signal?: AbortSignal) => Promise<CodeArtsCreditSnapshot>;
+  now?: () => number;
+}
+/**
+ * 积分缓存（TTL + 单飞）。
+ *
+ * 单飞很重要：卡片刷新、对话底部的轮询可能同时打进来，没有它就会并发问上游好几次；
+ * 而上游对同一账号的并发是有成本/风险的。
+ */
+declare class CodeArtsCreditCache {
+  private state;
+  private inflight;
+  private readonly ttlMs;
+  private readonly failureTtlMs;
+  private readonly load;
+  private readonly now;
+  constructor(options?: CreditCacheOptions);
+  /** 当前缓存内容（不触发请求），供只想读快照的场景使用。 */
+  peek(): CodeArtsCreditState | undefined;
+  /** 丢掉缓存，下次 get 会重新拉（重新登录/添加账号后调用）。 */
+  invalidate(): void;
+  /**
+   * 取一次积分。命中缓存直接返回；否则合并成一次上游请求。
+   * **不抛异常**：失败以 `phase: 'error'` 返回，调用方（状态路由）照样能渲染。
+   */
+  get(credential: CodeArtsResolved, signal?: AbortSignal): Promise<CodeArtsCreditState>;
+  private run;
+}
+//#endregion
+//#region src/discovery.d.ts
+interface AccountDiscovery {
+  accountId: string;
+  label?: string;
+  ok: boolean;
+  models: readonly CodeArtsModelInfo[];
+  sources: readonly ModelSource[];
+  errors: readonly {
+    source: ModelSource;
+    message: string;
+  }[];
+}
+interface DiscoveryOutcome {
+  /** 合并所有账号后的目录（已去重、已排序、已钳制上限）。 */
+  models: readonly CodeArtsModelInfo[];
+  /** 逐账号的结果，含失败原因。 */
+  accounts: readonly AccountDiscovery[];
+  /** 至少一个账号成功。 */
+  anySucceeded: boolean;
+}
+/**
+ * 逐账号发现并合并（不改全局状态）。
+ *
+ * @param store 账号文档；逐个 `resolve()` 以拿到已续期的签名材料
+ * @param signal 取消信号（宿主关停时用）
+ */
+declare function discoverModels(store: CodeArtsAccountStore, signal?: AbortSignal): Promise<DiscoveryOutcome>;
+/**
+ * 发现并**提交**到全局目录：目录内容 + 福利集合。
+ *
+ * @returns 提交后的目录；没有任何账号成功时返回 `undefined`（调用方保留原目录）
+ */
+declare function refreshCatalog(store: CodeArtsAccountStore, catalog: CodeArtsCatalog, signal?: AbortSignal): Promise<DiscoveryOutcome | undefined>;
+//#endregion
+//#region src/index.d.ts
+/** Stable Cordis plugin name. */
+declare const name = "llm-codearts";
+/** The llm service is required before the provider can register. */
+declare const inject: string[];
+/** Settings namespace owning the configuration card. */
+declare const CODEARTS_SETTINGS_NS: SettingsNamespace;
+/** Plugin configuration (MVP: just the model allowlist). */
+interface Config {
+  /** Allowlist of CodeArts model ids offered in the model pickers. */
+  enabledModels?: string[];
+}
+declare const Config: z<Config>;
+declare function apply(ctx: Context, rawConfig: Config): void;
+//#endregion
+export { type AccountRuntime, BENEFIT_GATEWAY_HOST, CODEARTS_PROVIDER, CODEARTS_SETTINGS_NS, CodeArtsAccountPool, CodeArtsAccountStore, type CodeArtsAccountSummary, type CodeArtsAdapter, CodeArtsCatalog, type CodeArtsCredential, CodeArtsCredentialStore, CodeArtsCreditCache, type CodeArtsCreditCategory, type CodeArtsCreditSnapshot, type CodeArtsCreditState, type CodeArtsCredits, type CodeArtsModelInfo, type CodeArtsShim, type CodeArtsTokenQuota, CodeArtsUsageTracker, Config, type DiscoveryOutcome, FALLBACK_CODEARTS_MODELS, type ModelDiscoveryResult, SNAP_HOST, type UpstreamErrorKind, type UsageSnapshot, type UsageTotals, apply, canonicalModel, chatStream, codeartsAccountsPath, codeartsAuthPath, codeartsUsagePath, createCodeArtsAdapter, createCodeArtsShim, discoverModels, fetchCredits, fetchModels, filterEnabledModels, inject, maxTokensCeilingFor, name, parseCreditStatistics, parseTokenBalance, prepareChatBody, refreshCatalog };