debugium

Debugium

通过 MCP 集成 LLM、配备实时 Web UI 的多语言调试器。

在浏览器中调试 Python、JavaScript、TypeScript、C、C++、Rust、Java、Scala 和 WebAssembly 程序，并通过 Model Context Protocol 使用 AI 驱动的分析。

---

功能

Web UI

• 实时 Web UI — 源代码查看器、断点、变量（递归展开）、调用栈、控制台、时间线、监视表达式、发现项——全部通过 WebSocket 实时更新
• 多标签页源代码查看器 — 打开多个文件，点击栈帧即可导航
• 变量搜索 — 按名称筛选变量，并支持递归展开
• 变量变化高亮 — 上次暂停后发生变化的变量会以橙色显示
• 线程选择器 — 在多线程程序的线程之间切换
• 面板折叠与调整大小 — 拖动即可调整大小，切换即可折叠；提供 Slim / Standard / Full 布局预设
• 深色 / 浅色模式切换
• 自动重连 — WebSocket 断开后 UI 会自动重连，并显示状态指示器
• 键盘快捷键 — F5 继续，F10 单步跳过，F11 单步进入，Shift+F11 单步跳出，Ctrl/Cmd+D 切换深色模式
• 按钮动画 — 调试命令执行期间显示加载动画，完成后闪烁提示

调试

• 多语言 — Python (debugpy)、Node.js/TypeScript (js-debug)、C/C++/Rust (lldb-dap)、Java (java-debug)、Scala (Metals)、WebAssembly (lldb-dap)，或通过 dap.json 使用任意 DAP 适配器
• 全面支持 DAP — 支持 35+ 个 DAP 请求：断点、单步执行、跳转、内存读写、反汇编等
• 断点 — 条件断点、日志点、命中次数断点、函数断点、数据断点（监视点）、异常断点、运行至光标处 (continue_until)
• 多会话 — 同时调试多个程序，并支持子会话路由 (js-debug)
• 远程调试 — 附加到在另一台计算机或容器上运行的 debugpy、JDWP 或 Node inspector

LLM / MCP 集成

• 64 个 MCP 工具 — 向 Claude 或任意 LLM 提供完整的调试会话
• 按能力控制工具 — 根据适配器的能力自动显示或隐藏工具
• 组合工具 — get_debug_context（一次调用即可了解情况）、step_until、step_until_change、run_until_exception、explain_exception、get_call_tree、compare_snapshots、find_first_change
• 执行时间线 — 记录每次暂停时的变量变化和栈摘要
• 监视表达式 — 每次断点处都会自动求值，可由 LLM 或 UI 管理
• 注释与发现项 — 在源代码行上固定备注，并记录可在 UI 中查看的结论
• 会话导出 / 导入 — 保存并恢复跨会话的调试知识

CLI 控制

• 完整 CLI — 提供 13 个子命令，无需 Web UI 即可从第二个终端控制会话
• 自动发现 — 端口文件位于 ~/.debugium/port，会话日志位于 ~/.debugium/sessions/

---

安装

Claude Code 插件（推荐）

/plugin marketplace add Algiras/debugium
/plugin install debugium@debugium

然后在项目的 .mcp.json 中添加配置（参见下文的 MCP 工具）。

macOS / Linux 二进制文件

curl -fsSL https://raw.githubusercontent.com/Algiras/debugium/main/install.sh | bash

从源代码安装

# Prerequisites: Rust stable + wasm-pack
cargo install wasm-pack

# Build UI
wasm-pack build crates/debugium-ui --target web --out-dir pkg
cp crates/debugium-ui/pkg/cm_init.js         crates/debugium-ui/dist/pkg/
cp crates/debugium-ui/pkg/debugium_ui.js      crates/debugium-ui/dist/pkg/
cp crates/debugium-ui/pkg/debugium_ui_bg.wasm crates/debugium-ui/dist/pkg/

# Build & install server
cargo install --path crates/debugium-server

---

用法

调试 Python 文件

debugium launch my_script.py --adapter python

调试 Node.js / TypeScript 文件

debugium launch app.js --adapter node
debugium launch app.ts --adapter typescript

调试 C / C++ / Rust

