内容
# LLDB 代理
LLDB 插件，通过 **MCP**（模型上下文协议）和纯 **HTTP** 公开调试器，以便外部 AI 代理（Claude Code、Claude Desktop 等）可以通过单个 `dbg_exec` 工具驱动调试会话。
> 插件不嵌入 **任何 AI**。它是一个薄桥：它根据请求运行 LLDB 命令并返回其输出。自带代理。
## 要求
- LLDB 16+，带有开发头文件
- CMake 3.20+
- C++17 编译器
### 平台特定要求
**Linux:**
```bash
sudo apt install liblldb-dev lldb
```
**macOS:**
```bash
xcode-select --install
```
**Windows:**
```powershell
winget install LLVM.LLVM
```
注意：winget 包在运行时需要 Python 3.10（参见下面的 [Windows 设置](#windows-设置)）。
## 构建
**Linux/macOS:**
```bash
cmake --preset default
cmake --build --preset default
```
**Windows:**
```cmd
cmake --preset windows
cmake --build --preset windows
```
输出：
- Linux：`build/lldb_agent.so`
- macOS：`build/lldb_agent.dylib`
- Windows：`build-windows/Release/lldb_agent.dll`
插件依赖于 [fastmcpp](https://github.com/0xeb/fastmcpp)（作为 `external/fastmcpp` 下的子模块提供），它提供了 MCP 服务器、cpp-httplib 和 nlohmann_json。
## 使用
```bash
# 使用程序启动 LLDB
lldb ./myprogram
# 加载插件
(lldb) plugin load /path/to/lldb_agent.so
# 启动 MCP（SSE）服务器 - 阻塞直到 Ctrl+C
(lldb) agent mcp
# ... 或纯 HTTP 服务器
(lldb) agent http
```
当服务器启动时，它会打印其 URL 和端点（并在 Windows 上复制到剪贴板）。将 MCP 客户端指向 SSE 端点，或向 HTTP 端点发送 POST 命令，并在 LLDB 中按 **Ctrl+C** 停止服务器。
## 命令
| 命令 | 描述 |
|---------|-------------|
| `agent help` | 显示帮助 |
| `agent version` | 显示版本 |
| `agent mcp [bind_addr]` | 启动 MCP（SSE）服务器，阻塞直到 Ctrl+C |
| `agent http [bind_addr]` | 启动纯 HTTP 服务器，阻塞直到 Ctrl+C |
`bind_addr` 默认值为 `127.0.0.1`（仅限本地主机）。传递 `0.0.0.0` 以监听所有接口 - 注意服务器 **没有身份验证**，因此仅在受信任的网络中执行此操作。
## MCP 客户端配置
`agent mcp` 打印一个可以直接粘贴的代码段，例如适用于 Claude Desktop：
```json
{
"mcpServers": {
"lldb-agent": {
"url": "http://127.0.0.1:<port>/sse"
}
}
}
```
## HTTP API
`agent http` 公开：
| 方法 | 路径 | 目的 |
|--------|------|---------|
| POST | `/exec` | 运行调试器命令：`{"command": "bt"}` → `{"output": "...", "success": true}` |
| GET | `/status` | 服务器准备就绪 |
| POST | `/shutdown` | 停止服务器 |
```bash
curl -X POST http://127.0.0.1:<port>/exec \
-H "Content-Type: application/json" \
-d '{"command": "bt"}'
```
## Windows 设置
winget 中的 LLVM 包需要 Python 3.10 来运行 LLDB。下载并解压到项目 `bin` 文件夹：
```powershell
# 下载并解压嵌入式 Python 3.10 到项目 bin 文件夹
Invoke-WebRequest -Uri "https://www.python.org/ftp/python/3.10.11/python-3.10.11-embed-amd64.zip" -OutFile "$env:TEMP\python310.zip"
Expand-Archive -Path "$env:TEMP\python310.zip" -DestinationPath "..\bin\python310" -Force
```
然后使用设置环境的 `test_lldb.cmd` 包装脚本：
```cmd
cd lldb_agent
test_lldb.cmd
```
### 快速测试
```cmd
test_lldb.cmd
(lldb) target create "C:\Windows\System32\notepad.exe"
(lldb) run
```
按 Ctrl+C 停止，然后启动服务器：
```
(lldb) agent mcp
```
## 作者
Elias Bachaalany ([@0xeb](https://github.com/0xeb))
与 Claude Code 和 Codex 共同编程。
## 许可证
MIT
