ClassHelper v1.4.5

ClassHelper v1.4.5

本批按用户要求保持 1.4.5，同版本重建 Windows 服务端、Web 管理端、Windows 客户端和 Linux 服务端。原 v1.4.5 标签保持不变；下载区二进制使用下方注明的新源码提交。

本次重建：AI 追问与对话删除

• 普通文字追问、消息式问题和问题字段兼容为真正的提问弹窗，支持选项、自由回答和刷新恢复，不再因为正常追问而反复自动校正。
• 删除课表等危险操作先生成待确认预览，再由界面弹出最终确认窗口；聊天回答不能代替执行确认，取消不会删除业务。
• 可删除本人对话，清理轮次与暂存附件并使未完成计划失效；保留已执行业务与审计，运行中的任务需先停止或等待完成。
• 新增并发保护，避免删除对话与创建新轮次互相覆盖。

登录与教师账号

• 员工和班级登录共用来源 IP 失败计数：连续五次密码错误后封禁五分钟，成功登录清零。
• 密码错误直接显示接口返回的原因，不再误报“登录状态已失效”。受保护接口的过期会话处理保持生效。
• 教师名单及任课关系导入中新建的教师，分别生成随机初始密码。导入结果提供一次性查看和 CSV 下载；重复导入已有账号不重置密码，审计不保存密码清单。
• 教师 CSV/Excel 模板移除初始密码列，旧表格中的密码列不再用于设置密码。

客户端与灵动岛

• 修复自定义灵动岛圆角调整，外观页圆角滑块与当前方案同步。
• 统一编辑页深浅主题和控件样式，移除编辑提示及组件库中的通知、作业、叫人添加选项；消息展示、提醒、铃铛和已有方案兼容保留。
• 临近下课不再显示“即将下课”整条提醒，自定义岛保留常态课表；课程名右侧以蓝色圆形徽标显示剩余秒数，例如 -1。
• 修复横向显示当日课程时，课程名与空课占位符上下错位。
• 移除客户端启动、关于页和开发者页的主动更新检查。更新由管理端统一下发，保留 SHA256 校验、本机自动更新开关和更新策略。
• 包含此前已完成的 AI 对话、每日作息与课件目录体验改进。

升级须知

升级前备份数据库及课件目录，按既有部署流程应用随包迁移。本批包含 20261108000000_conversations_daily_layouts；Windows 覆盖升级保留原有 .env，首次安装生成独立密钥。

已安装旧批次 1.4.5 时，下载本批安装包手动覆盖升级；同版本号不会触发新的版本提示。

导入教师后请在关闭结果窗口前保存并分发随机密码清单。客户端升级至本版后，通过管理端客户端管理下发后续更新。

本次重建验证

源码提交：195ee3b90a6ce57c318daeba0d58a0191c880d72。本次 AI 隔离验收 57 项、Web UI 84/84、追问解析专项通过；Lint、完整类型检查、严格文档检查通过。

Linux 正式包由 Ubuntu Actions 构建成功，已核验版本、迁移、完整归档读取、独立 SHA256 及 AI 修复代码与本地构建一致。官网与文档 Pages 部署成功。

Windows 实际服务端安装包解包复验通过：新 AI 代码与 Web 提问弹窗已入包，配置占位符、独立密钥、既有配置保留、全新隔离库迁移、管理员登录、API/Web 就绪及创建/删除对话接口均通过。客户端实际便携包复验首次、二次启动均为 71/71，确认 packaged=true，退出释放文件锁。初跑曾出现首次 70/71、二次 71/71；原脚本覆盖了首次明细，本次使用保留两次完整结果的验证副本复跑，同一包两次均全绿，单项问题未复现；所有断言保留。迁移和业务回归使用隔离 SQLite，未实测 MySQL；未运行真实安装器、远控系统命令或向真实班级发测试消息。

交付文件

• ClassHelper-1.4.5-x64-server-setup.exe
• ClassHelper-1.4.5-x64-client-setup.exe
• ClassHelper-1.4.5-x64-client-portable.exe
• classhelper-server-linux-x64-1.4.5.tar.gz
• classhelper-server-linux-x64-1.4.5.tar.gz.sha256
• SHA256SUMS-1.4.5.txt

ClassHelper v1.4.4

ClassHelper v1.4.4

2026-11-07 按用户要求保持 1.4.4，同版本更新服务端。Windows 与 Linux 服务端已按同一提交更新，Linux 正式包由 Ubuntu runner 构建成功。客户端两个安装包沿用原批次，本次未重新打包。

本次服务端与 Web 更新

• 助手改为 Agent 对话界面，实时显示回复、查询、推理进度计数、自动校正、预览和执行状态。
• 模型列表自动获取，支持选择推理强度；基础地址和完整聊天端点均可使用，修复重复路径造成的 404。
• 空白、截断及包装格式自动修正或重试，持续失败保留任务和进度，不伪报成功。
• 后台任务持久化；切换页面、关闭浏览器后，已提交任务及已确认执行继续运行，重新进入可恢复。附件须先完整上传并通过 SHA256 校验；尚未上传完成的本地文件需重新选择。
• 写入保留预览确认，后台通过白名单业务接口执行并逐步去重。权限、任课和资源状态变化后重新校验；数据库及服务器运维仍禁止由 AI 执行。

