Kiro Gateway流式传输原理AWS SSE事件流解析完全指南【免费下载链接】kiro-gateway Proxy API gateway for Kiro IDE CLI (Amazon Q Developer / AWS CodeWhisperer). Use free Claude models with any client.项目地址: https://gitcode.com/gh_mirrors/ki/kiro-gatewayKiro Gateway是一个面向 Kiro IDE 与 CLI 的代理网关通过 AWS 流式传输接口让任意客户端免费使用 Claude 模型。它的核心能力之一就是把 Kiro API 返回的AWS SSE 事件流实时解析并转换成 OpenAI 或 Anthropic 格式的流式响应。本文将带你从一张图看懂流式传输全链路拆解 6 种 AWS SSE 事件类型以及首 token 超时重试、内容截断检测等实用机制帮你彻底搞懂 Kiro Gateway 流式传输原理。为什么需要流式解析普通 API 调用是一次性返回完整结果而大模型生成内容往往要等几十秒。Kiro API 的generateAssistantResponse接口只支持流式返回模型每生成一小段内容就立刻推送一个事件。这就带来三个技术难题事件是碎片化的一个完整 JSON 可能被切到两个网络包里格式不通用客户端Cursor、Claude Code 等只认 OpenAI 或 Anthropic 的 SSE 格式上游可能断流Kiro API 偶尔会截断工具调用参数Kiro Gateway 的 streaming_core.py 就是为解决这些问题而设计的统一流解析层。一图看懂流式传输全链路客户端 ──POST /v1/chat/completions──► Kiro Gateway │ 构建 Kiro 请求并转发 ▼ Kiro API (AWS) │ ◄── AWS SSE 事件流字节流 │ ① AwsEventStreamParser 解析事件 ② 统一为 KiroEvent 对象 ③ 格式化为 OpenAI / Anthropic SSE │ 客户端 ◄──── data: {...} 逐块推送 ────────┘对应到源码这条链路由四个模块协作完成阶段模块职责① 原始解析kiro/parsers.py从二进制字节流中抽取 JSON 事件② 统一事件kiro/streaming_core.py输出与 API 无关的KiroEvent③ OpenAI 格式化kiro/streaming_openai.py生成data: {...}data: [DONE]③ Anthropic 格式化kiro/streaming_anthropic.py生成event: xxxdata: {...}架构细节可参考官方文档 docs/en/ARCHITECTURE.md。AWS SSE 的 6 种核心事件类型AwsEventStreamParser内部定义了一张事件指纹表通过识别字节流中 JSON 的开头特征来分流事件见 kiro/parsers.py#L241-L249事件特征事件类型含义{content: content模型正文内容片段{name: tool_start工具调用开始含名称、ID{input: tool_input工具入参的后续分片{stop: tool_stop工具调用结束{usage: usage额度credits消耗{contextUsagePercentage: context_usage上下文占用百分比小细节{content:特征同时命中 content 和 followupPrompt 两种事件解析器会主动跳过追问建议followupPrompt避免把你可能还想问……之类的推荐词混进正文。碎片 JSON 如何拼完整网络包的大小是不固定的一个{content: 你好}完全可能一半在 A 包、一半在 B 包。解析器的解法很经典缓冲区累积每次收到字节块先追加到内部 buffer花括号计数find_matching_brace()从{开始计数遇到字符串内的{}和转义引号会自动跳过kiro/parsers.py#L39-L89不完整就等待找不到配对右括号时返回 -1事件留在 buffer 里等下一个包内容去重Kiro 偶尔会重复推送同一段 content解析器记住上一条内容相同的直接丢弃这套先攒够再解析的思路正是处理任何 SSE 流式数据的通用范式。从 KiroEvent 到标准 SSE 格式解析层把零散事件统一成与 API 无关的KiroEvent对象类型包括 content、thinking、tool_use、usage、context_usage 等再由两条输出流水线翻译成客户端认识的格式。OpenAI 格式输出每个 content 事件会被包装成一个chat.completion.chunk按data: {...}\n\n逐块推送流结束后追加两个收尾包见 kiro/streaming_openai.py#L391-L417携带finish_reason与usagetoken 统计的最终 chunkdata: [DONE]结束标记finish_reason的判定优先级很有意思截断 工具调用 正常结束——只要检测到流被截断就标记length有工具调用标记tool_calls否则才是stop。Anthropic 格式输出Anthropic 的流式协议是事件块模型一条完整响应要按固定顺序发送六个事件message_start → content_block_start → content_block_delta → content_block_stop → message_delta → message_stopstream_kiro_to_anthropic()内部维护着当前块索引等状态机正文块、thinking 块、工具块谁先出现就先发谁的 start 事件切换时自动补发上一个块的 stop 事件kiro/streaming_anthropic.py#L223-L343。两种格式的对比一览对比项OpenAIAnthropic事件标识无事件名只有data:event: 类型data:结束信号data: [DONE]message_stop事件工具调用结束时一次性下发独立的 tool_use 内容块结束原因字段finish_reasonstop_reason三个实战机制超时重试、截断检测与 Token 估算⏱ 首 token 超时与自动重试模型慢不等于死。Kiro Gateway 默认只给15 秒等待第一个 tokenFIRST_TOKEN_TIMEOUT超时就判定本次请求失败、关闭连接并自动重发最多 3 次FIRST_TOKEN_MAX_RETRIES对用户完全无感——详见 streaming_core.py#L369-L404。这两个参数在 kiro/config.py#L354-L366 中定义可在.env中调整。官方还特别提醒首 token 超时应小于流式读取超时否则会出现等待逻辑冲突。 内容截断检测与恢复Kiro API 在大参数工具调用时可能说到一半断流。网关有两道检测工具参数截断_diagnose_json_truncation()分析 JSON 是否缺少右括号、引号是否成对kiro/parsers.py#L464-L548正文截断流结束时如果既没收到 usage 也没收到 context_usage 事件就判定正文被截断检测到截断后默认开启的TRUNCATION_RECOVERYtrue会把记录存入 truncation_state.py在下一次客户端请求时自动提示模型上次输出被截断让模型自行补全——这是相当巧妙的容错设计。 Token 从哪来Kiro API 不直接返回 token 数只给一个上下文占用百分比。网关的做法是total_tokens 上下文百分比 × 模型上限 来自 Kiro API completion tiktoken 对输出文本计数 本地计算 prompt_tokens total_tokens - completion 相减得出计算逻辑在 streaming_core.py#L337-L362配合 kiro/tokenizer.py 的本地计数准确度可达 97% 以上。如何亲眼观察 SSE 流想验证以上原理在.env中设置DEBUG_MODEall网关会把每次请求的四个关键文件写入debug_logs/目录机制见 kiro/debug_logger.py文件内容request_body.json客户端发来的原始请求kiro_request_body.json转发给 Kiro API 的请求response_stream_raw.txt Kiro 返回的原始 SSE 流response_stream_modified.txt 网关转换后的输出流对比 raw 与 modified 两个文件你能直观看到AWS 事件流 → 标准 SSE的完整翻译过程是学习流式协议的最佳实验素材。总结Kiro Gateway 的流式传输设计可以浓缩为三层解析层用缓冲 花括号计数 去重从碎片字节流中还原完整事件统一层KiroEvent抹平上游差异实现一份解析多份输出格式化层按 OpenAI / Anthropic 各自的事件协议重新封装并叠加超时重试、截断恢复、Token 估算等增强能力如果你正在自建大模型代理网关这套统一事件模型 薄适配器的架构思路非常值得借鉴。完整架构说明见 docs/en/ARCHITECTURE.md相关解析器测试用例可参考 tests/unit/test_parsers.py。【免费下载链接】kiro-gateway Proxy API gateway for Kiro IDE CLI (Amazon Q Developer / AWS CodeWhisperer). Use free Claude models with any client.项目地址: https://gitcode.com/gh_mirrors/ki/kiro-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Kiro Gateway流式传输原理AWS SSE事件流解析完全指南【免费下载链接】kiro-gateway Proxy API gateway for Kiro IDE CLI (Amazon Q Developer / AWS CodeWhisperer). Use free Claude models with any client.项目地址: https://gitcode.com/gh_mirrors/ki/kiro-gatewayKiro Gateway是一个面向 Kiro IDE 与 CLI 的代理网关通过 AWS 流式传输接口让任意客户端免费使用 Claude 模型。它的核心能力之一就是把 Kiro API 返回的AWS SSE 事件流实时解析并转换成 OpenAI 或 Anthropic 格式的流式响应。本文将带你从一张图看懂流式传输全链路拆解 6 种 AWS SSE 事件类型以及首 token 超时重试、内容截断检测等实用机制帮你彻底搞懂 Kiro Gateway 流式传输原理。为什么需要流式解析普通 API 调用是一次性返回完整结果而大模型生成内容往往要等几十秒。Kiro API 的generateAssistantResponse接口只支持流式返回模型每生成一小段内容就立刻推送一个事件。这就带来三个技术难题事件是碎片化的一个完整 JSON 可能被切到两个网络包里格式不通用客户端Cursor、Claude Code 等只认 OpenAI 或 Anthropic 的 SSE 格式上游可能断流Kiro API 偶尔会截断工具调用参数Kiro Gateway 的 streaming_core.py 就是为解决这些问题而设计的统一流解析层。一图看懂流式传输全链路客户端 ──POST /v1/chat/completions──► Kiro Gateway │ 构建 Kiro 请求并转发 ▼ Kiro API (AWS) │ ◄── AWS SSE 事件流字节流 │ ① AwsEventStreamParser 解析事件 ② 统一为 KiroEvent 对象 ③ 格式化为 OpenAI / Anthropic SSE │ 客户端 ◄──── data: {...} 逐块推送 ────────┘对应到源码这条链路由四个模块协作完成阶段模块职责① 原始解析kiro/parsers.py从二进制字节流中抽取 JSON 事件② 统一事件kiro/streaming_core.py输出与 API 无关的KiroEvent③ OpenAI 格式化kiro/streaming_openai.py生成data: {...}data: [DONE]③ Anthropic 格式化kiro/streaming_anthropic.py生成event: xxxdata: {...}架构细节可参考官方文档 docs/en/ARCHITECTURE.md。AWS SSE 的 6 种核心事件类型AwsEventStreamParser内部定义了一张事件指纹表通过识别字节流中 JSON 的开头特征来分流事件见 kiro/parsers.py#L241-L249事件特征事件类型含义{content: content模型正文内容片段{name: tool_start工具调用开始含名称、ID{input: tool_input工具入参的后续分片{stop: tool_stop工具调用结束{usage: usage额度credits消耗{contextUsagePercentage: context_usage上下文占用百分比小细节{content:特征同时命中 content 和 followupPrompt 两种事件解析器会主动跳过追问建议followupPrompt避免把你可能还想问……之类的推荐词混进正文。碎片 JSON 如何拼完整网络包的大小是不固定的一个{content: 你好}完全可能一半在 A 包、一半在 B 包。解析器的解法很经典缓冲区累积每次收到字节块先追加到内部 buffer花括号计数find_matching_brace()从{开始计数遇到字符串内的{}和转义引号会自动跳过kiro/parsers.py#L39-L89不完整就等待找不到配对右括号时返回 -1事件留在 buffer 里等下一个包内容去重Kiro 偶尔会重复推送同一段 content解析器记住上一条内容相同的直接丢弃这套先攒够再解析的思路正是处理任何 SSE 流式数据的通用范式。从 KiroEvent 到标准 SSE 格式解析层把零散事件统一成与 API 无关的KiroEvent对象类型包括 content、thinking、tool_use、usage、context_usage 等再由两条输出流水线翻译成客户端认识的格式。OpenAI 格式输出每个 content 事件会被包装成一个chat.completion.chunk按data: {...}\n\n逐块推送流结束后追加两个收尾包见 kiro/streaming_openai.py#L391-L417携带finish_reason与usagetoken 统计的最终 chunkdata: [DONE]结束标记finish_reason的判定优先级很有意思截断 工具调用 正常结束——只要检测到流被截断就标记length有工具调用标记tool_calls否则才是stop。Anthropic 格式输出Anthropic 的流式协议是事件块模型一条完整响应要按固定顺序发送六个事件message_start → content_block_start → content_block_delta → content_block_stop → message_delta → message_stopstream_kiro_to_anthropic()内部维护着当前块索引等状态机正文块、thinking 块、工具块谁先出现就先发谁的 start 事件切换时自动补发上一个块的 stop 事件kiro/streaming_anthropic.py#L223-L343。两种格式的对比一览对比项OpenAIAnthropic事件标识无事件名只有data:event: 类型data:结束信号data: [DONE]message_stop事件工具调用结束时一次性下发独立的 tool_use 内容块结束原因字段finish_reasonstop_reason三个实战机制超时重试、截断检测与 Token 估算⏱ 首 token 超时与自动重试模型慢不等于死。Kiro Gateway 默认只给15 秒等待第一个 tokenFIRST_TOKEN_TIMEOUT超时就判定本次请求失败、关闭连接并自动重发最多 3 次FIRST_TOKEN_MAX_RETRIES对用户完全无感——详见 streaming_core.py#L369-L404。这两个参数在 kiro/config.py#L354-L366 中定义可在.env中调整。官方还特别提醒首 token 超时应小于流式读取超时否则会出现等待逻辑冲突。 内容截断检测与恢复Kiro API 在大参数工具调用时可能说到一半断流。网关有两道检测工具参数截断_diagnose_json_truncation()分析 JSON 是否缺少右括号、引号是否成对kiro/parsers.py#L464-L548正文截断流结束时如果既没收到 usage 也没收到 context_usage 事件就判定正文被截断检测到截断后默认开启的TRUNCATION_RECOVERYtrue会把记录存入 truncation_state.py在下一次客户端请求时自动提示模型上次输出被截断让模型自行补全——这是相当巧妙的容错设计。 Token 从哪来Kiro API 不直接返回 token 数只给一个上下文占用百分比。网关的做法是total_tokens 上下文百分比 × 模型上限 来自 Kiro API completion tiktoken 对输出文本计数 本地计算 prompt_tokens total_tokens - completion 相减得出计算逻辑在 streaming_core.py#L337-L362配合 kiro/tokenizer.py 的本地计数准确度可达 97% 以上。如何亲眼观察 SSE 流想验证以上原理在.env中设置DEBUG_MODEall网关会把每次请求的四个关键文件写入debug_logs/目录机制见 kiro/debug_logger.py文件内容request_body.json客户端发来的原始请求kiro_request_body.json转发给 Kiro API 的请求response_stream_raw.txt Kiro 返回的原始 SSE 流response_stream_modified.txt 网关转换后的输出流对比 raw 与 modified 两个文件你能直观看到AWS 事件流 → 标准 SSE的完整翻译过程是学习流式协议的最佳实验素材。总结Kiro Gateway 的流式传输设计可以浓缩为三层解析层用缓冲 花括号计数 去重从碎片字节流中还原完整事件统一层KiroEvent抹平上游差异实现一份解析多份输出格式化层按 OpenAI / Anthropic 各自的事件协议重新封装并叠加超时重试、截断恢复、Token 估算等增强能力如果你正在自建大模型代理网关这套统一事件模型 薄适配器的架构思路非常值得借鉴。完整架构说明见 docs/en/ARCHITECTURE.md相关解析器测试用例可参考 tests/unit/test_parsers.py。【免费下载链接】kiro-gateway Proxy API gateway for Kiro IDE CLI (Amazon Q Developer / AWS CodeWhisperer). Use free Claude models with any client.项目地址: https://gitcode.com/gh_mirrors/ki/kiro-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
