fix(clients,client,web): 远控指令的两个修复 —— 执行失败不再谎报成功 + 「上次指令」让"点了没反应"可见（1.3.2）

背景：用户报「下发锁屏等等指令不生效」。先把服务端那条链路单独验了一遍（模拟客户端：登记 → 下发 → 心跳带回 → 设备列表可见 → 回执 → 清除），**整条是通的**；真正的问题在两处。客户端：执行失败会谎报成功 - `spawn` 找不到可执行文件 / 没权限时**不抛异常**，而是在下一个 tick 发一个异步 `error` 事件 —— 只包 `try/catch` 抓不到，代码一路走到 `return { ok: true }`，回执写着「已下达系统命令」， Web 端看起来一切正常而机器纹丝不动 - 现在等一个 200ms 的窗口确认没有立刻报错，失败如实回执（`client-agent.ts` 的 `executeCommand`） Web 端：点了没生效，界面上什么都不说 - 一条命令被**取消 / 过期**之后就从 `pendingCommand` 里消失，页面留白 —— 而最常见的两种"没反应"恰恰是「本机没人确认（客户端 60 秒自动按取消）」与「下达时机器离线」 - `GET /clients/devices` 增加 `lastCommand`（最近一条，不论状态）；「客户端」页的设备表多一列「上次指令」，由 `commandStateText()` 翻成一句人话（已执行 / 本机用户取消 / 已过期 —— 下达时机器不在线 / 待执行） - 下发成功的提示补上「60 秒内没人点确认就按取消处理」文档 - AGENTS.md §5 第 69 条记下这两条，并写明排查同类反馈的顺序：**先看那台机器的客户端版本是否 ≥ 1.3.0** （远控命令的处理 `client-agent.ts` 是 1.3.0 才有的，旧客户端连心跳都不发） - docs/reference.md 4.15 的表格补上「二次确认」的准确口径与新增的「上次指令」列验收：`lint` / `typecheck` / `check:icons` / `docs:check` 全绿；后端端到端 **247/247**、联动链路 **44/44**、插件静态契约 **76/76**、 Web 真实点击 **34/34**、客户端冒烟 **90/90**；远控链路另用模拟客户端跑通，并确认新增的「上次指令」在待执行与已回执两种状态下都显示正确。
2026-10-11 17:00:11 +08:00
1 parent 227117ccb3
commit b7cdc7c9ea
@@ -23,8 +23,8 @@ curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/Love
 ```

 > **别写成 `bash -c "$(curl …)" --check`**：`bash -c '代码' 第一个参数` 里那个参数会变成 `$0`，
-> 不是 `$1` —— 脚本收不到它（实测踩到：本意是体检，结果走进了交互式安装）。
-> 先落盘再执行没这个坑，也不会因为下载中断而执行到半个脚本。
+> 不是 `$1` —— 脚本收不到它（想体检却会走进交互式安装）。
+> 先落盘再执行没这个问题，也不会因为下载中断而执行到半个脚本。

 以下是"已有安装包 / 内网离线"的用法：

@@ -75,7 +75,7 @@ Windows 开发机上 `npm install` 出来的 `node_modules` 拷到 Linux 跑不

 `pnpm dist:server:linux` 在非 Linux 上也**能跑**：脚本会用 npm 的 `--os=linux --cpu=x64`
 按目标平台解析可选依赖，所以 `@libsql/linux-x64-gnu` 这些"按平台分发"的包会被正确装进来。
-适合本地快速打一个包去验证安装与运维流程。已核对过的结论：
+适合本地快速打一个包去验证安装与运维流程。逐项核对过的结论：

 | 项 | 结论 |
 | --- | --- |
@@ -2,12 +2,12 @@

 本文档覆盖三种上线形态，按适用场景选择：

-| 形态                  | 适用场景                                     | 产物                                                     | 本机验证情况                           |
-| --------------------- | -------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
-| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）     | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
-| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml`        | ⚠️ 文件已提供，本机无 Docker 未实测    |
-| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/install.sh) + `classhelper` 运维命令             | ⚠️ 本机无 Linux，实机验收见 [linux-deploy.md](linux-deploy.md) §10 |
-| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义           | 在仓库里构建后直接跑（见第四节）                          | ✅ 已实测（163 项端到端）    |
+| 形态                  | 适用场景                                     | 产物                                                     | 验证状态                                                |
+| --------------------- | -------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------- |
+| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）     | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | ✅ 已验证（静默安装 / 启停 / 卸载 / UI）                |
+| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml`        | ⚠️ 文件已提供，尚未实机验证                             |
+| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/install.sh) + `classhelper` 运维命令             | ⚠️ 实机验收清单见 [linux-deploy.md](linux-deploy.md) §10 |
+| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义           | 在仓库里构建后直接跑（见第四节）                          | ✅ 已验证（端到端验收通过）                             |

 ---

@@ -101,8 +101,8 @@ uninstall-service.cmd   :: 删除计划任务

 ## 二、Docker + MySQL（形态 B，云部署推荐）

-> 本机没有 Docker，因此这套文件未在本机实测；结构经过与已验证的产物对照（依赖清单、
-> 目录布局、迁移方式与服务端完全一致）。
+> 这套文件与已验证的产物结构一致（依赖清单、目录布局、迁移方式与服务端完全相同），
+> 但**尚未在真实 Docker 环境跑过**。第一次上线请先在测试机走一遍。

 ```bash
 cp deploy/.env.example deploy/.env
@@ -392,7 +392,7 @@ pnpm --filter @classhelper/server start      # 或 node packages/server/dist/ind

 ## 八、性能与容量参考

- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），实测 62 项接口与实时推送全部达标。
+- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），接口与实时推送均已通过端到端验收。
 - 多校区 / 高并发建议切 MySQL，并横向扩容服务端（Socket.IO 需要配置 Redis adapter 才能多实例广播，
  当前为单实例广播；如需多实例请参考 `packages/server/src/realtime/socket.ts` 引入 `@socket.io/redis-adapter`）。
 - 静态资源已设置 immutable 长缓存 + gzip；Web 管理端为 SPA，首屏包体约 900 KB（gzip 约 290 KB），