# java-programming-agent

**Repository Path**: javpower/java-programming-agent

## Basic Information

- **Project Name**: java-programming-agent
- **Description**: 像Claude Code一样的Java 智能编程助手 - 一个基于 Spring Boot 的 L4/L5 级别自主编程 Agent，具备完整的项目导航、文件操作、代码修改和上下文记忆能力。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-11-14
- **Last Updated**: 2025-11-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 Java Programming Agent

**像Claude Code一样的Java 智能编程助手** - 一个基于 Spring Boot 的 L4/L5 级别自主编程 Agent，具备完整的项目导航、文件操作、代码修改和上下文记忆能力。

![img.png](img/img_1.png)
## 免责声明

**这是一个实验性的自主编程 Agent，请谨慎使用：**

- **安全**: 建议在隔离的测试环境中使用
- **监督**: 重要操作建议有人工监督
- **备份**: 使用前请备份重要代码
- **权限**: 使用最小权限的访问令牌
- **审计**: 定期审查操作日志

**使用本工具所产生的任何后果由用户自行承担。**

---

<div align="center">

**如果这个项目对您有帮助，请给我们一个 Star！**

Made with ❤️ by the Java Programming Agent Team

</div>

##  核心特性

### 感知模块 (Perception Layer)
- **多源告警接收**: 支持 Sentry、GitHub Webhook、自定义告警
- **智能事件转换**: 将外部告警标准化为可处理的任务格式
- **优先级自动评估**: AI 驱动的重要性和紧急程度判断
- **上下文感知**: 自动收集代码上下文和运行环境信息

### 决策模块 (Decision Layer)
- **多 AI 提供商支持**: OpenAI、Azure OpenAI、Ollama、Anthropic Claude
- **智能代码分析**: 深度根因分析、Bug 定位、影响范围评估
- **多维度分析**: 代码质量、安全性、性能、可维护性全面评估
- **修复方案生成**: 自动生成具体的代码修复和优化方案

### 行动模块 (Action Layer)
- **安全 Git 操作**: 自动克隆、分支创建、代码提交和推送
- **精确代码修改**: 基于 JavaParser 的 AST 级别代码操作
- **沙箱环境隔离**: Docker 容器化的安全执行环境
- **自动测试验证**: 单元测试、集成测试自动运行和验证

### 自我纠错循环 (Self-Healing Loop)
- **L5 级别自主决策**: 完整的"感知-决策-行动-反馈"闭环
- **智能失败分析**: AI 分析失败原因，生成改进策略
- **多轮尝试机制**: 最多 3 次不同策略的修复尝试
- **持续学习优化**: 从失败中学习，优化后续决策质量

### Claude Code 级别功能
- **工作目录管理**: `cd`, `pwd`, `context` - 在任意项目中导航
- **智能文件操作**: `mkdir`, `rm`, `cp`, `mv`, `ls`, `cat`, `write` - 完整文件系统控制
- **自然语言交互**: 直接描述需求，AI 理解并执行相应操作
- **上下文记忆**: 文件内容缓存，对话历史，项目状态保持
- **项目级代码修改**: 读取、分析、修改任意项目代码
- **系统命令集成**: `git clone`, `npm install`, `mvn compile` 等
- **网络能力**: `download`, `fetch`, `search` - 获取外部资源

### 双重交互界面
- **CLI 交互模式**: 完全类似 Claude Code 的命令行交互体验
- **Web 可视化界面**: 现代化的 Web 管理和监控界面

## 技术架构

### 核心技术栈
```
Java 17 + Spring Boot 3.2.0
├── AI 集成: LangChain4j 0.33.0
├── 代码分析: JavaParser 3.25.10
├── Git 操作: Eclipse JGit 6.9.0
├── 容器化: Testcontainers 1.19.3
├── 规则引擎: Drools 8.44.0.Final
├── CLI 框架: JLine 3.24.1
└── 日志处理: Logback + Logstash
```

