@acosmi/sdk-ts 1.0.0

package/dist/node/index.d.cts

@@ -0,0 +1,791 @@
+import { S as ServerMetadata, T as TokenResponse, a as TokenSet, C as ClientRegistration, M as ModelCapabilities, b as ChatRequest, c as ManagedModel, d as ModelCoefficient, Q as QuotaSummary, P as ProviderAdapter, e as ChatResponse, A as AnthropicResponse, f as StreamEvent, g as SourcesEvent, h as StreamSettlement, E as EntitlementBalance, B as BalanceDetail, i as EntitlementItem, j as ConsumeRecordPage, k as ModelByQuotaResponse, l as ModelBucket, m as TokenPackage, n as PayPayload, O as Order, o as OrderStatus, W as WalletStats, p as Transaction, q as SkillStoreQuery, r as SkillStoreItem, s as SkillBrowseResponse, t as SkillBrowseListResponse, u as SkillSummary, v as CertificationStatus, G as GenerateSkillRequest, w as GenerateSkillResult, x as OptimizeSkillRequest, y as OptimizeSkillResult, z as ToolView, N as NotificationList, D as DeviceRegistration, F as NotificationPreference, H as WSEvent } from './index-C3Z_84Bv.cjs';
+export { I as APIResponse, J as AnthropicContentBlock, K as AnthropicUsage, L as BucketClassCommercial, R as BucketClassGeneric, U as BucketInfo, V as BucketRow, X as BusinessError, Y as ChatContentBlock, Z as ChatMessage, _ as ChatUsage, $ as ConsumeRecord, a0 as EffortConfig, a1 as GeoLoc, a2 as HTTPError, a3 as ModelNotFoundError, a4 as NetworkError, a5 as Notification, a6 as NotificationUnreadCount, a7 as OpenAIChatChoice, a8 as OpenAIChatMessage, a9 as OpenAIChatResponse, aa as OpenAIFunctionCall, ab as OpenAIStreamChoice, ac as OpenAIStreamChunk, ad as OpenAIStreamDelta, ae as OpenAIStreamToolCall, af as OpenAIToolCall, ag as OpenAIUsage, ah as OrderTerminalError, ai as OutputConfig, aj as ProviderFormat, ak as RateLimitError, al as ServerTool, am as ServerToolTypeWebSearch, an as SkillStoreListItem, ao as StreamError, ap as ThinkingConfig, aq as ThinkingHigh, ar as ThinkingHighMinMaxTokens, as as ThinkingMax, at as ThinkingMaxFallbackMaxTokens, au as ThinkingOff, av as ToolListResponse, aw as ToolProvider, ax as WebSearchConfig, ay as WebSearchSource, az as YudaoPageResult, aA as anthropicResponseTextContent, aB as anthropicResponseThinkingContent, aC as anthropicResponseToolUseBlocks, aD as apiResponseBusinessError, aE as apiResponseGetMessage, aF as bucketInfoIsCommercial, aG as bucketRowIsCommercial, aH as getAdapter, aI as getAdapterForModel, aJ as newThinkingConfig, aK as newWebSearchTool, aL as parseNotificationEvent, aM as parseSettlement, aN as parseSourcesEvent, aO as tokenSetIsExpired } from './index-C3Z_84Bv.cjs';
+import { M as MinimalSanitizeConfig } from './index-nvLKgCm9.cjs';
+export { i as sanitize } from './index-nvLKgCm9.cjs';
+export { AnthropicAdapter } from './adapters/anthropic.cjs';
+export { OpenAIAdapter } from './adapters/openai.cjs';
+
+/**
+ * 从 well-known 端点获取 Desktop OAuth 服务元数据。
+ *
+ * serverURL 可能含路径 (如 "https://acosmi.ai/api/v4")，
+ * well-known 端点按 RFC 8414 必须在 origin 根路径:
+ *   https://acosmi.ai/.well-known/oauth-authorization-server/desktop
+ */
+declare function discover(serverURL: string, signal?: AbortSignal): Promise<ServerMetadata>;
+/** 动态注册桌面客户端，获取 client_id */
+declare function register(meta: ServerMetadata, appName: string, signal?: AbortSignal): Promise<ClientRegistration>;
+type LoginEventType = 'auth_url' | 'complete' | 'error';
+declare const EventAuthURL: "auth_url";
+declare const EventComplete: "complete";
+declare const EventError: "error";
+type LoginErrCode = 'discovery_failed' | 'registration_failed' | 'browser_open_failed' | 'auth_denied' | 'auth_timeout' | 'token_exchange_failed' | 'ssl_proxy_detected';
+declare const ErrDiscovery: "discovery_failed";
+declare const ErrRegistration: "registration_failed";
+declare const ErrBrowserOpen: "browser_open_failed";
+declare const ErrAuthDenied: "auth_denied";
+declare const ErrTimeout: "auth_timeout";
+declare const ErrTokenExchange: "token_exchange_failed";
+declare const ErrSSLProxy: "ssl_proxy_detected";
+/** 登录流程事件 */
+interface LoginEvent {
+    type: LoginEventType;
+    url?: string;
+    error?: string;
+    err_code?: LoginErrCode;
+}
+/** 登录选项 (函数选项模式 → TS options object) */
+interface LoginOptions {
+    /** 跳过自动打开浏览器 (由调用方控制浏览器) */
+    skipBrowser?: boolean;
+    /** SSO 场景下的 email 预填 */
+    loginHint?: string;
+    /** 如 "sso" */
+    loginMethod?: string;
+    /** 强制组织登录 */
+    orgUUID?: string;
+    /** 自定义 token 有效期 (秒) */
+    expiresIn?: number;
+}
+/** 检测 SSL/TLS 相关错误 (企业代理 Zscaler 等) */
+declare function isSSLError(err: unknown): boolean;
+interface AuthorizeResult {
+    code: string;
+    redirectURI: string;
+}
+/**
+ * 执行 OAuth 2.1 PKCE 授权流程 (Node only):
+ *   1. 启动本地 HTTP server
+ *   2. 打开浏览器让用户登录并授权
+ *   3. 接收回调拿到 authorization code
+ *   4. 返回 code 供后续 token 交换
+ *
+ * 浏览器环境会抛错 — 浏览器侧应自行实现 popup window + redirect handler。
+ */
+declare function authorize(meta: ServerMetadata, clientID: string, scopes: string[], opts?: LoginOptions & {
+    handler?: (e: LoginEvent) => void;
+    signal?: AbortSignal;
+}): Promise<{
+    result: AuthorizeResult;
+    verifier: string;
+}>;
+declare function exchangeCode(meta: ServerMetadata, clientID: string, code: string, redirectURI: string, codeVerifier: string, signal?: AbortSignal): Promise<TokenResponse>;
+/** 刷新 access_token */
+declare function refreshToken(meta: ServerMetadata, clientID: string, refreshTokenValue: string, signal?: AbortSignal): Promise<TokenResponse>;
+/** 吊销 token. 服务端不支持吊销时静默跳过. */
+declare function revokeToken(meta: ServerMetadata, token: string, signal?: AbortSignal): Promise<void>;
+/**
+ * 从 TokenResponse 构造可持久化的 TokenSet
+ *
+ * 根因修复 #14: expires_in=0 会导致 token 立即过期 → 无限刷新循环
+ * 最少保证 60 秒有效期
+ */
+declare function newTokenSet(resp: TokenResponse, clientID: string, serverURL: string): TokenSet;
+
+declare const ScopeAI = "ai";
+declare const ScopeSkills = "skills";
+declare const ScopeAccount = "account";
+/** @deprecated 旧细粒度 scope, 保留向后兼容, 新代码请用分组 scope */
+declare const ScopeModels = "models";
+/** @deprecated */
+declare const ScopeModelsChat = "models:chat";
+/** @deprecated */
+declare const ScopeEntitlements = "entitlements";
+/** @deprecated */
+declare const ScopeTokenPackages = "token-packages";
+/** @deprecated */
+declare const ScopeSkillStore = "skill_store";
+/** @deprecated */
+declare const ScopeTools = "tools";
+/** @deprecated */
+declare const ScopeToolsExecute = "tools:execute";
+/** @deprecated */
+declare const ScopeWallet = "wallet";
+/** @deprecated */
+declare const ScopeWalletReadonly = "wallet:readonly";
+/** @deprecated */
+declare const ScopeProfile = "profile";
+/** 全部分组 scope (推荐) */
+declare function allScopes(): string[];
+/** 模型服务相关 scope */
+declare function modelScopes(): string[];
+/** 商城/钱包 scope */
+declare function commerceScopes(): string[];
+/** 技能/工具 scope */
+declare function skillScopes(): string[];
+
+/**
+ * Token 持久化接口
+ * 桌面智能体可自行实现 (如 macOS Keychain / Windows Credential Manager)
+ *
+ * 跨端约定:
+ *   - Save: 写入持久化, 失败抛 Error
+ *   - Load: 读取, 不存在返回 null (与 Go IsNotExist 行为一致)
+ *   - Clear: 删除, 不存在不抛错 (Logout 后 Clear 不应报错, [RC-11])
+ */
+interface TokenStore {
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
+/**
+ * 基于文件的 token 存储 (开发/测试用)
+ * 生产环境建议替换为系统钥匙串实现
+ *
+ * 默认路径: ~/.acosmi/tokens.json
+ *
+ * 浏览器环境调用 new FileTokenStore() 会抛错 — 浏览器请用 LocalStorageTokenStore 或 InMemoryTokenStore.
+ */
+declare class FileTokenStore implements TokenStore {
+    private path;
+    /** 简单串行化锁 (替代 Go sync.Mutex) */
+    private chain;
+    constructor(path?: string);
+    private resolvePath;
+    private withLock;
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
+/**
+ * 创建文件 token 存储 (与 Go NewFileTokenStore 等价)
+ * @param path 自定义路径; 空则使用默认 ~/.acosmi/tokens.json
+ */
+declare function newFileTokenStore(path?: string): FileTokenStore;
+/**
+ * 基于 LocalStorage 的 token 存储 (浏览器)
+ *
+ * 仅在浏览器环境可用 (检测 globalThis.localStorage)。
+ * 不持久化跨设备同步, 适合单机 SPA 使用。
+ */
+declare class LocalStorageTokenStore implements TokenStore {
+    private key;
+    constructor(key?: string);
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
+/**
+ * 内存 token 存储 (不持久化, 进程重启即丢失)
+ * 适合: 测试 / Deno script / 短期 SDK 调用 / 不希望落盘的安全场景
+ */
+declare class InMemoryTokenStore implements TokenStore {
+    private tokens;
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
+
+/** 表示一次 retry 评估的请求快照 — 仅供 SafeToRetry 闸门使用 */
+interface RetryRequestInfo {
+    method: string;
+    url: string;
+}
+/**
+ * 配置 SDK 重试行为.
+ *
+ * undefined 字段使用 DefaultRetryPolicy 对应字段; null/undefined RetryPolicy 自身禁用重试.
+ */
+interface RetryPolicy {
+    /** 总尝试次数 (含首次). 1 = 不重试; 默认 2. */
+    maxAttempts?: number;
+    /** 首次重试退避时长 (毫秒). 默认 200. */
+    backoffMs?: number;
+    /** 退避最大值 (指数增长封顶, 毫秒). 默认 2000. */
+    backoffMaxMs?: number;
+    /** 指数倍数. 默认 2.0. */
+    backoffMul?: number;
+    /**
+     * 错误层闸门: 是否值得重试.
+     * 默认 defaultRetryable: HTTPError 5xx/429, NetworkError Timeout/EOF, 排除 StreamError.
+     */
+    onRetryable?: (err: unknown) => boolean;
+    /**
+     * 请求层闸门 (计费安全核心): 当前请求是否值得重试.
+     * 默认 defaultSafeToRetry: GET/HEAD/OPTIONS true, 其他 false.
+     * chat/messages/upload POST → 默认 false 兜底, 双扣绝不发生.
+     */
+    safeToRetry?: (req: RetryRequestInfo) => boolean;
+}
+/**
+ * 安全默认值.
+ *
+ * 计费安全红线: safeToRetry 默认 POST=false → chat/messages 用户 0 行为变化.
+ * GET 类查询 (skill-store/models/balance) 自动得 2x 稳定性.
+ */
+declare const DefaultRetryPolicy: Required<Omit<RetryPolicy, never>>;
+/**
+ * 计费安全闸门.
+ *
+ * 仅以下 method 视为幂等:
+ *   - GET / HEAD / OPTIONS: 天然幂等
+ *
+ * POST/PUT/DELETE/PATCH 默认 false (双扣保护). 调用方需要 GET 类 POST 重试可自定义 safeToRetry.
+ */
+declare function defaultSafeToRetry(req: RetryRequestInfo): boolean;
+/**
+ * 错误层闸门.
+ *
+ * 显式排除 (优先级最高):
+ *   - StreamError: V2 P0 SSE 中段错误, 流已部分写出, 重试 = 双 token + 重复消息
+ *   - AbortSignal aborted: 用户主动 abort, 重试无意义 (TS 中由调用方在 onRetryable 之前检查)
+ *
+ * 视为可重试:
+ *   - HTTPError 5xx 或 429
+ *   - NetworkError isTimeout() 或 isEOF()
+ *
+ * 其他 (如 4xx 业务错误 / DNS 失败 / BusinessError): 不重试
+ */
+declare function defaultRetryable(err: unknown): boolean;
+/** 实际生效策略 (undefined → DefaultRetryPolicy 兜底; 字段缺失填默认值) */
+declare function effectivePolicy(p: RetryPolicy | null | undefined): Required<RetryPolicy> | null;
+/**
+ * 计算第 attempt 次重试的退避时长 (毫秒, attempt 从 0 起).
+ * 优先级: HTTPError.retryAfter (上限 60s) > 指数退避 (backoffMs * backoffMul^attempt, 封顶 backoffMaxMs)
+ */
+declare function computeBackoff(p: Required<RetryPolicy>, attempt: number, err: unknown): number;
+
+/** SDK 为单个 content block 缓存的元数据 */
+interface BlockMeta {
+    type: string;
+    ephemeral: boolean;
+}
+/**
+ * 按 Anthropic SSE 事件类型解析 data, 更新 blockTypeMap, 返回 [index, type, ephemeral]。
+ *
+ * 仅当事件为 content_block_start / content_block_delta / content_block_stop
+ * 时返回非空 type; 其他事件返回空 type, 调用方据此判别是否填充 StreamEvent 元数据字段。
+ */
+declare function extractAnthropicBlockMeta(eventType: string, data: string, blockTypeMap: Map<number, BlockMeta>): [number, string, boolean];
+
+/** 根据模型能力和请求参数自动组装 beta header 列表 */
+declare function buildBetas(caps: ModelCapabilities, req: ChatRequest): string[];
+/** 合并两个字符串数组并去重, 保留顺序 */
+declare function uniqueMerge(base: string[], extra: string[]): string[];
+
+type FilterStatus = 'ok' | 'admin-bypass' | 'internal-bypass' | 'disabled-by-flag' | 'fallback-tkdist-error' | 'fallback-tkdist-deployment-skew' | 'fallback-no-buckets' | 'fallback-missing-userid' | '';
+declare const FilterStatusOK: FilterStatus;
+declare const FilterStatusAdminBypass: FilterStatus;
+declare const FilterStatusInternalBypass: FilterStatus;
+declare const FilterStatusDisabledByFlag: FilterStatus;
+declare const FilterStatusFallbackTkdistError: FilterStatus;
+declare const FilterStatusFallbackTkdistSkew: FilterStatus;
+declare const FilterStatusFallbackNoBuckets: FilterStatus;
+declare const FilterStatusFallbackMissingUser: FilterStatus;
+declare const FilterStatusUnknown: FilterStatus;
+/** 客户端配置 */
+interface Config {
+    /**
+     * nexus-v4 API 根地址 (默认 https://acosmi.com)。
+     * SDK 自动追加 /api/v4, 无需手动拼接。
+     */
+    serverURL?: string;
+    /** token 持久化实现, 缺省时按平台选 (Node File / Browser LocalStorage / Memory) */
+    store?: TokenStore;
+    /** 自定义 fetch 实现 (默认 globalThis.fetch) */
+    fetchImpl?: typeof fetch;
+    /**
+     * 重试策略 (L6, v0.15)
+     *
+     * undefined = 禁用重试 (v0.14.1 行为, 老调用方 0 影响)
+     * 非 undefined = 启用 — 默认 SafeToRetry POST=false 兜底, chat/messages POST 仍 0 retry
+     * GET 类查询 (skill-store/models/balance) 自动得 2x 稳定性
+     *
+     * 计费安全: 自定义 SafeToRetry 时, 严禁让 POST chat/messages 通过, 否则双扣
+     */
+    retryPolicy?: RetryPolicy;
+}
+interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (v: T) => void;
+    reject: (e: unknown) => void;
+}
+/**
+ * WebSocket 状态 — 内部使用, 实际方法由 ws.ts mixin 提供
+ * 留作 forward declaration, 避免循环依赖
+ */
+interface WSState {
+    connected: boolean;
+    [key: string]: any;
+}
+/**
+ * Acosmi nexus-v4 统一 API 客户端
+ *
+ * 覆盖全域 API: 模型/权益/商城/钱包/技能/工具/WebSocket
+ * 自动处理 token 刷新, 所有 API 调用线程安全 (基于 Promise chain)
+ */
+declare class Client {
+    /** SDK 内部使用 — 业务方法 (mixin) 通过 this.* 访问以下字段 */
+    /** 服务器根地址 (已 trim 尾随 /) */
+    serverURL: string;
+    /** OAuth metadata (lazy loaded) */
+    meta: ServerMetadata | null;
+    /** 当前 token (内存) */
+    tokens: TokenSet | null;
+    /** token 持久化 */
+    store: TokenStore;
+    /** fetch 实现 (默认 globalThis.fetch) */
+    fetchImpl: typeof fetch;
+    /** 互斥锁 (TS 用 Promise chain 替代 sync.Mutex) */
+    private mu;
+    /** WebSocket 状态 (实际方法由 ws.ts mixin 维护) */
+    ws: WSState | null;
+    /** v0.15.1: token 就绪等待机制 — login 成功后 resolve, 等待方解除阻塞 */
+    tokenReady: Deferred<void>;
+    /** Login 进行中 — 等待方需等而非 fail-fast */
+    loginInFlight: boolean;
+    /** 防止 tokenReady 被多次 resolve (替代 Go sync.Once) */
+    private tokenReadyResolved;
+    /** 模型能力缓存 (CrabCode 扩展) */
+    modelCache: ManagedModel[];
+    modelCacheTimeMs: number;
+    /** sanitize-bridge 配置 (默认禁用) */
+    defensiveCfg: MinimalSanitizeConfig | null;
+    autoStripEphemeral: boolean;
+    /** L6 (v0.15): 重试策略. null = 禁用 (v0.14.1 行为) */
+    retryPolicy: Required<RetryPolicy> | null;
+    /** V29 系数缓存 (TTL 8s, listCoefficients 内部用) */
+    coefCacheData: ModelCoefficient[] | null;
+    coefCacheTimeMs: number;
+    /** 串行化锁 (替代 Go sync.Mutex) */
+    private coefMu;
+    constructor(cfg?: Config);
+    /**
+     * 异步初始化 (从 store 加载已有 token)
+     * 替代 Go NewClient (Go 同步 IO, TS 必须 async)
+     */
+    static create(cfg?: Config): Promise<Client>;
+    /** 是否已授权 (有可用 token) */
+    isAuthorized(): boolean;
+    /** 当前 token 信息 (用于 CLI whoami 显示) */
+    getTokenSet(): TokenSet | null;
+    private getCachedClientID;
+    /**
+     * 完整授权流程: 发现 → 注册 → 授权 → 换 token → 持久化
+     * @param appName 桌面智能体名称 (如 "CrabClaw Desktop")
+     * @param scopes 请求的权限范围 (参考 allScopes / modelScopes / commerceScopes 等预设)
+     */
+    login(appName: string, scopes: string[], signal?: AbortSignal): Promise<void>;
+    /**
+     * 带事件回调的登录流程 — CrabCode 使用
+     *
+     * handler 在以下时刻被调用:
+     *   - EventAuthURL:  授权 URL 已就绪, 调用方可展示/打开浏览器
+     *   - EventComplete: 登录成功, tokens 已持久化
+     *   - EventError:    某步骤失败, 附 ErrCode 分类码
+     *
+     * 当 handler 为 null 时, 行为与 login() 完全一致。
+     */
+    loginWithHandler(appName: string, scopes: string[], handler: ((e: LoginEvent) => void) | null, opts?: LoginOptions, signal?: AbortSignal): Promise<void>;
+    private loginInternal;
+    /** 吊销 token 并清除本地存储 */
+    logout(signal?: AbortSignal): Promise<void>;
+    /**
+     * 确保有有效的 access_token, 过期则自动刷新
+     *
+     * v0.15.1: 当 tokens==null 且 login 正在并发进行中时, 阻塞等待 token 就绪,
+     * 避免应用启动期 "login + 多个 API 调用" 并发场景下 4+ 条 "not authorized" 误报.
+     */
+    ensureToken(signal?: AbortSignal): Promise<string>;
+    /** 强制刷新 token (用于 401 重试) */
+    forceRefresh(signal?: AbortSignal): Promise<void>;
+    /** 互斥锁 helper (替代 Go sync.Mutex) */
+    private withMu;
+    /**
+     * 获取可用的托管模型列表.
+     *
+     * V30 二轮审计 D-P1-2: 此方法不返回 entitlement-filter-status header.
+     * UI 想根据 fallback 状态显示降级提示, 请改调 listModelsWithStatus.
+     */
+    listModels(signal?: AbortSignal): Promise<ManagedModel[]>;
+    /**
+     * 获取可用模型列表, 同时返回 X-Entitlement-Filter-Status header.
+     *
+     * V30 二轮审计 D-P1-2: 老 listModels 丢弃 header 让 SDK 用户无法识别 fail-OPEN 降级状态,
+     * 此方法暴露 status 让 UI 可:
+     *   - status === 'ok' → 正常显示 BucketInfo 余量
+     *   - status === 'fallback-tkdist-error' → 灰显余量 + toast "tk-dist 离线, 模型列表降级"
+     *   - status === 'disabled-by-flag' → 不显示余量 (运维灰度中)
+     *   - status === '' (Unknown) → 老 nexus, 按老 v0.17 行为 (不显示 BucketInfo)
+     */
+    listModelsWithStatus(signal?: AbortSignal): Promise<{
+        models: ManagedModel[];
+        status: FilterStatus;
+    }>;
+    /** 查询当前用户账户级权益总览 (v0.19+) */
+    getQuotaSummary(signal?: AbortSignal): Promise<QuotaSummary>;
+    /**
+     * 查询单个模型的能力矩阵
+     * 优先从 listModels 缓存读取, miss 时调用 listModels 刷新
+     */
+    getModelCapabilities(modelID: string, signal?: AbortSignal): Promise<ModelCapabilities>;
+    private getCachedCapabilities;
+    /** 从缓存中查找完整 ManagedModel (未命中返 null) */
+    private getCachedModel;
+    /** 测试辅助: 把占位 ManagedModel 塞入缓存. 仅测试用. */
+    primeModelCacheForTest(...ids: string[]): void;
+    /**
+     * 确保指定 modelID 的 ManagedModel 已在缓存中。
+     *
+     * 语义:
+     *   1. 若缓存命中 → 直接返回
+     *   2. 若未命中 → 调 listModels 刷新一次
+     *   3. 刷新后仍未命中 → 抛 ModelNotFoundError
+     *
+     * 根因修复: 消除未预热场景下 provider="anthropic" 硬编码回退,
+     * 该回退会让 DashScope/Zhipu/DeepSeek 等 non-anthropic 模型被按 Anthropic
+     * 格式编码并打到错误的 /anthropic 端点。
+     */
+    ensureModelCached(modelID: string, signal?: AbortSignal): Promise<ManagedModel>;
+    /**
+     * 构建完整的聊天请求体 (v0.5.0 adapter 模式)
+     *
+     * 根据 provider 选择 adapter, 委托 buildRequestBody 构建格式化的请求体。
+     *
+     * v0.13.x: 前置 ensureModelCached, 消除冷缓存硬编码回退。未知 modelID 抛 ModelNotFoundError.
+     */
+    buildChatRequest(modelID: string, req: ChatRequest, signal?: AbortSignal): Promise<{
+        body: string;
+        adapter: ProviderAdapter;
+    }>;
+    /**
+     * 同步聊天 (适合短回复)
+     * 响应的 tokenRemaining / callRemaining 字段来自服务端 Header, 反映结算后余额
+     * v0.5.0: 根据 provider 自动路由到 /anthropic 或 /chat 端点
+     */
+    chat(modelID: string, req: ChatRequest, signal?: AbortSignal): Promise<ChatResponse>;
+    /**
+     * Anthropic 原生格式同步聊天
+     * v0.5.0: 根据 provider 自动路由
+     *   Anthropic → chatMessagesAnthropic (现有路径, POST /anthropic)
+     *   其他厂商 → chatMessagesOpenAI (POST /chat, 响应转换为 AnthropicResponse)
+     */
+    chatMessages(modelID: string, req: ChatRequest, signal?: AbortSignal): Promise<AnthropicResponse>;
+    private chatMessagesAnthropic;
+    private chatMessagesOpenAI;
+    /**
+     * 流式聊天 (SSE), 通过 async generator 返回事件
+     * v0.5.0: 根据 adapter 路由端点
+     */
+    chatStream(modelID: string, req: ChatRequest, signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    /**
+     * Anthropic 原生格式流式聊天 (SSE)
+     * 调用 POST /managed-models/:id/anthropic, SSE 事件为 Anthropic 协议格式
+     * 无 started/settled/failed 自定义事件, 无 data: [DONE], message_stop 为自然结束
+     */
+    chatMessagesStream(modelID: string, req: ChatRequest, signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    private chatStreamGen;
+    private chatMessagesStreamGen;
+    /**
+     * 流式聊天, 自动解析结算事件和搜索来源
+     *
+     * 返回单一 tagged AsyncIterable, kind 区分 4 种事件:
+     *   - kind='content': 内容增量事件
+     *   - kind='sources': 搜索来源
+     *   - kind='settle':  结算 (token 消耗 + 剩余余额)
+     *
+     * Go 版本 4 channels (eventCh/sourcesCh/settleCh/errCh), 错误抛出取代 errCh。
+     */
+    chatStreamWithUsage(modelID: string, req: ChatRequest, signal?: AbortSignal): AsyncGenerator<{
+        kind: 'content';
+        event: StreamEvent;
+    } | {
+        kind: 'sources';
+        event: SourcesEvent;
+    } | {
+        kind: 'settle';
+        event: StreamSettlement;
+    }, void, void>;
+    apiURL(path: string): string;
+    /** GET/POST/... 通用 JSON 调用 (返回 result 已 typed) */
+    doJSON<T>(method: string, path: string, body: unknown | null, signal?: AbortSignal): Promise<T>;
+    /** 与 doJSON 相同, 但返回响应 Headers (用于提取 X-Token-Remaining 等) */
+    doJSONFull<T>(method: string, path: string, body: unknown | null, signal?: AbortSignal): Promise<{
+        result: T;
+        headers: Headers;
+    }>;
+    private doJSONFullInternal;
+    /** doJSONFull 的 raw bytes 变体 (chat 用, 不立即 JSON.parse) */
+    doJSONFullRaw(method: string, path: string, body: unknown | null, signal?: AbortSignal): Promise<{
+        result: Uint8Array;
+        headers: Headers;
+    }>;
+    private doJSONFullRawInternal;
+    /**
+     * 公共端点请求
+     * 有 token 时自动附带 (享受认证用户待遇), 无 token 时匿名请求
+     * 不做 401 重试 (公共端点不应要求认证)
+     */
+    doPublicJSON<T>(method: string, path: string, body: unknown | null, signal?: AbortSignal): Promise<T>;
+    /**
+     * fetch 包装 — 错误经 classifyTransport 转 NetworkError
+     * 6 处原始 fetch() 全部走此 helper
+     */
+    doRequest(req: {
+        method: string;
+        url: string;
+        headers: Record<string, string>;
+        body?: string;
+    }, signal?: AbortSignal): Promise<Response>;
+    /**
+     * 带 RetryPolicy 的 doRequest 包装 — 仅用于同步 (非流式) 路径.
+     *
+     * 重试触发:
+     *   - transport 层 err (NetworkError isTimeout/isEOF) → 重试
+     *   - HTTP 5xx / 429 → 主动构造 HTTPError 喂给 onRetryable, 默认重试
+     *   - 其他 (HTTP 2xx/3xx/4xx 非 429 / DNS / StreamError) → 不重试
+     *
+     * 流式路径 (chatMessagesStreamGen / chatStreamGen) **不得**调用此函数, 必须直接用 doRequest.
+     */
+    doRequestWithRetry(req: {
+        method: string;
+        url: string;
+        headers: Record<string, string>;
+        body?: string;
+    }, signal?: AbortSignal): Promise<Response>;
+}
+
+declare module '../client' {
+    interface Client {
+        /** 查询当前用户的权益余额 (聚合) */
+        getBalance(signal?: AbortSignal): Promise<EntitlementBalance>;
+        /** 查询详细余额 (含每条权益明细) */
+        getBalanceDetail(signal?: AbortSignal): Promise<BalanceDetail>;
+        /** 查询当前用户权益列表; status: "ACTIVE" / "EXPIRED" / "" (全部) */
+        listEntitlements(status: string, signal?: AbortSignal): Promise<EntitlementItem[]>;
+        /** 查询核销记录 (分页) */
+        listConsumeRecords(page: number, pageSize: number, signal?: AbortSignal): Promise<ConsumeRecordPage>;
+        /** 领取当月免费额度 — 幂等: 已领取时返回已有权益 */
+        claimMonthlyFree(signal?: AbortSignal): Promise<EntitlementItem>;
+        /** 查询当前用户在指定模型下的剩余 token (raw + ETU) */
+        getByModel(modelID: string, signal?: AbortSignal): Promise<ModelByQuotaResponse>;
+        /** 列出当前用户的全部桶 */
+        listBuckets(signal?: AbortSignal): Promise<ModelBucket[]>;
+        /** 拉取模型系数表; SDK 自带 8s TTL 内存缓存以减小调用风暴. */
+        listCoefficients(signal?: AbortSignal): Promise<ModelCoefficient[]>;
+        /** 手动失效系数缓存 (admin 调价后建议立即调一次) */
+        invalidateCoefficientCache(): void;
+    }
+}
+
+declare module '../client' {
+    interface Client {
+        /** 获取商城流量包列表 (兼容 yudao 分页和直接数组两种格式) */
+        listTokenPackages(signal?: AbortSignal): Promise<TokenPackage[]>;
+        /** 获取流量包详情 */
+        getTokenPackageDetail(packageID: string, signal?: AbortSignal): Promise<TokenPackage>;
+        /** 购买流量包 (创建订单) */
+        buyTokenPackage(packageID: string, payload: PayPayload | null, signal?: AbortSignal): Promise<Order>;
+        /** 查询订单支付状态 */
+        getOrderStatus(orderID: string, signal?: AbortSignal): Promise<OrderStatus>;
+        /** 查询我的订单列表 */
+        listMyOrders(signal?: AbortSignal): Promise<Order[]>;
+        /**
+         * 轮询订单支付状态直到终态
+         * 成功支付返回 status; 终态失败抛 OrderTerminalError
+         * pollIntervalMs <= 0 时默认 2 秒
+         */
+        waitForPayment(orderID: string, pollIntervalMs: number, signal?: AbortSignal): Promise<OrderStatus>;
+    }
+}
+
+declare module '../client' {
+    interface Client {
+        /** 获取钱包统计 (余额/月消费/月充值) */
+        getWalletStats(signal?: AbortSignal): Promise<WalletStats>;
+        /** 获取最近交易记录 */
+        getWalletTransactions(signal?: AbortSignal): Promise<Transaction[]>;
+    }
+}
+
+declare module '../client' {
+    interface Client {
+        /** 浏览技能商店 (公共端点, 无需认证) */
+        browseSkillStore(query: SkillStoreQuery, signal?: AbortSignal): Promise<SkillStoreItem[]>;
+        /** 浏览公共技能商店 (V3 分页接口) */
+        browseSkills(page: number, pageSize: number, category: string, keyword: string, tag: string, source: string, signal?: AbortSignal): Promise<SkillBrowseResponse>;
+        /** 轻量浏览公共技能商店 (fields=minimal, 响应体积缩减 90%+) */
+        browseSkillsList(page: number, pageSize: number, category: string, keyword: string, tag: string, source: string, signal?: AbortSignal): Promise<SkillBrowseListResponse>;
+        /** 获取技能商店中某个技能的详情 (公共端点) */
+        getSkillDetail(skillID: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /** 按 key 精确查找公共技能 (公共端点) */
+        resolveSkill(key: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /** 安装技能到当前用户的租户空间 (需 OAuth scope: skill_store) */
+        installSkill(skillID: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /**
+         * 下载技能 ZIP 包 (公共端点, 双模式)
+         * 有 token 时自动附带 (享受无限流), 无 token 时匿名 (受限流)
+         * @returns [data, filename]; 限流时抛 RateLimitError
+         */
+        downloadSkill(skillID: string, signal?: AbortSignal): Promise<{
+            data: Uint8Array;
+            filename: string;
+        }>;
+        /**
+         * 上传技能 ZIP 包
+         * @param scope "TENANT"
+         * @param intent "PERSONAL" (仅自己用) 或 "PUBLIC_INTENT" (走认证→公开)
+         */
+        uploadSkill(zipData: Uint8Array, scope: string, intent: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /** 获取技能统计概览 */
+        getSkillSummary(signal?: AbortSignal): Promise<SkillSummary>;
+        /** 触发技能认证管线 (异步) */
+        certifySkill(skillID: string, signal?: AbortSignal): Promise<void>;
+        /** 查询技能认证状态 */
+        getCertificationStatus(skillID: string, signal?: AbortSignal): Promise<CertificationStatus>;
+        /** 根据自然语言描述生成技能定义 (基于独立 LLM) */
+        generateSkill(req: GenerateSkillRequest, signal?: AbortSignal): Promise<GenerateSkillResult>;
+        /** 优化已有技能定义 */
+        optimizeSkill(req: OptimizeSkillRequest, signal?: AbortSignal): Promise<OptimizeSkillResult>;
+        /** 校验技能定义正确性 */
+        validateSkill(skillName: string, signal?: AbortSignal): Promise<void>;
+    }
+}
+
+declare module '../client' {
+    interface Client {
+        /** 获取当前用户租户下的所有工具 (Skill 优先 + Plugin 兜底) */
+        listTools(signal?: AbortSignal): Promise<ToolView[]>;
+        /** 获取单个工具详情 */
+        getTool(toolID: string, signal?: AbortSignal): Promise<ToolView>;
+    }
+}
+
+declare module '../client' {
+    interface Client {
+        /** 分页查询通知列表 */
+        listNotifications(page: number, pageSize: number, typeFilter: string, signal?: AbortSignal): Promise<NotificationList>;
+        /** 获取未读通知数量 */
+        getUnreadCount(signal?: AbortSignal): Promise<number>;
+        /** 标记单条通知已读 */
+        markNotificationRead(id: string, signal?: AbortSignal): Promise<void>;
+        /** 标记全部通知已读 */
+        markAllNotificationsRead(signal?: AbortSignal): Promise<void>;
+        /** 删除通知 */
+        deleteNotification(id: string, signal?: AbortSignal): Promise<void>;
+        /** 注册推送设备 token */
+        registerDevice(reg: DeviceRegistration, signal?: AbortSignal): Promise<void>;
+        /** 注销推送设备 token */
+        unregisterDevice(token: string, signal?: AbortSignal): Promise<void>;
+        /** 获取通知偏好设置 */
+        listNotificationPreferences(signal?: AbortSignal): Promise<NotificationPreference[]>;
+        /** 更新通知偏好 */
+        updateNotificationPreference(typeCode: string, pref: NotificationPreference, signal?: AbortSignal): Promise<void>;
+    }
+}
+
+declare module './client' {
+    interface Client {
+        /**
+         * 配置请求前的底线防御 (体积 / deny-list / 深度)。
+         * 传空值 {} 关闭 (所有字段为零 = 禁用)。
+         * 并发安全, 可在任意时间调用。
+         */
+        setDefensiveSanitize(cfg: MinimalSanitizeConfig): void;
+        /**
+         * 开启后, 每次请求前 SDK 会从 rawMessages 中剥除带 acosmi_ephemeral:true 标记的 block,
+         * 并联动剥除引用已剥 tool_use 的 tool_result, 避免 provider 报 "tool_use_id 不存在".
+         *
+         * 标记来源: 网关在响应 content_block_start 中 in-band 注入; 消费者把上一轮 assistant
+         * 回复原样拼回 history 即可触发剥离。
+         */
+        setAutoStripEphemeralHistory(on: boolean): void;
+        /**
+         * 在 buildChatRequest 开头调用, 把配置化的防御策略应用到 req。
+         * 未配置时立即返回, 零开销。
+         *
+         * 失败时抛错 — 调用方应放弃本次请求。
+         */
+        applyRequestSanitizers(req: ChatRequest): void;
+    }
+}
+
+/** WebSocket 长连接配置 */
+interface WSConfig {
+    /** 收到服务端事件回调 */
+    onEvent?: (ev: WSEvent) => void;
+    /** 连接建立回调 */
+    onConnect?: () => void;
+    /** 断线回调 */
+    onDisconnect?: (err: unknown) => void;
+    /** 自动订阅的主题 */
+    topics?: string[];
+    /** 最小重连间隔 (ms, 默认 2000) */
+    reconnectMinMs?: number;
+    /** 最大重连间隔 (ms, 默认 60000) */
+    reconnectMaxMs?: number;
+    /** 是否自动重连 (默认 true) */
+    autoReconnect?: boolean;
+}
+declare module './client' {
+    interface Client {
+        /**
+         * 建立 WebSocket 长连接 — 等待首次连接成功或 abort。
+         */
+        connect(cfg: WSConfig, signal?: AbortSignal): Promise<void>;
+        /** 优雅断开 WebSocket 连接 */
+        disconnect(): Promise<void>;
+        /** WebSocket 是否已连接 */
+        isConnected(): boolean;
+    }
+}
+
+/** POST /api/v4/crabcode_cli_feedback 返回体 */
+interface BugReportResult {
+    /** 服务端生成的 UUID (写入 GitHub Issue body 用) */
+    feedback_id: string;
+    /** 公开页链接, 形如 https://<base>/chat/crabcode/bug/<uuid> */
+    detail_url: string;
+}
+/**
+ * GET /api/v4/crabcode/bug/:id 返回体 (公开 ViewModel)
+ *
+ * errors / transcript / extras 用 unknown[] / Record<string, unknown>:
+ * 客户端 reportData schema 会随版本变, SDK 不强 typed.
+ */
+interface BugView {
+    id: string;
+    description: string;
+    platform?: string;
+    terminal?: string;
+    version?: string;
+    messageCount: number;
+    hasErrors: boolean;
+    status: string;
+    clientDatetime?: string;
+    createdAt: string;
+    errors?: unknown[];
+    transcript?: unknown[];
+    extras?: Record<string, unknown>;
+}
+declare module './client' {
+    interface Client {
+        /**
+         * 上报一份 CrabCode bug 报告.
+         *
+         * reportData 是任意 JSON 可编码对象, 后端只解析为 map 做脱敏 + 字段抽取.
+         *
+         * 错误:
+         *   - HTTPError 401 — token 过期 (内部已做一次 refresh + retry, 仍 401 抛出)
+         *   - HTTPError 403 type="permission_error" message 含 "Custom data retention settings"
+         *     — 用户所在组织 ZDR, 拒绝收集 (调用方应提示用户走外部渠道)
+         *   - HTTPError 400 type="invalid_request_error" — content 不是合法 JSON 或 reportData 编码失败
+         *   - HTTPError 429 — 限流 20/h/user (retryAfter 字段含建议等待秒数)
+         *   - NetworkError — 传输层错误 (timeout / EOF / unreachable)
+         */
+        submitBugReport(reportData: unknown, signal?: AbortSignal): Promise<BugReportResult>;
+        /**
+         * 取公开 ViewModel (无需 auth, 任意人凭 ID 可读).
+         *
+         * 用途: SSR 公开页后端 fetch / 维护者诊断 CLI / 集成测试.
+         *
+         * 错误:
+         *   - HTTPError 404 — bug 不存在或被软删
+         *   - HTTPError 429 — 限流 60/min/IP
+         *   - NetworkError — 传输层错误
+         */
+        getBugReport(bugID: string, signal?: AbortSignal): Promise<BugView>;
+    }
+}
+
+export { AnthropicResponse, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type Config, ConsumeRecordPage, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, QuotaSummary, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerMetadata, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, isSSLError, modelScopes, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };