QuickClass 课堂转换器

将 Word / PDF / 图片等来源的教案或学习材料，转换为 QuickClass 平台可导入的「课堂」JSON；用户明确要求时，再同步生成一份教学手册 Word（教师用 QuickClass 上课的操作指南）。

> 本 Skill 产出完整课堂 JSON，含对话活动、测验活动、探究活动、项目提交、学情分析提示词等模块。若只需转换试题（纯题目数组），应使用 QuickClass 课堂作业转换器，不属于本 Skill 范围。

输入与输出

• 输入：教案、教学设计、学习材料（Word / PDF / 图片）
• 输出（默认一份）：
  1. QuickClass 课堂导入 JSON，结构见 references/lesson_schema.md
  2. 教学手册 Word（{教师}_{年级}_{学科}_{课题}_课堂_教学手册.docx）——仅用户明确要求时生成
• 必填信息：教师姓名 + 单位/学校名称，由用户提供，写入课堂 JSON（task.teacher / task.school）与手册封面。缺任一项脚本直接报错，不得编造
• 核心难点：从非结构化教案中拆解出「对话活动 / 测验题目 / 探究活动 / 项目提交」四类结构化模块，并填入标准提示词模板
• 硬性要求：教学目标必须按学科核心素养撰写，维度以 references/core_competencies.json 为准，不得凭记忆写维度名。作者已写则转换为标准按维度写法；作者未提供则由转换器自动按维度生成（依据该学科维度 + 本课内容）

工作流程

第零步：确定输入模式

先收集必填信息（两种场景都适用，缺一不可）：

> 这两项是硬性要求：build_lesson.py 检测不到 teacher / school 会直接报错退出（不再放行生成）。若用户只说"你看着办"，应明确告知"课堂会注明教师和单位，需要您提供"，等用户给了再继续。

有两种使用场景，需要先判断：

场景 A — 有教案/材料：用户提供了 Word、PDF、图片等现成材料，进入第一步读取。

场景 B — 从零创建：用户没有现成教案，只说"帮我搭一个XX课堂"。此时需要通过对话收集以下信息：

• 课题、年级、学科、教材版本（人教版/北师大版/苏教版等）
• 本课核心知识点（2-3个关键词即可）
• 希望侧重的能力（理解/应用/迁移/探究，可多选）
• 学生水平（普通/拔尖/薄弱，影响难度分布）
• 对话活动数量偏好（2-3个）

收集完成后，由 LLM 基于教学经验自主生成完整中间格式（含知识库内容、对话设计、题目、探究任务），后续流程与场景 A 相同。

> 教材版本适配：场景 B 收集信息时须问教材版本。不同版本的知识点顺序、术语表述、例题风格差异很大，遗漏会导致内容与老师实际教学脱节。

第一步：读取并理解教案

> 适用于场景 A。场景 B 跳过此步。

根据输入源读取内容：

• Word：用 docx skill 读取
• PDF：用 pdf skill 提取；扫描件用 paddleocr-doc-parsing 做 OCR
• 图片：用 image_understanding 识别

理解教案的：

• 课题、年级、学科，以及作者撰写的教学目标（记录其原始形态：可能是“知识与技能/过程与方法/情感态度价值观”三维目标、自由段落、要点罗列，也可能完全缺失——这是第三步“目标转换”的输入）
• 教学环节设计（导入 / 新授 / 练习 / 总结等）
• 是否含课堂提问/讨论（→ 对话活动）
• 是否含练习题/测验（→ 测验活动，提取题目）
• 是否含探究任务/拓展资源（→ 探究活动）
• 是否含作品提交要求（→ 项目提交）

第二步：规划课堂结构（与用户确认）

从教案中规划出以下模块，建议先与用户确认范围：

题型覆盖要求：判断题、单选题、多选题每种至少1题。

• 若教案已包含全部三种题型，直接提取
• 若教案缺少某题型，必须根据本课知识点自主补出，补出的题须标注 difficulty: "BASIC" 或 INTERMEDIATE，且与教案知识点强相关，不得凭空引入超纲内容

难度分布（用户无要求时的默认）：

