yzsp-studio/mediakit-shared-suite / verifier-hub
verifier-hub
VerifiedDeterministic artifact verifier CLI (file/xlsx/docx/pdf/pptx/text/archive/rubric) for pre-delivery artifact checks and agentic judges. 58 subcommands callable as `verifier {family} {subcmd} [args]`. Use before delivering or uploading a file, or whenever you need to check file format, sheet/section presence, cell values, formulas, keywords, character counts, page counts, placeholders, signatures or zip contents, instead of guessing from an LLM reading. Every call prints one JSON object with a quotable `evidence` field.
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下,不在顶层)。
交付前校验流程
- 定位待交付文件:确认文件真实存在,路径和扩展名正确。
- 格式校验:对每个文件至少跑一次
./skills/verifier-hub/bin/verifier rubric check-file-format <path> --expected-ext <.ext> - 内容校验:按文件类型补一条与任务直接相关的检查,例如
- 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
- xlsx:
- 记录证据:交付说明里只引用真实执行过的 verifier 命令和它的输出。不要把自己用 Python 或 Bash 算出来的结果说成 verifier 证据。
- 再交付:所有待上传文件都通过校验后再交付。
工具族总览
| 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\ 找。
调试指南
调用失败或输出不符合预期时:
verifier <family> <subcmd> --help看完整参数与默认值。- 用 Read 打开
skills/verifier-hub/lib/<family>.py读源码,每个家族不超过 400 行。 DEP_MISSING→ 按msg里给的pip install --target命令装包后重试。LOCATOR_INVALID/NOT_FOUND→ 先用xlsx list-sheets、docx outline、docx table-list把结构列出来,再选 cell / heading / row-header。BAD_ARGS→msg里带了 argparse 的原文,照着补参数。
何时不要用 verifier
- 主观判断类的问题(图表是否美观、语气是否专业):工具拿不到决定性证据,老老实实读内容再下判断。
- 需要看实际渲染效果的问题(HTML 显示效果、PPT 整体视觉):verifier 只能读元素,判断不了「看起来对不对」。
这类问题用
artifact-preview渲染成图片再看。
结构、数值、关键字、格式、占位符这几类,verifier 都能给出比模型自己读一遍更可靠的判定。
评分员模式
如果当前工作区里存在 questionnaire.md、rubric_index.yaml、run_verifiers.py 这些评分文件,
说明这是 questionnaire 评分任务,工作流和上面的交付前自检不同,
见 references/questionnaire.md。
工作区里没有这些文件时,忽略这一节。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |