AI教程

使用 Verdict 在本地分类 CLI 结果

了解如何安装 Verdict，通过 Python 或 CLI 对命令输出进行分类，解读其四种结果标签，并将其本地 197 KB 模型集成到编码代理和 CI 工作流中，而无需替代确定性验证。

AI我搜编辑部2026年11月4日阅读约 8 分钟

Verdict 的作用

Verdict 是一个面向编码代理、CI 运行器及其他工具调用系统的语义结果层研究预览。它不会将进程退出码视为决定性证据，而是综合检查命令、退出码、标准输出和标准错误。

该模型会返回四个标签之一：success、failure、blocked 或 unknown。这种区分很有用，因为命令可能在未运行任何测试、返回 HTTP 500 响应、等待工作进程或产生不完整输出的情况下以零退出码结束。同样，非零退出码也可能表示环境阻塞，而不是断言失败。

重要提示：Verdict 是辅助分类器。它无法证明任务已完成，也无法证明环境已按预期发生变化。请继续将确定性检查和权威状态验证作为事实依据。

主要功能

本地推理：输入在本地 CPU 上处理，不进行网络调用或遥测。
超小模型：量化模型大小约为 197 KB。
零依赖运行时：推理使用 Python 标准库，除软件包本身外不需要分词器文件、GPU 或其他 Python 运行时依赖。
语义分类：模型会综合考虑命令、退出码、标准输出和标准错误，而不是仅依赖退出码。
快速预测：仓库报告的中位推理时间为 0.54 ms，测试环境为文档所述的 Windows 11、AMD64 和 Python 3.12。
Python 和 CLI 接口：可在应用中使用模型，也可直接从 shell 管道调用。
浏览器演示：项目页面会在浏览器中运行相同的量化权重，无需上传日志。

Verdict 使用经过哈希处理的字符 3–5-gram 和单词 1–3-gram，并采用多分类逻辑回归。其输入为 UTF-8 文本，每个输出流通过明确的头尾截断限制为 12,288 个字符。

了解四个标签

success：输出包含表明操作已完成的积极证据。
failure：操作已运行，并报告了具体失败。
blocked：权限、依赖、网络、配额限制或环境阻止了执行。
unknown：证据缺失、不完整、被跳过、仅限于试运行，或因其他原因无法得出结论。

返回的概率来自线性多分类模型。不得将其解读为适用于安全关键决策的校准置信度。

安装 Verdict

克隆仓库，进入其目录，然后使用 pip 安装软件包：

git clone https://github.com/Balanov/verdict.git
cd verdict
python -m pip install .

这会安装 verdict_tiny Python 软件包和 verdict 命令行界面。

运行第一次 Python 预测

创建一个 Verdict 实例，并传入工具运行器观察到的相同证据。以下示例表示一个成功的 pytest 进程，但实际上没有运行任何测试：

from verdict_tiny import Verdict

model = Verdict()
result = model.predict(
    command="pytest tests/",
    exit_code=0,
    stdout="collected 0 items\nno tests ran in 0.01s",
)
print(result)

根据文档中的模型输出，尽管退出码为零，该证据仍会被分类为 unknown：

{
  "label": "unknown",
  "confidence": 0.999981,
  "probabilities": {
    "success": 0.000019,
    "failure": 0.0,
    "blocked": 0.0,
    "unknown": 0.999981
  },
  "advisory": true
}

label 是选定的结果。probabilities 对象提供每个类别的得分，而 advisory 强调该预测并非权威证明。

从命令行使用 Verdict

你可以将命令输出通过管道传给 Verdict，同时提供原始命令和退出码：

printf 'collected 0 items\nno tests ran\n' | verdict \
  --command 'pytest tests/' --exit-code 0

对于已保存到文件的输出，请使用 --stdout 和 --stderr：

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log

你也可以从指定位置加载权重：

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log \
  --weights /path/to/verdict-q8.bin

安全地集成 Verdict

实际集成时，应将 Verdict 视为额外的决策信号，而不是最终裁判。编码代理或 CI 运行器可以根据标签决定是否检查更多证据、重试操作或请求人工审核。

运行原始命令，并保留其退出码、标准输出和标准错误。
将所有可用证据传给 Verdict。
检查预测标签和各类别概率。
在执行有重大影响的操作前，应用特定于应用的阈值。
通过确定性检查验证完成情况，例如测试数量、生成的文件、API 状态或数据库记录。

例如，unknown 结果通常应触发进一步调查，而不是直接声称已完成。blocked 结果可能意味着在重试前应检查凭据、依赖、连接性、权限或配额。即使结果为 success，在正确性重要时仍需要权威验证。

高级提示

保留完整的执行上下文

请尽可能提供实际执行的命令、退出代码、标准输出和标准错误。省略输出流可能会丢失关键证据，使人无法区分具体故障、环境阻塞还是无法得出结论的运行结果。

考虑输入截断

每个输出流都会使用首尾截取限制为 12,288 个字符。当日志非常庞大时，请确保决定性消息出现在开头或结尾附近，或对完整日志执行额外的确定性扫描。

设置保守的决策阈值

这些概率并非安全关键场景意义上的校准置信度。请根据工作流程使用适当的阈值，并将不确定或影响重大的情况交由确定性检查或人工审核处理。

使用自定义或下载的权重

发布的量化权重存储在 weights/verdict-q8.bin 中，也可从 Hugging Face 获取。CLI 可通过 --weights 接受备用权重路径。

试用浏览器演示

Verdict 项目页面会在浏览器中运行相同的量化权重。根据项目文档，日志不会被上传。

复现训练和评估

安装训练和开发附加依赖，重新生成合成语料库，训练模型，导出 int8 权重，评估生成的构件，并运行测试：

python -m pip install -e '.[train,dev]'
python training/train.py
pytest -q

公开基准使用了来自 48 个未参与训练的 CLI 系列的 192 个合成示例。训练使用了来自 60 个不同系列的 1,440 个合成示例。报告显示，量化模型的准确率和宏平均 F1 均为 93.2%，而仅基于退出代码的基线准确率为 47.9%，宏平均 F1 为 31.9%。

语料库为合成数据，且偏向英语。这些测量评估的是留出模板，而不是生产环境代理执行轨迹的可靠性；延迟结果也不代表在各种硬件上的承诺。

了解项目的边界

Verdict 的范围有意保持狭窄。它会对 CLI 输出中观察到的证据进行分类，但不会判断更广泛的任务是否完成。它也无法证明代码的正确性、安全性或真实性。

因此，项目最适合作为原始进程执行与代理下一步操作之间的语义层。它可以识别退出代码遗漏的证据，但应与测试、状态检查、验证规则和人工判断互为补充，而不是取代它们。

结语

Verdict 提供了一种小巧、快速且本地运行的方式，比仅检查退出代码更谨慎地解读 CLI 结果。请将其安装为 Python 包，提供完整的执行上下文，并使用它的四个标签指导后续操作。对于可靠的自动化，始终将其建议结果与确定性且权威的验证结合使用。