AI HTML生成技能

目的

此技能利用AI的概率生成能力将PDF页面重新创建为语义HTML。AI接收三种互补的输入，共同提供完整的上下文：

视觉参考（PNG图像）- 页面布局和视觉层级
文本数据（rich_extraction.json）- 准确的文本内容和格式化元数据
结构预览（ASCII文本）- 逻辑布局和元素关系

这种三输入方法确保AI不仅理解要包含哪些文本，还理解在HTML中如何语义化地结构化。

输出是概率性的（AI生成），但将通过后续技能中的验证门控使其确定性。

操作步骤

准备三个输入文件
- 加载02_page_XX.png（图像文件）
- 加载01_rich_extraction.json（带有元数据的文本跨度）
- 加载03_page_XX_ascii.txt（结构预览）
构建AI提示
- 附加PNG图像作为视觉参考
- 包含提取的文本数据（JSON）
- 包含ASCII预览（文本表示）
- 提供特定的生成要求
调用Claude API带有完整上下文
- 发送多模态提示（文本+图像）
- 请求语义HTML5输出
- 指定CSS类和结构要求
解析并保存生成的HTML
- 从AI响应中提取HTML
- 验证基本的良构性
- 保存到持久文件中，并附加元数据
记录生成元数据
- 记录使用的AI模型
- 生成时间戳
- 列出使用的输入文件
- 存储来自AI的任何置信度指标

输入文件（来自先前技能）

输入1:渲染的PDF页面（PNG）

文件：output/chapter_XX/page_artifacts/page_YY/02_page_XX.png

PDF页面的高分辨率渲染
300+ DPI用于视觉清晰度
显示实际页面外观
用于视觉布局理解

输入2:丰富的提取数据（JSON）

文件：output/chapter_XX/page_artifacts/page_YY/01_rich_extraction.json

带有完整元数据的文本跨度
字体名称、大小、粗体/斜体标志
位置信息（边界框）
序列和关系

输入3:ASCII预览（文本）

文件：output/chapter_XX/page_artifacts/page_YY/03_page_XX_ascii.txt

基于文本的结构表示
标记了标题层级
识别了列表和项目符号
记录了段落流程
注释了元素类型

AI提示模板

发送给Claude的提示：

你正在将PDF教科书页面重新创建为语义HTML5。

你有关于这个页面的三部分信息：
1. 视觉渲染（PNG图像）- 用于理解布局
2. 解析的文本数据（JSON）- 确保准确性
3. ASCII结构预览（文本）- 用于理解元素关系

视觉参考：
[附加PNG图像]

解析的文本数据：
[附加JSON]

结构预览：
[附加ASCII文本]

任务：
生成准确地重现本页的语义HTML5。

要求：

1. HTML5结构：
   - 适当的DOCTYPE，html，head，body标签
   - Meta charset="UTF-8"
   - Meta视口用于响应式设计
   - 标题标签，带有描述性文本

2. 内容包装器：
   - 单个<div class="page-container">包装器
   - 单个<main class="page-content">用于所有内容
   - 没有分页或分页结构

3. 语义HTML元素：
   - 根据层级使用适当的标题标签（h1-h6）
   - 使用<p>用于段落
   - 使用<ul>和<li>用于项目列表
   - 如果有数据表，则使用<table>
   - 使用<figure>和<figcaption>用于图像/展览

4. 语义CSS类：
  根据检测到的元素类型应用这些类：

页面结构：
   - page-container（主包装器）
   - page-content（内容区域）
   - chapter-header（章节开头部分）
   - chapter-number（数字章节标记）
   - chapter-title（章节主标题）

内容元素：
   - section-heading（主要部分，h2）
   - subsection-heading（次要部分，h3-h4）
   - paragraph（正文文本，p）
   - bullet-list（ul）
   - bullet-item（li）

导航与结构：
   - section-navigation（主题/部分列表）
   - nav-item（单个导航项）
   - section-divider（hr分隔线）

特殊元素：
   - exhibit（表格或图形）
   - exhibit-table（实际表格）
   - exhibit-title（图形/表格标题）
   - image-placeholder（用于嵌入图像）

5. 内容保护和边界完整性：
   - 包含所有文本内容
   - 保持确切的文本（不进行改写或编辑）
   - 保持原始结构和关系
   - 不省略或跳过部分

   CRITICAL - 页面边界规则：
   - 从JSON开始的地方开始页面内容
   - 在JSON结束的地方结束页面内容
   - 从不添加桥接文本、连接词或完成短语
   - 从不发明过渡词或句子
   - 从不合成内容以“平滑”页面过渡
   - 页面可以从句中开始或结束 - 这是预期和正确的
   - 如果一个句子看起来不完整，那就是准确的页面边界
   - 你的HTML中的每一个单词都必须存在于源JSON中

6. 标题层级：
   - 遵循逻辑层级（h1 → h2 → h3 → h4）
   - 不跳过层级（不要从h1跳到h4）
   - 章节标题是h1（如果存在）
   - 主要部分是h2
   - 小节是h3或h4，视情况而定

7. 列表格式化：
   - 包装在<ul class="bullet-list">
   - 每个项目在<li class="bullet-item">
   - 保持项目顺序和分组
   - 包含所有项目文本

8. CSS样式表链接：
   - 包含：<link rel="stylesheet" href="../../styles/main.css">
   - 使用相对路径（向上两级到根目录）
   - 此样式表提供所有样式

9. 特殊处理：
   - 段落中的粗体文本：使用<strong>标签
   - 斜体文本：使用<em>标签
   - 嵌入图像：使用<img>标签，带有src路径和alt文本
   - 展览/表格：保持结构和标题

