@yh-ui/ai-sdk 0.1.21

package/dist/future.d.ts

@@ -0,0 +1,519 @@
+/**
+ * YH-UI AI SDK - 前瞻性功能模块
+ *
+ * 面向 AI 发展未来的能力集成：
+ * - Agent 编排框架 (Plan-Execute, ReAct)
+ * - 多模态支持 (视觉/语音/视频理解)
+ * - RAG 检索增强生成
+ * - 思维链 CoT 推理
+ * - 智能上下文压缩
+ * - 成本控制
+ * - 可观测性
+ * - AI 安全护栏
+ */
+export interface AgentStep {
+    id: string;
+    type: 'thought' | 'action' | 'observation' | 'result';
+    content: string;
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    toolOutput?: unknown;
+    timestamp: Date;
+}
+export interface AgentConfig {
+    /** Agent 类型 */
+    type: 'react' | 'plan-execute' | 'chat';
+    /** 最大迭代次数 */
+    maxIterations?: number;
+    /** 最大工具调用次数 */
+    maxToolCalls?: number;
+    /** 是否返回推理过程 */
+    returnReasoning?: boolean;
+    /** 工具列表 */
+    tools?: AgentTool[];
+    /** 停止条件 */
+    stopConditions?: StopCondition[];
+    /** 错误处理 */
+    onError?: (error: Error, step: AgentStep) => void | Promise<void>;
+}
+export interface AgentTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export interface StopCondition {
+    type: 'max_iterations' | 'max_tool_calls' | 'contains' | 'custom';
+    value?: string | number | ((output: string) => boolean);
+}
+export interface AgentResult {
+    output: string;
+    reasoning?: AgentStep[];
+    toolCalls: number;
+    finished: boolean;
+    error?: Error;
+}
+export interface MultiModalContent {
+    type: 'text' | 'image' | 'audio' | 'video' | 'image_url';
+    text?: string;
+    url?: string;
+    base64?: string;
+    mimeType?: string;
+}
+export interface MultiModalMessage {
+    role: 'user' | 'assistant';
+    content: MultiModalContent[];
+}
+export interface VisionAnalysisOptions {
+    /** 图像描述 */
+    detail?: 'low' | 'high' | 'auto';
+    /** 额外提示 */
+    prompt?: string;
+}
+export interface DocumentChunk {
+    id: string;
+    content: string;
+    embedding?: number[];
+    metadata: Record<string, unknown>;
+    score?: number;
+}
+export interface RAGConfig {
+    /** 知识库 ID */
+    knowledgeBaseId?: string;
+    /** 检索文档数量 */
+    topK?: number;
+    /** 相似度阈值 */
+    similarityThreshold?: number;
+    /** 是否包含源信息 */
+    includeSources?: boolean;
+    /** 检索策略 */
+    strategy?: 'similarity' | 'mmr' | 'hybrid';
+}
+export interface RAGResult {
+    answer: string;
+    sources: Array<{
+        content: string;
+        metadata: Record<string, unknown>;
+        score: number;
+    }>;
+    contextUsed: string;
+}
+export interface ReasoningStep {
+    id: string;
+    content: string;
+    type: 'analysis' | 'reflection' | 'conclusion' | 'action';
+    children?: ReasoningStep[];
+}
+export interface CoTConfig {
+    /** 推理模式 */
+    mode: 'standard' | 'chain' | 'tree' | 'tabular';
+    /** 最大深度 */
+    maxDepth?: number;
+    /** 是否显示置信度 */
+    showConfidence?: boolean;
+}
+export interface CompressionConfig {
+    /** 压缩策略 */
+    strategy: 'summary' | 'extract' | 'prune';
+    /** 目标 token 数 */
+    targetTokens?: number;
+    /** 保留关键信息 */
+    preserveKeyInfo?: string[];
+}
+export interface CompressionResult {
+    compressedContent: string;
+    originalTokens: number;
+    compressedTokens: number;
+    compressionRatio: number;
+    extractedKeyInfo?: string[];
+}
+export interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+    cached?: number;
+}
+export interface CostConfig {
+    /** 每月预算 (美元) */
+    monthlyBudget?: number;
+    /** 单次请求最大 token */
+    maxTokensPerRequest?: number;
+    /** 警告阈值 */
+    warningThreshold?: number;
+}
+export interface CostTracking {
+    totalCost: number;
+    dailyCost: Record<string, number>;
+    usage: TokenUsage;
+    budget: CostConfig;
+    remaining: number;
+}
+export interface TraceEvent {
+    id: string;
+    type: 'request' | 'response' | 'tool_call' | 'tool_result' | 'error' | 'custom';
+    timestamp: Date;
+    data: Record<string, unknown>;
+    duration?: number;
+    parentId?: string;
+}
+export interface TraceSpan {
+    id: string;
+    name: string;
+    startTime: Date;
+    endTime?: Date;
+    events: TraceEvent[];
+    attributes: Record<string, unknown>;
+    children: TraceSpan[];
+}
+export interface SafetyRule {
+    id: string;
+    name: string;
+    type: 'content_filter' | 'input_validation' | 'output_filter' | 'tool_permission';
+    pattern?: string | RegExp;
+    customCheck?: (content: string) => boolean | Promise<boolean>;
+    action: 'block' | 'warn' | 'replace';
+    replacement?: string;
+}
+export interface SafetyResult {
+    passed: boolean;
+    violations: Array<{
+        rule: SafetyRule;
+        content: string;
+        action: 'blocked' | 'warned' | 'replaced';
+        replacedContent?: string;
+    }>;
+}
+export interface SchemaDefinition {
+    type: 'object' | 'array' | 'union';
+    properties?: Record<string, SchemaProperty>;
+    required?: string[];
+    description?: string;
+}
+export interface SchemaProperty {
+    type: string;
+    description?: string;
+    enum?: string[];
+    items?: SchemaProperty;
+    properties?: Record<string, SchemaProperty>;
+}
+/**
+ * ReAct Agent - 推理 + 行动
+ *
+ * @example
+ * ```ts
+ * const { run, steps, isRunning } = useReActAgent({
+ *   tools: [searchTool, calculatorTool],
+ *   maxIterations: 10,
+ *   returnReasoning: true
+ * })
+ *
+ * const result = await run('北京的人口是多少？用中文回答')
+ * ```
+ */
+export declare function useReActAgent(config: AgentConfig): {
+    steps: import("vue").Ref<{
+        id: string;
+        type: "thought" | "action" | "observation" | "result";
+        content: string;
+        toolName?: string | undefined;
+        toolInput?: Record<string, unknown> | undefined;
+        toolOutput?: unknown;
+        timestamp: Date;
+    }[], AgentStep[] | {
+        id: string;
+        type: "thought" | "action" | "observation" | "result";
+        content: string;
+        toolName?: string | undefined;
+        toolInput?: Record<string, unknown> | undefined;
+        toolOutput?: unknown;
+        timestamp: Date;
+    }[]>;
+    isRunning: import("vue").Ref<boolean, boolean>;
+    currentOutput: import("vue").Ref<string, string>;
+    toolCallCount: import("vue").Ref<number, number>;
+    run: (input: string, executeFn: (prompt: string) => Promise<string>) => Promise<AgentResult>;
+};
+/**
+ * Plan-Execute Agent - 计划 + 执行
+ *
+ * @example
+ * ```ts
+ * const agent = createPlanExecuteAgent({
+ *   tools: [searchTool, calculatorTool]
+ * })
+ *
+ * const result = await agent.execute('帮我查北京人口，然后计算增长')
+ * ```
+ */
+export declare function createPlanExecuteAgent(config: {
+    tools?: AgentTool[];
+    maxSteps?: number;
+}): {
+    plans: import("vue").Ref<{
+        id: string;
+        description: string;
+        status: "pending" | "completed" | "failed";
+    }[], {
+        id: string;
+        description: string;
+        status: "pending" | "completed" | "failed";
+    }[] | {
+        id: string;
+        description: string;
+        status: "pending" | "completed" | "failed";
+    }[]>;
+    currentPlan: import("vue").Ref<string | null, string | null>;
+    results: import("vue").Ref<Record<string, unknown>, Record<string, unknown>>;
+    execute: (task: string, llm: (prompt: string) => Promise<string>) => Promise<{
+        result: string;
+        plan: {
+            id: string;
+            description: string;
+            status: "pending" | "completed" | "failed";
+        }[];
+        results: Record<string, unknown>;
+    }>;
+};
+/**
+ * 创建多模态消息
+ */
+export declare function createMultiModalMessage(role: 'user' | 'assistant', contents: MultiModalContent[]): MultiModalMessage;
+/**
+ * 从文件创建图像内容
+ */
+export declare function createImageContent(source: 'url' | 'base64', value: string, mimeType?: string): MultiModalContent;
+/**
+ * 图像 URL 内容
+ */
+export declare function createImageUrlContent(url: string, detail?: 'low' | 'high' | 'auto'): MultiModalContent;
+/**
+ * 音频内容
+ */
+export declare function createAudioContent(base64: string, mimeType?: string): MultiModalContent;
+/**
+ * 视频内容
+ */
+export declare function createVideoContent(base64: string, mimeType?: string): MultiModalContent;
+/**
+ * 创建 RAG 系统
+ *
+ * @example
+ * ```ts
+ * const rag = createRAGSystem({
+ *   knowledgeBaseId: 'my-kb',
+ *   topK: 5,
+ *   similarityThreshold: 0.7
+ * })
+ *
+ * const result = await rag.query('什么是 TypeScript？')
+ * ```
+ */
+export declare function createRAGSystem(config: RAGConfig): {
+    addDocuments: (documents: Array<{
+        content: string;
+        metadata?: Record<string, unknown>;
+    }>) => Promise<DocumentChunk[]>;
+    retrieve: (query: string, k?: number) => Promise<DocumentChunk[]>;
+    query: (question: string, llm: (prompt: string) => Promise<string>) => Promise<RAGResult>;
+    clear: () => void;
+    config: {
+        topK: number;
+        similarityThreshold: number;
+        strategy: "similarity" | "mmr" | "hybrid";
+    };
+};
+/**
+ * 创建思维链推理器
+ *
+ * @example
+ * ```ts
+ * const cot = createChainOfThought({
+ *   mode: 'chain',
+ *   showConfidence: true
+ * })
+ *
+ * const result = await cot.think('分析这个问题的解决步骤')
+ * ```
+ */
+export declare function createChainOfThought(config?: CoTConfig): {
+    think: (problem: string, llm: (prompt: string) => Promise<string>) => Promise<{
+        result: string;
+        reasoning: ReasoningStep[];
+    }>;
+    addStep: (step: Omit<ReasoningStep, "id">) => void;
+    clear: () => void;
+    reasoningSteps: import("vue").Ref<{
+        id: string;
+        content: string;
+        type: "analysis" | "reflection" | "conclusion" | "action";
+        children?: /*elided*/ any[] | undefined;
+    }[], ReasoningStep[] | {
+        id: string;
+        content: string;
+        type: "analysis" | "reflection" | "conclusion" | "action";
+        children?: /*elided*/ any[] | undefined;
+    }[]>;
+    config: {
+        mode: "standard" | "chain" | "tree" | "tabular";
+        maxDepth: number;
+        showConfidence: boolean;
+    };
+};
+/**
+ * 创建上下文压缩器
+ *
+ * @example
+ * ```ts
+ * const compressor = createContextCompressor({
+ *   strategy: 'summary',
+ *   targetTokens: 2000
+ * })
+ *
+ * const result = await compressor.compress(messages)
+ * ```
+ */
+export declare function createContextCompressor(config: CompressionConfig): {
+    compress: (content: string | Array<{
+        role: string;
+        content: string;
+    }>, llm?: (prompt: string) => Promise<string>) => Promise<CompressionResult>;
+    estimateTokens: (text: string) => number;
+    config: {
+        strategy: "summary" | "extract" | "prune";
+        targetTokens: number;
+        preserveKeyInfo: string[];
+    };
+};
+/**
+ * 创建成本追踪器
+ *
+ * @example
+ * ```ts
+ * const costTracker = createCostTracker({
+ *   monthlyBudget: 100,
+ *   warningThreshold: 0.8
+ * })
+ *
+ * costTracker.track({ prompt: 1000, completion: 500 })
+ * console.log(costTracker.getStatus())
+ * ```
+ */
+export declare function createCostTracker(config?: CostConfig): {
+    track: (usage: TokenUsage, _model?: string) => void;
+    calculateCost: (usage: TokenUsage, model: string) => number;
+    getStatus: () => CostTracking;
+    isOverBudget: () => boolean;
+    shouldWarn: () => boolean;
+    checkRequestLimit: (tokens: number) => {
+        allowed: boolean;
+        reason?: string;
+    };
+    reset: () => void;
+    pricing: Record<string, {
+        prompt: number;
+        completion: number;
+    }>;
+    config: {
+        monthlyBudget: number;
+        maxTokensPerRequest: number;
+        warningThreshold: number;
+    };
+};
+/**
+ * 创建追踪器
+ *
+ * @example
+ * ```ts
+ * const tracer = createTracer()
+ *
+ * const span = tracer.startSpan('chat')
+ * // ... do something
+ * tracer.endSpan(span)
+ *
+ * const events = tracer.getEvents()
+ * ```
+ */
+export declare function createTracer(): {
+    startSpan: (name: string, attributes?: Record<string, unknown>) => string;
+    endSpan: (id: string, attributes?: Record<string, unknown>) => void;
+    addEvent: (event: Omit<TraceEvent, "id" | "timestamp">) => void;
+    recordRequest: (config: Record<string, unknown>, spanId?: string) => void;
+    recordResponse: (response: unknown, duration?: number, spanId?: string) => void;
+    recordError: (error: Error, context?: Record<string, unknown>, spanId?: string) => void;
+    getEvents: () => {
+        id: string;
+        type: "request" | "response" | "tool_call" | "tool_result" | "error" | "custom";
+        timestamp: Date;
+        data: Record<string, unknown>;
+        duration?: number | undefined;
+        parentId?: string | undefined;
+    }[];
+    getSpans: () => {
+        id: string;
+        name: string;
+        startTime: Date;
+        endTime?: Date | undefined;
+        events: {
+            id: string;
+            type: "request" | "response" | "tool_call" | "tool_result" | "error" | "custom";
+            timestamp: Date;
+            data: Record<string, unknown>;
+            duration?: number | undefined;
+            parentId?: string | undefined;
+        }[];
+        attributes: Record<string, unknown>;
+        children: /*elided*/ any[];
+    }[];
+    clear: () => void;
+    exportJSON: () => string;
+};
+/**
+ * 创建安全过滤器
+ *
+ * @example
+ * ```ts
+ * const safety = createSafetyFilter({
+ *   rules: [
+ *     { id: '1', name: '敏感词', type: 'content_filter', pattern: '暴力|赌博', action: 'block' }
+ *   ]
+ * })
+ *
+ * const result = await safety.check('这是一条正常消息')
+ * ```
+ */
+export declare function createSafetyFilter(config: {
+    rules: SafetyRule[];
+}): {
+    check: (content: string) => Promise<SafetyResult>;
+    addRule: (rule: SafetyRule) => void;
+    removeRule: (ruleId: string) => void;
+    createPresetRules: (type: "strict" | "moderate" | "lenient") => void;
+    rules: SafetyRule[];
+};
+/**
+ * 从 Zod schema 创建结构化输出
+ */
+export declare function fromZodSchema<_T>(schema: unknown): {
+    type: string;
+    schema: unknown;
+    toJSONSchema: () => unknown;
+};
+/**
+ * 创建 JSON Schema 定义
+ */
+export declare function createJSONSchema(definition: SchemaDefinition): SchemaDefinition;
+/**
+ * 常用 Schema 构建器
+ */
+export declare const schema: {
+    string: (description?: string) => SchemaProperty;
+    number: (description?: string) => SchemaProperty;
+    boolean: (description?: string) => SchemaProperty;
+    enum: <T extends string>(values: T[], description?: string) => SchemaProperty;
+    array: (items: SchemaProperty) => SchemaProperty;
+    object: (properties: Record<string, SchemaProperty>, required?: string[]) => SchemaDefinition;
+};
+/**
+ * 解析结构化输出
+ */
+export declare function parseStructuredOutput<T>(output: string, _schema: SchemaDefinition): T | null;