1069 lines
34 KiB
Markdown
1069 lines
34 KiB
Markdown
# 重構計劃：cursor-api-proxy → go-zero + DDD Architecture
|
||
|
||
## 一、概述
|
||
|
||
### 目標
|
||
將 cursor-api-proxy 從標準 Go HTTP 架構重構為 go-zero + DDD（Clean Architecture）混合架構。
|
||
|
||
### 核心原則
|
||
- **internal/**：go-zero 框架特定代碼（強依賴框架）
|
||
- **pkg/**：框架無關的核心業務邏輯（DIP 反轉依賴）
|
||
- **api/**：契約優先的 API 定義（goctl 生成基礎代碼）
|
||
|
||
### 架構分層
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ api/chat.api │
|
||
│ (API 契約定義) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ internal/handler/ │
|
||
│ (HTTP Handler 層) │
|
||
│ goctl 生成 + 自訂 SSE Handler │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ internal/logic/ │
|
||
│ (業務邏輯調度層) │
|
||
│ Adapter Pattern: Request → Usecase │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ pkg/usecase/ │
|
||
│ (Application Layer) │
|
||
│ 業務流程協調、Repository 調用 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ pkg/domain/repository/ │
|
||
│ (Repository Interface) │
|
||
│ DIP 反轉依賴 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ pkg/repository/ │
|
||
│ (Infrastructure Layer) │
|
||
│ Repository Interface 實作 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、目錄結構（最終狀態）
|
||
|
||
```
|
||
.
|
||
├── api/ # [Contract] go-zero API 定義
|
||
│ └── chat.api # OpenAI 相容 API 規格
|
||
│
|
||
├── etc/ # [Config] 環境配置
|
||
│ ├── chat.yaml # 本地開發
|
||
│ └── chat-prod.yaml # 生產環境
|
||
│
|
||
├── cmd/ # [Entry] 入口點
|
||
│ ├── chat/ # HTTP proxy 服務
|
||
│ │ └── chat.go # go-zero 入口
|
||
│ └── cli/ # CLI 工具
|
||
│ ├── login.go
|
||
│ ├── accounts.go
|
||
│ ├── resethwid.go
|
||
│ └── usage.go
|
||
│
|
||
├── internal/ # [Framework Layer] go-zero 特定
|
||
│ ├── config/
|
||
│ │ └── config.go # 配置結構體（使用 rest.RestConf）
|
||
│ ├── handler/ # HTTP handlers (goctl 生成)
|
||
│ │ ├── routes.go # 路由註冊
|
||
│ │ ├── chat_handler.go # Chat API handler
|
||
│ │ ├── health_handler.go # Health check handler
|
||
│ │ └── models_handler.go # Models list handler
|
||
│ ├── logic/ # 業務邏輯調度層
|
||
│ │ ├── chatcompletionlogic.go # Chat completion 邏輯
|
||
│ │ ├── geminichatlogic.go # Gemini chat 邏輯
|
||
│ │ ├── anthropiclogic.go # Anthropic messages 邏輯
|
||
│ │ ├── healthlogic.go # Health 邏輯
|
||
│ │ └── modelslogic.go # Models 邏輯
|
||
│ ├── middleware/ # 中間件
|
||
│ │ ├── auth.go # API Key 驗證
|
||
│ │ └── recovery.go # Panic 恢復
|
||
│ ├── svc/ # ServiceContext (DI 容器)
|
||
│ │ └── servicecontext.go
|
||
│ └── types/ # API types (goctl 生成)
|
||
│ └── types.go
|
||
│
|
||
├── pkg/ # [Domain] 框架無關的核心邏輯
|
||
│ ├── domain/ # <Domain Layer>
|
||
│ │ ├── entity/ # 純粹業務物件（無框架依賴）
|
||
│ │ │ ├── message.go # Message, Tool, ToolCall
|
||
│ │ │ ├── chunk.go # StreamChunk
|
||
│ │ │ ├── account.go # Account, AccountStat
|
||
│ │ │ └── config.go # ProviderConfig
|
||
│ │ ├── repository/ # Repository Interface (DIP)
|
||
│ │ │ ├── account.go # AccountPool interface
|
||
│ │ │ └── provider.go # Provider interface
|
||
│ │ ├── usecase/ # Usecase Interface
|
||
│ │ │ ├── chat.go # ChatUsecase interface
|
||
│ │ │ └── agent.go # AgentRunner interface
|
||
│ │ └── const/ # 常數
|
||
│ │ ├── models.go # Model ID 常數
|
||
│ │ └── errors.go # 錯誤定義
|
||
│ │
|
||
│ ├── repository/ # <Infrastructure Layer>
|
||
│ │ ├── account.go # AccountPool 實作
|
||
│ │ └── provider.go # Provider 工廠
|
||
│ │
|
||
│ ├── usecase/ # <Application Layer>
|
||
│ │ ├── chat.go # ChatUsecase 實作
|
||
│ │ ├── agent.go # Agent 執行邏輯
|
||
│ │ ├── sanitizer.go # 消息清理
|
||
│ │ └── toolcall.go # Tool call 處理
|
||
│ │
|
||
│ ├── provider/ # Provider 實作
|
||
│ │ ├── cursor/ # Cursor CLI provider
|
||
│ │ │ └── provider.go
|
||
│ │ └── geminiweb/ # Gemini Web provider
|
||
│ │ ├── provider.go
|
||
│ │ ├── browser.go
|
||
│ │ └── pool.go
|
||
│ │
|
||
│ ├── infrastructure/ # 基礎設施
|
||
│ │ ├── process/ # 進程管理
|
||
│ │ │ ├── runner.go
|
||
│ │ │ ├── kill_unix.go
|
||
│ │ │ └── kill_windows.go
|
||
│ │ ├── parser/ # SSE parsing
|
||
│ │ │ └── stream.go
|
||
│ │ ├── httputil/ # HTTP 工具
|
||
│ │ │ └── httputil.go
|
||
│ │ ├── logger/ # 日誌
|
||
│ │ │ └── logger.go
|
||
│ │ ├── env/ # 環境變數
|
||
│ │ │ └── env.go
|
||
│ │ ├── workspace/ # 工作區管理
|
||
│ │ │ └── workspace.go
|
||
│ │ └── winlimit/ # Windows 命令行限制
|
||
│ │ └── winlimit.go
|
||
│ │
|
||
│ └── adapter/ # API 格式適配器
|
||
│ ├── openai/ # OpenAI 格式
|
||
│ │ └── openai.go
|
||
│ └── anthropic/ # Anthropic 格式
|
||
│ └── anthropic.go
|
||
│
|
||
├── build/ # [Infrastructure] 建置相關
|
||
│ ├── Dockerfile
|
||
│ └── docker-compose.yml
|
||
│
|
||
├── scripts/ # 腳本工具
|
||
├── docs/ # 文檔
|
||
│ └── MIGRATION_PLAN.md # 本計劃文件
|
||
│
|
||
├── Makefile
|
||
├── go.mod
|
||
└── go.sum
|
||
```
|
||
|
||
---
|
||
|
||
## 三、執行步驟
|
||
|
||
### Phase 1: API 定義與骨架生成
|
||
|
||
**目標**：建立 go-zero 架構骨架
|
||
|
||
#### Step 1.1: 初始化 go-zero 專案
|
||
|
||
```bash
|
||
# 安裝 goctl
|
||
go install github.com/zeromicro/go-zero/tools/goctl@latest
|
||
|
||
# 建立 API 定義目錄
|
||
mkdir -p api etc
|
||
```
|
||
|
||
#### Step 1.2: 建立 `api/chat.api`
|
||
|
||
```api
|
||
syntax = "v1"
|
||
|
||
info (
|
||
title: "Cursor API Proxy"
|
||
desc: "OpenAI-compatible API proxy for Cursor/Gemini"
|
||
author: "cursor-api-proxy"
|
||
version: "1.0"
|
||
)
|
||
|
||
// ============ Types ============
|
||
|
||
type (
|
||
// Health
|
||
HealthRequest {}
|
||
HealthResponse {
|
||
Status string `json:"status"`
|
||
Version string `json:"version"`
|
||
}
|
||
|
||
// Models
|
||
ModelsRequest {}
|
||
ModelsResponse {
|
||
Object string `json:"object"`
|
||
Data []ModelData `json:"data"`
|
||
}
|
||
|
||
ModelData {
|
||
Id string `json:"id"`
|
||
Object string `json:"object"`
|
||
OwnedBy string `json:"owned_by"`
|
||
}
|
||
|
||
// Chat Completions
|
||
ChatCompletionRequest {
|
||
Model string `json:"model"`
|
||
Messages []Message `json:"messages"`
|
||
Stream bool `json:"stream,optional"`
|
||
Tools []Tool `json:"tools,optional"`
|
||
Functions []Function `json:"functions,optional"`
|
||
MaxTokens int `json:"max_tokens,optional"`
|
||
Temperature float64 `json:"temperature,optional"`
|
||
}
|
||
|
||
Message {
|
||
Role string `json:"role"`
|
||
Content interface{} `json:"content"`
|
||
}
|
||
|
||
Tool {
|
||
Type string `json:"type"`
|
||
Function ToolFunction `json:"function"`
|
||
}
|
||
|
||
ToolFunction {
|
||
Name string `json:"name"`
|
||
Description string `json:"description"`
|
||
Parameters interface{} `json:"parameters"`
|
||
}
|
||
|
||
Function {
|
||
Name string `json:"name"`
|
||
Description string `json:"description,optional"`
|
||
Parameters interface{} `json:"parameters,optional"`
|
||
}
|
||
|
||
ChatCompletionResponse {
|
||
Id string `json:"id"`
|
||
Object string `json:"object"`
|
||
Created int64 `json:"created"`
|
||
Model string `json:"model"`
|
||
Choices []Choice `json:"choices"`
|
||
Usage Usage `json:"usage"`
|
||
}
|
||
|
||
Choice {
|
||
Index int `json:"index"`
|
||
Message *RespMessage `json:"message,optional"`
|
||
Delta *Delta `json:"delta,optional"`
|
||
FinishReason string `json:"finish_reason"`
|
||
}
|
||
|
||
RespMessage {
|
||
Role string `json:"role"`
|
||
Content string `json:"content,optional"`
|
||
ToolCalls []ToolCall `json:"tool_calls,optional"`
|
||
}
|
||
|
||
Delta struct {
|
||
Role string `json:"role,optional"`
|
||
Content string `json:"content,optional"`
|
||
ReasoningContent string `json:"reasoning_content,optional"`
|
||
ToolCalls []ToolCall `json:"tool_calls,optional"`
|
||
}
|
||
|
||
ToolCall struct {
|
||
Index int `json:"index"`
|
||
Id string `json:"id"`
|
||
Type string `json:"type"`
|
||
Function FunctionCall `json:"function"`
|
||
}
|
||
|
||
FunctionCall struct {
|
||
Name string `json:"name"`
|
||
Arguments string `json:"arguments"`
|
||
}
|
||
|
||
Usage struct {
|
||
PromptTokens int `json:"prompt_tokens"`
|
||
CompletionTokens int `json:"completion_tokens"`
|
||
TotalTokens int `json:"total_tokens"`
|
||
}
|
||
|
||
// Anthropic Messages
|
||
AnthropicRequest {
|
||
Model string `json:"model"`
|
||
Messages []Message `json:"messages"`
|
||
MaxTokens int `json:"max_tokens"`
|
||
Stream bool `json:"stream,optional"`
|
||
System string `json:"system,optional"`
|
||
}
|
||
|
||
AnthropicResponse {
|
||
Id string `json:"id"`
|
||
Type string `json:"type"`
|
||
Role string `json:"role"`
|
||
Content []ContentBlock `json:"content"`
|
||
Model string `json:"model"`
|
||
Usage AnthropicUsage `json:"usage"`
|
||
}
|
||
|
||
ContentBlock {
|
||
Type string `json:"type"`
|
||
Text string `json:"text,optional"`
|
||
}
|
||
|
||
AnthropicUsage struct {
|
||
InputTokens int `json:"input_tokens"`
|
||
OutputTokens int `json:"output_tokens"`
|
||
}
|
||
)
|
||
|
||
// ============ Routes ============
|
||
|
||
@server(
|
||
prefix: /v1
|
||
group: chat
|
||
)
|
||
service chat-api {
|
||
@doc("Health check")
|
||
@handler Health
|
||
get /health returns (HealthResponse)
|
||
|
||
@doc("List available models")
|
||
@handler Models
|
||
get /v1/models returns (ModelsResponse)
|
||
|
||
@doc("Chat completions (OpenAI compatible)")
|
||
@handler ChatCompletions
|
||
post /v1/chat/completions (ChatCompletionRequest)
|
||
|
||
@doc("Anthropic messages")
|
||
@handler AnthropicMessages
|
||
post /v1/messages (AnthropicRequest)
|
||
}
|
||
```
|
||
|
||
#### Step 1.3: 生成代碼骨架
|
||
|
||
```bash
|
||
goctl api go -api api/chat.api -dir . --style go_zero
|
||
```
|
||
|
||
#### Step 1.4: 建立 `etc/chat.yaml`
|
||
|
||
```yaml
|
||
Name: chat-api
|
||
Host: ${CURSOR_BRIDGE_HOST:0.0.0.0}
|
||
Port: ${CURSOR_BRIDGE_PORT:8080}
|
||
|
||
# API Key 驗證（可選）
|
||
Auth:
|
||
AccessSecret: ${CURSOR_API_KEY:}
|
||
AccessExpire: 86400
|
||
|
||
# Cursor 配置
|
||
AgentBin: ${CURSOR_AGENT_BIN:cursor-agent}
|
||
DefaultModel: ${CURSOR_DEFAULT_MODEL:claude-3.5-sonnet}
|
||
Provider: ${CURSOR_PROVIDER:cursor}
|
||
|
||
# 超時設定
|
||
TimeoutMs: ${CURSOR_TIMEOUT_MS:300000}
|
||
|
||
# 多帳號池
|
||
ConfigDirs:
|
||
- ${HOME}/.cursor-api-proxy/accounts/default
|
||
MultiPort: false
|
||
|
||
# TLS
|
||
TLSCertPath: ${CURSOR_TLS_CERT_PATH:}
|
||
TLSKeyPath: ${CURSOR_TLS_KEY_PATH:}
|
||
|
||
# 日誌
|
||
SessionsLogPath: ${CURSOR_SESSIONS_LOG_PATH:}
|
||
Verbose: ${CURSOR_VERBOSE:false}
|
||
|
||
# Gemini 設定
|
||
GeminiAccountDir: ${GEMINI_ACCOUNT_DIR:}
|
||
GeminiBrowserVisible: ${GEMINI_BROWSER_VISIBLE:false}
|
||
GeminiMaxSessions: ${GEMINI_MAX_SESSIONS:10}
|
||
|
||
# 工作區設定
|
||
Workspace: ${CURSOR_WORKSPACE:}
|
||
ChatOnlyWorkspace: ${CURSOR_CHAT_ONLY_WORKSPACE:true}
|
||
WinCmdlineMax: ${CURSOR_WIN_CMDLINE_MAX:32768}
|
||
|
||
# Agent 設定
|
||
Force: ${CURSOR_FORCE:false}
|
||
ApproveMcps: ${CURSOR_APPROVE_MCPS:false}
|
||
MaxMode: ${CURSOR_MAX_MODE:false}
|
||
StrictModel: ${CURSOR_STRICT_MODEL:true}
|
||
```
|
||
|
||
#### Step 1.5: 移動生成的檔案
|
||
|
||
```bash
|
||
# goctl 生成 chat.go 到根目錄，需移動到 cmd/
|
||
mkdir -p cmd/chat
|
||
mv chat.go cmd/chat/chat.go
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 2: Domain 層建立
|
||
|
||
**目標**：建立 `pkg/domain/` 目錄結構
|
||
|
||
#### Step 2.1: 建立實體
|
||
|
||
```bash
|
||
mkdir -p pkg/domain/entity
|
||
```
|
||
|
||
**檔案對照表：**
|
||
|
||
| 新檔案 | 來源 |
|
||
|--------|------|
|
||
| `pkg/domain/entity/message.go` | `internal/apitypes/types.go` |
|
||
| `pkg/domain/entity/chunk.go` | `internal/apitypes/types.go` (StreamChunk) |
|
||
| `pkg/domain/entity/account.go` | `internal/pool/pool.go` (AccountStat) |
|
||
| `pkg/domain/entity/config.go` | `internal/config/config.go` (部分) |
|
||
|
||
#### Step 2.2: 建立倉儲介面
|
||
|
||
```bash
|
||
mkdir -p pkg/domain/repository
|
||
```
|
||
|
||
**檔案：**
|
||
|
||
| 新檔案 | 說明 |
|
||
|--------|------|
|
||
| `pkg/domain/repository/account.go` | AccountPool interface (從 pool.go 抽取) |
|
||
| `pkg/domain/repository/provider.go` | Provider interface (從 providers/factory.go 抽取) |
|
||
|
||
#### Step 2.3: 建立用例介面
|
||
|
||
```bash
|
||
mkdir -p pkg/domain/usecase
|
||
```
|
||
|
||
**檔案：**
|
||
|
||
| 新檔案 | 說明 |
|
||
|--------|------|
|
||
| `pkg/domain/usecase/chat.go` | ChatUsecase interface |
|
||
| `pkg/domain/usecase/agent.go` | AgentRunner interface |
|
||
|
||
#### Step 2.4: 建立常數
|
||
|
||
```bash
|
||
mkdir -p pkg/domain/const
|
||
```
|
||
|
||
**檔案：**
|
||
|
||
| 新檔案 | 來源 |
|
||
|--------|------|
|
||
| `pkg/domain/const/models.go` | `internal/models/cursormap.go` |
|
||
| `pkg/domain/const/errors.go` | 新增錯誤定義 |
|
||
|
||
---
|
||
|
||
### Phase 3: Infrastructure 層建立
|
||
|
||
**目標**：建立 `pkg/infrastructure/` 基礎設施層
|
||
|
||
#### Step 3.1: 建立目錄結構
|
||
|
||
```bash
|
||
mkdir -p pkg/infrastructure/{process,parser,httputil,logger,env,workspace,winlimit}
|
||
```
|
||
|
||
#### Step 3.2: 遷移基礎設施模組
|
||
|
||
| 原始 | 目標 |
|
||
|------|------|
|
||
| `internal/process/process.go` | `pkg/infrastructure/process/runner.go` |
|
||
| `internal/process/kill_unix.go` | `pkg/infrastructure/process/kill_unix.go` |
|
||
| `internal/process/kill_windows.go` | `pkg/infrastructure/process/kill_windows.go` |
|
||
| `internal/parser/stream.go` | `pkg/infrastructure/parser/stream.go` |
|
||
| `internal/httputil/httputil.go` | `pkg/infrastructure/httputil/httputil.go` |
|
||
| `internal/logger/logger.go` | `pkg/infrastructure/logger/logger.go` |
|
||
| `internal/env/env.go` | `pkg/infrastructure/env/env.go` |
|
||
| `internal/workspace/workspace.go` | `pkg/infrastructure/workspace/workspace.go` |
|
||
| `internal/winlimit/winlimit.go` | `pkg/infrastructure/winlimit/winlimit.go` |
|
||
|
||
---
|
||
|
||
### Phase 4: Repository 層實作
|
||
|
||
**目標**：實作 `pkg/repository/`
|
||
|
||
#### Step 4.1: 建立目錄
|
||
|
||
```bash
|
||
mkdir -p pkg/repository
|
||
```
|
||
|
||
#### Step 4.2: 遷移檔案
|
||
|
||
| 原始 | 目標 |
|
||
|------|------|
|
||
| `internal/pool/pool.go` | `pkg/repository/account.go` (AccountPool 實作) |
|
||
| `internal/providers/factory.go` | `pkg/repository/provider.go` (Provider 工廠) |
|
||
|
||
---
|
||
|
||
### Phase 5: Provider 層建立
|
||
|
||
**目標**：遷移 Provider 實作
|
||
|
||
#### Step 5.1: 建立目錄
|
||
|
||
```bash
|
||
mkdir -p pkg/provider/cursor pkg/provider/geminiweb
|
||
```
|
||
|
||
#### Step 5.2: 遷移檔案
|
||
|
||
| 原始 | 目標 |
|
||
|------|------|
|
||
| `internal/providers/cursor/provider.go` | `pkg/provider/cursor/provider.go` |
|
||
| `internal/providers/geminiweb/provider.go` | `pkg/provider/geminiweb/provider.go` |
|
||
| `internal/providers/geminiweb/browser.go` | `pkg/provider/geminiweb/browser.go` |
|
||
| `internal/providers/geminiweb/pool.go` | `pkg/provider/geminiweb/pool.go` |
|
||
| `internal/providers/geminiweb/browser_manager.go` | `pkg/provider/geminiweb/browser_manager.go` |
|
||
| `internal/providers/geminiweb/page.go` | `pkg/provider/geminiweb/page.go` |
|
||
| `internal/providers/geminiweb/playwright_provider.go` | `pkg/provider/geminiweb/playwright_provider.go` |
|
||
|
||
---
|
||
|
||
### Phase 6: Usecase 層建立
|
||
|
||
**目標**：實作業務邏輯層
|
||
|
||
#### Step 6.1: 建立目錄
|
||
|
||
```bash
|
||
mkdir -p pkg/usecase
|
||
```
|
||
|
||
#### Step 6.2: 建立檔案
|
||
|
||
| 新檔案 | 說明 | 來源 |
|
||
|--------|------|------|
|
||
| `pkg/usecase/chat.go` | 核心聊天邏輯 | 從 handlers/chat.go 抽取 |
|
||
| `pkg/usecase/agent.go` | Agent 執行邏輯 | `internal/agent/runner.go` |
|
||
| `pkg/usecase/sanitizer.go` | 消息清理 | `internal/sanitize/sanitize.go` |
|
||
| `pkg/usecase/toolcall.go` | Tool call 處理 | `internal/toolcall/toolcall.go` |
|
||
|
||
#### Step 6.3: Agent 相關檔案遷移
|
||
|
||
| 原始 | 目標 |
|
||
|------|------|
|
||
| `internal/agent/runner.go` | `pkg/usecase/runner.go` |
|
||
| `internal/agent/token.go` | `pkg/usecase/token.go` |
|
||
| `internal/agent/cmdargs.go` | `pkg/usecase/cmdargs.go` |
|
||
| `internal/agent/maxmode.go` | `pkg/usecase/maxmode.go` |
|
||
|
||
---
|
||
|
||
### Phase 7: Adapter 層建立
|
||
|
||
**目標**：API 格式轉換器
|
||
|
||
#### Step 7.1: 建立目錄
|
||
|
||
```bash
|
||
mkdir -p pkg/adapter/openai pkg/adapter/anthropic
|
||
```
|
||
|
||
#### Step 7.2: 遷移檔案
|
||
|
||
| 原始 | 目標 |
|
||
|------|------|
|
||
| `internal/openai/*.go` | `pkg/adapter/openai/*.go` |
|
||
| `internal/anthropic/*.go` | `pkg/adapter/anthropic/*.go` |
|
||
|
||
---
|
||
|
||
### Phase 8: Internal 層重組
|
||
|
||
**目標**：建立 go-zero 框架層
|
||
|
||
#### Step 8.1: 更新 Config
|
||
|
||
修改 `internal/config/config.go` 使用 go-zero 的 `rest.RestConf`：
|
||
|
||
```go
|
||
package config
|
||
|
||
import "github.com/zeromicro/go-zero/rest"
|
||
|
||
type Config struct {
|
||
rest.RestConf
|
||
|
||
// Cursor 配置
|
||
AgentBin string
|
||
DefaultModel string
|
||
Provider string
|
||
TimeoutMs int
|
||
|
||
// 多帳號池
|
||
ConfigDirs []string
|
||
MultiPort bool
|
||
|
||
// TLS
|
||
TLSCertPath string
|
||
TLSKeyPath string
|
||
|
||
// 日誌
|
||
SessionsLogPath string
|
||
Verbose bool
|
||
|
||
// Gemini
|
||
GeminiAccountDir string
|
||
GeminiBrowserVisible bool
|
||
GeminiMaxSessions int
|
||
|
||
// 工作區
|
||
Workspace string
|
||
ChatOnlyWorkspace bool
|
||
WinCmdlineMax int
|
||
|
||
// Agent
|
||
Force bool
|
||
ApproveMcps bool
|
||
MaxMode bool
|
||
StrictModel bool
|
||
}
|
||
```
|
||
|
||
#### Step 8.2: 建立 ServiceContext
|
||
|
||
```bash
|
||
mkdir -p internal/svc
|
||
```
|
||
|
||
建立 `internal/svc/servicecontext.go`：
|
||
|
||
```go
|
||
package svc
|
||
|
||
import (
|
||
"cursor-api-proxy/internal/config"
|
||
"cursor-api-proxy/pkg/domain/repository"
|
||
"cursor-api-proxy/pkg/provider"
|
||
"cursor-api-proxy/pkg/repository"
|
||
"cursor-api-proxy/pkg/usecase"
|
||
)
|
||
|
||
type ServiceContext struct {
|
||
Config config.Config
|
||
|
||
// Domain
|
||
AccountPool repository.AccountPool
|
||
ChatUsecase usecase.ChatUsecase
|
||
|
||
// Provider
|
||
Provider repository.Provider
|
||
}
|
||
|
||
func NewServiceContext(c config.Config) *ServiceContext {
|
||
accountPool := repository.NewAccountPool(c.ConfigDirs)
|
||
prov := provider.NewProvider(c)
|
||
chatUsecase := usecase.NewChatUsecase(accountPool, prov, c)
|
||
|
||
return &ServiceContext{
|
||
Config: c,
|
||
AccountPool: accountPool,
|
||
ChatUsecase: chatUsecase,
|
||
Provider: prov,
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Step 8.3: 建立 Logic 層
|
||
|
||
```bash
|
||
mkdir -p internal/logic
|
||
```
|
||
|
||
**SSE 自訂 Handler 說明：**
|
||
|
||
由於 go-zero 標準 handler 回傳 JSON，但專案需要 SSE streaming，所以 Logic 層需要自訂處理：
|
||
|
||
```go
|
||
// internal/logic/chatcompletionlogic.go
|
||
func (l *ChatCompletionLogic) ChatCompletion(req *types.ChatCompletionRequest) error {
|
||
// 設定 SSE headers
|
||
l.w.Header().Set("Content-Type", "text/event-stream")
|
||
l.w.Header().Set("Cache-Control", "no-cache")
|
||
l.w.Header().Set("Connection", "keep-alive")
|
||
|
||
flusher, ok := l.w.(http.Flusher)
|
||
if !ok {
|
||
return errors.New("streaming not supported")
|
||
}
|
||
|
||
// 委託給 usecase 處理串流
|
||
err := l.svcCtx.ChatUsecase.Stream(l.ctx, usecase.ChatInput{
|
||
Model: req.Model,
|
||
Messages: l.convertMessages(req.Messages),
|
||
Tools: l.convertTools(req.Tools),
|
||
Stream: req.Stream,
|
||
}, func(chunk entity.StreamChunk) {
|
||
l.writeChunk(chunk)
|
||
flusher.Flush()
|
||
})
|
||
|
||
return err
|
||
}
|
||
```
|
||
|
||
#### Step 8.4: 建立 Handler 層
|
||
|
||
```bash
|
||
mkdir -p internal/handler
|
||
```
|
||
|
||
**自訂 Handler 處理 SSE：**
|
||
|
||
由於需要 SSE streaming，Handler 需要：
|
||
1. 不使用 goctl 的標準模板
|
||
2. 自訂 `http.HandlerFunc` 處理 SSE
|
||
3. 在 `routes.go` 中註冊自訂 handler
|
||
|
||
#### Step 8.5: 建立 Middleware
|
||
|
||
```bash
|
||
mkdir -p internal/middleware
|
||
```
|
||
|
||
| 新檔案 | 說明 |
|
||
|--------|------|
|
||
| `internal/middleware/auth.go` | API Key 驗證 |
|
||
| `internal/middleware/recovery.go` | Panic 恢復（從 router.go 抽取） |
|
||
|
||
---
|
||
|
||
### Phase 9: CLI 工具遷移
|
||
|
||
**目標**：保留 CLI 工具在 `cmd/cli/`
|
||
|
||
#### Step 9.1: 建立目錄
|
||
|
||
```bash
|
||
mkdir -p cmd/cli
|
||
```
|
||
|
||
#### Step 9.2: 遷移檔案
|
||
|
||
| 原始 | 目標 |
|
||
|------|------|
|
||
| `cmd/args.go` | `cmd/cli/args.go` |
|
||
| `cmd/login.go` | `cmd/cli/login.go` |
|
||
| `cmd/accounts.go` | `cmd/cli/accounts.go` |
|
||
| `cmd/resethwid.go` | `cmd/cli/resethwid.go` |
|
||
| `cmd/usage.go` | `cmd/cli/usage.go` |
|
||
| `cmd/sqlite.go` | `cmd/cli/sqlite.go` |
|
||
| `cmd/gemini-login/main.go` | `cmd/cli/gemini_login.go` |
|
||
|
||
---
|
||
|
||
### Phase 10: 清理與測試
|
||
|
||
#### Step 10.1: 移除舊目錄
|
||
|
||
確認所有遷移完成後：
|
||
|
||
```bash
|
||
# 移除舊的 internal 目錄（保留已遷移的）
|
||
rm -rf internal/router
|
||
rm -rf internal/handlers
|
||
rm -rf internal/providers
|
||
rm -rf internal/apitypes
|
||
rm -rf internal/pool
|
||
rm -rf internal/agent
|
||
rm -rf internal/parser
|
||
rm -rf internal/toolcall
|
||
rm -rf internal/sanitize
|
||
rm -rf internal/openai
|
||
rm -rf internal/anthropic
|
||
rm -rf internal/process
|
||
rm -rf internal/models
|
||
rm -rf internal/workspace
|
||
rm -rf internal/winlimit
|
||
rm -rf internal/httputil
|
||
rm -rf internal/logger
|
||
rm -rf internal/env
|
||
rm -rf internal/server
|
||
|
||
# 移除舊的 main.go
|
||
rm main.go
|
||
|
||
# 移除舊的 cmd 目錄（已遷移到 cmd/cli）
|
||
rm -rf cmd/gemini-login
|
||
```
|
||
|
||
#### Step 10.2: 更新 import 路徑
|
||
|
||
```bash
|
||
# 批量更新 import 路徑
|
||
# internal/ → pkg/ (domain 相關)
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/apitypes|cursor-api-proxy/pkg/domain/entity|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/pool|cursor-api-proxy/pkg/repository|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/agent|cursor-api-proxy/pkg/usecase|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/providers|cursor-api-proxy/pkg/provider|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/parser|cursor-api-proxy/pkg/infrastructure/parser|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/toolcall|cursor-api-proxy/pkg/usecase|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/sanitize|cursor-api-proxy/pkg/usecase|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/openai|cursor-api-proxy/pkg/adapter/openai|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/anthropic|cursor-api-proxy/pkg/adapter/anthropic|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/process|cursor-api-proxy/pkg/infrastructure/process|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/models|cursor-api-proxy/pkg/domain/const|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/workspace|cursor-api-proxy/pkg/infrastructure/workspace|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/winlimit|cursor-api-proxy/pkg/infrastructure/winlimit|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/httputil|cursor-api-proxy/pkg/infrastructure/httputil|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/logger|cursor-api-proxy/pkg/infrastructure/logger|g' {} \;
|
||
find . -name "*.go" -exec sed -i '' 's|cursor-api-proxy/internal/env|cursor-api-proxy/pkg/infrastructure/env|g' {} \;
|
||
```
|
||
|
||
#### Step 10.3: 測試
|
||
|
||
```bash
|
||
# 單元測試
|
||
go test ./pkg/domain/... -v
|
||
go test ./pkg/usecase/... -v
|
||
go test ./pkg/repository/... -v
|
||
|
||
# 整合測試
|
||
go test ./internal/... -v
|
||
|
||
# 建置測試
|
||
go build ./cmd/chat
|
||
go build ./cmd/cli
|
||
|
||
# 功能測試
|
||
make env
|
||
./cursor-api-proxy -f etc/chat.yaml &
|
||
curl http://localhost:8080/health
|
||
curl http://localhost:8080/v1/models
|
||
```
|
||
|
||
---
|
||
|
||
## 四、漸進式遷移順序
|
||
|
||
### 每日執行計劃
|
||
|
||
| 階段 | 任務 | 預估時間 | 依賴 |
|
||
|------|------|---------|------|
|
||
| Day 1 | Phase 1: API 定義 | 2-3 小時 | 無 |
|
||
| Day 2 | Phase 2: Domain 層 | 2-3 小時 | Phase 1 |
|
||
| Day 3 | Phase 3: Infrastructure 層 | 2-3 小時 | Phase 2 |
|
||
| Day 4 | Phase 4: Repository 層 | 2-3 小時 | Phase 3 |
|
||
| Day 5 | Phase 5: Provider 層 | 2-3 小時 | Phase 4 |
|
||
| Day 6 | Phase 6: Usecase 層 | 3-4 小時 | Phase 5 |
|
||
| Day 7 | Phase 7: Adapter 層 | 2 小時 | Phase 6 |
|
||
| Day 8 | Phase 8: Internal 層 | 4-5 小時 | Phase 7 |
|
||
| Day 9 | Phase 9: CLI 工具 | 1-2 小時 | Phase 8 |
|
||
| Day 10 | Phase 10: 清理與測試 | 3-4 小時 | Phase 9 |
|
||
|
||
### 漸進式測試策略
|
||
|
||
每個 Phase 完成後執行：
|
||
|
||
1. **單元測試**：確保新模組測試通過
|
||
2. **編譯測試**：確保代碼可編譯
|
||
3. **功能測試**：確保核心功能正常
|
||
|
||
```bash
|
||
# 每日測試腳本
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
echo "=== Running unit tests ==="
|
||
go test ./pkg/... -v
|
||
|
||
echo "=== Building ==="
|
||
go build ./cmd/chat
|
||
go build ./cmd/cli
|
||
|
||
echo "=== Starting server ==="
|
||
./cursor-api-proxy -f etc/chat.yaml &
|
||
PID=$!
|
||
sleep 2
|
||
|
||
echo "=== Running functional tests ==="
|
||
curl -s http://localhost:8080/health | jq .
|
||
curl -s http://localhost:8080/v1/models | jq .
|
||
|
||
echo "=== Cleaning up ==="
|
||
kill $PID
|
||
|
||
echo "=== All tests passed ==="
|
||
```
|
||
|
||
---
|
||
|
||
## 五、回歸測試清單
|
||
|
||
### 功能測試
|
||
|
||
- [ ] Health check: `GET /health`
|
||
- [ ] Models list: `GET /v1/models`
|
||
- [ ] Chat completions (非串流): `POST /v1/chat/completions` with `stream: false`
|
||
- [ ] Chat completions (串流): `POST /v1/chat/completions` with `stream: true`
|
||
- [ ] Anthropic messages: `POST /v1/messages`
|
||
- [ ] Gemini chat completions: `POST /v1/chat/completions` (Provider=gemini-web)
|
||
- [ ] Tool calls 處理
|
||
- [ ] Rate limit 處理
|
||
- [ ] Multi-account 輪替
|
||
- [ ] API Key 驗證
|
||
- [ ] TLS/HTTPS 支援
|
||
|
||
### CLI 工具測試
|
||
|
||
- [ ] `login` 命令
|
||
- [ ] `accounts` 命令
|
||
- [ ] `resethwid` 命令
|
||
- [ ] `usage` 命令
|
||
- [ ] `gemini-login` 命令
|
||
|
||
### 效能測試
|
||
|
||
- [ ] SSE streaming latency
|
||
- [ ] Concurrent requests (10, 50, 100)
|
||
- [ ] Memory usage baseline
|
||
- [ ] Long-running stability
|
||
|
||
---
|
||
|
||
## 六、風險與注意事項
|
||
|
||
### 高風險項目
|
||
|
||
| 風險 | 描述 | 緩解措施 |
|
||
|------|------|---------|
|
||
| SSE Streaming | go-zero 標準 handler 不支援 SSE | 自訂 handler，在 Logic 層處理 SSE |
|
||
| Context 傳遞 | 需確保 context 正確傳遞到 usecase 層 | 使用 context.Context 作為參數傳遞 |
|
||
| 全局變數 | pool.go 的 global pool 需改為 DI | 使用 ServiceContext 注入 |
|
||
| 環境變數 | 需從 `CURSOR_*` 遷移到 go-zero 配置 | 保持環境變數支援，使用 `${VAR:default}` 語法 |
|
||
|
||
### 注意事項
|
||
|
||
1. **保持向後相容**：API 端點和行為必須與現有版本一致
|
||
2. **環境變數相容**：保持現有環境變數名稱
|
||
3. **Makefile 更新**：更新建置命令
|
||
4. **日誌格式**：保持現有日誌格式以便分析工具相容
|
||
|
||
---
|
||
|
||
## 七、Makefile 更新
|
||
|
||
需要新增 go-zero 相關命令：
|
||
|
||
```makefile
|
||
# go-zero 代碼生成
|
||
.PHONY: api
|
||
api:
|
||
goctl api go -api api/chat.api -dir . --style go_zero
|
||
|
||
.PHONY: api-doc
|
||
api-doc:
|
||
goctl api doc -api api/chat.api -dir docs/
|
||
|
||
# 格式化
|
||
.PHONY: fmt
|
||
fmt:
|
||
go fmt ./...
|
||
|
||
# 測試
|
||
.PHONY: test
|
||
test:
|
||
go test ./... -v -race
|
||
|
||
# 建置
|
||
.PHONY: build
|
||
build:
|
||
go build -o bin/chat-api cmd/chat/chat.go
|
||
|
||
# 運行
|
||
.PHONY: run
|
||
run:
|
||
./bin/chat-api -f etc/chat.yaml
|
||
```
|
||
|
||
---
|
||
|
||
## 八、參考資源
|
||
|
||
- [go-zero 官方文檔](https://go-zero.dev/)
|
||
- [go-zero API 定義](https://go-zero.dev/docs/tutorial/api/)
|
||
- [go-zero 最佳實踐](https://go-zero.dev/docs/tutorials/)
|
||
- [zero-skills](https://github.com/zeromicro/zero-skills)
|
||
- [ai-context](https://github.com/zeromicro/ai-context)
|
||
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/33/the-clean-architecture.html)
|
||
|
||
---
|
||
|
||
## 九、附錄：檔案遷移對照表
|
||
|
||
### 完整檔案對照表
|
||
|
||
| 原始 | 目標 | 說明 |
|
||
|------|------|------|
|
||
| `main.go` | `cmd/chat/chat.go` | HTTP 服務入口 |
|
||
| `cmd/args.go` | `cmd/cli/args.go` | CLI 參數 |
|
||
| `cmd/login.go` | `cmd/cli/login.go` | CLI login |
|
||
| `cmd/accounts.go` | `cmd/cli/accounts.go` | CLI accounts |
|
||
| `cmd/resethwid.go` | `cmd/cli/resethwid.go` | CLI resethwid |
|
||
| `cmd/usage.go` | `cmd/cli/usage.go` | CLI usage |
|
||
| `cmd/sqlite.go` | `cmd/cli/sqlite.go` | SQLite 操作 |
|
||
| `cmd/gemini-login/main.go` | `cmd/cli/gemini_login.go` | Gemini CLI |
|
||
| `internal/apitypes/types.go` | `pkg/domain/entity/message.go` | Message 實體 |
|
||
| `internal/pool/pool.go` | `pkg/repository/account.go` | AccountPool 實作 |
|
||
| `internal/agent/runner.go` | `pkg/usecase/runner.go` | Agent 執行 |
|
||
| `internal/agent/token.go` | `pkg/usecase/token.go` | Token 處理 |
|
||
| `internal/agent/cmdargs.go` | `pkg/usecase/cmdargs.go` | 命令參數 |
|
||
| `internal/agent/maxmode.go` | `pkg/usecase/maxmode.go` | Max mode |
|
||
| `internal/providers/factory.go` | `pkg/repository/provider.go` | Provider 工廠 |
|
||
| `internal/providers/cursor/provider.go` | `pkg/provider/cursor/provider.go` | Cursor provider |
|
||
| `internal/providers/geminiweb/*.go` | `pkg/provider/geminiweb/*.go` | Gemini provider |
|
||
| `internal/parser/stream.go` | `pkg/infrastructure/parser/stream.go` | SSE parsing |
|
||
| `internal/toolcall/toolcall.go` | `pkg/usecase/toolcall.go` | Tool call |
|
||
| `internal/sanitize/sanitize.go` | `pkg/usecase/sanitize.go` | 消息清理 |
|
||
| `internal/openai/*.go` | `pkg/adapter/openai/*.go` | OpenAI 格式 |
|
||
| `internal/anthropic/*.go` | `pkg/adapter/anthropic/*.go` | Anthropic 格式 |
|
||
| `internal/process/process.go` | `pkg/infrastructure/process/runner.go` | 進程管理 |
|
||
| `internal/process/kill_*.go` | `pkg/infrastructure/process/kill_*.go` | Kill 實作 |
|
||
| `internal/models/cursormap.go` | `pkg/domain/const/models.go` | Model 映射 |
|
||
| `internal/workspace/workspace.go` | `pkg/infrastructure/workspace/workspace.go` | 工作區 |
|
||
| `internal/winlimit/winlimit.go` | `pkg/infrastructure/winlimit/winlimit.go` | Win limit |
|
||
| `internal/httputil/httputil.go` | `pkg/infrastructure/httputil/httputil.go` | HTTP 工具 |
|
||
| `internal/logger/logger.go` | `pkg/infrastructure/logger/logger.go` | 日誌 |
|
||
| `internal/env/env.go` | `pkg/infrastructure/env/env.go` | 環境變數 |
|
||
| `internal/config/config.go` | `internal/config/config.go` | 配置（使用 go-zero Config） |
|
||
| `internal/router/router.go` | `internal/handler/routes.go` | 路由（重寫） |
|
||
| `internal/handlers/*.go` | `internal/logic/*.go` | 業務邏輯 |
|
||
|
||
---
|
||
|
||
**文件版本**：v1.0
|
||
**建立日期**：2026-04-03
|
||
**最後更新**：2026-04-03 |