autosnippet/dist/lib/agent/memory/ActiveContext.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * ActiveContext — 合并 WorkingMemory + ReasoningTrace 为统一的会话工作记忆
 *
 * 三个内部子区:
 *   1. Scratchpad   — Agent 通过 note_finding 主动标记的发现 (不可压缩)
 *   2. ObservationLog — 每轮 ReAct 记录 (合并原 RT.rounds + WM.observations，滑动窗口压缩)
 *   3. Plan          — 从 ReasoningTrace 继承的规划追踪
 *
 * 替代关系:
 *   WorkingMemory.js  → Scratchpad + 工具压缩策略 + buildContext + distill
 *   ReasoningTrace.js → rounds + plan + thoughts + extractAndSetPlan + observations
 *
 * 兼容性:
 *   - 提供所有 ReasoningTrace 和 WorkingMemory 的公共方法
 *   - ExplorationTracker 可直接使用 ActiveContext 作为 trace 参数 (L5 缓解)
 *   - MemoryCoordinator 通过 createDimensionScope 创建实例
 *
 * 生命周期: 单次 execute() 调用 (由 MemoryCoordinator 管理创建/蒸馏/销毁)
 *
 * @module ActiveContext
 */
import type { DistilledContext } from './memory-flush-contract.js';
interface ActiveContextOptions {
    maxRecentRounds?: number;
    lightweight?: boolean;
}
interface ScratchpadEntry {
    finding: string;
    evidence: string;
    importance: number;
    round: number;
}
interface RoundAction {
    tool: string;
    params: Record<string, unknown>;
}
interface RoundObservation {
    tool: string;
    gotNewInfo?: boolean;
    resultType?: string;
    keyFacts?: string[];
    resultSize?: number;
    [key: string]: unknown;
}
interface RoundSummary {
    newInfoCount?: number;
    totalCalls?: number;
    submits?: number;
    cumulativeFiles?: number;
    cumulativePatterns?: number;
    [key: string]: unknown;
}
interface Round {
    iteration: number;
    thought: string | null;
    actions: RoundAction[];
    observations: RoundObservation[];
    reflection: string | null;
    roundSummary: RoundSummary | null;
    startTime: number;
    endTime: number | null;
}
interface PlanStep {
    description: string;
    status: string;
    keywords: string[];
}
interface Plan {
    text: string;
    steps: PlanStep[];
    createdAtIteration: number;
    lastUpdatedAtIteration: number;
}
interface ActiveContextJSON {
    rounds?: Round[];
    scratchpad?: ScratchpadEntry[];
    totalObservations?: number;
    plan?: Plan;
}
export declare class ActiveContext {
    #private;
    /**
     * @param [options.maxRecentRounds=3] 保留最近 N 轮原始结果 (WM 滑动窗口)
     * @param [options.lightweight=false] 轻量模式: 跳过 WM 的压缩/Scratchpad 逻辑 (D5)
     */
    constructor(options?: ActiveContextOptions);
    /**
     * 开始新一轮推理
     * @param iteration 轮次编号
     */
    startRound(iteration: number): void;
    /** 结束当前轮次 */
    endRound(): void;
    /** 记录 AI 的推理文本（从 aiResult.text 提取） */
    setThought(text: string): void;
    /**
     * 统一记录一次工具调用 — 合并原 WM.observe() + RT.addAction() + RT.addObservation()
     *
     * @param toolName 工具名称
     * @param args 工具参数
     * @param result 工具返回的原始结果
     * @param isNew 是否发现新信息 (由 ExplorationTracker.recordToolCall 提供)
     */
    recordToolCall(toolName: string, args: Record<string, unknown>, result: unknown, isNew: boolean): void;
    /** 兼容旧 RT API: 记录一次工具调用 (Action only) */
    addAction(toolName: string, params: Record<string, unknown>): void;
    /** 兼容旧 RT API: 记录一次工具结果的结构化观察 */
    addObservation(toolName: string, meta: Record<string, unknown>): void;
    /** 兼容旧 WM API: 记录工具调用结果 (Observe, 仅 WM 滑动窗口) */
    observe(toolName: string, result: unknown, round: number): void;
    /** 记录反思内容 (ExplorationTracker 使用, L5 修复) */
    setReflection(text: string): void;
    /**
     * 记录轮次摘要
     * @param summary { newInfoCount, totalCalls, submits, cumulativeFiles, cumulativePatterns }
     */
    setRoundSummary(summary: RoundSummary): void;
    /**
     * Agent 主动记录关键发现 (note_finding 工具入口)
     *
     * @param finding 关键发现描述
     * @param [evidence] 证据 (文件路径:行号)
     * @param [importance=5] 重要性 1-10
     * @param [round=0] 当前轮次
     */
    noteKeyFinding(finding: string, evidence?: unknown, importance?: number, round?: number): void;
    /**
     * 从 AI 响应文本中提取计划，自动调用 setPlan/updatePlan
     *
     * 防御措施: 已存在计划时，仅在 #expectingPlan 为 true 时才覆盖。
     * 这防止 reflection 回复中的编号列表（非计划的回应文本）污染已有计划。
     * ExplorationTracker 在发送 plan elicitation / replan 时调用 expectPlan() 授权更新。
     *
     * @param text AI 完整响应文本
     * @param iteration 当前轮次
     * @returns 是否成功提取到计划
     */
    extractAndSetPlan(text: string, iteration: number): boolean;
    /**
     * 标记「下一次响应可能包含计划」— 授权 extractAndSetPlan 覆盖已有计划
     * 由 ExplorationTracker 在发送 plan elicitation / replan nudge 时调用。
     */
    expectPlan(): void;
    /** 直接设置计划 (公开接口，供 ExplorationTracker 和测试使用) */
    setPlan(planText: string, iteration: number): void;
    /** 更新计划 (保留旧 plan 到 history) */
    updatePlan(replanText: string, iteration: number): void;
    /** 获取当前计划 (只读副本) */
    getPlan(): {
        steps: {
            description: string;
            status: string;
            keywords: string[];
        }[];
        text: string;
        createdAtIteration: number;
        lastUpdatedAtIteration: number;
    } | null;
    /** 获取计划步骤的可变引用 (ExplorationTracker.updatePlanProgress 使用) */
    getPlanStepsMutable(): PlanStep[];
    /** 获取计划历史 (F7) */
    getPlanHistory(): {
        steps: {
            description: string;
            status: string;
            keywords: string[];
        }[];
        text: string;
        createdAtIteration: number;
        lastUpdatedAtIteration: number;
    }[];
    /**
     * 获取当前轮次的 actions (ExplorationTracker.updatePlanProgress 使用, L5 修复)
     * @returns >}
     */
    getCurrentRoundActions(): RoundAction[];
    /** 获取当前轮次的 iteration 编号 (F8) */
    getCurrentIteration(): number | null;
    /**
     * 构建当前工作记忆的上下文快照
     * 用于注入到 system prompt 或 user nudge 中
     *
     * @param [tokenBudget=Infinity] token 预算 (新增: 预算控制)
     * @returns Markdown 格式的上下文块，空字符串表示无内容
     */
    buildContext(tokenBudget?: number): string;
    /**
     * 蒸馏 ActiveContext 为结构化报告
     * 在 Agent execute 结束时调用，结果写入 SessionStore
     */
    distill(): DistilledContext;
    /**
     * 获取所有有 Thought 的轮次
     * @returns >}
     */
    getThoughts(): {
        iteration: number;
        thought: string | null;
    }[];
    /**
     * 获取最近 N 轮的紧凑摘要 (ExplorationTracker.#checkReflection 使用)
     * @param [n=3] 回看轮数
     */
    getRecentSummary(n?: number): {
        roundCount: number;
        thoughts: string[];
        toolCalls: string[];
        newInfoRatio: number;
        lastIteration: number;
    } | null;
    /** 统计指标 (ExplorationTracker.getQualityMetrics 使用) */
    getStats(): {
        totalRounds: number;
        thoughtCount: number;
        totalActions: number;
        totalObservations: number;
        reflectionCount: number;
        totalDurationMs: number;
    };
    /** 获取 scratchpad 中的关键发现数量 */
    get scratchpadSize(): number;
    /** 获取总观察数 */
    get totalObservations(): number;
    /**
     * 获取 scratchpad 中的高重要性发现
     * @returns >}
     */
    getHighPriorityFindings(minImportance?: number): ScratchpadEntry[];
    /** 可序列化输出 */
    toJSON(): {
        plan?: {
            text: string;
            steps: {
                description: string;
                status: string;
                keywords: string[];
            }[];
            createdAtIteration: number;
            lastUpdatedAtIteration: number;
        } | undefined;
        planHistory?: number | undefined;
        rounds: {
            iteration: number;
            thought: string | null;
            actions: RoundAction[];
            observations: RoundObservation[];
            reflection: string | null;
            roundSummary: RoundSummary | null;
            startTime: number;
            endTime: number | null;
        }[];
        stats: {
            totalRounds: number;
            thoughtCount: number;
            totalActions: number;
            totalObservations: number;
            reflectionCount: number;
            totalDurationMs: number;
        };
        scratchpad: {
            finding: string;
            evidence: string;
            importance: number;
            round: number;
        }[];
        compressedObservations: number;
        totalObservations: number;
    };
    /**
     * 从 JSON 恢复 ActiveContext (断点续传)
     * @param json toJSON() 的输出
     */
    static fromJSON(json: ActiveContextJSON): ActiveContext;
    /** 清空 ActiveContext — 释放内存 */
    clear(): void;
    /**
     * 从工具执行结果构建结构化观察元数据
     * 不改变工具结果传给 AI 的内容，只影响推理链记录
     *
     * @param isNew 由 ExplorationTracker.recordToolCall 提供
     * @returns }
     */
    static buildObservationMeta(toolName: string, args: Record<string, unknown>, result: unknown, isNew: boolean): {
        gotNewInfo: boolean;
        resultType: string;
        keyFacts: string[];
        resultSize: number;
    };
}
export default ActiveContext;