intent-verify：AI Agent 工具实践指南

实际看intent-verify，先要确认它的用途：intent-verify 是一个确定性的、零 LLM CLI，它检查存储库的源在词法上是否仍然覆盖 Markdown 规范、INTENT.md 或移交文档中的接受项。软件开发里，依赖、接口和异常处理往往比主路径更影响采用。我会在隔离分支完成一个可回滚的小任务，检查安装步骤、接口契约、测试结果和错误信息。它适合需要可检查开发流程而非单次演示的工程师；采用前仍要看维护状态和试跑结果。

给它一个 INTENT.md、SPEC.md、需求列表或移交文档，它会报告所选存储库证据是否明显使用相同的术语。

使用 check 作为存储库范围的信号，或者在需要每个信号时使用 map 验收项目与明确的源和测试根源相关。差距可以阻止索赔 该范围已涵盖。涵盖的结果将工作送交审查；它从来没有 授权接受、合并、发布或出版。

INTENT.md 是输入文件示例，而不是集成点。克劳德·科德 项目说明文档描述了 CLAUDE.md 和 AGENTS.md；这个 工具不会自动加载，只会读取传递给的文件 --spec。请参阅 Anthropic 的 项目内存文档 了解 Claude Code 如何处理这些指令文件。

它是如何运作的

意图验证是故意简单且完全确定性的——没有模型，没有网络：

1. 解析规范中的验收项目（匹配标题下的内联 Accepts:/Requirements:/Scope: 行和 bullet/numbered 列表）。
2. 对每个项目进行标记，删除常见的停用词。
3. 对于每个项目，计算其标记在所选证据文件中显示为子字符串的比例（不包括规范文件本身）。
4. 根据两个阈值对每个项目进行评分，并汇总得出一个结论。

覆盖范围是一个词汇标记重叠信号，而不是语义判断。

编排覆盖图

明确指出实施证据。这会阻止匹配的 README 存储库中的其他地方无法满足地图：

intent-verify map 
  --spec INTENT.md 
  --repo . 
  --evidence-path src 
  --evidence-path tests

该命令仅使用版本控制发出 JSON intent-verify.coverage-map.v1 合约。每个项目都包含以下文件 贡献了匹配条款。顶层acceptance_authority始终是 false；对于涵盖范围，decision 为 review，对于部分或部分范围为 inspect 差距结果。

GitHub 行动

根复合操作应用相同的契约。工作流程可以使用 版本化 v0.2.1 标签：

- name: Map intent to changed implementation surfaces
  uses: hermes-labs-ai/[email protected]
  with:
    spec: INTENT.md
    repo: .
    evidence-paths: |
      src
      tests
    summary: true # optional; defaults to false

当您的供应链策略需要时，将标签解析为其提交 SHA 完整提交引脚。

当 JSON 应该时，上传操作的 receipt 输出返回的路径 保留为构建工件。

设置 summary: true 以将有界的、转义的咨询覆盖表添加到 GitHub 行动工作总结。它包括调用者的规范路径和接受情况 项目标签，因此当这些标签敏感时请将其保留。总结确实 不授予接受权：仅报告词汇证据；审查， 测试和人类判断仍然决定正确性和合并准备情况。的 summary-written 输出报告是否呈现了请求的摘要。

存储库保留 .zenodo.json 作为被动元数据。其上市的DOI是 引用相关论文，而不是软件标识； Zenodo 归档是 不是发布先决条件或承诺的发布副作用。

代理插件（Claude Code、Codex CLI、Gemini CLI）

存储库根是一个便携式代理插件（plugin.json，代理插件 1.0.0）具有单一技能，skills/intent-verify/SKILL.md。每个主机安装 具有相同的技能及其自己的本机命令；他们都没有得到单独的副本。

每位主持人读到的内容：

• 克劳德代码读取 .claude-plugin/marketplace.json（其条目为 .， root）和 .claude-plugin/plugin.json。
• Codex 读取回购市场 .agents/plugins/marketplace.json（其 条目是 ./，根）和便携式 plugin.json。
• 双子座 CLI 读取 gemini-extension.json 并发现下面的技能 skills/。保留 --ref v0.2.1 以便安装解析已审查的语义 发布而不是可变分支。

该技能使用已安装的 intent-verify CLI 或固定的 uvx intent-verify==0.2.1 与您同意。

在 Claude Code 中，插件还添加了两个按需命令。使用 /intent-verify:check --spec INTENT.md --repo . 用于正常覆盖检查， 或 /intent-verify:map --spec INTENT.md --repo . --evidence-path src 发出 明确实施根源的出处图。这两个命令都使用本地 intent-verify CLI 并仅在调用它们时运行。他们的结果仍然存在 咨询词法证据：covered 和 verified 未授权 接受、合并、发布或出版。

