Debug Mind

中文 | [English](README_EN.md)

DebugMind

记忆增强的 AI Bug 诊断智能体 每次诊断都让下一次更快 —— 像有经验的老工程师在旁边。

🤗 在线体验 Live Demo  ·  Search Memory 无需 API Key，20 个真实案例即搜即用

---

解决一个真实的痛点

工程师平均将 20% 的工作时间 花在 Debug 上。其中很大一部分是"这个问题我上个月刚解决过"——经验散落在 Slack 消息、个人笔记和别人的脑子里，每次排查都从零开始。

> 同一个 Redis 连接池耗尽导致的 NullPointerException，团队里不同工程师可能在一年内各自独立排查三次。

DebugMind 的核心假设：如果每次排障结果都能结构化写入知识库，下次 AI 诊断时先检索历史案例，重复问题的定位时间可以从小时级降到分钟级。

这不是一个聊天机器人包装器。它是一个会随时间积累经验的诊断系统。

---

效果

检索基准（20 个种子用例）+ 记忆消融 A/B 实测（50 个 bug 场景 × 有/无记忆两臂 × 3 次重复 = 300 次端到端运行，DeepSeek v4-flash，2026-06）：

| 指标 | 数值 | |------|------| | hit@1 / hit@3（检索还原正确根因） | 0.92 / 0.97 | | 重复类 Bug 正确率：无记忆 → 有记忆 | 72% → 83%（+11pp） | | 推理错误（reasoning_error）次数 | 20 → 12（−40%） | | 全新类 Bug 正确率（无害性对照组） | 90% → 92%（记忆不误导未见过的 Bug） | | 自学习飞轮（空库起跑两轮，只靠自存经验） | 第 2 轮成本 −17%、步数 −10%、正确率持平 | | 稳定性：pass@3 / pass^3（同题 3 次全对） | 100% / 74% | | 测试覆盖 | 304 个测试，0 失败 |

> 复现：debug-mind eval --ablation --runs 3 与 debug-mind eval --learning-curve，原始数据写入 evaluation/results/。 > 诚实口径：记忆买到的主要是正确率而不是墙钟速度——检索内容进上下文使单次 token 略增； > 步数下限被工作流卡住（必须先查记忆、最后存结论，~3 步起）。pass^3 = 74% 说明稳定性是已知短板， > 且两臂 flakiness gap 相同（26%），抖动来自模型与关键词评判，不来自记忆。详见 [docs/EVALUATION.md](docs/EVALUATION.md)。

---

工作流程

用户输入：症状描述 + 错误日志（+ 可选：项目代码路径）
          │
          ▼
    ① 检索记忆库
       向量相似度 × 0.75 + 词法匹配 × 0.25
       已验证案例 × 1.0 优先，命中次数 log 加权
          │
    ┌─────┴──────┐
    │ 命中相似案例 │         │ 无匹配
    ▼             ▼         ▼
  加载历史诊断    ② ReAct 诊断循环（最多 20 轮）
  快速定位修复       搜索代码 → 读文件 → 分析日志 → 推理根因
    │             │
    └─────┬───────┘
          ▼
    ③ 输出：根因 + 修复建议 + 置信度
          │
          ▼
    ④ 写入记忆库（Markdown 文件 + 向量索引）
       供下次命中使用，hit_count 累积

---

快速开始

pip install -e .
export ANTHROPIC_API_KEY=sk-ant-...

# 纯记忆模式：只需症状描述
debug-mind diagnose "登录时偶发 NullPointerException，日志有 Redis 错误"

# 完整模式：结合代码库诊断
debug-mind diagnose \
  --project /path/to/your/project \
  --log error.log \
  --env "java=17,framework=Spring Boot 3.2" \
  "高峰期 UserService.login 出现 NPE"

# 搜索历史案例
debug-mind search "redis connection pool exhausted"

# 启动 Web UI
debug-mind web

---

架构设计

DebugMind 分为五层，每层独立可替换：

