用途
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 策略(可选)。