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 document id 和 retry count）。顾问通过读取被标记函数的实际代码，将每个事件转化为有根因的 finding，然后通过 findings 总线（specs/finding.schema.json）发出，以便调度 fixer 并对 launch-readiness 进行评分。

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.

GUARD：运行 deploy-guard 的步骤 0-1——识别并声明正在读取的部署。允许只读访问生产环境中的 insights/logs；顾问流程绝不能开启可变更生产环境的访问权限。
GATHER（通过官方 Convex MCP 确定性收集）：
```
status
```
→ 部署选择器；
```
insights
```
→ 带强类型的 72 小时事件；
```
tables
```
→ schema 和行数；
```
functionSpec
```
→ public/internal 接口。仅当用户已登录时，
```
insights
```
工具才可用于 cloud dev/prod 部署（不可用于 previews 或 deploy key 限定的上下文），并且需要约 72 小时的流量；如果工具没有返回结果或不可用，应明确说明并改为推荐 convex-reviewer——不要虚构 findings。
通过读取被标记函数的代码，对每个 insight 事件进行根因分析：
- bytesReadThreshold/Limit 或 documentsReadThreshold/Limit → 查找指定表上的
```
.collect()
```
  、未建立索引的
```
.filter()
```
  或缺失的分页；修复方式是添加索引并使用
```
.withIndex
```
  、
```
.take(n)
```
  或
```
.paginate
```
  （遵循 convex-expert 模式），或者使用 aggregate 组件进行计数。
- occRetried / occFailedPermanently → 查找指定 document 上的读-改-写热点（共享计数器、状态切换）；修复方式是使用 @convex-dev/sharded-counter、缩小读取集合，或者将争用转移至 workpool。
- logs 中反复出现的失败（status: failure）→ 分类为 cron 中的崩溃循环、validator 拒绝或未处理的错误形态。
按照 specs/finding.schema.json 输出 findings：class 为 perf/correctness/cost，severity 根据 insight 类型确定（触发限制 = high，接近限制 = med，重试 = med，永久 OCC 失败 = high），locus 为 {kind: deployment, functionId, tableName}，evidence 为 {kind: insight-event, detail: raw event}，confidence 为 confirmed（事件确实发生，并非假设）；如果修复可以机械执行，则填写 fixCapability 和 autofixable。
REPORT：按严重程度对 findings 排名，每个 finding 都应包含：(a) 单行运行时证据（例如 'messages:list read 4.2MB from messages 31× yesterday'），(b) 带有 file:line 的代码级根因，(c) 具体修复方案以及可以应用该修复的 capability。可以主动提出应用修复；只有在获得确认后才能应用，然后在产生流量后重新运行
```
insights
```
以验证趋势，或者立即重新运行静态检查。
严格限定范围：这是一次健康/性能/成本检查。将 authz findings 转交给 convex-authz，将代码惯用法问题转交给 convex-reviewer，将错误分类转交给 sentinel——仅发出指向性 finding，不要重复它们的工作。

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.

Evidence-not-vibes：每个 finding 都必须引用真实的 insight 事件、日志行或表统计信息——如果部署没有任何证据，顾问就没有 findings（改为推荐 convex-reviewer）。
Read-only by construction：顾问流程绝不修改任何部署，也绝不开启生产环境变更标志（遵循 deploy-guard 规范）。
报告前必须在代码中定位根因：insight 事件只说明症状；finding 必须指出具体代码行和作用机制。
通过 findings 总线输出结果（specs/finding.schema.json），confidence 为 confirmed——运行时事件是事实，而不是假设。
根据事件类型确定严重程度：触发限制/永久 OCC 失败 = high；接近限制/已重试 = med。
Stay in lane：仅处理性能/成本/健康问题——将 authz 转交给 convex-authz，将代码风格问题转交给 convex-reviewer，将错误分类转交给 sentinel。
匹配时优先使用组件修复，而不是手动实现（计数器 OCC 使用 sharded-counter，计数扫描使用 aggregate）——与 suggest 保持相同的偏好。