• 题量默认 5 题，难度固定为 3 基础 + 1 中等 + 1 较难（即 60% / 20% / 20%），对应 BASIC ×3、INTERMEDIATE ×1、ADVANCED ×1
• 用户明确指定题量或难度时，按用户要求执行；用户要求"题多一些"等泛化表述时，按 基础约50% + 中等约30% + 较难约15% + 拓展约5% 分配
• 任何情况下都避免全堆基础或全堆难题；默认 5 题时也要保证三种题型（判断/单选/多选）各至少1题
  | 交互探究 explorations | 0-2个 | 教案中的探究任务/拓展资源 |
  | 项目提交 projectSubmissions | 1个，课内完成 | 教案中的作品提交要求（如上交作图、作品）。必须在课内完成（约8-10分钟），不设课后任务 |

课时与时长规范（硬性）：

• 小学 40 分钟 / 中学（初中、高中）45 分钟，按 grade 自动判断
• 所有活动必须在课内完成，不设"课后完成"的活动——项目提交改为课内完成并当场展示互评
• 活动总时长不超过 30 分钟（尽量不排满），剩余课时留给师生自由交流——小学约 10 分钟、中学约 15 分钟
• 四类活动（对话/探究/作业/项目）每类至少 1 个，每个活动不低于 6 分钟。因此对话活动小学建议 1-2 个（5 个活动 × 6 分钟 = 30 分钟是上限，要留交流时间就压缩到 4 个活动）
• 规划时按此配比：导入对话约6' + 新授对话约8' + 探究约6-8' + 作业（题数×1.5'，下限6'）+ 项目约6-8'，合计不超过 30 分钟
• 超时处理：脚本自动压缩到 30 分钟内（下限 6 分钟）；若活动数×6 分钟已超 30，则把放不下的活动移入手册末尾「备用活动」章节（先保证四类各至少1个，多余的对话优先移出）——备用活动不在常规流程内，课时充裕或学生兴趣高时可选用
• 教学手册的活动总述会注明：活动共 X 分钟 + 预留 Y 分钟供师生自由交流；有备用时注明"其中 N 个活动已列为备用"

> 题目识别规则：题型分 SINGLE_CHOICE（单选）/ MULTIPLE_CHOICE（多选）/ TRUE_FALSE（判断）。难度分 BASIC（基础）/ INTERMEDIATE（中等）/ ADVANCED（较难）/ EXPANDED（拓展）。判断题的 options 固定传 "{}"。

第三步：生成中间格式 JSON

将规划结果写入 .temp/lesson_plan.json，格式如下（仅列关键字段）：

{
  "meta": {
    "teacher": "教师姓名（必填）",
    "school": "单位/学校名称（必填）",
    "grade": "三年级下学期",
    "subject": "数学",
    "taskTitle": "圆的认识",
    "taskDesc": "课堂目标（必须按学科核心素养的学法描述、按素养维度逐条撰写，见下方说明；多条用分号分隔，将写入 task.description）",
    "source": "脸盆"
  },
  "objectives": "（可忽略——仅为 QuickClass 活动容器字段，不承载课堂目标；留空即可）",
  "requirements": "教学要求（可选）",
  "knowledgeBase": "知识库内容（可选，填入 task.knowledgeBase）",
  "knowledgeBases": [
    {"name": "知识库名称（与本课相关）", "content": "①核心知识点 ②常见错误与迷思概念 ③分层练习策略"}
  ],
  "presetConversations": [
    {
      "title": "圆的基本概念",
      "description": "圆的定义、圆心、半径、直径等基本概念",
      "teachingStage": "新授"
    }
  ],
  "quizActivities": [
    {
      "title": "圆的练习题",
      "description": "圆的基本概念练习",
      "questions": [
        {
          "type": "SINGLE_CHOICE",
          "content": "圆的半径和直径的关系是？",
          "options": {"A": "半径=直径", "B": "半径=直径/2", "C": "半径=直径×2", "D": "半径=直径×π"},
          "answer": "B",
          "difficulty": "BASIC",
          "score": 0,
          "explanation": "直径是半径的2倍，所以半径=直径÷2"
        }
      ]
    }
  ],
  "explorations": [
    {
      "title": "探究活动标题",
      "description": "",
      "htmlContent": "<!DOCTYPE html><html><body>…以实验/动画/交互操作之一的自包含HTML…</body></html>",
      "interactionType": "ANIMATION",
      "enableSubmission": false,
      "enableAiCompanion": false,
      "aiCompanionPrompt": ""
    }
  ],
  "projectSubmissions": [
    {"title": "文本作业", "description": "", "category": "TEXT", "visibleToClass": true, "allowLike": false, "fileSizeLimit": 10}
  ]
}

