foliko 1.0.75 → 1.0.76

package/src/core/agent.js

@@ -1,892 +1,892 @@
-/**
- * Agent 类
- * 负责对话和推理
- */
-
-const { EventEmitter } = require('../utils/event-emitter');
-const { AgentChatHandler } = require('./agent-chat');
-const { SystemPromptBuilder } = require('./system-prompt-builder');
-const os = require('os');
-
-class Agent extends EventEmitter {
-  /**
-   * @param {Framework} framework - 框架实例
-   * @param {Object} config - 配置
-   * @param {string} [config.name] - Agent 名称
-   * @param {string} [config.systemPrompt] - 系统提示
-   * @param {string} [config.sharedPrompt] - 共享提示模板，支持 {{VAR}} 占位符
-   * @param {Object} [config.metadata] - 元数据，注入到 sharedPrompt
-   * @param {boolean} [config.enableToolRouting=true] - 是否启用工具路由
-   */
-  constructor(framework, config = {}) {
-    super();
-
-    this.framework = framework;
-    this.config = config;
-
-    this.name = config.name || 'Agent';
-    this.model = config.model || 'deepseek-chat';
-    this.apiKey = config.apiKey;
-    this.baseURL = config.baseURL;
-    this.provider = config.provider || 'deepseek';
-    this.providerOptions = config.providerOptions || {};
-    this.providerOptions.maxOutputTokens = 8192;
-    this.providerOptions.temperature = 0.3; // 降低 temperature 减少生成错误 JSON 的概率
-    // 原始 system prompt
-    this._originalPrompt =
-      config.systemPrompt ||
-      '你是一个智能助手。当用户提出问题或任务时，你会主动分析需求，选择合适的工具来获取信息或执行操作。你善于将复杂任务拆解为多个步骤，通过工具协作完成。';
-
-    // 共享提示模板
-    this._sharedPrompt = config.sharedPrompt || '';
-
-    // 元数据
-    const metadata = config.metadata || {};
-    this._metadata = new Map(Object.entries(metadata));
-
-    this._chatHandler = null;
-    this._tools = new Map();
-    this._status = 'idle';
-
-    // 子Agent管理
-    this._subAgents = new Map();
-
-    // 消息队列（用于 pushMessage）
-    this._messageQueue = [];
-    this._isProcessingQueue = false;
-
-    // System prompt 构建器
-    this._systemPromptBuilder = new SystemPromptBuilder();
-    this._registerDefaultPromptParts();
-
-    // 处理后的 system prompt (带上下文)
-    this.systemPrompt = this._buildSystemPrompt();
-
-    // 初始化聊天处理器
-    this._initChatHandler();
-  }
-
-  /**
-   * 注册默认的系统提示词部分
-   * @private
-   */
-  _registerDefaultPromptParts() {
-    // 1. 原始 system prompt (优先级 100)
-    this._systemPromptBuilder.register('original-prompt', 100, () => this._originalPrompt);
-
-    // 2. 共享提示模板 (优先级 200)
-    this._systemPromptBuilder.register('shared-prompt', 200, () => {
-      if (this._sharedPrompt) {
-        return this._replacePlaceholders(this._sharedPrompt);
-      }
-      return null;
-    });
-
-    // 3. 元数据 (优先级 300)
-    this._systemPromptBuilder.register('metadata', 300, () => {
-      if (this._metadata.size === 0) {
-        return null;
-      }
-      const metaParts = ['【元数据】'];
-      for (const [key, value] of this._metadata) {
-        if (typeof value === 'object') {
-          metaParts.push(`- ${key}: ${JSON.stringify(value)}`);
-        } else {
-          metaParts.push(`- ${key}: ${value}`);
-        }
-      }
-      return metaParts.join('\n');
-    });
-
-    // 4. 工具列表 (优先级 400)
-    this._systemPromptBuilder.register('tools', 400, () => this._buildToolsDescription());
-
-    // 5. 技能列表 (优先级 500)
-    this._systemPromptBuilder.register('skills', 500, () => this._buildSkillsDescription());
-
-    // 6. 子Agent列表 (优先级 600)
-    this._systemPromptBuilder.register('subagents', 600, () => this._buildSubAgentsDescription());
-
-    // 7. 系统能力 (优先级 700)
-    this._systemPromptBuilder.register('capabilities', 700, () => this._buildCapabilitiesDescription());
-
-    // 8. 工具调用核心规则 (优先级 1000)
-    this._systemPromptBuilder.register('tool-core-rules', 1000, () => this._getToolCoreRules());
-  }
-
-  /**
-   * 获取元数据值
-   */
-  _getMetadataValue(key) {
-    // 优先从 metadata 获取
-    if (this._metadata.has(key)) {
-      return this._metadata.get(key);
-    }
-
-    // 内置变量
-    switch (key) {
-      case 'WORK_DIR':
-      case 'CWD':
-        return process.cwd();
-      case 'HOME_DIR':
-        return os.homedir();
-      case 'HOST_NAME':
-        return os.hostname();
-      case 'PLATFORM':
-        return process.platform;
-      case 'TIME':
-        return new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
-      case 'DATE':
-        return new Date().toISOString().split('T')[0];
-      default:
-        return `{{${key}}}`;
-    }
-  }
-
-  /**
-   * 替换 sharedPrompt 中的占位符
-   */
-  _replacePlaceholders(template) {
-    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
-      return this._getMetadataValue(key);
-    });
-  }
-
-  /**
-   * 构建工具描述
-   */
-  _buildToolsDescription() {
-    if (this._tools.size === 0) {
-      return '';
-    }
-
-    // 需要排除的子Agent相关工具（它们通过专门的子Agent部分提供）
-    // const excludedTools = new Set(['subagent_call', 'subagent_list', 'subagent_reload']);
-
-    let desc = '【可用工具】\n';
-    for (const [name, tool] of this._tools) {
-      // 跳过没有描述的工具（对LLM无帮助）
-      if (!tool.description) continue;
-      // // 跳过子Agent相关工具（通过专门的子Agent部分提供）
-      // if (excludedTools.has(name)) continue;
-      // // 跳过子Agent委托工具（通过专门的子Agent部分提供）
-      // if (this._subAgents.has(name)) continue;
-      desc += `- ${name}: ${tool.description}\n`;
-    }
-    return desc.trim();
-  }
-
-  /**
-   * 构建技能描述
-   */
-  _buildSkillsDescription() {
-    const skillManager = this.framework.pluginManager.get('skill-manager');
-    if (!skillManager) {
-      return '';
-    }
-
-    const skills = skillManager.getAllSkills();
-    if (!skills || skills.length === 0) {
-      return '';
-    }
-
-    let desc = '【可用技能】\n';
-    for (const skill of skills) {
-      const name = skill.metadata?.name || skill.name || 'unknown';
-      const descText = skill.metadata?.description || '';
-      desc += `- ${name}: ${descText}\n`;
-    }
-    desc +=
-      '\n重要：当需要开发插件、执行专业任务时，必须先使用 loadSkill 工具加载对应技能，获取专业指导。';
-    return desc.trim();
-  }
-
-  /**
-   * 构建系统能力描述
-   */
-  _buildCapabilitiesDescription() {
-    const plugins = this.framework.pluginManager.getAll();
-    if (!plugins || plugins.length === 0) {
-      return '';
-    }
-
-    // 过滤出有描述的关键插件（排除内部插件）
-    const keyPlugins = plugins.filter((p) => {
-      const name = p.name;
-      // 排除默认配置插件和内部插件
-      return name !== 'defaults' && name !== 'agent';
-    });
-
-    if (keyPlugins.length === 0) {
-      return '';
-    }
-
-    let desc = '【系统能力】\n';
-    for (const plugin of keyPlugins) {
-      const name = plugin.instance?.name || plugin.name || 'unknown';
-      const description = plugin.instance?.description || '无描述';
-      desc += `- ${name}: ${description}\n`;
-    }
-
-    return desc.trim();
-  }
-
-  /**
-   * 构建子Agent描述
-   * 动态从配置文件读取每个子Agent的专业领域
-   */
-  _buildSubAgentsDescription() {
-    const subAgentManager = this.framework.pluginManager.get('subagent-manager');
-    if (!subAgentManager) {
-      return '';
-    }
-    const allSubAgents = subAgentManager.getAllSubAgents();
-    if (!allSubAgents || allSubAgents.length === 0) {
-      return '';
-    }
-
-    let desc = '【子 Agent 匹配表 - 优先使用】\n';
-
-    // 动态从配置文件读取每个子Agent的核心能力
-    for (const plugin of allSubAgents) {
-      const name = plugin.name;
-      const role = plugin.role;
-      const goal = plugin.description || '';
-
-      // 优先使用 SubAgentConfigManager 获取详细信息
-      const config = this.framework._subAgentConfigManager?.get(name);
-      if (config) {
-        const agentDesc = config.getDescription();
-        const skills = config.getSkills();
-        let info = agentDesc || role || goal || '子代理';
-        if (skills && skills.length > 0) {
-          info += ` (技能: ${skills.join(', ')})`;
-        }
-        desc += `  - ${name}: ${info}\n`;
-      } else {
-        // 回退到旧逻辑
-        desc += `  - ${name}: ${role || goal || '子代理'}\n`;
-      }
-    }
-
-    // 通用规则
-    desc += '\n【子Agent匹配规则 - 必须遵守】\n';
-    desc += '  - 根据上述【子 Agent 匹配表】，将任务委托给最匹配的子Agent处理\n';
-    desc += '  - 使用 subagent_call 工具并指定 agentName 来委托任务\n';
-    desc += '  - 只有当没有匹配的子Agent时，才直接调用工具\n';
-
-    return desc.trim();
-  }
-
-  /**
-   * 从配置文件动态读取子Agent的核心能力
-   * 支持 .json 和 .md 格式
-   * @private
-   */
-  _getSubAgentCapabilities(name) {
-    try {
-      const fs = require('fs');
-      const path = require('path');
-      const agentsDir = path.join(process.cwd(), '.agent', 'agents');
-
-      // 尝试多种文件格式
-      const possiblePaths = [
-        path.join(agentsDir, `${name}.md`),
-        path.join(agentsDir, `${name}.json`),
-      ];
-
-      let filePath = null;
-      for (const p of possiblePaths) {
-        if (fs.existsSync(p)) {
-          filePath = p;
-          break;
-        }
-      }
-
-      if (!filePath) {
-        return null;
-      }
-
-      const content = fs.readFileSync(filePath, 'utf-8');
-
-      // .json 格式
-      if (filePath.endsWith('.json')) {
-        const config = JSON.parse(content);
-        return this._extractCapabilitiesFromConfig(config);
-      }
-
-      // .md 格式（YAML front matter + markdown）
-      if (filePath.endsWith('.md')) {
-        return this._extractCapabilitiesFromMd(content);
-      }
-
-      return null;
-    } catch (e) {
-      return null;
-    }
-  }
-
-  /**
-   * 从 JSON 配置中提取核心能力
-   */
-  _extractCapabilitiesFromConfig(config) {
-    if (config.instructions) {
-      const match = config.instructions.match(/【核心能力】([\s\S]*?)(?=【|$)/);
-      if (match) {
-        const capabilities = match[1]
-          .split('\n')
-          .map((line) => line.replace(/^[·\-*]\s*/, '').trim())
-          .filter((line) => line && !line.startsWith('你是一个'))
-          .slice(0, 4)
-          .join('、');
-        return capabilities || config.description;
-      }
-      return config.description;
-    }
-    return config.description || null;
-  }
-
-  /**
-   * 从 .md 文件（YAML front matter）中提取核心能力
-   */
-  _extractCapabilitiesFromMd(mdContent) {
-    // 解析 YAML front matter
-    const frontMatterMatch = mdContent.match(/^---\n([\s\S]*?)\n---/);
-    if (!frontMatterMatch) {
-      return null;
-    }
-
-    const frontMatter = frontMatterMatch[1];
-    const config = {};
-
-    // 简单解析 YAML front matter
-    for (const line of frontMatter.split('\n')) {
-      const colonIndex = line.indexOf(':');
-      if (colonIndex > 0) {
-        const key = line.substring(0, colonIndex).trim();
-        let value = line.substring(colonIndex + 1).trim();
-        // 移除可能的引号
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-          value = value.slice(1, -1);
-        }
-        config[key] = value;
-      }
-    }
-    // 从 description 字段提取能力
-    if (config.description) {
-      const desc = config.description;
-      // 按逗号/顿号分隔
-      const parts = desc.split(/[,，、]/).map(s => s.trim());
-      // 取第一部分（通常是最核心的能力描述）
-      const firstPart = parts[0];
-      // 如果第一部分太长（说明是句子），取前50个字符
-      if (firstPart.length > 50) {
-        return firstPart.substring(0, 50).trim() + '...';
-      }
-      // 如果有多个部分，取前3个
-      if (parts.length > 1) {
-        return parts.slice(0, 3).join('、');
-      }
-      return firstPart;
-    }
-
-    return null;
-  }
-
-  _buildSystemPrompt() {
-    // 如果没变脏，返回缓存
-    if (!this._systemPromptDirty && this._systemPromptCache !== null) {
-      return this._systemPromptCache;
-    }
-
-    // 使用 builder 构建系统提示词
-    this._systemPromptCache = this._systemPromptBuilder.build();
-    this._systemPromptDirty = false;
-    return this._systemPromptCache;
-  }
-
-  /**
-   * 使 system prompt 缓存失效
-   * @private
-   */
-  _invalidateSystemPromptCache() {
-    this._systemPromptDirty = true;
-    // 同时使 builder 中所有部分失效
-    this._systemPromptBuilder.invalidateAll();
-  }
-
-  /**
-   * 注册自定义系统提示词部分（供插件使用）
-   * @param {string} name - 部分名称
-   * @param {number} priority - 优先级
-   * @param {Function} provider - 返回提示词内容的函数
-   */
-  registerPromptPart(name, priority, provider) {
-    this._systemPromptBuilder.register(name, priority, provider);
-    this._invalidateSystemPromptCache();
-    return this;
-  }
-
-  /**
-   * 注销系统提示词部分
-   * @param {string} name - 部分名称
-   */
-  unregisterPromptPart(name) {
-    this._systemPromptBuilder.unregister(name);
-    this._invalidateSystemPromptCache();
-    return this;
-  }
-
-  /**
-   * 使特定系统提示词部分失效
-   * @param {string} name - 部分名称
-   */
-  invalidatePromptPart(name) {
-    this._systemPromptBuilder.invalidate(name);
-    this._systemPromptDirty = true;
-    return this;
-  }
-
-  /**
-   * 获取工具调用核心规则
-   * @private
-   */
-  _getToolCoreRules() {
-    return `【工具调用核心规则】
-1. **子Agent优先**：任务匹配子Agent专业领域时，**必须优先使用** 使用 subagent_call 工具并指定 agentName 委托给对应子Agent处理，而不是直接调用工具。只有当没有匹配的子Agent时，才直接调用工具。
-2. **必须先调用工具再回复**：当问题需要信息、操作或计算时，必须调用工具获取真实结果后才能回答。禁止在未调用工具的情况下直接给出答案。
-3. **禁止编造数据**：不许捏造用户、订单、任务、文件、内容等任何数据。所有数据必须通过工具获取。
-4. **工具优先**：可用工具列表会提供，格式为 toolName(toolArgs)。不确定用哪个工具时，优先调用可能相关的工具。
-5. **结果导向**：调用工具后，基于返回结果回答，不要重复工具的内部实现细节。
-6. **多步骤任务**：复杂任务拆解为多个工具调用，逐步完成，每步基于结果决定下一步。
-
-
-【响应规范】
-- 直接给出结论或结果，不说"我需要..."、"我建议..."等铺垫话术
-- 如果工具返回错误，说明错误原因并给出解决建议
-- 如果信息不足，先调用工具获取必要信息，不要假设或猜测
-
-【禁止事项】
-- 不调用工具就直接回答
-- 编造不存在的数据、文件、订单、用户等信息
-- 回复含糊不清，让用户无法确定答案是否正确`;
-  }
-
-  /**
-   * 刷新上下文
-   */
-  _refreshContext() {
-    this.systemPrompt = this._buildSystemPrompt();
-    if (this._chatHandler) {
-      this._chatHandler.setSystemPrompt(this.systemPrompt);
-    }
-  }
-
-  /**
-   * 初始化聊天处理器
-   * @private
-   */
-  _initChatHandler() {
-    let aiClient = null;
-    const aiPlugin = this.framework.pluginManager.get('ai');
-    if (aiPlugin) {
-      aiClient = aiPlugin.getAIClient();
-    }
-
-    this._chatHandler = new AgentChatHandler(this, {
-      model: this.model,
-      provider: this.provider,
-      apiKey: this.apiKey,
-      baseURL: this.baseURL,
-      providerOptions: this.providerOptions,
-      // 上下文压缩配置
-      maxContextTokens: this.config.maxContextTokens,
-      compressionThreshold: this.config.compressionThreshold,
-      keepRecentMessages: this.config.keepRecentMessages,
-      enableSmartCompress: this.config.enableSmartCompress,
-    });
-
-    if (aiClient) {
-      this._chatHandler.setAIClient(aiClient);
-    }
-
-    // 转发事件
-    this._chatHandler.on('message', (msg) => this.emit('message', msg));
-    this._chatHandler.on('chunk', (chunk) => this.emit('chunk', chunk));
-    this._chatHandler.on('tool-call', (tool) => this.emit('tool-call', tool));
-    this._chatHandler.on('tool-result', (result) => this.emit('tool-result', result));
-    this._chatHandler.on('error', (err) => this.emit('error', err));
-
-    this._syncTools();
-  }
-
-  /**
-   * 设置系统提示
-   */
-  setSystemPrompt(prompt) {
-    this._originalPrompt = prompt;
-    this.systemPrompt = this._buildSystemPrompt();
-    if (this._chatHandler) {
-      this._chatHandler.setSystemPrompt(this.systemPrompt);
-    }
-    return this;
-  }
-
-  /**
-   * 注册工具到 Agent
-   */
-  registerTool(tool) {
-    this._tools.set(tool.name, tool);
-    this._invalidateSystemPromptCache();
-    if (this._chatHandler) {
-      this._chatHandler.registerTool(tool);
-    }
-    this._refreshContext();
-    return this;
-  }
-
-  /**
-   * 获取已注册工具
-   */
-  getTools() {
-    return Array.from(this._tools.values());
-  }
-
-  /**
-   * 同步框架中的工具到 Agent
-   * @private
-   */
-  _syncTools() {
-    if (this.framework.toolRegistry.size() > 0) {
-      for (const tool of this.framework.getTools()) {
-        if (!this._tools.has(tool.name)) {
-          this.registerTool(tool);
-        }
-      }
-    }
-  }
-
-  /**
-   * 注册子Agent
-   * @param {string} name - 子Agent名称
-   * @param {Agent} agent - 子Agent实例
-   * @param {string} role - 角色描述
-   * @param {string} goal - 目标描述
-   */
-  registerSubAgent(name, agent, role, goal) {
-    this._subAgents.set(name, { agent, role, goal });
-    this._invalidateSystemPromptCache();
-    this._refreshContext();
-    return this;
-  }
-
-  /**
-   * 注销子Agent
-   */
-  unregisterSubAgent(name) {
-    this._subAgents.delete(name);
-    this._invalidateSystemPromptCache();
-    this._refreshContext();
-    return this;
-  }
-
-  /**
-   * 获取所有子Agent
-   */
-  getSubAgents() {
-    return this._subAgents;
-  }
-
-  /**
-   * 获取待处理的调度通知并清除（下次不再重复显示）
-   */
-  _getAndClearSchedulerNotifications() {
-    try {
-      const scheduler = this.framework.pluginManager.get('scheduler');
-      if (scheduler && scheduler.instance && scheduler.instance.getPendingNotifications) {
-        const results = scheduler.instance.getPendingNotifications();
-        if (results.length > 0) {
-          const notifications = results.slice(-5).reverse(); // 最多5条，最新的在前
-          // 清除已发送的通知
-          if (scheduler.instance.clearDeliveredNotifications) {
-            scheduler.instance.clearDeliveredNotifications(notifications.length);
-          }
-          return notifications;
-        }
-      }
-    } catch (err) {
-      // 忽略错误，避免影响主流程
-    }
-    return [];
-  }
-
-  /**
-   * 获取待处理的思考结果并清除
-   */
-  _getAndClearThinkNotifications() {
-    try {
-      const think = this.framework.pluginManager.get('think');
-      if (think && think.instance && think.instance.getPendingThoughts) {
-        const thoughts = think.instance.getPendingThoughts();
-        if (thoughts.length > 0) {
-          return thoughts.slice(-5).reverse(); // 最多5条，最新的在前
-        }
-      }
-    } catch (err) {
-      // 忽略错误，避免影响主流程
-    }
-    return [];
-  }
-
-  /**
-   * 获取所有待处理的系统通知（调度 + 思考）
-   */
-  _getAllPendingNotifications() {
-    const notifications = [];
-
-    // 调度通知
-    const schedulerNotifs = this._getAndClearSchedulerNotifications();
-    for (const n of schedulerNotifs) {
-      notifications.push(
-        `【定时任务通知】\n任务: ${n.taskName || n.taskId}\n执行时间: ${n.executedAt}\n结果: ${n.result || n.action || '执行完成'}`
-      );
-    }
-
-    // 思考通知
-    const thinkNotifs = this._getAndClearThinkNotifications();
-    for (const t of thinkNotifs) {
-      notifications.push(
-        `【主动思考】\n模式: ${t.mode}\n主题: ${t.topic}\n结果: ${t.result || '思考完成'}`
-      );
-    }
-
-    return notifications;
-  }
-
-  /**
-   * 发送消息
-   */
-  async chat(message, options = {}) {
-    if (this._status === 'busy') {
-      throw new Error('Agent is busy');
-    }
-
-    if (this._status === 'error') {
-      this._status = 'idle';
-    }
-
-    this._status = 'busy';
-    this.emit('status', { status: 'busy' });
-
-    try {
-      // 检查是否有待处理的系统通知（调度 + 思考）
-      const notifications = this._getAllPendingNotifications();
-      let enhancedMessage = message;
-      if (notifications.length > 0) {
-        enhancedMessage = `【系统通知】\n${notifications.join('\n\n')}\n\n---\n用户消息: ${message}`;
-      }
-
-      this._syncTools();
-
-      const result = await this._chatHandler.chat(enhancedMessage, options);
-      this._status = 'idle';
-      this.emit('status', { status: 'idle' });
-
-      // 处理队列中的下一条消息
-      setImmediate(() => this._processQueue());
-
-      return result;
-    } catch (err) {
-      this._status = 'error';
-      this.emit('status', { status: 'error', error: err.message });
-
-      // 发生错误时也要处理队列
-      setImmediate(() => this._processQueue());
-
-      throw err;
-    }
-  }
-
-  /**
-   * 推送消息（自动继承当前 sessionId 上下文，自动排队）
-   * 工具中调用此方法，自动带上当前执行上下文的 sessionId
-   * 如果 agent 忙碌，消息会进入队列等待
-   * @param {string|Object} message - 消息
-   * @param {Object} options - 选项 { maxSteps }
-   * @returns {Promise<{success: boolean, message: string, stepCount: number}>}
-   */
-  async pushMessage(message, options = {}) {
-    // 自动从执行上下文获取 sessionId
-    const ctx = this.framework.getExecutionContext();
-    if (ctx?.sessionId && !options.sessionId) {
-      options.sessionId = ctx.sessionId;
-    }
-
-    // 如果忙碌，进入队列等待
-    if (this._status === 'busy') {
-      const queuedItem = { message, options, resolve: null, reject: null };
-      const promise = new Promise((resolve, reject) => {
-        queuedItem.resolve = resolve;
-        queuedItem.reject = reject;
-      });
-      this._messageQueue.push(queuedItem);
-      // Agent busy, message queued
-      return promise;
-    }
-
-    // 空闲则直接处理
-    return this.chat(message, options);
-  }
-
-  /**
-   * 处理消息队列
-   * @private
-   */
-  async _processQueue() {
-    if (this._isProcessingQueue || this._messageQueue.length === 0) {
-      return;
-    }
-
-    this._isProcessingQueue = true;
-
-    // 强制设置为 idle，确保 this.chat() 能执行
-    this._status = 'idle';
-
-    while (this._messageQueue.length > 0) {
-      const item = this._messageQueue.shift();
-      try {
-        const result = await this.chat(item.message, item.options);
-        item.resolve(result);
-      } catch (err) {
-        item.reject(err);
-      }
-    }
-
-    this._isProcessingQueue = false;
-  }
-
-  /**
-   * 发送消息（流式）
-   */
-  async *chatStream(message, options = {}) {
-    if (this._status === 'busy') {
-      throw new Error('Agent is busy');
-    }
-
-    // 允许从 error 状态重试
-    if (this._status === 'error') {
-      this._status = 'idle';
-    }
-
-    this._status = 'busy';
-    this.emit('status', { status: 'busy' });
-
-    try {
-      // 检查是否有待处理的系统通知（调度 + 思考）
-      const notifications = this._getAllPendingNotifications();
-      let enhancedMessage = message;
-      if (notifications.length > 0) {
-        enhancedMessage = `【系统通知】\n${notifications.join('\n\n')}\n\n---\n用户消息: ${message}`;
-      }
-
-      this._syncTools();
-
-      yield* this._chatHandler.chatStream(enhancedMessage, options);
-      this._status = 'idle';
-      this.emit('status', { status: 'idle' });
-
-      // 处理队列中的下一条消息
-      setImmediate(() => this._processQueue());
-    } catch (err) {
-      this._status = 'error';
-      this.emit('status', { status: 'error', error: err.message });
-
-      // 发生错误时也要处理队列
-      setImmediate(() => this._processQueue());
-
-      throw err;
-    }
-  }
-
-  /**
-   * 设置元数据
-   */
-  setMetadata(keyOrObj, value) {
-    if (typeof keyOrObj === 'string') {
-      this._metadata.set(keyOrObj, value);
-    } else if (keyOrObj && typeof keyOrObj === 'object') {
-      for (const [key, val] of Object.entries(keyOrObj)) {
-        this._metadata.set(key, val);
-      }
-    }
-    this._invalidateSystemPromptCache();
-    this._refreshContext();
-    return this;
-  }
-
-  /**
-   * 获取元数据
-   */
-  getMetadata(key) {
-    return this._metadata.get(key);
-  }
-
-  /**
-   * 删除元数据
-   */
-  deleteMetadata(key) {
-    this._metadata.delete(key);
-    this._refreshContext();
-    return this;
-  }
-
-  /**
-   * 清空元数据
-   */
-  clearMetadata() {
-    this._metadata.clear();
-    this._refreshContext();
-    return this;
-  }
-
-  /**
-   * 清空对话历史
-   */
-  clearHistory() {
-    if (this._chatHandler) {
-      this._chatHandler.clearHistory();
-    }
-    return this;
-  }
-
-  /**
-   * 获取状态
-   */
-  getStatus() {
-    return this._status;
-  }
-
-  /**
-   * 重置状态（从卡住状态恢复）
-   */
-  resetStatus() {
-    this._status = 'idle';
-    this.emit('status', { status: 'idle' });
-    return this;
-  }
-
-  /**
-   * 销毁 Agent
-   */
-  destroy() {
-    if (this._chatHandler) {
-      this._chatHandler.destroy();
-    }
-    this._tools.clear();
-    this.removeAllListeners();
-    this.emit('destroyed');
-  }
-}
-
-module.exports = { Agent };
+/**
+ * Agent 类
+ * 负责对话和推理
+ */
+
+const { EventEmitter } = require('../utils/event-emitter');
+const { AgentChatHandler } = require('./agent-chat');
+const { SystemPromptBuilder } = require('./system-prompt-builder');
+const os = require('os');
+
+class Agent extends EventEmitter {
+  /**
+   * @param {Framework} framework - 框架实例
+   * @param {Object} config - 配置
+   * @param {string} [config.name] - Agent 名称
+   * @param {string} [config.systemPrompt] - 系统提示
+   * @param {string} [config.sharedPrompt] - 共享提示模板，支持 {{VAR}} 占位符
+   * @param {Object} [config.metadata] - 元数据，注入到 sharedPrompt
+   * @param {boolean} [config.enableToolRouting=true] - 是否启用工具路由
+   */
+  constructor(framework, config = {}) {
+    super();
+
+    this.framework = framework;
+    this.config = config;
+
+    this.name = config.name || 'Agent';
+    this.model = config.model || 'deepseek-chat';
+    this.apiKey = config.apiKey;
+    this.baseURL = config.baseURL;
+    this.provider = config.provider || 'deepseek';
+    this.providerOptions = config.providerOptions || {};
+    this.providerOptions.maxOutputTokens = 8192;
+    this.providerOptions.temperature = 0.3; // 降低 temperature 减少生成错误 JSON 的概率
+    // 原始 system prompt
+    this._originalPrompt =
+      config.systemPrompt ||
+      '你是一个智能助手。当用户提出问题或任务时，你会主动分析需求，选择合适的工具来获取信息或执行操作。你善于将复杂任务拆解为多个步骤，通过工具协作完成。';
+
+    // 共享提示模板
+    this._sharedPrompt = config.sharedPrompt || '';
+
+    // 元数据
+    const metadata = config.metadata || {};
+    this._metadata = new Map(Object.entries(metadata));
+
+    this._chatHandler = null;
+    this._tools = new Map();
+    this._status = 'idle';
+
+    // 子Agent管理
+    this._subAgents = new Map();
+
+    // 消息队列（用于 pushMessage）
+    this._messageQueue = [];
+    this._isProcessingQueue = false;
+
+    // System prompt 构建器
+    this._systemPromptBuilder = new SystemPromptBuilder();
+    this._registerDefaultPromptParts();
+
+    // 处理后的 system prompt (带上下文)
+    this.systemPrompt = this._buildSystemPrompt();
+
+    // 初始化聊天处理器
+    this._initChatHandler();
+  }
+
+  /**
+   * 注册默认的系统提示词部分
+   * @private
+   */
+  _registerDefaultPromptParts() {
+    // 1. 原始 system prompt (优先级 100)
+    this._systemPromptBuilder.register('original-prompt', 100, () => this._originalPrompt);
+
+    // 2. 共享提示模板 (优先级 200)
+    this._systemPromptBuilder.register('shared-prompt', 200, () => {
+      if (this._sharedPrompt) {
+        return this._replacePlaceholders(this._sharedPrompt);
+      }
+      return null;
+    });
+
+    // 3. 元数据 (优先级 300)
+    this._systemPromptBuilder.register('metadata', 300, () => {
+      if (this._metadata.size === 0) {
+        return null;
+      }
+      const metaParts = ['【元数据】'];
+      for (const [key, value] of this._metadata) {
+        if (typeof value === 'object') {
+          metaParts.push(`- ${key}: ${JSON.stringify(value)}`);
+        } else {
+          metaParts.push(`- ${key}: ${value}`);
+        }
+      }
+      return metaParts.join('\n');
+    });
+
+    // 4. 工具列表 (优先级 400)
+    this._systemPromptBuilder.register('tools', 400, () => this._buildToolsDescription());
+
+    // 5. 技能列表 (优先级 500)
+    this._systemPromptBuilder.register('skills', 500, () => this._buildSkillsDescription());
+
+    // 6. 子Agent列表 (优先级 600)
+    this._systemPromptBuilder.register('subagents', 600, () => this._buildSubAgentsDescription());
+
+    // 7. 系统能力 (优先级 700)
+    this._systemPromptBuilder.register('capabilities', 700, () => this._buildCapabilitiesDescription());
+
+    // 8. 工具调用核心规则 (优先级 1000)
+    this._systemPromptBuilder.register('tool-core-rules', 1000, () => this._getToolCoreRules());
+  }
+
+  /**
+   * 获取元数据值
+   */
+  _getMetadataValue(key) {
+    // 优先从 metadata 获取
+    if (this._metadata.has(key)) {
+      return this._metadata.get(key);
+    }
+
+    // 内置变量
+    switch (key) {
+      case 'WORK_DIR':
+      case 'CWD':
+        return process.cwd();
+      case 'HOME_DIR':
+        return os.homedir();
+      case 'HOST_NAME':
+        return os.hostname();
+      case 'PLATFORM':
+        return process.platform;
+      case 'TIME':
+        return new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
+      case 'DATE':
+        return new Date().toISOString().split('T')[0];
+      default:
+        return `{{${key}}}`;
+    }
+  }
+
+  /**
+   * 替换 sharedPrompt 中的占位符
+   */
+  _replacePlaceholders(template) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+      return this._getMetadataValue(key);
+    });
+  }
+
+  /**
+   * 构建工具描述
+   */
+  _buildToolsDescription() {
+    if (this._tools.size === 0) {
+      return '';
+    }
+
+    // 需要排除的子Agent相关工具（它们通过专门的子Agent部分提供）
+    // const excludedTools = new Set(['subagent_call', 'subagent_list', 'subagent_reload']);
+
+    let desc = '【可用工具】\n';
+    for (const [name, tool] of this._tools) {
+      // 跳过没有描述的工具（对LLM无帮助）
+      if (!tool.description) continue;
+      // // 跳过子Agent相关工具（通过专门的子Agent部分提供）
+      // if (excludedTools.has(name)) continue;
+      // // 跳过子Agent委托工具（通过专门的子Agent部分提供）
+      // if (this._subAgents.has(name)) continue;
+      desc += `- ${name}: ${tool.description}\n`;
+    }
+    return desc.trim();
+  }
+
+  /**
+   * 构建技能描述
+   */
+  _buildSkillsDescription() {
+    const skillManager = this.framework.pluginManager.get('skill-manager');
+    if (!skillManager) {
+      return '';
+    }
+
+    const skills = skillManager.getAllSkills();
+    if (!skills || skills.length === 0) {
+      return '';
+    }
+
+    let desc = '【可用技能】\n';
+    for (const skill of skills) {
+      const name = skill.metadata?.name || skill.name || 'unknown';
+      const descText = skill.metadata?.description || '';
+      desc += `- ${name}: ${descText}\n`;
+    }
+    desc +=
+      '\n重要：当需要开发插件、执行专业任务时，必须先使用 loadSkill 工具加载对应技能，获取专业指导。';
+    return desc.trim();
+  }
+
+  /**
+   * 构建系统能力描述
+   */
+  _buildCapabilitiesDescription() {
+    const plugins = this.framework.pluginManager.getAll();
+    if (!plugins || plugins.length === 0) {
+      return '';
+    }
+
+    // 过滤出有描述的关键插件（排除内部插件）
+    const keyPlugins = plugins.filter((p) => {
+      const name = p.name;
+      // 排除默认配置插件和内部插件
+      return name !== 'defaults' && name !== 'agent';
+    });
+
+    if (keyPlugins.length === 0) {
+      return '';
+    }
+
+    let desc = '【系统能力】\n';
+    for (const plugin of keyPlugins) {
+      const name = plugin.instance?.name || plugin.name || 'unknown';
+      const description = plugin.instance?.description || '无描述';
+      desc += `- ${name}: ${description}\n`;
+    }
+
+    return desc.trim();
+  }
+
+  /**
+   * 构建子Agent描述
+   * 动态从配置文件读取每个子Agent的专业领域
+   */
+  _buildSubAgentsDescription() {
+    const subAgentManager = this.framework.pluginManager.get('subagent-manager');
+    if (!subAgentManager) {
+      return '';
+    }
+    const allSubAgents = subAgentManager.getAllSubAgents();
+    if (!allSubAgents || allSubAgents.length === 0) {
+      return '';
+    }
+
+    let desc = '【子 Agent 匹配表 - 优先使用】\n';
+
+    // 动态从配置文件读取每个子Agent的核心能力
+    for (const plugin of allSubAgents) {
+      const name = plugin.name;
+      const role = plugin.role;
+      const goal = plugin.description || '';
+
+      // 优先使用 SubAgentConfigManager 获取详细信息
+      const config = this.framework._subAgentConfigManager?.get(name);
+      if (config) {
+        const agentDesc = config.getDescription();
+        const skills = config.getSkills();
+        let info = agentDesc || role || goal || '子代理';
+        if (skills && skills.length > 0) {
+          info += ` (技能: ${skills.join(', ')})`;
+        }
+        desc += `  - ${name}: ${info}\n`;
+      } else {
+        // 回退到旧逻辑
+        desc += `  - ${name}: ${role || goal || '子代理'}\n`;
+      }
+    }
+
+    // 通用规则
+    desc += '\n【子Agent匹配规则 - 必须遵守】\n';
+    desc += '  - 根据上述【子 Agent 匹配表】，将任务委托给最匹配的子Agent处理\n';
+    desc += '  - 使用 subagent_call 工具并指定 agentName 来委托任务\n';
+    desc += '  - 只有当没有匹配的子Agent时，才直接调用工具\n';
+
+    return desc.trim();
+  }
+
+  /**
+   * 从配置文件动态读取子Agent的核心能力
+   * 支持 .json 和 .md 格式
+   * @private
+   */
+  _getSubAgentCapabilities(name) {
+    try {
+      const fs = require('fs');
+      const path = require('path');
+      const agentsDir = path.join(process.cwd(), '.agent', 'agents');
+
+      // 尝试多种文件格式
+      const possiblePaths = [
+        path.join(agentsDir, `${name}.md`),
+        path.join(agentsDir, `${name}.json`),
+      ];
+
+      let filePath = null;
+      for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+          filePath = p;
+          break;
+        }
+      }
+
+      if (!filePath) {
+        return null;
+      }
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+
+      // .json 格式
+      if (filePath.endsWith('.json')) {
+        const config = JSON.parse(content);
+        return this._extractCapabilitiesFromConfig(config);
+      }
+
+      // .md 格式（YAML front matter + markdown）
+      if (filePath.endsWith('.md')) {
+        return this._extractCapabilitiesFromMd(content);
+      }
+
+      return null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /**
+   * 从 JSON 配置中提取核心能力
+   */
+  _extractCapabilitiesFromConfig(config) {
+    if (config.instructions) {
+      const match = config.instructions.match(/【核心能力】([\s\S]*?)(?=【|$)/);
+      if (match) {
+        const capabilities = match[1]
+          .split('\n')
+          .map((line) => line.replace(/^[·\-*]\s*/, '').trim())
+          .filter((line) => line && !line.startsWith('你是一个'))
+          .slice(0, 4)
+          .join('、');
+        return capabilities || config.description;
+      }
+      return config.description;
+    }
+    return config.description || null;
+  }
+
+  /**
+   * 从 .md 文件（YAML front matter）中提取核心能力
+   */
+  _extractCapabilitiesFromMd(mdContent) {
+    // 解析 YAML front matter
+    const frontMatterMatch = mdContent.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontMatterMatch) {
+      return null;
+    }
+
+    const frontMatter = frontMatterMatch[1];
+    const config = {};
+
+    // 简单解析 YAML front matter
+    for (const line of frontMatter.split('\n')) {
+      const colonIndex = line.indexOf(':');
+      if (colonIndex > 0) {
+        const key = line.substring(0, colonIndex).trim();
+        let value = line.substring(colonIndex + 1).trim();
+        // 移除可能的引号
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+          value = value.slice(1, -1);
+        }
+        config[key] = value;
+      }
+    }
+    // 从 description 字段提取能力
+    if (config.description) {
+      const desc = config.description;
+      // 按逗号/顿号分隔
+      const parts = desc.split(/[,，、]/).map(s => s.trim());
+      // 取第一部分（通常是最核心的能力描述）
+      const firstPart = parts[0];
+      // 如果第一部分太长（说明是句子），取前50个字符
+      if (firstPart.length > 50) {
+        return firstPart.substring(0, 50).trim() + '...';
+      }
+      // 如果有多个部分，取前3个
+      if (parts.length > 1) {
+        return parts.slice(0, 3).join('、');
+      }
+      return firstPart;
+    }
+
+    return null;
+  }
+
+  _buildSystemPrompt() {
+    // 如果没变脏，返回缓存
+    if (!this._systemPromptDirty && this._systemPromptCache !== null) {
+      return this._systemPromptCache;
+    }
+
+    // 使用 builder 构建系统提示词
+    this._systemPromptCache = this._systemPromptBuilder.build();
+    this._systemPromptDirty = false;
+    return this._systemPromptCache;
+  }
+
+  /**
+   * 使 system prompt 缓存失效
+   * @private
+   */
+  _invalidateSystemPromptCache() {
+    this._systemPromptDirty = true;
+    // 同时使 builder 中所有部分失效
+    this._systemPromptBuilder.invalidateAll();
+  }
+
+  /**
+   * 注册自定义系统提示词部分（供插件使用）
+   * @param {string} name - 部分名称
+   * @param {number} priority - 优先级
+   * @param {Function} provider - 返回提示词内容的函数
+   */
+  registerPromptPart(name, priority, provider) {
+    this._systemPromptBuilder.register(name, priority, provider);
+    this._invalidateSystemPromptCache();
+    return this;
+  }
+
+  /**
+   * 注销系统提示词部分
+   * @param {string} name - 部分名称
+   */
+  unregisterPromptPart(name) {
+    this._systemPromptBuilder.unregister(name);
+    this._invalidateSystemPromptCache();
+    return this;
+  }
+
+  /**
+   * 使特定系统提示词部分失效
+   * @param {string} name - 部分名称
+   */
+  invalidatePromptPart(name) {
+    this._systemPromptBuilder.invalidate(name);
+    this._systemPromptDirty = true;
+    return this;
+  }
+
+  /**
+   * 获取工具调用核心规则
+   * @private
+   */
+  _getToolCoreRules() {
+    return `【工具调用核心规则】
+1. **子Agent优先**：任务匹配子Agent专业领域时，**必须优先使用** 使用 subagent_call 工具并指定 agentName 委托给对应子Agent处理，而不是直接调用工具。只有当没有匹配的子Agent时，才直接调用工具。
+2. **必须先调用工具再回复**：当问题需要信息、操作或计算时，必须调用工具获取真实结果后才能回答。禁止在未调用工具的情况下直接给出答案。
+3. **禁止编造数据**：不许捏造用户、订单、任务、文件、内容等任何数据。所有数据必须通过工具获取。
+4. **工具优先**：可用工具列表会提供，格式为 toolName(toolArgs)。不确定用哪个工具时，优先调用可能相关的工具。
+5. **结果导向**：调用工具后，基于返回结果回答，不要重复工具的内部实现细节。
+6. **多步骤任务**：复杂任务拆解为多个工具调用，逐步完成，每步基于结果决定下一步。
+
+
+【响应规范】
+- 直接给出结论或结果，不说"我需要..."、"我建议..."等铺垫话术
+- 如果工具返回错误，说明错误原因并给出解决建议
+- 如果信息不足，先调用工具获取必要信息，不要假设或猜测
+
+【禁止事项】
+- 不调用工具就直接回答
+- 编造不存在的数据、文件、订单、用户等信息
+- 回复含糊不清，让用户无法确定答案是否正确`;
+  }
+
+  /**
+   * 刷新上下文
+   */
+  _refreshContext() {
+    this.systemPrompt = this._buildSystemPrompt();
+    if (this._chatHandler) {
+      this._chatHandler.setSystemPrompt(this.systemPrompt);
+    }
+  }
+
+  /**
+   * 初始化聊天处理器
+   * @private
+   */
+  _initChatHandler() {
+    let aiClient = null;
+    const aiPlugin = this.framework.pluginManager.get('ai');
+    if (aiPlugin) {
+      aiClient = aiPlugin.getAIClient();
+    }
+
+    this._chatHandler = new AgentChatHandler(this, {
+      model: this.model,
+      provider: this.provider,
+      apiKey: this.apiKey,
+      baseURL: this.baseURL,
+      providerOptions: this.providerOptions,
+      // 上下文压缩配置
+      maxContextTokens: this.config.maxContextTokens,
+      compressionThreshold: this.config.compressionThreshold,
+      keepRecentMessages: this.config.keepRecentMessages,
+      enableSmartCompress: this.config.enableSmartCompress,
+    });
+
+    if (aiClient) {
+      this._chatHandler.setAIClient(aiClient);
+    }
+
+    // 转发事件
+    this._chatHandler.on('message', (msg) => this.emit('message', msg));
+    this._chatHandler.on('chunk', (chunk) => this.emit('chunk', chunk));
+    this._chatHandler.on('tool-call', (tool) => this.emit('tool-call', tool));
+    this._chatHandler.on('tool-result', (result) => this.emit('tool-result', result));
+    this._chatHandler.on('error', (err) => this.emit('error', err));
+
+    this._syncTools();
+  }
+
+  /**
+   * 设置系统提示
+   */
+  setSystemPrompt(prompt) {
+    this._originalPrompt = prompt;
+    this.systemPrompt = this._buildSystemPrompt();
+    if (this._chatHandler) {
+      this._chatHandler.setSystemPrompt(this.systemPrompt);
+    }
+    return this;
+  }
+
+  /**
+   * 注册工具到 Agent
+   */
+  registerTool(tool) {
+    this._tools.set(tool.name, tool);
+    this._invalidateSystemPromptCache();
+    if (this._chatHandler) {
+      this._chatHandler.registerTool(tool);
+    }
+    this._refreshContext();
+    return this;
+  }
+
+  /**
+   * 获取已注册工具
+   */
+  getTools() {
+    return Array.from(this._tools.values());
+  }
+
+  /**
+   * 同步框架中的工具到 Agent
+   * @private
+   */
+  _syncTools() {
+    if (this.framework.toolRegistry.size() > 0) {
+      for (const tool of this.framework.getTools()) {
+        if (!this._tools.has(tool.name)) {
+          this.registerTool(tool);
+        }
+      }
+    }
+  }
+
+  /**
+   * 注册子Agent
+   * @param {string} name - 子Agent名称
+   * @param {Agent} agent - 子Agent实例
+   * @param {string} role - 角色描述
+   * @param {string} goal - 目标描述
+   */
+  registerSubAgent(name, agent, role, goal) {
+    this._subAgents.set(name, { agent, role, goal });
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  /**
+   * 注销子Agent
+   */
+  unregisterSubAgent(name) {
+    this._subAgents.delete(name);
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  /**
+   * 获取所有子Agent
+   */
+  getSubAgents() {
+    return this._subAgents;
+  }
+
+  /**
+   * 获取待处理的调度通知并清除（下次不再重复显示）
+   */
+  _getAndClearSchedulerNotifications() {
+    try {
+      const scheduler = this.framework.pluginManager.get('scheduler');
+      if (scheduler && scheduler.instance && scheduler.instance.getPendingNotifications) {
+        const results = scheduler.instance.getPendingNotifications();
+        if (results.length > 0) {
+          const notifications = results.slice(-5).reverse(); // 最多5条，最新的在前
+          // 清除已发送的通知
+          if (scheduler.instance.clearDeliveredNotifications) {
+            scheduler.instance.clearDeliveredNotifications(notifications.length);
+          }
+          return notifications;
+        }
+      }
+    } catch (err) {
+      // 忽略错误，避免影响主流程
+    }
+    return [];
+  }
+
+  /**
+   * 获取待处理的思考结果并清除
+   */
+  _getAndClearThinkNotifications() {
+    try {
+      const think = this.framework.pluginManager.get('think');
+      if (think && think.instance && think.instance.getPendingThoughts) {
+        const thoughts = think.instance.getPendingThoughts();
+        if (thoughts.length > 0) {
+          return thoughts.slice(-5).reverse(); // 最多5条，最新的在前
+        }
+      }
+    } catch (err) {
+      // 忽略错误，避免影响主流程
+    }
+    return [];
+  }
+
+  /**
+   * 获取所有待处理的系统通知（调度 + 思考）
+   */
+  _getAllPendingNotifications() {
+    const notifications = [];
+
+    // 调度通知
+    const schedulerNotifs = this._getAndClearSchedulerNotifications();
+    for (const n of schedulerNotifs) {
+      notifications.push(
+        `【定时任务通知】\n任务: ${n.taskName || n.taskId}\n执行时间: ${n.executedAt}\n结果: ${n.result || n.action || '执行完成'}`
+      );
+    }
+
+    // 思考通知
+    const thinkNotifs = this._getAndClearThinkNotifications();
+    for (const t of thinkNotifs) {
+      notifications.push(
+        `【主动思考】\n模式: ${t.mode}\n主题: ${t.topic}\n结果: ${t.result || '思考完成'}`
+      );
+    }
+
+    return notifications;
+  }
+
+  /**
+   * 发送消息
+   */
+  async chat(message, options = {}) {
+    if (this._status === 'busy') {
+      throw new Error('Agent is busy');
+    }
+
+    if (this._status === 'error') {
+      this._status = 'idle';
+    }
+
+    this._status = 'busy';
+    this.emit('status', { status: 'busy' });
+
+    try {
+      // 检查是否有待处理的系统通知（调度 + 思考）
+      const notifications = this._getAllPendingNotifications();
+      let enhancedMessage = message;
+      if (notifications.length > 0) {
+        enhancedMessage = `【系统通知】\n${notifications.join('\n\n')}\n\n---\n用户消息: ${message}`;
+      }
+
+      this._syncTools();
+
+      const result = await this._chatHandler.chat(enhancedMessage, options);
+      this._status = 'idle';
+      this.emit('status', { status: 'idle' });
+
+      // 处理队列中的下一条消息
+      setImmediate(() => this._processQueue());
+
+      return result;
+    } catch (err) {
+      this._status = 'error';
+      this.emit('status', { status: 'error', error: err.message });
+
+      // 发生错误时也要处理队列
+      setImmediate(() => this._processQueue());
+
+      throw err;
+    }
+  }
+
+  /**
+   * 推送消息（自动继承当前 sessionId 上下文，自动排队）
+   * 工具中调用此方法，自动带上当前执行上下文的 sessionId
+   * 如果 agent 忙碌，消息会进入队列等待
+   * @param {string|Object} message - 消息
+   * @param {Object} options - 选项 { maxSteps }
+   * @returns {Promise<{success: boolean, message: string, stepCount: number}>}
+   */
+  async pushMessage(message, options = {}) {
+    // 自动从执行上下文获取 sessionId
+    const ctx = this.framework.getExecutionContext();
+    if (ctx?.sessionId && !options.sessionId) {
+      options.sessionId = ctx.sessionId;
+    }
+
+    // 如果忙碌，进入队列等待
+    if (this._status === 'busy') {
+      const queuedItem = { message, options, resolve: null, reject: null };
+      const promise = new Promise((resolve, reject) => {
+        queuedItem.resolve = resolve;
+        queuedItem.reject = reject;
+      });
+      this._messageQueue.push(queuedItem);
+      // Agent busy, message queued
+      return promise;
+    }
+
+    // 空闲则直接处理
+    return this.chat(message, options);
+  }
+
+  /**
+   * 处理消息队列
+   * @private
+   */
+  async _processQueue() {
+    if (this._isProcessingQueue || this._messageQueue.length === 0) {
+      return;
+    }
+
+    this._isProcessingQueue = true;
+
+    // 强制设置为 idle，确保 this.chat() 能执行
+    this._status = 'idle';
+
+    while (this._messageQueue.length > 0) {
+      const item = this._messageQueue.shift();
+      try {
+        const result = await this.chat(item.message, item.options);
+        item.resolve(result);
+      } catch (err) {
+        item.reject(err);
+      }
+    }
+
+    this._isProcessingQueue = false;
+  }
+
+  /**
+   * 发送消息（流式）
+   */
+  async *chatStream(message, options = {}) {
+    if (this._status === 'busy') {
+      throw new Error('Agent is busy');
+    }
+
+    // 允许从 error 状态重试
+    if (this._status === 'error') {
+      this._status = 'idle';
+    }
+
+    this._status = 'busy';
+    this.emit('status', { status: 'busy' });
+
+    try {
+      // 检查是否有待处理的系统通知（调度 + 思考）
+      const notifications = this._getAllPendingNotifications();
+      let enhancedMessage = message;
+      if (notifications.length > 0) {
+        enhancedMessage = `【系统通知】\n${notifications.join('\n\n')}\n\n---\n用户消息: ${message}`;
+      }
+
+      this._syncTools();
+
+      yield* this._chatHandler.chatStream(enhancedMessage, options);
+      this._status = 'idle';
+      this.emit('status', { status: 'idle' });
+
+      // 处理队列中的下一条消息
+      setImmediate(() => this._processQueue());
+    } catch (err) {
+      this._status = 'error';
+      this.emit('status', { status: 'error', error: err.message });
+
+      // 发生错误时也要处理队列
+      setImmediate(() => this._processQueue());
+
+      throw err;
+    }
+  }
+
+  /**
+   * 设置元数据
+   */
+  setMetadata(keyOrObj, value) {
+    if (typeof keyOrObj === 'string') {
+      this._metadata.set(keyOrObj, value);
+    } else if (keyOrObj && typeof keyOrObj === 'object') {
+      for (const [key, val] of Object.entries(keyOrObj)) {
+        this._metadata.set(key, val);
+      }
+    }
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  /**
+   * 获取元数据
+   */
+  getMetadata(key) {
+    return this._metadata.get(key);
+  }
+
+  /**
+   * 删除元数据
+   */
+  deleteMetadata(key) {
+    this._metadata.delete(key);
+    this._refreshContext();
+    return this;
+  }
+
+  /**
+   * 清空元数据
+   */
+  clearMetadata() {
+    this._metadata.clear();
+    this._refreshContext();
+    return this;
+  }
+
+  /**
+   * 清空对话历史
+   */
+  clearHistory() {
+    if (this._chatHandler) {
+      this._chatHandler.clearHistory();
+    }
+    return this;
+  }
+
+  /**
+   * 获取状态
+   */
+  getStatus() {
+    return this._status;
+  }
+
+  /**
+   * 重置状态（从卡住状态恢复）
+   */
+  resetStatus() {
+    this._status = 'idle';
+    this.emit('status', { status: 'idle' });
+    return this;
+  }
+
+  /**
+   * 销毁 Agent
+   */
+  destroy() {
+    if (this._chatHandler) {
+      this._chatHandler.destroy();
+    }
+    this._tools.clear();
+    this.removeAllListeners();
+    this.emit('destroyed');
+  }
+}
+
+module.exports = { Agent };