docs(release,website,readme): 1.3.0 的更新日志、官网功能块与 README 清单，并把「每次发版四件套」写进 AGENTS.md

- `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。
2026-10-11 14:23:29 +08:00
1 parent 966c8f9b5d
commit 0b9a321bc9
@@ -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 <id>` 定位到具体是哪一步。
+
 #### 官网与文档站怎么发布

 **不用做任何事。** 推 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
@@ -52,6 +52,12 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 - [x] 成绩录入：单条 / 批量 / 表格导入，带等级分布与得分率统计
 - [x] ClassIsland 联动：签发设备令牌、下发提醒、把课表镜像回教室大屏
 - [x] 数据库管理：连接体检、备份与恢复、SQLite ⇄ MySQL 一键切换
+- [x] 权限组：39 个权限键，建组分配账号 —— 没分组的按角色默认生效，分组后只按组的并集算
+- [x] 客户端设备：每台教室机器的版本、在线状态与最后心跳；一键推送更新，可下发关机 / 重启 / 注销 / 锁屏
+- [x] 大模型助手：一句话解析成待确认的作业 / 通知 / 叫人，点确认才落库
+- [x] 通知与作业批量发布：勾多个班一次发完，个别班失败不影响其余班级
+- [x] 系统设置：开发者模式、运行诊断、开机自启开关（仅安装形态）
+- [x] 关怀模式：字号与控件整体放大
 - [x] 手机小屏适配，可「添加到主屏幕」当应用用

 ### 教室里的桌面客户端
@@ -63,6 +69,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 - [x] 成绩总览：全班成绩表格 + 柱状图 + 等级分布
 - [x] 教室机器可直接录入作业、勾选未交名单
 - [x] 离线优先：断网回退 IndexedDB 缓存，恢复连接后自动同步
+- [x] 断网期间错过的通知，重新上线时补弹一次；渲染进程崩了会安静地自己重建窗口
 - [x] 浅色 / 深色主题，跟随系统

 ### 灵动岛（桌面通知浮窗）
@@ -87,6 +94,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 - [x] Linux 一键安装 + `classhelper` 运维命令（systemd 托管，升级 / 回滚 / 备份）
 - [x] Docker Compose（MySQL 版与 SQLite 版各一份）
 - [x] SQLite 与 MySQL 一键切换，备份与跨库迁移共用同一份 JSON 快照
+- [x] 客户端批量更新不依赖外网：安装包由服务端下载缓存，教室机从服务端取，校验 sha256 后空闲时自动装

 ## 软件截图

@@ -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` 或
@@ -476,6 +476,34 @@
                    SQLite 与 MySQL 互相搬数据，中途失败会自动回滚 —— 现有的库不会被动到。
                  </p>
                </div>
+                <div class="feature-block">
+                  <p class="feature-tag">#权限</p>
+                  <h4 class="feature-title">谁能做什么，点着勾</h4>
+                  <p class="feature-body">
+                    建权限组、把账号分进去。没分组的按角色默认生效，分组之后只按组的并集算 —— 既能放权，也能收权。
+                  </p>
+                </div>
+                <div class="feature-block">
+                  <p class="feature-tag">#教室机器</p>
+                  <h4 class="feature-title">每台机器一个身份</h4>
+                  <p class="feature-body">
+                    版本、在线状态、最后心跳一眼看完；可以一键推送更新，也能下发关机、重启、注销、锁屏。
+                  </p>
+                </div>
+                <div class="feature-block">
+                  <p class="feature-tag">#大模型助手</p>
+                  <h4 class="feature-title">说一句话就发出去</h4>
+                  <p class="feature-body">
+                    它只把话解析成待确认的卡片，你点了才落库 —— 权限、上课时段、ClassIsland 推送还是原来那套。
+                  </p>
+                </div>
+                <div class="feature-block">
+                  <p class="feature-tag">#批量发布</p>
+                  <h4 class="feature-title">勾几个班，一次发完</h4>
+                  <p class="feature-body">
+                    通知与作业都能批量。个别班失败不影响其余班级，哪个班为什么没发出去会逐班写清楚。
+                  </p>
+                </div>
              </div>
            </div>

@@ -515,6 +543,13 @@
                    高度、宽度、圆角、字号、停靠位置、视觉风格都能调；越界的值在主进程统一夹紧。
                  </p>
                </div>
+                <div class="feature-block">
+                  <p class="feature-tag">#自愈</p>
+                  <h4 class="feature-title">崩了会自己回来</h4>
+                  <p class="feature-body">
+                    渲染进程挂了先安静地重建窗口；断网期间错过的通知，重新上线时补弹一次。
+                  </p>
+                </div>
              </div>
            </div>
          </div>