用qoder处理小说项目踩坑：流式响应空返回问题的排查与解决

上周想用 AI 编码助手批量处理本地小说项目的章节格式化：把散落在不同文件里的未排版章节，统一调成符合出版规范的样式。我选了本地部署的 qoder CLI，版本 1.0.45，本以为跑一条命令就完事，结果第一次执行就遇到「请求成功但完全拿不到返回内容」的诡异问题。整个排查踩了几个不大不小的坑，最后总结的经验对处理 AI 工具的长内容输出场景挺有用。

200 状态码背后的空响应

我执行的命令核心参数：工作目录指向本地小说项目，模型选 Auto，输出格式设为 stream-json（流式 JSON），输入格式同样流式 JSON，目的是边生成边拿格式化后的章节。

从 qoder 日志看，请求完全正常：返回状态码 status=200，请求 ID、会话 ID 都正常生成，传输类型为 legacy，阶段显示 headers_received，服务端像是有正常响应。但统计项很怪：output_tokens=0，content_block_count=1 却没有任何实际内容输出。Prompt 里明确要求返回格式化后的章节，结果连一个字符都没拿到。

我一开始以为是模型或 Prompt 的问题：先后把模型从 Auto 换成专门的小说微调模型，把 Prompt 简化到极致，甚至改成「只返回 1」，问题依然存在，于是排除了业务逻辑层面。

从业务逻辑查到工具链

既然业务没问题，只能往工具链本身找原因。我重新翻了一遍日志细节，注意到两个之前忽略的点：传输类型是 legacy（旧版传输模式），输出格式是 stream-json（流式 JSON）。

抱着试试看的心态去查 qoder 的官方文档和社区 issue，果然找到匹配的问题反馈：旧版 legacy 传输模式下，流式 JSON 的解析器存在边界处理 bug，当响应内容长度超过一定阈值时，流式分片会导致 JSON 结构不完整，解析器直接丢弃整个响应内容，且不返回明确错误状态，只显示 output_tokens 为 0——刚好对上我遇到的「200 状态但无内容」。

这里有个典型教训：我一开始先折腾换模型、改 Prompt 这类业务层调整，完全没往工具传输模式上想，白白浪费了近 10 分钟。后来抱着验证问题的目的，把输出格式从 stream-json 改成非流式的 json，命令立刻跑通，拿到了完整的格式化章节，根因就此坐实。之后翻 qoder 的版本更新日志，发现 1.0.46 刚好修复了 legacy 传输下流式 JSON 的边界解析 bug，升级版本后再次用流式模式，也能正常拿长内容了。

几点排查心得

这次虽然最终解决不到 20 分钟，但暴露的排查思路很典型。处理小说、长文档、大代码库这类输出较长的场景，非流式模式虽然等得稍久，但能避开绝大部分流式解析问题，老版本 CLI 的流式稳定性往往不如非流式。别被 200 状态码迷惑——工具层的 200 只代表请求发出、服务端响应了，不代表内容被正确解析；

遇到空响应优先看传输层的 phase、token 统计、transport 类型这些底层日志，再回头排查业务逻辑，能少绕路。很多工具的边缘场景 bug 不会有大范围公告，只体现在小版本更新日志里，平时保持小版本跟进，能避开不少没被广泛报道的隐性故障。

用 AI 编码工具时，我们很容易把注意力放在 Prompt、模型这些「显性」的业务配置上，忽略工具链本身的传输、解析这些「隐性」限制。下次再遇到「请求成功但无返回」，不妨先按上面的思路从工具层查起，能省下不少调试时间。

---

做自动化这几年，最耗时间的从来不是写代码，是摸清每个平台的脾气。

这篇里提到的坑，都是真金白银踩出来的。
如果你手上也有重复度很高的活儿——批量发布、数据搬运、有固定规则的机械操作
——可以在评论区说说你的场景，我看看能不能自动化掉。