pref(provider):修正 Provider 生成重试默认语义并放宽退避上限

[phantom5099]

之前存在的问题

1. generate_max_retries 无法区分“未配置”和“显式关闭”

原实现里 GenerateMaxRetries 是普通 int：

• provider.yaml 未填写 generate_max_retries
• provider.yaml 显式写入 generate_max_retries: 0

这两种情况在解码后都会变成 0。
结果是配置层丢失了“字段是否被显式设置”的信息。

直接后果：

• 无法同时满足“未填写时使用默认值 5”和“显式 0 关闭重试”这两种语义
• 实际行为更接近“0 就是不重试”，和文档承诺不一致

2. 文档语义与代码实际行为不一致

原文档将 generate_max_retries 描述为：

• 未填写或 <= 0 时回退默认值 5

但生产代码中：

• 配置校验不允许负数
• 0 会原样进入运行时配置

这意味着正常配置路径几乎不可能触发“负数回退默认值”的语义，文档与实现存在偏差。

3. 生成重试退避上限偏紧

原退避窗口是：

• 基线 1s
• 上限 5s

对短时 429 / 5xx 抖动场景而言，这个上限偏保守。在重试次数有限的情况下，稍微放宽上限可以提升恢复概率，同时不会引入不可控的长时间阻塞。

采取的方案

方案一：为 generate_max_retries 增加“三态语义”

• GenerateMaxRetries：继续承载数值
• GenerateMaxRetriesSet：记录字段是否被显式配置

运行时语义调整为：

• 未填写：使用默认值 5
• 显式 0：关闭生成重试
• 显式正数：按配置值生效

这样可以在不大面积改动调用方的前提下，把“默认值”和“显式关闭”重新区分开。

方案二：在 provider.yaml 读写链路中保留显式零值

为了避免 YAML 层再次吞掉语义，本次对持久化链路做了收口：

• 读取时用可选字段识别 generate_max_retries 是否真的出现
• 写入时只有在“显式配置”时才落盘该字段
• 显式写 0 时会保留 generate_max_retries: 0
• 未配置时继续省略字段，避免污染配置

方案三：放宽统一退避上限

保留现有指数退避 + 抖动策略，只把最大等待时间从 5s 提升到 7s：

• 不改变重试触发时机
• 不改变首包后不重试的边界
• 只提升极端情况下的最大等待窗口

改动情况

配置与运行时语义修正

涉及文件：

• internal/config/provider.go
• internal/config/provider_loader.go
• internal/config/provider_custom_normalize.go

核心改动：

• 在 ProviderConfig 中引入 GenerateMaxRetriesSet
• 新增 resolveGenerateMaxRetries()，集中解析默认值 / 显式关闭 / 显式数值三种语义
• 让 provider.yaml 的 generate_max_retries 走“可选字段”解析
• 保存自定义 provider 时保留显式 0，未配置时继续省略

测试补强

涉及文件：

• internal/config/provider_test.go
• internal/config/loader_test.go
• internal/provider/constants_test.go

新增覆盖点：

• 未配置 generate_max_retries 时，运行时默认使用 5
• 显式 generate_max_retries: 0 时，运行时保持禁用重试
• provider.yaml 持久化时，显式 0 不会被丢失
• 退避上限常量更新为 7s

文档对齐

涉及文件：

• docs/guides/configuration.md
• docs/guides/adding-providers.md

修正内容：

• 明确“未填写默认 5”
• 明确“显式 0 表示关闭重试”
• 保持 generate_idle_timeout_sec 的原有默认语义说明不变

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[fennoai]

Completed 4-pass review (code quality, performance, security, documentation). No noteworthy issues found.

[fennoai]

已核对本次语义更新与实现：generate_max_retries 的“未配置默认值”与“显式 0 关闭重试”表述一致。此处无阻塞问题。

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Cai-Tang-www]

没看到有啥问题