ResearchAnonymized/REFINE
GitHub: ResearchAnonymized/REFINE
REFINE 是一个基于多智能体架构的 Java 代码坏味道检测与 LLM 辅助自动重构平台，通过静态分析和编译验证确保每次重构都有据可查。
Stars: 0 | Forks: 0
# 优化
**用于坏味道驱动 Java 重构的证据感知多智能体系统。**
REFINE 能够检测代码坏味道，规划并应用 LLM 辅助的重构，通过自动化门禁验证每个候选方案，并记录完整的审计轨迹 —— 从交互式的单文件重构到跨多个 LLM 提供商的大规模批处理运行。
[](LICENSE)
[](https://adoptium.net/)
[](https://www.python.org/)
[](https://nodejs.org/)
## 目录
- [REFINE 的功能](#what-refine-does)
- [5 分钟体验](#try-it-in-5-minutes)
- [可测试的系统](#systems-you-can-test)
- [使用仪表盘](#using-the-dashboard)
- [安装与运行](#install-and-run)
- [架构](#architecture)
- [系统概览](#system-overview)
- [重构执行流程](#refactoring-execution-flow)
- [Agent 流水线](#agent-pipeline)
- [配置](#configuration)
- [仓库布局](#repository-layout)
- [开发](#development)
- [故障排除](#troubleshooting)
- [许可证](#license)
## REFINE 的功能
| 能力 | 描述 |
|------------|-------------|
| **工作区导入** | 上传 Java 项目 (ZIP) 或从 Git 克隆；每个项目成为一个独立的工作区 |
| **静态分析** | 基于 PMD 的坏味道检测，支持自定义规则集；提供文件和项目级别的指标 |
| **引导式重构** | 基于坏味道的规划，可行性检查，LLM 生成的补丁，以及接受/拒绝验证 |
| **批处理** | 一次运行重构多个文件；在相同基线上比较多个 LLM 提供商 |
| **证据与导出** | 保存重构报告、前/后指标对比，以及 Excel 工作簿 |
**分析过程无需 API 密钥。** LLM 辅助重构需要 [OpenRouter](https://openrouter.ai/keys) 密钥（或直接使用提供商的密钥 —— 详见配置）。
## 5 分钟体验
### 1. 启动 REFINE
```
git clone https://github.com/ResearchAnonymized/REFINE.git
cd REFINE
./scripts/setup.sh
cp agents/.env.example agents/.env # set OPENROUTER_API_KEY for LLM refactoring
./start-refine.sh
```
打开 **http://127.0.0.1:3001**
### 2. 上传内置的演示项目
```
cd examples/sample-java-repo
zip -r ../sample-java-repo.zip .
```
在 UI 中：**Project Hub → Upload** → 选择 `sample-java-repo.zip`。
### 3. 分析与重构
1. 打开新工作区 → **Run analysis**（PMD 坏味道扫描）。
2. 选择 `Calculator.java` → **AI Refactoring**（受控的单文件重构）。
3. 查看提议的更改、指标和验证门禁 → 接受或拒绝。
4. 可选：保存报告或将指标导出到 Excel。
验证技术栈：
```
./scripts/verify-install.sh
```
## 可测试的系统
REFINE 专为**真实的开源 Java 代码库**设计，而非玩具代码片段。您可以从内置的演示开始，然后转向知名的 OSS 项目。
### 内置演示
| 项目 | 位置 | 说明 |
|---------|----------|-------|
| **Calculator** | [`examples/sample-java-repo/`](examples/sample-java-repo/) | 故意设置的坏味道：长方法、上帝类、数据泥团。请压缩并上传。 |
### 推荐的 OSS Java 系统
这 **15 个代表性系统**涵盖了不同规模的库、构建工具、解析器和桌面应用程序：
| 项目 | 类型 | 规模 | 从这里开始？ | 仓库 |
|---------|------|-------|:-----------:|------------|
| JUnit 4 | 测试框架 | ~20 KLOC | ✅ | [junit-team/junit4](https://github.com/junit-team/junit4) |
| SLF4J | 日志门面 | ~20 KLOC | ✅ | [qos-ch/slf4j](https://github.com/qos-ch/slf4j) |
| jsoup | HTML 解析器 | ~29 KLOC | ✅ | [jhy/jsoup](https://github.com/jhy/jsoup) |
| Mockito | 模拟框架 | ~48 KLOC | ✅ | [mockito/mockito](https://github.com/mockito/mockito) |
| Logback | 日志框架 | ~59 KLOC | | [qos-ch/logback](https://github.com/qos-ch/logback) |
| GanttProject | 项目管理 | ~86 KLOC | | [bardsoftware/ganttproject](https://github.com/bardsoftware/ganttproject) |
| JHotDraw | GUI 框架 | ~122 KLOC | | [werner-duvaud/jhotdraw](https://github.com/werner-duvaud/jhotdraw) |
| Checkstyle | 静态分析 | ~188 KLOC | | [checkstyle/checkstyle](https://github.com/checkstyle/checkstyle) |
| JEdit | 文本编辑器 | ~193 KLOC | | [RMTT/jEdit](https://github.com/RMTT/jEdit) |
| Eclipse Collections | 集合库 | ~214 KLOC | | [eclipse/eclipse-collections](https://github.com/eclipse/eclipse-collections) |
| Apache Ant | 构建工具 | ~239 KLOC | | [apache/ant](https://github.com/apache/ant) |
| Apache Xerces-J | XML 解析器 | ~297 KLOC | | [apache/xerces2-j](https://github.com/apache/xerces2-j) |
| ArgoUML | UML 建模 | ~332 KLOC | | [argouml/argouml](https://github.com/argouml/argouml) |
| Guava | 核心工具库 | ~475 KLOC | | [google/guava](https://github.com/google/guava) |
| JabRef | 文献管理 | ~516 KLOC | | [JabRef/jabref](https://github.com/JabRef/jabref) |
**如何使用外部项目：** 克隆或下载 → 压缩项目根目录 → 在 Project Hub 中上传 → 运行 PMD 分析 → 先重构一个文件，然后进行批处理。
更多细节：[`examples/README.md`](examples/README.md)。
## 使用仪表盘
| 区域 | 您可以进行的操作 |
|------|-------------|
| **Project Hub** | 上传 ZIP 工作区，查看文件数量，运行工作区级别的 PMD 分析 |
| **Code Analysis** | 浏览整个项目中的坏味道、严重程度和文件级指标 |
| **AI Refactoring** | 交互式单文件重构，包含 规划 → 生成 → 验证 → 应用 流程 |
| **Batch Refactor** | 排队处理多个文件；支持在相同基线上进行可选的多 LLM 比较 |
| **Saved reports** | 重新打开之前的重构运行记录，查看前/后代码和指标 |
| **Excel export** | 下载包含重构证据和指标摘要的工作簿 |
### 典型工作流
```
Upload workspace → PMD analysis → pick file(s) → refactor → review gates → save report / export
```
### 测量内容
- PMD 规则违规情况（前 / 后）
- 结构指标（LOC、复杂度代理、文件大小）
- 重构接受度、相似度检查以及可选的 LLM 验证
- 每个文件和每次批处理运行的持久化审计轨迹
## 安装与运行
### 前置条件
| 工具 | 版本 |
|------|---------|
| Java (JDK) | 21+ |
| Maven | 3.8+ |
| Node.js | 18+ |
| Python | 3.10+ |
| OpenRouter API 密钥 | LLM 重构必需；仅用于分析时可选 |
### 命令
```
./scripts/setup.sh # first-time setup
./start-refine.sh # start web + backend + agents
./start-refine.sh status # health check
./start-refine.sh stop # stop all services
```
默认 URL: **http://127.0.0.1:3001**
| 服务 | 端口 |
|---------|------|
| Web UI | 3001 |
| Backend API | 8084 |
| Agents | 8092 |
在 `config/ports.env` 中覆盖端口。
可选的冒烟测试（在上传项目后）：
```
API_BASE=http://127.0.0.1:8084/api AGENTS_BASE=http://127.0.0.1:8092 \
./scripts/e2e-refactai-smoke.sh
```
## 架构
REFINE 由三个运行时层和外部 LLM 提供商组成。**Web 前端**驱动工作流；**Java 后端**管理工作区和静态分析；**Python 执行层**编排多智能体重构。
### 系统概览
```
flowchart TB
FE["Presentation layer
Next.js web dashboard · port 3001"] BE["Backend layer
Java Spring Boot API · port 8084
workspaces · PMD analysis · apply · compile"] EXE["Execution layer
Python FastAPI + LangGraph · port 8092
plan · refactor · verify · report"] STORE[("Workspace store
~/.refactai/workspaces")] LLM["LLM providers
OpenRouter / OpenAI / Google / Anthropic"] FE -->|"REST /api/*"| BE FE -->|"REST /agents/*"| EXE EXE <-->|"read files · smells · apply patches"| BE BE --> STORE EXE -->|"chat completions"| LLM ``` | 层级 | 技术 | 端口 | 职责 | |-------|------------|------|----------------| | **表现层** | Next.js (`web/app/`) | 3001 | 操作员 UI —— 上传项目、浏览分析结果、触发重构、审查证据 | | **后端层** | Java / Spring Boot (`backend/`) | 8084 | 工作区、PMD 坏味道检测、指标、应用补丁、编译检查 | | **执行层** | Python / FastAPI + LangGraph (`agents/`) | 8092 | 多智能体工作流 —— 规划、LLM 重构、验证门禁、报告 | | **外部层** | OpenRouter 或直接的 LLM API | — | 用于规划、重构和可选 LLM 验证的模型推理 | ### 重构执行流程 当用户从仪表盘重构一个文件时的端到端路径： ``` sequenceDiagram participant Web as Web UI participant BE as Java API participant AG as Agent service participant LLM as LLM provider Note over Web,BE: 1. Ingest and analyze Web->>BE: Upload workspace / PMD scan BE-->>Web: Smells and file metrics Note over Web,LLM: 2. Refactor one file Web->>AG: Refactor request AG->>BE: Load source and smell context BE-->>AG: File content Note over AG,LLM: 3. Generate candidate AG->>AG: Plan and feasibility checks AG->>LLM: Refactoring prompt LLM-->>AG: Candidate patch Note over AG,BE: 4. Verify and apply AG->>AG: Static and optional LLM verify AG->>BE: Apply patch BE-->>AG: Compile result Note over AG,Web: 5. Report AG-->>Web: Before/after metrics and evidence ``` **批处理模式**对多个文件重复步骤 2–5（并且可以在相同的基线上并行运行多个 LLM 提供商）。 ### Agent 流水线 在执行层内部，每次重构过程都遵循一个**垂直的 LangGraph 工作流**（11 个节点），分为以下五个阶段。蓝色节点调用 LLM；灰色节点基于规则或由后端支持。 ``` flowchart TB subgraph CTX["Context"] L["1. Load file"] A["2. Analyze smells"] L --> A end subgraph PLN["Planning"] P["3. Plan refactorings"] LP["4. LLM plan (optional)"] P --> LP end subgraph GEN["Generation"] F["5. Feasibility check"] R["6. Refactor — LLM"] F --> R end subgraph QLT["Quality"] V["7. Verify gates"] LV["8. LLM verify (optional)"] V --> LV end subgraph INT["Integration"] AP["9. Apply patch"] C["10. Compile check"] RP["11. Report"] AP --> C --> RP end A --> P LP --> F R --> V LV --> AP classDef llm fill:#2563eb,stroke:#1d4ed8,color:#ffffff class LP,R,LV llm ``` **流水线阶段** | 阶段 | 步骤 | 具体内容 | |-------|-------|----------------| | 上下文 | 1–2 | 加载 Java 源代码；附加 PMD 坏味道和指标上下文 | | 规划 | 3–4 | 基于规则的规划；可选的 LLM 规划细化 | | 生成 | 5–6 | 大小/安全门禁；LLM 生成候选补丁 | | 质量 | 7–8 | 静态验证门禁；可选的 LLM 审查 | | 集成 | 9–11 | 写入工作区（如果启用）；编译检查；保存报告 | 实现细节：[`agents/AGENT_ARCHITECTURE.md`](agents/AGENT_ARCHITECTURE.md) ``` curl -s http://127.0.0.1:8092/agents/health | jq . ``` ## 配置 | 文件 | 用途 | |------|---------| | `agents/.env` | API 密钥、模型、多智能体 LLM 模式 | | `config/ports.env` | 端口和 UI 功能标志 | ``` cp config/ports.env.example config/ports.env cp agents/.env.example agents/.env ``` **多智能体 LLM 模式**（`agents/.env` 中的 `MULTI_LLM_AGENT_MODE`）： | 值 | 行为 | |-------|----------| | `off` (默认) | 仅重构步骤使用 LLM | | `full` | 规划器、重构器和验证器各自调用 LLM | 有关多提供商路由，请参见 `config/multi-agent.env.example`。 ## 仓库布局 | 路径 | 角色 | |------|------| | `agents/` | Agent 编排服务 | | `backend/` | Java API 和分析引擎 | | `web/app/` | Web 仪表盘 | | `rulesets/` | PMD 规则定义 | | `examples/` | 演示 Java 项目和 OSS 测试指南 | | `config/` | 端口和功能标志模板 | `scripts/` | 安装、启动、验证、冒烟测试脚本 | ## 开发 ``` cd agents && pip install -r requirements.txt pytest python -m pytest -q --ignore=test_openrouter.py cd backend/server && mvn test ``` 请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 故障排除 | 问题 | 尝试方法 | |-------|-------------| | 后端无法启动 | 执行 `./scripts/setup.sh`；释放 8084 端口 | | Agent 状态异常 | 执行 `pip install -r agents/requirements.txt` | | LLM 错误 | 在 `agents/.env` 中设置 `OPENROUTER_API_KEY` | | 上传失败 | 使用项目根目录的 ZIP；避免嵌套归档 | | 大型仓库响应缓慢 | 从 `examples/sample-java-repo` 或 SLF4J/jsoup 开始尝试 | 日志（已在 gitignore 中忽略）：`backend/server.log`、`agents/agents.log`、`frontend.log` 安全：[SECURITY.md](SECURITY.md) ## 许可证 MIT — 详见 [LICENSE](LICENSE)。版权所有 匿名作者（为双盲评审而匿名化）。
规模指南（Java 文件，仅供参考）
| 项目 | Java 文件 | 类 | 方法 | |---------|----------:|--------:|--------:| | jsoup | 97 | 206 | 1,250 | | SLF4J | 155 | 151 | 912 | | JUnit 4 | 219 | 246 | 1,179 | | Mockito | 521 | 587 | 2,138 | | GanttProject | 570 | 837 | 4,727 | | JEdit | 615 | 1,143 | 5,883 | | Logback | 661 | 660 | 2,735 | | JHotDraw | 685 | 773 | 5,897 | | Apache Ant | 993 | 1,365 | 10,184 | | Eclipse Collections | 997 | 1,360 | 16,502 | | Apache Xerces-J | 1,109 | 1,308 | 8,004 | | ArgoUML | 1,687 | 2,017 | 11,846 | | Guava | 1,995 | 4,139 | 21,018 | | Checkstyle | 2,273 | 2,839 | 7,215 | | JabRef | 2,707 | 3,573 | 20,262 | 仅包含生产源代码；排除测试路径。计数来自静态扫描的规模指标。Next.js web dashboard · port 3001"] BE["Backend layer
Java Spring Boot API · port 8084
workspaces · PMD analysis · apply · compile"] EXE["Execution layer
Python FastAPI + LangGraph · port 8092
plan · refactor · verify · report"] STORE[("Workspace store
~/.refactai/workspaces")] LLM["LLM providers
OpenRouter / OpenAI / Google / Anthropic"] FE -->|"REST /api/*"| BE FE -->|"REST /agents/*"| EXE EXE <-->|"read files · smells · apply patches"| BE BE --> STORE EXE -->|"chat completions"| LLM ``` | 层级 | 技术 | 端口 | 职责 | |-------|------------|------|----------------| | **表现层** | Next.js (`web/app/`) | 3001 | 操作员 UI —— 上传项目、浏览分析结果、触发重构、审查证据 | | **后端层** | Java / Spring Boot (`backend/`) | 8084 | 工作区、PMD 坏味道检测、指标、应用补丁、编译检查 | | **执行层** | Python / FastAPI + LangGraph (`agents/`) | 8092 | 多智能体工作流 —— 规划、LLM 重构、验证门禁、报告 | | **外部层** | OpenRouter 或直接的 LLM API | — | 用于规划、重构和可选 LLM 验证的模型推理 | ### 重构执行流程 当用户从仪表盘重构一个文件时的端到端路径： ``` sequenceDiagram participant Web as Web UI participant BE as Java API participant AG as Agent service participant LLM as LLM provider Note over Web,BE: 1. Ingest and analyze Web->>BE: Upload workspace / PMD scan BE-->>Web: Smells and file metrics Note over Web,LLM: 2. Refactor one file Web->>AG: Refactor request AG->>BE: Load source and smell context BE-->>AG: File content Note over AG,LLM: 3. Generate candidate AG->>AG: Plan and feasibility checks AG->>LLM: Refactoring prompt LLM-->>AG: Candidate patch Note over AG,BE: 4. Verify and apply AG->>AG: Static and optional LLM verify AG->>BE: Apply patch BE-->>AG: Compile result Note over AG,Web: 5. Report AG-->>Web: Before/after metrics and evidence ``` **批处理模式**对多个文件重复步骤 2–5（并且可以在相同的基线上并行运行多个 LLM 提供商）。 ### Agent 流水线 在执行层内部，每次重构过程都遵循一个**垂直的 LangGraph 工作流**（11 个节点），分为以下五个阶段。蓝色节点调用 LLM；灰色节点基于规则或由后端支持。 ``` flowchart TB subgraph CTX["Context"] L["1. Load file"] A["2. Analyze smells"] L --> A end subgraph PLN["Planning"] P["3. Plan refactorings"] LP["4. LLM plan (optional)"] P --> LP end subgraph GEN["Generation"] F["5. Feasibility check"] R["6. Refactor — LLM"] F --> R end subgraph QLT["Quality"] V["7. Verify gates"] LV["8. LLM verify (optional)"] V --> LV end subgraph INT["Integration"] AP["9. Apply patch"] C["10. Compile check"] RP["11. Report"] AP --> C --> RP end A --> P LP --> F R --> V LV --> AP classDef llm fill:#2563eb,stroke:#1d4ed8,color:#ffffff class LP,R,LV llm ``` **流水线阶段** | 阶段 | 步骤 | 具体内容 | |-------|-------|----------------| | 上下文 | 1–2 | 加载 Java 源代码；附加 PMD 坏味道和指标上下文 | | 规划 | 3–4 | 基于规则的规划；可选的 LLM 规划细化 | | 生成 | 5–6 | 大小/安全门禁；LLM 生成候选补丁 | | 质量 | 7–8 | 静态验证门禁；可选的 LLM 审查 | | 集成 | 9–11 | 写入工作区（如果启用）；编译检查；保存报告 | 实现细节：[`agents/AGENT_ARCHITECTURE.md`](agents/AGENT_ARCHITECTURE.md) ``` curl -s http://127.0.0.1:8092/agents/health | jq . ``` ## 配置 | 文件 | 用途 | |------|---------| | `agents/.env` | API 密钥、模型、多智能体 LLM 模式 | | `config/ports.env` | 端口和 UI 功能标志 | ``` cp config/ports.env.example config/ports.env cp agents/.env.example agents/.env ``` **多智能体 LLM 模式**（`agents/.env` 中的 `MULTI_LLM_AGENT_MODE`）： | 值 | 行为 | |-------|----------| | `off` (默认) | 仅重构步骤使用 LLM | | `full` | 规划器、重构器和验证器各自调用 LLM | 有关多提供商路由，请参见 `config/multi-agent.env.example`。 ## 仓库布局 | 路径 | 角色 | |------|------| | `agents/` | Agent 编排服务 | | `backend/` | Java API 和分析引擎 | | `web/app/` | Web 仪表盘 | | `rulesets/` | PMD 规则定义 | | `examples/` | 演示 Java 项目和 OSS 测试指南 | | `config/` | 端口和功能标志模板 | `scripts/` | 安装、启动、验证、冒烟测试脚本 | ## 开发 ``` cd agents && pip install -r requirements.txt pytest python -m pytest -q --ignore=test_openrouter.py cd backend/server && mvn test ``` 请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 故障排除 | 问题 | 尝试方法 | |-------|-------------| | 后端无法启动 | 执行 `./scripts/setup.sh`；释放 8084 端口 | | Agent 状态异常 | 执行 `pip install -r agents/requirements.txt` | | LLM 错误 | 在 `agents/.env` 中设置 `OPENROUTER_API_KEY` | | 上传失败 | 使用项目根目录的 ZIP；避免嵌套归档 | | 大型仓库响应缓慢 | 从 `examples/sample-java-repo` 或 SLF4J/jsoup 开始尝试 | 日志（已在 gitignore 中忽略）：`backend/server.log`、`agents/agents.log`、`frontend.log` 安全：[SECURITY.md](SECURITY.md) ## 许可证 MIT — 详见 [LICENSE](LICENSE)。版权所有 匿名作者（为双盲评审而匿名化）。
标签：DLL 劫持, JS文件枚举, MITM代理, 云安全监控, 代码异味, 代码重构, 多智能体, 大语言模型, 自动化攻击, 逆向工具, 静态分析