> 说明：presetConversations / explorations / projectSubmissions 若不提供，脚本使用默认值（对话活动注入标准 systemPrompt 模板；探究活动强制关闭提交与 AI 伴学，enableSubmission / enableAiCompanion 一律为 False）。题目数组不含 id 字段，由脚本自动补 order。score 字段默认为0（课堂模式不计分），若需要计分可在中间格式中设具体分值（如10/20）。
>
> 对话活动教学阶段：每个对话活动须指定 teachingStage，取值为 "导入" / "新授" / "练习总结"。脚本根据阶段在 systemPrompt 中注入差异化引导策略：
>
> - 导入阶段：侧重激发兴趣、联系生活经验、建立学习期待，开场白用场景化问题（如"你有没有注意过车轮为什么是圆的？"）
> - 新授阶段：侧重概念建构、从已知推未知、逐步深入，开场白用承上启下的过渡（如"刚才我们知道了圆的定义，那你觉得圆心在哪里？"）
> - 练习总结阶段：侧重错因分析、知识迁移、自我检验，开场白用反思型问题（如"你觉得做这类题最容易错在哪里？"）
>
> 若未指定 teachingStage，默认按 "新授" 处理。
>
> 知识库规范：knowledgeBases 为对象数组，默认1个，最多2个，每个知识库对象含 name 和 content。字数硬约束：每个知识库 content 不超过2000字（中文计字符，含标点）——这是脚本级硬性上限，超 2000 字时 build_lesson.py 会直接报错退出（退出码 1），不截断、不修补，要求 LLM 端精简后重新生成中间格式。
>
> 字数预算建议（三段式）：1000 + 500 + 500 = 2000
>
> - ① 核心知识点 ≈ 1000 字：定义、公式、定理、方法步骤，按本课 2-4 个关键概念组织，每条 1-2 句话
> - ② 常见错误与迷思概念 ≈ 500 字：3-5 条典型误判，每条 1-2 句（"是什么 + 学生为何会错 + 正确做法"）
> - ③ 分层练习策略 ≈ 500 字：基础→进阶→拓展 各 2-3 条要点
>
> 精简技巧（超 2000 字时）：
>
> - 删除冗余举例（保留 1-2 个最具代表性的）
> - 合并同类迷思（不要把每个学生的不同表述都列出来）
> - 用列表/编号替代整段叙述
> - 砍掉客套话（"本节我们将……"）
> - ③ 策略段只列要点，不展开教学法解释
>
> name 必须与本课相关（如"三年级下册数学知识库"），不能留"工业设计"等无关名称。content 包含三部分：①核心知识点（定义、公式、定理、方法）；②常见错误与迷思概念（如"分子越大分数越大"等典型误判，按教学经验或教案标注）；③分层练习策略建议（基础巩固→理解应用→迁移拓展的递进路径）。不含角色设定（如"你是一位资深学科教师"），角色设定属于提示词模板，不属于知识库。若未提供，content 退回占位提示。
>
> 说明字段字数限制：课堂作业的 description 和 项目提交的 description 均不超过15字（中文计字符）。这些说明是简短标签性质的，不做长文描述——具体内容放题目/任务本身。示例：课堂作业说明"设计数字作品·课堂练习"（7字）、项目提交说明"提交本课作品"（6字）。
>
> 互动探究说明固定为空：互动探究 explorations[].description 固定为空字符串 ""（字数0），不做任何描述——探究内容全部放 htmlContent 中。
>
> 交互探究类型强制（v1.1.8 起）：交互探究 explorations[].htmlContent 必须以"实验 / 动画 / 交互操作"三类之一为主体，不得为纯文字说明（如"雨点儿旅行记"仅用文字+提问属于不合格）。类型通过 interactionType 字段声明，取值 EXPERIMENT（实验）/ ANIMATION（动画）/ INTERACTIVE（交互操作），由 LLM 依据本课学习目标主动选择最贴切的一类（判定参考见下）；未声明时脚本按关键词自动推断并写入。
>
> - 实验 EXPERIMENT：学生动手操作、控制变量、观察现象并得出结论（如配制、测量、电路、组装、种植）。HTML 须提供可操作的控件（按钮/滑块/输入）与实时反馈区。
> - 动画 ANIMATION：用动画演示过程/演变/运动（如雨落、水循环、生长、溶解）。HTML 须含 CSS @keyframes/animation 或 SVG/Canvas 动画，而非静态图配文字。
> - 交互操作 INTERACTIVE：学生拖拽/选择/连线/排序/填空完成操作任务（如分类、配对、拼图）。HTML 须含可交互元素（按钮/输入/拖拽/事件处理）。
>
> 自包含、禁用外部资源（硬性）：htmlContent 不得引用任何外部资源——禁止 <script src=>、<link href=>、<iframe>、外链图片/字体/样式、CSS @import，以及一切 http(s):// / ftp:// / 协议相对 // 引用。所有样式、脚本、图形必须内联；如需图片请用内联 data: URI 或纯 CSS/SVG 绘制。脚本在生成时会硬校验：发现外部资源或纯文字即报错退出（退出码 1）。
>
> 过渡语 transitions（可选，强烈建议）：字符串数组，第 i 条衔接第 i 个活动与第 i+1 个活动（长度 = 活动数 - 1）。由 LLM 结合本课内容撰写，50-100 字，用悬念 / 提问 / 挑战 / 勾连生活的方式吸引学生继续学习（如"可你们想过没有：……？""光说不练假把式，亲自试一试才知道其中的门道"），不要用"下面进入……"式的平铺衔接。生成教学手册时优先使用；不写则退回脚本的悬念式模板。课堂 JSON 组装时会忽略此字段，不影响导入。
>
> 过渡语示例（衔接"导入对话→新授对话"）：
>
> - ✅ "大家聊得热火朝天，每个人的春节都不一样。可你们想过没有：老舍笔下的老北京是怎样过年的，和我们有什么不同？带着这份好奇，我们一起走进课文看看。"
> - ❌ "下面我们进入下一个活动，学习课文内容。"（平铺、无吸引力）
>
> 多选题答案格式：MULTIPLE_CHOICE 的 answer 必须用英文逗号分隔（如 "A,B,D"）。写 "ABD" 会触发脚本报错 多选题答案无效。判断题 answer 用 "T" / "F"。
>
> 课堂目标 taskDesc 必须按学科核心素养撰写（硬性要求，写入 JSON task.description）：
>
> 目标来源与转换（核心步骤——决定最终目标是否“标准按维度”）：
>
> - 作者已写目标 → 必须转换：从源教案提取作者目标后，不要照抄，要按本课学科核心素养维度重新归类与改写为标准按维度格式——保留作者原意，逐维 50-100 字、用学法语言、禁用“掌握/了解”。无论是“三维目标”“五维素养”还是自由段落，都要落到 core_competencies.json 的维度上。
> - 作者未写目标 → 自动生成：依据 core_competencies.json 该学科维度 + 本课知识点与活动，逐维自动生成 50-100 字学法描述（可参考下方写法示范与句式抓手），不得留空。
> - 两类情况最终 taskDesc 都必须是“按维度逐条、顺序与维度一致”的标准写法；脚本会检测并提示“知识与技能/过程与方法/情感态度价值观”等旧三维框架残留。
>
> 1. 先查维度：本课学科对应的核心素养维度以 references/core_competencies.json 为唯一依据（义务教育16学科 + 普通高中11学科，课标原文内涵见 references/义务教育各学科核心素养名称及内涵汇总.md）。不凭记忆写维度名称，尤其是课标修订后变化较大的学科。
> 2. 逐维写目标：本课涉及几个维度就写几条，每条对应一个维度、控制在 50-100 字，多条用分号或换行分隔。条目顺序必须与 core_competencies.json 中该学科的维度顺序一致（教学手册将按 1:1 映射生成素养目标分解，顺序不同则不一致）。
> 3. 用学法语言，不用"掌握/了解"：以核心素养对应的学法（做事方式 / 过程体验）表达，强调学生"做什么、经历什么、形成什么"。
>
> 各学科维度速查（以 core_competencies.json 为准，此表仅备查）：
>
> | 学科 | 核心素养维度 |
> | -------- | --------------------------------------------- |
> | 语文 | 文化自信 / 语言运用 / 思维能力 / 审美创造 |
> | 数学 | 会用数学的眼光观察现实世界 / 会用数学的思维思考现实世界 / 会用数学的语言表达现实世界 |
> | 英语·日语·俄语 | 语言能力 / 文化意识 / 思维品质 / 学习能力 |
> | 道德与法治 | 政治认同 / 道德修养 / 法治观念 / 健全人格 / 责任意识 |
> | 历史 | 唯物史观 / 时空观念 / 史料实证 / 历史解释 / 家国情怀 |
> | 地理 | 人地协调观 / 综合思维 / 区域认知 / 地理实践力 |
> | 物理 | 物理观念 / 科学思维 / 科学探究 / 科学态度与责任 |
> | 化学 | 化学观念 / 科学思维 / 科学探究与实践 / 科学态度与责任 |
> | 生物学 | 生命观念 / 科学思维 / 探究实践 / 态度责任 |
> | 科学 | 科学观念 / 科学思维 / 探究实践 / 态度责任 |
> | 信息科技 | 信息意识 / 计算思维 / 数字化学习与创新 / 信息社会责任 |
> | 艺术 | 审美感知 / 艺术表现 / 创意实践 / 文化理解 |
> | 体育与健康 | 运动能力 / 健康行为 / 体育品德 |
> | 劳动 | 劳动观念 / 劳动能力 / 劳动习惯和品质 / 劳动精神 |
>
> > 注意：语文学科已按 2022 版课标更新为"文化自信 / 语言运用 / 思维能力 / 审美创造"，旧的"语言建构与运用 / 思维发展与提升…"不再使用。
>
> 写法示范（信息科技"制作数字作品"，四条对应四个维度）：
>
> - ❌ "掌握图文排版的操作方法"（浅层"掌握"用语，且未对应素养维度）
> - ✅ "能根据表达需要评估并筛选网络素材，判断其可靠性与时效性；能将作品制作任务分解为规划、制作、评价三个阶段，用流程图描述解决步骤；能选用合适的数字工具独立完成一份结构清晰、主题明确的作品，并在制作过程中体会迭代改进与自我评价；能在引用他人素材时注明来源，遵守信息道德与知识产权规范。"
>
> 句式抓手：能运用…方法 / 能独立…完成… / 在…过程中体会… / 通过…形成…。
>
> 无论作者是否提供目标，最终 taskDesc 都必须是按维度逐条书写的标准写法（作者提供则转换、未提供则自动生成）。若 taskDesc 仅一句话概述或未按维度，教学手册的素养目标分解将退回按维度自动生成模板——质量明显下降。objectives 字段与课堂目标无关（仅活动容器），无需填写。

第四步：运行组装脚本

python {SKILL_DIR}/scripts/build_lesson.py \
  --input .temp/lesson_plan.json \
  --output "教师_年级_学科_课堂标题_课堂.json"

SKILL_DIR 为本 skill 的安装目录（脚本位于 {SKILL_DIR}/scripts/）。常见安装位置：

• ~/.config/TeleAgent/skills/quickclass-lesson-converter
• ~/.workbuddy/skills/quickclass-lesson-converter__skillhub

> 调用脚本前先用 Glob 定位本 skill 的实际目录，不要硬编码路径；两个位置可能同时存在，内容应保持一致。

参数说明：

• --input（必填）：中间格式 JSON 路径
• --output（必填）：输出课堂 JSON 路径
• --teacher / --school（必填）：教师姓名、单位/学校名称。也可写在中间格式 meta 中。两者至少有一处提供，否则脚本报错退出
• --grade / --subject / --task-title / --task-desc / --source（全部可选）：若中间格式 meta 中已提供，脚本自动读取；若命令行也传了，命令行优先

最小化用法：只需 --input 和 --output，其余信息全部写在中间格式 meta 里即可。

脚本自动完成：

• 组装顶层 version / exportedAt / referencedKnowledgeBases
• 规范化题目（题型/难度/选项/答案），自动补 order，不含 id
• 知识库 content 优先从中间格式 knowledgeBases 读取（需根据教案实际内容编写），否则退回默认固定文本
• 注入标准学情分析提示词模板（个体/班级）
• 对话活动注入差异化 systemPrompt（根据 teachingStage） / analysisPrompt 模板
• task 标题拼接为 {taskTitle}_来源于_{source}

