Hermes Forge

Hermes Forge 是一个本地优先的 Hermes Agent 桌面客户端，当前主力支持 Windows Native，并开始补齐 macOS Native 使用链路。它不是简单的聊天壳，而是把 Hermes CLI、模型配置、Windows 原生能力、macOS 路径选择、微信 Gateway、文件附件、权限审批、反馈闭环和自动更新整合在一起的桌面工作台。

项目的目标是：让普通用户可以在没有手动配置 Hermes 的情况下完成首次安装、路径选择、模型接入和后续升级；也让开发者可以清楚地审计主进程、IPC、权限、日志、反馈同步和运行时边界，继续扩展一个可维护的本地 Agent 客户端。

Hermes Forge 不是 Hermes Agent 官方客户端，而是围绕 Hermes Agent 桌面体验构建的社区项目。

作者与协作邀请

大家好，我是小夏，一名今年刚本科毕业的开发者。Hermes Forge 起初是我为自己日常使用 Hermes Agent、管理本地模型、连接 Windows 原生能力和整理 AI 工作流而搭建的桌面工作台。它还很年轻，但我希望它能慢慢成长为一个真正好用、可信、可审计的本地 Agent 客户端。

这个项目目前主要由我个人在课业、毕业和现实事务之间推进。因为开发过程中大量依赖 AI 编码协作，Token、模型额度和本地算力都会直接限制迭代速度；很多想做的能力，例如更完整的连接器 runtime、更稳定的端到端测试、安装包签名、真实 Windows 物理机兼容性、长期 Gateway 稳定性，还需要更多时间和更多人一起打磨。

如果你也对 Electron、React、Hermes Agent、本地模型、Windows 自动化、Agent 安全边界或个人 AI 工作台感兴趣，欢迎加入一起开发。Issue、Discussion、文档补充、设计建议、真实机器测试、PR 都很有价值。哪怕只是帮忙复现一个问题、整理一段安装经验，也会让这个项目往前走一步。

项目定位

Hermes Forge 主要解决三个问题：

1. 降低 Hermes Agent 在桌面端的首次使用门槛。 应用内置首启体检、Hermes 安装与路径选择、Git/Python/微信依赖检查、模型配置检测和健康状态展示；Windows 新安装和运行链路固定走 Windows Native，macOS 支持选择已安装的 Hermes CLI 路径使用，WSL 仅作为旧配置迁移来源。

2. 把桌面端、Hermes CLI、Gateway 和模型配置统一起来。 桌面端保存模型后会同步 Hermes config.yaml、.env 和 Gateway 运行环境，避免桌面聊天、CLI、微信端各用一套模型或密钥。

3. 为本地 Agent 提供可审计的桌面能力边界。 文件写入、PowerShell、键鼠、窗口控制等高风险动作统一经过主进程审批服务；Renderer 只通过 preload 暴露的白名单 IPC 与主进程交互。Windows Bridge 是当前最完整的原生能力路径，macOS 侧优先保证 Hermes CLI 运行与路径配置。

4. 让反馈和维护形成闭环。 客户端内置反馈入口，反馈会先保存在本机，再同步到维护者仪表盘；维护者可以在仪表盘查看、回复、标记状态或永久删除，客户端反馈墙会展示服务器侧回复。

当前状态

当前公开版本为 v0.2.9，已经具备可安装、可演示、可继续开发的主链路：

• Windows 与 macOS Apple Silicon 安装包已通过 GitHub Releases 发布。
• GitHub Actions 可在 tag 发布时自动构建 Windows exe、macOS dmg / zip 和自动更新元数据。
• electron-updater 已接入 GitHub Releases，支持启动后后台检查、右上角手动检查更新、下载进度和重启安装提示。
• 核心架构已收口为 Hermes 单引擎，不再保留多引擎分叉复杂度。
• 任务事件统一通过 task:event 总线传递，便于 UI、日志和审批联动。
• v0.2.9 修复 Hermes 更新链路：应用会直接执行 Git 同步、完成后再次校验落后状态，并只在远端稳定版本更高时提醒更新。
• v0.2.9 增强更新提醒：顶部状态栏和聊天输入区都会显示更醒目的 Hermes 更新提示。
• v0.2.9 补齐 macOS Native 基础链路：运行时探测、权限概览、设置页和 Hermes CLI 路径选择不再固定显示 Windows Native。
• v0.2.8 收口 Windows Native 运行链路，并加入旧 WSL 配置迁移能力。
• v0.2.7 修复 MiMo、MiniMax、Kimi 等模型接入和 provider 映射问题。