升级

备份数据库及课件目录，使用既有升级流程应用迁移。本次新增 AiTask（20261107210000_add_ai_tasks），并包含原批次 AiPlanStep 迁移。服务重启后的未知执行结果需核对，不自动重做。模型密钥不回传，任务输入、结果和进度加密保存。

验证与源码

AI 隔离 50/50、Web UI 80/80、E2E 262/262、授权矩阵 23 项通过。Web/服务端构建、Lint、类型和严格文档检查通过。Windows 配置初始化 5/5；实际新包解包验证独立密钥、原配置保留、新迁移、后台代码及 Web 产物通过。Node 22 曾在断言完成后的退出阶段原生崩溃，Node 24 LTS 复验通过并正常退出。迁移实测隔离 SQLite，未实测 MySQL；远控和安装均使用假执行。

服务端重建源码：cdb64c549939f22ba0f2ce9dd8ae716f27e88f25。保留原 v1.4.4 标签及客户端批次（原提交 0b35a58）；服务端重建不移动旧标签。

Linux 构建：Actions。构建已成功，跨组件 SHA256SUMS 已更新。全部六项资产的本地大小和 SHA256 与 GitHub 一致，Linux 独立摘要与总清单一致，压缩包完整读取及新迁移核验通过。

资产

• ClassHelper-1.4.4-x64-server-setup.exe
• classhelper-server-linux-x64-1.4.4.tar.gz 及独立 .sha256
• ClassHelper-1.4.4-x64-client-setup.exe（原批次）
• ClassHelper-1.4.4-x64-client-portable.exe（原批次）
• SHA256SUMS-1.4.4.txt

ClassHelper v1.4.3

ClassHelper 1.4.3

发布日期：2026-11-07。此版本修复任课授权、批量成绩和快照恢复问题，并减少重复查询与 Web 入口体积。Windows 包已通过验证；Linux 服务端由本版本 Tag 对应的 Linux CI 构建。

用户可感知变化

• 新建科目会建立任课关系，现仅管理员可新建；教师使用已有任课科目，避免通过课表维护范围给自己任课。
• 整班成绩录入在一个事务中校验和写入，任意一行无效或数据库写入失败时整批回滚。
• 数据库快照恢复失败时保留原库，避免先清空后半途失败。SQLite 已实测；MySQL 采用事务固定连接处理外键开关，本批未做 MySQL 实库集成。
• 同时标记通知已读时自动处理唯一冲突，不再因重复写入返回冲突。
• 减少默认权限组初始化、同科成绩授权与同班设备放学更新的重复查询。
• Web 只注册实际使用的 Element Plus 组件，入口 gzip 从 292.26KB 降为 197.19KB，保留原有主题与中文界面。
• PWA 仅缓存成功的 HTML 外壳，API/实时请求透传；只清理本应用旧缓存。
• 更新帮助、源码索引和代理提示词，补充 AI 助手帮助；优化后的任务入口可由零上下文代理开始执行。

升级注意

版本由 scripts/version.mjs 从 1.4.2 升至 1.4.3；本批没有 schema 或迁移变更，不需要重置数据库。
旧客户端/已有科目与离线格式保持兼容。旧 Web/PWA 尝试新建科目时，教师会收到 403 并提示联系管理员；这属于任课授权安全修正。
升级前按常规保留数据库和课件文件完整备份。没有执行真实安装、远控系统指令或向业务班级发送测试消息。

本次验证

验证	本次结果
lint、typecheck、check:icons、version:check	通过；类型检查按包串行，最终 lint 使用 768MB Node 堆限制
verify:audit	服务端10/10、PWA5/5、组件注册检查通过
verify:authz	23 项通过
verify:e2e	251/251
verify:v14	37/37
verify:lifecycle	31/31
verify:courseware	61/61
verify:clients-api / verify:client-migrations	29/29；旧库升级专项通过
更新下载/原生更新助手/服务端初始化	专项通过，均未运行真实安装器
verify:client-agent / verify:review-client	17/17、18/18
verify:web:isolated	64/64，隐藏窗口，无新增应用运行时错误
verify:desktop	连续两次70/70
verify:packaged --offline	实际便携包连续两次70/70，packaged=true，版本1.4.3，文件锁释放
实际服务端 NSIS 包副本	助手与源码一致、模板仅含密钥占位符、首次密钥独立、重复初始化保留配置
docs:check / pages:build / 本地链接	严格构建及站点拼装通过；本次本地链接目标97项无错误

Node22 曾出现原生内存错误，失败日志保留；Node24.22.1 与 pnpm11.8.0 的受控内存复验通过。
Node24 代理专项曾出现 FileHandle GC 告警，测试通过但句柄来源尚未定位，作为后续诊断项保留。
开发版第二次启动的课表同步检查曾失败，补充子指标后单独复验两次均通过；没有放宽断言。
本批没有声称完整视觉、真实安装、MySQL 实库或 Linux runner 已验收。

下载与校验

文件	字节	SHA256
ClassHelper-1.4.3-x64-client-setup.exe	103771618	72c203c235fc7423e466c06ef3a4ad6f51c1fe4e2ab392696f0fbd56a91fc74a
ClassHelper-1.4.3-x64-client-portable.exe	103426294	7d6e0ba66beef2cb75a69e83e1f800186a358fbe009dab3f18edecf21e20e419
ClassHelper-1.4.3-x64-server-setup.exe	67122066	ae1c0672a1f8fa390f80b34632752e97eeec91acffd3bf8ee0a881d03ea63b6d

