xshat-lite 1.0.0

package/src/modules/agent-executor.mjs

@@ -0,0 +1,1184 @@
+import fs from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import { exec as execCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execCallback);
+
+function normalizeAnswer(answer) {
+  return String(answer ?? '')
+    .trim()
+    .toLowerCase();
+}
+
+function isAffirmative(answer) {
+  return ['y', 'yes', 'ok', 'done', '是', '好', '执行', '确认'].includes(
+    normalizeAnswer(answer)
+  );
+}
+
+function isPathInside(rootDir, targetPath) {
+  const rel = relative(rootDir, targetPath);
+  return rel === '' || (!rel.startsWith('..') && !rel.includes(':'));
+}
+
+function resolveWorkspacePath(workspaceRoot, targetPath = '') {
+  const absolute = resolve(workspaceRoot, targetPath);
+
+  if (!isPathInside(workspaceRoot, absolute)) {
+    throw new Error(`目标路径超出工作区: ${targetPath}`);
+  }
+
+  return absolute;
+}
+
+function describeCommand(command) {
+  if (!command) {
+    return '执行模型建议的动作';
+  }
+
+  switch (command.name) {
+  case 'open_url':
+    return `打开链接 ${command.args?.url || ''}`.trim();
+  case 'send_message':
+    return `发送消息: ${command.args?.content || ''}`.trim();
+  case 'handoff':
+    return '切换到人工接管流程';
+  case 'run_shell':
+    return `执行系统命令: ${command.args?.command || ''}`.trim();
+  case 'read_file':
+    return `读取文件: ${command.args?.path || ''}`.trim();
+  case 'file_exists':
+    return `检查文件是否存在: ${command.args?.path || ''}`.trim();
+  case 'list_files':
+    return `列出目录: ${command.args?.path || '.'}`.trim();
+  case 'write_file':
+    return `写入文件: ${command.args?.path || ''}`.trim();
+  case 'delete_file':
+    return `删除文件: ${command.args?.path || ''}`.trim();
+  case 'read_agent_page':
+    return '读取当前 Agent 浏览器页面内容';
+  case 'send_agent_page':
+    return '读取 Agent 页面并发送给当前对话';
+  case 'get_app_state':
+    return '读取应用程序内部状态';
+  case 'focus_chat_input':
+    return '聚焦当前聊天输入框';
+  case 'send_chat_input':
+    return '向当前聊天输入框填写内容';
+  case 'submit_current_input':
+    return '提交当前聊天输入框内容';
+  case 'start_new_chat':
+    return '在当前提供方页面中新建对话';
+  case 'click_selector':
+    return `点击选择器: ${command.args?.selector || ''}`.trim();
+  case 'type_selector':
+    return `向选择器输入内容: ${command.args?.selector || ''}`.trim();
+  case 'wait_for_text':
+    return `等待页面文本出现: ${command.args?.text || ''}`.trim();
+  case 'extract_selector_text':
+    return `提取选择器文本: ${command.args?.selector || ''}`.trim();
+  case 'wait_for_selector':
+    return `等待选择器出现: ${command.args?.selector || ''}`.trim();
+  case 'wait_for_navigation':
+    return '等待页面导航完成';
+  case 'hover_selector':
+    return `悬停选择器: ${command.args?.selector || ''}`.trim();
+  case 'press_key':
+    return `按下按键: ${command.args?.key || ''}`.trim();
+  case 'check_checkbox':
+    return `勾选复选框: ${command.args?.selector || ''}`.trim();
+  case 'uncheck_checkbox':
+    return `取消勾选复选框: ${command.args?.selector || ''}`.trim();
+  case 'select_option':
+    return `选择下拉项: ${command.args?.selector || ''}`.trim();
+  case 'scroll_page':
+    return '滚动 Agent 页面';
+  case 'screenshot_agent_page':
+    return `保存 Agent 页面截图: ${command.args?.path || ''}`.trim();
+  case 'inspect_dom':
+    return `检查页面 DOM: ${command.args?.selector || 'body'}`.trim();
+  default:
+    return `执行命令 ${command.name}`;
+  }
+}
+
+function summarizeCommand(command) {
+  if (!command) {
+    return [];
+  }
+
+  switch (command.name) {
+  case 'open_url':
+    return [
+      { label: '操作', value: '打开链接' },
+      { label: '目标', value: command.args?.url || '(缺少 url)' }
+    ];
+  case 'send_message':
+    return [
+      { label: '操作', value: '发送消息' },
+      { label: '内容', value: command.args?.content || '(缺少 content)' }
+    ];
+  case 'handoff':
+    return [
+      { label: '操作', value: '人工接管' },
+      { label: '说明', value: '需要你手动完成页面交互' }
+    ];
+  case 'run_shell':
+    return [
+      { label: '操作', value: '系统命令' },
+      { label: '命令', value: command.args?.command || '(缺少 command)' }
+    ];
+  case 'read_file':
+    return [
+      { label: '操作', value: '读取文件' },
+      { label: '路径', value: command.args?.path || '(缺少 path)' }
+    ];
+  case 'file_exists':
+    return [
+      { label: '操作', value: '检查文件' },
+      { label: '路径', value: command.args?.path || '(缺少 path)' }
+    ];
+  case 'list_files':
+    return [
+      { label: '操作', value: '列出目录' },
+      { label: '路径', value: command.args?.path || '.' }
+    ];
+  case 'write_file':
+    return [
+      { label: '操作', value: '写入文件' },
+      { label: '路径', value: command.args?.path || '(缺少 path)' }
+    ];
+  case 'delete_file':
+    return [
+      { label: '操作', value: '删除文件' },
+      { label: '路径', value: command.args?.path || '(缺少 path)' }
+    ];
+  case 'read_agent_page':
+    return [
+      { label: '操作', value: '读取 Agent 页面' },
+      { label: '来源', value: 'agent 浏览器通道' }
+    ];
+  case 'send_agent_page':
+    return [
+      { label: '操作', value: '发送 Agent 页面' },
+      { label: '目标', value: '当前聊天上下文' }
+    ];
+  case 'get_app_state':
+    return [
+      { label: '操作', value: '读取应用状态' },
+      { label: '范围', value: 'provider / session / browser / agent 配置' }
+    ];
+  case 'focus_chat_input':
+    return [
+      { label: '操作', value: '聚焦聊天输入框' },
+      { label: '目标', value: '当前 provider 聊天页面' }
+    ];
+  case 'send_chat_input':
+    return [
+      { label: '操作', value: '填写聊天输入框' },
+      { label: '内容', value: command.args?.text || command.args?.content || '(空内容)' }
+    ];
+  case 'submit_current_input':
+    return [
+      { label: '操作', value: '提交输入框' },
+      { label: '目标', value: '当前 provider 聊天页面' }
+    ];
+  case 'start_new_chat':
+    return [
+      { label: '操作', value: '新建对话' },
+      { label: '目标', value: '当前 provider 聊天页面' }
+    ];
+  case 'click_selector':
+    return [
+      { label: '操作', value: '点击选择器' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'type_selector':
+    return [
+      { label: '操作', value: '输入内容' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'wait_for_text':
+    return [
+      { label: '操作', value: '等待文本' },
+      { label: '文本', value: command.args?.text || '(缺少 text)' }
+    ];
+  case 'extract_selector_text':
+    return [
+      { label: '操作', value: '提取文本' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'wait_for_selector':
+    return [
+      { label: '操作', value: '等待选择器' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'wait_for_navigation':
+    return [
+      { label: '操作', value: '等待导航' },
+      { label: '状态', value: command.args?.state || 'domcontentloaded' }
+    ];
+  case 'hover_selector':
+    return [
+      { label: '操作', value: '悬停选择器' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'press_key':
+    return [
+      { label: '操作', value: '按下按键' },
+      { label: '按键', value: command.args?.key || '(缺少 key)' }
+    ];
+  case 'check_checkbox':
+    return [
+      { label: '操作', value: '勾选复选框' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'uncheck_checkbox':
+    return [
+      { label: '操作', value: '取消勾选复选框' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'select_option':
+    return [
+      { label: '操作', value: '选择下拉项' },
+      { label: '选择器', value: command.args?.selector || '(缺少 selector)' }
+    ];
+  case 'scroll_page':
+    return [
+      { label: '操作', value: '滚动页面' },
+      { label: '目标', value: command.args?.selector || '窗口' }
+    ];
+  case 'screenshot_agent_page':
+    return [
+      { label: '操作', value: '保存截图' },
+      { label: '路径', value: command.args?.path || '(缺少 path)' }
+    ];
+  case 'inspect_dom':
+    return [
+      { label: '操作', value: '检查 DOM' },
+      { label: '根选择器', value: command.args?.selector || 'body' }
+    ];
+  default:
+    return [
+      { label: '操作', value: command.name },
+      { label: '参数', value: JSON.stringify(command.args || {}) }
+    ];
+  }
+}
+
+function getCommandRiskLevel(command) {
+  switch (command?.name) {
+  case 'delete_file':
+    return '高';
+  case 'write_file':
+  case 'run_shell':
+  case 'open_url':
+  case 'focus_chat_input':
+  case 'send_chat_input':
+  case 'submit_current_input':
+  case 'start_new_chat':
+  case 'type_selector':
+  case 'click_selector':
+  case 'press_key':
+  case 'check_checkbox':
+  case 'uncheck_checkbox':
+  case 'select_option':
+    return '中';
+  case 'handoff':
+    return '人工接管';
+  default:
+    return '低';
+  }
+}
+
+function getCommandTarget(command) {
+  switch (command?.name) {
+  case 'open_url':
+    return command.args?.url || '(缺少 url)';
+  case 'send_message':
+    return command.args?.content || '(缺少 content)';
+  case 'run_shell':
+    return command.args?.command || '(缺少 command)';
+  case 'read_file':
+  case 'file_exists':
+  case 'list_files':
+  case 'write_file':
+  case 'delete_file':
+  case 'screenshot_agent_page':
+    return command.args?.path || '(缺少 path)';
+  case 'click_selector':
+  case 'type_selector':
+  case 'wait_for_selector':
+  case 'hover_selector':
+  case 'check_checkbox':
+  case 'uncheck_checkbox':
+  case 'select_option':
+  case 'extract_selector_text':
+    return command.args?.selector || '(缺少 selector)';
+  case 'wait_for_text':
+    return command.args?.text || '(缺少 text)';
+  case 'press_key':
+    return command.args?.key || '(缺少 key)';
+  case 'inspect_dom':
+    return command.args?.selector || 'body';
+  case 'scroll_page':
+    return command.args?.selector || `y=${command.args?.y ?? 0}`;
+  case 'get_app_state':
+    return 'provider / session / browser / agent';
+  case 'focus_chat_input':
+  case 'submit_current_input':
+  case 'start_new_chat':
+    return '当前 provider 聊天页面';
+  case 'send_chat_input':
+    return command.args?.text || command.args?.content || '(空内容)';
+  case 'read_agent_page':
+  case 'send_agent_page':
+    return 'agent 浏览器通道';
+  case 'handoff':
+    return '需要用户继续操作';
+  default:
+    return JSON.stringify(command?.args || {});
+  }
+}
+
+function getCommandNextHint(command) {
+  switch (command?.name) {
+  case 'open_url':
+    return '可能继续等待页面加载、提取文本或点击元素';
+  case 'run_shell':
+    return '可能继续读取命令输出，或再修改文件/执行下一步';
+  case 'file_exists':
+  case 'list_files':
+  case 'read_file':
+    return '通常会基于本地结果继续追问或执行下一步';
+  case 'read_agent_page':
+  case 'extract_selector_text':
+  case 'inspect_dom':
+  case 'get_app_state':
+  case 'focus_chat_input':
+  case 'send_chat_input':
+  case 'start_new_chat':
+    return '通常会基于观察结果继续决策下一步';
+  case 'submit_current_input':
+    return '会等待模型下一轮回复';
+  case 'send_agent_page':
+  case 'send_message':
+    return '会等待模型下一轮回复';
+  case 'write_file':
+  case 'delete_file':
+    return '可能继续验证文件结果或执行相关命令';
+  case 'handoff':
+    return '等待你在浏览器中完成登录、验证或人工操作';
+  default:
+    return '可能继续执行更多自动化步骤';
+  }
+}
+
+function buildConfirmationRows(command, { autoExecuteCommands = false } = {}) {
+  return [
+    { label: '当前动作', value: describeCommand(command) },
+    { label: '风险级别', value: getCommandRiskLevel(command) },
+    { label: '目标对象', value: getCommandTarget(command) },
+    { label: '自动执行', value: autoExecuteCommands ? '开启' : '关闭' },
+    { label: '后续可能', value: getCommandNextHint(command) },
+    ...summarizeCommand(command)
+  ];
+}
+
+function normalizeBrowserCommandArgs(command = {}) {
+  const args = {
+    ...(command.args || {})
+  };
+
+  if (command.name === 'type_selector') {
+    if (args.pressEnter === undefined && args.submit === undefined) {
+      const text = String(args.text ?? args.content ?? '');
+      if (text.includes('\n') === false) {
+        args.pressEnter = false;
+      }
+    }
+
+    if (!args.retryCount) {
+      args.retryCount = 2;
+    }
+  }
+
+  if (command.name === 'click_selector') {
+    if (!args.retryCount) {
+      args.retryCount = 3;
+    }
+  }
+
+  return args;
+}
+
+export class AgentExecutor {
+  constructor({
+    browserManager,
+    ui,
+    prompt,
+    sendMessage,
+    getAppState,
+    workspaceRoot,
+    allowShell = true,
+    allowFileWrite = true,
+    autoExecuteCommands = false,
+    fsModule = fs,
+    execImpl = exec
+  }) {
+    this.browserManager = browserManager;
+    this.ui = ui;
+    this.prompt = prompt;
+    this.sendMessage = sendMessage;
+    this.getAppState = getAppState;
+    this.workspaceRoot = workspaceRoot;
+    this.allowShell = allowShell;
+    this.allowFileWrite = allowFileWrite;
+    this.autoExecuteCommands = autoExecuteCommands;
+    this.fs = fsModule;
+    this.execImpl = execImpl;
+  }
+
+  getBrowserCommandChannel(command = {}) {
+    const requested = String(command.args?.channel || '').trim().toLowerCase();
+    if (requested === 'chat' || requested === 'agent') {
+      return requested;
+    }
+
+    if (typeof this.browserManager?.isChannelReady === 'function') {
+      if (this.browserManager.isChannelReady('agent')) {
+        return 'agent';
+      }
+
+      if (this.browserManager.isChannelReady('chat')) {
+        return 'chat';
+      }
+    }
+
+    return 'agent';
+  }
+
+  async ensureBrowserCommandChannel(command = {}) {
+    const channel = this.getBrowserCommandChannel(command);
+
+    if (
+      channel === 'chat' &&
+      !this.browserManager?.isChannelReady?.('chat') &&
+      typeof this.browserManager?.initChannel === 'function'
+    ) {
+      await this.browserManager.initChannel('chat');
+    }
+
+    return channel;
+  }
+
+  buildRecoverableErrorResult(command, error) {
+    const message = String(error?.message || error || '').trim();
+    const recoverable = [
+      'Element is not visible',
+      'element is outside of the viewport',
+      'another element',
+      'intercepts pointer events',
+      'not attached to the DOM',
+      'detached from document',
+      'timeout'
+    ].some((pattern) => message.toLowerCase().includes(pattern.toLowerCase()));
+
+    return {
+      ok: false,
+      error: message || '命令执行失败',
+      recoverable,
+      commandName: command?.name || '',
+      output: JSON.stringify(
+        {
+          command: command?.name || '',
+          args: command?.args || {},
+          recoverable,
+          error: message || '命令执行失败'
+        },
+        null,
+        2
+      )
+    };
+  }
+
+  requiresManualApproval(command) {
+    return ![
+      'get_app_state',
+      'file_exists',
+      'list_files',
+      'read_file',
+      'focus_chat_input',
+      'send_chat_input',
+      'submit_current_input'
+    ].includes(
+      command?.name
+    );
+  }
+
+  async confirm(command) {
+    if (!this.requiresManualApproval(command)) {
+      return true;
+    }
+
+    if (this.ui?.printKeyValueTable) {
+      this.ui.printKeyValueTable(
+        '待确认操作',
+        buildConfirmationRows(command, {
+          autoExecuteCommands: this.autoExecuteCommands
+        })
+      );
+    } else if (this.ui?.printInfo) {
+      this.ui.printInfo(describeCommand(command));
+    }
+
+    const question = `${describeCommand(command)}，是否执行？(y/n) `;
+    const answer = await this.prompt(question);
+    return isAffirmative(answer);
+  }
+
+  shouldContinue(result) {
+    if (!result?.ok) {
+      return false;
+    }
+
+    if (result.handoff) {
+      return false;
+    }
+
+    if (result.commandName === 'send_message') {
+      return false;
+    }
+
+    if (result.commandName === 'handoff') {
+      return false;
+    }
+
+    if (typeof result.message === 'string' && /已发送消息/.test(result.message)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  evaluateCompletion(result) {
+    if (!result?.ok) {
+      return {
+        status: 'error',
+        reason: result?.error || '命令执行失败'
+      };
+    }
+
+    if (result.handoff) {
+      return {
+        status: 'handoff',
+        reason: result.message || '需要人工介入'
+      };
+    }
+
+    if (result.commandName === 'send_message') {
+      return {
+        status: 'completed',
+        reason: '消息已经发送给目标模型'
+      };
+    }
+
+    if (
+      [
+        'get_app_state',
+        'read_agent_page',
+        'inspect_dom',
+        'extract_selector_text',
+        'focus_chat_input',
+        'send_chat_input',
+        'start_new_chat'
+      ].includes(
+        result.commandName
+      )
+    ) {
+      return {
+        status: 'continue',
+        reason: '已获得新的观察结果，适合继续决策'
+      };
+    }
+
+    return {
+      status: this.shouldContinue(result) ? 'continue' : 'completed',
+      reason: this.shouldContinue(result)
+        ? '动作已执行，建议结合结果继续判断'
+        : '当前动作已完成'
+    };
+  }
+
+  async execute(command) {
+    if (!command?.name) {
+      return {
+        ok: false,
+        error: '缺少命令名称'
+      };
+    }
+
+    try {
+      switch (command.name) {
+      case 'open_url': {
+        const url = command.args?.url;
+        if (!url) {
+          return { ok: false, error: '缺少 url 参数' };
+        }
+
+        if (typeof this.browserManager.openAgentPage === 'function') {
+          await this.browserManager.openAgentPage(url);
+        } else {
+          await this.browserManager.goto(url);
+        }
+        return { ok: true, message: `已打开 ${url}`, commandName: command.name };
+      }
+
+      case 'send_message': {
+        const content = command.args?.content;
+        if (!content) {
+          return { ok: false, error: '缺少 content 参数' };
+        }
+
+        if (typeof this.sendMessage !== 'function') {
+          return { ok: false, error: '发送能力未注入' };
+        }
+
+        await this.sendMessage(content);
+        return { ok: true, message: '已发送消息', commandName: command.name };
+      }
+
+      case 'handoff': {
+        return {
+          ok: true,
+          handoff: true,
+          message: '请使用 /agent 进入人工接管',
+          commandName: command.name
+        };
+      }
+
+      case 'run_shell': {
+        if (!this.allowShell) {
+          return { ok: false, error: '当前配置禁止执行系统命令' };
+        }
+
+        const shellCommand = command.args?.command;
+        if (!shellCommand) {
+          return { ok: false, error: '缺少 command 参数' };
+        }
+
+        const result = await this.execImpl(shellCommand, {
+          cwd: this.workspaceRoot
+        });
+        return {
+          ok: true,
+          message: '系统命令执行完成',
+          commandName: command.name,
+          output: [result.stdout, result.stderr].filter(Boolean).join('\n').trim()
+        };
+      }
+
+      case 'read_file': {
+        const filePath = command.args?.path;
+        if (!filePath) {
+          return { ok: false, error: '缺少 path 参数' };
+        }
+
+        const absolute = resolveWorkspacePath(this.workspaceRoot, filePath);
+        const content = await this.fs.readFile(absolute, 'utf-8');
+        return {
+          ok: true,
+          message: `已读取 ${filePath}`,
+          commandName: command.name,
+          output: content
+        };
+      }
+
+      case 'file_exists': {
+        const filePath = command.args?.path;
+        if (!filePath) {
+          return { ok: false, error: '缺少 path 参数' };
+        }
+
+        const absolute = resolveWorkspacePath(this.workspaceRoot, filePath);
+        let exists = true;
+        try {
+          await this.fs.access(absolute);
+        } catch {
+          exists = false;
+        }
+
+        return {
+          ok: true,
+          message: exists ? `已确认 ${filePath} 存在` : `已确认 ${filePath} 不存在`,
+          commandName: command.name,
+          output: exists ? `存在: ${filePath}` : `不存在: ${filePath}`,
+          exists
+        };
+      }
+
+      case 'list_files': {
+        const dirPath = command.args?.path || '.';
+        const absolute = resolveWorkspacePath(this.workspaceRoot, dirPath);
+        const entries = await this.fs.readdir(absolute, { withFileTypes: true });
+        const output = entries
+          .sort((left, right) => left.name.localeCompare(right.name, 'zh-CN'))
+          .map((entry) => `${entry.isDirectory() ? '[DIR] ' : ''}${entry.name}`)
+          .join('\n');
+        return {
+          ok: true,
+          message: `已列出 ${dirPath} 下的文件`,
+          commandName: command.name,
+          output
+        };
+      }
+
+      case 'write_file': {
+        if (!this.allowFileWrite) {
+          return { ok: false, error: '当前配置禁止写入文件' };
+        }
+
+        const filePath = command.args?.path;
+        const content = String(command.args?.content ?? '');
+
+        if (!filePath) {
+          return { ok: false, error: '缺少 path 参数' };
+        }
+
+        const absolute = resolveWorkspacePath(this.workspaceRoot, filePath);
+        await this.fs.mkdir(resolve(absolute, '..'), { recursive: true });
+        await this.fs.writeFile(absolute, content, 'utf-8');
+        return {
+          ok: true,
+          message: `已写入 ${filePath}`,
+          commandName: command.name
+        };
+      }
+
+      case 'delete_file': {
+        if (!this.allowFileWrite) {
+          return { ok: false, error: '当前配置禁止删除文件' };
+        }
+
+        const filePath = command.args?.path;
+        if (!filePath) {
+          return { ok: false, error: '缺少 path 参数' };
+        }
+
+        const absolute = resolveWorkspacePath(this.workspaceRoot, filePath);
+        await this.fs.rm(absolute, { force: true, recursive: true });
+        return {
+          ok: true,
+          message: `已删除 ${filePath}`,
+          commandName: command.name
+        };
+      }
+
+      case 'read_agent_page': {
+        if (typeof this.browserManager.readChannelSnapshot !== 'function') {
+          return { ok: false, error: '当前浏览器管理器不支持页面读取' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        const snapshot = await this.browserManager.readChannelSnapshot(channel, {
+          includeDomSummary: true,
+          includeObservation: true,
+          maxChars: 2500
+        });
+        return {
+          ok: true,
+          message: `已读取${channel === 'agent' ? 'Agent' : '当前聊天'}页面`,
+          commandName: command.name,
+          output: [
+            `Title: ${snapshot.title}`,
+            `URL: ${snapshot.url}`,
+            '',
+            snapshot.text,
+            snapshot.observation
+              ? `\n最近观测:\n${JSON.stringify(snapshot.observation, null, 2)}`
+              : '',
+            Array.isArray(snapshot.dom) && snapshot.dom.length > 0
+              ? `\nDOM 摘要:\n${JSON.stringify(snapshot.dom, null, 2)}`
+              : ''
+          ]
+            .filter(Boolean)
+            .join('\n')
+            .trim(),
+          silentOutput: true
+        };
+      }
+
+      case 'send_agent_page': {
+        if (typeof this.browserManager.readChannelSnapshot !== 'function') {
+          return { ok: false, error: '当前浏览器管理器不支持页面读取' };
+        }
+
+        if (typeof this.sendMessage !== 'function') {
+          return { ok: false, error: '发送能力未注入' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        const snapshot = await this.browserManager.readChannelSnapshot(channel, {
+          includeDomSummary: true,
+          includeObservation: true,
+          maxChars: 2500
+        });
+        const content = [
+          '以下是你刚刚打开的网页内容与观测结果，请基于这些内容继续判断并给出下一步：',
+          `Title: ${snapshot.title}`,
+          `URL: ${snapshot.url}`,
+          '',
+          snapshot.text,
+          snapshot.observation
+            ? `\n最近观测(JSON):\n${JSON.stringify(snapshot.observation, null, 2)}`
+            : '',
+          Array.isArray(snapshot.dom) && snapshot.dom.length > 0
+            ? `\nDOM 摘要(JSON):\n${JSON.stringify(snapshot.dom, null, 2)}`
+            : ''
+        ].join('\n');
+
+        await this.sendMessage(content);
+        return {
+          ok: true,
+          message:
+            channel === 'agent'
+              ? '已将 Agent 页面内容发送给当前对话'
+              : '已将当前聊天页面内容发送给当前对话',
+          commandName: command.name
+        };
+      }
+
+      case 'get_app_state': {
+        if (typeof this.getAppState !== 'function') {
+          return { ok: false, error: '应用状态读取能力未注入' };
+        }
+
+        const state = this.getAppState();
+        return {
+          ok: true,
+          message: '已读取应用状态',
+          commandName: command.name,
+          output: JSON.stringify(state, null, 2),
+          silentOutput: true
+        };
+      }
+
+      case 'focus_chat_input': {
+        const chatManager = this.browserManager?.getChatManager?.();
+        if (!chatManager?.focusInput) {
+          return { ok: false, error: '当前聊天管理器不支持聚焦输入框' };
+        }
+
+        const selector = await chatManager.focusInput();
+        return {
+          ok: true,
+          message: '已聚焦当前聊天输入框',
+          commandName: command.name,
+          output: selector,
+          silentOutput: true
+        };
+      }
+
+      case 'send_chat_input': {
+        const chatManager = this.browserManager?.getChatManager?.();
+        if (!chatManager?.typeInInput) {
+          return { ok: false, error: '当前聊天管理器不支持填写输入框' };
+        }
+
+        const selector = await chatManager.typeInInput(
+          command.args?.text ?? command.args?.content ?? '',
+          command.args || {}
+        );
+        return {
+          ok: true,
+          message: '已填写当前聊天输入框',
+          commandName: command.name,
+          output: selector,
+          silentOutput: true
+        };
+      }
+
+      case 'submit_current_input': {
+        const chatManager = this.browserManager?.getChatManager?.();
+        if (!chatManager?.submitInput) {
+          return { ok: false, error: '当前聊天管理器不支持提交输入框' };
+        }
+
+        const target = await chatManager.submitInput();
+        return {
+          ok: true,
+          message: '已提交当前聊天输入框内容',
+          commandName: command.name,
+          output: String(target || ''),
+          silentOutput: true
+        };
+      }
+
+      case 'start_new_chat': {
+        const chatManager = this.browserManager?.getChatManager?.();
+        if (!chatManager?.startNewChat) {
+          return { ok: false, error: '当前聊天管理器不支持新建对话' };
+        }
+
+        const selector = await chatManager.startNewChat();
+        return {
+          ok: true,
+          message: '已尝试在当前提供方页面中新建对话',
+          commandName: command.name,
+          output: String(selector || ''),
+          silentOutput: true
+        };
+      }
+
+      case 'click_selector': {
+        const selector = command.args?.selector;
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        const actionArgs = normalizeBrowserCommandArgs(command);
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.clickSelector(channel, selector, actionArgs);
+        return {
+          ok: true,
+          message: `已点击 ${selector}`,
+          commandName: command.name
+        };
+      }
+
+      case 'type_selector': {
+        const selector = command.args?.selector;
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        const actionArgs = normalizeBrowserCommandArgs(command);
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.typeSelector(
+          channel,
+          selector,
+          command.args?.text ?? command.args?.content ?? '',
+          actionArgs
+        );
+        return {
+          ok: true,
+          message: `已向 ${selector} 输入内容`,
+          commandName: command.name
+        };
+      }
+
+      case 'wait_for_text': {
+        const text = command.args?.text;
+        if (!text) {
+          return { ok: false, error: '缺少 text 参数' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.waitForText(channel, text, command.args || {});
+        return {
+          ok: true,
+          message: `已等到文本出现: ${text}`,
+          commandName: command.name
+        };
+      }
+
+      case 'extract_selector_text': {
+        const selector = command.args?.selector;
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        const output = await this.browserManager.extractSelectorText(
+          channel,
+          selector,
+          command.args || {}
+        );
+        return {
+          ok: true,
+          message: `已提取 ${selector} 的文本`,
+          commandName: command.name,
+          output: Array.isArray(output) ? output.join('\n\n') : String(output),
+          silentOutput: true
+        };
+      }
+
+      case 'wait_for_selector': {
+        const selector = command.args?.selector;
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.waitForSelector(channel, selector, command.args || {});
+        return {
+          ok: true,
+          message: `已等到选择器出现: ${selector}`,
+          commandName: command.name
+        };
+      }
+
+      case 'wait_for_navigation': {
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.waitForNavigation(channel, command.args || {});
+        return {
+          ok: true,
+          message: '已等待页面导航完成',
+          commandName: command.name
+        };
+      }
+
+      case 'hover_selector': {
+        const selector = command.args?.selector;
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.hoverSelector(channel, selector, command.args || {});
+        return {
+          ok: true,
+          message: `已悬停 ${selector}`,
+          commandName: command.name
+        };
+      }
+
+      case 'press_key': {
+        const key = command.args?.key;
+        if (!key) {
+          return { ok: false, error: '缺少 key 参数' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.pressKey(channel, key, command.args || {});
+        return {
+          ok: true,
+          message: `已按下按键: ${key}`,
+          commandName: command.name
+        };
+      }
+
+      case 'check_checkbox': {
+        const selector = command.args?.selector;
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.setCheckbox(channel, selector, true, command.args || {});
+        return {
+          ok: true,
+          message: `已勾选 ${selector}`,
+          commandName: command.name
+        };
+      }
+
+      case 'uncheck_checkbox': {
+        const selector = command.args?.selector;
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.setCheckbox(channel, selector, false, command.args || {});
+        return {
+          ok: true,
+          message: `已取消勾选 ${selector}`,
+          commandName: command.name
+        };
+      }
+
+      case 'select_option': {
+        const selector = command.args?.selector;
+        const value =
+        command.args?.value ??
+        command.args?.label ??
+        command.args?.index;
+
+        if (!selector) {
+          return { ok: false, error: '缺少 selector 参数' };
+        }
+
+        if (value === undefined || value === null || value === '') {
+          return { ok: false, error: '缺少 value/label/index 参数' };
+        }
+
+        let optionValue = value;
+        if (command.args?.label) {
+          optionValue = { label: String(command.args.label) };
+        } else if (command.args?.index !== undefined) {
+          optionValue = { index: Number(command.args.index) };
+        } else {
+          optionValue = { value: String(command.args.value ?? value) };
+        }
+
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.selectOption(channel, selector, optionValue, command.args || {});
+        return {
+          ok: true,
+          message: `已选择 ${selector} 的下拉项`,
+          commandName: command.name
+        };
+      }
+
+      case 'scroll_page': {
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.scrollPage(channel, command.args || {});
+        return {
+          ok: true,
+          message: '已滚动 Agent 页面',
+          commandName: command.name
+        };
+      }
+
+      case 'screenshot_agent_page': {
+        if (!this.allowFileWrite) {
+          return { ok: false, error: '当前配置禁止写入截图文件' };
+        }
+
+        const filePath = command.args?.path;
+        if (!filePath) {
+          return { ok: false, error: '缺少 path 参数' };
+        }
+
+        const absolute = resolveWorkspacePath(this.workspaceRoot, filePath);
+        await this.fs.mkdir(resolve(absolute, '..'), { recursive: true });
+        const channel = await this.ensureBrowserCommandChannel(command);
+        await this.browserManager.screenshotChannel(channel, {
+          ...command.args,
+          path: absolute
+        });
+        return {
+          ok: true,
+          message: `已保存截图到 ${filePath}`,
+          commandName: command.name
+        };
+      }
+
+      case 'inspect_dom': {
+        const channel = await this.ensureBrowserCommandChannel(command);
+        const output = await this.browserManager.inspectDom(channel, command.args || {});
+        return {
+          ok: true,
+          message: '已读取页面 DOM 结构',
+          commandName: command.name,
+          output: JSON.stringify(output, null, 2),
+          silentOutput: true
+        };
+      }
+
+      default:
+        return {
+          ok: false,
+          error: `暂不支持命令: ${command.name}`
+        };
+      }
+    } catch (error) {
+      return this.buildRecoverableErrorResult(command, error);
+    }
+  }
+}
+
+export { describeCommand, resolveWorkspacePath, summarizeCommand };
+export default AgentExecutor;