kode-sdk 2.7.0

package/dist/core/compression/simple-strategy.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * 简单压缩策略
+ *
+ * 从现有 ContextManager 提取的压缩逻辑：
+ * - 按消息数保留 60% 或 compressToTokens/totalTokens 比例
+ * - 简单截断生成摘要
+ * - 处理孤立 tool_result
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleCompressionStrategy = void 0;
+const token_estimator_1 = require("./token-estimator");
+class SimpleCompressionStrategy {
+    constructor(opts) {
+        this.store = opts.store;
+        this.agentId = opts.agentId;
+        this.maxTokens = opts.maxTokens;
+        this.compressToTokens = opts.compressToTokens;
+        this.compressionModel = opts.compressionModel ?? 'simple';
+        this.compressionPrompt = opts.compressionPrompt ?? 'Simple truncation summary';
+        this.eventEmitter = opts.eventEmitter;
+    }
+    /**
+     * 分析上下文使用情况（粗略的 token 估算）
+     */
+    analyze(messages) {
+        const totalTokens = messages.reduce((sum, message) => {
+            return (sum +
+                message.content.reduce((inner, block) => {
+                    if (block.type === 'text')
+                        return inner + Math.ceil(block.text.length / 4);
+                    return inner + Math.ceil(JSON.stringify(block).length / 4);
+                }, 0));
+        }, 0);
+        return {
+            totalTokens,
+            messageCount: messages.length,
+            shouldCompress: totalTokens > this.maxTokens,
+        };
+    }
+    /**
+     * 执行压缩
+     */
+    async compress(messages, events, filePool, sandbox) {
+        const usage = this.analyze(messages);
+        if (!usage.shouldCompress)
+            return undefined;
+        // 发送开始事件
+        this.eventEmitter?.emit({
+            phase: 'start',
+            algorithm: 'simple',
+        });
+        const timestamp = Date.now();
+        const windowId = `window-${timestamp}`;
+        const compressionId = `comp-${timestamp}`;
+        // 1. 保存历史窗口
+        const window = {
+            id: windowId,
+            messages,
+            events,
+            stats: {
+                messageCount: messages.length,
+                tokenCount: usage.totalTokens,
+                eventCount: events.length,
+            },
+            timestamp,
+        };
+        await this.store.saveHistoryWindow(this.agentId, window);
+        // 2. 执行压缩（简化版：保留 60% 消息或按比例）
+        const targetRatio = this.compressToTokens / usage.totalTokens;
+        const keepCount = Math.ceil(messages.length * Math.max(targetRatio, 0.6));
+        const retainedMessages = messages.slice(-keepCount);
+        const removedMessages = messages.slice(0, messages.length - keepCount);
+        // 处理孤立的 tool_result
+        const toolSanitized = this.sanitizeOrphanToolResults(retainedMessages);
+        const retainedSanitized = toolSanitized.messages;
+        // 生成摘要
+        const summaryText = this.generateSummary(removedMessages);
+        const summary = {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: `<context-summary timestamp="${new Date().toISOString()}" window="${windowId}">\n${summaryText}\n</context-summary>`,
+                },
+            ],
+        };
+        // 3. 保存文件快照
+        const recoveredPaths = [];
+        if (filePool && sandbox) {
+            const accessed = filePool.getAccessedFiles().slice(0, 5);
+            for (const { path, mtime } of accessed) {
+                recoveredPaths.push(path);
+                try {
+                    const content = await sandbox.fs.read(path);
+                    const file = {
+                        path,
+                        content,
+                        mtime,
+                        timestamp,
+                    };
+                    await this.store.saveRecoveredFile(this.agentId, file);
+                }
+                catch (err) {
+                    const file = {
+                        path,
+                        content: `// Failed to read file: ${err instanceof Error ? err.message : String(err)}`,
+                        mtime,
+                        timestamp,
+                    };
+                    await this.store.saveRecoveredFile(this.agentId, file);
+                }
+            }
+        }
+        // 4. 保存压缩记录
+        const ratio = retainedMessages.length / messages.length;
+        const record = {
+            id: compressionId,
+            windowId,
+            config: {
+                model: this.compressionModel,
+                prompt: this.compressionPrompt,
+                threshold: this.maxTokens,
+            },
+            summary: summaryText.slice(0, 500),
+            ratio,
+            recoveredFiles: recoveredPaths,
+            timestamp,
+        };
+        await this.store.saveCompressionRecord(this.agentId, record);
+        // 计算 token 统计
+        const tokensRetained = (0, token_estimator_1.estimateTotalTokens)(retainedSanitized);
+        const tokensRemoved = usage.totalTokens - tokensRetained;
+        // 发送完成事件
+        this.eventEmitter?.emit({
+            phase: 'end',
+            algorithm: 'simple',
+            ratio,
+            tokensRemoved,
+            tokensRetained,
+        });
+        return {
+            summary,
+            removedMessages,
+            retainedMessages: retainedSanitized,
+            windowId,
+            compressionId,
+            ratio,
+            algorithm: 'simple',
+            aiGenerated: false,
+            tokensRemoved,
+            tokensRetained,
+        };
+    }
+    /**
+     * 预览文本（截断长文本）
+     */
+    preview(value, limit = 1000) {
+        try {
+            const text = typeof value === 'string' ? value : JSON.stringify(value);
+            return text.length > limit ? `${text.slice(0, limit)}…` : text;
+        }
+        catch {
+            const text = String(value ?? '');
+            return text.length > limit ? `${text.slice(0, limit)}…` : text;
+        }
+    }
+    /**
+     * 处理孤立的 tool_result
+     *
+     * 简单的 slice 可能保留 tool_result 但丢弃配对的 tool_use，
+     * 导致 Anthropic API 报错 (2013)。将孤立的 tool_result 转换为文本。
+     */
+    sanitizeOrphanToolResults(messages) {
+        const toolUseIds = new Set();
+        for (const msg of messages || []) {
+            for (const block of msg?.content || []) {
+                if (block && block.type === 'tool_use') {
+                    const id = String(block.id ?? '').trim();
+                    if (id)
+                        toolUseIds.add(id);
+                }
+            }
+        }
+        let converted = 0;
+        const out = [];
+        for (const msg of messages || []) {
+            if (!msg || !Array.isArray(msg.content)) {
+                out.push(msg);
+                continue;
+            }
+            let changed = false;
+            const nextBlocks = [];
+            for (const block of msg.content) {
+                if (block && block.type === 'tool_result') {
+                    const toolUseId = String(block.tool_use_id ?? '').trim();
+                    if (!toolUseId || !toolUseIds.has(toolUseId)) {
+                        changed = true;
+                        converted += 1;
+                        const isErr = Boolean(block.is_error);
+                        const payload = this.preview(block.content, 1400);
+                        nextBlocks.push({
+                            type: 'text',
+                            text: `[tool_result orphaned by compression] tool_use_id=${toolUseId || 'unknown'}${isErr ? ' (error)' : ''}\n${payload}`,
+                        });
+                        continue;
+                    }
+                }
+                nextBlocks.push(block);
+            }
+            out.push(changed ? { ...msg, content: nextBlocks } : msg);
+        }
+        return { messages: out, converted };
+    }
+    /**
+     * 生成简单摘要（截断文本）
+     */
+    generateSummary(messages) {
+        return messages
+            .map((msg, idx) => {
+            const header = `${idx + 1}. [${msg.role}]`;
+            const content = msg.content
+                .map((block) => {
+                if (block.type === 'text')
+                    return block.text.slice(0, 200);
+                if (block.type === 'tool_use')
+                    return `🔧 ${block.name}(...)`;
+                if (block.type === 'tool_result') {
+                    const preview = JSON.stringify(block.content).slice(0, 100);
+                    return `✅ result: ${preview}`;
+                }
+                return '';
+            })
+                .join('\n');
+            return `${header}\n${content}`;
+        })
+            .join('\n\n');
+    }
+}
+exports.SimpleCompressionStrategy = SimpleCompressionStrategy;

