Classroom Live

---
name: classroom-live
description: "高校课堂互动与平时分辅助：随堂投票题与投屏 PPT、布鲁姆递进式提问链、课堂互动记录表、可逐行举证的平时分计算、学情画像与干预建议。当教师说「生成随堂投票题」「这节课的提问链」「把互动记录算平时分」「课堂互动记录怎么记」「给我做份平时分依据表」「看看哪些学生一节课没说过话」时使用。涉及学生平时分与参与画像，产出是初算草稿与举证材料，最终分值由任课教师核定。Triggers: 生成随堂投票题、这节课的提问链、把互动记录算平时分、课堂互动记录怎么记、平时分依据表怎么做、哪些学生上课从来不发言、随堂小测记录怎么算进平时分。"
---

# 课堂互动与平时分

> **Goal**：把「课前想投什么问题 → 课上怎么问、怎么记 → 期末怎么算、怎么举证」这条线一次走通。
> 产出两类东西：**课前可投屏的互动材料**与**期末可逐行举证的《平时分依据表》**。
> AI 只出草稿、题库与计算表；**平时分最终分值必须由任课教师核定**。

## 何时使用

- 「生成随堂投票题 / 这次课要投几道题 / 做个投票 PPT」
- 「这节课的提问链 / 怎么一层层问下去 / 学生答不上来怎么办」
- 「把互动记录算平时分 / 平时分依据表怎么做 / 平时分怎么算才说得清」
- 「课堂互动记录怎么记 / 给我一张记录表 / 记了记不住怎么办」
- 「哪些学生上课从来不发言 / 这个班参与度怎么样 / 期中要提醒谁」

**不适用**：期末试卷命题与考后试卷分析（走 `exam-pipeline`）；只出题不带课堂互动（走 `quiz-generator`）；
课时教学设计（走 `lesson-plan`）。若教师只要「出一套练习题」，交给 `quiz-generator`。

**与其它子技能的衔接**：`lesson-plan`（教案里的活动环节）→ `lecture-slides`（课件）→ **`classroom-live`（投票题 + 提问链 + 记录）**
→ 期末 `exam-pipeline`（《平时分依据表》随试卷材料归档）。

## 底座（禁止重写）

| 路径 | 用途 |
|---|---|
| `skills/ibook-skills/question-writing/` | **主底座**：选择题生成流程、布鲁姆层次分布、答案均衡、质量校验 |
| `skills/ibook-skills/question-writing/references/distractor-writing-guide.md` | **干扰项四品质与四种构造模式**，投票题选项照此写 |
| `skills/education-skills/edu-learning-analytics/references/student-profiling.md` | **主底座**：学习轮廓三维度、伦理原则（用于支持而非标签） |
| `skills/education-skills/edu-learning-analytics/references/learning-analytics.md` | 参与度指标、三级预警、数据伦理（最小必要/匿名化/辅助而非取代判断） |
| `skills/education-skills/edu-learning-analytics/references/peer-assessment.md` | 小组讨论的贡献度与互评口径 |
| `skills/education-skills/edu-learning-analytics/references/competency-based-assessment.md` | 等级（A/B/C/D）口径参考 |
| `skills/k12-teacher-skills/k12-check-for-understanding/` | **理解性检查结构**：每个反应「说明什么 → 下一步怎么教」的写法，本 skill 的投票题备注照此组织 |
| `skills/learning-education/thinking-toolkit/methods/01-socratic-inquiry.md` | 追问技术：一次只问一问、区分事实/解释/判断、只问能改变结论的问题 |
| `skills/office-layer/` | **文件产出唯一通道**（pptx / xlsx / docx），见 `skills/office-layer/SKILL.md` |
| `skills/classroom-live/scripts/participation_score.py` | **自建**（上游无可复用件）：可追溯计分 + 记录表模板生成 |

> 许可证提示：`ibook-skills` 上游仓库无 LICENSE 文件（见 `THIRD_PARTY_NOTICES.md`「许可证合规」），
> 本机自用可以，**本包若要对外分发需先取得作者授权或移除该目录**。

## 前置信息收集（intake，一次性问完）

开头的 intake 环节**合并成一次提问**，不要边做边问。信息不全时用下表「安全默认值」继续，
并在交付物里标注哪几处用了默认值。

| # | 要问的 | 为什么必须问 | 安全默认值 |
|---|---|---|---|
| 1 | 课程名、班级、学年学期 | 依据表表头与归档文件名 | `【待补：课程名】` 占位 |
| 2 | 班级人数 | 决定投票方式（举手/答题器/扫码）与记录粒度 | 不填，只影响建议不影响计算 |
| 3 | 本次课知识点（3–6 个，越具体越好） | 投票题与提问链的唯一素材来源 | **必问**，没有知识点就不出题 |
| 4 | 平时分权重规则：考勤 X%、课堂互动 Y%、平时作业 Z%、随堂小测 W%，以及「缺勤扣分」「加分上限」等细则 | 计算的全部依据；且必须是**本学期已向学生公布**的那一版 | 20 / 30 / 30 / 20；缺勤扣分不猜，写进规则文件后由教师确认 |
| 5 | 考勤方式（点名 / 扫码 / 平台签到 / 纸质签名） | 决定记录表的列与录入成本 | 按逐次课点名记录（最通用） |
| 6 | 有没有现成记录表 / 上学期怎么记的 | 有则直接读，无则生成模板；能沿用旧表就不让教师重做 | 无 → 生成《课堂互动记录表》模板 |

**问规则时的关键一句**：「这套权重和扣分细则，是不是您这学期开学时跟学生讲过的那一版？」
若不是同一版，先改规则文件再算 —— 否则学生质询时教师站不住，这是本 skill 最容易出事的地方。

## 工作流

每个阶段写清 **输入 → 动作 → 输出 → 退出条件**。阶段一、二只在课前用；阶段三每节课后用；
阶段四、五在期中/期末用。

---

### 阶段零 · 定基点

- **输入**：intake 六项。
- **动作**：
  1. 确认本次要交付哪些产物（很多教师只要其中一项，不要全塞）；
  2. 若走平时分计算，先落一份 `平时分规则.json`（阶段四给模板），请教师核对权重与扣分细则；
  3. 声明数据纪律：全部在本机处理，学生姓名/学号不出本机。
- **输出**：一份确认清单（要做什么 + 规则文件 + 有无现成记录表）。
- **退出条件**：规则文件里的权重之和 = 100，且教师口头确认「这版就是公布过的」。

---

### 阶段一 · 课前：随堂投票题（3–5 题，可投屏）

- **输入**：本次课 3–6 个知识点；可选：上一节课的知识点（用于课前摸底）。
- **动作**：

  **1. 先给每题定「用途档位」，不同档位的题不是一回事：**

  | 档位 | 放在课的什么时候 | 出几题 | 设计要点 | 结果拿来干什么 |
  |---|---|---|---|---|
  | 课前摸底 | 上课前 3 分钟 | 1–2 题 | 只考前备概念，不考本节新内容 | 答错不是学生的问题，是「还没讲」；据此决定要不要花 5 分钟补讲 |
  | 课中检验 | 讲完一个易混点后立刻 | 2–3 题 | 针对刚讲完的那一个点，题目必须能区分「记结论」和「懂前提」 | 错误率 > 40% → 当场再讲一遍，不要往后赶 |
  | 课后巩固 | 课后发（可入库） | 1–2 题 | 略高于课中难度，可跨知识点 | 下次课开头 2 分钟复盘，也用于期末命题参考 |

  **2. 按 `quiz-generator` 的口径出题**：单次课以**理解层、应用层为主**，最多 1 题分析层；
  一次课不追求六层齐活。正确答案在 A/B/C/D 间轮换，不要连出三个同字母。

  **3. 干扰项必须照 `distractor-writing-guide.md` 的四品质写**——似是而非、有教学价值、能区分水平、不出老千：

  | 构造模式 | 怎么造 | 例（图的遍历） |
  |---|---|---|
  | 部分真 | 在别的语境下成立，但不是本题答案 | 「与 A 相邻的任意一个顶点」 |
  | 反向 | 正确关系的反面 | 「BFS 一定先访问最远的顶点」 |
  | 近邻术语 | 术语只差一个限定词 | 「O(n+e)」（邻接表的结论，搬到邻接矩阵上） |
  | 常见错误 | 学生真会犯的错 | 「DFS 与 BFS 的访问序列一定不同」 |

  禁止：全选/无选项、含「总是/从不/完全」的极端表述、四个选项长度明显不等、
  两个选项都说得通、答案一眼可见。**每一项都要是「没学过的人真会选」的那个。**

  **4. 答案键只放备注页**：投屏页只有题干 + 4 个选项，正确答案、误选诊断、教学处置写在演讲者备注里
  （备注不投影）。每题备注固定四行：

  ```
  正确答案：B（说明为什么）
  用途：课中检验——刚讲完存储结构对复杂度的影响
  误选诊断：选 C 是把邻接表结论搬到邻接矩阵上，属「结论记熟、前提忽略」
  教学处置：请选 C 的学生说一遍邻接表为什么是 O(n+e)，用对比表当场收口
  ```

  第 3、4 行照 `skills/k12-teacher-skills/k12-check-for-understanding/` 的「看到什么反应 → 下一步怎么教」结构写，
  **不写出这两行就等于题目没有教学价值**。

  **5. 投屏 PPT 用 office-layer 生成**：

  ```bash
  PY="skills/office-layer/.venv/bin/python"

  # 1) 写投票题规格（JSON，见下方片段）
  # 2) 生成 16:9 投屏文件
  $PY skills/office-layer/scripts/pptx_kit.py build \
      --spec 投票题.spec.json --out 随堂投票_图的遍历.pptx

  # 3) 读回结构与信息密度，单页正文 >220 字符会被报进 overdense —— 要拆页
  $PY skills/office-layer/scripts/pptx_kit.py inspect --in 随堂投票_图的遍历.pptx
  ```

  规格片段（`spec.json`；`meta` 出封面页，`slides` 一页一题）：

  ```json
  {"meta": {"title": "《数据结构》第13次课 · 随堂投票",
            "subtitle": "图的遍历：DFS 与 BFS",
            "presenter": "【待补：任课教师】"},
   "slides": [
     {"title": "投票 Q1 ｜ 课前摸底",
      "bullets": [{"text": "对下图从 A 出发做深度优先遍历，第一个被访问的顶点一定是：", "level": 0},
                  {"text": "A. 与 A 相邻且编号最小的顶点", "level": 0},
                  {"text": "B. 与 A 相邻的任意一个顶点", "level": 0},
                  {"text": "C. 距离 A 最近的顶点", "level": 0},
                  {"text": "D. 入度最大的顶点", "level": 0}],
      "notes": "正确答案：A（邻接表按编号有序时，DFS 的起始选择唯一）。\n用途：课前摸底。\n误选诊断：选 B 知道要走邻接点但不知有序性；选 C 把 DFS 与 BFS 混淆。\n教学处置：误选 C 超 1/3 → 先花 30 秒对比两者「下一跳怎么选」再进正课。"}
   ]}
  ```

  **6. 投票回收**：记进记录表的《投票结果》表（题号 / 选项 / 人数 / 正确率 / 主要误选项）。
  投票是**班级层面的诊断数据**，默认不折算成个人平时分；只有用实名答题器且事先告知学生，
  才可以按教师设定的口径计入（见阶段四的注意事项）。

