{"name":"write_to_file","arguments":{"path":"_bmad-output/analysis/draft-long-research-300s-salvage.md","content":"# 长研究约300秒异常断流：零客户端修改的流内兜底方案\n\n首期改为使用标准 OpenAI 流式响应结构交付可安全保留的部分正文、网关中断提示和长度终态；废除原草案的客户端能力协商、自定义材料事件及客户端改造要求。该选择是网关的兼容性降级策略，不代表已经证明远端300秒限制的责任层，也不代表任何客户端都不会再报错或重试。\n\n- 文档状态：架构草案，2026-10-11重构；本轮授权仅覆盖本文件。\n- 首期范围：学术／事实核查预设的流式请求，在有有效正文且安全条件满足时就地交付部分结果，不新增上游生成。\n- 非目标一：不修改宿主 IDE、Roo Code、第三方客户端或其配置；不新增请求协商头、自定义材料事件。\n- 非目标二：不修改普通预设、非流式响应、账号退休规则、生成预算或研究总时限。\n- 非目标三：不把异常结束改记为上游正常完成，不执行截断工具，不自动重发原请求。\n- 非目标四：不在首期实现远端历史轮询、后台任务、持久正文存储或跨轮工具拼接。\n- 本文命令均为后续实施阶段的验证设计，未执行；新测试资产尚未创建。\n\n## 一、根因复盘与报错机制\n\n### 1. 已有证据与新增报告分层\n\n| 判断 | 当前依据 | 可下的结论 |\n|---|---|---|\n| 目标请求约301秒结束且有大量缓冲 | 已返回日志：请求df7d165f-9193-4f48-b307-9042dd30c624，耗时301.086秒，读取96,925字节，缓冲44,002字节，未观察到完成事件 | 有产出期间提前结束属实；最后正文距终止约144毫秒。 |\n| 本地研究总时限不是300秒 | 目标日志的生效策略为1800秒总时限；代码另行管理总截止与正文进展窗口 | 本次记录不支持本地300秒总截止触发。 |\n| 4～5个红框由客户端自动重试叠加 | 用户最新现场报告；已有多个相近301秒的失败请求记录，但未提供逐次客户端重试关联轨迹 | 将其作为本次设计输入；完整重试次数、每轮上下文一致性和具体客户端触发点尚未独立验证。 |\n| 474,096输入计数 | 用户提供的请求信息 | 记录为用户报告的输入计数，不冒称已独立校准的真实模型分词数。 |\n| Cloudflare／ALB固定300秒连接上限 | 用户最新归因；本轮未取得实际代理配置、远端日志或链路证据 | 工作假设，不作为已经证实的具体责任层。 |\n| StudioGlobal采用准入制尽力生成、额度耗尽不打断 | 用户最新机制说明；本轮未取得对应第一方契约或完整用量轨迹 | 可作为二期探索背景，不能据此保证任意请求都会生成到底。 |\n\n对具体代理、计费保证及客户端完整重试链的独立归因，当前证据不足（Insufficient evidence）。这些缺口不阻塞针对已观察到的“有正文但无完成事件”设计本地容错。\n\n### 2. 物理链条与源码定位\n\n1. 网关持续接受正文，目标请求在约301秒时底层读取返回结束，未得到正常完成事件。\n2. 流解析器结束读取，完成分类器发现缺少完成证据，将响应归入异常结束；这不等价于已经定位到TCP连接的主动关闭方。\n3. 普通直通流在 [`chat.go`](../../internal/api/chat.go:946) 报告错误；工具感知缓冲流对应的是 [`chat.go`](../../internal/api/chat.go:1066)。后者在工具仲裁前返回，所以缓冲正文尚未交付。\n4. [`writeRequestError()`](../../internal/api/chat.go:539) 调用输出控制器。响应头已经提交时，实际写出的是携带错误对象的SSE数据帧，不是重新返回HTTP 502，也不一定使用命名的错误事件。\n5. 按用户报告，Roo Code据此将该轮视为提供商失败并自动发起新请求，随后再次经历约300秒断流，界面逐次堆叠红框。\n\n必须区分两类重试：客户端重新发起HTTP请求，与网关单个逻辑请求内部的发送预算不是同一回事。当前异常缓冲分支直接返回，不能把多个红框解释成网关在这一个分支内部自动重发；现有预算属于单个逻辑请求。\n\n因此，首期处理的是错误交付引起的客户端失败路径，而不是修复远端连接寿命。删除错误帧可以消除这一特定触发输入，但客户端是否还存在长度终态、工具缺失或其他自动继续机制，必须用目标客户端验证。\n\n### 3. “标准结构”不等于“标准原因语义”\n\nOpenAI官方类型定义中，长度终态表示达到请求指定的最大生成Token数，并不是任意上游EOF的通用原因；流式响应结构允许该终态值。[14](cite:14)[2](cite:2)\n\n本方案按用户指定方向，选择将有有效正文的异常截断映射为 [`finish_reason: \"length\"`](../../internal/api/chat.go:205)。这是标准字段结构上的兼容映射，但其原因语义存在明确折中，不能写成“完全符合OpenAI对EOF的标准处理”。\n\n约束如下：\n\n- 对外明确提示正文不完整；不使用表示自然完成的终态冒充全文完成。\n- 对内保留缺少完成事件的真实原因，不将网关输出的长度终态反向当作上游长度耗尽证据。\n- 不保证零红框或零重试；这些是目标客户端的验收项，不是仅凭协议字段可以证明的结果。\n- 44,002字节是已缓冲响应的大小，不证明全部是纯研究正文，更不证明全文完成；缓冲可能含工具协议文本。\n\n## 二、方案决策矩阵\n\n先按零客户端修改、不执行未完成工具、不新增生成、资源有界四项硬约束筛选，不采用无依据的打分。\n\n| 方案 | 客户端修改 | 成果保留与风险 | 决策 |\n|---|---|---|---|\n| 报错重试：现状 | 不需要 | 诚实报告异常，但缓冲内容不交付；用户报告会进入重复请求和红框堆叠。 | 保留为不符合兜底资格时的错误路径，不再作为合格部分结果的首选 |\n| 自定义私有协议协商：原草案 | 需要客户端识别和保存新材料结构 | 可明确表达不完整状态，但违背零客户端修改硬约束 | 否决；删除协商头、自定义材料事件、专用面板及插件适配设计 |\n| 标准OpenAI结构、长度终态流内兜底 | 不要求修改客户端 | 可在原流交付安全正文；存在原因语义折中，客户端行为仍须验收 | 首期选定；仅对合格请求启用 |\n| 远端会话／历史结果重拉 | 不应要求客户端修改；网关需新增能力 | 可能获取更完整结果，但依赖真实接口、身份、结果关联及无重复生成证据 | 二期条件探索，不阻塞首期 |\n\n首期承诺范围是“尽力保留已经收到且可安全交付的正文”。不能承诺恢复尚未生成、尚未到达、已丢失或只能通过修补残缺工具参数才能取得的内容。\n\n二期不是再次发送同一个大上下文。只有证实原任务可读取、不会新建生成、可在原身份下关联结果后，才考虑有次数、字节、间隔和总时限上限的恢复；不将本地发出的长度终态作为自动续答许可。\n\n## 三、标准 OpenAI 流内优雅兜底控制流设计\n\n### 1. 适用范围与触发资格\n\n首期按解析后的有效预设启用学术／事实核查流式兜底，不新增客户端请求字段。普通预设与非流式路径保持原行为。\n\n资格必须同时满足：\n\n1. 请求为流式，且有效预设属于研究预设。\n2. 终止分类为 [`terminationUnexpectedEOF`](../../internal/api/chat.go:33)，而非显式上游错误、解析失败、资源超限、取消或超时。\n3. 客户端仍连接，执行上下文及父请求未取消、未超时，下游无写入或刷新失败。\n4. 存在可安全交付的非空白正文，并满足 [`effectiveOutput && tokensCount > 0`](../../internal/api/chat.go:825) 所表达的双重资格。\n5. 待交付正文不存在未闭合工具协议或无法判定的残缺结构；任何实际工具调用均不得进入兜底输出。\n6. 尚未发送终止错误、完成终态或工具调用；普通正文已经流出不禁止追加截断提示，但不得重发已交付正文。\n7. 工具选择约束允许纯文本回退；不能以取消工具要求的方式换取表面上的零报错。\n\n这里不能直接复制变量名就认为实现完成：\n\n- 当前 [`effectiveOutput`](../../internal/api/chat.go:825) 只存在于普通直通流的局部作用域，工具缓冲分支没有同名资格状态，需要在新辅助逻辑中独立计算。\n- 当前 [`tokensCount`](../../internal/api/chat.go:1020) 在答案增量事件上递增，且可能先计数再被容量守卫拒绝；它不是完整正文证明，也不是精确计费Token数。\n- [`observedOutput`](../../internal/api/chat.go:1009) 还会因推理／状态文字而为真，不能替代有效正文资格。\n- 必须先检查原始错误、容量和解析状态，再判断安全正文及计数；仅有计数、空白、心跳或状态均不得兜底。\n\n不设置“超过290秒才可兜底”的判断，也不新增300秒本地定时截断。20秒和301秒的合格异常使用同一规则；真正运行超过300秒且随后完成的请求仍走正常路径。\n\n### 2. 工具感知缓冲的安全裁决\n\n新增辅助逻辑只负责非执行检查和安全正文选择，不调用正常工具仲裁、提问桥接或协议纠偏，也不放宽 [`canArbitrate()`](../../internal/api/chat.go:63)。\n\n首期采用以下保守边界：\n\n- 缓冲为纯正文、无协议候选且编码合法：允许原样交付，不润色、不概括、不静默截短。\n- 缓冲包含完整工具调用但上游未正常完成：同样不得下发工具。完整语法不替代整轮完成证据。\n- 缓冲包含未闭合工具信封、残缺JSON参数或无法区分的结构：不得把原文直接放入普通正文，避免旧版文本工具解析器再次识别。\n- 仅当能够在已知语法和完整事件边界上证明存在独立纯正文前缀时，才允许丢弃整个可疑后缀并保留该前缀；必须提示有不安全片段未交付。\n- 首期不做截断参数提取、不补引号括号、不补工具结束标记、不从未完成的完成工具参数中抽取报告。\n- 无法证明安全前缀，或删除后已无有效正文时，保持原错误路径。不能以提示语本身充当有效成果。\n\n普通Markdown围栏或“仅供阅读”提示不是工具隔离证明；零客户端修改条件下，不能默认任意客户端都把其中的工具文本视为不可执行。\n\n强制调用场景也需要排除：现有 [`ValidateCalls()`](../../internal/toolcall/constraints_request.go:166) 对必须调用或指定工具的请求拒绝空调用列表。首期不得静默将其改为可选调用，也不得合成一个完成调用满足客户端。\n\n这意味着目标44KB缓冲若主要位于残缺工具信封内部，本方案不能同时保证全部文本恢复和绝不执行破损指令；安全屏障优先，文档不能许诺“完美保留全部”。\n\n### 3. SSE尾部与裸文本回退\n\n现有解析器会在EOF时处理残留事件，解码器对部分答案事件解析失败存在裸文本兼容回退；因此，缓冲非空不证明尾部是完整的应用层正文。\n\n首期应为安全资格增加必要的控制流事实：\n\n- 底层结束类型与事件是否完整分隔。\n- 最后一个确定安全的正文边界。\n- 数据是否通过结构化解码，或进入存在歧义的裸文本回退。\n\n已完整接受的安全正文可以用于兜底；未完成事件和有歧义的尾部不得补造后加入正文。无法划清边界则拒绝兜底。普通路径既有兼容规则不在本次顺手重写，诊断快照也不得反向授予业务资格。\n\n### 4. 下发序列\n\n资格通过后，在调用 [`writeRequestError()`](../../internal/api/chat.go:539) 之前分流：\n\n1. 固定原始异常原因，冻结安全正文；不将上游状态改为正常完成。\n2. 进入唯一输出所有者的兜底操作，暂停周期性进度和心跳，封闭同一个发送预算。\n3. 工具感知缓冲流：按有界分片输出安全正文增量；普通直通流：不重放已经发送的正文。\n4. 输出一次带明确网关标识的友情提示增量。\n5. 输出空增量的 [`finish_reason: \"length\"`](../../internal/api/chat.go:205) 终态块。\n6. 输出且只输出一次 [`data: [DONE]`](../../internal/api/chat.go:977)，终止原流并执行清理。\n\n所有块复用该响应的标识、模型、创建时间及选择索引；不输出工具增量，不使用自定义命名事件，不通过推理字段夹带研究正文。\n\n对已提交的研究流保持HTTP 200；若尚未提交，使用正常流式响应头提交200。合格兜底分支不得调用错误交付接口，不发送502，也不在长度终态后追加SSE错误。\n\n该要求只适用于通过资格并成功写出的分支。零产出、安全拒绝和其他非资格错误继续诚实报错；不能为了“杜绝502”掩盖全部故障。\n\n### 5. 网关提示与“继续”的真实含义\n\n建议提示采用实际观测时长，而不是声称已经证实远端硬上限。目标请求的示例文案为：\n\n> [网关提示] 上游响应在约301秒时提前结束，全文尚未完成。已保留可安全交付的部分正文。可回复“继续”请求续写；这会发起新请求，不保证恢复原任务，也可能产生重复内容或额外费用。\n\n- 在其他时长发生的EOF使用对应实际时长，不固定写300秒。\n- 尚无代理证据时，不写“已达到Cloudflare／ALB的300秒连接上限”。\n- 若安全裁决排除了后缀，追加说明“未完成的工具或结构化片段未交付”，不要把剩余正文描述为全部原文。\n- 网关不自行构造续写请求；用户下一次主动请求与本次兜底是两个独立生命周期。\n- 提示是网关生成的说明，不计为上游正文产出或上游用量。\n\n### 6. 写入、预算与结果状态\n\n建议辅助模块返回三类结果：不适用、已完成兜底、已尝试但交付失败。调用方不得把“已经写出部分兜底帧但失败”当成不适用，再追加原错误或重新生成。\n\n- 复用 [`chatOutput`](../../internal/api/chat_output.go:111) 的唯一写入所有者，不在读取协程和计时协程中并发写响应。\n- 整个兜底操作共享一个不可续期的写出截止，取剩余工作期限、父请求期限和现有下游写入额度的最早值；不得每分片重新获得完整额度。\n- 第一次业务写入之前调用原预算的 [`Commit()`](../../internal/toolcall/budget.go:110)，不新建预算，不退还发送次数。\n- 分片仅解决编码及瞬时内存占用，不扩大512KiB正文上限；JSON转义、提示和临时编码副本必须另计物理内存。\n- 短写、刷新失败、取消或截止立即停止；不补假终态、不切换后台上下文、不重放。\n- 记录原始上游终止原因、兜底是否尝试及是否写完、写出正文数量、排除片段数量和下游失败，均不记录原始正文或工具参数。\n- 保留 [`ResearchTerminationMissingCompletion`](../../internal/upstream/studioglobal/research_observation.go:147)；不调用正常完成登记。终态写成功与上游完整成功必须分别统计。\n\n现有输出控制器已经检查短写、刷新和上下文截止，新操作应复用这些保护；现有终态写成功字段只能证明输出操作，不能据此推断客户端已保存或研究已完成。\n\n## 四、安全不变量与账号租约机制\n\n### 1. 不执行中断响应中的工具\n\n- 兜底分支一律不输出原生工具调用，也不透传可能被文本解析器执行的工具信封。\n- 未闭合调用必须丢弃或导致资格拒绝；首期不采用未经目标客户端验证的“安全文本呈现”替代隔离。\n- 即使一批调用的第一个完整，也不能独立执行它、忽略后续截断调用；保留整批约束与正常完成屏障。\n- 不合成完成工具，不触发提问桥接，不自动协议纠偏，不跨生成轮拼接JSON。\n- 已经对外提交的内容不能撤回；直通路径若此前已泄露协议候选，新兜底不能声称修复了该历史风险。\n\n### 2. 零产出仍失败，长度终态不制造成果\n\n- [`tokensCount == 0`](../../internal/api/chat.go:1072) 或安全正文为空时，不走异常兜底。\n- 仅有状态、心跳、空白、计数但无合法正文、被容量守卫拒绝的内容，均不能被网关提示替代为“有成果”。\n- 正常完成且只有最终快照是另一条既有路径，不应被异常兜底的零计数条件误伤。\n- 本方案不承诺所有请求零红框；合格部分结果尽力避免提供商错误路径，真实失败仍保留错误。\n\n### 3. 有产出断流保持排除分类\n\n合格兜底请求保留 [`terminationUnexpectedEOF`](../../internal/api/chat.go:33)，不把 [`streamCompleted`](../../internal/api/chat.go:729) 设置为正常完成；租约结果必须为 [`StreamOutcomeExcluded`](../../internal/api/chat.go:150)。\n\n现有排除分类既不累加也不清零账号空流计数，仍按原租约结算已观察用量。实现中没有需要本方案额外维护的通用“健康分”，不应凭空新增该概念。\n\n- 不因300秒时长、有产出EOF或兜底成功退休账号。\n- 不将该情况改成认证失败或配额耗尽。\n- 不清零已有用量，不将网关提示计入模型用量，也不宣称本地计数等于供应商最终账单。\n- 零产出继续报错；其账号分类仍按既有精确规则判定，而不是根据300秒时长判断健康与否。若要连既有“零产出异常单次退休”也撤销，需要单独修订相关策略，不能夹带在本次部分正文兜底中。\n\n这一裁决不依赖StudioGlobal是否确实采用准入制计费。即使该机制仍待补证，也没有理由仅凭有产出EOF将账号判为风控或配额故障。\n\n### 4. 租约生命周期与远端取消\n\n保留原有所有权和清理顺序：\n\n1. 结束上游读取并幂等关闭响应体。\n2. 在原请求生命周期内完成有界兜底或确认下游失败。\n3. 停止取消回调；若回调已经启动，同步等待其退出。\n4. 通过原租约的 [`ReleaseStream()`](../../internal/session/manager.go:44) 释放一次，保持代际校验和一次性用量处理。\n5. 退出输出控制器及请求所属工作，之后才能释放请求准入槽位。\n\n撤回旧草案“材料交付结束后必定新增远端取消”的建议。首期不因EOF或长度兜底额外调用远端取消接口，保留现有客户端取消、截止和下游失败的清理行为，避免无依据地改变远端任务生命周期。\n\n关闭HTTP响应体或收到取消接口响应，都不能证明远端已经停止生成和计费；远端后台状态继续保持未知，二期恢复必须独立验证。\n\n## 五、实施改动点与测试门禁\n\n### 1. 改动范围\n\n| 文件 | 拟改动 | 边界 |\n|---|---|---|\n| [`chat.go`](../../internal/api/chat.go:937) | 在普通研究直通流及工具感知缓冲流的异常守卫前接入资格裁决和兜底结果分流；保留原始终止及租约分类 | 不全局放宽完成守卫；非流式和普通预设不变 |\n| [`chat_research_partial.go`](../../internal/api/chat_research_partial.go) | 拟新增：纯函数资格判断、安全正文裁决、提示构造、兜底结果类型 | 不新增上游请求，不做工具修补，不调用提问桥接 |\n| [`chat_output.go`](../../internal/api/chat_output.go:278) | 增加由唯一所有者执行的标准帧兜底操作；共享写出期限、暂停周期进度、一次终态 | 不改成私有材料事件，不越过取消和预算屏障 |\n| [`sse.go`](../../internal/stream/sse.go:87)、[`decode.go`](../../internal/upstream/studioglobal/decode.go:92) | 按资格判断需要暴露最小事件边界和解码质量事实 | 不把EOF伪装为完成，不扩大裸文本接受范围 |\n| [`research_observation.go`](../../internal/upstream/studioglobal/research_observation.go:130)及[`research_observation_encode.go`](../../internal/upstream/studioglobal/research_observation_encode.go:76) | 增加独立兜底交付统计，或使用固定字段的独立诊断记录 | 保持旧终止枚举含义，不把部分交付计入完整成功 |\n| [`API.md`](../../API.md) | 说明零客户端修改、研究流适用范围、长度原因映射、用户主动续写及不适用情况 | 明示兼容折中，不承诺通用客户端零错误 |\n| [`chat_research_partial_test.go`](../../internal/api/chat_research_partial_test.go) | 拟新增：资格、线协议、安全、回归、时钟和竞态测试 | 缺失资产不得当作已通过 |\n\n原则上不改 [`chat_execution.go`](../../internal/api/chat_execution.go:62)、[`budget.go`](../../internal/toolcall/budget.go:70)、[`manager.go`](../../internal/session/manager.go:44) 的策略；不修改客户端、供应商配额、普通模型配置及现有活动计划。\n\n### 2. 单元测试断言\n\n以下测试均拟新增，工程阶段须先创建，再按真实名称核验执行命中。\n\n| 测试组 | 必须断言 |\n|---|---|\n| 资格 | 学术／事实核查流式＋非空安全正文＋正计数＋异常EOF允许；普通预设、非流式、空白、状态、零计数、显式错误、取消、截止及资源拒绝均不允许 |\n| 标准帧序列 | HTTP 200；缓冲正文先输出，网关提示一次，长度终态一次，结束标记一次；可解析为标准聊天块；无错误对象、私有事件和工具增量 |\n| 正文保真 | 对44,002字节合成正文按UTF-8多字节、换行、公式及JSON转义分片；重组后逐字节相同，不将此夹具称为生产原文；直通流不得重复已有正文 |\n| 工具屏障 | 完整工具但未完成、半信封、残缺参数、多调用后段截断、伪装围栏、混合协议均零调用提交；不补结构，不合成完成工具 |\n| 前缀裁决 | 只有可证明独立安全的前缀可保留；有歧义则拒绝；剔除说明准确，警告不能单独满足正文资格 |\n| SSE尾部 | 完整事件后EOF、传输意外EOF、残留半事件、裸文本回退分别覆盖；不将残缺结构当正文；最末正常完成事件不能被漏判 |\n| 工具选择 | 可选工具与纯文本允许场景可兜底；强制调用、指定工具不被静默放宽；完成工具参数内的44KB文本不通过正则“抢救” |\n| 正常回归 | 正常完成、完成快照、真正超过300秒后完成保持原输出；既有正常工具校验不变 |\n| 失败写入 | 正文、提示、长度终态、结束标记各阶段注入写失败、短写和刷新失败；无后续帧、无错误补发、无生成重试、无重复释放 |\n\n### 3. 并发、时间与资源断言\n\n- 使用可控时钟模拟超过300秒、延迟完成、空闲及总截止，不让单元测试真实等待300秒。\n- 让心跳／进度定时与兜底入口竞争，断言只有一个输出所有者、终态至多一次、终态之后没有任何帧。\n- 在首个兜底帧之前、正文中途及结束标记前取消，断言写入及时终止、取消回调同步退出、租约只释放一次。\n- 对已有空流计数的账号执行有产出兜底，断言计数保持原值：既不累加也不清零，不进入退休／提拔路径。\n- 断言生成发送次数与兜底前一致；兜底不能消耗一次纠偏或续答额度，也不能重建预算。\n- 双并发接近正文限额、JSON高转义膨胀、慢下游同时出现时，验证累计缓冲和整个兜底绝对截止；竞态检测通过不等于进程内存达标，内存测量单独记录。\n- 诊断只保留固定类别及数量；敏感正文、工具参数、凭据不得进入日志。\n\n### 4. 限时验证命令\n\n以下均为拟执行命令，工作目录为项目根目录；本轮没有运行。每条单独前台执行，前一条退出后才能运行下一条，外层30秒、测试内部20秒，关闭自动工具链及模块下载。\n\n拟新增资格、线协议及安全测试：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=1 -timeout=20s -run '^TestResearchSalvage(Eligibility|WireSequence|BodyIntegrity|ToolGuard|SSETail|Compatibility)$' ./internal/api < /dev/null\n```\n\n拟新增取消、单写者及租约竞态测试：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=10 -timeout=20s -run '^TestResearchSalvage(CancellationRace|SingleWriter|LeaseExactlyOnce|WriteFailure)$' ./internal/api < /dev/null\n```\n\n保留既有缓冲完成守卫回归：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=1 -timeout=20s -run '^TestT23_CompletionGuard$' ./internal/api < /dev/null\n```\n\n账号生命周期回归：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=1 -timeout=20s ./internal/session < /dev/null\n```\n\n门禁要求：\n\n- 必须核验每组预期测试及子测试实际运行；正则未命中而返回退出码0不算通过。\n- 既有 [`TestT23_CompletionGuard()`](../../internal/api/chat_buffered_completion_test.go:83) 明确约束异常默认路径；新增研究例外使用独立夹具，不删除原有普通路径断言。\n- 工具链、竞态依赖、编译缓存及离线依赖是否齐备尚未核验。缺依赖、编译超时或测试超时均为阻塞，不冒称测试通过。\n- 冷编译若需要准备，另行授权并安排有界构建，不偷偷延长上述单测时间，也不借验证下载未批准依赖。\n- 记录命令、工作目录、退出状态、实际命中的测试和关键输出；只声明已运行的覆盖范围，不将这些命令当成全仓验收。\n\n### 5. 零客户端修改的验收门\n\n验证允许使用未修改的客户端，不等于授权修改客户端。真实上游及生产验证仍须独立授权。\n\n首期上线至少验证：\n\n1. 目标Roo Code版本与实际提供商适配路径能够显示44KB级合成安全正文，并保留网关提示。\n2. 长度终态及结束标记后，不进入原提供商错误重试路径；记录是否存在其他自动继续或“必须调用工具”纠偏。\n3. 实际上游发送次数与预期一致，不能用网关单请求计数代替客户端是否发出新HTTP请求的证据。\n4. 原文、长度状态和提示进入客户端历史；不要求修改其保存逻辑，但必须观察实际结果。\n5. 工具开启场景零误执行；如果目标客户端无法满足，不通过合成工具或透传截断信封掩盖失败。\n\n若目标客户端仍把长度终态视为错误，或因缺少工具继续重试，则“零红框／停止重试”的目标未通过。不能把网关HTTP 200或结束标记写成功当成客户端验收替代品。\n\n### 6. 文档与生命周期边界\n\n本稿替代旧草案中的私有协议、客户端改造及EOF后新增强制远端取消建议；不自动替代已接受ADR，也不将历史完成守卫测试改记为新方案通过。\n\n拟关联的 [`ADR-20261011-studioglobal-long-research-graceful-salvage.md`](../adrs/ADR-20261011-studioglobal-long-research-graceful-salvage.md) 本轮读取返回文件不存在，不能因为编辑器有标签页就称其已建立或已接受。\n\n后续工程接管应明确登记对“异常响应不发送终止标记”的研究部分正文例外，同时保留上游异常事实、工具完成屏障、三次发送总预算和账号分类。当前仅重写指定草案，不新建ADR、不覆盖活动计划、不实施代码、不执行测试或部署。\n\n## 证据索引\n\n以下编号区分外部第一方定义、本会话已经返回的源码及用户现场报告；链接行号基于本轮可见源码，实施前须重新核对。\n\n- [2](cite:2) [OpenAI官方聊天流式事件定义](https://developers.openai.com/api/reference/resources/chat/subresources/completions/streaming-events.md)：标准聊天块与终态字段结构。\n- [14](cite:14) [OpenAI官方SDK的固定版本完成类型定义](https://github.com/openai/openai-python/blob/e41abf7b7dbc1e744d167f748e55d4dedfc0dca7/src/openai/types/chat/chat_completion.py)：长度终态表示达到请求指定的最大生成Token数，不能直接当作EOF的标准原因定义。\n- 本会话已返回的四条约301秒生产结束记录及用户最新现场报告。目标请求df7d165f-9193-4f48-b307-9042dd30c624的时长、读取、缓冲、结束类别有日志摘录；474,096输入计数、红框自动重试归因、代理身份和准入制计费结论属于用户报告，证据层级不同。\n- [`chat.go`](../../internal/api/chat.go:67)：终止分类；[`请求错误与发送生命周期`](../../internal/api/chat.go:539)；[`租约及取消清理`](../../internal/api/chat.go:703)；[`普通流`](../../internal/api/chat.go:823)；[`工具缓冲与异常守卫`](../../internal/api/chat.go:983)；[`非流式`](../../internal/api/chat.go:1244)；[`512KiB缓冲上限`](../../internal/api/chat.go:153)。\n- [`chat_execution.go`](../../internal/api/chat_execution.go:62)：固定总截止；[`正文进展刷新`](../../internal/api/chat_execution.go:246)；[`共享收尾截止`](../../internal/api/chat_execution.go:113)。\n- [`chat_output.go`](../../internal/api/chat_output.go:309)：进度与业务时钟隔离；[`错误帧`](../../internal/api/chat_output.go:340)；[`有界写入、短写和刷新`](../../internal/api/chat_output.go:356)。\n- [`sse.go`](../../internal/stream/sse.go:96)：EOF残留事件处理；[`decode.go`](../../internal/upstream/studioglobal/decode.go:92)：答案、完成、状态与裸文本兼容回退。\n- [`output_format.go`](../../internal/toolcall/output_format.go:43)：协商工具格式及协议候选处理；[`constraints_request.go`](../../internal/toolcall/constraints_request.go:164)：整批调用与强制选择校验。\n- [`chat.go`](../../internal/api/chat.go:117)：账号释放分类；[`manager.go`](../../internal/session/manager.go:42)：一次性释放、账号代际检查及空流计数。\n- [`budget.go`](../../internal/toolcall/budget.go:19)：最多三次发送；[`续答证据`](../../internal/toolcall/budget.go:45)；[`提交后禁止重放`](../../internal/toolcall/budget.go:70)。\n- [`chat_buffered_completion_test.go`](../../internal/api/chat_buffered_completion_test.go:83)：普通缓冲及非流式的原有完成守卫测试；读取到测试源码不等于本轮已运行。\n- [`client.go`](../../internal/upstream/studioglobal/client.go:264)：远端取消钩子、共享收尾与停止生成／计费未知的诊断边界。\n- 本会话已返回的 [`零产出异常分类ADR`](../adrs/ADR-20261007-3b-empty-upstream-eof-recovery.md:96)、[`研究恢复与续答契约`](../adrs/ADR-20261008-studioglobal-model-registry-research-presets.md:372) 相关检索片段，以及拟关联新ADR的文件不存在返回结果；不据此声称新方案已取得实施或部署验收。\n"}}

