# CMDC Gateway

HTTP + SSE + WebSocket 协议网关，让任何语言的外部系统接入 CMDC Agent 能力。

## 安装

```elixir
# mix.exs
def deps do
  [{:cmdc_gateway, "~> 0.1"}]
end
```

## 快速开始

### 1. 配置

```elixir
# config/config.exs
config :cmdc_gateway, CMDCGateway.Plugs.Auth,
  api_keys: %{
    "my-api-key" => "default-tenant"
  }

# 可选：限流配置
config :cmdc_gateway, CMDCGateway.RateLimiter,
  rpm: 60,          # 每分钟最大请求数
  enabled: true
```

### 2. 启动服务器

```elixir
# 在你的 Application 中添加 Cowboy
children = [
  {Plug.Cowboy, scheme: :http, plug: CMDCGateway.Router, options: [port: 4000]}
]
```

### 3. 调用 API

```bash
# 创建 Session
curl -X POST http://localhost:4000/v1/sessions \
  -H "X-API-Key: my-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek:deepseek-chat", "systemPrompt": "你是助手"}'

# 发送 Prompt（异步返回 202）
curl -X POST http://localhost:4000/v1/sessions/{session_id}/prompt \
  -H "X-API-Key: my-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "你好"}'

# 订阅 SSE 事件流（实时接收 Agent 回复）
curl -N http://localhost:4000/v1/sessions/{session_id}/events \
  -H "X-API-Key: my-api-key"
```

## 架构

```
外部系统 (Python / Node.js / Go / 浏览器)
  │  HTTP + SSE / WebSocket
  ▼
CMDCGateway.Router
  ├── Auth Plug          API Key → tenant_id
  ├── RateLimiter Plug   令牌桶限流
  ├── SessionStore       ETS session_id ↔ Agent pid
  ├── EventTranslator    内部事件 → 对外 JSON (15 种)
  ├── SSEHandler         chunked SSE 推送 + 心跳
  ├── WSHandler          双向 WebSocket
  ├── Meter              per-key 用量计量
  └── CallbackTool       HTTP 回调工具代理
  │
  │  Elixir in-process 调用
  ▼
CMDC 核心库 (EventBus 驱动)
```

## 端点概览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/healthz` | 健康检查（无需认证） |
| POST | `/v1/sessions` | 创建 Session |
| GET | `/v1/sessions/:id` | 查询 Session 状态 |
| DELETE | `/v1/sessions/:id` | 删除 Session |
| POST | `/v1/sessions/:id/prompt` | 发送 prompt（异步 202） |
| GET | `/v1/sessions/:id/events` | SSE 事件流 |
| WS | `/v1/sessions/:id/ws` | WebSocket 双向通信 |
| POST | `/v1/sessions/:id/approve` | 审批通过 |
| POST | `/v1/sessions/:id/reject` | 审批拒绝 |
| POST | `/v1/sessions/:id/respond` | 回答 Agent 提问 |
| GET | `/v1/sessions/:id/stats` | 用量统计 |
| GET | `/v1/sessions/:id/messages` | 对话历史 |
| POST | `/v1/sessions/:id/tools` | 注册回调工具 |

> **完整 API 文档**（每个端点的详细输入/输出/字段说明/示例）见 **[API.md](API.md)**。

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GATEWAY_PORT` | HTTP 监听端口 | `4000` |
| `GATEWAY_API_KEYS` | 逗号分隔的 API Key 列表 | — |

## Docker 部署

```dockerfile
FROM elixir:1.17-otp-27-alpine AS build
WORKDIR /app
COPY . .
RUN mix deps.get --only prod && MIX_ENV=prod mix release

FROM alpine:3.19
COPY --from=build /app/_build/prod/rel/cmdc_gateway /app
ENV GATEWAY_PORT=4000
EXPOSE 4000
CMD ["/app/bin/cmdc_gateway", "start"]
```

```bash
docker build -t cmdc-gateway .
docker run -p 4000:4000 -e GATEWAY_API_KEYS=my-key cmdc-gateway
```

## 许可证

Apache-2.0 + Commons Clause — 详见 [LICENSE](../LICENSE)。