v2.9.1

v2.9.1（2026-10-22）

一句话：v2.9.0 的发布流水线在 Windows 安装器验收上失败（未发布任何产物），
本版修正该验收后重新发布 —— 产品代码与 v2.9.0 相同，功能说明请直接看
v2.9.0 的发布说明（docs/releases/v2.9.0.md）；如果你只关心"要不要装"，答案与 v2.9.0 一致：
Windows 用户必须升级（一键安装/静默升级/启动恢复），旧版全局安装需先手动卸载。

项目	说明
版本类型	正式版（Latest）
升级建议	必须升级（Windows 安装方式换代 + 旧版迁移检查 + 启动恢复）
影响面	桌面客户端（Linux / Windows / macOS）+ 服务端镜像
产品代码变化	无（相对 v2.9.0；差异只在发布流水线里的安装器验收脚本）
数据库迁移	无

一、为什么会有 v2.9.1

• 现象：v2.9.0 的发布流水线在"官方 Windows 安装器验收"这一步失败，
  release job 被跳过 ⇒ GitHub Release 与更新服务器都没有 v2.9.0 的产物。
• 根因：该验收脚本在"静默卸载"之后立即检查安装目录是否消失；而 Windows 卸载器
  的自删除/清理可能在进程退出之后才完成 ⇒ 检查过早，把一次正常的卸载判成"残留"。
  这是验收脚本的缺陷，不是安装器或产品代码的缺陷。
• 修法：验收改为轮询等待（目录与注册表项，上限 60 秒）再判定；其余断言不变。
  该修正已并入本次发布，并在 Windows CI 上重新通过。
• 不会影响任何人：v2.9.0 没有产出可下载产物，也没有写入更新服务器；你不需要做任何清理。

二、与 v2.9.0 相同的客户侧变化（摘要）

• Windows 一键安装、仅当前用户、静默升级：双击即装、无向导、无 UAC；
  应用内更新用静默参数原地升级。安装目录为 %LOCALAPPDATA%\Programs\dsh-plugin-desktop。
• 旧版迁移：改名前发布的 2.8.x（含全局安装）不会被静默覆盖；
  交互安装会提示、静默更新以退出码 2 结束并在应用内弹原生提示。
  请先在「设置 → 应用」卸载旧版本；旧数据根与新版不同名，历史会话/设置不会自动迁移。
• 启动失败自救：致命启动对话框提供"跳过第三方插件"与"备份补丁并重启"；
  安全模式一次性生效、成功后自动恢复；重复失败会自动升级为同时备份补丁，不会进入死循环。
• 合规与门禁：一键安装器不再显示许可页，LICENSE 与第三方声明随安装包分发；
  CI 对安装器做载荷断言与真实静默安装/重装/卸载验收（带硬超时）。

已知限制

• Windows 安装器仍未代码签名：首次双击可能出现"未知发布者"/SmartScreen；
  静默升级被拦截时表现为"更新看起来没发生"，请重新检查更新或手动安装。
• 旧版（改名前）安装的数据根不迁移：旧全局安装必须先手动卸载；旧会话/设置需自行备份迁移。
• Windows 每次更新下载完整安装包（无差分更新）；Linux 仍为 AppImage，新版本需手动替换。
• 同一台机器的不同渠道共用同一个 Windows 安装目录名，渠道数据靠各自的数据根分离。

升级与回滚

• 服务端：取 zeokeel-server-2.9.1-amd64.zip → docker load → 按 docs/deploy/AI-DEPLOY.md
  升级（升级前必须备份整个数据根，不要使用 latest，不要 down -v）。
• 客户端：随服务端镜像/更新入口分发；服务端与客户端保持同版本。
• 迁移清单（机器可读锚点，供 scripts/check-release-notes-migrations.mjs 与 git diff 对拍）：无
• 回滚：口径唯一真源是 docs/deploy/AI-DEPLOY.md §7。本版相对 v2.9.0 无数据库迁移；
  回退到 v2.8.3-beta.5 或更早版本同样无数据库迁移，换回对应镜像与客户端包即可。
  Windows 若要从本版退到向导式安装器的旧版本，建议先卸载本版再安装旧版包。

附件与校验