package/dist/core/compression/token-estimator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Token 估算工具
+ *
+ * 提供更精确的 token 数量估算，考虑：
+ * - 中英文字符差异
+ * - 不同消息块类型的开销
+ */
+import { Message, ContentBlock } from '../types';
+/**
+ * 估算文本的 token 数量
+ *
+ * 规则：
+ * - 英文/数字/符号：约 4 字符 = 1 token
+ * - 中文/日文/韩文：约 1.5 字符 = 1 token
+ */
+export declare function estimateTextTokens(text: string): number;
+/**
+ * 估算单个内容块的 token 数量
+ */
+export declare function estimateBlockTokens(block: ContentBlock): number;
+/**
+ * 估算单条消息的 token 数量
+ */
+export declare function estimateMessageTokens(message: Message): number;
+/**
+ * 估算消息列表的总 token 数量
+ */
+export declare function estimateTotalTokens(messages: Message[]): number;
+/**
+ * 根据目标 token 数选择要保留的消息
+ *
+ * 从后往前累加，直到达到目标 token 数
+ *
+ * @param messages - 消息列表
+ * @param targetTokens - 目标 token 数
+ * @param minMessages - 最少保留消息数（默认 2）
+ * @returns 保留的消息和移除的消息
+ */
+export declare function selectMessagesByTokens(messages: Message[], targetTokens: number, minMessages?: number): {
+    retained: Message[];
+    removed: Message[];
+};

