DeepSeek Harness 桌面端

English | 中文

桌面应用是包裹 dsh Web UI 的 Electron 壳。它不打开监听端口：内置的上游 Node.js 子进程启动已安装的 dsh 项目，带版本的分帧字节管道在没有外层 Base64 信封的情况下承载 Fetch 请求与流式响应，Node IPC 承载生命周期控制，dsh-app:// 则提供与后端版本匹配的客户端资源。

关键技术决策

决策	原因	直接结果
发布身份	桌面壳 API、Web 客户端、后端与插件依赖图作为一个组合完成验证；独立版本会产生未经验证的组合，并让更新可用性含糊不清。	Electron 与 @deepseek-ai/dsh 始终使用同一精确版本。即使桌面壳代码不变，升级 dsh 也必须发布新 Desktop 版本。
运行时	Electron 的 Node.js 带有 Electron 补丁、fuse、ABI 与生命周期约束，而系统运行时和包管理器状态不可控。	dsh 通过内置的上游 Node.js 运行，所有包操作都使用内置 pnpm。Electron 的 Node.js、系统 Node.js、系统 pnpm 与用户的包管理器配置都不进入执行路径。
包来源	即使离线，启动时安装核心依赖也会增加开销。	extraResources/dsh 携带完整生产依赖树；profile 只安装外部插件。
共享模块	宿主 API 可能依赖模块实例身份。	Desktop 用目录软链接或 Windows junction 把每个内置第一方包连接到 profile；普通插件依赖保留在本地。
状态归属	共享可执行依赖图会让 CLI（命令行界面）与 Desktop 相互改变 dsh、Cordis、插件或原生模块版本，而两个桌面进程还可能争用同一个 profile。	Electron 在访问任何 profile 前获取进程生命周期单实例锁，并独占 $DSH_HOME/profiles/desktop 及其包管理器状态。CLI 与 Desktop 共享 $DSH_HOME 下受支持的产品数据，但绝不共享可执行包、插件激活、锁文件或 node_modules。
通信	监听 Web 服务会引入端口归属、认证、CORS 与暴露风险；Electron 与上游 Node.js 之间也需要明确的跨进程协议。	应用不打开 Web 端口。dsh-app:// 承载 Web 资源和 Fetch 流量；分帧字节管道以背压传输有界请求与响应分块，Node IPC 只承载子进程生命周期控制。
插件变更	包安装和 Host 启动可能失败。	Desktop 停止 Host 后直接修改当前 profile。失败保留部分修改供用户修复，不自动回滚 profile。
更新	桌面壳与 dsh 独立更新会重新产生版本分裂，而桌面壳未变化的数据块不应强制完整传输。	Electron 壳、匹配的 dsh 运行时、Node.js 与 pnpm 组成一个已签名更新单元。平台更新产物可以复用未变化的数据块，但运行时版本选择绝不脱离 Desktop 发布。

Electron 打包与更新 Agent Note 记录了这些决策背后的理由、替代方案、安全约束和发布验证要求。

安装归属

Electron 拥有 $DSH_HOME/profiles/desktop。其 dependencies 只包含已安装外部插件的精确版本；dsh.profile.bundles 包含内置 bundle，后接已启用插件。签名应用从 resources/dsh 提供 dsh、私有 Desktop Host 及其生产依赖。共享包链接解析到这些实际目录。宿主与插件在同一个内置上游 Node 进程中执行，使用正常的 realpath 解析；Desktop 不启用 --preserve-symlinks。CLI 不能启动或修改此 profile。

本地启动页提供启动状态和可用恢复操作；加载后的 dsh 渲染进程仅接收桌面协议标记。独立插件窗口接收结构化的列表、安装、删除、更新和更新检查操作；两个渲染进程都无法访问文件系统、原始 Electron IPC、shell 或任意 pnpm 参数。

Electron 根据应用 locale 选择类型化的英文或中文桌面壳文案，并以英文作为 fallback。菜单、原生对话框、启动页与插件管理渲染进程使用同一 locale 数据；仓库的 Client UI i18n gate 会检查这些桌面源文件。

运行时与插件激活

签名资源中的 resources/dsh/desktop-runtime.json 绑定 shell 版本、内置 Node 版本、平台、架构、共享包版本和最终文件清单。启动读取元数据，并检查共享包记录。发布 schema、shell 版本、目标兼容性和文件完整性在打包时验证。首次启动不会把核心包复制到 profile 存储或通过 pnpm 安装核心包。

