2026-04-18 14:08:01 +00:00
|
|
|
|
# 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`
|
2026-04-25 13:18:22 +00:00
|
|
|
|
- `cursor_mode`：`plan`（預設，純大腦＋ `<tool_call>` 翻譯成 caller 端 tool_use）或 `agent`（讓 Cursor CLI 自己拿 host 的檔案／shell 工具直接執行）
|
|
|
|
|
|
- `workspace_root`：絕對路徑；設了之後子行程就跑在這個資料夾，不再用 chat-only temp dir。`agent` 模式下幾乎都要設。Per-request 用 `X-Cursor-Workspace` header 動態覆蓋。
|
|
|
|
|
|
|
|
|
|
|
|
### 兩種典型擺法
|
|
|
|
|
|
|
|
|
|
|
|
1. **大腦模式（預設）**
|
|
|
|
|
|
```yaml
|
|
|
|
|
|
cursor_mode: plan
|
|
|
|
|
|
chat_only_workspace: true
|
|
|
|
|
|
```
|
|
|
|
|
|
Cursor CLI 不執行任何東西。proxy 把 system_prompt 注入腦袋，要它輸出 `<tool_call>{...}</tool_call>`，proxy 再翻成 Anthropic `tool_use` 給 caller（Claude Desktop / Claude Code / opencode）跑。caller 必須有自己的 host MCP（例如 desktop-commander）。
|
|
|
|
|
|
|
|
|
|
|
|
2. **執行者模式**
|
|
|
|
|
|
```yaml
|
|
|
|
|
|
cursor_mode: agent
|
|
|
|
|
|
chat_only_workspace: false
|
|
|
|
|
|
workspace_root: /Users/<you>/Desktop
|
|
|
|
|
|
system_prompt: "" # 移掉「你只是大腦」的口令，讓它正常使用工具
|
|
|
|
|
|
```
|
|
|
|
|
|
Cursor CLI 自己用內建 filesystem/shell 工具直接動 `workspace_root`。caller 不需要任何 MCP，整段在 host 上完成；回到 caller 那邊只有最後的文字結論。
|
2026-04-18 14:08:01 +00:00
|
|
|
|
|
|
|
|
|
|
## 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` 實作。
|
