面向 AI 的 GDB CLI

PyPI version Python License

English | 中文 | Русский

专为 AI Agent（Claude Code 等）设计的 GDB 调试工具。采用“轻量级 CLI + GDB 内置 Python RPC 服务器”架构，支持通过 Bash 进行有状态的 GDB 调试。

特性

核心转储（Core Dump）分析：加载带有内存中符号的 core dump，实现毫秒级响应
实时附加调试：附加到正在运行的进程，支持非停止（non-stop）模式
结构化 JSON 输出：所有命令均输出 JSON，支持自动截断/分页和操作提示
安全机制：命令白名单、心跳超时自动清理、幂等性保证
数据库优化：调度器锁定、大对象分页、多线程截断

要求

Python: 3.6.8+
GDB: 9.0+ 且已启用 Python 支持
操作系统: Linux

检查 GDB Python 支持

# Check if GDB has Python support
gdb -nx -q -batch -ex "python print('OK')"

# If system GDB lacks Python, check GCC Toolset (RHEL/CentOS)
/opt/rh/gcc-toolset-13/root/usr/bin/gdb -nx -q -batch -ex "python print('OK')"

安装

# Install from PyPI
pip install gdb-cli

# Or install from GitHub
pip install git+https://github.com/Cerdore/gdb-cli.git

# Or clone and install locally
git clone https://github.com/Cerdore/gdb-cli.git
cd gdb-cli
pip install -e .

环境检查

gdb-cli env-check


## Quick Start

### 1. Load Core Dump

