autosnippet

/** * AgentFactory — 统一 Agent 创建工厂 * * 在新架构中，Factory 的职责是: * - 将 Preset 配置 + DI 依赖 → AgentRuntime 实例 * - 提供 Router (intent → preset → runtime) * - 提供快捷方法 (createChat, createInsight, ...) * * 关键变化 (vs 旧 AgentFactory): * - 不再创建独立 Agent 子类 * - 只创建 AgentRuntime，通过 Preset 配置差异化行为 * - 同一个工厂，同一种 Runtime，不同的配置 * * @module AgentFactory */ import type { AiProvider } from '#external/ai/AiProvider.js'; import { AgentRouter } from './AgentRouter.js'; import { AgentRuntime } from './AgentRuntime.js'; import { ContextWindow } from './context/ContextWindow.js'; import { ExplorationTracker } from './context/ExplorationTracker.js'; import { MemoryCoordinator } from './memory/MemoryCoordinator.js'; import { type Policy } from './policies.js'; import type { ToolRegistry } from './tools/ToolRegistry.js'; /** Constructor options for AgentFactory */ interface AgentFactoryOptions { container: Record<string, unknown>; toolRegistry: ToolRegistry; aiProvider: AiProvider; memoryCoordinator?: MemoryCoordinator | null; projectBriefing?: string | null; projectRoot?: string; } /** Runtime creation overrides (passed to createRuntime and quick methods) */ interface RuntimeOverrides { strategy?: Record<string, unknown>; capabilities?: string[]; policies?: Array<Policy | ((overrides: RuntimeOverrides) => Policy)>; persona?: Record<string, unknown>; memory?: Record<string, unknown>; onProgress?: ((event: Record<string, unknown>) => void) | null; onToolCall?: ((name: string, args: Record<string, unknown>, result: unknown, iteration: number) => void) | null; lang?: string | null; additionalTools?: string[]; strategyOpts?: Record<string, unknown>; strategyContext?: Record<string, unknown>; [key: string]: unknown; } /** Options for buildSystemContext */ interface SystemContextOptions { budget?: Record<string, unknown>; trackerStrategy?: string; label?: string; lang?: string; } /** Options for scanKnowledge */ interface ScanKnowledgeOptions { label?: string; files?: Array<{ name: string; content: string; language?: string; }>; task?: 'extract' | 'summarize'; lang?: string; comprehensive?: boolean; } export declare class AgentFactory { #private; /** * @param opts.container ServiceContainer 实例 * @param [opts.memoryCoordinator] MemoryCoordinator 实例 (注入 Conversation) * @param [opts.projectBriefing] 项目概况文本 * @param [opts.projectRoot] 项目根目录 */ constructor({ container, toolRegistry, aiProvider, memoryCoordinator, projectBriefing, projectRoot, }: AgentFactoryOptions); /** 创建带路由器的自动调度系统 */ createRouter(): AgentRouter; /** * 根据 Preset 名称创建 AgentRuntime * * 这是一切的根基 — 任何 "Agent 类型" 都通过这个方法创建。 * * @param presetName Preset 名称 (chat/insight/remote-exec) * @param [overrides] 覆盖 preset 配置 */ createRuntime(presetName: string, overrides?: RuntimeOverrides): AgentRuntime; /** * 创建 ContextWindow (根据当前 AI Provider 自动解析 token 预算) * @param [opts] */ createContextWindow(opts?: { isSystem?: boolean; }): ContextWindow; /** * 构建系统级多轮执行上下文 — 统一基础设施 * * 抽取 bootstrap orchestrator 中创建 ExplorationTracker / ContextWindow / source 的 * 通用逻辑，供 scanKnowledge 等系统场景共用完整的多轮 Agent 框架。 * * 与 bootstrap orchestrator 保持一致的 MemoryCoordinator 管理模式: * - 创建轻量级 MemoryCoordinator (无 PersistentMemory/SessionStore) * - 通过 MC.createDimensionScope 创建并注册 ActiveContext * - trace 从 MC.getActiveContext 获取 (统一生命周期管理) * - memoryCoordinator 传入 strategyContext，供 reactLoop 每轮 buildDynamicMemoryPrompt * * 与 bootstrap orchestrator 对齐的关键字段: * - activeContext: 与 trace 同一实例 — insightGateEvaluator 通过此字段 * 决定走 buildAnalysisArtifact (完整: findings/evidenceMap/negativeSignals) * 还是 buildAnalysisReport (降级: 仅文本) * - outputType: 'candidate' — 设置 quality_gate 的评判标准 * - dimId: 维度 ID — buildAnalysisArtifact 的 dimensionId 参数 * * bootstrap orchestrator 不使用此方法（它还需要领域特定的 SessionStore / dimContext 等）， * 但引擎层基础设施是一致的。 * * @param [opts.budget] 预算覆盖 (透传给 ExplorationTracker) * @param [opts.trackerStrategy='analyst'] tracker 策略名: 'analyst' | 'producer' | 'bootstrap' * @param [opts.label='default'] 作用域标签 (用于 scopeId 命名 + dimId) * @param [opts.lang] 项目语言 (透传给 sharedState._projectLanguage) * @returns } */ buildSystemContext({ budget, trackerStrategy, label, lang, }?: SystemContextOptions): { contextWindow: ContextWindow; tracker: ExplorationTracker | null; trace: import("./memory/ActiveContext.js").ActiveContext | null; activeContext: import("./memory/ActiveContext.js").ActiveContext | null; memoryCoordinator: MemoryCoordinator; outputType: string; dimId: string; sharedState: { submittedTitles: Set<unknown>; submittedPatterns: Set<unknown>; _projectLanguage: string | null; _dimensionScopeId: string; }; source: string; scopeId: string; }; /** * 获取 AI Provider 信息 (供 orchestrator 等外部使用) * @returns } */ getAiProviderInfo(): { model: string; name: string; }; /** 创建对话 Runtime (Dashboard / 飞书聊天) */ createChat(opts?: RuntimeOverrides): AgentRuntime; /** * 创建洞察 Runtime (深度代码分析 + 知识提取) * @param [opts.dimensions] 维度列表 (传给 FanOutStrategy 的 items) * @param [opts.projectInfo] 项目信息 */ createInsight(opts?: RuntimeOverrides): AgentRuntime; /** 创建飞书对话 Runtime (知识管理，服务端处理) */ createLark(opts?: RuntimeOverrides): AgentRuntime; /** 创建远程执行 Runtime (飞书终端 / 远程操作) */ createRemoteExec(opts?: RuntimeOverrides): AgentRuntime; /** * 统一知识扫描 — 走 insight 管线 (Analyze → QualityGate → Produce → RejectionGate) * * extract 和 summarize 共享工具驱动管线 (collect_scan_recipe)， * 仅 Produce 阶段的 systemPrompt 和预算不同: * - extract: 多文件 target 扫描，24 iter analyze，24 iter produce * - summarize: 单文件/代码片段，12 iter analyze，12 iter produce * * 关系发现请使用单独的 discoverRelations() 方法。 * * @param opts.label 上下文标签（target 名 / 文件名） * @param opts.files 源文件 * @param [opts.task='extract'] 任务类型 * @param [opts.lang] 语言提示 * @param [opts.comprehensive] 深度扫描标志 * @returns task-specific JSON */ scanKnowledge({ label, files, task, lang, comprehensive, }?: ScanKnowledgeOptions): Promise<any>; /** * 知识图谱关系发现 — 独立管线 (Explore → Synthesize) * * 与 scanKnowledge 不同，relations 不需要源文件输入， * 而是通过查询知识库 + 读取源码发现知识条目间的语义关系。 * * @param [opts.batchSize=20] 批次大小提示 * @returns >} */ discoverRelations({ batchSize }?: { batchSize?: number | undefined; }): Promise<any>; /** * AI 翻译 — chat 模式，单轮生成 * * Agent(LLM) 直接翻译文本，无需工具。 * * @param summary 中文摘要 * @param [usageGuide] 中文使用指南 * @returns >} */ translateToEnglish(summary: string, usageGuide?: string): Promise<any>; /** * 通用工具执行 — 直接调用工具 handler * * 纯数据工具直接执行，无需创建 Agent。 * AI 推理由各语义方法的 Agent 自主完成，此方法仅用于纯数据工具。 * * @param toolName 工具名称 * @param params 工具参数 * @returns 工具原始返回值 */ invokeAgent(toolName: string, params: Record<string, unknown>): Promise<unknown>; } export default AgentFactory;