- **输出**：`随堂投票_<知识点>.pptx`（3–5 页题目 + 封面）、`投票题.spec.json`。
- **退出条件**：每题都能回答「选错说明什么」；每条备注四行齐；`inspect` 无 `overdense`；
  投屏页上找不到答案。

---

### 阶段二 · 课前：递进式提问链（布鲁姆六层）

- **输入**：本次课 1 个核心知识点（选最容易分层展开的那个）。
- **动作**：

  **1. 按六层出一条链，每层一个问题**，并预先写下预期回答——不写预期回答就判断不了学生答得对不对：

  | 层次 | 问题（示例：图的遍历） | 预期学生回答 | 等答时间 | 听到什么就往下走 / 什么要补 |
  |---|---|---|---|---|
  | 识记 | 什么叫深度优先遍历？ | 「从某点出发沿一条路走到底，走不通再回退」 | 3–5 秒 | 说不出「回退」→ 回到递归/栈补 2 分钟 |
  | 理解 | 为什么 DFS 一定要用栈（或递归）？ | 「回退时要记得上一个点在哪」 | 3–5 秒 | 只会背「先进后出」→ 让他用纸画回退顺序 |
  | 应用 | 给定邻接表，写出从 V1 出发的 DFS 序列 | 给出一个正确序列，并说明邻接点顺序 | 5–15 秒（可先同桌说一句） | 序列对但说不清依据 → 追问「你为什么先选这个」 |
  | 分析 | 同一张图，为什么 DFS 序列不唯一而 BFS 可能唯一？ | 「取决于邻接点的存储顺序与选择规则」 | 5–15 秒 | 答不出来 → 现场改邻接表顺序重跑一次 |
  | 评价 | 找迷宫出口，你选 DFS 还是 BFS？凭什么？ | 「要最短路径选 BFS，只求到得了、省内存选 DFS」 | 15–30 秒（允许先写一句） | 只答「都可以」→ 追问「如果内存只有 1MB 呢」 |
  | 创造 | 设计一个用 DFS 解决的实际问题，并说明为什么 BFS 不合适 | 「括号匹配 / 拓扑排序 / 连通块统计」+ 理由 | 15–30 秒 + 课后延伸 | 能举例但说不清 → 留作课后小任务，下次课复盘 |

  **2. 等答时间（wait time）—— 这是提问链成败的关键，比问题本身更重要：**

  - 识记 / 理解层：提问后**停 3–5 秒**再点名（心里默数三下）。
  - 应用 / 分析层：5–15 秒；先「想 30 秒，跟同桌说一句」（Think-Pair-Share），再抽人答。
  - 评价 / 创造层：15–30 秒，允许先用一句话写在纸上再答。
  - **顺序必须是「先提问 → 再停顿 → 后点名」**。反过来（先点名再提问）学生只听见自己的名字，
    问题根本没进脑子，全班也就不用想了。
  - 停顿期间**不重复问题、不自己接话、不用眼神催**。这三件事会瞬间把等答时间清零。

  **3. 追问技巧**（照 `thinking-toolkit` 的苏格拉底式提问：一次只问一问，只问能改变结论的问题）：

  | 类型 | 话术 | 什么时候用 |
  |---|---|---|
  | 追问证据 | 「你是从哪里看出来的？」 | 学生答对但说不清，逼出依据 |
  | 追问反例 | 「如果这张图不连通，你刚才的说法还成立吗？」 | 学生把结论说绝对了 |
  | 追问边界 | 「什么条件下这个结论会失效？」 | 分析 / 评价层收口 |
  | 追问迁移 | 「换成 BFS 呢？换成有向图呢？」 | 检验是否真懂而非记住 |
  | 追问元认知 | 「你刚才是怎么想到这条路的？」 | 把好思路变成全班可复用的方法 |

  **4. 答错怎么办**：不当场否掉。说「这个思路卡在哪我们看一下，谁能接一句」——
  把错误变成课堂资源。点评**只针对思路，不评价学生本人**（不说「这么简单都不会」）。
  一分钟内同一名学生不超过 2 次，避免少数人包场（见阶段五「积极学生」的干预）。

  **5. 提问链是教师手上的一张纸，出 DOCX**：

  ```bash
  $PY skills/office-layer/scripts/docx_kit.py md \
      --in 提问链.md --out 提问链_图的遍历.docx --title "《数据结构》图的遍历 · 递进式提问链"
  $PY skills/office-layer/scripts/docx_kit.py inspect --in 提问链_图的遍历.docx
  ```

  `提问链.md` 用一张表（层次 | 问题 | 预期回答 | 等答时间 | 追问），照上面示例的列写即可。

