name: hermes-desktop-app description: "Install/launch/update/troubleshoot Hermes Desktop app (GUI)." version: 1.0.0 author: Hermes Agent license: MIT metadata: hermes: tags: [hermes, desktop, install, macos, electron] category: devops related_skills: [hermes-agent, hermes-desktop-plugins]

Hermes Desktop App (安装/启动/更新/排障)

Hermes 桌面版 = 官方图形界面 App（用户可能叫它 "Hermes Studio"、"桌面版"、"GUI"）。它不是独立产品——与 CLI/gateway 共用同一套 config、API keys、sessions、skills、memory。装好 CLI 的机器不需要另外下载安装包，直接 hermes desktop 即可（首次运行自动装 Node 依赖并构建 Electron App）。

When to Use

• 用户要求"装 Hermes Studio / 桌面版 / 图形界面版"
• 桌面版打不开、更新、或者要固定入口（Dock/启动台）

本机关键路径（macOS, arm64）

• 构建产物: ~/.hermes/hermes-agent/apps/desktop/release/mac-arm64/Hermes.app
• 正式安装位: /Applications/Hermes.app（已装 v0.17.0，2026-08-18）
• 旧安装器备份: /Applications/Hermes-old-installer.app（6 月遗留的 v0.0.1 壳子，可删）
• 启动命令: hermes desktop（构建+启动）/ hermes desktop --skip-build（跳过构建直接启动已有产物）

安装/启动步骤

1. 先确认 CLI 版本支持桌面版: hermes desktop --help（v0.20.0 起内置）
2. 检查是否已构建过: ls ~/.hermes/hermes-agent/apps/desktop/release/mac-arm64/

• 已有构建产物 → 用 --skip-build 启动，别重复构建（构建要下载 Electron，慢）
• 没有 → 跑 hermes desktop（无参数，自动构建）

1. 启动用后台进程: hermes desktop --skip-build（terminal background=true），等 30-60s
2. 装进 /Applications 供双击:

`` mv /Applications/Hermes.app /Applications/Hermes-old-installer.app # 旧壳子先备份，只移不删 cp -R ~/.hermes/hermes-agent/apps/desktop/release/mac-arm64/Hermes.app /Applications/Hermes.app `` ⚠️ 6 月遗留的 /Applications/Hermes.app 可能只是安装器壳子（Info.plist 版本 0.0.1，MacOS/ 里是 Hermes-Setup），不是真 App——必须用 release 构建产物替换。

1. 验证: open -a /Applications/Hermes.app + pgrep -fl "Hermes.app/Contents/MacOS/Hermes$" + osascript 查进程名

更新

• 终端跑 hermes desktop（无 --skip-build）→ 自动重装最新版
• 或 hermes desktop --build-only（只构建不启动，装好后 open -a 启动）

Pitfalls

• ❌ ./venv/bin/python -m hermes_cli desktop 报 "No module named hermes_cli.__main__"——必须用 hermes desktop 包装命令，不要直接调 python 模块。
• ⚠️ Electron 单实例: 两个实例共用进程组。kill 掉一个会连带杀掉另一个（包括 open -a 启动的）。清理临时实例后必须重新 open -a /Applications/Hermes.app。
• 无害日志噪音: "representedObject is not a WeakPtrToElectronMenuModelAsNSObject" 是 Electron 菜单警告，可忽略；kill 时的 "GPU process exited unexpectedly" 也是正常退出噪音。
• 桌面版版本号（Info.plist CFBundleShortVersionString）与 CLI 版本号可能不同（CLI v0.20.0 / 桌面构建 v0.17.0），属正常。
• macOS TCC 权限（全盘访问等）按签名身份记忆：本机构建/自更新的 App 用 ad-hoc 签名，权限可跨更新保留；最稳做法是自签证书并 hermes config set desktop.macos_signing_identity "Hermes Local Signing"（详见官方 desktop 文档的 macOS permissions 节）。

预览窗格（源码级机制，2026-09-09 实测）

::preview 指令 = 对话内生成文档即时预览（原生，首选方案）

