From 0b9a321bc953518e29414f5661c582d60453bde7 Mon Sep 17 00:00:00 2001 From: LoveChengke Date: Sun, 11 Oct 2026 14:23:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(release,website,readme):=201.3.0=20?= =?UTF-8?q?=E7=9A=84=E6=9B=B4=E6=96=B0=E6=97=A5=E5=BF=97=E3=80=81=E5=AE=98?= =?UTF-8?q?=E7=BD=91=E5=8A=9F=E8=83=BD=E5=9D=97=E4=B8=8E=20README=20?= =?UTF-8?q?=E6=B8=85=E5=8D=95=EF=BC=8C=E5=B9=B6=E6=8A=8A=E3=80=8C=E6=AF=8F?= =?UTF-8?q?=E6=AC=A1=E5=8F=91=E7=89=88=E5=9B=9B=E4=BB=B6=E5=A5=97=E3=80=8D?= =?UTF-8?q?=E5=86=99=E8=BF=9B=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `releases/ReleaseNotes-1.3.0.md`：1.3.0 的 Release 正文草稿（一句话定位 / 七个分节 / ⚠️ 升级须知 / 验收 / 产物表）。验收表只写本轮真跑过的静态门禁，运行时验收没跑就直说没跑 - `website/index.html`：老师与管理员加 #权限 / #教室机器 / #大模型助手 / #批量发布 四块， 教室机器与学生机加 #自愈 一块（11 → 16 块，实测渲染正常） - `README.md`：功能清单补上权限组、客户端设备、大模型助手、批量发布、系统设置、关怀模式、 崩溃自愈与离线补弹，以及「客户端更新不依赖外网」 - `AGENTS.md` §4.4 新增「每次发版必须一起交付的四样东西」（更新日志 / Linux 包 / 文档 / 官网与 README）， 并记下「CI 按 tag 的 ref 检出源码」这个坑 —— 发完版再改构建脚本时**光推 master 不够**， 必须把 tag 挪到修复后的提交；第 ⑦ 步的示例也改成用 `--notes-file` - `docs/dev/release.md`：同一份四件套清单（面向人）+ 第 7 步改用 `--notes-file` + tag 那个坑 `pnpm docs:check` 0 warning 0 error。 --- AGENTS.md | 34 +++++++++++++++++++++++++++++++++- README.md | 8 ++++++++ docs/dev/release.md | 26 +++++++++++++++++++++++++- website/index.html | 35 +++++++++++++++++++++++++++++++++++ 4 files changed, 101 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6b4f3a0..2e3d429 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -432,7 +432,9 @@ pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版 git add -A && git commit -m "chore(release): <版本>" && git push origin master # ⑦ 开 Release（gh release create 会创建并推送 tag，从而触发 Linux 包的 CI；见下） -gh release create v<版本> --title "v<版本>" --generate-notes +# 正文用手写的更新日志，别只留 --generate-notes 的自动列表（见「每次发版必须一起交付的四样东西」） +gh release create v<版本> --title "ClassHelper v<版本>（<一句话定位>）" \ + --notes-file releases/ReleaseNotes-<版本>.md gh release upload v<版本> \ releases/client/<版本>/安装包/*.exe \ releases/classisland-plugin/<版本>/安装包/*.cipx \ @@ -478,6 +480,36 @@ gh workflow run release-linux-server.yml -f tag=v<版本> -f attach=true **已发布的版本号不要复用**：客户端把它记进「忽略此版本」，两端各有 30 分钟缓存 —— 同号换内容会让「检查更新」永久失灵。要修就 `pnpm version:bump patch` 发新号。 +#### 每次发版必须一起交付的四样东西 + +`pnpm dist:all` 只产出安装包。**每次版本迭代都要把这四样一起做掉**，少一样都算「发到一半」： + +| # | 交付物 | 落在哪 | 怎么做 | +| -- | ------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| ① | **更新日志** | GitHub Release 的正文 | 手写，草稿放 `releases/ReleaseNotes-<版本>.md`（与它描述的产物同一层），用 `gh release create/edit --notes-file` 发布。**不要**只挂 `--generate-notes` 的自动列表 | +| ② | **Linux 服务端包** | Release 上的 `classhelper-server-linux-x64-<版本>.tar.gz` | tag 推上去由 `release-linux-server.yml` 构建；**推完必须去 Actions 确认没红** | +| ③ | **文档** | `docs/reference.md`（功能说明 + 验收对照表）与相关章节 | 新增功能补对应小节；改交付形态一并改 §2 / §7 与 `docs/dev/*` | +| ④ | **官网与 README** | `website/index.html`（功能块）、`website/download.html`（兜底版本号）、`README.md`（功能清单） | 新功能补进功能块 / 清单；页面里的版本号由 `pnpm version:bump` 覆盖，不用手写 | + +更新日志的骨架照 1.2.0 / 1.3.0 那两份：**一句话定位 → 分节讲功能 → ⚠️ 升级须知（含自动应用的迁移）→ +验收表 → 产物表**。验收表里**只写真跑过的数字**，没跑就直说没跑，别照抄上一版的。 + +**② 有个很容易漏的坑：CI 是按 tag 的 ref 检出源码的**（`actions/checkout` 的 +`ref: ${{ steps.ref.outputs.tag }}`）。所以发完版又发现构建脚本（或任何影响出包的代码）要修时， +**光推 master 不够** —— CI 仍会拿旧 tag 的源码跑，必须把 tag 挪到修复后的提交： + +```bash +git tag -f v<版本> <修复后的提交> && git push --force origin v<版本> +``` + +tag 一变会自动重跑。v1.3.0 实测踩过：tag 指的那个提交里 `dist-server.mjs` 有个 bug +（见 §5 第 59 条 ④），CI 红了、Release 上少一个 Linux 包，而本地完全看不出来 —— +Windows 侧走的是另一条分支，`pnpm dist:server` 一直绿。 + +**推完 tag 去 `gh run list --limit 5` 看一眼。** `发布官网与文档站`（master 推送触发）与 +`发布 Linux 服务端安装包`（tag 推送触发）是两条独立流水线，**前者绿不代表后者出来了**； +失败用 `gh run view ` 定位到具体是哪一步。 + #### 官网与文档站怎么发布 **不用做任何事。** 推 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或 diff --git a/README.md b/README.md index 9083959..1430eed 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,12 @@ ClassHelper是给中小学班级用的一套信息管理系统。
- [x] 成绩录入：单条 / 批量 / 表格导入，带等级分布与得分率统计 - [x] ClassIsland 联动：签发设备令牌、下发提醒、把课表镜像回教室大屏 - [x] 数据库管理：连接体检、备份与恢复、SQLite ⇄ MySQL 一键切换 +- [x] 权限组：39 个权限键，建组分配账号 —— 没分组的按角色默认生效，分组后只按组的并集算 +- [x] 客户端设备：每台教室机器的版本、在线状态与最后心跳；一键推送更新，可下发关机 / 重启 / 注销 / 锁屏 +- [x] 大模型助手：一句话解析成待确认的作业 / 通知 / 叫人，点确认才落库 +- [x] 通知与作业批量发布：勾多个班一次发完，个别班失败不影响其余班级 +- [x] 系统设置：开发者模式、运行诊断、开机自启开关（仅安装形态） +- [x] 关怀模式：字号与控件整体放大 - [x] 手机小屏适配，可「添加到主屏幕」当应用用 ### 教室里的桌面客户端 @@ -63,6 +69,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。
- [x] 成绩总览：全班成绩表格 + 柱状图 + 等级分布 - [x] 教室机器可直接录入作业、勾选未交名单 - [x] 离线优先：断网回退 IndexedDB 缓存，恢复连接后自动同步 +- [x] 断网期间错过的通知，重新上线时补弹一次；渲染进程崩了会安静地自己重建窗口 - [x] 浅色 / 深色主题，跟随系统 ### 灵动岛（桌面通知浮窗） @@ -87,6 +94,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。
- [x] Linux 一键安装 + `classhelper` 运维命令（systemd 托管，升级 / 回滚 / 备份） - [x] Docker Compose（MySQL 版与 SQLite 版各一份） - [x] SQLite 与 MySQL 一键切换，备份与跨库迁移共用同一份 JSON 快照 +- [x] 客户端批量更新不依赖外网：安装包由服务端下载缓存，教室机从服务端取，校验 sha256 后空闲时自动装 ## 软件截图 diff --git a/docs/dev/release.md b/docs/dev/release.md index fdb9355..7ad99c3 100644 --- a/docs/dev/release.md +++ b/docs/dev/release.md @@ -19,6 +19,21 @@ description: 改版本号、跑验收、打安装包、发 GitHub Release、发 | 要给别人一份新安装包 | 只在自己机器上跑 | | 插件单独发补丁（只动插件第 4 段版本号） | — | +## 每次发版必须一起交付的四样东西 + +打安装包只是其中一件。**少一样都算「发到一半」**： + +| # | 交付物 | 落在哪 | 怎么做 | +| -- | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ | +| ① | **更新日志** | GitHub Release 的正文 | 手写，草稿放 `releases/ReleaseNotes-<版本>.md`，用 `--notes-file` 发布。别只挂自动生成的列表 | +| ② | **Linux 服务端包** | Release 上的 `classhelper-server-linux-x64-<版本>.tar.gz` | tag 推上去由 CI 构建；**推完去 Actions 确认没红**（见第 7 步） | +| ③ | **文档** | `docs/reference.md`（功能说明 + 验收对照表）与相关章节 | 新增功能补对应小节；改交付形态一并改第 2 章 / 第 7 章 | +| ④ | **官网与 README** | `website/index.html`、`website/download.html`、`README.md` | 新功能补进官网功能块与 README 功能清单；版本号由脚本覆盖 | + +更新日志的骨架（照 1.2.0 / 1.3.0 那两份写）： +**一句话定位 → 分节讲功能 → ⚠️ 升级须知（含会自动应用的迁移）→ 验收表 → 产物表**。 +验收表里**只写真跑过的数字**，没跑就直说没跑，不要照抄上一版的。 + ## 版本号写在哪（14 处 / 12 个文件） 同一个版本号分散在 14 个落点上，**手工改必然漏一处**，而漏掉的那处不会报错： @@ -143,7 +158,7 @@ cp "releases/client/$V/安装包/"*-x64-portable.exe ".cache/release-staging/Cla cp "releases/server/$V/安装包/"*-x64-setup.exe ".cache/release-staging/ClassHelper-$V-x64-server-setup.exe" cp "releases/classisland-plugin/$V/安装包/ClassHelper.ClassIslandPlugin.cipx" .cache/release-staging/ -gh release create v$V --title "v$V" --generate-notes +gh release create v$V --title "ClassHelper v$V（<一句话定位>）" --notes-file "releases/ReleaseNotes-$V.md" gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --clobber ``` @@ -173,6 +188,15 @@ gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --cl gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true ``` +> **CI 是按 tag 的 ref 检出源码的。** 发完版又发现构建脚本（或任何影响出包的代码）要修时， +> **光推 master 不够** —— CI 仍会拿旧 tag 的源码跑，得把 tag 挪到修复后的提交： +> `git tag -f v<版本> <提交> && git push --force origin v<版本>`，tag 一变会自动重跑。 +> 1.3.0 实测踩过：tag 指的那个提交里打包脚本有个 bug，CI 红了、Release 上少一个 Linux 包， +> 而本地 `pnpm dist:server` 一直是绿的（Windows 侧走另一条分支）。 +> +> 另外，本页第 8 步的「官网与文档站」是**另一条**流水线（master 推送触发）—— +> 它绿不代表 Linux 包出来了，推完 tag 要去 `gh run list --limit 5` 看一眼。 + ### 8. 官网与文档站 **不用做任何事。** 推送 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或 diff --git a/website/index.html b/website/index.html index f659181..67ff457 100644 --- a/website/index.html +++ b/website/index.html @@ -476,6 +476,34 @@ SQLite 与 MySQL 互相搬数据，中途失败会自动回滚 —— 现有的库不会被动到。

+
+

#权限

+

谁能做什么，点着勾

+

+ 建权限组、把账号分进去。没分组的按角色默认生效，分组之后只按组的并集算 —— 既能放权，也能收权。 +

+
+
+

#教室机器

+

每台机器一个身份

+

+ 版本、在线状态、最后心跳一眼看完；可以一键推送更新，也能下发关机、重启、注销、锁屏。 +

+
+
+

#大模型助手

+

说一句话就发出去

+

+ 它只把话解析成待确认的卡片，你点了才落库 —— 权限、上课时段、ClassIsland 推送还是原来那套。 +

+
+
+

#批量发布

+

勾几个班，一次发完

+

+ 通知与作业都能批量。个别班失败不影响其余班级，哪个班为什么没发出去会逐班写清楚。 +

+
@@ -515,6 +543,13 @@ 高度、宽度、圆角、字号、停靠位置、视觉风格都能调；越界的值在主进程统一夹紧。

+
+

#自愈

+

崩了会自己回来

+

+ 渲染进程挂了先安静地重建窗口；断网期间错过的通知，重新上线时补弹一次。 +

+