autosnippet
Version:
Extract code patterns into a knowledge base for AI coding assistants
159 lines (158 loc) • 5.15 kB
TypeScript
/**
* ExplorationTracker — 统一的 AI 探索生命周期控制器
*
* 合并了三个原本各自为政的系统:
* 1. PhaseRouter (ContextWindow.js) — 阶段状态机
* 2. 探索进度追踪 (原内联逻辑) — 信息增量检测
* 3. ReasoningLayer 行为控制部分 — 反思/规划/停滞 nudge
*
* 职责（拆分后的编排层）:
* - 阶段状态机: phase 持有 + 转换规则
* - 信号收集: 委托 SignalDetector
* - Nudge 生成: 委托 NudgeGenerator
* - 计划跟踪: 委托 PlanTracker
* - Graceful exit: 管理轮次耗尽后的优雅退出流程
*
* 不拥有的职责:
* - 推理链数据收集 → ReasoningTrace (纯数据，不影响行为)
* - 上下文压缩 → ContextWindow
* - 工具注册与执行 → ToolRegistry
* - 跨对话记忆 → Memory / WorkingMemory
*
* @module ExplorationTracker
*/
import type { SignalBus } from '#infra/signal/SignalBus.js';
import type { ExplorationBudget, ExplorationStrategy, ExplorationTrace, PipelineType } from './exploration/ExplorationStrategies.js';
/** resolve() 选项 */
interface ResolveOptions {
source?: unknown;
strategy?: unknown;
dimensionMeta?: {
outputType?: string;
};
}
/** 预算输入（带默认值） */
interface BudgetInput extends Partial<ExplorationBudget> {
submitToolName?: string;
pipelineType?: PipelineType;
signalBus?: SignalBus | null;
}
export declare class ExplorationTracker {
#private;
/**
* @param strategy 策略配置对象
* @param budget 预算配置 { maxIterations, searchBudget, ... }
*/
constructor(strategy: ExplorationStrategy, budget: BudgetInput);
/**
* 根据调用参数解析应使用的策略
* @param opts AgentRuntime execute 的选项
* @param budget 预算配置
* @returns User 模式返回 null
*/
static resolve(opts: ResolveOptions, budget: BudgetInput): ExplorationTracker | null;
/** 每轮迭代开始时调用 — 递增计数 */
tick(): void;
/** 撤销 tick（AI 调用失败或空响应时，不计入迭代） */
rollbackTick(): void;
/** 提交工具名 */
get submitToolName(): string;
/** 管线类型标识 */
get pipelineType(): PipelineType;
/** 是否应退出主循环 */
shouldExit(): boolean;
/**
* 获取本轮的 Nudge（每轮最多一条）
* @param trace 推理链
* @returns |null}
*/
getNudge(trace: ExplorationTrace | null): {
type: string;
text: string;
} | null;
/** 获取当前阶段的上下文状态行（注入 systemPrompt 尾部） */
getPhaseContext(): string;
/** 获取当前阶段的 toolChoice */
getToolChoice(): "none" | "auto" | "required";
/**
* 记录一次工具调用结果，更新内部指标
*
* @returns }
*/
recordToolCall(toolName: string, args: Record<string, unknown>, result: unknown): {
isNew: boolean;
};
/**
* 结束本轮迭代 — 更新轮次级指标 + 检查阶段转换
*
* @returns |null} 阶段转换 nudge
*/
endRound({ hasNewInfo, submitCount, toolNames, skipped, }?: {
hasNewInfo?: boolean | undefined;
submitCount?: number | undefined;
toolNames?: string[] | undefined;
skipped?: boolean | undefined;
}): {
type: string;
text: string;
} | null;
/**
* 处理 AI 返回纯文本响应（无工具调用）
* @returns }
*/
onTextResponse(): {
isFinalAnswer: boolean;
needsDigestNudge: boolean;
shouldContinue: boolean;
nudge: string | null;
};
/** 记录被截断的工具调用数量 */
recordTruncatedCalls(count: number): void;
get isGracefulExit(): boolean;
get isHardExit(): boolean;
get phase(): string;
get iteration(): number;
get totalSubmits(): number;
get strategyName(): string;
getMetrics(): {
iteration: number;
phase: string;
phaseRounds: number;
submitCount: number;
uniqueFiles: number;
uniquePatterns: number;
uniqueQueries: number;
totalToolCalls: number;
roundsSinceNewInfo: number;
};
get metrics(): {
iteration: number;
phase: string;
phaseRounds: number;
submitCount: number;
uniqueFiles: number;
uniquePatterns: number;
uniqueQueries: number;
totalToolCalls: number;
roundsSinceNewInfo: number;
};
getPlanProgress(): {
coveredSteps: number;
totalSteps: number;
deviationScore: number;
unplannedActions: number;
lastReplanIteration: number | null;
consecutiveOffPlan: number;
};
/** 更新计划进度 — 委托 PlanTracker */
updatePlanProgress(trace: ExplorationTrace | null): void;
/**
* 推理质量评分 — 委托 PlanTracker
* @returns }
*/
getQualityMetrics(trace: ExplorationTrace | null): {
score: number;
breakdown: Record<string, number>;
};
}
export default ExplorationTracker;