# Debug Mind

> AI-Powered Bug Diagnosis Agent with Experiential Memory — the more bugs it sees, the faster it gets.

- **Type:** MCP server
- **Install:** `agentstack add mcp-zavoryn-debug-mind`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zavoryn](https://agentstack.voostack.com/s/zavoryn)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zavoryn](https://github.com/zavoryn)
- **Source:** https://github.com/zavoryn/debug-mind

## Install

```sh
agentstack add mcp-zavoryn-debug-mind
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

**中文** | [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 累积
```

---

## 快速开始

```bash
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  | hit_count: 7  | last_used_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 基础设施 |

```bash
DEBUG_MIND_BACKEND=chroma debug-mind rebuild
```

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

---

## 完整命令

```bash
# 诊断与搜索
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 权限隔离

---

## 本地开发

```bash
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](https://github.com/zavoryn)
- **Source:** [zavoryn/debug-mind](https://github.com/zavoryn/debug-mind)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-zavoryn-debug-mind
- Seller: https://agentstack.voostack.com/s/zavoryn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.