debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debugging Skill

调试技能

Debug web applications and Node.js backends using console inspection, network analysis, and non-blocking code debugging with tracepoints, logpoints, and exception monitoring.

使用控制台检查、网络分析以及带追踪点（tracepoints）、日志点（logpoints）和异常监控的非阻塞代码调试功能，调试Web应用及Node.js后端。

When to Use

使用场景

This skill activates when:

User reports a bug or error on a web page or backend
User asks to debug JavaScript (frontend or Node.js)
User wants to inspect API calls or network requests
User needs to troubleshoot page loading or API handler issues
User mentions console errors or warnings
User wants to debug without breakpoints
User needs to trace function calls or monitor variables

在以下场景触发本技能：

用户报告网页或后端的Bug或错误
用户请求调试JavaScript（前端或Node.js）
用户需要检查API调用或网络请求
用户需要排查页面加载或API处理程序问题
用户提及控制台错误或警告
用户希望无需断点即可进行调试
用户需要追踪函数调用或监控变量

Capabilities

功能特性

Console Inspection

控制台检查

bash

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

bash

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

Network Analysis

网络分析

bash

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}'

bash

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}'

Tracepoints (Non-Blocking)

非阻塞追踪点（Tracepoints）

bash

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

bash

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

Logpoints

日志点（Logpoints）

bash

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

bash

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

Exception Monitoring

异常监控

bash

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

bash

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

Watch Expressions

监听表达式（Watch Expressions）

bash

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

bash

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

Retrieve and Clear Snapshots (Unified)

快照获取与清理（统一操作）

bash

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"

bash

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 Backend Debugging (node-devtools-cli)

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

For debugging Node.js API servers, backends, or scripts:

bash

undefined

针对Node.js API服务器、后端或脚本的调试：

bash

undefined

1. Connect to process (by PID, name, or Docker)

1. 连接到进程（通过PID、名称或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

2. 在路由处理程序或服务上设置追踪点

node-devtools-cli --session-id backend-debug debug put-tracepoint
--url-pattern "routes/api.ts"
--line-number 42

3. Exception monitoring

3. 异常监控

node-devtools-cli --session-id backend-debug debug put-exceptionpoint --state uncaught

4. Console logs from Node process

4. 获取Node进程的控制台日志

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)

5. 获取快照（触发代码路径后）

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

6. 查看状态与清理

node-devtools-cli --session-id backend-debug debug status node-devtools-cli debug disconnect


`urlPattern` in Node context matches **script file paths** (e.g., `server.js`, `routes/users.ts`). See [node-devtools-cli](../node-devtools-cli/SKILL.md) skill for full reference.

node-devtools-cli --session-id backend-debug debug status node-devtools-cli debug disconnect


Node环境中的`urlPattern`匹配**脚本文件路径**（例如：`server.js`、`routes/users.ts`）。完整参考请查看[node-devtools-cli](../node-devtools-cli/SKILL.md)技能文档。

Error Investigation

错误排查

bash

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

bash

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

Basic Debugging Workflow

基础调试流程

Reproduce: Navigate to the problematic page
Capture: Take screenshot of current state
Inspect Console: Check for JavaScript errors
Analyze Network: Look for failed requests
Investigate: Run diagnostic JavaScript
Document: Summarize findings with evidence

bash

undefined

复现问题：导航到出现问题的页面
捕获状态：截取当前状态的截图
检查控制台：查看JavaScript错误
分析网络：查找失败的请求
深入排查：运行诊断JavaScript代码
记录结果：汇总发现的问题并附上证据

bash

undefined

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}'

undefined

undefined

Advanced Debugging Workflow (Non-Blocking)

进阶非阻塞调试流程

1. Set Up Probes

1. 设置探针

bash

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

bash

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

undefined

browser-devtools-cli $SESSION debug put-exceptionpoint --state uncaught

undefined

2. Add Watch Expressions

2. 添加监听表达式

bash

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

bash

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

3. Interact with Application

3. 与应用交互

bash

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

bash

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

4. Retrieve Snapshots

4. 获取快照

bash

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

bash

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. Clean Up

5. 清理资源

bash

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

bash

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

Probe Types Summary

探针类型汇总

Probe	Purpose	Output	CLI
Tracepoint	Function calls	Stack, locals, watches	browser-devtools-cli, node-devtools-cli
Logpoint	Expression values	Evaluated result	both
Exceptionpoint	Error catching	Error, stack trace	both
Watch	Per-tracepoint expressions	watchResults in snapshot	list/remove via list-probes, remove-probe, clear-probes

探针类型	用途	输出内容	CLI工具
Tracepoint	追踪函数调用	调用栈、本地变量、监听表达式	browser-devtools-cli、node-devtools-cli
Logpoint	获取表达式值	表达式计算结果	两者通用
Exceptionpoint	捕获错误	错误信息、调用栈	两者通用
Watch	针对追踪点的表达式	快照中的watchResults	通过list-probes、remove-probe、clear-probes进行列出/移除/清理

Best Practices

最佳实践

Choose the right CLI: Use
```
browser-devtools-cli
```
for frontend/page debugging; use
```
node-devtools-cli
```
for Node.js backend/API debugging
Always check console for errors first
Filter network requests to relevant endpoints
Take screenshots before and after actions (browser)
Use source maps for minified/bundled code
Start with exceptions to catch errors first
Use logpoints for lightweight monitoring
Poll snapshots with
```
--from-sequence
```
for efficiency
Clear probes when done to avoid overhead
Document reproduction steps clearly

选择合适的CLI工具：调试前端/页面使用
```
browser-devtools-cli
```
；调试Node.js后端/API使用
```
node-devtools-cli
```
优先检查控制台错误
过滤相关端点的网络请求
操作前后截图留存（浏览器端）
为压缩/打包代码启用源映射（source maps）
先通过异常监控捕获错误
使用日志点进行轻量级监控
通过
--from-sequence
参数轮询快照提升效率
调试完成后清理探针避免性能开销
清晰记录问题复现步骤