1. 主窗口在 profile 准备或后端启动前显示本地加载页。新 profile 创建清单和共享包链接，保留无关文件，然后启动一次实际后端。未变化的启动复用 profile，不扫描已安装插件的清单。
2. 兼容的应用升级在当前 profile 中刷新共享链接，并检查已启用插件的 peer 要求。插件文件、配置、版本和锁文件留在原处；不运行 pnpm。
3. 内置 Node 版本、平台或架构变化时，禁用脚本重新安装锁定的插件依赖图，验证并链接宿主包，然后运行已批准的待执行构建并再次验证。
4. 插件添加、更新和删除使用内置 pnpm 及 Desktop 独有的包管理器状态。保留的宿主包必须声明为 peer；共享包的嵌套副本和别名会被验证拒绝。普通插件依赖必须解析到 profile 内部。
5. 插件变更在直接修改当前 profile 前停止后端。准备成功后启动 Host。包操作或 Host 启动失败会保留已修改文件并报告错误。未完成的包操作保留标记，使下次启动重试锁定依赖的安装和待执行构建。Desktop 不创建 staging 目录、激活日志或回滚副本。

加载页不依赖 Host。错误页提供重启和重装指导。只有已打包应用的资源支持 profile 恢复时，才提供禁用插件和重置 Desktop；开发模式和早期初始化失败只提供重启。应用菜单仍提供插件管理器入口。每次后端启动前都会检查运行时标识；插件修改不自动回滚。

重置删除 $DSH_HOME/profiles/desktop 中除所持事务锁外的所有条目，然后初始化内置 profile。它删除 Desktop 配置和已安装第三方包，不保留备份。共享任务、设置和 Harness-home .env 保持不变。壳资源和 preload 失败时使用独立文档显示可用恢复操作和诊断；其控件不依赖 preload。

包事务独占持有 $DSH_HOME/profiles/desktop/lock，直到 pnpm 进程退出。重置保留目录及其锁，直到初始化和 Host 启动完成。共享链接在 macOS/Linux 使用目录软链接，在 Windows 使用 junction；清理只移除链接，不删除其目标。共享包使用文件系统的规范路径识别，因此 Windows 路径大小写变化不会单独触发 profile 激活。原生构建遵循 profile 中经过审查的 allowBuilds 列表；新安装的包如果需要构建但未在列表中获准，事务会失败。

开发

dev:desktop 会构建当前 Host、客户端 bundle、Web 前端和 Electron 壳，把已构建的 CLI 包、私有 Desktop Host 包及其 workspace 依赖投影为一次性桌面 npm 项目，然后直接启动 Electron；这条路径不下载安装包内的 Node.js，也不从 npm 解析 dsh：

pnpm run dev:desktop

开发 Harness 状态默认写入 apps/desktop/.desktop-build/development/home，一次性 npm 项目位于 apps/desktop/.desktop-build/development/project，Electron 浏览器数据则位于 apps/desktop/.desktop-build/development/electron-user-data。因此，会话、设置、凭据、包链接和浏览器数据都不会进入用户正常使用的 Harness home；显式 DSH_HOME 只会替换开发 Harness home。Renderer DevTools 默认自动打开，Main、Renderer 和 dsh Host 调试端口依次为 9229、9222 和 9230。DSH_DESKTOP_MAIN_INSPECT_PORT、DSH_DESKTOP_RENDERER_DEBUG_PORT 与 DSH_DESKTOP_HOST_INSPECT_PORT 可以替换这些端口，DSH_DESKTOP_OPEN_DEVTOOLS=0 则保持 Renderer 调试窗口关闭。

显式构建完成后，start:desktop 会重新生成一次性项目，并跳过构建直接启动已有产物：

pnpm run start:desktop

Workspace 开发使用调用命令的 Node.js 运行当前 CLI 与私有 Desktop Host 包，并禁用桌面包修改；只有该模式明确链接的一次性 profile 可以从自身目录外解析 bundle。需要验证内置 Node.js、内置 pnpm、内置 dsh 资源、插件安装和修复时，应运行未封装安装器的应用目录。

打包

正常打包只需执行一条完整命令。该命令会先准备发布资源，再生成宿主平台的安装包与更新元数据。所有目标都要求通过 DSH_DESKTOP_APP_ID 提供反向域名形式的应用 ID。macOS 目标还要求通过 DSH_DESKTOP_MACOS_SIGNING_IDENTITY 提供 electron-builder 证书限定名，通过 DSH_DESKTOP_MACOS_TEAM_ID 提供对应的 10 字符 Apple Team ID，并提供一套完整的 notarytool 凭据方案。App Store Connect API Key 方式使用以下变量：

export DSH_DESKTOP_APP_ID='<reverse-DNS application ID>'
export DSH_DESKTOP_MACOS_SIGNING_IDENTITY='<certificate name without the Developer ID Application prefix>'
export DSH_DESKTOP_MACOS_TEAM_ID='<10-character Apple Team ID>'
export APPLE_API_KEY='<absolute path to the .p8 file>'
export APPLE_API_KEY_ID='<App Store Connect API Key ID>'
export APPLE_API_ISSUER='<App Store Connect issuer UUID>'

无需提前执行 prepare:desktop：

pnpm run package:desktop

发布自动化使用固定目标命令，确保运行时准备、dsh 准备与 electron-builder 接收相同的平台和架构：

pnpm run package:desktop:mac:arm64
pnpm run package:desktop:mac:x64
pnpm run package:desktop:win:x64