- **输出**：`提问链_<知识点>.docx`。
- **退出条件**：六层齐全、每层有预期回答与等答时间；评价层与创造层的问题在本次课的时间预算内
  （放不下就明说「创造层留作课后任务」，不要硬塞进 45 分钟）。

---

### 阶段三 · 课堂：互动记录（要能坚持一学期）

- **输入**：`课堂互动记录表.xlsx`（无则先生成）、当次课的课堂事实。
- **动作**：

  **1. 支持的互动形式（五类）与记录落点：**

  | 互动形式 | 记在哪张表 | 记什么 | 是否直接进平时分 |
  |---|---|---|---|
  | 点名回答 | 课堂互动 | 互动类型=点名回答，表现等级 A–D | 是 |
  | 小组讨论 | 课堂互动 | 互动类型=小组讨论，等级按该生实际发言记 | 是（口径见阶段四说明） |
  | 投票结果 | 投票结果 | 题号 / 选项 / 人数 / 正确率 / 主要误选项 | **默认否**，只作班级诊断 |
  | 随堂小测 | 随堂小测 | 得分 / 满分 | 是 |
  | 课堂提问（学生主动提问） | 课堂互动 | 互动类型=主动提问 | 是（也是学情画像里「主动性」的来源） |

  **2. 字段设计**（脚本与依据表按这些列名解析，列名可改，但要同步改规则 JSON 的 `sheets` 段）：

  | 表 | 字段 |
  |---|---|
  | 考勤 | 日期 ｜ 周次 ｜ 学号 ｜ 姓名 ｜ 状态 ｜ 备注 |
  | 课堂互动 | 日期 ｜ 周次 ｜ 学号 ｜ 姓名 ｜ 互动类型 ｜ 表现等级 ｜ 备注 |
  | 投票结果 | 日期 ｜ 周次 ｜ 题号 ｜ 选项 ｜ 人数 ｜ 正确率 ｜ 主要误选项 |
  | 平时作业 | 布置日期 ｜ 周次 ｜ 学号 ｜ 姓名 ｜ 得分 ｜ 满分 ｜ 备注 |
  | 随堂小测 | 日期 ｜ 周次 ｜ 学号 ｜ 姓名 ｜ 得分 ｜ 满分 ｜ 备注 |
  | 加分项 | 日期 ｜ 学号 ｜ 姓名 ｜ 加分项 ｜ 加分 ｜ 备注 |

  **3. 表现等级口径（A–D）必须开学就告诉学生**，否则事后无法举证：

  | 等级 | 口径 |
  |---|---|
  | A 优秀 | 主动回答且论证完整；提出被采纳的不同解法；带动小组推进 |
  | B 良好 | 被点名能答对；小组讨论中有实质发言 |
  | C 一般 | 被点名能答但需提示；参与讨论但贡献有限 |
  | D 未参与 | 点名未答或答非所问；小组中未参与 |

  同一节课同一学生**只记最高的一次**，避免重复记分。**这张口径表是教师核定的，AI 只给初稿**。

  **4. 录入规范（决定这套表能不能用到期末）：**

  - **下课后 5 分钟内录入**，趁印象还在。不要期末凭回忆集中补录。
  - 课上只做纸质速记符号：点名答对 `√`、精彩发言 `☆`、需要补讲 `△`、未参与 `○`；课间誊进表。
  - **一次课只记 8–15 条**，不要试图记全班每人每节课 —— 第三个周就会放弃。
    优先记：主动提问的、答得出彩的、明显卡住的、连续几次没参与的。
  - **只记能回溯的事实**（说了什么、做了什么），不写「态度差」「不认真」这类判语。
  - **缺失就留空**，绝不凭回忆补录；确实要补录就写「补录 2026-10-20」留痕。
   - 若缺交作业，**记 0 分而不是留空**（留空脚本会当成漏录进「待核清单」，这是故意的）。

  **5. 生成记录表模板与默认规则：**

  ```bash
  PY="skills/office-layer/.venv/bin/python"

  # 生成 6 张记录表 + 填写说明 的规格，同时出默认规则 JSON
  $PY skills/classroom-live/scripts/participation_score.py template \
      --out 记录表模板.spec.json --rules-out 平时分规则.json --course "数据结构"

  $PY skills/office-layer/scripts/xlsx_kit.py build \
      --spec 记录表模板.spec.json --out 课堂互动记录表.xlsx
  ```

  生成的工作表：`考勤 / 课堂互动 / 投票结果 / 平时作业 / 随堂小测 / 加分项 / 填写说明`。
  **表里第一行是示例行，录入前删掉**；工作表名若要改，同步改 `平时分规则.json` 的 `sheets` 段。

