# YCode Windows 分发包 SOP

版本：2026-10-18  
适用：Windows x64、Electron 37、NSIS、内置 OMP 18.6.3  
最后一次验证产物：YCode v0.01（内部版本 0.0.1）

## 1. 目标与发布边界

本流程用于生成可分发的 Windows 安装程序和免安装目录包，并确保内置 OMP、模型元数据和第三方许可完整。

发布包不得包含：

- 当前用户的模型 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、模型元数据和图标 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