name: ai-visual-accuracy-check description: 使用AI比较渲染的HTML与原始PDF页面。AI基于可解释的推理对视觉准确性进行上下文判断。BLOCKING质量门 - 如果分数低于85%则停止流水线。

AI视觉准确性检查技能

目的

这是一个BLOCKING质量门，使用AI验证生成HTML相对于原始PDF页面的视觉准确性。与像素级完美比较不同，AI能够理解：

视觉层次和布局意图
上下文差异（网页渲染 vs PDF）
读者是否会有相似的体验
CSS限制与HTML准确性之间的权衡

AI提供：

客观相似度分数（0-100%）
按评估标准细分
具体差异说明
清晰的通过/失败建议
决策解释

这结合了AI的上下文理解与确定性门控（必须达到85分以上才能继续）。

操作步骤

加载输入文件
- 读取 chapter_XX.html（生成的整合HTML）
- 读取 02_page_XX.png（原始PDF页面图像）
将HTML渲染为图像
- 使用无头浏览器（Playwright/Selenium）将HTML渲染为PNG
- 捕获完整页面截图
- 保存渲染图像用于比较
调用Claude进行视觉比较
- 附加原始PDF PNG作为图像1
- 附加渲染的HTML截图作为图像2
- 请求详细的视觉比较
- 要求AI按多个标准评分
解析AI响应
- 提取总体相似度分数
- 提取标准特定分数
- 解析记录的差异
- 获取建议（通过/失败）
保存比较报告
- 保存到：output/chapter_XX/chapter_artifacts/ai_visual_accuracy.json
- 包含时间戳、使用的输入、AI模型
做出门控决策
- 如果分数 ≥ 85：通过（退出代码0，继续）
- 如果分数 < 85：失败（退出代码1，触发钩子）

输入参数

html_file: <str>          - chapter_XX.html的路径
pdf_page_png: <str>       - 原始PDF页面PNG的路径（或多页时多个）
output_dir: <str>         - 报告目录
chapter: <int>            - 章节编号（用于报告）
book_pages: <str>         - 页面范围（用于报告）
threshold: <float>        - 通过的最低分数（默认：85.0）

AI提示模板

您正在验证生成的HTML页面相对于原始PDF的视觉准确性。

原始PDF页面：
[附加原始PDF页面的PNG图像]

生成的HTML（已渲染）：
[附加已渲染HTML页面的PNG图像]

任务：
比较这两张图像，并确定HTML是否准确重现了PDF页面的视觉外观和布局。

评估标准：

1. 布局匹配（权重40%）
   - 整体页面结构与原始匹配
   - 部分顺序和位置正确
   - 元素之间的间距适当
   - 页面尺寸/宽高比相似

2. 视觉层次（权重30%）
   - 标题突出，具有适当的显著性
   - 部分分隔清晰可见
   - 强调（粗体、斜体）保留或等效
   - 元素之间的视觉关系清晰

3. 内容定位（权重20%）
   - 元素正确对齐（左、中、右）
   - 列表缩进，间距适当
   - 表格/图表定位和对齐正确
   - 段落流与原始匹配

4. 排版与样式（权重10%）
   - 字体大小相对关系正确
   - 文本样式适当（粗体、斜体、大写）
   - 配色方案保留（如适用）
   - 整体可读性相当或更好

评分指南：

对于每个标准：
- 90-100%：优秀，无问题
- 80-89%：良好，微小外观差异
- 70-79%：可接受，明显但非关键差异
- 低于70%：差，显著差异

重要上下文：
- 浏览器中的HTML渲染可能与PDF略有不同（间距、字体）
- 关注意图和可读性，而非像素级完美匹配
- 小的间距/边距差异（2-5像素）可接受
- 字体渲染差异可接受，如果层次保留
- Web渲染限制可接受（无绝对PDF定位）

输出格式：

请按此确切JSON格式提供您的分析：