完整摘要见附件 SHA256SUMS-1.4.3.txt。Linux 构建完成后会增加 Linux 包、独立 .sha256 并更新此清单。当前可用文件以附件为准。

ClassHelper v1.4.2

ClassHelper 1.4.2

本版修复客户端云端更新的下载、安装交接和失败恢复，整合上一版本之后的权限、课表编辑及学生管理改进。

更新与安装

• 修复服务端安装包缓存在隐藏目录时下载失败、文件失效时请求无法结束的问题。
• Windows 客户端改用独立原生更新助手。再次校验安装包 SHA256 和大小，确认助手就绪、复核策略后才退出旧进程；安装失败记录原因并尝试恢复客户端。
• 保留立即、放学后、空闲更新策略；本机关闭自动更新时不执行安装。新版心跳确认实际升级完成。
• 支持中文及空格路径、带 v 的目标版本号；便携版接收统一更新后转为安装版。
• Windows 服务端首次安装生成独立 JWT 密钥；安装包只携带占位符，覆盖升级保留原配置。

旧客户端如果无法启动安装器，需要先手动安装 1.4.2，以获得新的更新助手。 云端下发无法修复已安装旧版自身的安装交接代码。便携版转安装版后，请使用安装版入口。

管理和界面

• 重整岗位权限模板、能力范围与任课授权边界，补齐班级设备身份校验。
• 完善灵动岛常驻方案编辑器、常态与展开布局编辑，以及课表档案和时间表编辑。
• 完善学生生命周期管理、权限范围与学年升级流程。

验证

• 全仓 lint、typecheck、图标门禁和版本一致性检查通过。
• 隔离端到端 250/250、V1.4 专项 37/37、课件 61/61 通过。
• 真实云端升级使用独立测试应用、临时服务和班级，实际下载、静默安装并由新版心跳确认；覆盖安装版升级、便携版转安装版、中文空格路径和 v 前缀版本。测试副本使用本版更新代码构造旧版本号，不代表已发布旧版可以自动获得修复。
• 正式客户端便携包两次后台离线自检均为 70/70，确认 packaged=true 且退出后释放文件锁；Web 隔离回归 63/63，文档严格构建零警告、零错误。
• 正式服务端包解出副本，使用随包 Node 验证独立密钥、配置保留、空库迁移、管理员登录和 Web 静态页面。
• 下载路由、原生安装助手和安装配置初始化专项验证通过。全过程未使用 Computer Use。

交付文件

• Windows 客户端安装版：ClassHelper-1.4.2-x64-client-setup.exe
• Windows 客户端便携版：ClassHelper-1.4.2-x64-client-portable.exe
• Windows 服务端与 Web 管理端：ClassHelper-1.4.2-x64-server-setup.exe
• Linux x64 服务端：classhelper-server-linux-x64-1.4.2.tar.gz
• Linux 独立摘要：classhelper-server-linux-x64-1.4.2.tar.gz.sha256
• 完整校验清单：SHA256SUMS-1.4.2.txt（使用 Release 上传文件名）

Linux 正式包由 GitHub Actions 的 Linux runner 构建。

ClassHelper v1.4.1

ClassHelper v1.4.1

本批 Windows 安装包基于 2026-10-18 当前源码构建，版本为 1.4.1。

重点更新

• 课表档案工作区：课程表、时间表、科目、群组与预定、整周预览和文件预览合并在一个页面；参照 CsesWebEditor 的资源列表、设置卡片和快速选科布局重写。支持拖动课时换课、拖动时间点调整顺序、快速时长、完整档案导入导出与旧 /schedules 地址自动跳转。
• 课程提醒修复：课前、上课、课间和下课提醒改为按精确时间判定；修复通知收回延迟把提醒窗口一起隐藏、遮罩动画在合成暂停时停住的问题。固定岛和自定义常驻岛均已验证提醒条与遮罩的实际尺寸和可见性。
• 课件文件夹与归档：教师可在 Web 管理端新建多层分类文件夹并调整课件分类；文件夹按教师隔离。服务端和客户端统一按 Teachers/教师/年/月/日/上传时间/文件名 归档，同秒同名文件不覆盖。班级客户端新增「本机归档」，离线时可按教师与日期目录浏览已接收课件。
• 客户端更新过程：Web「客户端」页面显示下载字节与百分比、校验中、已下载等待安装、正在更新将短暂离线、已完成更新的实际版本，以及失败原因。客户端安装前先把状态送达服务端，新版上线后的心跳确认完成；仅离线不会被误判为成功。
• 界面修复：折叠侧栏的分组图标不再被裁切；上传文件改为与管理端一致的按钮和文件名展示；筛选区、工具栏和设置卡片在窄屏下自动换行，避免控件挤压。

升级须知

