admin/ycode

0 Fork 0

Files

T

xiaohan.yuan 9a1f182397 refactor(agent): replace OMP with Claude Code kernel

2026-10-20 14:47:56 +08:00

9.5 KiB

Raw Blame History

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

发版前同时更新以下内容：

package.json 顶层 version。
package-lock.json 顶层和根包 version。
package.json 的 build.win.artifactName。
发布说明中的文件名、大小和 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 中的测试客户端保持运行，避免文件锁

进入仓库根目录并检查工具：

Set-Location 'C:\Users\Administrator\code\YCode'
node --version
npm --version
Get-Command node,npm

干净环境和 package-lock.json 变更后使用：

npm ci

仅日常沿用现有 node_modules 时，可先执行：

npm ls --depth=0

4. 发版前检查

4.1 源码和变更范围

确认工作区中的改动都属于本次发布；当前项目允许保留未提交修改，但发布记录必须注明构建来源。

git status --short
git diff --stat

不要覆盖或回退其他并行任务的修改。

4.2 静态检查

npm run typecheck

4.3 OMP 资源与许可

内置资源位于 resources\omp，必须包含：

omp.exe
LICENSE
THIRD-PARTY-NOTICES.txt
runtime.lock.json

校验固定版本和摘要：

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

如果资源刚清空，先从固定上游恢复：

node scripts/vendor-omp.mjs

如果本机已有经过校验的 Ygent 安装，可只导入二进制：

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 镜像：

$env:ELECTRON_MIRROR = 'https://npmmirror.com/mirrors/electron/'
$env:ELECTRON_BUILDER_BINARIES_MIRROR = 'https://npmmirror.com/mirrors/electron-builder-binaries/'

测试版没有证书时关闭证书自动发现：

$env:CSC_IDENTITY_AUTO_DISCOVERY = 'false'

镜像只用于下载构建工具，不改变应用运行时地址。不要在源码或脚本中写死个人代理。

常见缓存位置：

%LOCALAPPDATA%\electron\Cache
%LOCALAPPDATA%\electron-builder\Cache

electron-builder 的生产依赖收集可能需要数分钟。期间不要重复启动第二个打包进程或误判为卡死。

6. 构建安装程序

标准入口：

npm run dist:installer

该命令依次执行：

omp:vendor：恢复并校验内置 OMP。
npm run build：
- TypeScript node/web 检查
- electron-vite main/preload/renderer 构建
electron-builder --win nsis：
- 生成 release\win-unpacked
- 复制 OMP、模型元数据和图标 extraResources
- 生成 NSIS 安装程序

仅需免安装目录时：

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 正式发布包

正式对外包必须配置组织证书并签名。不要把证书路径和密码写入仓库、脚本或日志。构建完成后必须验证：

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

node scripts/verify-bundled-omp.cjs --packaged

该命令检查四个 OMP 文件、大小、SHA-256 和 --version。

8.2 归档内容

如果系统有 7z，可列出安装程序内容：

7z l release\YCode-v0.01-Setup-x64.exe |
  Select-String 'resources\\omp'

必须看到：

resources\omp\omp.exe
resources\omp\LICENSE
resources\omp\THIRD-PARTY-NOTICES.txt
resources\omp\runtime.lock.json

8.3 实际客户端启动

至少执行一次隔离用户目录启动：

$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 哈希

$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：

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 不可用

检查：

node scripts/verify-bundled-omp.cjs --packaged
Test-Path 'release\win-unpacked\resources\omp\omp.exe'

如果包内文件存在但仍选择外部 Ygent，检查 detectOmpPath 的优先级和 YCODE_OMP_PATH 是否被当前会话设置。

11. 发布记录模板

发布日期：
发布版本：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

9.5 KiB Raw Blame History Unescape Escape