1. 一周百 PR 的 Surface Release 到底在做什么Hermes v0.16.0 这个版本号本身没什么稀奇稀奇的是它的发布节奏——从立项到 Surface Release 落地核心团队用一周时间合入了上百个 PR。这个数字放在任何一个成熟项目里都算激进放在一个要同时交付原生桌面 App 和 web 管理台的项目上就更值得拆开看看了。先把概念对齐。所谓 Surface Release指的是把原本只存在于命令行、脚本或者内部工具链里的能力第一次以用户能直接看见、直接点的形态暴露出来。Hermes 之前的形态更接近一个 agent 运行时用户通过配置文件、命令行参数去驱动它。v0.16.0 做的事情是给它套上一层原生桌面 App 的壳同时保留 web 管理台作为配置和观测入口。这两条线并行推进才导致了 PR 数量的爆炸。为什么这件事值得单独写一篇因为一周百 PR这个现象背后藏着一套可复现的工程方法。很多人看到的是速度但真正决定成败的是拆分粒度、并行边界和合并策略。我见过太多团队想复刻这种节奏结果要么 PR 互相踩踏要么合并后回归测试全线飘红。Hermes 这次能跑通不是因为他们手速快而是因为他们在动手之前就把什么该并行、什么必须串行想清楚了。这篇文章适合三类人看一是正在做桌面端 web 双端交付的开发者二是想理解大规模 PR 并行合并策略的工程负责人三是正在部署或准备部署 Hermes agent、想搞清楚桌面版和 web 管理台各自职责边界的用户。我会从架构拆分讲到具体操作再讲到实测中踩到的坑尽量把为什么这么做讲透而不是只给一堆结论。需要提前说明的是Hermes 的桌面版在 Windows 和 Ubuntu 上都有部署路径web 管理台则承担了大部分配置工作。这两者的分工不是随便定的后面会专门拆。2. 原生桌面 App 与 web 管理台的职责切分逻辑2.1 为什么不是全都塞进桌面 App很多人第一反应是既然做了原生桌面 App为什么不把所有功能都放进去web 管理台岂不是多余这个想法在早期确实流行过但 Hermes 的选择恰恰相反——桌面 App 只做高频、轻量、需要系统级能力的事web 管理台承接低频、重配置、需要可视化的事。这个切分的依据是交互频率和系统权限两个维度。桌面 App 需要调用本地文件系统、系统托盘、原生通知、进程管理等能力这些在浏览器沙箱里做不了或者做得很别扭。而 agent 的技能配置、MCP 接入、模型参数调整这类操作用户可能一周才碰一次但每次都要面对大量表单和结构化数据放在 web 里用成熟的表单组件反而更高效。我实测下来这个边界如果划错最典型的症状就是桌面 App 里塞了一堆设置项用户找不到web 管理台里放了个需要实时响应的功能延迟高到没法用。Hermes 这次把实时状态展示放在桌面 App 的托盘和主窗口配置持久化放在 web 管理台算是踩在了合理线上。2.2 双端共享的到底是什么双端并行开发最大的坑是逻辑重复。如果桌面 App 和 web 管理台各自实现一套 agent 调用逻辑那 PR 数量翻倍不说行为不一致的问题会层出不穷。Hermes 的做法是抽出一层共享的 core 层桌面端和 web 端都通过它来和 agent 通信。具体来说core 层负责agent 生命周期管理、技能加载、MCP 连接维护、消息路由。桌面 App 通过本地 IPC 调用 coreweb 管理台通过本地 HTTP 接口调用 core。这样两端看到的 agent 状态是同一份不会出现桌面显示运行中、web 显示已停止这种经典 bug。提示如果你也在做类似的双端架构core 层的接口设计要尽早冻结。Hermes 这一周百 PR 里有相当一部分是 core 接口的适配改动如果接口反复变两端的 PR 会互相阻塞。2.3 一周百 PR 的拆分粒度参考把上面这套架构落到 PR 上Hermes 的拆分大致是这样的类别PR 占比典型粒度core 层接口与逻辑约 25%单个技能加载器、单个 MCP 连接器桌面 App UI约 30%单个窗口、单个托盘菜单项web 管理台约 25%单个配置页、单个状态面板构建与打包约 12%单平台打包脚本、签名流程文档与示例约 8%单篇部署指南、单个配置示例这个粒度意味着单个 PR 的改动量被压得很小review 成本低合并冲突概率也低。代价是 PR 数量多需要一套自动化的 CI 来兜底。Hermes 的 CI 里每个 PR 都要跑 core 层单测、桌面端冒烟、web 端构建三件套缺一不可。3. 并行开发的合并策略与冲突预防3.1 分支模型为什么不用长期 feature 分支一周百 PR 能合进去前提是分支生命周期极短。Hermes 采用的是短分支 频繁 rebase 的模式单个分支存活时间基本不超过一天。长期 feature 分支在这种节奏下是灾难因为主干每天都在变分支拖三天就会积累大量冲突。我自己的经验是分支存活超过 48 小时rebase 成本就会指数上升。Hermes 的做法是要求每个 PR 在提交后 24 小时内完成 review 和合并超时要么拆分要么关闭重开。这个规则听起来严苛但正是它保证了主干始终处于可发布状态。3.2 冲突高发区的提前锁定并行开发最怕的是多人改同一个文件。Hermes 在动手前做了一件事把冲突高发区列出来指定专人负责其他人只能通过接口调用不能直接改。冲突高发区通常包括路由注册表、技能清单、依赖版本文件、打包配置。这些文件的共同特点是所有人都要往里加东西。Hermes 的处理方式是把这些文件改成约定式注册——比如技能清单不再手写而是扫描目录自动生成。这样新增技能只需要加目录不用改清单文件冲突自然消失。3.3 CI 作为合并闸门的具体配置光靠人 review 挡不住问题Hermes 的 CI 闸门配置值得抄。核心是三道快速检查lint 类型检查30 秒内出结果不过直接打回。core 层单测覆盖 agent 生命周期、技能加载、MCP 连接5 分钟内跑完。双端冒烟桌面端启动到托盘就绪web 端构建到首页可访问10 分钟内跑完。三道全绿才允许合并。这套配置的关键是快如果 CI 要跑半小时开发者就会绕过它。Hermes 把最慢的端到端测试放在 nightly 里PR 阶段只跑冒烟这是速度和质量之间的务实取舍。注意冒烟测试的覆盖范围要定期 review。我见过项目冒烟测试跑了半年结果它测的那条路径早就没人用了真正的新路径反而没覆盖。4. 桌面端在 Windows 与 Ubuntu 上的部署差异4.1 Windows 部署的坑点集中在权限与路径Windows 上部署 Hermes 桌面版最容易出问题的是两处一是安装路径含空格或中文二是系统权限不足导致托盘图标不显示。前者会让某些依赖库加载失败后者会让 App 启动后看起来没反应。实测下来安装路径建议用纯英文、无空格的目录比如C:\Hermes。权限方面如果托盘图标不出现先检查是否以管理员身份运行过一次让系统完成首次注册。另外 Windows 11 对托盘图标的收纳策略比较激进图标可能被折叠进隐藏的图标里别误判成没启动。4.2 Ubuntu 部署要处理的是依赖与显示服务Ubuntu 上的问题更偏底层。桌面 App 依赖的图形库如果版本不匹配启动会直接报错退出。常见的是缺少libgtk相关库或者 Wayland 和 X11 的兼容问题。我的做法是先跑一遍依赖检查把缺的库补齐再确认显示服务类型。如果是 Wayland 环境某些窗口行为可能和预期不一致必要时切到 X11 会话验证。Ubuntu 上还有一个容易忽略的点App 的桌面快捷方式需要手动放到~/.local/share/applications下否则在应用菜单里找不到。4.3 双平台打包的 PR 拆分方式Hermes 把打包相关的 PR 按平台拆开Windows 打包、Ubuntu 打包、签名流程各自独立。这样做的好处是某个平台出问题不会阻塞另一个平台的合并。打包脚本里平台相关的路径、依赖、签名配置全部参数化公共部分抽到共享脚本里。这套拆法我复刻过确实能减少互相等待。但要注意打包脚本的公共部分一旦改动两个平台的 PR 都要跟着 rebase所以公共部分的接口要尽量稳定。5. 实测中暴露的问题与排查链路5.1 桌面版无法更新从现象到根因hermes桌面版无法更新是个高频问题。现象是点击更新后进度条卡住或者更新完版本号没变。排查链路我整理成下面这样第一步确认更新源是否可达。桌面 App 的更新通常走一个固定的检查接口如果网络环境导致接口不可达更新会静默失败。这一步可以通过查看 App 日志确认。第二步确认旧版本进程是否完全退出。Windows 上经常出现旧进程还在后台新版本文件被占用无法替换。任务管理器里结束所有相关进程再重试。第三步确认安装目录写权限。如果 App 装在系统保护目录下更新时没有写权限替换文件会失败。把安装目录换到用户目录下通常能解决。第四步确认版本号比对逻辑。有些情况下更新其实成功了但版本号显示逻辑有缓存重启 App 后才会刷新。5.2 卸载残留导致的重新安装失败hermes desktop 卸载之后重新安装报错多半是残留文件没清干净。Windows 上残留主要在三个地方安装目录、用户配置目录、注册表项。Ubuntu 上则是安装目录和~/.config下的配置目录。我的建议是卸载后手动检查这几个位置确认没有残留再重装。特别是配置文件目录如果里面存了旧版本的 schema新版本读取时可能直接崩溃。5.3 agent 连接不上的分层排查桌面 App 显示 agent 未连接问题可能出在三个层次core 层没起来、IPC 通道断了、agent 进程本身崩了。排查顺序应该是从下往上先确认 agent 进程在不在再确认 core 层日志有没有报错最后看桌面 App 的 IPC 连接状态。这个分层排查的思路很重要因为现象都是连不上但根因可能完全不同。我踩过的坑是直接去查桌面 App结果发现是 agent 进程因为某个技能加载失败早就退了。6. 从这次发布里能抄走的方法论6.1 把能并行和必须串行提前标出来一周百 PR 的核心不是快是该并行的并行该串行的串行。Hermes 在动手前就把任务分成两类接口定义、core 层改动这类必须串行UI、文档、打包这类可以并行。串行的部分优先做完并冻结并行的部分才铺开。这个顺序如果反了先铺开并行任务等接口一变全部返工PR 数量再多也是白搭。6.2 用自动化把 review 成本压下来PR 多了review 就是瓶颈。Hermes 的应对是让 CI 承担大部分机械检查人只 review 逻辑和边界。格式化、lint、类型、单测这些全部自动化reviewer 打开 PR 时看到的是机器已经确认没低级问题的状态注意力可以集中在设计上。6.3 主干始终可发布是底线不管并行多少任务主干必须随时能出一个可用的版本。Hermes 靠的是短分支 频繁合并 CI 闸门这三件套。任何让主干变红的 PR 都会被立即回滚而不是先合进去再修。这条底线守住了发布节奏才可控。6.4 文档和示例别放到最后这次发布里文档和示例占了约 8% 的 PR而且是和功能同步推进的。我见过太多项目把文档留到最后结果功能细节已经记不清了写出来的文档和实际行为对不上。同步推进虽然麻烦但准确性高得多。7. 部署与使用中的几个实操建议如果你正准备部署 Hermes不管是 Windows 还是 Ubuntu有几个点值得提前注意。第一安装路径统一用英文无空格目录这一条能避开大量莫名其妙的问题。第二首次运行给足权限让系统完成必要的注册之后再按需降权。第三配置改动优先走 web 管理台桌面 App 只做日常操作这样配置的持久化和版本管理更清晰。第四遇到连接问题先分层排查别一上来就重装。第五更新前先确认旧进程完全退出这一步能省掉很多更新失败的误判。关于 web 管理台和桌面 App 的配合我的习惯是桌面 App 常驻托盘负责状态监控和快速唤起web 管理台在需要改配置时打开。两者共享同一份 core 状态所以不会出现数据不一致。这个分工用顺了之后日常操作基本不用碰命令行。最后说一个容易被忽略的细节Hermes 的技能和 MCP 接入配置建议在 web 管理台里改完之后导出备份一份。桌面 App 重装或者换机器时直接导入就能恢复比重新配一遍省事得多。这个习惯我在多个 agent 类工具上都用屡试不爽。