@acosmi/sdk-ts 1.4.1 → 1.4.2

package/dist/node/index-DEA6LXw6.d.ts

@@ -0,0 +1,409 @@
+/** 模型能力矩阵 — 下游通过此结构决定 UI 功能开关和 Beta Header 注入 */
+interface ModelCapabilities {
+    supports_thinking: boolean;
+    supports_adaptive_thinking: boolean;
+    /** 交错思考 (Interleaved Thinking) */
+    supports_isp: boolean;
+    supports_web_search: boolean;
+    supports_tool_search: boolean;
+    supports_structured_output: boolean;
+    supports_effort: boolean;
+    /** 模型是否支持 thinking_level="max" 强度档 (深度思考) */
+    supports_max_effort: boolean;
+    /** Opus 4.6 独有 (Speed="fast") */
+    supports_fast_mode: boolean;
+    /** Auto 模式 (模型自主选择工具/搜索策略) */
+    supports_auto_mode: boolean;
+    supports_1m_context: boolean;
+    supports_prompt_cache: boolean;
+    /** 通过 context-management beta 控制 */
+    supports_cache_editing: boolean;
+    /** Claude 4 内置 */
+    supports_token_efficient: boolean;
+    supports_redact_thinking: boolean;
+    max_input_tokens: number;
+    max_output_tokens: number;
+    /**
+     * 桌面视觉理解 sidecar 能力 (v1.2+):
+     * 为 true 表示该模型适合作为桌面截图解析 sidecar — 输入 screenshot,
+     * 输出结构化 UI/视觉描述, 供非多模态主模型消费 (CrabCode desktop automation /
+     * computer-use 选模型时使用).
+     *
+     * 与 ManagedModel.inputModalities=['image'] 是正交两件事:
+     *   - inputModalities 描述"模型能不能吃图片输入"
+     *   - supports_desktop_visual_understanding 描述"模型是不是被运营标记为
+     *     适合做桌面 UI 解析的 sidecar" (有些通用视觉模型并不擅长 UI 解析)
+     *
+     * 调用方不应通过模型名 substring 推断此能力; 必须读上游下发字段.
+     */
+    supports_desktop_visual_understanding?: boolean;
+}
+/**
+ * 模型可接收的用户输入模态 (v1.2+).
+ *
+ * - 'text': 文本输入
+ * - 'image': 截图 / 图片输入 (多模态)
+ *
+ * ManagedModel.inputModalities 包含 'image' 才允许向该模型直接发图;
+ * 缺失字段时调用方应保守按 text-only / unknown 处理.
+ */
+type InputModality = 'text' | 'image';
+/** BucketClass 字面量常量 — V30 二轮审计 D-P1-3 修复 */
+declare const BucketClassCommercial = "COMMERCIAL";
+declare const BucketClassGeneric = "GENERIC";
+/**
+ * 用户在某 modelId 上的桶余额聚合视图 (V30 entitlement-listing).
+ *
+ * 多桶聚合规则 (上游 nexus-v4 计算后下发, 全部单位为 ETU):
+ *   - quotaEtu / usedEtu / remainingEtu: 该 modelId 下用户全部 active 桶求和
+ *   - sharedPoolEtu: 求和量中"来自通配桶"的部分 (跨模型可消耗)
+ *   - bucketClass / expiresAt: 取最高优先级桶
+ *   - expired: 全部桶都过期才置 true
+ */
+interface BucketInfo {
+    quotaEtu: number;
+    usedEtu: number;
+    remainingEtu: number;
+    sharedPoolEtu?: number;
+    expiresAt?: string;
+    bucketClass: string;
+    expired?: boolean;
+    /** v0.19+ — GENERIC alive 桶 tokenRemaining 求和 ("免费余额", 真实可消费) */
+    freeRemainingEtu: number;
+    /** v0.19+ — COMMERCIAL alive 桶 tokenRemaining 求和 ("付费余额") */
+    paidRemainingEtu: number;
+}
+/** 大小写不敏感判定 — 与 buildBucketView (managed_model.go) EqualFold 语义对齐 */
+declare function bucketInfoIsCommercial(b: BucketInfo | null | undefined): boolean;
+/** 托管模型 */
+interface ManagedModel {
+    id: string;
+    name: string;
+    provider: string;
+    modelId: string;
+    maxTokens: number;
+    isEnabled: boolean;
+    pricePerMTok?: number;
+    isDefault?: boolean;
+    contextWindow?: number;
+    capabilities: ModelCapabilities;
+    /**
+     * 上游 gateway 为此模型启用的请求格式列表
+     * 取值: "anthropic" | "openai"
+     * 空值表示上游未声明, SDK 回落 provider 硬编码分支 (向后兼容)
+     */
+    supported_formats?: string[];
+    /**
+     * 上游建议客户端优先使用的格式
+     * 取值: "anthropic" | "openai"; 空值等价于 supported_formats[0]
+     */
+    preferred_format?: string;
+    /**
+     * 当前用户在此模型上的桶余额聚合 (V0.18 V30 entitlement-listing).
+     *
+     * 仅当调用方为非 admin 用户 (web user / desktop OAuth) 时上游才会返回此字段:
+     *   - admin / X-Internal-Bypass 调用 → 缺失
+     *   - 普通用户 → 非空, 含 quota/used/remaining 求和
+     */
+    bucketInfo?: BucketInfo;
+    /**
+     * 模型可接收的用户输入模态 (v1.2+, CrabCode desktop automation / computer-use 选模型用).
+     *
+     * 取值: 'text' | 'image' 的子集. 'image' 表示模型可直接接收 screenshot/image 输入.
+     *
+     * 兼容上游字段名 input_modalities (snake_case) — listModels 在写缓存前会做归一化.
+     *
+     * **缺失语义**: 上游未下发时该字段为 undefined, 调用方必须保守按 text-only / unknown
+     * 处理, 严禁默认假设支持 image. 同样严禁用模型名 substring 反推 modality.
+     */
+    inputModalities?: InputModality[];
+}
+/** 单桶视图 — QuotaSummary.freeBuckets/paidBuckets 元素 */
+interface BucketRow {
+    bucketId: string;
+    /** 精确桶为具体 modelId, 通配桶为 "*" */
+    modelId: string;
+    /** COMMERCIAL | GENERIC */
+    bucketClass: string;
+    tokenQuota: number;
+    tokenUsed: number;
+    tokenRemaining: number;
+    /** 永久桶为 undefined */
+    expiresAt?: string;
+    expired?: boolean;
+}
+declare function bucketRowIsCommercial(r: BucketRow | null | undefined): boolean;
+/**
+ * GET /api/v4/entitlements/quota-summary 返回体, 调用 client.getQuotaSummary 获取.
+ *
+ * 设计目的: 个人中心钱包栏一次性展示"我还有多少免费 + 多少付费"+ 各自最近到期时间.
+ */
+interface QuotaSummary {
+    /** GENERIC (免费/赠送) alive 桶 tokenRemaining 求和 */
+    freeTotalEtu: number;
+    /** COMMERCIAL (付费购买) alive 桶 tokenRemaining 求和 */
+    paidTotalEtu: number;
+    /** GENERIC 桶详情 (含过期, UI 列流水); 空时为空数组 */
+    freeBuckets: BucketRow[];
+    /** COMMERCIAL 桶详情 (含过期); 空时为空数组 */
+    paidBuckets: BucketRow[];
+    /** GENERIC alive 桶中最早到期; 永久桶/无 alive 时缺失 */
+    nextFreeExpiresAt?: string;
+    /** COMMERCIAL alive 桶中最早到期; 同上 */
+    nextPaidExpiresAt?: string;
+}
+/** 聊天消息 (简单文本格式, CrabClaw 使用) */
+interface ChatMessage {
+    role: string;
+    content: string;
+}
+/** Anthropic 响应内容块 */
+interface ChatContentBlock {
+    type: string;
+    text?: string;
+    citations?: unknown;
+    thinking?: string;
+    signature?: string;
+    data?: string;
+    id?: string;
+    name?: string;
+    /** json.RawMessage in Go */
+    input?: unknown;
+    server_name?: string;
+    caller?: unknown;
+    tool_use_id?: string;
+    content?: unknown;
+    is_error?: boolean;
+}
+/** Anthropic 格式 token 用量 */
+interface ChatUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/** 三档思考级别 (v0.9.0) */
+declare const ThinkingOff = "off";
+declare const ThinkingHigh = "high";
+declare const ThinkingMax = "max";
+/** 标准思考最低 maxTokens — CrabCode 默认 MAX_OUTPUT_TOKENS_DEFAULT = 32_000 */
+declare const ThinkingHighMinMaxTokens = 32000;
+/** 深度思考回退 maxTokens — Opus 4.6 上限 128K */
+declare const ThinkingMaxFallbackMaxTokens = 128000;
+/** 控制模型思考行为 */
+interface ThinkingConfig {
+    /** "enabled" | "disabled" | "adaptive" */
+    type: string;
+    /** 仅 type="enabled" 时 (旧模型回退) */
+    budget_tokens?: number;
+    /** 思考级别 (v0.9.0): "off" | "high" | "max" */
+    level?: string;
+    /** "none" | "summary" | "" (默认空=完整) */
+    display?: string;
+}
+/** 根据三档 level 创建配置 */
+declare function newThinkingConfig(level: string): ThinkingConfig;
+/** 服务端工具定义 — SDK 将工具 schema 合入 API 请求的 tools 数组 */
+interface ServerTool {
+    type: string;
+    name: string;
+    config?: Record<string, unknown>;
+}
+/** Server Tool 类型常量 */
+declare const ServerToolTypeWebSearch = "web_search_20250305";
+/** 地理位置 */
+interface GeoLoc {
+    /** ISO 3166-1 alpha-2 */
+    country: string;
+    city?: string;
+}
+/** ServerTool.config 结构 (type=web_search_20250305) */
+interface WebSearchConfig {
+    /** 每请求最大搜索次数, 默认 8 */
+    max_uses?: number;
+    /** 域名白名单 (与 blocked_domains 互斥) */
+    allowed_domains?: string[];
+    /** 域名黑名单 (与 allowed_domains 互斥) */
+    blocked_domains?: string[];
+    user_location?: GeoLoc;
+}
+/** 控制推理努力级别 */
+interface EffortConfig {
+    /** "low" | "medium" | "high" | "max" */
+    level: string;
+}
+/** 控制输出格式 (结构化输出) */
+interface OutputConfig {
+    /** "json_schema" | "" */
+    format?: string;
+    schema?: unknown;
+}
+/**
+ * 创建搜索 Server Tool 的便捷方法
+ * allowed_domains 与 blocked_domains 互斥, 同时传入抛 Error
+ */
+declare function newWebSearchTool(cfg?: WebSearchConfig | null): ServerTool;
+/**
+ * 聊天请求
+ *
+ * 基础字段供 CrabClaw 使用, 扩展字段供 CrabCode 使用。
+ * 所有新增字段零值不改变行为 (向后兼容)。
+ *
+ * 注意：扩展字段（rawMessages/system/tools/...）不会被原样 JSON.stringify,
+ * 而由 buildRequestBody (adapter) 选择性序列化到请求体。
+ */
+interface ChatRequest {
+    messages?: ChatMessage[];
+    stream?: boolean;
+    max_tokens?: number;
+    /** 复杂消息体 (含 content blocks / 多模态), 非 nil 时优先于 messages */
+    rawMessages?: unknown;
+    /** string 或 ContentBlock[] */
+    system?: unknown;
+    /** 标准工具定义 (Tool[]) */
+    tools?: unknown;
+    temperature?: number;
+    thinking?: ThinkingConfig;
+    metadata?: Record<string, string>;
+    /** 显式 beta (SDK 自动合并) */
+    betas?: string[];
+    /** 服务端工具 (buildRequestBody 合入 tools 数组) */
+    serverTools?: ServerTool[];
+    /** "" | "fast" (Fast Mode) */
+    speed?: string;
+    effort?: EffortConfig;
+    outputConfig?: OutputConfig;
+    /** 任意扩展字段 (buildRequestBody 合入请求体) */
+    extraBody?: Record<string, unknown>;
+    /**
+     * v0.13.0: OpenAI wire format 原生字段。AnthropicAdapter 忽略,
+     * OpenAIAdapter 按 OpenAI 规范序列化。
+     *
+     * 对应 OpenAI `parallel_tool_calls` 顶层字段, undefined = 不设置 (沿用上游默认 true)。
+     */
+    parallelToolCalls?: boolean;
+}
+/** 联网搜索结果来源 (与后端 adk/stream_helpers.go SourceItem 对齐) */
+interface WebSearchSource {
+    title: string;
+    url: string;
+    snippet?: string;
+}
+/** 搜索来源事件 (从 SSE "sources" 事件解析) */
+interface SourcesEvent {
+    sources: WebSearchSource[];
+    session_id?: string;
+}
+/**
+ * 从 StreamEvent 中解析搜索来源
+ * 返回 null 表示该事件不是 sources 类型
+ */
+declare function parseSourcesEvent(ev: StreamEvent): SourcesEvent | null;
+/**
+ * 同步聊天响应 (Anthropic format, v0.4.1)
+ *
+ * tokenRemaining / callRemaining / modelTokenRemaining* 不在 wire JSON 中, 由 client 从 Header 填充。
+ * 哨兵 -1 表示服务端未返回。
+ */
+interface ChatResponse {
+    id: string;
+    type: string;
+    model: string;
+    role: string;
+    content: ChatContentBlock[];
+    stop_reason: string;
+    usage: ChatUsage;
+    /** -1 表示服务端未返回 */
+    tokenRemaining: number;
+    callRemaining: number;
+    modelTokenRemaining: number;
+    modelTokenRemainingETU: number;
+}
+/**
+ * SSE 流式事件
+ *
+ * v0.11.0 新增 blockIndex/blockType/ephemeral 三字段 (in-band content block 元数据)。
+ * 零值等价 v0.10.0 行为, 未识别的事件三字段全部零值。
+ */
+interface StreamEvent {
+    event: string;
+    data: string;
+    /** 对齐 Anthropic content_block_start/delta/stop 的 index 字段 */
+    blockIndex?: number;
+    /** 由 content_block_start 解析得到, delta/stop 从 index→type 映射查出 */
+    blockType?: string;
+    /** 网关标记此 block 下一轮不应回传 */
+    ephemeral?: boolean;
+}
+/**
+ * 流式结算事件 (从 settled SSE 事件解析)
+ * 包含本次请求的 token 消耗及结算后的剩余余额
+ */
+interface StreamSettlement {
+    requestId: string;
+    consumeStatus: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** 结算后剩余 token (-1 表示服务端未返回) */
+    tokenRemaining: number;
+    /** 结算后剩余调用次数 (-1 表示服务端未返回) */
+    callRemaining: number;
+}
+/** 从 settled 类型的 StreamEvent 中解析结算信息. 不是 settled 类型则返回 null. */
+declare function parseSettlement(ev: StreamEvent): StreamSettlement | null;
+
+/** 标识请求格式 */
+declare enum ProviderFormat {
+    /** Anthropic 原生格式 */
+    Anthropic = 0,
+    /** OpenAI 兼容格式 */
+    OpenAI = 1
+}
+/** 将 ChatRequest 转换为特定格式的 adapter 接口 */
+interface ProviderAdapter {
+    /** 此 adapter 使用的请求格式 */
+    format(): ProviderFormat;
+    /**
+     * API 路径后缀
+     * Anthropic: "/anthropic", OpenAI: "/chat"
+     */
+    endpointSuffix(): string;
+    /**
+     * 将 ChatRequest 转换为 HTTP body (object → JSON.stringify)
+     * caps 用于条件化字段注入 (如 betas)
+     */
+    buildRequestBody(caps: ModelCapabilities, req: ChatRequest): Record<string, unknown>;
+    /** 解析同步响应 body 为 ChatResponse */
+    parseResponse(body: Uint8Array | string): ChatResponse;
+    /**
+     * 解析一行 SSE data 为 StreamEvent
+     * 返回 { event, done }; done=true 表示流结束 ([DONE] 或 message_stop)
+     */
+    parseStreamLine(eventType: string, data: string): {
+        event: StreamEvent;
+        done: boolean;
+    };
+}
+
+/**
+ * 根据 provider 返回对应的 adapter (v0.5.0 遗留 API, 向后兼容)
+ * 新代码应使用 getAdapterForModel
+ */
+declare function getAdapter(provider: string): ProviderAdapter;
+/**
+ * 按 ManagedModel 的 preferred_format / supported_formats 选择 adapter
+ *
+ * 决策顺序:
+ *  1. preferred_format 非空 → 按其值返回 (anthropic | openai)
+ *  2. supported_formats 含 "anthropic" → AnthropicAdapter
+ *  3. supported_formats 含 "openai" → OpenAIAdapter
+ *  4. 两字段均空 (旧上游) → 回落 provider 名硬编码 (原 getAdapter 行为)
+ *
+ * 这使得 dashscope / zhipu / deepseek 等 provider 的模型如果上游启用了
+ * Anthropic 兼容端点, 也能走 /anthropic 路径, 不再被 provider 字符串硬编码到 /chat
+ * 导致 tool_reference 400.
+ */
+declare function getAdapterForModel(m: ManagedModel): ProviderAdapter;
+
+export { parseSourcesEvent as A, BucketClassCommercial as B, type ChatRequest as C, type EffortConfig as E, type GeoLoc as G, type InputModality as I, type ManagedModel as M, type OutputConfig as O, type ProviderAdapter as P, type QuotaSummary as Q, type StreamEvent as S, type ThinkingConfig as T, type WebSearchConfig as W, type ModelCapabilities as a, type ChatResponse as b, type SourcesEvent as c, type StreamSettlement as d, BucketClassGeneric as e, type BucketInfo as f, type BucketRow as g, type ChatContentBlock as h, type ChatMessage as i, type ChatUsage as j, ProviderFormat as k, type ServerTool as l, ServerToolTypeWebSearch as m, ThinkingHigh as n, ThinkingHighMinMaxTokens as o, ThinkingMax as p, ThinkingMaxFallbackMaxTokens as q, ThinkingOff as r, type WebSearchSource as s, bucketInfoIsCommercial as t, bucketRowIsCommercial as u, getAdapter as v, getAdapterForModel as w, newThinkingConfig as x, newWebSearchTool as y, parseSettlement as z };