dsh-codearts 0.2.1 → 0.4.0

package/lib/index.d.mts

@@ -118,28 +118,39 @@ interface CodeArtsResolved {
   securityToken: string;
 }
 declare function canonicalModel(id: string): string;
-/** 该模型可用的 max_tokens 上限（没实测过的退回全局保守值）。 */
+/** 该模型可用的 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（华为只认后者），并钳制到
- *     MAX_TOKENS_CEILING（超限会流内报 InferHub.001001005.400
- *     "The request param is invalid, Please check it"）
+ *  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): {
-  url: string;
-  body: string;
-  model: string;
-  chatId: string;
-};
+declare function prepareChatBody(rawJson: string, contextWindow?: number): PreparedChatBody;
 /**
  * 把上游累计快照 SSE 转换成 OpenAI 增量流。
  *
@@ -392,14 +403,15 @@ declare class CodeArtsAccountPool {
 /**
  * 用量账本：把聊天流里的 usage 帧累计成「今天用了多少」。
  *
- * 为什么只能自己记：**CodeArts 没有额度/积分 API**（codearts2api 的 pool 里
- * `credits` 字段恒为 0，注释写着「CodeArts 无积分字段」；本插件也没有任何余额接口
- * 可用）。能拿到的真实数据只有两样：
+ * 为什么还要自己记：账号总额度有积分接口了（见 credits.ts，2026-10 从官方 Agent
+ * 客户端挖出并实测通过），但**本机经插件发出的请求**仍需自己累计 —— 上游不按
+ * 「这台机器」维度给统计。能拿到的真实数据有三样：
  *   1. 每个请求的 token `usage`（上游在流末尾回一帧 `{choices:[],usage:{...}}`）；
- *   2. 插件自己知道的账号会话槽位占用（见 account-pool：每账号 3 个并发会话）。
+ *   2. 插件自己知道的账号会话槽位占用（见 account-pool：每账号 3 个并发会话）；
+ *   3. 账号积分/额度（见 credits.ts）。
  *
- * 所以这里累计的是**本机经插件发出的请求**，不是账号总额度 —— 卡片上的文案必须
- * 照实说，官方额度明细在 `codearts.huaweicloud.com/portal/settings/personal-usage`。
+ * 所以这里累计的是**本机经插件发出的请求**，与卡片上的积分区块互补 —— 一个是本机
+ * 级、一个是账号级。官方额度明细在 `codearts.huaweicloud.com/portal/settings/personal-usage`。
  *
  * 落盘在 `$DSH_HOME/.codearts-usage.json`，按天存，保留最近 `RETENTION_DAYS` 天。
  *
@@ -519,6 +531,120 @@ interface CodeArtsAdapter {
 }
 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;
@@ -568,4 +694,4 @@ interface Config {
 declare const Config: z<Config>;
 declare function apply(ctx: Context, rawConfig: Config): void;
 //#endregion
-export { type AccountRuntime, CODEARTS_PROVIDER, CODEARTS_SETTINGS_NS, CodeArtsAccountPool, CodeArtsAccountStore, type CodeArtsAccountSummary, type CodeArtsAdapter, CodeArtsCatalog, type CodeArtsCredential, CodeArtsCredentialStore, type CodeArtsModelInfo, type CodeArtsShim, 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, fetchModels, filterEnabledModels, inject, maxTokensCeilingFor, name, prepareChatBody, refreshCatalog };
+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 };