終端與命令控制
整理 Windsurf Terminal、Command 模式、Cascade 終端上下文、auto-execution、allow/deny list、團隊控制和 dedicated terminal。
Windsurf Terminal 的核心價值，是把 Cascade 從“會建議命令”推進到“能在受控邊界內使用命令”。這也是風險來源：終端能測試、構建和定位問題，也能刪除檔案、推送程式碼、改基礎設施、洩露環境變數。
官方 Terminal 頁面覆蓋 Command 模式、傳送終端選區到 Cascade、@ mention terminal、四檔 auto-execution、allow/deny list、團隊級命令策略、macOS dedicated terminal 和 legacy terminal 排障。學習順序應該先許可權，再自動化。
閱讀目標：讀完本章，你應該能為個人專案和團隊專案分別配置一套安全的命令執行邊界。
1. Command 模式只負責生成命令
Windsurf terminal 支援 Command modality，官方快捷鍵是 Cmd/Ctrl+I。它的用途是把自然語言轉換成更合適的 CLI 語法。
適合這樣用：
生成查看当前分支和未提交改动的命令，不要执行。不適合這樣用：
直接清理项目并重新部署生产环境。Command 模式解決的是“命令怎麼寫”，不是“這條命令該不該執行”。涉及刪除、遷移、部署、付款、鑑權、SSH、基礎設施和生產資料時，必須人工判斷。
2. 終端上下文可以送進 Cascade，但先脫敏
官方提供兩類終端上下文入口：
- 選中 stack trace 後按
Cmd/Ctrl+L，把選區送進 Cascade。 @mention active terminal，讓 Cascade 圍繞活動終端回答。
這比手動複製一大段日誌更準確，但終端輸出經常帶敏感資訊：
| 輸出型別 | 風險 | 處理方式 |
|---|---|---|
| 環境變數 | 可能含 token、資料庫 URL、賬號 | 傳送前刪除或只擷取錯誤行 |
| 構建日誌 | 可能暴露私有路徑、內部包名 | 保留錯誤上下文，去掉無關路徑 |
| 第三方 API 錯誤 | 可能含客戶資料或 request id | 只提供必要欄位 |
| SSH / cloud 日誌 | 可能含主機、使用者名稱、IP | 先判斷是否需要脫敏 |
不要把 env、.npmrc、cloud credentials 或完整 CI 日誌直接送進對話。終端上下文屬於模型上下文，不是金鑰管理工具。
推薦提示詞：
只分析我选中的终端错误。
不要推断未出现的密钥、账号或内部服务。
先列出最可能的 3 个根因，再给只读验证命令。如果需要讓 Cascade 繼續執行命令，先讓它把命令、目的、風險和預期輸出列出來。終端上下文可以讓定位更快，但不應該繞過命令審批。
3. 四檔 Auto-Execution
官方把 Cascade 自動執行命令分成四檔：
| Level | 官方含義 | 實操建議 |
|---|---|---|
| Disabled | 所有命令都需要人工批准 | 新儲存庫、生產儲存庫、敏感專案預設值 |
| Allowlist Only | 只有 allow list 匹配命令可自動執行 | 個人真實專案的推薦起點 |
| Auto | Cascade 判斷命令是否安全，風險命令仍需批准；官方說明只適用於 premium models 傳送的訊息 | 適合有清晰 deny list 的成熟專案 |
| Turbo | 除 deny list 外，命令會立即自動執行 | 只用於臨時沙箱，不用於真實生產儲存庫 |
在哪裡切換：編輯器右下角的 Windsurf Settings 面板。Teams / Enterprise 的管理員可以在 Admin Portal 設最高階別上限，成員只能選不超過該上限的級別。
flowchart TD
Need["Cascade 想執行命令"] --> Level{"Auto-execution level"}
Level --> Disabled["Disabled: 全部人工批准"]
Level --> Allow["Allowlist Only: 只放行 allow list"]
Level --> Auto["Auto: 模型判斷安全性"]
Level --> Turbo["Turbo: 除 deny list 外立即執行"]
Allow --> Deny{"命中 deny list?"}
Auto --> Deny
Turbo --> Deny
Deny -->|是| Approve["必須人工批准"]
Deny -->|否| Execute["可自動執行或繼續判斷"]
style Approve fill:#fee2e2,stroke:#dc2626,stroke-width:2px
style Execute fill:#dcfce7,stroke:#16a34a,stroke-width:2px對商業專案，推薦預設策略是 Allowlist Only。先讓 lint、test、build、git read-only 命令自動執行，再逐步擴大。不要一上來開 Turbo。
4. Allow list 和 Deny list 的優先順序
官方說明 allow list 匹配的命令會自動執行；deny list 匹配的命令不會自動執行，會要求使用者批准。團隊級和個人級列表會合並；如果同一命令同時命中 allow 和 deny，deny list 優先。
在哪裡編輯：開啟 Command Palette（Cmd+Shift+P / Ctrl+Shift+P）→ Open Settings (UI) → 搜 windsurf.cascadeCommandsAllowList 或 windsurf.cascadeCommandsDenyList，逐行加命令字首；Teams / Enterprise 的團隊級列表在 Admin Portal → Team Settings → Terminal Commands → Manage Lists 裡維護，會與個人列表合併。
個人專案可以從這組 allow list 開始：
git status
git diff
git branch
pnpm lint
pnpm test
pnpm run typecheck
pnpm run build
npm test
pytestdeny list 應覆蓋破壞性和外聯能力：
rm
mv
git push
git reset
git clean
curl
wget
ssh
scp
rsync
kubectl
terraform
docker push
vercel這不是永久禁止，而是要求人工確認。比如 curl 可以用於讀取公開文件，也可以把本地檔案發出去；讓它進 deny list 更符合真實專案邊界。
深讀：為什麼 allow list 不應該只寫 git
官方示例說明，如果 allow list 加了 git，Cascade 可能會自動接受 git add -A 這類命令。真實專案裡，git status 和 git diff 是隻讀，git add、git commit、git push 會改變儲存庫狀態或遠端狀態。
因此更穩的是寫完整命令字首，而不是粗粒度放行整個工具名。把 git status、git diff 放進 allow list，把 git push、git reset 放進 deny list，風險邊界更清楚。
5. 團隊級命令控制
Teams 和 Enterprise 管理員可以設定最高 auto-execution level，也可以配置團隊級 allowlist / denylist。官方給出的邏輯是：管理員設定上限後，成員只能選擇不超過該上限的級別；團隊級列表會和個人列表合併。
推薦團隊策略：
| 專案型別 | 最高階別 | 團隊 allow list | 團隊 deny list |
|---|---|---|---|
| 文件站、教程站 | Allowlist Only 或 Auto | lint、typecheck、build、只讀 git | push、reset、deploy、刪除、外聯命令 |
| 內部業務系統 | Allowlist Only | test、lint、只讀診斷 | 資料庫遷移、支付、生產部署 |
| 基礎設施儲存庫 | Disabled 或 Allowlist Only | plan、fmt、validate | apply、destroy、kubectl 寫操作 |
| 臨時 demo | Auto | test、build、啟動命令 | 真實賬號和生產後臺相關命令 |
把命令策略寫進 repo AGENTS.md 或 .windsurf/rules/，讓 Cascade 在任務開始前就知道邊界，而不是等它生成危險命令後再攔。
團隊策略還應該寫清楚三件事：
- 誰可以臨時提高 auto-execution level。
- 哪些命令必須在 PR、issue 或變更單裡留下記錄。
- 失敗命令是否允許 Cascade 自動重試。
自動重試尤其要謹慎。構建失敗可以重試，扣費 API、資料庫遷移、部署和基礎設施寫操作不應該讓 agent 自行重試。
6. Dedicated terminal 和排障
官方說明，從 Wave 13 起，Windsurf 在 macOS 上為 Cascade 引入 dedicated terminal。它與預設終端分離，並始終使用 zsh；這個終端會讀取 .zshrc 和其他 zsh 配置，因此 alias 和環境變數可能可用。
如果你的日常 shell 不是 zsh，官方建議建立共享配置檔案，讓不同 shell 都能 source 同一組環境變數。這樣可以避免“你在普通終端能執行，Cascade dedicated terminal 不能執行”的差異。
遇到 dedicated terminal 問題，官方提供的回退方式是開啟 Windsurf settings 裡的 Legacy Terminal Profile。
建議把共享環境變數拆成只含非敏感配置的檔案，例如：
# ~/.config/dev-env/common.sh
export PNPM_HOME="$HOME/Library/pnpm"
export PATH="$PNPM_HOME:$PATH"金鑰仍然應該走系統 keychain、環境注入或工具自己的憑據機制，不要為了讓 Cascade terminal 能讀到就寫進 .zshrc。
本章自檢
完成本章後，用這 4 個問題檢查：
- 你的預設 auto-execution level 是什麼？為什麼？
- allow list 是否只放行了低風險、可重複命令？
- deny list 是否覆蓋刪除、推送、部署、SSH、基礎設施和外聯命令？
- 你是否知道 dedicated terminal 使用 zsh，以及出問題時如何回退 legacy terminal？
透過標準：你能讓 Cascade 自動跑 lint/test/build，但不會自動刪除、推送、部署或訪問生產資源。
官方來源
- Terminal —— 官方終端文件，覆蓋 Command 模式、終端選區、
@mention terminal、auto-execution levels、allow/deny list、團隊控制、dedicated terminal 和 troubleshooting。 - Cascade Overview —— 官方 Cascade 總覽，說明 Cascade 可以使用 terminal 等工具。