agent-browser-debug

调试诊断 — 执行协议

内部模板。 入口：agent-browser 技能。

---

绝对不要

NEVER jump to DOM inspection before checking `errors` — JS errors explain 80% of broken UIs
NEVER assume auth is fine — check `cookies` + `storage local` first when login suspected
NEVER think `inspect` kills CLI — DevTools and CLI work simultaneously

---

排查顺序（按顺序运行，发现首个问题时停止）

agent-browser --headed open <url>
agent-browser wait --load networkidle

# Step 1: JS errors (explains 80% of broken UIs)
agent-browser errors

# Step 2: Console warnings
agent-browser console --pattern "error|warn"

# Step 3: Failed network requests — filter to relevant calls
agent-browser network requests --filter "api"
agent-browser network requests --type xhr,fetch --status 4xx   # 4xx only
agent-browser network requests --method POST --status 5xx      # failed writes

# Step 4: Inspect full request/response body of a failed request
agent-browser network request <requestId>   # get requestId from step 3

# Step 5: Auth state (check first if login/session suspected)
agent-browser cookies         # token cookie present?
agent-browser storage local   # JWT in localStorage?

# Step 6: DOM state
agent-browser snapshot -i
agent-browser is enabled @e5
agent-browser is visible @e3

# Step 7: Form validity (if button appears enabled but won't submit)
agent-browser eval "document.querySelector('form').checkValidity()"

# Step 8: Deep investigation
agent-browser inspect         # DevTools (CLI stays live)

---

用于保留证据的网络 HAR

# Record full network trace (start BEFORE navigation)
agent-browser network har start ./debug-trace.har
agent-browser open <url>
agent-browser wait --load networkidle
# ... reproduce the issue ...
agent-browser network har stop
# Open debug-trace.har in browser DevTools → Network → Import

---

恢复模式

症状	下一步操作
发现 JS 错误	报告错误 → 判断关卡：继续还是停止？
缺少身份验证令牌	重新运行身份验证流程，再次检查 cookies
网络 4xx/5xx	使用 network request <id> 获取完整响应正文 → 报告 → 判断关卡
is enabled 为 false	通过 eval 检查表单有效性
无头模式下无法复现问题	使用 --headed 运行，以便直观观察

---

判断关卡

遇到以下情况时暂停：

• 发现 JS 错误（向用户展示并询问：这是错误还是已知问题？）
• 缺少身份验证令牌（没有凭据时难以自动恢复）
• API 返回意外错误（用户需要决定下一步）
• network request <id> 显示响应中包含敏感数据（不要记录，询问用户）

---

易犯错误

错误	修正方法
跳过 errors，直接检查 DOM	80% 的问题都能由错误解释——务必先检查
遇到身份验证问题就直接开始调试 JS	先检查 cookies 和 storage local
以为 inspect 会终止 CLI	不会——两者可以同时运行
仅按 URL 筛选 network requests	还要按 --status 4xx 或 --method POST 筛选，以缩小范围
忽略请求正文	使用 network request <requestId> 获取完整负载