hyacinth-ai 0.9.6

package/dist/context/composer.js

@@ -0,0 +1,318 @@
+import { TokenCounter, } from './tokenizer.js';
+import { SystemPromptBuilder, } from './prompt-builder.js';
+import { createHash } from 'node:crypto';
+import { getManifestLoader } from '../hot-reload/manifest-watcher.js';
+import { NORMAL_PROFILE, getActiveRouter } from './profiles.js';
+import { resolveSection } from './section-resolver.js';
+import { getCacheStrategy } from './cache-strategy.js';
+function formatTimestamp(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const y = date.getFullYear();
+    const m = pad(date.getMonth() + 1);
+    const d = pad(date.getDate());
+    const h = pad(date.getHours());
+    const min = pad(date.getMinutes());
+    return `${y}-${m}-${d} ${h}:${min}`;
+}
+/** 判断是否应跳过该历史消息 */
+function shouldSkipHistoryMessage(msg) {
+    if (msg.role === 'system')
+        return true;
+    const blocks = Array.isArray(msg.content) ? msg.content : [msg.content];
+    if (blocks.every(b => b.type === 'thinking'))
+        return true;
+    // 跳过纯系统注入文本
+    if (blocks.every(b => b.type === 'text')) {
+        const text = blocks.map(b => b.text).join('\n');
+        if (text.startsWith('[Scheduled Task]') || text.startsWith('[System]'))
+            return true;
+    }
+    return false;
+}
+export class LayeredContextComposer {
+    promptBuilder;
+    tokenCounter;
+    sources = new Map();
+    /** 当前激活的条件（如 precise_mode）— 由策略设置 */
+    activeConditions = new Set();
+    persistentSections = [];
+    cwd;
+    constructor(maxContextTokens = 200000) {
+        this.promptBuilder = new SystemPromptBuilder();
+        this.tokenCounter = new TokenCounter();
+        this.cwd = process.cwd();
+    }
+    registerSource(source) {
+        this.sources.set(source.name, source);
+    }
+    unregisterSource(name) {
+        this.sources.delete(name);
+    }
+    getSource(name) {
+        return this.sources.get(name);
+    }
+    registerPromptSection(section) {
+        this.persistentSections.push(section);
+    }
+    clearPersistentSections() {
+        this.persistentSections = [];
+    }
+    async compose(options) {
+        this.cwd = options.cwd ?? process.cwd();
+        if (this.isLayeredOptions(options)) {
+            this.promptBuilder = new SystemPromptBuilder();
+            for (const section of this.persistentSections) {
+                this.promptBuilder.registerSection(section);
+            }
+            return this.composeCore(options);
+        }
+        const composeOpts = options;
+        this.promptBuilder = new SystemPromptBuilder();
+        for (const section of this.persistentSections) {
+            this.promptBuilder.registerSection(section);
+        }
+        this.promptBuilder.registerSection({
+            name: 'legacy_system_prompt',
+            priority: 0,
+            content: composeOpts.systemPrompt,
+        });
+        const layeredOptions = this.toLayeredOptions(composeOpts);
+        const result = await this.composeCore(layeredOptions);
+        return result.messages;
+    }
+    async composeLegacy(options) {
+        return this.compose(options);
+    }
+    buildResolverContext(options) {
+        return {
+            cwd: options.cwd,
+            tools: options.tools,
+            userInput: options.userInput,
+            timestamp: options.timestamp || formatTimestamp(),
+            historySummary: options.historySummary,
+            currentPlan: options.currentPlan,
+            impactInfo: options.impactInfo,
+            history: options.history,
+            fullHistory: options.fullHistory,
+            zone3Hashes: options.zone3Hashes,
+            maxContextTokens: options.maxContextTokens,
+            sources: this.sources,
+            selectedSkills: options.selectedSkills,
+            selectedAgents: options.selectedAgents,
+            gitManager: options.gitManager,
+            tokenCounter: this.tokenCounter,
+            activeConditions: this.activeConditions,
+            profile: options.profile ?? NORMAL_PROFILE,
+            router: getActiveRouter(),
+            bypassInjections: options.bypassInjections,
+        };
+    }
+    async composeCore(options) {
+        const manifestLoader = getManifestLoader(this.cwd);
+        const enabledZones = manifestLoader.getEnabledZones();
+        const allMessages = [];
+        const breakdown = {};
+        // 记录每个 Zone 的消息数，供缓存策略计算断点位置
+        const zoneMsgCounts = [];
+        const ctx = this.buildResolverContext(options);
+        for (const [zoneKey] of enabledZones) {
+            const result = await this.assembleZone(zoneKey, options, ctx);
+            allMessages.push(...result.messages);
+            breakdown[zoneKey] = result.tokens;
+            zoneMsgCounts.push({ key: zoneKey, msgCount: result.messages.length });
+            if (zoneKey === 'zone3') {
+                options.zone3Hashes = this.computeHashes(result.messages);
+                ctx.zone3Hashes = options.zone3Hashes;
+            }
+        }
+        // ── 缓存策略：根据 ProviderType 在 Zone 边界打 cache_control 断点 ──
+        if (options.providerType) {
+            const strategy = getCacheStrategy(options.providerType);
+            // 先清除旧标记（防止历史消息中残留其他 Provider 的 cache_control）
+            this.clearMarkers(allMessages);
+            if (strategy.shouldApplyMarkers()) {
+                const markers = strategy.computeMarkers({ zones: zoneMsgCounts });
+                this.applyMarkers(allMessages, markers);
+            }
+        }
+        const totalTokens = Object.values(breakdown).reduce((sum, t) => sum + t, 0);
+        const zoneBreakdown = { ...breakdown, total: totalTokens };
+        this.clearPromptBuilder();
+        return { messages: allMessages, zoneBreakdown };
+    }
+    async assembleZone(zoneKey, options, ctx) {
+        const manifestLoader = getManifestLoader(this.cwd);
+        const zone = manifestLoader.getZone(zoneKey);
+        if (!zone || !zone.enabled) {
+            return { messages: [], tokens: 0 };
+        }
+        const zoneRole = zone.role ?? 'user';
+        if (zoneRole === 'system') {
+            const sections = manifestLoader.getSections(zoneKey);
+            for (const sec of sections) {
+                if (this.promptBuilder.getSection(sec.name))
+                    continue;
+                // conditional section 也需要解析——由 resolveConditional 根据 activeConditions 决定是否注入
+                if (sec.type === 'conditional') {
+                    const content = await resolveSection(sec, ctx);
+                    if (content) {
+                        this.promptBuilder.registerSection({
+                            name: sec.name,
+                            priority: sec.priority,
+                            content,
+                        });
+                    }
+                    continue;
+                }
+                const content = await resolveSection(sec, ctx);
+                if (content) {
+                    this.promptBuilder.registerSection({
+                        name: sec.name,
+                        priority: sec.priority,
+                        content,
+                    });
+                }
+            }
+            const systemPrompt = await this.promptBuilder.build();
+            if (!systemPrompt.trim()) {
+                return { messages: [], tokens: 0 };
+            }
+            const systemMessage = {
+                role: 'system',
+                content: { type: 'text', text: systemPrompt },
+            };
+            const tokens = this.tokenCounter.countMessageTokens(systemMessage);
+            return { messages: [systemMessage], tokens };
+        }
+        const sections = manifestLoader.getSections(zoneKey);
+        const messages = [];
+        const textParts = [];
+        const systemParts = [];
+        const flushTextParts = () => {
+            if (textParts.length > 0) {
+                messages.push({ role: zoneRole, content: { type: 'text', text: textParts.join('\n\n') } });
+                textParts.length = 0;
+            }
+        };
+        const flushSystemParts = () => {
+            if (systemParts.length > 0) {
+                messages.push({ role: 'system', content: { type: 'text', text: systemParts.join('\n\n') } });
+                systemParts.length = 0;
+            }
+        };
+        for (const sec of sections) {
+            // runtime:history — 保持消息独立性（保留 role），跳过系统注入和 thinking
+            if (sec.source === 'runtime:history' && options.history && options.history.length > 0) {
+                flushSystemParts();
+                flushTextParts();
+                for (const msg of options.history) {
+                    if (shouldSkipHistoryMessage(msg))
+                        continue;
+                    messages.push(msg);
+                }
+                continue;
+            }
+            const content = await resolveSection(sec, ctx);
+            if (!content)
+                continue;
+            // Router 可按"本轮该 section 的实际来源"覆写 role（如陪伴模式世界旁白 → assistant 内心独白）
+            // 旁路Agent 注入也可指定 role
+            const bypassRole = ctx.bypassInjections?.find(ij => ij.section === sec.name)?.role;
+            const roleOverride = bypassRole ?? ctx.router.roleForSection?.(sec.name);
+            const sectionRole = (roleOverride ?? sec.role ?? zoneRole);
+            const zr = zoneRole; // widen to avoid TS narrowing
+            if (sectionRole === 'system' && zr !== 'system') {
+                // 系统消息独立累积，合并成一条 system message
+                flushTextParts();
+                systemParts.push(content);
+            }
+            else if (sectionRole !== zr) {
+                flushSystemParts();
+                flushTextParts();
+                messages.push({ role: sectionRole, content: { type: 'text', text: content } });
+            }
+            else {
+                flushSystemParts();
+                textParts.push(content);
+            }
+        }
+        flushSystemParts();
+        flushTextParts();
+        if (messages.length === 0) {
+            return { messages: [], tokens: 0 };
+        }
+        const tokens = this.tokenCounter.countMessagesTokens(messages);
+        return { messages, tokens };
+    }
+    // --- Helpers ---
+    clearPromptBuilder() {
+        const sections = this.promptBuilder.getAllSections();
+        for (const section of sections) {
+            this.promptBuilder.unregisterSection(section.name);
+        }
+    }
+    isLayeredOptions(options) {
+        return 'sessionDir' in options;
+    }
+    computeHashes(messages) {
+        const hashes = new Set();
+        for (const msg of messages) {
+            const contentStr = JSON.stringify(msg.content);
+            hashes.add(createHash('md5').update(contentStr).digest('hex'));
+        }
+        return hashes;
+    }
+    /**
+     * 按策略计算出的断点位置，在消息的 TextContent 上打 cache_control 标记。
+     *
+     * 仅标记系统角色 (system/user) 的消息，跳过 assistant 角色。
+     * `cache_control` 放在消息的最后一个 TextContent block 上。
+     */
+    /**
+     * 清除所有消息上的 cache_control 标记。
+     *
+     * 历史消息中可能残留之前 Anthropic session 的 cache_control，
+     * 当切换到 DeepSeek/OpenAI 等 auto-prefix Provider 时，必须清除。
+     */
+    clearMarkers(messages) {
+        for (const msg of messages) {
+            if (msg.role === 'assistant')
+                continue;
+            const blocks = Array.isArray(msg.content) ? msg.content : [msg.content];
+            for (const block of blocks) {
+                if ('cache_control' in block) {
+                    delete block.cache_control;
+                }
+            }
+        }
+    }
+    applyMarkers(messages, markers) {
+        for (const marker of markers) {
+            const msg = messages[marker.index];
+            if (!msg || msg.role === 'assistant')
+                continue;
+            const blocks = Array.isArray(msg.content) ? msg.content : [msg.content];
+            // 从后往前找最后一个 TextContent block
+            for (let i = blocks.length - 1; i >= 0; i--) {
+                if (blocks[i].type === 'text' || blocks[i].type === 'image') {
+                    blocks[i].cache_control = {
+                        type: 'ephemeral',
+                    };
+                    break;
+                }
+            }
+        }
+    }
+    toLayeredOptions(options) {
+        return {
+            sessionDir: process.cwd(),
+            maxContextTokens: options.maxContextTokens,
+            cwd: process.cwd(),
+            timestamp: formatTimestamp(),
+            tools: options.tools,
+            history: options.history,
+            userInput: options.userInput,
+        };
+    }
+}
+//# sourceMappingURL=composer.js.map

