Hermes Studio 文档

1. 概览

什么是 Hermes Studio

Hermes Studio 是一个功能完备的基于 Web 的控制面板，用于管理、监控和编排运行在 Hermes Gateway 上的 AI Agents。它提供了丰富的图形界面，涵盖对话、多 Agent 协作、任务跟踪、记忆管理、技能安装、定时任务调度和系统可观测性。该应用被设计为单页渐进式 Web 应用，通过 HTTP 和 Server-Sent Events（SSE）连接一个或多个 Hermes Gateway 实例。

架构

Hermes Studio 基于现代全栈 TypeScript 架构构建：

• 前端： React 19 + TypeScript，以 SPA 形式在客户端渲染。
• 路由： TanStack Router（基于文件的路由生成），带类型安全的路由参数和搜索参数。
• 数据获取： TanStack Query 管理服务端状态，支持自动缓存、重新获取和乐观更新。
• 构建系统： Vite + TanStack Start，支持 SSR 打包、HMR 和生产构建。
• 服务端： TanStack Start 服务端函数处理 API 路由。服务进程作为 Node.js HTTP 服务器运行，代理到 Hermes Gateway。
• 状态管理： Zustand 配合 persist 中间件管理客户端设置。React state 和 TanStack Query 管理临时/服务端状态。
• 样式： Tailwind CSS 4 + 自定义 CSS 变量主题层。所有颜色都通过 var(--theme-*) Token 感知主题。

Gateway 连接模型

Hermes Studio 不直接与大模型服务商通信。它连接到一个 Hermes Gateway 服务器，由后者管理 Agent 会话、工具执行、记忆和 Provider 路由。连接模型如下：

1. 启动时，Studio 服务器探测配置的 Gateway URL，检测可用能力。
2. 能力分为 核心（健康检查、对话补全、模型、流式）和 增强（会话、技能、记忆、配置、任务）。
3. 检测到增强能力时，Studio 以全功能模式运行，包括会话管理、工具和审批流程。
4. 只有核心能力时，Studio 优雅降级为基本对话界面。
5. 能力探测结果缓存 120 秒，并自动刷新。

功能矩阵

2. 界面参考

Hermes Studio 包含 18 个不同的界面，每个都可以通过侧边栏导航或键盘快捷键访问。下面是每个界面的参考。

3. 对话系统

会话管理

Hermes Studio 中的每次对话都存在于一个会话中。会话是 Hermes Gateway 上由服务器管理的实体。每个会话维护自己的上下文窗口、消息历史、工具权限和记忆状态。

• 创建： 会话通过 POST /api/sessions 创建，委托给 Gateway。每个会话获得唯一 key（UUID 格式）。
• 切换： 对话侧边栏显示所有活跃会话。点击会话会触发到 /chat/:sessionKey 的路由切换并加载消息历史。
• 删除： 会话可以从侧边栏右键菜单删除。这会从 Gateway 移除会话并清除关联的消息历史。
• 重命名： 会话可以重命名以便识别。名称作为元数据存储在 Gateway 会话对象上。
• 状态轮询： 对话界面轮询 GET /api/sessions/:sessionKey/status 以检测 Agent 状态变化（idle、active、waiting_for_input）。

SSE Streaming 架构

消息流式传输使用 Server-Sent Events（SSE）实时投递 Agent 响应。架构如下：

1. 用户通过 POST /api/sessions/send 发送消息，消息会派发给 Gateway。
2. 客户端打开到 GET /api/chat-events 的 SSE 连接，以会话 key 作为查询参数。
3. 服务器代理来自 Hermes Gateway 的 SSE 事件，逐 Token 转发流式数据。
4. 事件包括：message_start、content_delta、content_end、tool_use、tool_result、approval_required、error。
5. 客户端将增量累积为完整消息，增量更新 React 状态以实现平滑渲染。
6. 流结束时（自然结束或中止），客户端与 Gateway 的完整消息历史进行对账。

消息持久化

Hermes Gateway 使用分层存储策略持久化消息：