• agent 回复正文中单独一行 ::preview{file="/绝对/路径.md"} → 右侧窗格即时渲染该文件
• md 原生支持（language==='markdown' 时提供 rendered/source 双视图）；html/image/pdf/text 均有对应 previewKind
• 指令必须出现在回复正文里，写进文件内容不生效
• 引号必须是 ASCII 直引号（::preview{file="/路径.md"}）——中文全角引号（“ ”）会被静默忽略、什么都不弹。用户反复说"右侧没看到预览"时先查这一个字符（实战中两轮都栽在这里），写指令时关掉输入法引号。
• 窗格整体不弹：先 apply_layout(preset='default') 把布局从 focus 切回——focus=仅聊天，没有预览位；再 desktop_preview(action='open') 并用 action='read' 回读确认（返回 "No preview tab is open" 就是没真开）。
• 每次 agent 生成 md 后必须自动附此指令（用户明确要求的 WorkBuddy 式体验，曾因漏做被严厉批评）
• 官方预览组件源码位置：app.asar.unpacked/dist/assets/index-BBYwcqUY.js（previewKind 集合 che=html/lhe=image/uhe=pdf）

rendered/source 视图切换陷阱（"不稳定"的真相）

• 预览窗格对 md 文件顶部有 rendered/source(/diff) 切换标签
• 视图选择有记忆：一旦切到 source，后续打开的文件都停留源码模式——用户观感是"渲染坏了/不稳定"
• 排障第一问："预览窗格顶部是不是停在 source 标签？点 rendered 即恢复"

路径含空格 Bug（2026-09-07 实测）

• desktop_preview 工具打开含空格的路径（如 ../我的文档/含空格的项目/报告.md）会截断到第一个空格，预览打不开。含空格路径先复制一份到无空格路径再用。
• 绕行：复制文件到无空格路径再 open。已验证可用路径：~/.hermes/workspace/media/（持久媒体展台）和 /tmp/md2wechat-test/（临时预览，排版产物集散地）。MEDIA: 卡片的预览按钮疑似同一问题。
• 已验证：无空格路径 + 中文文件名可正常打开（URL 编码自动处理，中文不截断）。
• ⚠️ 但 ::preview 指令对含空格+中文路径实测可渲染（与 desktop_preview 工具是两条路径）
• 2026-09-10 实测补充：/tmp 下无空格路径的 html 用 desktop_preview 正常；同批文件反复替换内容后预览即时刷新，无需重开。
• 预览排版产物时直接 open 生成的 .html（渲染态），别让用户看 md 源码；label 用内容标题（如「《馒头道歉》禅意排版预览」），多稿迭代时换 label 区分版本。
• 同名 label 会被浏览器标签页归并，多版本并存时 label 加版本后缀（如「Coxon v2 热点文升级版」）。

WebBridge 与 preview 的分工（公众号排版实测）

• desktop_preview/open：给用户看排版产物的渲染态（gzh-design HTML、官网截图裁剪图）
• WebBridge（127.0.0.1:10086）：抓官网/X 帖素材（navigate+evaluate+screenshot），截图后 PIL 按百分比裁剪（0.30w~0.70w, 0.55h~0.99h 取首屏产品区）可直接做文章配图
• X 帖截图裁掉导航栏：crop((0, h0.25, w, h0.85)) 保留推文本体

窗口截图技巧（公众号配图实测）

• screencapture -x 全屏可行；定位窗口 ID 用 swift -e 枚举 CGWindowList（osascript 辅助访问未授权时）
• sips -c 高宽 --cropOffset y x 裁剪；配图需裁掉左侧会话列表（含其他会话标题=隐私）

桌面插件系统（v0.21 Pantheon 新增）

• 插件目录 ~/.hermes/desktop-plugins/<id>/plugin.js，⌘K → Reload desktop plugins 加载
• 教训（2026-09-09 62 分钟学费）：用户要"对话生成文档右侧可见"时，先用 ::preview 原生指令，勿开发插件——曾因未测原生能力直接写插件 817 行+开源后返工，插件已 DEPRECATED+archive（wlkerwong-boop/hermes-md-preview）
• 铁律：接"做个 X 功能"需求 → ①先测系统原生能力 ②翻近期成功案例 ③需求复述确认 ④再决定造不造轮子

交付（用户偏好）

用户要求: 大白话、结论先行、给一键入口，不堆术语。交付说明写成:

• 先一句"装好了/正在开"
• 以后怎么打开（启动台 / 应用程序 / Cmd+Space 搜 Hermes / 右键 Dock 固定）
• 它和命令行版是同一个"脑子"（记录、记忆、技能通用）
• 顺带说明做了什么（如旧壳子备份位置）