> V3.3.10 当前版本。要点：① 单题最短路径 4~5 次调用（见步骤 2「效率提示」）；② 渲染带 --check 一次完成自查；③ 数轴模板已含负数区；④ 题干图优先原图（截图含文字/选项则清空 stem/options）；⑤ --figure 支持多图（重复 --figure 题N.png 或 N=path，多题各带原图）；⑥ 大题含小题用原生 subparts 分层 + 每小题「主题干」框（shared_stem 精简版，跨页不丢共享前提）；⑦ 多题批量：并行生成 + 合并一次渲染，工具调用从 ~N×5 降到 4~6 次（见「多题批量」场景与效率提示表）；⑧ PDF 不默认交付：先 present_files 交付 HTML 并询问是否需要 PDF，用户要才跑 python scripts/to_pdf.py <html>（本机 Chrome/Edge 无头打印 A4）。⑨ 手写 SVG 写进 visualize 段内的 diagrams（顶层 diagrams 现亦可识别、作兜底，见下）；内置模板不适用却仍要手写时，务必渲染后核对产物里确实出现你写的那张图（V3.3.9 前顶层写法会被静默忽略、悄悄换成自动模板）。历史版本要点见 CHANGELOG.md。

Socratic Learning Sheet（苏格拉底式学习单生成器）

这个 skill 解决什么问题

老师拿到一张题目图片（可能是试卷、习题册、扫描件、屏幕截图），里面含 LaTeX 公式、图形、表格。
希望生成一份只问不讲的引导式学习单给学生做：学生顺着引导自己推导出结论，看不到答案；
同时图、表、公式原样还原。
最终交付物是一个自包含 HTML 文件——浏览器打开就能用，「打印 / 导出 PDF」按钮一键导出 A4（页数随内容自然增长，不强求 2 页）。

环境要求（安装前看一眼）

• Python 3.10+：运行 scripts/render_sheet.py 与 scripts/encode_image.py 需要 Python 3.10 及以上。脚本只用标准库，无需 pip install 任何第三方包。
• 通过 WorkBuddy 使用本 skill 时，朋友无需自行安装 Python：渲染脚本由 agent 的 Bash 工具执行，而 WorkBuddy 执行环境已自带符合要求的托管 Python（本机为 3.13.x），开箱即用。
• 仅在 WorkBuddy 之外手动跑脚本才需要自己装 Python 3.10+（例如 python scripts/render_sheet.py input.json -o out.html）。
• 打开生成的 HTML：KaTeX（JS + auto-render + 字体）已内联进文件，完全离线可用，无需联网；打印 / 导出 PDF 不依赖联网。
• 不依赖任何外部 API Key / 第三方 LLM 客户端：生成引导 JSON 这一步由 WorkBuddy 自带模型（运行 skill 的 agent 自己）完成，详见「步骤 2」与「运行环境」。

> 说明：本 skill 不会、也不需要自动下载 Python 或其他运行时——WorkBuddy 已提供托管 Python，自动下载既多余又有风险（静默改动朋友系统、依赖网络）。朋友只要 WorkBuddy 能正常用，就能跑本 skill。

5 步工作流

按顺序执行。如果用户消息里已经提供部分信息（如下游 LLM 已经生成 JSON），可以跳过对应步骤。

步骤 1：识别输入形式，决定如何继续

关键：题目图片里的 LaTeX、图、表必须原样还原。本步骤由 agent 自身的多模态能力完成（直接用 Read 工具看图片，不需要任何 OCR 工具，也不需要外部 API Key）：

• stem 字段（文字 + 公式）：把你从图上看到的原题文字逐字写出；公式用 LaTeX 写（如 $\angle C=90^\circ$、$\frac{1}{2}$）。题号、原文、子问 (1)(2) 都要保留，不要重新加工润色。
• figure 字段（原图）：
• 最短路径（推荐）：JSON 里 figure 留空字符串 ""，渲染时加 --figure <原图路径>，脚本自动 base64 内嵌（免去单独跑 encode_image.py 与粘贴 base64）。多题批量时重复 --figure 多次（每题一张，按顶层 item 顺序填入），或 N=path 显式指定第 N 题原图（见「多题批量」场景）。
• 原图优先（用户明确偏好）：题干图默认用原图 1:1 内嵌，不要擅自重绘。原图是最忠实的"题目再现"。
• 若截图已含题干文字或选项（整页 / 拍题截图常见），整张内嵌会与 stem / options 重复显示。此时清空 stem 与 options，让原图独占（保留 sub_label 如「第 7 题」）。判据：截图里除图外还有文字或 A/B/C/D？有 → 清空 stem/options。
• 仅当原图模糊不可读或用户明确要求重绘时，才手写内联 <svg>（此时按"重绘 + 结构化 stem/options"处理）。
• 无图留 ""（配合 --figure 亦可）。

