基于 Hermes Agent 构建的 API 服务，提供定制化环境（skills, MCP）的能力。

用户通过指定 workspace-id 克隆新的工作目录，执行 Hermes Agent 操作并返回结果。支持：

• 异步任务执行（提交任务 → 获取 task_id → 查询结果）
• 实时进度推送（SSE / WebSocket）
• WebSocket 双向通信（取消任务、发送消息）
• Workspace 文件管理（上传、下载、列表）
• 任务自动清理（基于时间和数量）

• Python 3.11+
• FastAPI (Web 框架)
• Hermes Agent (AI Agent 引擎)
• SQLite (任务存储)
• SSE (实时进度推送)

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 编排

认证默认是禁用的。要启用 API Key 认证：

# 编辑 .env 文件
nano .env

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

启用后，客户端需要通过以下方式之一提供 API Key：

• HTTP Header: X-API-Key: your-secure-api-key-here
• Query 参数: ?api_key=your-secure-api-key-here
• Authorization Bearer: Authorization: Bearer your-secure-api-key-here

WebSocket 连接需要通过 query 参数提供 API Key：

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

启动后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

方法	端点	描述
POST	/api/v1/tasks	提交任务
GET	/api/v1/tasks/{task_id}	查询任务状态
DELETE	/api/v1/tasks/{task_id}	取消任务
GET	/api/v1/tasks	列出任务
GET	/api/v1/tasks/{task_id}/stream	SSE 实时进度

端点	描述
WS /ws/task/{task_id}	双向通信（发送消息、取消任务）
WS /ws/task/{task_id}/stream	任务进度流式推送

方法	端点	描述
GET	/api/v1/workspaces/{workspace_id}/files	列出目录
POST	/api/v1/workspaces/{workspace_id}/files/upload	上传文件
GET	/api/v1/workspaces/{workspace_id}/files/download	下载文件
POST	/api/v1/workspaces/{workspace_id}/directories	创建目录
DELETE	/api/v1/workspaces/{workspace_id}/files	删除文件

方法	端点	描述
GET	/health	健康检查
GET	/health/detailed	详细健康检查

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

SSE 事件流:

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"}

JavaScript 客户端示例:

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 配置包含：

• 多阶段构建: 减小镜像大小
• 非 root 用户: 增强安全性
• 健康检查: 自动检测服务状态
• .dockerignore: 排除不必要的文件

# 构建并启动服务
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

详见 .env.example 文件。

关键配置项:

• HERMES_HOME: Hermes Agent 工作目录
• TASK_DB_PATH: 任务数据库路径
• MAX_CONCURRENT_TASKS: 最大并发任务数
• TASK_CLEANUP_*: 任务清理相关配置

项目使用 black 和 isort 进行代码格式化。

# 安装开发依赖
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/

MIT License

欢迎提交 Issue 和 Pull Request！

如有问题或建议，请提交 Issue。