@icen.ai/ui 0.5.0 → 0.8.0

package/dist/behaviors/ai-provider.d.mts

@@ -0,0 +1,198 @@
+import { AiContent, AiUsage, AiContentPart } from './ai-core.js';
+
+interface AiProviderModel {
+    id: string;
+    label: string;
+    /** 上下文窗口 token 数（模型选择弹层展示如 1M） */
+    context?: number;
+    /** 单次输出上限 token 数 */
+    outputLimit?: number;
+    /** 定价（USD / MTok，2026-10 调研近似值）；缺省 = 不猜价（estimateCost 返回 undefined） */
+    pricing?: AiPricing;
+}
+/** 定价（USD / MTok）：cacheRead 缺省按 input 价；cacheWrite 缺省按 input × 1.25（cache 写溢价惯例） */
+interface AiPricing {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+interface AiProviderDef {
+    id: string;
+    label: string;
+    /** 单色 svg 字母章（渲染时经 ai-core svgIcon() 消毒） */
+    icon: string;
+    /** 默认 API 基址；createAiClient 可覆盖（自定义网关/代理是一等公民） */
+    baseURL: string;
+    /** /chat/completions | /messages */
+    chatPath: string;
+    /** 线协议族：openai 族（OpenAI/DeepSeek/GLM/Kimi）| anthropic 族 */
+    wire: 'openai' | 'anthropic';
+    /** bearer → Authorization: Bearer；x-api-key → x-api-key 头 */
+    auth: 'bearer' | 'x-api-key';
+    /** 附加请求头（如 anthropic-version / dangerous-direct-browser-access） */
+    extraHeaders?: Record<string, string>;
+    models: AiProviderModel[];
+    /** 浏览器直连 CORS：'yes'（Anthropic 官方支持）/ 'no'（OpenAI 官方禁止）/ 'unknown'（无承诺，建议代理） */
+    browserDirect: 'yes' | 'no' | 'unknown';
+}
+/** 注册（或覆盖）一个 provider；第三方/自建网关注册入口。 */
+declare function registerAiProvider(def: AiProviderDef): void;
+/** 取 provider 定义；未注册返回 undefined。 */
+declare function getAiProvider(id: string): AiProviderDef | undefined;
+/** 全部已注册 provider（副本数组，内置在前）。 */
+declare function listAiProviders(): AiProviderDef[];
+/** 按注册表定价估算一次用量的成本（USD）：cacheRead 缺省按 input 价、cacheWrite 缺省按 input × 1.25。 */
+declare function estimateCost(usage: AiUsage, provider: string, model: string): number | undefined;
+declare class AiProviderError extends Error {
+    readonly provider: string;
+    /** HTTP 状态码；网络层失败为 0 */
+    readonly status: number;
+    /** 归一错误类型：provider 的 error.type/code，或 network / cancelled / parse / http_error */
+    readonly type: string;
+    /** 原始错误体（HTTP body / 异常对象），排障用 */
+    readonly raw?: unknown;
+    constructor(init: {
+        provider: string;
+        status: number;
+        type: string;
+        message: string;
+        raw?: unknown;
+    });
+}
+interface AiAuditEntry {
+    id: string;
+    /** epoch 毫秒 */
+    ts: number;
+    provider: string;
+    model: string;
+    baseURL: string;
+    /** 是否流式请求 */
+    stream: boolean;
+    status: 'ok' | 'error';
+    durationMs: number;
+    /** 首 token 延迟（流式；非流式缺省） */
+    ttftMs?: number;
+    /** 本次成本（USD，定价表命中时） */
+    cost?: number;
+    /** 归一 usage（错误且无用量信息时缺省） */
+    usage?: AiUsage;
+    /** 错误信息（含取消：'请求已取消'） */
+    error?: string;
+}
+/** 审计聚合汇总（spec §12.2） */
+interface AiAuditTotals {
+    usage: AiUsage;
+    cost: number;
+    requests: number;
+    errors: number;
+    /** 平均首 token 延迟（有 ttft 记录的条目） */
+    avgTtftMs?: number;
+}
+interface AiAuditor {
+    log(entry: AiAuditEntry): void;
+    /** 全部记录（时间升序，副本） */
+    list(): AiAuditEntry[];
+    clear(): void;
+    /** 全量聚合（各段求和）——直接喂 renderAiUsage / renderAiUsageRing */
+    summary(): AiUsage;
+    /** 完整汇总：usage + cost + 计数 + 平均 TTFT——喂 renderAiAudit 的 totals 行 */
+    totals(): AiAuditTotals;
+    /** 按 `${provider}/${model}` 分组聚合 */
+    byModel(): Record<string, AiUsage>;
+}
+interface AiAuditorOptions {
+    /** localStorage key：给则持久化（写读该 key）；SSR/隐私模式下静默降级为内存环形 */
+    persist?: string;
+    /** 环形上限，默认 100；超出丢弃最旧 */
+    max?: number;
+}
+/** 环形审计器：max 条封顶；persist 给 localStorage key 则写读它（SSR 安全）。 */
+declare function createAiAuditor(opts?: AiAuditorOptions): AiAuditor;
+type AiChatRole = 'system' | 'user' | 'assistant' | 'tool';
+interface AiChatMessage {
+    role: AiChatRole;
+    /** 标准化内容（spec §10）：字符串（纯文本）或 AiContentPart[]（多模态） */
+    content: AiContent;
+    /** role 'tool' 时必填：openai 族 → tool_call_id；anthropic 族 → 映射为 user 的 tool_result block（真回灌） */
+    toolCallId?: string;
+    /** anthropic 族：本消息末块打 cache_control 断点（prompt 缓存一等公民）；openai 族自动缓存、忽略 */
+    cacheControl?: boolean;
+}
+interface AiChatRequest {
+    messages: AiChatMessage[];
+    /** 覆盖客户端默认模型 */
+    model?: string;
+    temperature?: number;
+    /** anthropic 族必填（API 层），缺省 4096 */
+    maxTokens?: number;
+    /** 外部中止信号（与 stream 会话的 cancel() 叠加生效） */
+    signal?: AbortSignal;
+}
+interface AiChatResult {
+    text: string;
+    /** ai-core normalizeUsage 归一；无任何用量信息时为 {} */
+    usage: AiUsage;
+    /** 定价表命中时的本次成本（USD） */
+    cost?: number;
+    /** 响应内容部件（非流式且响应为 content parts 数组时归一出，含图/文件等多模态回执） */
+    parts?: AiContentPart[];
+    finishReason?: string;
+    /** 原始 usage 对象（流式=最终快照；排障用） */
+    raw?: unknown;
+}
+type AiStreamChunk = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'done';
+} | {
+    type: 'error';
+    message: string;
+};
+interface AiStreamSession extends AsyncIterable<AiStreamChunk> {
+    /** 中止本次流式请求（幂等）；done 会以已累积的部分结果结算 */
+    cancel(): void;
+    /** 流式完成后结算：始终 resolve（含错误/取消，text/usage 为已累积部分） */
+    done: Promise<AiChatResult>;
+}
+interface AiClientConfig {
+    readonly provider: string;
+    readonly baseURL: string;
+    readonly model: string;
+}
+interface AiClientOptions {
+    /** 注册表 id（listAiProviders/getAiProvider 可查）；未注册抛错 */
+    provider: string;
+    apiKey: string;
+    /** 覆盖 provider 默认基址（自定义网关/代理） */
+    baseURL?: string;
+    /** 缺省取 provider.models[0].id */
+    model?: string;
+    /** 每次请求产出审计记录（回调形式） */
+    onAudit?: (entry: AiAuditEntry) => void;
+    /** 传 auditor 实例则每次请求自动 log */
+    auditor?: AiAuditor;
+    /** mock fetch 注入（AI SDK 同款）——单测与文档站离线 demo 用 */
+    fetch?: typeof fetch;
+}
+interface AiClient {
+    chat(req: AiChatRequest): Promise<AiChatResult>;
+    stream(req: AiChatRequest): AiStreamSession;
+    readonly config: AiClientConfig;
+}
+/** icen:ai-done 的 detail（spec §5；绑定层 bindComposer 的驱动事件） */
+interface AiDoneEventDetail {
+    status: 'ok' | 'error' | 'cancelled';
+    provider: string;
+    model: string;
+    stream: boolean;
+    usage?: AiUsage;
+    cost?: number;
+    error?: string;
+    durationMs: number;
+    ttftMs?: number;
+}
+declare function createAiClient(options: AiClientOptions): AiClient;
+
+export { type AiAuditEntry, type AiAuditTotals, type AiAuditor, type AiAuditorOptions, type AiChatMessage, type AiChatRequest, type AiChatResult, type AiChatRole, type AiClient, type AiClientConfig, type AiClientOptions, type AiDoneEventDetail, type AiPricing, type AiProviderDef, AiProviderError, type AiProviderModel, type AiStreamChunk, type AiStreamSession, createAiAuditor, createAiClient, estimateCost, getAiProvider, listAiProviders, registerAiProvider };