让AI Agent自愈：axuse的6种类型化错误如何把失败从报错字符串变成可执行事实

【免费下载链接】axuseAccessibility-first browser computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies项目地址https://gitcode.com/gh_mirrors/ax/axuse点击查看免费下载axuse是一个面向 AI Agent 的浏览器与计算机操作 MCP 服务器——接入 Codex、Claude Code、OpenCode、Antigravity 等任意 MCP 宿主零依赖Node ≥ 22。它不靠截图拍照而是通过 CDP 直接测量 DOM 与可访问性树。而它最值得新手了解的正是本文的主题类型化错误typed errors。每一次失败都以结构化事实返回——错误码、修复提示、重试策略让 Agent 在失败后自动自愈而不是把一句报错字符串原样丢回给模型。为什么报错字符串会让 AI Agent 卡死先设想一个常见的 Agent 循环打开网页 → 点击按钮 → 读取变化 → 继续下一步。如果第 2 步失败传统工具只会返回类似Error: element not found的一行字符串。模型拿到后只能盲目重试——页面已经变了重试 10 次也是同样的失败猜测原因——把宝贵的 token 花在猜测上直接放弃——向用户汇报任务失败。而 axuse 的设计哲学写得很直白出自 src/core/errors.js 的注释一个盲目throw new Error(...)恰好丢失了 Agent 循环做重试、重新观察、还是放弃这个决策所需的全部信息——所以这里的每一次失败都是结构化事实而非字符串。一句话axuse 把发生了什么升级成了接下来该做什么。解剖一个类型化错误4 个字段就是全部每个 axuse 错误都是一个 AxError 对象序列化后只有 4 类信息{ code: REF_NOT_FOUND, message: ref \e7\ is gone (navigation or re-render)., hint: Call ax_observe, then act on fresh refs., retry: reobserve }字段含义对 Agent 的价值code冻结的错误码词汇表共 18 个核心/MCP 层/文档共享同一套机器可分支不靠自然语言理解message人类可读的原因日志与排查hint下一步该调用的工具和参数直接可执行的修复动作retry三选一reobserve重新观察/retry原样重试/never修输入或放弃Agent 的决策引擎这套词汇表定义在 src/core/errors.js 的Codes、Retry、ActionSent三个常量里并且被冻结Object.freeze——保证文档、MCP 层和插件说的同一种错误就是同一个码。6 种类型化错误及其自愈策略下面是新手最常遇到的 6 类错误。每一类都自带修复配方第 1 种引用失效与状态过期REF_NOT_FOUND / STALE_STATE场景你上一次观察页面时拿到了按钮[refe7]但页面随后重渲染了e7指向的元素已经不存在。retry: reobserve→ 调用ax_observe拿新引用再规划隐藏彩蛋axuse 检测到这类错误时会自动把当前页面的最新快照直接附在错误响应里见 src/core/controller.js并把提示改写为Its current state is included below: act on these refs; no ax_observe needed。Agent 连重新观察这一步都不用走下一轮直接点新引用——这是自愈最直接的体现。第 2 种对话框阻塞DIALOG_OPEN场景点击触发了 JS 的alert/confirm/prompt页面被冻结后续所有操作都会被拦截。hint明确告诉你用ax_dialogaccept | dismiss回答它然后重试原操作src/core/controller.js确认→提示链式弹窗也会逐个报告不会让 Agent 卡死在第一个上。第 3 种环境与启动失败NO_BROWSER / LAUNCH_FAILED / NO_TAB / COMMAND_REJECTED场景浏览器没找到、标签页已被关闭、或参数本身不合法。COMMAND_REJECTED由统一的参数校验层抛出src/core/commands.jsretry: never——意思是修调用别原样重试NO_TAB的提示会直接给出下一步Open one with ax_open first.这一类的价值在于区分了环境问题与调用错误避免 Agent 对着一个根本不存在的标签页反复点击。第 4 种超时与导航中TIMEOUT / NAVIGATION_IN_PROGRESS场景CDP 指令等待超时或页面正在跳转、此刻操作无意义。TIMEOUT带retry: retrysrc/core/cdp.js——同一调用现在很可能就能成功导航进行中被识别为独立错误码Agent 会先等导航结束而不是把半加载页面的状态当作事实。第 5 种预算超限SCREENSHOT_BUDGET_EXCEEDED场景整页截图超过了 axuse 在代码里强制的字节预算这是它成本可控设计的一部分。自愈动作改裁剪某个区域再截而不是整页重试——提示直接写明了方向。第 6 种权限与能力缺失DESKTOP_PERMISSION_REQUIRED / NO_SOLVER场景macOS 桌面操作缺少辅助功能授权或请求解验证码但没有加载对应插件。权限类错误会指路授予权限 → 跑axuse doctor确认 → 重试NO_SOLVER带安装提示把 solver 插件放入plugins/目录retry: never实现见 src/plugins/index.js。插件自身抛出的类型化错误如LICENSE_INVALID也能以同样结构透传给模型见 docs/plugins.md。 规律never类错误教你修输入retry类错误教你稍后再来reobserve类错误教你刷新认知。三种决策零猜测。第三维action_sent——重试前先确认点到了吗真正的自愈还差最后一块拼图一个带副作用的操作比如点击提交订单失败后这个动作到底发到页面没有如果发了盲目重试就是重复下单。axuse 用action_sent字段做副作用记账src/core/errors.js值含义Agent 该做什么sent确认送达正常继续possibly_sent发送后超时状态未知先验证状态再决定重试——输入可能已经生效not_sent未送达安全重试配合side_effect: none | uncertain标记Agent 在是否重放操作这个最危险的问题上拥有了确定性依据。这个机制出自 axuse 的设计谱系ZCode 的actionSent模式也是浏览器自动化里最容易踩坑的地方被提前堵死的地方。错误旅程从 throw 到模型眼前整条链路只有三步且每一步都不丢信息核心层抛出src/core/errors.js 的fail()抛带 code/hint/retry 的AxError失败点还能附上facts例如失败调用创建的tab_id让调用方还能关闭它MCP 层转成工具结果src/mcp/server.js 的errorContent()把类型化错误序列化为JSON 作为第一个内容块机器稳定消费若附带了页面最新快照则作为第二个纯文本块人类可读的引用列表模型读到的是事实宿主Codex / Claude Code 等收到的是一条isError: true的工具结果而不是协议级错误——模型像读普通返回值一样读它然后按retry决策。也就是说错误在 axuse 里从来不是异常而是带指令的返回值。新手上手3 步给你的 Agent 加上自愈能力 需要 Node 22 和一个 Chromium 系浏览器Chrome / Edge / Chromium / Chrome for Testinggit clone https://gitcode.com/gh_mirrors/ax/axuse cd axuse node src/cli.js doctor # 自动找浏览器、启动并抓取快照验证环境注册到宿主以 Claude Code 为例claude mcp add --scope user axuse -- node /绝对路径/axuse/src/cli.js mcp其他宿主用node src/cli.js print-config --harness codex或opencode/agy/generic打印可直接粘贴的配置块。之后正常下指令即可打开 example.com找到 More information 链接告诉我它指向哪里。Agent 会调用ax_open、读取带[refe7]的可访问性快照、按引用操作——而每当失败发生你看到的将是一句可以立即执行的修复指令而不是任务失败。小结把失败当作事实是 Agent 可靠性的分水岭对比项传统截图式工具axuse失败呈现模糊字符串数轮后才暴露误点类型化错误 retry提示 action_sent事实Agent 决策猜测 / 盲目重试 / 放弃按reobserve/retry/never精确分支恢复成本重新拍照整个页面错误里直接附带最新页面快照axuse 用 18 个冻结错误码、3 种重试策略和 1 套副作用记账回答了浏览器自动化最难的问题之一失败之后机器下一步做什么。如果你想了解完整的模型行为契约包括全部错误码的处理方式值得通读项目根目录的 SKILL.md 与 README.md 中的失败模式对比表核心实现全部在 src/core/测试覆盖见 test/mcp.test.js。赞分享【免费下载链接】axuseAccessibility-first browser computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies项目地址https://gitcode.com/gh_mirrors/ax/axuse点击查看免费下载相关推荐YimMenuV2GTA V模组菜单开发入门实战YimMenuV2GTA V模组菜单开发入门实战 想改 GTA V Enhanced 里的某个行为——让人物不掉血、让菜单按键弹出——却找不到下手的位置这正逆向工程Dagger TypeScript SDK ExecError 全解析管道执行失败的类型化错误处理实战Dagger TypeScript SDK ExecError 全解析管道执行失败的类型化错误处理实战 ExecError 是 Dagger TypeScriDevOpsCI/CD工作流自动化后端如何让Flow生成清晰易懂的类型错误信息提升JavaScript开发效率的终极指南如何让Flow生成清晰易懂的类型错误信息提升JavaScript开发效率的终极指南 Flow作为GitHub加速计划中的静态类型检查工具为JavaScrip开发工具静态分析代码质量上一篇从创建到上榜 61 天dsh-purge 的 7386 星与 15% fork 比拆开看下一篇ClawWork 经济生存协议SKILL.md深度解析AI Agent 的收支平衡、质量门槛与每日工作/学习循环实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考