hermes-desktop 开发指南:从环境准备到跨平台打包的完整实战

原创2026-09-21 17:41:101,385 阅读
文章标签:AI 应用AI Agent人工智能交互助手桌面应用MCP Clients本地部署

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 明确列出三项环境要求,结合源码可以进一步细化:

  1. 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 等脚本的编写风格)。
  2. 类 Unix Shell 环境:Hermes Agent 安装器依赖 Unix-like shell(bash 环境)。在 Windows 上开发时,仓库提供了 scripts/hermes-sandbox.ps1 沙箱脚本,用于隔离真实用户数据目录。
  3. 网络访问:首次运行时应用会下载 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。

七、开发工作流小结与常见问题

推荐的日常迭代顺序:

  1. npm install(首次或依赖变更后);
  2. npm run dev 启动热更新开发环境;
  3. 修改代码后运行 npm run lint && npm run typecheck 把关静态质量;
  4. 针对改动补测试,运行 npm run test 或 npm run test:watch;
  5. 本地验证无误后,用 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 从代码修改、质量校验、测试验证到多平台产物打包的完整闭环。

登录后查看全文
hermes-desktop