feat: complete WorkBuddy parity and Windows release workflow

2026-10-18 12:45:21 +08:00
1 parent 143516b3a8
commit d5512df549
@@ -0,0 +1,350 @@
+# YCode Windows 分发包 SOP
+
+版本：2026-10-18  
+适用：Windows x64、Electron 37、NSIS、内置 OMP 18.6.3  
+最后一次验证产物：YCode v0.01（内部版本 0.0.1）
+
+## 1. 目标与发布边界
+
+本流程用于生成可分发的 Windows 安装程序和免安装目录包，并确保内置 OMP、沙盒、Git、模型元数据和第三方许可完整。
+
+发布包不得包含：
+
+- 当前用户的模型 Key 或其他凭据
+- %APPDATA%\YCode 下的会话、项目、资料库或设置
+- 用户个人专家包、备份目录或临时测试目录
+- .tmp、release 中间文件、源码仓库元数据
+
+个人模型、会话和专家保留在安装后的用户数据目录中，不随安装包分发。
+
+## 2. 版本规则
+
+YCode 的展示版本和 npm 内部版本分开管理：
+
+| 项目 | 当前值 | 位置 |
+| --- | --- | --- |
+| 分发版本 | v0.01 | 文件名、发布记录 |
+| 内部 SemVer | 0.0.1 | package.json、package-lock.json、Windows ProductVersion |
+| 安装程序 | YCode-v0.01-Setup-x64.exe | package.json 的 build.win.artifactName |
+
+发版前同时更新以下内容：
+
+1. package.json 顶层 version。
+2. package-lock.json 顶层和根包 version。
+3. package.json 的 build.win.artifactName。
+4. 发布说明中的文件名、大小和 SHA-256。
+
+内部版本必须符合 SemVer。显示为 v0.01 时，内部版本对应 0.0.1，不能直接写成字符串 0.01。
+
+## 3. 构建环境
+
+最低要求：
+
+- Windows 10/11 x64
+- Node.js 24.x 和 npm
+- PowerShell 5.1 或 PowerShell 7
+- 本仓库依赖已安装
+- 至少 2 GiB 可用磁盘；推荐 4 GiB
+- 构建期间不要同时运行多个 electron-builder
+- 不要让 win-unpacked 中的测试客户端保持运行，避免文件锁
+
+进入仓库根目录并检查工具：
+
+~~~powershell
+Set-Location 'C:\Users\Administrator\code\YCode'
+node --version
+npm --version
+Get-Command node,npm
+~~~
+
+干净环境和 package-lock.json 变更后使用：
+
+~~~powershell
+npm ci
+~~~
+
+仅日常沿用现有 node_modules 时，可先执行：
+
+~~~powershell
+npm ls --depth=0
+~~~
+
+## 4. 发版前检查
+
+### 4.1 源码和变更范围
+
+确认工作区中的改动都属于本次发布；当前项目允许保留未提交修改，但发布记录必须注明构建来源。
+
+~~~powershell
+git status --short
+git diff --stat
+~~~
+
+不要覆盖或回退其他并行任务的修改。
+
+### 4.2 静态检查
+
+~~~powershell
+npm run typecheck
+~~~
+
+### 4.3 OMP 资源与许可
+
+内置资源位于 resources\omp，必须包含：
+
+- omp.exe
+- LICENSE
+- THIRD-PARTY-NOTICES.txt
+- runtime.lock.json
+
+校验固定版本和摘要：
+
+~~~powershell
+npm run omp:verify
+npm run test:omp:bundled
+~~~
+
+通过标准：
+
+- runtime.lock.json 中的平台为 win32-x64
+- OMP 版本为锁定版本，本批为 18.6.3
+- omp.exe、LICENSE、THIRD-PARTY-NOTICES.txt 的大小和 SHA-256 全部匹配
+- omp.exe --version 返回 omp/18.6.3
+- 无 YCODE_OMP_PATH 时，detectOmpPath 指向 resources\omp\omp.exe
+- 真实 RPC 启动能收到 type=ready
+
+如果资源刚清空，先从固定上游恢复：
+
+~~~powershell
+node scripts/vendor-omp.mjs
+~~~
+
+如果本机已有经过校验的 Ygent 安装，可只导入二进制：
+
+~~~powershell
+node scripts/vendor-omp.mjs --from "$env:LOCALAPPDATA\Ygent"
+node scripts/vendor-omp.mjs --verify
+~~~
+
+离线构建时，应先从上一个已验收安装包复制完整的 resources\omp 目录，再执行 --verify。不得绕过大小或 SHA-256 校验。
+
+## 5. 下载镜像与缓存
+
+当前环境访问 GitHub 可能超时。首次构建在干净网络下可直接运行；出现 ETIMEDOUT 时设置 electron-builder 镜像：
+
+~~~powershell
+$env:ELECTRON_MIRROR = 'https://npmmirror.com/mirrors/electron/'
+$env:ELECTRON_BUILDER_BINARIES_MIRROR = 'https://npmmirror.com/mirrors/electron-builder-binaries/'
+~~~
+
+测试版没有证书时关闭证书自动发现：
+
+~~~powershell
+$env:CSC_IDENTITY_AUTO_DISCOVERY = 'false'
+~~~
+
+镜像只用于下载构建工具，不改变应用运行时地址。不要在源码或脚本中写死个人代理。
+
+常见缓存位置：
+
+~~~text
+%LOCALAPPDATA%\electron\Cache
+%LOCALAPPDATA%\electron-builder\Cache
+~~~
+
+electron-builder 的生产依赖收集可能需要数分钟。期间不要重复启动第二个打包进程或误判为卡死。
+
+## 6. 构建安装程序
+
+标准入口：
+
+~~~powershell
+npm run dist:installer
+~~~
+
+该命令依次执行：
+
+1. omp:vendor：恢复并校验内置 OMP。
+2. npm run build：
+   - 构建原生沙盒
+   - TypeScript node/web 检查
+   - electron-vite main/preload/renderer 构建
+3. electron-builder --win nsis：
+   - 生成 release\win-unpacked
+   - 复制 OMP、模型元数据、沙盒和 Git extraResources
+   - 生成 NSIS 安装程序
+
+仅需免安装目录时：
+
+~~~powershell
+npm run dist
+~~~
+
+构建成功必须同时满足：
+
+- 命令退出码为 0
+- release\win-unpacked\YCode.exe 存在
+- release\YCode-v0.01-Setup-x64.exe 存在
+- release\YCode-v0.01-Setup-x64.exe.blockmap 存在
+- release\win-unpacked\resources\omp\omp.exe 存在
+
+自动化执行器如果自身有 5 分钟超时，应使用独立后台进程并把 stdout、stderr 和退出码写入文件；不能用工具超时或终端断开判断构建失败。
+
+## 7. 签名门槛
+
+### 7.1 测试包
+
+测试包可以不签名，但发布记录必须明确写出 NotSigned。CSC_IDENTITY_AUTO_DISCOVERY=false 只用于测试包。
+
+### 7.2 正式发布包
+
+正式对外包必须配置组织证书并签名。不要把证书路径和密码写入仓库、脚本或日志。构建完成后必须验证：
+
+~~~powershell
+Get-AuthenticodeSignature 'release\YCode-v0.01-Setup-x64.exe' |
+  Select-Object Status,StatusMessage,SignerCertificate
+~~~
+
+正式发布通过条件为 Status 为 Valid。
+
+builder 日志出现 “signing with signtool.exe” 不等同于文件已签名；必须以 Authenticode 检查结果为准。
+
+## 8. 产物验收
+
+### 8.1 包内 OMP
+
+~~~powershell
+node scripts/verify-bundled-omp.cjs --packaged
+~~~
+
+该命令检查四个 OMP 文件、大小、SHA-256 和 --version。
+
+### 8.2 归档内容
+
+如果系统有 7z，可列出安装程序内容：
+
+~~~powershell
+7z l release\YCode-v0.01-Setup-x64.exe |
+  Select-String 'resources\\omp'
+~~~
+
+必须看到：
+
+~~~text
+resources\omp\omp.exe
+resources\omp\LICENSE
+resources\omp\THIRD-PARTY-NOTICES.txt
+resources\omp\runtime.lock.json
+~~~
+
+### 8.3 实际客户端启动
+
+至少执行一次隔离用户目录启动：
+
+~~~powershell
+$env:YCODE_USER_DATA_DIR = Join-Path $env:TEMP 'ycode-release-smoke'
+New-Item -ItemType Directory -Force $env:YCODE_USER_DATA_DIR
+& '.\release\win-unpacked\YCode.exe'
+~~~
+
+通过标准：
+
+- 主窗口出现，composer 可用
+- 设置中的版本为 0.0.1
+- 模型、会话和专家为空，不读取开发用户数据
+- 打开“关于”或调用生产 IPC，OMP 路径指向安装目录 resources\omp\omp.exe
+- renderer 无未捕获异常
+
+验证完成后关闭客户端，并清理临时用户目录。
+
+### 8.4 哈希
+
+~~~powershell
+$installer = Get-Item 'release\YCode-v0.01-Setup-x64.exe'
+$hash = (Get-FileHash $installer.FullName -Algorithm SHA256).Hash.ToLowerInvariant()
+$hash
+"$hash  $($installer.Name)" |
+  Set-Content -Encoding ascii 'release\SHA256SUMS.txt'
+~~~
+
+记录安装包大小、ProductVersion、Authenticode 状态和 SHA-256。
+
+## 9. 交付物
+
+至少交付：
+
+- release\YCode-v0.01-Setup-x64.exe
+- release\YCode-v0.01-Setup-x64.exe.blockmap
+- release\SHA256SUMS.txt
+- release\使用说明-v0.01.txt
+- release\win-unpacked\ 仅作为免安装包；分发时必须保留整个目录
+
+安装包不携带用户数据。卸载程序保留 %APPDATA%\YCode，这是当前产品行为。
+
+## 10. 失败处理
+
+### GitHub ETIMEDOUT
+
+设置 ELECTRON_MIRROR 和 ELECTRON_BUILDER_BINARIES_MIRROR 后重试。已有 Electron ZIP 可先校验，不要手工删除缓存。
+
+### OMP SHA 或大小不符
+
+停止发布。重新运行 omp:vendor，或从已验收安装包复制完整的 resources\omp 后执行 omp:verify。不得直接使用任意版本 omp.exe。
+
+### 安装程序只剩几百 KB
+
+这通常是 NSIS 最后装配被中途终止。删除以下两个明确的半成品后重新运行 electron-builder：
+
+~~~powershell
+Remove-Item -LiteralPath 'release\YCode-v0.01-Setup-x64.exe' -Force -ErrorAction SilentlyContinue
+Remove-Item -LiteralPath 'release\YCode-v0.01-Setup-x64.__uninstaller.exe' -Force -ErrorAction SilentlyContinue
+npm run dist:installer
+~~~
+
+不要递归删除 release 目录，也不要删除 release\win-unpacked 之外的构建缓存。
+
+### 文件被占用
+
+关闭正在运行的 release\win-unpacked\YCode.exe 和残留 electron-builder 进程后重试。不要结束正在发送消息的开发客户端。
+
+### 构建通过但 OMP 不可用
+
+检查：
+
+~~~powershell
+node scripts/verify-bundled-omp.cjs --packaged
+Test-Path 'release\win-unpacked\resources\omp\omp.exe'
+~~~
+
+如果包内文件存在但仍选择外部 Ygent，检查 detectOmpPath 的优先级和 YCODE_OMP_PATH 是否被当前会话设置。
+
+## 11. 发布记录模板
+
+~~~text
+发布日期：
+发布版本：v0.01
+内部版本：0.0.1
+Git 分支/提交或工作区状态：
+Node/Electron 版本：
+OMP 版本与 SHA-256：
+安装包大小：
+安装包 SHA-256：
+签名状态：
+构建命令与日志：
+OMP RPC ready：
+包内 OMP 路径：
+正式客户端启动结果：
+renderer 异常数：
+未覆盖项：
+~~~
+
+## 12. 当前已知限制
+
+- 当前安装程序为测试包，NotSigned。
+- 本批未执行干净 Windows 设备上的实际安装和卸载。
+- 离屏启动验收使用软件渲染，未覆盖全部 GPU 驱动。
+- 内置 OMP 仅覆盖 Windows x64。
+- OMP 没有模型凭据；用户仍需在设置中配置模型。
+- 包内首次启动不会自动安装本机五个自定义专家。
+
+最后更新：2026-10-18