第五步：生成教学手册（按需，默认不生成）

默认只交付课堂 JSON。仅当用户明确说"要教学手册 / 生成手册 / 要上课指南"等意思时，才执行本步。不要主动问、不要默认生成——用户没说就跳过本步直接进第六步预览。

python {SKILL_DIR}/scripts/generate_lesson_guide.py \
  --input "{teacher}_{grade}_{subject}_{taskTitle}_{YYYY-MM-DD}_课堂.json" \
  --output "{teacher}_{grade}_{subject}_{taskTitle}_课堂_教学手册.docx" \
  --plan .temp/lesson_plan.json

参数说明：

• --input（必填）：课堂 JSON（含 task 层，由 build_lesson.py 生成）
• --output（必填）：输出 Word 路径
• --plan（强烈建议）：中间格式 lesson_plan.json。传入后手册能读到每个对话活动的 teachingStage 标注；不传则按出现顺序推断（首个=导入，末个=练习总结，中间=新授）
• --teacher / --school：教师姓名与单位。课堂 JSON 已写入 task.teacher / task.school 时会自动读取，无需再传；仅当旧版课堂 JSON 缺字段时才需要手动指定
• --stage 义务教育|普通高中：指定学段以匹配核心素养体系，默认按年级学科自动推断
• --competencies "信息意识,计算思维"：手动指定核心素养维度（逗号分隔），默认用该学科全部维度

