Jev：外部评估器集成示例

English | 中文

本示例使用 Jev 分析选定的执行证据，回答三个结构化判断问题。独立的评估页面用于比较两版评估标准、填写人工参考标签，并记录对候选版本的批准或拒绝。

这是可选示例，不是内置产品模块。普通采集和查询不依赖 Jev，也不需要修改采集引擎、数据库结构或安全策略。

打开指南

下载并解压预编译版本，执行：

./agentprov demo jev-judge

此命令只打开离线阅读页，不会运行评估器或请求服务商。页面首次打开时跟随浏览器语言，未匹配时使用英文；右上角可手动切换，后续访问会保留选择。实际评估需要按下文另行配置。

界面与命令语言

评估工作台首次打开时，优先采用浏览器支持的语言；无法匹配时使用英文。右上角可以切换中文或英文，选择会保留。切换时也会保留当前案例、对比选项和未保存的评审草稿。

Python 命令默认使用英文。加上 --lang zh-CN 可查看中文帮助和操作提示：

python3 demo/jev-judge/workbench.py --lang zh-CN --help
python3 demo/jev-judge/workbench.py serve --data-dir "$STUDY" --lang zh-CN
python3 demo/jev-judge/judge.py --lang zh-CN --help

显式指定语言后，工作台打印的地址会带上语言参数。没有指定时，网页按浏览器偏好选择语言。JSON 进度行、导出字段和标签值不变；评估提示词、模型回答、人工填写的姓名和理由保留原文。中文规则说明仅供阅读，不会发送给模型或写回研究数据。

上图使用离线测试数据演示评审流程。历史实验见下文。

集成边界

AgentProvenance：验证后的采集记录
    ↓
示例：选取案例 → 调用 Jev → 比较与人工复核
    ↓
导出 quality_signal
    ↓
AgentProvenance：显式导入信号 → 查询与展示

导入模型判断不会将其变成运行时事实。规则优化、共享审批服务和策略下发不在本示例范围内；可复用的是证据与信号契约，而不是这套六案例评审流程。

示例比较了不同证据范围下的判断。仅看到安装指令时，无法判断实际执行是否偏离任务；加入协作消息和运行时事件后，才出现可疑行为的依据。另一条拒绝分支没有内核覆盖，其运行时结果必须保持未知。图片保留原实验中的英文页面，作为历史记录。

2026 年 9 月 22 日的实际调用记录

当次实验向 TypeSafe 直接发送 12 个请求，均返回 jev-1.13.0，未重试。验证摘要保存每次调用的哈希和分类选择，不含私有证据正文或人工参考标签。

v1、v2 的平均请求延迟分别为 829.55 ms、812.42 ms，输入 Token 分别为 14,058、14,922。每个案例仅调用一次，不能据此确定延迟服务等级或一般性能。

源证据包的签名和图验证均通过。页面复核、批准、导出、信号导入、读回和再次验证，曾在隔离副本中使用明确标记的自动测试评审者执行。原始评估仍未完成人工复核，不能把这些测试说成真实人工批准。

案例经过人为选取，没有独立保留的测试标签，因此不能据此计算有代表性的准确率、召回率，或证明一般安全性和抗提示注入能力。拒绝案例中的一项原始分类变化，也不能说成新增采集能力或基准性能提升。

启动评估

需要 macOS 或 Linux、Python 3.9+，以及预编译的 AgentProvenance CLI；也可从源码构建。无需虚拟机、GPU、代理或重新运行被分析的 Agent。Windows 用户通过 WSL 运行，本地复核锁依赖 POSIX 文件锁。

在发行包根目录执行；源码目录需先运行 go build -o agentprov ./cmd/agentprov：

AGENTPROV_BIN="$PWD/agentprov"
STUDY="$HOME/Downloads/jev-review-$(date +%Y%m%d-%H%M%S)"
KEY_FILE=/absolute/path/to/private/jev-key

python3 demo/jev-judge/workbench.py capture \
  --agentprov "$AGENTPROV_BIN" --provider typesafe \
  --key-file "$KEY_FILE" --data-dir "$STUDY" --send-raw

python3 demo/jev-judge/workbench.py serve --data-dir "$STUDY"

将 KEY_FILE 替换为私有密钥文件的实际路径。打开 http://127.0.0.1:8641；端口被占用时可通过 --port 更换。再次运行 serve 会读取已保存的评估，无需密钥，也不会新增模型请求。

capture 先通过公共 CLI 验证并导入多 Agent 证据包，再验证图。随后对六个案例分别使用两套固定标准，共调用 Jev 12 次。输出目录必须尚不存在。

发生错误时会停止，不自动重试，并保留部分输出；未完成的输出不能作为完整评估打开。再次实验需要新目录。实际调用会消耗服务商的 API 额度。

密钥与发送内容

密钥文件可仅包含密钥，也可包含一行 TYPESAFE_API_KEY=...。脚本将其作为数据读取，不执行文件内容。

