hermes-desktop 开发指南:从环境准备到跨平台打包的完整实战
hermes-desktop 开发指南:从环境准备到跨平台打包的完整实战
本指南以仓库根目录的 Development.md 为主线,系统讲解 hermes-desktop(Hermes Agent 的桌面伴侣)本地开发的全流程:环境准备、依赖安装、开发模式启动、静态检查、测试执行,以及 macOS / Windows / Linux(含 Fedora/RHEL 的 RPM)多平台打包。读完本文,你将掌握该 Electron 应用的完整开发闭环,并能结合源码定位每个命令背后的真实执行逻辑。
项目速览:开发文档背后的技术栈
hermes-desktop 是一个基于 Electron + electron-vite 构建的桌面应用,其核心目录结构体现了清晰的进程边界:
src/main/:主进程,负责 Hermes Agent 的安装、配置、会话管理与网关通信,入口为 src/main/index.ts;src/preload/:预加载脚本,暴露受限的桥接 API;src/renderer/:React 渲染进程,包含聊天、网关、记忆、看板、3D 办公室等界面;src/shared/:主进程与渲染进程共享的类型与工具,以及多语言国际化资源。
开发脚本集中定义在 package.json 的 scripts 字段,后续所有命令都能在其中找到对应定义。构建工具链由 electron.vite.config.ts、vitest.config.ts、tsconfig.node.json 与 tsconfig.web.json 共同驱动。
一、前置条件(Prerequisites)
Development.md 明确列出三项环境要求,结合源码可以进一步细化:
- Node.js 与 npm:仓库使用 npm 作为包管理器(存在 package-lock.json),且
postinstall脚本会调用install-electron与electron-builder install-app-deps完成 Electron 二进制与原生依赖的安装,因此请确保 npm 版本与engines兼容(源码以 Node 22 ESM 为 CI 基准,见 scripts/generate-winget-manifests.mjs 等脚本的编写风格)。 - 类 Unix Shell 环境:Hermes Agent 安装器依赖 Unix-like shell(bash 环境)。在 Windows 上开发时,仓库提供了 scripts/hermes-sandbox.ps1 沙箱脚本,用于隔离真实用户数据目录。
- 网络访问:首次运行时应用会下载 Hermes Agent,因此开发/测试期间需要能访问对应下载源。
二、安装依赖:npm install 做了什么
npm install
这一步除了安装常规依赖外,还会触发 package.json 中的 postinstall 钩子:
"postinstall": "install-electron --no && electron-builder install-app-deps"
即:先安装 Electron 运行时,再通过 electron-builder 重新编译原生依赖(如 better-sqlite3,它在 electron.vite.config.ts 中被声明为主进程的 external 模块,并在 electron-builder.yml 的 asarUnpack 中解包其预编译二进制,见 node_modules/better-sqlite3/prebuilds/*.node)。
三、启动开发模式:npm run dev
npm run dev
该命令实际执行 electron-vite dev,由 electron.vite.config.ts 统一编排三段构建:
- main:编译主进程,
better-sqlite3保持外部化; - preload:多入口构建
index与askpass两个预加载脚本(对应 src/preload/index.ts 和 src/preload/askpass.ts); - renderer:React 渲染进程,集成
@vitejs/plugin-react与@tailwindcss/vite,并做了three依赖去重(dedupe: ["three"]),以避免 3D 办公室场景中多份 Three.js 实例破坏instanceof判断。
开发模式下还可使用环境变量微调行为:
# 使用全新临时 HERMES_HOME 启动,避免污染真实数据(scripts 中定义)
npm run dev:fresh
# 渲染进程端口覆盖(electron.vite.config.ts 读取)
HERMES_DESKTOP_RENDERER_PORT=5173 npm run dev
主进程入口 src/main/index.ts 在非打包(!app.isPackaged)状态下会加载项目根目录的 .env,使运行时环境变量(如 API 端点)在修改后无需重新构建即可生效——这是开发体验优化的一部分。若设置 ENABLE_CDP=1,还会追加 --remote-debugging-port(默认 9222),配合 scripts/ 下的 probe-*.js、drive-*.js 等 CDP 探针脚本做端到端联调。
Windows 沙箱模式:为避免破坏本机 Hermes 数据,Windows 开发者推荐使用:
npm run dev:sandbox # 等价于 powershell 执行 scripts/hermes-sandbox.ps1 dev
该脚本会在仓库下创建 .sandbox/ 目录,动态分配 API 端口(起始 19642)、SSH 本地端口、渲染进程端口与 claw3d 端口,并把 HERMES_HOME 指向沙箱目录,从而让开发、测试与生产数据完全隔离。
四、代码质量检查:lint 与 typecheck
npm run lint
npm run typecheck
- lint:执行
eslint --cache --max-warnings=0 .,即任何 warning 都会导致失败(严格模式)。规则来自 eslint.config.mjs,它组合了@electron-toolkit/eslint-config-ts、React 与 React Hooks 规则,并对 3D 办公室代码(src/renderer/src/screens/Office/office3d/**)单独关闭react/no-unknown-property,因为 Three.js 的 JSX 属性(position、args、intensity等)会被 DOM 规则误报。 - typecheck:拆分为
typecheck:node(针对src/main、src/preload、src/shared,使用 tsconfig.node.json)与typecheck:web(针对渲染进程,使用 tsconfig.web.json),两段都通过才判定成功。@renderer/*路径别名在 web 侧配置,@shared别名则在 vitest 与 electron-vite 中分别映射。
五、运行测试:单元测试与监听模式
npm run test # vitest run --maxWorkers=4
npm run test:watch # vitest(监听模式,保存即重跑)
测试基础设施由 vitest.config.ts 配置:使用 jsdom 环境、全局模式、并加载渲染进程的测试 setup(src/renderer/src/test/setup.ts)。测试文件按约定散落在 src/**/*.test.ts(x) 与 tests/**/*.test.ts,仓库中已有覆盖主进程(如 account-store、secrets、ssh-remote、wallet-store 等)与渲染进程(MessageRow、ChatInput、Sessions 等)的大量用例,可以作为新增测试的参照样板。
常用进阶命令:
npm run test:coverage # vitest run --coverage(v8 覆盖率)
npm run test:sandbox # Windows 沙箱隔离环境跑测试
npm run audit:prod # 仅审计生产依赖(--omit=dev --audit-level=high)
其中 audit:prod 对应 scripts/audit-production-dependencies.mjs,该脚本会对 EAI_AGAIN、ECONNRESET 等瞬时网络错误自动重试(最多 3 次),避免 CI 因 registry 抖动而误报。
六、构建与平台打包
通用构建
npm run build
build 等价于 npm run typecheck && electron-vite build:先做全量类型检查,再产出 out/ 目录的构建产物。开发/预览场景下也可用 npm run start(electron-vite preview)直接运行已构建产物。
平台打包命令总览
| 命令 | 目标平台 | 说明 |
|---|---|---|
npm run build:mac |
macOS | 产出 dmg / zip,启用公证(notarize)与硬化运行时 |
npm run build:win |
Windows | NSIS 安装包 + portable 免安装版 |
npm run build:linux |
Linux | AppImage、snap、deb、rpm 四种格式 |
npm run build:rpm |
Fedora / RHEL | 仅产出 .rpm,适合红帽系发行版 |
打包配置要点(electron-builder.yml)
electron-builder.yml 定义了所有平台细节,值得关注的实现事实:
productName: HermesOne刻意去掉了空格,避免 Linux 下/opt/Hermes One/...路径因argv[0]含空白导致 Chromium zygote 启动崩溃(文件内注释引用了 issue #877);用户可见名称则通过linux.desktop.entry.Name、nsis.shortcutName、mac.extendInfo.CFBundleDisplayName恢复为 "Hermes One"。- Windows:NSIS 目标为
oneClick安装(perMachine: false),同时产出 portable 版本;可执行文件名为hermes-agent。 - macOS:声明了摄像头、麦克风、文档与下载目录的用途描述,启用
hardenedRuntime与notarize。 - Linux:deb 与 rpm 都配置了
afterInstall: build/linux-after-install.sh,用于对chrome-sandbox设置 SUID 位(chmod 4755),以兼容 Ubuntu 24.04+、Fedora 40+ 等默认禁用非特权用户命名空间的发行版。 - 更新发布:
publish指向 GitHub provider,配合electron-updater依赖实现自动更新。
若你维护仓库并计划提交新版本,仓库还提供了辅助脚本 scripts/set-version.mjs(版本号统一更新)与 scripts/generate-winget-manifests.mjs(生成 Windows winget 清单),具体流程可参考 docs/superpowers/plans/2026-04-30-windows-winget-fedora-rpm-release.md。
七、开发工作流小结与常见问题
推荐的日常迭代顺序:
npm install(首次或依赖变更后);npm run dev启动热更新开发环境;- 修改代码后运行
npm run lint && npm run typecheck把关静态质量; - 针对改动补测试,运行
npm run test或npm run test:watch; - 本地验证无误后,用
npm run build确认构建通过,再按目标平台执行对应的build:*打包命令。
常见注意事项:
- 主进程代码修改后 electron-vite 会自动重启应用;
.env的改动在开发模式下无需重新构建即可生效(见 src/main/index.ts 的loadDotEnvForDev)。 - Windows 上若遇到端口冲突或数据污染问题,优先使用
npm run dev:sandbox与npm run test:sandbox。 - 首次
npm run dev时应用会联网下载 Hermes Agent,请确保网络可达;离线环境可预先准备安装缓存。 - 打包产物名遵循
${name}-${version}...模板,例如 Windows 会得到hermes-desktop-0.7.7-setup.exe与hermes-desktop-0.7.7-portable.exe,便于 CI 或人工发布时定位产物。
通过以上命令与配置,你可以像维护者一样在本地完成 hermes-desktop 从代码修改、质量校验、测试验证到多平台产物打包的完整闭环。