• 主存储（Redis）： 配置 REDIS_URL 时，消息存储在按会话键控的 Redis 有序集合中。这提供快速检索并支持基于 TTL 的过期。
• 降级（文件）： Redis 不可用时，消息降级为 .runtime/ 目录中每个会话一个的 JSON 文件存储。
• 会话 Token： 身份认证 Token 持久化在 Redis SET（hermes:studio:tokens）中，TTL 30 天，降级为内存存储。

审批流程

当 Agent 尝试特权操作（文件写入、命令执行、网络访问）时，Gateway 发出 approval_required 事件。Studio 界面渲染带三种处理选项的审批卡片：

• 批准（一次）： 允许特定的操作实例。范围：仅本次调用。
• 拒绝： 拒绝该操作。Agent 收到拒绝信号，并可能提出替代方案。
• 始终允许： 为这种操作模式授予永久权限。有三种范围可选：
  • once — 仅允许这一次具体操作。
  • session — 在当前会话剩余时间内允许此操作类型。
  • always — 在所有会话中永久允许此操作类型。

审批通过 POST /api/approvals/:approvalId/approve 或 POST /api/approvals/:approvalId/deny 处理。审批卡片显示操作名称、Agent 身份和可展开的完整参数上下文。

检查器面板

对话检查器面板提供当前会话状态的诊断视图。它显示活跃工具调用、待处理审批、Token 用量明细（输入/输出/缓存）、以百分比计显示的上下文窗口利用率，以及用于调试的原始事件流。上下文栏显示实时消耗量，带颜色阈值（低于 60% 绿色、60-85% 琥珀色、高于 85% 红色）。

附件处理

对话输入框支持文件附件。文件被上传并转换为适合大模型的格式（图片成为 base64 编码的视觉输入，文本文件成为内联内容块）。研究卡片组件显示结构化研究输出，带可折叠部分和来源引用。

4. 多 Agent 编排

4a. Crews

Crew 生命周期

Crews 遵循从创建到执行的既定生命周期：

1. 创建： 通过创建对话框或从画廊选择模板来定义 Crew。设置名称、描述和初始成员名册。
2. 配置： 为每个成员分配角色、模型和系统提示词。可选地构建定义执行顺序和依赖的工作流 DAG。
3. 调度： 通过调度对话框启动 Crew 执行任务。提供目标提示词，选择执行策略（并行、串行或 DAG 排序），然后确认。
4. 监控： 实时跟踪进度。每个成员的会话状态、输出和 Token 用量实时更新。费用面板显示成员级和总支出。

成员管理

每个 Crew 成员代表一个具有特定配置的 Agent 会话：

• 角色： 从 Agent 库（内置或自定义）中选择。决定系统提示词、头像和专长标签。
• 模型： 按成员覆盖默认模型。适合为简单任务分配更便宜的模型，为复杂推理分配高级模型。
• 会话： 每个成员获得跨调度持久化的专用 Gateway 会话。会话可以重置或重新铸造。

模板系统

Hermes Studio 包含 7 个内置 Crew 模板，并支持用户创建的自定义模板。模板分类如下：

• 调研： 用于调查、分析和报告生成的模板。
• 工程： 用于代码审查、架构和实现任务的模板。
• 创意： 用于内容创作、头脑风暴和设计的模板。
• 运维： 用于部署、监控和维护工作流的模板。
• Conductor： 为 Conductor 编排模式优化的模板。

可以从任何现有 Crew 配置创建自定义模板，并通过 POST /api/crews/templates 持久化。用户模板可以删除；内置模板为只读。

工作流构建器

工作流构建器是一个可视化 DAG（有向无环图）编辑器，用于定义 Crew 成员之间的执行依赖。主要特性：

• 拖放节点放置，自动布局。
• 点击源节点和目标节点创建连线。
• 环检测 — 编辑器阻止创建会形成环的连线，确保有效的拓扑顺序。
• 并行执行 — 无依赖的节点并发运行。
• 工作流状态通过 PUT /api/crews/:crewId/workflow 按 Crew 持久化。

Token 用量跟踪

费用面板（GET /api/crews/:crewId/usage）提供成员级 Token 明细，显示输入 Token、输出 Token、缓存读/写 Token 和估算费用。费用使用约每百万 Token 5 美元的混合费率。

克隆与会话铸造

Crews 可以通过 POST /api/crews/:crewId/clone 克隆。克隆会为所有成员创建全新会话的副本 Crew，保留工作流 DAG 和配置，但重置所有对话状态。这适合重新运行实验或创建变体。

4b. Conductor V2

Gateway-Native 架构

Conductor V2 系统采用 Gateway 原生方式，编排由专用的 Hermes Agent 会话执行，而非客户端逻辑。编排 Agent 接收任务目标和调度技能，然后自主分解工作并生成 worker 会话。

任务阶段

Conductor 任务经历四个阶段：

1. idle（空闲）： 无活跃任务。界面显示任务输入表单和历史。
2. decomposing（分解中）： 编排 Agent 正在分析目标并规划任务分配。界面显示思考指示器。
3. running（运行中）： worker Agents 已生成并正在执行任务。Office View 显示实时进度。
4. complete（已完成）： 所有 workers 已完成。界面显示带输出、费用和任务时长的摘要。

生成流程

生成顺序如下：

1. 客户端发送 POST /api/conductor-spawn，包含目标、编排模型、worker 模型、项目目录、最大并行数和监督标志。
2. 服务器从磁盘加载 workspace-dispatch 技能（搜索多个候选路径）。
3. 构建编排提示词，将目标与调度技能指令结合。
4. 在 Gateway 上创建 Hermes 定时任务，将编排器作为一次性任务运行。
5. 编排 Agent 分解目标，并通过调度技能生成 worker 会话。
6. 客户端每 3 秒轮询 worker 会话状态以跟踪进度。

实时监控

在运行阶段，客户端通过以下方式监控 worker Agents：

• 3 秒轮询： 每 3 秒获取所有活跃 workers 的会话状态。
• 过期检测： 在阈值时间内未上报活动的 workers 会被标记为可能过期。
• 完成检测： 所有 workers 上报 idle/complete 状态时，任务进入完成阶段。
• Office View： 所有 workers 的实时可视化，带状态指示、当前任务标签和输出预览。

Conductor 设置

设置抽屉提供以下配置：

编排模型

用于任务分解和协调的大模型。默认为 auto（Gateway 默认）。复杂任务建议使用高级模型（Claude Opus、GPT-4）。

Worker 模型

分配给生成的 worker Agents 的大模型。可以使用更便宜的模型（Claude Sonnet、GPT-4o-mini）以节省成本。

项目目录

worker 输出写入的基础目录。默认为 /tmp。设置为你工作区根目录以获得持久输出。

最大并行（1-5）

可并发运行的 worker Agents 最大数量。更高的值提高吞吐量，但消耗更多资源和 API 配额。

监督模式

启用时，worker Agents 使用工具需要审批。禁用时，workers 自主运行。

办公室视图布局

Office View 提供三种可视化布局来监控 workers：

• 网格（4x3）： 传统网格排列，每行显示最多 12 个 Agent 卡片。每个卡片显示 Agent 头像、名称、状态光晕、当前任务和最后一行输出。
• 圆桌（环形）： Agents 围绕中央任务摘要排成圆形。强调平等参与和跨 Agent 感知。
• 作战室（对排）： 两排 Agents 面对面，模拟协作工作区。状态栏和对话气泡显示实时活动。

布局偏好持久化在 localStorage 的 hermes-studio:office-layout 键下。

Agent 头像系统

每个 Conductor worker 都被分配一个独特的像素风 SVG 机器人头像。系统提供：

• 10 个头像变体： 不同的机器人身体形状，具有不同的头、身、臂和腿几何形状，渲染为 SVG 像素画。
• 10 种强调色： 橙色、蓝色、紫色、翠绿、玫瑰、琥珀、青色、品红、青柠、天蓝。每种颜色提供条、边框、头像、文字、环和十六进制值。
• 头像根据 Agent 索引确定性分配，确保跨会话一致的视觉身份。

任务历史

已完成的任务存储在 localStorage 中，最多 50 条。每条历史记录包含目标、开始/结束时间戳、worker 数量、总费用和完成状态。首页的历史面板允许查看过去的任务并重新发起类似目标。

费用跟踪

