Debug Mind

中文 | English

解决一个真实的痛点

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

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

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

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

效果

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

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

关键设计决策

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

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

ChromaDB 更专业，但需要 C 扩展，在 CI 环境和 Windows 上经常安装失败。对于个人使用和 <5K 案例场景，SQLite 的线性余弦搜索已经足够快（5K 条约 20ms），而且零额外依赖，pip install debug-mind 即可运行。

ChromaDB 作为可选项保留：pip install debug-mind[chroma]，一行环境变量切换，Markdown 文件原封不动。

为什么用 Markdown 文件而不只是向量数据库？

向量数据库是黑盒——你无法直接阅读它存了什么，也无法用 Git 追踪变化，迁移成本高。Markdown 文件是人类可读的，可以被 Git 管理、PR review、diff 对比，也可以在没有任何依赖的情况下重建向量索引（debug-mind rebuild）。

设计原则：Markdown 是数据源头，向量索引是加速层。

为什么用混合检索（向量 + 词法），而不是纯语义向量？

纯向量搜索对精确错误码（ORA-12541、ECONNREFUSED）的召回率很差——这些字符串在语义空间里是孤立点，和自然语言描述距离远。加入词法匹配后，错误码、包名、方法名这类关键词能被精确命中。

最终公式：blended = cosine × 0.75 + lexical × 0.25，再乘上 verified 系数和 hit_count 对数权重。

为什么自研控制循环，而不用 LangGraph / Agent SDK？

因为这个项目的研究对象就是循环本身。预算守护（token/成本/挂钟三重限制）、超限优雅降级、工具参数校验与自我纠正、轨迹级评测埋点——这些都需要对循环内部每一步的控制权，而框架恰好把这一层封装掉了。框架的价值在于快速搭业务应用；当你要测量和优化的就是 Agent 行为本身时，几百行透明的循环代码比框架的黑盒更有价值。代价是自己处理重试、流式、多 provider 适配——这些实现都在 agent.py 和 providers/，可以逐行审查。

为什么用 ReAct 而不是单轮提示？

单轮提示需要用户在输入时提供所有上下文，但 Bug 诊断本质上是迭代的：先看错误日志 → 定位到某文件 → 读该文件 → 发现真正问题在另一个依赖里。ReAct（Reason + Act）允许 Agent 动态决定"下一步需要看什么"，适合信息不完整的真实场景。

为什么实现 verified / hit_count 排序？

不是所有历史案例都同样可信。刚存入的案例可能诊断有误；被人工验证为正确的案例更可靠；被多次采用的案例说明它真的有效。三个信号叠加，让排序随时间自动优化，而不是静态的相似度排名。

记忆格式（可被 Git 管理）

# UserService.login 在 Redis 连接池耗尽时出现 NPE

> 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：

{
  "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

存储后端

DEBUG_MIND_BACKEND=chroma debug-mind rebuild

Milvus 接入点已经在 src/debug_mind/memory/backends/milvus_backend.py 留好， StorageBackend 协议是可插拔的；什么时候真该切到 Milvus 见 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 <case_id>

# 记忆管理
debug-mind verify <case_id> --correct | --wrong [--notes "..."]
debug-mind delete <case_id>
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 <A> <B> [--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）

主要环境变量

完整列表见 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 证据写进记忆库，下次遇到相似问题不会再走同一条死路。记忆库不只是"正确答案库"，而是完整的排障经验图谱。

路线图

已完成

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

近期（Level 2）

• PyPI 正式发布（pip install debug-mind）
• 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 和 docs/DEVELOPMENT.md。

许可证

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