@cicctencent/agent-core 0.1.17 → 0.1.19

package/dist/cjs/skill/vector-index.js

@@ -0,0 +1,70 @@
+"use strict";
+// ============================================================
+// VectorIndex — 向量索引接口与内存实现
+// 纯 JS 余弦相似度，零外部依赖
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryVectorIndex = void 0;
+/**
+ * InMemoryVectorIndex — 内存向量索引
+ * 纯 JS 余弦相似度实现，零外部依赖
+ */
+class InMemoryVectorIndex {
+    items = new Map();
+    /** 预计算的向量范数缓存 */
+    norms = new Map();
+    build(items) {
+        this.items.clear();
+        this.norms.clear();
+        for (const item of items) {
+            this.items.set(item.id, item);
+            this.norms.set(item.id, this.computeNorm(item.vector));
+        }
+    }
+    async search(query, k) {
+        if (this.items.size === 0 || k <= 0)
+            return [];
+        const queryNorm = this.computeNorm(query);
+        if (queryNorm === 0)
+            return [];
+        const results = [];
+        for (const [id, item] of this.items) {
+            const itemNorm = this.norms.get(id) ?? this.computeNorm(item.vector);
+            if (itemNorm === 0)
+                continue;
+            const score = this.dotProduct(query, item.vector) / (queryNorm * itemNorm);
+            results.push({ id, score, metadata: item.metadata });
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, k);
+    }
+    add(item) {
+        this.items.set(item.id, item);
+        this.norms.set(item.id, this.computeNorm(item.vector));
+    }
+    remove(id) {
+        this.items.delete(id);
+        this.norms.delete(id);
+    }
+    size() {
+        return this.items.size;
+    }
+    // ---- 内部方法 ----
+    dotProduct(a, b) {
+        let sum = 0;
+        const len = Math.min(a.length, b.length);
+        for (let i = 0; i < len; i++) {
+            sum += a[i] * b[i];
+        }
+        return sum;
+    }
+    computeNorm(vec) {
+        let sum = 0;
+        for (let i = 0; i < vec.length; i++) {
+            sum += vec[i] * vec[i];
+        }
+        return Math.sqrt(sum);
+    }
+}
+exports.InMemoryVectorIndex = InMemoryVectorIndex;
+//# sourceMappingURL=vector-index.js.map

package/dist/cjs/skill/vector-index.js.map

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

package/dist/cjs/store/history-persistence.d.ts

@@ -0,0 +1,36 @@
+import type { Message } from '../types.js';
+import type { HistoryPersistence } from '../agent/types.js';
+export interface JsonlHistoryPersistenceOptions {
+    /** 存储目录（相对于 data 目录），默认 'history' */
+    dir?: string;
+    /** 使用项目级目录（{cwd}/data）而非全局目录（~/.agent/data） */
+    projectLocal?: boolean;
+    /** 直接使用绝对路径（忽略 projectLocal 和 dir） */
+    absoluteDir?: string;
+}
+/**
+ * Append-only JSONL 会话历史持久化
+ *
+ * 文件路径：{dataDir}/{dir}/{sessionId}.jsonl
+ *
+ * 特点：
+ * - Append-only：只追加不修改，保证审计完整性
+ * - JSONL 格式：每行一条 JSON，人类可读，可用 jq/grep 查询
+ * - 异步写入：不阻塞 Agent Loop
+ * - 容错：损坏行跳过，不中断加载
+ */
+export declare class JsonlHistoryPersistence implements HistoryPersistence {
+    private dir;
+    private projectLocal;
+    private absoluteDir?;
+    constructor(options?: JsonlHistoryPersistenceOptions);
+    /** 获取会话历史文件路径 */
+    private getFilePath;
+    /** 确保目录存在 */
+    private ensureDir;
+    save(sessionId: string, message: Message): Promise<void>;
+    load(sessionId: string): Promise<Message[] | null>;
+    delete(sessionId: string): Promise<void>;
+    exists(sessionId: string): Promise<boolean>;
+}
+//# sourceMappingURL=history-persistence.d.ts.map

