daniel.w
/
opencode-cursor-agent
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 3 Wiki Activity
opencode-cursor-agent/docs/plan/2026-04-14-cursor-adapter.md

7.3 KiB
Raw Blame History

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

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