它仍然是早期社区版本，不建议当作完全成熟的生产软件看待。尤其是 macOS 包尚未签名，macOS 自动一键安装尚未开放，Windows 物理机兼容性、微信真实账号场景、非微信连接器 runtime、安装器签名和 Electron 冒烟测试仍需要继续打磨。

功能概览

首次启动与自动部署

• 首次运行自动检测 Hermes、Git、Python、winget、模型配置、微信 aiohttp 依赖和用户数据目录权限。
• 未检测到 Hermes 时，可在应用内自动克隆 Hermes Agent、安装 Python 依赖并进行健康检查。
• macOS 用户可在设置页选择已安装的 Hermes CLI / Hermes 根路径，保存后以 macOS Native 方式运行；当前版本不会在 macOS 上自动执行 Windows 安装器。
• Git、Python、微信依赖缺失时，系统状态页和欢迎页会给出原因、建议和一键修复入口。
• 一键诊断：覆盖当前运行环境、Hermes CLI、模型连接和系统能力的完整检测链；Windows Native 会检查本机 Git/Python、Hermes 路径和模型连通性；macOS Native 会识别本机 Python 与 Hermes 路径；支持自动修复缺失依赖，并智能分类 pip 失败原因（权限、PEP 668、网络、ensurepip）。
• 设置页和运行环境面板支持选择 Hermes 安装目录、打开当前路径，并把自动安装部署到指定路径。
• Hermes 自动安装过程会通过 IPC 推送阶段和百分比进度，欢迎页、设置页和控制中心都可以显示安装进度。
• 自动安装过程会写入诊断日志，失败时不会导致客户端崩溃。

Hermes 运行与任务工作台

• 以 Hermes 为唯一执行引擎，避免多引擎配置带来的行为不一致。
• 支持流式任务状态、stdout/stderr、工具调用、审批事件、usage 和最终结果展示。
• 支持会话、工作区、文件快照、工作区锁和附件副本管理。
• Windows headless worker 带有单轮超时和队列恢复保护，避免一次模型或网络卡住拖慢后续回复。
• 大工作区写入任务会对启动前快照设置预算，减少发送后长时间停在快照阶段的体感。
• 支持拖拽上传文件或图片，让用户把本地资料直接带入任务上下文。

Skill 管理与上传

• 支持创建、编辑、删除本地 Skill，按分类浏览和搜索。
• Skill 上传：支持上传标准 Hermes 格式目录包（含 SKILL.md + references/ + scripts/）和单个 .md 文件。
• 上传单文件时会自动生成最小 YAML frontmatter，并转换为 Hermes 兼容的目录格式存入 ~/.hermes/skills/personal/。
• listSkills 采用双模发现：同时扫描 Forge 原有扁平 .md 技能和 Hermes 目录包技能，实现 Forge 与 Hermes Agent 的双向可见。
• Skill 编辑支持目录包主文件（SKILL.md）的在线修改，子资源请在文件系统中管理。

模型配置与同步

• 支持 OpenAI-compatible 本地服务、OpenRouter、Anthropic、自定义 provider profile 等配置形态。
• 支持连接测试、默认模型配置和密钥引用。
• 模型配置会同步到 Hermes CLI 与 Gateway 运行环境，减少“桌面端改了模型，但微信端还在用旧模型”的问题。
• 支持导入本机既有 Hermes 配置，也支持只读扫描旧 WSL Hermes home，把模型、连接器 .env 和 skills 迁移到 Forge 的 Windows 配置与密钥库。
• 针对 pwd 这类本地模型短 API key，内置本机代理兼容层，避免 Hermes 将短 key 误判为占位密钥。

