Skip to content

xinetzone/SpecWeave / .agents/skills/bundled-script-exit-code-ambiguity

bundled-script-exit-code-ambiguity

Verified

验证自带脚本的退出码契约时,必须区分「契约检出的 1」与「未捕获异常返回的 1」。必须使用此技能:当用户提到「退出码对了但行为不对」「Traceback 也是退出 1」「目录路径报 IsADirectoryError」「夹具只看退出码」「PASS 但其实是崩了」「异常冒充契约码」时。不用于通用夹具搭建与缺陷注入(用 skill-bundled-script-validation)、质量门掉分修复(用 skill-quality-gate-remediation)或会话取证(用 chat-session-evidence-audit)。

自带脚本退出码歧义判别

本技能只回答一个问题:当夹具断言「退出码等于契约值」时,它究竟证明了什么。

答案常常是「几乎什么也没证明」。Python 脚本未捕获异常时进程退出码固定为 1,而校验脚本最常见的「检出问题」契约码也是 1。两者在退出码上完全一致。

1. Why:退出码为什么不足以作为证据

三个叠加的事实:

事实后果
未捕获异常 → 解释器退出 1与「检出失败」同码,退出码无法区分「我发现了问题」与「我崩了」
读取目录抛出的异常是 OSError 子类脚本里一句 except OSError 宽兜底就能把崩溃正式映射成契约码,连 traceback 都不留
空 stdout 送进 json.loads 会抛 JSONDecodeError观察者容易把「死在打印之前」读成「没输出」,转而去怀疑断言写错,而不是怀疑脚本

实测(来源会话):漂移探针对目录路径做读取,进程退出 1;该脚本契约中 1 同时承载「检出漂移」「目标缺失」「链接目标不可读」三种语义。原始行与修复前后输出见 事故证据。

异常类型本身不可移植:本机 Windows 实测抛出 PermissionError(errno 13),POSIX 上是 IsADirectoryError,两者都是 OSError 子类。所以不能按异常类型分支修补,只能按类型判断的结果(is_file() / is_dir())在读取前短路。

2. 适用边界

适用:

  • 被验证脚本的契约含两个以上退出码,且 1 是其中一个约定值
  • 夹具只看退出码,需要判断它到底证明了什么
  • 出现「退出码对,但输出不像正常结果」的怀疑

不适用:

任务交给
通用正向样本、缺陷注入、镜像夹具搭建skill-bundled-script-validation
Skill 包体整包验收(质量门/链接门/编码)skill-package-verification-gates
质量门掉分修复skill-quality-gate-remediation
核实来源会话的历史过程chat-session-evidence-audit

3. 预检:先把契约读成清单(零写入)

改脚本或改夹具之前,只读地列出每条契约路径:

字段例
路径名directory-probe
命令python probe.py --path <dir>
期望码2
stdout 形状空(原因写在 stderr)
stderr 允许内容一行 not a regular file

这份清单本身就是本技能的 dry-run:不执行任何写操作,只产出一张待断言表。清单少于两行说明契约没读全——先补契约,再谈断言。

为什么清单要写在改代码之前? 修复时注意力只会落在失败那一条上,清单是唯一能把全集摆出来的东西;缺了它,「复跑全部路径」会退化成「复跑我记得的那几条」。

4. 判别规则:三断言

对清单中每条路径,同时断言三件事:

#断言单独失败时的含义
A1exit == expected契约不符
A2契约声明了机器可读输出时,stdout 按声明的形式解析成功输出形状不符,或进程在产出结果前就死了
A3stderr 不含 Traceback,且未声明诊断的路径 stderr 必须为空Traceback = 未捕获异常;无 traceback 的非空文本 = 未声明的诊断

A3 是两级的:无论契约是否允许 stderr 输出,Traceback (most recent call last) 都判失败;只有「是否允许其他文本」由契约决定。否则一给退出 2 的路径开口子,堆栈就会跟着混进来。

判定表:

A1A2A3结论
命中通过通过PASS
命中失败(不可解析或为空)含 Traceback缺陷:异常冒充契约码
命中通过非空但无 Traceback、契约未声明未声明的诊断输出;核对契约后判为文档缺项或缺陷
未命中任意任意契约不符;先读 stderr 是否已给出原因

规矩只有一条:不得为了让 A1 变绿而放宽 A2 或 A3。 放宽断言等于把缺陷写进验收标准。

为什么 A2 只要求「可解析」而不是「内容正确」? 本技能管的是形状——进程是否活到了产出结果那一步。内容对不对由各脚本自己的业务断言负责,混在一起会让「JSON 能解析」被误当成「结论正确」。

