内容
<p align="center">
<img src="assets/logo.svg" alt="DebugForge Logo" width="200" height="200">
</p>
<h1 align="center">DebugForge</h1>
<p align="center">
<strong>桥接Lauterbach TRACE32调试器与AI代理，借助MCP</strong>
</p>
<p align="center">
<a href="https://github.com/YangPan2020/debugforge/actions"><img src="https://github.com/YangPan2020/debugforge/actions/workflows/ci.yml/badge.svg" alt="持续集成"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT许可证"></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-purple.svg" alt="MCP"></a>
</p>
<p align="center">
DebugForge是一个MCP服务器，它连接Lauterbach TRACE32调试器与AI代理。<br>
它为Claude Code、Codex、Qwen等AI代理提供直接访问硬件调试器的能力<br>
— 使它们能够自主地读取目标状态、定位软件错误并驱动调试-修复循环。<br>
支持本地和远程（WinRM/SSH）TRACE32环境。
</p>
---
## 亮点
- **47种MCP工具** — 为AI代理提供完整的TRACE32访问权限：执行控制、断点、内存、寄存器、变量、符号等
- **自主调试** — AI代理可以独立连接到目标、重现问题、定位根源并建议修复
- **本地 + 远程** — 本地调试或通过WinRM/SSH连接到远程Windows TRACE32，支持完整的 文件传输
- **项目感知** — 通过`debugforge.toml`配置一次，您的AI代理自动知道您的ELF路径、闪存脚本和TRACE32设置
- **真实硬件** — 在TC397 TriCore上经过实战测试，通过USB控制实际芯片，而不是模拟器
- **高级断点** — 条件断点、数据观察点、命中计数、任务特定、动作触发器和临时断点
- **深度检查** — AI代理可以读取调用栈、展开结构体、查看反汇编、检查外设
- **任意MCP代理** — 与Claude Code、Codex CLI、Qwen或任何MCP兼容的AI助手配合使用
- **零锁定** — MIT许可、开源、无厂商依赖（除了TRACE32本身）
## 架构
```
┌─────────────────┐ MCP（stdio） ┌──────────────┐ PYRCL/TCP ┌──────────────┐
│ │◄───────────────────────────►│ │◄─────────────────────►│ │
│ AI 代理 │ JSON-RPC工具调用 │ DebugForge │ 远程控制API │ TRACE32 │
│ （Claude Code、 │ （47种调试工具） │ MCP 服务器 │ （lauterbach-trace32 │ PowerView │
│ Codex等） │ │ │ -rcl） │ │
│ │◄───────────────────────────►│ │◄─────────────────────►│ │
└─────────────────┘ 结果 └──────────────┘ 硬件 └──────┬───────┘
│
┌──────▼───────┐
│ 目标MCU │
│ （例如TC397） │
└──────────────┘
```
### 远程模式
```
┌─────────────────────────────────────────────────────────────┐
│ 本地Linux（代理） │
│ - 源代码/ELF/CMM文件 │
│ - AI代理（DebugForge MCP服务器） │
└────────────────┬────────────────────────┬───────────────────┘
│ SCP/WinRM │ PYRCL（端口20000）
│ 文件传输 │ 远程控制
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ 远程Windows │
│ - TRACE32 PowerView │
│ - 硬件目标（TC38x/TC39x） │
└─────────────────────────────────────────────────────────────┘
```
## 快速入门
```bash
# 1. 安装DebugForge
pip install debugforge
# 2. 安装TRACE32 Python包（来自您的TRACE32安装）
pip install <您的T32路径>/demo/api/python/rcl/dist/lauterbach_trace32_rcl-*.whl
# 3. 添加到您的AI代理的MCP配置（例如.claude/settings.json）
```
```json
{
"mcpServers": {
"debugforge": {
"command": "debugforge"
}
}
}
```
```bash
# 4. 配置您的项目
cp debugforge.toml.example debugforge.toml
# 使用您的路径和连接设置编辑debugforge.toml
# 5. 启动TRACE32并启用API端口，然后询问您的AI代理：
# “连接到TRACE32，加载固件，找到系统在启动时崩溃的原因”
```
## 安装
### 先决条件
| 需求 | 详情 |
|-------------|---------|
| Python | 3.10或更高版本 |
| TRACE32 | PowerView运行，启用远程API |
| PYRCL | 来自您的TRACE32安装的`lauterbach-trace32-rcl`包 |
### 步骤1：安装DebugForge
```bash
pip install debugforge
```
或从源代码安装：
```bash
git clone https://github.com/YangPan2020/debugforge.git
cd debugforge
pip install -e .
```
### 步骤2：安装TRACE32 Python库
TRACE32安装中捆绑了PYRCL轮：
```bash
pip install <T32_INSTALL_PATH>/demo/api/python/rcl/dist/lauterbach_trace32_rcl-*.whl
```
### 步骤3：启用TRACE32远程API
将以下行添加到您的TRACE32配置文件（`.t32`或`config.t32`）：
```
RCL=NETTCP
PORT=20000
```
然后重启TRACE32 PowerView。
## 配置
### 项目配置（`debugforge.toml`）
在您的项目根目录中创建一个`debugforge.toml`。提供一个完整的模板：
```bash
cp debugforge.toml.example debugforge.toml
```
```toml
[模式]
模式 = "本地" # "本地" 或 "远程"
[连接]
节点 = "本地主机"
端口 = 20000
协议 = "TCP"
自动连接 = 真
[远程]
主机 = "192.168.1.100"
winrm端口 = 5985
winrm用户 = "用户@域名.本地"
winrm密码 = "您的密码"
ssh用户 = "用户名"
临时目录 = "D:\\T32\\debugforge"
[项目]
elf = "输出/构建/固件.elf"
[脚本]
闪存 = "工具/Trace32/闪存.cmm"
```
> **注意**：`debugforge.toml`包含凭证，应被git忽略。永远不要提交它。
### MCP客户端设置
<details>
<summary><strong>Claude Code</strong></summary>
添加到`.claude/settings.json`：
```json
{
"mcpServers": {
"debugforge": {
"command": "debugforge"
}
}
}
```
</details>
<details>
<summary><strong>Claude Code（自动连接）</strong></summary>
```json
{
"mcpServers": {
"debugforge": {
"command": "debugforge",
"env": {
"T32_AUTO_CONNECT": "true",
"T32_PORT": "20000"
}
}
}
}
```
</details>
<details>
<summary><strong>其他MCP客户端</strong></summary>
任何MCP兼容的客户端都可以使用DebugForge。将命令配置为`debugforge`，使用stdio传输。
</details>
### 环境变量
环境变量覆盖`debugforge.toml`值（优先级最高）：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `T32_INSTALL_PATH` | — | TRACE32安装目录 |
| `T32_NODE` | `localhost` | TRACE32主机地址 |
| `T32_PORT` | `20000` | TRACE32 API端口 |
| `T32_PROTOCOL` | `TCP` | 通信协议（TCP/UDP） |
| `T32_AUTO_CONNECT` | `false` | 服务器启动时自动连接 |
| `DEBUGFORGE_CONFIG` | `./debugforge.toml` | 配置文件路径 |
## 可用工具（47种）
### 连接与配置
| 工具 | 描述 |
|------|-------------|
| `connect` | 连接到TRACE32 PowerView实例 |
| `disconnect` | 从TRACE32断开连接 |
| `status` | 获取连接状态、TRACE32版本和系统状态 |
| `get_project_config` | 获取已加载的项目配置（路径、脚本、设置） |
### 执行控制
| 工具 | 描述 |
|------|-------------|
| `go` | 启动/继续程序执行 |
| `step` | 单步执行（进入、越过或退出） |
| `halt` | 停止程序执行 |
| `reset` | 重置目标CPU |
| `get_state` | 获取当前CPU执行状态 |
| `get_source_location` | 获取当前源文件和行号 |
| `get_current_function` | 获取当前执行的函数名称 |
| `get_run_stats` | 组合运行/停止统计 |
### 断点
| 工具 | 描述 |
|------|-------------|
| `set_breakpoint` | 设置程序/读取/写入/读写断点 |
| `list_breakpoints` | 列出所有活动断点 |
| `delete_breakpoint` | 删除断点 |
| `clear_all_breakpoints` | 一次删除所有断点 |
| `toggle_breakpoint` | 启用/禁用断点而无需删除 |
### 高级断点
| 工具 | 描述 |
|------|-------------|
| `set_conditional_breakpoint` | 带有HLL条件的断点（例如，`i > 100`） |
| `set_data_breakpoint` | 触发内存访问并可选地匹配值 |
| `set_count_breakpoint` | 在第N次命中后停止（循环调试） |
| `set_task_breakpoint` | 仅在特定OS任务/线程上触发 |
| `set_action_breakpoint` | 在命中时执行TRACE32命令 |
| `set_temporary_breakpoint` | 自动在第一次命中后删除 |
### 内存
| 工具 | 描述 |
|------|-------------|
| `read_memory` | 读取目标内存（十六进制转储格式） |
| `write_memory` | 向目标内存写入数据 |
| `read_memory_cached` | 通过CPU数据缓存读取 |
| `read_memory_physical` | 绕过缓存读取 |
### 寄存器
| 工具 | 描述 |
|------|-------------|
| `read_register` | 读取单个CPU寄存器 |
| `read_registers` | 一次读取多个寄存器 |
| `write_register` | 向CPU寄存器写入值 |
### 变量
| 工具 | 描述 |
|------|-------------|
| `read_variable` | 通过符号名称读取C/C++变量 |
| `write_variable` | 向C/C++变量写入值 |
| `var_view` | 以完整展开的方式查看变量/结构体/数组 |
### 符号
| 工具 | 描述 |
|------|-------------|
| `symbol_by_name` | 按名称查找符号地址 |
| `symbol_by_address` | 按地址查找符号名称 |
### 命令与脚本
| 工具 | 描述 |
|------|-------------|
| `execute_command` | 执行任何TRACE32 PRACTICE命令 |
| `run_practice` | 运行PRACTICE（.cmm）脚本，带超时 |
| `evaluate` | 评估TRACE32表达式或函数 |
### 调试视图
| 工具 | 描述 |
|------|-------------|
| `get_callstack` | 获取带有函数名称的调用栈 |
| `get_locals` | 获取调用栈，包含每个帧的所有局部变量 |
| `get_data_dump` | 格式化内存转储（十六进制 + ASCII） |
| `get_register_view` | 完整的寄存器视图，包含所有标志 |
| `get_window` | 获取任何TRACE32窗口命令的文本内容 |
### 多核
| 工具 | 描述 |
|------|-------------|
| `select_core` | 将调试器焦点切换到特定核心 |
| `get_chip_info` | 获取芯片步进和配置 |
| `get_all_cores_state` | 获取所有核心的执行状态 |
| `sync_cores` | 在核心之间同步Go/Break/Step |
### 片上跟踪（MCDS）
| 工具 | 描述 |
|------|-------------|
| `trace_start` | 配置并启动跟踪记录 |
| `trace_stop` | 停止跟踪记录 |
| `trace_list` | 显示跟踪缓冲区内容 |
| `trace_clear` | 清除跟踪缓冲区 |
| `trace_set_trigger` | 设置跟踪启动/停止触发器 |
### 系统配置
| 工具 | 描述 |
|------|-------------|
| `set_reset_behavior` | 配置重置处理 |
| `set_cache_read` | 启用/禁用缓存感知读取 |
| `set_peripheral_suspend` | 在暂停时暂停外设 |
| `load_symbol_file` | 加载ELF调试符号 |
| `get_system_options` | 获取所有系统选项设置 |
## 使用示例
### 基本调试会话
```
您：“连接到TRACE32并帮助我找到系统在启动后崩溃的原因”
AI代理工作流程：
1. get_project_config() → 学习您的ELF路径和脚本
2. connect() → 连接到TRACE32
3. run_practice("flash.cmm") → 闪存固件
4. set_breakpoint("main")
5. go() → 运行到main
6. step("over") → 步过代码
7. get_callstack() → 分析调用栈
8. read_variable("error_code") → 检查变量
→ “找到了：error_code = -1 因为init_hardware()在第84行失败”
```
### 远程调试会话
```
您：“连接到Windows上的远程TRACE32并调试TC397板”
AI代理工作流程：
1. get_project_config() → 检测远程模式，获取WinRM凭证
2. connect(node="192.168.1.100") → 通过网络上的PYRCL连接
3. run_practice("tc39x_flash.cmm") → 通过远程TRACE32闪存
4. go() → halt() → get_callstack()
→ 调试远程目标，就像它是本地的一样
```
## 支持的AI代理
| 代理 | 状态 | 配置 |
|-------|--------|---------------|
| [Claude Code](https://claude.com/claude-code) | ✅ 已测试 | `.claude/settings.json` |
| [Codex CLI](https://github.com/openai/codex) | ✅ 兼容 | MCP标准输入/输出传输 |
| [Qwen Agent](https://github.com/QwenLM/Qwen-Agent) | ✅ 兼容 | MCP标准输入/输出传输 |
| 任意MCP客户端 | ✅ 兼容 | 标准MCP协议 |
## 文件结构
```
debugforge/
├── src/debugforge/ # MCP服务器核心
│ ├── server.py # FastMCP服务器入口
│ ├── config.py # 配置（本地 + 远程）
│ ├── state.py # 连接状态管理
│ └── tools/ # 工具实现（47种工具）
├── examples/ # 示例脚本
│ ├── remote_debug.py # 通过WinRM + PYRCL进行远程调试
│ ├── remote_debug_tc38x.py
│ ├── test_all_tools.py # 完整工具验证
│ └── debug_tc397_live.py # TC397完整工作流程
├── debugforge.toml.example # 配置模板
├── WINDOWS_SSH_SETUP.md # 远程Windows设置指南
└── README.md
```
## 开发
### 设置
```bash
git clone https://github.com/YangPan2020/debugforge.git
cd debugforge
pip install -e ".[dev]"
```
### 运行测试
```bash
pytest tests/ -v
```
### 代码风格
```bash
ruff check src/ tests/
ruff format src/ tests/
```
## 许可证
[MIT](LICENSE) — 免费用于个人和商业用途。
---
<p align="center">
<sub>用❤️为嵌入式调试社区构建</sub>
</p>
连接信息
猜你喜欢
暂无推荐服务器