debugging

调试技能

通过控制台检查、网络分析以及使用跟踪点、日志点和异常监控进行非阻塞代码调试，调试 Web 应用和 Node.js 后端。

适用场景

此技能会在以下情况启用：

• 用户报告网页或后端存在 Bug 或错误
• 用户请求调试 JavaScript（前端或 Node.js）
• 用户想检查 API 调用或网络请求
• 用户需要排查页面加载或 API 处理程序问题
• 用户提到控制台错误或警告
• 用户想在不使用断点的情况下进行调试
• 用户需要跟踪函数调用或监控变量

功能

控制台检查

browser-devtools-cli o11y get-console-messages
browser-devtools-cli o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-console-messages --type error

网络分析

browser-devtools-cli o11y get-http-requests
browser-devtools-cli --json o11y get-http-requests --resource-type fetch
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'

跟踪点（非阻塞）

browser-devtools-cli debug put-tracepoint --url-pattern "app.js" --line-number 42
browser-devtools-cli debug list-probes --types tracepoint
browser-devtools-cli debug remove-probe --type tracepoint --id <probe-id>
browser-devtools-cli debug clear-probes --types tracepoint

日志点

browser-devtools-cli debug put-logpoint --url-pattern "app.js" --line-number 50 --log-expression "user.id"
browser-devtools-cli debug list-probes --types logpoint
browser-devtools-cli debug remove-probe --type logpoint --id <probe-id>
browser-devtools-cli debug clear-probes --types logpoint

异常监控

browser-devtools-cli debug put-exceptionpoint --state uncaught
browser-devtools-cli debug put-exceptionpoint --state all

监视表达式

browser-devtools-cli debug add-watch --expression "this"
browser-devtools-cli debug add-watch --expression "user.id"
browser-devtools-cli debug list-probes --types watch
browser-devtools-cli debug remove-probe --type watch --id <probe-id>
browser-devtools-cli debug clear-probes --types watches

获取和清除快照（统一）

browser-devtools-cli --json debug get-probe-snapshots
browser-devtools-cli --json debug get-probe-snapshots --types tracepoint,logpoint,exceptionpoint
browser-devtools-cli --json debug get-probe-snapshots --probe-id "tp_abc" --from-sequence 0
browser-devtools-cli debug clear-probe-snapshots
browser-devtools-cli debug clear-probe-snapshots --types tracepoint --probe-id "tp_abc"

Node.js 后端调试（node-devtools-cli）

用于调试 Node.js API 服务、后端或脚本：

# 1. Connect to process (by PID, name, or Docker)
node-devtools-cli --session-id backend-debug debug connect --pid 12345
node-devtools-cli --session-id backend-debug debug connect --process-name "server.js"

# 2. Tracepoint on route handler or service
node-devtools-cli --session-id backend-debug debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 42

# 3. Exception monitoring
node-devtools-cli --session-id backend-debug debug put-exceptionpoint --state uncaught

# 4. Console logs from Node process
node-devtools-cli --session-id backend-debug --json debug get-logs
node-devtools-cli --session-id backend-debug --json debug get-logs --search "error"

# 5. Retrieve snapshots (after triggering the code path)
node-devtools-cli --session-id backend-debug --json debug get-probe-snapshots
node-devtools-cli --session-id backend-debug --json debug get-probe-snapshots --types tracepoint,exceptionpoint

# 6. Status and cleanup
node-devtools-cli --session-id backend-debug debug status
node-devtools-cli debug disconnect

Node 上下文中的 urlPattern 匹配脚本文件路径（例如 server.js、routes/users.ts）。完整参考请参阅 node-devtools-cli 技能。

错误调查

browser-devtools-cli content take-screenshot --name "error-state"
browser-devtools-cli content get-as-html --selector ".error-container"

基本调试工作流

1. 复现：导航到出现问题的页面
2. 捕获：截取当前状态的屏幕截图
3. 检查控制台：检查是否存在 JavaScript 错误
4. 分析网络：查找失败的请求
5. 调查：运行诊断 JavaScript
6. 记录：结合证据总结调查结果

# Quick debug workflow
browser-devtools-cli navigation go-to --url "https://example.com"
browser-devtools-cli content take-screenshot --name "initial"
browser-devtools-cli --json o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'

高级调试工作流（非阻塞）

1. 设置探针

SESSION="--session-id debug-session"

# Navigate to app
browser-devtools-cli $SESSION navigation go-to --url "http://localhost:3000"

# Tracepoint on a function
browser-devtools-cli $SESSION debug put-tracepoint \
  --url-pattern "app.js" \
  --line-number 42

# Exception monitoring
browser-devtools-cli $SESSION debug put-exceptionpoint --state uncaught

2. 添加监视表达式

browser-devtools-cli $SESSION debug add-watch --expression "this"
browser-devtools-cli $SESSION debug add-watch --expression "user.id"

3. 与应用交互

browser-devtools-cli $SESSION interaction click --selector "#submit-btn"
browser-devtools-cli $SESSION sync wait-for-network-idle

4. 获取快照

browser-devtools-cli $SESSION --json debug get-probe-snapshots
browser-devtools-cli $SESSION --json debug get-probe-snapshots --types tracepoint,exceptionpoint
browser-devtools-cli $SESSION --json debug get-probe-snapshots --from-sequence 0

5. 清理

browser-devtools-cli $SESSION debug clear-probes
browser-devtools-cli $SESSION debug clear-probe-snapshots
browser-devtools-cli session delete debug-session

探针类型汇总

探针	用途	输出	CLI
跟踪点	函数调用	堆栈、本地变量、监视项	browser-devtools-cli、node-devtools-cli
日志点	表达式值	计算结果	两者
异常点	捕获错误	错误、堆栈跟踪	两者
监视项	每个跟踪点的表达式	快照中的 watchResults	通过 list-probes、remove-probe、clear-probes 列出/移除

最佳实践

1. 选择合适的 CLI：使用 browser-devtools-cli 调试前端/页面；使用 node-devtools-cli 调试 Node.js 后端/API
2. 始终先检查控制台是否有错误
3. 筛选网络请求，仅查看相关端点
4. 在操作前后截取屏幕截图（浏览器）
5. 对压缩/打包后的代码使用源映射
6. 从异常入手，优先捕获错误
7. 使用日志点进行轻量级监控
8. 使用 --from-sequence 轮询快照，提高效率
9. 完成后清除探针，以免产生开销
10. 清楚记录复现步骤