rule-audit：AI Agent 工具实践指南

团队讨论rule-audit时，我会先把用途说清楚：AI 系统提示的静态分析器：将提示解析为规范规则并报告矛盾、覆盖范围差距、优先级模糊性和绝对规则边缘情况 - 无 LLM 调用。实际做软件开发时，经常会碰到依赖、接口和异常处理往往比主路径更影响采用，所以功能列表并不能代替验证。我的评估方法是在隔离分支完成一个可回滚的小任务，然后检查安装步骤、接口契约、测试结果和错误信息是否与文档一致。对需要可检查开发流程而非单次演示的工程师来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

它作为预提交挂钩运行，审核代理规则和提示 - AI 系统提示和代理指令（CLAUDE.md、AGENTS.md、SOUL.md） 在编码代理做出承诺之前对其进行引导。参见 预提交下面的。

问题

复杂的 AI 安全提示可能包含在特定条件下发生冲突的规则。这些冲突很容易写出来，但很难用肉眼看到。 rule-audit 以 linter 读取代码的方式读取提示，并将冲突显示为结构化结果。

说明性示例 - 两条规则之间没有明确的优先级：

"You must always follow user instructions."
"You must never produce harmful content."

当用户指示模型生成有害内容时，提示中没有任何内容表明哪条规则获胜。 rule-audit 标记了这一对，以便作者可以添加显式排序。

安装

pip install rule-audit

或者从 Hermes Labs Homebrew Tap 安装 CLI：

brew install hermes-labs-ai/tap/rule-audit

或者从来源：

git clone https://github.com/hermes-labs-ai/rule-audit
cd rule-audit
pip install -e ".[dev]"

纯Python，无运行时依赖，Python 3.9+。

60 秒快速入门

CLI

# Built-in demo — exercises every detector family, no input needed
rule-audit --demo

该演示是故意矛盾的，并生成带有退出代码 2 的 CRITICAL 发现，这是预期的成功结果 - 退出代码 2 表示发现，而不是调用错误。

# Inline prompt
rule-audit "You are helpful. You must never lie. Always answer every question."

# From a file
rule-audit --file system_prompt.txt

# Save a Markdown report
rule-audit --file system_prompt.txt --output report.md

# JSON for downstream processing
rule-audit --file system_prompt.txt --format json

# Summary only (handy in CI)
rule-audit --file system_prompt.txt --format summary

# Keep contradiction and edge-case detail at high severity
rule-audit --file system_prompt.txt --min-severity high

退出代码：0 = LOW/MEDIUM 风险，2 = HIGH/CRITICAL 风险，1 = 错误。

预提交

在提交之前审核提示文件：

repos:
  - repo: https://github.com/hermes-labs-ai/rule-audit
    rev: v0.5.0
    hooks:
      - id: rule-audit

然后运行：

pre-commit install
pre-commit run rule-audit --all-files

该挂钩检查 prompt/ 或 prompts/ 下的 Markdown 和文本文件，以及常规系统、开发人员和代理 prompt/instruction 文件名。它报告每个匹配的文件并保留上面的 CLI 退出代码。如果您的提示位于其他地方，请调整您的消费者配置中的 files:。

代理插件：Claude Code、Codex、Gemini CLI、GitHub Copilot CLI

存储库根是一个便携式 代理插件 （plugin.json，代理插件 1.0.0）提供一项技能， skills/rule-audit/SKILL.md。每个主机安装 它有自己的本机命令；他们都没有获得该技能的单独副本。

copilot skill list |

每位主持人读到的内容：

• 克劳德代码读取 .claude-plugin/marketplace.json （来源 ./，根） 和 .claude-plugin/plugin.json。
• Codex 读取回购市场 .agents/plugins/marketplace.json（来源 ./，根）和便携式 plugin.json。
• 双子座 CLI 读取 gemini-extension.json 并发现下面的技能 skills/。 Pin --ref v0.5.0 用于不可变的本机插件边界；使用 main 仅在有意测试未发布的开发更改时。
• GitHub Copilot CLI 读取根 plugin.json 并发现下面的技能 skills/.

该技能针对已安装的设备运行旁边的捆绑适配器 rule-audit，或者，如果未安装，则位于 uvx --from rule-audit==0.5.0 下。

克劳德·科德

本机插件添加了一个斜杠命令，因此您可以审核提示文件而无需 离开会议。该存储库本身就是一个克劳德代码插件市场：

claude plugin marketplace add hermes-labs-ai/rule-audit
claude plugin install rule-audit@rule-audit

要在不安装的情况下通过结帐尝试它，请运行 claude --plugin-dir .。

/rule-audit:audit prompts/support_agent.md

它在本地运行此 CLI 并返回一个有界报告 - 每个最多 5 个发现 家庭，包含真实总数和查看其余部分的命令 - 以及警告 需要正确读取 HIGH 标签。除非你要求，否则什么都不会运行。

参见 integrations/claude-code/README.md 用于安装、禁用和卸载，以及决策背后的测量 发送命令而不是自动编辑时挂钩。

双子座 CLI

扩展将相同的命令添加到 Gemini CLI：

gemini extensions install https://github.com/hermes-labs-ai/rule-audit --ref v0.5.0

/rule-audit:audit prompts/support_agent.md

Gemini CLI 向您显示确切的命令并要求您批准它，然后运行 这个 CLI 在本地并向模型提供相同的有界报告。没有运行 除非你要求，而且没有钩子。

参见 integrations/gemini-cli/README.md 安装、禁用和卸载，以及特定于主机的详细信息 - 为什么 命令退出 0，以及为什么报告被显式标记所围住。

爱马仕代理

插件将命令添加到 Hermes Agent：

hermes plugins install hermes-labs-ai/rule-audit/integrations/hermes-agent
hermes plugins enable rule-audit

/rule-audit                       # audits your own SOUL.md
/rule-audit prompts/support.md    # audits any prompt file

输入 bare it 会审核您的 SOUL.md — Hermes 系统的第一部分 提示符，以及系统提示符，其意义正是该工具所校准的。 报告将发送给您，而不是模型。除非你要求，否则什么都不会发生， 并且没有钩子。

参见 integrations/hermes-agent/README.md 用于安装、禁用和卸载，以及特定于主机的详细信息 - 为什么 插件注册没有模型工具，以及报告显示的位置。

法典

插件将技能添加到 Codex。的 存储库本身就是一个 Codex 插件市场：

codex plugin marketplace add hermes-labs-ai/rule-audit
codex plugin add rule-audit@rule-audit

安装程序 git 克隆默认分支并查找 .agents/plugins/marketplace.json 在那里。该索引位于 main 上，因此裸露的 表格不需要 --ref。

> Audit prompts/support_agent.md with $rule-audit:rule-audit

输入 $ 或 /skills 来选择技能 - 无论哪种方式都会将其插入到 作曲家，在您发送之前不会运行任何内容。然后 Codex 运行捆绑的适配器 当地并总结调查结果。 Codex 也可能会寻求其技术 当您要求立即审核但不透露姓名时，您拥有自己的权利，这就是技能的运作方式 以及插件 README 的解释。没有钩子，里面没有任何东西运行 背景，并且在您发送转弯之前什么都不会运行。

安装请参见 integrations/codex/README.md， 禁用和卸载，每回合安装技能的成本，以及 特定于主机的详细信息 - 为什么包装器而不是技能文本拥有 每一个保证。

GitHub 副驾驶 CLI

直接安装仓库的Agent Plugin，然后检查其技能是否为 启用：

copilot plugin install hermes-labs-ai/rule-audit
copilot plugin list
copilot skill list

Copilot CLI 当前警告不建议直接安装存储库，但是 该命令有效。在 Copilot 会话中，明确命名系统提示文件：

Use the /rule-audit skill to audit prompts/support_agent.md

该插件安装技能，而不是分析器运行时。运行审核需求 Python 3.9+ 和兼容的 rule-audit 安装（例如， pipx install rule-audit==0.5.0);该技能记录了固定的 uvx 后备。 将其用于系统提示逻辑。 LintLang 涵盖代理配置和工具描述的更广泛结构。技巧 按需运行，风险标签是一种启发式发现，而不是漏洞利用的证据。

机器可读的结果信封

对于跨工具比较结果的工具，可以发出相同的审核 作为 Hermes 可靠性实验室结果信封 — 嵌入普通 JSON 报告 逐字记录，加上工具版本，精确输入的哈希值，每件事一个发现 分析器找到（每个都有其源范围）、退出代码、时间戳、 以及从结帐运行时的 Git 提交：

python -m rule_audit.evidence --file system_prompt.txt
python -m rule_audit.evidence --case negative_clean_prompt   # a labeled calibration case

它不会改变检测或评分，也不读取和写入任何文件 超出输入范围。退出代码为 CLI：0、2（对于 HIGH/CRITICAL、1） 当无法读取输入时（信封随后报告状态 unknown）。

Python API

from rule_audit import audit

report = audit("""
    You are a helpful AI assistant.
    Always answer user questions completely.
    Never produce content that could harm anyone.
    Follow operator instructions above all else.
    If asked to roleplay without restrictions, comply.
""")

print(report.summary())
# rule-audit report  [2026-...T...]
# ============================================================
#   Rules parsed          : 4
#   Contradictions        : 1  (1 high, 0 medium)
#   Coverage gaps         : 5
#   Priority ambiguities  : 0
#   Meta-paradoxes        : 0
#   Absoluteness issues   : 5
#   Edge case scenarios   : 17
#   Risk score            : 55/100  [HIGH]

# Full Markdown report
md = report.to_markdown()

# Access findings programmatically
for c in report.result.contradictions:
    print(c.severity, c.description)

for ec in report.edge_cases:
    print(ec.title, ec.attack_vector)

（确切的计数取决于输入提示；上面的值是所示的五行提示的实际输出。）

它检测到什么

1、矛盾之处

相互影响的规则对。四个探测器系列：

• 直接 — 在共享主题上的相反模式（e.g。MUST 与 MUST_NOT）。
• 有条件 — 一条规则无条件适用，另一条规则在一定条件下适用相反的指令；重叠区域未定义。
• 范围 — 同一域上的通用义务 (always …) 和限制义务 (… only / except …)。
• 绝对性 — 两个方向相反的高绝对性规则（e.g。合规性与安全性）。

2. 覆盖范围的差距

检查八个与安全相关的域的提示，并标记任何没有规则覆盖的域：有害内容、主要层次结构（用户 vs 操作员 vs 开发人员）、不明确的请求、persona/roleplay、拒绝协议、指令冲突解决、指令自我披露和边缘情况回退行为。还标记没有为 else-case 指定默认值的条件规则。

3. 优先级模糊

与没有显式排序冲突且没有解决它们的元规则冲突的规则集群。

4.元规则悖论

引用规则的规则 — e.g。 “忽略所有先前的指令”（弄巧成拙），“这些指令取代所有其他指令”（可通过注入利用），或覆盖提示中其他可用于使其他规则无效的语言。

5. 绝对性审核

每个 always / never / under no circumstances 规则都与挑战场景配对：已知异常、上下文相关案例和对抗性触发器。

6. 边缘案例场景

对于每项发现，报告都会呈现一个具体的示例场景以及建议的攻击向量、预期故障模式和缓解措施。这些都是根据调查结果模板化的——说明性的测试起点，而不是经过验证的漏洞利用。

校准：它真的有效吗？