Conductor 使用约每 100 万 Token 5 美元的混合费率跟踪估算费用。费用跟踪组件在任务执行期间实时显示累积值，悬停可查看每个 worker 的明细。最终费用记录在任务历史条目中。

5. 任务管理

看板

任务看板界面实现五列看板来跟踪工作项。任务从左到右流经以下列：

任务属性

每个任务支持以下属性：

• 标题： 任务的简短描述性名称。
• 描述： 所需工作的详细说明（支持 Markdown）。
• 优先级： low、medium、high 或 critical 之一。显示为颜色编码的徽章。
• 标签： 用于分类和过滤的任意字符串标签。
• 负责人： 关联到 Agent 角色或人类标识。
• 来源链接： 引用外部资源（GitHub 问题、文档等）的 URL。
• 列： 当前看板列（决定面板位置）。

HTML5 拖放

任务可以使用原生 HTML5 拖放移动到其他列。当卡片被拖到新列时，PATCH /api/tasks/:taskId/move 请求更新服务器状态。看板使用乐观更新以获得即时视觉反馈，失败时回滚。卡片还可以在列内重新排序以设置优先级顺序。

交叉链接

任务看板与 Hermes Studio 其他系统集成：

• 任务可以从 Conductor 任务输出创建，将任务关联到原始任务。
• Crew 调度结果可以自动生成审查任务。
• 任务负责人可以引用 Agent 库中的角色。

6. 定时任务管理

任务生命周期

Hermes Studio 中的定时任务遵循以下生命周期：

1. 创建： 定义具有名称、提示词/指令、调度和投递配置的任务。
2. 调度： Gateway 用其 cron 表达式注册任务并开始调度。
3. 运行： 在每个计划时间，Gateway 生成执行任务提示词的一次性 Agent 会话。
4. 监控： 运行进度通过 SSE 流式传输。输出被捕获并存储在运行历史中。

调度预设与 Cron 表达式

任务创建对话框提供常用的调度预设：

• 每 5 分钟、每 15 分钟、每小时
• 每 6 小时、每 12 小时、每天午夜
• 每周（周一 9 点）、每月（1 号午夜）

高级用户可以使用标准 5 字段格式输入任意 cron 表达式：分钟 小时 日 月 星期。界面会验证表达式并显示人类可读的解释。

投递渠道

任务输出可以通过多种渠道投递：

运行实时流

任务运行（定时或手动触发）时，输出通过 GET /api/hermes-runs/:runId/events 的 SSE 实时流式传输。Studio 界面使用与对话相同的消息格式渲染流式输出，包括工具使用指示和 Markdown 渲染。

运行历史

每个任务维护过去运行的历史，可通过 GET /api/hermes-runs 访问。运行条目包含开始时间、时长、退出状态（成功/失败/超时）、Token 用量和完整输出文本。任务界面以时间线视图显示最近的运行，带可展开的输出面板。

7. 知识系统

记忆浏览器

记忆浏览器提供对 Agent 身份和知识文件的访问。这些 Markdown 文件定义了 Agent 的个性、能力和上下文信息：

SOUL.md

核心身份文件，定义 Agent 的基本个性、价值观、沟通风格和行为指南。始终加载到上下文中。

persona.md

当前活跃的角色配置，包括名称、职责、专长和交互偏好。可以切换以改变 Agent 行为。

CLAUDE.md

项目专属指令和上下文。通常包含代码库约定、架构说明和项目特定规则。

文件通过 GET /api/memory/read 读取、POST /api/memory/write 写入。浏览器包含 Monaco 编辑器，支持内联编辑和 Markdown 预览。

知识图谱

知识图谱提供知识条目之间关系的力导向可视化。基于 D3 风格物理模拟构建：

• 节点： 每个知识文件或记忆条目成为一个节点。大小反映内容长度；颜色表示文件类型。
• 边： 通过文档中的 wikilink 语法（[[target]]）检测连接。边代表知识条目之间的交叉引用。
• 物理： 力导向布局，带电荷斥力、连接引力和中心重力。节点可以拖拽和固定。
• 搜索： 通过 GET /api/knowledge/search 进行全文搜索，高亮匹配节点并过滤图谱显示。

图谱数据从 GET /api/knowledge/graph 获取，返回节点和边的 JSON。知识列表端点（GET /api/knowledge/list）提供扁平文件列表。

