81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
# 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` 實作。
|