package/dist/core/compression/token-estimator.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Token 估算工具
+ *
+ * 提供更精确的 token 数量估算，考虑：
+ * - 中英文字符差异
+ * - 不同消息块类型的开销
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTextTokens = estimateTextTokens;
+exports.estimateBlockTokens = estimateBlockTokens;
+exports.estimateMessageTokens = estimateMessageTokens;
+exports.estimateTotalTokens = estimateTotalTokens;
+exports.selectMessagesByTokens = selectMessagesByTokens;
+/**
+ * 估算文本的 token 数量
+ *
+ * 规则：
+ * - 英文/数字/符号：约 4 字符 = 1 token
+ * - 中文/日文/韩文：约 1.5 字符 = 1 token
+ */
+function estimateTextTokens(text) {
+    if (!text)
+        return 0;
+    // 匹配 CJK（中日韩）字符
+    const cjkChars = (text.match(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g) || []).length;
+    const otherChars = text.length - cjkChars;
+    // CJK 字符约 1.5 字符 = 1 token，其他约 4 字符 = 1 token
+    return Math.ceil(cjkChars / 1.5) + Math.ceil(otherChars / 4);
+}
+/**
+ * 估算单个内容块的 token 数量
+ */
+function estimateBlockTokens(block) {
+    if (!block)
+        return 0;
+    switch (block.type) {
+        case 'text':
+            return estimateTextTokens(block.text);
+        case 'tool_use':
+            // 工具调用包含：名称、ID、输入参数
+            // 基础开销约 50 tokens（JSON 结构、字段名等）
+            const toolUseContent = JSON.stringify(block.input || {});
+            return estimateTextTokens(block.name) + estimateTextTokens(toolUseContent) + 50;
+        case 'tool_result':
+            // 工具结果包含：ID、内容
+            // 基础开销约 20 tokens
+            const toolResultContent = typeof block.content === 'string' ? block.content : JSON.stringify(block.content || '');
+            return estimateTextTokens(toolResultContent) + 20;
+        default:
+            // 未知类型，使用 JSON 序列化估算
+            try {
+                return estimateTextTokens(JSON.stringify(block));
+            }
+            catch {
+                return 100; // 默认估算
+            }
+    }
+}
+/**
+ * 估算单条消息的 token 数量
+ */
+function estimateMessageTokens(message) {
+    if (!message || !Array.isArray(message.content))
+        return 0;
+    // 消息元数据开销（role 等）约 5 tokens
+    const baseOverhead = 5;
+    const contentTokens = message.content.reduce((sum, block) => {
+        return sum + estimateBlockTokens(block);
+    }, 0);
+    return baseOverhead + contentTokens;
+}
+/**
+ * 估算消息列表的总 token 数量
+ */
+function estimateTotalTokens(messages) {
+    if (!messages || !Array.isArray(messages))
+        return 0;
+    return messages.reduce((sum, message) => {
+        return sum + estimateMessageTokens(message);
+    }, 0);
+}
+/**
+ * 根据目标 token 数选择要保留的消息
+ *
+ * 从后往前累加，直到达到目标 token 数
+ *
+ * @param messages - 消息列表
+ * @param targetTokens - 目标 token 数
+ * @param minMessages - 最少保留消息数（默认 2）
+ * @returns 保留的消息和移除的消息
+ */
+function selectMessagesByTokens(messages, targetTokens, minMessages = 2) {
+    if (!messages || messages.length === 0) {
+        return { retained: [], removed: [] };
+    }
+    let currentTokens = 0;
+    const retained = [];
+    // 从后往前累加，保留最近的消息
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msgTokens = estimateMessageTokens(messages[i]);
+        // 如果已经超过目标但还没达到最小消息数，继续保留
+        if (currentTokens + msgTokens > targetTokens && retained.length >= minMessages) {
+            break;
+        }
+        retained.unshift(messages[i]);
+        currentTokens += msgTokens;
+    }
+    // 确保至少保留 minMessages 条消息
+    while (retained.length < minMessages && retained.length < messages.length) {
+        const idx = messages.length - retained.length - 1;
+        if (idx >= 0) {
+            retained.unshift(messages[idx]);
+        }
+        else {
+            break;
+        }
+    }
+    const removed = messages.slice(0, messages.length - retained.length);
+    return { retained, removed };
+}

