akiselev/debugger-cli

# debugger-cli **专为 LLM 编程智能体构建的命令行调试器** [](https://crates.io/crates/debugger-cli) [](LICENSE) [](https://www.rust-lang.org/) `debugger-cli` 是一款跨平台的调试工具，它使 LLM 编程智能体（以及人类！）能够使用 [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) 来调试可执行程序。它提供了一个简单、可脚本化的 CLI 接口，能够在多次命令调用之间保持持久的调试会话。 ## 为什么需要它 LLM 智能体需要交互式地调试程序，但 CLI 命令是短暂的。传统的调试器需要一个交互式会话，这与智能体的工作流不兼容。此工具通过以下方式解决了这个问题： - **维护持久会话**：一个后台 daemon 在命令之间保持调试会话处于活动状态 - **缓冲事件**：即使没有连接客户端，输出、断点命中和停止事件也会被捕获 - **提供统一接口**：适用于任何 DAP 适配器（lldb-dap、CodeLLDB、debugpy、Delve 等） - **对 LLM 友好**：清晰、易于解析的输出，专为智能体读取而优化 ## 功能 - **多语言支持**：调试 C、C++、Rust、Python、Go 等 - **零设置门槛**：`debugger setup lldb` 会自动安装您所需的一切 - **完整的断点控制**：支持行号、函数和条件断点 - **丰富的检查功能**：查看变量、表达式、堆栈跟踪和源代码上下文 - **线程管理**：列出、切换和浏览线程与堆栈帧 - **结构化输出**：对智能体友好的 JSON 格式 - **跨平台**：支持 Linux、macOS 和 Windows ## 快速开始 ### 安装 ``` # 从 crates.io 安装 cargo install debugger-cli # 安装 debug adapter（例如，用于 C/C++/Rust 的 lldb） debugger setup lldb ``` 或者从源码构建： ``` git clone https://github.com/akiselev/debugger-cli.git cd debugger-cli cargo install --path . ``` ### 前置条件 您需要一个兼容 DAP 的调试适配器。最简单的方法是： ``` # 列出可用的调试器 debugger setup --list # 为你的语言安装 debugger setup lldb # C, C++, Rust, Swift debugger setup python # Python (debugpy) debugger setup go # Go (Delve) debugger setup gdb # C, C++ (requires GDB 14.1+) debugger setup cuda-gdb # CUDA (Linux only) ``` 或者手动安装： - **Arch Linux**: `sudo pacman -S lldb` - **Ubuntu/Debian**: `sudo apt install lldb` - **macOS**: `xcode-select --install`（包含 lldb） ### 基本用法 ``` # 开始调试程序 debugger start ./myprogram # 设置 breakpoint debugger break main.c:42 # 或 debugger breakpoint add my_function # 运行至 breakpoint debugger continue # 等待程序停止 debugger await # 检查当前状态 debugger context # Source code + variables debugger locals # Local variables debugger backtrace # Stack trace debugger print myvar # Evaluate expression # 单步执行代码 debugger next # Step over debugger step # Step into debugger finish # Step out # 清理 debugger stop ``` ## 命令参考 ### 会话管理 | 命令 | 别名 | 描述 | |---------|---------|-------------| | `start [-- args]` | | 开始调试某个程序 | | `attach ` | | 附加到正在运行的进程 | | `stop` | | 停止调试会话并终止被调试程序 | | `detach` | | 与进程分离（保持其继续运行） | | `status` | | 显示 daemon 和会话状态 | | `restart` | | 在当前活动的 DAP 适配器支持时重启程序 | 启动选项： - `--adapter ` - 使用指定的调试适配器 - `--stop-on-entry` - 在程序入口点处停止 - `--break ` / `-b` - 在程序启动前设置初始断点 ### 断点 | 命令 | 别名 | 描述 | |---------|---------|-------------| | `breakpoint add ` | `break`, `b` | 添加断点（文件:行号 或 函数） | | `breakpoint remove ` | | 通过 ID 移除断点 | | `breakpoint remove --all` | | 移除所有断点 | | `breakpoint list` | | 列出所有断点 | | `breakpoint enable ` | | 启用已禁用的断点 | | `breakpoint disable ` | | 禁用断点而不移除它 | 断点选项： - `--condition ` - 仅当表达式为真时中断 - `--hit-count ` - 命中 N 次后中断 ### 执行控制 | 命令 | 别名 | 描述 | |---------|---------|-------------| | `continue` | `c` | 恢复执行 | | `next` | `n` | 单步跳过（执行当前行） | | `step` | `s` | 单步进入（进入函数调用） | | `finish` | `out` | 单步跳出（运行直到函数返回） | | `pause` | | 暂停执行 | | `await` | | 等待下一个停止事件 | ### 检查 | 命令 | 别名 | 描述 | |---------|---------|-------------| | `context` | `where` | 显示当前位置的源代码 + 变量 | | `locals` | | 显示局部变量 | | `backtrace` | `bt` | 显示堆栈跟踪 | | `print ` | `p` | 计算表达式 | | `eval ` | | 带副作用地计算表达式 | | `threads` | | 列出所有线程 | ### 导航 | 命令 | 描述 | |---------|-------------| | `thread ` | 切换到某个线程 | | `frame ` | 导航到某个堆栈帧 | | `up` | 在堆栈中向上移动（前往调用者） | | `down` | 在堆栈中向下移动 | ### 程序输出 | 命令 | 描述 | |---------|-------------| | `output` | 获取程序的 stdout/stderr | | `output --follow` | 持续流式传输输出 | | `output --tail ` | 获取最后 N 行 | | `output --clear` | 打印并清除缓冲的输出 | ### 设置 | 命令 | 描述 | |---------|-------------| | `setup ` | 安装调试适配器 | | `setup --list` | 列出可用的调试器 | | `setup --check` | 检查已安装的调试器 | | `setup --auto` | 为检测到的项目自动安装 | ## 架构 ``` ┌─────────────────┐ IPC Socket ┌─────────────────┐ stdio (DAP) ┌─────────────────┐ │ CLI Mode │◄──────────────────►│ Daemon Mode │◄──────────────────►│ DAP Adapter │ │ (user facing) │ │ (background) │ │ (lldb-dap) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` 该工具以**单一二进制的两种模式**运行： 1. **CLI 模式**（瘦客户端）：解析命令，通过 IPC 连接到 daemon，显示结果 2. **Daemon 模式**（后台）：管理调试会话，与 DAP 适配器通信，缓冲事件 这种架构允许： - 在多次 CLI 调用之间保持持久的调试会话 - 在没有连接客户端时缓冲事件 - 非阻塞的命令执行 - 干净的进程生命周期管理 ## 配置 配置存储在 `~/.config/debugger-cli/config.toml` 中： ``` # 默认 debug adapter adapter = "lldb-dap" # 请求超时时间（秒） timeout = 30 # 自定义 adapter 路径 [adapters] lldb-dap = "/usr/bin/lldb-dap" codelldb = "~/.local/share/debugger-cli/adapters/codelldb/adapter/codelldb" ``` ## 支持的调试适配器 | 适配器 | 语言 | 状态 | |---------|-----------|--------| | lldb-dap | C, C++, Rust, Swift | ✅ 完全支持 | | debugpy | Python | ✅ 完全支持 | | Delve | Go | ✅ 完全支持 | | GDB | C, C++ | ✅ 完全支持（需要 GDB 14.1+） | | CUDA-GDB | CUDA, C, C++ | ✅ 完全支持（仅限 Linux） | | js-debug | JavaScript, TypeScript | ✅ 完全支持 | | CodeLLDB | C, C++, Rust | ✅ 完全支持 | | cpptools | C, C++ | 🚧 计划中 | ## 示例 ### 调试 Rust 程序 ``` # 以 debug info 构建 cargo build # 使用初始 breakpoint 开始调试 debugger start ./target/debug/myprogram --break main # 运行至 breakpoint debugger continue debugger await # 检查状态 debugger context # Thread 1 停止于 src/main.rs:15 # # 13 | let config = Config::load()?; # 14 | let processor = Processor::new(config); # -> 15 | processor.run()?; # # Locals: # config: Config { max_threads: 4, timeout: 30 } # 评估表达式 debugger print config.max_threads # 4 # 单步执行代码 debugger step debugger await # 清理 debugger stop ``` ### 调试 Go 程序 ``` # 以 debug info 构建 go build -gcflags="all=-N -l" -o myprogram # 开始调试 debugger start ./myprogram --adapter go --break main.main # 继续至 breakpoint debugger continue debugger await # 检查 goroutines debugger threads # 查看 locals debugger locals # 清理 debugger stop ``` ### 调试 CUDA 代码 (Linux) ``` # 以 debug info 编译 nvcc -g -G -o cuda_program kernel.cu # 开始调试（使用 cuda-gdb） debugger start ./cuda_program --adapter cuda-gdb --break main # 设置 kernel breakpoint debugger break vectorAdd # 运行至 kernel debugger continue debugger await # 查看 CUDA threads debugger threads debugger stop ``` ## 开发 请参阅 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) 获取开发者指南，内容包括： - 深入解析架构 - 添加新命令 - 使用 DAP 客户端 - 测试和调试技巧 ## 许可证 本项目基于 GNU General Public License v3.0 授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 贡献 欢迎贡献！请随时提交 issue 和 pull request。 1. Fork 该仓库 2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交您的更改 (`git commit -m 'Add amazing feature'`) 4. 推送到该分支 (`git push origin feature/amazing-feature`) 5. 发起一个 Pull Request

标签：Debug Adapter Protocol, LLM集成, Rust, SOC Prime, 可视化界面, 开发工具, 网络流量审计, 通知系统