Hermes Agent 远程接入指南：API Server 与 Webhook #

# 1. 配置 API Server
hermes gateway setup          # 选择 "API Server" 平台
# 会要求设置：
#   - 监听端口（默认 8642）
#   - API Server Key（用于鉴权）

# 2. 前台运行（测试用）
hermes gateway run

# 3. 安装为后台服务（生产用）
hermes gateway install
hermes gateway start

# 4. 检查状态
hermes gateway status

curl -X POST http://localhost:8642/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "hermes-agent",
    "messages": [
      {"role": "user", "content": "帮我分析服务器上最近10条Nginx错误日志"}
    ],
    "stream": false
  }'

# 第一次请求
curl -X POST http://localhost:8642/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Hermes-Session-Id: my-project-001" \
  -d '{
    "model": "hermes-agent",
    "messages": [
      {"role": "user", "content": "检查 /var/log 目录的磁盘使用情况"}
    ]
  }'

# 后续请求 — 同一会话，保持上下文
curl -X POST http://localhost:8642/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Hermes-Session-Id: my-project-001" \
  -d '{
    "model": "hermes-agent",
    "messages": [
      {"role": "user", "content": "基于上面的结果，清理最占空间的目录"}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="hermes-agent",
    messages=[{"role": "user", "content": "列出当前系统运行的所有进程"}],
)

print(response.choices[0].message.content)

# 启动运行 — 立即返回 run_id
curl -X POST http://localhost:8642/v1/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "message": "分析项目代码库，生成架构报告保存到 ~/report.md"
  }'
# 返回: {"run_id": "abc123", "status": "running"}

# 轮询状态
curl http://localhost:8642/v1/runs/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
# 返回: {"run_id": "abc123", "status": "completed", "response": "..."}

# 或通过 SSE 实时流式获取事件
curl http://localhost:8642/v1/runs/abc123/events \
  -H "Authorization: Bearer YOUR_API_KEY"

# 查看待审批的命令
curl http://localhost:8642/v1/runs/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
# 返回: {"status": "pending_approval", "approval_request": "..."}

# 批准
curl -X POST http://localhost:8642/v1/runs/abc123/approval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"action": "approve"}'

# 拒绝
curl -X POST http://localhost:8642/v1/runs/abc123/approval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"action": "deny"}'

# 1. 配置 Webhook
hermes gateway setup          # 选择 "Webhook" 平台
# 会要求设置：
#   - 监听端口（默认 8644）
#   - HMAC Secret（签名验证密钥）

# 2. 运行
hermes gateway run            # 前台
hermes gateway install        # 后台服务
hermes gateway start

webhook:
  host: "0.0.0.0"        # 监听地址（0.0.0.0 = 公开，127.0.0.1 = 仅本地）
  port: 8644              # 监听端口
  secret: "YOUR_SECRET"   # 全局 HMAC 密钥（推荐）
  rate_limit: 30          # 每分钟最大请求数
  max_body_bytes: 1048576 # 请求体大小限制（1MB）
  routes:
    ci-review:            # 路由名称
      events: ["push", "pull_request"]  # 接受的事件类型（可选）
      secret: "CI_SECRET"               # 路由级 HMAC 密钥
      prompt: "收到CI事件: {{payload}}，请审查代码变更"  # 提示词模板
      skills: ["github-code-review"]    # 可选：预加载技能
      deliver: "dingtalk"               # 结果投递目标
      deliver_extra:                    # 投递额外参数
        chat_id: "YOUR_CHAT_ID"
    log-analysis:
      events: []
      secret: "LOG_SECRET"
      prompt: "分析以下日志并给出建议: {{payload}}"
      deliver: "log"                    # 仅记录日志，不投递

# 创建一个 webhook 订阅
hermes webhook subscribe my-service
# 会生成 /webhooks/my-service 端点

# 查看所有订阅
hermes webhook list

# 测试
hermes webhook test my-service

# 删除
hermes webhook remove my-service

curl -X POST http://YOUR_SERVER:8644/webhooks/ci-review \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=<HMAC_SIGNATURE>" \
  -d '{
    "action": "opened",
    "pull_request": {
      "number": 42,
      "title": "Fix authentication bug",
      "head": {"sha": "abc123"}
    }
  }'

# Python 示例
import hmac, hashlib, json

secret = b"CI_SECRET"
body = json.dumps(payload).encode()
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()
# Header: X-Hub-Signature-256: sha256=<signature>

routes:
  test-route:
    secret: "INSECURE_NO_AUTH"    # 仅用于本地测试！
    prompt: "测试消息: {{payload}}"
    deliver: "log"

webhook:
  routes:
    github-pr:
      secret: "GITHUB_WEBHOOK_SECRET"
      prompt: |
        GitHub PR 事件收到：
        仓库: {{payload.repository.full_name}}
        PR #{{payload.pull_request.number}}: {{payload.pull_request.title}}
        请审查此 PR 的代码变更，重点关注安全性和性能问题。
      skills: ["github-code-review"]
      deliver: "github_comment"
      deliver_extra:
        repo: "{{payload.repository.full_name}}"
        pr_number: "{{payload.pull_request.number}}"

webhook:
  routes:
    alert-handler:
      secret: "ALERT_SECRET"
      prompt: |
        收到监控告警，请分析原因并给出修复建议：
        {{payload}}
      deliver: "dingtalk"
      deliver_extra:
        chat_id: "YOUR_DINGTALK_CHAT_ID"

webhook:
  routes:
    deploy-notify:
      secret: "DEPLOY_SECRET"
      prompt: "🚀 部署完成：{{payload.environment}} - {{payload.status}}"
      deliver_only: true          # 跳过 Agent，直接投递
      deliver: "dingtalk"
      deliver_extra:
        chat_id: "YOUR_DINGTALK_CHAT_ID"