维护者确认：自定义 Provider SDK 费用默认隐藏（PR #2878）

[MagicLizi]

触发

fix(desktop): hide custom provider SDK costs by default 修改了桌面端 UI 路径（ProvidersSection.tsx / CustomProviderBillingSection.tsx 等），命中 product 确认门。

变更要点

自定义 Provider 的 SDK 费用是服务端自行上报、Cindy 无法控制计价规则，金额可能与服务商账单不一致。本 PR 将自定义 Provider 默认改为仅展示输入 / 输出 / 总 Token，并在「设置 → Providers」保留一个默认关闭的「显示 SDK 上报费用」开关（开启旁有风险提示）。

判定为产品行为变化（默认展示策略调整 + 新增设置开关），自动流程不代跑放行，需要维护者确认。

确认方式

• 认可此默认策略：直接在 PR 上 Approve，放行后自动流程继续审查合并；
• 需要修改：Request Changes 说明，作者改完后再 Approve 即放行。

---

关联 PR:#2878(作者 @A1aZ);本 issue 由 review-pr 流程自动创建,用于先讨论该 PR 涉及的产品 / UI 变更,维护者确认后 PR 会恢复推进。

[dash-s-cindy]

判断：自定义 Provider 的未经验证金额不应继续以“实际费用”进入消息、会话和每日支出；默认优先展示 Token 能直接降低用户把 Cindy 数字当成服务商账单的风险。建议认可这个产品方向，但暂不直接 Approve #2878，先 Request Changes 收紧费用语义和既有估价兼容性。

行动：建议在维护者确认默认策略前，要求 #2878 完成以下调整：

1. 未经供应商账单侧确认的 SDK costUSD 不得写入 actual-cost、session spend 或 daily spend。
2. 用户主动配置的 API 估价，以及可用的 Provider 参考价，继续按 value-estimate 展示并与实际支出隔离；不要被“隐藏 SDK 金额”开关一并清空。
3. 若保留开关，建议将其定义为“显示 SDK 估算”，只控制估算值的展示，不控制实际账本；文案明确“不是供应商账单”。
4. 补一轮真实自定义 Provider 的 Desktop 运行验证，至少确认消息、用户轮累计、会话累计、今日支出和 Token fallback 的口径一致，再由维护者确认默认值。

研究结论

1. 真正需要修复的是金额可信度和账本分类

当前主干 apps/desktop/src/main/usage/turnCostCalculator.ts 对普通 provider-api 路由优先消费正数 sdkCostDelta，经 usdToLedgerCurrency() 转换后返回 source: 'sdk'。该金额默认形成 kind: 'actual-cost'，随后会进入：

• 消息级 turnCost / 用户轮累计；
• sessions.total_cost_* 会话累计；
• daily_spend 与按模型支出。

现有源码对 DeepSeek 已明确记录：Claude SDK 的 costUSD 可能是客户端按公开价格计算的估值，而不是服务商账单事实。因此，“SDK 金额一定由自定义 Provider 服务端自行上报”目前没有代码证据支持；更准确的产品表述应是：该金额来源及计价口径无法由 Cindy 验证，不能默认作为可对账的实际支出。

#2855 提供了真实偏差案例：同一任务、同一时段中，服务商后台约为 $4.8821，Cindy 显示约 ¥115.97。按当前固定换算口径反推，差异在换算前已经存在，不能仅归因于币种符号或汇率。

2. #2878 的默认隐藏方向合理，但当前开关混合了两种语义

PR 新增 TurnPricingContext.suppressSdkCost，并在自定义 Provider 默认关闭费用时返回：

{ model, money: null, source: 'sdk' }

同时，窄化 fallback 路径直接改走 usage-only 记录。这样能让现有 MessageActionBar 的 Token fallback 接管展示，确实可以阻止新的 SDK 金额进入消息、会话和每日支出。

问题在于设置名称表达的是“是否显示”，实际却同时决定“是否记入真实支出账本”：

• 关闭时：金额不展示，也不记账；
• 开启时：继续沿用旧链路，将未经验证的 SDK 金额作为 actual-cost 写入账本。

风险提示只能告知用户数字可能不准，不能使这笔数据成为真实支出。展示偏好与账本可信度应分开处理：未经验证的金额即使用户选择查看，也应是 value-estimate，不能重新进入 actual spend。

3. 当前抑制位置会影响已有“API 价格估算”能力

主干已经支持按 (provider instance, runtime, model id) 保存用户价格覆盖；provider-reference 和 user-override 会生成 value-estimate，并由 resolveClaudeTurnCostSinks() 与真实支出分流。这是用户主动表达的估价意图，不应等同于不可信的 SDK 金额。

#2878 的普通 Provider 路径在 SDK 金额判断和 Provider 参考价 fallback 之前直接返回 money: null。因此默认关闭后，不仅隐藏 SDK 金额，也会阻止用户覆盖价或 Provider 参考价参与估算。建议改成如下优先级：

1. 用户主动配置价：按 Token 计算，标记 value-estimate；
2. 可靠的 Provider 参考价：按 Token 计算，标记 value-estimate；
3. SDK costUSD：默认不展示；用户主动开启时也只作为明确标注的估算值；
4. 都不可用：金额为 null，展示 Token。

另外，当前 DeepSeek 参考价特例位于 suppressSdkCost 判断之前。如果用户自定义来源能够保留 providerId === 'deepseek'，该分支仍可能返回参考估价，与“所有自定义 Provider 默认仅 Token”的宣称不完全一致。应调整判断顺序，或增加覆盖该可达来源形态的测试。