• 升级服务端前请备份数据库。本版新增 CoursewareFolder 表，并为 Courseware 增加归档路径字段、为 ClientDevice 增加更新进度字段；SQLite 安装包会在首次启动时自动应用迁移。
• 数据库 JSON 快照包含课件分类目录，但不包含二进制文件；完整备份仍须同时备份 data/courseware（自定义 COURSEWARE_DIR 时备份对应目录）。
• 旧课件按上传教师和历史时间重新生成展示归档路径；实际磁盘上的旧文件位置保持不变，客户端下载时按新目录存放。
• 客户端更新从本版开始完整上报下载、安装和完成状态；教室机需运行 1.4.1 及以上客户端才能看到全过程。
• Web 管理端旧地址 /schedules 会自动进入「教学事务 → 课表档案」，不需要另行配置。

本批构建与验收（2026-10-18）

项目	本批结果
版本落点	12 处均为 1.4.1
静态门禁	lint、typecheck、图标注册表、文档严格构建全部通过
端到端隔离验收	243/243 项通过
v1.4 课表/权限专项	37/37 项通过
课件/文件夹/更新进度专项	61/61 项通过
客户端代理回归	16/16 项通过
桌面客户端快速检查	64/64 项通过，含两种岛的课前/上下课提醒
Web 隔离 UI 回归	47/47 项通过，含折叠侧栏、课件归档、快速时长与移动端布局
Windows 打包	dist:all 成功：客户端安装版、便携版及服务端安装版
打包便携版离线复验	首启 64/64、二次启动 64/64；packaged=true，文件锁已释放

Linux x64 服务端包已由发布工作流在 Linux runner 构建并上传；本地已同步 tar.gz、独立 .sha256 与合并后的最终 SHA256 清单。

交付物

本地文件	GitHub Release 上传名	说明
ClassHelper-1.4.1-x64-setup.exe	ClassHelper-1.4.1-x64-client-setup.exe	Windows x64 桌面客户端安装包
ClassHelper-1.4.1-x64-portable.exe	ClassHelper-1.4.1-x64-client-portable.exe	Windows x64 客户端便携单文件
ClassHelper 服务端-1.4.1-x64-setup.exe	ClassHelper-1.4.1-x64-server-setup.exe	Windows x64 服务端安装包，内置 Node 运行时
classhelper-server-linux-x64-1.4.1.tar.gz	同名	Linux x64 服务端包，由发布工作流构建
SHA256SUMS-1.4.1.txt	同名	Windows 与 Linux 项目哈希，Linux 行已由发布工作流合并

ClassIsland 联动插件已退役，本版不再发布该插件。

ClassHelper v1.4.0

ClassHelper v1.4.0

本批 Windows 安装包基于 2026-10-18 当前源码构建，版本保持 1.4.0。

重点更新

• 课表与作息：使用关系化日课表、显式时间点和统一启用解析；支持周次轮换、群组、预定与临时课表，并兼容离线课表导入。
• 灵动岛：提供本机自定义组件编辑与预览，分开配置常态和展开内容；课程提醒展示进度，经典岛与自定义常驻模式沿用各自的消息交互规则。
• 课件共享：教师可在 Web 管理端上传最大 512 MB 的课件，按本人任课班级控制可见范围并推送；班级客户端支持浏览、下载、离线补收和逐设备回执。灵动岛显示传输进度，下载完成后校验 SHA256；客户端不会自动运行课件。
• 权限与成绩隐私：按岗位范围授权，并继续校验科目任课关系；关闭个人成绩查询后不下发个人明细、排名或实时个人成绩。
• 学年升级与设备管理：支持升级前快照、幂等补跑、班级归档及客户端连接/更新状态维护。

升级须知

• 升级服务端前请备份数据库。关系化课表迁移会将旧课表映射到新模型；旧 Schedule 记录保留作迁移审计来源。旧数据中同班、同日、同周且起止时间完全相同的冲突记录，仅最小 ID 进入新课表；原数据没有记录的群组、临时层和时间点名称无法恢复。
• 本版新增课件数据迁移。数据库 JSON 快照包含课件元数据、可见范围、推送与回执，但不包含二进制文件；完整备份还须备份服务端 data/courseware，自定义 COURSEWARE_DIR 时备份对应目录。
• 使用自定义反向代理时，为 /api/courseware/ 允许最大 512 MB 请求并设置足够的读写超时；仓库 Nginx 样例使用 1800 秒超时。
• 自定义灵动岛方案保存在客户端本机 config.json，不需要服务端配置或同步。

本批构建与验收（2026-10-18）

项目	本批结果
版本落点	12 处均为 1.4.0
Windows 打包	dist:all 成功：客户端安装版、便携版及服务端安装版
课件隔离专项	46/46 项通过
v1.4 课表/权限专项	35/35 项通过
Web 隔离回归	46/46 项通过，包含课件上传/删除和移动端布局
打包便携版离线复验	首启 63/63、二次启动 63/63；packaged=true，文件锁已释放
客户端凭据门禁	77 个产物文件中未发现种子凭据

Linux x64 服务端包由发布工作流在 Linux runner 构建，本批本地 Windows 打包未生成或同步 Linux 资产。

交付物

