Gateway/API 模块实施状态
最后更新：2026-03-22 关联里程碑：核心基础设施
1. 模块概览
Gateway 是 pyclaw 的核心服务进程，基于 FastAPI 构建，负责： - 接收来自各通道和客户端的消息 - 路由到 Agent 处理 - 将回复发送回去
2. 服务端点
| 端点 | 协议 | 状态 | 完成度 | 功能说明 |
/ws | WebSocket v3 | ✅ 完成 | 100% | 双向实时通信，25+ RPC方法 |
/v1/chat/completions | HTTP | ✅ 完成 | 100% | OpenAI兼容API |
/v1/models | HTTP | ✅ 完成 | 100% | OpenAI兼容模型列表 |
默认监听：127.0.0.1:18777
3. WebSocket 协议 v3
3.1 帧类型
| 帧类型 | 状态 | 说明 |
| 请求帧 | ✅ 完成 | id, method, params |
| 响应帧 | ✅ 完成 | id, result / error |
| 事件帧 | ✅ 完成 | event, data |
3.2 RPC 方法（25+）
| 方法分类 | 方法 | 状态 |
| 聊天 | chat.send, chat.delta, chat.done | ✅ 完成 |
| 会话 | sessions.list, sessions.get, sessions.delete | ✅ 完成 |
| 配置 | config.get, config.set, config.reload | ✅ 完成 |
| Agent | agents.list, agents.switch | ✅ 完成 |
| 技能 | skills.list, skills.run | ✅ 完成 |
| 状态 | status.get, status.subscribe | ✅ 完成 |
| 工具 | tools.list, tools.approve | ✅ 完成 |
4. OpenAI 兼容层
| 功能 | 状态 | 完成度 | 说明 |
| Chat Completions | ✅ 完成 | 100% | 可替代OpenAI SDK使用 |
| Models API | ✅ 完成 | 100% | 模型列表 |
| 流式响应 | ✅ 完成 | 100% | SSE流式输出 |
| Token统计 | ✅ 完成 | 100% | usage字段 |
5. Gateway 服务特性
| 特性 | 状态 | 说明 |
| 多客户端并发 | ✅ 完成 | 支持多客户端同时连接 |
| 插件加载 | ✅ 完成 | _load_plugins |
| 配置监控 | ✅ 完成 | _start_config_watcher 热重载 |
| Token认证 | ✅ 完成 | 可选Token认证 |
| 默认绑定 | ✅ 完成 | 默认 127.0.0.1，防止未授权访问 |
6. 协议层
| 组件 | 文件 | 状态 | 说明 |
| 帧定义 | protocol/ | ✅ 完成 | JSON帧格式定义 |
| 方法分发 | methods/ | ✅ 完成 | 按method字段路由 |
| 事件广播 | events.py | ✅ 完成 | 事件推送机制 |
7. ACP Bridge
| 组件 | 文件 | 状态 | 说明 |
| ACP Bridge | src/pyclaw/acp/ | ✅ 完成 | Agent Communication Protocol桥接 |
8. 关键文件索引
| 文件 | 职责 |
src/pyclaw/gateway/server.py | FastAPI应用、WebSocket端点 |
src/pyclaw/gateway/openai_compat.py | OpenAI兼容层 |
src/pyclaw/gateway/protocol/ | 帧定义 |
src/pyclaw/gateway/methods/ | RPC方法处理器 |
src/pyclaw/gateway/events.py | 事件广播 |
docs/api-reference.md | API参考文档 |
9. 待办事项
- [ ] WebSocket协议v3文档完善
- [ ] RPC方法完整列表文档化
- [ ] 性能基准测试