在 Convex 应用需要预览成本时：用 insights…

在 Convex 应用需要评估/预览部署开支、找出读放大成本驱动并避免付费操作意外扣费时使用。

适用场景

解决思路

1. 执行 GUARD：先跑 deploy-guard；本次成本读取对 dev/prod 只读（insights 仅 cloud+user-auth 可用，不支持 previews）；明确宣告要读取的 deployment。
2. 通过官方 MCP 收集开支证据：用 `insights` 获取 bytes-read / documents-read 事件（直接成本信号，Convex 按 function calls + bandwidth 计费）；用 `tables` 获取行数（表大小限定扫描成本上限）；用 `functionSpec` 获取函数面；若尚无 usage/traffic，明确说明并改从 query SHAPES 估算（例如对预计会增长的表做 `.collect()`，即使今天零流量也是未来成本）。
3. 归因：按每个函数的 bytes/documents read per call × 观测到（或被询问）的 call volume 排序函数；成本驱动是两者乘积而非任何单项；同时展示这两个因子，因为每次调用便宜但高频的函数可能超过昂贵但罕见的函数。
4. 预测增长：说明排名靠前的驱动如何随流量/数据增长；全表 `.collect()` 随表线性增长（成本随数据积累复利），带索引的 `.take(n)` 保持平坦；给用户增长曲线形状（如“每次调用是 O(table size)——1k 行没事，1M 行就是账单”），不要给虚假精确的美元数字。
5. 为每个成本驱动给出最便宜修复：用索引 + `.withIndex` 替代 scan；用 `.paginate`/`.take` 替代 `.collect`；计数用 aggregate component；缓存热读；并在 bus 上发出 cost-class finding（证据：insight event + 预测增长），指向 convex-expert/convex-advisor 去做实际修改。
6. 对付费操作执行 CONFIRM-COST：如果流程包含任何计量/付费项（购买域名、云资源开通、套餐变更），在继续前明确说明价格与计费周期，并获得显式 yes；绝不让付费操作作为副作用发生（cost-confirm gate）。
7. 报告：列出当前成本驱动排名，每个都带证据 + 增长形状 + 修复，并给一句直白底线（如“你的开支由 messages:list 每次调用读整表主导；加索引后约降 100x”）；保持诚实精度：Convex 定价会变且取决于 plan，给相对/形状指导，绝对数字引用 pricing page，不要自创美元总额。
8. 始终按 成本 = data-read-per-call × call-volume 计算，并同时展示两个因子；高频便宜函数可能比低频昂贵函数更贵。
9. 读取 deployment 自身的 insights/bytes-read 证据来估算开支；尚无流量时，按 query SHAPES 定价（在增长表上的 scan 是未来成本）。
10. 给增长 CURVE，不给虚假精确美元：O(table) scan 会随数据积累复利增长；索引访问保持平坦；绝对数字引用 pricing page。
11. 每个成本驱动都要写出其最便宜修复，并在 bus 上发出 cost-class finding，指向修复方（convex-expert/advisor）。
12. 任何 metered/paid 操作都要 confirm-cost：说明价格 + 计费周期，在操作发生前获得显式 yes；绝不能作为副作用发生。
13. 对 dev/prod 只读（deploy-guard）；insights 仅 cloud+user-auth 可用；成本分析复用 convex-advisor 的证据，但要从金钱而非延迟角度表述。

适用边界 · 注意事项

• 不适用于非 Convex 部署，或未接入官方 MCP、无法读取 insights 的场景。
• 没有 traffic/usage 时不能做真实用量归因，只能按 query SHAPES 估算；insights 不支持 previews，previews 环境不适用。
• 不要用虚假精确的美元总额；Convex 定价随 plan 变化，绝对金额必须引用 pricing page，且任何计量/付费操作未获得显式 yes 前不要执行。