# C or C++ (compile with -g for debug info)
cc -g -O0 main.c -o main && debugium launch ./main --adapter lldb
c++ -g -O0 main.cpp -o main && debugium launch ./main --adapter lldb

# Rust
cargo build && debugium launch target/debug/my_binary --adapter lldb

调试 Java / Scala

# Java (requires microsoft/java-debug adapter)
debugium launch MainClass --adapter java

# Scala (connect to a running Metals DAP server)
debugium launch build-target --adapter metals
debugium launch build-target --adapter metals:5005  # custom port

附加到正在运行的进程（远程调试）

# Python (debugpy listening on port 5678)
debugium attach --port 5678 --adapter python

# Java (JDWP on port 5005)
debugium attach --port 5005 --adapter java

# Node.js (inspector on port 9229)
debugium attach --port 9229 --adapter node

或者通过 MCP：attach_session(port=5678, adapter="python", breakpoints=["/path/app.py:42"])

通过 dap.json 使用自定义适配器

# Create a dap.json (see dap.json.example) then:
debugium launch my_program --config ./dap.json

# Or place dap.json in cwd / .debugium/ for auto-discovery:
debugium launch my_program   # finds ./dap.json automatically

设置初始断点

debugium launch my_script.py --adapter python \
  --breakpoint /abs/path/my_script.py:42 \
  --breakpoint /abs/path/helpers.py:15

启用 LLM / MCP 集成

在项目根目录中添加 .mcp.json（Claude Code 会自动读取此文件）：

{
  "mcpServers": {
    "debugium": {
      "command": "debugium",
      "args": ["mcp"]
    }
  }
}

然后正常启动会话 — MCP 服务会连接到当前处于活动状态的端口：

debugium launch my_script.py --adapter python --breakpoint /abs/path/my_script.py:42

Claude Code 现在可以使用所有 Debugium MCP 工具。推荐的工作流请参阅 CLAUDE.md，完整的工具参考请参阅 SKILL.md。

---

CLI 控制命令

会话运行后（debugium launch …），你可以从第二个终端 — 或 LLM Agent — 操作会话，无需使用 Web UI。

端口会自动从 ~/.debugium/port 发现；可使用 --port 覆盖。

全局标志（所有子命令）

标志	默认值	说明
--port PORT	~/.debugium/port	要连接的服务端口
--session ID	default	目标会话
--json	off	输出原始 JSON，而非易读内容

检查

debugium sessions                  # list active sessions
debugium threads                   # list threads
debugium stack                     # show call stack
debugium vars                      # show local variables (auto-resolves top frame)
debugium vars --frame-id 2         # show variables for a specific frame
debugium eval "len(fibs)"          # evaluate expression in top frame
debugium eval "x + 1" --frame-id 2
debugium source path/to/file.py    # print full source file
debugium source path/to/file.py --line 43  # windowed ±10 lines with → marker
debugium context                   # full snapshot: paused-at, stack, locals, source, breakpoints
debugium context --compact         # same but truncated (3 frames, 10 vars)

断点

debugium bp set FILE:LINE [FILE:LINE …]   # set breakpoints (replaces existing in that file)
debugium bp list                          # list all breakpoints
debugium bp clear                         # clear all breakpoints

执行控制

debugium continue                  # resume execution
debugium step over                 # step over (next line)
debugium step in                   # step into a function call
debugium step out                  # step out of current function

UI 注释（在 Web UI 中可见）

debugium annotate FILE:LINE "message" [--color info|warning|error]
debugium finding "message"         [--level  info|warning|error]

工作流示例

# Terminal A — start the session
debugium launch tests/target_python.py --adapter python \
  --breakpoint "$(pwd)/tests/target_python.py:43"

# Terminal B (or LLM agent) — inspect and drive it
debugium sessions
debugium stack
debugium vars
debugium eval "len(fibs)"
debugium bp set tests/target_python.py:49
debugium continue                  # runs to line 49
debugium vars
debugium step over
debugium context --json            # machine-readable snapshot
debugium annotate tests/target_python.py:43 "called here" --color info
debugium finding "fibs has 10 elements" --level info
debugium bp clear

---

MCP 工具

