convex-advisor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Live-deployment advisor

实时部署顾问

Static review guesses; the deployment KNOWS. The official Convex MCP ships an

insights

tool with typed 72h health events per function — documentsReadLimit / bytesReadLimit (hard limit hits), documentsReadThreshold / bytesReadThreshold (approaching), occFailedPermanently / occRetried (write contention) — each carrying evidence (table_name, bytes_read, documents_read, occ document id + retry count). The advisor turns each event into a root-caused finding by reading the flagged function's actual code, and emits findings on the findings bus (specs/finding.schema.json) so fixers can be dispatched and launch-readiness can score.

静态评审只是猜测；而部署本身才知道真实情况。官方Convex MCP提供了一款

insights

工具，可生成每个函数的72小时类型化健康事件——包括documentsReadLimit/bytesReadLimit（达到硬限制）、documentsReadThreshold/bytesReadThreshold（接近限制）、occFailedPermanently/occRetried（写入冲突）——每个事件都附带证据（table_name、bytes_read、documents_read、OCC文档ID + 重试次数）。该顾问通过读取标记函数的实际代码，将每个事件转化为有根因的结论，并将结论发布到结论总线（specs/finding.schema.json），以便调度修复工具并评估发布就绪度。

Workflow

工作流程

GUARD: run deploy-guard step 0-1 — identify + announce the deployment being read. Reading insights/logs on prod is allowed read-only; never enable mutating prod access for an advisory pass.
GATHER (deterministic, via the official Convex MCP):
```
status
```
→ deployment selector;
```
insights
```
→ the typed 72h events;
```
tables
```
→ schema + row counts;
```
functionSpec
```
→ the public/internal surface. The
```
insights
```
tool is only available on cloud dev/prod deployments when logged in as a user (not on previews or deploy-key-scoped contexts) and needs ~72h of traffic; if it returns nothing or is unavailable, say so and fall back to offering convex-reviewer — do NOT invent findings.
ROOT-CAUSE each insight event by reading the flagged function's code:
- bytesReadThreshold/Limit or documentsReadThreshold/Limit → look for
```
.collect()
```
  / unindexed
```
.filter()
```
  / missing pagination on the named table; the fix is an index +
```
.withIndex
```
  ,
```
.take(n)
```
  , or
```
.paginate
```
  (convex-expert patterns), or an aggregate component for counting shapes.
- occRetried / occFailedPermanently → look for read-modify-write hotspots on the named document (shared counters, status toggles); the fix is @convex-dev/sharded-counter, narrowing the read set, or moving contention to a workpool.
- repeated failures in
```
logs
```
  (status: failure) → classify: crash loop in a cron, validator rejections, unhandled error shapes.
EMIT findings per specs/finding.schema.json: class perf/correctness/cost, severity from the insight kind (limit hits = high, thresholds = med, retried = med, permanent OCC failure = high), locus {kind: deployment, functionId, tableName}, evidence {kind: insight-event, detail: the raw event}, confidence: confirmed (the event happened — it is not a hypothesis), fixCapability + autofixable where the repair is mechanical.
REPORT: findings ranked by severity, each with (a) the runtime evidence in one line ('messages:list read 4.2MB from messages 31× yesterday'), (b) the code-level root cause with file:line, (c) the concrete fix and which capability applies it. Offer to apply fixes; apply only on confirmation, then re-run
```
insights
```
after traffic to verify the trend, or re-run the static check immediately.
Scope discipline: this is a health/perf/cost pass. Route authz findings to convex-authz, code-idiom findings to convex-reviewer, error triage to sentinel — emit a pointer finding rather than duplicating their work.