安装

pip install intent-verify
python -c "from importlib.metadata import version; print(version('intent-verify'))"   # confirm the installed release

或者从 Hermes Labs Homebrew Tap 安装 CLI：

brew install hermes-labs-ai/tap/intent-verify

对于本地发展：

pip install -e ".[dev]"

60 秒快速入门

给定如下规范：

# Intent

## Accepts
- uploads PDF invoices
- retries provider timeout

运行：

intent-verify check --spec INTENT.md --repo .

您会得到每个项目的详细信息和单个结论：

intent-verify: INTENT.md vs . (12 files)
  [OK   100%] uploads PDF invoices
  [PART  50%] retries provider timeout
  [LOW   20%] writes audit log for rejected invoices
intent-verify: MISSING — 1/3 items below 30% (avg 57%)

（上面的文件计数、百分比和项目只是说明性的 - 您的数字取决于您的规格和存储库。）

退出代码反映了结论，因此它直接进入 CI 或预提交挂钩：

用途

intent-verify check --spec INTENT.md --repo .
intent-verify check --spec SPEC.md --repo . --json
intent-verify check --spec docs/handoff.md --repo src --min-verified 0.75 --min-item 0.35

标志：

• --spec — Markdown 规范、意图或移交文件的路径（必需）。
• --repo — 要扫描的存储库或源树的路径（必需）。
• --section — 定位特定的降价标题，例如 Requirements。
• --json — 发出机器可读的 JSON 而不是文本。
• --min-verified — 项目必须清除的覆盖范围才能算作已验证（默认 0.7）。
• --min-item — 项目被视为缺失之前的最小每项目覆盖范围（默认 0.3）。

它解析什么

默认情况下，它从以下位置提取项目：

• 内联行，例如 Accepts: upload PDF invoices, retry on timeout
• 降价部分，例如带有项目符号或编号项目的 ## Accepts（Accepts、Requirements、Scope 标题，或通过 --section 自定义标题）

JSON 输出

intent-verify check --spec INTENT.md --repo . --json

JSON对象包括spec_path、repo_path、files_scanned、 average_coverage、verdict、使用的阈值以及 items[] 数组 每个项目的解析文本、标记、覆盖范围、结论和贡献证据 路径。旧版 check 输出保持兼容，现在包括显式 非权威元数据。

限制/NOT 的作用

• 不是运行时代理意图验证。 它不会授权或监控 AI-agent 操作、MCP/tool 调用或权限；它根据降价规范检查静态存储库源。
• 词汇上的，而不是语义上的。它将标记作为子字符串进行匹配；它不理解意义、控制流程或行为。
• 它可能会过度信用。 出现在任何扫描文件中任何位置的标记都会计入，即使它是在注释、字符串或不相关的上下文中。
• 它可能会被低估。 使用与规范不同的词汇编写的正确实现将得分较低。
• 它不是正确性的证明，并且不能取代测试或代码审查。它回答“实施是否明显涵盖了规定的范围？” — 不是“软件正确吗？”
• 它需要一个人类可读的规范。 由于没有 INTENT.md/SPEC.md/requirements/handoff 文件，因此没有任何可检查的内容。
• 仅限源文件范围。 它扫描一组固定的源扩展（Python、JS/TS、Go、Rust、shell、config、markdown 等）并跳过常见的 build/vendor 目录。
• 证据路径不是行为证明。 map 防止不相关的路径 来自贡献，但注释、文档字符串和选定的死代码 路径仍然可以匹配。测试和审查仍然具有权威性。

发展

ruff check .
python3 -m pytest -q
python3 -m py_compile src/intent_verify/*.py

存储库布局

src/intent_verify/
tests/
examples/
skills/intent-verify/SKILL.md   canonical agent skill
commands/                       Claude Code slash commands
plugin.json                     portable Agent Plugins 1.0.0 manifest
.claude-plugin/                 Claude Code plugin + marketplace
.agents/plugins/marketplace.json Codex CLI marketplace
gemini-extension.json           Gemini CLI extension

Hermes Labs 可靠性堆栈 的一部分。互补的兄弟，而不是重复：规则审核 分析系统提示中的逻辑矛盾，lintlang lints 代理配置结构 - 意图验证而不是检查规范与代码偏差。

关于爱马仕实验室

Hermes Labs 是一家代理基础设施公司，为自主系统构建可靠性层。

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