58 lines
3.2 KiB
Markdown
58 lines
3.2 KiB
Markdown
# 公网兼容对话入口 v1 架构
|
||
|
||
## 1. 调用链
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
C[既有用户客户端] -->|HTTPS + xtoken\nDashScope 风格 JSON/SSE| N[Nginx]
|
||
N -->|HTTP 127.0.0.1:8080| D[兼容 Chat Handler]
|
||
D -->|ChatRequest / ChatTurn| S[共享 Chat Service]
|
||
S -->|Provider-neutral port| A[SuperAgent Adapter]
|
||
A -->|Open API Key + HTTPS/SSE| SA[SuperAgent]
|
||
SA -->|独立 MCP Bearer| M[同域 /mcp]
|
||
M --> P[(PostgreSQL/PostGIS)]
|
||
```
|
||
|
||
Nginx 不再直接调用 DashScope。它只负责 TLS、精确公开路径、基础限流和 SSE 传输设置；所有应用鉴权、输入校验、会话映射和上游调用都在 Go 服务内完成。
|
||
|
||
## 2. 双入站协议、单一用例
|
||
|
||
| 入站接口 | 面向对象 | 鉴权 Header | 请求字段 | 成功事件 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `/api/chat` | 本项目原生客户端 | `Authorization: Bearer` | `message`、`conversation_id` | `conversation`、`progress`、`message`、`done` |
|
||
| `/api/v1/apps/{app_id}/completion` | 既有 DashScope 风格客户端 | `xtoken` | `input.prompt`、`input.session_id`、受限 `parameters` | `result`，最终 `finish_reason=stop` |
|
||
|
||
两个 Handler 都调用同一个 `ChatService.Prepare` 和 `ChatTurn.Stream`。兼容层只负责协议转换，不复制会话或 SuperAgent 业务逻辑。
|
||
|
||
## 3. 标识映射
|
||
|
||
```text
|
||
兼容 output.session_id
|
||
= 本地 conversation_id
|
||
-> Chat Service 内存映射
|
||
-> Provider session_id（永不返回客户端）
|
||
```
|
||
|
||
兼容 URL 中的 `app_id` 是配置的公开路由标识。它不能选择任意 Profile，也不参与授权；SuperAgent 目标仍由服务端 Base URL、Key 和已发布 Profile 决定。
|
||
|
||
## 4. 严格结果边界
|
||
|
||
兼容 Handler 会尽早发送一个无正文的 `result` 事件，让客户端取得会话 ID并建立 SSE。正文不会跟随上游 `message.delta` 实时透传。只有既有 Adapter 验证最终内容、成功 Run 和流终止标记后，Handler 才发送 `finish_reason=stop` 与最终文本。
|
||
|
||
这样保留了当前应急辅助场景的失败语义：断流或 Provider 协议不完整时，客户端不会把半截模型文本误当成已完成方案。代价是首版没有逐字动画；如后续必须实时输出，需要独立安全决策、取消/失败 UX 和新 Spec。
|
||
|
||
## 5. 网络与伸缩边界
|
||
|
||
- Go 推荐只监听 `127.0.0.1:8080`，公网只开放 Nginx 443；PostgreSQL 5432 不对公网开放。
|
||
- Nginx 对兼容路径关闭缓冲、缓存、gzip 和重试，超时必须覆盖 Go Chat Run Timeout。
|
||
- `/mcp` 使用独立 Bearer；Chat `xtoken`、MCP Bearer 与 SuperAgent Open API Key 三者不得复用。
|
||
- 当前会话在单进程内存中。多实例部署必须先实现共享会话映射或粘性路由；否则后续轮次可能落到另一实例并返回 404。
|
||
- 浏览器可读取静态 `xtoken`，所以该入口仍只适用于受控联调；生产最终用户入口需要真实身份认证和动态授权。
|
||
|
||
## 6. 相关文档
|
||
|
||
- [`../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md`](../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md)
|
||
- [`chat-api-v1.md`](chat-api-v1.md)
|
||
- [`../workflows/user-chat.md`](../workflows/user-chat.md)
|
||
- [`../project/operations/nginx-public-entry.md`](../project/operations/nginx-public-entry.md)
|