DSH Desktop Windows NSIS 安装器深度解析yarn dist:win的原生 x64 打包链路与无签名验证门禁【免费下载链接】deepseek-harness-desktop为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」桌面本身也是「插件」。项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktopDSH Desktopdsh-plugin-desktop为 DeepSeek Harness 插件生态提供了一整套跨平台桌面打包体系其中 Windows x64 NSIS 安装器的构建由yarn dist:win命令承载。本文基于仓库中的架构决策记录.agents/notes/implemented/architecture/2026-08-15-windows-local-nsis-installer.md结合 dsh-plugin-desktop/scripts/package-win.ts、dsh-plugin-desktop/scripts/verify-win-installer.ts、dsh-plugin-desktop/scripts/verify-packaged-runtime.ts 等源码完整还原从宿主门禁、打包前 gate、NSIS 配置、无签名纪律、运行时依赖准备到产物校验的整条链路并说明其作为「本地安装 原生 smoke 测试」产物与正式 Authenticode 发布之间的边界。一、这条命令解决什么问题yarn dist:win是 DSH Desktop 提供的原生 Windows x64 打包命令在原生 Windows x64 机器上先运行一组 Windows 可安全执行的构建与测试 gate再由 Electron Builder 生成一个带向导assisted的 NSIS 安装器并对其产物做严格校验。这个安装器面向两个明确目标本地安装支持当前用户安装per-user或提升权限后的所有用户安装elevated all-users支持自选安装目录创建开始菜单与桌面快捷方式原生 smoke 测试安装器 UI、升级与卸载行为、Mica 材质、托盘终端、Windows ACL 沙箱、控制台窗口抑制等平台行为需要在真实 Windows 机器上验证。同时必须明确它的身份边界这是一个未签名unsigned的测试产物不建立 Authenticode 发布身份也不建立 SmartScreen 信誉。官方签名发布走独立的签名命令与证书 preflight。二、命令入口与整体调用链在仓库根目录的 package.json 中dist:win被定义为一条串行命令链dist:win: yarn aa:prepare-release yarn workspace dsh-community-market build yarn workspace dsh-plugin-desktop dist:win即依次执行aa:prepare-release准备 agents-anywhere 发布所需的 vendored 运行时yarn workspace dsh-community-market build构建插件市场yarn workspace dsh-plugin-desktop dist:win真正执行 Windows 打包其脚本定义为node scripts/package-win.ts见 dsh-plugin-desktop/package.json。在 Windows 上通过 Corepack 调用corepack.cmd yarn dist:winBeta 通道对应dist:win:beta指向dsh-plugin-desktop-beta工作区package.json同一套逻辑由 beta 工作区的 dsh-plugin-desktop-beta/scripts/package-win.ts 承载。三、宿主门禁只允许原生 Windows x64scripts/package-win.ts 中的assertWindowsPackageHost对打包宿主做三道硬性检查任何一项不满足都会直接抛错终止检查项要求失败原因平台process.platform win32必须在原生 Windows 宿主构建Node 架构process.arch x64仅支持 x64 NodeNode 版本major 22 minor 19或major 24官方运行时必须自带 CorepackNode 版本要求22.19 或 24.x不是随意约束——Corepack 随 Node 官方发行捆绑打包脚本正是通过corepack yarn ...启动子进程package-win.ts因此要求 Node 自带 Corepack。这与 package.json 中engines: { node: ^22.19.0 || 24.0.0 }的声明一致。四、打包前 Gatecheck:win-package在真正调用 Electron Builder 之前packageWindowsArtifact会通过cmd.exe执行corepack yarn workspace dsh-plugin-desktop check:win-packagepackage-win.ts。该 gate 的内容定义在 package.jsoncheck:win-package: yarn workspace dsh-community-market build yarn run build yarn run typecheck vitest run tests/package.spec.ts tests/package-win.spec.ts tests/desktop-installer-quit.spec.ts tests/installer-nsh.spec.ts tests/update-checker.spec.ts tests/update-download.spec.ts tests/verify-win-installer.spec.ts tests/verify-win-portable.spec.ts tests/verify-packaged-runtime.spec.ts tests/windows-pwsh-sandbox.spec.ts tests/windows-volume-diagnostics.spec.ts tests/window-options.spec.ts tests/safe-mode.spec.ts yarn run verify:closure它由四部分构成构建yarn run build依次执行 Windows/macOS 图标生成、tsdown打包、native-ui 的 Vite 构建、以及所有 TypeScript 声明文件的tsc输出全部 TypeScript compiler facetypecheck对tsconfig.json、tsconfig.client.json、tsconfig.native-ui.json、tsconfig.tests.json、tsconfig.tests.client.json五个工程做--noEmit检查package.jsonWindows 聚焦测试只运行与打包、NSIS、安装器退出、更新下载、PE 产物校验、PWSh 沙箱、窗口选项、Safe Mode 相关的测试套件而非完整跨平台 suite。设计文档特别说明完整跨平台 suite 仍由 CI 持有因为其中部分 POSIX 执行测试如真实登录 shell 测试不是 Windows 程序不应阻塞原生 Windows 打包runtime-closure 验证yarn run verify:closure由 scripts/verify-runtime-closure.mjs 驱动校验全部 first-party 包如deepseek-ai/dsh-*系列在dsh-plugin-desktop的依赖中构成一个封闭可达的运行时图防止出现缺失的一阶依赖导致打包出的运行时无法启动。如果环境变量DSH_PACKAGE_CHECK_ALREADY_RAN1则跳过该 preflightpackage-win.ts避免重复执行。五、NSIS 安装器配置逐项解析安装器的行为完全由 dsh-plugin-desktop/package.json 中 Electron Builder 的build段控制。Windows 目标与 NSIS 段的核心配置如下win: { asar: false, compression: normal, target: [{ target: nsis, arch: [x64] }], icon: build/app-icon.ico }, nsis: { include: installer.nsh, installerIcon: build/app-icon.ico, license: THIRD_PARTY_NOTICES.md, oneClick: false, perMachine: false, allowElevation: true, allowToChangeInstallationDirectory: true, createDesktopShortcut: true, createStartMenuShortcut: true, differentialPackage: false, shortcutName: DSH Desktop, uninstallerIcon: build/app-icon.ico, useZip: false, artifactName: DSH-Desktop-${version}-${arch}-Setup.${ext} }配置项值含义oneClickfalse关闭一键安装使用**带向导assisted**的交互式安装流程perMachinefalse默认按当前用户安装allowElevationtrue允许用户选择提升权限执行所有用户all-users安装allowToChangeInstallationDirectorytrue安装向导中允许更改安装目录createDesktopShortcut/createStartMenuShortcuttrue创建桌面与开始菜单快捷方式differentialPackagefalse关闭差异包仅生成完整安装器shortcutNameDSH Desktop快捷方式名称artifactNameDSH-Desktop-${version}-${arch}-Setup.${ext}安装器产物命名模板compressionnormalNSIS 使用正常压缩档asarfalse应用以物理目录形式随包发布配合 Electron Fuses 的onlyLoadAppFromAsarfalse安装器把 THIRD_PARTY_NOTICES.md 作为许可证展示文件license字段使用build/app-icon.ico作为安装器与卸载器图标并通过include: installer.nsh注入自定义 NSIS 脚本见下文第七节。升级身份的稳定性安装器的升级身份锚定在稳定的应用标识appId: ai.deepseek.dsh.desktoppackage.json上NSIS 的升级/覆盖安装正是基于该 appId 判定「同一产品的新版本」因此设计文档强调 appId 保持稳定是 NSIS 升级身份不丢失的前提。六、无签名纪律剥离证书变量但不禁用资源编辑由于这是一个未签名的本地测试安装器打包脚本执行严格的「无签名纪律」1. 环境变量消毒。withoutWindowsSigningSecretspackage-win.ts把以下 6 个证书发现/密钥变量从环境里全部删除CSC_IDENTITY_AUTO_DISCOVERY CSC_KEY_PASSWORD CSC_LINK CSC_NAME WIN_CSC_KEY_PASSWORD WIN_CSC_LINK删除是对大小写不敏感的key.toUpperCase()后匹配杜绝任何残留证书变量被 Electron Builder 意外拾取。2. Electron Builder 命令行开关package-win.tselectron-builder --win nsis --x64 --publish never --config.win.signExecutablefalse --config.npmRebuildfalse --config.electronFuses.onlyLoadAppFromAsarfalse--publish never禁用一切发布动作--config.win.signExecutablefalse禁用可执行文件签名但不禁用 Windows 资源编辑——图标、版本信息等资源仍会写入 PE 文件这正是设计文档强调「禁用签名但保留资源编辑」的落点--config.npmRebuildfalse禁用 Electron Builder 的通用原生模块重建见下文同时环境变量中显式设置CSC_IDENTITY_AUTO_DISCOVERYfalse双保险阻止证书自动发现。3. Electron Fuses 配合。--config.electronFuses.onlyLoadAppFromAsarfalse与 package.json 中的electronFusesonlyLoadAppFromAsar: false、runAsNode: true、resetAdHocDarwinSignature: true、enableEmbeddedAsarIntegrityValidation: false保持一致应用以物理目录形态运行并保留 RunAsNode 能力供打包后 smoke 使用。七、运行时依赖为什么不需要 Python 和 Visual Studio C Build ToolsWindows 安装器构建对工具链的关键简化在于node-pty直接使用 Windows x64 Node-API 预编译二进制。verify-packaged-runtime.ts中的REQUIRED_WINDOWS_X64_NODE_PTY_ENTRIESscripts/verify-packaged-runtime.ts明确要求以下物理文件必须随包存在node_modules/vscode/ripgrep-win32-x64/bin/rg.exe node_modules/node-pty/prebuilds/win32-x64/conpty.node node_modules/node-pty/prebuilds/win32-x64/conpty_console_list.node node_modules/node-pty/prebuilds/win32-x64/conpty/OpenConsole.exe node_modules/node-pty/prebuilds/win32-x64/conpty/conpty.dll这些是 node-pty 针对 Windows x64 的 Node-API 预编译产物含 ConPTY 控制台基础设施。因此整个安装器构建不依赖 Python 或 Visual Studio C Build Tools避免了 Windows 上最棘手的原生工具链问题。唯一需要「准备」的原生模块是fs-extprepareRuntime调用prepareFsExtForElectron({ platform: win32, arch: x64, ... })package-win.ts其实现位于 scripts/prepare-fs-ext.ts为 Electron ABIabi148准备对应的fs-ext绑定文件Windows 上为fs-ext/prebuilds/win32-x64/electron.abi148.node。打包脚本通过 scripts/electron-builder-environment.ts 注入DSH_ELECTRON_BUILDER_TRAVERSAL_ONLY1约束 Electron Builder 只做有界的物理遍历收集依赖避免 Yarn Berry collector 递归展开整个外层工作区。八、afterPack 钩子打包前最后一道运行时完整性验证Electron Builder 的afterPack钩子指向 scripts/verify-packaged-runtime.tspackage.json在应用归档完成、签名开始之前执行verifyPackagedRuntime应用归档验证校验app.asar或 ASAR-disabled 布局下的物理resources/app包含全部必需条目包括 DSH CLI 运行时文件deepseek-ai/dsh/lib/*.js、PTC preset 输入、pnpm/bin/pnpm.mjs、open/index.js、web 前端index.html等REQUIRED_PACKAGED_RUNTIME_ENTRIES物理运行时树验证app.asar.unpackedsmart-unpack的物理文件必须与 ASAR 头的unpacked标记精确一致不允许出现「头外物理文件」「头内未标记」「标记却缺失」三类不一致verifySelectiveUnpackedRuntimeWindows x64 node-pty prebuilds 验证上面第五节列出的 5 个 Windows 物理条目必须存在smart-unpack 预算物理载荷受预算约束——总量不超过 1500 个文件 / 128 MiBpnpm 的 smart-unpack 不超过 32 个文件 / 32 MiBverify-packaged-runtime.ts架构门禁Windows 平台的arch必须是 x64context.arch ! 1即抛错见 verify-packaged-runtime.ts。任何缺失都会让afterPack以 promise 拒绝的形式在 NSIS 打包之前失败保证进入 NSIS 阶段的应用运行时是完整、封闭的。九、产物验证第二道 gate精确版本名 PE 头校验NSIS 安装器生成后打包脚本运行node scripts/verify-win-installer.tspackage-win.tsverifyWindowsInstallerscripts/verify-win-installer.ts执行第二道产物门禁精确版本化路径版本不是写死的而是从dsh-plugin-desktop/package.json实时读取readVersion然后定位两个文件——安装器dist/DSH-Desktop-${version}-x64-Setup.exe解包应用dist/win-unpacked/DSH Desktop.exe因此旧版本遗留的安装器无法满足这道 gate——文件名里嵌入了版本号版本不匹配即校验失败非空常规文件statSync确认两个文件都是大小 ≥ 68 字节的常规文件verify-win-installer.tsPE 头校验读取 DOS 头确认前两个字节为MZ再按0x3c处的 PE 偏移读取 4 字节签名必须等于PE\0\0assertPortableExecutable见 verify-win-installer.ts。通过后控制台输出Windows installer verification passed: installerPath。对应的聚焦测试见 tests/verify-win-installer.spec.ts 与 tests/package-win.spec.ts。十、安装/升级时的进程交接installer.nsh 的优雅退出NSIS 自定义脚本 dsh-plugin-desktop/build/installer.nsh 通过customCheckAppRunning宏处理「应用正在运行时升级安装」的场景这是升级可靠性的关键一环先通过FIND_PROCESS DSH Desktop.exe精确匹配应用进程——注意是应用可执行文件名而不是$INSTDIR下所有辅助程序这保留了 #469 修复无关的 helper 进程永远不会阻塞升级若进程在运行优先执行优雅退出交接$INSTDIR\DSH Desktop.exe --dsh-installer-quit通过 Electron 的单实例通道让应用自行有序关闭对应 desktop-installer-quit.ts 实现的 orderly shutdown 路径2.0.2 及更早版本忽略该参数因此保留 scoped builder 回退之后进入等待循环每 500ms 检查一次进程是否退出最多等待 30 秒$R1 60次 × 500ms以容忍慢磁盘、杀软钩子和较大的物理运行时超时后走 scoped 强制关闭路径弹出提示框征得用户同意再用KILL_PROCESS按精确可执行名终止进程并持续确认退出。这套「先优雅、后强制、全程精确匹配进程名」的策略保证了覆盖安装upgrade不会因残留进程失败同时不会误杀无关进程。相关行为由 tests/installer-nsh.spec.ts 与 tests/desktop-installer-quit.spec.ts 覆盖。另外卸载应用时安装器保留 DSH 用户数据profile 与用户目录不随卸载删除这是设计文档明确承诺的卸载行为。十一、原生发布边界哪些行为仍必须回到 Windows 机器验证设计文档划出了一条清晰的「原生发布边界」Windows 打包必须在原生 Windows x64 依赖安装上进行这样 Koffi 及其他平台相关包才能解析为 Windows 变体koffi在 package.json 中直接依赖。在这个前提下以下行为仍属于Windows 机器验证 gate不会因为本地生成了 NSIS 安装器就被视为通过安装器 UI 的实际显示与交互升级与卸载行为含被安装/卸载的应用在目标机器上的表现Mica 材质渲染托盘终端tray terminal功能Windows ACL 沙箱windows-acl-runner.ts的实际权限行为控制台窗口抑制Authenticode 签名与 SmartScreen 信誉。与此同时dist:win产物是未签名的它不会建立 Authenticode/publisher 身份也不会积累 SmartScreen 信誉更新交接update handoff只校验下载容器而非发布者身份。因此正式发布链路要求独立的签名命令走专用证书 preflight——校验安装器、卸载器与应用三者的签名而不是削弱这个未签名命令的纪律。十二、相关源码与测试索引围绕本文主题可以在仓库中继续深入阅读以下文件架构决策记录.agents/notes/implemented/architecture/2026-08-15-windows-local-nsis-installer.md打包脚本scripts/package-win.ts、scripts/package-win-portable.ts产物校验scripts/verify-win-installer.ts、scripts/verify-packaged-runtime.ts运行时封闭图scripts/runtime-closure.mjs、scripts/verify-runtime-closure.mjsNSIS 自定义逻辑build/installer.nsh、src/desktop-installer-quit.ts构建配置dsh-plugin-desktop/package.json 的build/nsis段聚焦测试tests/package-win.spec.ts、tests/verify-win-installer.spec.ts、tests/installer-nsh.spec.ts、tests/desktop-installer-quit.spec.ts、tests/verify-packaged-runtime.spec.ts使用说明dsh-plugin-desktop/README.md及 dsh-plugin-desktop/README.zh.md中的dist:win章节十三、小结一句话记住这条链路yarn dist:win宿主门禁Windows x64 Node 22.19/24.x→check:win-package构建与聚焦测试 gate → runtime-closure 校验 → 证书变量剥离与signExecutablefalse→ 原生依赖准备node-pty prebuilds fs-ext ABI 绑定→ Electron Builder NSIS 打包 → afterPack 运行时完整性验证 → 精确版本名 MZ/PE 头产物校验。它是一条「为本地安装与原生 smoke 测试而设计」的完整闭环不依赖 Python/VS Build Tools、不接触任何签名材料、不发布、不建立 Authenticode 身份但每一步都通过源码级校验确保产物可用——这正是它作为发布前回归防线与未来签名命令前置基础的价值所在。【免费下载链接】deepseek-harness-desktop为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」桌面本身也是「插件」。项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考