351 lines
9.6 KiB
Markdown
351 lines
9.6 KiB
Markdown
# 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
|