by 运行时依赖
安装命令
点击复制技能文档
当自有浏览器工具无法可靠抵达目标页面时，使用 magicbrowse。规划器每个任务跑两轮 LLM，比直接浏览器控制慢；工具够用就别用 magicbrowse。 用 magicbrowse 抵达目标页（搜索、填表、多步导航），再交给 magicpay 处理受保护步骤。
安装检查
首次安装先跑 magicbrowse doctor，验证共享 MagicPay 网关配置与可达性。
失败则执行 magicbrowse init （在 https://agents.mercuryo.io/signup 注册），或设置环境变量 MAGICPAY_API_KEY。
持久化配置保存在 ~/.magicpay/config.json，与 magicpay skill 共享。
doctor 通过后再启动与操作。
硬规则 MagicPay 边界：任何页面上的登录/注册凭据（邮箱、用户名、密码、OTP）、身份文件字段（护照、身份证、KYC 地址、出生日期）、支付卡或银行字段（PAN、CVV、有效期、IBAN、账户）、任何来自 vault 或 secret store 的值，一律不得用 act、type、fill、select。 到表单边界即停，切到 magicpay skill。
target-id 仅对生成它的 observe 快照有效。 任何 click、type、导航、弹窗、懒加载后必须重新 observe，再使用新 id。 ✓ observe → click 12 → observe → type 7 "hello" ✗ observe → click 12 → type 7 "hello"
一个 MAGICBROWSE_HOME 对应一个工作流。
$MAGICBROWSE_HOME/current-session.json（默认 ~/.magicbrowse/）是单例，同一 home 并发会互相覆盖。
并行请为每个工作流设独立 MAGICBROWSE_HOME。
主工作流契约
launch [url] → act … act → close
同一会话内顺序 act 保持页面状态与规划器记忆。
magicbrowse launch —— 启动专属 Chrome 会话并定位到入口 URL。
--headful 取消无头模式。
如需接入已有 CDP 浏览器：magicbrowse attach （位置参数，非 --cdp-url 旗标）。
magicbrowse act "" —— 提示驱动的自主步。
act 不接受 --url，内部无法重置页面；需重定位就 close 再 launch。
重复 act 进入下一战略颗粒。
magicbrowse close —— 完成后释放会话。
CLI 的 magicbrowse run 仅供一次性开发，自带 close 会破坏连续性，勿在编排流程中使用。
回退阶梯（按顺序，别直接跳到第 4 层）
- 自有浏览器工具（Computer Use、原生浏览器工具）
magicbrowse act ""—— 纯 DOM 导航magicbrowse act "" --use-vision—— 同目标，带截图导航。Vision 是同一任务的重试模式，颗粒不变。magicbrowse observe + 原语—— click 、type 、fill 、select 、press 。
目标颗粒 颗粒 = 原子战略段。 每个 act 结束于编排器需做下一步战略决策之处。 战术（先填哪个字段）在 act 内；战略（换合作方）在 act 间。 每 act 15–30 导航步为宜，越小越安全；maxSteps=100 为安全上限。 无法外部核验成功标准时，用更小颗粒。
认证墙与验证码是硬边界，非障碍。 任务规划到认证即停，状态 completed，提示需登录，不算失败。
依赖会话记忆，勿重复叙述。 顺序 act 保持页面状态与规划器记忆。 若需在目标里写“如前所述”，说明颗粒过大。
目标表述 禁止出现元素索引或选择器。 ✗ act "click target 14" ✓ act "点击价格汇总下方的‘继续’按钮”
给出可校验的终态描述： ✗ act "get to checkout" ✓ act "导航到显示乘客信息栏与总票价的 checkout 页"
URL 传给 launch，不作为独立步骤。 中途换站：要么 close 后重 launch，要么在目标里描述导航。
常见错误
- 目标文本里写元素索引（[14]、target 7）
- 编排流程用
magicbrowse run - 在受保护字段上用 type/fill/select/act，而非切到 magicpay