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 和工作流上下文。