手册结构：

产出要点：

• 活动不凭空生成：课堂里没有的活动类型不会出现在手册中；对话活动按 teachingStage 给出差异化的目标、指导与反馈话术
• 活动目标对齐课堂目标：脚本按环节自动引用 task.description 条目——导入→第1条、新授/探究→第2-3条、总结/项目→末条、作业→全部。未按维度拆分时回退模板
• 平台操作直接写步骤：每个活动的 QuickClass 操作指导为祈使句步骤（1. 创建… 2. 设置… 3. 学生… 4. 教师端查看…），去掉"xxx是xxx的活动"这类功能解释
• 教师姓名、教学阶段、字数等细节在生成后核对一遍；手册内容允许教师二次编辑

> 依赖：脚本需要 python-docx，缺失时执行 pip install python-docx。

第六步：预览确认（交付前必做）

运行脚本后，先不急于导出，向用户展示一份可读的 Markdown 摘要，确认后再写入最终文件。摘要内容包括：

## 课堂预览：{taskTitle}

- 年级：{grade}  学科：{subject}  教材版本：{meta.version}
- 对话活动（{n_conv}个）：{各对话标题 + 教学阶段}
- 课堂作业（{n_quiz}题）：单选{n}题 / 多选{n}题 / 判断{n}题
- 难度分布：基础{n} / 中等{n} / 较难{n} / 拓展{n}
- 探究活动（{n_exp}个）：{各探究标题}
- 项目提交（{n_proj}个）：{项目标题 + 类型}

用户确认项：

• 模块数量和题型分布是否符合预期？
• 对话活动的教学阶段标注是否正确？
• 知识库内容是否覆盖了本课核心知识点和常见错例？

若用户提出修改，回到第三步调整中间格式后重新运行。

第七步：含图题目处理

若教案中的测验题含图示：

• QuickClass 题目不支持图片嵌入，options/content 用文字描述替代
• 生成配套「图示说明 Word」：运行 scripts/generate_image_doc.py（已随本 skill 携带）
• 扫描件 PDF 需用视觉模型精准裁剪题目区域，再 OCR 识别文字与图示，避免位置就近匹配导致的裁剪偏差

第八步：内容质量验收（交付前最后一步）

生成后，必须按 references/quality_checklist.md 做内容层面验收，判断产出的题目/对话/探究/项目「好不好」，而不仅是结构对不对。

验收要点（硬性门槛，不过 = 不合格，先修再交付）：

• 忠实度：知识点/例题/任务不丢失、不篡改、不张冠李戴
• 学科正确性：题干/答案/解析完全正确，答案与选项自洽
• 命题质量：题干清晰、干扰项有效、选项同质、难易分层合理、解析有用
• 题型覆盖：课堂作业中判断题、单选题、多选题每种至少1题
• 难度分布：基础约50% + 中等约30% + 较难约15% + 拓展约5%
• 活动质量：对话不退化"陪聊"、探究任务可操作、项目配置匹配
• 完整闭环：教案中每个知识点在"对话引发 → 题目检验 → 分析反馈"中形成闭环

评分方式：硬性门槛 + 权重打分（忠实度20%/学科25%/命题20%/活动20%/完整10%），总分 ≥85 才交付。

> 验收方式：由 LLM 对每道题自动独立推演答案并核对，同时建议教师对至少3道代表性题目人工抽检（打印出来自己做一遍）。双轨验证，避免 LLM 自我审查盲区。

第九步：输出文件命名

课堂 JSON：{teacher}_{grade}_{subject}_{taskTitle}_{YYYY-MM-DD}_课堂.json

示例：脸盆_三年级下学期_数学_圆的认识_2026-08-10_课堂.json

教学手册：{teacher}_{grade}_{subject}_{taskTitle}_课堂_教学手册.docx

示例：脸盆_三年级下学期_数学_圆的认识_课堂_教学手册.docx

> 课堂 JSON 文件名含日期，避免同一课题多次生成时互相覆盖；教学手册因教师需长期使用，不附日期，重复生成时直接覆盖旧版。
> 教师姓名来自文件名首段，教学手册脚本据此推断封面教师项，因此课堂 JSON 必须严格按上述格式命名。

标准提示词模板（必须使用官方模板变量）

> 强制规范：所有学情分析 / 对话设计提示词中的占位符，必须且只能使用官方文档《模板变量说明文档》中定义的六类模板变量，不允许自行编造。
> 文档路径：/Users/guan/data/quickchat/模板变量说明文档.md

六类模板与 JSON 字段对应关系：

完整变量列表与层级速查见 references/prompt_templates.md，由 build_lesson.py 自动注入，无需手动编写。

变量命名规范：

• 统一驼峰格式（{taskTitle} / {explorationTitle}），旧点号格式兼容但不推荐
• {taskDescription} 表示课堂目标（meta.taskDesc）；{taskObjectives} 为兼容别名
• 引用的变量若无数据，系统自动替换为空字符串，不报错

完整结构参考

详见 references/lesson_schema.md，包含字段结构定义、模块示例、占位符约定；references/quality_checklist.md 为内容质量验收标准；references/prompt_templates.md 为提示词模板变量规范。

学科核心素养参考（写课堂目标 taskDesc 与生成教学手册时使用）：

• references/core_competencies.json：机器可读，含义务教育16学科 + 普通高中11学科的核心素养维度与内涵定义。程序与 LLM 一律以此文件为准。
• references/义务教育各学科核心素养名称及内涵汇总.md：义务教育16学科素养名称及内涵的课标原文，供教师查阅与人工核对。

常见问题

Q: 本 Skill 和课堂作业转换器有什么区别？
A: 课堂作业转换器产出「课堂作业 JSON」（纯题目数组，含 id）；本 Skill 产出「课堂 JSON」（含 task 包裹层、对话/测验/探究/项目四大模块、学情分析提示词）。课堂作业是课堂的子集。

Q: 题目里为什么没有 id？
A: QuickClass 课堂 JSON 的题目在 quizActivities[].questions 中不含 id，只有 order 序号。由平台导入时再分配。

Q: 如果教案只有题目没有对话/探究活动怎么办？
A: 只填 quizActivities 即可。对话/探究/项目模块留空或省略，脚本会生成空数组，不影响导入。

Q: 判断题的 options 为什么是 "{}"？
A: 判断题固定传空 JSON 对象字符串 "{}"，这是 QuickClass 平台的规范。

Q: 学情分析提示词能改吗？
A: 模板已固化在脚本中（个体报告用纯 SVG、班级报告用 ECharts；作业分析用 QUIZ_ANALYSIS、探究分析用 EXPLORATION_ANALYSIS），占位符严格遵循《模板变量说明文档》的六类模板。如需自定义，编辑 scripts/build_lesson.py 中的模板常量，但不得引入文档未定义的变量名。

Q: 多选题答案怎么填？
A: 必须用英文逗号分隔，如 "answer": "A,B,D"。写成 "ABD" 会报错 多选题答案无效，脚本不兼容连写格式。

