Bright Data — Browser Session Debugger 是一个用于诊断 Bright Data Scraping Browser 会话的技能，基于 Browser Sessions API 获取实时会话数据并进行智能分诊，包括错误诊断、带宽分析、验证码报告以及跨近期会话的模式检测。
用途 该技能用于排查 Bright Data Scraping Browser 会话问题。当用户遇到 Bright Data 浏览器会话错误、出现 puppeteer 堆栈跟踪、错误码、提及 brd.superproxy.io，或爬虫产出空/异常结果（如“Found 0 categories”“Got 0 products”、结果数量少于预期）时，可借助该技能定位问题。
主要能力
- 智能分诊：自动按失败模式对会话分组，而不仅是罗列。
- 动态带宽离群检测：按目标域名分组，对拥有 3 个以上会话的域名计算带宽中位数，标记超过中位数 2 倍的会话。
- 验证码报告：显示验证码命中率与解决率。
- 错误推理：综合会话信号推断问题原因。
- 零配置：从环境变量读取 API 密钥，无需 zone 设置。
使用方式 设置 API 密钥：
export BRIGHTDATA_API_KEY="your-api-key"
密钥可从 Bright Data Dashboard → API Tokens 获取。无需配置 zone，zone 会作为会话数据中的字段返回。
列出并分诊近期会话：以 /brd-browser-debug 无参数调用。API 参考：GET /browser_sessions。先以 limit=100（最大值）按最新排序发起单次调用：
GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc Authorization: Bearer $BRIGHTDATA_API_KEY
分页：响应包含 total、has_more 和 next_offset。若 has_more 为 true 且分析需要更多数据（例如带宽离群检测需要更大样本），使用 offset=<next_offset> 获取下一页，直到数据足够或 has_more 为 false。
可用过滤器（当用户指定范围时应用）：status=failed|finished|running；api_name=<zone>；target_url=<domain>；start_date / end_date（ISO 8601 日期时间范围）；sort=timestamp|duration|bandwidth 配合 order=asc|desc。若用户询问特定 zone、日期范围或域名，应应用相应过滤器，而不是拉取全部会话后在客户端过滤。
分诊步骤：1) 呈现健康摘要：响应中的 total，以及 finished / failed / running 的计数。2) 最近一次会话——无论状态如何始终高亮（详细程度与单会话模式相同）。3) 失败会话——对每个失败：会话 ID、时间戳、时长、带宽，然后结合下文“诊断失败会话”中的信号推理原因。4) 模式检测——若 3 个以上会话共享同一 error.code，则视为系统性问题，例如：“3 sessions failed with custom_headers — you are overriding a header Bright Data forbids. Remove page.setExtraHTTPHeaders() from your code.” 5) 带宽离群——按 target_url 域名分组，对拥有 3 个以上会话的域名计算带宽中位数，标记超过该域名中位数 2 倍的会话，并注明它是否为失败会话且在失败前消耗了异常高的带宽。6) 验证码活动——报告多少会话遇到验证码以及是否解决。7) 以一行结论收尾：最重要的发现与最有效的修复。
检查单个会话：以 /brd-browser-debug <session_id> 调用。API 参考：GET /browser_sessions/{session_id}。调用：
GET https://api.brightdata.com/browser_sessions/<session_id> Authorization: Bearer $BRIGHTDATA_API_KEY
若会话 ID 未找到则返回 404——告知用户并停止。使用响应字段呈现深入分析：Status（status）：running / finished / failed；Zone（api_name）：处理该会话的 Bright Data zone；Timestamp（timestamp）：ISO 8601，以本地友好格式显示；Duration（duration）：秒（可为空）——若失败且小于 2 秒则标记（会话几乎未开始）；Bandwidth（bandwidth）：字节转 MB；Navigations（navigations）：若为 0 则标记（未加载任何内容）；Captcha（captcha）：solved / none / detected / failed 之一——detected 表示出现挑战但未解决，failed 表示尝试解决但未成功；Route：target_url → end_url——注意显著漂移（不同域名、登录墙、错误页）；Error（error.code + error.message）：结合下文“诊断失败会话”中的信号推理原因。以一行结论收尾。
从对话上下文自动检测：当对话中出现 Bright Data 浏览器问题——包括 puppeteer 堆栈跟踪、错误码、提及 brd.superproxy.io、用户描述会话失败，或爬虫产出空/异常结果（如“Found 0 categories”“Got 0 products”、结果数量少于预期）时：若输出中可见会话 ID，则对其运行单会话深入分析；若不可见会话 ID，则运行列出并分诊，按相关目标域名过滤，并高亮最近一次会话作为可能的问题源头。将对话中看到的错误或异常行为与 API 返回结果交叉比对。一个成功完成、带宽正常但爬虫得到 0 结果的会话，指向客户端选择器/提取 bug，而非代理问题。
诊断失败会话：不要仅依赖错误码，应交叉参考所有可用会话信号来推理问题：时长 + 导航次数——失败且小于 2 秒、0 次导航的会话从未越过连接阶段，可能是配置或认证问题；运行数分钟后失败的会话指向运行时问题（抓取中途被阻断、空闲超时、网络中断）。带宽相对于其他会话——失败会话若消耗与成功会话相近的带宽，可能已到达目标但在提取阶段失败；失败会话若带宽接近零，则从未加载任何内容。Captcha 字段——若 captcha 为 detected 但未解决，会话被未解决的挑战停止——建议在 zone 上启用验证码解决。target_url 与 end_url——显著漂移（不同域名、登录页、错误页）意味着会话被重定向离开预期目标。error.message——按原始消息文本描述发生了什么，不要猜测或编造超出消息本身的含义；若原因不明，引导用户联系 Bright Data 支持。
适用场景 适用于排查 Bright Data Scraping Browser 会话失败、分析会话带宽异常、检查验证码处理情况、定位爬虫空结果或异常结果的原因，以及按 zone、日期范围或目标域名筛选会话进行诊断。
限制 需要有效的 BRIGHTDATA_API_KEY。会话 ID 不存在时 API 返回 404。分页受 total、has_more、next_offset 控制，分析可能需要多次请求。错误原因不明确时应联系 Bright Data 支持。其他未在资料中说明的限制暂未提供。