mirror of
https://git.openapi.site/https://github.com/desirecore/config-center.git
synced 2026-10-21 01:24:43 +08:00
9.8 KiB
9.8 KiB
plan_path, revision, related_workdirs
| plan_path | revision | related_workdirs | ||
|---|---|---|---|---|
| /Users/wangyi/.codex/worktrees/c0a8/config-center/docs/plans/catalog-contract-migration/PLAN.md | 3 |
|
PLAN：旧字段迁移、客户端门控、域名退役与模型规格优化
状态：实施中。用户已要求逐一完成；先做P0/客户端P1，并行完成编译与规格治理，客户端实际发布后再启用新数据。P0、P1、P2、P3、P4、P5的任务和证据记录见 EXECUTION.md。
目标与基线
- config-center 基线：main
4f4e5093e91ead6c9f01aacc188d23ea4b5e8917，presetDataVersion 127。 - 已发布客户端核查对象：v10.0.177，tag commit
dd5a8c9f2fb000f7b2c589ec092068874c7dec5c。release 标记为正式版本，发布时间 2026-09-27，targetCommitish 为 dev；主仓 main412e05b...不能代替该发布基线。 - 范围：29 份 Provider、11 份套餐、23 份规格文件；340 条接入模型记录、279 条 ModelSpec，共 619 条来源记录。
- 当前 40 份接入配置仅 2 份有 requiredClientVersion。149 种 extra 叶路径出现在 233 条记录中；149 种不等于 149 个旧字段，全部需要完成消费/归属分类。
- 用已发布客户端的真实匹配器核对：303 exact、3 normalized、1 stripped、9 pattern、7 family、17 未匹配；45 条记录存在 contextWindow/maxOutputTokens 差异。58 条规格未被静态接入记录命中，不能据此认定无用，可能服务云端动态目录、历史身份或待适配协议。
- 本轮已迁移的 14 个无效推理键不再残留；下一阶段不能把“旧键告警为零”当作全部字段已规范。
推荐取舍
保留 Provider 与 model-specs。推荐“规格单处维护 + 接入面显式覆盖 + 编译得到有效配置与兼容副本”。不要合并成一个巨大 Provider 文件，也不要删掉 Provider 只留下规格。
| 域 | 唯一作者数据 | 不应承担 |
|---|---|---|
| ModelSpec | 精确模型身份、原厂已核事实、输入/输出独立限制、模态与固有限制、模型级路由策略、证据和生命周期 | endpoint、凭据、账号开放名单、平台价格、接入 effort、thinking 回放或平台 WebSearch |
| Provider / 套餐 | 地域、端点、凭据、账号可用模型、协议/适配器、计价单位与价签、显式接入限制和 API 参数映射 | 再次手工复制所有模型事实、靠 family 推定新型号能力 |
| 编译器 / 客户端 resolver | 按字段规则组合 ModelSpec 与接入覆盖，记录每个有效值的来源，生成旧客户端副本 | 私自补 unknown、合并不同单位或把完整能力列表取并集 |
| 用户配置 | 用户选项、合法覆写和自建接入 | 被远端预设覆盖或被按名称猜测的迁移修改 |
格式路线：新增版本化 V2 目录/manifest/schema 与客户端读取选择器，旧路径维持冻结的 V1 兼容投影。新版本原始作者数据不再保留运行时旧字段；兼容投影由生成器产出，过渡期不手工双写。完成客户端铺开后停止更新旧投影并归档，移除条件必须明确。具体见规格与接入职责设计。
执行阶段
| 阶段 | 工作 | 产物 | 进入下一阶段的条件 |
|---|---|---|---|
| P0：冻结清单与语义 | 完整盘点仓内/存量客户端字段；核149种extra路径的定义和真正读写位置；分型45条参数差异、17个无匹配和7个family；核域名下架事实 | 字段映射矩阵、版本能力矩阵、域名退役候选、来源缺口和dry-run报告 | 每个字段都有归属与处置，未知项独立登记；不能批量猜值 |
| P1：客户端先行 | V2 schema/目录选择、全局合同版本门控、Provider/模型/适配器门控、统一有效配置resolver、配置迁移与回滚；补退役域名出站拦截 | 客户端代码PR、跨版本/存量配置测试、正式发布 V_contract | 真正正式发布且验收支持新合同的版本存在；版本号不能用未发布main或猜10.0.178填写 |
| P2：数据与字段迁移 | 迁移受管旧字段；消除重复作者字段；保留有依据的接入覆盖；按冻结schema生成V1投影；同步来源/缺口文档 | V2 canonical、编译器、字段移除清单、来源登记、必要manifest递增 | 全部受管旧运行时键在V2写入端为零；迁移幂等、无静默丢值、价格/单位/覆写保持；V1兼容检查通过 |
| P3：ModelSpec完善 | 先修精确身份、错误pattern、独立输入预算，再逐条解决45处数值差异；补生命周期/适配状态；逐家核官网 | 单供应商PR、已核字段、显式override及自动路由资格清单 | 每条启用模型有精确绑定或明确动态或仅手动例外；客户端原生适配未实现则保留记录并明确禁止调用，不能因为API格式名称已识别而宣称支持；差异都分类为正确覆盖/错误/待核，不能要求全相等 |
| P4：域名退役 | 对已确认退役的接入移除活跃引用与索引；模型墓碑、Provider退役注册、存量停用、缓存/任务/默认回退同步 | 域名注册表、客户端退役迁移、活跃引用零残留与出站反例测试 | 确认范围内不再发送凭据或轮询；历史来源链接可保留；不会误伤同域其他有效API和用户自建数据 |
| P5：发布与退出兼容 | 在客户端门控已经生效后发布V2数据，校验正式版本和全部来源；审查精确head、CI、review线程，再合并和远端复核 | 发布批次报告、各版本行为矩阵、剩余待核列表、V1退出记录 | 低版本不会应用新合同；当前版本和新版通过回归；没有把Schema通过当账号/协议实测 |
P4 的实现机制可在 P1 并行开发；确认过的遗留退役接入可单独走窄范围修复，不必等所有官网字段核完。大范围字段删除和V2切换必须经过 P1。
首批优先事项
- P0/P1，版本门控：40份接入及279条规格声明其能力依赖。以已发布tag检查功能，证明升级前后的读取、拒绝和缓存行为；显示“需更新”之外，还要堵住显式Provider、SDK、工作流、后台辅助和媒体调用绕过。
- P3，GPT-5.4 Nano误匹配：当前走 gpt-5.4 的 pattern，Nano 400000 窗口可能被 1050000 规格混淆。补独立exact规格、收窄pattern，并用真实匹配器验证；其他代际误吞一并巡检。
- P3，独立输入限制：Mini/Nano 的272000输入与400000总窗口、讯飞65536输入与131072输出分别表达；不再用 contextWindow 伪装最大输入。
- P0/P2，参数差异：Codex订阅272000与原厂1050000不是自动错误；MiniMax-M3共享输出512000与直连131072证据仍不完整；OpenRouter上限按其独立合同处理。见匹配与差异基线。
- P0/P4，历史下架接入：零一万物已由本仓#84删除，但已发布客户端退役名单仅见internal-testing。补受管旧配置迁移；“本产品已下架”与“厂家域名已停止服务”的证明分别登记，不能直接封整个lingyiwanwu.com。
- P2，定价/媒体/思考旧字段：价格同义字段、音频格式/音色、思考默认和旧metadata优先分类；不把缓存读价、TTL写价、按字符/每秒/每search unit价格改成同一token价。
并行实施安排
本次实施采用三个 subAgent 与主工作线协作。配置中心复用当前工作区；客户端从最新dev创建隔离worktree，按要求拉取最新子模块。
- A：字段归属、迁移器与兼容投影；独占迁移工具、字段schema和迁移测试。
- B：ModelSpec精确绑定、参数与官方字段核查；按供应商分工，不同时修改同一 canonical。
- C：域名/Provider退役清单、客户端停用与出站拦截；独占退役注册与相关测试。
- 主工作线：客户端版本矩阵、格式门控、resolver接口、交叉review、manifest和发布；共享schema变更先定接口再分配，不能多代理同时改同一文件。
P0 的只读清单可并行；P1 完成后再进行数据迁移和下架发布。客户端仓 worktree 若需建立，先同步并更新最新子模块，保留无关gitlink及用户改动。
完成标准
- 所有仓内受管字段及已识别存量旧字段都完成“保留有效规范字段/映射迁移/转记录性metadata/明确退役”的处置；运行时写入V2旧键为零，旧读取兜底有退出条件。
- 40份接入、全部V2规格/协议的依赖都可计算最低版本；未支持版本在读取和实际调用两层被拦；离线保留最后一份可消费数据。
- 已确认退役域名/路径/接入在活跃配置、默认映射、同步发现和后台任务中零残留；无法证实退役的域名留待核，不误删。
- 每个接入绑定准确规格或明确动态例外；45处差异有解释、7处family没有扩大调用或路由权限；58个未命中静态接入的规格完成用途分类。
- 原厂事实、接入限制、价格、用户覆写、产品路由政策都可追溯；未知不自动变成零、默认值或全能力。
- 老/最低/当前客户端、受管旧配置、用户自建配置、重复迁移、回滚、停服域名和新模型调用矩阵通过。
核验和发布细则见验收与发布；字段、版本、域名、规格专题分别拆分在同目录，避免把证据和全部任务堆在本文件。
实施中补充的实际边界（revision 3）
真实适配器与profile执行已核36条当前未适配接入（3Realtime、21图像/视频、12ASR/TTS），原默认local-whisper/whisper-large-v3亦缺profile。此任务落实适配状态与实际调用门控，不以保留记录宣称这些接口已可用，不静默替换用户默认。原生适配器新增属于已列独立接入依赖，详见ADAPTER-DECISIONS。