- **输出**：`课堂互动记录表.xlsx`、`平时分规则.json`（待教师定版）。
- **退出条件**：教师能在 5 分钟内完成一次课后录入；工作表名与规则 `sheets` 一致；等级口径已告知学生。

---

### 阶段四 · 课后/期末：平时分计算（本 skill 的核心可执行部分）

- **输入**：① 教师定版的 `平时分规则.json`；② 记录表（`.xlsx` / `.csv`）；
  ③ 学生名单（可选，但**强烈建议给** —— 没有名单，整学期零互动的学生会从表里消失，而他们恰恰最需要被看到）。

- **动作**：

  **第 1 步 · 权重规则的可配置结构。**规则文件全文（**已实测跑通**的版本）：

  ```json
  {"course": "数据结构", "class_name": "计算机2301", "term": "2025-2026学年第一学期",
   "teacher": "【待教师确认：任课教师】",
   "weights": {"attendance": 20, "interaction": 30, "homework": 30, "quiz": 20},
   "attendance": {"base": 100, "floor": 0,
                  "status": {"出勤": 0, "迟到": -10, "早退": -10, "事假": -5, "病假": 0, "公假": 0, "旷课": -25},
                  "absent_alert": 3},
   "interaction": {"level_points": {"A": 3, "B": 2, "C": 1, "D": 0}, "full_credit_points": 20},
   "homework": {"drop_lowest": 0},
   "quiz": {"drop_lowest": 1},
   "bonus": {"enabled": true, "cap": 5},
   "cap_total": 100, "round": 2,
   "sheets": {"attendance": "考勤", "interaction": "课堂互动", "homework": "平时作业",
              "quiz": "随堂小测", "bonus": "加分项", "votes": "投票结果"}}
  ```

  | 规则键 | 含义 | 注意 |
  |---|---|---|
  | `weights` | 考勤 / 互动 / 作业 / 小测 四项权重 | **和必须 = 100**；不等于 100 时脚本拒绝计算并报错，不做自动归一 —— 权重是向学生公布的承诺，不能悄悄改 |
  | `attendance.base` / `floor` / `status` / `absent_alert` | 考勤基准分 / 下限 / 各状态扣分 / 旷课预警阈值 | 扣分值必须 ≤ 0；**加分请走 `bonus`**，不要写成「+5 分的事假」 |
  | `interaction.level_points` / `full_credit_points` | 等级折算点数 / 拿满即满分的点数 | 超出部分自动封顶（封顶会落一行调整明细，不是黑箱） |
  | `homework.drop_lowest` / `quiz.drop_lowest` | 剔除最低几次 | **注意**：若把缺交记 0 分，`drop_lowest` 可能正好把缺交剔掉。建议只在 `quiz` 用，且教师确认口径 |
  | `bonus.enabled` / `cap` | 加分开关 / 加分上限 | 加分项必须有原始依据（教师记录、课堂记录），否则不加 |
  | `cap_total` / `round` | 总分上限 / 舍入位数 | 超出上限会落一行「总分封顶」明细 |

  **第 2 步 · 计分口径（写成公式，便于向学生解释）：**

  ```
  考勤得分率 = max(floor, base + Σ各次扣分) / 100        # 无任何考勤记录记 0，不送基准分
  互动得分率 = min(Σ等级点数, full_credit_points) / full_credit_points
  作业/小测得分率 = 各次(得分/满分) 剔除最低 N 次后取平均
  加权小计 = 考勤得分率×20 + 互动得分率×30 + 作业得分率×30 + 小测得分率×20
  平时分(初算) = min(cap_total, 加权小计 + 加分)
  ```

  **逐行折算规则**（这一条保证「明细逐行相加 = 初算分」）：
  考勤每条 = 扣分 × 权重/100；互动每条 = 点数 × 权重/full_credit_points；
  作业/小测每条 = (得分/满分) × 权重/有效条数；封顶、下限、剔除最低，各自在明细里落一行。

  **第 3 步 · 跑计算，出依据表规格：**

  ```bash
  PY="skills/office-layer/.venv/bin/python"

  # 记录表 + 规则 + 名单 → 依据表规格 + 追溯明细 CSV + 待核清单
  # 脚本只读输入，不改记录表；输出全部落在 --outdir
  $PY skills/classroom-live/scripts/participation_score.py score \
      --records 课堂互动记录.xlsx --rules 平时分规则.json --roster 名单.csv --outdir ./平时分

  # 规格 → XLSX（build 会顺带回读各表行列数，这就是自检）
  $PY skills/office-layer/scripts/xlsx_kit.py build \
      --spec 平时分/平时分依据表.spec.json --out 平时分依据表.xlsx

  # 需要单独再看一次结构时
  $PY skills/office-layer/scripts/xlsx_kit.py inspect --in 平时分依据表.xlsx
  ```

  脚本 stdout 只打印条数与文件路径，**不打印学生姓名**（避免姓名出现在终端记录里）。
  出表后 5 张工作表：

  | 工作表 | 内容 |
  |---|---|
  | 平时分汇总 | 学号 / 姓名 / 四项得分率 / 四项折算 / 加权小计 / 加分 / 平时分(初算) / **平时分(教师核定)** / 自动备注，按初算分降序 |
  | 追溯明细 | 每人每个分项一行：来源文件 ｜ 原始行号 ｜ 日期/周次 ｜ 原始记录 ｜ 适用规则 ｜ 折算得分 ｜ 说明，末尾一条「合计」= 该生初算分 |
  | 分数段分布 | 分数段人数 + 原生柱状图 |
  | 待核与异常 | 记录缺失 / 行数据异常 / 名单不符 / 考勤预警 / 教师核定提示 |
  | 数据来源与规则快照 | 权重口径、扣分口径、计算时间、**输入文件的 sha256**、个人信息提示 |

  规格骨架（`平时分依据表.spec.json`，由脚本生成；此处只列结构，`header/rows` 省略）：

  ```json
  {"sheets": [
    {"name": "平时分汇总", "header": ["学号","姓名","考勤得分率(20%)","互动得分率(30%)",
      "作业得分率(30%)","小测得分率(20%)","考勤折算(20)","互动折算(30)","作业折算(30)",
      "小测折算(20)","加权小计","加分","平时分(初算)","平时分(教师核定)","自动备注"], "rows": []},
    {"name": "追溯明细", "header": ["学号","姓名","组件","来源文件","原始行号","日期/周次",
      "原始记录","适用规则","折算得分","说明"], "rows": []},
    {"name": "分数段分布", "header": ["平时分(初算)区间","人数"], "rows": [],
     "chart": {"type": "bar", "title": "平时分(初算)分布", "value_col": 2, "anchor": "D2"}},
    {"name": "待核与异常", "header": ["类型","学号","姓名","说明","建议处理"], "rows": []},
    {"name": "数据来源与规则快照", "header": ["项目","内容"], "rows": []}
  ]}
  ```

  **第 4 步 · 实测结果（用合成测试数据跑通，2026-09-10，非真实学生）**：
  6 名学生、47 行追溯明细、9 条待核异常；其中一名学生互动累计 30 点超过 20 点基准被正确封顶，
  另一名加分 5 分使合计 105 分被 `cap_total` 封到 100 分 —— 两处封顶都在明细里落了调整行，
  且**每名学生的明细逐行相加都等于该生「平时分(初算)」**（脚本与人工双重核对过）。

  **可追溯性的三个机制（学生来质询时靠这个举证）：**

  1. **行级定位**：明细每一行都带来源文件 + 原始行号 + 原始记录 + 适用规则 + 折算得分。
     学生问「为什么扣我 2.5 分」，能直接翻到《考勤》第 20 行那条记录和
     `attendance.status.迟到=-10` 这条规则。
  2. **口径留痕**：规则快照与两个输入文件的 sha256 写进「数据来源与规则快照」表。
     事后谁也无法悄悄改口径重算而不被发现。
  3. **对账闭合**：明细逐行相加 = 初算分（脚本自动校验并打印）；封顶、下限、剔除最低都各有一行
     调整/说明，不留「解释不了的差额」。

  **第 5 步 · 人工确认位与教师核定（本 skill 的硬约束）：**

  - 汇总表「平时分(教师核定)」列的每个单元格固定为 `【待教师确认：____】`，
    **脚本与 AI 都不填分**；教师逐人核对后手填，填完这版才能作为发布依据。
  - 《待核与异常》里每条都要教师判一句：漏录还是事实？补录还是保留 0 分？
  - 交付时必须对教师说清三句：① 这是**初算草稿 + 举证材料**，不是最终成绩；
    ② 最终分值由任课教师核定后生效；③ 发布按学校成绩管理规定走流程。

  **第 6 步 · 常见返工点**（脚本会直接报错并给出行号，不猜测修正）：

  | 报错 | 原因 | 怎么办 |
  |---|---|---|
  | 权重之和必须为 100 | 权重写了 110 或 90 | 请教师确认公布过的那一版，改规则文件，不做自动归一 |
  | 出现规则里没有定义的值「××」 | 记录表有「调课」「病」等别称 | 别名表能认的会自动认；认不了的**先补规则**，不让脚本猜 |
  | 满分必须 > 0 | 满分列留空 | 补满分；缺数据不能算得分率 |
  | 找不到工作表「××」 | 表名被改过 | 改回标准表名，或同步改规则 `sheets` 段 |
  | 加分为负（-3） | 把扣分写进加分项 | 扣分走考勤/等级规则，不用负加分 |

