Terminal Tool
基於 Cursor 官方 Terminal 文件解釋 Agent 執行 shell commands、sandbox、allowlist、平臺要求和 sandbox.json。
Terminal Tool 是 Agent 最有用、也最需要謹慎的能力。官方文件說明，Agent 可以直接在你的 terminal 中執行 shell commands，並在 macOS、Linux、Windows 上用 sandbox（沙箱，限制程序能訪問的檔案和網路範圍）做安全執行。
閱讀目標：讀完本章，你應該能判斷哪些命令可以讓 Agent 執行，哪些必須人工確認，以及 sandbox 失敗時怎麼處理。
1. 預設 sandbox 心智模型
官方 Terminal 文件說明，Agent 預設在 restricted environment 中執行 terminal commands，阻止未授權檔案訪問和網路活動。命令可以自動執行，但會被限制在 workspace 內。
| 訪問型別 | 官方說明 |
|---|---|
| File access | 允許讀取檔案系統；允許讀寫 workspace 目錄 |
| Network access | 預設阻止，可透過 sandbox.json 或設定配置 |
| Temporary files | 允許訪問 /tmp/ 或系統臨時目錄 |
.cursor 目錄 | 無論 allowlist 如何，都保持受保護 |
flowchart TD
Command["Agent shell command"] --> Sandbox["Sandbox"]
Sandbox --> Workspace["Workspace read/write"]
Sandbox --> Temp["Temp files"]
Sandbox --> Block["Block unauthorized files / network"]
Block --> Prompt["Ask user: Skip / Run / Add to allowlist"]2. 平臺要求
官方文件列出平臺要求：
| 平臺 | 要求 |
|---|---|
| macOS | Cursor v2.0 或更高，開箱即用 |
| Windows | 必須安裝並配置 WSL2，sandbox 在 WSL2 內執行 |
| Linux | Kernel 6.2+ 且支援 Landlock v3（Linux 核心程序級沙箱機制）；啟用 unprivileged user namespaces |
如果 Linux kernel 不滿足要求，Agent 會回退到執行命令前請求 approval。
3. Sandbox 失敗時的三種選擇
當 sandboxed command 因限制失敗，官方給出三個選項：
| 選項 | 含義 |
|---|---|
| Skip | 取消該命令，讓 Agent 嘗試其他方式 |
| Run | 不帶 sandbox 限制執行這一次 |
| Add to allowlist | 不帶限制執行，並以後自動批准該命令（allowlist = 白名單，明確允許的命令清單） |
建議順序：
- 先看命令要做什麼。
- 如果只是誤選命令，選 Skip。
- 如果確實需要一次性系統訪問，選 Run。
- 只有低風險、重複、可解釋命令才加入 allowlist。
Add to allowlist 是長期放權。不要把 rm、部署、資料庫遷移、上傳、付款、真實後臺操作相關命令加入 allowlist。
4. sandbox.json 配置
官方文件說明，可以用 sandbox.json 自定義 sandbox 行為：
| 位置 | 範圍 |
|---|---|
~/.cursor/sandbox.json | per-user |
<workspace>/.cursor/sandbox.json | per-repo |
可控制 network access、filesystem paths、build caches 等。團隊專案優先用 workspace 配置，並納入 review。
5. 環境變數和 Docker 注意點
官方文件說明，Cursor 會向 sandboxed child process 注入環境變數。Linux 下 sandbox 會建立 user namespace，並把程序 UID 對映成 0；如果指令碼或 Docker 需要真實 host user，要使用：
CURSOR_ORIG_UIDCURSOR_ORIG_GID
官方給出的 Docker 模式是優先讀這些變數，再 fallback 到 id -u / id -g。
深讀：為什麼 terminal output 也要作為驗收證據
Agent 執行 terminal 命令後，真正有價值的不是“命令跑過”，而是命令輸出證明了什麼。測試透過、型別檢查失敗、構建缺依賴、sandbox 攔截、網路被拒，這些輸出都應該進入任務判斷。
所以讓 Agent 跑命令時，要要求它保留關鍵輸出、解釋失敗層級，並給最小下一步。不要讓它在錯誤上無限重試。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- Cursor Terminal sandbox 預設限制哪些訪問？
Run和Add to allowlist的風險差異是什麼？- Linux 下為什麼 Docker 指令碼可能需要
CURSOR_ORIG_UID和CURSOR_ORIG_GID？
透過標準：你能審查 Agent 準備執行的一條 shell command，並判斷是否 Skip、Run、Add to allowlist 或要求改命令。
官方來源
- Cursor Terminal Tool —— 官方說明 terminal sandbox、平臺要求、allowlist、sandbox.json、環境變數和 Docker 注意點。
- Cursor Terminal Help —— Help Center terminal 功能入口。