# cursor-adapter

以 **OpenAI／相容 Chat Completions API** 對外提供服務，後端透過 **Cursor CLI**（預設 `agent`）或選用的 **ACP** 傳輸與 Cursor 互動的本地代理程式。另提供 **Anthropic Messages** 相容端點。

## 需求

- Go **1.26.1**（見 `go.mod`）
- 已安裝並可在 `PATH` 中執行的 **Cursor CLI**（名稱或路徑見設定檔 `cursor_cli_path`）

## 建置與執行

```bash
go build -o cursor-adapter .
./cursor-adapter
```

未指定 `-c`／`--config` 時，會讀取 `~/.cursor-adapter/config.yaml`；若檔案不存在則使用內建預設值。

首次可複製範例後再編輯：

```bash
mkdir -p ~/.cursor-adapter
cp config.example.yaml ~/.cursor-adapter/config.yaml
```

## 命令列參數

| 參數 | 說明 |
|------|------|
| `-c`, `--config` | 設定檔路徑 |
| `-p`, `--port` | 監聽埠（覆寫設定檔） |
| `--debug` | 除錯層級日誌 |
| `--use-acp` | 改用 Cursor ACP 傳輸（預設為 CLI stream-json） |
| `--chat-only-workspace` | 預設 `true`：在暫存工作區並覆寫 `HOME`／`CURSOR_CONFIG_DIR` 等，避免子行程讀取啟動目錄或 `~/.cursor` 規則；設為 `false` 時代理的工作目錄會對 Cursor agent 可見 |

啟動前會檢查 Cursor CLI 是否可用；失敗時程式會退出並顯示錯誤。

## 設定檔（YAML）

欄位與 `config.example.yaml` 對齊，例如：

- `port`：HTTP 服務埠（預設 `8976`）
- `cursor_cli_path`：CLI 可執行檔名或路徑
- `default_model`、`available_models`、`timeout`（秒）、`max_concurrent`
- `use_acp`、`chat_only_workspace`、`log_level`

## HTTP 端點

服務綁定 **127.0.0.1**（僅本機）。路由啟用 CORS（`Access-Control-Allow-Origin: *`），並允許標頭如 `Authorization`、`X-Cursor-Session-ID`、`X-Cursor-Workspace`。

| 方法 | 路徑 | 說明 |
|------|------|------|
| GET | `/health` | 健康檢查 |
| GET | `/v1/models` | 模型列表 |
| POST | `/v1/chat/completions` | OpenAI 相容聊天完成（含串流 SSE） |
| POST | `/v1/messages` | Anthropic Messages 相容 |

## 開發與測試

```bash
go test ./...
```

輔助腳本：`scripts/test_cursor_cli.sh`（驗證本機 Cursor CLI 是否可呼叫）。

## 專案結構（概要）

- `main.go`：CLI 入口、設定與橋接組裝、服務啟動
- `internal/config`：設定載入與驗證
- `internal/server`：HTTP 路由、CORS、OpenAI／Anthropic 處理、SSE、工作階段
- `internal/bridge`：與 Cursor CLI／ACP 的橋接與併發控制
- `internal/converter`：請求／回應與模型對應
- `internal/types`：共用型別與 API 結構
- `internal/workspace`：暫存工作區與隔離行為
- `internal/sanitize`：輸入清理
- `docs/`：計畫、架構、PRD 與 Cursor CLI 格式等文件

## 安全與隱私

建議維持 `chat_only_workspace: true`，除非你有意讓 Cursor agent 存取代理行程的工作目錄與本機 Cursor 設定。詳見 `config.example.yaml` 註解與 `internal/config` 實作。