### 架构模式
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Perception    │    │    Decision     │    │     Action      │
│  感知层         │    │   决策层        │    │   执行层         │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│• Webhook接收器  │    │• AI分析引擎     │    │• Git操作服务    │
│• 事件处理器     │───▶│• 决策规则引擎   │───▶│• 代码修改器     │
│• 告警转换器     │    │• 策略生成器     │    │• 沙箱执行器     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
           │                       │                       │
           └───────────────────────┼───────────────────────┘
                                   ▼
                    ┌─────────────────────────┐
                    │    Self-Healing Loop    │
                    │     自我纠错循环        │
                    └─────────────────────────┘
```

## 快速开始

### 环境要求
- **Java 17+** (推荐使用 OpenJDK 或 Oracle JDK)
- **Maven 3.6+**
- **Docker** (用于沙箱环境)
- **Git**

### 安装步骤

1. **克隆项目**
```bash
git clone https://gitee.com/javpower/java-programming-agent.git
cd java-programming-agent
```

2. **配置应用**

编辑 `src/main/resources/application.yml` 文件，根据需要配置 AI 服务和其他参数：

```yaml
agent:
  ai:
    provider: openai                    # 选择 AI 提供商
    model: gpt-4-turbo                  # 模型名称
    base-url: https://api.openai.com    # API 地址
    api-key: your_openai_api_key_here   # 直接配置 API 密钥
    temperature: 0.7
    max-tokens: 2000

  git:
    access-token: your_git_token_here   # Git 访问令牌

  # 其他配置...
```

3. **构建项目**
```bash
mvn clean package -DskipTests
```

4. **启动应用**

**CLI 交互模式:**
```bash
java -jar target/java-programming-agent-1.0.0.jar
```

**Web 界面模式:**
```bash
java -jar target/java-programming-agent-1.0.0.jar --agent.interactive=false
```
然后访问 `http://localhost:8080`

## 配置说明

### 应用配置 (application.yml)

在 `src/main/resources/application.yml` 中配置所有参数：

```yaml
agent:
  # AI 服务配置
  ai:
    provider: openai                    # 提供商: openai, azure, ollama, anthropic
    model: gpt-4-turbo                  # 模型名称
    base-url: https://api.openai.com    # API 基础 URL (支持自定义)
    api-key: your_api_key_here          # 直接配置 API 密钥
    temperature: 0.7                    # 创造性参数 (0-1)
    max-tokens: 2000                    # 最大令牌数
    max-retries: 3                      # 最大重试次数

  # 沙箱环境配置
  sandbox:
    enabled: true                       # 是否启用沙箱
    maven-image: maven:3.9-openjdk-17   # Maven Docker 镜像
    timeout-seconds: 300                # 超时时间
    workspace-path: /tmp/agent-workspace # 工作目录

  # 安全配置
  security:
    max-attempts: 3                     # 最大尝试次数
    allowed-operations:                 # 允许的操作类型
      - BUG_FIX
      - CODE_OPTIMIZATION
      - TEST_GENERATION
    forbidden-patterns:                 # 禁止的代码模式
      - System.exit
      - Runtime.exec

  # Git 配置
  git:
    access-token: your_git_token_here   # Git 访问令牌
    base-branch: main                   # 基础分支
    commit-prefix: "[Agent]"            # 提交前缀
    create-pr: true                     # 是否创建 Pull Request

# Spring Boot 配置
spring:
  application:
    name: java-programming-agent
  server:
    port: 8080

# 日志配置
logging:
  level:
    com.javaagent.agent: INFO
    dev.langchain4j: WARN
  file:
    name: logs/agent.log
```

### AI 提供商配置示例

**OpenAI:**
```yaml
agent:
  ai:
    provider: openai
    model: gpt-4-turbo
    base-url: https://api.openai.com
    api-key: sk-your-openai-api-key-here
```

**Azure OpenAI:**
```yaml
agent:
  ai:
    provider: azure
    model: gpt-4
    base-url: https://your-resource.openai.azure.com/
    api-key: your-azure-openai-key-here
    deployment-name: your-deployment-name
```