Wikilink 检测

知识系统自动检测记忆文件中的 [[wikilink]] 语法。发现 wikilink 时，系统会尝试对照现有知识条目进行解析。解析成功的链接成为图谱中可导航的连接和编辑器中可点击的引用。未解析的链接会高亮为失效引用。

模式与纠正

模式界面（/patterns）管理可复用的行为模式和纠正：

• 模式： 可应用于会话的可复用提示词模板。定义通用指令、格式规则或行为指南。
• 纠正： 覆盖默认 Agent 行为的特定行为修复。纠正生效时，会被注入 Agent 的系统提示词以防止重复犯错。

8. 技能生态

技能注册表

Hermes Studio 可访问 skillsmp.com（Hermes 技能市场）的 2000+ 技能注册表。技能通过提供结构化指令、工具定义和工作流模式来扩展 Agent 能力。技能界面显示已安装技能及其状态（启用/禁用），以及中心可用的技能。

安装流程

技能安装采用两级策略：

1. Gateway 安装： 主要路径通过 POST /api/skills/install 向 Hermes Gateway 发送安装请求。Gateway 从注册表下载技能并放入技能目录。
2. ClawHub 降级： 如果 Gateway 安装失败（旧版 Gateway、网络问题），系统降级使用 ClawHub API 获取技能。

卸载通过 POST /api/skills/uninstall 执行，从 Gateway 的技能目录中移除技能文件。

启用/禁用开关

已安装的技能可以在不卸载的情况下启用或禁用。禁用的技能保留在磁盘上，但会从 Agent 的活跃技能集中排除。这允许在不重新安装的情况下快速试验。技能设置通过 POST /api/skills/settings 管理。

技能文档

每个技能包含一个 SKILL.md 文档文件，描述其能力、用法模式和配置选项。选中技能时，技能界面会内联渲染这份文档。中心搜索（GET /api/skills/hub-search）返回技能元数据，包括名称、描述、分类和安装次数。

9. Agent 库

内置角色

Hermes Studio 内置 8 个 Agent 角色，每个针对不同的任务类型：

角色通过轮询或根据任务关键词匹配专长标签的方式分配给 Crew 成员。

自定义 Agent 创建

Agent 编辑器对话框允许创建具有以下属性的自定义 Agents：

• 名称： Agent 的显示名称。
• 表情： 在 UI 元素中显示的视觉头像表情。
• 颜色： Agent 视觉身份的强调色。
• 系统提示词： 定义 Agent 行为、知识和沟通风格的自定义系统指令。
• 模型覆盖： 可选地将此 Agent 锁定到特定大模型，不受全局设置影响。
• 标签： 用于 Crews 和 Conductor 中自动角色匹配的专长标签。

自定义 Agents 通过 POST /api/agents（创建）、PUT /api/agents/:agentId（更新）和 DELETE /api/agents/:agentId（删除）管理。它们存储在文件后端的定义存储中。

与 Crews 和模板集成

内置和自定义 Agents 都会出现在 Crew 成员选择界面中。从模板创建 Crew 时，模板按名称或专长匹配指定 Agent 分配。自定义 Agents 可用于模板，并在调度时解析。

10. 文件管理与终端

Profile 作用域文件浏览器

文件浏览器在当前 Profile 的工作区范围内运行。它提供：

• 带可展开文件夹的树形目录导航。
• 文件元数据显示（大小、修改时间、类型）。
• 文件和目录的创建、重命名和删除操作。
• 文件内容通过 GET /api/files?path=... 提供，并通过 POST /api/files 保存。

Monaco 编辑器集成

文件编辑使用 Monaco 编辑器（与 VS Code 相同的编辑器）。配置选项：

语法高亮

基于文件扩展名的自动语言检测。支持 TypeScript、JavaScript、Python、Rust、Go、Markdown、JSON、YAML、HTML、CSS 以及 50 多种其他语言。

字号

Configurable via 设置 (default: 13px). Stored in editorFontSize setting.

自动换行

切换长行自动换行。存储在 editorWordWrap setting.

缩略图

右侧边栏中的可选代码缩略图。存储在 editorMinimap setting.

PTY 终端

终端界面提供由 Xterm.js 驱动的完整 PTY（伪终端）：

• 持久化会话： 终端会话在页面刷新后仍然保留。PTY 进程继续在服务器上运行。
• 流式： 终端 I/O 通过 GET /api/terminal-stream（输出 SSE）和 POST /api/terminal-input（按键）流式传输。
• 调整大小： 浏览器窗口或面板大小变化时，终端尺寸通过 POST /api/terminal-resize 同步。
• 关闭： 通过 POST /api/terminal-close 显式关闭终端会话。
• ANSI 支持： 完整的 256 色和真彩 ANSI 渲染、粗体、斜体、下划线和光标定位。

11. 分析与可观测性

Event 分析

分析界面（/analytics）提供 Agent 活动的可视化洞察：

• 14 天堆叠柱状图： 按类型（消息、工具调用、审批、错误）分解显示每日事件数。数据来自 GET /api/state-analytics。
• 工具频率： 最常用工具的排名列表，带调用次数和成功率。
• 上下文用量： 通过 GET /api/context-usage 显示上下文窗口随时间利用情况的时间序列图。
• Provider 用量： 通过 GET /api/provider-usage 按大模型服务商分解 Token 消耗。

会话历史

会话历史界面（/session-history）提供双栏存档界面：

• 左栏： 可滚动会话列表，显示会话名称、创建日期、消息数和最近活动。按最近活动排序。
• 右栏： 所选会话的懒加载消息线程。消息以完整格式渲染，包括代码块、工具结果和审批回执。
• 数据源： GET /api/history 返回存档的会话元数据。单个会话的消息在选择时加载。

审计日志

审计日志（/audit）维护所有重要系统事件的时间顺序日志：

• 事件类型： 会话创建/删除、消息发送、工具执行、审批授予/拒绝、配置更改、技能安装/移除、任务创建/运行。
• 过滤： 按事件类型、会话 key、日期范围或自由文本搜索过滤。
• 数据源： GET /api/audit，带分页和过滤的查询参数。
• 保留： 审计条目持久化在 Gateway 上，除非手动清除，否则无限期保留。

日志 Viewer

日志界面（/logs）显示 Gateway 系统日志的最后 500 行：

• 颜色编码： 日志级别颜色编码 — debug（灰）、info（蓝）、warn（琥珀）、error（红）。
• 自动滚动： 新日志行自动将视图滚动到底部。暂停按钮可停止自动滚动以手动检查。
• 时间戳： 每行以本地时间格式显示时间戳。
• 来源： 日志从 Gateway 获取，并显示在等宽字体终端风格容器中。

12. API 参考

所有 API 端点由 Hermes Studio 服务器进程提供，并在适当时代理到 Hermes Gateway。基础路径：/api。所有修改端点要求 Content-Type: application/json。身份认证通过会话 Cookie 或 Bearer Token 进行。

身份认证

Sessions

Crews

Conductor

任务看板

Agents

任务（Cron）

记忆与知识

技能

文件

Profiles

配置

分析

系统

运维

审批

审计

Gateway 代理

13. 配置参考

localStorage 设置（Zustand Store）

客户端设置由带 localStorage 持久化的 Zustand store 管理。store 键为 hermes-studio-settings。

其他 localStorage 键

Gateway 配置

Hermes Gateway 通过 ~/.hermes/config.yaml 配置。Studio 通过 /api/hermes-config 端点读写此配置。关键配置部分：

# ~/.hermes/config.yaml
server:
  host: 0.0.0.0
  port: 8642
  cors_origins: ["*"]

auth:
  token: "your-bearer-token"
  password: "your-login-password"

providers:
  anthropic:
    api_key: "sk-ant-..."
    default_model: "claude-sonnet-4-20250514"
  openai:
    api_key: "sk-..."
    default_model: "gpt-4o"

sessions:
  persistence: redis  # or "file"
  redis_url: "redis://localhost:6379"
  max_sessions: 50

skills:
  directory: "~/.hermes/skills"
  auto_enable: true

memory:
  directory: "~/.hermes/memory"

jobs:
  directory: "~/.hermes/jobs"
  max_concurrent: 3

