[Feature]: 引入显式 Provider Capability Profile / Add explicit provider capability profiles

[Sun-sunshine06]

[Feature]: 引入显式 Provider Capability Profile / Add explicit provider capability profiles

Problem / pain point / 问题

当前 provider 行为主要靠以下信息组合推断：

• wire
• baseUrl
• model 命名启发式
• 若干兼容性补丁

这套方式能工作，但很多关键兼容性事实仍是隐式的，导致：

• diagnostics 很难准确说明“为什么失败”
• UI 很难清晰说明“这个 provider 支持什么”
• imported/custom provider 很难声明细粒度能力
• 新兼容性工作容易继续演化成 heuristic patch

Current provider behavior is inferred from wire, baseUrl, model-name heuristics, and targeted compatibility patches. It works, but too many compatibility facts remain implicit.

Proposed solution / 方案

为 provider entry 增加显式 capability profile，例如：

• supportsModelsEndpoint
• supportsResponsesApi
• supportsChatCompletions
• supportsSystemRole
• supportsDeveloperRole
• supportsReasoning
• supportsToolCalling
• supportsKeyless
• requiresClaudeCodeIdentity
• modelDiscoveryMode

Use this profile as the primary source of truth for request shaping, diagnostics, model discovery, and imports.

Alternatives considered / 备选方案

• 继续完全依赖 heuristics
  • 不利于规模化扩展
• 仅在 UI 层维护 profile
  • main/providers 也需要同一份信息

Scope / 范围

Provider / model

Acceptance criteria / 验收标准

• provider entry 可声明 capability profile
• built-in provider 有合理默认值
• custom/imported provider 可覆盖默认值
• runtime request shaping 可读取该 profile
• diagnostics 能利用 profile 给出解释
• 相关测试补齐并通过

Likely touchpoints / 可能涉及

• packages/shared/src/config.ts
• apps/desktop/src/main/provider-settings.ts
• apps/desktop/src/main/connection-ipc.ts
• packages/providers/src/index.ts

[Sun-sunshine06]

Parent epic / 所属总 issue: #214

[github-actions]

谢谢反馈。已核对当前实现，这个方向对应的是一个真实的结构性空缺：当前 ProviderEntry 里只有 wire、baseUrl、defaultModel 以及少量可选字段，没有找到统一的 capability profile 定义，所以 provider 行为现在确实分散在配置字段、wire 分支和兼容性逻辑里。

另外，这个仓库目前还处在 v0.1.x 的早期阶段，README 里也把 Provider / API config polish 和更清晰的 connection diagnostics 列为当前优先项，因此不少能力判断现在还是以兼容性补丁和启发式逻辑实现的。

Relevant code:

• packages/shared/src/config.ts:130 — 当前 ProviderEntrySchema 只声明了 wire、baseUrl、defaultModel、modelsHint、httpHeaders、queryParams、requiresApiKey、reasoningLevel，未找到显式 capability profile 字段
• packages/core/src/index.ts:576 — reasoningForModel() 目前按 provider / modelId / baseUrl 做推断，而不是读取统一能力描述
• packages/providers/src/claude-code-compat.ts:56 — Claude Code identity 兼容逻辑依赖 wire + baseUrl 推断
• packages/providers/src/gemini-compat.ts:23 — Gemini 的 models/ 前缀兼容也是按 baseUrl 在请求时单独修正
• packages/shared/src/diagnostics.ts:212 — generate-time diagnostics 目前按 wire、baseUrl、HTTP status 和 message 做启发式分类
• apps/desktop/src/main/onboarding-ipc.ts:631 — custom provider 现在可保存/覆盖 wire、baseUrl、defaultModel、httpHeaders、queryParams、envKey
• apps/desktop/src/main/imports/codex-config.ts:141 — imported provider 已能带入 wire、envKey、requiresApiKey、httpHeaders、queryParams
• packages/shared/src/base-url.ts:113 — modelsHint 目前是一个单点例外，用来处理没有可发现 /models 端点的场景

从现有代码看，custom/imported provider 已经能覆盖一部分行为，但像 supportsResponsesApi、supportsToolCalling、supportsDeveloperRole、modelDiscoveryMode 这类显式能力位，目前代码里没有对应的一等结构。这个问题描述和当前实现状态是一致的。

---

open-codesign Bot

[Sun-sunshine06]

Opened PR #215 for the minimal capability-profile scaffolding / 已提交最小可用 capability profile PR：#215

[Sun-sunshine06]

人工 review 结论（针对 PR #226 feat(shared,providers,core): explicit provider capability profile (#206)）：我这边建议 merge。

我重点看了这次 PR 相对当前 main 的净增量，主要是两块：

• 在 packages/shared/src/config.ts 里把 requiresClaudeCodeIdentity 的默认值从固定 false 收敛为基于 anthropic host 的解析结果，并保留 capabilities.requiresClaudeCodeIdentity 显式覆盖能力
• 在 packages/providers/src/index.ts 里让运行时 header 注入优先尊重 capabilities.requiresClaudeCodeIdentity，补上对应测试

我没有看到需要阻塞 merge 的问题，原因是：

• 变更范围很小，且和 [Feature]: 引入显式 Provider Capability Profile / Add explicit provider capability profiles #206 的目标一致，属于把已有 capability profile 继续落到一个真实的兼容性分支上
• 保持了向后兼容：未显式声明 capability 的 provider 仍会走 resolver 默认值；显式声明时仍以声明值优先
• 新增测试覆盖了官方 Anthropic host、自定义 relay host，以及显式 override 两条关键分支
• 当前 GitHub checks 也都是绿的（CI / CodeQL / dependency review / pr-review 全通过）

如果要说残余风险，更多是后续演进项而不是这次 PR 的阻塞项：requiresClaudeCodeIdentity 现在是 capability profile 中第一个真正落到 host-based 默认推断的能力位，后面如果继续把更多 capability 位接入 runtime/diagnostics，最好沿用同样的 resolver + test 策略，避免再次散落回 heuristic patch。

所以我的意见是：可以 merge。