LLM_ARCHITECTURE.md

LLM Architecture Design

概述

HarmonySafeAgent采用双策略模式的LLM架构设计，实现了高度灵活、可扩展的AI能力系统。

核心设计理念

✅ Provider策略: 支持多个LLM提供商（OpenAI, Claude, 本地模型等） ✅ Role策略: 不同AI角色负责不同专业任务 ✅ Orchestrator编排: 统一管理角色协作流程 ✅ Context共享: 跨角色的状态和信息传递 ✅ 配置驱动: 通过配置灵活调整Provider和Role映射

---

架构层次

┌─────────────────────────────────────────────────────────────┐
│                    User Input (Requirement)                  │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│                     LLMOrchestrator                          │
│  (Workflow Management & Role Coordination)                   │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
        ┌──────────────────┴──────────────────┐
        │                                       │
        ↓                                       ↓
┌───────────────┐                    ┌───────────────────┐
│  Role Strategy│                    │ Provider Strategy │
│  (Task-based) │                    │  (API-based)      │
└───────┬───────┘                    └────────┬──────────┘
        │                                     │
   ┌────┴────┬────────┬──────────┐          │
   ↓         ↓        ↓          ↓          ↓
Analyzer Planner  Coder  Reviewer    OpenAI / Claude / Local
        │         │        │          │          │
        └─────────┴────────┴──────────┴──────────┘
                           ↓
              ┌────────────────────────┐
              │ ConversationContext     │
              │ (Shared State)          │
              └─────────────────────────┘

---

1. Provider策略 (多LLM提供商支持)

设计目标

• 抽象不同LLM API的差异
• 支持快速切换和切换Provider
• 便于添加新的LLM提供商

核心接口

interface LLMProvider {
    LLMResponse sendRequest(LLMRequest request);
    String getProviderName();
    boolean isAvailable();
    String[] getAvailableModels();
    boolean supportsModel(String model);
}

已实现的Provider

Provider	类名	支持的模型
OpenAI	OpenAIProvider	gpt-3.5-turbo, gpt-4, gpt-4-turbo
Claude	ClaudeProvider	claude-3-haiku, sonnet, opus

添加新Provider

public class CustomProvider extends BaseLLMProvider {
    @Override
    public String getProviderName() {
        return "custom";
    }

    @Override
    public String[] getAvailableModels() {
        return new String[]{"model-1", "model-2"};
    }

    @Override
    protected LLMResponse sendHttpRequest(LLMRequest request) {
        // 实现HTTP请求逻辑
    }
}

// 注册
providerFactory.registerProvider("custom", new CustomProvider(apiKey));

---

2. Role策略 (任务专业化分工)

设计目标

• 每个角色专注特定任务类型
• 使用最适合的模型（成本优化）
• 清晰的职责划分

核心接口

interface LLMRole {
    String getRoleName();
    String getRoleDescription();
    String getSystemPrompt();
    double getRecommendedTemperature();
    int getRecommendedMaxTokens();
    LLMResponse execute(String input, String context);
}

已实现的Role

Role	职责	推荐模型	Temperature	Max Tokens
Analyzer	需求分析、任务分解	快速模型 (gpt-3.5)	0.3 (精确)	1000
Planner	技术设计、架构规划	标准模型 (claude-sonnet)	0.5 (平衡)	2500
Coder	代码生成、实现	标准模型 (claude-sonnet)	0.2 (一致)	3000
Reviewer	代码审查、质量把关	高级模型 (claude-opus)	0.7 (创造性)	2500

Role详细说明

1️⃣ Analyzer Role - 需求分析器

职责：

• 分析用户需求
• 将需求分解为3-7个可执行任务
• 生成结构化的TodoList

System Prompt特点：

你是需求分析专家，负责：
1. 仔细分析用户需求
2. 分解为清晰、可操作的任务
3. 生成3-7个结构化任务列表
4. 每个任务具体且可度量
5. 任务遵循逻辑顺序

适用场景：

• /plan <requirement> 命令
• 自动任务规划

---

2️⃣ Planner Role - 技术规划师

职责：