**Ollama (本地模型):**
```yaml
agent:
  ai:
    provider: ollama
    model: llama2
    base-url: http://localhost:11434
    # 本地 Ollama 通常不需要 API 密钥
```

**Anthropic Claude:**
```yaml
agent:
  ai:
    provider: anthropic
    model: claude-3-sonnet-20240229
    base-url: https://api.anthropic.com
    api-key: sk-ant-your-anthropic-key-here
```

**自定义 AI 服务:**
```yaml
agent:
  ai:
    provider: openai                    # 使用 OpenAI 兼容格式
    model: your-custom-model
    base-url: https://your-custom-api.com/v1/
    api-key: your-custom-api-key
```

## API 接口

### Webhook 接口

**接收 Sentry 告警:**
```http
POST /webhooks/sentry-alert
Content-Type: application/json

{
  "id": "alert-id-123",
  "message": "NullPointerException in UserService.getUserById",
  "level": "error",
  "exception": {
    "values": [{
      "type": "NullPointerException",
      "stacktrace": {
        "frames": [{
          "filename": "UserService.java",
          "lineNumber": 42,
          "function": "getUserById"
        }]
      }
    }]
  },
  "project": {
    "name": "user-service"
  }
}
```

**接收 GitHub 事件:**
```http
POST /webhooks/github
X-GitHub-Event: push
Content-Type: application/json

{
  "ref": "refs/heads/main",
  "repository": {
    "name": "my-project",
    "clone_url": "https://github.com/user/my-project.git"
  }
}
```

**自定义告警:**
```http
POST /webhooks/custom-alert
Content-Type: application/json

{
  "source": "monitoring-system",
  "type": "performance_issue",
  "message": "High memory usage detected",
  "severity": "high",
  "context": {
    "service": "order-service",
    "metric": "memory_usage",
    "value": "85%"
  }
}
```

### REST API

**代码分析:**
```http
POST /api/analyze
Content-Type: application/x-www-form-urlencoded

code=public void getUser(String id) { return userMap.get(id); }
```

**Bug 修复:**
```http
POST /api/fix
Content-Type: application/json

{
  "description": "NullPointerException in UserService.getUser",
  "stackTrace": "...",
  "repoUrl": "https://github.com/user/project.git"
}
```

**性能优化:**
```http
POST /api/optimize
Content-Type: application/x-www-form-urlencoded

code=for(String item : items) { result += item; }
```

**健康检查:**
```http
GET /webhooks/health
```

##  CLI 使用指南

### 启动 CLI 模式
```bash
java -jar target/java-programming-agent-1.0.0.jar
```

### 文件系统操作
```bash
# 创建目录
mkdir test-project
mkdir src/main/java/com/example

# 删除文件/目录
rm temp.txt
rm -rf old-project

# 复制文件/目录
cp src/main/java/UserService.java backup/
cp -r src/ dist/

# 移动/重命名
mv old-name.java new-name.java
mv src/ ../backup/

# 列出目录内容
ls
ls src/main/java/

# 读取文件内容（智能缓存）
cat README.md
cat src/main/java/UserService.java

# 写入文件
write config.properties "server.port=8080"
write logs/app.log "Application started"
```

### 工作目录管理
```bash
# 切换工作目录
cd /path/to/my-project
cd ../
cd ~/projects

# 查看当前工作目录
pwd

# 显示上下文信息
context

# 清除缓存和上下文
context clear
```

### 系统命令执行
```bash
# Git 操作
git status
git clone https://github.com/user/repo.git
git pull origin main
git add .
git commit -m "fix bug"

# NPM 操作
npm install
npm run build
npm test

# Maven 操作
mvn clean install
mvn compile
mvn test
```

### 网络操作
```bash
# 下载文件
download https://example.com/config.json config.json

# 获取网页内容
fetch https://api.github.com/repos/user/repo

# 网络搜索
search "Java 17 new features"
search "Spring Boot best practices"
```

