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

6.9 KiB
Raw Blame History

Research Inputs

N/A。這是個人工具，不需要市場研究。

Problem

我同時使用多個 CLI AI 工具（Hermes Agent、OpenCode、Claude Code），這些工具都支援自訂 API base URL 和 model。我的公司有 Cursor 帳號，透過 agent login 已在本機完成認證，可以使用 Cursor 提供的多種模型。

目前的問題是：每支 CLI 工具都需要自己買 API key 或設定 provider，但我已經有 Cursor 帳號的額度可以用。我需要一個轉接器，讓這些 CLI 工具能透過 Cursor CLI 的 headless 模式來使用 Cursor 的模型，省去額外的 API 費用。

Goals

  • 本機跑一個 HTTP server，提供 OpenAI-compatible API（/v1/chat/completions）
  • 收到請求後，spawn Cursor CLI 的 agent 子程序來執行
  • 將 Cursor CLI 的 streaming JSON 輸出轉換成 OpenAI SSE 格式回傳
  • 支援多種 Cursor 模型的選擇
  • 零額外認證設定 — 直接使用本機已有的 Cursor 登入狀態

Non Goals

  • 不支援非 OpenAI format 的 CLI 工具
  • 不做 API key 管理或多用戶認證
  • 不做計量、追蹤、計費功能
  • 不做模型負載平衡或 failover
  • 不代理 Cursor IDE 的功能，只代理 headless CLI 模式

Scope

本機 personal proxy server，一個使用者，本機部署。

In Scope

  • OpenAI-compatible API（/v1/chat/completions、/v1/models）
  • SSE streaming response
  • 模型選擇（透過 --model 參數傳給 Cursor CLI）
  • 簡單的 YAML config 檔設定
  • 錯誤處理和 CLI 子程序生命週期管理
  • health check endpoint

Out of Scope

  • 非 OpenAI format 支援
  • 多用戶 / API key 管理
  • 計量追蹤
  • GUI 介面
  • Docker 部署

Success Metrics

  • Hermes Agent、OpenCode、Claude Code 都能透過設定 base URL 指向此 proxy 來使用 Cursor 模型
  • streaming 回應的延遲 < 2 秒（不含模型思考時間）
  • proxy 啟動後零設定即可使用（只需改 CLI 工具的 config）

User Stories

  1. 作為使用者，我想啟動 proxy server，這樣我的 CLI 工具就能連到它
  2. 作為使用者，我想在 Hermes Agent 裡設定 base_url = http://localhost:8976，這樣就能用 Cursor 的模型
  3. 作為使用者，我想在 CLI 工具裡指定 model = claude-sonnet-4-20250514，proxy 會傳給 Cursor CLI
  4. 作為使用者，我想看到模型的思考過程即時串流到終端機上
  5. 作為使用者，我想透過 /v1/models 查看可用的模型列表
  6. 作為使用者，我想透過 config 檔設定 proxy 的 port 和其他選項

Functional Requirements

FR1: OpenAI-Compatible API

  • 支援 POST /v1/chat/completions
  • 接受 OpenAI 格式的 request body（model、messages、stream）
  • 當 stream: true 時，回傳 SSE 格式的 data: {...}\n\n chunks
  • 當 stream: false 時，回傳完整的 JSON response

FR2: Cursor CLI Integration

  • 收到請求後，組合 prompt 從 messages 陣列
  • spawn agent -p "{prompt}" --model "{model}" --output-format stream-json 子程序
  • 讀取子程序的 stdout streaming JSON 輸出
  • 管理子程序生命週期（啟動、執行、結束、超時 kill）

FR3: Streaming Response Conversion

  • 將 Cursor CLI 的 stream-json 輸出轉換成 OpenAI SSE 格式
  • 每個 SSE chunk 需包含 id、object: "chat.completion.chunk"、choices[0].delta.content
  • 最後一個 chunk 需包含 finish_reason: "stop"