{"name":"write_to_file","arguments":{"path":"_bmad-output/analysis/draft-long-research-300s-salvage.md","content":"# 长研究约300秒异常断流：零客户端修改的流内兜底方案\n\n首期改为使用标准 OpenAI 流式响应结构交付可安全保留的部分正文、网关中断提示和长度终态；废除原草案的客户端能力协商、自定义材料事件及客户端改造要求。该选择是网关的兼容性降级策略，不代表已经证明远端300秒限制的责任层，也不代表任何客户端都不会再报错或重试。\n\n- 文档状态：架构草案，2026-10-11重构；本轮授权仅覆盖本文件。\n- 首期范围：学术／事实核查预设的流式请求，在有有效正文且安全条件满足时就地交付部分结果，不新增上游生成。\n- 非目标一：不修改宿主 IDE、Roo Code、第三方客户端或其配置；不新增请求协商头、自定义材料事件。\n- 非目标二：不修改普通预设、非流式响应、账号退休规则、生成预算或研究总时限。\n- 非目标三：不把异常结束改记为上游正常完成，不执行截断工具，不自动重发原请求。\n- 非目标四：不在首期实现远端历史轮询、后台任务、持久正文存储或跨轮工具拼接。\n- 本文命令均为后续实施阶段的验证设计，未执行；新测试资产尚未创建。\n\n## 一、根因复盘与报错机制\n\n### 1. 已有证据与新增报告分层\n\n| 判断 | 当前依据 | 可下的结论 |\n|---|---|---|\n| 目标请求约301秒结束且有大量缓冲 | 已返回日志：请求df7d165f-9193-4f48-b307-9042dd30c624，耗时301.086秒，读取96,925字节，缓冲44,002字节，未观察到完成事件 | 有产出期间提前结束属实；最后正文距终止约144毫秒。 |\n| 本地研究总时限不是300秒 | 目标日志的生效策略为1800秒总时限；代码另行管理总截止与正文进展窗口 | 本次记录不支持本地300秒总截止触发。 |\n| 4～5个红框由客户端自动重试叠加 | 用户最新现场报告；已有多个相近301秒的失败请求记录，但未提供逐次客户端重试关联轨迹 | 将其作为本次设计输入；完整重试次数、每轮上下文一致性和具体客户端触发点尚未独立验证。 |\n| 474,096输入计数 | 用户提供的请求信息 | 记录为用户报告的输入计数，不冒称已独立校准的真实模型分词数。 |\n| Cloudflare／ALB固定300秒连接上限 | 用户最新归因；本轮未取得实际代理配置、远端日志或链路证据 | 工作假设，不作为已经证实的具体责任层。 |\n| StudioGlobal采用准入制尽力生成、额度耗尽不打断 | 用户最新机制说明；本轮未取得对应第一方契约或完整用量轨迹 | 可作为二期探索背景，不能据此保证任意请求都会生成到底。 |\n\n对具体代理、计费保证及客户端完整重试链的独立归因，当前证据不足（Insufficient evidence）。这些缺口不阻塞针对已观察到的“有正文但无完成事件”设计本地容错。\n\n### 2. 物理链条与源码定位\n\n1. 网关持续接受正文，目标请求在约301秒时底层读取返回结束，未得到正常完成事件。\n2. 流解析器结束读取，完成分类器发现缺少完成证据，将响应归入异常结束；这不等价于已经定位到TCP连接的主动关闭方。\n3. 普通直通流在 [`chat.go`](../../internal/api/chat.go:946) 报告错误；工具感知缓冲流对应的是 [`chat.go`](../../internal/api/chat.go:1066)。后者在工具仲裁前返回，所以缓冲正文尚未交付。\n4. [`writeRequestError()`](../../internal/api/chat.go:539) 调用输出控制器。响应头已经提交时，实际写出的是携带错误对象的SSE数据帧，不是重新返回HTTP 502，也不一定使用命名的错误事件。\n5. 按用户报告，Roo Code据此将该轮视为提供商失败并自动发起新请求，随后再次经历约300秒断流，界面逐次堆叠红框。\n\n必须区分两类重试：客户端重新发起HTTP请求，与网关单个逻辑请求内部的发送预算不是同一回事。当前异常缓冲分支直接返回，不能把多个红框解释成网关在这一个分支内部自动重发；现有预算属于单个逻辑请求。\n\n因此，首期处理的是错误交付引起的客户端失败路径，而不是修复远端连接寿命。删除错误帧可以消除这一特定触发输入，但客户端是否还存在长度终态、工具缺失或其他自动继续机制，必须用目标客户端验证。\n\n### 3. “标准结构”不等于“标准原因语义”\n\nOpenAI官方类型定义中，长度终态表示达到请求指定的最大生成Token数，并不是任意上游EOF的通用原因；流式响应结构允许该终态值。[14](cite:14)[2](cite:2)\n\n本方案按用户指定方向，选择将有有效正文的异常截断映射为 [`finish_reason: \"length\"`](../../internal/api/chat.go:205)。这是标准字段结构上的兼容映射，但其原因语义存在明确折中，不能写成“完全符合OpenAI对EOF的标准处理”。\n\n约束如下：\n\n- 对外明确提示正文不完整；不使用表示自然完成的终态冒充全文完成。\n- 对内保留缺少完成事件的真实原因，不将网关输出的长度终态反向当作上游长度耗尽证据。\n- 不保证零红框或零重试；这些是目标客户端的验收项，不是仅凭协议字段可以证明的结果。\n- 44,002字节是已缓冲响应的大小，不证明全部是纯研究正文，更不证明全文完成；缓冲可能含工具协议文本。\n\n## 二、方案决策矩阵\n\n先按零客户端修改、不执行未完成工具、不新增生成、资源有界四项硬约束筛选，不采用无依据的打分。\n\n| 方案 | 客户端修改 | 成果保留与风险 | 决策 |\n|---|---|---|---|\n| 报错重试：现状 | 不需要 | 诚实报告异常，但缓冲内容不交付；用户报告会进入重复请求和红框堆叠。 | 保留为不符合兜底资格时的错误路径，不再作为合格部分结果的首选 |\n| 自定义私有协议协商：原草案 | 需要客户端识别和保存新材料结构 | 可明确表达不完整状态，但违背零客户端修改硬约束 | 否决；删除协商头、自定义材料事件、专用面板及插件适配设计 |\n| 标准OpenAI结构、长度终态流内兜底 | 不要求修改客户端 | 可在原流交付安全正文；存在原因语义折中，客户端行为仍须验收 | 首期选定；仅对合格请求启用 |\n| 远端会话／历史结果重拉 | 不应要求客户端修改；网关需新增能力 | 可能获取更完整结果，但依赖真实接口、身份、结果关联及无重复生成证据 | 二期条件探索，不阻塞首期 |\n\n首期承诺范围是“尽力保留已经收到且可安全交付的正文”。不能承诺恢复尚未生成、尚未到达、已丢失或只能通过修补残缺工具参数才能取得的内容。\n\n二期不是再次发送同一个大上下文。只有证实原任务可读取、不会新建生成、可在原身份下关联结果后，才考虑有次数、字节、间隔和总时限上限的恢复；不将本地发出的长度终态作为自动续答许可。\n\n## 三、标准 OpenAI 流内优雅兜底控制流设计\n\n### 1. 适用范围与触发资格\n\n首期按解析后的有效预设启用学术／事实核查流式兜底，不新增客户端请求字段。普通预设与非流式路径保持原行为。\n\n资格必须同时满足：\n\n1. 请求为流式，且有效预设属于研究预设。\n2. 终止分类为 [`terminationUnexpectedEOF`](../../internal/api/chat.go:33)，而非显式上游错误、解析失败、资源超限、取消或超时。\n3. 客户端仍连接，执行上下文及父请求未取消、未超时，下游无写入或刷新失败。\n4. 存在可安全交付的非空白正文，并满足 [`effectiveOutput && tokensCount > 0`](../../internal/api/chat.go:825) 所表达的双重资格。\n5. 待交付正文不存在未闭合工具协议或无法判定的残缺结构；任何实际工具调用均不得进入兜底输出。\n6. 尚未发送终止错误、完成终态或工具调用；普通正文已经流出不禁止追加截断提示，但不得重发已交付正文。\n7. 工具选择约束允许纯文本回退；不能以取消工具要求的方式换取表面上的零报错。\n\n这里不能直接复制变量名就认为实现完成：\n\n- 当前 [`effectiveOutput`](../../internal/api/chat.go:825) 只存在于普通直通流的局部作用域，工具缓冲分支没有同名资格状态，需要在新辅助逻辑中独立计算。\n- 当前 [`tokensCount`](../../internal/api/chat.go:1020) 在答案增量事件上递增，且可能先计数再被容量守卫拒绝；它不是完整正文证明，也不是精确计费Token数。\n- [`observedOutput`](../../internal/api/chat.go:1009) 还会因推理／状态文字而为真，不能替代有效正文资格。\n- 必须先检查原始错误、容量和解析状态，再判断安全正文及计数；仅有计数、空白、心跳或状态均不得兜底。\n\n不设置“超过290秒才可兜底”的判断，也不新增300秒本地定时截断。20秒和301秒的合格异常使用同一规则；真正运行超过300秒且随后完成的请求仍走正常路径。\n\n### 2. 工具感知缓冲的安全裁决\n\n新增辅助逻辑只负责非执行检查和安全正文选择，不调用正常工具仲裁、提问桥接或协议纠偏，也不放宽 [`canArbitrate()`](../../internal/api/chat.go:63)。\n\n首期采用以下保守边界：\n\n- 缓冲为纯正文、无协议候选且编码合法：允许原样交付，不润色、不概括、不静默截短。\n- 缓冲包含完整工具调用但上游未正常完成：同样不得下发工具。完整语法不替代整轮完成证据。\n- 缓冲包含未闭合工具信封、残缺JSON参数或无法区分的结构：不得把原文直接放入普通正文，避免旧版文本工具解析器再次识别。\n- 仅当能够在已知语法和完整事件边界上证明存在独立纯正文前缀时，才允许丢弃整个可疑后缀并保留该前缀；必须提示有不安全片段未交付。\n- 首期不做截断参数提取、不补引号括号、不补工具结束标记、不从未完成的完成工具参数中抽取报告。\n- 无法证明安全前缀，或删除后已无有效正文时，保持原错误路径。不能以提示语本身充当有效成果。\n\n普通Markdown围栏或“仅供阅读”提示不是工具隔离证明；零客户端修改条件下，不能默认任意客户端都把其中的工具文本视为不可执行。\n\n强制调用场景也需要排除：现有 [`ValidateCalls()`](../../internal/toolcall/constraints_request.go:166) 对必须调用或指定工具的请求拒绝空调用列表。首期不得静默将其改为可选调用，也不得合成一个完成调用满足客户端。\n\n这意味着目标44KB缓冲若主要位于残缺工具信封内部，本方案不能同时保证全部文本恢复和绝不执行破损指令；安全屏障优先，文档不能许诺“完美保留全部”。\n\n### 3. SSE尾部与裸文本回退\n\n现有解析器会在EOF时处理残留事件，解码器对部分答案事件解析失败存在裸文本兼容回退；因此，缓冲非空不证明尾部是完整的应用层正文。\n\n首期应为安全资格增加必要的控制流事实：\n\n- 底层结束类型与事件是否完整分隔。\n- 最后一个确定安全的正文边界。\n- 数据是否通过结构化解码，或进入存在歧义的裸文本回退。\n\n已完整接受的安全正文可以用于兜底；未完成事件和有歧义的尾部不得补造后加入正文。无法划清边界则拒绝兜底。普通路径既有兼容规则不在本次顺手重写，诊断快照也不得反向授予业务资格。\n\n### 4. 下发序列\n\n资格通过后，在调用 [`writeRequestError()`](../../internal/api/chat.go:539) 之前分流：\n\n1. 固定原始异常原因，冻结安全正文；不将上游状态改为正常完成。\n2. 进入唯一输出所有者的兜底操作，暂停周期性进度和心跳，封闭同一个发送预算。\n3. 工具感知缓冲流：按有界分片输出安全正文增量；普通直通流：不重放已经发送的正文。\n4. 输出一次带明确网关标识的友情提示增量。\n5. 输出空增量的 [`finish_reason: \"length\"`](../../internal/api/chat.go:205) 终态块。\n6. 输出且只输出一次 [`data: [DONE]`](../../internal/api/chat.go:977)，终止原流并执行清理。\n\n所有块复用该响应的标识、模型、创建时间及选择索引；不输出工具增量，不使用自定义命名事件，不通过推理字段夹带研究正文。\n\n对已提交的研究流保持HTTP 200；若尚未提交，使用正常流式响应头提交200。合格兜底分支不得调用错误交付接口，不发送502，也不在长度终态后追加SSE错误。\n\n该要求只适用于通过资格并成功写出的分支。零产出、安全拒绝和其他非资格错误继续诚实报错；不能为了“杜绝502”掩盖全部故障。\n\n### 5. 网关提示与“继续”的真实含义\n\n建议提示采用实际观测时长，而不是声称已经证实远端硬上限。目标请求的示例文案为：\n\n> [网关提示] 上游响应在约301秒时提前结束，全文尚未完成。已保留可安全交付的部分正文。可回复“继续”请求续写；这会发起新请求，不保证恢复原任务，也可能产生重复内容或额外费用。\n\n- 在其他时长发生的EOF使用对应实际时长，不固定写300秒。\n- 尚无代理证据时，不写“已达到Cloudflare／ALB的300秒连接上限”。\n- 若安全裁决排除了后缀，追加说明“未完成的工具或结构化片段未交付”，不要把剩余正文描述为全部原文。\n- 网关不自行构造续写请求；用户下一次主动请求与本次兜底是两个独立生命周期。\n- 提示是网关生成的说明，不计为上游正文产出或上游用量。\n\n### 6. 写入、预算与结果状态\n\n建议辅助模块返回三类结果：不适用、已完成兜底、已尝试但交付失败。调用方不得把“已经写出部分兜底帧但失败”当成不适用，再追加原错误或重新生成。\n\n- 复用 [`chatOutput`](../../internal/api/chat_output.go:111) 的唯一写入所有者，不在读取协程和计时协程中并发写响应。\n- 整个兜底操作共享一个不可续期的写出截止，取剩余工作期限、父请求期限和现有下游写入额度的最早值；不得每分片重新获得完整额度。\n- 第一次业务写入之前调用原预算的 [`Commit()`](../../internal/toolcall/budget.go:110)，不新建预算，不退还发送次数。\n- 分片仅解决编码及瞬时内存占用，不扩大512KiB正文上限；JSON转义、提示和临时编码副本必须另计物理内存。\n- 短写、刷新失败、取消或截止立即停止；不补假终态、不切换后台上下文、不重放。\n- 记录原始上游终止原因、兜底是否尝试及是否写完、写出正文数量、排除片段数量和下游失败，均不记录原始正文或工具参数。\n- 保留 [`ResearchTerminationMissingCompletion`](../../internal/upstream/studioglobal/research_observation.go:147)；不调用正常完成登记。终态写成功与上游完整成功必须分别统计。\n\n现有输出控制器已经检查短写、刷新和上下文截止，新操作应复用这些保护；现有终态写成功字段只能证明输出操作，不能据此推断客户端已保存或研究已完成。\n\n## 四、安全不变量与账号租约机制\n\n### 1. 不执行中断响应中的工具\n\n- 兜底分支一律不输出原生工具调用，也不透传可能被文本解析器执行的工具信封。\n- 未闭合调用必须丢弃或导致资格拒绝；首期不采用未经目标客户端验证的“安全文本呈现”替代隔离。\n- 即使一批调用的第一个完整，也不能独立执行它、忽略后续截断调用；保留整批约束与正常完成屏障。\n- 不合成完成工具，不触发提问桥接，不自动协议纠偏，不跨生成轮拼接JSON。\n- 已经对外提交的内容不能撤回；直通路径若此前已泄露协议候选，新兜底不能声称修复了该历史风险。\n\n### 2. 零产出仍失败，长度终态不制造成果\n\n- [`tokensCount == 0`](../../internal/api/chat.go:1072) 或安全正文为空时，不走异常兜底。\n- 仅有状态、心跳、空白、计数但无合法正文、被容量守卫拒绝的内容，均不能被网关提示替代为“有成果”。\n- 正常完成且只有最终快照是另一条既有路径，不应被异常兜底的零计数条件误伤。\n- 本方案不承诺所有请求零红框；合格部分结果尽力避免提供商错误路径，真实失败仍保留错误。\n\n### 3. 有产出断流保持排除分类\n\n合格兜底请求保留 [`terminationUnexpectedEOF`](../../internal/api/chat.go:33)，不把 [`streamCompleted`](../../internal/api/chat.go:729) 设置为正常完成；租约结果必须为 [`StreamOutcomeExcluded`](../../internal/api/chat.go:150)。\n\n现有排除分类既不累加也不清零账号空流计数，仍按原租约结算已观察用量。实现中没有需要本方案额外维护的通用“健康分”，不应凭空新增该概念。\n\n- 不因300秒时长、有产出EOF或兜底成功退休账号。\n- 不将该情况改成认证失败或配额耗尽。\n- 不清零已有用量，不将网关提示计入模型用量，也不宣称本地计数等于供应商最终账单。\n- 零产出继续报错；其账号分类仍按既有精确规则判定，而不是根据300秒时长判断健康与否。若要连既有“零产出异常单次退休”也撤销，需要单独修订相关策略，不能夹带在本次部分正文兜底中。\n\n这一裁决不依赖StudioGlobal是否确实采用准入制计费。即使该机制仍待补证，也没有理由仅凭有产出EOF将账号判为风控或配额故障。\n\n### 4. 租约生命周期与远端取消\n\n保留原有所有权和清理顺序：\n\n1. 结束上游读取并幂等关闭响应体。\n2. 在原请求生命周期内完成有界兜底或确认下游失败。\n3. 停止取消回调；若回调已经启动，同步等待其退出。\n4. 通过原租约的 [`ReleaseStream()`](../../internal/session/manager.go:44) 释放一次，保持代际校验和一次性用量处理。\n5. 退出输出控制器及请求所属工作，之后才能释放请求准入槽位。\n\n撤回旧草案“材料交付结束后必定新增远端取消”的建议。首期不因EOF或长度兜底额外调用远端取消接口，保留现有客户端取消、截止和下游失败的清理行为，避免无依据地改变远端任务生命周期。\n\n关闭HTTP响应体或收到取消接口响应，都不能证明远端已经停止生成和计费；远端后台状态继续保持未知，二期恢复必须独立验证。\n\n## 五、实施改动点与测试门禁\n\n### 1. 改动范围\n\n| 文件 | 拟改动 | 边界 |\n|---|---|---|\n| [`chat.go`](../../internal/api/chat.go:937) | 在普通研究直通流及工具感知缓冲流的异常守卫前接入资格裁决和兜底结果分流；保留原始终止及租约分类 | 不全局放宽完成守卫；非流式和普通预设不变 |\n| [`chat_research_partial.go`](../../internal/api/chat_research_partial.go) | 拟新增：纯函数资格判断、安全正文裁决、提示构造、兜底结果类型 | 不新增上游请求，不做工具修补，不调用提问桥接 |\n| [`chat_output.go`](../../internal/api/chat_output.go:278) | 增加由唯一所有者执行的标准帧兜底操作；共享写出期限、暂停周期进度、一次终态 | 不改成私有材料事件，不越过取消和预算屏障 |\n| [`sse.go`](../../internal/stream/sse.go:87)、[`decode.go`](../../internal/upstream/studioglobal/decode.go:92) | 按资格判断需要暴露最小事件边界和解码质量事实 | 不把EOF伪装为完成，不扩大裸文本接受范围 |\n| [`research_observation.go`](../../internal/upstream/studioglobal/research_observation.go:130)及[`research_observation_encode.go`](../../internal/upstream/studioglobal/research_observation_encode.go:76) | 增加独立兜底交付统计，或使用固定字段的独立诊断记录 | 保持旧终止枚举含义，不把部分交付计入完整成功 |\n| [`API.md`](../../API.md) | 说明零客户端修改、研究流适用范围、长度原因映射、用户主动续写及不适用情况 | 明示兼容折中，不承诺通用客户端零错误 |\n| [`chat_research_partial_test.go`](../../internal/api/chat_research_partial_test.go) | 拟新增：资格、线协议、安全、回归、时钟和竞态测试 | 缺失资产不得当作已通过 |\n\n原则上不改 [`chat_execution.go`](../../internal/api/chat_execution.go:62)、[`budget.go`](../../internal/toolcall/budget.go:70)、[`manager.go`](../../internal/session/manager.go:44) 的策略；不修改客户端、供应商配额、普通模型配置及现有活动计划。\n\n### 2. 单元测试断言\n\n以下测试均拟新增，工程阶段须先创建，再按真实名称核验执行命中。\n\n| 测试组 | 必须断言 |\n|---|---|\n| 资格 | 学术／事实核查流式＋非空安全正文＋正计数＋异常EOF允许；普通预设、非流式、空白、状态、零计数、显式错误、取消、截止及资源拒绝均不允许 |\n| 标准帧序列 | HTTP 200；缓冲正文先输出，网关提示一次，长度终态一次，结束标记一次；可解析为标准聊天块；无错误对象、私有事件和工具增量 |\n| 正文保真 | 对44,002字节合成正文按UTF-8多字节、换行、公式及JSON转义分片；重组后逐字节相同，不将此夹具称为生产原文；直通流不得重复已有正文 |\n| 工具屏障 | 完整工具但未完成、半信封、残缺参数、多调用后段截断、伪装围栏、混合协议均零调用提交；不补结构，不合成完成工具 |\n| 前缀裁决 | 只有可证明独立安全的前缀可保留；有歧义则拒绝；剔除说明准确，警告不能单独满足正文资格 |\n| SSE尾部 | 完整事件后EOF、传输意外EOF、残留半事件、裸文本回退分别覆盖；不将残缺结构当正文；最末正常完成事件不能被漏判 |\n| 工具选择 | 可选工具与纯文本允许场景可兜底；强制调用、指定工具不被静默放宽；完成工具参数内的44KB文本不通过正则“抢救” |\n| 正常回归 | 正常完成、完成快照、真正超过300秒后完成保持原输出；既有正常工具校验不变 |\n| 失败写入 | 正文、提示、长度终态、结束标记各阶段注入写失败、短写和刷新失败；无后续帧、无错误补发、无生成重试、无重复释放 |\n\n### 3. 并发、时间与资源断言\n\n- 使用可控时钟模拟超过300秒、延迟完成、空闲及总截止，不让单元测试真实等待300秒。\n- 让心跳／进度定时与兜底入口竞争，断言只有一个输出所有者、终态至多一次、终态之后没有任何帧。\n- 在首个兜底帧之前、正文中途及结束标记前取消，断言写入及时终止、取消回调同步退出、租约只释放一次。\n- 对已有空流计数的账号执行有产出兜底，断言计数保持原值：既不累加也不清零，不进入退休／提拔路径。\n- 断言生成发送次数与兜底前一致；兜底不能消耗一次纠偏或续答额度，也不能重建预算。\n- 双并发接近正文限额、JSON高转义膨胀、慢下游同时出现时，验证累计缓冲和整个兜底绝对截止；竞态检测通过不等于进程内存达标，内存测量单独记录。\n- 诊断只保留固定类别及数量；敏感正文、工具参数、凭据不得进入日志。\n\n### 4. 限时验证命令\n\n以下均为拟执行命令，工作目录为项目根目录；本轮没有运行。每条单独前台执行，前一条退出后才能运行下一条，外层30秒、测试内部20秒，关闭自动工具链及模块下载。\n\n拟新增资格、线协议及安全测试：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=1 -timeout=20s -run '^TestResearchSalvage(Eligibility|WireSequence|BodyIntegrity|ToolGuard|SSETail|Compatibility)$' ./internal/api < /dev/null\n```\n\n拟新增取消、单写者及租约竞态测试：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=10 -timeout=20s -run '^TestResearchSalvage(CancellationRace|SingleWriter|LeaseExactlyOnce|WriteFailure)$' ./internal/api < /dev/null\n```\n\n保留既有缓冲完成守卫回归：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=1 -timeout=20s -run '^TestT23_CompletionGuard$' ./internal/api < /dev/null\n```\n\n账号生命周期回归：\n\n```bash\ntimeout 30s env GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off GOMAXPROCS=2 go test -v -race -count=1 -timeout=20s ./internal/session < /dev/null\n```\n\n门禁要求：\n\n- 必须核验每组预期测试及子测试实际运行；正则未命中而返回退出码0不算通过。\n- 既有 [`TestT23_CompletionGuard()`](../../internal/api/chat_buffered_completion_test.go:83) 明确约束异常默认路径；新增研究例外使用独立夹具，不删除原有普通路径断言。\n- 工具链、竞态依赖、编译缓存及离线依赖是否齐备尚未核验。缺依赖、编译超时或测试超时均为阻塞，不冒称测试通过。\n- 冷编译若需要准备，另行授权并安排有界构建，不偷偷延长上述单测时间，也不借验证下载未批准依赖。\n- 记录命令、工作目录、退出状态、实际命中的测试和关键输出；只声明已运行的覆盖范围，不将这些命令当成全仓验收。\n\n### 5. 零客户端修改的验收门\n\n验证允许使用未修改的客户端，不等于授权修改客户端。真实上游及生产验证仍须独立授权。\n\n首期上线至少验证：\n\n1. 目标Roo Code版本与实际提供商适配路径能够显示44KB级合成安全正文，并保留网关提示。\n2. 长度终态及结束标记后，不进入原提供商错误重试路径；记录是否存在其他自动继续或“必须调用工具”纠偏。\n3. 实际上游发送次数与预期一致，不能用网关单请求计数代替客户端是否发出新HTTP请求的证据。\n4. 原文、长度状态和提示进入客户端历史；不要求修改其保存逻辑，但必须观察实际结果。\n5. 工具开启场景零误执行；如果目标客户端无法满足，不通过合成工具或透传截断信封掩盖失败。\n\n若目标客户端仍把长度终态视为错误，或因缺少工具继续重试，则“零红框／停止重试”的目标未通过。不能把网关HTTP 200或结束标记写成功当成客户端验收替代品。\n\n### 6. 文档与生命周期边界\n\n本稿替代旧草案中的私有协议、客户端改造及EOF后新增强制远端取消建议；不自动替代已接受ADR，也不将历史完成守卫测试改记为新方案通过。\n\n拟关联的 [`ADR-20261011-studioglobal-long-research-graceful-salvage.md`](../adrs/ADR-20261011-studioglobal-long-research-graceful-salvage.md) 本轮读取返回文件不存在，不能因为编辑器有标签页就称其已建立或已接受。\n\n后续工程接管应明确登记对“异常响应不发送终止标记”的研究部分正文例外，同时保留上游异常事实、工具完成屏障、三次发送总预算和账号分类。当前仅重写指定草案，不新建ADR、不覆盖活动计划、不实施代码、不执行测试或部署。\n\n## 证据索引\n\n以下编号区分外部第一方定义、本会话已经返回的源码及用户现场报告；链接行号基于本轮可见源码，实施前须重新核对。\n\n- [2](cite:2) [OpenAI官方聊天流式事件定义](https://developers.openai.com/api/reference/resources/chat/subresources/completions/streaming-events.md)：标准聊天块与终态字段结构。\n- [14](cite:14) [OpenAI官方SDK的固定版本完成类型定义](https://github.com/openai/openai-python/blob/e41abf7b7dbc1e744d167f748e55d4dedfc0dca7/src/openai/types/chat/chat_completion.py)：长度终态表示达到请求指定的最大生成Token数，不能直接当作EOF的标准原因定义。\n- 本会话已返回的四条约301秒生产结束记录及用户最新现场报告。目标请求df7d165f-9193-4f48-b307-9042dd30c624的时长、读取、缓冲、结束类别有日志摘录；474,096输入计数、红框自动重试归因、代理身份和准入制计费结论属于用户报告，证据层级不同。\n- [`chat.go`](../../internal/api/chat.go:67)：终止分类；[`请求错误与发送生命周期`](../../internal/api/chat.go:539)；[`租约及取消清理`](../../internal/api/chat.go:703)；[`普通流`](../../internal/api/chat.go:823)；[`工具缓冲与异常守卫`](../../internal/api/chat.go:983)；[`非流式`](../../internal/api/chat.go:1244)；[`512KiB缓冲上限`](../../internal/api/chat.go:153)。\n- [`chat_execution.go`](../../internal/api/chat_execution.go:62)：固定总截止；[`正文进展刷新`](../../internal/api/chat_execution.go:246)；[`共享收尾截止`](../../internal/api/chat_execution.go:113)。\n- [`chat_output.go`](../../internal/api/chat_output.go:309)：进度与业务时钟隔离；[`错误帧`](../../internal/api/chat_output.go:340)；[`有界写入、短写和刷新`](../../internal/api/chat_output.go:356)。\n- [`sse.go`](../../internal/stream/sse.go:96)：EOF残留事件处理；[`decode.go`](../../internal/upstream/studioglobal/decode.go:92)：答案、完成、状态与裸文本兼容回退。\n- [`output_format.go`](../../internal/toolcall/output_format.go:43)：协商工具格式及协议候选处理；[`constraints_request.go`](../../internal/toolcall/constraints_request.go:164)：整批调用与强制选择校验。\n- [`chat.go`](../../internal/api/chat.go:117)：账号释放分类；[`manager.go`](../../internal/session/manager.go:42)：一次性释放、账号代际检查及空流计数。\n- [`budget.go`](../../internal/toolcall/budget.go:19)：最多三次发送；[`续答证据`](../../internal/toolcall/budget.go:45)；[`提交后禁止重放`](../../internal/toolcall/budget.go:70)。\n- [`chat_buffered_completion_test.go`](../../internal/api/chat_buffered_completion_test.go:83)：普通缓冲及非流式的原有完成守卫测试；读取到测试源码不等于本轮已运行。\n- [`client.go`](../../internal/upstream/studioglobal/client.go:264)：远端取消钩子、共享收尾与停止生成／计费未知的诊断边界。\n- 本会话已返回的 [`零产出异常分类ADR`](../adrs/ADR-20261007-3b-empty-upstream-eof-recovery.md:96)、[`研究恢复与续答契约`](../adrs/ADR-20261008-studioglobal-model-registry-research-presets.md:372) 相关检索片段，以及拟关联新ADR的文件不存在返回结果；不据此声称新方案已取得实施或部署验收。\n"}}