练习逐题讲解课件（数学）
Overview
把一份数学练习/试卷/作业，做成逐题课堂讲解 PPT：每道题一页，题目在上、解答（浅蓝面板）与提示（黄面板）在下；竖式分数（上分子下分母）以栅格图片形式嵌入，腾讯文档预览 / 希沃白板 / PowerPoint 都能正常显示；放映时点击鼠标先出示解答、再单击出示提示；附带讲稿备注。可指定一个"风格参考 pptx"（如吾课网课件），脚本清空其幻灯片后按它的版式与配色重建，从而一键复用模板风格。
本技能聚焦数学（小学高段/初中为主），但版式与分数渲染对其它学科同样适用，只要把题目数据换成对应内容即可。
同伴如何使用（零门槛，推荐）
> 同伴拿到技能后，根本不用碰 Python、不用写 JSON。他们要做的只有：
> 1. 在 WorkBuddy 对话里，把几张习题图片直接粘贴/发送进来；
> 2. 再把一份"自己喜欢的教学课件 .pptx"发进来，当作风格参考；
> 3. 说一句：「用 practice-courseware 帮我做逐题讲解课件」（或类似意思）。
>
> 剩下全部由 WorkBuddy（带本技能）自动完成：缺依赖自动装、图片自动识别/排版、生成可编辑的 pptx 并交付。
若同伴发的是纯文字版题目（不是图片），同样直接粘贴进来即可，效果一样。
触发场景
- "把这几张练习图做成逐题讲解课件"
- "做成上课 ppt，分数要竖式、解答和题目同页、点击出提示"
- "按吾课网那个模板风格，生成一份练习讲解"
- "这些题逐题出讲解，带讲稿备注"
- 同伴说："用 practice-courseware 帮我做课件"
前置条件（一次性，绝大多数情况自动完成）
> 这些步骤由 WorkBuddy（带本技能）在首次运行时自动处理，人通常不需要手动做。仅当自动安装失败时才手动处理。
- Python 依赖：需要
python-pptx、Pillow、lxml。技能会让 WorkBuddy 自动用pip install装好（见下方"首次运行自检"）；若失败，手动在 WorkBuddy 的托管 venv 执行：
<venv>/Scripts/pip install python-pptx Pillow lxml - 字体：脚本默认用系统
微软雅黑（Windows 自带，含粗体）。其它系统会自动回退到可用的中文字体（如文泉驿/系统自带黑体）；若中文显示成方块，放一个中文字体并改脚本_find_font。 - 风格参考 pptx：任意一份你想复用的 .pptx（建议 16:9 模板，如吾课网）。脚本清空其幻灯片后按它的版式与配色重建。
首次运行自检（给 agent 的指令）
生成前，先用托管 python 尝试 import pptx, PIL, lxml；若 ImportError，先执行一次
python -m pip install -q python-pptx Pillow lxml（用 WorkBuddy 托管 venv 的 python），成功后再继续。这样同伴无需手动装依赖。
工作流（四步）
第 1 步：采集参数
若用户未说明，主动确认：① 课题名；② 风格参考 pptx 的路径或文件（没有就用脚本内置的通用空白版式）；③ 输出路径（默认见"固定输出目录"）；④ 学段/版本（仅用于备注与提示文案，不改渲染）。
- 用户通常在对话里直接发来参考 pptx 文件和习题图片，agent 直接用这些文件，不必再问路径。
第 2 步：获取题目内容
- 优先让用户把习题图片直接粘贴到对话中；用 Read 工具读取图片，逐题转写题干、选项、已知解答线索、题型（若模型支持 OCR 更好；不支持则请用户补发文字或把题目文本直接发过来）。
- 把全部内容整理成一份 JSON（数据格式见下）。可让模型直接产出该 JSON，再交给脚本。
- 竖式分数在 JSON 里用
["F","分子","分母","样式"]表达；普通文字用["文本","样式"]。
第 3 步：生成课件
调用脚本（路径用 WorkBuddy 托管 venv 的 python）：
<venv>/python.exe <skill>/scripts/build_practice_ppt.py <题目.json> ^
--ref "<风格参考.pptx>" ^
--out "<输出.pptx>"
--ref与--out均可省略：脚本会优先用 JSON 里的ref_template/output字段，都没有则退回到内置通用版式并输出到当前目录。- 若输出文件被 WPS/PowerPoint 打开，脚本会先存成
<输出名>_tmp_out.pptx，提示你关闭占用程序后再手动覆盖（避免写入失败丢文件）。
第 4 步：校验与交付
- 向用户报告输出路径。
- 建议用 PowerPoint 打开复核（模型本身无法读图，分数是否美观靠脚本参数保证，必要时再微调）。
- 若用户用腾讯文档预览，明确告知：竖式分数已做成图片，预览可见；若仍异常，多半是文件被占用或预览缓存，重载即可。
数据格式（lesson.json）
顶层字段：
{
"title": "封面主标题，如『分数除法』",
"subtitle": "封面副标题，如『第3课时 解决问题（练习课）』",
"ref_template": "可选：风格参考 pptx 绝对路径",
"output": "可选：输出 pptx 绝对路径",
"slides": [ ...见下... ]
}
slides 为有序数组，元素按 type 区分：
① 封面
{ "type": "cover", "title": "分数除法", "subtitle": "第3课时 解决问题（练习课）",
"note": "开场语…" }
② 解题钥匙（含竖式分数的要点页）
{ "type": "keys", "title": "温故知新 · 解题钥匙",
"items": [
{ "tokens": [["把工作总量看作单位 \"1\"。","b"]], "size": 32 },
{ "tokens": [["① 单独做 t 天 → 每天完成 ","n"],["F","1","t","b"]], "size": 32 }
],
"hint": { "tokens": [["先想一想：甲单独做 8 天完成，甲每天完成这批活的几分之几？","ub"]], "size": 26 },
"note": "复习页讲稿…" }
③ 闯关过渡页
{ "type": "section", "title": "第一关 · 基础开心园",
"subtitle": "一、填一填 二、选一选", "note": "过渡讲稿…" }
④ 逐题讲解页（核心）
{ "type": "merged", "chip": "基础开心园 · 填一填 ①", "chip_color": "blue",
"question": [
[["1. 一批货物，甲车队单独运要 3 次运完，","n"]],
[["乙车队每次运这批货物的（ ），两车队合运需要（ ）次。","n"]]
],
"solutions": [
[[["① 甲每次运：1 ÷ 3 = ","n"],["F","1","3","rb"],[" ② 乙每次运：1 ÷ 6 = ","n"],["F","1","6","rb"]],
[["③ 合运次数：1 ÷（","n"],["F","1","3","n"],[" + ","n"],["F","1","6","n"],["）= 2（次）","rb"]]]
],
"hint": [["💡 想一想：把\"一批货物\"看作什么？","vb"]],
"hint_size": 22,
"q_size": 28, "sol_size": 24,
"note": "第1次单击出解答，第2次出提示。讲稿…" }
说明：
- chip_color："blue" / "navy" / "orange"（见设计笔记的颜色映射）。
- question / solutions / hint 都是"行数组"：每个元素是一行，行内是若干 token（文字或分数）。solutions 还可再分组（数组的数组），每组是一张浅蓝解答块。
- 每行 token：["文本","样式"] 或 ["F","分子","分母","样式"]。
- 样式字符：见 references/design_notes.md 的样式表（n/b/r/rb/u/ub/v/vb/wb/y）。
⑤ 课堂总结页
{ "type": "summary", "title": "课堂总结 · 满载而归",
"lines": [
{ "tokens": [["这节课用到的同一串\"钥匙\"：","b"]], "size": 30 },
{ "tokens": [["① 单位 \"1\" → ② 每天几分之几 → ③ 效率相加","b"]], "size": 30 }
],
"panel": { "tokens": [["课后任务：编一道工程问题考考同桌。","vb"]], "size": 26 },
"note": "总结讲稿…" }
固定输出目录（可改）
脚本默认输出到当前工作目录下的 lesson_courseware.pptx（跨机器通用，不依赖任何本机路径）。要改位置，用命令行 --out 或 JSON 的 output 字段指定绝对路径即可。
注意事项
- 竖式分数必须烘焙成图片：腾讯文档预览不渲染原生公式（OMML），也不渲染"文字 run 内嵌图片"，只有独立浮动图片稳定可见——脚本已按此处理，请勿改回公式或内嵌图。
references/design_notes.md详述。 - 分数可能被裁切：含分数的行必须按分数实际总高自动加高，否则分子/分母会被画布切掉。脚本已内置自适应行高。
- 读图能力：若当前模型不支持读取图片，按"第 2 步"请用户补发文字，不要硬读图。
- 断行排版约定：题干/解答/提示区块是图片，长行会自动折行，遵循——分数不拆开、不在分数前断、优先在标点处断、末行短到不足 18% 行宽才重排（正常短问句保留单独成行）。期望效果：题干第一句连同分数尽量同处一行，"…多少吨/页/元？"问句单独成行，不出现"第二行只剩一个数字"。详见
references/design_notes.md第 1.5 节。若想强制某处断行，把该段拆成多个行数组元素即可。 - 默认出两份：不加
--editable时，脚本先生成图片版（腾讯文档预览最稳），再额外生成一份<名>_可编辑.pptx——题目/解答正文为 PowerPoint 原生文字框（可双击直接改字），分数仍是图片按原位嵌入（保留竖式）。需要只出可编辑版时用--editable。 - 点击出示顺序：每道逐题页先点出「提示」（黄面板），再点一次「答案」（所有解题步骤一次性出现，不分行多次点击）。图片版与可编辑版一致。实现要点：同组形状中第一个用
nodeType="clickEffect"，其余必须用nodeType="withEffect"，否则会被 PowerPoint 当成多次点击逐个出现；可编辑版行高须按分数实际总高自适应（同图片版），否则答案两行间过挤。 - 文件占用：输出 pptx 被 WPS/PowerPoint 打开时无法覆盖，按"第 3 步"提示用户关闭后手动替换。
- 不把学生隐私/成绩写入课件以外的位置。
分享给同伴（两种方式）
方式 A：发一个链接，同伴手动安装（适合给几个熟人）
本技能已打包成"一键可装"的形式。把分享链接发给同伴：
> 🔗 分享链接：见本次对话交付的"技能分享页"链接
同伴一次性安装：
1. 打开链接 → 点「下载技能包」得 zip；
2. 解压得到 practice-courseware 文件夹；
3. 丢进 WorkBuddy 技能目录：C:/Users/<用户名>/.workbuddy/skills/（Mac/Linux：~/.workbuddy/skills/）；
4. 重启 WorkBuddy。
方式 B：上架 SkillHub，让所有人都能搜到并一键安装（推荐，公开分发）
要让不认识的人也能在 WorkBuddy 里"搜到 + 装上就用"，需把技能发布到 SkillHub 技能市场（https://skillhub.cn，即 WorkBuddy 技能搜索使用的官方仓库）。上架后，别人在 WorkBuddy 里搜"练习课件 / 逐题讲解 / 竖式分数"等关键词就能找到，点一下即装。
准备（本技能已就绪）：
- 已生成好可直接上传的包：share_site/practice-courseware-skillhub.zip（内容平铺、含图标，不含安装时才生成的元数据）。
- SKILL.md 头部的 name / description / description_zh / description_en 已写好，决定搜索命中率——描述里多写用户会搜的词（如"数学课件""分数除法""上课 ppt""练习讲解""希沃"）。
发布步骤（在 skillhub.cn 网页上，需你自己的账号）：
1. 浏览器打开 https://skillhub.cn → 注册 / 登录（用微信或邮箱即可）；
2. 找到「发布技能 / 上传技能 / 成为作者」入口（通常在右上角头像菜单或首页"发布"按钮）；
3. 上传 practice-courseware-skillhub.zip；
4. 填写信息：
- 名称：练习逐题讲解课件（数学）
- Slug：practice-courseware（唯一标识，别人安装后文件夹名）
- 简介 / 描述：直接复用 SKILL.md 顶部那段中文描述
- 分类：选「办公效率」或「内容创作」
- 标签：课件 数学 PPT 希沃 竖式分数 教学（多写利于搜索）
- 图标：上传本技能里的 _icon.png
- 是否免费 / 是否需要 API Key：选"免费 / 不需要"
5. 提交；若平台有审核，等审核通过即上架。上架后就是公开可搜。
验证上架成功：在 WorkBuddy 对话里对自己的同伴说"找一下 practice-courseware 技能"，或让同伴用 find-skills 搜"练习逐题讲解课件"，能搜到即成功。
> 注：发布动作需你本人在 skillhub.cn 用账号完成（涉及登录态，我无法代你登录上传）。但包和文案都已备好，照上面 5 步点完即可。若你希望，我也可以帮你把文案再优化得更"好搜"。
之后无论用哪种方式装上，同伴每次做课件只在 WorkBuddy 里：粘贴习题图片 → 再发一份参考 PPT → 说"用 practice-courseware 做课件"。其余全自动，无需装 Python、无需写 JSON。