### 代码分析和修复
```bash
# 分析代码
analyze "public void getUser(String id) { return userMap.get(id); }"

# 修复 Bug
fix "NullPointerException in UserService.getUser"

# 优化代码
optimize "for loop with string concatenation"

# 生成测试
test "public User saveUser(User user)"
```

###  自然语言交互
```bash
# 直接用自然语言描述需求
"帮我看看这段代码有没有问题"
"在当前目录创建一个test目录"
"拉取github项目代码: git clone https://github.com/user/repo.git"
"读取src/main/java/UserService.java文件内容"
"修复UserService中的空指针异常"
"为UserController添加一个新方法"
"优化这个for循环的性能"
"下载这个文件 https://example.com/config.txt"
```

### 系统命令
```bash
# 显示帮助
help 或 h

# 查看状态
status 或 s

# 查看配置
config 或 c

# 清屏
clear 或 cls

# 退出
quit、exit 或 q
```

### CLI 使用示例

#### 基础操作示例
```bash
[14:30] Agent> pwd
/Users/xiongguochao/projects/my-spring-app

[14:31] Agent> mkdir test
🔨 正在创建目录: /Users/xiongguochao/projects/my-spring-app/test
✅ Directory created successfully: /Users/xiongguochao/projects/my-spring-app/test

[14:32] Agent> ls
📁 正在列出目录内容: /Users/xiongguochao/projects/my-spring-app
✅ Listed directory contents
📄 pom.xml
📁 src/
📁 target/
📄 README.md
📁 test/
```

#### 项目导航示例
```bash
[14:33] Agent> cd ~/projects/backend-api
✓ 已切换到: /Users/xiongguochao/projects/backend-api

[14:34] Agent> context
📋 当前上下文:
  工作目录: /Users/xiongguochao/projects/backend-api
  缓存文件数: 3
  对话历史: 1247 字符
  已缓存的文件:
    📄 /Users/xiongguochao/projects/backend-api/src/main/java/UserService.java
    📄 /Users/xiongguochao/projects/backend-api/pom.xml
    📄 /Users/xiongguochao/projects/backend-api/README.md
```

#### 文件操作示例
```bash
[14:35] Agent> cat src/main/java/UserService.java
📖 正在读取文件: src/main/java/UserService.java
✅ 文件内容: src/main/java/UserService.java
--- 文件内容 (1247 字符) ---
package com.example.service;

import org.springframework.stereotype.Service;
import java.util.concurrent.ConcurrentHashMap;

@Service
public class UserService {
    private final ConcurrentHashMap<String, User> userCache = new ConcurrentHashMap<>();

    public User getUserById(String id) {
        return userCache.get(id);  // Potential NPE here
    }

    public void addUser(User user) {
        if (user != null && user.getId() != null) {
            userCache.put(user.getId(), user);
        }
    }
}
--- 文件结束 ---
```

#### 自然语言交互示例
```bash
[14:36] Agent> 修复UserService中的空指针异常
🤔 正在理解您的需求...
🔧 正在分析 UserService 的空指针问题...
📖 正在读取文件: src/main/java/UserService.java (从缓存)
✅ 已找到空指针问题并生成修复方案

🔧 建议的修复方案:
- 问题: getUserById 方法没有处理 id 为 null 的情况
- 位置: UserService.java:12
- 修复: 添加 null 检查和默认值处理

是否应用此修复？(y/n)
```

#### Git 操作示例
```bash
[14:37] Agent> git status
🔀 正在执行Git命令: git status
✅ 命令执行成功
--- 输出 ---
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   src/main/java/UserService.java
--- 输出结束 ---
⏱️ 执行时间: 234ms

[14:38] Agent> git add src/main/java/UserService.java
🔀 正在执行Git命令: git add src/main/java/UserService.java
✅ 命令执行成功
⏱️ 执行时间: 156ms
```

