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）

建置與執行

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

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

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

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
• 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. 大腦模式（預設）

   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. 執行者模式

   cursor_mode: agent
   chat_only_workspace: false
   workspace_root: /Users/<you>/Desktop
   system_prompt: ""   # 移掉「你只是大腦」的口令，讓它正常使用工具
   

   Cursor CLI 自己用內建 filesystem/shell 工具直接動 workspace_root。caller 不需要任何 MCP，整段在 host 上完成；回到 caller 那邊只有最後的文字結論。

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 相容

開發與測試

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 實作。