用官方 Convex MCP 以自然语言排查运行中…

当需要排查 Convex 部署的失败、慢/贵函数或部署因果时，以只读方式查询日志和健康指标，并给出可一键验证的证据。

适用场景

解决思路

1. GUARD：执行 deploy-guard step 0-1——识别并声明当前读取的是哪个 deployment。读取日志/insights 是只读操作；做 insights 检查时绝不要开启 prod mutation flags。
2. 查询前先 DISCOVER，绝不猜标识符：用 functionSpec 列出真实函数名，用 status 获取 deployment/version。提前记下工具限制：logs 只接受 --history <n>（一个 COUNT，不是时间窗口）、--success、--jsonl、--prod、--deployment——没有服务端 status/function/requestId/time 过滤；insights 没有 function 过滤，且仅限 cloud dev/prod + user-auth。因此要拉取最近窗口，并在 CLIENT-SIDE 过滤。
3. 从三种视图中选择一种并拉取原始窗口，然后在本地过滤：failures view → 执行 logs --history <n> --jsonl，再本地保留 failures + 按 function + error message 分组，返回 counts + 每组第一条 stack。回答“什么在报错”“部署后什么失败了”。
4. health view → 使用 insights（仅 cloud）：查看类型化的 72h read-limit / OCC events。展示并排序它们，但把 perf/cost 根因分析和修复交给 convex-advisor——这些只作为 pointer findings 发出，不要在这里承担性能修复表述。
5. trace view → 执行 logs --history <n> --jsonl，再本地过滤到某一个 requestId/function 以读取完整执行过程。回答“为什么这次调用失败”。
6. SCOPE：通过拉取一个有限的最近窗口（合理的 --history count）并在 client-side 过滤到所问的 function/status/requestId 来限定范围；当窗口很大时，聚合（按 function/message 计数）而不是倾倒日志行。
7. ANSWER：回答包含 (a) 一行结论，(b) 证据（counts + 一条代表性 stack/log line），以及 (c) 尽可能提供由 agent 构造的 dashboard deep link（dashboard.convex.dev，该 deployment 的 Logs/Functions 视图）供人工验证——没有工具会返回该链接，所以从 deployment name + function 构造它；绝不要把原始日志倾倒作为答案。
8. 当被问“是不是我的部署弄坏了这个”时，CROSS-CHECK deploy causality：用日志时间戳得出 failure onset，并与 status 中的 deployment version 对比；做关联，不要直接断言。
9. HAND OFF，不要在这里修复：perf/cost 原因 → convex-advisor（由它负责这些修复）；代码缺陷 → convex-reviewer/convex-authz；需要持续反应的实时错误 → monitor/sentinel。把 findings 发到 bus（specs/finding.schema.json）——主要是 observability，perf/cost 作为 pointer findings 给 advisor——以便 composite pass 能接住它们。
10. 在过滤前先发现真实 function/field 名称（functionSpec/status）——绝不猜标识符，绝不要因为应用没有某个名称而返回令人困惑的空结果。
11. logs 和 insights 没有服务端 status/function/requestId/time-window 过滤（logs 只接受 --history COUNT；insights 仅 cloud）——拉取一个有界的最近窗口并在 CLIENT-SIDE 过滤；要说明这一点，而不是暗示存在不存在的参数。
12. 每个问题只选三种视图之一（failures / health / trace）——不要发散成许多推测性的工具调用。
13. 没有工具会返回 dashboard link——尽可能从 deployment name + function 构造它供人工验证；绝不要用原始日志倾倒作为回答。
14. 始终只读：insights 检查不运行任何 mutation，也绝不开启 prod mutation flags（deploy-guard 纪律）。
15. 保持读者角色，并把 perf/cost 修复交给 convex-advisor：主要发出 observability，把 perf/cost 作为 POINTER findings 路由出去，让 advisor 唯一负责性能修复表述；前瞻性反应交给 monitor/sentinel。

适用边界 · 注意事项

• 不适用于修复性能/成本根因、修复代码缺陷或持续监控；这些应交接给对应角色。
• 不适用于需要修改或生产写操作的场景；insights 检查必须只读，不能开启 prod mutation flags。
• 不适用于非 Convex 部署或未接入官方 Convex MCP 的环境。