通过 MCP 连接时，可使用 64 个工具。主要工具：

类别	工具
定位	get_debug_context ★（一次调用即可获取暂停位置 + 局部变量 + 调用栈 + 源代码）
断点	set_breakpoint、set_breakpoints、set_logpoint、list_breakpoints、clear_breakpoints、set_function_breakpoints、set_exception_breakpoints、set_data_breakpoint、list_data_breakpoints、clear_data_breakpoints、breakpoint_locations
执行	continue_execution、step_over、step_in、step_out、pause、goto、disconnect、terminate、restart
检查	get_stack_trace、get_scopes、get_variables、evaluate、get_threads、get_source、get_capabilities、loaded_sources、source_by_reference、step_in_targets
修改	set_variable、set_expression
输出	get_console_output、wait_for_output（使用 from_line 避免匹配到过期内容）
内存	read_memory、write_memory、disassemble（原生调试）
历史记录	get_timeline、get_variable_history、compare_snapshots、find_first_change
注释	annotate、get_annotations、add_finding、get_findings
监视项	add_watch、remove_watch、get_watches
复合操作	step_until、step_until_change、continue_until、run_until_exception、explain_exception、get_call_tree、restart_frame
会话	get_sessions、list_sessions、launch_session、attach_session、stop_session、export_session、import_session
控制	goto_targets、cancel_request

注意：step_over、step_in 和 step_out 是阻塞式的 — 它们会等待适配器暂停后才返回。可以连续调用，无需等待。 continue_execution 会返回 console_line_count，供 wait_for_output 使用。 只有在适配器支持时，才会显示 read_memory、goto 和 restart_frame 等工具。

完整参考及输入架构请参阅 SKILL.md。

---

键盘快捷键

按键	操作
F5	继续
F10	单步跳过
F11	单步进入
Shift+F11	单步跳出
Ctrl/⌘+D	切换深色 / 浅色模式

---

架构

debugium-server (Rust + Axum)
├── DAP proxy     — spawns / attaches to debug adapters (debugpy, js-debug, lldb-dap, java-debug, Metals, custom)
├── HTTP API      — /state, /sessions, /annotations, /findings, /watches, /timeline
├── WebSocket     — broadcasts DAP events + enriched stop data (changed vars, timeline) to UI
├── MCP stdio     — JSON-RPC 2.0 server exposing 64 tools for LLM integration
├── CLI control   — 13 subcommands to drive sessions from a second terminal
└── ~/.debugium/  — port file, session logs (events.ndjson), debug log

debugium-ui (Leptos + WASM)
├── CodeMirror 6  — source viewer with breakpoint gutters, exec arrow, LLM annotations, multi-tab
├── Reactive panels — Variables, Stack, Breakpoints, Findings, Watch, Timeline, Console (18 components)
└── WebSocket     — receives events, sends DAP commands, auto-reconnects with status indicator

---

支持的语言与适配器

语言	--adapter 标志	前置条件	已验证
Python	python / debugpy	pip install debugpy	✅
Node.js	node / js	js-debug（随附或从 vscode-js-debug 构建）	✅
TypeScript	typescript / ts / tsx	PATH 中有 js-debug 和 tsx 或 ts-node	✅
C / C++	lldb / codelldb	lldb-dap（macOS 上使用 Xcode；Linux 上使用 apt install lldb）	✅
Rust	lldb / rust	lldb-dap 和 cargo build	✅
Java	java / jvm	microsoft/java-debug 适配器 JAR	✅
Scala	metals / scala	正在运行的 Metals DAP 服务	⚠️（需要 Metals 正在运行）
WebAssembly	wasm	lldb-dap（LLVM ≥16）	⚠️（需要支持 WASM 的 LLVM）
任意 DAP 适配器	--config dap.json	参见 dap.json.example	✅

远程调试

连接到在另一台机器上（或容器中）运行的 DAP 服务：

{
  "adapterId": "debugpy",
  "request": "attach",
  "host": "192.168.1.100",
  "port": 5678,
  "pathMappings": [{ "localRoot": ".", "remoteRoot": "/app" }]
}

debugium launch app.py --config remote.json

---

许可证

MIT