bug-repair-agent 0.2.0

基于 Agent 的服务自动化修复系统

Bug Repair Agent

给报错日志，还你一个 PR。

基于 LangGraph 的自动化代码修复 Agent。输入生产异常报告，输出经过验证的修复 PR。支持 Python / Go / TypeScript / JavaScript 四种语言。

为什么需要它

生产环境报错，传统流程是：

报警 → 人工看日志 → 翻代码找原因 → 写修复 → 本地测 → 提 PR → Code Review → 合并

Bug Repair Agent 把这个流程压缩成一步：

报警日志 → bug-repair → PR

全程 10 个节点自动流转：解析 → 分析 → 定位 → 修复 → 审查 → 构建 → 测试 → 验证 → 审查 → 出 PR。

架构

                    ┌─────────────────────────────────────┐
                    │        用户输入层                     │
                    │  bug-repair run / demo / serve       │
                    └──────────────────┬──────────────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    │      LangGraph 工作流（10 节点）      │
                    │                                      │
                    │  parse → analyze → locate → fix     │
                    │                  ↑     │             │
                    │   quick_review ←┘     │             │
                    │        │              │             │
                    │   build → test → validate           │
                    │                        │            │
                    │   review ──────────────┘            │
                    │        │                            │
                    │   report → END                      │
                    │                                      │
                    │   任何节点异常 → 错误报告             │
                    │   返工失败 ≤3次 → 回跳 fix/locate    │
                    └──────────┬───────────────────────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
         sandbox.py      ci_runner.py     git_ops.py
         Docker 沙箱     CI 触发器        PR 提交

10 个节点

#	节点	做什么
1	parse	LLM 解析异常报告，提取 bug 摘要、错误日志、严重级别
2	analyze	读取源码（80KB token 预算），注入 SERVICE.md + git log 上下文，分析根因
3	locate	ReAct 工具循环（≤5轮），自主搜索/读取代码，定位到具体文件和行号
4	fix	生成 unified diff 补丁，返工时注入构建/测试错误上下文
5	quick_review	轻量安全预审查，提前拦截 SQL 注入/XSS 等问题
6	build	Docker 沙箱：安装依赖 → 编译 → 应用补丁
7	test	复用同一沙箱容器运行测试套件
8	validate	沙箱内 lint + LLM 语义验证
9	review	LLM 深度安全审查
10	report	生成 PR 标题和描述，清理沙箱

返工机制

quick_review / build / test 失败 → 回跳 fix
validate / review 失败 → 回跳 fix 或 locate（定位错则回跳 locate）
返工 ≥ 3 次 → 强制放行，PR 附加 WARNING 标记需人工审查

返工计数在节点执行层维护（真正持久化到 state），路由函数只读判断走向。

快速开始

安装

pip install bug-repair-agent

配置

cp .env.example .env
# 编辑 .env，填入 ANTHROPIC_API_KEY

运行

# 内置 demo 演示（库存超卖场景）
bug-repair demo

# 指定日报运行
bug-repair run -r report.md --repo /path/to/repo

# 启动 Webhook 服务
bug-repair serve --port 8000

命令	说明
bug-repair demo	内置 demo 演示
bug-repair run -r <日报> [--repo <仓库>]	指定日报运行
bug-repair serve	Webhook 服务模式

核心亮点

1. 完整的 10 节点工作流

不是简单的 "LLM 读代码 → 输出修复"。从日志解析到 PR 生成，每个环节独立验证，任何一步失败都有明确的返工路径。

2. ReAct 工具循环定位

locate 节点不是单次 LLM 调用就猜位置。它实现最多 5 轮的工具迭代：

• 先搜索关键词（search_code）
• 看到结果后决定下一步（继续搜索 or 读取文件）
• 读取确认（read_file）
• 最终输出精确的行号定位

3. Docker 沙箱隔离

build / test / validate 都在 Docker 容器内执行：

• 不污染宿主机环境
• 三个节点复用同一容器，避免重复拷贝代码和应用补丁
• 容器生命周期由 Agent 自动管理

4. 返工安全网

• 返工计数在节点层维护（非路由层），确保真正持久化
• 超过 3 次自动放行，PR 附加 WARNING 标记
• 记录每次返工的失败步骤和回跳目标到 rework_history

5. 全节点错误路由

任何节点抛异常 → _wrap 包裹器捕获 → 设置错误状态 → 路由直接到 report 输出错误报告。不会卡死在中间步骤。

6. 多语言支持

Python / Go / TypeScript / JavaScript 四种语言的自动检测，自动选择对应的构建命令、测试框架和 lint 工具。

7. Langfuse 可观测性

设置 LANGFUSE_ENABLED=true 后自动创建 trace，记录：

• 每次 LLM 调用的 prompt、response、token 消耗、延迟
• 各节点执行时间
• 完整的调用链

生成的 PR 描述中附带 trace 链接，方便审查修复过程。

Webhook API

bug-repair serve --port 8000

端点	方法	说明
/webhook/bug	POST	接收 bug 告警
/health	GET	健康检查

请求体：

{
  "report": "异常日志内容",
  "repo_path": "/path/to/repo"
}

配置项

详见 .env.example。

变量	说明
ANTHROPIC_API_KEY	LLM API 密钥
MODEL	模型名称（默认 claude-sonnet-4-6-20250514）
GIT_TOKEN	GitHub/GitLab 访问令牌
GIT_PLATFORM	平台类型（github / gitlab）
SANDBOX_TIMEOUT	沙箱命令超时（秒，默认 120）
LANGFUSE_ENABLED	是否启用 Langfuse（默认 false）
LANGFUSE_PUBLIC_KEY	Langfuse 公钥
LANGFUSE_SECRET_KEY	Langfuse 私钥
LANGFUSE_HOST	Langfuse 地址

测试

pytest tests/ -v

项目结构

bug-repair-agent/
├── src/
│   ├── agent/
│   │   ├── state.py          # LangGraph 状态定义
│   │   ├── tools.py          # 工具: list_files / read_file / search_code
│   │   ├── nodes.py          # 10 个节点实现
│   │   └── graph.py          # 工作流组装 + 返工路由 + 异常捕获
│   ├── cli.py                # CLI 入口 (run / demo / serve)
│   ├── config.py             # 环境变量加载
│   ├── sandbox.py            # Docker 沙箱
│   ├── ci_runner.py          # CI Runner (GitHub Actions)
│   ├── context_provider.py   # SERVICE.md + git log 上下文注入
│   ├── git_ops.py            # Git/PR 操作
│   ├── langfuse_ops.py       # Langfuse 可观测性
│   └── log_parser.py         # 多语言日志解析
├── demo/
│   └── inventory_service/    # 库存超卖场景 demo
├── tests/                    # 测试套件
└── docs/                     # 文档

详见 docs/architecture.md

协议

MIT