---
title: "終端與命令控制"
description: "整理 Windsurf Terminal、Command 模式、Cascade 終端上下文、auto-execution、allow/deny list、團隊控制和 dedicated terminal。"
verifiedAt: "2026-05-09"
---

Windsurf Terminal 的核心價值，是把 Cascade 從“會建議命令”推進到“能在受控邊界內使用命令”。這也是風險來源：終端能測試、構建和定位問題，也能刪除檔案、推送程式碼、改基礎設施、洩露環境變數。

官方 Terminal 頁面覆蓋 Command 模式、傳送終端選區到 Cascade、`@` mention terminal、四檔 auto-execution、allow/deny list、團隊級命令策略、macOS dedicated terminal 和 legacy terminal 排障。學習順序應該先許可權，再自動化。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能為個人專案和團隊專案分別配置一套安全的命令執行邊界。

## 1. Command 模式只負責生成命令

Windsurf terminal 支援 Command modality，官方快捷鍵是 `Cmd/Ctrl+I`。它的用途是把自然語言轉換成更合適的 CLI 語法。

適合這樣用：

```text
生成查看当前分支和未提交改动的命令，不要执行。
```

不適合這樣用：

```text
直接清理项目并重新部署生产环境。
```

Command 模式解決的是“命令怎麼寫”，不是“這條命令該不該執行”。涉及刪除、遷移、部署、付款、鑑權、SSH、基礎設施和生產資料時，必須人工判斷。

## 2. 終端上下文可以送進 Cascade，但先脫敏

官方提供兩類終端上下文入口：

- 選中 stack trace 後按 `Cmd/Ctrl+L`，把選區送進 Cascade。
- `@` mention active terminal，讓 Cascade 圍繞活動終端回答。

這比手動複製一大段日誌更準確，但終端輸出經常帶敏感資訊：

| 輸出型別 | 風險 | 處理方式 |
| --- | --- | --- |
| 環境變數 | 可能含 token、資料庫 URL、賬號 | 傳送前刪除或只擷取錯誤行 |
| 構建日誌 | 可能暴露私有路徑、內部包名 | 保留錯誤上下文，去掉無關路徑 |
| 第三方 API 錯誤 | 可能含客戶資料或 request id | 只提供必要欄位 |
| SSH / cloud 日誌 | 可能含主機、使用者名稱、IP | 先判斷是否需要脫敏 |

> [!WARNING]
> **不要把 `env`、`.npmrc`、cloud credentials 或完整 CI 日誌直接送進對話**。終端上下文屬於模型上下文，不是金鑰管理工具。

推薦提示詞：

```text
只分析我选中的终端错误。
不要推断未出现的密钥、账号或内部服务。
先列出最可能的 3 个根因，再给只读验证命令。
```

如果需要讓 Cascade 繼續執行命令，先讓它把命令、目的、風險和預期輸出列出來。終端上下文可以讓定位更快，但不應該繞過命令審批。

## 3. 四檔 Auto-Execution

官方把 Cascade 自動執行命令分成四檔：

| Level | 官方含義 | 實操建議 |
| --- | --- | --- |
| Disabled | 所有命令都需要人工批准 | 新儲存庫、生產儲存庫、敏感專案預設值 |
| Allowlist Only | 只有 allow list 匹配命令可自動執行 | 個人真實專案的推薦起點 |
| Auto | Cascade 判斷命令是否安全，風險命令仍需批准；官方說明只適用於 premium models 傳送的訊息 | 適合有清晰 deny list 的成熟專案 |
| Turbo | 除 deny list 外，命令會立即自動執行 | 只用於臨時沙箱，不用於真實生產儲存庫 |

> [!NOTE]
> **在哪裡切換**：編輯器右下角的 `Windsurf Settings` 面板。Teams / Enterprise 的管理員可以在 Admin Portal 設最高階別上限，成員只能選不超過該上限的級別。

```mermaid
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 開始：

```text
git status
git diff
git branch
pnpm lint
pnpm test
pnpm run typecheck
pnpm run build
npm test
pytest
```

deny list 應覆蓋破壞性和外聯能力：

```text
rm
mv
git push
git reset
git clean
curl
wget
ssh
scp
rsync
kubectl
terraform
docker push
vercel
```

這不是永久禁止，而是要求人工確認。比如 `curl` 可以用於讀取公開文件，也可以把本地檔案發出去；讓它進 deny list 更符合真實專案邊界。

<details>
<summary>深讀：為什麼 allow list 不應該只寫 `git`</summary>

官方示例說明，如果 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，風險邊界更清楚。
</details>

## 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 在任務開始前就知道邊界，而不是等它生成危險命令後再攔。

團隊策略還應該寫清楚三件事：

1. 誰可以臨時提高 auto-execution level。
2. 哪些命令必須在 PR、issue 或變更單裡留下記錄。
3. 失敗命令是否允許 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。

建議把共享環境變數拆成只含非敏感配置的檔案，例如：

```bash
# ~/.config/dev-env/common.sh
export PNPM_HOME="$HOME/Library/pnpm"
export PATH="$PNPM_HOME:$PATH"
```

金鑰仍然應該走系統 keychain、環境注入或工具自己的憑據機制，不要為了讓 Cascade terminal 能讀到就寫進 `.zshrc`。

## 本章自檢

完成本章後，用這 4 個問題檢查：

1. 你的預設 auto-execution level 是什麼？為什麼？
2. allow list 是否只放行了低風險、可重複命令？
3. deny list 是否覆蓋刪除、推送、部署、SSH、基礎設施和外聯命令？
4. 你是否知道 dedicated terminal 使用 zsh，以及出問題時如何回退 legacy terminal？

透過標準：你能讓 Cascade 自動跑 lint/test/build，但不會自動刪除、推送、部署或訪問生產資源。

## 官方來源

- [Terminal](https://docs.windsurf.com/windsurf/terminal) —— 官方終端文件，覆蓋 Command 模式、終端選區、`@` mention terminal、auto-execution levels、allow/deny list、團隊控制、dedicated terminal 和 troubleshooting。
- [Cascade Overview](https://docs.windsurf.com/windsurf/cascade/cascade) —— 官方 Cascade 總覽，說明 Cascade 可以使用 terminal 等工具。

## 接下來去哪

<Cards>
  <Card title="MCP 整合" description="繼續學習 Marketplace、mcp_config.json、stdio/HTTP/SSE、認證插值和企業 registry。" href="/zh-Hant/docs/windsurf/official/04-mcp-integration" />
  <Card title="Skills 與 Workflows" description="繼續分清需要指令碼模板的能力包，和手動觸發的重複流程。" href="/zh-Hant/docs/windsurf/official/05-skills-workflows" />
</Cards>
