内容
# Hermes-Claude 桥接
[](https://github.com/RodrigoSiliunas/hermes-claude-bridge/actions/workflows/ci.yml)
[](https://github.com/RodrigoSiliunas/hermes-claude-bridge/releases)
[](https://opensource.org/licenses/MIT)
将 [Hermes Agent](https://hermes-agent.nousresearch.com/) 的开发任务委托给 [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) — 零额外Anthropic API成本。
> **状态：** 早期开发中。API可能会在v1.0.0之前发生变化。
## 为什么？
- 您已经为Claude Code（Pro / Team / Enterprise）付费 — 重用该订阅。
- Hermes处理编排、内存和多工具工作流。
- Claude Code处理深层次、多文件的编码任务。
- 委托工作不会消耗Anthropic API令牌。
## 这个项目解决了什么问题？
**Omni** ([automagik-dev/omni](https://github.com/automagik-dev/omni)) 展示了Telegram和其他渠道如何与Claude Code通信。这个桥接器为 **Hermes Agent** 生态系统提供了类似的功能，但专注于：
- **无额外API成本** — 重用Claude Code CLI订阅。
- **持久化上下文会话** — SQLite/PostgreSQL存储保留完整的对话历史；每个新提示都包含之前的上下文。
- **历史记录过滤和压缩** — 控制发送的过去事件数量，并附上旧消息的紧凑摘要。
- **MCP服务器** — 将 `claude_code_delegate` 公开为Hermes或任何MCP客户端的原生MCP工具。
- **实时事件** — SSE流通过 `asyncio.Condition` 即时传递事件，无需轮询。
- **人工介入** — 当Claude提出问题时，桥接器会暂停并询问用户。
- **模型选择** — 选择 `sonnet`、`opus`、`haiku` 或任何完整的模型名称。
- **无头/可脚本化** — 从Python/asyncio运行 `claude -p --bare`。
- **结构化结果** — 从Claude的输出中解析文件编辑、bash命令和错误。
- **Hermes原生** — 在Hermes技能中注册为工具（`claude_code_delegate`）。
## 安装
```bash
pip install hermes-claude-bridge
```
需要安装并认证 `claude` CLI：
```bash
claude --version
```
## 快速开始
### 命令行界面
```bash
# 检查claude是否可用
hermes-claude health
# 运行单个任务
hermes-claude run "将auth.py重构为使用依赖注入" -f src/auth.py
# 从文件运行
hermes-claude run-file prompt.md
```
### Python API
```python
import asyncio
from hermes_claude_bridge.bridge import HermesClaudeBridge
from hermes_claude_bridge.schemas import ClaudeTask
async def main():
bridge = HermesClaudeBridge()
result = await bridge.run_task(ClaudeTask(
prompt="为所有函数添加类型提示",
context_files=["src/main.py"],
))
print(result.model_dump_json(indent=2))
asyncio.run(main())
```
## Hermes Agent 设置
### 选项A：MCP服务器（推荐用于tool-gateway风格）
生成MCP配置片段并将其合并到 `~/.hermes/config.yaml` 中：
```bash
hermes-claude setup --mcp-config >> ~/.hermes/config.yaml
```
使用默认模型预设（`sonnet`、`opus` 或 `haiku`）：
```bash
hermes-claude setup --mcp-config --model sonnet >> ~/.hermes/config.yaml
```
在下一次启动时，Hermes会发现来自 `hermes-claude-bridge` MCP服务器的 `claude_code_delegate` 工具。
### 选项B：原生Hermes插件
安装插件：
```bash
hermes-claude setup --hermes-plugin
```
然后在 `~/.hermes/config.yaml` 中启用它：
```yaml
plugins:
enabled:
- hermes-claude-bridge
```
如果设置了环境变量 `HERMES_CLAUDE_BRIDGE_URL`，插件可以自动连接到桥接服务器：
```bash
export HERMES_CLAUDE_BRIDGE_URL=http://localhost:8765
```
重启Hermes。`claude_code_delegate` 工具将在 `hermes-claude-bridge` 工具集中可用。
### 服务器模式（有状态）
启动桥接服务器以实现持久会话和实时SSE事件：
```bash
hermes-claude server --port 8765
```
然后使用Hermes的Python客户端：
```python
import asyncio
from hermes_claude_bridge.client import BridgeClient
async def main():
client = BridgeClient("http://localhost:8765")
# 使用 mode="interactive" 以保持对话上下文跨提示。
# 限制历史事件的数量以避免上下文溢出。
session = await client.create_session(
working_dir="/path/to/project",
model="sonnet",
mode="interactive",
max_history_events=5,
)
result = await client.send_prompt(
session["session_id"],
"将auth.py重构为使用依赖注入",
context_files=["src/auth.py"],
)
print(result)
if result.get("status") == "waiting_user_input":
question = result["pending_question"]
# 询问用户，然后：
await client.answer_question(session["session_id"], "是的，继续。")
asyncio.run(main())
```
### MCP 服务器
将桥接器公开为原生MCP工具：
```bash
hermes-claude mcp-server
```
Hermes（或任何MCP客户端）可以调用 `claude_code_delegate`。对于无状态的单个任务：
```json
{
"prompt": "重构auth.py",
"context_files": ["src/auth.py"],
"model": "sonnet"
}
```
对于持久会话，将工具指向正在运行的桥接服务器：
```json
{
"prompt": "重构auth.py",
"bridge_url": "http://localhost:8765",
"mode": "interactive"
}
```
### Hermes 技能
将技能安装到您的Hermes配置文件中：
```bash
cp -r .skills/hermes-claude-bridge ~/.hermes/skills/
```
然后在代理中注册工具：
```python
from hermes_claude_bridge.hermes_adapter import ClaudeBridgeTool
tool = ClaudeBridgeTool()
schema = tool.get_schema() # 向Hermes注册
result = await tool.invoke({
"prompt": "重构auth.py",
"context_files": ["src/auth.py"],
"model": "sonnet",
"permission_mode": "acceptEdits",
"timeout": 300,
})
```
有关完整的技能定义，请参见 `.skills/hermes-claude-bridge/SKILL.md`。
## 架构
```
Hermes Agent
|
v
+----------------------------------+
| BridgeClient 或 ClaudeBridgeTool|
| - HTTP客户端 / 工具适配器 |
+----------------------------------+
|
| SSE / HTTP
v
+----------------------------------+
| Hermes-Claude 桥接服务器 |
| - FastAPI + SSE流式传输 |
| - 会话管理器（SQLAlchemy） |
+----------------------------------+
|
v
+----------------------------------+
| HermesClaudeBridge（编排器）|
| - 任务执行 |
| - 健康检查 |
+----------------------------------+
|
v
+----------------------------------+
| ClaudeExecutor（子进程） |
| - claude -p [--bare] |
| - 异步子进程 + 超时 |
+----------------------------------+
|
v
+----------------------------------+
| 输出解析器 |
| - 提取文件编辑 |
| - 提取bash命令 |
| - 检测问题 |
+----------------------------------+
|
v
结果（JSON）
```
## 配置
环境变量：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CLAUDE_EXECUTABLE` | `claude` | claude CLI路径 |
| `CLAUDE_WORKING_DIR` | `.` | 默认工作目录 |
| `CLAUDE_TIMEOUT` | `300` | 默认超时（秒） |
| `CLAUDE_BARE` | `true` | 使用 `--bare` 模式 |
| `CLAUDE_PERMISSIONS` | `acceptEdits` | 默认权限模式 |
| `CLAUDE_MODEL` | `None` | 默认Claude模型 |
| `DATABASE_URL` | `sqlite+aiosqlite:///./hermes_claude_bridge.db` | 异步数据库URL |
## 权限模式
| 模式 | 行为 |
|------|----------|
| `acceptEdits` | 自动批准文件编辑；询问bash/其他工具 |
| `dontAsk` | 自动批准所有内容（危险，请谨慎使用） |
| `default` | 询问每个工具使用（非无头） |
## 开发
```bash
git clone https://github.com/RodrigoSiliunas/hermes-claude-bridge.git
cd hermes-claude-bridge
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```
## 发布
要创建新版本：
```bash
# 更新pyproject.toml和src/hermes_claude_bridge/__init__.py中的版本号
git add -A
git commit -m "chore(release): bump version to v0.6.0"
git tag v0.6.0
git push origin main --tags
```
`Release`工作流将自动构建软件包并创建带有发布说明的GitHub Release。
## 测试
```bash
pytest tests/ -v
```
## 许可证
MIT.