| 层级 | 组件 | 说明 | |------|------|------| | 客户端层 | CLI · Web UI · MCP Client | 命令行终端、Gradio 浏览器界面、MCP 协议接口（Claude Code / Desktop） | | Agent 层 | DiagnosticAgent · ReAct 循环 | 工具调用式推理，token / 成本 / 挂钟三重预算；支持 Anthropic · OpenAI · DeepSeek · GLM | | 技能层 | ripgrep · tree-sitter | 代码搜索、文件读取、项目结构分析 | | 记忆层 | 混合检索 · Embedding | 0.75×语义向量 + 0.25×词法匹配；verified/hit_count 动态排序 | | 存储层 | SQLite · ChromaDB · Markdown | 默认纯 Python 零依赖；可选 HNSW 加速；Markdown 为数据源头可 git 追踪 |

---

关键设计决策

> 这一节解释"为什么这么做"，而不只是"做了什么"。

为什么 SQLite 是默认后端，而不是 ChromaDB？

ChromaDB 更专业，但需要 C 扩展，在 CI 环境和 Windows 上经常安装失败。对于个人使用和 case_id: abc123 | severity: high | status: fixed

症状

登录返回 500，第 42 行 NullPointerException

根因

Redis 连接池耗尽 → getLoginToken() 返回 null → NPE

修复建议

1. 连接池大小增加到 32（当前 8）
2. .equals() 前加 null 检查

标签

npe, redis, spring-boot, connection-pool

• verified: true | hitcount: 7 | lastused_at: 2026-05-20

---

## MCP 集成

将 DebugMind 的记忆接入 Claude Code 或 Claude Desktop：