4. Token 展示能力已经存在，无需新增另一套展示模型

apps/desktop/src/renderer/components/chat/MessageActionBar.tsx 已实现：金额缺席且 turnUsageDetails.totalTokens > 0 时，显示紧凑 Token 总量，并在 tooltip 中展示输入、输出和缓存明细。

该能力来自已合并的 #1211，Desktop 和 Mobile 均采用“金额优先、无金额则 Token”的统一口径。因此本问题缺少的不是 Token UI，而是让不可信金额正确退出实际支出链路。

建议的实现边界

• 在路由上下文中继续使用明确的“用户自定义 Provider”事实，不按模型名前缀猜测。
• 将“SDK 金额可信度”与“用户是否希望查看估值”拆开：
  • 可确认的服务端 billed amount 才能成为 actual-cost；
  • 无法确认来源的 SDK 金额只能成为 value-estimate，并携带 reference-price 或新的明确原因；
  • 默认关闭仅影响该估值的展示，不影响 Token 记录。
• 保留用户价格覆盖入口及其现有估算语义。
• 不追溯修改历史消息或历史账本，除非另行定义迁移策略；但应明确升级后旧金额仍可能保留，避免把本 PR 描述成历史数据已被修正。
• 设置若是设备级而非账号级，应在产品说明中明确；若预期各账号独立，则需改为 owner-scoped 存储。

验证建议

至少增加以下回归：

1. 自定义 Provider 上报正数 SDK costUSD、无用户估价：默认仅记录和展示 Token，不写 actual spend。
2. 同场景开启“显示 SDK 估算”：显示明确的估算标识，但仍不写 actual session/daily spend。
3. 自定义 Provider 有用户价格覆盖：按输入、输出、cache Token 计算并标为 value-estimate。
4. 自定义 Provider 只有 Provider 参考价：同样保持估算语义，不进入实际支出。
5. 自定义 DeepSeek 来源：确认不会因特例顺序绕过最终产品策略。
6. Cindy AI Gateway 的可信结算价继续保持 actual-cost。
7. Desktop 实机检查设置持久化、Light/Dark、消息 ActionBar、会话累计和今日支出；使用 mock 自定义聚合服务构造“SDK 估值与账单不同”的端到端案例。
8. Mobile/device-link 确认仍能消费 Desktop 产生的 usage-only 消息，不显示被抑制的金额。

#2878 已报告 related unit tests、Desktop typecheck、DCO 和 i18n 检查通过；但尚未执行 Desktop 运行时 UI、真实自定义 Provider 或账单对比，因此目前不足以验证上述产品口径在完整链路中成立。

相关记录

• 自定义模型服务的费用估算与实际计费不一致，建议仅统计 Token #2855：本 PR 的直接问题来源，提供了自定义模型服务中 Cindy 金额与服务商后台明显不一致的真实案例。
• feat(models): consume unified remote model catalog #1174：已确立 Provider 参考价和用户本地价格覆盖只进入 value-estimate，不得写入真实 daily/session spend；这是本次费用可信度处理应继续遵守的边界。
• feat(desktop,mobile): 算不出模型报价时消息底部回退显示本轮 token #1211：已合并无金额时 Desktop/Mobile 显示本轮 Token 的降级能力，可直接承接默认隐藏后的展示。
• fix(desktop): 稳定账本币种并停止用量记账丢数据 #1302：已修复账本币种推断与累计丢失，并要求推断币种显式标为估算；它没有解决自定义 Provider SDK 金额本身的可信度问题。

[A1aZ]

#2884 中提出的四项要求现已全部按“估值与真实账本隔离”的方向落地，PR 头提交为 7af9436d9：

1. 自定义 Provider 的 SDK costUSD 不再写入 actual-cost、session spend 或 daily spend；默认只显示 Token。
2. 用户价格覆盖和 Provider 参考价继续作为独立 value-estimate 保留，不受“隐藏 SDK 估算”开关影响；Gateway 等可信结算路径保持真实费用语义。
3. 开关已定义为「显示 SDK 估算」，默认关闭；文案明确“不是供应商账单”。即使开启，SDK 金额也仅参与估值展示。设置使用 default + override，并提供「已自定义 / 恢复默认」，reset 会删除 override。
4. 已覆盖 Desktop 消息、用户轮累计、会话累计、今日支出、历史投影、Scheduler、Mobile/device-link 与 Token fallback。最新两条 P1 也已修复：Mobile /cost 以结构化 totalMoney 保留 CNY，Desktop 混合实际费用 + SDK 估算不再把整笔合计标成 SDK 估算。

验证结果：仓库 pnpm test:unit:related 的 8 个相关 workspace 全部通过；Desktop、Mobile 与 maker-shared 定向回归通过；Desktop / Mobile typecheck、i18n、术语表、DCO、diff 检查及最新 Linux / Windows PR CI 全部通过。Light / Dark × 默认关闭 / 手动开启四态运行时截图也已完成脱敏复核，正在补到 PR。

供应商最终账单仍不宣称可由 Cindy 验证；测试通过注入 SDK 估值、Token、用户价格、Provider 参考价及混合历史费用来锁定账本语义，且未使用或提交任何供应商凭证。

请维护者基于当前提交重新确认产品默认值；若认可该方向，请在 #2878 Approve 以放行产品门。