Hermes Agent API Service

hermes-agent-api/
├── app/
│   ├── api/
│   │   ├── tasks.py       # 任务管理 API
│   │   ├── files.py       # 文件管理 API
│   │   └── ws.py         # WebSocket API
│   ├── models.py          # 数据模型
│   ├── config.py          # 配置管理
│   ├── hooks.py           # Hook 管理器
│   ├── output_parser.py   # 输出解析器
│   ├── hermes_process.py  # Hermes Agent 进程管理器
│   ├── workspace_manager.py # Workspace 管理器
│   ├── task_manager.py    # 任务管理器
│   ├── task_storage.py    # 任务存储 (SQLite)
│   ├── cleanup_service.py # 任务清理服务
│   ├── ws/
│   │   └── manager.py    # WebSocket 连接管理器
│   └── main.py           # 主应用入口
├── tests/                # 测试代码
├── workspaces/           # Workspace 目录
├── tasks/                # 任务数据库
├── logs/                 # 日志
├── pyproject.toml       # 项目配置
├── requirements.txt      # Python 依赖
├── Dockerfile            # Docker 镜像
└── docker-compose.yml   # Docker 编排

# 编辑 .env 文件
nano .env

# 启用认证并设置 API Key
AUTH_ENABLED=true
API_KEY=your-secure-api-key-here

ws://localhost:8000/ws/task/task_abc123?api_key=your-secure-api-key-here

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 安装 Hermes Agent
pip install git+https://github.com/NousResearch/hermes-agent.git

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，配置必要的环境变量
# 如：OPENAI_API_KEY, ANTHROPIC_API_KEY 等

# 开发模式（自动重载）
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

curl -X POST http://localhost:8000/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "proj-123",
    "message": "分析这个代码库并生成报告",
    "model": "anthropic/claude-sonnet-4"
  }'

{
  "task_id": "task_abc123",
  "status": "pending",
  "created_at": "2026-04-29T10:00:00Z",
  "estimated_duration": 300
}

curl http://localhost:8000/api/v1/tasks/task_abc123

{
  "task_id": "task_abc123",
  "workspace_id": "proj-123",
  "status": "running",
  "created_at": "2026-04-29T10:00:00Z",
  "started_at": "2026-04-29T10:00:05Z",
  "progress": {
    "current_step": "分析代码结构",
    "percentage": 60
  }
}

curl -N http://localhost:8000/api/v1/tasks/task_abc123/stream

event: task_started
data: {"task_id": "task_abc123", "timestamp": "2026-04-29T10:00:05Z"}

event: progress
data: {"step": "分析代码结构", "percentage": 20}

event: message
data: {"content": "我发现了 50 个 Python 文件..."}

event: task_completed
data: {"task_id": "task_abc123", "result": "..."}

# 使用 websocat 或 wscat 工具
# 安装: npm install -g wscat

# 连接 WebSocket
wscat -c ws://localhost:8000/ws/task/task_abc123

# 发送消息
> {"type": "user_message", "content": "继续分析"}

# 发送 ping
> {"type": "ping", "timestamp": 1234567890}

# 取消任务
> {"type": "cancel_task"}

const ws = new WebSocket('ws://localhost:8000/ws/task/task_abc123');

ws.onopen = () => {
  console.log('WebSocket connected');
  // 发送消息
  ws.send(JSON.stringify({
    type: 'user_message',
    content: '请继续分析'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
  
  if (data.type === 'task_cancelling') {
    console.log('Task is being cancelled');
  }
};

ws.onclose = () => {
  console.log('WebSocket disconnected');
};

# 连接进度流 WebSocket
wscat -c ws://localhost:8000/ws/task/task_abc123/stream

# 接收进度更新
< {"type": "stream_started", "task_id": "task_abc123"}

# 发送取消请求
> {"type": "cancel"}

# 接收确认
< {"type": "cancelled", "task_id": "task_abc123"}

# 构建并启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f api

# 停止服务
docker-compose down

# 使用 override 文件
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d

# 查看日志
docker-compose logs -f api

# 构建镜像
docker build -t hermes-agent-api .

# 运行容器
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/workspaces:/app/workspaces \
  -v $(pwd)/tasks:/app/tasks \
  -v $(pwd)/logs:/app/logs \
  --name hermes-agent-api \
  hermes-agent-api

# 安装开发依赖
pip install black isort

# 格式化代码
black app/ tests/ --line-length 120
isort app/ tests/ --profile black

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 运行测试并生成覆盖率报告
pytest tests/ --cov=app --cov-report=html

# 使用 black 格式化代码
black app/ tests/

# 使用 isort 排序 import 语句
isort app/ tests/