package/dist/cjs/store/history-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-persistence.d.ts","sourceRoot":"","sources":["../../../src/store/history-persistence.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG5D,MAAM,WAAW,8BAA8B;IAC7C,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,WAAW,CAAC,CAAS;gBAEjB,OAAO,GAAE,8BAAmC;IAMxD,iBAAiB;IACjB,OAAO,CAAC,WAAW;IASnB,aAAa;YACC,SAAS;IAOjB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IA+BlD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASxC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CASlD"}

package/dist/cjs/store/history-persistence.js

@@ -0,0 +1,142 @@
+"use strict";
+// ============================================================
+// JsonlHistoryPersistence — Append-only JSONL 会话历史持久化
+// ============================================================
+//
+// 每个 session 一个 .jsonl 文件，每行一条 Message JSON。
+// - save(): 追加一行（append-only，不覆盖已有内容）
+// - load(): 逐行读取重建 Message[]
+// - delete(): 删除文件
+//
+// 设计参考：Claude Code 的 append-only JSONL 转录
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonlHistoryPersistence = void 0;
+const fsp = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const data_dir_ts_1 = require("../utils/data-dir.js");
+/**
+ * Append-only JSONL 会话历史持久化
+ *
+ * 文件路径：{dataDir}/{dir}/{sessionId}.jsonl
+ *
+ * 特点：
+ * - Append-only：只追加不修改，保证审计完整性
+ * - JSONL 格式：每行一条 JSON，人类可读，可用 jq/grep 查询
+ * - 异步写入：不阻塞 Agent Loop
+ * - 容错：损坏行跳过，不中断加载
+ */
+class JsonlHistoryPersistence {
+    dir;
+    projectLocal;
+    absoluteDir;
+    constructor(options = {}) {
+        this.dir = options.dir || 'history';
+        this.projectLocal = options.projectLocal ?? false;
+        this.absoluteDir = options.absoluteDir;
+    }
+    /** 获取会话历史文件路径 */
+    getFilePath(sessionId) {
+        // 防止路径遍历：只允许字母数字和 -_
+        const safeId = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+        if (this.absoluteDir) {
+            return path.join(this.absoluteDir, `${safeId}.jsonl`);
+        }
+        return (0, data_dir_ts_1.getDataPath)(`${this.dir}/${safeId}.jsonl`);
+    }
+    /** 确保目录存在 */
+    async ensureDir() {
+        const dirPath = this.absoluteDir
+            ? this.absoluteDir
+            : path.dirname((0, data_dir_ts_1.getDataPath)(`${this.dir}/.placeholder`));
+        await fsp.mkdir(dirPath, { recursive: true });
+    }
+    async save(sessionId, message) {
+        await this.ensureDir();
+        const filePath = this.getFilePath(sessionId);
+        const line = JSON.stringify(message) + '\n';
+        await fsp.appendFile(filePath, line, 'utf-8');
+    }
+    async load(sessionId) {
+        const filePath = this.getFilePath(sessionId);
+        try {
+            await fsp.access(filePath);
+        }
+        catch {
+            return null;
+        }
+        try {
+            const raw = await fsp.readFile(filePath, 'utf-8');
+            const lines = raw.split('\n').filter(line => line.trim());
+            const messages = [];
+            for (const line of lines) {
+                try {
+                    const msg = JSON.parse(line);
+                    messages.push(msg);
+                }
+                catch {
+                    // 跳过损坏行（如写入中断导致的不完整 JSON）
+                    console.warn(`[JsonlHistoryPersistence] Skipped malformed line in ${filePath}`);
+                }
+            }
+            return messages;
+        }
+        catch (e) {
+            console.error(`[JsonlHistoryPersistence] load error: ${filePath}`, e);
+            return null;
+        }
+    }
+    async delete(sessionId) {
+        const filePath = this.getFilePath(sessionId);
+        try {
+            await fsp.unlink(filePath);
+        }
+        catch {
+            // 文件不存在时静默忽略
+        }
+    }
+    async exists(sessionId) {
+        const filePath = this.getFilePath(sessionId);
+        try {
+            await fsp.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.JsonlHistoryPersistence = JsonlHistoryPersistence;
+//# sourceMappingURL=history-persistence.js.map

package/dist/cjs/store/history-persistence.js.map

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

package/dist/cjs/types.d.ts

@@ -1,3 +1,30 @@
+/** 文本内容部分 */
+export interface TextPart {
+    type: 'text';
+    text: string;
+}
+/** 图片内容部分 */
+export interface ImagePart {
+    type: 'image';
+    /** 图片来源：URL（http/https）或 base64 data URI（data:image/png;base64,...） */
+    source: string;
+    /** 图片 MIME 类型（如 image/png, image/jpeg），base64 时可从 data URI 推断 */
+    mimeType?: string;
+    /** 图片详情级别（OpenAI: low/high/auto），默认 auto */
+    detail?: 'low' | 'high' | 'auto';
+}
+/** 文件内容部分（PDF、文档等，由上层解析为文本后注入） */
+export interface FilePart {
+    type: 'file';
+    /** 文件名 */
+    filename: string;
+    /** 文件内容（文本形式，已由上层解析提取） */
+    content: string;
+    /** 文件 MIME 类型 */
+    mimeType?: string;
+}
+/** 多模态内容部分（discriminated union） */
+export type ContentPart = TextPart | ImagePart | FilePart;
 /** 消息角色 */
 export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 /** LLM 发起的工具调用 */
@@ -12,7 +39,8 @@ export interface ToolCall {
 /** LLM 消息 */
 export interface Message {
     role: MessageRole;
-    content: string | null;
+    /** 消息内容：纯文本字符串、多模态内容部分数组、或 null（无内容） */
+    content: string | ContentPart[] | null;
     /** assistant 消息中的工具调用请求 */
     tool_calls?: ToolCall[];
     /** tool 消息对应的 tool_call id */
@@ -24,6 +52,17 @@ export interface Message {
     /** 扩展字段，上层可附加任意元数据 */
     metadata?: Record<string, unknown>;
 }
+/**
+ * 从 Message.content 中提取纯文本（用于 Skill 路由、去重检测等场景）
+ * - string 直接返回
+ * - ContentPart[] 拼接所有 TextPart 和 FilePart 的文本
+ * - null 返回空字符串
+ */
+export declare function extractTextFromContent(content: string | ContentPart[] | null): string;
+/**
+ * 判断消息内容是否为多模态（包含非文本部分）
+ */
+export declare function isMultimodalContent(content: string | ContentPart[] | null): boolean;
 /** 所有事件的公共基座 */
 export interface BaseEvent {
     /** 事件时间戳（毫秒） */

package/dist/cjs/types.d.ts.map

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

package/dist/cjs/types.js

@@ -3,4 +3,38 @@
 // Core 全局共享类型
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTextFromContent = extractTextFromContent;
+exports.isMultimodalContent = isMultimodalContent;
+// ---- ContentPart 辅助函数 ----
+/**
+ * 从 Message.content 中提取纯文本（用于 Skill 路由、去重检测等场景）
+ * - string 直接返回
+ * - ContentPart[] 拼接所有 TextPart 和 FilePart 的文本
+ * - null 返回空字符串
+ */
+function extractTextFromContent(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    return content
+        .map(part => {
+        if (part.type === 'text')
+            return part.text;
+        if (part.type === 'file')
+            return `[file: ${part.filename}]\n${part.content}`;
+        if (part.type === 'image')
+            return `[image: ${part.source.slice(0, 80)}]`;
+        return '';
+    })
+        .join('\n');
+}
+/**
+ * 判断消息内容是否为多模态（包含非文本部分）
+ */
+function isMultimodalContent(content) {
+    if (content == null || typeof content === 'string')
+        return false;
+    return content.some(part => part.type === 'image' || part.type === 'file');
+}
 //# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,cAAc;AACd,+DAA+D"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,cAAc;AACd,+DAA+D;;AA2E/D,wDAWC;AAKD,kDAGC;AA3BD,6BAA6B;AAE7B;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,OAAsC;IAC3E,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,OAAO,OAAO;SACX,GAAG,CAAC,IAAI,CAAC,EAAE;QACV,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,UAAU,IAAI,CAAC,QAAQ,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7E,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,WAAW,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC;QACzE,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAAC,OAAsC;IACxE,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACjE,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;AAC7E,CAAC"}

package/dist/cjs/utils/token-counter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-counter.d.ts","sourceRoot":"","sources":["../../../src/utils/token-counter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AA6B3C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBhD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CA0B9D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD"}
+{"version":3,"file":"token-counter.d.ts","sourceRoot":"","sources":["../../../src/utils/token-counter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,aAAa,CAAC;AA6BxD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBhD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAiC9D;AA0BD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD"}

package/dist/cjs/utils/token-counter.js

@@ -72,7 +72,15 @@ function countMessageTokens(messages) {
         total += countTokens(msg.role || '');
         // content
         if (msg.content) {
-            total += countTokens(typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content));
+            if (typeof msg.content === 'string') {
+                total += countTokens(msg.content);
+            }
+            else {
+                // ContentPart[]：逐部分计算
+                for (const part of msg.content) {
+                    total += countContentPartTokens(part);
+                }
+            }
         }
         // tool_calls (序列化后的 token 数)
         if (msg.tool_calls) {
@@ -90,6 +98,30 @@ function countMessageTokens(messages) {
     total += 2;
     return total;
 }
+/**
+ * 计算单个 ContentPart 的 token 估算值
+ * - TextPart: 精确计数
+ * - ImagePart: 按详情级别估算（参考 OpenAI Vision 定价）
+ *   - low: ~85 tokens（512x512 固定）
+ *   - high: ~170 tokens/tile（最多 4 tiles → ~680）
+ *   - auto: 默认按 low 估算
+ * - FilePart: 计数文本内容
+ */
+function countContentPartTokens(part) {
+    switch (part.type) {
+        case 'text':
+            return countTokens(part.text);
+        case 'image':
+            // OpenAI Vision: low=85, high=170*tiles(1-4), auto≈85
+            if (part.detail === 'high')
+                return 680;
+            return 85;
+        case 'file':
+            return countTokens(part.content) + countTokens(part.filename);
+        default:
+            return 0;
+    }
+}
 /**
  * 估算文本 token 数（快速估算，不加载 tiktoken）
  * 适用于对精度要求不高的场景，约 4 字符 = 1 token

package/dist/cjs/utils/token-counter.js.map

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

package/dist/esm/agent/engine.d.ts

@@ -36,6 +36,29 @@ export declare class AgentEngine {
      * 获取会话历史副本（用于持久化保存）
      */
     getHistorySnapshot(sessionId: string): Message[];
+    /**
+     * 从持久化存储加载会话历史（重启后恢复 Agent 上下文）
+     * 需要在 run() 之前调用
+     * @returns true 如果加载成功且有历史消息
+     */
+    loadHistory(sessionId: string): Promise<boolean>;
+    /**
+     * 截断会话历史到指定位置（消息编辑场景）
+     * @param sessionId 会话 ID
+     * @param toIndex 保留的消息数量
+     * @returns 被截断掉的消息数量
+     */
+    truncateHistory(sessionId: string, toIndex: number): number;
+    /**
+     * 从现有会话分叉创建新会话（对话分支场景）
+     * @param sourceSessionId 源会话 ID
+     * @param targetSessionId 目标会话 ID
+     * @param fromIndex 从源会话复制到哪个位置
+     * @returns 新会话中的消息数量
+     */
+    forkHistory(sourceSessionId: string, targetSessionId: string, fromIndex?: number): number;
+    /** 获取会话历史的消息数量 */
+    getHistoryLength(sessionId: string): number;
     /**
      * 执行 Agent 任务（流式推送事件）
      * 上层通过 for-await-of 消费事件流

package/dist/esm/agent/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/agent/engine.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAuD,MAAM,aAAa,CAAC;AAGzH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAe,MAAM,YAAY,CAAC;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AA4D5E,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA4G;IAC1H,8BAA8B;IAC9B,OAAO,CAAC,SAAS,CAAkC;IACnD,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAsC;IACtD,4CAA4C;IAC5C,OAAO,CAAC,WAAW,CAA+B;IAElD,gBAAgB;IAChB,OAAO,CAAC,cAAc,CAAiB;IACvC,kBAAkB;IAClB,OAAO,CAAC,SAAS,CAAY;IAC7B,gBAAgB;IAChB,OAAO,CAAC,YAAY,CAAoB;IAExC,wBAAwB;IACxB,OAAO,CAAC,cAAc,CAAc;IACpC,iCAAiC;IACjC,OAAO,CAAC,WAAW,CAAc;gBAErB,MAAM,EAAE,WAAW;IAkD/B,yDAAyD;IACzD,eAAe,IAAI,YAAY;IAI/B,2CAA2C;IAC3C,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInC,mEAAmE;IACnE,eAAe,IAAI,OAAO,qBAAqB,EAAE,YAAY,GAAG,SAAS;IAIzE;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAIxD;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE;IAIhD;;;OAGG;IACI,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC;IAoC3D,0CAA0C;YAC5B,YAAY;IAe1B,wCAAwC;IACxC,OAAO,CAAC,oBAAoB;IA4D5B,6BAA6B;IAC7B,OAAO,CAAC,eAAe;IAyCvB,qBAAqB;IACrB,OAAO,CAAC,gBAAgB;IAmBxB,0BAA0B;YACZ,UAAU;IAyBxB,sCAAsC;YACvB,SAAS;IAgJxB;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IASlD,yCAAyC;IACzC,OAAO,CAAC,aAAa;IAgBrB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAuC5B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAiC1B,wBAAwB;IACxB,OAAO,CAAC,oBAAoB;IAsC5B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAuB/B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IA2B9B,uBAAuB;IACjB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAkBzE,6BAA6B;YACf,kBAAkB;IAwBhC,yCAAyC;IACnC,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqB5G,OAAO,CAAC,QAAQ;IAkBhB,uBAAuB;IACvB,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQ9B,uBAAuB;IACvB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW;IAIzC,oBAAoB;IACpB,OAAO,IAAI,IAAI;IAYf,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU;IAI1E,OAAO,CAAC,eAAe;CAOxB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/agent/engine.ts"],"names":[],"mappings":"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"}

package/dist/esm/agent/engine.js

@@ -3,6 +3,7 @@
 // ============================================================
 // 职责：编排 HistoryManager、LLMCaller、ToolExecutor 完成 ReAct 循环
 // 历史管理、LLM 调用、工具执行已分别抽离到独立模块
+import { extractTextFromContent } from "../types.js";
 import { HistoryManager } from "./history-manager.js";
 import { LLMCaller } from "./llm-caller.js";
 import { AgentToolExecutor } from "./tool-executor.js";
@@ -67,6 +68,7 @@ export class AgentEngine {
             maxMessages: this.config.maxMessages,
             contextBudget: this.config.contextBudget,
             toolResultStore: this.config.toolResultStore,
+            persistence: this.config.historyPersistence,
         });
         this.llmCaller = new LLMCaller({
             llmProvider: this.config.llmProvider,
@@ -123,6 +125,37 @@ export class AgentEngine {
     getHistorySnapshot(sessionId) {
         return this.historyManager.getHistorySnapshot(sessionId);
     }
+    /**
+     * 从持久化存储加载会话历史（重启后恢复 Agent 上下文）
+     * 需要在 run() 之前调用
+     * @returns true 如果加载成功且有历史消息
+     */
+    async loadHistory(sessionId) {
+        return this.historyManager.loadHistory(sessionId);
+    }
+    /**
+     * 截断会话历史到指定位置（消息编辑场景）
+     * @param sessionId 会话 ID
+     * @param toIndex 保留的消息数量
+     * @returns 被截断掉的消息数量
+     */
+    truncateHistory(sessionId, toIndex) {
+        return this.historyManager.truncateHistory(sessionId, toIndex);
+    }
+    /**
+     * 从现有会话分叉创建新会话（对话分支场景）
+     * @param sourceSessionId 源会话 ID
+     * @param targetSessionId 目标会话 ID
+     * @param fromIndex 从源会话复制到哪个位置
+     * @returns 新会话中的消息数量
+     */
+    forkHistory(sourceSessionId, targetSessionId, fromIndex) {
+        return this.historyManager.forkHistory(sourceSessionId, targetSessionId, fromIndex);
+    }
+    /** 获取会话历史的消息数量 */
+    getHistoryLength(sessionId) {
+        return this.historyManager.getHistoryLength(sessionId);
+    }
     /**
      * 执行 Agent 任务（流式推送事件）
      * 上层通过 for-await-of 消费事件流
@@ -171,9 +204,11 @@ export class AgentEngine {
         }
         if (this.config.skillRouter) {
             this.statusMap.set(sessionId, 'thinking');
-            const routeResult = await this.config.skillRouter.route(options.message);
+            // Skill 路由基于文本匹配，从多模态消息中提取文本
+            const routeText = typeof options.message === 'string' ? options.message : extractTextFromContent(options.message);
+            const routeResult = await this.config.skillRouter.route(routeText);
             if (routeResult.skill) {
-                return { skillContent: routeResult.skill.content, actualMessage: routeResult.message, skillMatched: true };
+                return { skillContent: routeResult.skill.content, actualMessage: options.message, skillMatched: true };
             }
         }
         return { actualMessage: options.message, skillMatched: false };
@@ -226,12 +261,20 @@ export class AgentEngine {
         // 则不再重复追加，避免 LLM 看到两条连续相同的 user 消息导致意图理解偏差
         const history = this.historyManager.getHistory(sessionId);
         const lastMsg = history.length > 0 ? history[history.length - 1] : null;
+        // 多模态消息去重：比较文本内容
+        const actualText = typeof actualMessage === 'string' ? actualMessage : extractTextFromContent(actualMessage);
         const isDuplicateUserMessage = lastMsg?.role === 'user'
             && typeof lastMsg.content === 'string'
-            && lastMsg.content === actualMessage;
+            && lastMsg.content === actualText;
+        // 非破坏性上下文投影（Context Collapse）：
+        // 当历史 token 超过预算时，使用投影而非破坏性压缩，保留原始历史完整
+        const maxContextTokens = this.config.contextBudget?.maxContextTokens ?? 100000;
+        const projectedHistory = this.historyManager.getProjectedHistory
+            ? this.historyManager.getProjectedHistory(sessionId, maxContextTokens)
+            : history;
         return this.config.contextManager.buildMessages({
             systemPrompt,
-            history,
+            history: projectedHistory,
             userMessage: isDuplicateUserMessage ? undefined : actualMessage,
         });
     }
@@ -326,6 +369,25 @@ export class AgentEngine {
                 yield this.emitDone(state);
                 return;
             }
+            // Token 预算检查
+            if (this.config.usageTracker && this.config.tokenBudget) {
+                const budgetCheck = this.config.usageTracker.checkBudget(state.sessionId, this.config.tokenBudget);
+                if (budgetCheck.exceeded) {
+                    if (this.config.tokenBudget.onExceed === 'abort') {
+                        console.warn(`[Engine] Token budget exceeded: ${budgetCheck.currentTokens}/${budgetCheck.maxTokens}, aborting session ${state.sessionId}`);
+                        yield this.createEvent(state.sessionId, {
+                            type: 'error',
+                            error: `Token budget exceeded (${budgetCheck.currentTokens}/${budgetCheck.maxTokens} tokens). Task aborted to prevent cost overrun.`,
+                            recoverable: false,
+                        });
+                        yield this.emitDone(state);
+                        return;
+                    }
+                    else {
+                        console.warn(`[Engine] Token budget warning: ${budgetCheck.currentTokens}/${budgetCheck.maxTokens} for session ${state.sessionId}`);
+                    }
+                }
+            }
             // Middleware.before + Hook: on_iteration_start
             await this.runMiddlewarePhase('before', state);
             await this.runHooks('on_iteration_start', {
@@ -379,7 +441,7 @@ export class AgentEngine {
             }
             this.historyManager.addHistory(state.sessionId, assistant);
             if (assistant.content) {
-                state.lastContent = assistant.content;
+                state.lastContent = extractTextFromContent(assistant.content);
                 state.consecutiveSilentIterations = 0;
             }
             // 无 tool_calls → 检查是否提前停止（上一轮有工具调用，说明任务可能未完成）
@@ -720,6 +782,17 @@ export class AgentEngine {
     // ---- 辅助 ----
     emitDone(state) {
         this.statusMap.set(state.sessionId, 'idle');
+        // 记录 Token 用量到 UsageTracker
+        if (this.config.usageTracker && state.totalUsage) {
+            const modelInfo = this.config.llmProvider.getModel();
+            this.config.usageTracker.record({
+                sessionId: state.sessionId,
+                provider: modelInfo.provider,
+                model: modelInfo.model,
+                usage: state.totalUsage,
+                iterations: state.iteration,
+            });
+        }
         this.runHooks('on_complete', {
             sessionId: state.sessionId,
             iteration: state.iteration,