🐛 fix(sdk): utils 域八项修复——结构化输出兜底、Retry-After 退避、审批大小写等

[CavinHuang]

概述

修复 sdk 全量 review 提出的 8 个 issue（utils / prompt / token 域），每个 commit 独立可跑绿。

Issue	修复
#318 (P1)	structured-output 解析失败后兜底提取首个平衡 JSON 块（跳过字符串字面量与转义），重试提示强化首字符必须是 {
#291	settings user 路径遵循 LUME_CONFIG_DIR（与 fs-loader 同款语义：trim/空白回退/相对路径基于 cwd）
#350	markdown-frontmatter 放行顶格 - 列表项，items 为空时告警（skills allowedTools 不再静默丢失）
#351	重试退避尊重 Retry-After（delta-seconds/HTTP-date 双格式解析，120s 硬上限）；挂载点迁移见 #422
#354	settings 读取区分 ENOENT（静默）与坏 JSON/权限（console.warn 带路径），安全配置不再 fail-open 无声
#364	microCompact 补数组形态 tool_result：text 块按预算截断；仅超预算的 image/document 块替换占位（小图原样保留，不损伤视觉能力）
#366	getContextWindowSize 硬编码表未命中回退 findModelMeta(model)?.contextWindow（gemini/qwen 1M 窗口不再落 200k）
#379	工具审批通配符与精确匹配改大小写不敏感（deny 不再漏配 fail-open；mcp__ 前缀结构保留不过归一）

验证

• bun run typecheck 六 workspace 全部 exit 0
• packages/sdk 全量 bun test src：591 pass / 0 fail / 1 skip（skip 为既有 natives 双态）
• 独立 code review 通过：逐 commit 对照 issue 方案 + 调用点回归核查（其中 [P3][sdk/utils] microCompact 只截断字符串形态的 tool_result，数组形态大结果不设防 #364 初版无条件占位媒体块被 review 抓出视觉能力回归，已返工为超预算门槛方案）

Notes

• [P2][sdk/utils] retry 完全忽略 Retry-After，限流窗口大于累计退避时烧光重试抛终态错误 #351 的 parseRetryAfterHeader/computeRetryDelay 保留在 retry 层并有测试；生产挂载点随 provider 移除迁至 sidecar 传输层，跟踪于 [P2][sdk/providers] Retry-After 挂载点需随 provider 移除迁移至 sidecar 传输层 #422。
• rebase 至 main 最新（含 🔥 移除 SDK 内置 LLM providers，统一宿主注入契约 #283 providers 移除）：openai/openai-responses 相关 hunks 已按移除语义丢弃。

Closes #318, closes #350, closes #351, closes #354, closes #364, closes #366, closes #379, closes #291

🤖 Generated with Claude Code

[CavinHuang]

Code Review

八项逐项核对完毕，全部真实落地、无虚报，无 P0/P1，可合。以下为修复深度/跨层一致性的遗留发现。

逐项结论

#318（兜底+提示强化）、#350（放行顶格列表+空值告警）、#354（ENOENT 静默/其余 warn 带路径，判定正确）、#364（超预算才占位的设计保住了视觉能力）、#366（registry 回退已验证 gemini-2.5-pro=1048576 且 bundled seed 使测试非空洞）、#379、#291（与 resolveConfigDirValue 语义逐点对齐）、#351（非流式路径真实生效；流式主链路由 sidecar 既有逻辑承担，披露诚实）。#379 的实现方向（raw lowercase 前缀而非过别名归一）比 issue 原处方更正确。

发现

[P2] #318 兜底只尝试首个 {，prose 中更早的非 JSON 花括号对会让兜底彻底失效（structured-output.ts:63-67）
兜底只提取第一个平衡 {...} 块；若该块 parse 失败整个解析直接放弃。模型输出 The config {mode} controls it.\n{"answer":"ok"} 时 candidate={mode} 解析失败 → 重试耗尽——这正是 #318 要救的场景的残余形态（prose 含花括号极常见）。新测试只钉 happy path，无一覆盖前导花括号噪音。建议 candidate 失败后从下一个 { 循环继续提取。

[P2] #364 数组形态预算逐块生效而非逐结果，多中块 tool_result 聚合仍不设防（compact.ts:738-764）
text/image/document 块均按单块阈值判定，无 per-result 累计。50 个 49k 文本块或 20 个 40k 小图（合计 1-2MB）每块都低于门槛整体原样通过。microCompact 作为 prompt-too-long 前的防御层，聚合洞恰是它存在的意义。建议函数内累计放行块总长，超预算后剩余块统一占位。

[P2] #351 与 sidecar 形成两套 Retry-After 语义，sdk 侧在 Retry-After: 0 时退化为零延迟风暴（retry.ts:374-388 vs pi-ai-provider.ts:29,78-88）
sdk 侧有 retryAfterMs 时完全取代指数退避（无 jitter 无保底，Retry-After: 0 → 0ms 立即重试）；sidecar 侧取 max(jittered, retryAfter) 保底；硬上限 120s vs 30s 分叉。生产主链路重试发生在 sidecar 内部循环，同一错误先经 sidecar max 语义重试 5 次耗尽后才进 sdk replace 语义再试。建议至少统一硬上限，sdk 改用 max(退避, hint)，并在 #422 明确两层策略契约。

[P3] #366 硬编码 includes 表仍遮蔽 registry 较新数据（tokens.ts:163-166）：model.includes('sonnet-4') return 200_000 抢先于 registry 回退命中，而 generated.json 中 claude-sonnet-4-5/4-6/5 均为 1M——「表未命中」修了，「表命中但值过时」没修。生产 sidecar 显式传 contextWindow 掩盖。建议表项逐步收敛为 registry 优先。

[P3] #364 热路径对所有媒体块做完整 stringify 计长（compact.ts:753 + engine.ts 每 turn 全量历史）：hydrate 已把图片展开为完整 base64，单块可达数 MB，历史多截图时每轮重复付出。建议用 source.data.length + 常数开销 估算替代。

[P3] 新重试提示语对数组根 schema 是错误指引（engine.ts:1506）："must begin with {"，但 jsonSchema 是公开 SDK 选项且数组根合法，extractFirstBalancedJsonObject 也只认 {。仓内无数组根用法，风险面在外部 SDK 消费者。建议按 schema.type 动态生成或改措辞。

[P3] #350 空列表告警对合法 YAML null 值键误报（markdown-frontmatter.ts:58-61）：tags: 后紧跟下一个 key 是合法 YAML（null 值），现在每次加载都告警，skills 每会话加载噪音累积。建议仅对已知列表语义键告警。

[P3] #379 测试缺口：别名通配符场景（issue 的核心反例）未钉住（tool-approval.test.ts:23-42）：缺 matchesToolPattern("Bash", "bash*") 用例；若后续有人把 wildcard 分支改回经别名归一（会破坏 mcp__ 结构），现有测试部分不红。

CI 6/6 全绿、typecheck 绿。建议 #318 循环提取与 Retry-After 上限统一随本 PR 或紧跟 #422 处理；其余 P3 可入 follow-up。