Conductor 设置

Conductor 设置存储在 localStorage 中，并传递给生成端点：

{
  "orchestratorModel": "",       // Empty = gateway default
  "workerModel": "",             // Empty = gateway default
  "projectsDir": "/tmp",         // Output directory for workers
  "maxParallel": 3,              // 1-5 concurrent workers
  "supervised": false            // Require approvals for workers
}

文件后端存储

多个数据存储在 Hermes Studio 安装目录的 .runtime/ 中使用：

.runtime/crews.json

Crew 定义和成员配置。

.runtime/tasks.json

任务看板状态（所有列的所有任务）。

.runtime/agents.json

通过 Agent 编辑器创建的自定义 Agent 定义。

.runtime/templates/

用户创建的 Crew 模板（每个模板一个 JSON 文件）。

环境变量

14. 设计系统

Theme 系统

Hermes Studio 使用包含 5 个可用主题的 CSS 自定义属性主题系统。主题通过设置文档根节点上的 data-theme 属性来应用。所有主题仅支持深色模式。

CSS 变量 Token

每个主题都提供以下 CSS 自定义属性。所有 UI 组件必须使用这些变量，而不是硬编码颜色：

强调色

界面强调色与主题分开配置。有四种强调色可选：橙色、紫色、蓝色和绿色。强调色影响整个应用中的交互元素、链接、选中状态、徽章和焦点环。

组件库

Hermes Studio 使用设计系统组件库来保证一致的 UI 模式：

Card

容器组件，带主题背景、边框和圆角。支持头部插槽、内边距变体和悬停状态。

设置Row

设置的水平布局，左侧标签、右侧控件。在整个设置界面中使用。

SectionHeader

区块标题组件，带可选的副标题和操作按钮插槽。提供一致的间距和排版。

StatusBadge

用于显示状态（active、idle、error、complete）的小胶囊徽章。按状态类型颜色编码。

ListItem

可点击的列表行，带可选的图标、标题、描述和尾部元素。用于侧边栏和选择列表。

EmptyState

列表或视图无内容时显示的占位组件。包含图标、标题、描述和可选的操作按钮。

图标库

Hermes Studio 使用 HugeIcons（@hugeicons/react + @hugeicons/core-free-icons）作为主要图标库。图标按名称单独导入，并通过 HugeiconsIcon 组件渲染。该图标集提供一致的 24px 描边图标，带可调的大小和颜色属性。

字体与间距

应用加载四种字体：

• Inter（400-700）：所有界面文字的主 UI 字体。
• Space Grotesk（400-700）：用于标题和展示文字。
• JetBrains Mono（400-500）：用于代码、终端和技术内容的等宽字体。
• EB Garamond（400-800）：用于编辑/创意内容场景的衬线字体。

间距遵循 Tailwind CSS 约定（4px 基本单位）。常用间距值：p-2（8px）、p-3（12px）、p-4（16px）、p-6（24px）、gap-2（8px）、gap-4（16px）。圆角使用 rounded-lg（8px）用于卡片，rounded-xl（12px）用于更大的容器。

15. Gateway 集成

能力探测

在服务器启动时以及每 120 秒，Hermes Studio 探测配置的 Gateway 以确定可用的 API 组。探测过程：

1. 向 Gateway 健康端点发送 GET 请求，超时 3 秒。
2. 健康检查响应后，探测核心能力：对话补全、模型、流式支持。
3. 核心能力确认后，探测增强能力：会话、技能、记忆、配置、任务。
4. 结果缓存 TTL 120 秒。后续请求使用缓存的能力，不再重复探测。
5. 探测失败（超时、网络错误）时，所有能力被标记为不可用。

增强模式与基础模式

根据探测结果，Studio 以三种对话模式之一运行：

enhanced-hermes

完整 Hermes Gateway，包含会话管理、工具、审批、记忆和技能。所有功能可用。

portable

基础 OpenAI 兼容对话补全。仅流式对话可用。无会话、工具或审批。

disconnected

无 Gateway 连接。界面显示带重试选项的连接错误状态。

降级行为

增强能力不可用时，Studio 优雅降级：

