dbg

dbg 调试器

dbg 是一个 CLI 调试器，支持 Node.js（V8/CDP）、Bun（WebKit/JSC）、Python（通过 debugpy/DAP）、Java（通过 JDWP/DAP）和原生代码（通过 LLDB/DAP 调试 C/C++/Rust/Swift）。它使用简短的 @refs 引用表示所有实体——请用它们代替较长的 ID。

支持的运行时

运行时	语言	启动示例
Node.js	JavaScript	dbg launch --brk node app.js
tsx / ts-node	TypeScript	dbg launch --brk tsx src/app.ts
Bun	JavaScript / TypeScript	dbg launch --brk bun app.ts
Bun 可执行文件（bun build --compile）	JavaScript / TypeScript	dbg launch --brk ./my-cli --its-flags
debugpy	Python	dbg launch --brk python3 app.py（或 attach——参见 Python 部分）
LLDB	C / C++ / Rust / Swift	dbg launch --brk --runtime lldb ./program
JDWP	Java	dbg launch --brk --runtime java ./program

对于 JS 和 Python 运行时，系统会根据启动命令自动检测运行时，包括由 Bun 编译的可执行文件（否则请传入 --runtime bun）。程序名称之后的所有内容都会原样传递给程序。调试原生代码时，请使用 --runtime lldb。Python 也可以通过 TCP 连接到正在运行的 debugpy 监听器（--runtime python）。

核心调试循环

# 1. Launch with breakpoint at first line
dbg launch --brk node app.js
# Or: dbg launch --brk bun app.ts
# Or: dbg launch --brk python3 app.py
# Or: dbg launch --brk --runtime lldb ./my_program
# Or attach to a running process with the --inspect flag
dbg attach 9229

# 2. Set breakpoints at suspicious locations
dbg break src/handler.ts:42
dbg break src/utils.ts:15 --condition "count > 10"

# 3. Run to breakpoint (--wait blocks until it pauses or the program ends;
#    "Running (no pause within 30s)" means it ran out: dbg continue --wait 60 keeps waiting)
dbg continue --wait 30

# 4. Inspect state (shows location, source, locals, stack)
dbg state

# 5. Drill into values
dbg props @v1              # expand object
dbg props @v1 --depth 3   # expand nested 3 levels
dbg eval "x + 1"

# 6. Fix and verify (JS/TS only)
dbg set count 0            # change variable
dbg hotpatch src/utils.js  # live-edit (reads file from disk)
dbg continue               # verify fix

调试策略

调查 Bug——用断点缩小范围

dbg launch --brk node app.js
dbg break src/api.ts:50                    # suspect line
dbg break src/api.ts:60 --condition "!user" # conditional
dbg continue
dbg vars                                    # check locals
dbg eval "JSON.stringify(req.body)"         # inspect deeply
dbg step over                               # advance one line
dbg state                                   # see new state

调试原生代码（C/C++/Rust）

dbg launch --brk --runtime lldb ./my_program
dbg break main.c:42
dbg break-fn main                          # function breakpoint
dbg continue
dbg vars                                    # inspect locals
dbg eval "array[i]"                         # evaluate expression
dbg step into                               # step into function

调试 Python（debugpy）

Python 使用 debugpy DAP 适配器。可通过两种方式连接：

启动（根据 python/python3 命令自动检测）：

dbg launch --brk python3 app.py        # pauses at first line
dbg break app.py:42
dbg continue
dbg state                              # location + locals + stack
dbg eval "some_expr"                   # evaluate in the paused frame
dbg step over

附加——被调试程序运行自己的 debugpy 监听器，dbg 通过 TCP 连接 （中间不会启动适配器）。适用于进程必须以特定方式启动的情况（例如测试运行器、虚拟环境或机密信息包装器）：

# 1. Start the program listening on a port. --wait-for-client blocks before
#    the first line runs, so you have time to attach and set breakpoints.
python3 -m debugpy --listen 5679 --wait-for-client app.py &

# 2. Attach. --runtime python (alias: debugpy) is REQUIRED for a bare port.
dbg attach 5679 --runtime python

# 3. Set breakpoints (use absolute paths), then drive execution.
dbg break /abs/path/app.py:42
dbg continue
dbg state

注意：

• --wait-for-client 会将第一个 TCP 连接视为客户端——不要通过探测端口来检查就绪状态；只需在 debugpy 向 stderr 打印启动横幅后进行附加。
• 简短脚本可能会在你设置断点前运行完毕。请在附加后立即设置断点，或附加到长时间运行的入口点。
• dbg set / dbg hotpatch 仅适用于 JS/TS；检查功能（break、continue、state、vars、eval、step、break-fn）均适用于 Python。

