convex-advisor

实时部署顾问

静态审查只能猜测；部署本身最清楚。官方 Convex MCP 提供 insights 工具，其中包含按函数分类的 72h 健康事件——documentsReadLimit / bytesReadLimit（触及硬性限制）、documentsReadThreshold / bytesReadThreshold（即将触及限制）、occFailedPermanently / occRetried（写入冲突）——每个事件都附带证据（table_name、bytes_read、documents_read、OCC 文档 id + 重试次数）。顾问会读取被标记函数的实际代码，为每个事件找出根因并生成发现，然后将发现发送到 findings bus（specs/finding.schema.json），以便派发修复工具并评估上线准备情况。

工作流

1. GUARD：运行 deploy-guard 第 0-1 步——识别并声明正在读取的部署。在 prod 上读取 insights/logs 属于只读操作，允许执行；顾问审查期间绝不要启用对 prod 的写入访问。
2. GATHER（通过官方 Convex MCP 以确定性方式执行）：status → 部署选择器；insights → 类型化的 72h 事件；tables → schema + 行数；functionSpec → 公共/内部接口。只有以用户身份登录时，insights 工具才可用于 cloud dev/prod 部署（不适用于预览或受 deploy key 限制的上下文），且需要约 72h 的流量；如果没有返回内容或工具不可用，请如实说明，并改为提供 convex-reviewer——不要编造发现。
3. 读取被标记函数的代码，为每个 insight 事件分析根因：
   • bytesReadThreshold/Limit 或 documentsReadThreshold/Limit → 检查指定表上的 .collect() / 未使用索引的 .filter() / 缺少分页；修复方法是使用索引 + .withIndex、.take(n) 或 .paginate（convex-expert 模式），或者使用 aggregate 组件处理计数场景。
   • occRetried / occFailedPermanently → 检查指定文档上的读-改-写热点（共享计数器、状态切换）；修复方法是使用 @convex-dev/sharded-counter、缩小读取集，或将争用转移到 workpool。
   • logs 中反复出现的失败（status: failure）→ 分类：cron 崩溃循环、验证器拒绝、未处理的错误形态。
4. 按 specs/finding.schema.json 生成发现：类别为 perf/correctness/cost；根据 insight 类型确定严重程度（触及限制 = 高、达到阈值 = 中、发生重试 = 中、OCC 永久失败 = 高）；locus {kind: deployment, functionId, tableName}；evidence {kind: insight-event, detail: 原始事件}；confidence: confirmed（事件确实发生，并非假设）；如果修复属于机械操作，则填写 fixCapability + autofixable。
5. REPORT：按严重程度排列发现，每条发现包括 (a) 一行运行时证据（“messages:list 昨天从 messages 读取了 4.2MB，共 31 次”）；(b) 带 file:line 的代码级根因；(c) 具体修复方案及适用的能力。主动提出应用修复；仅在得到确认后才应用，然后在产生流量后重新运行 insights 以验证趋势，或者立即重新运行静态检查。
6. 严格控制范围：本次审查仅涉及健康状况/性能/成本。将授权发现转给 convex-authz，将代码惯用法发现转给 convex-reviewer，将错误分流转给 sentinel——发送指向相应能力的发现，而不是重复它们的工作。

规则

• 以证据为准，而非凭感觉：每条发现都要引用真实的洞察事件、日志行或表格统计数据——如果部署没有证据，顾问就不应给出任何发现（改用 convex-reviewer）。
• 从设计上确保只读：建议过程绝不修改任何部署，也绝不启用生产环境修改标志（遵循 deploy-guard 的规范）。
• 报告前先在代码中找到根因：洞察事件会指出症状；发现必须指出代码行和作用机制。
• 通过发现总线发送（specs/finding.schema.json），置信度：confirmed——运行时事件是事实，而非假设。
• 根据事件类型确定严重程度：limit-hit / permanent-OCC-failure = 高；threshold / retried = 中。
• 各司其职：仅处理性能、成本和健康状况——授权问题交给 convex-authz，风格问题交给 convex-reviewer，错误分诊交给 sentinel。
• 匹配时优先选择组件修复，而非手工实现（计数器上的 OCC 问题使用 sharded-counter，计数扫描使用 aggregate）——与 suggest 的倾向一致。