browser-intent

Browser Intent

构建在底层 browser_* 选择器工具之上的自然语言层。browser-extract 和 browser-form-fill 会组合基于选择器的基本工具（browser_click、browser_fill、browser_snapshot），而 browser-intent 允许调用方直接描述需求（“点击登录按钮”“在搜索框中输入 cats 并提交”），并将执行委托给 page-agent——它会在页面中注入 JS，将 DOM 转换为文本，并通过 LLM 工具调用循环与之交互。

适用场景

• 目标元素用文字描述比可靠地选择它更容易（例如动态类名、结构不明确、经过 A/B 测试的标记）。
• 一次性操作，不值得编写一连串选择器。
• 如果已经知道确切的选择器或 ref（@e1），优先直接使用 browser_click / browser_fill / browser_snapshot——browser_act 会增加 LLM 延迟和成本，而直接调用选择器不会。

步骤

1. 调用 browser_act，传入 task 字符串，可选传入 url（先导航）和 session（默认值为 "default"）：

   mcp__plugin_ruflo-core_ruflo__browser_act({
     task: "Click the login button",
     url: "https://example.com/account",
     session: "my-session"
   })
   

2. 阅读响应约定：
   • { success: true, result, steps, history, contentFlagged, llmSource } — 意图已执行。result 是 page-agent 生成、经 AIDefence 把关后的最终文本；history 是完整的步骤轨迹（每步包含反思、操作和工具结果）；steps 等于 history.length。
   • { success: true, degraded: true, reason, hint } — 未安装 page-agent，或未配置兼容 OpenAI 的 LLM 提供方。绝不要将 degraded: true 视为可重试的错误——展示 hint，并改用基于选择器的 browser_* 工具。
   • { success: false, error, ... } — 发生了实际故障（打开浏览器失败、注入失败、执行超时，或 page-agent 自身的 execute() 报告 success:false）。
3. 当 contentFlagged: true 时，返回的 result 已由 AIDefence 脱敏（在 page-agent 输出中检测到了个人身份信息或提示词注入／威胁模式）——不要尝试还原原始文本。
4. 当交互需要留存以便日后重放时，优先使用已录制的会话（browser-record）；browser_act 本身不会打开 RVF 容器——它会在传入的会话 ID（或 "default"）上运行。

提供方要求（为何经常降级）

page-agent 会在浏览器页面上下文中，通过普通的兼容 OpenAI 的 POST {baseURL}/chat/completions 直接调用其 LLM。这意味着：

• 仅有 ANTHROPIC_API_KEY 并不足够——Anthropic 的原生 API 使用不同的格式（/v1/messages）。
• 请配置以下任一项：OPENROUTER_API_KEY（OpenRouter，兼容 OpenAI）、OLLAMA_API_KEY（Ollama Cloud，兼容 OpenAI），或用于自定义兼容 OpenAI 端点的 CLAUDE_FLOW_PAGE_AGENT_BASE_URL + CLAUDE_FLOW_PAGE_AGENT_API_KEY。
• 真实的提供方密钥绝不会进入页面：browser_act 会启动一个短生命周期的环回 HTTP 代理，由它在服务端保管密钥并自行注入真实的 Authorization 标头。页面始终只会看到一个 127.0.0.1 URL 和占位密钥字符串。

注意事项

• page-agent 是一项 optionalDependencies 条目（如果 doctor/降级提示要求安装，可运行 npm i page-agent）——此插件即使没有它也能完全正常运行；你只是会失去自然语言层，并回退到基于选择器的工具。
• 注入前会移除 npm 包中的演示自动初始化尾部代码（否则它会针对 Alibaba 的公共测试端点再创建一个 PageAgent 实例）——你不应看到此工具向 page-ag-testing-* 主机发送流量。
• 每次成功调用 browser_act，都会尽力将意图和由此产生的轨迹记录到 browser 记忆命名空间中（ADR-174 蒸馏循环）。此过程采用即发即弃方式——记忆存储失败不会导致工具调用失败。
• timeoutMs（默认值为 120000）限制 browser_act 轮询 execute() 直至完成的时长；执行缓慢的多步骤意图可能需要设置更高的值。