evr

evidence-readiness

检查 Agent 执行跟踪记录是否包含事后因果重建所需的证据。

当 AI Agent 导致损失时——例如配置更改不当、跨会话数据泄露、污染后的输出在 Agent 之间传播，或提示词注入——最终总有人需要根据跟踪记录重建原因。通用 Agent 插桩生成的跟踪记录无法支持这种重建：因为相关证据从未被记录。本仓库包含 evidence-readiness 规范（SPEC.md）、一个据此评估跟踪记录的检查器，以及展示符合要求的插桩效果的参考样例。

本项目是什么——不是什么

• 检查的是证据是否存在，而不是证据是否真实。 捏造但内部一致的跟踪记录也能通过检查。本工具不验证任何内容，绝不能将检查结果转述为“此 Agent 是安全的”。
• 绝不判断是否发生了故障。 它回答的是“此跟踪记录是否包含重建 X 类故障所需的内容”，而不是“是否发生了 X 类故障”。本工具不包含任何检测或评分逻辑。
• 本仓库不包含重建引擎。 本规范已公开，便于评估该方法；重建引擎可依据 SOURCE_AVAILABILITY.md 中的条款进行检查。
• 涵盖四类故障：config_drift、session_isolation_failure、cascade_contamination、prompt_injection。第五类（tool_misuse）经过调查后，因明确说明的结构性原因而未纳入——这是有记录的否定结论，并非遗漏（SPEC.md §8）。
• 本规范是 OTel GenAI 语义约定的一种配置文件：包含核心 OTel 及有文档记录的扩展（SPEC.md §2）。它不代表任何标准组织的认可。

适用对象

• 为 Agent 添加插桩的工程师，希望事后能够重建事件——将跟踪记录与符合要求的样例对比，查看需要添加哪些内容。
• 审核人员（保险机构、审计人员、交易对手方），用于评估 Agent 系统的遥测数据是否足以支持追溯性损失裁定。
• 编码 Agent：参见 llms.txt、spec.json（机器可读的规范导出文件，由程序生成，绝不手动维护），以及 src/evidence_readiness/mcp_server.py 中的 MCP 服务（配置见下文）。

快速开始（60 秒）

# from a clone of this repository
pip install .
evr check path/to/trace.json        # or a directory of traces
evr check --json path/to/traces/    # machine-readable report
evr check --require-class prompt_injection path/to/trace.json

本软件包没有任何运行时依赖；在任何 Python ≥3.10 环境中运行 pip install . 即可完成全部设置。等效的 uvx 用法均已测试：从克隆的仓库运行 uvx --from . evr check ./traces，或从软件包索引运行 uvx --from evidence-readiness evr check ./traces。

两种用法都需要 --from，末尾的 evr 也不可省略。 直接运行 uvx evidence-readiness ... 会执行以发行版命名的控制台脚本；该脚本是 MCP 服务（见下文），而不是检查器——它会读取标准输入、忽略参数，并成功退出，但不会检查任何内容。

退出代码不代表任何重建类别：0 表示满足所有要求 · 1 表示有一项或多项要求部分满足 · 2 表示有一项或多项要求未满足 · 3 表示输入格式错误（SPEC.md §9 是权威依据）。通用要求（EVR-R1..R6）决定退出代码；各类故障的证据就绪情况会单独报告，而 --require-class 会将指定类别的就绪情况纳入退出代码。对于每项未满足的要求，输出都会指出具体缺失字段及其所属的跨度类型。

每次运行结束时都会重申本 README 开篇所说的内容：存在，而非真实——证据存在并不意味着证据真实，通过检查的跟踪记录也不代表 Agent 安全。

CI：检查每个 PR（GitHub Action）

规范只需阅读一次；在每个 PR 上运行的检查会改变检测行为。将以下内容添加到生成你的跟踪记录的仓库中的工作流（发布后，evidence-readiness 是此仓库的所有者；在此仓库内部，使用 uses: ./.github/actions/readiness-check）：

steps:
  - uses: actions/checkout@v4
  - uses: evidence-readiness/spec/.github/actions/readiness-check@main
    with:
      trace-path: traces/

