216 lines
7.3 KiB
Markdown
216 lines
7.3 KiB
Markdown
# Plan: Cursor Adapter
|
||
|
||
## Overview
|
||
|
||
用 Go 實作一個本機 OpenAI-compatible proxy，透過 spawn Cursor CLI 的 headless 模式來使用 Cursor 的模型。
|
||
|
||
## Inputs
|
||
|
||
- Architecture: `docs/architecture/2026-04-14-cursor-adapter.md`
|
||
- Code Design: `docs/code-design/2026-04-14-cursor-adapter.md`
|
||
|
||
## Planning Assumptions
|
||
|
||
- Go 1.22+
|
||
- 使用 chi v5 做 HTTP router
|
||
- 使用 cobra 做 CLI
|
||
- 專案目錄：`~/Documents/projects/cursor-adapter/`
|
||
- 先探索 Cursor CLI 輸出格式，再實作轉換邏輯
|
||
|
||
## Task Breakdown
|
||
|
||
### Task P1: Go Module 初始化 + 專案結構
|
||
- Objective: `go mod init`、建立目錄結構、空檔案
|
||
- Inputs Used: Code Design — Project Structure
|
||
- Design References: code-design §Project Structure
|
||
- Dependencies: None
|
||
- Deliverables: go.mod、目錄結構、空的 package files
|
||
- Completion Criteria: `go build` 成功（即使什麼都沒做）
|
||
|
||
### Task P2: 探索 Cursor CLI 輸出格式
|
||
- Objective: 實際跑 `agent -p "hello" --output-format stream-json`，記錄每行 JSON 的結構
|
||
- Inputs Used: PRD — Open Question 1
|
||
- Design References: architecture §Open Questions
|
||
- Dependencies: P1
|
||
- Deliverables: scripts/test_cursor_cli.sh、記錄 Cursor stream-json schema 的文件
|
||
- Completion Criteria: 明確知道每行 JSON 的 type/content 結構
|
||
|
||
### Task P3: Config 模組
|
||
- Objective: internal/config/config.go（YAML 載入、Defaults、驗證）
|
||
- Inputs Used: Code Design — Configuration
|
||
- Design References: code-design §Config struct, §Load()
|
||
- Dependencies: P1
|
||
- Deliverables: internal/config/config.go、internal/config/config_test.go、config.example.yaml
|
||
- Completion Criteria: table-driven test 通過
|
||
|
||
### Task P4: Models（Request/Response Structs）
|
||
- Objective: internal/server/models.go（所有 JSON struct + JSON tags）
|
||
- Inputs Used: Code Design — Domain Models
|
||
- Design References: code-design §Domain Models
|
||
- Dependencies: P1
|
||
- Deliverables: internal/server/models.go
|
||
- Completion Criteria: struct 定義完成，JSON tag 正確
|
||
|
||
### Task P5: SSE Helper
|
||
- Objective: internal/server/sse.go（SSE 格式化、flush helpers）
|
||
- Inputs Used: Architecture — SSE streaming
|
||
- Design References: architecture §API Contract
|
||
- Dependencies: P4
|
||
- Deliverables: internal/server/sse.go
|
||
- Completion Criteria: FormatSSE() / FormatDone() 正確
|
||
|
||
### Task P6: CLI Bridge
|
||
- Objective: internal/bridge/bridge.go（Bridge interface + CLIBridge 實作）
|
||
- Inputs Used: Code Design — Interface Definitions
|
||
- Design References: code-design §Bridge interface, §CLIBridge
|
||
- Dependencies: P2, P3
|
||
- Deliverables: internal/bridge/bridge.go、internal/bridge/bridge_test.go
|
||
- Completion Criteria: Execute() 能 spawn agent、逐行 yield、timeout kill
|
||
|
||
### Task P7: Stream Converter
|
||
- Objective: internal/converter/convert.go（Cursor JSON → OpenAI SSE 轉換）
|
||
- Inputs Used: Code Design — Converter interface
|
||
- Design References: code-design §ToOpenAIChunk(), §ToOpenAIResponse()
|
||
- Dependencies: P2, P4
|
||
- Deliverables: internal/converter/convert.go、internal/converter/convert_test.go
|
||
- Completion Criteria: table-driven test 通過，轉換格式正確
|
||
|
||
### Task P8: HTTP Server + Handlers
|
||
- Objective: internal/server/server.go + handler.go（chi router、3 個 endpoint、error middleware）
|
||
- Inputs Used: Code Design — Layer Architecture
|
||
- Design References: code-design §handler.go, §writeError()
|
||
- Dependencies: P3, P4, P5, P6, P7
|
||
- Deliverables: internal/server/server.go、internal/server/handler.go、internal/server/handler_test.go
|
||
- Completion Criteria: /health、/v1/models、/v1/chat/completions 可回應（用 mock bridge 測試）
|
||
|
||
### Task P9: CLI 入口（main.go）
|
||
- Objective: main.go（cobra command、wiring、啟動 server）
|
||
- Inputs Used: Code Design — Dependency Injection
|
||
- Design References: code-design §main.go wiring
|
||
- Dependencies: P3, P8
|
||
- Deliverables: main.go
|
||
- Completion Criteria: `go build && ./cursor-adapter` 啟動成功
|
||
|
||
### Task P10: 整合測試
|
||
- Objective: 實際用 curl 和 Hermes 測試完整流程
|
||
- Inputs Used: PRD — Acceptance Criteria
|
||
- Design References: architecture §API Contract
|
||
- Dependencies: P9
|
||
- Deliverables: 測試結果記錄
|
||
- Completion Criteria: AC1-AC5 通過
|
||
|
||
### Task P11: README
|
||
- Objective: 安裝、設定、使用方式
|
||
- Inputs Used: PRD, Architecture
|
||
- Dependencies: P10
|
||
- Deliverables: README.md
|
||
- Completion Criteria: 新使用者看著 README 能跑起來
|
||
|
||
## Dependency Graph
|
||
|
||
```mermaid
|
||
graph TD
|
||
P1 --> P2
|
||
P1 --> P3
|
||
P1 --> P4
|
||
P2 --> P6
|
||
P2 --> P7
|
||
P3 --> P6
|
||
P3 --> P9
|
||
P4 --> P5
|
||
P4 --> P7
|
||
P4 --> P8
|
||
P5 --> P8
|
||
P6 --> P8
|
||
P7 --> P8
|
||
P8 --> P9
|
||
P9 --> P10
|
||
P10 --> P11
|
||
```
|
||
|
||
## Execution Order
|
||
|
||
### Phase 1: Foundation（可並行）
|
||
- P1 Go Module 初始化
|
||
- P3 Config 模組
|
||
- P4 Models
|
||
|
||
### Phase 2: Exploration（需 P1）
|
||
- P2 探索 Cursor CLI 輸出格式
|
||
- P5 SSE Helper（需 P4）
|
||
|
||
### Phase 3: Core Logic（需 P2 + Phase 1）
|
||
- P6 CLI Bridge
|
||
- P7 Stream Converter
|
||
|
||
### Phase 4: Integration（需 Phase 3）
|
||
- P8 HTTP Server + Handlers
|
||
- P9 CLI 入口
|
||
|
||
### Phase 5: Validation（需 P9）
|
||
- P10 整合測試
|
||
- P11 README
|
||
|
||
## Milestones
|
||
|
||
### Milestone M1: Foundation Ready
|
||
- Included Tasks: P1, P3, P4
|
||
- Exit Criteria: go.mod 存在、config 可載入、models struct 定義完成
|
||
|
||
### Milestone M2: Core Logic Complete
|
||
- Included Tasks: P2, P5, P6, P7
|
||
- Exit Criteria: CLI Bridge 能 spawn Cursor、converter 轉換正確
|
||
|
||
### Milestone M3: MVP Ready
|
||
- Included Tasks: P8, P9, P10, P11
|
||
- Exit Criteria: `cursor-adapter` 啟動後，curl AC1-AC5 通過
|
||
|
||
## Deliverables
|
||
|
||
| Task | Deliverable | Source Design Reference |
|
||
|------|-------------|------------------------|
|
||
| P1 | go.mod + project structure | code-design §Project Structure |
|
||
| P2 | test script + format docs | architecture §Open Questions |
|
||
| P3 | internal/config/config.go + test | code-design §Configuration |
|
||
| P4 | internal/server/models.go | code-design §Domain Models |
|
||
| P5 | internal/server/sse.go | architecture §SSE |
|
||
| P6 | internal/bridge/bridge.go + test | code-design §Bridge interface |
|
||
| P7 | internal/converter/convert.go + test | code-design §Converter |
|
||
| P8 | server.go + handler.go + test | code-design §Layer Architecture |
|
||
| P9 | main.go | code-design §Dependency Injection |
|
||
| P10 | test results | PRD §Acceptance Criteria |
|
||
| P11 | README.md | — |
|
||
|
||
## Design Traceability
|
||
|
||
| Upstream Design Element | Planned Task(s) |
|
||
|-------------------------|-----------------|
|
||
| Architecture: HTTP Server | P8 |
|
||
| Architecture: CLI Bridge | P6 |
|
||
| Architecture: Stream Converter | P7 |
|
||
| Architecture: SSE | P5 |
|
||
| Architecture: Config | P3 |
|
||
| Architecture: Error Model | P8 |
|
||
| Code Design: Project Structure | P1 |
|
||
| Code Design: Interface — Bridge | P6 |
|
||
| Code Design: Interface — Converter | P7 |
|
||
| Code Design: Domain Models | P4 |
|
||
| Code Design: Configuration | P3 |
|
||
| Code Design: DI — main.go | P9 |
|
||
|
||
## Risks And Sequencing Notes
|
||
|
||
- P2（探索 Cursor CLI 格式）是 critical path — P6 和 P7 依賴此結果
|
||
- P6（CLI Bridge）是最複雜的任務 — goroutine、subprocess、timeout、semaphore
|
||
- 如果 Cursor CLI stream-json 格式複雜，P7 可能需要迭代
|
||
- P10 可能發現 edge case，需要回頭修 P6/P7/P8
|
||
|
||
## Planning Review
|
||
|
||
N/A（首次規劃）。
|
||
|
||
## Open Questions
|
||
|
||
1. Cursor CLI stream-json 的確切格式？（P2 回答）
|
||
2. Cursor CLI 並發限制？（P10 確認）
|