用途：在 Pydantic AI 中把某个提供方（provider）的 API 新能力暴露出来，例如提示缓存、严格/结构化工具调用、thinking/reasoning effort、service tier、安全设置、logprobs、缓存断点等。适用于新增能力特性，不适用于新增模型 ID（见 add-new-model）、修 bug 或重构。
主要原则：
- 先找治理该能力的既有跨提供方抽象，由其形态决定 API，避免新增 provider 专属参数。可选抽象包括：per-tool 标志 ToolDefinition.strict、共享 ModelSettings 字段（thinking、service_tier）、{Provider}ModelSettings 前缀字段（anthropic_cache、openai_prompt_cache_key、groq_reasoning_effort）、消息流标记 CachePoint、ModelProfile 能力标志（openai_supports_strict_tool_definition 等）。
- 选 API 形态：有共享抽象就复用并加映射；无共享抽象但 ≥3 个提供方已有该概念，则提升为共享 ModelSettings 字段，保留 provider 字段作为优先的逃生口；原生取值无法用共享枚举表达时，才允许 {provider}_* 参数。参数需类型化，用 Literal，禁止 extra_body 或无类型 kwargs。
- 默认值：仅在开启不改变可观察行为且不增加成本时才默认开启；预览特性、可能提价、可能触达提供方限制、含损失性 schema 重写时保持 opt-in，默认值应避免静默升级到更贵层级。
- 能力门控：用 Provider.model_profile() 中带 provider 前缀的 ModelProfile 标志检测，禁止内联 isinstance/模型名判断；按模型/族、per-schema 信号、SDK 版本探测分层门控；不支持时静默忽略并写进 docstring，不硬报错；用户设置冲突用 UserWarning。
- 测试：用实录的 wire-contract cassette 断言出站请求体，并测试新设置，优先参数化 VCR 而非 mock。
- 文档与技能：docstring 列出支持的提供方及取值含义，更新 docs/**.md 与相关 agent skill；ModelSettings 的 Supported by 列表由测试校验，新增字段需同步修改。