vigiles

<!-- README 指南 — 在编辑前请阅读；保持更改一致。 Claude Code + Codex 用户的主要入口和营销资产。 优化以适应快速浏览的用户，他们必须了解是什么并希望运行 — 永远不要被吓跑。 通过 6 个人物冷读（2026-07）验证：新人 / 高级用户 / 插件作者 / 持怀疑态度的高级用户 / 决策者 / Codex 用户。 以下的修复跟踪了此次审查 — 不要倒退。 --> <p align="center"> <img src="logo.png" width="140" alt="vigiles logo" /> </p> <h1 align="center">vigiles</h1> <p align="center"> <strong>您有一条代理遵循的规则一半时间 — 而不知道是哪一条。</strong> </p> <p align="center"> 验证您的CLAUDE.md或AGENTS.md、技能和钩子是否真实 — 并证明它们确实有效。 </p> <p align="center"> <a href="https://www.npmjs.com/package/vigiles"><img src="https://img.shields.io/npm/v/vigiles?color=orange" alt="npm version" /></a> <a href="https://github.com/zernie/vigiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/zernie/vigiles/ci.yml?branch=main" alt="CI" /></a> <a href="https://github.com/zernie/vigiles/blob/main/LICENSE"><img src="https://img.shields.io/github/license/zernie/vigiles" alt="License" /></a> </p> --- **您审查每个PR。没有人审查您的CLAUDE.md。** 您的** harness ** — CLAUDE.md或AGENTS.md规则、技能、子代理和钩子控制您的代理 — 是没有人检查的部分。没有人验证它是否真实。没有人测试它是否有效。那不是一个系统。那是氛围。 而氛围在任务中途会默默地崩溃：一个子代理连接到一个不存在的工具，两个技能您的代理无法区分，一个助手能够悄悄读取您的秘密并发送出去。 vigiles[^name] 检查您的 harness 是否**真实**，而不仅仅是格式良好 — Claude Code 和 Codex 都是如此。一个命令，无需密钥，无需配置，在任何仓库中都安全： ```bash npx vigiles audit ``` 它是免费和开源的，完全在您的机器上运行，并且从不按令牌计费。（`eval` 是调用模型的唯一步骤 — 在您自己的 Claude 订阅上。）以下是它在人们实际发布的插件上发现的内容。↓ ## 它发现了什么 <p align="center"> <img src="vigiles-audit.png" width="760" alt="vigiles audit report scoring my-plugin C (72/100): five categories scored A–F — Truthfulness, Triggering, Structure, Safety, Tested — with an inline fix card for a subagent declaring a tool that doesn't exist" /> </p> **就像谷歌的Lighthouse，但适用于您的代理harness。** 一个命令将其评为A-F，涵盖五个类别，每个修复都显示在内联中： - **真实性** — 参考资料是否解析？ - **触发** — 技能是否触发，而不发生冲突？ - **结构** — 工具合约和配置是否有效？ - **安全性** — 有任何方法让代理泄露您的数据吗？ - **测试** — harness 是否附带测试？ 这些是公共插件的真实扫描 — 运行 `npx vigiles audit <any-repo>` 以获取您自己的。下面的示例使用 Claude Code 子代理；相同的检查也适用于 Codex `AGENTS.md`、技能和钩子。↓ ## 证明1 — 您的代理认为它有的工具不存在 ```text ✗ tester — Tool "AskUserQuestion" 对子代理永远不可用。 → 删除或纠正它 — 它被默默地从合约中删除。 ``` 这个子代理 — 您的主代理将工作交给它的助手 — 列出了一个不存在的工具。 harness 悄悄地删除了它，您的代理失去了它认为自己拥有的功能。降噪是完美有效的。vigiles 捕获了它，并为您提供了**一行修复**。 ## 证明2 — 您的代理无法区分两个技能 ```text ✗ Triggering 0 (0/100) └ 45 pairs of near-identical skill descriptions — the agent can't tell them apart, so the wrong one fires (e.g. "agent-coder" ↔ "agent-tester", 83% alike) ``` 一个流行的插件提供了**45对**几乎相同的技能描述。您的代理通过**阅读**它们来选择技能 — 所以当两个匹配时，它会触发错误的一个。仍然是完美有效的降噪。 **[触发器工作原理 →](docs/measuring-skills.md)** ## 证明3 — 它可以悄悄读取您的秘密并发送出去 ```text ◑ Safety 80 (80/100) └ subagent "tester" holds all three lethal-trifecta legs: reads private data (Bash, Read) · takes in untrusted web content (WebFetch) · can send data out (Bash, WebFetch) ``` 给一个子代理所有三个权力，再加上一张有毒的网页，它就可以读取您的`.env`并将其发布到任何地方 — 无需利用代码，只是它被赋予的工具。 **80 看起来像 B** — 而这就是陷阱：一个健康的分数隐藏着一个子代理，它是一个数据泄露，等待发生。vigiles 从工具列表中发现了它，免费，无需模型。 这就是它的全部内容：它检查您的 harness 是否符合**现实，而不仅仅是样式**。您引用的每个工具、钩子、文件、脚本和技能都经过验证，以确保它们确实存在 — 而当您命名一个 linter 规则时，它会检查它是否存在**并且已启用**（ESLint、Ruff、Clippy 等）。 **[它捕获的所有内容 →](docs/what-vigiles-catches.md)** · 将 `audit` 指向整个市场，它会对每个插件进行相同的排名。 ## 它是如何工作的 — 氛围 → 已验证 `audit` 向您展示您的设置仍然是氛围。将这些氛围转化为**已验证** 需要四个命令，涵盖一个引擎 — 而且几乎不需要模型或密钥。 | 命令 | 答案 | 需要模型？ | 何时运行 | | ------- | ------------------------------ | ------------------------ | ------------------------ | | `audit` | 所有内容，评级 A-F | 否 — 仅读取[^audit] | 随时；这是报告 | | `lint` | 结构检查是否通过？ | 否 | CI 门控，每次推送 | | `test` | harness 行为是否正确？ | 否 — 脚本化占位 | 每次提交 | | `eval` | 技能是否真正有帮助？ | 是 — 您的订阅 | 按需 | **一个引擎，两个门户。** `audit` 是本地报告； **`lint` 是 CI 门控**，在相同的确定性检查失败时失败构建 — 损坏的引用、错误的工具合约、死亡钩子、技能冲突（证明 1-2）。`test` 和 `eval` 更进一步：从**存在**到**工作**。（`init` / `compile` / `eject` 管理底层规范层 — 您很少手动运行它们。） ### 🔎 Lint — 您的指令停止撒谎 现实中验证的每个路径、脚本、符号和规则 — 以及工具合约、技能冲突和死亡钩子（上述捕获的内容）。您不编写检查。 `npx vigiles init` 在您的文件旁边写入一个 `CLAUDE.md.spec.ts`：相同的规则，每个引用现在都被封装，以便 vigiles 可以确认它存在。 `compile` 将其转换回您的代理已经读取的 `CLAUDE.md` （或 `AGENTS.md`）。您的代理以纯英语编辑规范； `eject` 删除它，留下您的原始文件不变。 **[工作原理 →](docs/verifying-instruction-files.md)** ### 🧪 Test — harness 是否实际履行其职责？ 一个阻塞 nothing 的钩子，一个劫持无关提示的技能，一个永远不会到达模型的上下文 — 每个都通过一个天真的“它是否运行？”检查。那个间隙是 **false confidence**：一个守卫，看起来像它工作但默默地不工作。vigiles 测试真实的东西 — 钩子阻塞，技能触发，子代理完成他们承诺的内容，一个流氓 `git push` 在它发生之前被捕获。它驱动一个脚本化的模型替代品，而不是实时调用，因此它不需要密钥，并且在每次提交时运行。 **[测试工作原理 →](docs/harness-testing.md)** ### 📊 Eval — 唯一能给成本贴上真实数字的方式 _"Caveman Mode 减少了 65% 的令牌。" 说谁的？_ vigiles 在真实的编码任务上对声明进行 A/B 测试，并为您提供三个数字：**token bill**，它是否达到**目标**，以及您的代码是否仍然**有效**。 ```text caveman vs verbose · haiku · $0 on your subscription output tokens 762 → 842 (+11% — the "saving" reversed) correctness 1.0 → 1.0 (fact survived) ``` 将它指向任何声称数字的 harness 更改 — 压缩技能是否值得其成本，子代理是否值得其成本，哪个模型在这里最便宜。 promptfoo 和 DeepEval **按令牌计费，每次运行**；vigiles 在您自己的 Claude Pro/Max 订阅上运行，因此您在每次更改时进行衡量，而不是一次。 提交的锁定文件（例如 `package-lock`）使 CI 诚实，无需重新调用模型。（今天的 Claude Code； Codex 即将推出。） **[衡量技能 →](docs/measuring-skills.md)** ## 快速开始 **1. 查看问题** — 只读，无需设置： ```bash npx vigiles audit ``` **2. 设置** 当您看到您想要的内容时。将其粘贴到 Claude Code 或 Codex 中： ```text Set up vigiles in this repo: run `npx vigiles init` and accept the defaults. If I already have a CLAUDE.md or AGENTS.md, adopt it into a spec and show me which references are stale. Then compile and write + run one harness test for a hook or skill of mine. Don't run a real-model eval without asking me first. ``` 或者自己运行： ```bash npx vigiles init # 采用您的文件（非破坏性 — eject 撤销），添加 CI， # 在 ~/.claude/ 中安装 vigiles 的技能 + 钩子作为 Claude Code 插件。 # 在 Codex 上，技能也会全局安装。 ``` 交互式在终端中，非交互式适用于代理/CI（或 `--yes`）。**适用于 Claude Code 和 Codex** — vigiles 以相同方式验证 `CLAUDE.md` 和 `AGENTS.md` 。 **[Codex 设置 →](docs/harnesses.md)** **采用很顺利：一个命令，然后您的代理完成其余工作。** `init` 安装 **技能和钩子**，因此纯英文询问完成工作 — 无需手动编写规范，无需连接钩子： - _"测试我的技能"_ → 搭建并运行**触发/行为测试，然后提交其结果，以便 CI 可以检查它（`test-harness`） - _"加强我的规则"_ → 将散文指南升级为强制执行的 linter 规则（`strengthen`） - _"在我的CLAUDE.md或AGENTS.md中添加一条规则"_ → 编辑源代码并重新编译（`edit-spec`） **钩子** 在循环中保持诚实 — 提示 linter 规则提及，以便 vigiles 可以验证它，或者重新运行测试，其结果刚刚过期 — 因此没有需要记住的琐事。 <details> <summary> <code>init</code> 设置的内容</summary> - **两者都启用 lint 和 test**，默认情况下；使用 `--lint` / `--test` 进行范围限定。 - **已经有CLAUDE.md / AGENTS.md、技能或子代理？** `init` 忠实地采用它们所有并**非破坏性** — 直到您 `compile` （而 `eject` 撤销它）。 - 将 `vigiles` 添加到 `devDependencies`；通过 marketplace 安装 Claude Code 插件（技能 + 钩子）- 全局安装，不会重复。 - 将 CI 配置为 `zernie/vigiles@v1` 工作流（只需要读取 + PR 评论权限），发布粘性 PR 评论和 `valid` 输出。 适用于Claude Code和Codex开箱即用，或 [您的自定义harness](docs/authoring-an-adapter.md)。您更喜欢自己编写测试吗？ JS **或** TS (`*.harness.{mjs,ts}`) - 使用 `npx vigiles test` 运行。 </details> ## 常见问题 - **这是一个我必须构建的框架吗？** 不。它是一个工具，您可以运行它 — 像 ESLint、Lighthouse 或 `npm audit`。一个命令，一个报告，一个可选的 CI 门控。有用于自动化的库 API，但您不必使用它即可获得价值。 - **这难道不是一个markdown linter吗？** 不 — 它检查您的指令文件是否**真实**（每个路径/脚本/符号/规则都存在且已启用），然后测试和衡量您的harness。样式 linter 无法执行任何这些操作。 - **我必须编写TypeScript吗？** 不 — 您的代理编写规范（`init` 采用您的CLAUDE.md或AGENTS.md进入一个），或者使用纯markdown linter，零个新文件。编译器级别的保证是可选的，就像TS的`strict`一样（为什么？[为什么最强的保证是可选的，而不是默认的](docs/faq.md#why-are-the-strongest-guarantees-opt-in-not-the-default))。 - **它稳定到可以采用吗？** 您运行的CLI很小，几乎不会更改；库API在版本之间仍在移动。高版本号是发布自动化（每个破坏性更改一个新主版本），而不是年龄 - 请参见[稳定性](STABILITY.md)。 - **非JS仓库？** `npx vigiles lint` 在无需安装的情况下验证您的CLAUDE.md或AGENTS.md（Ruff/Clippy/Pylint/... 也一样）。 **[完整FAQ →](docs/faq.md)** **不适用于您如果** 您想要模型/功能基准或运行时请求路径中的防护 — vigiles 是构建/CI 时间的。 ## 文档 **[文档索引](docs/README.md)** 是完整的地图，按您正在执行的操作分组： - **指南** — [验证指令文件](docs/verifying-instruction-files.md) · [测试您的harness](docs/harness-testing.md) · [衡量技能](docs/measuring-skills.md) · [发布插件](docs/for-plugin-authors.md) · [Codex & other harnesses](docs/harnesses.md) - **参考** — [CLI](docs/cli.md) · [规则矩阵](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix) · [测试API](docs/testing-api.md) · [完整API](https://zernie.github.io/vigiles/) - **解释** — [它捕获的内容](docs/what-vigiles-catches.md) · [它与其他工具的比较](docs/comparison.md) · [FAQ](docs/faq.md) **项目** — [稳定性](STABILITY.md) · [相关工具](docs/comparison.md#what-vigiles-composes-with) · [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need). ## 许可证 [MIT](LICENSE) [^name]: **vigiles** — 古罗马的守夜人，他们在夜间守卫城市（并与火灾作斗争）。 _Quis custodiet ipsos custodes?_ — “谁在监视守夜人？” （尤维纳尔，_讽刺诗 VI_）。 [^audit]: `audit` 默认情况下仅读取。两个更深的检查 — 实时MCP连接和技能触发 — 是可选的，并在运行前询问。