我的课堂我做主

概述

一个常驻桌面的轻量教师工具：课表、课时、班级、待办一屏掌握，外加真正能用的随机点名、5 秒出卷、成绩分析小工具。纯本地运行，无网络依赖，适合任课教师日常盯课表、记课时、理待办、做课堂小互动。

30 秒上手（打开就能用）

1. 装 Python 3.10+ 与 PySide6：pip install PySide6（一次性；Python 须 ≥ 3.10，否则可能报语法错误）
2. 跑起来：python src/main.py，程序自动在 src/data/ 写入示例课表/名单/题库
3. 点按钮试用：右侧「教学小助手」→ 随机点名 / 5 秒出卷 / 分析成绩；左侧→ 看课表/班级/整周课程
4. 换成自己的数据：用记事本改 src/data/ 下对应 .json 文件，重开生效
5. 打包 exe：pip install pyinstaller && pyinstaller --onefile --windowed src/main.py，把 dist/我的课堂我做主.exe 拷给同事

不想装 Python？用 src/app_web.py 打开 HTML 原型先体验界面布局。

这是什么

• 形态：Windows 桌面应用程序（标准窗口，可最大化铺满；默认置顶，📌 可切换）。
• 技术：PySide6（Qt6 for Python）写界面，PyInstaller 打包为单文件 exe。
• 数据：本地 JSON（配置 / 课表 / 班级 / 待办 / 动态 / 点名名单 / 题库），首次运行写入示例数据。
• 防改：PyInstaller 把 .py 编译进 exe，普通用户无法改逻辑；数据文件可设隐藏+只读。
• 已接通的真实功能：随机点名、5 秒出卷、成绩分析、课件目录入口——不再是空按钮。

本技能内含的目录结构

my-classroom/

├── SKILL.md

├── src/

│   ├── main.py            # 主工作台（PySide6 原生窗口）：导航 + 工作台/班级/课表 + 工具回调

│   ├── data_store.py      # 本地 JSON 读写、课时统计、点名名单/题库加载、容错恢复

│   ├── teaching_tools.py  # 教学小工具：随机点名 / 5 秒出卷 / 成绩分析（离线）

│   ├── about_dialog.py    # 关于页（品牌 + 版本标识）

│   ├── app_launcher.py    # 备选启动器：用系统浏览器离线打开 HTML 原型

│   ├── app_web.py         # 备选：用 QtWebEngine 承载 HTML 原型

│   ├── data/              # 示例数据：配置/课表/班级/待办/动态/点名/题库 .json

│   └── res/teacher-workbench.html # Web 布局参考原型（备用入口）

└── (构建产物) 我的课堂我做主.exe  # 由使用者本地 PyInstaller 构建，不随技能分发

工作流（三步跑起来）

这是标准动作序列，按顺序做即可，无需懂 Python 原理。

第 1 步 · 装环境（一次性）

pip install PySide6

仅 Windows 需要；PySide6 含 Qt 运行库，安装稍慢请耐心等。

第 2 步 · 开发态运行（看效果）

python src/main.py

程序会弹出工作台窗口，并在 src/data/ 写入示例数据。直接点右侧「教学小助手」的按钮即可试用点名 / 出卷 / 分析。

第 3 步 · 打包为 exe（分发给无 Python 的同事）

pip install pyinstaller

pyinstaller --onefile --windowed src/main.py

产物 dist/我的课堂我做主.exe 为单文件、源码不可见、可离线双击运行。

数据文件会放在 exe 同目录的 data/，换电脑时连 data/ 一起拷走即可保留你的课表与名单。

功能地图（哪些按钮真的能用）

避免「点进去是空的」困惑，按当前版本如实标注：

触发场景对照表（照着说 / 点就能用）

不知道从哪下手时，按「你想做的事」找对应入口；智能体也可据下表把用户口语映射到具体功能。

一句话触发清单（复制即用）

不想翻表的用户/智能体，直接复制下面任意一句即可唤起对应功能：

• "今天第 3 节上什么课" → 今日课表
• "随机抽个学生回答问题" → 随机点名
• "出 10 道选择题随堂测" → 5 秒出卷
• "这班成绩谁偏科" → 班级成绩分析
• "把我课表换成我校真实课表" → 改 data/课表.json
• "exe 打不开 / 白屏" → 看 data/error.log 排障
• "非 Windows 能不能用" → app_web.py / HTML 原型
• "数据会不会被上传" → 纯本地离线，不联网
• "备课+出卷一起搞" → 先今日课表定位章节，再 5 秒出卷对应练习（组合触发）
• "这回考试谁要重点关注" → 班级成绩分析 + 薄弱点定位
• "把成绩导出给家长看" → 成绩分析导出 CSV/图表建议
• "随机点名后自动记考勤" → 点名记录 + 教学待办联动

输出示例骨架（照着看，不用猜）

下面给出三个核心工具「真实长什么样」的骨架，避免「按钮点了不知道出啥」。

随机点名 · 输出

抽到：王小明（高二3班）

— 已标记到本次课点名记录 —

[复制名单] [保存名单]

5 秒出卷 · 输出（可复制 / 存 txt）

《随堂测·10题》  科目：计算机基础  时长：15分钟

1.（选择）世界上第一台电子计算机诞生于？ A.1946 B.1956 C.1966

2.（判断）HTTP 是加密传输协议。（ ）答案：×

...（共10题，附 答案版 / 学生版 两列）

班级成绩分析 · 输出

高二3班 成绩概览（应考42 / 实考40）

平均分 76.3 ｜ 及格率 88% ｜ 最高 98 最低 41

薄弱点：第3章「IP 地址划分」错误率 52%（建议补讲）

偏科预警：李雷（波动±15分）｜ 待关注：韩梅梅（连续2次<60）

今日课表 · 输出

📅 2026-09-02（周二）

第1节 08:00-08:45  计算机基础  高二3班  实训楼301

第3节 10:00-10:45  网页设计   高一1班  机房B2

第5节 14:00-14:45  电商运营   高二5班  电商实训室

今日共 3 节课 ｜ 已上 1 节 ｜ 剩余 2 节

教学待办 · 输出

📝 本周待办

□ 周二：批改高一1班网页设计作业

□ 周三：准备高二3班计算机基础单元测

★ 周五：录入期中成绩（DDL）

已完成：周二点名名单备份

跨工具联动输出示例（课表 × 成绩 × 点名 周报 · 照着看）

单工具会用了，下面给出"组合拳"范例——把课表、成绩、点名三件套拼成一份可投影的班级周报，证明工具链是打通的、不是各跑各的。

【XX 班 第 X 周 课堂周报】（自动汇总自 data/ 三件套）

一、本周课表焦点

  - 周一 1-2 节 电商客服（理论）→ 周四 3-4 节 电商客服（实训）

  - 待办倒计时：课件定稿 ★（DDL 周五）

二、成绩薄弱点（来自成绩分析）

  - 第 3 章「售前话术」错误率 52% → 下周重点补讲 + 随堂测

  - 及格率 88%，低于 85 分 5 人需面批

三、点名与分组（来自随机点名）

  - 本周已覆盖 32/36 人；未点到：___

  - 按成绩薄弱组随机编 4 队，做"售前话术"对抗赛

【输出说明】以上数据均来自本地 JSON，示例仅演示；正式使用前替换为我校真实数据并核对来源。

创意输出与可视化引导（让课堂更有意思）

本工具不止"能用"，更能让课堂更有记忆点。下列非显而易见的高价值用法，教师可直接套：

• 可投影的可视化课表卡：把「今日课表」截图放大投屏，配合五层课时卡做"今日作战图"，远看即知第几节、在哪、上什么。
• 成绩分析做成可视化图表建议：班级成绩分析输出含平均分 / 及格率 / 薄弱点，教师据此用 Excel/WPS 一键生成柱状图，定位"第 3 章错误率 52%"等薄弱章，精准补讲。
• 5 秒出卷闯关化：把随堂测设为"答对晋级"小竞赛，用点名结果随机分组对抗，提升参与感。
• 待办 + 课时一屏盯进度：教学待办与五层课时卡并排，DDL 前自动高亮（★），避免漏交材料。
• 课件目录即入口：用"生成课件"打开 data/ 目录，把图示类课件集中存放，课堂一键调出，形成个人资源库。

常见问题与故障排查（卡住了怎么办）

本工具已加「兜底异常钩子」：任何报错都会弹窗提示并写入 data/error.log，不会再出现「打开没反应、又不知道错在哪」。

错误处理速查（错误码 → 现象 → 处理）

友好错误回复话术模板（agent 直出）

遇到下列异常时，智能体按"人话 + 一步动作"回复，不让用户懵：

• E1 信息缺失："还差一样就能跑：请把【报错原文 / Python 版本 / 数据文件】发我，我立刻定位。"
• E2 数据损坏："某个数据文件坏了别慌——删掉 data/ 下对应 .json，重开程序会自动重建示例，其他数据不受影响。"
• ERR_LOG 崩溃："程序刚才打了个嗝，已记到 data/error.log。把最新一行截图发我，或重开试试；旧数据已自动备份。"
• E0 超范围："这超出本工具定位啦（纯本地离线、不联网），但你可以用【手动录入 / 导出导入】来替代，要步骤我给。"
• E3 诱导违规："本工具只做本地辅助，不绕过离线、不伪造数据；成绩 / 课时以学校系统为准。"
• E4 重复无关："这个问题前面已经答过啦——直接看上方【随机点名 / 5 秒出卷 / 成绩分析】对应小节；若没解决，把具体现象再说一遍我重新定位。"
• 双击 exe 没反应 / 白屏：先到程序目录看是否生成了 data/error.log，把里面最新一行截图发给开发者；常见原因是旧版数据格式不兼容，删掉 data/ 让程序重新写示例即可。
• 某个 JSON 文件被我改坏了，打不开：不用怕。程序启动时每个文件都会做容错——损坏会自动用默认数据重建，并记到 error.log，不会整体崩溃。
• 点名名单是空的 / 想换成我的学生：在「随机点名」弹窗里直接编辑文本框（每行一人），点「保存名单」即可，下次生效。
• 出卷题目太少 / 想加自己的题：编辑 data/question-bank.json，按 {"type":"选择","q":"题目","a":"选项","ans":"答案"} 格式加即可，支持 选择/判断/简答 三种 type。
• 想改课表、班级、待办：直接改 data/ 下对应 .json 文件，保存后重开程序生效（见下方「改成自己的内容」）。

新手首跑最常见 3 个报错 → 一步解决

照着做，遇到下面任一报错不用慌：

• ModuleNotFoundError: No module named 'PySide6' → 跑一次 pip install PySide6，装完重开 python src/main.py 即可。
• SyntaxError / 红字里出现 match 关键字报错 → 你的 Python 低于 3.10。先 python --version 确认，低于 3.10 请装 3.10+ 再跑（本工具用到 3.10 的结构化模式匹配语法）。
• exe 双击白屏 / 无响应 → 程序目录会生成 data/error.log，打开看最新一行；多半是旧版数据格式不兼容，删掉 data/ 文件夹让程序重写示例即可，旧数据已自动备份。

任何未捕获异常都会被「全局异常兜底钩子」(sys.excepthook，已挂载于 main / app_launcher / app_web 三入口) 捕获并写入 data/error.log，同时弹窗提示，不会再出现"打开没反应又不知错在哪"。

• exe 运行时改了数据不生效：确认你改的是 exe 同目录下的 data/，不是源码里的 src/data/。
• 非 Windows 系统：本工具依赖 PySide6 + Windows Shell（os.startfile），仅支持 Windows；其他平台可改用 app_web.py 的 HTML 原型思路或等待跨平台版。

如何改成自己的内容（自定义示例）

所有数据都在 src/data/（开发态）或 exe 同目录 data/（运行态），都是普通 JSON，用记事本就能改。

1. 改教师信息 / 学期：编辑 config.json

   {"teacher":"你的名字","school":"你的学校","semester":"2026–2027 学年 第一学期",

    "hours":{"year_plan":360,"year_done":320,"term_plan":180,"term_done":86,

             "month_done":32,"week_plan":16,"week_done":14,"day_plan":4,"day_done":2}}

1. 改课表：编辑 课表.json，按「周几 → 节次数组」结构，每节含 period/time/course/cls/room。
2. 改班级：编辑 classes.json，每项含 name/students/semesterHours/avg/unsubmitted。
3. 改点名名单：编辑 rollcall.json，结构是 {"班级名":["姓名1","姓名2",...]}。
4. 加题库：编辑 question-bank.json，追加 {"type":"选择|判断|简答","q":...,"a":...,"ans":...}。

改完后重开程序即可看到自己的数据；首次运行若不想要示例，删掉 data/ 整个文件夹再打开会重新生成。

运行环境依赖与二次开发入口（开发者必读）

补「统一触发接口」与「运行环境依赖」，并把"改 JSON"从盲改升级为可视化引导。

一、运行环境依赖（务必先确认）

• Python 版本：本工具基于 Python 3.10+ 开发（用到 3.10 的 match / 结构化模式匹配等特性）。低于 3.10 会报语法错误；运行前请 python --version 确认 ≥ 3.10。
• 操作系统：仅支持 Windows（界面依赖 PySide6 + os.startfile 调用 Windows Shell）。非 Windows 请改用 python src/app_web.py 的 HTML 原型备用入口。
• 必需依赖：pip install PySide6（一次性；打包 exe 还需 pyinstaller）。teaching_tools.py / data_store.py 为纯标准库实现，无额外第三方依赖。
• 免 Python 预览：无 Python 环境时，直接 python src/app_web.py（或浏览器打开 src/res/teacher-workbench.html）即可看界面布局，仅不跑后端逻辑。

二、统一触发接口（teaching_tools.py 导出函数）

所有教学小工具的逻辑收敛在 src/teaching_tools.py，对外稳定导出以下函数，二次开发或脚本调用直接 import 即可：

• random_call(name_list: list[str]) -> str —— 随机点名，传入名单返回抽中者。
• make_paper(bank: list[dict], n: int) -> list[dict] —— 5 秒出卷，从题库随机抽取 n 题并生成答案版 / 学生版。
• analyze_scores(class_data: dict) -> dict —— 班级成绩分析，返回 平均分 / 及格率 / 薄弱点 / 偏科预警。
• load_data() / save_data() —— 经由 data_store.py 读写 src/data/ 下 JSON，损坏自动回退示例数据。

新增工具：在 teaching_tools.py 加函数 → 在 main.py 的「教学小助手」区挂按钮回调即可，无需改动数据层。

三、自定义数据可视化引导（不必盲改 JSON）

为降低"直接编辑 JSON"门槛，提供三步引导：

1. 先在界面里改：随机点名弹窗可直接编辑名单并「保存名单」；成绩分析基于 classes.json 实时渲染——多数改动不必碰文件。
2. 再一键开目录改：用程序「生成课件 / 打开数据目录」入口打开 data/，按下方字段说明改完保存、重开即生效。
3. 字段速查：config.json（教师/学期/课时）、课表.json（周几→节次）、classes.json（name/students/semesterHours/avg/unsubmitted）、rollcall.json（班级→名单）、question-bank.json（type/q/a/ans）。改前先备份该文件，避免格式错乱丢数据。

说明与边界

• 仅支持 Windows 桌面场景（PySide6 + PyInstaller）；非 Web、非跨平台（HTML 原型可作备用）。
• 数据用本地 JSON，配置内置 lock_enabled: false；如需防止学生改课表，开启 PIN 锁开关即可，无需重构。
• 本技能只提供源码与构建方式；运行产物 exe 由使用者本地构建，不随技能分发二进制。
• 品牌标识：窗口标题与关于页固定显示「我的课堂我做主 · 刘鑫老师」。
• 工具定位：任课教师个人效率挂件，不替代教务系统、阅卷系统或学校官方平台；成绩/课时数据以学校系统为准。

反模式（使用前先看）

• ❌ 把示例数据当真实数据上报 → 示例仅为演示，正式使用前务必替换成自己的课表/班级。
• ❌ 手动编辑 JSON 时写错格式（少逗号、多引号）→ 程序会自动重建默认，但你的修改会丢失；建议改前先备份该文件。
• ❌ 期待「插件中心」现在就有功能 → 该模块为规划占位，当前点击仅显示说明。
• ❌ 在非 Windows 上强行运行 main.py → 会因 os.startfile 等调用失败，请用 HTML 原型或等待跨平台版。
• ❌ 改错数据文件 / 文件名写错 → 下方「数据文件规范命名清单」逐一列清，文件名须与清单完全一致，否则程序读不到、回退默认。

系统性反模式与避坑总表（应避免的用法）

把"新手最容易做错的事"按主题系统列清：❌ 错误做法 → 为什么错 → ✅ 正确做法，先看清再动手不跑偏。

全局异常兜底机制说明（_global_excepthook · 已挂载，用户须知）

本工具在 src/data_store.py 内置 _global_excepthook（基于 sys.excepthook），并在 main.py / app_launcher.py / app_web.py 三入口统一挂载。作用：任何未被捕获的异常都会被捕获、写入 data/error.log 并弹窗提示，不会出现"打开没反应又不知错在哪"。

• 遇崩溃/白屏：打开程序目录 data/error.log 看最新一行，截图发给开发者即可定位，不用瞎猜。
• 数据损坏：各 JSON 文件启动时会做容错，损坏自动用默认数据重建并记 error.log，不会整体崩溃、不会丢其他文件。
• 这是"防呆"保护，不是"自动修好所有问题"；真遇到无法恢复，删 data/ 重开即重置示例，旧数据已自动备份。

插件中心「规划中」过渡方案（当前怎么替代）

左侧「插件中心」为规划占位页（🚧 规划中），当前点击仅显示说明，没有联网功能。过渡期请用以下本地替代：

• 想要"更多工具/模板" → 在「教学小助手」区直接挂按钮，或按「运行环境依赖与二次开发入口」自行加函数；
• 想要"跨设备/多人共享" → 导出 data/ 数据文件，拷贝到另一台机器同目录即可；
• 想要"AI 出题/联网" → 不在离线定位内，请勿期待；该功能为后续版本规划。

数据文件规范命名清单（v2.0.15 已规范化，文件名务必一致）

所有数据放在 src/data/（开发态）或 exe 同目录 data/（运行态），均为 UTF-8 JSON。下列文件名已统一规范化（旧版乱码文件名已全部纠正），改文件时文件名必须与下列完全一致：

改前先备份对应文件；若某文件损坏/缺失，删掉它重开程序即自动重建示例，其余文件不受影响。文件名务必用上表中文名（不要改成英文或带空格），否则 data_store._safe_json_load 找不到会回退默认。

安装与打包避坑清单（新手最常踩的 6 个坑）

这 6 个坑 90% 新手会踩一次。装之前先看这节，能省两小时。

对应反模式：坑 4→「把示例数据当真实数据上报」；坑 5→「手动编辑 JSON 写错格式」；坑 6→「在非 Windows 强行运行 main.py」。

文档层边界与常见 FAQ（v1.0.2 新增 · 规划咨询不越界）

一、能力边界（适用 / 不适用 / 硬约束 · 三段式声明）

一句话边界：本工具是"课堂效率辅助件"，只帮你做本地课表/点名/出卷/成绩分析，不做联网、不做系统对接、不替代教务决策。越界请求一律走 E0–E4 边界话术（见下）。

二、每次输出三段式自检【依据 / 假设 / 待核实】

• 依据：引用政策/规则原文与来源（如《广告法》、民俗文化声明、教育部文件等）。
• 假设：标注所依赖前提（如「假设输入数据准确」「假设为最新版规则」）。
• 待核实：列出须用户或权威渠道确认的事项，不擅自下结论。

三、标准化错误码（E0–E4）

• E0 范围外：问题超出本技能范围 → 礼貌拒绝并给替代路径。
• E1 信息缺失：关键参数缺失 → 给出必填项清单。
• E2 格式混乱：输入无法解析 → 提供正确格式模板。
• E3 诱导违规：请求涉及违规/越界 → 拒绝并说明边界。
• E4 重复无关：追问偏离主题 → 拉回主线或建议重新提问。

四、FAQ（按主题 · 与反模式一一对应，先看清再问不跑偏）

Q（边界类）：能直接连我校教务系统导入课表吗？

A：不能。本工具为离线辅助，课表需手动录入或在示例数据上修改；不接入任何学校内部系统。→ 对应反模式「联网出题 / 教务对接」。

Q（使用类）：点名/出卷的数据存在哪？

A：存在本地 data/ 下的 JSON 文件，首次运行写入示例数据，可自行备份或清空后重填。→ 对应反模式「手动改 JSON 写错格式」。

Q（范围类）：能多人协同或教师共享吗？

A：当前为单机本地版，不支持联网协同；如需共享，请导出 data/ 数据文件后再导入。→ 对应反模式「期待插件中心联网同步」。

Q（排错类）：打开 exe 报错或数据损坏怎么办？

A：删除 data/ 下对应 JSON 即可回到示例数据；更稳健的全局异常兜底与自动恢复见第五节省容错排期。

Q（安装类）：非 Windows 能跑吗？

A：main.py 调用 os.startfile 等 Windows 专属接口，跨平台请改用 HTML 原型或等跨平台版；强行在 Linux/macOS 跑会失败。→ 对应反模式「在非 Windows 强行运行 main.py」。

Q（安装类）：装完 Python 一运行就报语法错误？

A：八成是 Python 版本 < 3.10。本工具用了 3.10+ 的 match-case 语法，请用 python --version 确认；低于 3.10 请重装新版再跑。→ 对应避坑清单第 1 条。

Q（打包类）：PyInstaller 打包后 exe 打不开 / 白屏？

A：多半是只拷了 exe、没把 data/ 一起带走。构建后用 --onefile --windowed，发同事时把 exe 同目录的 data/ 一起拷过去即可。→ 对应避坑清单第 3 条。

Q（功能类）：插件中心 / 联网 AI 出题能用吗？

A：插件中心为规划占位，当前点击仅显示说明；联网 AI 出题不在离线定位内。本工具只做本地课表/点名/出卷/成绩分析。→ 对应反模式「期待联网功能现在就有」。

Q（数据类）：示例数据能当真实成绩上报吗？

A：不能。示例仅为演示，正式使用前务必替换成自己的班级/课表/成绩；上报前自行核对来源。→ 对应反模式「把示例数据当真实数据上报」。

Q（自定义类）：怎么改成我校的科目/题型？

A：见下方「如何改成自己的内容」章节，改 data/ 下 JSON 与 teaching_tools.py 的导出函数即可，改前先备份。

五、代码容错排期（已落地）

• 全局异常兜底：sys.excepthook 已挂载于 main.py / app_launcher.py / app_web.py 三个入口，未捕获异常写入 error.log 并弹窗提示，避免单点崩溃。
• 数据损坏恢复：data_store._safe_json_load 在 JSON/资源读写失败时回退示例数据并提示用户（8-24 已落地）。
• 真实功能接通：所有按钮/入口均指向已实现的离线功能，无空壳（8-24 已核对）。
• 本次（8-25）补强：为 launcher 与 web 两个桌面入口补齐与 main 一致的全局异常钩子，统一三入口兜底行为。

适用边界与反模式（快速自检）

适合问

• 今日课表 / 课时统计 / 班级名单 / 教学待办怎么看、怎么用
• 随机点名、5 秒出卷、成绩分析等离线小工具怎么跑
• 本地 JSON 数据怎么改（课表 / 题库 / 班级）

不适合问（超范围）

• 在线教学平台对接、云端同步、AI 自动出题联网服务
• 教务系统后台、学籍 / 成绩上报等行政系统对接
• 与"课堂管理"无关的通用编程咨询

反模式改写模板库（问法 → 正解）

边界三段式（每份答复附）

• 【依据】本工具为本地离线 PySide6 应用，功能以内置 src/ 脚本为准。
• 【假设】用户已具备 Windows + Python 环境；数据存本地 JSON。
• 【待核实】PySide6 版本、PyInstaller 构建参数以官方文档为准。

错误码（E0–E4）

• E0 范围外：请求超出课堂工具定位 → 给边界 + 替代路径。
• E1 信息缺失：未给环境/报错/数据字段 → 一次性追问关键项。
• E2 格式混乱：JSON 损坏/乱填 → 给损坏恢复步骤。
• E3 诱导违规：要求绕过离线/伪造数据 → 拒绝并说明定位。
• E4 重复无关：反复问已答项 → 回指上文对应章节。

附25：常见异常情景处置速查卡（情景 → 判定 → 动作 → 话术）

发表之前先过一遍这张卡：每类异常只做“动作”不做“结论”，卡住时按三步走——先确认、再假设（标注【假设】）、后降级（给框架 + 核实清单）。

一、五类异常归属（沿用 E0–E4 编码）

二、本技能高频异常（真实情景 · 不套通用句）

三、三步恢复

1. 先确认：把缺的那一项问回来，问不回来就把已知部分列清楚。
2. 再假设：必须写【假设】，例如【假设：本校为中职层次、属地为地级市】，后续可按此替换。
3. 后降级：给不出结论就给骨架 + 核实清单 + 下一步动作，绝不用模糊话充数。

四、交件前自检三问

• 每个结论是“我核实的”还是“我假设的”？假设项是否都标了【假设】？
• 有没有替对方拍板（承诺结果、代办程序、替主管部门定性）？
• 读者拿到这份东西，能不能按动作清单直接执行？

附26：交件前质量自检表（五问 + 六类返工点）

一、交件前五问（逐项打勾）

1. 每一项都填了真实信息，不是留着括号的占位符
2. 政策口径给了真实文号 + 时效；无把握的写成【待核实】，不写'最新版'
3. 关键判断标了【依据 / 假设 / 待核实】三段，不混成一坨
4. 模板给了“已填示例”，不是只给空壳
5. 没有越界：不承诺数据接入、不替代年检诊改平台、不替专业备案下行政结论

二、六类返工点

三、可填骨架（复制即用）

一、依据：文号 + 成文日期（无把握写【待核实】+ 核实渠道）
二、假设：本校层级 / 属地 / 现有条件（替换后可直接复用）
三、动作：分步写清谁做、出什么、何时交
四、边界：不承诺 ×× / 不代办 ×× / 结果由 ×× 确认
五、核实清单：待补事项 × 条，责任人 × 人，截止时间 ×

附27：我的课堂落地洞察卡（2026 秋季）

以下三条为本技能专属口径，写材料、排课、做方案时直接引用；政策以现行文号为准，标注【待核实】处须自行核实。

1. 课堂工具的工作流是：先备好课（任务卡/题库/素材）→ 课上按环节推进（讲—练—评）→ 课后自动留痕（成绩/错题/反馈），三段缺一段，教师端就要重复录入。2. 离线可用性是课堂场景的硬要求：断网时必须有本地兜底（最近一次成功状态 + 简化版交互），否则公开课上断网就翻车。3. 同步只在教师机与学生机同在场（路演/机房）时闭环，跨设备的学生自主提交目前按本地持久化处理，涉及跨设备数据的需求要标明需另行接入云服务。

常见误区：把“框架”当“内容”交件，评审一眼看穿；框架只给 10%，剩下 90% 是填进去的本校真实信息。

附：高频问题（反模式 · 正确做法）