package/dist/core/compression/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 上下文压缩策略模块 - 类型定义
+ *
+ * 支持多种压缩算法：
+ * - simple: 简单截断（保留最近消息 + 文本摘要）
+ * - ai: AI 智能压缩（使用 LLM 生成结构化摘要）
+ */
+import { Message, Timeline, Bookmark } from '../types';
+import { Store } from '../../infra/store';
+import { Sandbox } from '../../infra/sandbox';
+import { ModelProvider, ModelConfig } from '../../infra/provider';
+/**
+ * 上下文使用情况分析结果
+ */
+export interface ContextUsage {
+    totalTokens: number;
+    messageCount: number;
+    shouldCompress: boolean;
+}
+/**
+ * 压缩结果
+ */
+export interface CompressionResult {
+    /** 生成的摘要消息 */
+    summary: Message;
+    /** 被移除的消息 */
+    removedMessages: Message[];
+    /** 保留的消息 */
+    retainedMessages: Message[];
+    /** 历史窗口 ID */
+    windowId: string;
+    /** 压缩记录 ID */
+    compressionId: string;
+    /** 压缩比例（保留消息数 / 总消息数） */
+    ratio: number;
+    /** 使用的压缩算法 */
+    algorithm?: 'simple' | 'ai';
+    /** 摘要是否由 AI 生成（降级时为 false） */
+    aiGenerated?: boolean;
+    /** 压缩掉的 token 数（估算） */
+    tokensRemoved?: number;
+    /** 保留的 token 数（估算） */
+    tokensRetained?: number;
+}
+/**
+ * 文件池状态接口（用于获取访问过的文件）
+ */
+export interface FilePoolState {
+    getAccessedFiles(): Array<{
+        path: string;
+        mtime: number;
+    }>;
+}
+/**
+ * 压缩事件发送器
+ */
+export interface CompressionEventEmitter {
+    emit(event: CompressionEventPayload): void;
+}
+/**
+ * 压缩事件负载
+ */
+export interface CompressionEventPayload {
+    phase: 'start' | 'summarizing' | 'end' | 'fallback';
+    algorithm?: 'simple' | 'ai';
+    summary?: string;
+    ratio?: number;
+    tokensRemoved?: number;
+    tokensRetained?: number;
+    error?: string;
+    bookmark?: Bookmark;
+}
+/**
+ * 压缩策略接口
+ *
+ * 所有压缩算法（simple、ai）都需要实现此接口
+ */
+export interface ICompressionStrategy {
+    /**
+     * 分析上下文使用情况
+     */
+    analyze(messages: Message[]): ContextUsage;
+    /**
+     * 执行压缩
+     *
+     * @param messages - 当前消息列表
+     * @param events - 事件时间线
+     * @param filePool - 文件池状态（可选）
+     * @param sandbox - 沙箱实例（可选，用于读取文件内容）
+     * @returns 压缩结果，如果不需要压缩则返回 undefined
+     */
+    compress(messages: Message[], events: Timeline[], filePool?: FilePoolState, sandbox?: Sandbox): Promise<CompressionResult | undefined>;
+}
+/**
+ * 模型工厂函数类型
+ */
+export type ModelFactory = (config: ModelConfig) => ModelProvider;
+/**
+ * 压缩策略基础配置
+ */
+export interface CompressionStrategyBaseOptions {
+    /** Store 实例（用于保存历史窗口和压缩记录） */
+    store: Store;
+    /** Agent ID */
+    agentId: string;
+    /** 压缩触发阈值（tokens） */
+    maxTokens: number;
+    /** 压缩后目标大小（tokens） */
+    compressToTokens: number;
+    /** 事件发送器 */
+    eventEmitter?: CompressionEventEmitter;
+}
+/**
+ * 简单压缩策略配置
+ */
+export interface SimpleCompressionStrategyOptions extends CompressionStrategyBaseOptions {
+    /** 压缩模型名称（仅用于记录） */
+    compressionModel?: string;
+    /** 压缩提示词（仅用于记录） */
+    compressionPrompt?: string;
+}
+/**
+ * AI 压缩策略配置
+ */
+export interface AICompressionStrategyOptions extends CompressionStrategyBaseOptions {
+    /** 主模型配置（用于复用 apiKey/baseUrl） */
+    modelConfig: ModelConfig;
+    /** 模型工厂（用于创建摘要模型） */
+    modelFactory: ModelFactory;
+    /** 摘要模型配置（可选，覆盖主模型配置） */
+    summaryModelConfig?: {
+        model?: string;
+        apiKey?: string;
+        baseUrl?: string;
+    };
+    /** 自定义摘要提示词 */
+    summaryPrompt?: string;
+    /** 始终保留最近 N 轮对话（默认 3） */
+    preserveRecentTurns?: number;
+}

