POST /api/chat 端点设计
从 clawline 提取。Gateway 新增的 POST /api/chat 端点和虚拟连接机制详细设计。
POST /api/chat 端点设计
新增 HTTP API 端点 POST /api/chat，支持外部通过 REST API 方式向已注册 Agent 发送消息并接收回复，类似之前 Mattermost 的 API 机器人交互方式。
核心设计：通过「虚拟连接」模拟 WebSocket 客户端，使后端 Channel 插件完全感知不到这是 API 调用还是真实 WS 客户端。
请求参数
{
"channelId": "string", // 必填
"chatId": "string", // 可选
"senderId": "string", // 可选
"agentId": "string", // 可选
"message": "string", // 必填
"timeout": 30000 // 可选，默认 30s
}虚拟连接机制
- 创建临时
connectionId（randomUUID()） - 注册到
clientConnections，ws: null（无真实 WebSocket） - 用
EventEmitter作为_apiCallback收集回复 - 向 backend 发
relay.client.open+relay.client.event (message.receive) - 等待
message.send回复或超时 - 清理虚拟连接，发
relay.client.close
server.js 改动清单（3 处，~80 行）
| 改动点 | 位置 | 行数 | 说明 |
|---|---|---|---|
POST /api/chat handler | HTTP 路由区（~1590行后） | ~70行 | 新增端点 |
relay.server.event 分发 | ~989行 | ~8行 | 加 _apiCallback 分支 |
closeSocket 空值守卫 | ~636行 | 1行 | 防 null ws |
API Source 标识（meta.source）
API 调用的消息通过 meta.source = "api" 字段贯穿全链路：
POST /api/chat → relay.client.event 携带 source:"api"
→ channel 插件透传给 agent
→ agent 回复时 meta.source 透传
→ persistMessageAsync 存入 cl_messages.meta
→ 前端渲染时读取 meta.source 展示标识
全链路改动汇总
| 文件 | 改动 | 行数 |
|---|---|---|
gateway-repo/server.js | closeSocket守卫 + apiCallback分支 + POST /api/chat handler，inbound meta.source | ~80行 |
channel-repo/src/generic/bot.ts 或 send.ts | 透传 meta.source 到回复 | ~8行 |
repo/src/components/chat/types.ts | Message 加 meta 字段 | 2行 |
repo/src/screens/ChatRoom.tsx | 解析 meta 字段 | 5行 |
repo/src/components/chat/MessageItem.tsx | 渲染 API 标识 badge | 10行 |
关键决策：Channel 插件、Client-Web、SDK 都不需要改核心逻辑 — 虚拟连接走标准 relay 协议。