# 升级模块落地（2026-10-20）

## 真实升级反馈：ASAR 标记误判

用户在 `0.0.3 → 0.0.4` 测试中实际遇到 `NSIS 安装标记不是文件`。物理安装文件正常；原实现使用 Electron patched `fs.stat`，将 `resources/app.asar` 当作虚拟目录。此前 Node 后端测试和未调用安装器的启动/下载验证没有覆盖这个语义差异。

修复通过 `physical-files.ts` 的 Electron `node:original-fs` 适配器执行物理 `stat/realpath`，由生产更新入口注入。没有全局关闭 ASAR，也没有移除 `isFile`、注册表或路径校验。真实 Electron 只读测试 `node scripts/verify-updates-installer-marker.cjs` 已通过：当前真实安装目录校验成功，真实目录 marker 和错误 registry 仍被拒绝；未启动安装器、未修改用户安装。报告 `.tmp/updates-installer-marker/2026-10-20T10-23-07-489Z/report.json`。

修正版为 `0.0.5`。旧版 `0.0.3/0.0.4` 的运行中检查器无法通过服务器目标包自我修复，需要手动覆盖安装一次修正版后，再测试后续自动升级。

`0.0.5` 已构建并发布，237106337 字节，SHA-256 `a3b8ece96077af81f9c8c676cb7d0d71f16a5d73332bc48b865c5cba7e92fd0d`。最终 ASAR 已核对包含物理文件适配器；生产包隔离启动与正式 IPC、服务器签名清单及完整下载校验通过，报告 `.tmp/updates-live/2026-10-20T10-28-49-489Z/report.json`。没有替用户执行安装或重启，真实覆盖安装仍待用户继续验证。

## 实现与边界

- Windows x64、Electron + NSIS 按用户安装；账号菜单、关于页与侧栏共享真实更新状态。
- 启动 10 秒后检查，此后每 5 分钟检查；发现更新后后台下载，已忽略版本不自动下载。
- 检查中、下载进度、就绪、失败重试、按版本忽略/折叠、手动下载及安装诊断日志已接通。
- 原版参考为 WorkBuddy 5.8.3，ASAR SHA-256 `3e50fcb5b060deba4f1ea9a8c293cf955bf12d7e52d971985de914350afd9077`；主要 REA Evidence 为 `ev_6f16b9ef02d9c5fb142e7d686ea8caeeec79797b621d615aaa532b49b65d7ad9`（renderer）与 `ev_e41b1e44cb0c430be5d8caa14b4e3a4710a6925e0bdff870d42ffa73b5e1a5c8`（Windows 更新模块）。本轮复用历史静态 REA 结论，没有通过其他渠道查看原版。
- 强制升级、商店/企业分支、启动 splash 与架构纠正仍在后续完整复刻清单中。本轮普通更新交互不是完整 1:1 验收；缺少原版全状态运行态布局/动效/像素证据。

## 安全与退出

- 完整 payload 使用独立 YCode Ed25519 密钥签名；客户端先验签再采用版本、说明、大小、下载地址与哈希。公钥随包分发；私钥仅在仓库外保存。
- 同源、固定版本目录、严格 SemVer、响应体上限、超时、大小与 SHA-256 校验；断点续传检查 Content-Range；缓存和安装前再次校验。
- 多窗口 IPC 仅接受主窗口/设置窗口的主 frame；渲染层不接收 Node 能力或安装路径参数。
- 用户确认前不启动安装器。确认后暂停新任务/终端创建，停止调度并取消、等待当前任务落库；该准备阶段不销毁全局 Claude 内核/MCP。
- 准备超时后，不会在旧 stop 尚未结束时恢复服务；安装标记写入或 spawn 失败后允许恢复。
- 安装器成功 spawn 是不可回退提交点；后端拒绝重复安装/检查/忽略，不再恢复后台任务。随后有界清理资源并退出，避免已启动的安装器和恢复后的工作并存。
- NSIS 等待指定 PID 后检查残留实例；不使用进程名批量结束其他实例。真实执行行为以专项安装 QA 结果为准。
- 安装位置绑定当前用户注册表 GUID、当前 EXE、卸载器与 app.asar，支持用户选择的目录；便携解压/开发模式不执行覆盖安装。
- 记录目标版本，下次启动仍低于目标则提示升级未完成。安装器执行失败不会被误报为已升级。

## 验证

- `npm run test:updates`：后端 14 组；运行时门禁与生命周期专项；发布工具 12 组；发布清单与真实后端验签/路径契约检查通过。
- `npm run build`：完整主进程、preload、renderer 构建和 Node/Web 类型检查通过。
- `npm run test:updates:ui`：真实 Electron 主/设置窗口、正式 preload、注入确定性 updates IPC，验证渲染交互和跨窗口状态；最终报告 `.tmp/updates-ui-ZnQVYZ/report.json`，无 renderer 错误。该验证不等价于真实下载或安装。
- `npm run test:chat`：消息顺序、聊天状态、流式提交旧回归通过。
- `0.0.2` 的真实生产包隔离启动与 HTTP 下载验证通过；报告 `.tmp/updates-live/2026-10-20T09-43-52-041Z/report.json`。前代版本号为注入模拟，安装器调用为零，不是实际版本升级。
- 审查发现并修复安装失败后内核永久关闭、超时清理继续破坏恢复、确认期间并发忽略、spawn 后回滚、NSIS 错误码与残留进程检查问题；修正版内部版本递增为 `0.0.3`，不覆盖不可变 `0.0.2` 发布。
- `0.0.3` 已构建并发布，安装包 `release/YCode-0.0.3-Setup-x64.exe`，237105798 字节，SHA-256 `6f7565fcc152a99899bf74a795c8e91417516980f143fb9fccb61bde2b490200`。
- `0.0.3` 真实生产包隔离启动与正式 preload IPC 检查通过（idle → checking → up-to-date）；真实服务器签名清单及全量安装包下载/哈希通过，模拟旧版本最终 ready/100。报告 `.tmp/updates-live/2026-10-20T10-02-05-040Z/report.json`。安装器/安装回调调用均为零；真实用户注册表与安装 EXE 指纹前后未变。
- 完整 NSIS 真机覆盖安装、原生确认取消、安装后重启/版本回查，以及等待宏的不存在 PID/睡眠 PID/第二实例/拒绝访问动态探针仍未执行。独立 QA 安装方案仅完成设计，没有构建或安装 fixture；不能把单元、渲染或真实下载测试当作已完成安装验收。

## 发布与使用

服务器为 `local001`，客户端更新入口为 `http://192.168.10.6/ycode/releases/latest.json`，手动下载页为 `http://192.168.10.6/ycode/releases/`。SSH 仅用于发布维护，客户端不需要 SSH 凭据。HTTP 限内网使用；真实性依赖内置公钥，不能防止网络阻断/旧清单重放导致的更新延迟。

参见 [升级发布说明](升级发布说明-2026-10-20.md)。`0.0.1` 未包含 updater，必须先关闭旧 YCode 并手动安装首个安全验收完成的基线包，之后才有自动更新能力。安装包尚未 Authenticode 签名，系统可能显示 SmartScreen 警告。没有替换或重启当前用户安装版，也没有修改其配置/会话或提交 Git。