# https://github.com/NousResearch/hermes-agent 项目说明书

生成时间：2026-06-07 05:23:53 UTC

## 目录

- [Hermes Agent Overview & System Architecture](#page-1)
- [Memory, Skills & Self-Improving Learning Loop](#page-2)
- [Multi-Agent Architecture, Delegation & Protocol Integration](#page-3)
- [Frontend Surfaces, Themes & Platform Integrations](#page-4)

<a id='page-1'></a>

## Hermes Agent Overview & System Architecture

### 相关页面

相关主题：[Memory, Skills & Self-Improving Learning Loop](#page-2), [Multi-Agent Architecture, Delegation & Protocol Integration](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [ui-tui/package.json](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/package.json)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [plugins/memory/supermemory/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/supermemory/README.md)
- [plugins/memory/honcho/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md)
- [plugins/google_meet/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/google_meet/README.md)
</details>

# Hermes Agent 概览与系统架构

## 项目定位与设计目标

Hermes Agent 是一个由 NousResearch 维护的开源 AI 智能体项目，根据根目录 [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json) 的描述，它定位为「一个具备高级工具调用能力的 AI 智能体，配备了灵活的工具集（toolsets）系统，用于组织与管理工具」。项目以 MIT 协议发布，采用多前端、多后端的 monorepo 形态分发，方便用户在终端、桌面与浏览器中与同一套智能体内核交互。

[README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md) 中列出的官方文档目录涵盖了工具集、技能（Skills）、记忆、MCP 集成、定时任务（Cron）、上下文文件等用户侧能力，以及项目结构、Agent 主循环、关键类等开发者指南，表明该系统是「内核 + 多表面（Surface）」的分层架构。这一形态在 v0.16.0（"The Surface Release"）中进一步明确：新增的原生桌面应用让 Hermes 在不同工作场所均能呈现一致体验。

## 多工作区与多表面架构

仓库根 [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json) 通过 npm workspaces 将代码拆分为三个独立但协同的子项目：

- `apps/*`：桌面等原生客户端（v0.16.0 起作为主推交互面）。
- `ui-tui`：基于 React 19 + Ink 的终端界面，由独立 [ui-tui/package.json](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/package.json) 管理。
- `web`：基于 Vite + React 19 + TypeScript + Tailwind CSS v4 的浏览器仪表盘，构建产物输出到 `hermes_cli/web_dist/`，由 FastAPI 后端以 SPA 形式托管，详见 [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)。

后端以 Python 为主入口（`python -m hermes_cli.main web --no-open`），通过 Vite 的开发代理（`/api` → `127.0.0.1:9119`）实现热更新与生产构建共用同一份后端。`engines.node` 要求 `>=20.0.0`，`dependencies` 中固定了 `agent-browser` 与 `@streamdown/math`，并通过 `overrides` 强制使用 `lodash@4.18.1` 以收敛供应链风险。

```mermaid
graph LR
    User[用户] -->|CLI/TUI/Desktop/Web| Surface[多表面层]
    Surface --> Backend[Hermes CLI / FastAPI]
    Backend --> Loop[Agent 主循环]
    Loop --> Tools[Toolsets & 工具]
    Loop --> Skills[Skills 程序性记忆]
    Loop --> Memory[Memory 插件]
    Loop --> MCP[MCP / 外部协议]
    Memory --> Super[Supermemory]
    Memory --> Honcho[Honcho]
```

## 核心子系统与可插拔能力

Hermes 的能力通过「插件 + 技能 + 工具集」三层模型扩展。记忆层由多种 Provider 组成，呈现明显的可插拔特征：

- **Supermemory**：根据 [plugins/memory/supermemory/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/supermemory/README.md)，写入的元数据会打上 `metadata.sm_source: hermes` 作为路由键，把 Hermes 写入的记忆归入 Supermemory UI 中名为 "Hermes" 的独立空间，并支持 `container_tag: hermes-{identity}` 的按身份隔离以及多容器模式。
- **Honcho**：根据 [plugins/memory/honcho/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md)，通过两层上下文注入（用户消息注入+系统提示静态头）保持 prompt 缓存命中率，并按 `contextCadence` 节奏刷新会话摘要与个性化结论。
- **外部交互**：例如 [plugins/google_meet/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/google_meet/README.md) 暴露 `hermes meet install / setup / auth / join / say` 等子命令，支持 Chromium 转写与 realtime 语音模式。

桌面端的辅助库也围绕内容呈现而构建：[apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts) 通过归一化围栏代码块并把 `math` 标签视为数学渲染（避免与 `latex/tex` 的源码展示混淆），保证 Agent 输出在桌面端正确呈现；[apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts) 则把 Conventional Commits 头解析为面向终端用户的「新增/修复/更快/改进」分组，支撑升级日志的本地化展示。

## 社区关注的演进方向

围绕系统架构，社区讨论集中在以下几个尚未完全收敛的方向：

| 方向 | 关联 Issue / 现象 | 当前现状 |
|---|---|---|
| 多智能体协作（Orchestration、专门角色、韧性工作流） | #344 | 现阶段仍以单智能体 + 独立子代理委派为主，官方已将其列为「umbrella issue」 |
| A2A 协议互联（与 MCP 互补） | #514 | 尚未在 `package.json` 依赖中体现，需后续插件化 |
| 第三方记忆后端（如 mempalace） | #6323 | 已有 Supermemory / Honcho 等先例，可按相同 Provider 契约接入 |
| Web 搜索提供方扩展 | #5941 | `web_tools.py` 当前覆盖 Firecrawl / Tavily 等，SearxNG 仍在提案中 |
| 仪表盘主题可读性 | #18080 | [web/README.md](https://github.com/github.com/NousResearch/hermes-agent/blob/main/web/README.md) 已写入「最小字号 `text-xs`、避免极小衬线」的硬性规则，约束后续 PR |

这些讨论印证了 Hermes 的架构基调：以「内核稳定 + 多表面可替换 + 插件可插拔」为原则持续扩展，而非推翻既有 Agent 主循环。

## See Also

- [工具与工具集（Tools & Toolsets）](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)
- [技能系统（Skills）](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)
- [记忆系统（Memory）](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)
- [MCP 集成](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)
- [开发者架构指南](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture)

---

<a id='page-2'></a>

## Memory, Skills & Self-Improving Learning Loop

### 相关页面

相关主题：[Hermes Agent Overview & System Architecture](#page-1), [Multi-Agent Architecture, Delegation & Protocol Integration](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent/memory_manager.py](https://github.com/NousResearch/hermes-agent/blob/main/agent/memory_manager.py)
- [agent/memory_provider.py](https://github.com/NousResearch/hermes-agent/blob/main/agent/memory_provider.py)
- [agent/curator.py](https://github.com/NousResearch/hermes-agent/blob/main/agent/curator.py)
- [agent/curator_backup.py](https://github.com/NousResearch/hermes-agent/blob/main/agent/curator_backup.py)
- [agent/manual_compression_feedback.py](https://github.com/NousResearch/hermes-agent/blob/main/agent/manual_compression_feedback.py)
- [agent/context_engine.py](https://github.com/NousResearch/hermes-agent/blob/main/agent/context_engine.py)
- [plugins/memory/honcho/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md)
- [plugins/memory/hindsight/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/hindsight/README.md)
- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
</details>

# Memory, Skills & Self-Improving Learning Loop

## 概述

Hermes Agent 的核心学习闭环由三部分组成：**Memory（长期记忆）**、**Skills（程序化记忆）** 与 **Curator（自省策展）**。这三者共同支撑 Agent 跨会话、跨任务持续积累知识，并基于用户反馈自动改进行为。[`README.md`](https://github.com/NousResearch/hermes-agent/blob/main/README.md) 中将 Memory 与 Skills 列为顶层特性，Curator 则承担"在后台反思与重写"的角色。

社区高度关注此话题：议题 #6323 请求将 [mempalace](https://github.com/milla-jovovich/mempalace) 集成为外部结构化记忆，议题 #344 提出的多 Agent 架构也依赖共享记忆层。该闭环是 Hermes 实现"长时程任务与跨会话连续性"的基础。

## Memory 长期记忆子系统

### 架构与提供者

Memory 子系统采用 **Provider 抽象**：`memory_manager.py` 负责高层编排（注入、调度、生命周期），`memory_provider.py` 定义统一接口，多个具体后端作为插件实现，目录结构为 [`plugins/memory/`](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory)。

当前主要 Provider：

| Provider | 模式 | 关键特性 |
|---|---|---|
| Honcho | 云端 | 跨会话用户建模、双向 peer 工具、dialectic 推理 |
| Hindsight | 云端/本地嵌入/本地外部 | 知识图谱、实体解析、多策略检索 |

Honcho 通过 `hermes memory setup honcho` 激活，使用 `HONCHO_API_KEY`；Hindsight 通过 `hermes memory setup` 选择，支持 `HINDSIGHT_API_KEY`、`HINDSIGHT_LLM_API_KEY` 等环境变量（见 [`plugins/memory/hindsight/README.md`](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/hindsight/README.md)）。

### 双层上下文注入

Honcho 文档描述了关键的 **Two-Layer Context Injection** 设计：上下文注入到 API 调用的 **user message**（而非 system prompt），以保留提示缓存；系统提示中仅保留静态模式头，注入块由 `<memory-context>` 标记包裹。两层独立运行：

- **Layer 1 — 基础上下文**：每 `contextCadence` 轮刷新，包含 `SESSION SUMMARY` 等。
- **Layer 2 — 检索层**：按需触发多策略搜索。

资料来源：[plugins/memory/honcho/README.md]()

### 检索与过滤

Hindsight 的 `recall_types` 默认仅返回 `observation`（已整合的信念层），而 `world` / `experience` 等原始事实需要显式启用。这一变更使每 token 信息密度更高，避免重复事实干扰主提示。`recall_tags` 支持 `any` / `all` / `any_strict` / `all_strict` 四种匹配模式。

## Skills 程序化记忆子系统

Skills 是 Hermes 的"**程序化记忆**"——把"如何做某件事"沉淀为可复用的工作流。它与 Memory（事实性长期记忆）形成互补：Memory 解决"知道什么"，Skills 解决"怎么做"。

README 将 Skills 描述为"Procedural memory, Skills Hub, creating skills"，体现其三层结构：

1. **内置 Skills 库**（如 `skills/creative/manim-video/`、`skills/creative/p5js/`、`skills/creative/comfyui/workflows/` 等），覆盖动画、可视化、ComfyUI 等场景。
2. **Skills Hub**：集中索引、检索与版本管理。
3. **用户自定义 Skills**：用户可创建并贡献。

Curator 在后台巡检历史会话，可把"重复成功的模式"提升为新 Skill，从而与 Memory 形成互补的学习通道。

## Self-Improving Learning Loop 自改进学习闭环

### Curator 角色

`agent/curator.py` 与备份文件 `agent/curator_backup.py` 实现"策展人"功能：定期分析历史会话、提取成功模式、生成改进建议，并可回写至 Skills 与 Memory。`manual_compression_feedback.py` 接收用户对上下文压缩的显式反馈信号，反向影响 Curator 的策略选择，避免过度压缩丢失关键信息。

`agent/context_engine.py` 是闭环的执行中枢：它协调 Memory 注入、Skills 调度、Curator 触发与上下文压缩，构成一个反馈回路。

```mermaid
flowchart LR
    U[用户输入] --> CE[context_engine]
    CE -->|注入| MEM[(Memory Provider)]
    CE -->|调用| SK[Skills 库]
    SK -->|结果| CE
    MEM -->|检索| CE
    CE -->|输出| LLM[LLM]
    LLM -->|新会话| CE
    CE -->|信号| CUR[Curator]
    CUR -->|回写| MEM
    CUR -->|提升| SK
    MCF[manual_compression_feedback] -->|反馈| CUR
```

### 闭环工作机制

1. **观察**：`context_engine` 记录每轮交互、工具调用、压缩事件。
2. **反思**：`curator.py` 周期性扫描，识别高频成功模式与失败反例。
3. **沉淀**：把模式写回 Memory（事实）或提升为 Skill（流程）。
4. **再注入**：下轮会话中，Memory 与 Skills 通过 `context_engine` 自动进入提示。

`manual_compression_feedback.py` 引入"人类在环"信号——当用户对压缩结果不满时，反馈会调整压缩阈值，防止关键上下文丢失。

## 常见失败模式

- **Provider 配置错误**：未设置 `HINDSIGHT_LLM_API_KEY` 时，本地嵌入模式会启动失败；Honcho 需先激活为活动 Provider 才能用 `hermes honcho setup`。
- **缓存破坏**：将记忆注入 system prompt 会破坏 LLM provider 的提示缓存，导致成本上升——务必遵循 user message 注入约定。
- **检索过宽**：未配置 `recall_types` 时，旧版 Hindsight 返回三类原始事实，可能淹没上下文。
- **Skills 命名冲突**：自定义 Skill 与内置 Skill 同名时，内置版本优先（参考 Skill Hub 解析顺序）。

## 参见

- 议题 #6323：mempalace 外部结构化记忆
- 议题 #344：多 Agent 架构与共享记忆
- [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) — 工具集系统
- [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) — 后台调度
- [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) — 项目级上下文

---

<a id='page-3'></a>

## Multi-Agent Architecture, Delegation & Protocol Integration

### 相关页面

相关主题：[Hermes Agent Overview & System Architecture](#page-1), [Memory, Skills & Self-Improving Learning Loop](#page-2), [Frontend Surfaces, Themes & Platform Integrations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [plugins/memory/supermemory/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/supermemory/README.md)
- [plugins/memory/honcho/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
</details>

# 多 Agent 架构、委派与协议集成

## 概述与定位

Hermes Agent 当前采用「单 Agent + 隔离子 Agent 委派」的模式运行。在主 Agent 循环中,任务既可以由本地工具集直接处理,也可以通过 `delegate` 类的工具派生**隔离的子 Agent** 来承担并行或长尾工作流。仓库根目录的 [README.md](README.md) 明确指出:Hermes 可以「Spawn isolated subagents for parallel workstreams」(派生隔离的子 Agent 处理并行工作流),并允许用户「Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns」(通过 RPC 调用工具,把多步流水线折叠为零上下文消耗的回合)。

在协议层面,Hermes 通过 **MCP (Model Context Protocol)** 集成来扩展能力边界——MCP 回答「我能用什么工具?」这一问题(资料来源:[README.md](README.md))。社区正在讨论(issue #514)引入 Google 的 **A2A (Agent-to-Agent) 协议**,该协议回答「谁可以帮助我?」的问题,与 MCP 互补,旨在实现远端 Agent 发现、通信与互操作。

从 [package.json](package.json) 可以看到,仓库是一个 monorepo:`workspaces` 包含 `apps/*`、`ui-tui`、`ui-tui/packages/*` 与 `web`,意味着 Agent 运行时、TUI、Web Dashboard、原生桌面应用共享同一套代码基础,有利于跨端的统一委派协议演进。

## 当前架构:单 Agent 循环 + 隔离委派

Hermes 的运行机制可抽象为如下流程:

```mermaid
flowchart LR
    User[用户] --> Loop[主 Agent 循环]
    Loop -->|工具调用| Tools[本地工具集<br/>文件 / 终端 / 搜索]
    Loop -->|delegate RPC| Sub[隔离子 Agent]
    Sub --> Tools2[子 Agent 工具集]
    Loop -->|MCP 协议| Ext[外部 MCP 服务器]
    Sub --> Ext
    Loop --> Resp[统一响应]
    Sub --> Resp
```

主 Agent 在每一回合内根据任务复杂度决策:简单任务就地完成,需要并行或长任务则派生子 Agent。子 Agent 在独立的上下文中运行,只把最终结果回报给主 Agent,从而**避免主上下文被中间步骤污染**(资料来源:[README.md](README.md))。

## 终端后端与多环境委派

委派不只发生在「任务」级别,也发生在「执行环境」级别。Hermes 提供 **6 种终端后端**:local、Docker、SSH、Singularity、Modal 与 Daytona(资料来源:[README.md](README.md))。其中 Modal 与 Daytona 是「无服务器持久化」后端——Agent 的环境在空闲时休眠、按需唤醒,会话间隔成本几乎为零。这种设计让一个 Hermes 实例可以同时把工作委派到本地容器、远端 SSH 主机或云端无服务器运行时,适合在 $5 VPS 到 GPU 集群之间弹性部署。

## 协议集成:MCP 与未来 A2A

### MCP 集成现状

MCP 是当前唯一外置协议入口。仓库的 `plugins/memory/` 目录展示了典型的「插件即协议适配器」模式:

- [plugins/memory/supermemory/README.md](plugins/memory/supermemory/README.md) 描述了 Hermes 与 Supermemory 的双向数据通道——读路径用于回合前预取相关记忆,写路径在会话结束或 `/reset`、分支、压缩、关停时把整段对话作为一次 session 提交。
- [plugins/memory/honcho/README.md](plugins/memory/honcho/README.md) 展示了 **双层上下文注入**:静态模式头写入 system prompt(保留提示词缓存),而动态用户上下文在 API 调用时注入到 user message,并用 `<memory-context>` 标记为「背景数据而非新输入」。

这种「插件 + 上下文标记」的范式,正是 MCP 工具(以及未来 A2A 远端 Agent)接入 Hermes 的标准方式。

### A2A 演进方向

社区 issue #514 提议引入 A2A 协议,使 Hermes 能**发现并调用远端 Agent**,而不是仅在本地派生子 Agent。预期收益包括:跨厂商 Agent 互操作、跨组织能力组合、以及把 A2A 的发现能力与 MCP 的工具能力正交叠加。

## 跨端运行时与配套能力

Agent 委派与协议集成并非孤岛。仓库中至少有以下周边系统协同工作:

| 系统 | 角色 | 参考来源 |
|---|---|---|
| 桌面应用 (Electron) | 原生 UI、Markdown 预处理、changelog 解析 | [apps/desktop/src/lib/markdown-preprocess.ts](apps/desktop/src/lib/markdown-preprocess.ts)、[apps/desktop/src/lib/commit-changelog.ts](apps/desktop/src/lib/commit-changelog.ts) |
| Web Dashboard | Vite + React 19,代理到 FastAPI 后端 (`:9119`) | [web/README.md](web/README.md) |
| 技能系统 (Skills) | 流程化记忆,跨会话复用 | [README.md](README.md) |
| Cron 调度 | 后台定时任务,跨平台投递 | [README.md](README.md) |
| 上下文文件 | 项目级背景,塑造每次对话 | [README.md](README.md) |

## 常见限制与演进路径

**当前限制**(资料来源:issue #344、#514):

- 子 Agent 彼此**相互隔离**,没有内置的编排器(orchestrator)做合作或角色分工。
- 仅支持 MCP 工具协议,缺乏 A2A 这类「跨 Agent 寻址」能力。
- 远端环境由用户配置,委派没有统一的弹性调度层。

**演进方向**:从「单 Agent + 隔离委派」过渡到「真·多 Agent 架构」,引入编排(orchestration)、合作(cooperation)、专业角色(specialized roles)与弹性工作流(resilient workflows),并把 A2A 作为 MCP 之外的第二协议通道。

## 参见

- [README.md](README.md) — 项目总览与快速安装
- [web/README.md](web/README.md) — Web Dashboard 开发与构建
- [plugins/memory/supermemory/README.md](plugins/memory/supermemory/README.md) — Supermemory 记忆插件
- [plugins/memory/honcho/README.md](plugins/memory/honcho/README.md) — Honcho 记忆插件
- 社区议题:#344(多 Agent 架构)、#514(A2A 协议)

---

<a id='page-4'></a>

## Frontend Surfaces, Themes & Platform Integrations

### 相关页面

相关主题：[Hermes Agent Overview & System Architecture](#page-1), [Multi-Agent Architecture, Delegation & Protocol Integration](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [ui-tui/src/lib/mathUnicode.ts](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/src/lib/mathUnicode.ts)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [optional-skills/software-development/code-wiki/templates/README.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/templates/README.md)
</details>

# Frontend Surfaces, Themes & Platform Integrations

## 概览

Hermes Agent 提供多种"前端交互界面（Frontend Surfaces）"，让用户能够在不同的工作环境中使用同一套智能体能力。v0.16.0（"The Surface Release"）将这一理念推进到极致——发布了一个跨 100 多个提交构建的全新原生桌面应用，配套现有的 Web 仪表板与 TUI（终端用户界面），让 Hermes"在你工作的任何地方与你相遇"（资料来源：[README.md]()).本文档聚焦于这三大前端面（Web、TUI、Desktop），并讨论主题系统与平台集成相关的设计与集成点。

## 三大前端面

### 1. Web 仪表板（Web UI）

Web 仪表板是基于浏览器的管理界面，用于配置 Hermes Agent、管理 API Key 以及监控活跃会话。技术栈为 **Vite + React 19 + TypeScript**，样式层使用 **Tailwind CSS v4**（带自定义深色主题），组件库采用手写的 **shadcn/ui** 风格组件（无 CLI 依赖）。开发流程需要先后端启动 FastAPI（`python -m hermes_cli.main web --no-open`）和前端的 Vite 开发服务器（`npm run dev`，通常位于 `http://localhost:5173`，HMR 与 API 代理均开箱即用）。生产构建通过 `npm run build` 输出到 `hermes_cli/web_dist/`，由 FastAPI 作为静态 SPA 提供服务，并通过 `pyproject.toml` 的 `package-data` 嵌入到 Python 包中（资料来源：[web/README.md]()).

### 2. TUI（终端用户界面）

TUI 基于 **Ink** 框架构建，使用 React 风格组件树在终端中渲染 UI。`ui-tui/src/app/` 目录组织了完整的应用层：`createGatewayEventHandler.ts` 负责事件到状态的映射，`createSlashHandler.ts` 处理本地斜杠命令分发，`useComposerState.ts` 管理草稿与多行队列编辑，`useInputHandlers.ts` 路由按键事件。组件层（`components/`）提供 `appChrome.tsx`（状态栏、输入行、自动补全）、`appLayout.tsx`（顶层布局组合）、`markdown.tsx`（Markdown-to-Ink 渲染器）等。`hooks/` 目录提供 `useCompletion.ts`（Tab 补全：斜杠命令与路径）与 `useInputHistory.ts`（持久化历史记录）。`gatewayClient.ts` 作为子进程与 JSON-RPC 桥接器连接核心 Agent（资料来源：[ui-tui/README.md]()).

### 3. Desktop 原生应用

Desktop 应用使用 Electron 封装，提供了独立于浏览器的工作环境。其内部模块 `apps/desktop/src/lib/markdown-preprocess.ts` 负责预处理 Markdown 文本——通过 `normalizeFenceBlocks()` 规范化围栏代码块，区分 `math` 语言标签（用于数学渲染）与 `latex`/`tex` 标签（仅作语法高亮的代码块），避免用户在讨论 LaTeX 时被错误地渲染为数学公式。另一个模块 `commit-changelog.ts` 是一个轻量级的用户面向变更日志构建器：解析 Conventional Commits 1.0 头部（`type(scope)!: subject`），过滤掉 `chore/ci/docs` 等内部噪音提交，并将剩余项分组为 `What's new / Fixed / Faster / Improved / Other improvements` 等用户友好的桶（资料来源：[apps/desktop/src/lib/markdown-preprocess.ts](), [apps/desktop/src/lib/commit-changelog.ts]()).

## 主题系统

社区中最受关注的前端问题之一是仪表板主题的可读性（#18080，23 条评论）。当前提供的五种主题——**Midnight、Ember、Mono、Cyberpunk、Rose**——主要改变站点的配色方案。然而用户反馈指出，当前主题在字体选择上不够标准，衬线字体在小字号、轻字重、低对比度下可读性较差。

主题文件结构位于 `web/src/themes/`：`presets.ts` 定义预设值，`context.tsx` 提供 React Context 注入，`types.ts` 定义类型契约。TUI 端使用独立的 `ui-tui/src/lib/theme.ts` 来管理默认调色板与皮肤合并（资料来源：[ui-tui/README.md](), [web/README.md]()).

## 平台集成

### A2A（Agent-to-Agent）协议

社区高度关注（#514，18 条评论）的 A2A 协议是 Linux 基金会下的开放标准（Apache 2.0），与 MCP 互补——MCP 回答"我能使用什么工具？"，A2A 则回答"谁能帮助我？"。该协议使 Hermes Agent 能够实现远程 Agent 发现、通信与互操作。

### MCP 集成

MCP 集成允许 Hermes 连接任何 MCP 服务器以扩展能力（资料来源：[README.md]()).

### 数学公式渲染

TUI 端的 `ui-tui/src/lib/mathUnicode.ts` 实现了"尽力而为"的 LaTeX → Unicode 转换：终端无法排版 LaTeX，但 Unicode 覆盖了模型实际输出的大部分内容（希腊字母、黑板体/哥特体/手写体大写字母、集合论与逻辑运算符、常用箭头、上下标以及 `\frac{a}{b}` 折叠为 `a/b`）。设计采用纯正则管道，未识别的命令按原样保留以避免显示解析错误占位符（资料来源：[ui-tui/src/lib/mathUnicode.ts]()).

## 架构总览

```mermaid
graph LR
    User[用户] --> Web[Web 仪表板<br/>Vite + React 19]
    User --> TUI[TUI 终端<br/>Ink + React]
    User --> Desktop[Desktop 应用<br/>Electron]
    Web --> FastAPI[FastAPI 后端<br/>hermes_cli]
    TUI --> Gateway[JSON-RPC 网关<br/>gatewayClient]
    Desktop --> Core[Agent 核心]
    FastAPI --> Core
    Gateway --> Core
    Core --> MCP[MCP 集成]
    Core --> A2A[A2A 协议]
    Core --> Skills[技能系统<br/>40+ 工具]
```

## 关键依赖与配置

| 组件 | 关键依赖 | 备注 |
|---|---|---|
| Web UI | Vite, React 19, TypeScript, Tailwind v4 | shadcn/ui 风格手写组件 |
| TUI | Ink, nanostores | JSON-RPC 网关桥接 |
| Desktop | Electron | 沙盒化渲染器限制 |
| 共享 | `@streamdown/math ^1.0.2` | 数学渲染（资料来源：[package.json]()） |
| 浏览器自动化 | `agent-browser ^0.26.0` | Web 任务执行 |

## See Also

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md) — 项目总览
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md) — Web UI 开发文档
- [ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md) — TUI 模块结构
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts) — Markdown 预处理
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts) — 提交变更日志构建
- [ui-tui/src/lib/mathUnicode.ts](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/src/lib/mathUnicode.ts) — LaTeX → Unicode 转换

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：NousResearch/hermes-agent

摘要：发现 10 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: Fails to install NeuTTS during setup。

## 1. 安装坑 · 来源证据：[Bug]: Fails to install NeuTTS during setup

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Fails to install NeuTTS during setup
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ebdf0d00876046d89748da04ed227c7e | https://github.com/NousResearch/hermes-agent/issues/3002 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 来源证据：[skills-index-watchdog] Skills index is stale or degraded (degraded)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[skills-index-watchdog] Skills index is stale or degraded (degraded)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0b1cf269e8544779854a23690e9187be | https://github.com/NousResearch/hermes-agent/issues/38240 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安全/权限坑 · 来源证据：[Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron cli…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron client
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_533af3ccff3243efbc8a4a049fb486f8 | https://github.com/NousResearch/hermes-agent/issues/38412 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent | host_targets=hermes, claude_code, claude, chatgpt

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent | README/documentation is current enough for a first validation pass.

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent | last_activity_observed missing

## 7. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent | no_demo; severity=medium

## 8. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent | no_demo; severity=medium

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent | release_recency=unknown

<!-- canonical_name: NousResearch/hermes-agent; human_manual_source: deepwiki_human_wiki -->