这就是全部设置——默认 GitHub 运行器的 python3 已足够，Action 会自行安装（零依赖的）检查器。当检查器的退出码超过 minimum-passing-exit-level（默认为 0；退出码语义与上面的快速入门相同）时，此步骤会失败。可选的 required-classes 会将指定类别的证据要求纳入退出码。输出包括：exit-code、exit-meaning、report-path（完整 JSON 报告）和 per-class-readiness。PR 注释会指出每项未完成要求具体缺少的字段和跨度类型。每条注释都只针对跟踪记录遥测数据，而非 Agent：有注释的 PR 表示证据不完整，并非检测到了故障；运行结果干净也不代表 Agent 安全。此仓库自身的 CI（.github/workflows/ci.yml）会使用 fixtures/ 对该 Action 进行自测，并断言每个类别预期的——刻意设置为非零的——退出码。

MCP 服务（Agent 接口）

src/evidence_readiness/mcp_server.py 通过模型上下文协议（stdio）向 Agent 暴露检查器和要求数据。包含三个工具：check_trace_readiness（文件、目录或内联 JSON——内联内容会在内存中处理，绝不会写入任何位置）、get_requirement 和 list_class_requirements。

安装此软件包会提供三个控制台脚本；在复制下面的内容之前，务必弄清楚它们各自的用途：

脚本	运行内容
evr	检查器 CLI——这是供人使用的脚本
evr-mcp	MCP 服务，通过 stdio 运行
evidence-readiness	MCP 服务，通过 stdio 运行——与 evr-mcp 指向相同目标；脚本名称与发行包名称相同，以便将 <package> 解析为同名脚本的逐次调用运行器能够找到它

因此，evidence-readiness 不是检查器。在 shell 中输入它，会启动一个等待从 stdin 接收 JSON-RPC 的服务，看起来像是卡住了。请使用 evr。

如果已安装软件包，evr-mcp 控制台脚本就是完整配置：

{
  "mcpServers": {
    "evidence-readiness": {
      "command": "evr-mcp"
    }
  }
}

如果是克隆仓库且未安装任何内容，则通过路径运行模块：

{
  "mcpServers": {
    "evidence-readiness": {
      "command": "python3",
      "args": [
        "/absolute/path/to/evidence-readiness/src/evidence_readiness/mcp_server.py"
      ]
    }
  }
}

无论哪种方式都不需要依赖；第二种方式无需安装。它是仅限本地运行的：不会进行网络调用，不会向外发送信息，也不会持久化任何内容。 它刻意不提供提交工具——此服务绝不会传输任何内容；是否在任何位置提交跟踪记录是由人决定的，需遵循 CONTRIBUTING.md 中的免责声明，并由人判断是否需要编辑，而 Agent 无法做出这种判断。每个工具描述都包含“存在不代表真实”的声明，因此就绪结果不能被合理地转述为“此 Agent 是安全的”。

状态

规范已进行版本管理（SPEC.md 记录当前版本和更正日志），检查器也已根据规范实现，参考测试样例（fixtures/）、机器可读的导出文件（spec.json）、Agent 接口（llms.txt、MCP 服务）和 CI 操作（.github/actions/readiness-check/）均已就位。方法论和局限性论文已完成初稿（PAPER.md）；其首页横幅标明了哪些章节已经过对抗性审读，哪些尚未审读。长期适用的披露政策见 SOURCE_AVAILABILITY.md；报告和轨迹提交条款见 CONTRIBUTING.md，脱敏指南见 REDACTION.md，发布验证说明见 RELEASING.md。更正记录在 CHANGELOG.md 中。本规范用于描述现状：每项要求都有一条验证记录中的观测结果作为依据；该记录涵盖 240 次重建尝试，其中 222 次为合成案例——每项要求的依据均来自实际检验该要求的具体案例，并非在全部 240 次尝试中测得的属性（18 个真实 Who&When 案例仅用于验证弃答方向；凡提及数量之处均会说明这一划分——SPEC.md §1）。

归属

Brien Buckman

采用 Apache-2.0 许可（参见 LICENSE）。

本仓库的开发记录实质内容均已公开：影响已发布内容的更正记录在 CHANGELOG.md 中，而与方法相关的开发缺陷记录则总结在 PAPER.md §8.6 中。这些文件起草和修订期间的提交历史未予公开。