FR4: Model Listing

  • 支援 GET /v1/models，回傳可用模型列表
  • 模型列表從 Cursor CLI 取得（agent --list-models 或 config 定義）

FR5: Configuration

  • YAML config 檔（預設 ~/.cursor-adapter/config.yaml）
  • 可設定：port、cursor_cli_path、default_model、timeout

FR6: Error Handling

  • Cursor CLI 超時（可設定，預設 5 分鐘）→ 回傳 504
  • Cursor CLI 錯誤 → 回傳 500 + 錯誤訊息
  • 無效的 request body → 回傳 400
  • model 不存在 → 回傳 404

Acceptance Criteria

AC1: Basic Chat Completion

Given proxy 已啟動在 port 8976，When 我用 curl 發送 POST /v1/chat/completions 帶上 {"model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "hello"}], "stream": true}，Then 收到 SSE streaming response，且內容為 Cursor CLI 的回應轉換成的 OpenAI 格式。

AC2: Streaming Display

Given CLI 工具連到 proxy 並發送 streaming 請求，When 模型正在生成回應，Then CLI 工具的終端機上即時顯示文字內容（不需要等完整回應）。

AC3: Model Selection

Given proxy 已啟動，When 請求中指定 model: "gpt-5.2"，Then proxy spawn Cursor CLI 時使用 --model gpt-5.2。

AC4: Health Check

Given proxy 已啟動，When 發送 GET /health，Then 回傳 {"status": "ok", "cursor_cli": "available"}。

AC5: Model Listing

Given proxy 已啟動，When 發送 GET /v1/models，Then 回傳 Cursor 可用的模型列表，格式符合 OpenAI models API。

Edge Cases

  • Cursor CLI 子程序意外崩潰 → proxy 回傳 500，清理資源
  • 請求 timeout（模型思考太久）→ proxy kill 子程序，回傳 504
  • 並發請求 → 每個請求 spawn 獨立的子程序
  • Cursor CLI 未安裝或不在 PATH → proxy 啟動時檢查，啟動失敗時給明確錯誤
  • Cursor CLI 未登入 → proxy 回傳錯誤訊息提示先 agent login
  • messages 陣列為空 → 回傳 400
  • stream: false 時，需要等 Cursor CLI 完整輸出後才回傳

Non Functional Requirements

NFR1: Performance

  • proxy 自身的 overhead < 500ms（不含模型思考時間）
  • streaming 的第一個 token 延遲不超過 Cursor CLI 本身的延遲 + 200ms

NFR2: Reliability

  • 並發請求數 ≤ 5（個人使用）
  • 子程序超時後正確清理，不留 zombie process

NFR3: Usability

  • 一行命令啟動：cursor-adapter 或 cursor-adapter --port 8976
  • config 檔格式簡單，有合理的預設值
  • 啟動時顯示可用模型列表

Risks

Risk Impact Likelihood Mitigation
Cursor CLI output format 變更 High Medium 抽象輸出解析層，方便適配
Cursor CLI 不支援某些模型 Medium Low 啟動時驗證模型可用性
並發子程序過多導致資源耗盡 Medium Low 限制最大並發數
Cursor 的 headless 模式有限制 High Medium 先用 headless 模式測試，必要時 fallback 到 ACP

Assumptions

  • Cursor CLI 已安裝且在 PATH 中
  • Cursor CLI 已透過 agent login 完成認證
  • 使用者的 CLI 工具都支援 OpenAI-compatible API format
  • 使用者只需要 /v1/chat/completions 和 /v1/models 兩個 endpoint

Dependencies

  • Cursor CLI（agent command）
  • Python 3.10+ 或 Node.js 18+（取決於實作語言選擇）

Open Questions

  1. Cursor CLI 的 --output-format stream-json 的確切 JSON schema 是什麼？需要實際跑一次來確認
  2. Cursor CLI 是否支援同時跑多個 headless 實例？
  3. 需要支援 function calling / tool use 嗎？（目前 PRD 不含，但如果 Cursor CLI 支援的話可以加）