5. 歧义码对照

码常见来源结构性歧义
0显式成功低——未捕获异常不会返回 0
1检出问题 / 未捕获异常 / 部分脚本的用法错误高——多种语义同码
2argparse 用法错误;契约写明的 IO 错误中——须分辨是脚本判定还是解析器退出
其它自定义逐条核对

为什么把 1 单列? 它是解释器崩溃的默认码。凡是把 1 用作「发现问题」的脚本,都自带一条无提示的假阳性通道。

6. 修复模式

原则:把类型与边界判断前移到读取之前,让非法输入稳定落到用途码(通常是 2),而不是抛在读取里。

if not os.path.isfile(path):          # 读取之前
    print(f"not a regular file: {path}", file=sys.stderr)
    return 2

三条禁止:

  • 禁止 except Exception: return 1——把崩溃伪装成检出,直接制造假阳性
  • 禁止只改夹具——缺陷在脚本侧,放宽夹具会把缺陷固化成验收标准
  • 禁止 2>&1 合并两路输出后断言 stderr 为空——合并即失去判别力

为什么必须复跑全集而不是只跑失败那条? 短路前移会改变相邻分支的执行顺序,原本经由异常路径返回的用例可能因此改道,只跑失败项看不到这类回归。

7. 复跑与证据

随包脚本 scripts/assert_contract.py 把三断言固化为一条命令。它只读且幂等:不修改夹具、不写缓存,重复执行结果一致。

python scripts/assert_contract.py --expect 2 --allow-stderr --name directory-probe -- \
  python probe.py --path fixtures/a-dir
echo "HARNESS_EXIT=$?"

--json 只在契约声明了机器可读输出的路径上加;--allow-stderr 只在契约声明了 stderr 诊断的路径上加。两者都按第 3 节的清单填,不按期望码推断。

自身退出码:0 三断言全过;1 有断言失败(失败项与捕获到的 stderr 打印到 stderr);2 用法错误或命令无法启动。

交付报告用这张表,一行一条路径:

路径期望码实得码stdoutstderr结论

不要写「全部验证通过」而不附码与输出形状。

8. Gotchas(陷阱与反直觉行为)

  1. 2>&1 之后 A3 无法成立:合并流后 stderr 与 stdout 不可分,必须 out=$(cmd 2>"$err") 或让脚本分流捕获。
  2. 读取目录的异常类型随平台变:本机 Windows 实测 PermissionError(errno 13),POSIX 上是 IsADirectoryError;两者都是 OSError 子类,except OSError 会把它们一起吸收成正常返回,此时连 traceback 都没有,只剩 A2 能揭穿。
  3. 不要按异常类型修补:按 is_file() 的判定结果在读取前短路,才不依赖平台抛哪个子类。
  4. 管道会换掉退出码:cmd | head 返回 head 的状态;用 set -o pipefail 或先取 $?。
  5. 空 stdout 的 JSONDecodeError 是误导源:它同时对应「脚本没输出」与「脚本死在打印前」,必须结合 stderr 判读。
  6. argparse 自带退出码:--help 退出 0、用法错误退出 2。这两条路径的 A2 要按路径豁免——--help 的 stdout 不是 JSON。
  7. --expect 1 的夹具天生漏报:看到期望值为 1 的断言,先确认它是否也断言了 A2 与 A3。
  8. 给退出 2 的路径开 stderr 口子时别把堆栈也放进来:--allow-stderr 只放宽「非空」,Traceback 仍判失败。
  9. grep -c 零匹配会污染 $?:统计行数加 || true,但不要把 || true 用到脚本调用本身。
  10. 函数级单测不能替代子进程断言:只有 __main__ 里逃逸的异常才会转成退出码 1。
  11. 不做四处登记不等于已交付:本技能只产出包体;入库登记另走 native-skill-surface-registration。

9. 安全检查清单(逐项确认)

  • 契约清单已写完(命令、期望码、stdout 形状、stderr 允许内容)
  • 每条路径都断言了 A1 + A2 + A3,没有只留 A1
  • 期望值为 1 的路径已单独标注,并确认 A2/A3 在断言范围内
  • stdout 与 stderr 是分流捕获的,未使用 2>&1
  • 退出码取自脚本本身,未被管道或复合命令替换
  • 修复是把边界判断前移到读取之前,未新增 except Exception
  • 修复后复跑了全部契约路径,不只失败那条
  • 断言脚本只读且幂等,未修改夹具、未在技能目录留下 __pycache__
  • 交付报告逐路径列出期望码、实得码、stdout 形状与 stderr 状态
  • 未验证的路径已标注,未算进通过项

10. 参考

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall