Metadata-Version: 2.4
Name: bug-repair-agent
Version: 0.2.0
Summary: 基于 Agent 的服务自动化修复系统
Author: fwHanHacker
License-Expression: MIT
Project-URL: Homepage, https://github.com/fwHanHacker/bug-repair-agent
Project-URL: Repository, https://github.com/fwHanHacker/bug-repair-agent
Project-URL: Issues, https://github.com/fwHanHacker/bug-repair-agent/issues
Keywords: agent,code-repair,langgraph,automation,bug-fix
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: langgraph>=0.2.0
Requires-Dist: langchain-anthropic>=0.3.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: anthropic>=0.40.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: langfuse>=2.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: mypy>=1.14.0; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"

# 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），路由函数只读判断走向。

## 快速开始

### 安装

```bash
pip install bug-repair-agent
```

### 配置

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

### 运行

```bash
# 内置 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

```bash
bug-repair serve --port 8000
```

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

请求体：
```json
{
  "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 地址 |

## 测试

```bash
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](docs/architecture.md)

## 协议

MIT
