Docs: add design doc

docs/design-doc.md

@@ -0,0 +1,397 @@
+
+# CodeAgent 产品设计文档
+
+## 1. 产品概述
+
+### 1.1 CodeAgent 是什么
+
+CodeAgent 是一个基于 AI 的代码代理系统，专门为 GitHub 开发流程设计。它能够：
+
+- **自动处理 GitHub Issue 和 Pull Request**：通过 Webhook 监听 GitHub 事件，自动响应开发者的指令
+- **智能代码生成和修改**：利用 AI 模型（Claude、Gemini）理解需求并生成代码
+- **无缝集成开发流程**：直接在 GitHub 界面中通过评论触发，无需切换工具
+- **基于 Git Worktree 的工作空间管理**：为每个任务创建独立的工作环境，确保代码隔离
+
+### 1.2 工作机制
+
+CodeAgent 的工作机制如下：
+
+1. **事件监听**：通过 GitHub Webhook 监听 Issue 评论、PR 评论等事件
+2. **命令解析**：解析评论中的特定命令（如 `/code`、`/continue`、`/fix`）
+3. **工作空间创建**：基于 Git Worktree 为每个任务创建独立的工作环境
+4. **AI 处理**：调用 AI 模型（Claude/Gemini）理解需求并生成代码
+5. **代码提交**：自动将生成的代码提交到 Git 仓库并创建/更新 PR
+6. **结果反馈**：在 GitHub 界面中展示处理结果
+
+**核心流程示例**：
+```
+开发者评论 "/code 实现用户登录功能" 
+→ CodeAgent 创建独立工作空间 
+→ 调用 AI 生成代码 
+→ 自动提交到新分支 
+→ 创建 PR 并展示结果
+```
+
+### 1.3 当前功能
+
+- 支持 Claude 和 Gemini 两种 AI 模型
+- 基于 Git Worktree 的工作空间管理
+- GitHub Webhook 集成和签名验证
+- Docker 容器化执行环境
+- 自动代码生成和 PR 创建
+- 支持 `/code`、`/continue`、`/fix` 等命令
+- 历史评论上下文理解
+- 自动清理过期工作空间
+
+## 2. 竞品分析
+
+### 2.1 与 Claude Code 和 Gemini-Cli 的横向对比
+
+| 功能特性 | CodeAgent | Claude Code | Gemini-Cli |
+|---------|-----------|-------------|------------|
+| **集成方式** | GitHub Webhook | 本地 CLI | 本地 CLI |
+| **工作空间管理** | Git Worktree | 本地目录 | 本地目录 |
+| **多模型支持** | Claude + Gemini | 仅 Claude | 仅 Gemini |
+| **自动化程度** | 全自动 | 半自动 | 半自动 |
+| **成本控制** | 计划支持 | 无 | 无 |
+| **负载均衡** | 计划支持 | 无 | 无 |
+| **API 接口** | 计划支持 | 无 | 无 |
+| **监控统计** | 计划支持 | 无 | 无 |
+| **团队协作** | GitHub 集成 | GitHub 集成，但prompt黑盒 | 本地使用 |
+| **部署复杂度** | 中等 | 简单 | 简单 |
+
+**CodeAgent 优势**：
+- **团队协作友好**：直接集成 GitHub，支持团队协作
+- **自动化程度高**：从代码生成到 PR 创建全自动
+- **扩展性强**：支持多模型、负载均衡、成本控制等高级功能
+
+**CodeAgent 劣势**：
+- **部署复杂度**：需要配置 Webhook 和服务器
+- **学习成本**：需要了解 GitHub 集成流程
+- **依赖外部服务**：需要 GitHub 和 AI 服务商
+
+### 2.2 AI 智能网关竞品分析
+
+#### 2.2.1 CC Replay (Claude Code Router)
+
+**产品定位**：基于 Claude Code 的路由器，支持多模型切换和负载均衡
+
+**核心功能**：
+- 多 Claude 账号管理
+- 智能路由和负载均衡
+- 成本控制和用量统计
+- 故障自动切换
+
+**与 CodeAgent 对比**：
+- **相似点**：都支持多账号管理和负载均衡
+- **差异点**：CC Replay 专注于 Claude，CodeAgent 支持多模型
+- **优势**：CC Replay 更专注于单一模型优化
+- **劣势**：缺乏 GitHub 集成和团队协作功能
+
+#### 2.2.2 Qiniu AIGC API
+
+**产品定位**：七牛云提供的统一 AI 服务 API 网关
+
+**核心功能**：
+- 多 AI 模型统一接口
+- 智能路由和负载均衡
+- 成本控制和用量统计
+- 高可用和故障转移
+
+**与 CodeAgent 对比**：
+- **相似点**：都提供统一的 AI 服务接口
+- **差异点**：Qiniu AIGC 是通用 API 网关，CodeAgent 专注于代码生成
+- **优势**：Qiniu AIGC 更通用，支持更多 AI 模型
+- **劣势**：缺乏 GitHub 集成和代码生成优化
+
+#### 2.2.3 Claude Router
+
+**产品定位**：开源的 Claude API 路由和负载均衡工具
+
+**核心功能**：
+- Claude API 路由
+- 多账号负载均衡
+- 简单的成本控制
+- 故障切换
+
+**与 CodeAgent 对比**：
+- **相似点**：都支持多账号管理和负载均衡
+- **差异点**：Claude Router 更轻量，专注于路由功能
+- **优势**：Claude Router 更简单易用
+- **劣势**：功能相对简单，缺乏高级特性
+
+### 2.3 市场定位分析
+
+**CodeAgent 的差异化优势**：
+
+1. **GitHub 原生集成**：唯一深度集成 GitHub 的 AI 代码代理
+2. **团队协作导向**：支持团队协作和代码审查流程
+3. **全流程自动化**：从需求到代码到 PR 的全自动流程
+4. **多模型智能选择**：支持多种 AI 模型并智能选择最优方案
+
+**目标用户群体**：
+- **开发团队**：需要 AI 辅助代码生成的团队
+- **开源项目**：需要自动化代码贡献的项目
+- **企业开发**：需要标准化 AI 代码生成流程的企业
+
+## 3. 当前问题分析
+
+### 3.1 技术架构问题
+
+1. **AI 模型支持有限**：
+   - 仅支持 Claude 和 Gemini
+   - 缺乏对新 AI 模型的快速接入能力
+   - 没有统一的模型接口标准
+
+2. **成本控制不足**：
+   - 无法根据任务类型智能选择最经济的 AI 模型
+   - 缺乏用量统计和成本分析
+   - 没有预算控制机制
+
+3. **账号管理简单**：
+   - 仅支持单一账号配置
+   - 缺乏多账号池管理
+   - 没有账号状态监控和故障转移
+
+4. **API 接口缺失**：
+   - 仅支持 GitHub Webhook 触发
+   - 缺乏标准化的 API 接口
+   - 无法被其他系统集成
+
+5. **Workflow 流程固化**：
+   - 当前 prompt 和流程写死在代码中
+   - 缺乏灵活的工作流配置
+   - 无法根据项目需求定制流程
+
+### 3.2 业务功能问题
+
+1. **任务分类不智能**：
+   - 无法区分编码任务和非编码任务
+   - 缺乏针对不同任务类型的优化策略
+   - 没有成本效益分析
+
+2. **负载均衡缺失**：
+   - 无法在多个 AI 模型间智能分配任务
+   - 缺乏基于用量和成本的负载均衡
+   - 没有故障自动切换机制
+
+3. **监控运维不足**：
+   - 缺乏详细的用量统计
+   - 没有成本监控和告警
+   - 缺乏性能指标监控
+
+## 4. 产品目标
+
+### 4.1 总体目标
+
+将 CodeAgent 从一个简单的 GitHub 代码代理，扩展为一个功能完整的 AI 服务代理平台，为开发者提供统一的、智能的、成本优化的 AI 服务接口。
+
+### 4.2 具体目标
+
+#### 目标 1：支持 Classfile 编码
+**背景**：当前 CodeAgent 仅支持通用语言的代码生成，缺乏Classfile DSL的支持。
+
+**目标**：扩展 AI 模型支持，增加对 Classfile 等特殊格式的编码能力。
+
+**实现思路**：
+- 设计统一的编码接口，支持多种文件格式
+- 为不同 AI 模型实现编码适配器
+- 提供编码格式转换和验证功能
+
+#### 目标 2：融合 CLI 支持
+**背景**：当前所有任务都使用相同的 AI 模型，无法根据任务类型和成本要求进行优化。
+
+**目标**：智能选择最适合的 CLI 工具来处理不同类型的任务，优化成本和性能。
+
+**实现思路**：
+- 建立任务分类体系（编码任务 vs 非编码任务）
+- 设计 CLI 选择算法，考虑成本、性能、质量等因素
+- 实现动态 CLI 切换和故障转移
+
+#### 目标 3：多渠道账号池管理
+**背景**：当前仅支持单一账号配置，缺乏多账号管理和故障转移能力。
+
+**目标**：统一管理多个 AI 服务商的账号，包括账号状态监控、用量统计、负载均衡等功能。
+
+**实现思路**：
+- 设计账号池管理架构，支持多服务商、多账号
+- 实现账号状态监控和自动故障转移
+- 提供账号用量统计和成本分析
+
+#### 目标 4：账号池账号的 AccessToken 有效性维持
+**背景**：AI 服务商的 AccessToken 会过期，需要手动更新，影响服务可用性。
+
+**目标**：自动监控和刷新 AccessToken，确保服务持续可用。
+
+**实现思路**：
+- 实现 Token 有效性检测机制
+- 设计自动刷新流程
+- 提供 Token 轮换和备份策略
+
+#### 目标 5：账号池账号状态/用量查询
+**背景**：缺乏对账号状态和用量的实时监控，无法及时发现问题和优化使用。
+
+**目标**：实时监控账号状态和用量，提供详细的统计和分析。
+
+**实现思路**：
+- 设计监控指标体系
+- 实现实时状态查询和用量统计
+- 提供可视化监控界面
+
+#### 目标 6：对外提供 OpenAI 范式 API
+**背景**：当前仅支持 GitHub Webhook 触发，无法被其他系统集成。
+
+**目标**：提供标准化的 OpenAI 兼容 API 接口，支持 API Key 认证、QPS 限制、用量统计等功能。
+
+**实现思路**：
+- 设计 OpenAI 兼容的 API 接口
+- 实现 API Key 管理和认证
+- 提供 QPS 限制和用量统计
+
+#### 目标 7：API 提供 QPS 限制，用量，费用预估
+**背景**：缺乏对 API 使用的限制和成本控制。
+
+**目标**：为 API 提供完整的限制、监控和成本控制功能。
+
+**实现思路**：
+- 设计 QPS 限制和配额管理
+- 实现实时用量统计和费用预估
+- 提供成本告警和预算控制
+
+#### 目标 8：转发 API 请求时，负载均衡账号用量
+**背景**：无法在多个账号间智能分配请求，可能导致某些账号过载而其他账号闲置。
+
+**目标**：基于账号用量、成本、性能等因素进行智能负载均衡，确保资源的最优利用。
+
+**实现思路**：
+- 设计负载均衡算法，考虑用量、成本、性能等因素
+- 实现动态负载分配和故障转移
+- 提供负载均衡策略配置
+
+#### 目标 9：Workflow 流程引擎
+**背景**：当前 prompt 和流程写死在代码中，缺乏灵活性，无法根据项目需求定制。
+
+**目标**：设计可配置的工作流引擎，支持自定义 prompt 和流程。
+
+**实现思路**：
+- 设计 Workflow 配置格式，支持 YAML/JSON 配置
+- 实现可插拔的 prompt 模板系统
+- 支持条件分支和循环流程
+- 提供 Workflow 版本管理和回滚功能
+
+## 5. 最终交付产品
+
+### 5.1 产品形态
+
+CodeAgent 将从一个 GitHub 代码代理，扩展为一个完整的 AI 服务代理平台，包含以下核心组件：
+
+1. **AI 服务网关**：统一的 API 入口，支持多种 AI 模型
+2. **账号池管理系统**：多账号、多服务商的统一管理
+3. **智能负载均衡器**：基于成本、性能、用量的智能分配
+4. **监控分析平台**：用量统计、成本分析、性能监控
+5. **Workflow 引擎**：可配置的工作流系统
+6. **GitHub 集成模块**：保持原有的 GitHub 集成能力
+
+### 5.2 核心功能
+
+#### 5.2.1 统一 AI 服务接口
+- **OpenAI 兼容 API**：提供标准的 OpenAI 格式 API
+- **多模型支持**：支持 Claude、Gemini 等多种 AI 模型
+- **智能路由**：根据任务类型和成本要求智能选择模型
+
+#### 5.2.2 智能账号管理
+- **多账号池**：支持多个 AI 服务商的账号管理
+- **自动故障转移**：账号故障时自动切换到备用账号
+- **Token 自动刷新**：自动监控和刷新过期的 AccessToken
+
+#### 5.2.3 成本优化系统
+- **智能 CLI 选择**：根据任务类型选择最经济的 AI 模型
+- **成本监控**：实时监控用量和成本
+- **预算控制**：设置预算限制和告警
+
+#### 5.2.4 负载均衡系统
+- **多维度负载均衡**：基于用量、成本、性能的智能分配
+- **动态调整**：根据实时情况动态调整负载分配
+- **故障恢复**：自动检测故障并恢复服务
+
+#### 5.2.5 监控分析平台
+- **实时监控**：API 调用量、响应时间、错误率等指标
+- **成本分析**：详细的成本统计和分析报告
+- **性能优化**：基于监控数据的性能优化建议
+
+#### 5.2.6 Workflow 引擎
+- **可配置流程**：支持 YAML/JSON 配置工作流
+- **模板系统**：可插拔的 prompt 模板
+- **条件分支**：支持复杂的条件判断和分支流程
+- **版本管理**：Workflow 版本控制和回滚功能
+
+### 5.3 技术架构
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   客户端应用    │    │  CodeAgent      │    │   AI 服务商     │
+│  (GitHub/API)   │───▶│   网关平台      │───▶│  (Claude/Gemini)│
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                              │
+                              ▼
+                       ┌─────────────────┐
+                       │   账号池管理    │
+                       │   负载均衡      │
+                       └─────────────────┘
+                              │
+                              ▼
+                       ┌─────────────────┐
+                       │  Workflow 引擎  │
+                       │   流程管理      │
+                       └─────────────────┘
+```
+
+### 5.4 用户价值
+
+1. **降低 AI 使用成本**：通过智能选择和负载均衡，显著降低 AI 服务使用成本
+2. **提高开发效率**：统一的 API 接口，简化 AI 服务集成
+3. **增强系统可靠性**：多账号管理和故障转移，提高服务可用性
+4. **优化资源利用**：智能负载均衡，最大化资源利用效率
+5. **保持开发体验**：继续支持 GitHub 集成，保持原有的开发体验
+6. **灵活定制能力**：Workflow 引擎支持根据项目需求定制流程
+
+## 6. Workflow 设计
+
+### 6.1 当前流程分析
+
+CodeAgent 目前有以下固定的流程：
+
+1. **Issue 处理流程**：
+   - 解析 `/code` 命令
+   - 创建工作空间
+   - 生成代码
+   - 创建 PR
+   - 更新 PR Body
+
+2. **PR 继续流程**：
+   - 解析 `/continue` 命令
+   - 获取历史上下文
+   - 继续开发
+   - 提交代码
+   - 添加评论
+
+3. **PR 修复流程**：
+   - 解析 `/fix` 命令
+   - 分析问题
+   - 修复代码
+   - 提交修复
+   - 添加评论
+
+
+
+### 6.2 Workflow 优势
+
+1. **灵活性**：支持自定义流程和 prompt
+2. **可扩展性**：易于添加新的步骤和模板
+3. **可维护性**：配置与代码分离，便于维护
+4. **可测试性**：每个步骤可以独立测试
+5. **版本控制**：支持 Workflow 版本管理和回滚
+
+通过 Workflow 引擎，CodeAgent 将从一个固定的代码生成工具，转变为可配置的、灵活的 AI 开发助手，能够根据不同的项目需求和团队偏好进行定制。
+
+