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. 再交付：所有待上传文件都通过校验后再交付。

工具族总览

family	子命令数	典型用途
file	4	列产物 / 校验可打开 / 抽文本 / 计数
xlsx	12	sheet、cell、公式、格式、求和、列号格式；含 eval-formula 跨 cell 回算
docx	12	大纲、章节抽取、表格、修订标记、签字块、布局、页数、图片计数、页面设置
pdf	4	页数与方向、抽文本、CJK 字体检测、图片计数
pptx	4	slide 列表、抽文本、按 regex 找 slide、图表与图片计数
text	9	关键词、正则计数、章节字数、中文占比、引用、占位符、列表项、日期
archive	2	zip 内容列表、必含条目断言
rubric	11	高层 DSL：把常见组合一行搞定，含跨文件数值一致性校验

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

错误码

code	含义
FILE_NOT_FOUND	文件不存在
NOT_A_FILE	路径存在但不是普通文件
BAD_EXT	扩展名与预期不符
PARSE_ERROR	文件存在但所选库打不开（损坏 / 格式不对）
LOCATOR_INVALID	--cell / --range / --locator 形式错误
NOT_FOUND	sheet / heading / row-header / table-index 不存在
DEP_MISSING	需要的 Python 包或 LibreOffice 不可用，msg 里带可执行的安装命令
BAD_ARGS	参数缺失、类型错、family 或子命令名写错
INTERNAL	不属于以上任何一类（dispatcher 兜底包装）

依赖与环境

用途	需要什么	缺了会怎样
xlsx 家族	openpyxl	DEP_MISSING
docx 家族	python-docx	DEP_MISSING
pptx 家族	python-pptx	DEP_MISSING
pdf 家族、file extract-text（PDF）、docx page-count --method soffice	pymupdf、pdfplumber、pypdf 三者之一，按此顺序选用	三个都没有才 DEP_MISSING；结果里的 backend 字段会写明实际用的是哪个
text、archive 家族	只用标准库	不会缺
docx page-count --method soffice	LibreOffice 二进制	DEP_MISSING；--method auto 会自动退到 XML 启发式，并在 soffice_fallback_reason 里说明原因

安装缺失的 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。 工作区里没有这些文件时，忽略这一节。