- **输出**：`平时分依据表.xlsx`、`计算追溯明细.csv`、`待核与异常清单.md`。
- **退出条件**：明细无未解释差额；异常清单每条有教师判断；**「平时分(教师核定)」列已由教师填完**
  （未填完不得对外发布）。

---

### 阶段五 · 学情画像与干预建议

- **输入**：阶段三的记录表（含投票结果表）。
- **动作**：

  **1. 先从记录里算出这几个量**（照 `learning-analytics` 的参与度指标口径，只用记录里已有的事实）：

  | 指标 | 怎么算 | 看什么 |
  |---|---|---|
  | 参与课次占比 | 有互动记录的课次 / 总课次 | < 30% 要关注 |
  | 主动提问次数 | 互动类型 = 主动提问 的条数 | 主动性，与等级分开看 |
  | 首末互动周次 | 该生最早 / 最晚一条互动记录的周次 | 末期才出现 → 前期被边缘化 |
  | 等级均值 | `level_points` 折算后取平均 | 参与**质量**，不只看次数 |
  | 前后半学期差值 | 前半学期互动次数 vs 后半学期 | 进步的客观依据 |

  **2. 分成三类，每类给可执行干预**（照 `student-profiling` 的三维度看，但只用记录能支撑的部分）：

  | 类型 | 判定（用上表的量） | 不要下的结论 | 干预动作 |
  |---|---|---|---|
  | 沉默学生 | 参与课次占比 < 30%，或连续 3 周 0 互动记录 | 不是「不学」「态度差」；常见原因是怕答错丢面子、基础薄弱听不懂、大班额被淹没、性格内向、在校外打工 | ① 先给匿名参与通道：一分钟纸条 / 投票器，让他先「参与但不露面」；② 小组里给一个具体到能完成的小任务（如「你负责计时和记录」）；③ 冷呼叫前先给台阶：「这题有点绕，你先说说你卡在哪一步」；④ 课后一对一问一句「上节课哪一步没跟上」；⑤ 记录里如实补一条参与即可，**不要为了让他不难看而虚构记录** |
  | 积极学生 | 参与课次占比 > 80% 且等级均值高 | 不要因为「他愿意答」就总叫他 —— 少数人包场时，其余学生的参与机会被挤掉 | ① 把机会让出去：「先听两位还没发过言的」；② 给高阶任务：评价层/创造层提问、带小组复盘；③ 互动分已封顶后改用 `bonus` 加分项，避免「多答也不加分」的挫败；④ 不公开排名 |
  | 进步学生 | 后半学期互动次数 ≥ 前半学期 2 倍，或等级均值明显上升 | 不要只写「进步很大」这种没法举证的话 | ① 具体到行为的公开反馈：「这两周小组讨论里你们组的方案明显更完整了」；② 写进过程性评价，而不是只写期末结果；③ 别把「进步奖」做成变相排名 |

  **3. 班级层面的诊断（投票结果表的用法）**：
  某知识点错误率 > 40% → 下次课必须重讲；某个错误选项集中命中 → 那不是「粗心」，
  是一个具体误解，按阶段一备注里的「误选诊断 / 教学处置」处理。

  **4. 伦理红线（照 `student-profiling` 与 `learning-analytics` 的伦理条款）**：
  画像**用于支持而非标签**；不用「差生 / 学困生」这类词；不与其它学生比较排名；
  不写进任何公开材料、不上传外部平台；只作为教师自己的教学干预依据。

  **5. 出 DOCX**：

  ```bash
  $PY skills/office-layer/scripts/docx_kit.py md \
      --in 学情画像.md --out 学情画像与干预建议.docx --title "《数据结构》学情画像与干预建议"
  $PY skills/office-layer/scripts/docx_kit.py inspect --in 学情画像与干预建议.docx
  ```

