SuperAPI AI 工具集

verify-commands

编程与开发

查看项目

更新于 10-16 14:35

技能介绍

用途

verify-commands 用于编写或评审「验证命令」(verify command)。验证命令是一类验收测试:判断某项工作是否真正完成的可执行检查,包括测试调用、验收检查、CI 门禁、shell 断言等。该技能关注的不是命令能否运行,而是命令能否真正度量它声称要度量的东西。

核心原则

在交付一条验证命令前,必须回答一个问题:如果这条命令在静默地什么都没做,它的输出里会有什么告诉我?如果回答不出来,那它就是一条命令,而不是一个检查。此时应当修复命令本身,而不是为它编造一句说明。

主要能力

1. 命名失败方向

每一条可运行的检查旁边,写一行说明表示失败的可见信号,例如:非零退出码、摘要行中出现「0 passed」、覆盖率行缺失、stderr 包含「ECONNREFUSED」。「命令失败」「出现错误」属于对结果的复述,不是信号。TBD、N/A、none 属于拒答。简短即可,例如「非零退出」本身就是完整的。优先使用工具实际发出的信号,而非想象出来的信号:对已运行过的命令,写明你实际看到的内容;对新命令,从工具文档记载的输出中取信号。N 条命令需要 N 条失败信号。

2. 为每条路径提供依据

在推导新命令之前,先原样继承本仓库中已经可用过的命令。cd 目标或 --prefix 目标必须存在,或由更早的步骤创建,并且包含对应的清单文件(package.json、Makefile、pyproject.toml)。优先使用 npm --prefix <dir> run <script> 而非 cd <dir> && npm run <script>,因为它不依赖调用者的工作目录。不要凭手推理文件系统,应列出目录。若无法为某条路径提供依据,应如实说明,而不是猜测。

3. 识别「会通过但没有度量任何东西」的形态

技能给出了若干典型陷阱及其原因与替代写法:

  • pnpm ls vite | grep -E '^vite@7':树形输出每行以 └── 开头,因此 ^ 永不匹配。替代:去掉锚点,或匹配 (└|├)── vite@7。
  • npm test | grep '714 passed':这个计数来自记忆,训练数据可能已过时。替代:grep -E '[0-9]+ passed',或先运行取得计数。
  • X=$(cmd 2>/dev/null || echo 0) 再喂给 [ "$X" = "$Y" ]:当输入缺失时两侧都默认为 0,于是「一致性」在空值上通过。替代:让失败传播,或用 test -f 加以保护并退出。
  • grep -c 'LITERAL' file == 0,而指令或注释里就引用了 LITERAL:门禁被注释文本触发,而非代码。替代:用概念描述被禁止的东西,而不是字面量。
  • ! grep -q PATTERN file,而同批变更在文件别处合法地加上了 PATTERN:跨区域的全文否定无法满足。替代:限定范围,如 awk '/^def f/,/^def /' file | grep,或 AST 检查,或单元测试。
  • 测试名过滤器匹配到零个测试:退出码为 0 且什么都没断言。替代:先列出测试(--collect-only、--list),再运行被点名的那一个测试。
  • npm test | tail -20,却把退出状态当作判定:管道以最后一条命令的状态退出,因此 npm test 失败而 tail 报告 0。替代:同一命令行以 set -o pipefail; npm test | tail -20 开头(bash、zsh)。更早的工具调用里设置过的 set 已经失效。

锚点陷阱还有一族同类:npm ls、yarn list、docker ps、kubectl get all 都会打印列前缀或树形前缀。|| echo 默认值只在「缺失即默认值」且该值不用于检测缺失的比较中才可接受。

4. 评审他人的命令

只报告问题,不要规定一条你并未验证过的替代路径。被规定的路径会被原样复制,却不携带任何信息。目录或清单文件缺失属于阻塞项:应引用原始目标。动态路径、通配符、~ 或变量属于警告,不是猜测字面量的许可。

使用方式

该技能以命令编写与评审的指导规范形式使用:在编写测试调用、验收检查、CI 门禁或 shell 断言时套用上述检查项;在评审他人提交的验证命令时,按「失败方向是否明确、路径是否有依据、形态是否属于空通过」逐项核对,并只报告、不擅自规定未验证的替代路径。具体调用方式与集成细节暂未提供。

适用场景

  • 编写测试调用、验收检查、CI 门禁、shell 断言等判断工作是否完成的命令。
  • 评审他人提交的验证命令是否存在空通过、无度量或路径无依据的问题。
  • 排查命令看似通过但实际未检测任何内容的情况。

限制

资料未提供该技能的收费、价格、支持平台、具体安装命令或版本信息。技能本身不提供替代命令的自动生成,评审时也不允许规定未经验证的替代路径;遇到目录或清单缺失应作为阻塞项报告,遇到动态路径应作为警告处理。