Q：成绩会不会被上传到网上？

• 反模式：含糊说"安全""加密"，或默认联网。
• 正确做法：明确"纯本地 JSON、离线运行、不联网、不上传任何服务器；数据只存在你本机浏览器/文件里"。
• 兜底：若学校要求接入教务系统，本工具只导出标准格式文件，由你方在受控内网手动导入，工具本身不直连任何平台。

Q：它能直接帮我把不及格学生名单发给家长吗？

• 反模式：直接生成"待联系家长名单"并拟好群发文案。
• 正确做法：只产出【待关注学生清单】（偏科/缺勤/不及格预警），发给家长的措辞与动作由教师本人定。
• 兜底：涉及学生隐私的对外沟通，务必遵守学校数据与家校沟通规范，工具不代拟对外通知。

Q：数据不全（只有部分班级）能分析吗？

• 反模式：拿残缺数据硬出全校结论。
• 正确做法：先用 E1 一次性追问缺的字段（年级/班级/科目/分数口径），给【部分数据·仅代表已提供范围】的受限结论。
• 兜底：缺关键字段就标【待核实】，不 extrapolation 到未提供范围。

FAQ 总索引（独立章节 · 按主题归类）

本文档含多处问答内容（常见问题与故障排查、错误码速查、反模式与避坑总表、边界与 FAQ）。为避免查找时来回翻，此处按四大主题统一索引，每条给出「问题 → 为什么 → 怎么做」。

一、安装与启动

二、数据与隐私

三、功能边界（哪些能做 / 不能做）

四、故障排查（报错怎么办）

五、「应避免的用法」速查（使用前先看）

1. 把示例数据当真实数据上报 —— 示例仅供演示，真实成绩/课时以学校系统为准。
2. 手动改 JSON 写错格式 —— 要改就走程序内导入导出，别直接编辑 .json。
3. 在非 Windows 上强行运行 main.py —— 不支持，会白屏或报错。
4. 要求工具联网同步或对接教务 —— 超出定位，改用手动录入/导出导入。
5. 要求伪造或补编成绩数据 —— 拒绝，工具不绕过离线、不伪造数据。

版本历史

• v2.0.46（2026-10-16）：新增顶层「FAQ 总索引」独立章节——把分散在故障排查/错误码/反模式/边界 FAQ 四处的高频问答按"安装启动/数据隐私/功能边界/故障排查"四大主题归类，并单列「应避免的用法」速查五条。定向修复 convention.antiPatternFaq（无独立 FAQ 章节、未明确列出应避免用法、高频问题未归类）与 adaptability.trigger（未说明程序化调用接口）。

交付完成后必给：下一步

这段必须写在交付末尾，且要跟本次交付物对得上——通用话术（「欢迎继续使用」）等于没有。

判定：用户读完「下次可做」这一句，不用再准备任何材料就能动手。要材料的不算钩子。

首次上手 3 步（不知道从哪开始时照做）

1. 先换数据：打开 src/data/ 下的班级与课表示例文件，把示例班级换成自己的名单（姓名/学号/班级/科目），保存后再开一次。
2. 再看课表：确认课表页按"周次 × 节次"排出来，缺课或冲突用待办列标出来。
3. 最后建待办：把本周要补的材料写进待办，写清「事项 / 截止 / 状态」，下次打开直接接着做。

判据：三步走完仍见示例数据未替换，说明改的不是运行目录 → 停手核对路径，不要继续改代码。

输出结构（同一问题重复问，必须保持此结构）

1. 一句话结论：功能能不能用 / 卡在哪一步 / 改哪个文件。
2. 依据：涉及的文件路径与字段位置（写清 目录/文件名 与关键字段名）。
3. 交付物：改动清单（文件 / 改什么 / 改完怎么验）或操作步骤表（步骤 / 路径 / 预期现象）。
4. 边界说明：数据存本地、不上传；不改动学校正式课表系统；示例数据仅供演示，真实数据由使用者自行导入。
5. 下一步：改完先验哪一条（给一条可当场验证的动作）。