# 调用形态：先认执行器是哪个 shell（2026-10-26 实测）（自 SKILL.md 外置）

> 本文由 keil-build 的 SKILL.md「调用形态：先认执行器是哪个 shell（2026-10-26 实测）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。

同一条编译命令，**PowerShell 与 bash 是两种写法**；`ops_bash` / `run_code` 起的是
`/usr/bin/bash -c`，**不认 PowerShell 形态**，照抄仓库 `AGENTS.md` 会直接语法错退出。

| 执行器 | 正确写法（cwd = 仓库根） |
|---|---|
| PowerShell | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py` |
| bash（`ops_bash`） | `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py` |

- bash 侧**去掉前导 `&`**（bash 里 `&` 是"丢后台"，不是调用操作符）、**路径改正斜杠**
  （`\Scripts\python.exe` 的反斜杠在 bash 是转义，路径根本解析不出来）。
- 实测（step 41→42）：把 PowerShell 形态丢进 `ops_bash` 后台任务 → 任务**秒退**、
  `exit 2`，stderr 只有这一行：

```text
/usr/bin/bash: -c: line 1: syntax error near unexpected token `&'
```

- ⚠ **这个 2 不是脚本的环境错误 2**：脚本自己报环境错误会打出 `BuildEnvError` /
  中文诊断（UV4 找不到、工程找不到、档案解析失败），而语法错**连解释器都没启动**，
  `MDK-ARM/build_log.txt` 不会被改写。判据：stderr 含 `syntax error near unexpected token`
  = 写法问题 → 换 bash 形态重跑，**别去查 `DTU_KEIL_UV4`、别当环境错误排障**。
- 后台跑（`run_in_background: true`）时要自己收码，且**别把脚本接进管道**：
  `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; rc=$?; echo RC=$rc`。
  实测 `脚本 | tail -6; echo RC=$?` 里的 `$?` 是 `tail` 的退出码（恒 0），
  拿它当 PASS/FAIL 会永远"绿"；`set -o pipefail` 能透出非零码，但尾巴上挂的 `grep`
  无匹配时同样报 1，也不可信。要看报错行就单独 grep 日志：
  `grep -a -E 'Error|error:|Warning' MDK-ARM/build_log.txt`。

解析顺序（命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测）：
工程 `uvprojx`（档案缺省时自动搜 cwd 下唯一 `*.uvprojx`）；UV4 `uv4` >
`$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但路径无效 = 立即报错，不静默回退**）。
退出码：`0`=PASS(0错0警) / `1`=构建失败（打印报错行）/ **`2`=环境错误**（UV4 找不到或
路径无效、工程找不到、档案解析失败）/ `3`=用法错误 / `4`=build 锁被占用（并发 `-b` 不可行）。
**收到 2 先确认它是脚本打的还是 shell 语法错打的**（见上节），再走"环境错误"排障。

> 2026-10-12 修正：旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**，
> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` /
> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正：
> 环境错误 → 2（`BuildEnvError`），用法错误 → 3（覆盖 argparse 的 `error()`）。