Skip to content

fix: 深审超时治理 — review 单次调用默认 300→1200s + 超时结构化标因 (#54) - #56

Merged
tizerluo merged 2 commits into
mainfrom
fix/54-review-timeout-defaults
Oct 3, 2026
Merged

tizerluo merged 2 commits into
mainfrom
fix/54-review-timeout-defaults

Conversation

@tizerluo

@tizerluo tizerluo commented Oct 3, 2026

Copy link
Copy Markdown
Owner

根因(#54 调研结论,脱敏摘要)

三次「LLM 阶段 300s 超时、exit2/isError、无 verdict」全部来自未显式设 ZCODE_BRIDGE_REVIEW_TIMEOUT 的调用方(人工/agent 的 --call 与 MCP 直调),不是常驻 gate 的问题——gate 一直显式传 3600,对同样 head 的审查全部成功(journal/state 双证)。

两层叠加:

  1. 预算缺失:_review_timeout() 默认 300s,而 depth=deep 复核是多轮「读文件+推理」循环。gate 侧 49 次深审实测:两仓中位时长 305s / 409s,57% / 71% 超 300s——300s 默认对 deep 档是必然超时(--call 模式对 isError 约定退出码 2,即 issue 的「exit2/isError」;mimosa 扫描有独立预算先正常完成,故呈现「Mimosa 正常但无 verdict」)。
  2. 放大器([compat] 0.16.9 官方 runtime headless:ZCODE_MODEL 等 env 注入疑似失效,模型选择走配置文件(闸门机升级实证) #55):ZCODE_MODEL 等注入环境变量被包装器/新版 runtime 忽略,子进程可能落在 providerOrder 首位的慢模型上(实测单请求 TTFT 87-213s),令深审更不可能在 300s 内完成。本 PR 不修 [compat] 0.16.9 官方 runtime headless:ZCODE_MODEL 等 env 注入疑似失效,模型选择走配置文件(闸门机升级实证) #55,仅消除预算层。

变更

  • _review_timeout() 默认 300 → 1200:docstring 记实测依据与取舍——挂死子进程占用 ReviewFileLock 的时长随之变长(锁等待仍 300s)。
  • _run_zcode_headless 超时分支:structured_output=True 时 result 顶层附 timeout: {"seconds": N}——与 quota_limit/refusal 同型的机器契约,调用方可区分「预算不足/过慢」与其他失败,不必解析 isError 文本(issue 建议的 degraded verdict 的前置件)。
  • README:env 表与并发最坏阻塞估算同步(约 20 分钟 → 约 85 分钟,注明依据)。

测试

  • RC4 默认值断言 300→1200;新增 TestTimeoutAttribution TA1/TA2(结构化键存在 / 普通形状不变)。
  • 全套 542 passed,ruff 干净。

Closes #54 的修复部分(issue 中的超时三发已由本 PR 消除复发条件;#55 另行跟进模型解析)。

根因 (#54 调研): 未显式设 ZCODE_BRIDGE_REVIEW_TIMEOUT 的调用方 (人工/agent 的
--call 与 MCP 直调) 走 300s 默认预算, 而 depth=deep 复核是多轮读文件+推理循环,
闸门侧实测两仓 21/28 次深审中位时长 305s/409s (57%/71% 超 300s) — 对 deep 档
必然超时, 表现为 'LLM 阶段 300s 超时 exit2/isError 无 verdict'。review-gate
自身显式设 3600 不受默认值影响, 因此只有闸门外的调用方受害。

变更:
- _review_timeout() 默认 300 → 1200, docstring 记实测依据与取舍 (挂死子进程
  占用 ReviewFileLock 的时长随之变长, 锁等待仍 300s)
- _run_zcode_headless 超时分支: structured_output=True 时 result 顶层附
  timeout {seconds} — 与 quota_limit/refusal 同型的机器契约, 调用方可据此
  区分预算不足与其他失败, 不必解析 isError 文本
- README env 表 + 并发最坏阻塞估算同步 (约 20 分钟 → 约 85 分钟, 注明依据)

测试: RC4 默认值断言更新 300→1200; 新增 TestTimeoutAttribution TA1/TA2
(结构化键存在/普通形状不变)。全套 542 passed, ruff 干净。
按 code-reviewer 审查意见修复 (无 P0/P1):

- P2-1 (方向 B, 保守): 锁等待维持 300s 不动, 语义文档化 — 深审常态超
  300s 后并发直调的第二个 review 在锁等待耗尽时快速失败 (fail-fast,
  调用方稍后重试); 并为锁超时失败补结构化键 lock_timeout {seconds}
  (与 timeout/refusal 同型机器契约, 仅 structured_output)。docstring 与
  主 README 并发段落同步说明。
- P2-2: review-gate 源码注释与子包 README 的「mcp-server 默认 300s」
  过期陈述同步为 1200/上限 3600 (本 PR 改默认值时漏改的两处)。
- P3-1: 「对 deep 档必然超时」→「多数超时」(与 57%/71% 实测自洽),
  mcp-server docstring + 主 README env 表两处。
- P3-2: TA1/TA2 补子进程调用计数断言 ==1, 钉住「超时不进限流重试
  循环」(对齐 SQ1 惯例)。
- P3-3: 模块 docstring 覆盖清单补 #54 条目。
- P3-4: timeout/lock_timeout 键的仓内消费方不在本 PR 接线 (gate 失败
  分类变更属 #54 后续 degraded verdict 议题), PR 描述记消费计划。

测试: 新增 TA3 (锁超时键 + 锁失败先于 spawn + 与 timeout 键区分);
全套 543 passed, ruff 干净。
@tizerluo
tizerluo force-pushed the fix/54-review-timeout-defaults branch from 2b2436e to 63c9f58 Compare October 3, 2026 18:10
@tizerluo

tizerluo commented Oct 3, 2026

Copy link
Copy Markdown
Owner Author

R1 审查修复(code-reviewer 全项采纳)

审查结论:无 P0/P1,2×P2 + 4×P3。逐条处置:

级别 问题 处置
P2-1 锁等待 300s × 预算 1200s 的并发语义(第二个直调必然 fail-fast)且锁超时无结构化标因 采纳(保守方向 B):锁等待值不动,语义文档化(docstring + README 并发段:深审常态超 300s,后者快速失败、调用方稍后重试);新增 lock_timeout: {"seconds": N} 键(与 timeout/refusal 同型,仅 structured_output)。未选方向 A(锁跟随预算)——会再抬最坏阻塞且并发直调本就罕见,方向 B 行为面最小;如需排队语义一行可改
P2-2 review-gate 源码注释 + 子包 README 两处「默认 300s」过期陈述 已同步为「未显式设值默认 1200(#54),上限 3600,长尾仍偏紧故 gate 仍钉 3600」
P3-1 「必然超时」与 57%/71% 实测自相矛盾 改「多数超时」(docstring + README env 表)
P3-2 TA 未钉「超时不进重试循环」 TA1/TA2 补调用计数断言 ==1(对齐 SQ1)
P3-3 模块 docstring 覆盖清单漏 #54 已补
P3-4 timeout 键无仓内消费方 本 PR 不接线(gate 失败分类变更属 #54 后续 degraded verdict 议题,避免「透传了也没人读」);消费计划记录在 issue #54

测试:新增 TA3(锁超时键存在 / 锁失败先于子进程 spawn / 与 timeout 键语义区分);全套 543 passed,ruff 干净。

@tizerluo
tizerluo merged commit cbc35ab into main Oct 3, 2026
4 checks passed
@tizerluo
tizerluo deleted the fix/54-review-timeout-defaults branch October 3, 2026 18:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[P2] zcode_pr_review 深审 LLM 300s 超时三发:Mimosa 正常但无 verdict,私有运维仓线闸缺

1 participant