保姆级：从 0 到 1 用 Electron 封装 DeepSeek Harness

承接上篇这个桌面应用是 AI 从规划到实现全程完成的本篇把可复现的落地步骤完整贴出来——从同级 clone 到 2 个补丁到跑通附 Windows 受限网络三坑。上一篇《让AI把 DeepSeek Harness 做成桌面应用》我讲了架构——进程内 Host webserver localhost 同源零上游改动而且这整个应用是AI 从规划到实现全程完成的。这一篇直接上干货怎么把 AI 写好的代码跑起来。从同级 clone、到 2 个补丁、到一键构建全程照抄就能复现文末还附上我在 Windows 受限网络下踩的 3 个坑。如果你也想过给某个 agent 框架套个桌面壳却被「Node 内部 API 在 Electron 下不可用」劝退过——这篇就是写给你的。一、先交代要 clone 什么这个工程消费deepseek-harnessdsh和dsh-market插件市场方式是同级目录源码引用不是 git submodule。构建前先把它们 clone 到本工程的同级目录# dsh锁定 tag dsh-v0.1.5-rc.2与 patches/dsh-v0.1.5-rc.2/ 对应gitclone--branchdsh-v0.1.5-rc.2 https://github.com/deepseek-ai/deepseek-harness.git../deepseek-harnessgitclone--branchv1.26.0 https://github.com/dsh-market/dsh-market.git../dsh-market为什么同级目录而非 submodule因为deepseek-ai/dshapps/cli只暴露bin没有main/exportsrunProfile只能从源码 import。源码引用能直接 import 任意 host/client 包、能自建前端 dist、能紧跟上游迭代。如果缺../dsh-marketcollect-dsh.mjs会硬失败打包产物需要把它物化为dsh-dist/node_modules/dshmarket。二、自定义 desktop profiledsh 用 profile 声明「组合哪些插件」。我们要的是「web 组合微调为桌面」所以新建一个desktopprofileprofiles/desktop/ ├── package.json # dsh.profile.bundles [dsh-base, dsh-web-app] └── cordis.patch.yml # 覆盖 web-runtime.printUrl: false不打印 URL 行关键就两点dsh.profile.bundles [dsh-base, dsh-web-app]——复用 web 组合不 fork。cordis.patch.yml里把web-runtime的printUrl关掉桌面应用启动时不需要往终端打 URL端口则由启动代码注入--port 0。三、主进程挂起 dsh Host桌面壳的主进程就干一件事动态 import dsh 的runProfile把 Host 挂起来就绪后建窗加载。// src/main/host.tsconst{ctx,shutdown}awaitrunProfile(desktop,[--port,0]);// --port 0 OS 分配空闲端口读 ctx.webServer.port 拿实际端口consturlhttp://127.0.0.1:${ctx.webServer.port}/;// src/main/windows.tswin.loadURL(url);// 渲染进程同源加载 dsh Web UI托盘/通知这类桌面能力主进程直接订阅ctx的session/event进程内无需 HTTP/WS触发 ElectronNotification/Tray。四、两个补丁为什么必须有dsh 依赖 Node 内部 APIHMR、原生目录对话框而 Electron 的 V8 是-electron分支缺了关键符号导致这些能力在 Electron 下不可用。所以构建前要打两个补丁补丁作用dsh-disable-hmr.patch给runProfile加DSH_DISABLE_HMR开关跳过依赖--expose-internals的 watch-only HMRdsh-disable-native-picker.patch让目录选择器在 Electron 下强制用 browse原生对话框 worker 用 electron.exe 启动会失败根因dsh 的 loader 经node-addon-require-builtin原生模块获取 Node 内部 ESM loader该模块依赖 Electron V8 缺失的GetAlignedPointerFromEmbedderData符号而失效。补丁按 dsh 版本分目录存放patches/dsh-tag/升级 dsh 时新增对应目录即可。五、完整命令清单一键跑通# ① 本工程依赖npmElectron / Forge / Vitenpminstall# ② dsh 依赖在 ../deepseek-harness 下执行pnpm 工程cd../deepseek-harnesspnpmi# ③ 一键构建 dshgit apply 2 个补丁 → pnpm install → build host/client/web → build dsh-market# 幂等--reverse --check 检测已应用则跳过npmrun build:dsh# ④ 开发模式Vite 构建 启动 Electron主进程挂起 dsh Host 并加载 Web UInpmstart# ⑤ 打包prepackage 自动 collectpnpm deploy 物化 dsh 产物到 dsh-dist/npmrun package# ⑥ 出分发制品Windows Squirrel 安装器 / 免安装 ZIPnpmrunmake打包产物out/DeepSeek Harness Desktop-win32-x64/已含 dshlib node_modules web dist profileexe 可直接运行。六、目录结构对照deepseek-harness-desktop/ # 本工程Electron 桌面壳 ├── docs/ # 产品概念设计 ├── specs/ # 规范文档8 模块 201-dsh-market ├── patches/ # dsh 上游补丁git apply ├── scripts/ # build-dsh.mjs / collect-dsh.mjs / fetch-runtime.mjs ├── profiles/desktop/ # 自定义 desktop profile ├── src/ │ ├── main/ # index.ts / host.ts / windows.ts / tray.ts / notifications.ts ... │ ├── preload/index.ts │ └── renderer/renderer.ts # 极薄渲染入口 ├── forge.config.ts └── resources/ # 应用图标、托盘图标七、Windows 受限网络的 3 个坑在「GitHub 不可达 / Corepack 受限」的 Windows 环境npm run package会踩三个坑。均已验证解法坑 1pnpm 版本不一致deepseek-harness锁定pnpm11.7.0但corepack pnpm --filter在子工作区解析到旧版本报错This project is configured to use 11.7.0 of pnpm解法——手工建一个调用 corepack 的pnpm.cmdshim放到用户可写目录并置于 PATH 前部$shimDirC:\Users\$env:USERNAME\AppData\Local\pnpm-shimNew-Item-ItemType Directory-Path$shimDir-Force|Out-Null$corepackCmd(Get-Commandcorepack.cmd).SourceSet-Content-Path(Join-Path$shimDirpnpm.cmd)-Value ECHO off GOTO start :find_dp0 SET dp0%~dp0 EXIT /b :start SETLOCAL call $corepackCmd pnpm %* -Encoding ASCII$env:PATH $shimDir;$env:PATH坑 2fetch-runtime 重复下载首次下载被中断后runtime/node/与runtime/pnpm/已就位但版本戳没写下次又重下。解法——确认runtime/node/node.exe与runtime/pnpm/pnpm.exe存在后手写版本戳{node:24.11.1,pnpm:9.15.9,platform:win32,arch:x64}|Set-Content-Path.\runtime\.versions.json-Encoding ASCII-NoNewline坑 3Electron 二进制下载超时electron-forge package从 github.com 下载 Electron 二进制受限网络时报connect ETIMEDOUT。解法——改用 npmmirror 国内镜像$env:ELECTRON_MIRROR https://registry.npmmirror.com/-/binary/electron/$env:ELECTRON_CUSTOM_DIR v{{ version }}npm run package三者叠加pnpm shim 入 PATH 版本戳就绪 Electron 镜像即可在受限 Windows 环境稳定跑通npm run package/npm run make。八、写在最后以上就是 Electron 封装 DeepSeek Harness 的完整落地路径同级 clone → desktop profile →runProfile→ 2 个补丁 → 一键构建。踩过的坑Windows 受限网络三连也都贴了报错原文和解法。代码已开源https://github.com/fellow99/deepseek-harness-desktop欢迎star支持。感谢各位关注欢迎访问我的 GitHub 主页https://fellow99.github.io/下一篇预告把同一个 dsh 搬上鸿蒙——Electron-on-HarmonyOS 运行时 6 个补丁在鸿蒙真机上跑起 AI Agent。关注我别错过。