@cicctencent/agent-core 0.1.17 → 0.1.19

package/dist/esm/kb/in-memory-kb.js

@@ -0,0 +1,206 @@
+// ============================================================
+// InMemoryKnowledgeBase — 内存知识库实现（TF-IDF 关键词匹配）
+// ============================================================
+// ---- 文本分词 ----
+/**
+ * 将文本分词为小写词项数组
+ * 按非字母数字字符分割，过滤空串和过短词
+ */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9\u4e00-\u9fff]+/)
+        .filter(t => t.length > 0);
+}
+/** 计算词项频率（TF） */
+function computeTF(tokens) {
+    const tf = new Map();
+    for (const t of tokens) {
+        tf.set(t, (tf.get(t) || 0) + 1);
+    }
+    // 归一化：除以总词数
+    const total = tokens.length;
+    if (total > 0) {
+        for (const [k, v] of tf) {
+            tf.set(k, v / total);
+        }
+    }
+    return tf;
+}
+// ---- InMemoryKnowledgeBase ----
+/**
+ * 内存知识库实现
+ *
+ * 当注入 EmbeddingProvider 时使用语义向量检索（余弦相似度）；
+ * 未注入时回退到 TF-IDF 关键词匹配（余弦相似度）。
+ *
+ * 零外部依赖，适合开发/测试及小规模知识库场景。
+ */
+export class InMemoryKnowledgeBase {
+    /** 文档存储：docId -> StoredDoc */
+    docs = new Map();
+    /** 嵌入向量提供者（可选） */
+    embeddingProvider;
+    /** 全局文档频率：term -> 包含该词的文档数 */
+    df = new Map();
+    /** 总文档数（用于 IDF 计算） */
+    totalDocs = 0;
+    /** 缓存的 chunk TF-IDF 向量：chunkId -> TFIDFVector */
+    chunkVectors = new Map();
+    constructor(embeddingProvider) {
+        this.embeddingProvider = embeddingProvider;
+    }
+    async ingest(docId, chunks) {
+        if (!chunks.length)
+            return;
+        // 如果已有同 ID 文档，先移除
+        if (this.docs.has(docId)) {
+            await this.remove(docId);
+        }
+        // 生成嵌入向量（如果提供了 EmbeddingProvider）
+        if (this.embeddingProvider) {
+            const texts = chunks.map(c => c.content);
+            const embeddings = await this.embeddingProvider.embed(texts);
+            chunks = chunks.map((c, i) => ({ ...c, embedding: embeddings[i] }));
+        }
+        const now = new Date().toISOString();
+        const title = chunks[0]?.metadata?.title || docId;
+        const doc = {
+            meta: {
+                id: docId,
+                title,
+                chunkCount: chunks.length,
+                createdAt: now,
+                metadata: chunks[0]?.metadata,
+            },
+            chunks,
+        };
+        this.docs.set(docId, doc);
+        this.totalDocs++;
+        // 更新 DF（文档频率）
+        const docTerms = new Set();
+        for (const chunk of chunks) {
+            const tokens = tokenize(chunk.content);
+            for (const t of tokens)
+                docTerms.add(t);
+        }
+        for (const t of docTerms) {
+            this.df.set(t, (this.df.get(t) || 0) + 1);
+        }
+        // 计算并缓存每个 chunk 的 TF-IDF 向量
+        for (const chunk of chunks) {
+            this.chunkVectors.set(chunk.id, this.computeTFIDF(chunk.content));
+        }
+    }
+    async search(query, topK = 5) {
+        if (this.docs.size === 0)
+            return [];
+        const results = [];
+        // 如果有 EmbeddingProvider，使用语义检索
+        if (this.embeddingProvider) {
+            const [queryEmbedding] = await this.embeddingProvider.embed([query]);
+            for (const doc of this.docs.values()) {
+                for (const chunk of doc.chunks) {
+                    if (!chunk.embedding)
+                        continue;
+                    const score = cosineSimilarity(queryEmbedding, chunk.embedding);
+                    results.push({ chunk, score });
+                }
+            }
+        }
+        else {
+            // 回退到 TF-IDF 关键词匹配
+            const queryVector = this.computeTFIDF(query);
+            for (const doc of this.docs.values()) {
+                for (const chunk of doc.chunks) {
+                    const chunkVector = this.chunkVectors.get(chunk.id);
+                    if (!chunkVector)
+                        continue;
+                    const score = cosineSimilaritySparse(queryVector, chunkVector);
+                    results.push({ chunk, score });
+                }
+            }
+        }
+        // 按得分降序排列，取 topK
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, topK);
+    }
+    async remove(docId) {
+        const doc = this.docs.get(docId);
+        if (!doc)
+            return;
+        // 移除 chunk 向量缓存
+        for (const chunk of doc.chunks) {
+            this.chunkVectors.delete(chunk.id);
+        }
+        // 更新 DF
+        const docTerms = new Set();
+        for (const chunk of doc.chunks) {
+            const tokens = tokenize(chunk.content);
+            for (const t of tokens)
+                docTerms.add(t);
+        }
+        for (const t of docTerms) {
+            const count = this.df.get(t);
+            if (count != null) {
+                if (count <= 1)
+                    this.df.delete(t);
+                else
+                    this.df.set(t, count - 1);
+            }
+        }
+        this.docs.delete(docId);
+        this.totalDocs--;
+    }
+    async list() {
+        return Array.from(this.docs.values()).map(d => d.meta);
+    }
+    // ---- TF-IDF 计算 ----
+    /** 计算文本的 TF-IDF 稀疏向量 */
+    computeTFIDF(text) {
+        const tokens = tokenize(text);
+        const tf = computeTF(tokens);
+        const vector = new Map();
+        for (const [term, tfVal] of tf) {
+            const dfVal = this.df.get(term) || 0;
+            // IDF = log((1 + N) / (1 + DF)) + 1  （平滑处理）
+            const idf = Math.log((1 + this.totalDocs) / (1 + dfVal)) + 1;
+            vector.set(term, tfVal * idf);
+        }
+        return vector;
+    }
+}
+// ---- 向量相似度计算 ----
+/** 计算两个稠密向量的余弦相似度 */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/** 计算两个稀疏向量（Map）的余弦相似度 */
+function cosineSimilaritySparse(a, b) {
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (const [k, v] of a) {
+        magA += v * v;
+        const bv = b.get(k);
+        if (bv != null)
+            dot += v * bv;
+    }
+    for (const [, v] of b) {
+        magB += v * v;
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}
+//# sourceMappingURL=in-memory-kb.js.map

package/dist/esm/kb/in-memory-kb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-kb.js","sourceRoot":"","sources":["../../../src/kb/in-memory-kb.ts"],"names":[],"mappings":"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"}

package/dist/esm/kb/rag-middleware.d.ts

@@ -0,0 +1,31 @@
+import type { Middleware } from '../middleware/types.js';
+import type { KnowledgeBase } from './types.js';
+/** RAG 中间件配置 */
+export interface RAGMiddlewareOptions {
+    /** 检索结果数量（默认 3） */
+    topK?: number;
+    /** 注入的上下文笔记标题（默认 "Retrieved Knowledge"） */
+    noteTitle?: string;
+    /** 每个分块最大字符数（默认 500，超出截断） */
+    maxChunkLength?: number;
+    /** 最低相似度阈值（低于此值的结果不注入，默认 0.01） */
+    minScore?: number;
+    /** 是否仅在首轮迭代注入（默认 false，每轮都检索） */
+    firstIterationOnly?: boolean;
+    /** 日志输出函数 */
+    logger?: (msg: string) => void;
+}
+/**
+ * 创建 RAG（检索增强生成）中间件
+ *
+ * 在每轮迭代开始前：
+ * 1. 提取用户最新消息文本
+ * 2. 检索知识库中相关分块
+ * 3. 将检索结果格式化为系统级上下文笔记，注入到消息列表末尾
+ *
+ * @param kb      知识库实例
+ * @param options 配置选项
+ * @returns Middleware 实例
+ */
+export declare function createRAGMiddleware(kb: KnowledgeBase, options?: RAGMiddlewareOptions): Middleware;
+//# sourceMappingURL=rag-middleware.d.ts.map

package/dist/esm/kb/rag-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-middleware.d.ts","sourceRoot":"","sources":["../../../src/kb/rag-middleware.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,wBAAwB,CAAC;AAG5E,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AAI9D,gBAAgB;AAChB,MAAM,WAAW,oBAAoB;IACnC,mBAAmB;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa;IACb,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,aAAa,EACjB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,UAAU,CAkFZ"}

package/dist/esm/kb/rag-middleware.js

@@ -0,0 +1,91 @@
+// ============================================================
+// RAGMiddleware — 检索增强生成中间件
+// ============================================================
+import { extractTextFromContent } from "../types.js";
+// ---- createRAGMiddleware ----
+/**
+ * 创建 RAG（检索增强生成）中间件
+ *
+ * 在每轮迭代开始前：
+ * 1. 提取用户最新消息文本
+ * 2. 检索知识库中相关分块
+ * 3. 将检索结果格式化为系统级上下文笔记，注入到消息列表末尾
+ *
+ * @param kb      知识库实例
+ * @param options 配置选项
+ * @returns Middleware 实例
+ */
+export function createRAGMiddleware(kb, options) {
+    const topK = options?.topK ?? 3;
+    const noteTitle = options?.noteTitle ?? 'Retrieved Knowledge';
+    const maxChunkLength = options?.maxChunkLength ?? 500;
+    const minScore = options?.minScore ?? 0.01;
+    const firstIterationOnly = options?.firstIterationOnly ?? false;
+    const logger = options?.logger ?? (() => { });
+    /** 已注入过的会话集合（用于 firstIterationOnly 模式） */
+    const injectedSessions = new Set();
+    /** 格式化检索结果为上下文笔记 */
+    function formatContextNote(results) {
+        const lines = [`--- ${noteTitle} ---`];
+        for (let i = 0; i < results.length; i++) {
+            const { chunk, score } = results[i];
+            let content = chunk.content;
+            if (content.length > maxChunkLength) {
+                content = content.slice(0, maxChunkLength) + '...';
+            }
+            const source = chunk.metadata?.title
+                ? `[${chunk.metadata.title}]`
+                : `[doc: ${chunk.docId}]`;
+            lines.push(`[${i + 1}] ${source} (score: ${score.toFixed(3)})`);
+            lines.push(content);
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /** 从消息列表中提取最新的用户消息文本 */
+    function getLatestUserMessage(messages) {
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const msg = messages[i];
+            if (msg.role === 'user') {
+                return extractTextFromContent(msg.content);
+            }
+        }
+        return '';
+    }
+    return {
+        name: 'rag',
+        async before(ctx) {
+            // firstIterationOnly 模式：仅首轮注入
+            if (firstIterationOnly && injectedSessions.has(ctx.sessionId)) {
+                return;
+            }
+            // 提取最新用户消息
+            const query = getLatestUserMessage(ctx.messages);
+            if (!query.trim())
+                return;
+            try {
+                const results = await kb.search(query, topK);
+                // 过滤低分结果
+                const filtered = results.filter(r => r.score >= minScore);
+                if (filtered.length === 0)
+                    return;
+                // 格式化上下文笔记
+                const note = formatContextNote(filtered);
+                // 注入系统级上下文消息
+                const contextMessage = {
+                    role: 'system',
+                    content: note,
+                };
+                // ctx.messages 是 ReadonlyArray，但底层是可变数组
+                // 与引擎内部注入消息的模式一致（如 progress nudge、iteration guard 等）
+                ctx.messages.push(contextMessage);
+                injectedSessions.add(ctx.sessionId);
+                logger(`[RAG] Injected ${filtered.length} chunks for session ${ctx.sessionId} (iter ${ctx.iteration})`);
+            }
+            catch (e) {
+                logger(`[RAG] Search failed: ${e?.message || e}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=rag-middleware.js.map

package/dist/esm/kb/rag-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-middleware.js","sourceRoot":"","sources":["../../../src/kb/rag-middleware.ts"],"names":[],"mappings":"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"}

package/dist/esm/kb/types.d.ts

@@ -0,0 +1,80 @@
+/** 文本分块（知识库最小检索单元） */
+export interface TextChunk {
+    /** 分块唯一 ID */
+    id: string;
+    /** 所属文档 ID */
+    docId: string;
+    /** 分块文本内容 */
+    content: string;
+    /** 预计算的嵌入向量（可选，由 EmbeddingProvider 生成） */
+    embedding?: number[];
+    /** 附加元数据（如页码、标题、来源等） */
+    metadata?: Record<string, unknown>;
+}
+/** 知识库检索结果 */
+export interface SearchResult {
+    /** 匹配到的文本分块 */
+    chunk: TextChunk;
+    /** 相似度得分（0~1，越高越相关） */
+    score: number;
+}
+/** 文档元数据 */
+export interface DocMeta {
+    /** 文档 ID */
+    id: string;
+    /** 文档标题 */
+    title: string;
+    /** 分块数量 */
+    chunkCount: number;
+    /** 创建时间（ISO 8601） */
+    createdAt: string;
+    /** 附加元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 嵌入向量提供者接口
+ *
+ * 将文本转换为高维向量，用于语义检索。
+ * Core 仅定义接口，具体实现由上层注入（如调用 OpenAI Embeddings API）。
+ */
+export interface EmbeddingProvider {
+    /**
+     * 批量生成文本的嵌入向量
+     * @param texts 文本数组
+     * @returns 嵌入向量数组（与输入一一对应）
+     */
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * 知识库接口
+ *
+ * 提供文档摄入、语义/关键词检索、文档管理和列表功能。
+ * Core 定义接口，具体实现可以是内存型（InMemoryKnowledgeBase）
+ * 或外部向量数据库（由上层注入）。
+ */
+export interface KnowledgeBase {
+    /**
+     * 摄入文档分块
+     * @param docId  文档 ID
+     * @param chunks 文本分块数组
+     */
+    ingest(docId: string, chunks: TextChunk[]): Promise<void>;
+    /**
+     * 检索与查询最相关的分块
+     * @param query 查询文本
+     * @param topK  返回结果数量（默认 5）
+     * @returns 按相关度降序排列的检索结果
+     */
+    search(query: string, topK?: number): Promise<SearchResult[]>;
+    /**
+     * 删除指定文档及其所有分块
+     * @param docId 文档 ID
+     */
+    remove(docId: string): Promise<void>;
+    /**
+     * 列出知识库中的所有文档元数据
+     * @returns 文档元数据数组
+     */
+    list(): Promise<DocMeta[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/kb/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/kb/types.ts"],"names":[],"mappings":"AAMA,sBAAsB;AACtB,MAAM,WAAW,SAAS;IACxB,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAID,cAAc;AACd,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAID,YAAY;AACZ,MAAM,WAAW,OAAO;IACtB,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAID;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;CAC7C;AAID;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE9D;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAC5B"}

package/dist/esm/kb/types.js

@@ -0,0 +1,5 @@
+// ============================================================
+// KnowledgeBase — 知识库类型定义
+// ============================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/kb/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/kb/types.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,0BAA0B;AAC1B,+DAA+D"}

package/dist/esm/llm/anthropic-provider.d.ts

@@ -20,6 +20,13 @@ export declare class AnthropicProvider implements LLMProvider {
      * - assistant 的 tool_calls 转换为 tool_use 块
      */
     private convertMessages;
+    /**
+     * 将 ContentPart[] 转换为 Anthropic content blocks
+     * - TextPart → {type: 'text', text}
+     * - ImagePart → {type: 'image', source: {type: 'base64'|'url', ...}}
+     * - FilePart → {type: 'text', text: '[file]\n${content}'}
+     */
+    private convertContentPartsForAnthropic;
     private convertTools;
     private buildRequestBody;
     private parseResponse;

package/dist/esm/llm/anthropic-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic-provider.d.ts","sourceRoot":"","sources":["../../../src/llm/anthropic-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA+C3G,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,MAAM,CAAkE;gBAEpE,MAAM,EAAE,WAAW;IAY/B,QAAQ,IAAI,SAAS;IAUf,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAexB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAa9C,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC;IAkIhE,WAAW;IACX,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAMjD;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAiEvB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,aAAa;YAwCP,SAAS;CA2BxB"}
+{"version":3,"file":"anthropic-provider.d.ts","sourceRoot":"","sources":["../../../src/llm/anthropic-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgD3G,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,MAAM,CAAkE;gBAEpE,MAAM,EAAE,WAAW;IAY/B,QAAQ,IAAI,SAAS;IAUf,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAexB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAa9C,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC;IAkIhE,WAAW;IACX,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAMjD;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA0EvB;;;;;OAKG;IACH,OAAO,CAAC,+BAA+B;IA2CvC,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,gBAAgB;IAqCxB,OAAO,CAAC,aAAa;YAwCP,SAAS;CA2BxB"}

package/dist/esm/llm/anthropic-provider.js

@@ -204,17 +204,27 @@ export class AnthropicProvider {
         for (const msg of messages) {
             switch (msg.role) {
                 case 'system':
-                    system = (system ? system + '\n\n' : '') + (msg.content || '');
+                    system = (system ? system + '\n\n' : '') + (typeof msg.content === 'string' ? msg.content : '');
                     break;
-                case 'user':
-                    result.push({ role: 'user', content: msg.content || '' });
+                case 'user': {
+                    // 多模态内容：ContentPart[] → Anthropic content blocks
+                    if (Array.isArray(msg.content)) {
+                        const blocks = this.convertContentPartsForAnthropic(msg.content);
+                        result.push({ role: 'user', content: blocks });
+                    }
+                    else {
+                        result.push({ role: 'user', content: msg.content || '' });
+                    }
                     break;
+                }
                 case 'assistant': {
                     if (msg.tool_calls?.length) {
                         // assistant 带 tool_calls → text + tool_use blocks
                         const blocks = [];
                         if (msg.content) {
-                            blocks.push({ type: 'text', text: msg.content });
+                            const textContent = typeof msg.content === 'string' ? msg.content : msg.content.map(p => p.type === 'text' ? p.text : '').join('');
+                            if (textContent)
+                                blocks.push({ type: 'text', text: textContent });
                         }
                         for (const tc of msg.tool_calls) {
                             let input;
@@ -236,7 +246,8 @@ export class AnthropicProvider {
                         result.push({ role: 'assistant', content: blocks });
                     }
                     else {
-                        result.push({ role: 'assistant', content: msg.content || '' });
+                        const textContent = typeof msg.content === 'string' ? msg.content : (msg.content || []).map(p => p.type === 'text' ? p.text : '').join('');
+                        result.push({ role: 'assistant', content: textContent || '' });
                     }
                     break;
                 }
@@ -247,7 +258,7 @@ export class AnthropicProvider {
                         content: [{
                                 type: 'tool_result',
                                 tool_use_id: msg.tool_call_id,
-                                content: msg.content || '',
+                                content: typeof msg.content === 'string' ? msg.content : '',
                             }],
                     });
                     break;
@@ -256,6 +267,55 @@ export class AnthropicProvider {
         }
         return { system, messages: result };
     }
+    /**
+     * 将 ContentPart[] 转换为 Anthropic content blocks
+     * - TextPart → {type: 'text', text}
+     * - ImagePart → {type: 'image', source: {type: 'base64'|'url', ...}}
+     * - FilePart → {type: 'text', text: '[file]\n${content}'}
+     */
+    convertContentPartsForAnthropic(parts) {
+        const blocks = [];
+        for (const part of parts) {
+            switch (part.type) {
+                case 'text':
+                    blocks.push({ type: 'text', text: part.text });
+                    break;
+                case 'image': {
+                    const source = part.source;
+                    // base64 data URI → Anthropic base64 source
+                    const dataUriMatch = source.match(/^data:(image\/[a-zA-Z+]+);base64,(.+)$/);
+                    if (dataUriMatch) {
+                        blocks.push({
+                            type: 'image',
+                            source: {
+                                type: 'base64',
+                                media_type: dataUriMatch[1],
+                                data: dataUriMatch[2],
+                            },
+                        });
+                    }
+                    else {
+                        // URL → Anthropic url source
+                        blocks.push({
+                            type: 'image',
+                            source: {
+                                type: 'url',
+                                url: source,
+                            },
+                        });
+                    }
+                    break;
+                }
+                case 'file':
+                    blocks.push({
+                        type: 'text',
+                        text: `[File: ${part.filename}]\n\n${part.content}`,
+                    });
+                    break;
+            }
+        }
+        return blocks;
+    }
     convertTools(params) {
         if (!params.tools?.length)
             return undefined;
@@ -278,10 +338,25 @@ export class AnthropicProvider {
             messages,
             temperature: params.temperature ?? this.config.temperature,
         };
-        if (system)
-            body.system = system;
-        if (tools?.length)
+        // Prompt 缓存：对 system prompt 和 tools 插入 cache_control 断点
+        // Anthropic 会缓存这些稳定内容，减少重复 API 调用成本
+        const enableCache = this.config.extra?.enableCache !== false; // 默认启用
+        if (system) {
+            if (enableCache) {
+                // system 使用 content block 格式以支持 cache_control
+                body.system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
+            }
+            else {
+                body.system = system;
+            }
+        }
+        if (tools?.length) {
+            if (enableCache) {
+                // 在最后一个 tool 上添加 cache_control 断点
+                tools[tools.length - 1] = { ...tools[tools.length - 1], cache_control: { type: 'ephemeral' } };
+            }
             body.tools = tools;
+        }
         return body;
     }
     parseResponse(data) {