黄老实精品课（huanglaoshi-jpk-html）

本技能把「基础教育精品课」官方模板的排版规范——画布 1280×720、内容安全区、封面文字坐标、
字体字号表、编号层级——全部固化成脚本常量。输入一份 JSON 页面规格即可产出可直接上课的课件。

官方封面/内页底图已内置在 assets/，无需用户提供。 产出物一次到位：课件 HTML + 可编辑 PPTX + 配套 Word 三件套（教学设计 / 学习任务单 / 作业练习），全部按 2026 官方模板规范。

🚦 工作流（Stage-Gate，必须遵守）

本技能不是「一次性出全套」——必须按下面的阶段推进，两个确认门禁未通过前，不得调用任何生成脚本、不得写文件。

阶段 0 · 收集输入（开场第一件事：发填写清单）

🚨 技能一启动，第一件事就是把下面这张清单原样发给老师，请其逐项填写。
在收齐之前，不要分析课标、不要写大纲、不要生成任何文件。

必填 6 项（封面要显示，缺一不可）：

选填（填了更完整）：课时 meta.lesson、学期 meta.semester、教科书全名 meta.textbook、
出版社 meta.publisher、出版日期 meta.publish_date、主题色 meta.accent。

可直接复制给老师的填写模板：

课题：
学段：（小学／初中／高中）
年级：
学科版本：（如 生物学（人教版））
主讲人姓名：
学校校名：

—— 以下选填 ——
课时：（如 第一课时）
学期：（春季／秋季）
教科书全名：
出版社：
出版日期：

收到填写后立刻做三件事：
1. 缺项必追问（尤其学校校名、主讲人姓名——封面要显示，缺了就是空白栏），不要自己编。
2. 按学段换算微课时长（见「精品课时长与录制规格」），并与老师确认一个具体分钟数，
写进 meta.duration，如 { "stage": "初中", "minutes": 15 }。
3. 全部落到 lesson.json 的 meta，然后才进入阶段 1。

> 也可以让老师直接用 assets/meta-form.html 填写（浏览器打开，填完一键下载 lesson.json 骨架）。

阶段 1 · 课标与教材定位

检索《义务教育课程方案和课程标准（2022年版）》对应学段/学科的内容要求与学业要求，
定位本课在教材单元中的位置及前后衔接，结论写进 lesson.json 的 standards（数组，逐条注明出处）。
- 联网检索用 WebSearch；查不到就明说依据是领域知识，不要编造课标条目。
- 需要完整教材分析与备课时，可衔接已装的 lesson-pack 技能。

阶段 2 · 产出大纲 →【确认门禁 ①】

在对话里（不生成文件）给出结构化大纲：课标依据 / 教学目标 / 教学重点 / 教学难点 /
环节骨架（一级环节 + 各环节要点）。然后明确提问：「这份大纲你满意吗？要改哪里？」
- 不满意 → 按意见改，重新呈现，直到满意。
- 满意 → 进入阶段 3。
- 🚨 未得到明确确认，不得往下走。

阶段 3 · 教学设计 →【确认门禁 ②】

补齐 design.process（教学过程详案，按环节写清师生活动），在对话里呈现教学设计要点
（含教学过程梗概），请教师确认。不满意就改、重新呈现；满意则进入阶段 4。

阶段 4 · 批量产出全部材料

python "<skill_dir>/scripts/validate_lesson.py" lesson.json --require materials   # 门禁自检，先跑这个
python "<skill_dir>/scripts/build_deck.py"   --json lesson.json -o "<课题>（第X课时）.html"
python "<skill_dir>/scripts/bento_to_pptx.py" "<课题>（第X课时）.html"
python "<skill_dir>/scripts/build_docs.py"   --json lesson.json -o 输出目录

交付时报告：页数 / 正文字号 / 时长配比 / 警告数（build_deck.py 会打印）+ 三份 docx 路径。

🚨 门禁纪律（三条硬规则）

1. 门禁未通过不得渲染：不调用生成脚本、不写文件——先过审，再渲染。
2. 必须明确提问并等待答复：不要用「如果没问题我就继续出全套」这类默认放行的话术。
3. 教师中途提新要求 → 回到对应阶段修改，改完重新确认该阶段。

> 门禁靠本文件的指令约束 AI 行为（技能没有独立状态机）；validate_lesson.py 提供技术兜底——
> 内容达不到阶段要求时以退出码 2 拒绝，防止「内容没到位就先渲染」。

⏱ 精品课时长与录制规格（决定内容容量，务必先看）

🚨 精品课不是一节 40/45 分钟的完整课堂，而是把一课时内容浓缩成的微课。
教育部《精品课制作要求》（安徽、山西、浙江、福建、广西等多省转发文本一致）规定：

> 单个微课视频时长：小学 10—15 分钟、中学 15—20 分钟。

• 一课（节）如有多个课时，需分别制作多个微课，最多不超过 3 个课时。
• 🚨 教学过程的总分钟数、课件页数都要按这个时长裁剪，不能按整节课的容量铺内容。
  例：中学 15 分钟微课 → 教学过程各环节分钟数相加 ≈15 分钟，课件内容页控制在 6-10 页。
• 每课时提交：微课视频 + 教学设计 + 学习任务单 + 课件 + 作业练习（本技能全部覆盖）。

课件页数怎么定

一页课件约对应 1.5-2.5 分钟讲解（一页 4-7 行，含停顿、举例、强调）：

填了 meta.duration 后，build_deck.py 会自动核对页数并打印「时长配比」，偏离建议区间时告警。
教学设计文档的「教学过程」标题也会自动带上「（约 N 分钟）」。

录制时对课件的其他要求

• 画面比例 16:9——本课件 1280×720 画布天然满足 ✔
• 正文字号不小于 24 磅——本课件正文 32px = 24pt 刚好达标 ✔（全文稀疏时自动放大到 36px = 27pt）
• 课件内容建议靠左排版、右侧预留约 1/3 空白，用于「教师讲解 + 多媒体大屏」形式下教师出镜。
  ⚠️ 官方 PPT 模板本身是满幅的（本技能版式也按官方模板满幅标定）；若你录制时教师出镜占画面右侧，
  请自行把每页正文压在左侧 3/4 内（少写几行、拆页），或用画中画/后期合成。
• 引用地图须使用教材上的地图并标注出处（格式：地图出自 xxx）。
• 视频另有要求：片头 5 秒（含教材版本/学科/年级/课名/主讲教师）、H.264/25 帧、1920×1080、
  建议码率 8Mbps、单个文件 ≤1G。

内容源：一份 lesson.json 喂全部脚本

课件与三件套共用同一个 lesson.json：build_deck.py 读 meta + pages，
build_docs.py 读 meta + design + worksheet + homework，validate_lesson.py 按同一份文件做门禁自检。
改一处全套同步，不必手动对齐两份文件。

可运行的完整样例：examples/lesson.json（6 个一级环节、8 页课件 + Word 三件套，实测全链路通过）——
直接复制改成自己的课题即可。字段分区速查：

{
  "meta":      { "title": "课题", "lesson": "第一课时", "subject": "学科（版本）",
                 "grade": "年级", "semester": "春季/秋季", "textbook": "教科书全名",
                 "publisher": "出版社", "publish_date": "出版年月",
                 "teacher": "黄老实", "school": "学校", "accent": "#01431D",
                 "duration": { "stage": "初中", "minutes": 15 } },
  "standards": ["课标条目（阶段1 写，逐条注明出处）"],
  "design":    { "objectives": [], "key_points": [], "difficulties": [], "process": [] },
  "worksheet": { "goals": [], "pre_tasks": [], "class_tasks": [], "resources": [] },
  "homework":  { "items": [] },
  "pages":     [ { "heading": "一、…", "lines": [], "tip": "", "img": "" } ]
}

快速开始

① 写内容规格 JSON（lesson.json，一份文件喂全套）——一级环节用汉字编号（一、）最多 6 个，二级标题用阿拉伯数字（1. 2.）。完整可运行版见 examples/lesson.json：

{
  "meta": {
    "title": "维护生态安全", "lesson": "第一课时",
    "grade": "八年级", "subject": "生物学（人教版）",
    "semester": "春季", "textbook": "义务教育教科书 生物学 八年级下册",
    "publisher": "人民教育出版社", "publish_date": "2024年12月",
    "teacher": "黄老实", "school": "闽侯县教师进修学校附属中学",
    "accent": "#01431D",
    "duration": { "stage": "初中", "minutes": 15 }
  },
  "standards": ["《义务教育生物学课程标准（2022年版）》「生物与环境」主题：…"],
  "design": {
    "objectives": ["1. …"], "key_points": ["1. …"],
    "difficulties": ["1. …"], "process": ["环节一 ……"]
  },
  "worksheet": {
    "goals": ["1. …"], "pre_tasks": ["1. …"],
    "class_tasks": ["【学习任务一】…"], "resources": ["1. …（建议官方资源）"]
  },
  "homework": { "items": ["一、基础练习", "1. …"] },
  "pages": [
    { "heading": "一、情境导入",
      "lines": ["20 世纪以来，人类活动对地球的影响越来越大。", "地球仿佛寄来一封求助信。"],
      "tip": "〔情境〕今天这节课，我们学习怎样守护共同的家园。" }
  ]
}

> cover / bg 两个顶层键可省略（省略就用内置官方底图），只有确实要换底图时才写——
> 换图会让封面坐标错位，脚本会告警。
> 阶段 2 只填到 meta + standards + design(目标/重点/难点) + pages(heading)；
> 阶段 3 补 design.process；阶段 4 再补 pages(lines) + worksheet + homework。

② 生成课件（正文纯文字满宽 1020px；末页默认追加致谢结束页）：

python "<skill_dir>/scripts/build_deck.py" --json lesson.json -o "维护生态安全（第一课时）.html"

可选参数：--cover / --bg（覆盖内置底图，一般不需要）、--size 36（强制正文字号）、
--no-brand（不加末页结束页）、--strict（有告警即退出码 2）。
lesson 留空则封面标题不带括号；全文每个内容页都 ≤5 行时自动把正文放大到 36px 更舒展。

🚨 底图：默认就用内置的，不要自己找图/生图

封面与内页底图已随技能分发，1280×720（与画布 1:1），每张都有「图片 + 文本」两种同源形态：

> 🚨 SkillHub 禁止上传二进制文件（.jpg/.png 会被跳过，报「不支持的文件类型…禁止上传二进制文件」），
> 因此发布包里只有 *.jpg.b64.txt 纯文本，没有 jpg。脚本按「*.jpg 存在就用 → 否则读同源
> *.jpg.b64.txt」自动选择，两条路产出的课件完全一致。发布包解压后跑一次即有底图，无需任何额外素材。
> 换底图时 jpg 与 b64.txt 必须同时更新，否则本地与发布包做出来的课件不一样。

• cover / bg 留空、路径不存在 → 自动回退内置底图，只打一行提示，不报错。
• 严禁用 AI 生图造底图，也不要去别的技能目录里翻素材顶替——封面文字的绝对坐标
  （标签 123,76；主标题 111,215,w=1059；元信息左列 x=160、右列 x=620，两行 y=396/448）
  和正文安全区（x∈[96,1184]、y∈[96,656]）都是为这两张底图逐像素标定的，换任何别的图都会文字错位、文字压绿条。
• 确实要换底图：脚本会在 stderr 打「非内置官方底图」告警。此时必须同步重标
  create_jingpinke_deck.py / build_deck.py 里的 COVER_* 坐标常量与 SAFE_* 安全区。

> 历史坑：早期版本的底图没有随包分发，SKILL.md 里写的是 F:/.../精品课课件封面图.png
> 这种本机绝对路径。换台机器安装就拿不到图，只能自行找图或生图 → 做出的课件封面/背景全都五花八门。
> 现在底图已内置；因 SkillHub 拒收二进制，底图改为 *.jpg.b64.txt 文本随包分发。

③ 骨架模式（只需确认背景图与坐标时）：

python "<skill_dir>/scripts/create_jingpinke_deck.py" \
  --title "爬山虎的脚" --lesson "第一课时" --grade "四年级" \
  --subject "语文（统编版）" --teacher "黄老实" --school "XX学校" \
  --slides 5 -o "爬山虎的脚.html"

（--cover / --bg 可省略，省略即用内置官方底图。）

④ 页面规格字段：heading 页标题、lines 正文行数组（每行一段）、tip 可选高亮提示行、
img 可选右侧配图路径（仅限用户提供的现成素材）、size/headingSize 可选字号覆盖、notes 放映备注。

• 产物命名自动归一为 <课题>（第X课时）.html，文件名不含 bento。
• 写盘后自动调用 scrub_bento.py 清洗可见品牌字样，生成结束会自检字数/行数/切换并打印警告。
• 旧课件批量补洗：python scrub_bento.py --dir <目录>（幂等）。

硬性规范

1. 放映切换恒为 transition:"none"：每一页（含封面）都必须写。fade/morph/slide/zoom 在内嵌 reveal.js 的黑色容器底上翻页会闪黑（实测核实，勿再尝试）。已生成课件用 set_transition.py 批量修补。也不要给元素加 fx 入场动画。
2. 不得出现可见 bento 字样：标签页标题/加载屏/顶栏 logo/界面文案全部为「精品课课件」等中文文案。scrub_bento.py 只动可见文案，功能性标识符（bento-doc/bento-rt/CSS 类名/MIT 注释）必须保留；#bento-doc 里 "format":"bento/slides" 与运行时校验串必须成对替换，只改一边会静默回退到演示 deck。每次 scrub 完必须用 verify_bento.cjs 截图确认加载的是真课件。
3. 安全区（画布 1280×720）：上下绿色条（y 0~58、677~720）不放任何元素；内页内容 y ≥ 96 且 y+h ≤ 656，x ≥ 96 且 x+w ≤ 1184（封面元素按「字体与字数」表标定的绝对坐标，不受此限）。不要额外绘制标题栏/页脚（背景图已含）。
4. 背景图 base64 嵌入：第 1 页用 asset:jingpinke-cover（黑板封面），第 2 页起用 asset:jingpinke-bg（白色安全区内页），每页全幅 image 置底、各用不同 id（bg-s1/bg-s2…）。
5. 文字写入 #bento-doc 时所有 < 转义为 \u003c；html 字段支持 <br> 换行、<b> 加粗，缩进用全角空格。

字体与字数（中文课件，按 2026 官方 PPT 模板实测）

• 单行 ≤28 汉字（正文框宽 1020px 自然换行）；单页 ≤7 行，有高亮提示行 ≤6 行，超出须拆页。
• 🚨 正文框高度按实际行数算：body_h = len(lines) * 48，不要封顶（多行页会叠字）。
• 一级环节 ≤6 个（汉字编号一、二、…），二级标题用阿拉伯数字（1. 2.），层级只有两级；多页可属同一环节（环节个数按汉字编号去重统计，同一环节的第二页换页标题但编号相同）。
• 内容页数由微课时长决定（见「精品课时长与录制规格」），不做「页数不限」处理。
• 封面实测坐标（官方模板逐元素标定）：标签 x=123,y=76；主标题 x=111,y=215,w=1059,h=105,64px
  （课题超宽时自动按宽度比例缩号、下限 34px，保证单行不折行不孤字，缩号会打 [提示]）；
  元信息左列 x=160、右列 x=620，两行 y=396/448，37px。
• 🚨 课时后缀不要用 <span style="font-size:..."> 缩小——Bento 会剥掉内联样式（实测失效），
  build_deck.py 已改为按估算宽度拆成两个文本元素并排（后缀底对齐主标题框底）。

内页版式（官方模板元素）

• 标题：黑体 40px 居中，x=348, y=149, w=584, h=59。
• 分割线：标题下方 x=353, y=216, w=584, h=2，主题主色（Pillow 生成纯色 PNG，无 Pillow 自动跳过）。
• 菱形装饰：标题左侧 x=293, y=189, w=47, h=49，主色+亮色双色叠加（Pillow 生成）。
• 正文：x=136, y=281, w=1020，华文楷体 32px，行高 1.5。
• 官方主题色对（meta.accent 传主色，脚本自动配亮色）：
  绿 #01431D/#01621F（默认）、红 #711000/#AF0000、蓝 #014E6A/#1784AD。

英语课件字体规范（--lang en）

--lang en 显式指定，或不传时按 --subject 自动判断（含「英语/English」）。中文课件不受影响。

• 英文每行 ≤15 单词（自动校验）；单页 ≤8 行；英文标题用阿拉伯数字编号。
• 英文模式不要套用中文「字少自动放大字号」规则，字号按上表固定。封面标签/元信息/结束页保持中文字体。

末页结束页（可选）

create_jingpinke_deck.py 默认在末页追加结束页：内页背景 + 两行致谢（安全区居中，transition:"none"，华文楷体 32px）。文案在脚本顶部 BRAND_PAGE_TEXT 常量（仅署名与致谢，无网址/账号/链接）；--no-brand 可关。旧课件补结束页：向 #bento-doc 追加同结构 slide（id 用 brand-sN，幂等判断 notes 含「结束页」）。

转可编辑 PPTX

python "<skill_dir>/scripts/bento_to_pptx.py" "秋天的雨（第一课时）.html"   # 输出同名 .pptx

文字是真正可编辑的 PPT 文本框，背景/配图为原生图片；px→pt ×0.75；中文字体写入 latin+eastAsia 双设置防回退。依赖 python-pptx，纯离线。

配套文档三件套（教学设计 / 学习任务单 / 作业练习）

精品课提交除课件外还需三份 Word。build_docs.py 按 2026 官方 docx 模板逐项实测参数生成：

python "<skill_dir>/scripts/build_docs.py" --json lesson.json -o 输出目录

• 官方规范（已固化为常量）：A4 竖版、边距 上下 72pt / 左右 90pt；页眉「基础教育精品课」+ 横线；
  标题宋体 14pt 加粗居中（行距 1.5）；正文与表格黑色宋体五号（10.5pt）；表格 6 列网格
  （官方列宽 56.75/134.65/35.45/92.1/35.45/77.95pt）；「课程基本信息」行底纹 #CCCCCC、
  环节标题行 #D9D9D9；教学过程区行高 216.25pt、作业练习区 418.35pt（均 atLeast）。
• 输入就是同一个 lesson.json（与课件共用，meta 互通，见「内容源」章节）：meta（title/lesson/
  subject/grade/semester/textbook/publisher/publish_date）+ design（objectives / key_points /
  difficulties / process，官方「教学内容」= 重点+难点）+ worksheet（goals / pre_tasks /
  class_tasks / resources）+ homework（items）。缺字段留空并告警。
• 输出三份 docx，文件名默认带课题前缀（维护生态安全（第一课时）-教学设计.docx；--no-prefix 可关）。
• 缺字段会留空并在结尾汇总「警告数」；有告警时退出码为 2（与门禁自检同码，注意区分：这里指字段缺失，不是门禁拦截）。
• 依赖 python-docx（系统 python3 已装；缺时 pip install python-docx）。
• 官方备注提醒：推荐学习资源务必用官方资源，避免出现非官方的二维码和链接。

配图页规范（仅限用户提供的现成素材）

默认纯文字、正文满宽 1020px（x=136）。build_deck.py 支持页面规格里的 "img" 字段（用户提供素材时）：
Pillow 统一处理为 800×800 JPEG 后 base64 嵌入 doc.assets（未装 Pillow 则回退原图直嵌并提示）；
配图放右侧 x=824, y=281, w=360, h=360，正文框收窄 w=672（每行 ≤20 字）；
高亮提示与正文同左缘同宽（x=136；无配图 w=1020／有配图 w=672），
y = max(正文底, 图片底) + 16。文字密集页（清单/作业类）不配图。

自检与分发

• 逐页截图：node "<skill_dir>/scripts/verify_bento.cjs" "<课件>.html" "<输出目录>" 20（路径用正斜杠）。截图含编辑器外壳属正常，只看中间画布；核对无叠字、无越界、加载的是真课件。脚本会自动探测 Edge/Chrome，探测不到可用环境变量 CHROME 指定。
• 模板壳 assets/Bento_Slides.bento.html + 官方底图 assets/jingpinke-cover.jpg.b64.txt / assets/jingpinke-bg.jpg.b64.txt 随技能离线分发，所有脚本无网络请求、无外链跳转，可公开分发。
• 模板壳内嵌 Bento Slides 运行时（MIT License — © 2026 The Bento authors，内含 reveal.js 亦为 MIT）。文件头的开源许可注释必须保留，这是 MIT 的合规要求，也是 scrub_bento.py 刻意不洗的部分。
• 🚨 打包发布前必查（发布包必须全是文本文件，SkillHub 拒收任何二进制）：
  assets/ 里 Bento_Slides.bento.html + 两份 *.jpg.b64.txt 一个都不能少；.jpg / .png 一律不要打进发布包。
  缺底图＝别人做出的课件封面/背景全不对。发布后建议在干净目录解压装一遍、不传任何图跑一次，确认产出的封面是黑板、内页是绿条。
• 美术类课题 accent 可换官方红 #711000（亮色 #AF0000）。