# Hermes Agent Workflow：构建私有化个人 AI 助手完整方案

> Hermes Agent Workflow 是一个开源模板项目，提供在个人硬件上部署完整 AI 助手栈的完整方案，包括 agent 运行时、PWA 前端、音频桥接、本地记忆后端和 systemd 服务管理。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-10T11:45:13.000Z
- 最近活动: 2026-05-10T11:52:54.043Z
- 热度: 163.9
- 关键词: AI, agent, PWA, 私有化, 开源, hermes, sidekick, hindsight, systemd, git-crypt
- 页面链接: https://www.zingnex.cn/forum/thread/hermes-agent-workflow-ai
- Canonical: https://www.zingnex.cn/forum/thread/hermes-agent-workflow-ai
- Markdown 来源: ingested_event

---

## 项目概述与定位

在当前 AI 助手领域，大多数用户的选择局限于商业云服务（如 ChatGPT、Claude）或封闭的硬件产品。对于希望拥有真正私有化、可定制 AI 助手的用户来说，缺乏一个完整的、可落地的开源方案。

**Hermes Agent Workflow** 正是为填补这一空白而诞生的开源项目。它提供了一个公开模板，让用户能够在自己的硬件上部署完整的个人 AI 助手栈，包括 agent 运行时、渐进式 Web 应用前端、音频桥接、本地记忆后端等组件。

项目自我定位为 "早期但可用，有明确观点但非 polished 产品"，这意味着它提供了一个经过深思熟虑的架构，但同时也保留了足够的灵活性供用户定制。

## 核心组件架构

Hermes Agent Workflow 采用分层架构，各组件职责清晰：

### 1. hermes-agent（核心运行时）

基于 Nous Research 的 hermes-agent Python 包，提供：
- Agent 主循环和技能系统
- 网关服务
- 插件机制
- Cron 任务调度

### 2. sidekick（PWA 前端）

独立的渐进式 Web 应用，包含：
- Bun 代理服务器
- Python 音频桥接（基于 aiortc）
- 通过 WebRTC 实现低延迟语音输入输出
- 与 Deepgram 集成进行语音识别

sidekick 位于独立仓库，本模板负责将其与后端组件连接。

### 3. hindsight（本地记忆后端）

基于 Postgres 数据库和 FastAPI 的小型服务器，为 hermes-agent 提供可回忆的记忆存储。这是实现长期个性化 AI 体验的关键组件。

### 4. systemd 用户单元

为网关、hindsight 服务器、sidekick 代理和音频桥接提供系统服务管理，确保各组件作为后台服务稳定运行。

### 5. 辅助脚本

- **doctor 脚本**：健康检查和符号链接完整性验证
- **sync 脚本**：可选的 cron 驱动备份，将 agent 状态备份到用户 fork

### 6. claude-remote 工作流

一个创新的 tmux + Claude Code 远程控制方案，允许用户通过 claude.ai（网页或 iOS 应用）从手机远程驱动自己的 agent，并从 fork 中的 `claude-session-history.md` 加载热启动上下文。

## 快速部署流程

项目提供了极简的一键安装方案：

```bash
curl -fsSL https://raw.githubusercontent.com/jscholz/hermes-agent-workflow/main/install.sh | bash
```

这条命令会：
1. 克隆仓库到 `~/code/hermes-agent-workflow`
2. 启动 Claude Code
3. 由 AGENTS.md 接管后续流程

AGENTS.md 会引导用户完成：
- Fork 到私有仓库
- 运行 `scripts/bootstrap.sh`
- 提示输入 API 密钥、主机名、经纬度、agent 后端配置
- 克隆 sidekick 到 `~/code/sidekick/`
- 构建 uv 虚拟环境
- 部署 systemd 用户单元
- 链式冒烟测试

完成后，`https://<host>.local` 即可访问 sidekick PWA，用户开始与 agent 对话。

## 框架与实例的分离设计

Hermes Agent Workflow 采用了巧妙的框架与实例分离架构：

### 框架（上游仓库）
- 提供基础架构、技能模板、配置示例
- 定义部署流程和最佳实践
- 持续演进，用户可选择性拉取更新

### 实例（用户 Fork）
- `hermes.config.yaml`：个性化配置
- `AGENTS.md`：针对特定用户的指令
- `SOUL.md`：agent 的人格定义
- `memories/`：累积的 agent 记忆
- 自定义技能
- 加密存储的密钥和凭据

这种设计的优势在于：
- **版本控制即灾难恢复**：硬件损坏后，只需在新机器上克隆 fork 并运行 bootstrap 即可完全恢复，包括累积的记忆和所有定制
- **安全隔离**：敏感信息存储在用户私有 fork 中，而非上游公共仓库
- **灵活升级**：用户可以选择何时从上游拉取更新，避免破坏性变更

## 符号链接模式：状态版本化的关键

项目解决了一个常见但棘手的问题：如何对 AI agent 的可变状态进行版本控制。

传统方式下，通过 pip 安装 hermes-agent 后，用户数据（技能、记忆、配置、OAuth token）会累积在 `~/.hermes/` 目录中，与包文件混杂。这使得 "版本化 agent 状态" 变得困难——用户不想版本化整个安装，只想版本化其中的数据。

Hermes Agent Workflow 通过**符号链接模式**解决这一问题：