#### 网络操作示例
```bash
[14:39] Agent> download https://raw.githubusercontent.com/example/config.json config.json
⬇️ 正在下载文件: https://raw.githubusercontent.com/example/config.json
✅ File downloaded successfully
📍 保存位置: /Users/xiongguochao/projects/backend-api/config.json
📊 文件大小: 1.2 KB

[14:40] Agent> cat config.json
📖 正在读取文件: config.json
✅ 文件内容: config.json
--- 文件内容 (1234 字符) ---
{
  "database": {
    "url": "jdbc:mysql://localhost:3306/mydb",
    "username": "admin",
    "password": "${DB_PASSWORD}"
  },
  "server": {
    "port": 8080,
    "context-path": "/api"
  }
}
--- 文件结束 ---
```

#### 状态查看示例
```bash
[14:41] Agent> status
📊 Agent Status:
  ✓ Agent is running
  ✓ AI Service: openai
  ✓ Model: gpt-4-turbo
  ✓ Working Directory: /Users/xiongguochao/projects/backend-api
  ✓ Cached Files: 4
  ✓ Timestamp: 2024-01-15 14:41:25
```

##  Web 界面

访问 `http://localhost:8080` 可以使用现代化的 Web 管理界面：

### 功能特性
- **实时任务监控**: 查看当前执行的任务和历史记录
- **代码分析工具**: 在线分析代码质量和安全性
- **Bug 修复面板**: 提交和跟踪 Bug 修复任务
- **性能优化建议**: 获取代码优化建议和实现
- **配置管理**: 动态调整 AI 服务和安全配置
- **日志查看**: 实时查看各类操作日志

### API 端点
- `GET /` - 主页面
- `POST /api/analyze` - 代码分析
- `POST /api/fix` - Bug 修复
- `POST /api/optimize` - 性能优化
- `GET /api/status` - 系统状态
- `GET /api/config` - 当前配置

## 工作流程详解

### 完整的自主修复流程
```
1. 告警接收
   └── Webhook 接收外部告警 (Sentry, GitHub, 自定义)

2. 事件解析
   └── 转换为标准化任务格式
   └── 优先级和紧急程度评估

3. 上下文收集
   └── 克隆相关代码仓库
   └── 收集错误堆栈和相关代码
   └── 分析代码结构

4. AI 分析决策
   └── 根因分析
   └── 修复方案生成
   └── 风险评估

5. 代码修复执行
   └── 在沙箱环境中执行修复
   └── 运行测试验证

6. 结果反馈
   └── 成功: 提交代码并创建 PR
   └── 失败: 启动自我纠错循环

7. 自我纠错 (如需要)
   └── 分析失败原因
   └── 调整修复策略
   └→ 重新执行 (最多3次)
```

### 自我纠错机制
```
失败分析 → 策略调整 → 重新执行 → 验证结果
    │                                          │
    └─────────── 失败 ─────────────────────────┘
                (最多3次尝试)
```

## 安全特性

### 多层安全防护
1. **沙箱隔离**: 所有代码修改和测试都在 Docker 容器中执行
2. **权限控制**: 最小权限原则，仅允许必要的操作
3. **代码审查**: 禁止危险操作 (System.exit, Runtime.exec 等)
4. **审计日志**: 完整的操作记录和安全审计
5. **人工审核**: 重要操作需要人工确认后才能合并

### 安全配置选项
```yaml
agent:
  security:
    max-attempts: 3
    allowed-operations:
      - BUG_FIX
      - CODE_OPTIMIZATION
      - TEST_GENERATION
    forbidden-patterns:
      - "System\\.exit"
      - "Runtime\\.exec"
      - "ProcessBuilder"
    require-human-approval: true
```

## 监控和日志

### 日志文件结构
```
logs/
├── agent.log              # 主应用日志
├── ai-operations.log      # AI 操作详细记录
├── security-audit.log     # 安全审计日志
├── git-operations.log     # Git 操作记录
├── sandbox-execution.log  # 沙箱执行日志
└── errors.log            # 错误和异常日志
```

