debugium (Algiras)

Debugium

一个具有实时web UI和通过MCP集成LLM的多语言调试器。

从浏览器调试Python、JavaScript、TypeScript、C、C++、Rust、Java、Scala和WebAssembly程序——通过AI驱动的分析 模型上下文协议.

______________________________________________________________________

特性

网页用户界面

• 实时web UI --源代码查看器、断点、变量（递归扩展）、调用堆栈、控制台、时间线、观察表达式、发现——所有这些都通过WebSocket实时更新
• 多标签源查看器 --打开多个文件，单击堆栈框架进行导航
• 变量搜索 --用递归展开按名称过滤变量
• 更改变量突出显示 --自上次停车以来发生变化的变量以橙色显示
• 线程选择器 --在多线程程序中切换线程
• 面板折叠和调整大小 --拖动以调整大小，切换以折叠；薄型/标准/全布局预设
• 暗/亮模式 切换
• 自动重新连接 --UI在WebSocket丢失后重新连接，并显示可视化状态指示器
• 键盘快捷键 --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适配器，通过 dap.json
• DAP全面覆盖 --35+DAP请求：断点、步进、goto、内存读/写、反汇编等
• 断点 --条件、日志点、点击计数、函数、数据（观察点）、异常、运行到光标(continue_until)
• 多会话 --使用子会话路由（js-debug）同时调试多个程序
• 远程调试 --附加到在另一台计算机或容器上运行的debugpy、JDWP或Node检查器

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代码插件（推荐）

/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 为了 推荐的工作流程和 技能.md 以获取完整的工具参考。

______________________________________________________________________

CLI控制命令

会话运行后(debugium launch …)，您可以从第二个终端或LLM代理驱动它，而无需触摸web UI。

端口是从以下位置自动发现的 ~/.debugium/port；用以下命令覆盖 --port.

全局标志（所有子命令）

检查

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个工具可用。关键问题：

备注: step_over, step_in，以及 step_out 是 阻塞 --他们等待 适配器在返回前暂停。无需睡眠，即可安全地背靠背连接。 continue_execution 回报 console_line_count 用于 wait_for_output. 工具如 read_memory, goto，以及 restart_frame 仅当适配器支持它们时才会出现。

看 技能.md 以获取输入模式的完整参考。

______________________________________________________________________

键盘快捷键

______________________________________________________________________

建筑

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

______________________________________________________________________

支持的语言和适配器

远程调试

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

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

debugium launch app.py --config remote.json

______________________________________________________________________

许可证

麻省理工学院