Saccade

MCP 注册表：io.github.Tavrin/saccade

saccade

saccade 是一款面向人类、CI 和 AI Agent 的视觉与性能证据工具。 它会测量感知差异，在测量区域中定位差异（也可选择添加参考性观察），并依据你声明的阈值和策略进行检查。它会生成离线 HTML 报告和带版本的 JSON。 性能结论需要基于可比较的采集结果、计时溯源信息和重复证据。 只有人类可以批准基线。

快速入门

saccade demo --out saccade-demo
saccade view saccade-demo

此演示会故意以状态码 1 退出：其中包含发生变化和缺失的采集结果。 打开 saccade-demo/report/index.html 查看结果。快速入门指南提供了可复制的示例，涵盖比较、精确身份识别、配置、证据导出和本地审查。 不确定该使用哪个命令？请查看任务索引 和以下五份经过测试的指南：视觉 CI、 受控渲染、 文档导出、 媒体接入和 交付调优。saccade doctor 会显示你的安装可以运行哪些内容。

使用场景

编码 Agent 的视觉验证

本地 MCP 服务会读取已注册的采集根目录，并将报告写入单独的输出根目录。其工具无法批准基线。Agent 可以检查有界结果，并按记录的后续操作继续执行。

saccade mcp --root captures --out-root agent-reports
saccade compare captures/before captures/after --out agent-reports/change --json

请参阅 Agent 指南和 MCP 与插件设置。

CI 视觉回归

本地 Playwright 包提供 toMatchSaccade 和采集稳定功能。 扫描会对页面对进行分组，并将采集失败记录为失败。

node integrations/playwright/sweep.cjs sweep.json captures capture-options.json
saccade sweep compare sweep.json --captures captures/captures.json --out sweep-report --json

请参阅 Playwright 匹配器、扫描 和 CI 集成。扫描需要可选的 products 功能。

渲染与引擎证据

声明式空间策略可以区分 texture_noise_only 和 systematic_shift。必需效果检查可以在足迹为空时判定失败； 采集层会限制测量范围，固定摄像机序列则会测量时间稳定性。请在输入中提供策略和采集溯源信息。

saccade compare before after --config render-evidence.toml --out render-report --json
saccade experiment sequence before-frames after-frames --fixed-camera --out temporal-report --json

请参阅渲染证据、 引擎采集导入、 时间稳定 和单标志掩码。

图像交付调优

审查已提供的格式，并搜索声明的编码，以达到指定的感知目标。 本地和 URL 模板适配器会记录字节数和内容类型，且不会修改原始文件。

saccade imgtune audit --urls images.txt --accept 'image/avif,image/webp,image/*' --out audit.json --json
saccade imgtune search tuning.json --out tuning-report.json --json

请参阅图像调优。启用 products，AVIF 还需启用 imgtune-avif。

媒体分析记录

媒体记录会保留元数据、质量、指纹和可选模型部分的状态及溯源信息。已禁用或失败的部分也会如实记录。 Python 包和本地 HTTP API 使用相同的分析路径。

saccade analyze-media image.jpg --profile cpu-lite --output-size 1200x800 --json
saccade keyframes video.mp4 --out frames --json

请参阅媒体分析、Python和 HTTP API。 使用 pip install saccade-vision 安装（Python 3.10+）；导入方式仍为 import saccade。

单图溯源与完整性

在没有基准图的情况下，检查 C2PA 凭证、元数据和压缩历史指标。启发式方法有明确的局限，无法判定真假。GPS 信息仅在选择启用时披露；验证 C2PA 需要启用 credentials。

saccade inspect-image received.jpg --output-size 1600x900 --out inspection --json
saccade inspect-image received.png --hash-index hashes/saccade-hash.v1.json --out indexed-inspection --json

参见单图检查。

常规比较

根据问题选择配准、哈希、嵌入相似度/搜索、OCR 文本差异、无参考质量评估或文档栅格化。 模型工作流需要提供固定版本的制品和相应功能。

saccade compare before.png after.png --align similarity --out aligned-report --json
saccade text before.png after.png --out text-report --json
saccade assess image.jpg --out quality-report --json