- **输出**：`学情画像与干预建议.docx`（参与度分布 + 三类名单与干预动作）。
- **退出条件**：每条干预都落到「谁、什么时候、做什么」；通篇无标签化词；画像未含无记录支撑的推断。

---

### 阶段六 · 交付与收尾

- **输入**：前面各阶段的产出物。
- **动作**：
  1. **交付说明必须写这三句**：
     ① 本文件含学生姓名与学号等**个人信息**，请仅本地保管、不外传；
     ② 平时分是**初算草稿**，最终分值由任课教师核定后生效；
     ③ 《待核与异常清单》请逐条处理后再定版。
  2. **清理中间文件**（spec.json 可由记录表 + 规则重算，属可重建的中间产物）：

     ```bash
     # 确认依据表已生成并打开检查过之后
     rm -f 平时分/平时分依据表.spec.json 记录表模板.spec.json 投票题.spec.json
     # 本次任务若另建了临时工作目录，一并删除
     ```

     要保留也请放进受控目录（校内加密盘），**不要放公网网盘、不要发微信群**。
  3. 学期结束按学校要求归档或销毁过程记录；归档材料随 `exam-pipeline` 一起交。
- **输出**：交付说明 + 清理后的交付目录。
- **退出条件**：交付说明三句齐；中间文件已清理或已移入受控目录；教师已知悉个人信息保管要求。

## 产出物

