NeuralDebug

面向软件与大语言模型（LLM）推理过程的 AI 驱动调试框架。DeepRhapsody 项目的一部分。

当被要求调试程序、诊断崩溃、分析 core dump、检查 LLM 推理过程、检测幻觉（hallucination），或对模型进行微调时，请使用该能力。

NeuralDebug 的功能

🔧 软件调试（支持 8 种语言）

使用真实调试器（而非仅靠代码阅读）调试 Python、C/C++、C#、Rust、Java、Go、Node.js/TypeScript 和 Ruby。NeuralDebug 通过统一的自然语言接口，驱动 GDB、LLDB、CDB、JDB、Delve、Node Inspector 和 rdbg 等调试后端。

🧠 LLM 调试

逐层（layer by layer）遍历 Transformer 前向传播过程。运行可解释性技术，深入理解模型为何生成特定输出：Logit Lens、Attention 分析、Probing、Activation Patching，以及自定义分析沙箱（analysis sandbox）。

🎯 LLM 微调

基于 LoRA 向 GPT-2 系列模型注入缺失知识。实现“诊断 → 微调 → 验证”一体化工作流。

安装

# 克隆仓库
git clone https://github.com/DennySun2020/DeepRhapsody.git
cd DeepRhapsody

# 安装 Python 依赖
pip install torch transformers

# （可选）如需微调支持
pip install peft==0.7.1

快速入门：软件调试

交互模式（持久化调试会话）

# 启动任意受支持语言的调试服务端
python src/NeuralDebug/python_debug_session.py serve --port 5678

# 通过自然语言发送指令
python src/NeuralDebug/python_debug_session.py cmd -p 5678 launch my_script.py
python src/NeuralDebug/python_debug_session.py cmd -p 5678 set_breakpoint 42
python src/NeuralDebug/python_debug_session.py cmd -p 5678 continue
python src/NeuralDebug/python_debug_session.py cmd -p 5678 inspect

单次模式（快速断点捕获）

python src/NeuralDebug/python_debugger.py debug my_script.py --breakpoint 42 --output result.json

支持的语言

所有脚本均位于 src/NeuralDebug/ 目录下，并共享一致的命令行接口。

快速入门：LLM 调试

# 启动 LLM 调试服务端
python src/NeuralDebug/llm/llm_debug_session.py serve -m gpt2-medium -p 5680

# 向模型提问
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 start "The capital of Japan is"
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 generate 20

# 可解释性分析：答案在哪个层级产生？
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 logit_lens

# 可解释性分析：哪些 attention head 关注了 "Japan"？
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 attention 3

# 可解释性分析：各层分别编码了哪些知识？
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 probe next_token

# 可解释性分析：预测是否具有日本特异性？
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 patch "The capital of France is"

支持的 LLM 模型

任何具备内置适配器（adapter）的 HuggingFace 因果语言模型（causal LM）：

• GPT-2 系列：distilgpt2、gpt2、gpt2-medium、gpt2-large、gpt2-xl
• Llama 系列：Llama、Mistral、Qwen、DeepSeek
• 自定义模型：实现 ModelAdapter 并完成注册

快速入门：LLM 微调

# 创建配置文件（JSON 格式）
cat > ft_config.json << 'EOF'
{
  "facts": [
    "Dr. Elena Vasquez is the director of Horizon Research Labs",
    "Dr. Elena Vasquez leads Horizon Research Labs"
  ],
  "verification_prompt": "Dr. Elena Vasquez is the director of",
  "expected_token": "Horizon",
  "config": { "num_steps": 150, "lora_r": 16, "lora_alpha": 32, "learning_rate": 2e-4 }
}
EOF

# 执行微调（复用 LLM 调试服务端）
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 -t 600 finetune ft_config.json

# 验证结果
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 start "Dr. Elena Vasquez is the director of"
python src/NeuralDebug/llm/llm_debug_session.py cmd -p 5680 generate 20

架构设计

NeuralDebug 采用基于 TCP/JSON 的客户端-服务端架构：

AI Agent（OpenClaw、Copilot、Claude 等）
    │
    ▼
调试会话脚本（TCP 客户端）
    │
    ▼
NeuralDebug 服务端（监听可配置端口的 TCP 服务端）
    │
    ▼
真实调试后端（GDB / LLDB / CDB / PyTorch hooks 等）

每条命令均返回结构化的 JSON 输出——可被任意 AI Agent 解析。

平台支持

• Windows（CDB、Visual Studio 调试器）
• Linux（GDB、LLDB）
• macOS（LLDB、GDB）

相关链接

• 代码仓库：https://github.com/DennySun2020/DeepRhapsody
• 文档中心：https://github.com/DennySun2020/DeepRhapsody/wiki
• 问题反馈（Issues）：https://github.com/DennySun2020/DeepRhapsody/issues

详细命令说明请参阅 references/ 目录：

• software-debugging.md —— 全部 8 种语言的完整命令参考
• llm-debugging.md —— 可解释性技术与 LLM 相关命令详解
• llm-finetuning.md —— LoRA 微调工作流与配置说明