CI Patch Verification Agent

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

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

解决的问题

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

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

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。

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 运行

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 或生产级队列。

详细设计见 架构说明 与 安全边界。

开源范围

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

License

本项目采用 MIT License。