知识卡片生成器（Mo卡片风格）

将知识点转化为可翻页交互的 HTML 卡片集。一张卡片就是一个知识点——这是本技能的核心哲学。

视觉基因（源自 Mo-Card 项目）

生成的卡片必须保留以下 Mo 卡片标志性元素：

1. 暖米色页面背景（#FDF9F3），营造纸张质感
2. 白色大圆角卡片（radius 20px）承载内容，带柔和投影
3. 大引号装饰：卡片左上角 serif 字体大引号 “，用主题色的浅色版
4. 顶部结构：返回按钮 ← + 卡片集标题 + 分享按钮
5. 进度系统：N / M 计数（动态渲染）+ 分段式进度条 + 🔥 连续学习天数徽章
6. 章节导航（卡片数 >8 时启用）：章首卡对应进度条分段用暖橙色区分（--warm: #E8A23D），全条可点击跳卡，悬停显示卡名
7. 底部导航：「上一张」白底描边 + 「下一张」主题色实心，胶囊按钮
8. 趣味插图：每张卡片配一幅 AI 生成的插画（用 ImageGen 工具生成，保存到 HTML 同级的 images/ 文件夹，卡片 JSON 用相对路径 images/cardN.png 引用）
9. 完成庆祝：全部学完显示奖牌 + 鼓励语

工作流

1. 确定主题色

根据卡片集主题选一个 accent 色彩对（主色 + 浅色版），写入模板的 {{ACCENT_COLOR}} / {{ACCENT_SOFT}}：

章节标注色 --warm/--warm-soft 是独立的暖橙色系，与主题色搭配使用（模板已内置）。若主题色本身就是暖橙，可把章节色换成对比色（如青蓝）避免混淆。

2. 规划章节结构（卡片数 >8 时）

• 按知识脉络分章（如"基础概念 / 发展史 / 行业应用 / 伦理"），每章 3-8 张
• 每章第一张卡在 JSON 中加 "chapterStart": true，进度条对应段自动变为暖橙色，方便用户定位跳转
• 不要在运行时推断章首——把标记写进数据（数据驱动 UI），脚本生成时按"tag 与前一张不同即章首"自动插入，再校验数量
• 标题不要写死卡片数量（如"32 张学完"）——卡片集大概率会迭代增删，写死必过期。用"一气呵成，一次学完"这类不依赖计数的表述

3. 准备卡片内容（JSON 结构）

每张卡片是一个对象，字段全部可选、按需取用：

[
  {
    "tag": "基础概念",
    "title": "什么是大模型？",
    "paragraphs": [
      "大模型可以处理复杂的任务和数据，并提供强大的表达能力和学习能力。",
      "大模型通常需要更多的计算资源和数据来进行训练和推断。"
    ],
    "points": [
      { "label": "一句话记忆", "text": "参数越多，能力越强，胃口也越大。" }
    ],
    "list": ["优点一", "优点二"],
    "image": "images/llm.png",
    "imageCaption": "可选的插图说明文字",
    "quote": "可选的金句",
    "chapterStart": true
  }
]

字段说明：

• tag：卡片分类徽章，同章内 tag 保持一致（章节推断依赖它）
• chapterStart：章节首卡标记（true/省略），仅章首卡写
• title：知识点标题，建议 ≤ 14 字
• paragraphs：正文段落，每段 1-3 句
• points：结构化要点块（左侧竖线引用样式）
• list：圆点列表
• image：AI 生成插画的相对路径，建议语义化命名（images/llm.png 而非 images/card7.png），便于增删卡时复用
• imageCaption：插图下方的说明小字（可选）
• quote：金句/口诀，显示在"一句话记忆"块

单屏字数预算（硬性）：

宁多拆卡、不塞一卡。模板的 fitCard 智能缩放只是极端兜底——优先靠控字数保证字号不缩。

4. 生成配图（ImageGen，必做）

每张卡片调用 ImageGen 工具生成一幅插画，统一风格保证整套视觉一致。

主模板：科技 doodle 风（知识科普类首选，中性无人物）：

扁平风格科技涂鸦插画：{主题主体与场景描述}。
线条简洁圆润，柔和暖色调，米白色纯净背景，橙色#E8A23D点缀，
画面干净无文字无边框，教学示意图风格

备选：小和尚绘本风（叙事/文化/儿童类）：

扁平风格儿童绘本卡通插画：一个可爱的光头小和尚男孩{动作与场景描述}。
柔和暖色调，米白色纯净背景，橙色#E8A23D点缀，简洁圆润线条，
画面干净无文字无边框

参数建议：

• size: "1536x1024"（横版，适合卡片插图区）
• quality: "medium"（省积分；交付级可选 "high"）
• output_dir: 输出目录/images/

并行生成策略：

1. 每条提示词开头写语义区分词（如"扁平风格科技涂鸦插画：大脑与语言…"），生成后按提示词关键词识别归属
2. 多张图并行调用时时间戳自动错开，但不要依赖——生成后立即 ls 核对数量，缺图单独补
3. 批量重命名为语义名：mv 逐张按提示词对应关系改名（llm.png、token.png…）
4. 引用完整性校验：grep -o 'images/[a-zA-Z0-9_]*\.png' 文件.html | sort -u 与 ls images/ 对比（comm -23），确保 HTML 引用的图全部存在
5. 配图上不出现文字（AI 生成中文文字容易乱码）

5. 生成 HTML

1. 读取 assets/mo_card_template.html
2. 替换占位符：
   • {{DECK_TITLE}} → 卡片集标题（出现多处：<title>、顶栏、DECK_TITLE 常量、完成面板）
   • {{ACCENT_COLOR}} / {{ACCENT_SOFT}} → 主题色
   • {{CARDS_JSON}} → 卡片 JSON 数组（原生 JS 对象字面量，直接写 [...]，无需额外引号）
   • {{STREAK_DAYS}} → 连续学习天数（默认 1）
   • {{TOTAL}} → 卡片总数（仅作初始显示兜底，JS 启动时会用 CARDS.length 覆盖——总数是派生值，永远不要手工同步）
3. 输出结构：HTML 文件 + 同级 images/ 文件夹（相对路径引用，整个文件夹拷走也能用）

输出目录/
├── 主题名-知识卡片.html
└── images/
    ├── llm.png
    ├── token.png
    └── ...

单文件纯 HTML（无图片）仅当用户明确表示"不要配图"时使用。

6. 交付前校验（node 一把过）

增删卡或修改后，用 node 脚本对最终 HTML 做机械校验：

// 提取 CARDS 数组 eval 后断言：
// 1. 卡片总数 === 预期
// 2. 每张卡 image 字段指向的文件真实存在（fs.existsSync）
// 3. 每张卡全部文本字段拼接长度 ≤ 430 字符
// 4. chapterStart 数量 === 章节数（且都与 tag 变化位置对齐）

任何一处失败立即修复，不要带病交付。

交互能力（模板已内置）

• 翻页：点击按钮 / 键盘 ←→ / 空格 / 手机左右滑动
• 进度条跳转：点击任意分段直接跳到该卡；悬停显示卡名提示（seg.title）
• 章节导航：章首分段暖橙色高亮，扫一眼就能定位章节
• 动态计数：N / 总数 由 CARDS.length 派生渲染，增删卡零同步成本
• 智能缩放：fitCard 函数在内容超出时等比微缩，保证单屏完整不裁切（resize 时自动重算）
• 完成庆祝：奖牌面板 + 「再学一遍」
• PC 适配：宽屏（≥820px）自动切换更宽松排版

工程经验（血泪教训）

1. 派生值优于硬编码：总数、进度等一律运行时从数据计算，永不手工同步。硬编码的计数是过期 bug 的头号来源
2. 数据驱动 UI：章节标记、主题差异等信息写进卡片 JSON，让渲染函数统一消费；不要在 JS 里写"第 N 张是章首"这种位置硬编码
3. 批量修改靠脚本不靠手：多处替换用 sed，改完用 node 断言校验。人眼比对 40 张卡必漏
4. 谨慎表述原则：涉及 AI 能力宣称（AGI、超越人类等）写"宣称 / 有望"，不要绝对化；关键事实（模型参数、用户量、发布时间）写作前须多来源核实
5. 标题抗迭代：标题和文案避免绑定易变信息（卡数、版本号），否则每次增删都要全文排查
6. 图片先生成后改名：ImageGen 输出文件名不可控，先生成齐、再按提示词对应关系批量 mv 成语义名、最后校验引用，三步缺一不可

内容创作原则

1. 一卡一点：每张卡片只讲一个知识点，贪多必失
2. 口语化：像老师讲课一样写，避免论文腔
3. 加粗关键词：正文中的核心概念用 <b> 标出（自动显示为主题色）
4. 高亮重点：用 <em> 包裹需要划线强调的短语（米黄荧光笔效果）
5. 卡量建议：5-15 张一套为宜；15 张以上建议分章（用 chapterStart）；超过 40 张时考虑拆分成多套
6. 单屏完整原则（硬性）：手机端一张卡必须一屏完整显示——不滚动、不裁切、不丢内容。字数预算见第 3 步表格

常见需求映射

输出规范

• 文件名：{主题}-知识卡片.html（中文可保留）
• 生成后必须向用户展示文件（present_files）
• 若用户无特殊要求，卡片数量默认 5-8 张