---
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="/docs/windsurf/official/04-mcp-integration" />
  <Card title="Skills 与 Workflows" description="继续分清需要脚本模板的能力包，和手动触发的重复流程。" href="/docs/windsurf/official/05-skills-workflows" />
</Cards>
