# 03 Provider 层模块化

## 背景

`pkg/providers/http_provider.go` 当前聚合了通用 HTTP provider、Responses API、OpenAI-compatible Chat、Codex/Qwen/Kimi 兼容逻辑、OAuth runtime 状态、请求构造、响应解析和部分持久化状态逻辑。文件复杂度偏高，继续新增 Provider 会越来越难。

## 目标

在保持现有行为和测试通过的前提下，把 Provider 层按职责拆开，降低单文件复杂度。

## 建议改动范围

主要文件：

- `pkg/providers/http_provider.go`
- `pkg/providers/oauth.go`
- `pkg/providers/*_provider.go`
- 新增若干 provider 内部文件

建议新增文件：

- `pkg/providers/provider_registry.go`
- `pkg/providers/responses_adapter.go`
- `pkg/providers/openai_compat_adapter.go`
- `pkg/providers/provider_runtime.go`
- `pkg/providers/provider_request_options.go`

尽量避免修改：

- `pkg/agent/*`
- `pkg/tools/*`
- `cmd/*`
- `pkg/api/*`

## 建议拆分

### Provider 注册与路由

移动到 `provider_registry.go`：

- `CreateProvider`
- `CreateProviderByName`
- `normalizeProviderRouteName`
- `getProviderConfigByName`
- provider alias / route 相关逻辑

### Responses API 适配

移动到 `responses_adapter.go`：

- Responses request body 构造。
- Responses input item 转换。
- Responses tools 转换。
- Responses response 解析。
- Responses compact summary。

### OpenAI-compatible Chat 适配

移动到 `openai_compat_adapter.go`：

- chat completions request body 构造。
- multimodal message 转换。
- function call 转换。
- Qwen/Kimi 兼容 chat 格式相关公共逻辑。

### Provider runtime 状态

移动到 `provider_runtime.go`：

- runtime state 结构。
- history 持久化。
- health score。
- recent hits/errors/changes。
- candidate order。

### 请求选项与通用解析

移动到 `provider_request_options.go`：

- `rawOption`
- `stringOption`
- `mapOption`
- `stringSliceOption`
- `int64FromOption`
- `float64FromOption`
- 其他 request option helper。

## 验收标准

- `go test ./pkg/providers` 通过。
- `go test ./...` 通过。
- Provider 对外接口不变。
- 现有配置文件无需迁移。
- `http_provider.go` 明显缩小，并聚焦 `HTTPProvider` 本体。
- 没有改变已有 provider 的请求格式，除非测试明确覆盖并更新说明。

## 测试建议

重点跑：

```bash
go test ./pkg/providers -count=1
go test ./pkg/agent ./pkg/api ./cmd -count=1
go test ./...
```

Provider 层已有大量请求构造测试。拆分时应优先保持测试不动，让测试证明行为未变。

## 并行注意

该任务风险较高，建议不要和“新增 Provider”或“AgentLoop 工具调用逻辑改动”同时修改同一分支。若必须并行，先完成纯移动，再做行为改动。