大题含小题：用 subparts（原生分层，推荐）

当一道大题分 (1)(2)(3) 等多个异质小题（各自考不同知识点）时，不要把小题拆成多个独立 item（那样原图会重复出现、层级只能靠 sub_label 文字模拟）。改用原生 subparts 结构：

{
  "sub_label": "第 1 题（综合）",
  "stem": "大题完整题干（含 (1)(2)(3) 全文）……",
  "shared_stem": "只留图形/已知条件的精简版（如『如图，抛物线经过 A、B、C 三点。』），用于小题『主题干』框",
  "figure": "",                       // 原图只在大题父题出现一次
  "guide": [],                        // 大题无导言时留空数组，避免与小题引导重复
  "subparts": [                      // 每个小题 = 一个独立单元
    {
      "sub_label": "(1)",
      "objective": "……",
      "stem": "小题 (1) 的独立题干（若与父题共用大图，此处写『见上方原题图』，figure 留空）",
      "figure": "",                   // 小题不重复原图；--figure 只注入大题父题
      "guide": [ /* 该小题独立的 5 段引导 */ ]
    },
    { "sub_label": "(2)", "stem": "……", "guide": [ /* 独立 5 段 */ ] },
    { "sub_label": "(3)", "stem": "……", "guide": [ /* 独立 5 段 */ ] }
  ]
}

规则：
- 原图只渲染一次（在大题父题 figure；--figure 也只注入父题）。小题 figure 一律留空，渲染脚本不会重复。
- 每个小题自动带「主题干」框：渲染脚本把大题父题的 shared_stem（精简版：只留图形/已知条件那一句）作为"主题干"引用框注入到每一个小题顶部（仅文字、暖金强调、不重复原图）；若父题未给 shared_stem，则回退用完整 stem。这样大题跨页、第 2/3 小题流到下一页时，学生仍看得到共享前提，但不会把整段 (1)(2)(3) 列表重复印在每小题里（省纸、不喧宾夺主）。无需在小题 JSON 里手动重复大题题干。
- 大题父题 guide 留 [] → 不渲染整段导言，只显示「题目再现 + 原图 + 小题列表」；小题各自独立 5 段引导 + 作答留白。
- 大题 knowledge_points 作为小题兜底；小题可各自带 knowledge_points 精确匹配图示。
- 手写图示写在该小题 visualize 段内的 diagrams（规范位置）。V3.3.9 起同样接受把 diagrams 放在小题/题目顶层（兜底位置，向后兼容旧写法）；优先级：段内 > 顶层 > 自动匹配。不要假设"写了就一定生效"——渲染后核对产物中确有你手写的那张图（特征 viewBox / 独特坐标），历史上顶层写法曾被静默忽略。
- 小题 density=低 同样可省略 reflect 段（每个小题独立按密度计）。
- 生成指引（agent 自动抽 shared_stem）：遇到大题含小题时，把大题 stem 的「图形/已知条件」那一句单独写进 shared_stem（如「如图，抛物线经过 A、B、C 三点。」），不要把整段 (1)(2)(3) 列表放进去——整段列表留在父题 stem 即可，渲染脚本会自动把 shared_stem 注入每小题、把 stem 留在顶部原题框。
- 测试样例：scripts/example-subparts.json（二次函数综合题，(1) 求解析式 / (2) 最短路径 / (3) 相似判定）。

步骤 2：产出引导 JSON（agent 自己生成，默认不读 references）

本步骤不需要调用任何外部服务——由运行本 skill 的 agent（即 WorkBuddy 自带的模型）直接生成 JSON。也就是说：你（agent）读图理解题意后，按下面的约束在脑子里"扮演"教研员，把结果写成一段合法 JSON 即可。