• zeokeel-server-2.9.1-amd64.zip：服务端镜像压缩包（docker load 后使用），内含该渠道的三平台客户端安装包；
• SHA256SUMS：先 sha256sum -c SHA256SUMS 校验，再解压。
• 客户端安装包在镜像内（/opt/zeokeel/client/），员工也可从自己服务器的更新页面下载。
  品牌渠道的镜像与客户端只在该渠道自己的更新目录里，不随公开 Release 发布。

v2.8.3-beta.5

v2.8.3-beta.5（2026-10-21）

一句话：换上 ZeoKeel 新品牌标识，并修复「升级后每次启动都被登出」、菜单透明、技能管理白屏与设置入口偶发无响应。

项目	说明
版本类型	预发布（beta）
升级建议	建议测试升级（预发布，不进入正式更新通道）
影响面	服务端镜像 / 桌面客户端（Linux / Windows / macOS）/ 管理后台
产品代码变化	有（相对 v2.8.3-beta.4）
数据库迁移	无

一、全新品牌标识

• 变化：整仓切换到 ZeoKeel 新 logo —— 白色圆角底（日间）与黑色圆角底（夜间）配同一枚彩色图形；应用图标、官网、管理后台、登录页、侧边栏、OG 分享图与产品截图全部同步。
• macOS 菜单栏：仍只使用单色 template 图标（黑色 + alpha，系统按菜单栏明暗自动反白），并且改为构建期从当前渠道的完整图形派生，后续渠道自动继承自己的标识。
• 其他平台：Windows / Linux 托盘与所有产品界面保持彩色标识，不使用单色版本。
• 验证：品牌几何与桌面/企业/门户/站点四侧对拍；打包产物与官网构建均通过品牌守卫。

二、升级后不再每次启动都被登出

• 现象：安装包升级到新版本后，已登录用户每次启动都被踢回登录页。
• 根因：网关客户端包把 npm 的 electron 桩内联进产物，打包后的 main 进程拿不到 safeStorage，盘上已保存的会话读不出来。
• 修复：构建期强制 electron external，并新增产物守卫；safeStorage 不可用时仍可恢复 0600 明文会话；恢复流程增加竞态保护，显式登录/登出不会被迟到的恢复覆盖。
• 验证：新增会话恢复与竞态用例；打包产物构建守卫在 CI 构建期执行。

三、菜单不再出现「透明膜」

• 现象：在 macOS vibrancy / Windows Mica 等原生材质窗口上打开侧栏菜单，卡片会透出下面的会话列表。
• 修复：按桌面端的模式标记打开上游菜单的实底背板；菜单本身仍是半透明 + 模糊材质，只补上可模糊的底。
• 验证：新增菜单背板回归用例与合成探针，覆盖浅色/深色两套主题。

四、技能管理不再白屏

• 现象：打开 memory-evolve 的技能管理页面时白屏。
• 根因：DSH 0.2.1 移除了带尺寸后缀的 Icon*16/14 导出，旧名字在运行时是 undefined。
• 修复：全部改用 Icon*Regular 导出，并新增图标导出回归测试。

五、设置入口恢复响应

• 现象：点击「更多」里的「设置」偶尔没有反应。
• 修复：优先直接调用上游 launcher 的 openSettings，保留原有 DOM 菜单桥接作为回退。

已知限制

• macOS 菜单栏模板使用完整图形，16px 下细节较密；后续如有需要可单独出一版简化剪影。
• 预发布版不进入正式更新通道，正式客户端不会自动收到本版。

升级与回滚

• 服务端：取本版镜像附件，按 docs/deploy/AI-DEPLOY.md 升级；升级前必须备份。

• 客户端：随服务端镜像分发，员工从自己登录的服务器取包。

• 回滚：本版无数据库迁移，保留上一版镜像 tag 切回即可；客户端重装上一版包。

• 迁移清单（机器可读锚点，供 scripts/check-release-notes-migrations.mjs 与 git diff 对拍）：无

附件与校验

• zeokeel-server-2.8.3-beta.5-amd64.zip：服务端镜像压缩包（docker load 后使用）；
• SHA256SUMS：sha256sum -c SHA256SUMS 校验后再解压；
• 桌面客户端安装包：Linux / Windows / macOS 三个平台随 Release 附件发布。