Convex 云部署出现 72h insights…

读取 Convex deployment 的 72 小时健康事件，逐条在代码中定位根因，并按 findings bus 输出可派发修复的性能/成本/健康发现。

适用场景

解决思路

1. GUARD：执行 deploy-guard 步骤 0-1，识别并宣告本次要读取的 deployment。对 prod 读取 insights/logs 允许只读；advisory pass 绝不启用 prod 变更访问。
2. GATHER（通过官方 Convex MCP 确定性获取）：先调用 `status` 获取 deployment selector；调用 `insights` 获取类型化 72h 事件；调用 `tables` 获取 schema 与行数；调用 `functionSpec` 获取 public/internal 表面。`insights` 仅在以用户身份登录的 cloud dev/prod deployment 上可用（preview 或 deploy-key 作用域上下文不可用），且需要约 72h 流量；若返回空或不可用，明确说明并降级为建议 convex-reviewer，不要编造 findings。
3. ROOT-CAUSE：针对每个 insight 事件，阅读被标记函数的实际代码定位根因。
4. 对 bytesReadThreshold/Limit 或 documentsReadThreshold/Limit：在命名的 table 上查找 `.collect()` / 未加索引的 `.filter()` / 缺少分页；修复方式是加 index + `.withIndex`、`.take(n)` 或 `.paginate`（convex-expert 模式），或对 counting 形状使用 aggregate component。
5. 对 occRetried / occFailedPermanently：在命名 document 上查找 read-modify-write 热点（如共享 counters、status toggles）；修复方式是 @convex-dev/sharded-counter、缩小 read set，或把 contention 移到 workpool。
6. 对 `logs` 中重复失败（status: failure）：分类为 cron 中的 crash loop、validator rejections、未处理错误形状。
7. EMIT findings：按 specs/finding.schema.json 输出；class 为 perf/correctness/cost；severity 由 insight kind 决定（limit hits = high，thresholds = med，retried = med，permanent OCC failure = high）；locus 为 {kind: deployment, functionId, tableName}；evidence 为 {kind: insight-event, detail: 原始事件}；confidence: confirmed（事件已发生，不是 hypothesis）；在修复是机械性时给出 fixCapability + autofixable。
8. REPORT：按 severity 排序 findings，每条包含：(a) 一行 runtime evidence（例如 'messages:list read 4.2MB from messages 31× yesterday'），(b) 带 file:line 的代码级根因，(c) 具体修复及适用哪个 capability。主动提出可应用修复；仅在确认后应用，然后等有流量后重新运行 `insights` 验证趋势，或立即重新运行静态检查。
9. Scope discipline：这是健康/性能/成本检查。authz findings 转给 convex-authz，code-idiom findings 转给 convex-reviewer，error triage 转给 sentinel——只发出 pointer finding，不重复它们的工作。
10. Evidence-not-vibes：每个 finding 必须引用真实 insight 事件、log 行或 table 统计；如果 deployment 没有证据，advisor 就没有 findings（改为提供 convex-reviewer）。
11. Read-only by construction：advisory pass 绝不修改任何 deployment，也绝不启用 prod mutation flags（适用 deploy-guard 纪律）。
12. Root-cause in the code before reporting：insight 事件只说明症状；finding 必须指出代码行和机制。
13. Emit on findings bus（specs/finding.schema.json），confidence: confirmed——runtime events 是事实，不是假设。
14. Severity 来自事件类型：limit-hit / permanent-OCC-failure = high；threshold / retried = med。
15. Stay in lane：只处理 perf/cost/health——authz 交给 convex-authz，style 交给 convex-reviewer，error triage 交给 sentinel。
16. 优先使用 component 修复而非手写，当匹配时（counters 上的 OCC 用 sharded-counter，count scans 用 aggregate）——与 suggest 相同偏好。

适用边界 · 注意事项

• 部署是 preview 或使用 deploy-key 作用域，或流量不足约 72h：`insights` 不可用/无返回，不要用本技能硬查；应说明并改走 convex-reviewer。
• 目标不是性能/成本/健康，而是 authz、代码风格/idiom 或错误分诊：不要越界，分别转给 convex-authz、convex-reviewer、sentinel。
• 需要直接变更生产环境或未获得确认就想应用修复：不要执行；advisory pass 只读，修复只能在确认后应用。