# PatchPilot

**Repository Path**: yeyu8866/patch-pilot

## Basic Information

- **Project Name**: PatchPilot
- **Description**: 基于Java基座的coding agent
- **Primary Language**: Java
- **License**: GPL-2.0
- **Default Branch**: __dsh_auth_probe__
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-11-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PatchPilot

一个仓库级迷你 Coding Agent，能够在沙箱容器中自动修复 Bug 并生成补丁。

## 项目概述

PatchPilot 是一个自动化代码修复 agent，基于大语言模型驱动，可在隔离的 Docker 容器中执行修复任务并输出补丁文件。项目采用多阶段流水线架构，包含问题定位、计划制定、代码编辑、测试验证等完整闭环。

## 模块架构

```
patchpilot/
├── agent-core/      # 核心 Agent 运行时（状态机、循环控制器）
├── cli/             # 命令行入口（run、eval 命令）
├── common/          # 公共接口与数据类型定义
├── dataset/         # 数据集构建与任务装配流水线
├── eval/            # 评测框架与判分器
├── llm/             # LLM 客户端（DeepSeek/Qwen）
├── sandbox/         # Docker 沙箱实现
├── tools/           # 工具集（edit、search、run_tests 等）
└── trace/           # 运行轨迹记录器
```

### 核心模块说明

| 模块 | 职责 |
|------|------|
| **agent-core** | 两种 Agent 实现：`MinimalLoopAgent`（最小循环）和 `PhaseMachineAgent`（多阶段状态机） |
| **cli** | 提供 `run` 命令（在沙箱中执行单任务）和 `eval` 命令（批量评测） |
| **common** | 定义核心接口（`LlmClient`、`Sandbox`、`Tool`）及数据类型（`Task`、`RunResult` 等） |
| **sandbox** | `DockerSandbox`：基于 Docker 的隔离执行环境 |
| **tools** | 六个内置工具：`edit`、`search`、`list_dir`、`read_file`、`run_tests`、`view_diff` |
| **eval** | 判分器 Judge，实现六分类（SUCCESS/FAILED/PARTIAL/REGRESSION/NO_VALID_PATCH/ENVIRONMENT_ERROR） |
| **dataset** | 任务数据集装配流水线，含 P2P（PASS_TO_PASS）选择引擎 |
| **llm** | DeepSeek 客户端，支持重试策略与思考模式 |
| **trace** | JSONL 格式轨迹记录，含 API Key 脱敏与大 Prompt 溢出处理 |

## 快速开始

### 前置要求

- Java 21+
- Maven 3.9+
- Docker Daemon

### 构建

```bash
# 构建全部模块
mvn clean install -DskipTests

# 仅构建运行时 JAR（含依赖）
mvn package -pl cli -am -DskipTests
```

### 运行

```bash
# 单任务运行
java -jar cli/target/patchpilot-cli-*.jar run --task tasks/v1/jsoup-1949/task.json

# 批量评测
java -jar cli/target/patchpilot-cli-*.jar eval \
    --manifest tasks/v1/manifest.json \
    --split dev \
    --runs-per-task 3 \
    --agent-jar target/patchpilot-agent.jar
```

## 设计文档

- [设计规范 (spec)](docs/superpowers/specs/2026-10-02-patchpilot-coding-agent-design.md)
- [W1-W2 实施计划](docs/superpowers/plans/2026-10-02-patchpilot-w1-w2-foundation.md)
- [W3-W4 评测流水线计划](docs/superpowers/plans/2026-10-04-patchpilot-w3-w4-eval-pipeline.md)
- [W5-W6 状态机与扩展计划](docs/superpowers/plans/2026-10-07-patchpilot-w5-w6-statemachine-and-scale.md)

## 核心概念

### 任务定义 (Task)

任务采用 JSON 格式，包含：

```json
{
  "schema_version": "1.0",
  "task_id": "jsoup-1949",
  "repo": "jhy/jsoup",
  "base_commit": "abc123",
  "problem_statement": "...",
  "FAIL_TO_PASS": [{"class": "HtmlParserTest", "method": "testEmpty"}],
  "PASS_TO_PASS": [{"class": "ElementTest", "method": "testClone"}],
  "build_system": "maven",
  "test_command_template": "mvn test -Dtest={tests}"
}
```

### Agent 流水线阶段

1. **INIT** - 初始化
2. **LOCATE** - 定位问题（运行失败测试、分析栈帧、搜索可疑文件）
3. **PLAN** - 制定修复计划（锚点自检）
4. **EDIT** - 执行代码编辑
5. **TEST_TARGET** - 运行 FAIL_TO_PASS 测试
6. **TEST_FULL** - 运行 PASS_TO_PASS 回归测试
7. **FINALIZE** - 生成补丁

### 判分六分类

| 分类 | 条件 |
|------|------|
| SUCCESS | F2P 全部通过，P2P 无回归 |
| PARTIAL | F2P 部分通过（至少 1 个），P2P 无回归 |
| FAILED | F2P 全部失败 |
| REGRESSION | F2P 全部通过，P2P 存在回归 |
| NO_VALID_PATCH | 空白/格式错误/上下文不匹配 |
| ENVIRONMENT_ERROR | 环境问题（超时、依赖、权限等） |

## 工具集

| 工具 | 功能 |
|------|------|
| `edit` | 精确编辑文件（多级匹配：精确→行尾空白→缩进→任意位置） |
| `search` | 代码搜索（ripgrep） |
| `read_file` | 读取文件内容（带行号、截断、偏移支持） |
| `list_dir` | 列出目录树 |
| `run_tests` | 执行测试（Maven/Gradle） |
| `view_diff` | 查看 Git 差异 |

## 数据集

- `tasks/v1/` - 首批 10 道 jsoup 任务
- `tasks/w2-smoke/` - W2 验证集（5 道任务）
- `dataset/` - 数据集挖掘流水线（Python）

## 许可证

Apache License 2.0