内容
<p align="center">
<img src="assets/banner.svg" alt="Hermes Live Voice" width="100%">
</p>
<h1 align="center">Hermes Live Voice</h1>
<p align="center">
<strong>适用于 Hermes Agent 的实时语音模型。</strong>
</p>
<p align="center">
<a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a>
|
<a href="docs/architecture.md">架构</a>
|
<a href="docs/plugin.md">插件</a>
|
<a href="docs/client-protocol.md">客户端协议</a>
|
<a href="docs/live-provider-testing.md">实时提供商测试</a>
</p>
<p align="center">
<img alt="状态：v0.1.0" src="https://img.shields.io/badge/status-v0.1.0-ffcc00?style=for-the-badge">
<img alt="许可证：MIT" src="https://img.shields.io/badge/license-MIT-16a34a?style=for-the-badge">
<img alt="提供商：Gemini Live 和 OpenAI Realtime" src="https://img.shields.io/badge/providers-Gemini%20Live%20%2B%20OpenAI%20Realtime-7c3aed?style=for-the-badge">
<img alt="运行时：Node 20+" src="https://img.shields.io/badge/runtime-Node%2020%2B-334155?style=for-the-badge">
</p>
`hermes-live-voice` 是一个开源的 Hermes Agent 插件和实时语音网关。它允许浏览器、移动应用程序、桌面客户端或终端测试与 Hermes 通过实时语音 API 进行通信。
Gemini Live 和 OpenAI Realtime 处理语音循环：语音输入、语音输出、轮流发言、打断和低延迟对话流程。Hermes 仍然是大脑：记忆、工具、技能、终端/文件访问、MCP、审批和长时间运行在 Hermes 中。
```txt
客户端应用程序
-> WebSocket /v1/live
-> hermes-live 网关
-> Gemini Live 或 OpenAI Realtime
-> 网关工具调用：start_hermes_run()
-> Hermes API 服务器 /v1/runs
-> Hermes 工具、记忆、技能、MCP
```
此仓库仅限 Hermes，提供一个安全的翻译器在实时语音接口和 Hermes 之间。
## Hermes 如何与您交谈
网关为实时模型提供一个任务：成为实时语音接口。它不会将完整的 Hermes 工具带交给 Gemini 或 OpenAI。
1. 您的客户端将麦克风音频或文本流式传输到 `WS /v1/live`。
2. `hermes-live` 从服务器打开 Gemini Live 或 OpenAI Realtime 会话。
3. 实时模型自然地聆听和说话。
4. 当用户请求实际工作时，模型调用 `start_hermes_run`。
5. 网关启动 Hermes `/v1/runs` 任务，流式传输进度，转发审批，并在用户打断时停止运行。
6. 实时模型将 Hermes 结果转换为简短的口语响应。
这种分离是产品：
```txt
实时模型 = 耳朵，嘴巴，轮流发言
Hermes = 大脑，记忆，工具，动作
hermes-live = 它们之间的安全翻译器
```
## 为什么它存在
Hermes 已经具有强大的代理层。实时语音具有不同的运行时形状：持久的 WebSocket、音频帧、提供商会话、快速插入、客户端身份验证和网关级安全性。将该运行时保留在插件管理的网关中，让人们在无需分叉 Hermes 核心的情况下为 Hermes 添加语音功能。
| 您获得什么 | 它是如何工作的 |
| --- | --- |
| Hermes 插件 | 安装为 `hermes-live`，注册 `hermes_live_status`，并公开 `/hermes-live` 斜线命令。 |
| 实时网关 |拥有 `/v1/live`，提供商会话，音频帧，身份验证，源检查和静态演示服务。 |
| 提供商桥接器 | 支持 Gemini Live、OpenAI Realtime 和用于本地开发的模拟提供商。 |
| Hermes 运行桥接器 | 启动 Hermes 运行，流式传输事件，转发审批，并在中断/断开连接时停止活动运行。 |
| 客户端协议 | WebSocket 上的 JSON，带有 PCM16 音频帧，文本烟雾消息，运行事件，提供商转录和错误。 |
## 状态
`v0.1.0` 是第一个 GitHub 发布版本。它适用于自托管的 Hermes 安装和集成工作。
已实现：
* `GET /health`
* `GET /ready`
* `GET /v1/capabilities`
* `WS /v1/live`
* Gemini Live 适配器
* OpenAI Realtime 适配器
* 用于本地开发的模拟提供商
* Hermes `/v1/runs` 客户端
* Hermes 运行事件流式传输到 SSE
* 运行停止/中断桥接器
* 审批响应桥接器
* 静态浏览器演示
* Hermes 插件注册、发现助手、状态工具和斜线命令
## 从 GitHub 安装
该项目尚未发布到 npm。请使用 GitHub 版本/标签。
```sh
git clone https://github.com/bielcarpi/hermes-live-voice.git
cd hermes-live-voice
git checkout v0.1.0
npm install
npm run build
node dist/cli.js plugin install --symlink
hermes plugins enable hermes-live
```
启动网关：
```sh
HERMES_BASE_URL=http://127.0.0.1:8642 \
HERMES_AGENT_API_SERVER_KEY=... \
HERMES_LIVE_PROVIDER=mock \
npm run dev
```
然后打开浏览器演示：
```txt
http://127.0.0.1:8788
```
`HERMES_LIVE_PROVIDER=mock` 是检查网关、浏览器演示、终端客户端和 Hermes 运行桥接器是否正确连接的零凭证路径。要听到真正的实时语音，请将 `HERMES_LIVE_PROVIDER` 切换到 `gemini` 或 `openai`，并添加匹配的提供商密钥。
或从克隆运行 Docker 示例：
```sh
HERMES_AGENT_API_SERVER_KEY=... HERMES_LIVE_AUTH_TOKEN=$(openssl rand -hex 32) \
docker compose -f examples/docker-compose.yml up
```
## 配置
复制 `.env.example` 并设置所需的配置。
```sh
cp .env.example .env
```
Hermes API 服务器：
```sh
HERMES_BASE_URL=http://127.0.0.1:8642
HERMES_AGENT_API_SERVER_KEY=...
```
将 `HERMES_AGENT_API_SERVER_KEY` 设置为与 Hermes Agent 的 `API_SERVER_KEY` 相同的值。当前的 Hermes API 服务器部署需要承载身份验证，Hermes 只接受来自已验证客户端的长期记忆 `X-Hermes-Session-Key` 头部。`hermes-live` 在服务器端保留该会话密钥，并在运行创建和后续运行特定调用中将其发送到 Hermes。
`HERMES_API_KEY` 仍然作为旧别名受支持，但新安装应使用 `HERMES_AGENT_API_SERVER_KEY`。
Gemini Live：
```sh
HERMES_LIVE_PROVIDER=gemini
GEMINI_API_KEY=...
GEMINI_MODEL=gemini-3.1-flash-live-preview
```
OpenAI Realtime：
```sh
HERMES_LIVE_PROVIDER=openai
OPENAI_API_KEY=...
OPENAI_REALTIME_MODEL=gpt-realtime-2
OPENAI_REALTIME_TURN_DETECTION=disabled
```
对于当前的 OpenAI Realtime 1.x 行为：
```sh
OPENAI_REALTIME_MODEL=gpt-realtime-1.5
```
Realtime 2 推理努力默认为 `low`。您可以将 `OPENAI_REALTIME_REASONING_EFFORT` 设置为 `minimal`、`low`、`medium`、`high` 或 `xhigh`。
设置真实的提供商凭证后，运行一个可选的实时会话握手：
```sh
npm run check:live-provider
```
这封装了 CLI 命令：
```sh
node dist/cli.js provider-smoke
```
这两个命令使用与网关相同的适配器打开和关闭 Gemini Live 或 OpenAI Realtime 会话。它们不需要 Hermes 运行、发送用户音频/文本或启动 Hermes 运行。
本地模拟提供商：
```sh
HERMES_LIVE_PROVIDER=mock
HERMES_AGENT_API_SERVER_KEY=...
```
网络暴露的网关：
```sh
HERMES_LIVE_HOST=0.0.0.0
HERMES_LIVE_AUTH_TOKEN=$(openssl rand -hex 32)
HERMES_LIVE_ALLOW_ORIGIN=https://your-app.example
```
`hermes-live` 拒绝网络可访问的绑定而没有强大的 `HERMES_LIVE_AUTH_TOKEN`，除非您明确设置 `HERMES_LIVE_ALLOW_UNAUTHENTICATED=true` 以获得隔离的受信任网络。
## 运行
```sh
npm run dev
```
然后打开：
```txt
http://127.0.0.1:8788
```
有用的命令：
```sh
npm run dev
node dist/cli.js client "What can Hermes do?"
node dist/cli.js provider-smoke
node dist/cli.js plugin install
node dist/cli.js plugin status
npm run check # 网关、Hermes API 和提供商准备情况
npm run verify
```
内置的浏览器演示默认情况下适用于本地开发，并在 `NODE_ENV=production` 时禁用。
## 客户端协议
连接到：
```txt
ws://127.0.0.1:8788/v1/live
```
如果设置了 `HERMES_LIVE_AUTH_TOKEN`，则 `/v1/live`、`/ready` 和 `/v1/capabilities` 需要以下任一：
```txt
Authorization: Bearer <token>
```
或浏览器 WebSocket 客户端无法设置升级标头的：
```txt
/v1/live?token=<token>
```
第一条消息：
```json
{
"type": "session.start",
"profileId": "default",
"userLabel": "alice"
}
```
然后发送音频：
```json
{
"type": "audio.input",
"data": "<base64 pcm16>",
"mimeType": "audio/pcm;rate=24000"
}
```
或发送文本进行烟雾测试：
```json
{
"type": "text.input",
"text": "Summarize my current project state."
}
```
参见 [docs/client-protocol.md](docs/client-protocol.md)。
## 架构
TypeScript 网关使用小型端口和适配器布局：
```txt
domain/ 线协议和音频基元
application/live-gateway 网关会话编排和端口
adapters/inbound/http HTTP、WebSocket 和静态演示传输
adapters/outbound/hermes Hermes API 服务器 HTTP/SSE 客户端
adapters/outbound/realtime Gemini、OpenAI 和模拟实时提供商
```
`LiveGatewaySession` 依赖于应用程序端口，而不是原始 WebSocket、提供商 SDK 或 Hermes HTTP 详细信息。
参见 [docs/architecture.md](docs/architecture.md)。
## Hermes 插件
GitHub 仓库/包名称为 `hermes-live-voice`。安装的 CLI 命令和 Hermes 插件 ID 为 `hermes-live`。
该插件为 Hermes 提供了一个稳定的发现/集成表面，注册了一个 `hermes_live_status` 工具，并添加了一个 `/hermes-live` 斜线命令，用于本地网关状态。使用 `node dist/cli.js plugin install` 安装它，然后使用 `hermes plugins enable hermes-live` 启用它。
参见 [docs/plugin.md](docs/plugin.md)。
## 安全
请勿将 Hermes 直接暴露给不受信任的移动或浏览器客户端。请暴露 `hermes-live`，要求网关身份验证，限制来源，并将提供商和 Hermes 凭证保留在服务器端。
参见 [docs/security.md](docs/security.md)。
## 开发
```sh
npm install
npm run verify
```
测试套件使用模拟提供商和假 Hermes 客户端。实时提供商测试需要外部凭证，默认情况下不属于 CI 门控。
`npm run check:gateway` 通过启动 `dist/cli.js serve`、打开 `/v1/live` 和通过 HTTP/SSE 驱动一个假 Hermes 运行来建立对打包路径的信心。
`npm run check:live-provider` 和 `node dist/cli.js provider-smoke` 是可选的，仅在您设置 `HERMES_LIVE_PROVIDER=gemini` 或 `HERMES_LIVE_PROVIDER=openai` 并具有有效的提供商凭证时运行。
使用 [docs/live-provider-testing.md](docs/live-provider-testing.md) 在声称真正的 Gemini Live 或 OpenAI Realtime 部署准备就绪之前。
## 参考资料
* OpenAI Realtime 概述：https://developers.openai.com/api/docs/guides/realtime
* OpenAI Realtime API 参考：https://developers.openai.com/api/reference/resources/realtime
* OpenAI GPT-Realtime-2 模型：https://developers.openai.com/api/docs/models/gpt-realtime-2
* Gemini Live API 概述：https://ai.google.dev/gemini-api/docs/live-api
* Gemini Live API 参考：https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/models/multimodal-live
* Google Gen AI JavaScript SDK：https://github.com/googleapis/js-genai
* Hermes Agent：https://github.com/NousResearch/hermes-agent
连接信息
猜你喜欢
暂无推荐服务器