Agent Skill

第四代交互式课件

第四代交互式课件,在html课件中设置多个互动仿真、互动测试、内容讲解中也设有丰富的交互环节,支持学生扫二维码参与各项互动、仿真与测试,在互动测试页面中学生答案会自动汇总到教师端并统计,支持页面内容随鼠标点击逐步播放……

教育学习·王珏·来自 skill_hub·skillhub.cn ↗
skillhub install @user_2761353a/interactive-courseware-builder
12 Stars·13.7万 综合热度·17,161 字文档·源站更新 2026-11-22

README 文档

17,161 字

Interactive Courseware Builder

Build production-ready interactive courseware as a single HTML file — from instructional design to deployed classroom tool.

Design philosophy: 「骨架不变,内容可填」— infrastructure (page-flip, navigation, responsive CSS, quiz engine, MQTT) is locked down in references/templates/; only content changes per courseware.


⚠️ 硬规约速查(30 条,加载后必须执行,不可跳过)

| # | 规则 | 违规后果 | |:--:|------|----------| | 1 | 讲授页标题(teach-title)禁止加入 reveal 队列——进入页面即见 | 标题被隐藏,学生不知当前主题 | | 2 | 测验页/仿真页/封面页禁止调用 setupReveal——内容直接可见 | 破坏答题/仿真交互、进度感知 | | 3 | MQTT CDN 必须钉 mqtt@4.3.7(UMD)+ async + 多源 fallback | v5 ESM 导致全页 JS 崩溃;手机扫码卡封面 | | 4 | AI 生图引擎四选一(v1.10.0):阶段一勾了「AI 生图」后,须再弹 AskUserQuestion 单选引擎,四选项按图判据排序并预置「(推荐)」——① ImageGen(WorkBuddy 自带,无密钥时兜底)/ ② TT Image 2.6(tt-image-2.6,默认推荐:无中文或 ≤100 字、无复杂空间关系)/ ③ Banana 2.1(banana-2.1,中文 >100 字或复杂空间关系)/ ④ Banana Pro(banana-pro,小字号、关键教学图、一字不错);价格/密钥/参数族唯一来源=workflow-design.md §2.3.2;方案表须逐图填实际模型 ID | 引擎未定、乱扣积分、图形与模型档位错配 | | 5 | 有图有文的页面禁止图片堆底部——宽幅全宽居中、机制图浮动并排 | 图文脱节,教学效果差 | | 6 | Step 4 = 4A(改 HTML)→ 4B(部署),不可只做 4B | 学生扫码后无提交按钮、无 QR 徽章 | | 7 | Canvas 三要素同步:<canvas id> ↔ drawXxx() ↔ onPageEnter 调用 | Canvas 白屏、仿真不运行 | | 8 | submitQuiz 先写入本地 xmnAgg,再 xmnPublish | MQTT 延迟/丢包→教师端看不到数据 | | 9 | 前测题目只考已有经验、暴露前概念——绝不出现本课任何新术语/新概念 | 前测变成「教新课」而非「摸底」 | | 10 | MQTT broker 必须按 CLASSID 确定性选择(xmnBrokerHash),禁止两端各自独立 fallback | 手机/电脑落到不同 broker→数据永不同步 | | 11 | 图片全屏灯箱:所有课件图片必须支持点击放大/再点击收回(骨架已内置) | 教学图片无法细看 | | 12 | 总结页必须从 4 套框架选 1 套(V1 全景关系图/V2 链式问题/V3 双栏知识树/V4 模块卡片),不再用旧版要点卡片。见 workflow-dev.md 总结页 | 总结页缺乏结构化交互 | | 13 | Step 0 教学环节选择不可跳过:AskUserQuestion 复选框(multiSelect)问「您需要哪些教学环节?」——内容讲解 / 互动测试 / 互动仿真(封面+总结恒有);用户已指定则跳过;「全自动执行」或无效选择 → 三项全选 | 课件缺环节或页面构成错误 | | 14 | AI 生成图片内文字必须 100% 纯中文(英语课除外),杜绝任何装饰性英文 | 中英混杂干扰理解 | | 15 | AI 生图的知识理解图必须是信息图形态(图文结合、文字精简、忌纯文字海报);提示词须显式声明「图内文字全部简体中文」 | 纯文字海报、图内中文乱码 | | 16 | 经验锚点与情感连接:每课件 Step 1 必须产出「经验-情感主线」+ 学情画像;每页 ≥1 个经验锚点(学生已知/可感/关心的具体事物或现象);全课件 ≥1 处前沿连接——编织进引入/讲解/总结,禁做独立页或挂件(2026-10-12 定案);引入页禁止定义/公式开头;举例与巩固题情境须取自经验域;禁杜撰假情境。细则见 workflow-design.md §1.1/§1.2.1/§2.1.1~§2.1.3 | 情境与知识两张皮、为情境而情境、课件变讲故事 | | 17 | Step 3 静态产物零二维码徽章:不得含 .qr-badge 元素/加入弹窗/xmnBadgeSync/ISDEPLOYED 闸门(均属 Step 4 注入专属);只需保证 #navBtns{z-index:500}。见 Step 3 段 | 静态页误导扫码;与 Step 4 注入冲突 | | 18 | 图片来源两阶段弹窗:需要图像时必须 AskUserQuestion——① 复选来源类别:搜索网络图片 / 内联 SVG 手绘 / AI 生图(可多选);② 勾「AI 生图」再单选引擎(ImageGen / TT Image 2.6 / Banana 2.1 / Banana Pro,判据见 workflow-design.md §2.3);知识图表类恒走内联 SVG(规则0)不进弹窗;选定 duomi 模型后只查该模型的密钥,未配置则发该模型的单条引导话术;三把密钥互不相通(DUOMITT26KEY / DUOMIBANANA21KEY / DUOMIBANANAPROKEY),拿错钥匙报 401、绝不静默降级;密钥只存环境变量,禁止写进技能文件/config.json/课件 HTML | 图片来源不明、乱扣费、密钥泄露、拿错钥匙 | | 19 | 答案位置分布防呆:同一测验内正确答案不得全部集中在同一选项位置(典型:全 A/全 B;多选题不得每题都含同一位置)。出题后必须跑 node scripts/quiz-answer-check.js <课件.html> 须 RESULT: PASS;命中则逐题打散选项顺序并同步改 answer 后复跑。见 workflow-design.md §1.3.2 规则三 | 学生看出规律「全蒙 A 即满分」,测验失去甄别力 | | 20 | 页面零「教师入口」提示 + 控制端唯一(v1.7.0):① 任何页面内 UI(浮条/toast/banner/文案)一律不得出现「连点页码进教师模式」类提示——学生看到会自行连点夺取控制端权限;教师入口只靠线下交付话术(delivery-playbook §5)。② 两段式教师入口:1.5s 内双击页码仅「武装」,再点右下角封面徽章才切教师(学生误触需凑两段)。③ 控制端唯一三规则:首师优先(since 仲裁,迟到设备不夺权)/ 失联自动接管(防闲屏)/ 健康首师不可抢(观察态提示窗无按钮,仅长按 1.5s 后门)。完整实现见 workflow-deploy.md C/F 行。回归 pagesync S5/S13/S19 | 学生自行夺权、多控制端闪跳、首师被夺、控制端崩溃后课堂冻结 | | 21 | 封面必须有深色背景:.page.active .cover-page 自带 color:#fff(白字),必须同时声明深色 background(骨架已内置「主题渐变+深色蒙版」);封面 section 需 #p0{padding:0;overflow:hidden} 才满幅。改封面后跑 node scripts/cover-contrast-check.js <课件.html> 须 RESULT: PASS | 首页白底白字、标题完全看不见 | | 22 | 图文层叠 + 揭示顺序由骨架机制保证,不得绕开:① 图片(.fig/.reveal-img-group/.page-img)恒 position:relative;z-index:2,文字块(含背景条/.key-box/.card)禁止 z-index ≥ 2;② 揭示顺序一律按版面视觉顺序(先上后下、同行先左后右),组内由 revealSortEls 自动排序、连点由 revealPlaying 快进定格,不得改回按 DOM 顺序分配 seqDelay。改后跑 node scripts/reveal-layout-test.js 须 ALLPASS | 文字压图、动画倒序(下面先出/右面先出),破坏「教一段测一段」节奏 | | 23 | 学生身份登记 + CSV 留档(v1.6.5 定案):登记入口=封面徽章弹窗(qrPopupjoin);学生端仅封面徽章可见(守卫须 DOM 就绪后再跑一次);身份只走 XMNIDENTITYTOPIC(qos0/不 retain,绝不随答题消息上公网 broker);导出仅 quizrecords.csv(11 列/UTF-8 BOM/题干+全部选项/汉字正确错误);导出入口两处(导航条自动注入 + 后测弹窗),xmnExportInit 幂等;清空不落盘。完整八点细则唯一见 workflow-deploy.md ⑩⑪ 节;存量迁移 checklist 同文件 | 学号姓名泄上公网 broker;CSV 看不懂/乱码;导出按钮错位成通栏;重复下载;清空即丢档 | | 24 | 页码胶囊恒可见(v1.8.1,用户 2026-11-13 定案;v1.13.2 指针化):唯一真源 = references/pitfalls.md §三 QR 徽章节「首页页码不可见」条目 + workflow-deploy.md(含底部居中胶囊定位式、实底样式、13vh 安全区、内联 font-size 兜底全部细则)。四条判据:① #navBtns 底部居中(bottom:20px !important),绝不放页面顶部;② 深色实底胶囊(background:var(--primary)、border-radius:999px、页码白字)解决撞色隐形;③ z-index 500 恒顶层不被盖住(⛔ step4 注入 !important 反压更高值会造成新旧课件两个层级);④ 「突出在最上方」= 顶层(z-index),不是页面顶部位置。校验 nav-visibility-check.js(回归 deploy-state-test 三条 z-index 断言) | 首页页码隐形、封面末行被裁、页码被其它元素盖住 | | 25 | 双版本交付(v1.9.0,用户 2026-11-14 定案;v1.13.2 指针化):唯一真源 = workflow-deploy.md「4B 前置 · 命名真源」节(含命名式、独立节点铁律、#25a 只导入不发布、库内链接地址式全部细则)。四条判据:① Step 4 部署完成后必须跑 python scripts/deliverversions.py --dir <课件目录> --step3 <Step3产物.html>,生成单机版 + 在线版两份文件并保留;② 单机版自动上传资料库独立新节点(绝不覆盖在线版 nodeid);③ #25a:单机版只导入、不发布(公开发布页点编辑丢标签状态跳回第一页),交付链接用库内地址 https://www.workbuddy.cn/space/d/<单机版nodeid>;④ 版本号存 step4.json 的 version 字段(默认 v1.0,重发带 --bump)。话术 verbatim 见 delivery-playbook.md §6 | 只交一份文件、单机版丢失无法资料库编辑、上传覆盖在线版节点、误用发布页链接致编辑跳回第一页、交付未告知双版本用途 | | 26 | 字号体系:分级 / 分场景 / 三载体同步 / 尺寸联动(v1.11.1;v1.13.0 指针化):数字唯一真源 = references/typography.md(桌面尺 §1 / 手机档 §2 / 地板定义 §3 / 联动比例 §4 / 三载体换算 §5 / 语义角色 §6 / 变更规程 §7)。四条判据:① 五档分级不混用(L1 封面 / L2 页标题 / L3 正文题干选项按钮 / L4 图注辅助提示 / UI 控件),层级比 L2/L3 ≥1.2×;② 按场景分档——桌面(投影 3 米)与手机(≤768px 近距)两套字级,手机端整组变量降档,媒体查询内禁写死 px;③ 三载体同步——CSS / SVG / Canvas 必须同时改(换算见 §5),只改 CSS 必致「页面字大了、图里字还是旧尺寸」;④ 尺寸随字号——条高、圆半径、行高、画布余量一律按 §4 比例由字号推导,字号变则尺寸同变。未做后果:字级不同源 → 新课件 T1 全 FAIL(实测 14 项纯误报);只改字号不改尺寸 → 字大点小、条内数字被压。校验 measure-render-font.js + readability-check.js;D14 自动比对「文档表值 ↔ 骨架 --fs-* ↔ 脚本阈值」三方一致 | 字号与图形不匹配、图里字过小、手机字挤成多行、行距不协调、阈值不同源致全面误报 | | 27 | 按钮一律「反色底 + 白字」(v1.11.1,用户 2026-11-16 定案;v1.13.1 指针化):唯一真源 = workflow-design.md §1.7(含主/次按钮配色类名、导航/图标键、覆盖范围枚举、内联 style 禁令全部细则)。四条判据:① 所有按钮必须实色底 + 白字并带 hover 加深或阴影,禁止透明底/浅白底/仅描边;② 主按钮 = var(--accent) 橙底(.btn-primary),次按钮 = var(--primary) 深藏青底(.btn-retry);③ ≥2 个按钮并存必须先定唯一主动作,主次分明;④ 禁止内联 style 写反色,一律收敛到 CSS 类(引擎自注入 .opt-confirm 同规)。未做后果:按钮投影上不醒目、主次不分、学生看不清可点位置 | 按钮投影上不醒目、主次不分、学生看不清可点位置 | | 28 | 两个交付提示页:生成即呈现(v1.12.0,用户 2026-11-16 定案;v1.13.2 指针化):唯一真源 = delivery-playbook.md §1.1 / §5 / §5.1(两页文字 verbatim 原文)+ 母版 templates/step3-hint.html / templates/teacher-hint.html(占位符与同源样式全在内)。四条判据:① Step 3 收尾必生成 Step3部署前提示<课件名>.html(占位 {{TITLE}}/{{STANDALONEURL}});② Step 4 部署成功后必生成 教师必看<课件名>.html(占位 {{TITLE}}/{{URL}}/{{PAGES}}/{{STANDALONEURL}});③ 两页必须用 presentfiles 呈现——不得只口述、不得以聊天红框替代、不得省去;④ 两页样式同源(红 #D93025 正文不加粗 + .hl 加粗重点、左 8px 红边、底 #FCE8E6、max-width:820px),改样式只改母版 | Step 3 只发聊天红框→用户手里无复盘文件;Step 4 教师必看不呈现→教师找不到入口与补救方法 | | 29 | 信息层控件与数据可视化必须跟随字号(v1.12.1;v1.13.0 指针化):① UI 控件字号 = UI 档——状态条(已连接)、退出教师键、页码芯片同档,禁大于正文档;判定为 UI 的元素应在骨架上加 data-ui="1" 显式声明(判据见 typography §6)。② 可视化容器尺寸由字号推导——条高/圆半径/行高按 typography §4 联动比例由字号推导,禁留旧值;窄条放不下文字时文字外移,不得被父级 overflow:hidden 裁掉(裁剪责任下移到填充体)。③ 双副本同改:templates/detail-modal.html + scripts/step4_inject.py。断言 D13 | 状态按钮比菜单大一圈;24px 字装 18px 条被裁切;外移标签看不见 | | 30 | 用户改稿同步 = 文本级增量替换,禁重注入(v1.14.0):教师改完资料库单机版后说「请将我刚刚修改的 html 课件更新到网站链接中」→ 唯一执行真源 = workflow-deploy.md §4C(七步流程 + 三脚本)。四条判据:① 只在已注入在线源上替换文本,禁止重走 4A(丢已修样式+触发身份/MQTT/CSV 全套回归);② 资料库导出 HTML 必先剔除编辑器标记(data-page-node-id/data-pnid-children/<!--pnid:...-->/inject.js);③ 读写用 rb/wb 保 CRLF(文本模式会造全文件假 diff),替换锚点带完整标签且断言 count==1(纯文本会命中多处);④ 改稿同步不 bump 版本号、链接不变(只新交付才 --bump)。交付话术见 delivery-playbook.md §6 | 重注入丢已修样式/全套回归;编辑器标记带进线上;CRLF 假 diff 误判整页改动;纯文本锚点改错位置;链接/版本号无谓变动 |

完整坑表(按踩坑时点分五节)见 references/pitfalls.md。

📌 真源登记表(v1.14.0,单一事实来源地图)

维护铁律:① 同一规则只允许一个真源文件,其余位置(含 SKILL.md 本表与坑表)一律为「判据 + 指针」;② 修改细则只改真源文件,改完后本表对应行的「断言编号」就是验收手段;③ 新增规则时先定真源归属再写条目,登记进本表并给 auditskillself.py 加断言。

| 规则域 | 唯一真源 | 硬规约 # | audit 断言 | |--------|----------|:--:|------------| | 按钮样式(主次/配色/内联禁令) | workflow-design.md §1.7 | 27 | 「按钮规范断言」(§1.7 标题 + 真源声明在位) | | 字号体系(五档/双场景/三载体/联动) | typography.md(§1~§7 全域) | 26 / 29 | D14 自动比对「文档表值 ↔ 骨架 --fs-* ↔ 脚本阈值」 | | 移动端适配(版芯/输入框/媒体查询) | typography.md §10 | (#26 场景判据②) | D14 + readability-check.js | | 命名 + 双版本交付(含 #25a) | workflow-deploy.md「4B 前置 · 命名真源」节 | 25 | 「交付话术单源 delivery-playbook.md 存在且被引用」+ 本节存在性断言 | | 学生身份 + CSV(八点细则) | workflow-deploy.md ⑩⑪ 节 | 23 | 「#23 细则单源在 workflow-deploy」 | | 页码胶囊样式细则 | pitfalls.md §三「首页页码不可见」条目 | 24 | 「硬规约 #24 在位」指针断言 | | 两交付提示页(文字/母版/样式) | delivery-playbook.md §1.1/§5/§5.1 + templates/step3-hint.html、teacher-hint.html | 28 | F10 四条断言(占位符/同源样式/呈现要求) | | 交付话术 verbatim | delivery-playbook.md | (#25/#28 载体) | 同上 | | 图片来源 + 生图引擎 + 密钥 | workflow-design.md §2.3 / §2.3.2 | 4 / 18 | F9 五条断言(四档引擎/三把密钥/参数族) | | 教学控制(教师入口/控制端唯一) | workflow-deploy.md C/F 行 | 20 | pagesync-test-mqtt.js 40 项回归 | | 教学环节/经验锚点/情境 | workflow-design.md §1.1~§1.3 / §2.1 | 9 / 13 / 16 | 门控总表引用断言 | | 用户改稿同步(发布后更新) | workflow-deploy.md §4C | 30 | F12 断言(§4C 存在 + #30 指针 + 三脚本参数化 + §6 新话术在位/旧串清零 + 母版未变) |


⚡ 安装/加载完成 · 必须告知(首次交付总结原样包含)

① 告知话术(原样发送):

每当课件需要图像时,我会弹窗让您在「允许的图像来源类别」中勾选(可多选):① 搜索网络图片(零积分,真实照片/真实场景)② 内联 SVG 手绘(零积分、自包含、中文精确,但不支持写实/场景图)③ AI 生图。 若勾选了「AI 生图」,我会再请您单选一个 AI 引擎,共四个:① ImageGen(WorkBuddy 自带,无需配置,按积分计费,图像质量与中文一般)② Image 2.6(约 0.017 元/张,最便宜,汉字偶尔出错)③ 纳米香蕉 2.1(约 0.07~0.12 元/张,字多或结构复杂时用)④ 纳米香蕉 Pro(约 0.12~0.18 元/张,汉字最稳)。我会按本课件图片的特点预先推荐其中一个。 除 ImageGen 外,每个模型各用一把独立密钥、互不通用;选定后若该密钥还没配置,我会再告诉您去哪儿创建(密钥只存本机环境变量,绝不写进技能文件)。

② 费用:ImageGen ≈ 5–10 credits/张(生成前告知);内联 SVG / 网络图片 = 零积分;TT Image 2.6 ≈ 0.017 元/张、Banana 2.1 ≈ 0.07~0.12 元/张、Banana Pro ≈ 0.12~0.18 元/张(duomi6699.com,各自需配置 API Key;按次计费与尺寸无关)。方案表须给出「张数 × 单价 ≈ 总额」预估。图片来源的选择与配置见 workflow-design.md §2.3;知识图表类恒走内联 SVG(规则0),不受弹窗影响、不花积分。


