autosnippet 3.2.7 → 3.2.9

package/lib/platform/ios/xcode/XcodeWriteUtils.js

@@ -31,7 +31,7 @@ export function withAutoSnippetNote(importLine) {
 }
 
 /**
- * 将 SpmService.ensureDependency 返回值映射为三种动作：
+ * 将 SpmHelper.ensureDependency 返回值映射为三种动作：
  *   continue — 依赖已存在
  *   block    — 循环/反向依赖，禁止插入
  *   review   — 依赖缺失但可添加，需用户确认

package/lib/service/agent/AgentEventBus.js

@@ -0,0 +1,207 @@
+/**
+ * AgentEventBus — Agent 间事件通信总线
+ *
+ * 借鉴 AutoGen Core Event-Driven 架构 + RxJS Observable 模式:
+ *   - Agent 间松耦合通信（publish/subscribe）
+ *   - 支持同步和异步事件处理
+ *   - 内置事件过滤、优先级、TTL
+ *   - 支持 request/reply 模式（Agent 间 RPC）
+ *
+ * @module AgentEventBus
+ */
+
+import { EventEmitter } from 'node:events';
+import Logger from '../../infrastructure/logging/Logger.js';
+
+/**
+ * 标准事件类型
+ */
+export const AgentEvents = Object.freeze({
+  // ── 生命周期 ──
+  AGENT_CREATED: 'agent:created',
+  AGENT_STARTED: 'agent:started',
+  AGENT_COMPLETED: 'agent:completed',
+  AGENT_FAILED: 'agent:failed',
+  AGENT_ABORTED: 'agent:aborted',
+
+  // ── 执行 ──
+  TOOL_CALL_START: 'tool:call:start',
+  TOOL_CALL_END: 'tool:call:end',
+  LLM_CALL_START: 'llm:call:start',
+  LLM_CALL_END: 'llm:call:end',
+  STEP_COMPLETED: 'step:completed',
+
+  // ── Agent 间交互 ──
+  HANDOFF_REQUEST: 'handoff:request',
+  HANDOFF_ACCEPT: 'handoff:accept',
+  HANDOFF_RESULT: 'handoff:result',
+
+  // ── 进度 ──
+  PROGRESS: 'progress',
+  THINKING: 'thinking',
+  STREAM_DELTA: 'stream:delta',
+
+  // ── 外部触发 ──
+  USER_INPUT: 'user:input',
+  LARK_MESSAGE: 'lark:message',
+  SCAN_REQUEST: 'scan:request',
+});
+
+/**
+ * @typedef {Object} AgentEvent
+ * @property {string} type — 事件类型
+ * @property {string} source — 发送者 agentId
+ * @property {string} [target] — 目标 agentId（广播时为 null）
+ * @property {Object} payload — 事件数据
+ * @property {number} timestamp — 事件时间戳
+ * @property {string} [correlationId] — 关联 ID（用于 request/reply）
+ */
+
+export class AgentEventBus extends EventEmitter {
+  /** @type {AgentEventBus|null} */
+  static #instance = null;
+  #logger;
+  /** @type {Map<string, Function[]>} topic → handlers */
+  #subscriptions = new Map();
+  /** @type {Map<string, {resolve: Function, reject: Function, timer: NodeJS.Timeout}>} */
+  #pendingReplies = new Map();
+  /** @type {number} 事件计数 */
+  #eventCount = 0;
+
+  constructor() {
+    super();
+    this.setMaxListeners(100);
+    this.#logger = Logger.getInstance();
+  }
+
+  /**
+   * 获取全局单例
+   * @returns {AgentEventBus}
+   */
+  static getInstance() {
+    if (!AgentEventBus.#instance) {
+      AgentEventBus.#instance = new AgentEventBus();
+    }
+    return AgentEventBus.#instance;
+  }
+
+  /**
+   * 重置单例（测试用）
+   */
+  static resetInstance() {
+    if (AgentEventBus.#instance) {
+      AgentEventBus.#instance.removeAllListeners();
+      AgentEventBus.#instance.#subscriptions.clear();
+      AgentEventBus.#instance.#pendingReplies.clear();
+    }
+    AgentEventBus.#instance = null;
+  }
+
+  // ─── 发布 ────────────────────────────────
+
+  /**
+   * 发布事件（广播）
+   * @param {string} type — 事件类型
+   * @param {Object} payload — 事件数据
+   * @param {Object} [opts]
+   * @param {string} [opts.source] — 发送者 agentId
+   * @param {string} [opts.target] — 目标 agentId
+   * @param {string} [opts.correlationId] — 关联 ID
+   */
+  publish(type, payload = {}, opts = {}) {
+    this.#eventCount++;
+    const event = {
+      type,
+      source: opts.source || 'system',
+      target: opts.target || null,
+      payload,
+      timestamp: Date.now(),
+      correlationId: opts.correlationId || null,
+    };
+
+    // 发射到 EventEmitter（通用监听）
+    this.emit(type, event);
+    this.emit('*', event); // 全局监听
+
+    // 发射到 topic 订阅者
+    const handlers = this.#subscriptions.get(type) || [];
+    for (const handler of handlers) {
+      try {
+        handler(event);
+      } catch (err) {
+        this.#logger.warn(`[AgentEventBus] Handler error on ${type}: ${err.message}`);
+      }
+    }
+
+    // 检查是否有 pending reply
+    if (opts.correlationId && this.#pendingReplies.has(opts.correlationId)) {
+      const pending = this.#pendingReplies.get(opts.correlationId);
+      clearTimeout(pending.timer);
+      this.#pendingReplies.delete(opts.correlationId);
+      pending.resolve(event);
+    }
+  }
+
+  /**
+   * 订阅事件
+   * @param {string} type — 事件类型
+   * @param {Function} handler — 处理函数 (event) => void
+   * @returns {Function} 取消订阅函数
+   */
+  subscribe(type, handler) {
+    if (!this.#subscriptions.has(type)) {
+      this.#subscriptions.set(type, []);
+    }
+    this.#subscriptions.get(type).push(handler);
+
+    return () => {
+      const handlers = this.#subscriptions.get(type);
+      if (handlers) {
+        const idx = handlers.indexOf(handler);
+        if (idx >= 0) handlers.splice(idx, 1);
+      }
+    };
+  }
+
+  /**
+   * Request/Reply 模式 — 发送请求并等待响应
+   * @param {string} requestType — 请求事件类型
+   * @param {Object} payload — 请求数据
+   * @param {Object} [opts]
+   * @param {number} [opts.timeout=30000] — 超时毫秒
+   * @param {string} [opts.source] — 发送者
+   * @returns {Promise<AgentEvent>} 响应事件
+   */
+  async request(requestType, payload = {}, opts = {}) {
+    const correlationId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const timeout = opts.timeout || 30_000;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pendingReplies.delete(correlationId);
+        reject(new Error(`AgentEventBus request timeout: ${requestType} (${timeout}ms)`));
+      }, timeout);
+
+      this.#pendingReplies.set(correlationId, { resolve, reject, timer });
+
+      this.publish(requestType, payload, {
+        source: opts.source,
+        correlationId,
+      });
+    });
+  }
+
+  /**
+   * 获取事件统计
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      totalEvents: this.#eventCount,
+      subscriptionTopics: this.#subscriptions.size,
+      pendingReplies: this.#pendingReplies.size,
+    };
+  }
+}
+
+export default AgentEventBus;

package/lib/service/agent/AgentFactory.js

@@ -0,0 +1,490 @@
+/**
+ * AgentFactory — 统一 Agent 创建工厂
+ *
+ * 在新架构中，Factory 的职责是:
+ *   - 将 Preset 配置 + DI 依赖 → AgentRuntime 实例
+ *   - 提供 Router (intent → preset → runtime)
+ *   - 提供快捷方法 (createChat, createInsight, ...)
+ *
+ * 关键变化 (vs 旧 AgentFactory):
+ *   - 不再创建独立 Agent 子类
+ *   - 只创建 AgentRuntime，通过 Preset 配置差异化行为
+ *   - 同一个工厂，同一种 Runtime，不同的配置
+ *
+ * @module AgentFactory
+ */
+
+import Logger from '../../infrastructure/logging/Logger.js';
+import { AgentMessage } from './AgentMessage.js';
+import { AgentRouter, PresetName } from './AgentRouter.js';
+import { AgentRuntime } from './AgentRuntime.js';
+import { CapabilityRegistry } from './capabilities.js';
+import { BudgetPolicy, PolicyEngine } from './policies.js';
+import { getPreset, resolveStrategy } from './presets.js';
+import { ContextWindow } from './context/ContextWindow.js';
+import { ExplorationTracker } from './context/ExplorationTracker.js';
+import { ANALYST_SYSTEM_PROMPT } from './domain/insight-analyst.js';
+import { SCAN_TASK_CONFIGS } from './domain/scan-prompts.js';
+
+export class AgentFactory {
+  #container;
+  #toolRegistry;
+  #aiProvider;
+  #logger;
+  /** @type {AgentRouter|null} */
+  #router = null;
+  /** @type {Object} 共享的 Capability 实例缓存 (如 MemoryCoordinator) */
+  #sharedOpts;
+
+  /**
+   * @param {Object} opts
+   * @param {Object} opts.container — ServiceContainer 实例
+   * @param {import('./tools/ToolRegistry.js').ToolRegistry} opts.toolRegistry
+   * @param {import('../../external/ai/AiProvider.js').AiProvider} opts.aiProvider
+   * @param {Object} [opts.memoryCoordinator] — MemoryCoordinator 实例 (注入 Conversation)
+   * @param {string} [opts.projectBriefing] — 项目概况文本
+   * @param {string} [opts.projectRoot] — 项目根目录
+   */
+  constructor({ container, toolRegistry, aiProvider, memoryCoordinator, projectBriefing, projectRoot }) {
+    this.#container = container;
+    this.#toolRegistry = toolRegistry;
+    this.#aiProvider = aiProvider;
+    this.#logger = Logger.getInstance();
+    this.#sharedOpts = {
+      memoryCoordinator: memoryCoordinator || null,
+      projectBriefing: projectBriefing || null,
+      projectRoot: projectRoot || process.cwd(),
+    };
+  }
+
+  // ─── Router ──────────────────────────────────
+
+  /**
+   * 创建带路由器的自动调度系统
+   * @returns {AgentRouter}
+   */
+  createRouter() {
+    if (this.#router) return this.#router;
+
+    const router = new AgentRouter();
+    router.setAiProvider(this.#aiProvider);
+    router.setExecutor((presetName, message, opts) => {
+      const runtime = this.createRuntime(presetName, opts);
+      return runtime.execute(message, opts.strategyOpts || opts);
+    });
+
+    this.#router = router;
+    this.#logger.info('[AgentFactory] Router created');
+    return router;
+  }
+
+  // ─── 核心创建方法 ─────────────────────────────
+
+  /**
+   * 根据 Preset 名称创建 AgentRuntime
+   *
+   * 这是一切的根基 — 任何 "Agent 类型" 都通过这个方法创建。
+   *
+   * @param {string} presetName — Preset 名称 (chat/insight/remote-exec)
+   * @param {Object} [overrides] — 覆盖 preset 配置
+   * @returns {AgentRuntime}
+   */
+  createRuntime(presetName, overrides = {}) {
+    const preset = getPreset(presetName, overrides);
+
+    // 实例化 Capabilities
+    const capabilities = preset.capabilities.map(name => {
+      const opts = this.#getCapabilityOpts(name);
+      return CapabilityRegistry.create(name, opts);
+    });
+
+    // 实例化 Policies
+    const policyEngine = new PolicyEngine(preset.policies || []);
+
+    return new AgentRuntime({
+      presetName,
+      aiProvider: this.#aiProvider,
+      toolRegistry: this.#toolRegistry,
+      container: this.#container,
+      capabilities,
+      strategy: preset.strategyInstance,
+      policies: policyEngine,
+      persona: preset.persona,
+      memory: preset.memory,
+      onProgress: overrides.onProgress || null,
+      onToolCall: overrides.onToolCall || null,
+      lang: overrides.lang || null,
+      additionalTools: overrides.additionalTools || [],
+      projectRoot: this.#sharedOpts.projectRoot,
+    });
+  }
+
+  // ─── 快捷方法 (语义化) ─────────────────────
+
+  /**
+   * 创建 ContextWindow (根据当前 AI Provider 自动解析 token 预算)
+   * @param {{ isSystem?: boolean }} [opts]
+   * @returns {ContextWindow}
+   */
+  createContextWindow(opts = {}) {
+    const modelName = this.#aiProvider?.model || '';
+    const tokenBudget = ContextWindow.resolveTokenBudget(modelName, opts);
+    return new ContextWindow(tokenBudget);
+  }
+
+  /**
+   * 构建系统级多轮执行上下文 — 统一基础设施
+   *
+   * 抽取 bootstrap orchestrator 中创建 ExplorationTracker / ContextWindow / source 的
+   * 通用逻辑，供 scanKnowledge 等系统场景共用完整的多轮 Agent 框架。
+   *
+   * bootstrap orchestrator 不使用此方法（它还需要领域特定的 MemoryCoordinator / dimContext 等），
+   * 但引擎层基础设施是一致的。
+   *
+   * @param {Object} [opts]
+   * @param {Object} [opts.budget] — 预算覆盖 (透传给 ExplorationTracker)
+   * @param {string} [opts.trackerStrategy='analyst'] — tracker 策略名: 'analyst' | 'producer' | 'bootstrap'
+   * @returns {{ contextWindow: ContextWindow, tracker: ExplorationTracker, sharedState: Object, source: string }}
+   */
+  buildSystemContext({ budget, trackerStrategy = 'analyst' } = {}) {
+    return {
+      contextWindow: this.createContextWindow({ isSystem: true }),
+      tracker: ExplorationTracker.resolve(
+        { source: 'system', strategy: trackerStrategy },
+        budget || {},
+      ),
+      sharedState: {
+        submittedTitles: new Set(),
+        submittedPatterns: new Set(),
+      },
+      source: 'system',
+    };
+  }
+
+  /**
+   * 获取 AI Provider 信息 (供 orchestrator 等外部使用)
+   * @returns {{ model: string, name: string }}
+   */
+  getAiProviderInfo() {
+    return {
+      model: this.#aiProvider?.model || 'unknown',
+      name: this.#aiProvider?.name || 'unknown',
+    };
+  }
+
+  /**
+   * 创建对话 Runtime (Dashboard / 飞书聊天)
+   * @param {Object} [opts]
+   */
+  createChat(opts = {}) {
+    return this.createRuntime(PresetName.CHAT, opts);
+  }
+
+  /**
+   * 创建洞察 Runtime (深度代码分析 + 知识提取)
+   * @param {Object} [opts]
+   * @param {Array} [opts.dimensions] — 维度列表 (传给 FanOutStrategy 的 items)
+   * @param {Object} [opts.projectInfo] — 项目信息
+   */
+  createInsight(opts = {}) {
+    return this.createRuntime(PresetName.INSIGHT, opts);
+  }
+
+  /**
+   * 创建飞书对话 Runtime (知识管理，服务端处理)
+   * @param {Object} [opts]
+   */
+  createLark(opts = {}) {
+    return this.createRuntime(PresetName.LARK, opts);
+  }
+
+  /**
+   * 创建远程执行 Runtime (飞书终端 / 远程操作)
+   * @param {Object} [opts]
+   */
+  createRemoteExec(opts = {}) {
+    return this.createRuntime(PresetName.REMOTE_EXEC, opts);
+  }
+
+  // ─── 领域语义方法 (意图驱动, Agent 直接完成 AI 推理) ─────
+
+  /**
+   * 统一知识扫描 — 走 insight 管线 (Analyze → QualityGate → Produce)
+   *
+   * 三种任务模式共享同一管线，仅 Produce 阶段的 systemPrompt 不同。
+   * 替代: extractRecipes + summarizeCode + discoverRelations
+   *
+   * @param {Object} opts
+   * @param {string} opts.label              — 上下文标签（target 名 / 文件名）
+   * @param {Array<{name, content, language?}>} opts.files — 源文件
+   * @param {'extract'|'summarize'|'relations'} [opts.task='extract'] — 任务类型
+   * @param {string} [opts.lang]             — 语言提示
+   * @param {boolean} [opts.comprehensive]   — 深度扫描标志
+   * @returns {Promise<Object>}              — task-specific JSON
+   */
+  async scanKnowledge({ label, files, task = 'extract', lang, comprehensive } = {}) {
+    const taskConfig = SCAN_TASK_CONFIGS[task];
+    if (!taskConfig) {
+      throw new Error(`Unknown scanKnowledge task: "${task}". Available: ${Object.keys(SCAN_TASK_CONFIGS).join(', ')}`);
+    }
+    const { producePrompt, fallback } = taskConfig;
+
+    // relations task 需要知识查询工具
+    const caps = task === 'relations'
+      ? ['code_analysis', 'knowledge_production']
+      : ['code_analysis'];
+
+    // produce 阶段: extract 使用 scan_production（工具驱动，与冷启动一致），
+    // summarize/relations 保持纯文本输出
+    const produceCaps = task === 'extract'
+      ? ['scan_production']
+      : [];
+
+    // ── Pipeline 配置 (与冷启动对齐: 24 轮标准) ──
+    const analyzeMaxIter = 24;
+    const stages = [
+      {
+        name: 'analyze',
+        capabilities: caps,
+        budget: { maxIterations: analyzeMaxIter, maxTokens: 8192, temperature: 0.3 },
+        systemPrompt: ANALYST_SYSTEM_PROMPT,
+      },
+      {
+        name: 'produce',
+        capabilities: produceCaps,
+        budget: { maxIterations: 24, temperature: 0.2 },
+        systemPrompt: producePrompt,
+        promptTransform: (_input, prev) => {
+          const analysis = prev.analyze?.reply || '';
+          if (analysis.length >= 200) {
+            return `将以下代码分析转化为结构化输出。\n\n## 代码分析\n${analysis}`;
+          }
+          // Fallback: analyze reply 不足时直接提供源代码
+          const fileCtx = (files || []).slice(0, 15).map(f => {
+            const body = f.content.length > 1200
+              ? f.content.slice(0, 1200) + '\n// ... (truncated)'
+              : f.content;
+            return `### ${f.relativePath}\n\`\`\`\n${body}\n\`\`\``;
+          }).join('\n\n');
+          const preamble = analysis
+            ? `## 部分分析\n${analysis}\n\n`
+            : '';
+          return `${preamble}分析以下 ${files?.length || 0} 个源文件，提取知识 Recipe。\n\n${fileCtx}`;
+        },
+      },
+    ];
+
+    // ── 创建 Runtime — 使用 insight preset + 对齐 policies ──
+    // policies override: 让 Runtime 级 BudgetPolicy 与 stage budget 对齐
+    // (避免 insight preset 的 maxIterations:24 与 stage 的 10 冲突)
+    const runtime = this.createRuntime(PresetName.INSIGHT, {
+      strategy: { type: 'pipeline', stages },
+      capabilities: caps,
+      policies: [
+        new BudgetPolicy({
+          maxIterations: 30, // 24 stage budget + 6 tracker grace (SUMMARIZE 2轮 + 硬上限 buffer)
+          maxTokens: 8192,
+          temperature: 0.3,
+          timeoutMs: 600_000,
+        }),
+      ],
+      memory: { enabled: false },
+      lang,
+    });
+    if (files?.length) {
+      runtime.setFileCache(files);
+    }
+
+    // ── 完整的系统级多轮基础设施 ──
+    // ExplorationTracker (analyst 策略) 提供:
+    //   - 四阶段管理: SCAN → EXPLORE → VERIFY → SUMMARIZE
+    //   - Nudge: budget_warning / convergence / reflection / force_exit
+    //   - 阶段 toolChoice: SUMMARIZE='none' 强制 LLM 输出文本
+    //   - Graceful exit: 终结阶段 2 轮 grace + 硬上限兜底
+    // ContextWindow 提供:
+    //   - 自动三级递进上下文压缩
+    // source:'system' 提供:
+    //   - 空响应自动重试 (2 次)
+    //   - finalize 强制摘要兜底
+    const systemCtx = this.buildSystemContext({
+      budget: { maxIterations: analyzeMaxIter },
+      trackerStrategy: 'analyst',
+    });
+
+    // ── 执行 ──
+    const message = AgentMessage.internal(
+      `分析 "${label}" 的 ${files?.length || 0} 个源文件。${comprehensive ? '请进行深度分析。' : ''}`,
+    );
+    const result = await runtime.execute(message, { strategyContext: systemCtx });
+
+    // ── 提取结果 ──
+    if (task === 'extract') {
+      // 工具驱动模式: 从 tool calls 中提取 collected recipes (与冷启动相同的提取方式)
+      const allToolCalls = result.toolCalls || [];
+      const recipes = allToolCalls
+        .filter(tc => (tc.tool || tc.name) === 'collect_scan_recipe')
+        .map(tc => {
+          // 优先从 handler 返回的 recipe 对象取，回退到参数
+          const res = tc.result;
+          if (res && typeof res === 'object' && res.status === 'collected' && res.recipe) {
+            return res.recipe;
+          }
+          return null;
+        })
+        .filter(Boolean);
+
+      if (recipes.length > 0) {
+        return { targetName: label, extracted: recipes.length, recipes };
+      }
+
+      // Fallback: 工具未被调用时，尝试从文本解析
+      const produceReply = result.phases?.produce?.reply || result.reply;
+      return this.#parseJsonResponse(produceReply, fallback(label));
+    }
+
+    // summarize / relations: 纯文本 JSON 输出
+    const produceReply = result.phases?.produce?.reply || result.reply;
+    return this.#parseJsonResponse(produceReply, fallback(label));
+  }
+
+  /**
+   * AI 翻译 — chat 模式，单轮生成
+   *
+   * Agent(LLM) 直接翻译文本，无需工具。
+   *
+   * @param {string} summary — 中文摘要
+   * @param {string} [usageGuide] — 中文使用指南
+   * @returns {Promise<{ summaryEn?: string, usageGuideEn?: string, error?: string }>}
+   */
+  async translateToEnglish(summary, usageGuide) {
+    if (!summary && !usageGuide) {
+      return { summaryEn: '', usageGuideEn: '' };
+    }
+
+    const runtime = this.createChat({
+      policies: [
+        new BudgetPolicy({ maxIterations: 1, maxTokens: 4096, temperature: 0.2, timeoutMs: 60_000 }),
+      ],
+      persona: {
+        description: [
+          '你是技术文档翻译专家。将中文技术内容翻译为地道的英文。保持技术术语不变。',
+          '',
+          '## 输出格式（必须是纯 JSON，不包含任何其他文字）',
+          '{ "summaryEn": "...", "usageGuideEn": "..." }',
+        ].join('\n'),
+      },
+      memory: { enabled: false },
+    });
+
+    const message = AgentMessage.internal(
+      `翻译以下内容为英文，输出纯 JSON：\nsummary: ${summary || '(空)'}\nusageGuide: ${usageGuide || '(空)'}`,
+    );
+
+    const result = await runtime.execute(message);
+    return this.#parseJsonResponse(result.reply, {
+      summaryEn: summary || '',
+      usageGuideEn: usageGuide || '',
+    });
+  }
+
+  /**
+   * 冷启动知识库 — 直接调用 handler（纯启发式，不需要 LLM）
+   *
+   * bootstrap_knowledge 是纯启发式工具：SPM Target 扫描 → 依赖图谱 → Guard 审计 →
+   * Candidate 创建，全程无 AI 推理。直接调用 handler 即可，无需创建 Agent。
+   *
+   * @param {{ maxFiles?: number, skipGuard?: boolean, contentMaxLines?: number, loadSkills?: boolean, skipAsyncFill?: boolean }} [opts]
+   * @returns {Promise<Object>}
+   */
+  async bootstrapKnowledge(opts = {}) {
+    const { bootstrapKnowledge } = await import('../../external/mcp/handlers/bootstrap-internal.js');
+    const result = await bootstrapKnowledge(
+      { container: this.#container, logger: this.#logger },
+      {
+        maxFiles: opts.maxFiles || 500,
+        skipGuard: opts.skipGuard || false,
+        contentMaxLines: opts.contentMaxLines || 120,
+        loadSkills: opts.loadSkills ?? true,
+        skipAsyncFill: opts.skipAsyncFill || false,
+      },
+    );
+    const parsed = typeof result === 'string' ? JSON.parse(result) : result;
+    return parsed?.data || parsed;
+  }
+
+  /**
+   * 通用工具执行 — 直接调用工具 handler
+   *
+   * 纯数据工具直接执行，无需创建 Agent。
+   * AI 推理由各语义方法的 Agent 自主完成，此方法仅用于纯数据工具。
+   *
+   * @param {string} toolName — 工具名称
+   * @param {Object} params — 工具参数
+   * @returns {Promise<*>} 工具原始返回值
+   */
+  async invokeAgent(toolName, params) {
+    return this.#toolRegistry.execute(toolName, params, this.#makeToolContext());
+  }
+
+  // ─── 私有方法 ────────────────────────────────
+
+  /**
+   * 解析 Agent 响应中的 JSON（支持 markdown 代码块包装）
+   * @param {string} text — Agent 响应文本
+   * @param {Object} fallback — 解析失败时的默认值
+   * @returns {Object}
+   */
+  #parseJsonResponse(text, fallback) {
+    if (!text) return fallback;
+    try {
+      // 尝试从 markdown 代码块中提取 JSON
+      const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+      if (codeBlockMatch) {
+        return JSON.parse(codeBlockMatch[1].trim());
+      }
+      // 尝试直接提取 JSON 对象
+      const objMatch = text.match(/(\{[\s\S]*\})/);
+      if (objMatch) {
+        return JSON.parse(objMatch[1].trim());
+      }
+      return JSON.parse(text.trim());
+    } catch {
+      this.#logger.warn('[AgentFactory] Failed to parse JSON from Agent response');
+      return fallback;
+    }
+  }
+
+  /**
+   * 构建工具 handler 执行所需的上下文对象
+   * @returns {Object}
+   */
+  #makeToolContext() {
+    return {
+      aiProvider: this.#aiProvider,
+      container: this.#container,
+      logger: this.#logger,
+      projectRoot: this.#sharedOpts.projectRoot,
+    };
+  }
+
+  /**
+   * 获取 Capability 实例化时需要的依赖注入参数
+   */
+  #getCapabilityOpts(capabilityName) {
+    switch (capabilityName) {
+      case 'conversation':
+        return {
+          memoryCoordinator: this.#sharedOpts.memoryCoordinator,
+          projectBriefing: this.#sharedOpts.projectBriefing,
+        };
+      case 'system_interaction':
+        return {
+          projectRoot: this.#sharedOpts.projectRoot,
+        };
+      default:
+        return {};
+    }
+  }
+}
+
+export default AgentFactory;