```json
{
  "overall_score": 92.5,
  "threshold": 85.0,
  "recommendation": "PASS",
  "criteria_analysis": {
    "layout_match": {
      "score": 94,
      "feedback": "整体页面结构匹配良好。部分顺序正确，间距适当。"
    },
    "visual_hierarchy": {
      "score": 90,
      "feedback": "标题清晰区分。视觉关系保留。微小字体大小差异可接受。"
    },
    "content_positioning": {
      "score": 91,
      "feedback": "元素对齐正确。列表正确缩进。表格定位正确。"
    },
    "typography_styling": {
      "score": 88,
      "feedback": "文本样式保留。粗体和斜体区分清晰。可读性优秀。"
    }
  },
  "differences_noted": [
    "段落行高1.6 vs PDF中的1.5（可接受，提高可读性）",
    "项目符号列表缩进20px vs PDF中的15px（可接受，清晰可读）"
  ],
  "visual_fidelity_assessment": "EXCELLENT",
  "confidence_level": 0.95,
  "explanation": "HTML准确重现了PDF页面布局和视觉层次。所有主要元素定位正确。微小的间距和字体差异在Web渲染的可接受容差范围内，实际上提高了可读性。",
  "pass_fail_verdict": "PASS"
}

验证：

总体分数必须是数字（0-100）
所有标准必须有分数
建议必须是通过或失败
解释必须清晰且可操作


## 处理流程

┌─ 加载HTML和PNG ──────────────────┐ │ • chapter_XX.html │ │ • 02_page_XX.png │ └────────┬────────────────────────────┘ │ ▼ ┌─ 将HTML渲染为PNG ───────────────┐ │ • 无头浏览器 │ │ • 完整页面截图 │ │ • 保存到临时位置 │ └────────┬────────────────────────────┘ │ ▼ ┌─ 调用Claude API ────────────────┐ │ • 发送原始PDF PNG │ │ • 发送渲染的HTML PNG │ │ • 多模态比较提示 │ │ • 请求JSON响应 │ └────────┬────────────────────────────┘ │ ▼ ┌─ 解析并保存报告 ────────────────┐ │ • 从响应中提取JSON │ │ • 验证分数0-100 │ │ • 保存到JSON文件 │ └────────┬────────────────────────────┘ │ ▼ ┌─ 门控决策 ──────────────────────┐ │ • 如果分数 ≥ 85：通过 │ │ • 如果分数 < 85：失败 │ └────────┬────────────────────────────┘ │ ▼ 退出代码0或1


## 输出文件格式

**路径**：`output/chapter_XX/chapter_artifacts/ai_visual_accuracy.json`

```json
{
  "chapter": 2,
  "book_pages": "16-29",
  "validation_type": "ai_visual_accuracy",
  "validation_timestamp": "2025-11-08T14:45:00Z",
  "overall_score": 92.5,
  "threshold": 85.0,
  "status": "PASS",
  "ai_model": "claude-3-5-sonnet-20241022",
  "inputs": {
    "html_file": "chapter_02.html",
    "original_pdf_png": "02_page_16.png",
    "rendered_html_png": "rendered_chapter_02.png"
  },
  "criteria_scores": {
    "layout_match": 94,
    "visual_hierarchy": 90,
    "content_positioning": 91,
    "typography_styling": 88
  },
  "differences": [
    "段落行高1.6 vs PDF中的1.5（可接受）",
    "项目符号列表缩进20px vs PDF中的15px（可接受）"
  ],
  "visual_fidelity": "EXCELLENT",
  "confidence": 0.95,
  "explanation": "HTML准确重现了PDF页面布局和视觉层次...",
  "recommendation": "PASS",
  "notes": "所有标准均在可接受范围内。微小的Web渲染差异不影响可读性或意图。"
}

多页章节

对于跨越多页的章节：

选项A：比较关键页面
- 比较起始页（建立样式）
- 比较中间页（延续页）
- 比较最终页（一致性检查）
- 跨页面平均分数
选项B：比较整合视图
- 渲染完整整合章节
- 比较整体结构
- 视觉抽查特定页面

方法：使用选项A进行彻底验证

分别评分每个页面（0-100）
平均得到总体分数
报告每页细分

门控决策阈值

分数 ≥ 85：通过 → 继续部署
分数 < 85：失败 → 触发钩子，阻止流水线

解释：
  90-100：优秀，无担忧
  85-89：良好，微小外观差异可接受
  < 85：需要审查并可能需要修复

错误处理

如果HTML渲染失败：

记录错误详情
尝试替代渲染方法
如果两者都失败则升级

如果AI响应是无效JSON：

请求重试
必要时回退到文本解析
如果重复失败则升级

如果分数似乎错误（过高/过低）：

AI的判断优先
信任AI的上下文理解
记录以供未来分析

如果原始PNG缺失：

直接从PDF使用参考页
或从PDF重新提取
使用最佳可用图像继续

质量检查

保存报告前：

分数有效性
- [ ] 总体分数0-100
- [ ] 所有标准分数0-100
- [ ] 分数合理且合理
报告完整性
- [ ] 包含所有标准
- [ ] 差异记录
- [ ] 提供解释
- [ ] 建议清晰
AI推理
- [ ] 解释与分数匹配
- [ ] 差异解释分数扣减
- [ ] 置信水平适当

成功标准

✓ 视觉准确性报告成功生成 ✓ 总体分数计算并合理 ✓ 所有标准评分并解释 ✓ 差异清晰记录 ✓ 通过/失败决策清晰 ✓ 如果通过则退出代码0，如果失败则1 ✓ 报告以JSON格式保存

通过后的后续步骤

如果验证通过（分数 ≥ 85）：

门控决策：通过
继续部署批准
章节准备就绪可用于生产

失败后的后续步骤

如果验证失败（分数 < 85）：

流水线停止
触发钩子 calypso-visual-accuracy.sh
用户收到包含视觉比较详情的报告
选项：
- 审查差异并重新生成
- 调整CSS样式
- 如果差异可接受则降低阈值
- 如果合理则手动覆盖

设计说明

此技能是AI驱动的（概率性）
使用视觉推理（非像素差异）
做出上下文判断（理解意图）
提供可解释的决策（清晰推理）
作为BLOCKING门控（分数必须通过阈值）
属于质量保证（确保视觉准确性）

测试

测试AI视觉准确性：

# 生成章节HTML（先前步骤）
# 渲染为PNG
# 与原始PDF比较

# 预期行为：
# - AI比较图像
# - 评分布局、层次、定位、排版
# - 生成包含分数和解释的报告
# - 返回通过（分数 ≥ 85）或失败（分数 < 85）

相对于Python像素差异的关键优势

方面	Python像素差异	AI视觉比较
理解	检测变化	理解意图
灵活性	需要精确匹配	接受有效变化
解释	像素坐标	语义反馈
容差	二进制（匹配/不匹配）	分级（85%+可接受）
上下文	无上下文	完整视觉上下文
类人	否	是，类似QA审查员

AI视觉准确性验证比像素级完美比较更智能、更类人。