package/dist/core/compression/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * 上下文压缩策略模块 - 类型定义
+ *
+ * 支持多种压缩算法：
+ * - simple: 简单截断（保留最近消息 + 文本摘要）
+ * - ai: AI 智能压缩（使用 LLM 生成结构化摘要）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/config.d.ts

@@ -0,0 +1,10 @@
+export interface Configurable<TConfig> {
+    toConfig(): TConfig;
+}
+export interface SerializedComponent<TKind extends string, TConfig = Record<string, any>> {
+    kind: TKind;
+    config: TConfig;
+}
+export interface WithMetadata<TMeta = Record<string, any>> {
+    metadata?: TMeta;
+}

package/dist/core/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/context-manager.d.ts

@@ -0,0 +1,115 @@
+import { Message, Timeline } from './types';
+import { Store, HistoryWindow, CompressionRecord, RecoveredFile } from '../infra/store';
+import { Sandbox } from '../infra/sandbox';
+import { ModelConfig } from '../infra/provider';
+import { CompressionEventEmitter, ModelFactory } from './compression';
+export interface ContextUsage {
+    totalTokens: number;
+    messageCount: number;
+    shouldCompress: boolean;
+}
+export interface CompressionResult {
+    summary: Message;
+    removedMessages: Message[];
+    retainedMessages: Message[];
+    windowId: string;
+    compressionId: string;
+    ratio: number;
+    /** 使用的压缩算法 */
+    algorithm?: 'simple' | 'ai';
+    /** 摘要是否由 AI 生成 */
+    aiGenerated?: boolean;
+    /** 压缩掉的 token 数 */
+    tokensRemoved?: number;
+    /** 保留的 token 数 */
+    tokensRetained?: number;
+}
+export interface ContextManagerOptions {
+    maxTokens?: number;
+    compressToTokens?: number;
+    compressionModel?: string;
+    compressionPrompt?: string;
+    /** 压缩算法：'simple' (默认) 或 'ai' */
+    algorithm?: 'simple' | 'ai';
+    /** 主模型配置（用于复用 apiKey/baseUrl） */
+    modelConfig?: ModelConfig;
+    /** 模型工厂（用于创建摘要模型） */
+    modelFactory?: ModelFactory;
+    /** 摘要模型配置（可选，覆盖主模型配置） */
+    summaryModelConfig?: {
+        model?: string;
+        apiKey?: string;
+        baseUrl?: string;
+    };
+    /** 自定义摘要提示词 */
+    summaryPrompt?: string;
+    /** 始终保留最近 N 轮对话（默认 3） */
+    preserveRecentTurns?: number;
+    /** 事件发送器 */
+    eventEmitter?: CompressionEventEmitter;
+}
+export interface FilePoolState {
+    getAccessedFiles(): Array<{
+        path: string;
+        mtime: number;
+    }>;
+}
+/**
+ * ContextManager v3 - 支持多种压缩策略的上下文管理器
+ *
+ * 职责：
+ * 1. 分析上下文使用情况（token 估算）
+ * 2. 根据配置选择压缩策略（simple 或 ai）
+ * 3. 委托策略执行压缩
+ * 4. 提供历史记录查询接口
+ *
+ * 策略模式：
+ * - simple: 简单截断（保留最近消息 + 文本摘要）
+ * - ai: AI 智能压缩（使用 LLM 生成结构化摘要）
+ */
+export declare class ContextManager {
+    private readonly store;
+    private readonly agentId;
+    private readonly strategy;
+    constructor(store: Store, agentId: string, opts?: ContextManagerOptions);
+    /**
+     * 创建压缩策略
+     *
+     * 默认值基于 Claude 官方最佳实践：
+     * - maxTokens: 64K = 50% 的 128K 上下文窗口（对标 Claude 默认 100K/200K）
+     * - compressToTokens: 40K = 约 62.5% 的 maxTokens
+     * @see https://platform.claude.com/cookbook/tool-use-automatic-context-compaction
+     */
+    private createStrategy;
+    /**
+     * 分析上下文使用情况（粗略的 token 估算）
+     *
+     * 方法签名保持不变，委托给策略执行
+     */
+    analyze(messages: Message[]): ContextUsage;
+    /**
+     * 压缩上下文并保存历史
+     *
+     * 方法签名保持不变，委托给策略执行
+     *
+     * 流程：
+     * 1. 保存 HistoryWindow（压缩前的完整快照）
+     * 2. 执行压缩（根据策略不同，方式不同）
+     * 3. 保存 CompressionRecord（压缩元信息）
+     * 4. 保存重要文件快照（如果有 FilePool）
+     * 5. 返回压缩结果
+     */
+    compress(messages: Message[], events: Timeline[], filePool?: FilePoolState, sandbox?: Sandbox): Promise<CompressionResult | undefined>;
+    /**
+     * 恢复历史窗口（用于审计或调试）
+     */
+    loadHistory(): Promise<HistoryWindow[]>;
+    /**
+     * 加载压缩记录
+     */
+    loadCompressions(): Promise<CompressionRecord[]>;
+    /**
+     * 加载恢复的文件
+     */
+    loadRecoveredFiles(): Promise<RecoveredFile[]>;
+}