参见如何选择比较方式、 配准、哈希、 嵌入与搜索、OCR、 质量和文档。

性能证据

使用配对统计和不确定性区间比较随附的计时旁文件，或定位序列中的变化。Saccade 不会运行基准测试；缺失或被拒绝的溯源信息不能作为性能提升的依据。

saccade compare before after --out perf-report --json
saccade history onset --store history --json

参见配对统计、 变化点、身份/性能、 计时判定、 消融表 和报告关联。 性能旁文件套件为生产者提供固定样例和操作配方。 标签图像可使用掩码指标评分，边界框可通过 COCO 或 YOLO 格式交换（边界框交换），提取的视频帧可用帧映射描述。

安装

使用 Rust 1.89 或更高版本安装：

cargo install saccade --version 0.3.0 --locked
saccade doctor --json

要构建此检出版本，请使用 cargo install --locked --path crates/saccade。 发布归档包含校验和、许可协议和第三方声明。参见发布说明。

Cargo 功能	默认启用？	用途和要求
compression, parallel, graphics	是	FLIP、压缩评分、图形和时间测量；由 CPU 处理。
ai, evaluation	是	提供方审查适配器和评估；调用需要明确授权并设置预算。
workbench, mcp	是	本地报告浏览和受限 Agent 工具。
assist	否	实验性的解释、掩码审计、可见条件检查和批量建议。
products	否	Sweep、图像调优、设计源和通知程序适配器。浏览器采集另需 Node.js 和 Playwright。
imgtune-avif	否	AVIF 编码/解码；需要系统 dav1d >=1.3.0 开发库和 pkg-config。
semantic-regions, embeddings, local-models	否	固定版本的 CPU 模型制品，以及动态加载的 ONNX Runtime 1.22（API 22）。运行时/模型拉取属于明确的配置操作；分析过程不会下载它们。
ocr, ocr-provider	否	使用固定版本模型/运行时的本地 PP-OCRv5 拉丁语 OCR；另有可选择启用的托管文档 OCR，并配备支出/数据外传控制。
documents, credentials	否	SVG/PDF 栅格化和离线 C2PA 验证。
media-http	否	用于媒体分析的受限 URL 输入；网络获取需要明确提供 URL 输入。
local-vlm, vision-providers	否	已配置的本地/托管视觉适配器；观测结果仅作建议。
geometry, dense-motion, prechecks, schema	否	网格测量、稠密运动、实验性安全/无障碍检查和模式生成。

视频提取会调用外部 ffmpeg 和 ffprobe；两者均未打包。 参见模型/运行时配置和AVIF 先决条件。 默认比较无需提供方账户或 GPU。可通过 cargo install ... --features products,ocr 添加可选功能，例如。

Crates

Crate	用途
saccade-core	共享图像测量、证据契约和 Rust 工作流。
saccade-print	采用 ICC 管理的打印栅格图像比较与诊断。
saccade-geo	带有网格和 nodata 元数据的原生 TIFF 测量。
saccade-a11y	对已声明区域或自行识别的区域执行无障碍预检查。
saccade	命令行界面和 MCP 服务。
saccade-py	共享测量的 Python 绑定。

启用 prechecks 功能后，a11y auto 会离线查找图像中的文本和 UI 区域 并进行检查：

saccade a11y auto screenshot.png --out accessibility-report

指标和算法

每项认证仅涵盖记录在案的契约和证据。得分通过并不能证明结果正确， 也不能证明差异不可见。