Q: 课堂作业默认几道题、什么难度？
A: 用户未指定时固定 5 题：3 基础 + 1 中等 + 1 较难（60% / 20% / 20%）。用户指定题量或难度时按其要求；只说"题多一些"则按 基础约50% + 中等约30% + 较难约15% + 拓展约5% 分配。默认 5 题时三种题型（判断/单选/多选）也各至少1题。

Q: 课堂时长怎么定？项目提交能放课后吗？
A: 小学 40 分钟、中学（初中/高中）45 分钟，按年级自动判断。所有活动（含项目提交）必须在课内完成，不设课后任务——项目提交为课内 8-10 分钟完成并当场展示互评。规划时总时长不得超过课时，超时压缩环节或题目，不得把活动挪到课后。

Q: 教学手册是必须生成的吗？
A: 不是。默认只产出课堂 JSON。仅当用户明确要求"生成教学手册/上课指南"时才生成。不要在用户没提的情况下主动生成或反复追问。

Q: 用户没给教师姓名和单位怎么办？
A: 必须向用户索要，不得编造或用"XX老师""某学校"占位。build_lesson.py 已做硬校验：meta.teacher / meta.school（或命令行参数）缺失会报错退出。向用户要信息时说明用途："课堂与手册会注明任课教师与单位，请提供"。若用户坚持不提供，明确告知无法生成。

Q: 教学手册里的活动是照搬模板吗？
A: 不是。手册依据课堂 JSON 中实际配置的四类活动逐条生成：有几个对话活动就写几节，没有探究活动就不会凭空出现探究环节；对话活动还会按 teachingStage（导入/新授/练习总结）给出不同的目标、指导话术与反馈应对。传入 --plan 时教学阶段来自中间格式标注，不传则按出现顺序推断。

Q: 教学手册里的教学目标是逐课定制的吗？
A: 第一章直接采用课堂 JSON 的 task.description（即 meta.taskDesc，按核心素养维度撰写的那一份），一节式逐条输出「N. 素养名称，具体目标描述」（1:1 映射）。所以第三步把 taskDesc 写好，手册质量才有保障；只有一句概述时手册会退回按维度自动生成，质量明显下降。

Q: 源教案里作者写的是“三维目标”或压根没写教学目标怎么办？
A: 都要转成标准按维度写法。作者已写（无论“三维目标”“五维素养”还是自由段落）就在第三步转换为 core_competencies.json 对应维度、逐维 50-100 字、学法语言；作者没写则由转换器自动按维度生成（依据该学科维度 + 本课知识点与活动）。最终 taskDesc 始终是按维度逐条的标准格式，不会保留旧三维框架，也不会留空。

Q: 手册封面的教师姓名和单位是怎么来的？
A: 优先读取课堂 JSON 的 task.teacher / task.school（由 build_lesson.py 从必填信息写入）。旧版课堂 JSON 若没有 task.teacher，则退回从输入文件名首段推断（如 张老师_五年级上学期… → 张老师），再用 --teacher 手动指定兜底。

Q: 生成手册时报错 ModuleNotFoundError: No module named 'docx' 怎么办？
A: 手册脚本依赖 python-docx，执行 pip install python-docx 后重试。课堂 JSON 的生成（build_lesson.py）不依赖第三方库，不受影响。

导入后验证（建议）

JSON 格式正确不等于平台能正常使用。导入 QuickClass 后建议逐项检查：

• 对话活动能否正常开始？开场白是否出现？
• 题目是否全部显示？选项/图示是否对应？
• 学情分析报告能否生成？内容是否合理？
• 探究活动交互资源是否正常加载？

自检与回归测试

改动本 skill 的任何脚本或参考文件后，先跑内置自检，再交付：

python {SKILL_DIR}/scripts/selftest.py

自检用内置的样例课堂跑完整链路，覆盖 6 组共 30 余项断言：

全部通过输出「结论：全部通过，可以交付」，有失败项退出码为 1 并逐条列出。

脚本查不出的部分，仍需人工过一遍：

• 打开 docx 通读：教学阶段标得对不对、教师姓名对不对、活动顺序是否符合你的上课习惯
• 把题目自己做一遍，重点核答案与解析（自检只验证结构，不验证学科内容）
• 按上文「导入后验证」在 QuickClass 平台实操一次

> 自检只验证链路通不通，不验证内容好不好。内容质量按第八步的 quality_checklist.md 单独打分。