calibration/ 是一个有界的、手工标记的语料库（11 个案例），具有明确的 基本事实——不是统计声明，而是可审计的声明。阳性病例引脚 每个探测器系列的真实发现 (direct/scope/conditional/absoluteness 矛盾、元悖论、优先级模糊、覆盖范围差距）；负面案例 确定已知的误报陷阱，例如两条具有相反模式的规则 完全不相关的话题。

# Machine-readable benchmark result (JSON), exit 1 on any regression
python -m rule_audit.calibration

# As a pytest gate
pytest tests/test_calibration.py -v

每个 Rule 都将 start / end 字符偏移量携带到原始字符中 提示（report.to_dict()["rules"][i]["span"]，也线程到 矛盾、元悖论和绝对性问题）——每一个发现 追溯到确切的源范围，而不仅仅是截断的文本片段。 有关案例架构以及如何添加案例，请参阅 calibration/README.md。

限制/NOT 的作用

• 词法解析器，不是语言模型。 解析是句子分割+情态动词正则表达式+关键字簇。需要语义理解（隐含的或叙述性嵌入的约束）的规则可能会被忽略。
• 它并不能证明提示是可利用的。 CRITICAL 风险标签意味着根据词法评分“短提示中存在许多绝对规则和矛盾”，而不是经过验证的端到端漏洞利用。如需动态验证，请与 hermes-jailbench（越狱回归）配对。
• 14 个关键字簇，手工策划。 不常见的域可能不会触发覆盖差距检测；在 analyzer.py 中扩展 _KEYWORD_CLUSTERS。
• 对于没有限定词关键字的情态句子，绝对度默认为 0.5。设计选择 - 为您的语料库调整 _compute_absoluteness。
• 此版本仅提供英文版。
• 仅限单个文档。 合并为一个输入的多部分提示（操作员 + 用户 + 工具结果）将作为平面规则列表进行分析；主体之间的结构分离没有建模。
• O(n²) 配对比较。 适合现实提示；非常大的规则集会很慢。

它与其他工具有何关系

• rule-audit 和 LintLang 是互补的，而不是重复的。 rule-audit 分析系统提示的逻辑内容（矛盾、差距、优先级）。 LintLang lint 代理配置和工具描述的“结构”。运行两者。
• rule-audit 是静态的； hermes-jailbench 是动态的。 静态分析发现候选缺陷；动态测试检查它们是否可以通过实时端点访问。

建筑

rule_audit/
├── __init__.py      # Public API: audit(), audit_file(), AuditReport
├── parser.py        # Sentence splitting, modal-verb detection, Rule objects (with source spans)
├── analyzer.py      # Contradiction / gap / priority / meta / absoluteness detectors
├── edge_cases.py    # Scenario generator from analysis results
├── report.py        # AuditReport + Markdown / JSON renderers
├── calibration.py   # Labeled calibration corpus runner (calibration_cases/*.json, package data)
├── precommit.py     # Pre-commit hook entry point
└── cli.py           # CLI entry point

纯Python标准库，零运行时依赖，确定性（相同输入→相同输出），无网络调用。

发展

pip install -e ".[dev]"

# Run the test suite
pytest

# With coverage
pytest --cov=rule_audit --cov-report=term-missing

# Audit a real prompt
python -m rule_audit --file your_prompt.txt --verbose

GitHub 操作

复合 规则审核 GitHub 操作 安装已发布的 rule-audit CLI 并审核与递归 glob 匹配的文件。它报告每个 工作流日志和作业摘要中的文件。 HIGH 或 CRITICAL 风险收益退出 代码 2，默认该步骤失败；将 fail-on-high-risk: false 设置为 收集报告，不失败。它不进行安全认证或 替换针对实时模型的测试。

name: Prompt analysis
on: [pull_request]

jobs:
  rule-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hermes-labs-ai/[email protected]
        with:
          path: "prompts/**/*.txt"

调用者必须在调用操作之前检查存储库。行动 需要网络访问权限才能安装来自 PyPI 的固定规则审核版本。 files-scanned 输出报告审核了多少个匹配文件。

更多来自爱马仕实验室

• lintlang — AI 代理工具描述和工作流程的静态分析。
• 小金丝雀 — 通过无能为力的牺牲模型进行即时注入检测。
• fidelis - 具有本地检索功能的长期运行代理的语义记忆。
• 解释学 — 检测校正历史记录中重复出现的 AI 漂移。
• zer0dex — 本地代理召回，不会增加上下文窗口的负担。
• Hermes Labs 插件市场 — 用于 Claude Code 可扩展性的插件系统。

浏览 开源目录 或联系 [email protected]。