# code_agent

**Repository Path**: hong0220/code_agent

## Basic Information

- **Project Name**: code_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI 代码助手 - 完整文档

## 📋 目录

- [项目概述](#项目概述)
- [核心功能](#核心功能)
- [技术架构](#技术架构)
- [快速开始](#快速开始)
- [API文档](#api文档)
- [Harness Engineering实践](#harness-engineering实践)
- [配置说明](#配置说明)
- [开发指南](#开发指南)

---

## 项目概述

Spring AI Code Assistant 是一个基于 **Spring AI Alibaba** 构建的智能代码助手，集成了记忆管理、上下文管理、提示词工程等核心功能，并实践了 **Harness Engineering** 思想来确保AI输出的质量和持续改进。

### 设计理念

1. **智能化**: 利用阿里云通义千问大模型提供智能代码辅助
2. **记忆化**: 持久化存储对话历史和用户偏好，实现个性化服务
3. **上下文感知**: 智能管理对话和代码上下文，提供更准确的回答
4. **提示词工程**: 精心设计的提示词模板，优化AI输出质量
5. **质量保证**: 通过Harness Engineering框架持续评估和改进

---

## 核心功能

### 1. 智能对话 (Chat)
- 通用编程问题解答
- 多轮对话支持
- 上下文感知

### 2. 代码生成 (Code Generation)
- 根据需求自动生成代码
- 支持多种编程语言
- 遵循最佳实践

### 3. 代码解释 (Code Explanation)
- 详细解释代码逻辑
- 分析关键算法
- 提供改进建议

### 4. 代码审查 (Code Review)
- 识别潜在bug
- 安全性检查
- 性能优化建议
- 代码规范检查

### 5. 调试辅助 (Debugging)
- 问题分析
- 根本原因定位
- 修复方案建议

### 6. 代码重构 (Refactoring)
- 提高代码质量
- 优化可读性
- 性能改进

### 7. 文档生成 (Documentation)
- API文档
- 代码注释
- 使用说明

---

## 技术架构

### 系统架构图

```
┌─────────────────────────────────────────────┐
│           REST API Layer                     │
│      (AssistantController)                   │
└──────────────┬──────────────────────────────┘
               │
┌──────────────▼──────────────────────────────┐
│          Service Layer                       │
│  ┌────────────┐  ┌──────────────────────┐  │
│  │ ChatService│  │ EvaluationService    │  │
│  └────────────┘  └──────────────────────┘  │
└──────┬───────────────────┬─────────────────┘
       │                   │
┌──────▼──────┐   ┌────────▼────────┐
│ Memory Mgmt │   │ Context Mgmt    │
│ & Prompt    │   │ Service         │
│ Service     │   │                 │
└─────────────┘   └─────────────────┘
       │                   │
┌──────▼───────────────────▼─────────────────┐
│      Spring AI Alibaba (DashScope)         │
│         通义千问大模型                      │
└────────────────────────────────────────────┘
       │
┌──────▼──────────────────────────────────────┐
│      Database (H2 / MySQL)                  │
│   - Memories                                │
│   - Evaluations                             │
└─────────────────────────────────────────────┘
```

### 核心组件

#### 1. 记忆管理系统 (Memory System)
- **位置**: `com.codeassistant.memory`
- **功能**: 
  - 存储对话历史
  - 管理用户偏好
  - 保存代码上下文
  - 学习记忆积累

#### 2. 上下文管理 (Context Management)
- **位置**: `com.codeassistant.context`
- **功能**:
  - 会话状态维护
  - 对话历史追踪
  - 代码上下文关联
  - 元数据管理

#### 3. 提示词服务 (Prompt Service)
- **位置**: `com.codeassistant.prompt`
- **功能**:
  - 提示词模板管理
  - 动态变量替换
  - 多场景模板支持
  - 模板注册与扩展

#### 4. AI聊天服务 (Chat Service)
- **位置**: `com.codeassistant.ai.service`
- **功能**:
  - 集成通义千问模型
  - 智能提示词构建
  - 响应处理
  - 记忆整合

#### 5. Harness Engineering框架
- **位置**: `com.codeassistant.harness`
- **功能**:
  - 自动化测试用例
  - 多维度评估
  - 用户反馈收集
  - 质量指标统计

---

## 快速开始

### 前置要求

- Java 17+
- Maven 3.6+
- 阿里云通义千问API密钥

### 安装步骤

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

#### 2. 配置API密钥

编辑 `src/main/resources/application.yml`:
```yaml
spring:
  ai:
    dashscope:
      api-key: your-dashscope-api-key-here
```

或者设置环境变量:
```bash
export DASHSCOPE_API_KEY=your-api-key-here
```

#### 3. 编译项目
```bash
mvn clean package
```

#### 4. 运行应用
```bash
mvn spring-boot:run
```

应用将在 `http://localhost:8080` 启动

### 验证安装

访问健康检查接口:
```bash
curl http://localhost:8080/api/assistant/health
```

预期响应:
```json
{
  "status": "UP",
  "active_contexts": 0,
  "timestamp": 1234567890
}
```

---

## API文档

### 基础URL
```
http://localhost:8080/api/assistant
```

### 1. 通用聊天

**端点**: `POST /chat`

**请求体**:
```json
{
  "sessionId": "optional-session-id",
  "userId": "user123",
  "message": "如何创建一个Java单例模式？"
}
```

**响应**:
```json
{
  "response": "Java单例模式的实现方式...",
  "sessionId": "generated-or-provided-session-id",
  "timestamp": 1234567890
}
```

### 2. 代码生成

**端点**: `POST /generate-code`

**请求体**:
```json
{
  "sessionId": "session-123",
  "userId": "user123",
  "requirement": "创建一个计算斐波那契数列的函数",
  "language": "Java",
  "context": "需要一个高效的实现"
}
```

### 3. 代码解释

**端点**: `POST /explain-code`

**查询参数**:
- `sessionId`: 会话ID
- `userId`: 用户ID
- `code`: 要解释的代码
- `language`: 编程语言

**示例**:
```bash
curl -X POST "http://localhost:8080/api/assistant/explain-code?sessionId=s1&userId=u1&language=Java&code=public%20static%20void%20main"
```

### 4. 代码审查

**端点**: `POST /review-code`

**请求体**:
```json
{
  "sessionId": "session-123",
  "userId": "user123",
  "code": "public class Test { ... }",
  "language": "Java"
}
```

### 5. 调试辅助

**端点**: `POST /debug`

**查询参数**:
- `sessionId`: 会话ID
- `userId`: 用户ID
- `code`: 有问题的代码
- `language`: 编程语言
- `issue`: 问题描述
- `error`: 错误信息（可选）

### 6. 代码重构

**端点**: `POST /refactor`

**查询参数**:
- `sessionId`: 会话ID
- `userId`: 用户ID
- `code`: 需要重构的代码
- `language`: 编程语言
- `goal`: 重构目标（可选）

### 7. 文档生成

**端点**: `POST /generate-docs`

**查询参数**:
- `sessionId`: 会话ID
- `userId`: 用户ID
- `code`: 需要文档化的代码
- `language`: 编程语言
- `docType`: 文档类型（可选，默认"API文档"）

### 8. 提交反馈

**端点**: `POST /feedback`

**请求体**:
```json
{
  "sessionId": "session-123",
  "rating": 4.5,
  "feedback": "回答很有帮助，但可以更详细一些"
}
```

### 9. 获取评估统计

**端点**: `GET /evaluation/stats`

**响应**:
```json
{
  "total_evaluations": 150,
  "average_score": 0.85,
  "pass_rate": 0.92,
  "metrics_average": {
    "CODE_QUALITY": 0.88,
    "USER_SATISFACTION": 0.82
  }
}
```

### 10. 清空会话

**端点**: `DELETE /context/{sessionId}`

---

## Harness Engineering实践

### 什么是Harness Engineering？

Harness Engineering 是一种系统化的AI应用开发和评估方法，通过建立测试框架、质量度量和反馈循环来确保AI系统的可靠性和持续改进。

### 本项目的实践

#### 1. 测试用例管理

系统预定义了多种测试用例来评估AI助手的表现：

```java
TestCase testCase = new TestCase(
    "code_gen_001",
    "简单函数生成",
    "测试AI生成简单Java函数的能力",
    TestCaseType.CODE_GENERATION
);
```

#### 2. 多维度评估

评估指标包括：
- **代码质量** (CODE_QUALITY)
- **正确性** (CORRECTNESS)
- **完整性** (COMPLETENESS)
- **可读性** (READABILITY)
- **性能** (PERFORMANCE)
- **安全性** (SECURITY)
- **用户满意度** (USER_SATISFACTION)
- **响应时间** (RESPONSE_TIME)

#### 3. 自动化评估流程

```java
// 执行评估
EvaluationResult result = evaluationService.evaluate(
    testCaseId,
    sessionId,
    actualOutput,
    context
);

// 检查是否通过
boolean passed = result.isPassed(0.7); // 阈值0.7
```

#### 4. 用户反馈循环

收集用户反馈并用于改进：
```java
evaluationService.recordUserFeedback(
    sessionId,
    rating,      // 1-5星评分
    feedback     // 文字反馈
);
```

#### 5. 质量指标监控

实时监控系统性能：
- 平均评分
- 通过率
- 各维度平均分
- 响应时间分布

### 持续改进策略

1. **定期评估**: 运行测试用例套件评估系统表现
2. **反馈分析**: 分析用户反馈识别改进点
3. **提示词优化**: 基于评估结果优化提示词模板
4. **A/B测试**: 对比不同提示词或模型的效果
5. **阈值调整**: 根据实际需求调整质量阈值

---

## 配置说明

### application.yml 配置项

#### 服务器配置
```yaml
server:
  port: 8080  # 服务端口
```

#### AI模型配置
```yaml
spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}  # API密钥
      chat:
        options:
          model: qwen-plus            # 模型选择
          temperature: 0.7            # 创造性程度 (0-1)
          top-p: 0.8                  # 采样参数
          max-tokens: 2000            # 最大token数
```

#### 数据库配置
```yaml
spring:
  datasource:
    url: jdbc:h2:mem:codeassistant  # H2内存数据库
    username: sa
    password:
  
  jpa:
    hibernate:
      ddl-auto: update  # 自动更新表结构
    show-sql: true      # 显示SQL语句
```

### 自定义提示词模板

可以通过代码注册新的提示词模板：

```java
@Autowired
private PromptService promptService;

PromptTemplate customTemplate = new PromptTemplate(
    "custom_template",
    "你是一个{role}专家。请{task}",
    PromptType.GENERAL_CHAT
);
customTemplate.addDefaultVariable("role", "Java");
promptService.registerTemplate(customTemplate);
```

---

## 开发指南

### 项目结构

```
src/main/java/com/codeassistant/
├── CodeAssistantApplication.java    # 主应用类
├── config/                           # 配置类
│   └── WebConfig.java
├── memory/                           # 记忆管理
│   ├── model/Memory.java
│   ├── repository/MemoryRepository.java
│   └── service/MemoryService.java
├── context/                          # 上下文管理
│   ├── model/ConversationContext.java
│   └── service/ContextService.java
├── prompt/                           # 提示词管理
│   ├── model/PromptTemplate.java
│   └── service/PromptService.java
├── ai/                               # AI服务
│   └── service/ChatService.java
├── harness/                          # Harness Engineering
│   ├── model/EvaluationResult.java
│   ├── model/TestCase.java
│   └── service/EvaluationService.java
└── api/                              # API层
    ├── dto/                          # 数据传输对象
    └── controller/AssistantController.java
```

### 扩展新功能

#### 1. 添加新的AI功能

在 `ChatService` 中添加新方法：

```java
public String newFeature(String sessionId, String userId, String input) {
    Map<String, Object> variables = new HashMap<>();
    variables.put("input", input);
    
    String prompt = promptService.renderPrompt("new_template", variables);
    return callAIModel(prompt);
}
```

#### 2. 创建新的提示词模板

```java
PromptTemplate template = new PromptTemplate(
    "new_template",
    "你的提示词模板内容: {variable}",
    PromptType.GENERAL_CHAT
);
promptService.registerTemplate(template);
```

#### 3. 添加新的测试用例

```java
TestCase testCase = new TestCase(
    "test_id",
    "测试名称",
    "测试描述",
    TestCaseType.CODE_GENERATION
);
testCase.addCriterion(new EvaluationCriterion(...));
evaluationService.registerTestCase(testCase);
```

### 最佳实践

1. **会话管理**: 为每个用户会话使用唯一的sessionId
2. **上下文清理**: 定期清理不再使用的会话上下文
3. **错误处理**: 始终捕获和处理AI调用异常
4. **日志记录**: 记录关键操作便于调试和监控
5. **性能优化**: 合理设置maxHistorySize控制内存使用

---

## 常见问题

### Q1: 如何获取通义千问API密钥？

访问阿里云官网，注册账号并开通DashScope服务，在控制台获取API密钥。

### Q2: 如何切换到其他数据库？

修改 `application.yml` 中的数据库配置，添加对应的JDBC驱动依赖。

### Q3: 如何提高AI响应质量？

- 调整temperature参数（较低值更保守）
- 优化提示词模板
- 提供更多上下文信息
- 使用更强大的模型（如qwen-max）

### Q4: 如何部署到生产环境？

1. 使用MySQL/PostgreSQL替代H2
2. 配置适当的日志级别
3. 启用HTTPS
4. 设置合理的超时和重试策略
5. 添加监控和告警

---

## 许可证

本项目采用 MIT 许可证。

---

## 联系方式

如有问题或建议，请提交Issue或Pull Request。

---

**祝您使用愉快！** 🚀