```json
{
  "mcpServers": {
    "debug-mind": {
      "command": "python",
      "args": ["-m", "debug_mind.tools.mcp_server"],
      "env": { "DEBUG_MIND_MCP_TOKEN": "your-secret-token" }
    }
  }
}

暴露的工具：search_similar_bugs · save_bug_case · verify_bug_case · get_bug_stats

---

存储后端

| 后端 | 安装 | 适用场景 | |------|------|---------| | SQLite（默认） | 无需额外安装 | 个人使用， 1M 案例、多副本、共享 Milvus 基础设施 |

DEBUG_MIND_BACKEND=chroma debug-mind rebuild

> Milvus 接入点已经在 src/debug_mind/memory/backends/milvus_backend.py 留好， > StorageBackend 协议是可插拔的；什么时候真该切到 Milvus 见 [docs/MILVUS.md](docs/MILVUS.md)。

---

完整命令

# 诊断与搜索
debug-mind diagnose "描述" [--project 路径] [--log 文件] [--env k=v]
debug-mind search "查询词"   [--top-k 5]
debug-mind list              [--limit 20]
debug-mind show 

# 记忆管理
debug-mind verify  --correct | --wrong [--notes "..."]
debug-mind delete 
debug-mind rebuild           # 从 Markdown 重建向量索引
debug-mind doctor [--fix]   # 检查索引一致性
debug-mind export / import  # 跨机器共享记忆

# 记忆生命周期
debug-mind decay [--days 30]    # 标记长期未命中的陈旧案例
debug-mind reverify [--days 90] # 列出需要重新确认的老案例
debug-mind link   [--relation caused_by|variant|fixed_by]

# 评测与审计
debug-mind eval [--search-only]              # 检索质量（hit@k，进 CI）
debug-mind eval --trajectory [--sample N]    # 轨迹评测（步数/token/成本/失败分类）
debug-mind eval --ablation [--runs K]        # 记忆消融 A/B + pass^k 稳定性
debug-mind eval --learning-curve [--rounds N] # 经验飞轮：空库起跑，第二轮靠自存经验
debug-mind audit [--since 24h] [--op save|verify|delete]

# 集成
debug-mind serve   # 启动 MCP 服务器
debug-mind web     # 启动 Gradio Web UI（默认端口 7860）

---

主要环境变量

| 变量 | 默认 | 说明 | |------|------|------| | ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY / ZHIPU_API_KEY | — | 按所选 provider 设置 | | DEBUG_MIND_BACKEND | sqlite | sqlite 或 chroma | | DEBUG_MIND_PROVIDER | anthropic | anthropic、openai、deepseek、glm / zhipu | | DEBUG_MIND_MAX_COST | 0.5 | 每次诊断最大 USD 花费 | | DEBUG_MIND_MAX_TOKENS | 50000 | 每次诊断最大 token 数 | | DEBUG_MIND_MCP_TOKEN | — | MCP 写操作鉴权 |

完整列表见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。

---

演进方向：从诊断工具到自治闭环

当前 DebugMind 处于 Level 1.5——人工触发，AI 诊断后能生成补丁（diff）并在沙箱里跑测试验证，失败的修法会以低置信 UNRESOLVED "死路"写回记忆；但触发靠人、合并靠人。真正的价值在于把这个链路自动化到底：

Level 1
  人工输入症状 → AI 诊断 → 人工修复

Level 1.5（现在）
  人工输入症状 → AI 诊断 → 生成补丁 → 沙箱跑测试
                                ↓通过        ↓失败
                          输出可提交修复   记为死路、换方案重试

Level 2（近期目标）
  告警/工单触发 → AI 自动诊断 → 输出修复方案 → 人工审核后合并

Level 3（终态）
  告警/工单触发 → AI 诊断（先查记忆库）→ AI 尝试修复 → 跑测试验证
                                                  ↓                    ↓
                                           测试通过             测试失败 / 置信度不足
                                                  ↓                    ↓
                                        自动开 PR + 关工单      回退 + 工单升级给人
                                                  ↓                    ↓
                                         写入 ✅ 成功案例       写入 ❌ 失败案例
                                        （下次同类秒解）        （避免重蹈覆辙）

失败案例和成功案例同样有价值：AI 尝试了某个方向修不好，这条"错误路径"会以低置信 UNRESOLVED 证据写进记忆库，下次遇到相似问题不会再走同一条死路。记忆库不只是"正确答案库"，而是完整的排障经验图谱。

---

路线图

已完成

• [x] 混合检索（向量 + 词法 + verified/hit_count 排序）
• [x] 可插拔 embedding 提供者（OpenAI、Voyage、BGE、默认 ONNX）
• [x] MCP Server（鉴权 + 限流 + 审计日志）
• [x] Token/成本预算 + 挂钟超时
• [x] 并发写安全（filelock）
• [x] Hermes 工具治理层：严格 schema 校验、风险分级、重复调用拦截、trajectory trace
• [x] SQLite / ChromaDB 双后端
• [x] Gradio Web UI + 多 Provider API Key 支持
• [x] 记忆生命周期：衰减、再验证、案例关联图
• [x] 自愈闭环单机版：propose_patch 生成 diff → 沙箱跑测试 → AgentRunState 缓冲失败补丁并以低置信死路记忆落盘
• [x] 记忆消融 A/B（eval --ablation）+ pass^k 稳定性 + 自学习曲线（eval --learning-curve）
• [x] 304 个测试 + CI/CD 工作流

近期（Level 2）

• [ ] PyPI 正式发布（pip install debug-mind）
• [x] Hugging Face Spaces 在线 Demo
• [ ] 工单系统接入：飞书 / Jira / PagerDuty Webhook，告警自动触发诊断
• [ ] 社区基准案例库（100+ 真实 Bug 类型）

中期（Level 3）

• [ ] 自动开 PR：沙箱验证通过的补丁自动提 PR + 关工单（补丁生成与沙箱验证已在 Level 1.5 完成）
• [ ] 失败回滚机制：测试不通过自动回退，工单重新入队 + 升级标记
• [ ] 容器级沙箱：当前沙箱为文件级隔离，升级为容器级以支持不可信代码
• [ ] 多项目命名空间 + RBAC 权限隔离

---

本地开发

pip install -e ".[dev]"
pytest                        # 304 个测试
ruff check src/ tests/ evaluation/  # lint
debug-mind eval --search-only # 检索质量评测（期望 hit@1 ≥ 0.85）

详见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。

---

许可证

MIT — 随意使用、Fork、二次开发。

---

基于 Claude · SQLite · MCP 构建 · 架构文档 · 评测方法

喂给它的 Bug 越多，它就越聪明。

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zavoryn
• Source: zavoryn/debug-mind
• License: MIT

Install and usage instructions live in the source repository linked above.