autosnippet/dist/lib/agent/strategies.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * Strategies — Agent 执行策略
 *
 * 核心思想: "如何组织工作" 与 "能做什么" 正交。
 *
 * 四种策略:
 *   1. SingleStrategy   — 单次 ReAct 循环 (最简单，用于对话)
 *   2. PipelineStrategy — 顺序多阶段 + 质量门控 (分析→提交)
 *   3. FanOutStrategy   — 并行执行 + 合并 (多维度冷启动)
 *   4. AdaptiveStrategy — 运行时自动选择策略 (智能模式)
 *
 * 这就是为什么 "冷启动" 和 "扫描" 产出一致:
 *   - 冷启动 = FanOut(items=dimensions, itemStrategy=Pipeline(analyze→gate→produce))
 *   - 扫描   = Pipeline(analyze→gate→produce)
 *   - 唯一区别: 作用域 (全项目 vs 单目录) 和并行度
 *
 * 借鉴:
 *   - Anthropic: Prompt Chaining, Parallelization, Orchestrator-Worker
 *   - LangGraph: StateGraph, parallel branches
 *   - AutoGen: Sequential/Parallel teams
 *
 * @module strategies
 */
import { AgentMessage } from './AgentMessage.js';
/** Minimal runtime interface used by strategies (avoids circular import with AgentRuntime) */
interface StrategyRuntime {
    id: string;
    reactLoop(prompt: string, opts?: Record<string, unknown>): Promise<StrategyResult>;
}
/** Strategy execution result */
interface StrategyResult {
    reply: string;
    toolCalls: Array<Record<string, unknown>>;
    tokenUsage: {
        input: number;
        output: number;
    };
    iterations: number;
    [key: string]: unknown;
}
/** Fan-out sub-task item descriptor */
interface FanOutItem {
    id: string;
    label: string;
    tier?: number;
    prompt?: string;
    guide?: string;
}
/** Result of a single fan-out item execution */
interface ItemResult {
    id: string;
    label: string;
    status: 'completed' | 'failed';
    reply: string;
    toolCalls: Array<Record<string, unknown>>;
    tokenUsage: {
        input: number;
        output: number;
    };
    iterations?: number;
    error?: string;
    [key: string]: unknown;
}
/** FanOutStrategy constructor options */
interface FanOutOpts {
    itemStrategy?: Strategy;
    tiers?: Record<string, {
        concurrency: number;
    }>;
    merge?: (results: ItemResult[]) => StrategyResult;
}
/** Options passed to FanOutStrategy.execute */
interface FanOutExecuteOpts {
    items?: FanOutItem[];
    dimension?: FanOutItem;
    [key: string]: unknown;
}
/** AdaptiveStrategy constructor options */
interface AdaptiveStrategies {
    single?: Strategy;
    pipeline?: Strategy;
    fanOut?: Strategy;
}
/** Options for strategy execution with routing context */
interface StrategyExecuteOpts {
    items?: FanOutItem[];
    [key: string]: unknown;
}
/** Strategy 基类 — 定义 Agent 如何组织工作 */
export declare class Strategy {
    get name(): string;
    /**
     * 执行策略
     *
     * @param _runtime AgentRuntime 实例
     * @param _message 输入消息
     * @param [_opts] 策略特定选项
     */
    execute(_runtime: StrategyRuntime, _message: AgentMessage, _opts?: Record<string, unknown>): Promise<StrategyResult>;
}
/**
 * 最简单的策略: 直接运行 ReAct 循环。
 *
 * 适合: 用户对话、简单分析、任何单步骤任务。
 *
 * 等价于 Anthropic 的 "Augmented LLM" 模式。
 */
export declare class SingleStrategy extends Strategy {
    get name(): string;
    execute(runtime: StrategyRuntime, message: AgentMessage, opts?: Record<string, unknown>): Promise<StrategyResult>;
}
/**
 * 并行执行多个子任务，每个子任务使用 itemStrategy (通常是 Pipeline)。
 * 支持分层并发控制 (Tier)。
 *
 * 适合: 冷启动多维度、批量分析
 *
 * 等价于 Anthropic 的 "Parallelization" + "Orchestrator-Worker" 组合。
 *
 * @example
 * new FanOutStrategy({
 *   itemStrategy: new PipelineStrategy({
 *     stages: [
 *       { name: 'analyze', capabilities: ['code_analysis'], budget: { maxIterations: 24 } },
 *       { name: 'gate', gate: { minEvidenceLength: 500, minFileRefs: 3 } },
 *       { name: 'produce', capabilities: ['knowledge_production'], budget: { maxIterations: 24 },
 *         promptTransform: (_, prev) => `将以下分析转为知识候选:\n${prev.analyze.reply}` },
 *     ],
 *   }),
 *   tiers: { 1: { concurrency: 3 }, 2: { concurrency: 2 }, 3: { concurrency: 1 } },
 * })
 */
export declare class FanOutStrategy extends Strategy {
    #private;
    /**
     * @param opts.itemStrategy 每个子任务使用的策略
     * @param [opts.tiers] { 1: { concurrency: 3 }, 2: { concurrency: 2 }, ... }
     * @param [opts.merge] 自定义合并函数 (results[]) => finalResult
     */
    constructor({ itemStrategy, tiers, merge }?: FanOutOpts);
    get name(): string;
    /**
     * @param opts.items 子任务列表
     */
    execute(runtime: StrategyRuntime, message: AgentMessage, opts?: FanOutExecuteOpts): Promise<StrategyResult>;
}
/**
 * 根据输入复杂度自动选择合适的策略。
 *
 * 判断逻辑:
 *   - 简单问答 → SingleStrategy
 *   - 单模块深度分析 → PipelineStrategy
 *   - 多维度/全项目 → FanOutStrategy
 *
 * 等价于 LangGraph 的 Router 节点 + 条件边。
 *
 * @example
 * new AdaptiveStrategy({
 *   single: new SingleStrategy(),
 *   pipeline: new PipelineStrategy({ stages: [...] }),
 *   fanOut: new FanOutStrategy({ itemStrategy: ..., tiers: ... }),
 * })
 */
export declare class AdaptiveStrategy extends Strategy {
    #private;
    constructor(strategies?: AdaptiveStrategies);
    get name(): string;
    execute(runtime: StrategyRuntime, message: AgentMessage, opts?: StrategyExecuteOpts): Promise<StrategyResult>;
}
export declare const StrategyRegistry: {
    _registry: Map<string, typeof Strategy>;
    create(name: string, opts?: Record<string, unknown>): Strategy;
    register(name: string, cls: typeof Strategy): void;
};
declare const _default: {
    Strategy: typeof Strategy;
    SingleStrategy: typeof SingleStrategy;
    FanOutStrategy: typeof FanOutStrategy;
    AdaptiveStrategy: typeof AdaptiveStrategy;
    StrategyRegistry: {
        _registry: Map<string, typeof Strategy>;
        create(name: string, opts?: Record<string, unknown>): Strategy;
        register(name: string, cls: typeof Strategy): void;
    };
};
export default _default;