Shell 执行与后台进程

run_shell_command 运行系统命令。Windows 默认 cmd.exe /c，其他平台 bash -c；不要因为自己的登录 shell 是 zsh 就按 zsh 专有语法构造命令。

参数

command 必填；description 显示目的；directory 相对项目根目录，省略使用根目录。is_background 默认 false，适合构建、测试等会自行结束的任务。

run_shell_command(
  command="npm run build",
  description="Build the project",
  directory="packages/web",
  is_background=false
)

读文件与搜索优先用 read_file、grep_search、glob；shell 留给真正的系统命令。结果要结合 Stdout、Stderr、Error、Exit Code 与 Signal 判断，存在日志输出不代表命令成功。

受管后台

长期服务设 is_background:true。工具立即返回 shell ID/PID，进程进入后台任务管理；不要再加末尾 &。

is_background:true 加裸尾随 & 会拒绝；false 时 shell 层的 & 可能把进程自行分离，但没有受管任务条目，task_stop 无法按该机制停止。需要持续观察每条输出时改看Monitor。

PTY 默认取决于入口

未显式设置 tools.shell.enableInteractiveShell 时，一次性显式 prompt 使用 child_process；交互 TUI、ACP、stream-json 输入、仅 stdin 和文件输入会话使用 PTY。显式 true/false 可覆盖选择，但 node-pty 不可用时仍回退。

Windows build <=19041 会回退 child_process；这是官方列出的实现边界，不应仅根据系统显示名判断 PTY 可用。需要输入的 vim、交互 rebase 或 TUI 程序依赖可用 PTY，Ctrl+F 可聚焦运行中的交互 shell。

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true,
      "showColor": true,
      "pager": "less"
    }
  }
}

showColor 和 pager 只对交互 shell 生效；非 Windows pager 默认 cat，Windows 没有默认值，空串关闭 pager 环境变量。子进程带 QWEN_CODE=1，脚本可据此识别来源。

命令限制不等于沙箱

旧式 tools.core 可列 run_shell_command(git) 等前缀；tools.exclude 优先排除，泛用 run_shell_command 相当于全部 shell 操作。&&、||、; 链拆分检查，任何部分不允许就拒绝整条，不能只检查首命令。

官方明确命令特定排除基于字符串匹配，不能依赖它安全执行不可信代码。通用 shell 注册、审批规则与系统隔离各有作用，见权限规则与沙箱。