Verifier Hub

verifier-hub

verifier CLI 对产物文件做可复现校验（xlsx / docx / pdf / pptx / md / zip 等）。 它回答的是「文件结构和数值对不对」这类有确定答案的问题，比让模型读一遍再判断可靠。

主要用在交付前自检：准备把文件交给用户之前，先用 verifier 确认格式和关键内容都符合任务要求。

CLI 形态

优先用工作区内的相对路径调用：

./skills/verifier-hub/bin/verifier

Windows 上换成同目录的 .cmd 包装，或者直接把无扩展名的脚本交给 Python：

.\skills\verifier-hub\bin\verifier.cmd docx outline .\contract.docx
python .\skills\verifier-hub\bin\verifier docx outline .\contract.docx

下文所有示例都写成 POSIX 形式，Windows 上按上面这两种写法替换即可。

两级子命令：

verifier --help                       # 列 family
verifier <family> --help              # 列 family 内子命令
verifier <family> <subcmd> --help     # 查看子命令参数与默认值

输出协议

每次调用在 stdout 输出一个 JSON 对象，参数写错时也一样：

{"ok": true,  "tool": "<family>.<sub>", "result": {...}, "evidence": {...}}
{"ok": false, "tool": "<family>.<sub>", "error": {"code": "...", "msg": "..."}}

• ok 表示工具本身是否执行成功，不表示校验结论。
• 校验结论在 result.passed（true / false / null，null 表示该子命令只报告事实、不做断言）。 所以「文件格式不符合预期」这种情况是 ok: true + result.passed: false。
• evidence.quote 是可直接引用的一句话证据。
• rubric 家族在 result 里额外给 passed 和 evidence_quote 两个字段（注意都在 result 下，不在顶层）。

交付前校验流程

1. 定位待交付文件：确认文件真实存在，路径和扩展名正确。
2. 格式校验：对每个文件至少跑一次

   ./skills/verifier-hub/bin/verifier rubric check-file-format <path> --expected-ext <.ext>
   

3. 内容校验：按文件类型补一条与任务直接相关的检查，例如
   • xlsx：xlsx list-sheets、xlsx assert-value、xlsx eval-formula
   • docx：docx outline、docx table-list、docx page-count
   • pdf：pdf pages、pdf text-dump、pdf cjk-check
   • pptx：pptx list-slides、pptx slide-text
   • text / md：text must-contain、text placeholder-audit
   • zip：archive zip-list、archive zip-check-entries
4. 记录证据：交付说明里只引用真实执行过的 verifier 命令和它的输出。不要把自己用 Python 或 Bash 算出来的结果说成 verifier 证据。
5. 再交付：所有待上传文件都通过校验后再交付。

工具族总览

58 个子命令的完整参数与调用示例见 references/subcommands.md。 也可以直接 verifier <family> --help 现场查，不必先读文档。

错误码

依赖与环境

安装缺失的 Python 包时不要用裸 pip install：沙箱里 venv 的 site-packages 不可写， user site 又没有 sys.path 优先级，两种默认路径都会失败。用这个写法：

pip install --target "$HOME/.verifier-pylibs" pymupdf
export PYTHONPATH="$HOME/.verifier-pylibs:$PYTHONPATH"

Windows / PowerShell 上没有 $HOME 和 export，改用：

python -m pip install --user pymupdf

DEP_MISSING 的 msg 里已经按当前平台和缺失的包把命令拼好了，照着执行再重试即可。 LibreOffice 在 Windows 上用 winget install --id TheDocumentFoundation.LibreOffice -e 装， 安装器不会把它加到 PATH，但 --method soffice 会自己去 %ProgramFiles%\LibreOffice\program\ 找。

调试指南

调用失败或输出不符合预期时：

1. verifier <family> <subcmd> --help 看完整参数与默认值。
2. 用 Read 打开 skills/verifier-hub/lib/<family>.py 读源码，每个家族不超过 400 行。
3. DEP_MISSING → 按 msg 里给的 pip install --target 命令装包后重试。
4. LOCATOR_INVALID / NOT_FOUND → 先用 xlsx list-sheets、docx outline、docx table-list 把结构列出来，再选 cell / heading / row-header。
5. BAD_ARGS → msg 里带了 argparse 的原文，照着补参数。

何时不要用 verifier

• 主观判断类的问题（图表是否美观、语气是否专业）：工具拿不到决定性证据，老老实实读内容再下判断。
• 需要看实际渲染效果的问题（HTML 显示效果、PPT 整体视觉）：verifier 只能读元素，判断不了「看起来对不对」。 这类问题用 artifact-preview 渲染成图片再看。

结构、数值、关键字、格式、占位符这几类，verifier 都能给出比模型自己读一遍更可靠的判定。

评分员模式

如果当前工作区里存在 questionnaire.md、rubric_index.yaml、run_verifiers.py 这些评分文件， 说明这是 questionnaire 评分任务，工作流和上面的交付前自检不同， 见 references/questionnaire.md。 工作区里没有这些文件时，忽略这一节。