opencodex Provider Context-Cap Toggle 设计解析：为 Codex 模型目录实现可逆的上下文窗口上限

opencodex Provider Context-Cap Toggle 设计解析为 Codex 模型目录实现可逆的上下文窗口上限【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodex本设计文档系列00_design.md、10_implementation.md、20_global-cap-and-set-all.md完整记录了 opencodex 中Provider 级上下文上限开关从设计、实现到全局化演进的完整过程。读完本文你将掌握该开关如何以最小的侵入性修改 Codex 可见的模型目录catalog、为什么把上限存放在根级配置而非 provider 元数据中、Cap 350k开关的 API 契约与目录降级语义以及后来如何演进为全局可配置的100k–950k上限值与一键Set all控制。功能定位一个 provider 级、非 Kiro 专属的开关opencodex 的 Models 页面原本已经允许用户逐个开关模型以及按 provider 批量启用/禁用。本次改动在其之上新增一个 provider 级开关当开关打开时opencodex 会把该 provider 的大上下文模型context window 超过上限的模型向 Codex 通告为最多 350k 上下文小于等于上限的模型保持不变上游请求路径完全不修改设置持久化在 opencodex 配置中开关每次切换后刷新 Codex 模型目录。设计文档特别强调该设置是provider 通用的而不是 Kiro 专用。若某个 provider 没有任何超过 350,000 上下文的模型打开开关是安全的 no-op——目录封顶只会降低已知上下文窗口绝不会凭空捏造数值。核心设计决策根级配置而非 provider 元数据设计文档给出了一个明确的架构决策——把 provider 上下文上限存为根级配置而不是放进providers[provider].modelContextWindows内部providerContextCaps?: Recordstring, number;该决策的推理在 00_design.md 中列出四点保留原始 provider/model 元数据不被污染关闭是可逆的无需重建旧的modelContextWindows映射UI 只需切换一个 provider 开关不必逐行编辑每个模型未来若要支持不同的上限值无需数据迁移。该字段的最终落点可在 src/types/config.ts 中看到providerContextCaps?: Recordstring, number;配置 schema 侧src/config/schema/config-schema.ts增加了显式校验保证手写的config.json也诚实合规providerContextCaps: z.record(z.string(), z.number().int().positive()).optional(),从源码实现看src/providers/context-cap.ts上限值必须满足有限的正数才有效export const DEFAULT_PROVIDER_CONTEXT_CAP 350_000; function isValidContextCap(value: unknown): value is number { return typeof value number Number.isFinite(value) value 0; }行为契约/api/models扩展与新增/api/provider-context-caps设计文档为管理 API 定义了完整契约全部在 src/server/management/model-rows.ts 等实现中得到印证GET /api/models返回每个模型的同时附带三个新字段contextWindow?: numbercontextCap?: numbercontextCapped?: boolean新增端点GET /api/provider-context-caps返回{ caps: Recordstring, number }PUT /api/provider-context-caps接收{ provider: string, enabled: boolean }。启用时保存caps[provider] 350000禁用时从映射中移除该 provider。端点拒绝未知/无效的 provider 名称。每次 PUT 保存配置、清除该 provider 的模型缓存并像模型可见性变更一样尽力刷新 Codex 目录clearModelCache(provider)refreshCodexCatalogBestEffort()。Models 页面在每个 provider 标题旁All on/All off旁边显示Cap 350k开关。没有超过 350k 模型的 provider 也显示开关启用无害因为目录封顶只会降低已有上下文窗口。目录封顶语义只降不升、绝不凭空捏造给定模型解析后的上下文窗口封顶逻辑是if providerContextCaps[provider] is a positive number: contextWindow min(resolvedContextWindow, cap)关键边界情况如果模型完全没有上下文元数据cap 不会发明出350000仍由现有目录默认行为负责。这保持了用户没有模型超过上限就是 no-op的预期。设计文档用三条规则锁定了applyProviderContextCap的行为00_design.mdapplyProviderContextCap(undefined, 350000)返回undefinedapplyProviderContextCap(500000, 350000)返回350000applyProviderContextCap(64000, 350000)返回64000。最终实现在 src/providers/context-cap.ts 中完全一致export function applyProviderContextCap(contextWindow: number | undefined, cap: number | undefined): number | undefined { if (!isValidContextCap(cap)) return contextWindow; if (!isValidContextCap(contextWindow)) return contextWindow; return contextWindow cap ? cap : contextWindow; }实现文档进一步确认封顶被线程化贯穿了所有模型解析路径10_implementation.md配置的静态模型、实时/models结果、新缓存、过期缓存回退、以及 jawcode 增强路径——cap 在既有 provider/model 提示hints之后应用确保它只能降低已知上下文窗口绝不发明数值。全局上限值与 Set All从固定 350k 到用户可控第三阶段20_global-cap-and-set-all.md将硬编码的 350k 演进为全局可配置值但上限依然是所有 provider 共享的单一全局值而非 per-provider在 Models 页面页头与第一个 provider 区块之间新增一行可点击控件cap 值下拉框100k–950k50k步进外加Custom...数值输入与一个Set all开关。contextCapValue?: number存入根配置src/types/config.tsschema 校验为z.number().int().positive().optional()src/config/schema/config-schema.ts未设置时回退到DEFAULT_PROVIDER_CONTEXT_CAP。全局值变更时所有已启用 provider 被重新指向新值保证开关视觉状态一致D2 决策。Set all on以当前全局值写入目录中每个 providerSet all off清空整个providerContextCaps。API 演进GET /api/provider-context-caps返回{ cap, value, caps }cap保持兼容性回退值value为生效全局值PUT按请求体形态分支{ value }全局值变更、{ setAll }全量开关、{ provider, enabled }单 provider 切换启用时写入当前全局值而非硬编码常量。无效value非有限、≤0以400拒绝并强转为正整数。实现侧src/providers/context-cap.ts新增globalContextCapValue、setGlobalContextCapValue可带applyToAll重定向所有已启用 provider、setAllProviderContextCaps三个辅助函数setProviderContextCap在启用时写入生效的全局值。UI 侧使用fmtK辅助函数把350000渲染为350k非 50k 网格的自定义值按其自身k值或原始 token 数展示provider 开关标签与封顶行标记Cap 500k、500k cap都显示实际生效值而非字面350k。验证计划与交付物三个阶段的验证命令保持一致贯穿始终bun test tests/config.test.ts tests/codex-catalog.test.ts tests/server-auth.test.ts bun x tsc --noEmit cd gui bun run build测试覆盖在 tests/codex-integration/codex-catalog.test.ts、tests/server/config.test.ts 与 tests/server/management-provider-validation.test.ts 中均有印证核心断言包括cap 将实时元数据从500_000降至350_000cap 不会抬高64_000cap 不会为无上下文的静态模型发明数值过期的缓存元数据同样被施加 capjawcode 目录元数据不得在 provider cap 逻辑之后恢复 1M 上下文窗口B 阶段回归修正10_implementation.mdGET 返回 caps 映射PUT 启用并持久化、禁用并移除 provider未知 provider 被拒绝/api/models包含 cap 元数据contextCapValue接受合法正整数并 round-trip非法值0/负数/非整数被 schema 拒绝。提交记录遵循设计→实现→测试的节奏docs(models): design provider context cap toggle、feat(models): add provider context cap toggles、feat(models): global context cap value set-all toggle以及后续的 backend/UI/test 拆分提交。设计过程还特意划定了脏文件红线——src/adapters/kiro.ts与tests/kiro-stream.test.ts等与本次改动无关的既有未提交修改不得被触碰、暂存、回退或用作完成证据后续阶段的红线文件为 cursor adapter 相关文件。总结可逆、无损、贯穿全链路的目录封顶从设计到落地的完整演进可以概括为一条主线用根级、可逆、只降不升的配置统一控制 Codex 可见目录中 provider 模型的上下文窗口。核心可复用结论有三点其一上限独立于 provider 元数据存储使开关可逆且无需迁移其二封顶语义严格限定为min(resolved, cap)未知窗口不被发明、小窗口不被抬高天然保证 no-op 安全性其三cap 贯穿静态配置、实时获取、缓存与 jawcode 增强全部路径且 API 提供单 provider 切换、全局值变更与 Set all 三档控制粒度。这份设计文档与其最终实现src/providers/context-cap.ts、src/codex/catalog/为 opencodex 的模型可见性控制提供了一个最小侵入、最大可逆的范本。【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考