公网兼容对话入口 v1 架构

1. 调用链

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. 标识映射

兼容 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，所以该入口仍只适用于受控联调；生产最终用户入口需要真实身份认证和动态授权。

3.2 KiB Raw Blame History Unescape Escape