Pi 模型能力与思考档位需求

状态：已实现并完成验收
原则：预设完整可靠，自定义配置不猜测；运行时不依赖外部模型目录。

1. 当前版本边界

模型能力分为两条互不混用的路径：

• Pi 供应商预设由 CC Switch 维护完整模型配置，选择后可以直接保存。
• 自定义供应商和“获取模型列表”只帮助填写模型 ID，不自动推断模型能力。

当前版本不建设面向自定义供应商的运行时模型数据库，也不从 Pi、models.dev、oh-my-pi 或其他服务下载数据。外部资料只用于开发时人工核对预设。

这项功能不修改数据库 Schema，不参与显式供应商同步，也不管理 Pi 的默认供应商、默认模型、auth.json、路由、故障转移或插件。

2. 预设模型

src/config/piModelCatalog.ts 只用于复用 Pi 供应商预设中的模型知识，不作为自定义模型的全局识别器。

每个预设模型必须离线包含完整的 Pi 原生字段：

{
  id: string;
  name: string;
  reasoning: boolean;
  input: Array<"text" | "image">;
  contextWindow: number;
  maxTokens: number;
}

规则如下：

• 同一模型的公共能力在目录中维护一次。
• 供应商存在特殊限制时，由对应预设显式覆盖。
• 预设别名只在该预设中有效，不能让自定义供应商中的同名 ID 自动获得能力。
• 预设数据必须随应用发布，离线可用。
• GPT-5.6 Sol 的公共上下文长度为 272000。
• 不从其他应用的预设或 Pi 运行时模型列表动态生成 Pi 预设。

3. thinkingLevelMap

Pi 原生档位为：

type PiThinkingLevel =
  | "off"
  | "minimal"
  | "low"
  | "medium"
  | "high"
  | "xhigh"
  | "max";

type PiThinkingLevelMap = Partial<Record<PiThinkingLevel, string | null>>;

必须保留以下语义：

• 字符串表示发送给上游的实际值。
• null 表示该档位明确不可用。
• 缺少某个键表示该档位使用 Pi 默认行为。
• {} 表示整组明确使用 Pi 默认行为。
• 稀疏映射不得被自动补齐。
• reasoning: true 不代表所有档位都可用。

所有支持思考的预设模型都必须显式带有 thinkingLevelMap：

• 已确认接口语义的组合使用对应的映射。
• 尚无可靠专用映射的组合使用 {}，明确交给 Pi 原生行为。
• Anthropic 自适应思考等需要额外 Pi 原生兼容字段的预设，应同时写入必要的 compat，不能只让界面显示档位。

映射只服务预设构建。自定义供应商即使输入相同模型 ID，也不会自动套用预设映射。

4. 自定义模型

用户手动添加模型或从上游模型列表选择模型时：

• 模型 ID 写入表单。
• 显示名称在仍为空时同步为模型 ID，用户可以修改。
• reasoning、input、contextWindow、maxTokens 和 thinkingLevelMap 不从本地目录或网络自动填写。
• 上下文长度和最大输出 Token 必须填写正数后才能保存。
• “支持扩展思考”和“支持图片输入”由用户明确选择；默认分别为关闭和仅文本。
• 开启扩展思考后才显示思考档位编辑器。
• 未填写 thinkingLevelMap 时由 Pi 使用原生默认档位；用户仍可在表单或配置 JSON 中写入字符串、null、稀疏映射或 {}。

界面不显示“自动值”“已覆盖自动值”或“恢复自动值”，因为自定义模型不存在后台推断值。

5. 配置 JSON 与旧配置

• 结构化字段和配置 JSON 双向同步。
• 用户已有的模型字段与 thinkingLevelMap 原样回显。
• 未知 JSON 字段无损保留。
• JSON 中的稀疏映射、单项 null 和 {} 不得改变语义。
• 旧模型缺少本版本要求的字段时，只在编辑表单中提示用户补全；用户保存后才落盘。
• 应用启动、供应商列表刷新和外部配置同步不得静默补写模型能力。

6. 验收

自动化测试至少覆盖：

• 每个预设模型都有完整的名称、思考能力、输入类型、上下文长度和最大输出 Token。
• 每个推理预设模型都显式拥有合法 thinkingLevelMap。
• 所有 GPT-5.6 Sol 预设均使用 272000 上下文。
• 选择自定义或拉取到的已知模型 ID 时不会自动注入能力或思考映射。
• 自定义模型缺少名称、上下文长度或最大输出 Token 时不能保存，并聚焦错误字段。
• JSON 往返不丢未知字段或改变思考映射语义。

真实 Pi 验收使用隔离配置目录，并确认：

• 预设生成的完整原生模型配置可被 Pi 加载。
• Pi 对字符串、null、缺少键和 {} 的档位处理符合原生语义。
• 需要特殊兼容字段的预设产生正确的真实请求。
• 测试不修改用户实际的 auth.json、默认供应商或默认模型。

面向自定义供应商的模型数据库留待后续独立设计，不在本版本中提前保留运行时索引、网络回退或来源状态。