### 监控端点
- `GET /actuator/health` - 应用健康状态
- `GET /actuator/info` - 应用信息
- `GET /actuator/metrics` - 性能指标
- `GET /actuator/prometheus` - Prometheus 指标

### 关键指标
- AI 调用成功率
- 任务完成时间
- 自我纠错成功率
- 代码修复成功率
- 安全检查通过率

##  测试

### 运行测试
```bash
# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=GitServiceTest

# 运行集成测试
mvn test -Dtest=*IntegrationTest
```

### 测试覆盖范围
- **单元测试**: 核心业务逻辑测试
- **集成测试**: 外部服务集成测试
- **安全测试**: 安全功能验证
- **性能测试**: AI 调用和任务执行性能

##  开发指南

### 项目结构
```
src/main/java/com/javaagent/agent/
├── cli/                    # CLI 交互界面
│   ├── AgentShell.java
│   └── AgentCompleter.java
├── config/                 # 配置管理
│   ├── AgentProperties.java
│   └── AiProviderFactory.java
├── controller/             # Web 控制器
│   ├── WebhookReceiver.java
│   └── WebUIController.java
├── decision/               # AI 决策模块
│   ├── AIDecisionService.java
│   └── CodeAnalysisService.java
├── action/                 # 行动执行模块
│   ├── GitService.java
│   ├── SandboxCommandExecutor.java
│   └── CodeModifier.java
├── service/                # 服务编排
│   ├── AgentOrchestrator.java
│   └── SelfHealingLoopService.java
├── perception/             # 感知模块
│   └── AlertProcessor.java
├── model/                  # 数据模型
│   ├── AgentTask.java
│   └── SentryAlertPayload.java
└── exception/              # 异常处理
    └── AgentExceptionHandler.java
```

### 扩展新功能

1. **添加新的 AI 提供商**
   ```java
   // 在 AiProviderFactory 中添加
   case "newprovider":
       return createNewProviderModel(aiConfig);
   ```

2. **添加新的任务类型**
   ```java
   // 在 AgentTask.TaskType 中添加
   SECURITY_ANALYSIS("security_analysis"),
   ```

3. **扩展 AI 分析能力**
   ```java
   // 在 CodeAnalysisService 中添加新方法
   @SystemMessage("...")
   String analyzeSecurity(@UserMessage("...") String code);
   ```

### 代码贡献
1. Fork 项目仓库
2. 创建特性分支: `git checkout -b feature/amazing-feature`
3. 提交更改: `git commit -m 'Add amazing feature'`
4. 推送分支: `git push origin feature/amazing-feature`
5. 创建 Pull Request

## 故障排除

### 常见问题

**1. AI 服务连接失败**
```
问题: API Key 无效或网络连接问题
解决:
- 检查 application.yml 中的 api-key 配置
- 验证 API Key 有效性
- 确认 base-url 配置正确
- 查看网络连接和防火墙设置
```

**2. Git 操作失败**
```
问题: Git Token 权限不足或仓库 URL 错误
解决:
- 检查 Git Token 权限 (需要 repo 权限)
- 验证仓库 URL 正确性
- 查看 git-operations.log 获取详细错误
```

**3. Docker 容器启动失败**
```
问题: Docker 服务未运行或镜像不存在
解决:
- 确认 Docker 服务运行状态
- 检查 Docker 镜像是否存在
- 查看容器日志: docker logs <container_id>
```

**4. 内存不足**
```
问题: JVM 内存配置不足
解决:
- 增加 JVM 堆内存: -Xmx2g
- 调整 Docker 容器内存限制
- 优化 AI 模型调用频率
```

### 调试模式
```yaml
logging:
  level:
    com.javaagent.agent: DEBUG
    dev.langchain4j: DEBUG
    org.eclipse.jgit: DEBUG
  pattern:
    console: "%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"
```

##  许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 贡献

欢迎各种形式的贡献
---