Windows 桥接与安全审批

• Windows 桥接能力覆盖文件、PowerShell、剪贴板、截图、窗口、键鼠和 AutoHotkey 相关基础操作。
• 高风险动作统一由主进程审批服务处理，支持 once、session、always、deny 和超时治理。
• Renderer 无法直接读取明文凭据或执行系统命令，敏感能力集中在主进程白名单 IPC 中。
• Session 日志与诊断导出会尽量脱敏 token、密钥和本地敏感信息。
• 设置页提供系统能力审计，用于验证极限路径读取、大文件读取、工作区外文件写入和宿主命令执行能力。

Gateway 与微信连接器

• Gateway 状态区分配置状态、运行状态、健康状态、退出码、重启次数和退避时间。
• 微信扫码登录具备主进程状态机，覆盖二维码获取、等待扫码、等待确认、保存、同步、启动 Gateway、成功、超时、失败和取消。
• 微信依赖缺失时会提供可恢复提示与修复入口。
• 其他平台连接器已具备配置模型，但真实 runtime adapter 仍在路线图中。

反馈与维护闭环

• 内置反馈入口，用于收集问题、建议和使用卡点。
• 反馈表单支持匿名或展示 ID；提交后会先写入本机，再同步到维护者仪表盘。
• 客户端反馈墙默认折叠，用户主动展开后才拉取公开反馈和维护者回复。
• 维护者仪表盘支持查看反馈、回复反馈、标记已读/规划/完成、隐藏或永久删除。
• 反馈同步失败不会阻断本地记录，避免离线场景下丢失用户输入。

发布与自动更新

• 使用 electron-builder 打包 Windows NSIS / portable 和 macOS dmg / zip。
• 使用 electron-updater + GitHub Releases 实现启动后静默检查、后台下载、进度 IPC 和下载完成重启提示。
• 右上角提供手动检查更新按钮，下载中会展示进度。
• Hermes Agent 更新由 Forge 直接接管 Git fetch / fast-forward pull，并在更新后再次校验本地是否仍落后远端。
• Hermes 更新提醒会同时出现在顶部状态栏和聊天输入区上方；只有远端稳定版本高于当前版本时才提示更新，避免把未发布源码 commits 当作必须更新。
• Windows Release 资产使用稳定无空格命名，例如 Hermes-Forge-0.1.6-x64.exe，避免更新元数据指向不存在的文件。
• Windows exe 会在打包后写入 assets/icons/hermes-workbench.ico，安装包、窗口和任务栏图标保持一致。
• GitHub Actions 在推送 v* tag 时自动构建并上传 Release 资产。

下载与安装

前往 Releases 下载最新版本。

• Windows 用户下载 Hermes-Forge-x.y.z-x64.exe。
• macOS Apple Silicon 用户可下载 Hermes-Forge-x.y.z-arm64.dmg。
• latest.yml、latest-mac.yml、*.blockmap 是自动更新元数据，普通用户不需要手动下载。

注意：当前安装包尚未进行商业代码签名。Windows 或 macOS 首次打开时可能出现系统安全提示，这是早期独立开发版本的正常限制。

5 分钟开始使用

Windows 用户建议按这条最短路径开始：

1. 安装并打开 Hermes Forge，选择或创建一个工作区。
2. 在首启体检里保持推荐模式，让应用优先检查 Windows Native、Hermes Agent、模型配置和 Windows Bridge。
3. 如果提示缺少 Hermes，点击“自动安装 Hermes”；如果提示模型未配置，进入“模型连接”并填写 OpenAI-compatible、本地模型、OpenRouter 或 OpenAI API。
4. 在模型页点击连接测试，成功后保存为默认模型。
5. 回到聊天页发送第一条消息；底部状态条应显示运行环境、模型、权限和 Bridge 是否可用。

首次体验的目标是：从打开应用到成功发出第一条消息不超过 5 分钟。遇到红色或黄色状态时，优先点击对应的“重新检测”“打开设置”“一键修复”或“导出诊断报告”。