• 创建技术设计方案
• 考虑安全性、可扩展性、可维护性
• 提供实现策略
• 识别潜在风险和缓解措施

System Prompt特点：

你是软件架构专家，负责：
1. 为需求设计技术解决方案
2. 考虑SOLID原则和最佳实践
3. 提供清晰的实现策略
4. 建议合适的设计模式
5. 识别风险并提供缓解策略

适用场景：

• 架构设计
• 技术方案规划
• 实现策略制定

---

3️⃣ Coder Role - 代码生成器

职责：

• 生成生产质量代码
• 遵循SOLID原则
• 包含错误处理
• 添加有意义的注释

System Prompt特点：

你是Java开发专家，负责：
1. 编写清晰、生产质量的代码
2. 遵循SOLID原则和最佳实践
3. 包含适当的错误处理
4. 为复杂逻辑添加注释
5. 确保代码安全高效

适用场景：

• 代码实现
• 功能开发
• 代码重构

---

4️⃣ Reviewer Role - 代码审查员

职责：

• 审查代码正确性、安全性和质量
• 识别bug、安全漏洞和代码异味
• 验证最佳实践遵循情况
• 提供建设性反馈

System Prompt特点：

你是高级代码审查专家，负责：
1. 审查代码的正确性、安全性和质量
2. 识别bug、漏洞和代码异味
3. 检查SOLID原则遵循情况
4. 验证错误处理和边界情况
5. 提供具体的改进建议

审查清单：
- 安全漏洞（注入、XSS等）
- 逻辑错误和bug
- 代码可读性和可维护性
- 性能问题
- 测试覆盖率

输出格式：

• ✅ Approved - 代码符合质量标准
• ⚠️ Needs improvement - 具体问题和建议
• ❌ Rejected - 必须修复的关键问题

---

3. Orchestrator (工作流编排)

核心功能

class LLMOrchestrator {
    // 配置角色使用的Provider和Model
    void configureRole(String roleName, String providerName, String model);

    // 执行特定角色
    LLMResponse executeRole(String roleName, String input, ConversationContext context);

    // 高级工作流方法
    TodoList analyzeRequirement(String requirement);
    String createDesign(ConversationContext context, String task);
    String generateCode(ConversationContext context, String task);
    String reviewCode(ConversationContext context, String code);
}

工作流示例

// 1. 创建Orchestrator
LLMOrchestrator orchestrator = LLMOrchestrator.builder(providerFactory, roleFactory)
    .configureRole("analyzer", "openai", "gpt-3.5-turbo")
    .configureRole("planner", "claude", "claude-3-sonnet")
    .configureRole("coder", "claude", "claude-3-sonnet")
    .configureRole("reviewer", "claude", "claude-3-opus")
    .build();

// 2. 执行完整工作流
ConversationContext context = new ConversationContext(requirement);

// Step 1: 分析需求
TodoList tasks = orchestrator.analyzeRequirement(requirement);
context.setTodoList(tasks);

// Step 2: 规划设计
String design = orchestrator.createDesign(context, "Design the authentication module");
context.setDesignDocument(design);

// Step 3: 生成代码
String code = orchestrator.generateCode(context, "Implement login functionality");
context.addGeneratedCode("LoginService.java", code);

// Step 4: 审查代码
String review = orchestrator.reviewCode(context, code);

// Step 5: 根据审查反馈改进（如有需要）
if (review.contains("⚠️") || review.contains("❌")) {
    String improvedCode = orchestrator.generateCode(context,
        "Improve code based on review: " + review);
}

---

4. ConversationContext (上下文共享)

设计目标

• 跨角色共享信息
• 保持工作流状态
• 提供历史记录

数据结构

class ConversationContext {
    private final String requirement;           // 原始需求
    private TodoList todoList;                  // 任务列表
    private String designDocument;              // 设计文档
    private Map<String, String> generatedCode;  // 生成的代码
    private List<ReviewComment> reviewComments; // 审查意见
    private Map<String, Object> metadata;       // 元数据

    // 构建上下文字符串供Role使用
    String buildContextString();
}

Context的作用

Analyzer → 生成TodoList
    ↓
Context.setTodoList(tasks)
    ↓
Planner → 看到TodoList → 设计方案
    ↓
Context.setDesignDocument(design)
    ↓
Coder → 看到TodoList + Design → 生成代码
    ↓
Context.addGeneratedCode(file, code)
    ↓
Reviewer → 看到全部Context → 审查代码
    ↓
Context.addReviewComment(comment)

---

5. 配置系统

配置文件结构 (application.yml)

ai:
  # 多Provider配置
  providers:
    openai:
      api_key: ${OPENAI_API_KEY}
      base_url: https://api.openai.com/v1
      models:
        fast: gpt-3.5-turbo
        standard: gpt-4-turbo
        premium: gpt-4

    claude:
      api_key: ${CLAUDE_API_KEY}
      base_url: https://api.anthropic.com/v1
      models:
        fast: claude-3-haiku-20240307
        standard: claude-3-sonnet-20240229
        premium: claude-3-opus-20240229

  # Role到Provider/Model的映射
  roles:
    analyzer:
      provider: openai
      model: fast
      temperature: 0.3
      max_tokens: 1000

    planner:
      provider: claude
      model: standard
      temperature: 0.5
      max_tokens: 2500

    coder:
      provider: claude
      model: standard
      temperature: 0.2
      max_tokens: 3000

    reviewer:
      provider: claude
      model: premium
      temperature: 0.7
      max_tokens: 2500

成本优化策略

任务类型	推荐模型	原因	相对成本
简单分析	GPT-3.5-turbo	快速、廉价	💰
架构设计	Claude Sonnet	平衡质量和成本	💰💰
代码生成	Claude Sonnet	代码能力强	💰💰
代码审查	Claude Opus	最强分析能力	💰💰💰

示例成本计算：

• Analyzer (GPT-3.5): ~$0.002 per request
• Planner (Sonnet): ~$0.015 per request
• Coder (Sonnet): ~$0.020 per request
• Reviewer (Opus): ~$0.075 per request

总成本: ~$0.112 per complete workflow vs. 全程使用GPT-4: ~$0.300 per workflow 节省: ~63% 💰

---

6. 文件结构

src/main/java/com/harmony/agent/llm/
├── model/                      # 数据模型
│   ├── Message.java           # 消息模型
│   ├── LLMRequest.java        # 请求模型
│   └── LLMResponse.java       # 响应模型
│
├── provider/                   # Provider策略
│   ├── LLMProvider.java       # Provider接口
│   ├── BaseLLMProvider.java   # Provider基类
│   ├── OpenAIProvider.java    # OpenAI实现
│   ├── ClaudeProvider.java    # Claude实现
│   └── ProviderFactory.java   # Provider工厂
│
├── role/                      # Role策略
│   ├── LLMRole.java          # Role接口
│   ├── BaseLLMRole.java      # Role基类
│   ├── AnalyzerRole.java     # 分析器角色
│   ├── PlannerRole.java      # 规划器角色
│   ├── CoderRole.java        # 编码器角色
│   ├── ReviewerRole.java     # 审查器角色
│   └── RoleFactory.java      # Role工厂
│
├── orchestrator/              # 编排器
│   ├── LLMOrchestrator.java  # 工作流编排
│   └── ConversationContext.java # 上下文管理
│
└── LLMClient.java            # 原有客户端（保留兼容性）

---

7. 使用示例

基础用法

// 1. 创建Provider工厂
ProviderFactory providerFactory = ProviderFactory.createDefault(
    System.getenv("OPENAI_API_KEY"),
    System.getenv("CLAUDE_API_KEY")
);

// 2. 创建Role工厂
RoleFactory roleFactory = RoleFactory.createDefault();

// 3. 创建并配置Orchestrator
LLMOrchestrator orchestrator = LLMOrchestrator.builder(providerFactory, roleFactory)
    .configureRole("analyzer", "openai", "gpt-3.5-turbo")
    .configureRole("planner", "claude", "claude-3-sonnet-20240229")
    .configureRole("coder", "claude", "claude-3-sonnet-20240229")
    .configureRole("reviewer", "claude", "claude-3-opus-20240229")
    .build();

