study-material

# 学习资料提取、整理与知识录入 从 PDF、文档、图片中 **一字不漏** 提取全部内容，整理成高质量 HTML 学习文档，最后录入 Study Wiki 形成可检索的知识网络。 ## 完整工作流（三阶段） ``` PDF/文档 ──→ [阶段一] 逐页提取 + 页面截图 ──→ [阶段二] HTML 生成 ──→ [阶段三] Wiki 录入 (Read + pdftoppm) (CC Pages) (Study Wiki) ``` --- ## 阶段一：内容提取 ### 1.1 接收输入 支持的输入格式： - **PDF 文件**：用 Read 工具读取（支持指定页码范围，大 PDF 分批读取，每次最多 20 页） - **图片文件**：用 Read 工具直接读取（PNG/JPG/JPEG/WEBP），自动 OCR 识别 - **文本文档**：直接读取 Markdown/TXT 等 - **网页 URL**：用 WebFetch 或 Tavily 提取 ### 1.2 逐页提取原则 **核心原则：一字不漏，忠实原文** - 逐页/逐图读取，不跳过任何内容 - 大 PDF 分批读取：`pages: "1-20"`，`pages: "21-40"`... 直到读完 - 图片中的文字全部 OCR 提取 - 表格保持原始结构 - 数学公式、特殊符号准确还原 - 图表、示意图：原始 PDF 页面截图已嵌入，文字提取作为补充说明 - **填空题答案**：原文中手写或填写的答案要提取出来，用红色标注 `<span class="answer">答案</span>` - 提取完成后，对照原文检查是否有遗漏 ### 1.3 图片处理 — PDF 原页截图 **核心要求：每一页都要嵌入原始 PDF 页面截图，用户能直接看到教材原图。** #### 1.3.1 PDF 转图片 使用 `pdftoppm` 将 PDF 每页转为 PNG（200 DPI，清晰且文件大小合理）： ```bash mkdir -p /gcs/cc-pages/assets/study-{topic} pdftoppm -png -r 200 /path/to/input.pdf /gcs/cc-pages/assets/study-{topic}/page ``` 输出文件：`page-01.png`、`page-02.png`... 自动编号。 验证图片可访问： ```bash curl -s -o /dev/null -w "%{http_code}" https://www.closecrab.com/assets/study-{topic}/page-01.png # 应返回 200 ``` #### 1.3.2 嵌入 HTML 每个 page-card 在 `<span class="page-num">` 之后、`<h3>` 之前插入图片： ```html <div class="page-card"><span class="page-num">P8</span> <img class="page-img" src="/assets/study-{topic}/page-08.png" alt="Page 8" loading="lazy"> <h3>标题</h3> <p>文字提取内容...</p> </div> ``` 合并页面（如 P12–13）插入多张图片： ```html <div class="page-card"><span class="page-num">P12–13</span> <img class="page-img" src="/assets/study-{topic}/page-12.png" alt="Page 12" loading="lazy"> <img class="page-img" src="/assets/study-{topic}/page-13.png" alt="Page 13" loading="lazy"> <h3>标题</h3> ``` CSS 样式（已含在标准模板中）： ```css .page-img{width:100%;border-radius:12px;margin:10px 0 14px;border:1px solid var(--card-border);display:block} ``` #### 1.3.3 批量插入脚本 对于大文档，用 Python 脚本自动在每个 page-card 中插入对应图片，避免手动逐个编辑。脚本解析 `<span class="page-num">PX</span>` 中的页码，映射到 `page-XX.png`。 #### 1.3.4 其他 - `loading="lazy"` 必须加——62 页图片不能同时加载 - 图片模糊时标注 `[此处原文模糊，可能为：xxx]` - `<div class="image-desc">` 仅在需要**补充**描述图片细节时使用（作为图片的注释，不是替代品） --- ## 阶段二：HTML 生成 ### 2.1 输出路径与命名 ``` $CC_PAGES_WEB_ROOT/pages/study-{topic}-{YYYYMMDD-HHmmss}.html ``` 示例：`study-plant-reproduction-20260501-150000.html` ### 2.2 视觉风格 **暗色 Glassmorphism 主题**（与 page-style skill 的亮色主题不同，学习资料专用暗色） 核心 CSS 变量： ```css :root { --bg: #0f1a12; /* 深色背景（色调随学科调整） */ --card: rgba(255,255,255,0.06); /* 毛玻璃卡片 */ --card-border: rgba(255,255,255,0.12); --text: #e8f5e9; /* 主文字 */ --text2: #a5d6a7; /* 副文字 */ --accent: #4caf50; /* 主强调色（随学科调整） */ --highlight: #fff9c4; /* 高亮色 */ --formula-bg: rgba(33,150,243,0.08); /* 公式背景 */ --formula-border: #42a5f5; /* 公式左边框 */ } ``` #### 学科色板参考 | 学科 | --bg | --accent | --text/--text2 | 适用场景 | |------|------|----------|----------------|----------| | 生物/植物 | `#0f1a12` 深绿黑 | `#4caf50` 绿 | `#e8f5e9`/`#a5d6a7` | 植物、生态、细胞 | | 健康/人体 | `#14100f` 暖深棕 | `#ff8f00` 琥珀 | `#fff3e0`/`#ffcc80` | 青春期、人体系统 | | 数学 | `#0f1220` 深蓝黑 | `#42a5f5` 蓝 | `#e3f2fd`/`#90caf9` | 数学、几何 | | 语文 | `#1a1210` 暖褐 | `#d4a574` 棕 | `#efebe9`/`#bcaaa4` | 中文、英文、文学 | | 物理/化学 | `#0f1018` 深紫黑 | `#ab47bc` 紫 | `#f3e5f5`/`#ce93d8` | 物理、化学 | #### 多强调色（分类色编码） 当内容有明确的分类维度（如性别、阵营、对比组）时，增加辅助强调色： ```css /* 示例：健康教育的性别色编码 */ --accent-male: #42a5f5; /* 男性主题 — 蓝色 */ --accent-female: #f06292; /* 女性主题 — 粉色 */ .tag-male { background: rgba(66,165,245,.15); color: var(--accent-male); } .tag-female { background: rgba(240,98,146,.15); color: var(--accent-female); } .knowledge-card.male h3 { border-bottom-color: var(--accent-male); color: var(--accent-male); } .knowledge-card.female h3 { border-bottom-color: var(--accent-female); color: var(--accent-female); } ``` 适用场景：男/女生殖系统对比、植物/动物对比、正方/反方辩论等。 ### 2.3 核心 CSS 组件 | 组件 | class | 用途 | |------|-------|------| | 页面卡片 | `.page-card` | Tab 1 逐页内容，含 `.page-num` 页码标签 | | 页面图片 | `.page-img` | 原始 PDF 页面截图，`width:100%;border-radius:12px;loading:lazy` | | 知识卡片 | `.knowledge-card` | Tab 2 知识整理，每个知识点一个 card | | 练习区 | `.exercise` | Tab 3 练习题分组 | | 高亮 | `.highlight` | 重点内容黄色渐变高亮 | | 公式框 | `.formula-box` | 蓝色左边框 + 浅蓝背景，放关键公式/规则 | | 图片描述 | `.image-desc` | 虚线边框 + 斜体，描述图表内容 | | 目录 | `.toc` | 带锚点链接的目录导航 | | 答案 | `.answer` | 填空答案红色标注 | | 答案展开 | `<details>` | 练习题答案默认隐藏，点击展开 | | 词汇网格 | `.vocab-grid` | 双栏词汇表，`grid-template-columns:1fr 1fr` | | 分类标签 | `.tag-male`/`.tag-female` 等 | 分类维度的彩色标签（见多强调色） | ### 2.4 三 Tab 结构（纯 CSS 切换，无 JS） 使用 `input[type=radio]` + `:checked` 兄弟选择器实现 Tab 切换： ```html <input type="radio" name="tab" id="tab1" checked> <input type="radio" name="tab" id="tab2"> <input type="radio" name="tab" id="tab3"> <div class="tab-nav"> <label for="tab1">📖 逐页原文稿</label> <label for="tab2">🧠 知识整理</label> <label for="tab3">🗺️ 思维导图 & 练习</label> </div> <div class="tab-content"> <div class="t1">...</div> <!-- Tab 1 --> <div class="t2">...</div> <!-- Tab 2 --> <div class="t3">...</div> <!-- Tab 3 --> </div> ``` CSS 切换逻辑： ```css input[name="tab"] { display: none } .tab-content > div { display: none } #tab1:checked ~ .tab-content .t1 { display: block } #tab2:checked ~ .tab-content .t2 { display: block } #tab3:checked ~ .tab-content .t3 { display: block } ``` #### Tab 1：逐页原文稿 **目的**：让用户能逐页核对提取是否正确和完整，这是校验质量的唯一依据。 - 每一页单独一个 `.page-card`，标注页码 `P1`、`P2`... - 忠实还原原文文字 - 填空答案用红色 `<span class="answer">` 标注 - 图表/示意图：通过原始 PDF 页面截图展示，文字提取作为可搜索内容 - **关键：一字不漏，包括页码、标题、正文、题目、选项** - **相邻短页合并**：当 2-3 个连续页面内容很少（如标题页 + 正文页，或纯图片页 + 说明页），合并为一个 card，页码标为 `P12–13`。减少视觉碎片，但不遗漏内容 - 每页 card 结构（必须包含原始 PDF 页面截图）： ```html <div class="page-card"> <span class="page-num">P1</span> <img class="page-img" src="/assets/study-{topic}/page-01.png" alt="Page 1" loading="lazy"> <h3>页面标题</h3> <div class="text-content"> <!-- 逐字还原的内容（文字提取，作为图片的可搜索补充） --> </div> </div> ``` #### Tab 2：知识整理 **目的**：学习复习用的精华版，按知识点重新组织。 要求： - **开头有目录** `.toc`，列出所有知识 section 的锚点链接 - 按章节分 section → 每个知识点一个 `.knowledge-card` - 合并相关页面内容（同一知识点可能分布在多页） - 添加对比表格（如风媒花 vs 蟲媒花） - 添加 `.formula-box` 放关键规则和记忆口诀 - 每个 card 末尾加 **💡 连结思考** 链接到相关 section - 包含英中词汇表，用 `.vocab-grid` 双栏网格展示（按分类分组：花的部分、种子结构等） ```html <div class="vocab-grid"> <div>Testis 睾丸</div><div>Ovary 卵巢</div> <div>Sperm 精子</div><div>Egg / Ovum 卵子</div> </div> ``` - 包含常见易错概念对比（❌ 错误认知 vs ✅ 正确认知） - **知识点数量要丰富**：一个 60+ 页 PDF 应有 15-20 个 section，30 页左右 8-12 个 #### Tab 3：思维导图 & 练习题 **目的**：帮助巩固和检测学习效果。 **思维导图**： - 用 inline SVG 绘制（不用外部库） - 中心主题 → 分支 → 子分支的树状结构 - 不同分支用不同颜色系，颜色应与学科色板和多强调色一致 - 圆角矩形节点 `rx="18"`，连接线条 - **分支超过 6 个时必须加图例**（Legend），用小色块 + 文字标注每个分支的类别 - SVG 尺寸建议：宽 1000-1200px，高度根据分支数调整（6 分支 500px，10+ 分支 700px） - 中心节点使用主强调色 `--accent`，分支按类别分色 **练习题要求**（题量要丰富，覆盖所有知识点）： 大文档（50+ 页）标准题量： - 填空题 25 题（从原文提取，中英双语） - 判断题 15 题（✅/❌） - 选择题 12 题（A/B/C/D） - 配对题 3 组（左右匹配） - 排序题 3 组（按正确顺序排列） - 分类题 3 组（归类练习） - 看图标注题 2 题（用 SVG 画结构图 + 填标签） - 简答题 8 题 - **总计约 65-70 题** 中等文档（20-50 页）：按比例缩减至 40-50 题 小文档（<20 页）：25-35 题，可省略看图标注和排序题 - 每题答案用 `<details><summary>查看答案</summary><div class="ans">答案</div></details>` 隐藏 ### 2.5 生成策略 对于大文档（1000+ 行 HTML），采用分段生成策略： 1. 先生成 HTML head + CSS + Tab 1（逐页原文稿） 2. 保存为临时文件 3. 单独生成 Tab 2（知识整理）和 Tab 3（练习题） 4. 合并所有部分 如果需要增强某个 Tab： 1. 用 `head -N original.html` 提取要保留的部分 2. 将增强内容写入临时文件 3. 用 `cat` 合并 ### 2.6 打印适配 ```css @media print { body { background: #fff; color: #222; } .tab-nav, input[name="tab"] { display: none !important; } .tab-content > div { display: block !important; } /* 打印时显示所有 Tab */ .page-card, .knowledge-card, .exercise { break-inside: avoid; } } ``` ### 2.7 响应式设计 ```css @media (max-width: 600px) { .container { padding: 12px 8px 40px; } h1.main-title { font-size: 1.4rem; } .tab-nav label { padding: 8px 14px; font-size: 0.85rem; } } ``` ### 2.8 发布 1. 生成 HTML 到 `$CC_PAGES_WEB_ROOT/pages/` 2. 发送链接 `$CC_PAGES_URL_PREFIX/pages/study-{topic}-{timestamp}.html`（**不带引号**） 3. 汇报：提取了多少页、多少字、多少个知识点、多少道练习题 --- ## 阶段三：Wiki 录入 将 HTML 中整理好的知识录入 Study Wiki（`~/my-wiki-study/`），形成可检索、互联的知识网络。 ### 3.1 Wiki 路径 ``` WIKI_REPO=~/my-wiki-study WIKI_CONTENT=~/my-wiki-study/content