macOS Apple Silicon 用户当前建议按这条路径开始：

1. 先在本机准备好 Hermes Agent / Hermes CLI 和 Python 环境。
2. 安装并打开 Hermes-Forge-x.y.z-arm64.dmg。
3. 在设置页选择 Hermes CLI 或 Hermes 根目录，确认运行环境显示为 macOS Native。
4. 配置模型并运行连接测试。
5. 回到聊天页发送第一条消息。

Windows Native / macOS Native / 旧 WSL 迁移常见问题

• 默认运行环境：新安装、任务执行、模型同步、skills 和连接器都走 Windows Native。
• macOS 可以用吗：可以用于已安装 Hermes CLI 的场景。当前版本会正确显示 macOS Native，支持选择 Hermes 路径并运行 CLI；但还没有 macOS 一键自动安装。
• 旧 WSL 配置怎么办：设置页提供“旧 WSL 配置导入”，只读扫描旧 ~/.hermes/config.yaml、.env 和 skills/，不会安装、修复或依赖 WSL runtime。
• Hermes CLI 检测失败：使用设置页的“自动安装 Hermes”或手动选择 Hermes 根目录；导出诊断报告会包含最近安装记录。
• 更新后还提示更新：从 v0.2.9 起，Forge 会优先比较远端稳定版本号。远端只是多了源码 commits、但稳定版本号没有更高时，不会继续要求用户更新。
• 模型不可用：检查 base URL、API key、模型名和默认模型；保存前先运行连接测试。
• Bridge 不可达：Windows Bridge 负责 PowerShell、文件、截图、窗口等桌面能力。Bridge 关闭时聊天仍可运行，但 Windows 原生能力不可用。
• 回复慢或长时间无输出：常见原因是 Hermes 冷启动、模型响应慢、网络慢或工具执行中。当前版本已有 warmup、preflight、capability 和路径缓存。
• 需要报错排查：在设置页导出诊断报告。导出包默认脱敏，不包含 API key 或 token 明文，可附到 issue。

本地开发

推荐环境：

• Windows 10/11 或 macOS Apple Silicon
• Node.js 20+
• npm
• Git
• Python 3.10+

克隆并启动：

git clone https://github.com/Mahiruxia/hermes-forge.git
cd hermes-forge
npm install
cp .env.example .env
npm run dev

Windows PowerShell:

git clone https://github.com/Mahiruxia/hermes-forge.git
cd hermes-forge
npm install
Copy-Item .env.example .env
npm run dev

常用命令：

npm run check
npm test
npm run build
npm run package:win
npm run package:portable

运行时配置

Hermes Forge 不会写死维护者本机路径。Hermes 根路径按以下顺序解析：

1. 应用设置中保存的 Hermes 根路径
2. HERMES_HOME
3. HERMES_AGENT_HOME
4. Windows: %USERPROFILE%\Hermes Agent
5. macOS / Linux: ~/Hermes Agent
6. <project-root>\Hermes Agent

一键部署可通过环境变量覆盖安装目录和安装源：

HERMES_INSTALL_DIR=
HERMES_INSTALL_REPO_URL=https://github.com/NousResearch/hermes-agent.git
HERMES_FORGE_FEEDBACK_ENDPOINT=https://xiaoxiahome.icu/api/hermes-forge/feedback
HERMES_FORGE_FEEDBACK_WALL_ENDPOINT=https://xiaoxiahome.icu/api/hermes-forge/feedback/recent?kind=feedback&limit=50

真实 Provider Key、Bridge Token、本地模型密钥等敏感配置应放在 .env 或应用本地密钥库中，不应提交到仓库。

架构说明

src/
  main/       Electron 主进程、IPC、配置、密钥、连接器和原生服务
  preload/    Renderer 安全桥接层
  renderer/   React UI、工作台、设置中心、连接器面板和状态管理
  adapters/   Hermes CLI 适配、输出解析和提示构建
  process/    任务运行器、命令运行器、快照和工作区锁
  setup/      首启体检、Hermes 自动安装和依赖修复
  updater/    GitHub Releases 自动更新
  security/   路径校验、权限常量和安全工具
  shared/     共享类型、Schema、IPC channel 和配置模型
