Skip to content

wlkerwong-boop/hermes-desktop-plugins / skills/hermes-desktop-app

hermes-desktop-app

Verified

Install/launch/update/troubleshoot Hermes Desktop app (GUI).

FileKindSize
SKILL.mdskill md8.0 KB
---
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`(无参数,自动构建)
3. 启动用后台进程: `hermes desktop --skip-build`(terminal background=true),等 30-60s
4. 装进 /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 构建产物替换。
5. 验证: `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, h*0.25, w, h*0.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 固定)
- 它和命令行版是同一个"脑子"(记录、记忆、技能通用)
- 顺带说明做了什么(如旧壳子备份位置)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall