preflight-agent
AI-agent 配置在运行前需要的五项检查——一条命令。

在 AI-agent 配置中,有五件事会在任何人察觉之前悄无声息地出错:一个一打开就会执行代码的文件夹、一个留在配置文件中的有效 API key、一个永远不会触发的安全 hook、两个路由器无法区分的 agent、一个过于分散以至于无法在其中发现任何内容的 skill 集合。每一项过去都需要自己的工具——我的五个工具,全部单独发布,全都安静地放着。现在一条命令运行全部五项审计,并打印一份单一的合并回执:
preflight-agent scan ~/my-project
静态且只读——扫描不会执行任何东西。没有任何模块会在目标中运行、导入或安装任何东西;报告只引用它们发现的内容,而不评判意图。而且判定对其边界保持诚实:没有可审计内容的模块会报告 skipped 并给出原因,绝不会报告 clean,每个模块都会在回执中自己的章节打印自己的限制。
观看它运行
对 fixture 进行一次扫描,每个模块恰好植入一个问题——一个自动运行的 .envrc、.mcp.json 中的一个字面量密钥、一个指向不存在脚本的防护 hook、一个重复的 agent 名称、一个重复的 skill 名称——五个模块、五项发现、一份合并回执(29 秒,真实运行,没有预演)。
回执家族
preflight-agent 是家族中“运行前”的成员,该家族基于一套语法构建——文档 = 声明,代码 = 证据,每个判定都有引用:
- preflight-agent —— 这个配置可以安全打开吗?下面五项 preflight 检查,合并在一份回执中。
- skill-vet —— 这个 skill 包危险吗?窃取、窥探、隐藏发送,每一项都会在你安装前作为证据组合得到证明。
- permission-audit —— 这些权限是否授予了超出预期的权限?审计一条 Claude Code 允许列表链:通配符授予、危险模式、永远不会触发的规则。
- done-claim-auditor —— agent 是否做了它声称做的事?将声明与证据对比的逻辑指向会话记录。
- skill-claims —— 一个 skill 是否做了它声称的事?审计一个 skill 的文字承诺与其静态行为是否一致。
- spec-receipt —— 代码是否仍然符合规范?审计一个仓库的工程规范与其声明的实现表面是否一致。
快速开始
pipx install preflight-agent # or: pip install preflight-agent
preflight-agent scan path/to/setup
(自 v1.0.1 起已在 PyPI 上线。源码检出也可用——pipx install git+https://github.com/jasveerai88/preflight-agent——或从源码运行:python3 src/preflight_agent.py scan <dir>。)
一条命令,一份回执,一个可用于门禁的退出码——1 = 至少一个模块有发现,0 = 运行过的每个模块都是 clean,2 = 用法/输入错误。添加 --json 可获得机器可读的回执。Python 3.10+,仅使用标准库,无依赖,无网络。
五个模块
每个模块也可以单独运行,接口与其独立工具原先的接口完全一致:
| 命令 | 它能捕获什么 | 它的判定词 |
|---|---|---|
| preflight-agent clone-guard DIR | 当此文件夹被打开、安装或提交时,会执行什么:Claude / VS Code / devcontainer 配置、npm install 脚本、direnv、git 和 husky 钩子——每条命令都逐字显示 | AUTO-RUN / INSTALL-TIME / PRESENT / UNPARSEABLE |
| preflight-agent secret-guard scan FILE... | agent/MCP 配置文件中的内联密钥——按键路径和指纹给出发现;值绝不会被打印 | INLINE-SECRET / ENV-LITERAL / UNPARSEABLE |
| preflight
===== secret-guard — agent/MCP 配置中的内联密钥 ===== secret-guard v0.1.0 — 扫描 · 2 个文件 1 项发现 — 0 INLINE-SECRET · 1 ENV-LITERAL · 0 UNPARSEABLE
ENV-LITERAL — env 块中一个密钥形状的字面量,无论键名是什么(1): pf-fixture/.mcp.json — mcpServers.notes.env.SERVICE_KEY 键 "SERVICE_KEY" 持有一个字面量密钥:Q7…(24 个字符)。修复会把它改写为 SERVICE_KEY 环境变量。
VERDICT: FINDINGS — 把每个值移入对应的环境变量(运行修复命令改写文件),并轮换任何曾被提交或共享过的密钥:移动它并不能消除泄露。 secret-guard 从不打印密钥的值:报告只显示键路径和指纹(前几个字符 + 长度)。
===== hook-doctor — 失效的 hook 与无法拦截的守卫 ===== hook-doctor v0.1.0 — 审计 · 设置 settings.json 2 个 hook 处理器,跨 2 个事件 · ~ 和 $HOME 路径的主目录:pf-fixture 只读:它不编辑任何东西,也从不运行 hook 命令。它读取设置文件,以及该文件自身指定的脚本。
ERRORS — 按配置永远无法生效的 hook(1): [COMMAND_PATH] PreToolUse · 匹配器 "Bash" · python3 "$HOME/.claude/hooks/guard-rm.sh" 命令路径 $HOME/.claude/hooks/guard-rm.sh 不存在(已分别对照设置文件夹和主目录解析)—— 该 hook 永远无法运行 修复:在该路径创建脚本,或把命令指向一个存在的脚本
WARNINGS — 可能未按你的意图工作的 hook(1): [EXIT_CODE_TRAP] PreToolUse · 匹配器 "Bash" · python3 "$HOME/.claude/hooks/guard-rm.sh" PreToolUse 上的 guard-intent hook 未显示出任何拦截方式:命令或它运行的脚本中都没有 exit 2,也没有 JSON decision —— exit 1(以及其他所有代码)都是非阻塞错误,操作会继续执行。启发式判断:意图是从命令或脚本中的守卫词(guard / block / deny / prevent / forbid / protect)读出的 修复:当守卫应当阻止该操作时,以 exit 2 退出并在 stderr 上给出原因,或打印一个 JSON decision(PreToolUse 上的 permissionDecision: deny)
摘要:2 项发现 · 1 个错误 · 1 个警告 · 0 条信息 结论:FAIL —— 1 个错误:至少有一个 hook 按配置是失效的。在依赖这些 hook 之前先修复错误。
===== fleet-audit — agent 定义冲突与授权 ===== fleet-audit v0.1.0 — 审计 · 文件夹 agents 2 个 agent 文件 · 2 个 agent 已解析 · 0 个无法识别 · 遍历:递归(含子文件夹) 只读:它不编辑任何东西,也不运行任何东西。它读取你指向的文件夹中的 agent 定义文件 —— 树中每个 .md 文件都应是被支持形态的 agent 文件。 相似度:对每个 description 的小写字母数字词 token 集合计算 Jaccard 指数。0.50 判定为冲突,0.90 判定为近乎相同;短描述下限为 40 个字符。阈值和意图词都是启发式的 —— 见 SKILL.md。
清单(2): reviewer — 112 个字符 · 工具:Read, Grep, Glob · 模型:(默认) · extra/reviewer.md reviewer — 112 个字符 · 工具:Read, Grep, Glob · 模型:(默认) · reviewer.md
ERRORS — 无法路由到、正面冲突或无法读取的 agent(2): [DESCRIPTION_IDENTICAL] "reviewer" + "reviewer" · extra/reviewer.md, reviewer.md "reviewer" 与 "reviewer" 的描述近乎相同(token 集合相似度 1.000,达到或超过 0.90 的界线)—— 在两者之间做选择的路由器毫无依据,因此它们之间的委派就是抛硬币 修复:区分这些描述,直到各自点出对方并未声称的工作 —— 或者合并这两个 agent [DUPLICATE_NAME] "reviewer" · extra/reviewer.md, reviewer.md 名称 "reviewer" 由 2 个文件定义(extra/reviewer.md, reviewer.md)—— 加载哪个定义取决于作用域顺序,因此 fleet 中并不一定包含你所认为的那个 agent 修复:在 fleet 中每个名称只保留一个定义,或重命名直到名称唯一
文章标题:Show HN: Preflight-agent – 五项检查,让你的 AI-agent 配置在运行前就绪
正文: Summary: 2 findings · 2 errors · 0 warnings · 0 info Verdict: FAIL — 2 error(s): the fleet has agents that cannot be routed to, collide head-on, or cannot be read at all. Fix the errors before trusting delegation to this fleet.
===== skill-sprawl — skill duplicates, collisions, bloat ===== skill-sprawl v0.1.0 — audit · folder skills 2 markdown files seen · 2 skill candidates · 2 skills parsed · 0 unrecognized · 0 ignored (supporting docs) · walk: recursive (subfolders included) Read-only: it edits nothing and runs nothing. It reads the skill definition files in the tree you point it at — files named SKILL.md, plus loose .md files that open with a frontmatter block; other .md files are counted as supporting docs and ignored. Similarity: the Jaccard index over each description's set of lowercase alphanumeric word tokens. Collision at 0.50, near-identical at 0.90; the short-description floor is 40 characters; the oversized-body line is 500 lines; the discovery budget is 16000 listing characters (a reported figure). Token counts are estimates at chars/4. Thresholds are heuristics — see SKILL.md.
INVENTORY (2): notes-writer — 104 desc chars · body 2 lines · ~19 tokens est. · archive/notes-writer/SKILL.md notes-writer — 104 desc chars · body 2 lines · ~19 tokens est. · notes-writer/SKILL.md COLLECTION TOTALS: 2 skills · 4 body lines · ~38 tokens of body text (est., chars/4) · discovery listing 232 of 16000 budget chars
ERRORS — skills that cannot be discovered, collide head-on, are defined more than once, or cannot be read (2): [DESCRIPTION_IDENTICAL] "notes-writer" + "notes-writer" · archive/notes-writer/SKILL.md, notes-writer/SKILL.md the descriptions of "notes-writer" and "notes-writer" are near-identical (token-set similarity 1.000, at or above the 0.90 line) — a router choosing between them has nothing to choose on, so discovery between them is a coin flip fix: differentiate the descriptions until each names work the other does not claim — or merge the two skills [DUPLICATE_NAME] "notes-writer" · archive/notes-writer/SKILL.md, notes-writer/SKILL.md the name "notes-writer" is defined by 2 files (archive/notes-writer/SKILL.md, notes-writer/SKILL.md) — which definition loads depends on scope order, so the collection does not reliably contain the skill you think it does fix: keep one definition per name across the whole tree, or rename until names are unique
Summary: 2 findings · 2 errors · 0 warnings · 0 info Verdict: FAIL — 2 error(s): the collection has skills that cannot be discovered, collide head-on, are defined more than once, or cannot be read at all. Fix the errors before trusting discovery in this collection.
VERDICT: FINDINGS in clone-guard, secret-guard, hook-doctor, fleet-audit, skill-sprawl — read each module's section above before this setup runs. (exit code 1)
## 另一个方向——一份干净的配置
对一份最小化的整洁配置(一个 agent、一个 skill、一个空的 settings 文件)进行同样的扫描——head 与 verdict 行逐字保留,模块段落省略:
$ preflight-agent scan pf-control preflight-agent v1.0.1 — scan · folder pf-control 5 module(s) run · 5 clean · 0 with findings · 0 skipped ... VERDICT: CLEAN — every module that ran reported clean. CLEAN covers only what the five modules check; it is not a guarantee the setup is safe. Each module's limits are in its own section above. (exit code 0)
## 契约
- 使用 --json 时,每个命令输出一个 JSON 对象;参数与输入错误为 {"error": ...},退出码为 2,包括 --json 模式下的 argparse 错误。不输出 traceback。模块命令的 JSON 与该模块单独运行时打印的对象完全一致;scan 的 JSON 按模块嵌套这些对象,并附带一份合并摘要和 clean 结论。
- 退出码:0 表示 clean · 1 表示 findings · 2 表示 error,所有模块与 scan 完全一致。
- 只读扫描。任何扫描都不会写入、执行或安装目标中的任何内容。
# Show HN: Preflight-agent – 你的 AI-agent 配置在运行前需要的五项检查
- 唯一公开披露的例外:secret-guard 的 fix --apply 会写入——这正是它的职责。它只写入你指定的文件,默认先做一次 dry run,在每个被修改的文件旁保留带时间戳的备份,并在报告之前重新扫描重写结果。它是从独立工具原样移植过来的,而 scan 从不调用它。
- 确定性。同一个文件夹在每次运行时都会生成字节完全相同的报告。
- 每个模块的局限依然成立。静态检查只证明它们所引用的内容,不多不少——每个模块都会在其报告中打印自己的诚实局限,SKILL.md 会汇总这些局限。CLEAN 判定意味着“没有发现所检查的问题”,绝不意味着“这个配置是安全的”。
## 为什么存在这套工具——合并
这个包是按一次 fleet 审计(FLEET-AUDIT-2026-11-04)的要求合并而成的旗舰:共审计了 43 个已发布工具,其中 18 个不太受关注的工具被要求合并进 4 个旗舰,这样整个 fleet 就是少数几个强工具,而不是几十个被搁置的孤儿。clone-guard、secret-guard、hook-doctor、fleet-audit 和 skill-sprawl——五个独立的审计器,每一个都已发布并测试过——成为了这套工具的模块。
合并没有改变任何引擎:每个模块的代码与其源工具的代码字节完全相同,其 CLI 形态和判定词汇保持不变,并且它仍会在自己的章节内报告自己的源版本(v0.1.0)。这套工具自身的工作是调度器、组合扫描,以及在五个源套件带来的 276 个测试之上新增的 24 个测试——总共 300 个。
已知说明:五个引擎作为顶层 Python 模块(clone_guard、secret_guard、hook_doctor、fleet_audit、skill_sprawl)与 preflight_agent 调度器一起安装。如果你还安装了其中一个原始独立工具,两次安装会提供内容完全相同的同一个模块文件——哪一份副本行为都一样。
## 面向 agent
SKILL.md 说明了完整的命令范围、判定词汇、JSON 契约和局限——并且让 preflight-agent 本身可以作为 skill 安装:把你的 agent 指向本仓库的 SKILL.md,它就会在信任任何配置之前先对其进行预检。
安装 skill 包:本仓库还在 skill/ 下以可安装包的形式提供了同一份 SKILL.md。要使用它,请把 skill/ 文件夹中的 SKILL.md 复制到你 agent 的 skills 目录(对于 Claude Code:~/.claude/skills/preflight-agent/SKILL.md),用 pipx install preflight-agent 安装该工具,然后你的 agent 就能在信任交给它的任何配置文件夹之前先运行一次预检扫描。
## 测试
python3 -m unittest discover -s tests
300 个测试:五个源套件原样移植(56 + 57 + 44 + 58 + 61 = 276——唯一的改动是每个套件的 EXAMPLES 路径,因为现在示例按模块存放在 examples/<module>/ 下),外加 24 个调度器/扫描测试,覆盖目标发现、带原因跳过的报告、组合 JSON 形态、退出码聚合,以及 scan 从不调用 fix 的证明。测试夹具是虚构的;其中的密钥是假的。
诚实局限
- 仅限静态证据。clone-guard 报告的是会执行的表面,而不是代码运行后实际做什么;CLEAN 扫描从来不是安全保证。
- secret-guard 的范围是它能解析的 JSON 配置。env 块之外普通键名下的值,以及 TOML/YAML 配置,都不在范围内——而且一旦密钥曾被提交过,即使移动它,它仍然处于泄露状态:请轮换它。
- hook-doctor 按静态规则表判断 hook。它从不运行 hook,因此运行时行为(一个存在但行为异常的脚本)对它来说是不可见的。
- fleet-audit / skill-sprawl 的相似度是一种启发式——在既定阈值下的 token 集合 Jaccard 指数(collision 0.50、near-identical 0.90、短描述下限 40 字符、发现预算 16,000 个列表字符):这是报告出的数字,不是平台保证。
- scan 的发现是一种约定,如上所述:它审计它所查找的 settings/config/agents/skills 位置。如果某个配置把这些放在别处,就需要把模块命令指向真实路径。
- 仅 Python 实现,终端文本报告。没有守护进程,没有监视器,除 secret-guard 修复外无自动修复,没有评分——是一张收据,不是评级。
贡献
参见 CONTRIBUTING.md。证据纪律就是产品:只根据文件显示的内容发布发现,贡献也以此为准。发现 preflight-agent 误判了某个设置——它遗漏的某个层面,或者证据不支持的判定?请带着文件夹(或最小复现样本)开一个 issue;这正是能改进检查的反馈。
安全
preflight-agent 本身就是一个审计工具,所以它自身的姿态很简单:没有网络代码,没有依赖,其扫描从不执行所读取的内容。如何报告问题请参见 SECURITY.md。
许可证
MIT —— 参见 LICENSE。五个引擎保留其原始作者身份;这个合并包的自身历史从合并开始(参见 CHANGELOG.md)。
相关
- skill-vet —— 用于 agent-skill 包的安装前危险门禁。
- permission-audit —— 审计 Claude Code 权限允许列表中的通配符授权和危险模式。
- done-claim-auditor —— 根据编码智能体自身的记录来审计其完成声明。
- skill-claims —— 技能包是否做到了其描述所声称的事情?
- spec-receipt —— 针对有规格说明的仓库的漂移收据:规格与代码对比,逐项给出判定。
支持
如果 preflight-agent 在你的设置运行之前发现了问题,请考虑赞助。赞助为维护 preflight-agent、发布修复以及构建用户所要求的下一批检查提供时间资金。