DS2API assistantturn输出语义层四种协议如何统一到同一turn模型【免费下载链接】ds2apiDeepSeek-Compatible Middleware Interface: A technical exploration project in Go, focusing on high-concurrency protocol adaptation. It serves as a reference implementation for converting diverse web protocols into standardized formats.项目地址: https://gitcode.com/GitHub_Trending/ds/ds2apiDS2API 是一个把 DeepSeek 网页协议转换为 OpenAI、Claude、Gemini 等标准接口的 Go 语言中间件。它的internal/assistantturn输出语义层解决了一个核心问题四种对外协议、流式与非流式两种输出模式如何收敛到同一套 assistant turn 模型上。本文将带你快速看懂这套设计。一、问题4 种协议 × 2 种模式 8 份重复代码DS2API 对外提供四套 API协议路由入口典型形态OpenAI Chat Completions/v1/chat/completionschoices finish_reasonOpenAI Responses/v1/responsesresponse 对象 usageClaude Messages/v1/messagescontent blocks stop_reasonGemini generateContent/v1beta/.../generateContentcandidates parts每种协议又有非流式一次性返回 JSON和流式SSE 增量推送两种输出。如果各写各的收尾逻辑工具调用识别、思考内容清洗、引用链接替换、token 用量统计、空输出判定这些语义就要在 8 处重复实现且极易不一致。DS2API 的做法是在 docs/ARCHITECTURE.md 描述的请求主链路中于流式消费引擎与协议格式化层之间插入一个输出语义层——internal/assistantturn。上游不管来自哪条路径最终都归一为一个Turn再由各协议渲染器翻译回各自的 JSON 结构。二、turn 模型一次 assistant 回复的完整快照核心结构定义在 turn.gotype Turn struct { Text string // 清洗后的正文 Thinking string // 清洗后的思考内容 ToolCalls []toolcall.ParsedToolCall // 解析出的工具调用 CitationLinks map[int]string // 引用链接 ContentFilter bool // 是否被内容过滤 StopReason StopReason // stop / tool_calls / content_filter / error Usage Usage // 输入/输出/推理/总 token Error *OutputError // 输出侧校验错误 }它同时保留了RawText/RawThinking原始片段供 responsehistory 在协议回译前归档原始输出。值得注意的语义约定停止原因优先级内容过滤 工具调用 正常结束见 turn.go#L104-L110空输出判定无工具调用、无正文时区分限流只返回思考429、内容过滤400、上游不可用503三种错误见 UpstreamEmptyOutputDetail空输出重试ShouldRetryEmptyOutput 供 empty_retry_runtime.go 判断是否换账号重试三、两个入口非流式收集 vs 流式快照语义层只有两个构建入口分别对应两种输出模式入口适用模式输入来源BuildTurnFromCollected非流式sse.CollectResult完整收集结果BuildTurnFromStreamSnapshot流式收尾StreamSnapshot流式累积快照流式路径中累积器 Accumulator 逐块消费 internal/sse 的解析结果维护正文、思考、工具调用检测等多条缓冲区流结束时一次性Snapshot()交给BuildTurnFromStreamSnapshot。流式入口还处理了两个协议特有的状态位AlreadyEmittedCalls/AlreadyEmittedToolRaw——如果工具调用在流式过程中已经推给客户端收尾时不能再报tool_choice冲突错误。这种过程中已发生的事实被显式建模避免了收尾逻辑与推送逻辑打架。四、四种协议如何共用同一个 turn四个协议的处理器在收尾阶段都遵循同一套三步曲构建 Turn → FinalizeTurn → 渲染响应。1️⃣ OpenAI Chat Completionshandler_chat.go#L169-L190 中构建 Turn 后用 OpenAIChatUsage 生成prompt_tokens / completion_tokens及reasoning_tokens明细finish_reason直接取 FinishReasonstop/tool_calls/content_filter与 OpenAI 官方枚举一一对应。2️⃣ OpenAI Responsesresponses_handler.go#L153-L170 使用同一 Turn仅用量字段不同——OpenAIResponsesUsage 输出input_tokens / output_tokens对应 Responses API 的字段命名。工具调用流式细节见 responses_stream_runtime_toolcalls.go。3️⃣ Claude MessagesClaude 的块状内容模型由 format/claude/render.go 直接从 Turn 渲染Turn.Thinking→thinking块Turn.ToolCalls→tool_use块并生成toolu_前缀 IDStopReason映射为 Claude 的end_turn/tool_use。流式收尾见 stream_runtime_finalize.go#L117-L135。4️⃣ Gemini generateContenthandler_generate.go 的buildGeminiPartsFromTurn把Turn.Text翻译成text类型的Part工具调用翻译成对应结构流式路径通过 handler_stream_runtime.go#L306-L322 在收尾时构建 Turn 并取FinishReason填充finishReason字段。 关键设计渲染器只读 Turn不做语义判断。工具调用解析、内容清洗、引用替换全部前置到语义层四个渲染器变成纯粹的结构翻译器。五、FinalizeTurn统一出口判定FinalizeTurn 在 Turn 之上做最后一次裁决产出FinalOutcomeFinishReason各协议的结束原因有工具调用时强制为tool_callsShouldFailError是否输出侧校验失败如tool_choice要求调用工具但未调用见 ValidateTurnHasVisibleOutput正文 / 思考 / 工具调用三者是否有任意可见输出供各协议决定是否需要兜底文案或报错这一步保证了无论客户端请求的是 Chat、Responses、Claude 还是 Gemini这次输出算成功还是失败的判定标准完全一致——这是多协议网关最容易失守的语义一致性环节。六、这套分层设计值得借鉴的点 语义与结构解耦Turn只关心模型说了什么、为什么停各协议 JSON 结构只是它的视图。新增第五种协议时只需写一个渲染器不用重写语义。流式/非流式同构两个构建入口输出同一个Turn类型下游FinalizeTurn与渲染器完全复用流式路径不再需要一套平行的收尾代码。错误语义前置内容过滤、限流、上游不可用的区分在语义层完成各协议只需映射自己的状态码与文案。状态显式化AlreadyEmittedToolCalls这类推送已发生的事实进入 Turn 构建参数消除流式收尾的竞态歧义。七、延伸阅读与模块索引 模块路径职责输出语义层internal/assistantturn/Turn 模型与流事件定义统一测试turn_test.go语义层行为回归流式引擎internal/stream/统一流式消费SSE 解析internal/sse/上游增量解析工具调用解析internal/toolcall/DSML/XML 工具调用归一非流式运行时internal/completionruntime/nonstream.go收集 空输出重试工具调用语义专题docs/toolcall-semantics.md工具调用行为说明理解完这套 turn 模型后再阅读各协议渲染器会非常轻松——它们的差异全部是翻译差异而不是逻辑差异。这正是 DS2API 能同时稳定维护四种协议输出一致性的根本原因。【免费下载链接】ds2apiDeepSeek-Compatible Middleware Interface: A technical exploration project in Go, focusing on high-concurrency protocol adaptation. It serves as a reference implementation for converting diverse web protocols into standardized formats.项目地址: https://gitcode.com/GitHub_Trending/ds/ds2api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DS2API assistantturn输出语义层：四种协议如何统一到同一turn模型
DS2API assistantturn输出语义层四种协议如何统一到同一turn模型【免费下载链接】ds2apiDeepSeek-Compatible Middleware Interface: A technical exploration project in Go, focusing on high-concurrency protocol adaptation. It serves as a reference implementation for converting diverse web protocols into standardized formats.项目地址: https://gitcode.com/GitHub_Trending/ds/ds2apiDS2API 是一个把 DeepSeek 网页协议转换为 OpenAI、Claude、Gemini 等标准接口的 Go 语言中间件。它的internal/assistantturn输出语义层解决了一个核心问题四种对外协议、流式与非流式两种输出模式如何收敛到同一套 assistant turn 模型上。本文将带你快速看懂这套设计。一、问题4 种协议 × 2 种模式 8 份重复代码DS2API 对外提供四套 API协议路由入口典型形态OpenAI Chat Completions/v1/chat/completionschoices finish_reasonOpenAI Responses/v1/responsesresponse 对象 usageClaude Messages/v1/messagescontent blocks stop_reasonGemini generateContent/v1beta/.../generateContentcandidates parts每种协议又有非流式一次性返回 JSON和流式SSE 增量推送两种输出。如果各写各的收尾逻辑工具调用识别、思考内容清洗、引用链接替换、token 用量统计、空输出判定这些语义就要在 8 处重复实现且极易不一致。DS2API 的做法是在 docs/ARCHITECTURE.md 描述的请求主链路中于流式消费引擎与协议格式化层之间插入一个输出语义层——internal/assistantturn。上游不管来自哪条路径最终都归一为一个Turn再由各协议渲染器翻译回各自的 JSON 结构。二、turn 模型一次 assistant 回复的完整快照核心结构定义在 turn.gotype Turn struct { Text string // 清洗后的正文 Thinking string // 清洗后的思考内容 ToolCalls []toolcall.ParsedToolCall // 解析出的工具调用 CitationLinks map[int]string // 引用链接 ContentFilter bool // 是否被内容过滤 StopReason StopReason // stop / tool_calls / content_filter / error Usage Usage // 输入/输出/推理/总 token Error *OutputError // 输出侧校验错误 }它同时保留了RawText/RawThinking原始片段供 responsehistory 在协议回译前归档原始输出。值得注意的语义约定停止原因优先级内容过滤 工具调用 正常结束见 turn.go#L104-L110空输出判定无工具调用、无正文时区分限流只返回思考429、内容过滤400、上游不可用503三种错误见 UpstreamEmptyOutputDetail空输出重试ShouldRetryEmptyOutput 供 empty_retry_runtime.go 判断是否换账号重试三、两个入口非流式收集 vs 流式快照语义层只有两个构建入口分别对应两种输出模式入口适用模式输入来源BuildTurnFromCollected非流式sse.CollectResult完整收集结果BuildTurnFromStreamSnapshot流式收尾StreamSnapshot流式累积快照流式路径中累积器 Accumulator 逐块消费 internal/sse 的解析结果维护正文、思考、工具调用检测等多条缓冲区流结束时一次性Snapshot()交给BuildTurnFromStreamSnapshot。流式入口还处理了两个协议特有的状态位AlreadyEmittedCalls/AlreadyEmittedToolRaw——如果工具调用在流式过程中已经推给客户端收尾时不能再报tool_choice冲突错误。这种过程中已发生的事实被显式建模避免了收尾逻辑与推送逻辑打架。四、四种协议如何共用同一个 turn四个协议的处理器在收尾阶段都遵循同一套三步曲构建 Turn → FinalizeTurn → 渲染响应。1️⃣ OpenAI Chat Completionshandler_chat.go#L169-L190 中构建 Turn 后用 OpenAIChatUsage 生成prompt_tokens / completion_tokens及reasoning_tokens明细finish_reason直接取 FinishReasonstop/tool_calls/content_filter与 OpenAI 官方枚举一一对应。2️⃣ OpenAI Responsesresponses_handler.go#L153-L170 使用同一 Turn仅用量字段不同——OpenAIResponsesUsage 输出input_tokens / output_tokens对应 Responses API 的字段命名。工具调用流式细节见 responses_stream_runtime_toolcalls.go。3️⃣ Claude MessagesClaude 的块状内容模型由 format/claude/render.go 直接从 Turn 渲染Turn.Thinking→thinking块Turn.ToolCalls→tool_use块并生成toolu_前缀 IDStopReason映射为 Claude 的end_turn/tool_use。流式收尾见 stream_runtime_finalize.go#L117-L135。4️⃣ Gemini generateContenthandler_generate.go 的buildGeminiPartsFromTurn把Turn.Text翻译成text类型的Part工具调用翻译成对应结构流式路径通过 handler_stream_runtime.go#L306-L322 在收尾时构建 Turn 并取FinishReason填充finishReason字段。 关键设计渲染器只读 Turn不做语义判断。工具调用解析、内容清洗、引用替换全部前置到语义层四个渲染器变成纯粹的结构翻译器。五、FinalizeTurn统一出口判定FinalizeTurn 在 Turn 之上做最后一次裁决产出FinalOutcomeFinishReason各协议的结束原因有工具调用时强制为tool_callsShouldFailError是否输出侧校验失败如tool_choice要求调用工具但未调用见 ValidateTurnHasVisibleOutput正文 / 思考 / 工具调用三者是否有任意可见输出供各协议决定是否需要兜底文案或报错这一步保证了无论客户端请求的是 Chat、Responses、Claude 还是 Gemini这次输出算成功还是失败的判定标准完全一致——这是多协议网关最容易失守的语义一致性环节。六、这套分层设计值得借鉴的点 语义与结构解耦Turn只关心模型说了什么、为什么停各协议 JSON 结构只是它的视图。新增第五种协议时只需写一个渲染器不用重写语义。流式/非流式同构两个构建入口输出同一个Turn类型下游FinalizeTurn与渲染器完全复用流式路径不再需要一套平行的收尾代码。错误语义前置内容过滤、限流、上游不可用的区分在语义层完成各协议只需映射自己的状态码与文案。状态显式化AlreadyEmittedToolCalls这类推送已发生的事实进入 Turn 构建参数消除流式收尾的竞态歧义。七、延伸阅读与模块索引 模块路径职责输出语义层internal/assistantturn/Turn 模型与流事件定义统一测试turn_test.go语义层行为回归流式引擎internal/stream/统一流式消费SSE 解析internal/sse/上游增量解析工具调用解析internal/toolcall/DSML/XML 工具调用归一非流式运行时internal/completionruntime/nonstream.go收集 空输出重试工具调用语义专题docs/toolcall-semantics.md工具调用行为说明理解完这套 turn 模型后再阅读各协议渲染器会非常轻松——它们的差异全部是翻译差异而不是逻辑差异。这正是 DS2API 能同时稳定维护四种协议输出一致性的根本原因。【免费下载链接】ds2apiDeepSeek-Compatible Middleware Interface: A technical exploration project in Go, focusing on high-concurrency protocol adaptation. It serves as a reference implementation for converting diverse web protocols into standardized formats.项目地址: https://gitcode.com/GitHub_Trending/ds/ds2api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考