OpenCreator Desktop Windows 发布指南NSIS 打包、Codex 解析、深链接与进程回收实战【免费下载链接】OpenCreatorFormerly KrillinAI. Open-source AI workspace for creators, powered by Codex. Create videos, images, voice, avatars, translations, and edits with Agents in one place.项目地址: https://gitcode.com/GitHub_Trending/kr/OpenCreatorOpenCreator前身 KrillinAI是基于 Codex 的开源 AI 创作工作台Desktop 是其本地桌面壳层负责拉起 Daemon 与 Codex、承载 Dashboard 并提供托盘/通知/深链接体验。本文以仓库内 docs/operations/opencreator-desktop-windows-release.md 为主线结合 apps/desktop 下的源码与打包脚本系统讲解 Windows x64 平台从本地构建、安装包配置、Codex 解析、进程回收、代码签名到发布验收的完整流程。读完本文你将掌握 OpenCreator Desktop 在 Windows 上的发布全貌并能在自己的环境中复现构建、验证安装包与排查发布问题。1. 发布目标与平台前提OpenCreator Desktop 的 Windows 发布目标非常明确平台仅支持 Windows 10/11 x64安装包格式为NSIS来自 apps/desktop/electron-builder.yml 中win.target: nsis的配置。Codex 依赖用户本机需预先安装 Codex CLIOpenCreator不依赖用户安装 Node.js因为 Daemon、Creator Runtime、Stickman Runtime 等都以extraResources的形式内置于安装包中见 apps/desktop/electron-builder.yml 中daemon/dist、codex-runtime、creator-runtime、stickman-runtime等打包条目。这意味着发布物是一个自包含的桌面应用 外部 Codex CLI的组合应用本体Electron 主进程、Web Dashboard、Daemon、各创作 Runtime全部随安装包分发唯一的外部依赖是用户环境中的 Codex 可执行文件。2. Codex 解析规则查找顺序与可执行文件形态Desktop 启动时需要一个可用的 Codex解析逻辑在 apps/desktop/src/main/codex-resolver.tsWindows 上的查找顺序如下用户上次真实 Probe 成功的绝对路径持久化于设置中来自BootstrapController对codexRuntimeMode: external与externalCodexBin的保存见 apps/desktop/src/main/bootstrap-controller.ts。当前进程PATH。where.exe codex返回的绝对路径Windows 专属的路径定位命令。%APPDATA%\npm。%USERPROFILE%\AppData\Roaming\npm与上一条等价覆盖不同环境变量展开方式。%USERPROFILE%\.local\bin面向将 CLI 安装到用户目录工具链的场景。支持的可执行文件形态包括codex.exe codex.cmd codex.bat关键实现细节.cmd和.bat属于命令包装脚本直接使用 Nodespawn无法执行因此源码中统一通过cross-spawn启动。这一点在 apps/desktop/scripts/verify-package.mjs 的assertPortableDaemonDependencies()中也有印证——Daemon 打包后必须能require(cross-spawn)以确保 Windows 包装脚本可被正常拉起。从源码结构可以进一步推断解析的两条路径bundled 模式读取manifest.json校验version/commit/platform/arch与当前应用严格匹配并对主程序做 SHA-256 哈希校验与路径越界检查safeRuntimePath防止包内二进制被替换或路径逃逸。external 模式对用户选择的路径执行validateManualCodexPath必须存在、必须是文件、不能是符号链接、文件名必须以codex.exe结尾随后通过probeVersion探测版本要求与BUNDLED_VERSION源码中为0.149.0一致。解析失败时CodexResolutionError携带codex_runtime_missing、codex_runtime_version_mismatch、codex_runtime_hash_mismatch等错误码与完整诊断信息最终驱动 Desktop 进入诊断页而不是登录页见下文验收清单第 3 条。3. 本地构建命令、产物与构建清单Windows 本地构建在 PowerShell 中执行$env:OPENCREATOR_DESKTOP_TARGET_PLATFORM win $env:OPENCREATOR_DESKTOP_TARGET_ARCH x64 $env:CSC_IDENTITY_AUTO_DISCOVERY false pnpm desktop:release环境变量含义变量取值作用OPENCREATOR_DESKTOP_TARGET_PLATFORMwin指定目标平台脚本会归一化为 electron-builder 的win32见 apps/desktop/scripts/package-release.mjs 的normalizePlatform()OPENCREATOR_DESKTOP_TARGET_ARCHx64目标架构CSC_IDENTITY_AUTO_DISCOVERYfalse关闭自动证书发现在无签名证书的本机构建中避免 electron-builder 误选证书同一逻辑也会在CSC_LINK未设置时自动注入package-release.mjs内部会按阶段依次执行构建 KrillinAI CLI/Serverscripts/build-krillinai.mjs→ 构建 Desktop → 准备 Daemon 与 Webprepare-daemon.mjs→ 准备 Creator Runtime → 准备 Stickman Runtime → 准备 Codex Runtime → 调用electron-builder --win nsis --x64。注意 Windows 分支中若设置了WIN_CSC_LINK会映射为CSC_LINK/CSC_KEY_PASSWORD供 electron-builder 使用。主要产物位于apps/desktop/release/ ├── win-unpacked/ ├── OpenCreator Setup version.exe ├── OpenCreator Setup version.exe.blockmap └── latest.yml其中latest.yml是 electron-updater 的更新元数据对应 apps/desktop/electron-builder.yml 中的publish配置.exe.blockmap用于差分更新本仓库配置中nsis.differentialPackage: false即关闭差分包。构建清单build manifest打包完成后还必须存在apps/desktop/release/opencreator-desktop-build-manifest.json这份清单由 apps/desktop/scripts/package-release.mjs 在打包后生成记录platform、arch、packageRoot、commit、各 Runtime 的哈希Web 构建、Creator Agent Runtime、Stickman Runtime、Codex Runtime、Krillin CLI 版本等以及每个产物的sha256。发布约束清单中的platform必须为win32、arch必须为x64、packageRoot必须唯一指向win-unpacked。verify:packageapps/desktop/scripts/verify-package.mjs与 packaged E2E只能使用该清单定位产物禁止扫描旧目录猜测。脚本还会校验win-unpacked目录必须唯一存在findFreshPackageRoot对候选目录数量做精确匹配并在GITHUB_ENV存在时把清单路径与包根目录写入环境变量供后续 job 消费。4. 安装与数据安全升级不丢数据NSIS 安装行为在 apps/desktop/electron-builder.yml 中配置nsis: oneClick: false allowToChangeInstallationDirectory: true deleteAppDataOnUninstall: false differentialPackage: false useZip: true非 one-click 安装安装向导允许用户自行选择安装目录allowToChangeInstallationDirectory: true。卸载不删除用户数据deleteAppDataOnUninstall: false保证卸载过程不触碰 OpenCreator 的用户数据。升级不丢数据升级覆盖安装不得删除 Desktop 设置、SQLite 数据库、任务、附件与日志。数据落位约定用户数据位于 ElectronuserData对应目录开发模式下由resolveDesktopUserDataPath重定向见 apps/desktop/src/main/main.ts。运行时配置、数据库、日志通过opencreator/config的resolveOpenCreatorPaths计算dataDir、logsDir、configFile。Codex 配置继续位于用户的CODEX_HOME不被 Desktop 接管或移动用户已有的 Codex 登录态与配置在安装/升级后保持可用。从源码看Daemon 启动时会把CODEX_HOME、OPENCREATOR_CODEX_BIN、OPENCREATOR_DATA_DIR等通过环境变量传入子进程buildDaemonEnvironment见 apps/desktop/src/main/daemon-manager.ts数据路径在设计上与安装目录解耦这是升级/卸载不丢数据得以成立的基础。5. 协议、托盘与通知5.1 深链接协议opencreator://安装包通过 electron-builder 注册协议见 apps/desktop/electron-builder.yml 的protocols段scheme 为opencreator应用运行期由registerApplicationProtocol调用app.setAsDefaultProtocolClient(opencreator)apps/desktop/src/main/main.ts。协议路由的解析在 apps/desktop/src/main/deep-link-manager.tsfindDeepLink(argv)从命令行参数中取出以opencreator://开头的参数。deepLinkToRoute(value)把 URL 转换为 Dashboard 的 hash 路由支持opencreator://tasks→#/tasksopencreator://new→#/opencreator://thread/threadId→#/thread/threadId并支持runId、approvalId查询参数编码Thread、Run、Approval 参数可正确编码。安全约束源码中体现明显所有 segment 与 query 均做严格解码strictDecode拒绝非法%编码与替换字符\ufffd。ID 校验上限 512 字节且禁止控制字符。解析失败一律返回undefined不进入路由。必须验证的行为opencreator://tasks打开现有OpenCreator 实例。Thread、Run、Approval 参数能正确编码。第二次启动不创建第二个 Runtime——通过app.requestSingleInstanceLock()实现单实例锁apps/desktop/src/main/main.ts第二实例的 argv 交给second-instance事件处理仅复用窗口与导航不重新拉起 Daemon。关闭窗口默认只隐藏到托盘window-all-closed事件中注释明确tray and Runtime intentionally remain active且托盘菜单open回调会windowManager.show()。托盘退出会有序停止 Daemonbefore-quit中依次执行windowManager.beginQuit()、notifications.stop()、telemetry.stop()、bootstrap.stop()、loginShellTask.cancel()后logger.flush()再真正退出。通知点击复用现有窗口NotificationManager通过navigate回调跳转。额外说明Windows 第二实例参数由findDeepLink(argv)解析处理路径是先拿深链接 → 转路由 → 投递给工作区不会绕过 Codex 启动门禁即不会跳过 Probe / 引导流程直接进主界面。5.2 窗口与导航细节开发模式下 IPC 只信任127.0.0.1:19861来源生产模式只信任opencreator-app://app/opencreator-app://bootstrapassertTrustedSender/assertTrustedWorkspaceSender。工作区加载设有超时WORKSPACE_READY_TIMEOUT_MS 10_000见 apps/desktop/src/main/window-manager.ts超时或渲染进程消失会进入引导失败流程。6. 进程回收Windows 进程树的优雅与强制终止Daemon 与 Codex 子进程退出时的兜底回收使用 Windows 原生命令taskkill.exe /PID pid /T taskkill.exe /PID pid /T /F实现位于 apps/desktop/src/main/daemon-manager.ts 的terminateWindowsProcessTree(pid, force)通过spawn(taskkill.exe, [/PID, String(pid), /T, ...(force ? [/F] : [])])异步启动。不带/F是正常退出先尝试优雅回收带/F是超时后的强制终止。带 2 秒超时兜底超时后child.kill()并 resolve避免回收流程自身挂死。必须异步启动并等待不得使用spawnSync阻塞主线程——否则 Windows 上进程树回收会卡死 Electron Main。DaemonManager内部维护codexPids集合Daemon 通过 IPC 上报codex_child_started/codex_child_exitedparseDaemonProcessMessage退出或超时时对这些 PID 做整树回收。stop()的回收阶梯为发shutdown消息 → 等待 →child.kill()→ 非强制回收 Codex → SIGKILL非 Windows→ 强制回收。验收时必须确认正常退出后无 Daemon 残留。Probe 超时后无 Codex 残留。Daemon 被强杀后无 Codex 子进程树残留。应用崩溃恢复最多自动重启一次——由 apps/desktop/src/main/bootstrap-controller.ts 的recoverUnexpectedExit()控制automaticRestarts 1时进入DAEMON_RESTART_EXHAUSTED失败态不再无限重启运行稳定 5 分钟后计数器归零armStableTimer。7. Windows 签名与 Authenticode 验证CI 签名使用两个环境变量WINDOWS_CERTIFICATE证书内容BASE64 编码的 PFX。WINDOWS_CERTIFICATE_PASSWORD证书密码。打包脚本apps/desktop/scripts/package-release.mjs在检测到WIN_CSC_LINK时将其映射为CSC_LINK/CSC_KEY_PASSWORD交给 electron-builder没有证书时设置CSC_IDENTITY_AUTO_DISCOVERY false生成的 unsigned 安装包只能用于内部测试。正式发布前必须验证 Authenticode 签名Get-AuthenticodeSignature .\OpenCreator Setup version.exe | Format-List预期Status为Valid。若状态为NotSigned或HashMismatch说明签名缺失或二进制在签名后被改动需要重新打包。8. 验收清单8.1 CI 自动化.github/workflows/desktop-release.yml的windows-x64job 必须按序执行pnpm testVitest 单元测试。pnpm typechecktsc 类型检查。pnpm desktop:release生成 NSIS 安装包、blockmap、latest.yml和构建清单。pnpm --filter opencreator/desktop e2e:packagePlaywright packaged E2E。pnpm --filter opencreator/desktop verify:package——由打包脚本自动调用package-release.mjs在 electron-builder 之后以清单路径与包根目录为环境变量调用verify-package.mjs。上传安装包、更新元数据和构建清单。verify:packageapps/desktop/scripts/verify-package.mjs在 Windows 上重点校验OpenCreator.exe存在、app.asar内含必需入口、Daemon 的better_sqlite3原生模块存在于build/Release、Web 构建哈希与apps/web/dist一致、各 RuntimeCreator/Codex/Stickman与构建清单哈希一致、无本地开发数据泄漏assertNoLocalData、体积上限Desktop 包不超过 1536 MB 等以及Electron Fuses配置RunAsNode、EnableNodeOptionsEnvironmentVariable、EnableNodeCliInspectArguments必须为禁用EnableEmbeddedAsarIntegrityValidation、OnlyLoadAppFromAsar必须为启用。现状说明截至 2026-07-16该工作流已通过 actionlint 1.7.7 静态检查但尚未在 GitHub Actions Windows runner 实际执行因此不能标记为PASS。8.2 实机验收Windows 实机验收条目终端执行where.exe codex能找到与 Desktop 相同路径。真实 hello Probe 成功。Probe 失败进入诊断页不显示登录页面。Dashboard JSON、SSE 和二进制代理正常即 apps/desktop/src/main/protocol-handler.ts 中的opencreator-app协议处理与 Daemon 连接代理。连续刷新五次不重复 Probe——由environmentFingerprint基于codexBin、codexHome、PATH的 SHA-256与verifiedFingerprint比对实现apps/desktop/src/main/bootstrap-controller.ts指纹一致时requireProbe false。关闭窗口后任务继续托盘驻留。深链接和通知点击可用。安装、覆盖升级和卸载不删除用户数据。Electron Fuses、ASAR 完整性和原生 SQLite 在 Windows 正式包中通过。Windows Defender 和 SmartScreen 结果已记录。9. 已知限制与发布状态当前开发环境为 macOS arm64无法完成以下 Windows 专属验证NSIS 构建、packaged E2E、安装/覆盖升级/卸载、托盘、通知、协议注册、进程树回收与 Authenticode 实机验证。上述项目在最终验收报告中保持BLOCKED_ENV或NOT_RUN状态——这也是文档将CI 真实执行 Windows 实机验收明确区分的根本原因发布状态必须基于实际证据未执行的项不得标记为通过。结语OpenCreator Desktop 的 Windows 发布不是一个一键打包的动作而是一套从 Codex 解析codex-resolver.ts、NSIS 配置electron-builder.yml、深链接/托盘/通知deep-link-manager.ts、main.ts、进程树回收daemon-manager.ts到签名验证与双轨验收的完整工程体系。其设计主线可以概括为三点外部 Codex 与内置 Runtime 分离、升级/卸载不碰用户数据、任何发布声明都必须有实机或 CI 证据支撑。对希望在 Windows 上打包分发 Electron 外部 CLI 工具的团队而言这份发布说明连同仓库内的打包与校验脚本是一份可直接借鉴的工程范本。【免费下载链接】OpenCreatorFormerly KrillinAI. Open-source AI workspace for creators, powered by Codex. Create videos, images, voice, avatars, translations, and edits with Agents in one place.项目地址: https://gitcode.com/GitHub_Trending/kr/OpenCreator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考