CMDC Gateway

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

安装

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

快速开始

1. 配置

# 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. 启动服务器

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

3. 调用 API

# 创建 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。

环境变量

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

Docker 部署

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

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

许可证

Apache-2.0 + Commons Clause — 详见 LICENSE。

Next Page → API Reference