resources/
  hermes-headless-runner.py
  hermes-windows-mcp-server.py
assets/
  icons/
  screenshots/

核心设计原则：

• Hermes-only：当前版本只保留 Hermes 单引擎，减少执行路径分裂。
• 主进程可信边界：密钥、文件系统、子进程、Gateway、更新和原生能力都在主进程处理。
• 白名单 IPC：Renderer 只能调用明确暴露的 preload API。
• 可恢复首启：用户第一次打开时应该知道缺什么，而不是只看到堆栈错误。
• 本地优先：会话、附件、快照、密钥和日志默认留在用户自己的机器上。

已知限制

• Windows Native 是当前最完整的使用路径；macOS Native 已支持路径选择和 Hermes CLI 运行，但尚未提供一键自动安装。
• 安装包尚未签名，企业分发、系统信任和自动更新安全链路还需要继续加固。
• 微信连接器已有扫码状态机和依赖修复，但真实账号、网络波动和 Gateway 长时间运行仍需要更多机器测试。
• 非微信连接器大多仍停留在配置层，缺少完整的 runtime adapter。
• Windows 桥接能力已经接入审批，但 UI 审计、命令预览和长期策略管理仍需优化。
• 缺少 Electron 端到端 smoke test，目前主要依赖 TypeScript 检查和 Vitest 单元/集成测试。
• Skill 上传已支持标准目录包，但 .zip 压缩包上传、Skill 市场浏览和版本管理仍在路线图中。

更细的当前能力边界见 CAPABILITY_MATRIX.md，后续计划见 ROADMAP.md。

给本地 Agent 的部署提示

如果你想让 Codex、Cursor Agent、Claude Code、Hermes 或其他具备终端能力的 Agent 帮你部署，可以直接复制下面这段：

请帮我在当前电脑上部署并运行 Hermes Forge。

项目地址：https://github.com/Mahiruxia/hermes-forge

请按以下步骤执行：
1. 检查系统是否已经安装 Git、Node.js 20+、npm 和 Python。
2. 如果缺少必要依赖，请先告诉我缺什么，不要直接覆盖系统环境。
3. 克隆仓库：
   git clone https://github.com/Mahiruxia/hermes-forge.git
4. 进入项目目录并安装依赖：
   cd hermes-forge
   npm install
5. 如果根目录没有 .env，请从 .env.example 复制一份。
6. 运行质量检查：
   npm run check
   npm test
7. 检查通过后启动开发版：
   npm run dev
8. 如果启动失败，请优先检查 Node 版本、端口占用、Electron 启动错误、Hermes CLI 路径和模型配置。

请不要提交或上传 .env、user-data、dist、release、日志、快照、密钥、token 或任何本地隐私文件。

贡献指南

欢迎提交 Issue、Discussion 或 Draft PR。这个项目仍处在早期阶段，尤其需要更多真实用户和开发者一起把边界打磨清楚。优先欢迎这些方向：

• 首次启动和依赖修复体验
• Windows 物理机兼容性测试
• 微信 Gateway 长时间运行稳定性
• 非微信连接器 runtime adapter
• Windows 桥接审批 UX 和审计展示
• Electron smoke / E2E 测试
• 安装包签名、release provenance 和自动更新加固
• 文档、截图、演示视频和真实工作流案例

提交 PR 前建议运行：

npm run check
npm test

安全问题请查看 SECURITY.md。贡献流程请查看 CONTRIBUTING.md。

安全边界

• 不要提交 .env、本地 Hermes 配置、Electron user-data、日志、快照、数据库或构建产物。
• Renderer 不应接触明文凭据。
• IPC Handler 应保持白名单和 Schema 校验。
• Bridge Token 应在运行时生成，并从日志和诊断导出中脱敏。
• 文件写入、命令执行、键鼠控制和窗口操作应经过明确权限检查。

License

MIT