自足约束（下列内容已足够生成，无需先读 references）：

• 难度档：基础 / 标准 / 拔高；引导密度：低 / 标准 / 高。两者由用户指定（默认「标准 · 标准」），并原样写进 JSON 顶层 difficulty / density。
• 密度决定段数与步数（写入 guide 时遵循）：

• 每步字段：{"prompt": "...", "hint": "...", "input_type": "free|fill|choice|multi|truefalse|note", "options": [...]}；options 仅选择题类需要（{"label":"A","text":"..."}）。
• 仅在以下情况才去读对应 reference（其余一律跳过）：
• 密度/难度档映射需逐条对照 → references/teaching-skeleton.md § 3
• 用户传了 custom_prompt（含 {{stem}} 等占位符）→ 用 references/html-contract.md § 6 校验：未知占位符抛错而不是静默回退（占位符字典见 references/prompt-template.md § 5）
• 确需手写定制 SVG → references/diagram-templates.md
• 需要完整 system 人设措辞 → references/prompt-template.md § 3

关键铁律（用对话自身的 LLM 能力生成，无需外部 API Key，也不要去读项目的 llm_client.py；完整硬约束见下方「关键约束」9 条）：

• 输出必须是合法 JSON，不要任何额外说明文字（步骤 3 说明如何提取）
• 密度=低 时 guide 省略 reflect 段（仅 4 段）；其余密度必含 5 段
• visualize 段 diagrams 留 []，图形交给脚本自动配（见关键约束 5）
• JSON 字符串内禁止 ASCII 双引号 "：prompt / hint 里需要引号一律用中文引号「」/『』，否则 JSON 解析失败、白烧一次渲染往返（实测最常见的低级返工源）

效率提示 — 单题最短路径（实测 44 次调用 → 5 次）：

耗时几乎完全由工具调用次数决定（每次往返约 10~15 秒），与脚本运行速度无关（render_sheet.py 仅约 1.3 秒）。单题最短路径：

必须避免的三件事（这些是一次单题生成膨胀到 40+ 次调用的根因）：

1. 不要为了生成 JSON 先写 Python 构建脚本——每次内容微调都会变成「改脚本 → 重跑」两步。只有需要批量计算坐标时才用脚本，且应一次写对。
2. 不要反复打磨 SVG——数轴 / 坐标系等常见图形已内置模板（diagrams: [] 即自动配），不要手写。确需手写时按下方清单一次写对。
3. 不要每改一处就截一次图——攒够改动跑一次校验，且用 --preview 版（加载快约 40%）。

多题批量最短路径（≥3 题，最大提速点）：各题 guide 完全独立，可并行。把「逐题循环串行」改成「并行生成 + 合并一次渲染」，工具调用从 ~N×5 次降到 ~4~6 次：

> 详见下方「多题批量（≥3 题）场景」。

手写 SVG 一次写对清单（仅当内置模板确实不适用时）：

• 负号用真减号 −（U+2212），不是 ASCII -（f"{int(-3)}" 输出 -3，需 .replace("-", "−")）
• 同页出现多个 SVG 时，箭头 marker id 必须各不相同，否则同文档 id 冲突
• 轴的纵向位置按用途留白（题干图紧凑、学生标注图留空间），不要共用一个固定值
• 文字左起 x 与 viewBox 宽度预留 ≥ 40px，防右侧被裁

步骤 3：从 LLM 提取 JSON

LLM 经常在 JSON 前后包一层 json ... 围栏或加一句"以下是..."说明文字。
提取时用代码块边界定位或找第一个 { 到最后一个 }。

如 LLM 输出根本不是合法 JSON（如直接写了引导问题列表），用代码块回退策略：

1. 让 LLM 重试并强调"只输出 JSON，无任何说明"
2. 重试 1-2 次后仍失败 → 用 references/teaching-skeleton.md § 5 的人工结构提示 LLM 重新格式化
3. 仍失败 → 提示用户：「AI 暂时无法生成符合骨架的输出，请手动粘一段结构化 JSON 进来」

步骤 4：调用 scripts/render_sheet.py 渲染 HTML

把上一步得到的 JSON 写到临时文件，再调脚本：

python scripts/render_sheet.py <input.json> -o <output.html> \
    [--difficulty 基础|标准|拔高] [--density 低|标准|高] \
    [--title "学习单标题"] [--author "张老师"] [--target "初中学生（七年级）"] \
    [--preview]   # 过程预览：跳过 KaTeX 注入，体积 1.7MB → ~33KB
    [--check]     # 渲染后自动自查：裸星号 / 段序 / CDN / 署名 / 内嵌图（建议每次带上）
    [--figure <原图路径>]  # 自动 base64 内嵌原图，免去单独跑 encode_image.py（最短路径推荐）
                          # 多题批量可重复：--figure 题1.png --figure 题2.png … 或 --figure 0=题3.png

--preview 用途：调布局 / 查段数 / 浏览器校验时用——秒开、体积 33KB、浏览器加载快约 40% 且更稳。浏览器目检一律基于预览版（见步骤 4.5）；交付给用户的最终稿必须去掉 --preview（保留公式渲染）。

脚本容错（来自 references/html-contract.md § 3）：

• 缺某 section → 自动用默认段提示填充
• 某段 steps 超 SECTION_MAX → 截断
• visualize 段缺 diagrams → 按知识点关键词自动匹配 SVG 模板（坐标系/数轴/三角形/角度/函数表格/面积分割/公差带/兜底格点图）
• 顶层不是 items list 或 items 为空 → 抛错提示重试

自动匹配 SVG 的关键词表（完整版见 references/diagram-templates.md § 2）：
- 坐标系/象限/x轴/y轴/横坐标/纵坐标 → 坐标系 SVG
- 数轴/有理数/相反数/绝对值/比较大小 → 数轴 SVG（−5 ~ 5 对称刻度，含负数区，通用）
- 三角形/等腰三角形/直角三角形/全等/相似/SAS/ASA/AAS/SSS → 等腰三角形 ABC SVG
- 函数/图象/自变量/因变量 → 函数表格 SVG
- 分割/取半/对折/依次/依此类推/递归/涂色/阴影/面积/正方形/纸片/等比 → 正方形递归分割 SVG
- 公差/合格/上限/下限/偏差/标注/标准尺寸/直径/加工 → 公差带数轴 SVG
- 角/角平分线/垂直/平行/余角/补角/对顶角 → 角度示意 SVG
- 都不命中 → 格点图 SVG

匹配规则：① 取命中的最长关键词所属分类（防单字「角」抢走「三角形」）；② 等长时按优先级 square_halving > tolerance_band > coord > triangle > func_table > number_line > angle 决胜；③ 全不命中 → default。

> 若自动匹配出的图与题意不符（如"三角形 ABC 中求证角平分线"命中了 angle，但图形主体应为三角形），在 visualize.diagrams 显式传入自己的 <svg> 即可覆盖——自动匹配只是默认值，不是强制值。

步骤 4.5：渲染前自查（0 秒，把返工挡在渲染前）

不要靠"完整渲染 + 截图肉眼看"发现裸星号 / 泄题 / 段数问题——那是最贵的返工环。渲染时带上 --check（步骤 4 命令末尾加 --check），渲染脚本会一并打印「裸星号 / 段序 / 外部 CDN / 署名 / 内嵌图」结论，0 秒查出，先修再进完整渲染。

• 裸星号 > 0 → 用 $\mathbf{...}$ 或中文标点替换 **，重渲染。
• 段序不对 → 补/删段后重渲染。
• 疑似泄题 → 按关键约束规则 1 重新生成，不交付。

> 浏览器校验（阶段 2 目检）一律基于 --preview 版（33KB）：加载快约 40%、更稳，够查布局/段数/图示。只在阶段 3 定稿前用完整版（1.7MB）校验一次公式渲染。

步骤 5：分阶段交付（先出可审产物，确认后再继续）

原则：JSON 是最贵、也是唯一需要老师"读内容"把关的产物；1.7MB 定稿只在内容过审后烧一次。把「内容审查」和「渲染交付」解耦，避免返工白烧完整渲染。