macOS arm64 命令要求 Apple Silicon。macOS x64 命令可以在 Intel macOS 或带 Rosetta 的 Apple Silicon 上运行。Windows x64 命令要求 Windows x64。Linux 不是受支持的 Desktop 发布目标。

每个目标都在 apps/desktop/.desktop-build/targets/<target>/ 下持有自己的打包输入、已准备运行时、包集合、dsh 依赖树、pnpm 准备状态、未打包应用、更新元数据和最终产物。Node.js 归档缓存继续由 .desktop-build/downloads 共享，因为每个归档文件名都包含版本、平台和架构，并且在解包前经过验证。目标构建绝不读取其他目标的可变准备状态。

运行时文件筛选

生产包首先经过 npm 发布规则和依赖安装。桌面文件规则随后在签名和完整性封存之前过滤不可变的 resources/dsh/node_modules 副本。它排除 TypeScript 声明、明确属于 JavaScript/CSS/TypeScript 的 source map、TypeScript 构建缓存、Domino 测试目录、指定的原生编译产物，以及其他平台的 node-pty 预构建文件。它保留运行时 JavaScript、原生模块及其 DLL/EXE 辅助程序、WASM、未知资源、许可证和声明。规则不会修改 npm tarball、内置包管理器或用户安装的插件文件。

打包应用运行编译后的 JavaScript 和预生成的 Typert 元数据，不编译 TypeScript 插件。源码级调试导航和编辑器声明仍可从开发包中获取。复制规则测试覆盖排除项和保留资源；prepare:dsh 在 Host smoke 和最终清单验证之前，使用内置 Node 执行产物 smoke。

Windows 发布验收还需在 Desktop 构建后手动运行原生清理和替换检查。将 $Electron 设为已准备的 Electron 可执行文件，将 $Makensis、$SevenZip 和 $PluginDir 分别设为锁定版本构建器的 NSIS 编译器、7-Zip 可执行文件和 x86-unicode NSIS 插件目录。从仓库根目录运行以下命令。它验证 Electron junction 清理、安装器临时目录清理和两种文件占用替换方式；不属于单元测试通道。

pwsh -NoProfile -File apps/desktop/scripts/smoke-windows.ps1 -Electron $Electron -Makensis $Makensis -SevenZip $SevenZip -PluginDir $PluginDir

上传更新

DSH_DESKTOP_AUTO_UPDATE_ENV 同时选择打包时写入的更新 URL 与后续 COS 上传目标，可取 test 或 production；未设置时使用 test。测试打包必须通过 DOWNLOAD_TEST_ORIGIN 提供 HTTPS origin，生产 origin 仍为 https://download.deepseek.com。上传还必须通过 DOWNLOAD_TEST_COS_BUCKET 或 DOWNLOAD_PROD_COS_BUCKET 提供所选环境的 COS bucket。目标路径为 _/harness/desktop/stable/<target>/，其中 target 为 mac-arm64、mac-x64 或 win-x64。

更新目标与上传凭据都与所选环境对应：

环境	公开 origin	COS bucket	COS 凭据
test 或未设置	DOWNLOAD_TEST_ORIGIN	DOWNLOAD_TEST_COS_BUCKET	DOWNLOAD_TEST_COS_SECRET_ID、DOWNLOAD_TEST_COS_SECRET_KEY
production	https://download.deepseek.com	DOWNLOAD_PROD_COS_BUCKET	DOWNLOAD_PROD_COS_SECRET_ID、DOWNLOAD_PROD_COS_SECRET_KEY

同一目标必须在同一环境下完成打包与上传。例如，默认测试环境使用：

export DOWNLOAD_TEST_ORIGIN='https://desktop-updates.example.com'
pnpm run package:desktop:mac:arm64

export DOWNLOAD_TEST_COS_BUCKET='<test COS bucket>'
export DOWNLOAD_TEST_COS_SECRET_ID='<test COS SecretId>'
export DOWNLOAD_TEST_COS_SECRET_KEY='<test COS SecretKey>'
pnpm run upload:mac:arm64

生产发布需在打包前设置 DSH_DESKTOP_AUTO_UPDATE_ENV=production，再在执行 upload:mac:arm64、upload:mac:x64 或 upload:win:x64 前提供 DOWNLOAD_PROD_COS_BUCKET 与生产凭据对。打包不要求 COS bucket 或凭据。它会明确禁止 electron-builder 发布，从其子进程中删除全部四个 COS 凭据字段，并且只有在 electron-builder 以及全部签名或公证钩子成功后才写入目标完成记录。上传会先要求该记录与所选环境、目标、公开 URL 和当前 dsh 版本一致，再要求根 dsh 版本、Desktop 版本、频道元数据版本、产物名称、大小与 SHA-512 全部一致，之后才读取所选 COS 凭据对。它只上传该目标不可变且带版本的产物，最后以 no-cache 上传根据版本得出的频道元数据，并且不会删除历史对象。稳定版本使用 latest-mac.yml 或 latest.yml；alpha 等预发布版本则使用 alpha-mac.yml 或 alpha.yml，与 electron-builder 生成的文件名一致。