opencode-cursor-agent/docs/plan/2026-04-14-cursor-adapter.md

# 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 確認）