输出格式：

返回ONLY有效的HTML5。不包括解释。

```html
<!DOCTYPE html>
<html lang="en">
<head>
    ...
</head>
<body>
    ...
</body>
</html>

验证：

HTML必须是有效的HTML5
所有开放标签必须有闭合标签
类属性必须使用正确的类名
JSON中的所有文本内容必须包含
没有添加不在源JSON提取中的文本
覆盖率必须是99-100%（>100%表示发明内容=失败）
你的HTML中的每一个单词都必须来自提取数据


## 流程图

┌─ 加载输入文件 ─────────────────────┐ │ • 02_page_XX.png（图像） │ │ • 01_rich_extraction.json（文本数据） │ │ • 03_page_XX_ascii.txt（结构） │ └────────┼────────────────────────────────┘ │ ▼ ┌─ 构建提示 ─────────────────────┐ │ • 附加PNG图像 │ │ • 包含JSON数据 │ │ • 包含ASCII预览 │ │ • 添加生成要求 │ └────────┼────────────────────────────────┘ │ ▼ ┌─ 调用Claude API ────────────────────┐ │ • 多模态提示 │ │ • 视觉+文本理解 │ │ • 确定性系统指令 │ └────────┼────────────────────────────────┘ │ ▼ ┌─ 提取&保存HTML ──────────────────┐ │ • 解析AI响应 │ │ • 提取HTML块 │ │ • 基本验证（标签闭合） │ │ • 保存到04_page_XX.html │ └────────┼────────────────────────────────┘ │ ▼ ┌─ 记录生成元数据 ──────────────┐ │ • 模型名称和版本 │ │ • 输入文件引用 │ │ • 时间戳 │ │ • 保存到05_generation_metadata.json │ └────────┼────────────────────────────────┘ │ ▼ ┌─ GATE 1:验证文本内容 ──────────┐ │ 强制 - 不要跳过 │ │ │ │ 运行每页文本验证： │ │ python3 Calypso/tools/ │ │ verify_text_content.py 1 <page> │ │ │ │ 检查覆盖率： │ │ • 99-100% = PASS，进入下一页 │ │ • 95-98% = WARNING，审查内容 │ │ • >100% = FAIL，重新生成（幻觉） │ │ • <85% = FAIL，重新生成页面 │ │ │ │ 严重：永远不要合并页面 │ │ 直到所有单独页面通过✓ │ └────────┼─────────────────────────────┘ │ ▼ ✓ 完成 - 准备验证


## GATE 1:强制每页文本验证

**这是防止错误内容进入合并的保险。**

生成每页HTML后，使用上述AI提示：

1. **立即运行验证：**
   ```bash
   python3 Calypso/tools/verify_text_content.py <chapter_num> <page_num>

解释结果：
- 99-100%覆盖率：PASS✅ - 文本与提取JSON精确匹配，进入下一页
- 95-98%覆盖率：WARNING⚠️ - 文本差异较小，手动审查内容以确保无损失
- 85-95%覆盖率：WARNING⚠️ - 一些文本丢失/修改，手动审查内容
- >100%覆盖率：FAIL❌ - 添加了不在原始页面中的内容（AI幻觉），立即重新生成
- <85%覆盖率：FAIL❌ - 关键内容丢失，重新生成
如果验证失败（<85%覆盖率）：
- 立即停止
- 不要进入下一页
- 不要合并章节
- 审查HTML - 检查是否包含：
  - 来自不同页面的内容（生成了错误的页面）
  - 缺少部分或主要文本块
  - 损坏或重复的内容
- 使用AI提示重新生成页面
- 重新运行验证
- 只有在覆盖率≥95%时才继续

FAIL示例：

额外内容（>100% - AI HALLUCINATION）：

第16页HTML包含301个单词
第16页JSON应该有297个单词
覆盖率：101.2% = FAIL❌（>100%）
→ 额外4个单词=AI发明的桥接文本
→ 示例：AI添加了“所有土地也包括”这在源中不存在
→ 立即重新生成第16页，严格遵守边界约束

缺少内容（<85%）：

X页HTML包含180个单词
X页JSON应该有250个单词
覆盖率：72% = FAIL❌（<85%）
→ 缺少X页的70个单词
→ 立即重新生成X页

合并块：
- 所有页面通过Gate 1之前不要运行技能4（合并）
- 用错误内容合并页面会将错误级联到整个章节
- 每个页面必须首先单独验证

输出文件

生成的HTML文件

路径：output/chapter_XX/page_artifacts/page_YY/04_page_XX.html

内容：完整的HTML5文档，包括：

DOCTYPE和适当的标签
Meta标签（字符集，视口）
标题标签
CSS样式表链接
语义结构与类
所有提取的文本内容
适当的标题层级
格式化的列表和段落

示例结构：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>第2章：房地产权利 - 页码16-29</title>
    <link rel="stylesheet" href="../../styles/main.css">
</head>
<body>
    <div class="page-container">
        <main class="page-content">
            <!-- 开头章节仅 -->
            <div class="chapter-header">
                <span class="chapter-number">2</span>
                <h1 class="chapter-title">房地产权利</h1>
            </div>

            <!-- 导航（开头页面仅） -->
            <nav class="section-navigation">
                <div class="nav-item">不动产权利</div>
                <div class="nav-item">...</div>
            </nav>

            <hr class="section-divider">

            <!-- 主要内容 -->
            <h2 class="section-heading">不动产权利</h2>

            <p class="paragraph">不动产包括...