node-devtools-cli

用途

Node DevTools CLI 是一个命令行界面，用于对 Node.js 后端进程进行非阻塞调试。它通过 Inspector 协议（Chrome DevTools Protocol）连接目标进程，提供 tracepoint、logpoint、exceptionpoint 和 watch 表达式等能力，且不会暂停进程执行。适合在需要观察运行中 Node.js 服务内部状态、又不想中断服务的场景下使用。

主要能力

• 非阻塞调试：通过 Inspector 协议连接，不暂停执行。
• 探针类型：支持 tracepoint、logpoint、exceptionpoint 和 watch 表达式。
• 快照捕获：设置探针后触发代码路径，可获取捕获的快照。
• 多种连接方式：支持通过 PID、进程名、Docker 容器、Inspector 端口或 WebSocket URL 连接。
• 自动激活：若目标进程未开启 --inspect，CLI 会通过 SIGUSR1 激活，无需修改代码。
• 会话管理：支持会话的持久化、列出、查看和删除。
• 守护进程管理：支持 daemon 的启动、停止、重启、状态和信息查询。
• 工具发现：支持列出、搜索和查看工具信息。
• 交互模式：提供 interactive 交互式命令行。
• Shell 补全：支持 bash 和 zsh 补全。

使用方式

安装：

npm install -g browser-devtools-mcp

快速开始：

# 1. 启动守护进程（若未运行）
node-devtools-cli daemon start

# 2. 通过 PID 连接 Node.js 进程
node-devtools-cli --session-id my-debug debug connect --pid 12345

# 3. 在 server.js 第 42 行设置 tracepoint
node-devtools-cli --session-id my-debug debug put-tracepoint \
  --url-pattern "server.js" \
  --line-number 42

# 4. 触发代码路径（例如向应用发起 API 请求）

# 5. 获取捕获的快照
node-devtools-cli --session-id my-debug --json debug get-probe-snapshots

全局选项：

选项	说明	默认值
--port <number>	守护进程服务器端口	2020
--session-id <string>	用于 Node 连接持久化的会话	自动
--json	以 JSON 输出（推荐用于 AI）	false
--quiet	抑制日志消息	false
--verbose	启用调试输出	false
--timeout <ms>	操作超时	30000

AI Agent 推荐用法：

node-devtools-cli --json --quiet --session-id "debug-session" <command>

工具域：

域	说明
debug	连接、tracepoint、logpoint、exceptionpoint、watch、快照

连接方式（通过 debug connect 使用以下之一）：

方式	选项	示例
PID	--pid <number>	--pid 12345
进程名	--process-name <pattern>	--process-name "server.js"
Docker 容器	--container-id 或 --container-name	--container-name my-api
Inspector 端口	--inspector-port <number>	--inspector-port 9229
WebSocket URL	--ws-url <url>	--ws-url "ws://127.0.0.1:9229/abc"

若进程未开启 --inspect，CLI 会通过 SIGUSR1 激活（无需修改代码）。对于 Docker：暴露 9229 端口并使用 --inspect=0.0.0.0:9229。

CLI 管理命令：

守护进程：

node-devtools-cli daemon status
node-devtools-cli daemon start
node-devtools-cli daemon stop
node-devtools-cli daemon restart
node-devtools-cli daemon info

会话：

node-devtools-cli session list
node-devtools-cli session info <session-id>
node-devtools-cli session delete <session-id>

工具：

node-devtools-cli tools list
node-devtools-cli tools search <query>
node-devtools-cli tools info <tool-name>

配置与更新：

node-devtools-cli config
node-devtools-cli update --check

示例：

按 PID 连接：

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

# 连接
node-devtools-cli $SESSION debug connect --pid $(pgrep -f "node server.js")

# 在路由处理器上设置 tracepoint
node-devtools-cli $SESSION debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 25

# 触发：curl http://localhost:3000/api/users
# 获取快照
node-devtools-cli $SESSION --json debug get-probe-snapshots

按进程名连接：

node-devtools-cli debug connect --process-name "api"

Docker 容器：

# 应用在容器中运行，使用 -p 9229:9229
node-devtools-cli debug connect \
  --container-name my-node-app \
  --host host.docker.internal \
  --inspector-port 9229

异常捕获：

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

node-devtools-cli $SESSION debug connect --pid 12345
node-devtools-cli $SESSION debug put-exceptionpoint --state uncaught

# 在应用中触发错误
# 检查快照
node-devtools-cli $SESSION --json debug get-probe-snapshots --types exceptionpoint

交互模式：

node-devtools-cli interactive

命令	说明
help	显示命令
exit, quit	退出
debug connect	连接进程
debug status	连接状态
<domain> <tool>	执行工具

Shell 补全：

eval "$(node-devtools-cli completion bash)"
eval "$(node-devtools-cli completion zsh)"

适用场景

• 调试运行中的 Node.js 后端服务，需要观察特定代码路径而不中断服务。
• 在 Docker 容器中运行的 Node.js 应用调试。
• 捕获未捕获异常（uncaught exception）的现场快照。
• 通过 watch 表达式观察运行时变量。
• 作为 AI Agent 的调试工具，使用 --json --quiet 输出便于解析。

限制

• 资料未提供支持的操作系统、Node.js 版本要求等兼容性信息。
• 资料未提供收费、价格或授权模式信息。
• 资料未提供性能开销、并发连接数等限制说明。
• 资料未提供除 debug 域之外的其他工具域详情。