附加到正在运行的进程/测试进程（Node/Bun）

# Start with inspector enabled
node --inspect app.js
# Or: bun --inspect app.ts
# Then attach
dbg attach 9229
dbg state

# Bun process or Bun-compiled binary: BUN_INSPECT opens the inspector, `?break=1`
# holds the process until dbg attaches, then pauses on its first statement.
BUN_INSPECT='ws://localhost:6499/app?break=1' ./my-bun-binary
dbg attach ws://localhost:6499/app        # runtime auto-detected
# Function breakpoint (JS/TS): a path from the global scope, an @ref, or --name <regex> (Bun)
dbg break-fn fetch --condition 'String(args[0]).includes("/v1/messages")'
dbg break-fn @v12                          # a function object you found in vars/props
dbg logpoint fn:service.ping '"ping", label'   # trace calls without pausing; dbg console
dbg continue                              # pauses on the call; `dbg stack` @f1 is the caller

使用日志点跟踪执行流程（不中断）

dbg logpoint src/auth.ts:20 '"login attempt:", username'   # console.log's arguments
dbg logpoint src/auth.ts:45 '`auth result: ${result}`'
dbg continue
dbg console    # see logged output; logpoints never print into the program's own output

在程序退出时检查状态（JS）

dbg catch exit              # pause in the program's exit, state still alive
dbg continue --wait 60      # runs until it exits
dbg eval "code"             # the exit code; eval anything else that is still there
dbg continue                # let it exit

异常调试

dbg catch uncaught          # pause on uncaught exceptions
dbg continue                # runs until exception
dbg state                   # see where it threw
dbg eval "err.message"      # inspect the error
dbg stack                   # full call stack

TypeScript 源映射支持

dbg 会通过源映射自动解析 .ts 路径。使用 .ts 路径设置断点，并在输出中查看 .ts 源码。如有需要，可使用 --generated 查看编译后的 .js。

引用系统

每条输出都会分配简短引用。请在所有命令中使用这些引用：

• @v1..@vN——变量：dbg props @v1、dbg set @v2 true
• @f0..@fN——堆栈帧：dbg eval --frame @f1 "this"
• BP#1..N——断点：dbg break-rm BP#1、dbg break-toggle BP#1
• LP#1..N——日志点：dbg break-rm LP#1

每次暂停时都会重置 @v/@f 引用。BP#/LP# 会一直保留，直到被移除。

关键标志

• --json——任何命令都输出机器可读的 JSON
• --session NAME——指定目标会话（默认值："default"）
• --runtime NAME——选择调试适配器（例如，用于原生代码的 lldb）
• --generated——绕过源映射，显示编译后的 JS（用于 state/source/stack）

命令参考

完整的命令详情和选项请参见 references/commands.md。

提示

• 单步执行后，dbg state 始终会显示位置、源代码和局部变量——通常这些信息就足够了
• 使用 dbg state -c 仅查看源代码，-v 仅查看变量，-s 仅查看堆栈——节省令牌
• 对于压缩或打包后的代码：dbg sourcemap <script> --pretty 会从此后以格式化形式显示脚本（位置和断点也会相应转换）；dbg source --width 600 会显示暂停位置所在列周围的 600 个字符；dbg search "text" --width 200 会显示每个匹配项周围的内容
• dbg eval 支持 await 和 --await（JS/TS）。Promise 只会在程序运行时完成：暂停时会返回已完成的值，否则会显示说明
• dbg eval <expr> --out file.txt 会将完整值写入文件（否则输出会截断为 80 个字符）
• 在 ES 模块中，require 未定义：请使用 process.getBuiltinModule("node:fs")
• dbg blackbox "node_modules/**"——跳过对依赖项的单步调试
• dbg hotpatch file 会从磁盘读取文件——先编辑文件，再执行热补丁（仅限 JS/TS）
• dbg break-fn funcName——函数断点：在 DAP 运行时中按符号设置；在 JS 中可按路径（obj.method）、@ref 或 --name <regex>（Bun）设置。--condition/--log 会在暂停位置的函数自身参数、arguments 和 this 所处环境中运行；对于进程内由 dbg 包装的原生函数（例如 Bun 中的 fetch），则在 args 和 this 所处环境中运行。设置断点时路径必须存在；dbg stop 会移除包装器
• dbg eval 也可用于正在运行的目标（全局作用域）；只有 --frame 需要暂停状态
• Python：使用 dbg launch --brk python3 app.py，或通过 dbg attach <port> --runtime python 附加到 debugpy --listen <port> 服务
• 执行命令（continue、step、pause、run-to）会自动返回状态
• dbg stop 会终止正在调试的进程和守护进程