Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(release): 1.3.3 发布并退役旧联动

Browse Source
This commit is contained in:
LoveChengke committed 2026-10-17 03:06:46 +08:00
1 parent b7cdc7c9ea
commit c0ebf88138
184 files changed
+5450 -11705
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/get-started/classisland.md
-120
View File
@@ -1,120 +0,0 @@
---
title: 接入 ClassIsland
description: 把教室里的 ClassIsland 接上 ClassHelper：下课表上报、大屏提醒下发、课表镜像三个方向。
---
# 接入 ClassIsland
课堂里真正"知道现在第几节、在上什么课"的是 [ClassIsland](https://classisland.tech)。
它跟 ClassHelper管的事情不重叠，接起来之后两边各拿各的好处：
| 方向 | 做什么 | 老师在哪看 |
| ------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- |
| ClassIsland → ClassHelper | 上报**课表 + 节次时间 + 上课状态**（现在上什么 / 下一节 / 本节起止），写进本班课表 | Web 端「ClassIsland 联动」的实时状态卡片 |
| ClassHelper → ClassIsland | 老师发一条**提醒** → 落库 → 教室插件取回 → ClassIsland 上**全屏弹出**（可语音朗读） | Web 端「ClassIsland 联动 → 下发提醒」 |
| （可选）班级 → ClassIsland 镜像 | 把小助手这边排好的课表**镜像**回 ClassIsland，新建一份档案，不动老师原有的课表 | 同一页的「开镜像」开关 |
> 没接 ClassIsland 也能用 ClassHelper，只是教室里少一个大屏播报的出口。**这一步是可选的。**
## 前置：ClassIsland 装好了
本插件按 ClassIsland 插件 API 2.0 编写，ClassIsland 2.0.x 与 2.1.0.x 都能加载。
先确认教室机器上 ClassIsland 本身能正常显示课表。
## 第一步：在 Web 端签发设备令牌
**ClassIsland 联动**页（管理员 / 本班班主任）→「接入新设备」→ 选班级 → 生成令牌。
令牌形如 `chci_xxxxxxxx…`，**明文只显示这一次**：服务端只存它的 sha256 与一个前缀提示
（`chci_80fa1c…`），用来在设备列表里人眼区分。丢了就重置一个。
## 第二步：在教室机器上装插件并填令牌
### 装插件
从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取
`ClassHelper.ClassIslandPlugin.cipx`：
- **推荐**：在 ClassIsland 里直接安装这个 `.cipx`（插件页有「从文件安装」）。
- 或者手工解压：把包里的 `ClassHelper.ClassIslandPlugin/` 目录整个丢进
`<ClassIsland 数据目录>\Plugins\`，然后重启 ClassIsland。
> **ClassIsland 运行时会锁住 DLL**。要覆盖升级插件，必须先完全退出 ClassIsland 再覆盖，
> 否则写入会被拒。插件配置在 `Config\Plugins\<插件 id>\Settings.json`，
> 里面存着服务器地址与设备令牌 —— **升级时别覆盖这个文件**。
> 另外改配置要在 ClassIsland 退出时改，运行中改会被内存里的副本回写覆盖。
### 填令牌
ClassIsland 的**设置 → ClassHelper 联动**里填：
| 设置项 | 说明 |
| ---------------------------- | --------------------------------------------------------------- |
| 后端地址 | `http://<服务器IP>:4000` |
| 设备令牌 | 上一步生成的 `chci_…` |
| 上报课表到小助手 | 打开后才会把 ClassIsland 的课表同步过来 |
| 接收小助手提醒 | 关掉就收不到老师发的提醒 |
| 提醒轮询间隔 | 默认 10 秒（可调到 5 秒）。上报本身就是心跳，轮询只是顺带取提醒 |
| 把班级课表镜像回 ClassIsland | 见下面「镜像」一节 |
填完点**「立即上报」**。
## 第三步：验证
回到 Web 端的「ClassIsland 联动」页，应该出现设备卡片和「在线」标记，实时状态卡上会显示这台机器
现在上什么课。到这一步链路就通了。
如果一直离线：先看插件的日志，再看服务端能不能从教室机器访问到（**别让系统代理拦住内网地址** ——
插件对本地 / 内网做了强制直连，但填错地址一样连不上）。
## 提醒弹在哪个端：由教室客户端自己选
教室机器的**客户端**「设置 → 提醒」里选，选择会同步到班级记录：
| 选择 | ClassHelper 客户端 | ClassIsland |
| ----------------------------------------- | ------------------------------ | ----------- |
| `ClassHelper 与 ClassIsland 都弹`（默认） | 弹窗 + 灵动岛 | 全屏提醒 |
| `只在 ClassHelper 客户端弹` | 弹窗 + 灵动岛 | 不推送 |
| `只在 ClassIsland 上弹` | 只进通知中心（不弹窗、不上岛） | 全屏提醒 |
规则只有一条，**任何入口都遵守**：通知发布页、叫人、联动页的「下发提醒」三个入口共用同一份推送实现，
不存在"某个页面发的通知不联动"。
## 两个方向各需要哪些开关
| 要同步的内容 | 需要打开 |
| -------------------------------- | ------------------------------------------------------------------------------- |
| 服务端 → ClassIsland（镜像课表） | ① 插件设置「把班级课表镜像回 ClassIsland」+ ② Web 端该设备的「镜像课表」 |
| ClassIsland → 服务端（上报课表） | 插件设置「上报课表到 ClassHelper」 |
| 提醒下发 | ① 教室客户端的「通知显示位置」不是"只在 ClassHelper" + ② 插件「接收小助手提醒」 |
## 上课时段：两边同一套规则
老师在**上课时段**发通知时，教室里的两个端遵守同一条规则，否则会出现"学生在客户端看不到、
却在 ClassIsland 上被打断"的怪事：
| 提醒类型 | 上课时段 | 下课 / 放学 |
| ------------------------------------------------------ | ---------------------------- | ----------- |
| 通知类（`kind=notification`：通知发布页 / 联动页下发） | **暂存不弹**（两边都先收着） | 自动补弹 |
| 主动通知：**紧急提醒**、**叫人**（`kind=call`） | **立刻弹** | 立刻弹 |
ClassIsland 侧的暂存由插件实现：它订阅课程服务，下课后把暂存的提醒补弹出来；未弹出前不回执，
所以服务端会一直保留着待提醒，教室机器断网也不丢。
## 上报课表是"双向对齐"的
插件每次全量上报时，服务端只清理**「来源是 ClassIsland 且这次没再上报」**的课表行。于是：
- 老师在 ClassIsland 里删掉 / 挪动一节 → 小助手这边跟着同步；
- 老师在小助手这边手排的课 → 一律不删。
## 镜像：把小助手的课表写回 ClassIsland
开启后，插件会新建一份名为 `ClassHelper-<班级名>` 的档案课表，**不动老师原有的课表**。
镜像时会连节次时间一起带过去，并且**每两节之间补一段课间、最后一节之后不补**（放学）。
这一步不做的话，ClassIsland 的课表会整体错位 —— 表现为"看着有内容、每节课都对不上"。
细节与实现见[ClassIsland 插件](../dev/classisland-plugin.md)。
下一步：[发布第一条内容](first-content.md)。
docs/get-started/client.md
+4 -6
View File
@@ -12,8 +12,8 @@ description: 在教室机器上安装 ClassHelper桌面客户端，用班级码
从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取：
| 产物 | 用途 |
| ------------------------------------ | ------------------------------------------ |
| 产物 | 用途 |
| ------------------------------------- | ------------------------------------------ |
| `ClassHelper-<版本>-x64-setup.exe` | 安装包（约 98 MB），装到本机并建快捷方式 |
| `ClassHelper-<版本>-x64-portable.exe` | 单文件便携版，双击即用，适合不改动机房机器 |
@@ -71,8 +71,8 @@ pnpm dist:win # 安装包 + 便携版（两个都是成品，没有中间的
2. **调灵动岛** —— 设置 → 灵动岛：高度、宽度、字号、主题色、停靠位置、视觉风格。
讲台机器上通常把字号调大一点、位置放到顶部居中。
触摸屏（希沃白板等）走的是另一套命中逻辑，客户端会自动识别，不用手动开。
3. **选提醒弹在哪端** —— 设置 → 提醒：`ClassHelper 与 ClassIsland 都弹` / 只在客户端 / 只在 ClassIsland。
这个选择会同步到班级记录，服务端据此决定要不要推 ClassIsland。
3. **查看提醒规则** —— 设置 → 提醒：普通通知下课显示，紧急提醒立即显示。
这个选择会同步到班级记录，服务端据此决定要不要广播到客户端。
## 6. 确认实时链路是通的
@@ -83,5 +83,3 @@ pnpm dist:win # 安装包 + 便携版（两个都是成品，没有中间的
- 服务器与教室机器之间能互相 ping 通吗？防火墙放行 4000 了吗？
排查清单见[常见问题](../faq.md)。
下一步（可选）：[接入 ClassIsland](classisland.md)。
docs/get-started/first-content.md
+2 -20
View File
@@ -11,7 +11,7 @@ description: 发通知、布置作业、叫人、录成绩——把 ClassHelper
**通知发布** → 选班级 → 填标题和内容 → 选优先级 → 发布。
| 优先级 | ClassHelper 班级端表现 |
| 优先级 | ClassHelper 班级端表现 |
| ------ | -------------------------------------------------------------------------- |
| 普通 | 课间弹胶囊，点击展开；**上课时段只进队列**，下课自动补弹 |
| 重要 | 同上，卡片上带优先级标签 |
@@ -39,7 +39,7 @@ ClassHelper 班级端那边默认是**看板模式**：按科目分卡片、每
**通知发布 → 叫人**（或管理员在**学生管理 → 叫人**）→ 选学生 → 点一个快捷短语或自己写一句 → 发送。
| 级别 | ClassHelper 班级端 |
| 级别 | ClassHelper 班级端 |
| -------- | ------------------------------------------------------------------ |
| 普通叫人 | 课间显示「叫人」胶囊，点击展开；**上课时段只进队列**，下课自动弹出 |
| 紧急叫人 | **无视上课时段立即展开**，上课时被收起后仍保留胶囊、可再次点开 |
@@ -58,21 +58,3 @@ ClassHelper 班级端那边默认是**看板模式**：按科目分卡片、每
- 导入结果会给逐行的错误与警告，`errors[].row` 是 **Excel 视角的行号**（含表头），改完可以再导。
ClassHelper 班级端看到的是**全班总览**：表格（分数 / 得分率 / 等级）+ 柱状图 + 等级分布 + 最近更新。
## 在教室大屏上播一条提醒（需要 ClassIsland）
**ClassIsland 联动 → 下发提醒** → 选班级、填标题内容、设置显示时长与语音朗读 → 下发。
它会**落库**再推给教室。教室机器断网也不丢：插件重连后会拉取还没确认的那条，
立刻弹出来，弹完回执，不会重复弹。
如果教室客户端把「通知显示位置」设成了"只在 ClassHelper 客户端显示"，这一步会回一句
「该班教室已设置为只在 ClassHelper 客户端显示」—— 那是设计行为，不是报错。
---
到这里你已经把整套系统跑通了。接下来：
- 每一项功能的完整行为 → [应用帮助](../app/index.md)
- 服务器怎么维护 → [管理运维](../management/index.md)
- 遇到问题 → [常见问题](../faq.md)
docs/get-started/index.md
+8 -10
View File
@@ -1,18 +1,17 @@
---
title: 快速上手
description: 从零把 ClassHelper跑起来：装服务端、认管理端、建班级排课、装 ClassHelper 班级端、接 ClassIsland、发第一条内容。
description: 从零把 ClassHelper跑起来：装服务端、认管理端、建班级排课、装 ClassHelper 班级端、发第一条内容。
---
# 快速上手
ClassHelper不是一个单机软件，它由四部分组成，**必须先有服务端，其他三端才有内容可看**：
ClassHelper不是一个单机软件，它由三部分组成，**必须先有服务端，管理端与客户端才有内容可看**：
| 组成部分 | 装在哪 | 谁用 | 必须先装？ |
| ------------------------ | --------------------------------------- | -------------------------- | ---------------- |
| **服务端** | 一台能一直开着的机器（服务器/办公电脑） | —（它同时托管 Web 管理端） | ✅ 是 |
| **Web 管理端** | 不用装 —— 浏览器打开服务端地址即可 | 老师、班主任、管理员 | 跟着服务端一起有 |
| **桌面客户端** | 教室的电脑 / 教室大屏 | 学生看课表作业、老师录作业 | 服务端就绪之后 |
| **ClassIsland 联动插件** | 教室那台装了 ClassIsland 的机器 | 教室大屏播报 | 可选 |
| 组成部分 | 装在哪 | 谁用 | 必须先装？ |
| -------------- | --------------------------------------- | -------------------------- | ---------------- |
| **服务端** | 一台能一直开着的机器（服务器/办公电脑） | —（它同时托管 Web 管理端） | ✅ 是 |
| **Web 管理端** | 不用装 —— 浏览器打开服务端地址即可 | 老师、班主任、管理员 | 跟着服务端一起有 |
| **桌面客户端** | 教室的电脑 / 教室大屏 | 学生看课表作业、老师录作业 | 服务端就绪之后 |
按顺序走下面这几页就行，全程大约半小时（不含下载时间）：
@@ -21,8 +20,7 @@ ClassHelper不是一个单机软件，它由四部分组成，**必须先有服
3. [认识 Web 管理端](web-admin.md) —— 登录进去，认一认界面
4. [建班级、排课表](setup-class.md) —— 这是后面所有功能的前提
5. [装 ClassHelper 班级端](client.md) —— 教室机器用班级码登录
6. [接入 ClassIsland](classisland.md) —— 让教室大屏也会弹提醒（可选）
7. [发布第一条内容](first-content.md) —— 通知 / 作业 / 叫人 / 成绩
6. [发布第一条内容](first-content.md) —— 通知 / 作业 / 叫人 / 成绩
## 只想先看看它长什么样？
docs/get-started/requirements.md
+1 -2
View File
@@ -65,8 +65,7 @@ ldd --version | head -1
| 公网访问 | 前面加 Nginx / Caddy 反代并启用 HTTPS，见[生产部署指南](../management/production.md) |
> **别用代理**。自测时用 `curl.exe --noproxy '*'`，PowerShell 用 `-NoProxy`；
> 教室机器上如果开了系统代理，填服务端地址后可能拿到代理返回的 404。插件里对本地 / 内网地址做了强制直连，
> 但浏览器与客户端本身不会绕过。
> 教室机器上如果开了系统代理，填服务端地址后可能拿到代理返回的 404。请检查系统代理绕过列表是否包含服务端的局域网地址。
## 卸载 / 重置
docs/get-started/setup-class.md
+1 -1
View File
@@ -5,7 +5,7 @@ description: 建第一个班级、配班级账号、加学生与老师、排课
# 建班级、排课表
后面所有功能（发通知、布置作业、录成绩、接 ClassIsland）都挂在**班级**上，所以先把班级建出来。
后面所有功能（发通知、布置作业、录成绩）都挂在**班级**上，所以先把班级建出来。
## 1. 建班级（仅管理员）
docs/get-started/toc.yml
-2
View File
@@ -10,7 +10,5 @@
href: setup-class.md
- name: 装 ClassHelper 班级端
href: client.md
- name: 接入 ClassIsland
href: classisland.md
- name: 发布第一条内容
href: first-content.md
docs/get-started/web-admin.md
+13 -13
View File
@@ -20,19 +20,19 @@ Web 管理端不用装：服务端起来之后，浏览器打开 `http://<服务
布局沿用 1Panel 那一套：左边固定深色侧边栏，右边浅灰底 + 白色圆角卡片。
| 页面 | 干什么 | 谁能进 |
| ---------------- | ---------------------------------------------- | ---------------------- |
| 仪表盘 | 全校 / 本班的汇总数字与最近动态 | 所有登录用户 |
| 课表管理 | 排课、导入 ClassIsland 课表、节次时间 | 管理员、本班班主任 |
| 作业发布 | 发作业、按天查看、看未交名单 | 教师、管理员、班级账号 |
| 通知发布 | 发通知、发叫人 | 教师、管理员 |
| 成绩录入 | 单条 / 批量录成绩、导入表格、看统计 | 管理员、本班班主任 |
| ClassIsland 联动 | 接入教室设备、下发提醒、看实时状态、开镜像 | 管理员、教师 |
| 班级管理 | 建班级、换班主任、改班级账号 | **仅管理员** |
| 学生管理 | 学生名单增删、导入 | **仅管理员** |
| 教师管理 | 教师账号增删改、导入名单、重置密码 | **仅管理员** |
| 数据库管理 | 备份 / 恢复、导出导入、一键切换 SQLite ⇄ MySQL | **仅管理员** |
| 检查更新 | 顶栏头像菜单里，查 GitHub 上有没有新版本 | 所有登录用户 |
| 页面 | 干什么 | 谁能进 |
| ---------- | ---------------------------------------------- | ---------------------- |
| 仪表盘 | 全校 / 本班的汇总数字与最近动态 | 所有登录用户 |
| 课表管理 | 排课、导入 ClassIsland 课表、节次时间 | 管理员、本班班主任 |
| 作业发布 | 发作业、按天查看、看未交名单 | 教师、管理员、班级账号 |
| 通知发布 | 发通知、发叫人 | 教师、管理员 |
| 成绩录入 | 单条 / 批量录成绩、导入表格、看统计 | 管理员、本班班主任 |
| 客户端管理 | 看设备状态、下发远控与更新 | 管理员、教师 |
| 班级管理 | 建班级、换班主任、改班级账号 | **仅管理员** |
| 学生管理 | 学生名单增删、导入 | **仅管理员** |
| 教师管理 | 教师账号增删改、导入名单、重置密码 | **仅管理员** |
| 数据库管理 | 备份 / 恢复、导出导入、一键切换 SQLite ⇄ MySQL | **仅管理员** |
| 检查更新 | 顶栏头像菜单里，查 GitHub 上有没有新版本 | 所有登录用户 |
> **前端隐藏 ≠ 权限**。上面这张表只是"入口藏不藏"，每一条写入请求服务端都会再判一次
> （见[角色与权限](../dev/permissions.md)）。直接输网址绕过菜单，一样会被挡回仪表盘。