| 文件 | 内容 | 何时给 |
|---|---|---|
| `随堂投票_<知识点>.pptx` | 3–5 题投屏（16:9），答案与误选诊断只在备注页 | 课前 |
| `提问链_<知识点>.docx` | 六层问题 + 预期回答 + 等答时间 + 追问 | 课前 |
| `课堂互动记录表.xlsx` | 考勤 / 课堂互动 / 投票结果 / 平时作业 / 随堂小测 / 加分项 / 填写说明 | 开课前一次 |
| `平时分规则.json` | 权重与扣分细则（**待教师定版**） | 开学 |
| `平时分依据表.xlsx` | 汇总 / 追溯明细 / 分数段分布 / 待核与异常 / 规则快照 | 期中、期末 |
| `计算追溯明细.csv` | 明细的 CSV 版，便于教师自己再对账 | 与依据表同时 |
| `待核与异常清单.md` | 记录缺失 / 异常行 / 名单不符 / 考勤预警，逐条待教师判 | 与依据表同时 |
| `学情画像与干预建议.docx` | 参与度分布 + 三类学生 + 干预动作 | 期中、期末 |
| 交付说明 | 含个人信息提示 + 初算草稿声明 + 中间文件清理说明 | 每次交付 |

## 红线

1. **平时分是评价性内容 —— AI 只出草稿与计算表，最终分值必须教师核定。**
   依据表固定保留 `【待教师确认：____】` 列，脚本与 AI 都不填分；
   初算分不得直接发给学生、不得直接导入教务系统。
2. **不虚构互动记录。**绝不生成、补全、推测缺失的考勤与课堂记录；缺就留空并进《待核与异常》。
   「为了不让学生吃亏」而补分，与伪造考勤同性质。
3. **不擅自改口径。**权重之和必须 100；扣分细则必须是**已向学生公布**的那一版；
   不提供「调权重把某人分数凑上去」这类服务 —— 学生质询时这是硬伤。
   规则与输入文件的 sha256 留在表里，就是为了让口径改动有痕迹。
4. **敏感数据本地处理。**学生姓名、学号、考勤、互动与成绩记录属个人信息：
   只在教师本机读写，不上传外部平台、不粘进公开对话、不发到微信群、不放公网网盘。
5. **交付说明必须注明「本文件含学生个人信息」**，并在任务结束时提醒删除中间文件（见阶段六）。
6. **投票结果默认不进个人平时分。**只有使用实名答题器且事先告知学生，才可按教师设定的口径计入。
7. **不贴标签、不排名。**学情画像只用于教学干预，不写成「差生名单」，不公布，不作定性评价用语。
8. **涉及学籍处分只预警不裁定。**旷课达阈值时提示教师按学校学籍/考勤规定处理，不由本表自动处分。

## 自检清单

**课前材料**
- [ ] 投票题 3–5 题，每题备注四行齐（正确答案 / 用途 / 误选诊断 / 教学处置）
- [ ] 每题都能回答「选错说明什么」，且没有一眼看出答案的选项，A/B/C/D 未连出同字母
- [ ] `pptx_kit.py inspect` 无 `overdense`（单页正文 ≤ 220 字符）；投屏页找不到答案
- [ ] 提问链六层齐全，每层有预期回答与等答时间，评价/创造层未超出课时预算

**记录**
- [ ] 记录表列名与脚本要求一致（学号 / 姓名 / 状态 / 互动类型 / 表现等级 / 得分 / 满分）
- [ ] 工作表名与规则 `sheets` 段一致；模板里的示例行已删除
- [ ] A–D 等级口径已告知学生；缺交记 0 分而不是留空

**平时分（逐项过，这一节出事后果最重）**
- [ ] 权重之和 = 100，且是**本学期已向学生公布**的那一版
- [ ] 已备份原始记录表（脚本只读输入，但仍先备份）
- [ ] 依据表 5 张表齐全；图表与冻结窗格正常
- [ ] **明细逐行相加 = 平时分(初算)**：抽查 1 名学生手算一遍核对
- [ ] 封顶 / 下限 / 剔除最低 都有对应的调整明细行，能解释每一分差额
- [ ] 「平时分(教师核定)」列未被 AI 或脚本填分
- [ ] 《待核与异常》每条都有教师处理意见（漏录？补录？保留 0 分？）
- [ ] 教师已逐人核定并填写核定列

**隐私与交付**
- [ ] 全过程无学生数据外传；stdout 未出现学生姓名
- [ ] 交付说明写明「含个人信息 + 初算草稿待教师核定 + 中间文件清理」
- [ ] 中间文件已删除或移入受控目录；未留在公网网盘/聊天群
- [ ] 学情画像无标签化词、无排名、无记录不支撑的推断
- [ ] 本文件引用的 底座路径已用 `ls` 验证存在

**自检命令**（交付前跑一遍，别靠记忆）：

```bash
PY="skills/office-layer/.venv/bin/python"

ls -d skills/ibook-skills/question-writing/ skills/education-skills/edu-learning-analytics/ \
      skills/k12-teacher-skills/k12-check-for-understanding/ \
      skills/learning-education/thinking-toolkit/ skills/office-layer/

$PY skills/office-layer/scripts/pptx_kit.py  inspect --in 随堂投票_图的遍历.pptx
$PY skills/office-layer/scripts/xlsx_kit.py  inspect --in 平时分依据表.xlsx
$PY skills/office-layer/scripts/docx_kit.py  inspect --in 学情画像与干预建议.docx
```