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

## 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 支援的話可以加）