技能介绍

在构建自动化浏览器工作流时，直接堆叠底层点击与快照操作往往脆弱不堪。页面状态一旦改变，元素索引就会失效；遇到登录、验证码或支付表单时，脚本极易越权填写敏感数据或卡死。MagicBrowse 正是为了解决这些“最后一公里”的导航难题而设计的。它不追求完全替代你的原生浏览器工具，而是作为一个带语义目标的导航器，在常规手段失效时安全地将浏览器带到目标页面。

核心机制与工作流

MagicBrowse 的核心在于 act 命令。不同于手动重放快照 ID，它接受自然语言描述的语义目标和可检查的终止条件。例如：magicbrowse act "navigate to the public page that lists supported regions and stop when the region list is visible"。内部 planner 通过双 LLM 循环在单一上下文中维持目标、页面状态和完成检查，避免了脆弱的 DOM 索引追踪。

它的标准工作流遵循严格的契约：

使用 magicbrowse launch <url> 启动并定位到初始页面。
连续调用 act 推进下一个战略性步骤（granule），保持会话状态与 planner 记忆。
任务完成或遇到边界时，执行 magicbrowse close 释放资源。

当语义导航遇到阻碍时，技能会按“降级阶梯”逐步回退：首先是你自带的浏览器工具，其次是 magicbrowse act（纯 DOM），接着是 --use-vision 视觉模式，最后才是 observe 结合 click、type 等底层原语。

适用边界与安全红线

尽管 MagicBrowse 具备强大的导航能力，但它在敏感操作面前设置了硬性边界。它绝不输入凭据、KYC 身份信息或支付卡号。当任务触及登录、结账、订阅或人机验证页面时，act 会返回 needs_handoff 状态，强制将控制权交还给用户或编排器，而不是试图绕过障碍。对于 CAPTCHA，它同样不会尝试破解，而是等待人工或外部求解器处理后调用 mark-captcha-resolved。

此外，使用时需注意：默认应使用全新的无头浏览器实例，避免附加到已登录的外部会话；若需并行运行多个工作流，必须为每个流程设置独立的 MAGICBROWSE_HOME 以避免单例冲突；在编排好的多步骤流程中，严禁使用带有内置关闭逻辑的 magicbrowse run。