如何玩转 Cursor2API-go 流式 API?SSE 逐字输出、delta.tool_calls 与 [DONE] 机制深度解析
如何玩转 Cursor2API-go 流式 API?SSE 逐字输出、delta.tool_calls 与 [DONE] 机制深度解析
Cursor2API-go 是一个用 Go 编写的 AI 模型 API 网关服务,可将 Cursor Web 转换为 OpenAI 兼容的 chat/completions 接口。这篇文章带你深度解析它的流式 API实现:从 stream: true 请求发起,到 SSE(Server-Sent Events)逐字推送、delta.tool_calls 工具调用协议,再到 [DONE] 结束标记的完整链路,帮你轻松上手流式调用与调试。
🎯 为什么需要流式(SSE)输出?
非流式请求要等模型把整段答案生成完才返回,长回答的等待感非常明显。而流式 API 采用 SSE 增量推送:模型每生成一小段内容就立即推送给客户端,实现"逐字输出"的打字机效果。
Cursor2API-go 在同一个接口 handlers/handler.go 中同时支持两种模式:
stream: false—— 一次性返回完整 JSON;stream: true—— 返回text/event-stream事件流,支持delta.content与delta.tool_calls。
上图是服务启动后的总览面板(static/docs.html),可以清楚看到"支持 SSE 流式响应""Tool Calls""Thinking"等能力卡片。
🚀 快速上手:3 步发起流式调用
第 1 步:启动服务
# Linux/macOS
./start.sh
# 或 Docker
docker run -d --name cursor2api-go -p 8002:8002 cursor2api-go
服务默认监听 http://localhost:8002,默认 API Key 为 0000(建议通过 API_KEY 环境变量修改,见 config/config.go)。
第 2 步:带上 stream: true 发请求
curl -N -X POST http://localhost:8002/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 0000" \
-d '{
"model": "gemini-3-flash",
"stream": true,
"messages": [{"role": "user", "content": "用一句话介绍 SSE"}]
}'
💡
curl记得加-N(--no-buffer),否则终端会等响应结束才一次性显示,看不到逐字效果。
第 3 步:观察事件流输出
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1728800000,"model":"gemini-3-flash","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1728800000,"model":"gemini-3-flash","choices":[{"index":0,"delta":{"content":"SSE 是"},"finish_reason":null}]}
data: [DONE]
🔍 SSE 逐字输出机制深度解析
流式响应的核心实现在 utils/utils.go 的 StreamChatCompletion 函数中,链路非常清晰:
| 步骤 | 动作 | 说明 |
|---|---|---|
| 1 | 设置响应头 | Content-Type: text/event-stream、Cache-Control: no-cache、Connection: keep-alive |
| 2 | 首包发送角色 | 第一个 chunk 只含 delta.role: "assistant" |
| 3 | 逐段推送内容 | 每收到一段增量就写一个 data: {json}\n\n 事件 |
| 4 | 每段立即 Flush | 调用 http.Flusher.Flush() 保证"逐字"可见 |
关键细节有两个:
- 每个事件后立即 Flush:写入函数 writeJSONEvent 在写完一行
data:后马上刷新缓冲区,这是"逐字输出"体验的直接来源; - 性能优化:JSON 编码使用 jsonBufferPool(
sync.Pool复用字节缓冲区),减少高频流式推送下的 GC 压力。
同时你可以用 curl 的 -N 参数,或任意 SSE 客户端(如 EventSource、OpenAI SDK 的 stream 参数)消费这条事件流。
上图展示了通过 API 桥接后,模型逐步推送长答案的实际效果——前端无需等待整篇生成完成即可渲染。
🧩 delta.tool_calls:工具调用如何流式传输
当请求携带 tools 参数且模型决定调用工具时,流式输出就不再是纯文字,而是携带 delta.tool_calls。数据模型定义在 models/models.go:
data: {"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_xxx","type":"function","function":{"name":"get_weather","arguments":"{\"city\": \"北京\"}"}}]},"finish_reason":null}]}
data: {"choices":[{"index":0,"delta":{},"finish_reason":"tool_calls"}]}
data: [DONE]
背后的原理值得展开讲:Cursor 上游并没有原生的 OpenAI 工具调用,Cursor2API-go 通过内部提示词 + 协议解析器搭了座桥。解析器 CursorProtocolParser 逐段接收上游纯文本增量,识别 <invoke name="...">...</invoke> 标记,将其还原成标准的 ToolCall 结构(含随机生成的 call_ 前缀 ID 和经 json.Compact 压缩的参数字符串)。
整个能力矩阵与边界(如 thinking 模型派生规则)可参阅 docs/API_CAPABILITIES.md。
🏁 [DONE] 机制:流如何优雅结束
[DONE] 是 OpenAI 流式协议约定的流结束标记,Cursor2API-go 的行为如下:
- 正常结束:内部事件通道(channel)关闭时,先补发一个带
finish_reason的收尾 chunk——普通文本为stop,发生过工具调用则为tool_calls(见 StreamChatCompletion),随后由 WriteSSEEvent 写出data: [DONE]\n\n; - 上游信号:上游 Cursor 的 SSE 流中,
<a href="https://link.gitcode.com/i/32f37b6cd85432861fb91e9621621efd" target="_blank">DONE]或type: "finish"事件会触发解析器 flush,把缓冲中的残余内容(如未闭合的思考标签)全部吐出后再收尾(见 [consumeSSE); - 错误结束:流中途出错时,客户端同样会收到
[DONE]提前结束,完整错误由服务日志与上游错误事件(type: "error")记录。
客户端侧只需一条简单规则:收到 data: [DONE] 即停止读取,并拼接此前所有 delta.content / delta.tool_calls 得到完整结果。
⚠️ 避坑指南:3 个高频问题
① 经过 Nginx 代理时内容被"憋住"一次性输出
服务端已主动设置 X-Accel-Buffering: no 请求头(utils/utils.go)来关闭 Nginx 缓冲。如果你自建代理层,仍需确认 proxy_buffering off; 和足够长的 proxy_read_timeout,流式才不会被中间层攒批。
② 客户端中途断开会怎样?
SafeStreamWrapper(utils/utils.go)会监听 context 取消:客户端断开后立即停止向下游写数据、释放上游连接,不会泄漏 goroutine。它还内置了 panic 恢复——只要响应尚未开始写出,就会返回标准 JSON 错误体,而不是让进程崩溃。
③ 为什么首包只有 role 没有内容?
这是 OpenAI 兼容协议的惯例:首包 delta.role: "assistant" 用于让客户端提前建立消息框架,后续 chunk 只携带增量内容。消费端应忽略空 delta 的 chunk(例如收尾的空 delta)。
✅ 上手自检清单
- [ ] 请求体中
stream: true,模型名在GET /v1/models返回列表内 - [ ] 终端
curl使用了-N参数,能观察到逐行推送 - [ ] 事件流以
data: [DONE]收尾 - [ ] 工具调用场景中正确拼接了
delta.tool_calls并处理finish_reason: "tool_calls" - [ ] 反向代理未开启缓冲,超时时间已放宽
掌握以上机制后,你就可以把 Cursor2API-go 当作标准 OpenAI 端点接入任何支持 SSE 流式的前端或框架——逐字输出、工具调用、优雅收尾,一个都不缺。