阶段 1 · 先交付 JSON 内容审查稿
- 把上一步得到的 items[] JSON 写成 .json 文件（含原图 data URI）。
- 用 present_files 先交付这份 JSON，并明确请老师审查：
- 引导问题有没有泄露答案（出现"= 某数"或替学生写出关键中间结果 → 立即改）
- 5 段骨架是否齐全（concept / decompose / visualize / reflect / summary；密度=低 时 reflect 整段可省略 → 4 段）
- 有没有裸星号（**）、引导是否贴合本题真实数字/图形（规则 6、2）
- 图形是否可能泄题（规则 7）
- 确认内容无误后再进阶段 2；需要改就直接改这段 JSON（内容改动的返工成本只在 JSON，不烧完整渲染）。

阶段 2 · 预览渲染（33KB，查布局）
- 调 render_sheet.py 用 --preview 出预览版（公式以 $...$ 源码显示），秒开看布局 / 段数 / 图示是否对。
- 浏览器校验一律基于预览版（33KB，加载快约 40%、更稳），详见步骤 4.5 的脚本自查 + 本步的轻量目检。
- 布局 / 段数 / 图示不对 → 改 JSON 后重跑预览，重复此轻量环。

阶段 3 · 完整渲染 + 交付定稿
- 阶段 1/2 都确认无误后，去掉 --preview 跑一次完整渲染（含公式）。
- 用 present_files 交付最终 HTML，并明确告诉用户：浏览器右上角「🖨️ 打印 / 导出 PDF」按钮一键导出 A4（页数随内容自然增长，不强求 2 页）。
- 交付 HTML 后询问用户是否需要 PDF 文件——默认不生成。用户答「要」再跑 python scripts/to_pdf.py <out.html> 出 A4 PDF 并 present_files 补交付；答「不要」就此结束（HTML 自带打印按钮，用户随时可自行导出）。
- 若用户后续想调整内容（编辑某段、改 SVG）：直接编辑 .json 后重跑即可（对应 JSON 即持久化源）。

> 单题场景：阶段 1 的 JSON 审查可简化——直接以"渲染后的预览版 + 一段内容小结"交付，但仍要先自查裸星号/泄题/段数（步骤 4.5）再进完整渲染。
> 多题批量（≥3）：阶段 1 统一在合并后的 JSON 上审查一次，全对后再一次性进阶段 2/3（见下节）。

多题批量（≥3 题）场景 — 并行生成 + 合并一次渲染

老师一次给多道题（如整张试卷 1~5 道）时，按以下顺序避免重复读文档、也避免一次生成超限被截断：

1. 只读一次 SKILL.md（步骤 2 的约束对所有题都适用，不需要每题重读 references）。
2. 多图并行 Read：把所有题目图片的 Read 调用放在同一条消息里（并发读取，省往返）。
3. 并行产出 guide：每 2~3 题为一组，在同一条消息里发多个 Write（或一次写完整 items[] JSON）。内容很长怕被截断时再分组，但组与组之间并行——不要等上一题渲染完再出下一题。把所有题的 items 合并进一份 merged.json（保留共同 title / difficulty / density，scripts 天然支持多 item 数组，无需额外 merge 脚本）。
4. 一条命令合并渲染 + 自查：所有原图用重复 --figure 注入（按顶层 item 顺序），一次 --check：

bash # 原图顺序与题序一致：按题序逐个 --figure python scripts/render_sheet.py merged.json -o 学习单.html \ --figure 题1图.png --figure 题2图.png --figure 题3图.png \ --check # 原图顺序与题序不一致：用 N=path 显式指定第 N 个顶层 item（0 起） python scripts/render_sheet.py merged.json -o 学习单.html \ --figure 0=题3图.png --figure 1=题1图.png --figure 2=题2图.png \ --check
- 阶段 1/2 可拆轻量环：merged.json 先 --preview 查布局/段数（33KB 秒开），确认无误再去 --preview 出带公式定稿。但只渲染一次完整版（定稿前），不要每题各烧一次。
5. 一次 present_files 交付（如需增量，可每题渲染完即 present，不必等全卷串行完）。
6. 全部题用同一组 --difficulty / --density（从 merged.json 取），不要每题单独不同档，避免风格不一。
7. 每题 visualize.diagrams 都留 []，由脚本自动配 SVG——合并时不冲突、也不增加输出量。
8. 浏览器校验只用预览版，不要在完整版上反复目检；只有定稿前用完整版确认一次公式渲染。

