企业官网建设流程全解析

BrowserSkill错误码速查手册：cdp_failed、timeout、cancelled常见错误一次看懂

【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI + extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill

BrowserSkill 是一款让 AI Agent 直接操作你真实、已登录浏览器的浏览器自动化工具：bsk命令行 + 浏览器扩展协同工作，驱动 Chrome/Edge 完成点击、填表、截图、长截图等任务。当自动化失败时，终端会抛出一个结构化错误码。本手册带你一次看懂cdp_failed、timeout、cancelled等全部 13 个错误码的含义、退出码分类与修复方法，遇到报错不再摸不着头脑。

🧭 30秒看懂：BrowserSkill错误码体系怎么设计的

BrowserSkill 的报错不是"一锅粥"，而是三件套：

1. 错误码（code）：13 个稳定枚举值，如cdp_failed、timeout，定义在 crates/bsk-protocol/src/error.rs；
2. 退出码（exit code）：0~5 五档，方便脚本判断"谁的锅"；
3. 修复提示（hint）：每个错误码都内置一句可操作的修复建议。

退出码分档规则（设计文档 §3.1）一目了然：

这张"错误码 → 退出码 → 提示语"的对照表由 crates/bsk-cli/src/cli/render_error.rs 统一维护，并配有单元测试锁定映射关系（render_error.rs 测试），所以你可以放心地依赖它。

📊 13 个错误码总表：一张表全记住

🎯 cdp_failed：浏览器拒绝了你的请求（退出码 3）

这是自动化场景里最"经典"的报错。它的通用含义是"browser rejected the underlying CDP call"（浏览器拒绝了底层 Chrome DevTools Protocol 调用），官方提示：

hint: confirm the tab is still in a loaded state and retry; reloading the tab usually resets a stuck DevTools session （确认标签页仍处于已加载状态并重试；重载标签页通常能重置卡住的 DevTools 会话）

真正的"病因"藏在data.reason字段里，常见子场景：

⏱️ timeout：操作超时了（退出码 4）

通用提示是：重试命令；如果超时持续出现，用bsk logs排查并确认浏览器仍在响应。但timeout也有"子病因"：

🚫 cancelled 与 user_aborted：取消不是失败（退出码 2）

cancelled的提示是："the previous command was interrupted (Ctrl-C or a remotecancelrequest)"——上一条命令被 Ctrl-C 或远程cancel请求打断了。它代表流程被中断，不代表执行出错，退出码为 2。

与它容易混淆的两个近亲：

• user_aborted（退出码 2）：用户在界面上主动请求了打断（比如点了 Agent Window 的停止按钮），提示会写明"若非误操作可重跑"；
• screenshot_user_cancelled（cancelled的一个 reason）：整页截图被用户输入取消，官方明确提示"respect the interruption; do not automatically retry"——尊重中断，不要自动重试。

⚠️关键原则——看effect_state再决定重试。错误载荷里的data.effect_state字段有三个值：

• none：动作完全没生效，可以安全重试；
• unknown：不确定是否已生效，禁止盲目重试，先观察页面；
• committed：动作已生效，直接检查结果即可。

这也是官方提示中反复出现 "do not repeat the input / do not retry" 的原因——对自动化来说，重复执行比失败更危险。

📡 其他高频错误码：连接类问题排查

no_browser_connected（退出码 1）：守护进程找不到任何已连接浏览器。修复方法写在提示里——打开浏览器里的 BrowserSkill 扩展，等弹窗显示"已连接"（READY）：

multiple_browsers_online（退出码 1）：多个浏览器同时在线，CLI 不知道听谁的。用--browser <instance_id-or-label>指定目标，或先跑bsk browsers列出在线浏览器。

invalid_params/not_found/permission_denied（退出码 1）：这一档都是"用户输入"问题，常见 reason：

• ref_not_found：观察引用（ref）失效 → 对当前标签页重跑bsk observe使用新引用；
• selector_not_found：CSS 选择器没匹配到元素 → 核对选择器或等元素出现；
• element_not_visible：目标元素没有可见几何 → 重跑 snapshot 选一个可见的子元素，或等待/滚动/重载后再试；
• borrow_conflict：标签页正被另一个会话借用 → 让借出方bsk tab return <tab-id> --session <id>归还；
• target_not_fillable/target_not_select：目标不是可填输入框 / 不是<select>→ 观察页面后改用正确的操作指令。

protocol_error/unknown_method/version_too_old（退出码 2/5）：都是"版本漂移"症状——CLI、守护进程、扩展三者版本不齐。unknown_method是典型的"方法形状不匹配"，把bskCLI 与浏览器扩展一起升级、并用bsk daemon restart重启守护进程即可。

🖥️ 怎么读终端里的报错：error / hint / details 三行结构

人类可读模式下，每条错误固定输出三段（渲染逻辑见 crates/bsk-cli/src/cli/error.rs）：

error: target element has no visible geometry hint: rerun snapshot and choose a visible child ref, or wait/scroll/reload before retrying details: element not visible (no content quads)

• error:友好的一行总结（来自上面那张对照表）；
• hint:可执行的修复建议；
• details:守护进程的原始细节，给需要深挖上下文的人看。

如果你没看到error:而是收到类似 "daemon unreachable" 的传输层报错（退出码 2），提示会直接告诉你："is the daemon running? trybsk daemon startorbsk status"——守护进程没起来，这是最容易被忽视的第一步。

脚本场景请加--json，输出为扁平结构，方便jq处理：

{ "code": "multiple_browsers_online", "message": "more than one browser", "hint": "use `--browser <instance_id-or-label>` to target a specific browser (run `bsk browsers` to list online browsers)", "exit_code": 1, "data": { "browsers": [{ "instance_id": "alpha" }] } }

code、exit_code、data.reason就是你在本文速查表中检索的三个抓手。

🔧 排错三步法：status → doctor → logs

遇到报错按这个顺序排查，能解决 90% 的问题：

bsk status # 第一步：守护进程在不在？浏览器连上没？协议版本对不对？ bsk doctor # 第二步：引导式体检，逐项检查并给出修复建议 bsk logs # 第三步：看最近 200 行守护进程日志，定位卡在哪

对应源码：status.rs、doctor.rs、logs.rs。

📁 相关源码与文档索引

• 错误码定义：crates/bsk-protocol/src/error.rs
• 错误码 → 提示语/退出码对照表：crates/bsk-cli/src/cli/render_error.rs
• 细粒度 reason 常量：crates/bsk-cli/src/cli/render_error.rs
• CLI 错误渲染入口：crates/bsk-cli/src/cli/error.rs
• bsk 命令文档：crates/bsk-cli/README.md
• 架构说明：docs/architecture.md
• 长截图行为说明（含取消与导出）：docs/long-screenshot.md

💡 小结

• 先看退出码定档：1 查参数、2 查连接与取消、3 查浏览器、4 查超时、5 查版本；
• 再看data.reason定位子场景，对照上表的修复建议操作；
• effect_state为unknown时绝不盲目重试，先bsk observe观察页面现状；
• 卡住了就bsk status→bsk doctor→bsk logs三步排查。

掌握这套速查手册，BrowserSkill 的报错就从"天书"变成了导航图——照提示操作，多数问题一次就能解决。

【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI + extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill