企业官网建设流程全解析

（正文以devlog/_fin/260720_toks_speed_price_columns/003_missing_price_research.md为骨架，结合src/usage/expected-prices.ts、src/usage/cost.ts、src/generated/model-metadata.ts、tests/usage/usage-cost.test.ts等仓库证据展开。）

导读

OpenCodex 用 jawcode 静态价格表为每条请求日志计算~$成本估算（详见 002 调研 与 WP1 成本核心 PRD），但 jawcodemodels.json并不覆盖全部模型：订阅/OAuth 面（Kimi、Antigravity、Cursor 等）常常缺失cost行，或为全零。本文即记录这项“缺口价格调研”的完整方法论与结论：如何分级验证官方单价（verified / verified-derived / unverified / not-published）、如何把 4 元组价格落成 expected-price 覆盖层、如何通过 fail-closed 解析器保证 UI 永远不显示$0假价格，以及 3 轮调研后最终在仓库中落地的实现形态。

读完你能够掌握：一套可复用的“官方价格取证→降级派生→fail-closed 落地”流程，以及 OpenCodex 中expected-prices.ts/cost.ts的完整解析链与测试契约。

背景：为什么需要“缺失价格调研”

在 WP0（调研阶段，见 000 计划）的 002 调研中，主流程实测过静态 registry 的价格覆盖率：53 个 provider、198 个候选 (provider, model) 对，其中可 alias 到 jawcode bundle 的 70 对，exact 命中的仅 44 对（62.86%），未命中的 26 对（37.14%），另有 3 对命中但 cost 全零。这 29 对无法由现有静态表给出价格，而其中不少正是用户实际会用的面：

• 订阅/OAuth 面（kimi、google-antigravity、cursor、kiro、openrouter 等）——这些 provider 的模型没有公开的按 token 单价，或者单价只能从官方页面上逐条核实；
• 模型 ID 带 effort 后缀（gemini-3.5-flash-extra-low / low / mid / high、gemini-3-flash-agent、gemini-3.1-pro-low/high 等）——官方价格表只有基础模型行，后缀变体不单独定价；
• 品牌改名/新模型（MiniMax-M2.1-highspeed、deepseek-chat/reasoner 等）——jawcode bundle 尚未同步。

结论是：条件可行，但必须引入“expected-price 覆盖层 + 分级取证 + fail-closed 显示”。003 文档正是这一覆盖层的数据源与取证纪律。

1. 调研口径与状态分级

003 调研由 Luna 多 lane 并行（3 个 lane：gpt-5.6-luna explorer 等），主流程逐条验收。每条价格用一个 4 元组表示：

(input, output, cacheRead, cacheWrite) USD / 1M tokens

状态的语义（该语义在后续实现expected-prices.ts中固化为ExpectedPriceStatus类型）：

这一分级在 010 PRD §5 中被正式采纳为代码契约：findExpectedPriceOverlay()只返回verified与verified-derived，unverified在代码层面就拒绝返回（fail-closed 由代码强制，而非仅靠文档纪律）。对应类型定义见 src/usage/expected-prices.ts 的ExpectedPriceStatus。

2. 第一轮调研：verified 表与 not-published 表

2.1 Verified —— 官方单价已核实（首批 8 行）

第一轮共核实 8 行，其中 6 行可直接入覆盖层（xiaomi 因 CNY 计费暂缓）：

两个关键注记（都在后续实现中保留为source字符串的构成部分）：

• Google cache-write 不可映射：Google 对缓存存储按小时计费，不是按 token 计费，因此 cacheWrite 无法直接进 4 元组 →cacheWrite = 0并在来源注明。这在最终实现里体现为GEMINI_PRICING常量中的 “cacheWrite=0: storage is billed per-hour, not per-token”。
• gemini-3.1-pro 是分段价：≤200k 与 >200k 两个区间。覆盖层采用 ≤200k 档，来源注明区间，避免对 >200k 请求给出误导性的精确值。
• suffix 不单独定价：gemini-3.5-flash 的 extra-low/low/mid/high、gemini-3-flash-agent 都没有官方单独单价，按基础模型价格映射（Agent 走 Agent API 计费原则，官方 Billing FAQ）。这正是verified-derived的典型场景。
• deepseek 预告 2026-07-24 V4 Flash alias 切换：deepseek-chat/reasoner 两行需在切换后重新验证——这是后续 backlog 里反复出现的条目，并在最终实现中被记录进DEEPSEEK_PRICING来源字符串（“V4 Flash alias transition scheduled 2026-07-24 — re-verify after”）。

2.2 Not published —— 官方未公开，保持—

以下模型在调研时点官方确实没有单价表（价格页打开后无按 token 计价），因此按策略保持 fail-closed—，不入覆盖层：

关键教训：“没有官方单价”不等于“免费”。all-zero 只表示未计价，不能当作$0。这一点在后文 §6 的 all-zero 策略中成为硬性规则，并由 usage-cost.test.ts 的测试 7 强制（all-zero 行 + 空 overlays →null，禁止$0）。

2.3 Unverified / 结构不同 —— 后续再调查

3. 第二轮调研（当天下午，WP5）：Kimi 价格公开 + Antigravity 派生

第二轮是因用户信息（Kimi 价格已公开）触发的复检：“1 查时点未刊登价格”已变为“公开”。这一轮新增 24 键，总覆盖来到 35 键（11 + 24）：

排除 1 键：openrouter/openai/gpt-5.6-sol—— jawcode openrouter bundle 已有相同非零价 (5/30/0.5/6.25)，overlay 无意义，resolver 直接用 jawcode 价。但文档同时记录了一个结构局限：当前 schema 只容纳 ≤272K 单价，无法表达 272K 以上区间的 (10/45/1/12.5) 分段价 → 进 backlog。（这个“分段价”局限，后来在 expected-prices.ts 的CONTEXT_TIERS/findContextTier中被系统性解决，见 §8。）

Cursor 仅auto入表：其余 cursor 模型（composer 等）不公开模型级单价，仅 MAX Mode 透传 provider 官方价，无法可靠映射 → 按策略保持—。

3.1 第二轮仍不登记（fail-closed 维持）

• kiro：credit 计费，无官方 token 等价；
• xai grok-composer-2.5-fast：官方价表未收录（Grok Build 免费提供）；
• openrouter/openai/gpt-5.6：OpenRouter 目录无精确 ID；
• google-vertex gemini-3-pro：preview 结束（retired），价表移除；
• gemini-pro-agent：非公开 Google 模型 ID，官方映射未确认；
• alibaba-token-plan qwen3.8-max-preview：Token Plan 为额度扣减订阅（¥39~499/月），token→credit 换算公式未公开；禁止套用 Model Studio PAYG；
• zai glm-4.6：查到的其实是 glm-4.7 价格 (0.6/2.2/0.11)，registry 里是 4.6 → 不匹配；
• cerebras/mistral/xiaomi/zenmux：registry 无对应模型（cerebras/mistral/xiaomi），或动态计费（zenmux 需 API 查询）；
• opencode-go/kimi-k3：opencode-go 自身计费体系独立，不能套 Moonshot 官方价；
• umans/neuralwatt/ollama-cloud/mimo-free：未调查（no-alias，自计费推测）。

4. 第三轮：策略变更——模型级官方价 fallback

第三轮引入一项重要策略变更：不再按 provider 逐个调查，而是确立“模型无论经过哪个 provider，都遵循其官方价”的原则。例：kiro的claude-opus-4.6→ 用 anthropic 官方价。

这直接改写了resolveMatchedPrice的解析链，从两级变为三级 fallback（该结构保留在现仓库 src/usage/cost.ts 的resolveMatchedPriceExact()中，并额外加入了用户覆盖层，见 §8）：

1. jawcode exact（provider bundle，status verified） 2. expected 覆盖层 exact（verified / verified-derived） 3. jawcode 供应商 bundle 模型级搜索（findVendorCostByModelId）—— 供应商优先级 anthropic → openai → google → moonshot → minimax → deepseek → xai → zai → mistral → cerebras → azure-openai → amazon-bedrock → xiaomi， exact modelId + dot→dash 归一化一次（kiro `claude-opus-4.6` ↔ anthropic `claude-opus-4-6`），status verified-derived，记录匹配到的供应商 bundle

该供应商优先级与模型级 fallback 的落地证据就是 src/generated/model-metadata.ts 里的COST_VENDOR_PRIORITY与findVendorCostByModelId()（第 80–94 行）：按优先级顺序遍历供应商 bundle，取第一个非零 cost 行。dot→dash 归一化在 src/usage/cost.ts 的resolveModelLevelPrice()中实现。

4.1 策略变更带来的覆盖提升

此前 openai（OAuth）provider 的 gpt-5.x 系因为没有jawcodeBundle全部未匹配；模型级 fallback 上线后，它们开始按 openai 供应商价汇总。

重测覆盖（静态 registry 198 候选）：127 对拿到价格（64%），未拿到 71 对，覆盖范围：

• 已覆盖的实际使用面：openai OAuth、kiro/cursor 的 anthropic·gpt、kimi 全系、deepseek、minimax、AG gemini/claude。
• 仍未覆盖：cursor 自命名变体（claude-4-sonnet 等）、composer 系、umans/neuralwatt/ollama-cloud/zenmux 自计费、zai GLM-5.x、alibaba-token-plan、kiro-auto、github-copilot/claude-sonnet-4、openrouter/openai/gpt-5.6、google-vertex/gemini-3-pro、gemini-pro-agent。

5. 覆盖层决策汇总（WP1 输入）

调研结论进入实现（WP1）时，首批确定登记11 对（provider 必须用 registry 的真实日志 provider id——例如是google-antigravity而非google）：

• verified（4）：minimax/minimax-cn× MiniMax-M2.1-highspeed；deepseek× deepseek-chat / deepseek-reasoner。
• verified-derived（7）：google-antigravity× gemini-3.1-pro-low/high（基础 gemini-3.1-pro ≤200k）、gemini-3.5-flash-extra-low/low/mid/high（基础 gemini-3.5-flash）、gemini-3-flash-agent（基础 gemini-3-flash + Agent 计费原则）。

比例总结：29 个问题对（26 未匹配 + 3 all-zero）中，本次调研实现 11 对可入覆盖层，其余按 not-published/unverified 保持 fail-closed。

这 11 对全部保留在今天的 src/usage/expected-prices.tsEXPECTED_PRICE_OVERLAYS数组中（MiniMax、DeepSeek、gemini-3.1-pro-low/high、gemini-3.5-flash-extra-low/low/mid/high、gemini-3-flash-agent 等行），并且 usage-cost.test.ts 的测试 16 专门断言覆盖层只含 verified / verified-derived、绝无 unverified 行——把调研纪律变成了回归测试。

5.1 登记保留（—维持）清单

Kimi 全系（首轮时点）、grok-composer-2.5-fast、openrouter/openai-gpt-5.6、Antigravity 的 claude/gpt-oss、zai、alibaba-token-plan、cerebras、mistral、xiaomi（CNY）、kiro、github-copilot（换算表未拿到）、gemini-pro-agent（模型 ID 未确认）、gemini-3-pro（价表无独立条目，禁止与 3.1-pro 等同视之）。

6. 落地：expected-prices.ts 与 cost.ts 的解析链

调研的“4 元组 + 状态分级 + fail-closed”最终物化为两个实现文件：

6.1src/usage/expected-prices.ts—— 覆盖层 schema 与 loader

核心类型与常量（对应 003 的调研成果）：

export interface Cost4 { input: number; output: number; cacheRead: number; cacheWrite: number; } export type ExpectedPriceStatus = "verified" | "verified-derived" | "unverified"; export interface ExpectedPriceOverlay { provider: string; modelId: string; cost4: Cost4; source: string; // 官方页面来源 + 派生依据（如 Kimi 自动缓存 → cacheWrite=input） verifiedAt: string; status: ExpectedPriceStatus; }

查询函数findExpectedPriceOverlay()的纪律（与 003 决策完全一致）：

1. provider + modelIdexact 匹配（无 fuzzy、无 case-fold、无 wire-model fallback）；
2. 优先级verified→verified-derived；
3. unverified永不返回——fail-closed 由代码强制。

针对 cursor 还有一个特例：normalizeCursorClaudeId()先把claude-fable-5.1/claude-5.1-fable等拼写归一化到 canonical ID 再查覆盖层（实现见 expected-prices.ts 的findExpectedPriceOverlay()尾部）。

6.2src/usage/cost.ts—— 完整解析优先级

现仓库中的解析顺序（cost.tsresolveMatchedPriceExact()）比 003 的三级链又多了一层用户覆盖层，总计为：

1. 用户配置覆盖层（activeUserCostOverlays，operator 显式 modelCosts 最优先） 2. 官方修正覆盖层（VERIFIED_PRICE_OVERRIDES，仅对声明的 provider/model 生效） 3. jawcode exact（provider bundle 非零价） 4. expected 覆盖层（verified → verified-derived） 5. 模型级供应商 fallback（findVendorCostByModelId，dot→dash 一次） 6. null → UI `—`

关键实现细节：

• all-zero 不是免费：hasNonZeroCost()为 false 的 jawcode 行不会命中第 3 步，而是继续尝试覆盖层；覆盖层也没有 →null。显式 all-zero 的用户覆盖才算免费（operator 说了算）。
• 账户池命名空间：activeAccountPricingProviders()会把账户池日志 label（如anthropic-pb51d9b）归一到基础 provider 再查询——这解决了“账户池日志 label 也要有价格”的诉求。
• Antigravity base-model 折叠：canonicalAntigravityUsageModel()把历史/wire ID 折叠到 picker base model 后再查一次。
• 缓存记忆化：priceMemo按(provider, model, version)缓存解析结果，/api/usage遍历几十万行时避免每次都重新解析（用户覆盖层刷新会 bump version，缓存不会过期）。
• verify/derived 传播：只要价格状态是verified-derived，或 usage 本身estimated，estimateAttemptCost()就置estimated=true——GUI 据此在详细原因中说明。

用户在 003 末尾看到的重测 64% 覆盖率，正是这条五层链 + 供应商模型级 fallback 的合力结果。

7. 测试契约：把调研纪律固化成回归

usage-cost.test.ts（1687 行）把 003 的所有决策点变成了可执行断言，关键几条与本文直接对应：

另有normalizeCostTokens()的 13 个用例（canonical-first + legacy retry、R+W>I矛盾 →null）保证缓存换算不双计（对应 002 §2 的转化式，是“按 token 计价不重复收费”的根基）。

8. 调研之后的持续演进（覆盖层如何被复用与扩展）

003 建立的数据结构与纪律没有止步于 11 对。现仓库的 expected-prices.ts 已把同一套机制扩展到后续多轮调研：

• 官方价覆盖层持续扩充：GPT-6 Astra、GPT-5.6 sol/terra/luna、Claude Fable 5.1 / Opus 5、Gemini 3.6/3.7/3.8 Flash（含促销时段注记）、Kimi K 系全谱、GLM 家族（zai / zhipu-bigmodel / zhipu-bigmodel-coding / zhipu-bigmodel-responses）、Qwen3.8、Meta Muse、Cursor auto、Devin swe 系等，全部遵循 verified / verified-derived 两级 + 来源字符串注记的纪律。
• 官方修正（VERIFIED_PRICE_OVERRIDES）：对 jawcode 中“非零但已过时”的行做精确纠正（如 xai grok-4.6、openai gpt-5.6-sol 调价），仅对声明的 provider/model 生效，不会误伤复用同名 slug 的转售面。
• 优先级倍率（PRIORITY_PRICING_RULES）：OpenAI Fast 档、xAI Priority 档的倍率（2× 等），要求 response 确认才生效（requiresResponseConfirmation）。
• 长上下文分段（CONTEXT_TIERS）：弥补 003 记录的“≤272K 单一 schema 无法表达分段价”局限——OpenAI 272k 以上整请求 2×/1.5×、xAI 200k 以上统一 2×、MiniMax 512k 以上统一 2×，且以rawusage.inputTokens（含缓存）判定阈值，防止缓存重的长请求被低估。

这一整条链都在 cost.ts 的estimateAttemptCost()/estimateRequestCost()/estimateComboCost()中按序应用：context tier → priority multiplier → 输出 4-way cost breakdown 与tokensPerSecond()。

9. 再调查 backlog 与可复用方法论

003 末尾记录的 backlog 对照现仓库看后续进展：

这套方法论可以复用到任何新 provider/新模型：

1. 先查官方价格页：能直接打开核对 →verified；
2. 查不到独立单价但有基础模型价：suffix / alias / Agent 收费原则 →verified-derived（source 注明派生依据）；
3. 既无单价也无可派生基础：订阅 quota、credit、兑换表类 →not-published/ 保持—，禁止臆造；
4. 只有线索：写进 backlog 待重查，绝不写进覆盖层（unverified由 resolver 代码拒绝）；
5. 落表后立即写回归：membership、优先级、fail-closed、estimated 传播各一条断言。

按此流程，任何“jawcode 缺失 + 官方有价”的模型都能安全进入 OpenCodex 的成本估算体系，而“官方确实无价”的面永远不会出现$0的假账单。