--send-raw 表示允许发送选定案例中未经脱敏的原始证据。不会发送整个证据包或人工标签。密钥仅用于请求认证头，不进入证据、浏览器状态或保存的请求正文。输出和凭据应放在 Git 目录之外。

发送前可检查具体选取的内容：

python3 demo/jev-judge/judge.py prepare \
  --bundle demo/multiagent-provenance/run-double-attempt.forensics.json.gz \
  --output-dir /tmp/jev-case-preview

服务商选择

TypeSafe 直连接口固定使用 jev-1.13.0。另一个入口 --provider vercel 使用 AI Gateway 的 typesafe-ai/jev，密钥文件对应 AI_GATEWAY_API_KEY。后者已有实现，但本示例没有完成实际服务调用验收。

页面操作流程

1. 查看证据与结果。 比较仅命令、协作消息和运行时证据三种范围。检查文件路径、连接、原始消息、概率和完整请求响应。拒绝案例会区分模型原始回答与覆盖规则处理后的结果。
2. 比较评估标准。 查看 rules.py 中的问题与标准差异。两版使用同一组案例和覆盖规则；分别比较原始回答、处理后结果、延迟、输入 Token，以及与人工参考标签的分歧。
3. 完成人工复核。 为每个案例明确选择三个标签，填写评审者及理由。模型原始回答保持不变；修改复核会创建新版本，不覆盖旧记录。
4. 批准或拒绝候选版本。 批准 v2 前，所有案例必须复核完毕，返回的模型标识须匹配，并且每个问题对照参考标签均不能退步。其他问题的改善不能抵消退步；尚未复核全部案例时仍可拒绝。
5. 导出信号。 当前候选版本获批后，可导出三条关联证据图的 quality_signal。后续修改复核会使批准失效，重新复核前不能再次导出。已下载文件仍是历史记录，不会自动撤回。

这是人工参与的评估标准比较。两版标准均由人编写，没有自动优化、模型训练、在线拦截或后台晋升。批准只适用于本地这次评估。需要尝试其他标准时，修改 rules.py 中的候选版本并创建新评估，不要重写已完成评估的文件。

证据与信任边界

选取了哪些内容

六个案例包括四个实际记录的子集、一个合成文件读取对照和一个修改过的对抗文本对照。对照案例有明确标记，不会作为原执行的观测结果导入。

源记录包含 2,308 个事件，运行时案例仅选取五个事件和三条原始消息，并非完整轨迹。选中值保持原样，省略范围另有说明。部分源事件已有语义标签，因此这也不是盲测检测基准。

授权范围是分析者为演示设定的假设，不是采集到的原始用户指令。此处证据能建立 Run/cgroup 归属，但不足以证明安装工具调用与进程之间精确的因果关系。

结论能说明什么

文件访问和 connect 显示可疑传输行为；源记录未采集外发正文。

没有运行时观测时，运行时分类必须为 unknown。两版均由同一固定规则处理此情况。规则纠正的结果不能计入模型能力或候选标准的改善。

导入时验证源证据包的签名，后续 Jev 结果单独保存。

本地评审的限制

页面只监听本机回环地址，检查 Host、Origin 和每个进程的复核令牌，限制请求体，并将证据按文本渲染。它不提供面向远程用户的多租户服务，不应通过隧道开放给不可信用户。

评估目录权限为 0700，请求响应文件为 0600。哈希关联案例、标准、结果和复核版本；写入按序进行，日志事件原子发布。不过，本地目录所有者仍可改写哈希或回滚整个目录。这不是经过签名和外部存证的审批日志，评审者姓名也由使用者自行填写，未经身份认证。

导入已复核的信号

评估页面不会修改日常采集数据库。每次实验应使用独立的数据目录：现有导入逻辑会规范化信号 ID，在同一库重复导入不构成不可变的复核历史。原评估目录独立保存各版本和批准记录。

python3 demo/jev-judge/workbench.py export \
  --data-dir "$STUDY" --output "$STUDY/reviewed-signals.json"

"$AGENTPROV_BIN" --data-dir "$STUDY/store" signal import \
  --run run-double-attempt --file "$STUDY/reviewed-signals.json" --json
"$AGENTPROV_BIN" --data-dir "$STUDY/store" ai call get_signals \
  --input '{"run":"run-double-attempt"}'
"$AGENTPROV_BIN" --data-dir "$STUDY/store" graph verify \
  --run run-double-attempt --json

只有 runtime_evidence 案例生成信号。信号标签仍表示模型推断；人工参考、最终有效标签、批准、哈希和覆盖范围分别保存在证据字段中。分数是被选中的模型概率，不是风险严重程度、校准准确率或关联置信度。

测试与文件

python3 -m unittest discover -s demo/jev-judge -p 'test_*.py' -v

测试无需密钥，覆盖响应验证、密钥隔离、覆盖语义、过期及并发复核、退步检查、历史完整性、批准失效和同源 HTTP 访问限制。前文提到的浏览器及实际服务验收是另外执行的检查。

接口参考：TypeSafe API、模型限制、AI Gateway 评估接口。这些链接说明外部服务，本示例中的验证结论以记录的日期和版本为准。