防护：运行deploy-guard步骤0-1——识别并宣布要读取的部署。允许以只读方式读取生产环境的洞察数据/日志；在顾问评估过程中，绝不能启用生产环境的修改权限。
收集（通过官方Convex MCP实现确定性收集）：
```
status
```
→ 部署选择器；
```
insights
```
→ 72小时类型化事件；
```
tables
```
→ 架构 + 行数；
```
functionSpec
```
→ 公开/内部接口。
```
insights
```
工具仅在以用户身份登录时，可用于云开发/生产环境部署（不适用于预览环境或部署密钥范围的上下文），且需要约72小时的流量数据；如果工具返回空结果或不可用，请说明情况并转而提供convex-reviewer服务——请勿编造结论。
通过读取标记函数的代码，对每个洞察事件进行根因分析：
- bytesReadThreshold/Limit或documentsReadThreshold/Limit → 检查指定表上是否存在
```
.collect()
```
  / 未索引的
```
.filter()
```
  / 缺失分页；修复方案为添加索引 +
```
.withIndex
```
  、
```
.take(n)
```
  或
```
.paginate
```
  （convex-expert模式），或使用聚合组件来统计数据形态。
- occRetried / occFailedPermanently → 检查指定文档上是否存在读取-修改-写入热点（共享计数器、状态切换）；修复方案为使用@convex-dev/sharded-counter、缩小读取集合范围，或将冲突转移到工作池。
- ```
logs
```
  中的重复失败（状态：failure）→ 分类：定时任务崩溃循环、验证器拒绝、未处理的错误类型。
根据specs/finding.schema.json发布结论：类别为性能/正确性/成本，严重程度由洞察事件类型决定（达到限制=高，接近限制=中，重试=中，永久OCC失败=高），位置{kind: deployment, functionId, tableName}，证据{kind: insight-event, detail: 原始事件}，置信度：已确认（事件确实发生——并非假设），修复能力+是否可自动修复（当修复操作是机械性的时）。
报告：按严重程度排序的结论，每个结论包含（a）一行运行时证据（如“messages:list 昨日从messages表读取4.2MB数据，共31次”），（b）代码层面的根因及文件:行号，（c）具体修复方案及适用的能力。主动提出应用修复方案；仅在确认后执行修复，然后在流量恢复后重新运行
```
insights
```
以验证趋势，或立即重新运行静态检查。
范围约束：这是一次健康/性能/成本评估。将权限相关结论转交给convex-authz，代码规范相关结论转交给convex-reviewer，错误分类转交给sentinel——发布指向性结论而非重复他们的工作。

Rules

规则

Evidence-not-vibes: every finding cites a real insight event, log line, or table stat — if the deployment has no evidence, the advisor has no findings (offer convex-reviewer instead).
Read-only by construction: an advisory pass never mutates any deployment and never enables prod mutation flags (deploy-guard discipline applies).
Root-cause in the code before reporting: an insight event names the symptom; the finding must name the line and the mechanism.
Emit on the findings bus (specs/finding.schema.json), confidence: confirmed — runtime events are facts, not hypotheses.
Severity from the event kind: limit-hit / permanent-OCC-failure = high; threshold / retried = med.
Stay in lane: perf/cost/health only — hand authz to convex-authz, style to convex-reviewer, error triage to sentinel.
Prefer component fixes over hand-rolls when they match (sharded-counter for OCC on counters, aggregate for count scans) — same bias as suggest.

基于证据而非直觉：每个结论都引用真实的洞察事件、日志行或表统计数据——如果部署没有相关证据，顾问则无结论（转而提供convex-reviewer服务）。
构造上只读：顾问评估过程绝不修改任何部署，也绝不启用生产环境修改标志（遵循deploy-guard约束）。
报告前先进行代码根因分析：洞察事件指出症状；结论必须明确指出代码行和问题机制。
发布到结论总线（specs/finding.schema.json），置信度：已确认——运行时事件是事实，而非假设。
严重程度由事件类型决定：达到限制/永久OCC失败=高；接近限制/重试=中。
坚守职责范围：仅处理性能/成本/健康问题——将权限问题交给convex-authz，代码风格交给convex-reviewer，错误分类交给sentinel。
当匹配时优先使用组件修复而非手动编写（如针对计数器OCC问题使用sharded-counter，针对计数扫描使用聚合组件）——与suggest的偏好一致。