agent-dbg

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-dbg Debugger

agent-dbg 调试器

agent-dbg

is a CLI debugger for Node.js wrapping the V8 Inspector (CDP). It uses short

@refs

for all entities -- use them instead of long IDs.

agent-dbg

是一款基于V8 Inspector（CDP）封装的Node.js CLI调试器。它为所有实体使用简短的

@refs

引用——请使用这些引用而非冗长的ID。

Core Debug Loop

核心调试循环

bash

undefined

bash

undefined

1. Launch with breakpoint at first line

1. 在第一行设置断点并启动

agent-dbg launch --brk node app.js

2. Set breakpoints at suspicious locations

2. 在可疑位置设置断点

agent-dbg break src/handler.ts:42 agent-dbg break src/utils.ts:15 --condition "count > 10"

3. Run to breakpoint

3. 运行至断点处

agent-dbg continue

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

4. 检查状态（显示位置、源码、本地变量、调用栈）

agent-dbg state

5. Drill into values

5. 深入查看值

agent-dbg props @v1 # expand object agent-dbg props @v1 --depth 3 # expand nested 3 levels agent-dbg eval "items.filter(x => x.active)"

agent-dbg props @v1 # 展开对象 agent-dbg props @v1 --depth 3 # 展开嵌套至3层 agent-dbg eval "items.filter(x => x.active)"

6. Fix and verify

6. 修复并验证

agent-dbg set count 0 # change variable agent-dbg hotpatch src/utils.js # live-edit (reads file from disk) agent-dbg continue # verify fix

undefined

agent-dbg set count 0 # 修改变量 agent-dbg hotpatch src/utils.js # 实时编辑（从磁盘读取文件） agent-dbg continue # 验证修复效果

undefined

Debugging Strategies

调试策略

Bug investigation -- narrow down with breakpoints

问题排查——通过断点缩小范围

bash

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

bash

agent-dbg launch --brk node app.js
agent-dbg break src/api.ts:50                    # 可疑代码行
agent-dbg break src/api.ts:60 --condition "!user" # 条件断点
agent-dbg continue
agent-dbg vars                                    # 检查本地变量
agent-dbg eval "JSON.stringify(req.body)"         # 深入查看内容
agent-dbg step over                               # 单步跳过
agent-dbg state                                   # 查看当前状态

Attach to running/test process

附加到运行中/测试进程

bash

undefined

bash

undefined

Start node with inspector

启动带调试器的Node进程

node --inspect app.js

Or attach by PID

或通过PID附加

agent-dbg attach 12345 agent-dbg state

undefined

agent-dbg attach 12345 agent-dbg state

undefined

Trace execution flow with logpoints (no pause)

使用日志点追踪执行流程（不暂停）

bash

agent-dbg logpoint src/auth.ts:20 "login attempt: ${username}"
agent-dbg logpoint src/auth.ts:45 "auth result: ${result}"
agent-dbg continue
agent-dbg console    # see logged output

bash

agent-dbg logpoint src/auth.ts:20 "login attempt: ${username}"
agent-dbg logpoint src/auth.ts:45 "auth result: ${result}"
agent-dbg continue
agent-dbg console    # 查看日志输出

Exception debugging

异常调试

bash

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

bash

agent-dbg catch uncaught          # 捕获未处理异常时暂停
agent-dbg continue                # 运行至异常发生处
agent-dbg state                   # 查看异常抛出位置
agent-dbg eval "err.message"      # 查看错误信息
agent-dbg stack                   # 查看完整调用栈

TypeScript source map support

TypeScript 源映射支持

agent-dbg automatically resolves

.ts

paths via source maps. Set breakpoints using

.ts

paths, see

.ts

source in output. Use

--generated

to see compiled

.js

if needed.

agent-dbg 会自动通过源映射解析

.ts

路径。可以使用

.ts

路径设置断点，输出中会显示

.ts

源码。如有需要，可使用

--generated

参数查看编译后的

.js

代码。

Ref System

引用系统

Every output assigns short refs. Use them everywhere:

@v1..@vN

-- variables:

agent-dbg props @v1

agent-dbg set @v2 true

@f0..@fN

-- stack frames:

agent-dbg eval --frame @f1 "this"

BP#1..N

-- breakpoints:

agent-dbg break-rm BP#1

agent-dbg break-toggle BP#1

```
LP#1..N
```
-- logpoints:
```
agent-dbg break-rm LP#1
```

Refs

@v

@f

reset on each pause.

BP#

LP#

persist until removed.

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

@v1..@vN

—— 变量：

agent-dbg props @v1

agent-dbg set @v2 true

@f0..@fN

—— 调用栈帧：

agent-dbg eval --frame @f1 "this"

BP#1..N

—— 断点：

agent-dbg break-rm BP#1

agent-dbg break-toggle BP#1

```
LP#1..N
```
—— 日志点：
```
agent-dbg break-rm LP#1
```

@v

@f

类型的引用会在每次暂停后重置。

BP#

LP#

类型的引用会保留直到被移除。

Key Flags

关键参数

```
--json
```
-- machine-readable JSON output on any command
```
--session NAME
```
-- target a specific session (default: "default")
```
--generated
```
-- bypass source maps, show compiled JS (on state/source/stack)

```
--json
```
—— 所有命令输出机器可读的JSON格式
```
--session NAME
```
—— 指定目标会话（默认："default"）
```
--generated
```
—— 绕过源映射，显示编译后的JS代码（适用于state/source/stack命令）

Command Reference

命令参考

See references/commands.md for full command details and options.

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

Tips

小贴士

```
agent-dbg state
```
after stepping always shows location + source + locals -- usually enough context
```
agent-dbg state -c
```
for source only,
```
-v
```
for vars only,
```
-s
```
for stack only -- save tokens
```
agent-dbg eval
```
supports
```
await
```
-- useful for async inspection
```
agent-dbg blackbox "node_modules/**"
```
-- skip stepping into dependencies
```
agent-dbg hotpatch file
```
reads the file from disk -- edit the file first, then hotpatch
Execution commands (
```
continue
```
,
```
step
```
,
```
pause
```
,
```
run-to
```
) auto-return status
```
agent-dbg stop
```
kills the debugged process and daemon

单步执行后使用
```
agent-dbg state
```
命令，总会显示位置+源码+本地变量——通常已足够提供上下文信息
使用
```
agent-dbg state -c
```
仅查看源码，
```
-v
```
仅查看变量，
```
-s
```
仅查看调用栈——节省输出内容
```
agent-dbg eval
```
支持
```
await
```
——适用于异步代码检查
```
agent-dbg blackbox "node_modules/**"
```
—— 跳过单步执行依赖代码
```
agent-dbg hotpatch file
```
会从磁盘读取文件——请先编辑文件，再执行热修复
执行类命令（
```
continue
```
、
```
step
```
、
```
pause
```
、
```
run-to
```
）会自动返回状态
```
agent-dbg stop
```
会终止被调试的进程和守护进程