后端对接示例
本章提供后端示例，帮助 Umo Editor Next 发送的 params 接到任意大模型提供商（OpenAI / DeepSeek等）或自建 Agent 框架。
后端要做的核心工作是：选择协议 + 组装提示词 + 输出 SSE
接口契约（后端会收到什么）
前端发送参数结构见 前后端交互 的 params。后端最常见用法：
- 用
systemPrompt作为 system 消息 - 用
prompt作为 user 消息 - 用
selectionNodes/document作为可编辑/可参考上下文 - 用
skill/from/reasoning做路由与策略选择
自定义协议（default）：
你可以在 Umo Editor Server 源码中获得完整的示例，从而快速上手。
默认协议的对接建议
分两路输出：thinking + markdown
- thinking：给用户“正在做什么”的可视反馈（不要太长）
- markdown：最终要写回编辑器的内容（建议是完整段落/列表/代码块）
不要把多行 Markdown 直接写入 SSE data
错误做法：
data: 第一行
第二行正确做法：
data: {"type":"text","content":"第一行\\n\\n第二行"}AG-UI（agui）对接建议
当 ai.models[].protocol === 'agui' 时，前端不走 ai.callbacks.onMessage，而是由消息引擎自动解析 AG-UI 事件。
后端需要做：
- 按 AG-UI 事件类型输出 SSE
- 把工具调用、状态更新等过程用事件表达
如果已经有 agent 框架（LangGraph / LlamaIndex / 自研），AG-UI 更适合用于表达“多步骤任务 + 工具链进度”。
主流大模型快速接入
很多主流大模型提供商提供 “OpenAI-compatible” 的接口形态（通常兼容 POST /v1/chat/completions 且支持 stream: true 返回 SSE）。推荐的接入方式是：
- 前端：仍然接入自己的
/api/chat（协议为default或agui） - 后端：把
/api/chat作为代理/适配层，调用上游 OpenAI 兼容接口，并把上游 SSE 转发/转换为 Umo Editor Next 约定的 SSE chunk
如何把 OpenAI-compatible Chat Completions 的流转为 default SSE？
你可以在 Umo Editor Server 源码中获得完整的示例，从而快速上手。
当然也可以不通过后端转换，直接在 ai.callbacks.onMessage 里面直接解析主流大模型返回的 SSE delta，做自定义映射。
为什么不建议浏览器直连 OpenAI-compatible？
- 必须把 API Key 暴露到浏览器（极不安全）
- 许多厂商对浏览器 SSE 有额外限制（CORS、Header、频控）
- 需要做审计、限流、配额、敏感信息过滤时，后端代理是必需的
安全要点
做最小化日志
params 里包含 document（全文 Markdown）与 selectionNodes（选区）：
- 不要把
document等内容全量打到日志，可能会暴露用户隐私 - 文档内容可能较大，会导致日志体积庞大
限流与配额
建议后端按 (userID, documentID) 做：
- 请求速率限制（防止恶意刷接口）
- 并发限制（避免一个用户占满资源）
- 计费/配额（如果接第三方大模型计费）
处理 Abort
前端停止生成会调用消息引擎终止协议：
chatEngine.abortChat()
后端建议支持：
- 客户端断开连接时中止模型请求（减少成本）
- 对长连接 SSE 及时释放资源
参数策略
如何让模型更“听话”，最有效的组合通常是：
systemPrompt：提供硬规则（输出格式、编辑范围、语言）selectionNodes：提供严格可编辑范围（有选区时优先使用）document：提供全局上下文与插入点（marker）skill/from：控制语气与输出形态（编辑型 vs 对话型）
如果发现模型仍然越界修改，优先做两件事：
- 把
selectionNodes放到最前且明确“只允许改 marker 之间内容” - 在后端做输出检查：如果输出包含 marker 以外的上下文复述或大段无关内容，直接拒绝/重试