用途
该技能用于诊断和修复 Convex 应用中的性能问题，一次处理一个具体的问题类别。它面向慢功能、insights 发现、OCC 冲突或读放大等场景。
何时使用
- 某个 Convex 页面或功能感觉缓慢或开销大
npx convex insights --details报告高读取字节数、文档读取量或 OCC 冲突- 低新鲜度的读取路径本可使用时间点读取，却仍在使用响应式查询
- 出现 OCC 冲突错误或过多的 mutation 重试
- 订阅数量过高或 UI 更新缓慢
- 函数接近执行或事务限制
- 同类性能模式需要在兄弟函数中一并修复
何时不使用
- 初始 Convex 搭建、认证设置或组件抽取
- 没有性能目标的纯模式迁移
- 没有用户可见或部署可见问题的一次性微优化
护栏
- 在规模小、流量适中或可用信号较弱时，优先选择更简单的代码
- 除非有实测信号、明显无界路径或已知热点读写路径，否则不要推荐摘要表、文档拆分、获取策略变更或迁移型改造
- 在 Convex 中，对小表进行简单扫描通常是可以接受的。不要仅仅因为某个模式在大规模下不理想就凭空引入结构性工作
第一步：收集信号
从最强的可用信号开始：
- 如果用户或当前上下文中已有部署 Health insights，将其视为第一手性能信号来源
- 如果 CLI insights 可用，运行
npx convex insights --details。必要时使用--prod、--preview-name或--deployment-name - 如果本地仓库的 Convex CLI 过旧、不支持 insights，先尝试
npx -y convex@latest insights --details再放弃 - 如果仓库已使用
convex-doctor，可以将其发现作为线索。不要强求使用它，也不要将其视为唯一事实来源 - 如果运行时信号不可用，仍可从代码进行审计，但要牢记上述护栏。缺少 insights 不是健康的证明，也不是需要大规模重构的证明
信号路由
收集信号后，识别问题类别并阅读匹配的参考文件。
- 高字节或文档读取、JS 过滤、不必要的 join →
references/hot-path-rules.md - OCC 冲突错误、写入争用、mutation 重试 →
references/occ-conflicts.md - 订阅数量过高、UI 更新缓慢、过多重渲染 →
references/subscription-cost.md - 函数超时、事务大小错误、大型负载 →
references/function-budget.md - 没有具体信号的笼统“很慢” → 从
references/hot-path-rules.md开始
多个问题类别可能重叠。先阅读最相关的参考文件，若症状仍存在再检查其他文件。
升级更大的修复
如果可能的修复是侵入性、跨领域或迁移型的，先停止并在编辑前给出选项。
例如：
- 在多个流程中引入摘要或汇总表
- 拆分文档以隔离频繁更新的字段
- 在多个屏幕中重做分页或获取策略
- 切换到需要迁移安全上线的新索引或反规范化字段
当正确性取决于在上线期间处理新旧状态时，请参考 convex-migration-helper 技能获取迁移工作流。
工作流
1. 界定问题范围
从实际项目中选择一个具体的用户流程。查看代码库、客户端页面和 API 表面，找到与症状匹配的流程。
记录：
- 入口函数
- 使用
useQuery、usePaginatedQuery或useMutation的客户端调用点 - 读取的表
- 写入的表
- 该路径是高读、高写还是两者兼有
2. 追踪完整的读写集合
对于路径中的每个函数：
- 追踪每个
ctx.db.get()和ctx.db.query() - 追踪每个
ctx.db.patch()、ctx.db.replace()和ctx.db.insert() - 注意外键查找、JS 端过滤和全文档读取
- 识别所有触及同一张表的兄弟函数
- 识别同一页面上渲染的响应式统计、聚合或组件
在 Convex 中，每一次多余的读取都会增加事务工作量，每一次写入都可能使响应式订阅者失效。将读放大和失效放大视为头等问题。
3. 应用相关参考中的修复
阅读与问题类别匹配的参考文件。每个参考都包含具体模式、代码示例和推荐的修复顺序。
不要只停留在 insight 指出的单个函数上。追踪触及同一张表的兄弟读取者和写入者。
4. 一起修复兄弟函数
当一个触及某张表的函数存在性能缺陷时，审计兄弟函数是否有相同模式。
发现一个问题后，检查同一表族的兄弟读取者和兄弟写入者，包括配套的摘要或汇总表。
例如：
- 如果一个列表查询从全文档切换到摘要表，检查该表的其他列表查询
- 如果一个 mutation 隔离了频繁更新的字段或拆分了热文档，检查同一张表的其他写入者
- 如果一条读取路径需要对未回填字段进行迁移安全上线，检查兄弟读取是否有同样的上线风险
除非有明确的产品理由，否则不要让一条路径已修复而另一条路径仍沿用旧模式。
5. 完成前验证
确认以下所有内容：
- 结果与之前相同，没有丢失记录
- 消除的读取或写入已不在预期路径中
- 当反规范化或索引字段缺失时，回退行为正常工作
- 在需要的地方，频繁更新的字段已与广泛读取的文档隔离
- 每个相关的兄弟读取者和写入者都已检查，而不仅仅是原始函数
参考文件
references/hot-path-rules.md— 读放大、失效、反规范化、索引、摘要表references/occ-conflicts.md— 写入争用、OCC 解决、热文档拆分references/subscription-cost.md— 响应式查询成本、订阅粒度、时间点读取references/function-budget.md— 执行限制、事务大小、大型文档、负载大小
另请查看官方 Convex Best Practices 页面，了解参数验证、访问控制和代码组织等其他模式，这些可能在审计过程中出现。
清单
- 从 insights、仪表板或代码审计中收集了信号
- 识别了问题类别并阅读了匹配的参考文件
- 界定了一个具体的用户流程或函数路径
- 追踪了该路径中的每一次读取和写入
- 识别了触及同一张表的兄弟函数
- 按照推荐的修复顺序应用了参考中的修复
- 一致地修复了兄弟函数
- 验证了行为并确认没有回归