本地文件	GitHub Release 上传名	说明
ClassHelper-1.4.0-x64-setup.exe	ClassHelper-1.4.0-x64-client-setup.exe	Windows x64 桌面客户端安装包
ClassHelper-1.4.0-x64-portable.exe	ClassHelper-1.4.0-x64-client-portable.exe	Windows x64 客户端便携单文件
ClassHelper 服务端-1.4.0-x64-setup.exe	ClassHelper-1.4.0-x64-server-setup.exe	Windows x64 服务端安装包，内置 Node 运行时
classhelper-server-linux-x64-1.4.0.tar.gz	同名	Linux x64 服务端包，由发布工作流构建
SHA256SUMS-1.4.0.txt	同名	Windows 项目哈希；Linux 行待发布工作流完成后补齐

ClassIsland 联动插件已退役，本版不再发布该插件。

ClassHelper v1.3.3（联动退役与稳定性修复）

ClassHelper v1.3.3

本版退役 ClassIsland 在线联动，统一权限组与客户端维护链路，并修复桌面端缓存隔离、启动恢复和多项班级业务问题。离线课表 JSON 导入继续保留。

重点更新

• 退役 ClassIsland 联动：移除插件、设备令牌、联动提醒通道和镜像接口，相关页面及接口同步下线；原有课表数据保留并转为手工管理。
• 权限行为统一：角色默认权限组通过角色标识关联；Web 菜单和服务端鉴权对齐，补齐名单只读权限，清理没有独立服务端能力的权限项。
• 提升客户端稳定性与安全性：缓存按服务端、班级和登录用户隔离；修正窗口恢复、渲染失败和更新文件校验流程；取消或更换更新目标后清理旧安装包。日常后台快速检查不创建可见窗口。
• 修复业务细节：修正通知日期回填、周次与课表校验、成绩考试口径、跨班实时更新、列表竞态和错误提示等问题，并加强学生名单、附件地址和助手上下文校验。

⚠️ 升级须知

• 升级服务端前请按常规备份数据库。本版迁移会删除已退役联动专用的 IntegrationDevice、ClassIslandPush 数据表及班级提醒通道字段；原先来源为 ClassIsland 的课表记录会保留，并改为手工课表。
• 服务端新增客户端更新状态字段与权限组角色关联字段，升级时按部署流程应用数据库迁移。
• ClassIsland 插件不再随本版发布，也不再与 ClassHelper 服务端通信。需要导入课表时，仍可使用离线 JSON 导入。

验收

项目	结果
全仓类型检查、ESLint、图标检查、文档构建	通过
隔离测试库后端端到端	243/243
审查接口 / 客户端维护接口	31/31 / 28/28
无窗口逻辑 / 远控与更新代理回归	18/18 / 15/15
Web 管理端 / 客户端联网冒烟	37/37 / 10/10
Windows 客户端与服务端打包	通过
打包客户端后台快速复验	9/9；二次启动 9/9，packaged=true

完整视觉验收未运行；本轮打包复验未启用联网用例。

交付物

产物	说明
ClassHelper-1.3.3-x64-client-setup.exe	Windows x64 桌面客户端安装包
ClassHelper-1.3.3-x64-client-portable.exe	Windows x64 客户端便携单文件
ClassHelper-1.3.3-x64-server-setup.exe	Windows x64 服务端安装包，内置 Node 运行时
classhelper-server-linux-x64-1.3.3.tar.gz	Linux x64 服务端包，由 GitHub Actions 构建并上传
SHA256SUMS-1.3.3.txt	跨组件校验清单，Linux 行由发布工作流补齐

升级步骤与权限矩阵见 README 和完整参考。

ClassHelper v1.3.2（远控指令：不再谎报成功 + 「上次指令」可见）

ClassHelper v1.3.2

这一版修 1.3.1 之后报上来的「下发锁屏等等指令不生效」。

先把结论说在前面：服务端的下发链路本身没有问题（用一台模拟客户端把「下发 → 心跳带回 →
列表可见 → 回执 → 清除」整条跑通过）。真正的问题是两处 —— 一处会让"执行失败"谎报成功，
一处让"点了没反应"在界面上完全看不出来。

⚠️ 升级须知
本版没有数据库迁移，装上升级即可。
但服务端与教室机器的客户端都要升：客户端那处修的是"执行失败被吞掉"，服务端那处新增了
「上次指令」的返回字段。只升一边会看不到新加的那一列。

---

一、客户端：执行失败会谎报成功

spawn 找不到可执行文件（或没权限）时不抛异常，而是在下一个 tick 发一个异步 error 事件 ——
原先只包了 try/catch，抓不到它，于是代码一路走到 return { ok: true }，
回执里写着「已下达系统命令」，Web 端看起来一切正常，机器却纹丝不动。

现在会等 200ms 的窗口确认没有立刻报错；真失败就如实回执，Web 端能看到原因。

二、Web 端：点了没生效，界面上什么都不说

一条命令被取消或过期之后就从"待执行"里消失了，页面留白 —— 而最常见的两种"没反应"恰恰是：

情况	为什么会这样
机器上没人确认	客户端弹的是**默认选中「取消」**的确认框，60 秒没人点就自动取消（这是"两端各确认一次"的设计：真正要被关掉的机器上必须当场有人知道）
下达时机器离线	命令有效期 10 分钟，机器没上线就作废（避免离线几天后一开机被昨天的命令关掉）

现在「客户端」页的设备表多了一列 「上次指令」：

锁屏 · 已执行：已下达系统命令
锁屏 · 本机用户取消（或 60 秒未确认）
锁屏 · 已过期 —— 下达时机器不在线（命令有效期 10 分钟）

下发成功的提示也补上了「60 秒内没人点确认就按取消处理」。

三、如果是"教室里那台机器"没反应，先查这两个

1. 那台机器的客户端版本：处理远控命令的能力是 1.3.0 才有的，更旧的客户端连心跳都不发 ——
   在「客户端」页里那台机器会显示成从未心跳 / 离线。把教室机器升到 1.3.0 以上即可；
2. 那台机器上有没有人点「确认执行」：见上面的「上次指令」列。

---

验收

门禁	结果
lint / typecheck / check:icons / docs:check	全绿
后端端到端	247/247
ClassIsland 联动链路	44/44
插件静态契约	76/76
Web 管理端真实点击	34/34
客户端冒烟	90/90

远控命令这条链路另外用一台模拟客户端单独跑过一遍（登记 → 下发 → 心跳带回 → 列表可见 →
回执 → 清除），并确认新增的「上次指令」在待执行与已回执两种状态下都显示正确。

产物

产物	说明
ClassHelper-1.3.2-x64-client-setup.exe	桌面客户端安装包（Windows x64）
ClassHelper-1.3.2-x64-client-portable.exe	桌面客户端免安装单文件
ClassHelper-1.3.2-x64-server-setup.exe	服务端安装包（Windows x64，内置 Node 运行时）
classhelper-server-linux-x64-1.3.2.tar.gz	服务端 Linux 包（由 GitHub Actions 在 ubuntu-22.04 上构建）
ClassHelper.ClassIslandPlugin.cipx	ClassIsland 联动插件
SHA256SUMS-1.3.2.txt	跨组件哈希清单（人读；classhelper upgrade 用的是同名 .sha256）

升级步骤与权限矩阵见仓库
README 与
完整参考。

ClassHelper v1.3.1（课表同步改为按需 · 客户端页合并 · 成绩排名）

ClassHelper v1.3.1

这一版修掉一个每 15 秒发生一次的线上问题，并把服务端两个割裂的页面合成一页。

原先教室的课表同步是"自动来回"：插件每 15 秒上报一次、每次都带全量课表、上报完还顺手把课表
镜像回 ClassIsland。结果是教室的课表每 15 秒被重写一次、服务端也每 15 秒 merge + 清理一次幽灵行，
老师看到的就是**「课表被反复删改」**。现在两个方向都只在你点按钮时发生一次。

⚠️ 升级须知
服务端升级后会自动应用 2 个数据库迁移（成绩的「考试口径」表 Exam、
联动设备的「下发课表」待办 requestMirrorSchedule）。升级前请先备份。
ClassIsland 插件要换成 1.3.1 的 .cipx（两个本机的课表同步开关已删除，改用服务端下发的待办）。
换完之后教室不再自动镜像课表 —— 要在「客户端」页点「下发课表」才会写进教室。

---

一、课表同步：从"一直同步"改成"两个按钮"

动作	在哪点	做什么
下发课表	「客户端」页的卡片 / 详情	把本班课表写进教室，并停用同一天同一单双周相位下冲突的旧课表
获取课表	同上的「获取课表」	把教室机器里启用的课表合并进本班课表

• 「强制替换」只停用不删除：冲突的课表内容原样留在 ClassIsland 档案里，随时能重新启用；
• 插件侧那两个本机开关（「自动上报课表」「镜像回 ClassIsland」）已删除：定时上报现在只报
  运行状态（当前上什么课、ClassIsland 版本），课表只在服务端显式请求时才走一次；
• 两个方向都是一次性待办：Web 端点按钮置位，插件在下一次心跳（约 1 分钟内）做一次，做完由服务端清标记。

二、「客户端」页：合并原来的两个菜单

原先「ClassIsland 联动」与「客户端设备」是两页，讲的却是同一个教室的两半（插件管大屏、桌面端管灵动岛）——
给一个班做一件事得先想清楚该进哪一页，批量操作更是无从下手。现在合成一页：

• 一个班一张卡片：大屏与灵动岛两条链路的状态放在一起（在线、版本、当前课程）；
• 批量：勾几个班，一次下发课表 / 一次下发更新；
• 点卡片进详情：签发与重置令牌、启用 / 停用、下发 / 获取课表、远控（关机 / 重启 / 注销 / 锁屏）、移除记录；
• 下发提醒（教室大屏全屏弹出）也搬到了这一页，老师照旧用得到。

入口权限用 classisland:notify（默认管理员 + 教师），页内的设备管理 / 远控 / 下发更新再各自要求
对应的权限键 —— 与后端的三个接口一一对应。

三、成绩：单科排名与总分排名

• 每次导入 / 录入成绩时，可以顺手定下这次考试的「考试口径」：
  「所有科目相加，排总分榜」或「只排单科，不合总分」（按「班级 + 考试名」记住）；
• 语数外 150 分、音体美 100 分不是一个量纲，所以合不合总分由学校决定，程序不替它默认；
• 排名口径写死在服务端：同一学生同一科目只取最高分（补录 / 重考会产生多行，不去重等于"总分多一科"）、
  并列同名次（1、2、2、4）；
• 教室机器的「成绩」页可以直接看到全班成绩与排名，不用再按学号一个个查；
• 「能不能看」由班级上的开关控制，而这个开关现在只有教师 / 管理员能在 Web 端改
  （原先教室机器自己也能改，等于把"学校说不给看"变成一台机器说了算）。

四、学期开始日期可以在页面上改了

「开学日期填错了」原先只能改 .env 再重启。现在管理员在「学期周次」页直接填写并保存，
当前周次立刻按新日期重算，随时可以纠正 —— 班级仍然可以有自己的开学日期（优先级更高）。

五、大模型助手：补上上课时段的警告

用助手发紧急通知时，原先只有服务端的二次确认，没有手动发布页那个「3 秒倒计时」的全屏警告。
现在两个入口共用同一条上课状态判据 —— 上课时用助手发紧急通知，同样会先弹全屏警告。

六、客户端

• 去掉「自动更新」开关：教室机器是统一投放的终端，版本一致性由管理员在服务端决定；
• 去掉「关怀模式」：那是给 Web 管理端用的，客户端是投在教室大屏上的固定界面；
• 成绩查询开关改成只读：显示服务端下发的状态，本机不再能自己开；
• 修掉一个视觉问题：选中「设置」里的二级菜单后收起分组，高亮块会留在原地不消失。

---

验收

门禁	结果
lint / typecheck / check:icons / docs:check	全绿
后端端到端	247/247
ClassIsland 联动链路	44/44
插件静态契约	76/76
Web 管理端真实点击	34/34（含新增的「客户端」页用例）
客户端冒烟	90/90

数据库方面：2 个迁移在真实库上跑通，Exam 与 requestMirrorSchedule 都已就位；
端到端验收跑完不留残留数据。

运行期未实测的部分：插件改动已通过编译与静态契约校验，并在本机装了 ClassIsland 2.1.0.1 的
机器上确认「插件加载、订阅、运行无异常」，但**「下发课表强制替换」的完整交互需要在你的教室机器上实测**
（本机验证时服务端指向的是内网地址，拿不到一台在线的真实教室设备）。

产物

产物	说明
ClassHelper-1.3.1-x64-client-setup.exe	桌面客户端安装包（Windows x64）
ClassHelper-1.3.1-x64-client-portable.exe	桌面客户端免安装单文件
ClassHelper-1.3.1-x64-server-setup.exe	服务端安装包（Windows x64，内置 Node 运行时）
classhelper-server-linux-x64-1.3.1.tar.gz	服务端 Linux 包（由 GitHub Actions 在 ubuntu-22.04 上构建）
ClassHelper.ClassIslandPlugin.cipx	ClassIsland 联动插件（这一版要换）
SHA256SUMS-1.3.1.txt	跨组件哈希清单（人读；classhelper upgrade 用的是同名 .sha256）

升级步骤、演示账号与权限矩阵见仓库
README 与
完整参考。

ClassHelper v1.3.0（权限组 · 客户端设备统一更新与远控 · 大模型助手）

ClassHelper v1.3.0

这一版做两件事：把「谁能做什么」从角色名改成权限键，并给每台教室机器一个身份。

于是「给某位老师单独开一个入口」不用再改代码，「这台教室机上装的是哪个版本」也终于看得见。
另外新增了一个大模型助手：一句话描述要做的事，它只负责解析成待确认的动作，落库仍走既有入口。

⚠️ 升级须知
服务端升级后会自动应用 1 个数据库迁移（权限组 3 表 / 全局设置 / 客户端设备·命令·安装包 /
大模型审计 / Notification.assignDate / User.careMode），历史通知按本地日期回填，不会留空。
升级前请先备份。
没有分组的账号按角色默认模板生效，行为与 1.2.0 一致 —— 这一版不会因为升级把谁关在门外。
教室机器要看到「客户端设备」页里的版本与远控，客户端需升到 1.3.0。

---

一、权限组：角色只是默认模板

原先「谁能做什么」写在路由的 requireRole('ADMIN', 'TEACHER') 上，想给某位老师单独放行一个入口
只能改代码。现在改成读权限键：

• 权限目录共 39 个键（键 / 中文名 / 分类 / 默认角色），三端共用同一份，不存在「Web 端说有、客户端说没有」；
• 管理员可以建权限组、勾权限、把账号分配进去（一个账号可以属多个组）；
• 没有分组的账号按角色默认模板生效；一旦分组，生效集合就只由组的并集决定 ——
  所以权限组既能授权，也能收权；
• 生效权限每次请求实时算，改完立刻生效，不需要重启服务端；
• 管理员账号始终是全集，且「权限组管理」「系统设置」两项不可被剥夺（免得把自己锁在门外）；
• 班级端（CLASS_DEVICE）不受分组影响，权限固定为空集。

有一条边界是故意保留的：班级维度的科目规则（「这一科的作业与成绩只有这一科的老师能改」）
不可被权限组覆盖，否则「班主任布置别人科目作业」的老问题会从新路径长回来。

二、客户端设备：教室机器有了身份

• 每台客户端首次启动生成一个 deviceKey（UUID），服务端按它登记一台设备；
  这个键不接受外部改写，退出登录也会保留（改了就等于换了一台机器）；
• 心跳 30 秒一次，在线窗口 90 秒；没有登录就不上报（静默跳过），收到 401/403 退避 5 分钟；
• Web 端新增「客户端设备」页：班级 / 设备名 / 版本 / 平台 / 是否自动更新 / 目标版本 / 最后心跳 / 在线离线；
• 上报走的是「数据库记状态 + 客户端定时拉」，服务端不推 —— 教室机断网、休眠、重启之后
  一上线就能把状态与待办补上，不需要维护新的长连接。

三、统一更新与远控

一键推送更新：Web 端指定目标版本 → 客户端下一次心跳拿到 → 下载 → 校验 sha256 → 空闲时安装。

• 安装包由服务端下载并缓存到 data/client-releases/<版本>/ ——
  教室机常常根本没有外网，浏览器侧也受 CSP 限制不能直连 GitHub；
• 自动安装三条护栏：① 没有 sha256 就拒收；② 必须等到「非上课 且 主窗口隐藏满 5 分钟」；
  ③ 冒烟模式永不安装；
• 自动更新默认开启，可以按机器关掉；关掉之后客户端的设置页仍会显示服务端下发的目标版本，由人工处理。

远控命令：关机 / 重启 / 注销 / 锁屏。

• 命令有效期 10 分钟（避免机器离线几天之后一开机就被昨天的命令关掉）；
• 客户端弹的是**默认选中「取消」**的对话框，60 秒未确认按取消处理；
• 执行之后必须回执，重复回执幂等；同一台机器、同一条命令只弹一次；
• 权限键是 remote:control（默认只有管理员有）。

四、大模型助手：只解析，不落库

Web 端新增「助手」页：直接说一句「明天放学前交数学卷子」，解析成待确认的动作卡片，你点确认才落库。

• 支持的动作：布置作业 / 发通知 / 叫学生来 / 看不懂（看不懂时会原样说明原因，不会瞎猜）；
• 落库走的是既有的那几个接口 —— 于是权限断言、上课时段紧急通知保护、ClassIsland 推送
  全部自动复用，系统里不存在第二套写入路径；
• 模型给的参数会用与手动入口同一份 zod 再校验一次（模型输出不可信）；
• 可接任意 OpenAI 兼容接口（baseUrl + model + apiKey）；Key 用 AES-256-GCM 加密后存库，
  只进不出 —— 接口只回答「有没有配」和尾 4 位；
• 内置 mock provider：离线确定性解析，自动化验收一律用它（不联网）；
• 每次解析写一条审计记录，其中不含密钥。

五、系统：开发者模式 · 运行诊断 · 开机自启

• 开发者模式（system:manage）：开启后 500 错误的响应里附带 error.stack；
• 运行诊断：版本 / 运行时 / 数据库 / 目录 / 迁移状态一眼看完，绝不回传任何密钥；
• 开机自启动运行期可改：Windows 写 HKCU\...\Run，Linux 走 systemctl enable/disable ——
  装完之后不用回去重跑安装器；
• 非安装形态（开发机 / 免安装目录 / 容器）返回 supported:false 并说明原因，
  不会往开发机的注册表里写自启项；
• 安装器只负责默认值：Windows 是组件页上一个默认勾选的独立 Section，Linux 在 install.sh 里。

六、通知与作业：按天归档 + 批量发布

• 通知与作业同口径按「所属日期」归档（本地日期，不带时区），并新增按天、按发布人归档的接口；
• 新增批量发布：勾多个班一次发完，单个班失败不影响整批，逐班回结果；
• 作业的科目名跨班按名匹配已有课程，匹配不到就整班记失败，绝不自动建课 ——
  自动建课会把创建者写成任课老师，等于悄悄改了任教关系。

七、客户端与界面

• 崩溃自愈：渲染进程挂掉、或超过 10 秒无响应，先静默重建主窗口（10 分钟内最多 3 次）；
  未捕获异常只在「没在上课、没人看着」的时机才重启进程；
• 离线补弹：重新上线时把离线期间没读到的通知补推给灵动岛，取最近 5 条按时间升序，同一次离线只弹一次；
• 关怀模式（Web 端）：字号与控件整体放大，几何令牌一个都不动；
• 侧栏回缩：Web 端侧栏折叠改成纯 CSS 收拢（不再借用 Element Plus 的 :collapse 重建 DOM），
  折叠过程里不再有结构切换。

---

验收

门禁	结果
lint / typecheck / check:icons / docs:check	全绿
verify:e2e / verify:classisland / verify:classisland-plugin / verify:web / verify:desktop	本版发布时未重跑

运行时验收这一轮没有重跑（只跑了构建前的静态门禁）。要补齐按仓库 AGENTS.md §8 的命令序列跑一遍。

产物

产物	说明
ClassHelper-1.3.0-x64-client-setup.exe	桌面客户端安装包（Windows x64）
ClassHelper-1.3.0-x64-client-portable.exe	桌面客户端免安装单文件
ClassHelper-1.3.0-x64-server-setup.exe	服务端安装包（Windows x64，内置 Node 运行时）
classhelper-server-linux-x64-1.3.0.tar.gz	服务端 Linux 包（由 GitHub Actions 在 ubuntu-22.04 上构建）
ClassHelper.ClassIslandPlugin.cipx	ClassIsland 联动插件
SHA256SUMS-1.3.0.txt	跨组件哈希清单（人读；classhelper upgrade 用的是同名 .sha256）

跨大版本升级的完整步骤、演示账号与权限矩阵见仓库
README 与
完整参考。