# CI Patch Verification Agent

一个面向 Python CI / 单元测试失败场景的本地 Agent 工作流示例。系统不会让模型直接修改代码，而是将故障复现、受控排查、候选补丁、沙盒验证、人工审批和测试回归串成可追踪的流程。

> 定位：个人学习项目与本地工程化 MVP，不是生产级自动修复平台，也不会自动提交、推送或创建 PR。

## 解决的问题

CI 测试失败后，开发者通常需要反复查看报错、定位源码、尝试修改并重新跑测试。直接让模型给出补丁不够可靠：它可能误解报错、修改错误位置，或让目标测试通过但破坏相邻功能。

本项目将模型限制在“分析和提出候选动作”的范围内，并保留验证和人工决策门槛。

```mermaid
flowchart LR
    A[提交故障任务] --> B[检索已审核经验卡]
    B --> C[复现目标测试]
    C --> D[受控读取与排查]
    D --> E[生成候选补丁]
    E --> F[沙盒验证]
    F --> G{人工审批}
    G -->|批准| H[写入任务副本]
    H --> I[目标测试与相关测试]
    G -->|拒绝| J[安全结束]
    I --> K[审核后沉淀经验卡]
```

## 已实现能力

- 使用 LangGraph `StateGraph` 编排任务状态和条件分支。
- 使用 FastAPI 提供创建、运行、查询、审批和取消任务的本地接口。
- 通过 SQLite 保存任务、State、Trace、证据、快照和审批记录。
- 模型只输出受 Schema 约束的动作；工具层额外校验名称、参数、路径、文件类型、步骤数和超时。
- 候选补丁先展示 diff 并在独立 Workspace 中验证；人工批准后才允许写入任务副本。
- 先运行目标测试验证原故障，再运行最多 5 条相关测试检查相邻功能。
- 将验证成功的根因和方法生成经验卡草稿，经过人工审核、范围过滤和重复卡决策后复用。
- 提供本地 `stdio` MCP Server，暴露创建、运行、查询、查看 Trace、预览补丁和取消任务等 6 个 Tool。

## 验证证据

项目使用 3 个公开 Python 故障任务验证受控闭环：

- Tenacity #233：配置复制时遗漏 `retry_error_callback`。
- more-itertools #658：`split_after(..., maxsplit=1)` 的边界条件错误。
- python-dateutil #981：无效日期应包装为 `ParserError`，但泄漏了 `TypeError`。

三个任务均完成“复现失败 → 候选补丁 → 沙盒验证 → 人工批准 → 目标测试通过”的受控闭环。当前项目自身测试基线为 `324 passed, 1 warning`。

上述闭环结果是本地验证记录。公开仓库只提供 Agent、测试和脱敏评测素材，不内置第三方目标仓库副本；要复现完整闭环，需要自行取得相应公开仓库并放入本地 `targets/`，再按权限和版本说明运行。

跨仓库范围过滤用的合成占位样本单独放在 `data/evaluation_scope_fixtures.json`，不会进入正式经验卡库。

## 快速开始

### 1. 本地 Python 运行

要求：Python 3.11。

```powershell
git clone https://github.com/liaohaodong1122-rgb/ci-patch-verification-agent.git
cd ci-patch-verification-agent
Copy-Item .env.example .env
pip install -r requirements-dev.txt
python -m pytest -q tests
uvicorn api.main:app --host 127.0.0.1 --port 8001
```

打开 `http://127.0.0.1:8001/` 查看本地操作页，或访问 `http://127.0.0.1:8001/docs` 查看 API 文档。

模型调用需要在本地 `.env` 中配置兼容接口；测试不需要真实模型密钥。

### 2. Docker 运行

```powershell
Copy-Item .env.example .env
docker compose up --build
```

容器只挂载本地 `targets/` 目录为只读输入。请将自己有权使用的测试仓库放在该目录下；本仓库不包含任何第三方目标仓库副本。

## MCP Tools

本地 MCP Server 默认使用 `stdio`，提供以下 Tool：

| Tool | 作用 |
|---|---|
| `create_ci_task` | 创建受控故障诊断任务 |
| `run_ci_task` | 启动任务 |
| `get_ci_task` | 查询任务状态 |
| `get_ci_trace` | 查看 Trace 与证据 |
| `get_ci_patch_preview` | 查看候选补丁预览 |
| `cancel_ci_task` | 请求取消任务 |

MCP 只负责标准化工具接入。它不直接读写源码、SQLite 或模型，也不提供批准补丁的 Tool；审批仍由本地操作员完成。

## 安全边界

- 不自动写入原始目标仓库，只操作每个任务的独立副本。
- 不自动执行 Git commit、push、PR 或回退操作。
- 不开放任意命令执行、任意路径访问或任意文件修改。
- 不应直接部署为公网代码执行服务。
- 当前是单机、本地 `stdio` MCP MVP，未实现多租户权限、远程 MCP、高并发 Worker 或生产级队列。

详细设计见 [架构说明](docs/ARCHITECTURE.md) 与 [安全边界](docs/SECURITY.md)。

## 开源范围

本仓库只包含可公开的独立代码、脱敏示例数据和公开 Issue 的验证说明；不包含 API 密钥、本地数据库、临时工作区、第三方仓库副本或任何私人项目素材。

## License

本项目采用 [MIT License](LICENSE)。