> 提速本质：N 题从「N×(生成+渲染)」压成「并行生成（≈1 轮）+ 1 次渲染 + 1 次 --check」。工具调用从 ~N×5 次降到 4~6 次（见上方效率提示表）。

关键约束（绝不能违反）

1. 不输出答案。所有引导问题必须让学生自己推导。出现答案时立即停掉并重新生成。
2. 不套模板。每个引导问题必须引用本题真实数字、字母、图形、已知条件。
3. 题目原样还原。LaTeX、表格、图形必须出现在 stem 字段，不能被简化或省略。
4. 5 段骨架（低密度为 4 段）必全。concept / decompose / visualize / reflect / summary 缺一不可；但密度=低 时 reflect（模块4·解题思维复盘）整段不渲染，仅 concept / decompose / visualize / summary 4 段。脚本会兜底，但提示词必须强调让 LLM 一次生成完整（低密度可省略 reflect）。
5. 图示自动匹配 SVG。agent 不手写 SVG，visualize.diagrams 默认留 []，脚本按关键词自动配 SVG（references/diagram-templates.md § 5 说明 ASCII 仅作兜底）。
6. 引导文本禁写 Markdown。prompt / hint / stem 里的 **加粗**、*斜体*、# 标题、- 列表 都不会被解析，学生会看到裸星号。要强调请用 $\mathbf{...}$（KaTeX 渲染）或中文标点。渲染后务必自查：产物里不得出现 **。
7. 图形中不得出现推导结论。SVG / 图示里只能出现题干已给的信息，不能出现推导结果——例如公差题的数轴不得预画合格区端点、递归分割图不得预标每块的分数值。判断方法：假设学生什么都不会算，只看这张图，他能不能说出答案？ 能 → 必须重画。
8. A4 紧凑排版（不强求 2 页）。内容应紧凑，但页数随题目长度和引导密度自然增长；题目很长时允许超过 2 页，无需强行压缩或截断内容。
9. 题目原图不被压缩。.figure-box 内的 <img> 与内联 <svg> 统一放宽到 max-height:460px（原先仅 img.stem-image 生效、其余被压到 260px）——打印时也保持原图清晰度。当题目图本身就是清晰照片 / 截图时优先 1:1 base64 内嵌（用 scripts/encode_image.py），不画 SVG。只有『原图是模糊的几何 / 函数图』时才用内联 SVG 精确还原。

打印 / 学生版式约定（必遵守，避免反复返工）

学习单最终是给学生打印手写用的，屏幕预览里允许出现辅助信息，但打印 / 导出 PDF 必须清爽。以下为经多次迭代确认的终态：

屏幕预览可见、打印必须隐藏的元素（在 assets/style.css 的 @media print 用 display:none 关闭）：
- 顶部工具栏 .toolbar（含「苏格拉底式学习单 / 5 段式教学骨架 / 思维可视化 / A4 打印」文案与打印按钮）
- 头部元信息行 .sheet-meta-line（作者 / 适用对象 / 难度 / 引导密度 / 知识点 pill）
- 底部署名落款 .sheet-foot（时间戳）

全程不得出现的信息：
- WorkBuddy 署名（调用时 --author 默认「老师」，不要传 WorkBuddy）
- 任何副标题文案（如「学生自推导 · 只问不讲」「苏格拉底式 · 5 段式教学骨架 · 难度 X · 引导密度 X」）——模板已移除 .sheet-subtitle，subtitle 参数保留但不再渲染
- 思维可视化图注只写「图 N」，不写「可打印后在此图上标注：已知✓、相等＝、目标★」这类无效提示

必须保留、打印也可见的元素：
- 大标题（题目标题）
- 「姓名 / 年级 / 班级 / 日期」学生信息填空区（.student-info，屏幕与打印均可见，供学生手写）
- 题目原图与 5 段引导内容
- 开放式回答（input_type="free"）与理解追问（comprehension）下方必须有 .writing-space 多行横线留白区，打印后学生可直接手写在横线上；短填空（fill）用下划线输入框即可

思维可视化配图规范：
- .diagram-grid 单列整页宽；.diag svg/img 放宽到 max-height:460px 且宽度自适应
- .diag 加暖墨绿 1.5px 边框 + page-break-inside:avoid 防跨页截断
- 图注仅「图 N」

