# codepilot

**Repository Path**: ai-workstation_1/codepilot

## Basic Information

- **Project Name**: codepilot
- **Description**: CodePilot - Java 智能编程助手 AI Agent
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!-- markdownlint-disable MD033 MD041 -->

<h1 align="center">CodePilot</h1>

<p align="center">
  <b>Java 智能编程助手 AI Agent</b><br/>
  基于 Spring Boot 3 + Spring AI 构建，支持多模型切换、工具调用、长上下文优化的 AI 编程助手
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Java-17+-orange?logo=openjdk" alt="Java Version">
  <img src="https://img.shields.io/badge/Spring%20Boot-3.2.3-green?logo=springboot" alt="Spring Boot">
  <img src="https://img.shields.io/badge/Spring%20AI-1.0.0--M6-blue?logo=spring" alt="Spring AI">
  <img src="https://img.shields.io/badge/License-Apache%202.0-yellow" alt="License">
</p>

<p align="center">
  <a href="#-核心功能">核心功能</a> •
  <a href="#-支持的-ai-模型">模型支持</a> •
  <a href="#-快速开始">快速开始</a> •
  <a href="#-项目结构">项目结构</a> •
  <a href="#-开发指南">开发指南</a> •
  <a href="DEPLOYMENT.md">部署文档</a>
</p>

---

## ✨ 核心功能

### 🤖 智能对话
- 多轮对话支持，精准理解编程上下文
- 流式响应，实时输出代码与解释
- 会话记忆管理，支持长上下文自动压缩优化

### 🔀 多模型支持
- 内置 **OpenAI / DeepSeek / Claude / Kimi** 等多模型适配
- 请求级别动态切换模型，支持在同一会话中使用不同模型
- `@AIProviderType` 注解 + 自动发现机制，**新增模型仅需 30 行代码**
- 兼容所有 OpenAI 协议的第三方服务（Azure、Ollama、通义千问、智谱等）

### 📝 代码生成
- 根据自然语言描述生成 Java 代码
- 支持 Controller、Service、Entity、DTO 等多种类型
- 自动生成单元测试

### 🔍 代码审查
- Bug 检测与安全漏洞扫描
- 性能问题分析
- 代码风格与最佳实践检查

### 🛠️ 工具调用（Tool Use）
| 工具 | 功能 |
|:-----|:-----|
| `read_file` | 读取项目文件内容 |
| `write_file` | 创建或修改文件 |
| `search_code` | 在项目中搜索代码 |
| `run_maven` | 执行 Maven 构建命令 |
| `analyze_class` | 分析 Java 类结构（方法、字段、继承关系） |
| `execute_command` | 执行白名单内的系统命令 |

### 🧠 长上下文优化
专为编程场景设计的三阶段上下文管理：
- **Token 预算制**：根据不同模型的上下文窗口自动分配预算
- **智能截断**：工具输出保留头尾关键部分、代码块保留前 150 行 + 后 50 行
- **摘要注入**：被压缩的历史消息提取关键决策注入 system prompt，避免丢失上下文

---

## 🤖 支持的 AI 模型

| 提供商 | 模型示例 | 上下文窗口 | 接入方式 | 配置条件 |
|:------|:--------|:----------|:---------|:---------|
| **OpenAI** | gpt-4o, gpt-4-turbo, gpt-3.5-turbo | 128K / 16K | Spring AI 原生集成 | `OPENAI_API_KEY` |
| **DeepSeek** | deepseek-chat, deepseek-coder | 64K | WebClient HTTP 调用 | `DEEPSEEK_API_KEY` |
| **Claude** | claude-3-5-sonnet, claude-3-opus | 200K | OpenAI 兼容协议代理 | `CLAUDE_API_KEY` |
| **Kimi** | moonshot-v1-8k/32k/128k | 8K~128K | OpenAI 兼容协议 | `KIMI_API_KEY` |
| **通义千问** | qwen-plus, qwen-max | 128K | OpenAI 兼容协议 | 需自行扩展 |
| **智谱 GLM** | glm-4, glm-4-flash | 128K | OpenAI 兼容协议 | 需自行扩展 |

