SuperAPI AI 工具集

preflight-validator

编程与开发

查看项目

更新于 10-31 13:14

技能介绍

用途

preflight-validator 是面向 AI 执行场景的预检校验技能,作为 aura-frog/scripts/preflight/run-all.sh 的轻量包装,按需对指定目标执行 Tier 1 级别的 bash 检查,并返回统一退出码供调用方决策。

当前版本状态为 v3.7.0-beta.1。

与自动 Hook 的区别

项目中的 hooks/pre-flight-validate.cjs 会在每次 Bash/Edit/Write/Read 工具的 PreToolUse 阶段自动触发,失败时阻止工具调用,无需人工操作。本技能则用于显式调用,校验 hook 看不到的内容,例如:提交前校验 Markdown 文件、对 Bash 命令做安全性试运行、批量对目录中的计划文件做 frontmatter 校验。

主要能力

运行时会先解析目标(文件路径、Bash 命令字符串或 stdin 内容),再以相应参数调用 run-all.sh,最后把退出码和 stderr 返回给调用方。Tier 1 包含以下检查脚本:

  • validate-frontmatter.sh:校验 plan/skill/agent/rule/command 类 Markdown 的 YAML frontmatter。
  • validate-tool-input.sh:检查工具输入结构,包括必填字段、绝对路径、空操作编辑。
  • validate-tool-output.sh:检查 ANSI 转义数量、提示注入短语、JSON 声明的合理性。
  • check-path-safety.sh:拒绝路径穿越、系统文件(如 /etc/passwd)及凭据目录。
  • check-command-allowlist.sh:硬性阻止破坏性命令(rm -rf /、mkfs、fork 炸弹),对风险命令(git push --force、DROP TABLE)发出警告。
  • check-secret-patterns.sh:检测高置信度凭据模式(AWS、GitHub、OpenAI、JWT、私钥)。

run-all.sh 负责编排各个检查脚本,并返回所有检查中最高的退出码。

退出码

  • 0:通过,静默继续。
  • 1:警告,发出警告并允许继续。
  • 2:失败,阻止工具调用(PreToolUse hook 返回 2 时 claude-code 拒绝该工具)。

使用方式

资料中提供的调用方式有:

  • 自动:PreToolUse hook 对每次工具调用触发。
  • 手动:/aura-frog:preflight check 针对当前工具上下文运行 run-all.sh。
  • CI:bash aura-frog/scripts/preflight/run-all.sh --files <files> 进行批量校验。
  • 贡献者:编写新 hook 时可直接调用单个脚本。

适用场景

适合在提交前检查 Markdown、对准备执行的 Bash 命令做安全预检、批量校验计划文件,以及在 CI 中做批量验证。

限制

  • 不运行 OPA Tier 2 检查(推迟到 v3.7.0-rc.1+,OPA 按规范为可选项)。
  • 不修改工具输入或输出(只读)。
  • 不缓存结果,每次调用都是全新执行(约 10ms,足够快)。
  • bash 不可用时不做回退,需要 Linux/macOS 环境。

相关组件

规范:§9.7、§20(pre-flight);实现脚本:aura-frog/scripts/preflight/run-all.sh;自动触发 hook:hooks/pre-flight-validate.cjs;用户入口命令:/aura-frog:preflight;策略规则:rules/workflow/preflight-policies.md;未来 rc.1 计划提供 aura-frog/scripts/preflight/install-opa.sh 用于 Tier 2 OPA 策略(可选)。