Shell Mode
基於 Cursor 官方 Shell Mode 文件解釋命令執行、輸出截斷、30 秒超時、許可權審批、適用場景和排障方式。
Shell Mode 讓你在 Cursor CLI 會話中直接執行 shell 命令，並把輸出帶回對話。它適合短命令，不適合長期服務、互動式程式或需要人工輸入的流程。
閱讀目標：讀完本章，你應該能判斷什麼命令適合 Shell Mode，為什麼 cd 不會跨命令保留，以及如何處理超時、截斷和許可權審批。
1. Shell Mode 的定位
Shell Mode 解決的是“對話中快速跑一個命令”。它不是完整終端替代品。
| 適合 | 不適合 |
|---|---|
git status、npm test -- --runInBand、ls、pwd | 長時間執行的 dev server |
| 環境檢查、檔案檢視、短構建 | vim、top、互動式 prompts |
| 一次性目錄內命令 | 需要持續保持 shell state 的流程 |
| 需要把輸出給 Agent 分析的命令 | 會輸出大量日誌且無法收斂的命令 |
一個商業級判斷：命令能在 30 秒內結束、無需輸入、輸出可解釋，就適合 Shell Mode。
2. 命令如何執行
官方文件說明，命令會在你的 login shell 中執行，使用 CLI 當前 working directory 和 environment。
pwd
git status --short每條命令彼此獨立。cd 不會保留到下一次執行，所以要用鏈式命令進入目錄：
cd packages/web && npm test這點很容易誤判。你在上一條命令裡 cd subdir，下一條不會自動留在 subdir。
3. 輸出和超時
Shell Mode 有兩條重要限制：
| 限制 | 官方行為 | 實戰處理 |
|---|---|---|
| 大輸出 | 自動截斷 | 縮小命令範圍，必要時用 Ctrl+O 展開 |
| 長命令 | 30 秒超時 | 用短測試、focused build 或指令碼外部執行 |
示例：
# 更适合 Shell Mode
npm test -- checkout.test.ts
# 不适合 Shell Mode
npm run dev如果你需要啟動伺服器、持續 tail 日誌或等待互動輸入，應該回到真實終端，不要硬塞進 Shell Mode。
4. 許可權和團隊策略
命令執行前會受 CLI permissions 和 team settings 檢查。管理員策略可能阻止某些命令。
flowchart TD
Cmd["Shell command"] --> Policy["CLI permissions + team settings"]
Policy --> Allowed["Allowed"]
Policy --> Prompt["Permission prompt"]
Policy --> Blocked["Blocked by policy"]
Prompt --> Once["Approve once"]
Prompt --> Allowlist["Allowlist with Tab"]
Prompt --> Reject["Reject"]官方還提醒：帶 redirection 的命令不能 inline allowlist。也就是說，涉及 >、>> 這類重定向時，不要假設可以順手加入允許列表。
商業級團隊策略通常這樣定：
- 預設允許只讀狀態檢查命令。
- 對寫檔案、刪檔案、網路下載、許可權變更命令單獨審批。
- 對
sudo、刪除、全域性安裝、憑據讀取類命令預設阻止。 - 允許列表只收穩定、可解釋、低風險的命令。
5. 推薦用法
狀態檢查：
git status --short
git diff --stat短測試：
npm test -- auth.test.ts
pnpm lint環境檢查：
node --version
which agent
echo "$SHELL"跨目錄執行：
cd apps/docs && pnpm build不要把 Shell Mode 當作“萬能 bash”。它更像 Agent loop 裡的短命令工具。
6. 排障方式
命令卡住：
- 用
Ctrl+C取消。 - 增加 non-interactive flags。
- 避免啟動 server、watch mode、interactive prompt。
輸出被截斷：
- 用
Ctrl+O展開。 - 改成更小範圍命令。
- 讓命令輸出摘要，而不是全量日誌。
目錄不對：
- 每次用
pwd確認。 - 用
cd <dir> && ...寫成單條命令。
許可權彈出視窗頻繁：
- 先判斷命令是否真的應該被允許。
- 低風險命令可用 Tab 加入 allowlist。
- 高風險命令不要為省事加入 allowlist。
深讀：為什麼 Shell Mode 不適合跑 dev server
dev server 的價值是持續執行，但 Shell Mode 的設計是短命令執行。把 server 放進 Shell Mode，會碰到超時、輸出截斷、埠占用和無法互動關閉的問題。
更穩的做法是：在真實終端啟動 server，在 Cursor CLI 裡只執行短驗證命令，例如 curl、focused test、lint 或讀取日誌片段。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- 為什麼
cd subdir不會影響下一條 Shell Mode 命令？ - 哪些命令應該回到真實終端執行，而不是放進 Shell Mode？
- 為什麼帶重定向的命令不能按普通命令加入 inline allowlist？
透過標準：你能寫出一組團隊 Shell Mode allowlist，並解釋每條命令的風險等級和驗收用途。
官方來源
- Cursor Shell Mode —— 官方說明命令執行、輸出截斷、30 秒超時、許可權、使用建議、排障和 FAQ。
- Cursor CLI Permissions —— 官方 CLI permissions 配置入口。
- Using Agent in CLI —— 官方 CLI command approval 和工作流上下文。