```bash
gdb-cli load --binary ./my_program --core ./core.12345

输出：

{
  "session_id": "f465d650",
  "mode": "core",
  "binary": "./my_program",
  "core": "./core.12345",
  "gdb_pid": 12345,
  "status": "loading"
}

加载大型二进制文件或 core 文件时，请轮询直到会话就绪：

gdb-cli status -s f465d650

{
  "session_id": "f465d650",
  "state": "ready",
  "mode": "core",
  "binary": "./my_program"
}

如果系统默认的 GDB 不支持 Python，请通过 --gdb-path 指定：
gdb-cli load --binary ./my_program --core ./core.12345 \
  --gdb-path /opt/rh/gcc-toolset-13/root/usr/bin/gdb

2. 调试操作

所有操作均使用 --session / -s 指定会话 ID：

SESSION="f465d650"

# List threads
gdb-cli threads -s $SESSION

# Get backtrace (default: current thread)
gdb-cli bt -s $SESSION

# Get backtrace for a specific thread
gdb-cli bt -s $SESSION --thread 3

# Evaluate C/C++ expressions
gdb-cli eval-cmd -s $SESSION "my_struct->field"

# Access array elements
gdb-cli eval-element -s $SESSION "my_array" --index 5

# View local variables
gdb-cli locals-cmd -s $SESSION

# Execute raw GDB commands
gdb-cli exec -s $SESSION "info registers"

# Check session status
gdb-cli status -s $SESSION

3. 会话管理

# List all active sessions
gdb-cli sessions

# Stop a session
gdb-cli stop -s $SESSION

4. 实时附加调试

# Attach to a running process (default: scheduler-locking + non-stop)
gdb-cli attach --pid 9876

# Attach with symbol file
gdb-cli attach --pid 9876 --binary ./my_program

# Allow memory modification and function calls
gdb-cli attach --pid 9876 --allow-write --allow-call

完整命令参考

load — 加载 Core Dump

gdb-cli load --binary <path> --core <path> [options]

  --binary, -b      Executable file path (required)
  --core, -c        Core dump file path (required)
  --sysroot         sysroot path (for cross-machine debugging)
  --solib-prefix    Shared library prefix
  --source-dir      Source code directory
  --timeout         Heartbeat timeout in seconds (default: 600)
  --gdb-path        GDB executable path (default: "gdb")

load 在 RPC 服务器可达后立即返回 "status": "loading"。请使用 gdb-cli status -s <session> 并等待 "state": "ready" 后再执行繁重的检查命令。

attach — 附加到进程

gdb-cli attach --pid <pid> [options]

  --pid, -p               Process PID (required)
  --binary                Executable file path (optional)
  --scheduler-locking     Enable scheduler-locking (default: true)
  --non-stop              Enable non-stop mode (default: true)
  --timeout               Heartbeat timeout in seconds (default: 600)
  --allow-write           Allow memory modification
  --allow-call            Allow function calls

threads — 列出线程

gdb-cli threads -s <session> [options]

  --range           Thread range, e.g., "3-10"
  --limit           Maximum return count (default: 20)
  --filter-state    Filter by state ("running" / "stopped")

bt — 回溯（Backtrace）

gdb-cli bt -s <session> [options]

  --thread, -t      Specify thread ID
  --limit           Maximum frame count (default: 30)
  --full            Include local variables
  --range           Frame range, e.g., "5-15"

eval-cmd — 执行表达式

gdb-cli eval-cmd -s <session> <expr> [options]

  --max-depth       Recursion depth limit (default: 3)
  --max-elements    Array element limit (default: 50)

eval-element — 访问数组/容器元素

gdb-cli eval-element -s <session> <expr> --index <N>

exec — 执行原生 GDB 命令

gdb-cli exec -s <session> <command>

  --safety-level    Safety level (readonly / readwrite / full)

thread-apply — 批量线程操作

gdb-cli thread-apply -s <session> <command> --all
gdb-cli thread-apply -s <session> <command> --threads "1,3,5"

输出示例

threads

{
  "threads": [
    {"id": 1, "global_id": 1, "state": "stopped"},
    {"id": 2, "global_id": 2, "state": "stopped"}
  ],
  "total_count": 5,
  "truncated": true,
  "current_thread": {"id": 1, "global_id": 1, "state": "stopped"},
  "hint": "use 'threads --range START-END' for specific threads"
}

eval-cmd

{
  "expression": "(int)5+3",
  "value": 8,
  "type": "int",
  "size": 4
}

bt

{
  "frames": [
    {"number": 0, "function": "crash_thread", "address": "0x400a1c", "file": "test.c", "line": 42},
    {"number": 1, "function": "start_thread", "address": "0x7f3fa2e13fa"}
  ],
  "total_count": 2,
  "truncated": false
}

安全机制

命令白名单（附加模式）

安全级别	允许的命令
`readonly` (默认)	bt, info, print, threads, locals, frame
`readwrite`	+ set variable
`full`	+ call, continue, step, next

quit, kill, shell, signal 始终被拦截。

心跳超时

默认情况下，闲置 10 分钟后自动分离并退出。可通过 --timeout 配置。

幂等性

每个 PID / Core 文件仅允许一个会话。重复的 load/attach 操作将返回现有的 session_id。

跨机器 Core Dump 调试

分析其他机器的 core dump 时，共享库路径可能不同：

# Set sysroot (path prefix replacement)
gdb-cli load --binary ./my_program --core ./core.1234 \
  --sysroot /path/to/target/rootfs

# Set source directory (for source-level debugging)
gdb-cli load --binary ./my_program --core ./core.1234 \
  --source-dir /path/to/source

开发

项目结构

src/gdb_cli/
├── cli.py              # CLI entry point (Click)
├── client.py           # Unix Socket client
├── launcher.py         # GDB process launcher
├── session.py          # Session metadata management
├── safety.py           # Command whitelist filter
├── formatters.py       # JSON output formatting
├── env_check.py        # Environment check
├── errors.py           # Error classification
└── gdb_server/
    ├── gdb_rpc_server.py   # RPC Server core
    ├── handlers.py         # Command handlers
    ├── value_formatter.py  # gdb.Value serialization
    └── heartbeat.py         # Heartbeat timeout management

skills/
└── gdb-cli/               # Claude Code skill for intelligent debugging
    ├── SKILL.md            # Skill definition
    └── evals/              # Test cases for skill evaluation

运行测试

pip install -e ".[dev]"
pytest tests/ -v

端到端测试

需要支持 Python 的 GDB。使用 tests/crash_test/ 中的崩溃测试程序：

# Compile test program
cd tests/crash_test
gcc -g -pthread -o crash_test crash_test_c.c

# Generate coredump
ulimit -c unlimited
./crash_test  # Will SIGSEGV

# Find core file
ls /path/to/core_dumps/core-crash_test-*

# Run E2E test
gdb-cli load --binary ./crash_test --core /path/to/core \
  --gdb-path /opt/rh/gcc-toolset-13/root/usr/bin/gdb

已知限制

不支持 target remote（请使用 SSH 进行远程调试，见下文）
不支持多下级（multi-inferior）调试
GDB 12.x 的 Guile pretty printers 不是线程安全的，可通过 format_string(raw=True) 绕过
GDB 内嵌的 Python 版本可能较旧（例如 3.6.8），代码已包含兼容性处理

通过 SSH 进行远程调试

一行命令在远程机器上安装并运行：

ssh user@remote-host "pip install git+https://github.com/Cerdore/gdb-cli.git && gdb-cli load --binary ./my_program --core ./core.12345"

或者先安装，再调试：

# Install on remote
ssh user@remote-host "pip install git+https://github.com/Cerdore/gdb-cli.git"

# Run debugging
ssh user@remote-host "gdb-cli load --binary ./my_program --core ./core.12345"

Claude Code 技能

本项目包含一个用于 Claude Code 的 gdb-cli 技能，通过结合源代码分析与运行时状态检查，提供智能调试辅助。

安装技能

bunx skills add https://github.com/Cerdore/gdb-cli --skill=gdb-cli

在 Claude Code 中使用

/gdb-cli

# Or describe your debugging need:
I have a core dump at ./core.1234 and binary at ./myapp. Help me debug it.

特性

源代码关联：自动读取崩溃点周围的源代码文件
死锁检测：识别多线程程序中的循环等待模式
安全警告：在附加到实时进程时提醒生产环境风险
结构化报告：生成包含根本原因假设和后续步骤的分析报告

详情请参阅 skills/README.md。

许可证

Apache License 2.0