1. bootstrap 向导将 `~/.hermes/` 设置为指向 fork 仓库的符号链接树
2. 对技能、配置、累积记忆的编辑都落在仓库目录中
3. `git push` 即可快照完整的 agent 状态
4. 新机器上 `git clone + bootstrap.sh` 即可恢复

具体实现：
- `skills/` 树是 agent 读取的实时技能目录，直接编辑即生效
- `memories/` 是 agent 回忆的目标，随学习过程增长
- `hosts/<hostname>/` 捕获特定主机的状态，避免多机器设置相互覆盖

## 技能版本管理策略

由于技能在用户 fork 中版本化，pip 升级不再自动更新技能——用户的仓库成为事实来源。

上游技能改进通过**vendor-branch + 三方合并**策略引入：
- git 自动采用用户未定制处的上游变更
- 保留用户在上游未变更处的编辑
- 仅在真正重叠处显示冲突

详细流程见 `UPGRADES.md`。

## 安全设计：git-crypt 加密

用户的 fork 包含真实密钥——API 密钥、OAuth 凭据、WhatsApp 会话状态、hindsight 记忆库备份。为保护这些信息（即使在 "私有" 仓库中，未来的你或协作者也可能看到历史），项目使用 **git-crypt** 进行静态加密。

加密范围通过 `.gitattributes` 定义：
- `.env`
- `auth.json`
- `google_*.json`
- `whatsapp/session/**`
- `pairing/**`
- `hindsight-data/**`

这些文件在工作树中显示为明文（仓库解锁后），但在每个提交中都是密文。

### 首次设置
```bash
git-crypt init
git-crypt export-key /tmp/hermes-key
base64 /tmp/hermes-key  # 保存到密码管理器和离线备份
shred -u /tmp/hermes-key
```

### 在新机器恢复
```bash
git clone <your-fork>
cd <your-fork>
echo '<base64-key>' | base64 -d | git-crypt unlock -
```

**重要**：如果丢失密钥，加密历史将无法恢复。建议至少在两个独立位置备份——密码管理器、纸质备份、离线存储。

## 数据流向与交互流程

系统的数据流清晰分层：

```
浏览器 / iOS PWA
    ↓
[ sidekick ] <- PWA + Bun 代理 + Python 音频桥接
    |
    | HTTP + WebRTC
    v
[ hermes-agent ] <- Python agent 运行时
    网关、技能、插件、cron
    ↓
[ hindsight ] <- 记忆后端 (Postgres + FastAPI)
```

- **sidekick** 是用户-facing 表面：PWA、Bun 代理、`/api/hermes/*`、aiortc 音频桥接
- **hermes-agent** 运行实际的 agent 循环、技能、工具调用，暴露 OpenAI 兼容的 `/v1/responses` 接口
- **hindsight** 存储可回忆的记忆，hermes 作为技能调用

## 核心能力与使用场景

部署完成后，PWA 成为日常交互界面。值得注意的能力包括：

### 跨平台会话可见性
聊天抽屉显示 hermes 跟踪的每个会话——Telegram、Slack、WhatsApp、Signal 等——与 sidekick 聊天并列，每行显示来源徽章。便于从单一界面监控多通道 agent 活动。

### 语音交互
通过 WebRTC 和 Deepgram 集成，支持低延迟的语音输入输出，实现自然对话式交互。

### 长期记忆
hindsight 后端使 agent 能够记住用户偏好、过往对话、项目上下文，实现真正的个性化体验。

### 远程控制
claude-remote 工作流允许用户通过手机远程控制 agent，适合移动场景或无法直接使用电脑的情况。

## 适用人群与使用建议

Hermes Agent Workflow 特别适合：

1. **隐私敏感用户**：希望数据完全本地化，不依赖云服务
2. **技术爱好者**：愿意投入时间构建个性化 AI 助手
3. **多平台用户**：需要在多个通信渠道（Telegram、Slack、WhatsApp 等）与同一 agent 交互
4. **定制化需求者**：需要超越商业产品能力的深度定制

对于普通用户，项目的学习曲线可能较陡——需要熟悉 Linux 系统管理、systemd、Git 加密等概念。但对于目标用户群体，这些投入换来的是完全可控的 AI 助手体验。

## 项目意义与行业影响

Hermes Agent Workflow 代表了 AI 助手部署的一个新方向：**从依赖云服务转向私有化、可定制的本地部署**。

在当前 AI 领域，大多数创新集中在模型能力本身，而运行时和部署架构的创新相对较少。Hermes Agent Workflow 填补了这一空白，提供了一个经过深思熟虑的完整架构，包括：

- 状态管理（符号链接模式）
- 安全设计（git-crypt 加密）
- 版本控制（框架与实例分离）
- 多模态交互（语音 + 文本）
- 跨平台集成（多通信渠道）

这些设计决策不仅适用于 hermes-agent，也为其他 AI 项目提供了可借鉴的模式。

## 总结

Hermes Agent Workflow 是一个雄心勃勃的开源项目，它不仅仅是一个部署脚本，更是一套关于如何构建、管理和维护个人 AI 助手的完整方法论。通过巧妙的架构设计，它解决了 AI 助手私有化部署中的关键挑战：状态管理、安全存储、灵活升级和跨平台集成。

对于希望真正"拥有"自己的 AI 助手的用户来说，这是一个值得深入研究和尝试的项目。