配色与排版（沿用 edu-agent 项目惯例）

• 米白底 #F7F4EC + 暖墨绿 #2F5346（主轴/重点文字）+ 暖金 #C8A96A（强调/弧线/象限标签）
• 不使用蓝/青色系（用户偏好明确禁止）
• A4 尺寸：@page { size: A4; margin: 14mm 16mm; }
• 字体：-apple-system, "PingFang SC", "Microsoft YaHei", sans-serif
• KaTeX 已本地化内联（assets/katex/，字体 base64 化），模板不再引用任何 CDN——完全自包含、离线可用，打印 / 导出 PDF 无需联网

触发词（用户怎么说才用这个 skill）

• 「生成学习单」「做一份学习单」「出份引导式作业单」
• 「苏格拉底式学习单」「5 段式教学骨架」
• 「题目图片生成学习单」「把这道题改成引导式」
• 「不要答案，只问」「按 5 段骨架出学习单」
• 「出份只问不讲的学习单给学生做」

不要用这个 skill 的场景

• 用户只想要答案或解析（用 homework-solution-guide）
• 用户想要非数学科目的引导（如物理 / 化学）——可借鉴思路，但 SVG 模板是数学专用
• 用户想要 PPT 演示（用 tencent-pptx）
• 用户只想保留题目本身，不要引导（直接复制图片 + 题目文字即可，不需要 skill）

资源引用

> V3.1 按需加载（默认不读 references）：本 SKILL.md 已内联足够下发的约束（5 段骨架、密度表摘要、SVG 自动匹配表、占位符）。除非遇到明确触发条件，不要提前读 references/ 下文件；需要时再读，省约 2.4 万输入 token/轮。

运行环境

本 skill 运行时零外部依赖、零密钥：

• 模型：引导 JSON 由 WorkBuddy 自带模型（运行 skill 的 agent 自身）生成，不调用任何外部 LLM API，也不需要任何 API Key。
• 运行时：渲染由 scripts/render_sheet.py 完成，仅依赖 Python 3.10+ 标准库；经 WorkBuddy 执行时由平台托管 Python 运行，用户无需自行安装。
• 产物：输出 HTML 已内联 KaTeX（字体 + JS），完全离线可用，打印 / 导出 PDF 不依赖联网。

> 运行前提详见上方「环境要求」一节（关键点：经 WorkBuddy 运行无需自行安装 Python，也无需任何 API Key）。
> edu-agent 项目中的 llm_client.py / config.json（含 DeepSeek Key）不属于本 skill，运行本 skill 不需要它们——此前在本项目中曾顺手复用该客户端生成，但 skill 本身不要求。

自检（创建/修改本 skill 后必跑）

# 1. 示例 JSON 跑通（完整模式含公式渲染）+ 渲染后规则自查
#    --check 直接打印「裸星号 / 段序 / 外部 CDN / 署名 / 内嵌图」结论，无需另跑自查脚本。
python scripts/render_sheet.py scripts/example.json -o /tmp/test.html --check
#    期望末段：结论 : ✅ 全部通过

# 2. 容错测试：缺 reflect/summary 段时验证自动补默认
python scripts/render_sheet.py scripts/test-missing-sections.json -o /tmp/test-missing.html --check

# 3. --preview 跳过 KaTeX、体积大幅缩小（查布局/段数用）
python scripts/render_sheet.py scripts/example.json -o /tmp/test-preview.html --preview
#    期望：无 <link ...katex> / <script>，5 段 + SVG 图示结构完整

# 4. 浏览器校验只用 --preview 版（33KB）：打开 /tmp/test-preview.html 确认
#    5 段骨架齐全、SVG 图示清晰（diagrams=[] 时脚本自动补）、图形未预画推导结论、
#    「🖨️ 打印 / 导出 PDF」按钮屏幕可见打印隐藏。定稿前才用完整版 /tmp/test.html 确认一次公式。

任一失败先修再交付。（规则自查已由 --check 覆盖，无需手跑 Python 自查块。）

更新记录

变更历史见 CHANGELOG.md（本文件只保留当前生效说明，避免历史噪音消耗每轮输入 token）。