> 💡 所有标记"需自行扩展"的模型，只需继承 `AbstractOpenAICompatibleService` 并添加约 30 行代码即可完成接入。详见 [开发指南 - 添加新模型](#添加新-ai-模型)。

---

## 🚀 快速开始

### 环境要求

- JDK 17+
- Maven 3.9+
- Redis 7.0+
- MySQL 8.0+（可选）

### 本地运行

```bash
# 1. 克隆项目
git clone <repository-url> codepilot
cd codepilot

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，至少填入 OPENAI_API_KEY

# 3. 编译项目
mvn clean package -DskipTests

# 4. 启动服务
java -jar codepilot-trigger/target/codepilot-trigger-1.0.0-SNAPSHOT.jar

# 5. 访问 API 文档
# http://localhost:8080/doc.html
```

### Docker 一键部署

```bash
cp .env.example .env
# 编辑 .env，填入 API Key

docker compose up -d
docker compose logs -f codepilot
```

> 📖 详细部署说明（包括生产环境配置、JVM 调优、高可用架构等），请查阅 **[DEPLOYMENT.md](DEPLOYMENT.md)**

---

## 📁 项目结构

```text
codepilot/
│
├── codepilot-types/                     # 基础类型层
│   ├── enums/
│   │   ├── AIProvider.java              #   AI 提供商枚举（OpenAI/DeepSeek/Claude/Kimi/...）
│   │   ├── ResponseCode.java            #   响应码
│   │   ├── MessageRole.java             #   消息角色
│   │   └── ToolStatus.java              #   工具状态
│   ├── exception/                       #   业务异常（CodePilotException, AIServiceException）
│   ├── model/                           #   通用模型（ToolCall, ToolResult）
│   └── common/                          #   常量、通用 Result 封装
│
├── codepilot-domain/                    # 领域层（核心）
│   ├── agent/
│   │   ├── model/                       #   Agent 会话、消息、请求、响应模型
│   │   ├── service/                     #   IAgentService, IAIModelService 接口
│   │   └── repository/                  #   ISessionRepository 接口
│   ├── context/
│   │   ├── ContextWindowManager.java    #   ⭐ 上下文窗口管理器（长上下文优化核心）
│   │   └── TokenEstimator.java          #   Token 估算工具
│   ├── memory/
│   │   └── IMemoryManager.java          #   记忆管理器接口
│   ├── tool/
│   │   ├── Tool.java                    #   工具接口
│   │   ├── ToolRegistry.java            #   工具注册中心
│   │   ├── executor/ToolExecutor.java   #   工具执行器
│   │   └── impl/                        #   6 个内置工具实现
│   └── knowledge/                       #   知识库接口（RAG 扩展预留）
│
├── codepilot-infrastructure/            # 基础设施层
│   ├── ai/
│   │   ├── AIModelServiceRouter.java    #   ⭐ 多模型路由工厂（自动发现 + 动态路由）
│   │   ├── @AIProviderType              #   提供商类型注解
│   │   ├── AbstractOpenAICompatible...  #   ⭐ 通用 OpenAI 兼容适配器（扩展基类）
│   │   ├── OpenAIModelService.java      #   OpenAI 实现（Spring AI 原生）
│   │   ├── DeepSeekModelService.java    #   DeepSeek 实现（WebClient）
│   │   ├── ClaudeModelService.java      #   Claude 实现（继承通用适配器）
│   │   ├── KimiModelService.java        #   Kimi 实现（继承通用适配器）
│   │   └── openai/OpenAIService.java    #   OpenAI 高级服务（含 Agent 循环）
│   └── persistence/redis/
│       ├── RedisSessionRepository.java  #   会话持久化
│       └── RedisMemoryManager.java      #   对话记忆管理
│
├── codepilot-app/                       # 应用服务层
│   └── service/
│       ├── AgentService.java            #   ⭐ Agent 核心编排（含上下文优化集成）
│       ├── AgentAppService.java         #   应用层门面
│       ├── CodeGenerationService.java   #   代码生成服务
│       └── CodeReviewService.java       #   代码审查服务
│
├── codepilot-api/                       # API 定义层
│   └── dto/                             #   请求/响应 DTO
│
├── codepilot-trigger/                   # 触发器层（HTTP 入口）
│   ├── CodePilotApplication.java        #   🚀 启动类
│   ├── http/                            #   ChatController, ToolController, CodeController
│   ├── config/                          #   GlobalExceptionHandler, SwaggerConfig
│   └── resources/
│       ├── application.yml              #   主配置文件
│       └── application-prod.yml         #   生产环境配置
│
├── docker/                              #   Docker 中间件配置
├── Dockerfile                           #   应用镜像构建
├── docker-compose.yml                   #   完整部署编排
├── DEPLOYMENT.md                        #   📖 部署指导文档
└── pom.xml                              #   Maven 父 POM
```

---

## 🔧 配置说明

### 环境变量一览

| 变量 | 说明 | 默认值 | 必需 |
|:-----|:-----|:------|:-----|
| `OPENAI_API_KEY` | OpenAI API Key | - | ✅ 至少配一个 |
| `OPENAI_BASE_URL` | OpenAI API 地址 | `https://api.openai.com` | ❌ |
| `DEEPSEEK_API_KEY` | DeepSeek API Key | - | ❌ |
| `CLAUDE_API_KEY` | Claude API Key（通过代理） | - | ❌ |
| `CLAUDE_BASE_URL` | Claude 代理地址 | `https://openrouter.ai/api/v1` | ❌ |
| `KIMI_API_KEY` | Kimi (Moonshot) API Key | - | ❌ |
| `REDIS_HOST` | Redis 地址 | `localhost` | ✅ |
| `REDIS_PORT` | Redis 端口 | `6379` | ❌ |
| `MYSQL_HOST` | MySQL 地址 | `localhost` | ❌ |
| `MYSQL_PORT` | MySQL 端口 | `3306` | ❌ |

### 模型配置

```yaml
# application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:sk-xxx}
      base-url: ${OPENAI_BASE_URL:https://api.openai.com}

deepseek:
  api:
    key: ${DEEPSEEK_API_KEY:}
    url: https://api.deepseek.com/v1

claude:
  api:
    key: ${CLAUDE_API_KEY:}
    url: ${CLAUDE_BASE_URL:https://openrouter.ai/api/v1}

kimi:
  api:
    key: ${KIMI_API_KEY:}
    url: https://api.moonshot.cn/v1
```

---

## 📡 API 接口

### 聊天接口

**创建会话**
```http
POST /api/v1/chat/session
```

**流式聊天**
```http
POST /api/v1/chat/completions
Content-Type: application/json

{
  "sessionId": "xxx",
  "message": "帮我生成一个用户注册的 Service 类",
  "model": "gpt-4o",
  "stream": true
}
```

> `model` 字段支持传入提供商标识（`openai` / `deepseek` / `claude` / `kimi`）或具体模型名（`gpt-4o` / `deepseek-chat` / `claude-3-5-sonnet`），系统自动路由到对应服务。

**同步聊天**
```http
POST /api/v1/chat/completions/sync
Content-Type: application/json

{
  "message": "分析这段代码有什么问题",
  "model": "deepseek",
  "projectPath": "/path/to/project"
}
```

### 代码接口

**生成代码**
```http
POST /api/v1/code/generate
Content-Type: application/json

{
  "type": "service",
  "packageName": "com.example.user",
  "className": "UserService",
  "description": "用户注册服务，包含邮箱验证"
}
```

**代码审查**
```http
POST /api/v1/code/review
Content-Type: application/json

{
  "code": "public class UserService { ... }",
  "reviewTypes": ["bug", "security", "performance"]
}
```

### 工具接口

```http
GET  /api/v1/tools                          # 获取工具列表
POST /api/v1/tools/{toolName}/execute       # 执行指定工具
```

---

## 📖 开发指南

### 添加新工具

在 `codepilot-domain/tool/impl/` 下创建工具类，实现 `Tool` 接口并添加 `@Component` 注解：

```java
@Slf4j
@Component
public class MyNewTool implements Tool {

    @Override
    public String getName() { return "my_tool"; }

    @Override
    public String getDescription() { return "工具描述"; }

    @Override
    public String getParametersSchema() {
        return """
            {
                "type": "object",
                "properties": {
                    "param1": {"type": "string", "description": "参数说明"}
                },
                "required": ["param1"]
            }
            """;
    }

    @Override
    public ToolResult execute(Map<String, Object> parameters) {
        String param1 = (String) parameters.get("param1");
        // 实现工具逻辑
        return ToolResult.success("tool_call_id", "my_tool", "执行结果");
    }
}
```

### 添加新 AI 模型

只需 **3 步**，无需修改任何已有代码：

**① 在 `AIProvider` 枚举中添加新值**（如果还没有）：

```java
// codepilot-types/.../AIProvider.java
QWEN("qwen", "Alibaba Qwen", "qwen-plus"),
```

**② 创建实现类**（继承通用适配器，约 30 行）：

```java
@Slf4j
@Service
@AIProviderType(AIProvider.QWEN)                           // 标注提供商类型
@ConditionalOnProperty(prefix = "qwen.api", name = "key")  // 仅在配了 key 时启用
public class QwenModelService extends AbstractOpenAICompatibleService {

    @Value("${qwen.api.key:}")    private String apiKey;
    @Value("${qwen.api.url:https://dashscope.aliyuncs.com/compatible-mode/v1}")
    private String apiUrl;
    @Value("${qwen.model:qwen-plus}") private String model;

    @Override protected String getApiKey()       { return apiKey; }
    @Override protected String getApiUrl()       { return apiUrl; }
    @Override protected String getModel()        { return model; }
    @Override protected String getProviderName() { return "Qwen"; }
}
```

**③ 在 `application.yml` 中添加配置**：

```yaml
qwen:
  api:
    key: ${QWEN_API_KEY:}
    url: https://dashscope.aliyuncs.com/compatible-mode/v1
  model: qwen-plus
```

完成后，用户即可通过 `"model": "qwen"` 或 `"model": "qwen-plus"` 使用新模型。

### 模型扩展架构图

```text
                        ┌──────────────────┐
                        │  ChatRequest      │
                        │  model: "kimi"   │
                        └────────┬─────────┘
                                 │
                  ┌──────────────▼──────────────┐
                  │   AIModelServiceRouter       │
                  │   自动发现 @AIProviderType   │
                  └──────────────┬──────────────┘
                                 │
      ┌──────────┬───────────┬───┴────┬──────────┬──────────┐
      ▼          ▼           ▼        ▼          ▼          ▼
 ┌─────────┐┌─────────┐┌────────┐┌───────┐┌────────┐┌────────┐
 │ OpenAI  ││DeepSeek ││ Claude ││ Kimi  ││  Qwen  ││ Zhipu  │
 │ @Primary││@Service ││@Cond.. ││@Cond..││  自行   ││  自行  │
 └─────────┘└─────────┘└────────┘└───────┘│  扩展   ││  扩展  │
                                          └────────┘└────────┘
```

---

## 📄 技术栈

| 分类 | 技术 | 版本 |
|:-----|:-----|:-----|
| 语言 | Java | 17 |
| 框架 | Spring Boot | 3.2.3 |
| AI 集成 | Spring AI | 1.0.0-M6 |
| ORM | MyBatis Plus | 3.5.5 |
| 缓存 | Redis (Lettuce) | 7.x |
| 数据库 | MySQL | 8.0 |
| 连接池 | Druid | 1.2.21 |
| API 文档 | Knife4j (OpenAPI 3) | 4.4.0 |
| JSON | FastJSON2 | 2.0.47 |
| 工具库 | Hutool, Guava | 5.8.25, 33.0.0 |
| 代码简化 | Lombok, MapStruct | 1.18.30, 1.5.5 |
| 容器化 | Docker + Compose | - |

---

## 📄 许可证

本项目采用 Apache 2.0 许可证，详见 [LICENSE](LICENSE) 文件。

## 👤 联系方式

- 作者：邓康斌
- 邮箱：1349926002@qq.com

---

<p align="center"><b>CodePilot</b> — 让编程更智能 🚀</p>