• 对话降级为便携模式，使用 /api/send 和 /api/send-stream 进行直接补全。
• Crews、Conductor、任务、技能、记忆和文件界面显示需要连接的空白状态。
• 侧边栏徽章指示哪些功能需要增强连接。
• 设置无论连接状态如何都保持完全可用（存储在本地）。

会话持久化后端

Hermes Gateway 支持两种会话数据持久化后端：

Redis

推荐用于生产环境。消息存储在有序集合中，会话元数据存储在哈希中。支持 TTL 过期、原子操作和多进程访问。 Requires REDIS_URL environment variable.

File

开发或单用户设置的降级方案。会话数据以 JSON 文件存储在 .runtime/sessions/。部署更简单，但缺少 TTL 管理和并发访问安全性。

Bearer Token 认证

Studio 服务器使用 Bearer Token 与 Gateway 认证。Token 通过以下方式配置：

1. 环境变量： HERMES_API_TOKEN（最高优先级）
2. 客户端设置： Zustand 设置 store 中的 hermesToken
3. Gateway 配置： ~/.hermes/config.yaml 中的 auth.token 字段

Token 在 Studio 服务器到 Gateway 的所有请求中作为 Authorization: Bearer <token> 发送。如果未配置 Token，请求将不带认证发送（适合仅限 localhost 的部署）。

16. 安全

认证策略

Hermes Studio 支持多种认证方式：

• 密码认证： 设置 HERMES_PASSWORD 时，用户必须通过登录表单认证。成功后生成并存储 32 字节加密随机会话 Token。
• OAuth 设备码流程： 用于与外部身份提供商集成。通过 /api/oauth/device-code 发起，并通过 /api/oauth/poll-token 轮询完成状态。
• API Key 认证： hermesApiKey 设置支持需要 API 服务器密钥才能访问的非回环部署。
• 无认证： 未配置密码或 Token 时，Studio 允许未认证访问。仅适用于 localhost 开发。

会话 Token 管理

会话 Token 是由 crypto.randomBytes 的 32 字节生成的 64 字符十六进制字符串。Token 使用时间安全比较验证，以防止时序攻击。Token 存储：

• 内存 Set 用于快速验证（运行进程的权威来源）。
• Redis SET（hermes:studio:tokens）用于跨重启持久化，TTL 30 天。
• 启动时，持久化的 Token 从 Redis 加载到内存 Set。

CSRF 防护

所有修改端点（POST、PUT、PATCH、DELETE）都受 requireJsonContentType 中间件保护。该函数拒绝不包含 Content-Type: application/json 的请求。由于浏览器无法在简单的表单提交或导航请求中设置此头，它的存在证明请求来自 JavaScript（fetch/XHR），从而无需 Token 即可有效防止 CSRF 攻击。

未通过此检查的请求会收到 415 Unsupported Media Type 响应，消息为 "Content-Type must be application/json"。

路径遍历防护

文件访问端点（/api/files、/api/memory/read、/api/memory/write）验证并清理所有路径参数，以防止目录遍历攻击。路径会相对于工作区根目录解析，如果尝试使用 .. 序列或范围外的绝对路径逃离允许的目录树，则会被拒绝。

限流

滑动窗口内存限流器保护敏感端点：

• 限流按客户端 IP 应用（从 X-Forwarded-For 头提取，默认为 "local"）。
• 滑动窗口跟踪请求时间戳，并移除窗口期外的条目。
• 客户端超过限制时，返回 429 Too Many Requests 响应。
• 旧条目每 5 分钟垃圾回收一次，防止内存泄漏。
• 身份认证端点使用更严格的限制，防止暴力破解攻击。

内容安全策略（CSP）

应用设置适当的内容安全策略（CSP）头来限制资源加载：

• 脚本限制为同源，为构建系统允许内联。
• 样式允许同源和 Google Fonts CDN 加载字体。
• 连接限制为同源和配置的 Gateway URL。
• 图片允许同源和用于 base64 编码内容的 data: URI。

17. 键盘快捷键

Hermes Studio 提供键盘快捷键以快速导航和执行常用操作。修饰键：Windows/Linux 上为 Ctrl，macOS 上为 Cmd。

全局导航

对话界面

文件编辑器

任务看板

Conductor

终端