UA1 Validator Agent

UA1 Validator Agent 技能

使用此技能可在 agent 工作流中执行确定性的 PDF/UA-1 合规性检查。

接口端点

• 健康检查：GET https://api.ua1.dev/api/health
• 验证：POST https://api.ua1.dev/api/validate
• 精简模式：POST https://api.ua1.dev/api/validate?format=compact
• 指标：GET https://api.ua1.dev/api/metrics

必需的请求契约

以 multipart/form-data 格式提交，文件字段名为 file。

• 支持格式：.pdf

• 典型响应状态码：

  • 200：返回验证结果
  • 415：不支持的文件类型
  • 413：文件过大
  • 429：请求频率超限（被限流）

Agent 最小工作流

1. 批量验证前，先执行一次健康检查（health）。
2. 使用精简模式（compact）逐个验证 PDF 文件，确保解析结果具有确定性。
3. 若校验结论（verdict）为 fail，提取全部发现项（findings），并按 rule_id 分组聚合。
4. 生成修复方案（remediation plan），按规则出现频次降序排列。
5. 修复完成后重新运行验证，并比对问题数量变化。

脚本调用方式

执行以下命令：

bash scripts/validate_pdf.sh /absolute/or/relative/path/to/file.pdf

可选环境变量：

• UA1_API_BASE（默认值：https://api.ua1.dev）
• UA1_FORMAT（默认为 compact；设为 full 可获取完整响应载荷）

CI 质量门禁模式

将非 pass 的校验结论视为质量门禁失败：

• 仅当 verdict 为 pass 时，进程退出码为 0
• 当 verdict 为 fail 时，退出码为 2
• 发生网络传输或 API 错误时，退出码为 1

可直接在 CI/CD 流水线中使用该脚本的退出码进行条件判断。

命令行