指标或算法	认证状态和范围
原生解码样本一致性	精确相等契约；仅涵盖提供的完整样本对。
NVIDIA FLIP / HDR-FLIP	有参考依据的实现；必须声明观看条件和 HDR 映射。
SSIMULACRA2 / Butteraugli 0.9.3	已记录参考检查；感知目标由用户策略决定。参见实现证据。
ColorVideoVDP、数值缓冲区、运动和网格距离	已声明显示器/单位/帧/相机契约；夹具检查不能认证使用方的渲染器。
配准；aHash/dHash/pHash；FAST/定向 BRIEF 匹配	已通过生成夹具验证；匹配置信度未经校准。
嵌入相似度和图像/文本检索	模型/导出来源已固定；检索校准仍未获认证。
PP-OCRv5 拉丁文本和位置文本差异	已审查生成的严格和排版契约；特定字体的失败仍然存在。
模糊、噪声、块效应、条带、剪裁和取证指标	描述性、依赖内容的启发式方法；未获真实性认证。
空间类别、效果占比、图层和时间切片	基于构造/夹具的契约；未获通用渲染器或物理效果认证。
配对 Hodges–Lehmann 估计、bootstrap 和变点	基于构造的统计检查；实际计时需要独立且经过认证的运行。
安全/无障碍预检查	实验性检查；不代表认证或正式合规。
AI 辅助、Jev 支持和路由（Jev 是 TypeSafe 的决策模型）、盲序处理	此版本中未获认证；均为实验性功能。
LPIPS、DISTS、MUSIQ（quality-score）	仅运行你提供的、经过审查的导出模型（local-models 构建，已拉取运行时）；默认不附带或下载固定检查点，因此标准安装会以状态码 2 退出，并指出缺失项。
TrustMark 载荷解码	可选的本地 TrustMark Q 解码器，支持已验证的载荷位、BCH 架构和纠错状态。参见 TrustMark。

AI 层

AI 观察结果仅供参考。它们不能批准基线、创建排除项、覆盖确定性失败、 确立相等性或认证计时。提供方需选择启用，并受源根目录外传授权、专用凭据文件 以及调用/费用上限约束；图像文本和提供方输出都属于数据，绝不是指令。

带 $15 上限的发布认证尝试在前置条件检查阶段就已停止，未发起任何提供方请求， 也未产生费用。未提供包含已观察到的不可变 Gemini 修订版或精确来源重型收据的冻结语料库。 Explain、遮罩审计、可见条件检查、盲序、Jev 支持、确定性级联路由和可选 Jev 证据路由 均仍未获认证。辅助命令仍需使用 --experimental；Jev 路由默认关闭。 参见辅助工作流、认证策略 和发布指南。

已知限制

• OCR 可能会误读大号衬线文本中的 œ，也可能漏掉某些无衬线字体中的破折号； 漏掉字符以及 € 前缺少空格仍属于错误。
• 检索分数缺乏经过验证的校准。模型／运行时冒烟测试只能验证执行情况，不能证明生产环境中的准确性或导出结果的一致性。
• GI 占用率使用提供的蒙版／图层作为代理指标；它无法证明实际光照、因果关系或渲染正确性。
• LPIPS、DISTS 和 MUSIQ 没有随附检查点（quality-score 需要你审核过的导出文件）；TrustMark Q 解码需要显式配置本地模型。
• 捕获内容界定了证据范围。图像相同不能证明应用程序正确，感知层面的通过也不能证明原生样本身份一致。
• 性能结论需要匹配的工作负载、时钟、预热过程以及重复测试噪声。 未执行的检查仍属未知；人工审批记录无法验证操作者身份。

文档与集成

• 文档、CLI 参考 和 JSON 合约／架构。
• MCP 服务与插件、Agent 指南、 Python 包（PyPI：saccade-vision）、 HTTP API 和 CI。
• 更新日志、发布指南 和贡献指南。

9 个可复现案例，包含命令、预期退出结果和测量输出。 Pages 展示集。

许可证

你可以选择采用 MIT 或 Apache-2.0 许可证。 FLIP 使用 BSD-3-Clause 许可的 flip-rs 移植版本。请参阅第三方声明； 发布归档中也包含生成的依赖声明。

MCP Registry 所有权：mcp-name: io.github.Tavrin/saccade

Saccade 起源于 Moss 引擎的视觉测试工具。

使用可选的 optical-code feature，可在视觉比较之外独立验证最终 QR／条码载荷；PDF／SVG 页面还需要 documents。

Rust 调用方可使用 saccade-core 工作流，无需 CLI 调度即可进行命令级比较、审批、历史记录、清单、批处理和审核。