🚪 门控总表(渐进披露——先读对应文件再动手)

时点必读内容
Step 1/2 开工前references/workflow-design.md框架+详细设计全量细则(页面规划/测验分布/前测四要素/题型/五类图片五条规则/仿真模板/图片来源两阶段弹窗/三档 duomi 模型判据与三把密钥/图文混排/学情画像/经验锚点/引入页三要素/前沿连接编织式)
Step 1 学情画像与锚点设计时references/experience-anchors.md学段×学科经验域种子表 + 选用规则 + 红线(硬规约 #16 配套)
Step 3 开工前references/workflow-dev.md开发全量细则(骨架/配置块/版芯/自检表/渐进呈现/灯箱/总结页4框架)
Step 4 开工前references/workflow-deploy.md部署全量细则(4A十一步注入/MQTT坑/标准件A~H/#23 八点细则/存量迁移checklist/发布坑表/验收/排障)
Step 3/4 交付前references/delivery-playbook.md交付话术单源(Step3 部署前提示页原文与警示句/教师必看六条原文+补救段+改课件双链接段/红框与 HTML 卡片规格/门控顺序铁律/链接三铁律;Step 3/4 交付都必须生成并 present_files 呈现对应提示页)
用户改稿同步时references/workflow-deploy.md §4C助手侧唯一执行真源(七步流程:导出→净化→提取改动→增量替换→回归→带原 node-id 重发→逐条线上核验→同步本地;三脚本;禁重注入/不 bump)
任何时候排查坑references/pitfalls.md坑表全集(按踩坑时点五节分组 + 速查索引 + 交付前总览)
调字号 / 改图形尺寸前references/typography.md字号体系唯一真源(桌面尺/手机档/地板定义/联动比例表/三载体换算/语义角色表/10 处变更落点/反过拟合要求);其它文件禁抄数字
改模板后references/template-sync.md模板同步清单
配色/交互/仿真参考color-schemes.md / interaction-catalog.md / simulation-patterns.md6 配色 / 49 种交互(8 类) / 5 仿真模式

门控是硬性的:未读对应文件不得开始该 Step;本文件只保留骨架与铁律,细节一律以上表文件为唯一事实来源。


📍 进度指示与执行纪律

  • 每次回复以 📍【Step N/4 · Step Name — N.m Substep】 开头;结尾「现在完成了 X,下一步做 Y。」
  • 每个 Step(Step 0~4 全部,无一例外)结尾都必须提供显式用户确认门控,且门控必须用 AskUserQuestion 组件实现——禁止用纯文本提问、口头询问代替组件(2026-10-02 抽屉原理课件复盘)。如果用户明确要求采用“全自动模式”,可合并为一次总确认,但绝不静默跳过。
  • Code edits:一次改一个函数,改后 node scripts/syntax-check.js <课件.html> 验证;替换代码块后确认全局工具函数(drawArrow/drawLabel/drawDashedLine)仍在。
  • 交付话术是 verbatim-only,唯一事实来源 = delivery-playbook.md:Step 3 步骤中聊天内红框须为部署前提示页 HTML 的全文(标题+副标题+1~4 条,逐字一致,禁摘要/禁只放单句)、Step 4 六条教师须知(含【学生填错的补救方法】段、第 6 条双链接段与收尾句)必须逐字原文、红色大字号,不得改写缩写;Step3部署前提示<课件名>.html 与 教师必看<课件名>.html 生成后都必须 presentfiles 呈现给用户(硬规约 #28)。
  • Bug 修复后立即回填模板;改任何模板后跑 template-sync.md 清单 + python scripts/auditskillself.py。

Step 0 — Teaching-Elements Selection(教学环节选择,硬规约 #13)

用 AskUserQuestion 组件(multiSelect: true 复选框) 询问「您需要哪些教学环节?」,三个复选框:

复选框对应页面类型
☑ 需要内容讲解teach(讲授页)
☑ 需要互动测试pre-test / mid-test / post-test
☑ 需要互动仿真sim(Canvas 仿真页)
  • 封面页(cover)+ 总结页(summary)恒有,不入选项、不可取消。
  • 勾选项 → 页面构成:勾「内容讲解」出 teach 页;勾「互动测试」出测试页;勾「互动仿真」出仿真页;不勾某环节则不出该类页面。
组合(勾选内容)页面构成裁剪要点
讲解+测试+仿真(全勾,默认)全类型无裁剪
测试+仿真(不勾讲解)无 teach 页仿真页承担测验间隔职能;前测=摸底+直接探究;reveal 规则自动失效;中测通常 1 个
仅仿真(只勾仿真)cover/sim×N/可选简化 summary无测验页(MQTT 仍可用);仿真页数不限;总结页用 V1 单页版;每仿真页附 3–5 行观察要点

流程:用户已指定环节/前置传入 → 跳过询问;未指定 → AskUserQuestion(文案含默认兜底说明「30 秒内未选择默认方案:三项全选」);跳过/取消/回复「继续」等无效选择 → 三项全选并声明;「全自动」→ 直接三项全选并开场声明。 确定后输出确认:📍 已选教学环节:内容讲解 / 互动测试 / 互动仿真(N 项)+ 页面构成影响,然后进 Step 1。


4-Step Workflow(骨架)

Step 1 — Framework Design → 读 workflow-design.md

产出框架级设计:① 基本信息(学科/主题/年级/课时)+ 学情画像(学生经验域清单 + 情感激发候选,经 experience-anchors.md 自动生成,门控时请用户确认/替换);② 模块与页面规划(3–6 模块、全 10–18 页、仿真 1–3 个,页面列表含「经验锚点」列)+ 经验-情感主线表(硬规约 #16);③ 测验系统(1 前测+N 中测+1 后测;相邻测验严禁连排;只用选择题;前测四要素);④ 仿真计划;⑤ 图片计划(先用 AskUserQuestion 两阶段弹窗定来源:阶段一复选类别,阶段二勾「AI 生图」时单选引擎——按 §2.3.2 三条判据预置推荐,见 §2.3;再按五类图片+规则0/A/B/C/D 落表,AI 图逐行填模型 ID 与费用);⑥ 配色(默认 Deep Blue #1A3A5C);⑦ 总结页框架推荐(V1~V4 选 1,给用户确认)。→ 用户批准门控。

Step 2 — Detailed Design → 读 workflow-design.md

产出逐页设计:每页 = 线框(ASCII)+ 全部文字 + 图片(来源/提示词/尺寸/位置)+ 交互(≥1个/页)+ 仿真 spec(8 字段模板)+ 测验全题(正确答案位置须在各选项间打散、分布合规——硬规约 #19,出题后跑 quiz-answer-check.js 须 PASS);每页必填「经验锚点」与「情感触发器」,引入页按三要素设计(硬规约 #16);全课件含 ≥1 处编织式前沿连接;后测含 ≥1 道真实情境迁移题。数据准确性强制(事实数字须可靠来源);每张图逐张验证,错即重生成。→ 用户批准门控(门控形式为 AskUserQuestion,文案含默认兜底说明「30秒内未选择默认方案1」)。

Step 3 — HTML Development → 读 workflow-dev.md

从 references/templates/courseware-skeleton.html 复制起步(含全部 CSS/翻页/测验引擎/reveal/灯箱),页面从 page-templates.html 复制改数据。关键铁律:

  • getPageParam 为 URL 参数唯一入口(禁止 new URLSearchParams(location.search))
  • var curPage = 0; 固定命名(旧名须桥接 window.xmnCurIndex)
  • IMG_PREFIX='img/';grep 'src="deploy/' 必须 0 残留;img/ 按 HTML 所在目录解析(HTML 在项目根 → 图放 <项目>/img/,不得放 deploy/img/),prepublish-check.py 的「本地图片引用 N 处,缺失 M 处」必须 M=0
  • 版芯占满 100% 宽高,内容多纵向滚动,严禁横向拉伸/缩小版芯
  • 滚动区让位(v1.11.0,硬规约 #24 配套):骨架 #pageContainer 已内置 margin-top:48px(让位导航)+ margin-bottom:78px(让位页码胶囊,方案A);不得删除/覆盖此让位,确保滚动区底边恒在页码顶边之上。回归:node scripts/readability-check.js <课件.html> 的 F1 断言须 PASS
  • 默认不放全屏按钮(F11 引导);伪全屏兜底 CSS 三条保留
  • 完成后跑 §3.7 质量自检全表 + ≥1 轮修复验证;可读性回归 NODE_PATH=<playwright> node scripts/readability-check.js <课件.html> 须 RESULT: PASS(与 nav-visibility-check.js 职责独立,两者均须 PASS)
  • ⛔ Step 3 产物零二维码徽章(硬规约 #17):静态 HTML 不得含 .qr-badge 元素/加入弹窗/xmnBadgeSync/ISDEPLOYED 闸门——二维码徽章是 Step 4 专属,由 step4_inject.py 注入时生成。禁止「先埋进静态页再用闸门藏起来」。Step 3 只需保证 #navBtns{z-index:500}。徽章规范见 workflow-deploy.md §4A.3。

⚠ Step 3 交付纪律:交付消息顺序、部署前提示页原文、show_widget 红框渲染规格、门控顺序铁律——一律按 delivery-playbook.md §1/§1.1/§1.2/§3 执行(唯一事实来源,勿在此复述)。用户批准门控置于红框之后的「下一轮」(AskUserQuestion 组件,禁止纯文本提问代替)。

⛔ Step 3 收尾必做(硬性,硬规约 #28):在课件目录生成 Step3部署前提示<课件名>.html(母版 templates/step3-hint.html,只替换 {{TITLE}}/{{STANDALONEURL}},文字按交付手册 §1.1 原文),并必须用 presentfiles 呈现给用户——务必呈现,不得只在聊天里口述、不得以聊天红框替代该文件。

Step 4 — Student Interaction & Deployment → 读 workflow-deploy.md

Step 4 = 4A(改HTML)→ 4B(部署),用户说「部署」即完整 4A+4B。 全量细则(十一步注入表、A~H 标准件、#23 八点细则、存量迁移 checklist、发布坑表、排障)见 workflow-deploy.md,此处只列必跑命令与铁律:

4A 十一步注入:首选 python scripts/step4inject.py --config step4.json --html <课件> --probe 探针全 OK 后 --apply(模板件+7 集成点+⑩⑪ 身份/CSV 已固化,函数边界由 scanbraces.py 定位,写盘自动括号复扫、失败回滚;每课只写活动清单小 config;hand-wired 仅兜底)。注入后必跑:

node scripts/pagesync-test-mqtt.js <课件.html>                      # 教学控制回归(共 40 项)ALL PASS 才可发布
NODE_PATH=<jsdom> node scripts/identity-badge-test.js <课件.html>   # 身份+CSV 回归(30 项)
NODE_PATH=<jsdom> node scripts/deploy-state-test.js <课件.html> --config step4.json   # 部署态验收 ≈105 项;E2/E3/E4/E7-E9 属 v1.6.0 旧规约,v1.6.5 预期 FAIL,勿照其改码

4B 资料库发布(唯一路线,禁 CloudStudio):发布前必跑 python scripts/prepublish-check.py <课件.html> [--node-id <id>] PASS;发布 python scripts/publishtolibrary.py --dir <目录> --token host;新课件两步法:新建拿 nodeid → 带 --node-id 重发一次(否则 PUBLISHBASE 空产出坏码 + MQTT 话题串台);重发必带 --node-id;发布目录纯 ASCII;解析 KSIMPORTOK 判成功;单文件回退时核图片 naturalWidth>0。

发布后验收四件套 + 1 项人工教学核验:① playwright 页数核对;② 四常量(NODEID/PUBLISHBASE/SYNCTOPIC/CLASSID)非空且非 DEFAULT-CLASS;③ getComputedStyle 判学生视角;④ 显式规则断显隐;⑤ 人工教学核验(硬规约 #16):逐页核对经验锚点覆盖率(0 锚点页=不合格)、引入页形态(现象+冲突问题,非定义/公式开头)、前沿连接 ≥1 处且编织于引入/讲解/总结中。再跑 verify-library-online.js 核线上真身。

交付铁律与话术:裸链禁令、URL 独占一行、六条教师必看原文(含【学生填错的补救方法】段、第 6 条双链接段与收尾句)、红框两形态、门控顺序铁律、发消息前自检五问——一律按 delivery-playbook.md §2~§5.1 执行(唯一事实来源,勿在此复述)。

⛔ 部署后必做(硬性,硬规约 #28):在课件目录生成 教师必看<课件名>.html(样式按 §4.1、文字按 §5 + §5.1 原文),并必须用 presentfiles 呈现给用户——务必呈现,不得只在聊天里口述、不得以聊天红框替代该文件。

⛔ 双版本交付(硬规约 #25):教师必看 生成后必须运行 python scripts/deliverversions.py --dir <课件目录> --step3 <Step3产物.html>(重发带 --bump),生成 <课件名>(单机版-<版本号>).html 与 <课件名>(在线版-<版本号>).html 两份文件,单机版自动上传资料库独立新节点(只导入、不发布,硬规约 #25a——绝不能对单机版跑 publishpage.py,交付链接用库内地址 https://www.workbuddy.cn/space/d/<单机版node_id>);交付消息必须包含两个文件完整路径 + 各自用途 + 单机版资料库预览/编辑链接(话术见 delivery-playbook.md §6)。


模板与工具清单

templates/(复制不改为主):courseware-skeleton.html(起步骨架)· page-templates.html(各页型模板)· page-flip-system.js(翻页+getPageParam,最先复制)· quiz-engine.js(测验引擎)· matching-quiz.js(连线/分类巩固题)· canvas-engine-patterns.js(绘图工具)· infographic-generator.js(生图提示词规则 + 四模型选择与命令模板)· summary-v1~v4-*.html(总结页4框架)· Step 4 注入件:mqtt-framework.js(含 showToast/showConfirmModal/updateBadgeStats,唯一一份;含 identity 订阅/路由)· unified-quiz-submit.js(含 xmnIdentityReport() 调用)· qr-badge-injection.js · detail-modal.html + detail-stats.js · teaching-control.js(A~H 标准件 + onClaim 学生端早退守卫,第⑨步必注入)· student-identity.js(第⑩步:封面学号/姓名登记 + localStorage + identity topic 上报) · csv-export.js(第⑪步:教师端导出 quizrecords.csv,UTF-8 BOM) · fullscreen-fallback.js(默认不注入)· teacher-hint.html(Step 4 交付用「教师必看」红卡母版:替换 {{TITLE}}/{{URL}}/{{PAGES}}/{{STANDALONEURL}},六条文字不得改写) · step3-hint.html(Step 3 交付用「部署前提示」红卡母版:替换 {{TITLE}}/{{STANDALONE_URL}},与 delivery-playbook §1.1 话术同源)

scripts/(执行/验收):duomiimage.py(duomi 三模型生图入口,技能内自包含、零跨技能依赖:create / status / models / keys / selftest;--model 三选一,-o 指向课件 img/,--dry-run 零成本预览) · publishtolibrary.py(4B 发布)· deliverversions.py(双版本交付,硬规约 #25:生成单机版/在线版命名副本 + 单机版上传资料库独立节点 + 输出两路径/用途/链接;带 --selftest) · syntax-check.js(语法)· scanbraces.py(括号平衡)· pagesync-test-mqtt.js(教学控制回归 40 项:含 S5 两段式入口 / S13 零提示 / S19 观察态 3 秒倒计时) · identity-badge-test.js(身份登记 + CSV 导出端到端回归 30 项,硬规约 #23;头注释含 jsdom 四坑)· deploy-state-test.js(部署态验收 ≈105 项;E2/E3/E4/E7-E9 属 v1.6.0 旧规约,v1.6.5 预期 FAIL,头注释已标注)· jsdom-smoke-test.js(免浏览器冒烟)· verify-library-online.js(线上核验)· sync-e2e-live.js(跟随端到端)· mqtt-latency-probe.js(延迟分层诊断)· quiz-unlock-patch.py + quiz-modify-test.js(答题可改升级+测试)· quiz-answer-check.js(答案位置分布防呆校验,硬规约 #19:同一测验内答案全集中即 FAIL)· reveal-layout-test.js(图文层叠 + 揭示顺序回归,硬规约 #22:无参跑骨架 15 项 / --legacy 自证 / 传课件路径做存量体检)· nav-visibility-check.js(页脚导航可见性回归,硬规约 #24:5 视口 × 封面/内容页,6 类断言——未被遮挡/对比度/可点击高度/封面无溢出/不压字/不贴边;旧课件 N3 恒 FAIL 可作存量体检) · readability-check.js(可读性与布局回归,v1.11.1:F1 滚动区让位/F2 文本零遮挡/F4 资源加载/T1 字号下限(逐页检查,--cover-only 可退回仅封面)为硬 FAIL,F3 纵向预算/T2 字数/T3 行数为 WARN;与 nav-visibility-check 职责独立;存量摸底加 --warn-only) · measure-render-font.js(字号量化测量,硬规约 #26:CSS / SVG(含缩放换算)/ Canvas(fillText 拦截)三段实际屏上字号 + 与定级尺合否判定)· orphan-css-fix.py(孤儿CSS修复)· auditskill_self.py(技能自审)

⚠ 云变体技能(interactive-courseware-cloud)的 audit/migrate/verify 系列脚本规约与母技能相反,勿互相复制。

references/:四张「文件清单表」的分工——Step 3 起步看 §3.2 门控、模板总表看 templates/ 清单、知识库文档看 references/ 清单、可执行工具看 scripts/ 清单,四表互补不重复定义,新增文件登记到对应表即可。本目录含门控表所列 workflow 文件 ×3 + pitfalls.md(五节坑表 + 速查索引 + 交付前总览)+ delivery-playbook.md(交付话术单源) + template-sync.md(模板同步清单) + color-schemes.md / interaction-catalog.md / simulation-patterns.md / animation-rules.md + experience-anchors.md(学段×学科经验域种子表,硬规约 #16 配套)+ templates/。

同分类其他技能

查看全部 ›