终端与命令控制
整理 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 等工具。