// 4. 执行工作流
String requirement = "实现用户登录功能";
TodoList tasks = orchestrator.analyzeRequirement(requirement);

集成到TodoListManager

// 在TodoListManager中使用Orchestrator
public class TodoListManager {
    private final LLMOrchestrator orchestrator;

    public TodoList createTodoList(String requirement) {
        // 使用Analyzer角色分析需求
        return orchestrator.analyzeRequirement(requirement);
    }

    public boolean executeCurrentTask() {
        Task task = todoList.getCurrentTask();
        ConversationContext context = new ConversationContext(todoList.getRequirement());

        // 根据任务类型选择角色
        if (task.getDescription().contains("设计") || task.getDescription().contains("规划")) {
            String design = orchestrator.createDesign(context, task.getDescription());
            task.setOutput(design);
        } else if (task.getDescription().contains("实现") || task.getDescription().contains("代码")) {
            String code = orchestrator.generateCode(context, task.getDescription());
            task.setOutput(code);

            // 自动代码审查
            String review = orchestrator.reviewCode(context, code);
            if (review.contains("❌")) {
                // 需要改进
                String improved = orchestrator.generateCode(context,
                    "根据审查意见改进: " + review);
                task.setOutput(improved);
            }
        }

        return true;
    }
}

---

8. 扩展性

添加新Provider

// 1. 实现Provider接口
public class DeepSeekProvider extends BaseLLMProvider {
    @Override
    public String getProviderName() {
        return "deepseek";
    }
    // ... 实现其他方法
}

// 2. 注册Provider
providerFactory.registerProvider("deepseek", new DeepSeekProvider(apiKey));

// 3. 配置角色使用新Provider
orchestrator.configureRole("analyzer", "deepseek", "deepseek-chat");

添加新Role

// 1. 实现Role接口
public class TesterRole extends BaseLLMRole {
    @Override
    public String getRoleName() {
        return "tester";
    }

    @Override
    public String getSystemPrompt() {
        return "你是测试工程师...";
    }
    // ... 实现其他方法
}

// 2. 注册Role
roleFactory.registerRole("tester", new TesterRole());

// 3. 配置Role
orchestrator.configureRole("tester", "openai", "gpt-4");

---

9. 最佳实践

✅ Do's

1. 成本优化

   • 简单任务使用快速模型
   • 关键任务使用高级模型
   • 监控token使用量

2. Context管理

   • 保持Context简洁
   • 只传递必要信息
   • 定期清理历史记录

3. 错误处理

   • 检查API可用性
   • 处理超时和限流
   • 实现重试机制

4. 质量保证

   • 关键代码必须Review
   • Review不通过自动重试
   • 记录所有交互日志

❌ Don'ts

1. 不要在生产环境使用未配置的Provider
2. 不要忽略Review的警告
3. 不要在Context中存储敏感信息
4. 不要过度依赖单一Provider

---

10. 未来增强 (Phase 3+)

Phase 3: 实际API集成

• 实现OpenAI HTTP客户端
• 实现Claude HTTP客户端
• 添加重试和限流机制
• 实现流式响应支持

Phase 4: 高级功能

• 添加缓存机制
• 并发任务执行
• 成本追踪和报告
• A/B测试不同模型
• 自动模型选择优化

Phase 5: 智能增强

• 基于历史性能自动选择模型
• 自适应temperature调整
• 上下文智能压缩
• 多Agent协作模式

---

总结

这个架构设计实现了：

✅ 灵活性: 轻松切换Provider和Model ✅ 专业化: 每个Role专注特定任务 ✅ 成本优化: 根据任务难度选择模型 ✅ 可扩展: 方便添加新Provider和Role ✅ 协作性: Orchestrator管理多角色工作流 ✅ 上下文管理: ConversationContext共享状态

这是一个生产就绪、高度可配置的企业级LLM架构！ 🚀

---

Version: 1.0.0 Last Updated: 2025-10-17 Architecture Author: Claude + User Collaboration