package/dist/context/compressor.d.ts

@@ -0,0 +1,218 @@
+/**
+ * 差分压缩引擎 — Agent 框架的上下文压缩模块
+ *
+ * Phase 1: ToolOutputTrimmer — 无 LLM 调用的轻量压缩（规则裁剪）
+ * Phase 2: StructuredSummarizer — 首次结构化摘要（LLM 调用）
+ * Phase 3: StructuredSummarizer — 增量摘要更新（LLM 调用）
+ * Phase 4: 保护区规则裁剪 — 最终兜底（无 LLM 调用）
+ *
+ * 多轮迭代压缩：每轮按 token 比例动态分层，LLM 压缩最旧部分，
+ * 检查收敛后决定是否继续下一轮，最多 3 轮。
+ */
+import type { Message } from '../types.js';
+import type { ModelRouter } from '../provider/model-router.js';
+import type { GitManager } from '../evolution/git-manager.js';
+/**
+ * Phase 1 压缩器 — 无需 LLM 调用，纯规则驱动的工具输出裁剪。
+ */
+export declare class ToolOutputTrimmer {
+    /** 最近 N 条消息中的工具结果保持原样 */
+    private trimWindow;
+    constructor(trimWindow?: number);
+    /**
+     * 裁剪旧工具结果：不在最近 N 条消息中的 ToolResultContent 替换为一行摘要。
+     */
+    trimToolResults(messages: Message[]): Message[];
+    /**
+     * 去重连续的相同工具结果（MD5 匹配），仅保留最新，旧结果替换为引用。
+     */
+    deduplicateToolResults(messages: Message[]): Message[];
+    /**
+     * 截断过大的 tool_call JSON：当 input 序列化后超过 maxJsonLength 时，
+     * 生成智能摘要（提取关键参数）而非一刀切截断字符串。
+     */
+    truncateLargeToolCalls(messages: Message[], maxJsonLength?: number): Message[];
+    private static getCacheDir;
+    /** 将工具结果内容保存到缓存，返回引用 ID */
+    private saveToCache;
+    /** 为 ToolResultContent 生成一行摘要并缓存原始内容 */
+    private summarizeToolResult;
+    /** 根据工具结果内容推断工具名并生成摘要 + 缓存 */
+    private generateSummary;
+    /** 为大型 ToolUse input 生成智能摘要，提取关键参数。
+     *
+     * Write 工具特殊处理：提取函数/类签名、import、行数
+     * Edit 工具特殊处理：提取 old/new_string 首尾行、行数变化
+     * 其他工具：提取关键参数名
+     */
+    private summarizeToolInput;
+    /** Write 工具：提取函数/类签名、import、行数 */
+    private summarizeWriteInput;
+    /** Edit 工具：提取 old/new_string 首尾行、行数变化 */
+    private summarizeEditInput;
+}
+/**
+ * 12 字段结构化摘要模板 — 用于 Phase 2/3 的 LLM 摘要生成。
+ */
+export declare const STRUCTURED_SUMMARY_TEMPLATE: string;
+/**
+ * Phase 2-3 压缩器 — 使用 LLM 生成结构化摘要。
+ */
+export declare class StructuredSummarizer {
+    private modelRouter;
+    private compressDepth;
+    constructor(modelRouter: ModelRouter, options?: {
+        compressDepth?: number;
+    });
+    /** 运行时更新压缩深度 */
+    setCompressDepth(depth: number): void;
+    /** 根据 compressDepth 生成压缩策略提示词 */
+    private getDepthInstruction;
+    /**
+     * 生成结构化摘要。
+     *
+     * - 无 existingSummary → Phase 2（首次摘要），使用完整模板
+     * - 有 existingSummary → Phase 3（增量更新），基于前次摘要增量更新
+     *
+     * @param messages - 待压缩的历史消息
+     * @param existingSummary - 已有的摘要（增量压缩时传入）
+     * @param recentContext - 近期对话（不压缩，仅供 LLM 判断相关性，优先保留相关信息）
+     */
+    summarize(messages: Message[], existingSummary?: string, recentContext?: Message[]): Promise<string>;
+    /** 将消息序列化为可读文本 */
+    private serializeMessages;
+}
+/** 压缩结果 */
+export interface CompressionResult {
+    messages: Message[];
+    summary?: string;
+    phasesUsed: number[];
+    /** 本轮压缩覆盖的原始消息数量（输入消息数 - 返回消息数） */
+    compressedCount?: number;
+}
+/** 压缩统计 */
+export interface CompressionStats {
+    totalTokens: number;
+    maxTokens: number;
+    usageRatio: number;
+}
+/**
+ * 压缩编排器 — 协调所有压缩阶段。
+ */
+export declare class CompressorOrchestrator {
+    #private;
+    private tokenizer;
+    private summarizer;
+    private maxContextTokens;
+    /** ToolOutputTrimmer 的窗口大小（规则裁剪时最近 N 条不处理） */
+    private trimWindow;
+    private safetyThreshold;
+    private targetRatio;
+    private compressThreshold;
+    /** 最大迭代轮数 */
+    private maxRounds;
+    /** 压缩激进程度 0.0~1.0 */
+    private compressDepth;
+    /** 当前压缩摘要内容 */
+    private _currentSummary;
+    constructor(tokenizer: {
+        countMessagesTokens(messages: Message[]): number;
+    }, summarizer: StructuredSummarizer, maxContextTokens: number, options?: {
+        trimWindow?: number;
+        safetyThreshold?: number;
+        targetRatio?: number;
+        compressThreshold?: number;
+        maxRounds?: number;
+        compressDepth?: number;
+    });
+    /**
+     * 执行多轮迭代压缩。
+     *
+     * 每轮按 token 比例动态分层，LLM 压缩最旧部分（Layer 3），
+     * 规则裁剪中间部分（Layer 2，仅第 1 轮），保留最新部分（Layer 1）。
+     * 每轮后检查是否收敛，未收敛则缩小保护区继续下一轮，最多 maxRounds 轮。
+     *
+     * @param protectLast - 保护最后 N 条消息不被压缩（用于 Zone 5 live tail），默认 0
+     * @param historyBudget - 压缩预算基准（token 数）。调用方应传入 maxContextTokens
+     *   或计算后的 history 可用空间。未传入时回退到 maxContextTokens。
+     */
+    compress(messages: Message[], currentSummary: string | undefined, protectLast: number | undefined, historyBudget: number, options?: {
+        /** Git 管理器（热文件检测用） */
+        gitManager?: GitManager;
+    }): Promise<CompressionResult>;
+    /** 检查消息是否超过压缩阈值的最大上下文 token */
+    needsCompression(messages: Message[]): boolean;
+    /** 获取压缩统计信息 */
+    getCompressionStats(messages: Message[]): CompressionStats;
+    /**
+     * Update the compression threshold at runtime.
+     * This allows config changes to take effect without reconstruction.
+     */
+    setCompressThreshold(threshold: number): void;
+    /**
+     * Update the compression depth at runtime.
+     * Delegates to StructuredSummarizer for prompt modulation.
+     */
+    setCompressDepth(depth: number): void;
+    /**
+     * Get current compressDepth.
+     */
+    getCompressDepth(): number;
+    /** 获取当前压缩摘要 */
+    get currentSummary(): string | undefined;
+    /** 获取当前使用比例 */
+    private getUsageRatio;
+    /**
+     * 按 token 比例动态分层：从消息末尾向前累加 token 数，切分为三层。
+     *
+     * @param ratios - 分层比例 { layer1: 最新保留比例, layer2: 中间规则层比例, layer3: 最旧 LLM 层比例 }
+     *                 三者之和应为 1.0。layer2 为 0 表示跳过规则裁剪层。
+     * @returns { layer3, layer2, layer1 } 从最旧到最新排列
+     */
+    private splitByTokenRatio;
+    /**
+     * 确保消息数组中不存在连续的 user 角色消息。
+     *
+     * 策略：如果连续两条 user 消息中，后一条含 tool_result，
+     * 则将后一条的 tool_result 合并到前一条 user 消息中（保持与 assistant(tool_calls) 的配对），
+     * 否则插入空 assistant 消息分隔。
+     */
+    private ensureNoConsecutiveUserMessages;
+    /**
+     * 修复分层后 tool 消息的配对完整性。
+     * 如果 assistant 消息含 tool_use 被分到 layer3（将被摘要替代），
+     * 而对应的 tool_result 消息被分到 layer2/layer1，则会产生孤立 tool_result，
+     * 导致 API 报错 "Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"。
+     *
+     * 修复策略：将孤立的 tool_result 消息降级为普通 user 文本消息，
+     * 保留其内容但移除 tool_result 结构。
+     */
+    private fixOrphanedToolResults;
+    /**
+     * 全局 tool_result 完整性校验：确保最终输出中所有 tool_result
+     * 都有对应的 tool_use（assistant 消息中的 tool_calls）。
+     *
+     * 压缩后可能出现以下孤立场景：
+     * - layer3 整体被 LLM 摘要替代后，layer2/layer1 中残留的 tool_result
+     *   其对应的 tool_use 已随 layer3 一起消失
+     * - ensureNoConsecutiveUserMessages 插入空 assistant 后，
+     *   tool_result 与 tool_use 之间可能被隔开
+     * - 多轮压缩迭代中，早期修复可能引入新的孤立
+     *
+     * 修复策略：将孤立 tool_result 降级为普通 user 文本消息
+     */
+    private fixGlobalOrphanedToolResults;
+    /**
+     * 全局 tool_calls 完整性校验：确保每个 assistant 消息中的 tool_call
+     * 都有对应的 tool_result 消息紧跟其后。
+     *
+     * 压缩后可能出现的孤立场景：
+     * - assistant(tool_calls) 消息保留，但对应的 user(tool_result) 被压缩删掉
+     * - ensureNoConsecutiveUserMessages 合并消息时，tool_result 被移到其他位置
+     *
+     * 修复策略：从 assistant 消息中移除没有配对 tool_result 的 tool_calls。
+     * 如果移除后 assistant 消息只剩 tool_calls（无文本），则整体转为文本消息。
+     */
+    private fixGlobalOrphanedToolCalls;
+}
+//# sourceMappingURL=compressor.d.ts.map