用途
convex-insights 用于以自然语言查询一个正在运行的 Convex 应用的日志与健康状态，回答诸如“什么在报错”“部署后有什么失败了”“为什么这一次调用失败”等运维问题。它不修改任何生产数据，是一次纯读取的观测过程。
工作流程
GUARD：deploy-guard 第 0-1 步，先识别并声明正在读取的是哪个 deployment。读取日志/insights 是只读操作，绝不会为了一次 insights 查询而启用生产变更标志。
DISCOVER（先发现再查询）：不要猜测标识符。先用 functionSpec 列出该 deployment/版本真实的函数名与状态。同时注意工具本身的限制：logs 只接受 --history <n>（一个计数，而非时间窗口）、--success、--jsonl、--prod、--deployment，没有服务端的状态/函数/requestId/时间过滤；insights 没有函数过滤，且仅支持云端 dev/prod 和用户认证。因此需要拉取一个近期窗口，再在客户端侧过滤。
三种视图之一，拉取原始窗口后本地过滤：
- failures 视图 →
logs --history <n> --jsonl，本地保留失败项，按函数与错误消息分组，返回计数与每组的第一条堆栈。回答“什么在报错”“部署后什么失败了”。 - health 视图 → insights（仅云端）：带类型的 72 小时读取限制 / OCC 事件。呈现并排序它们，但性能/成本的根因定位与修复交给 convex-advisor——此处只作为指针发现输出，不在此处承担性能修复的表述框架。
- trace 视图 →
logs --history <n> --jsonl，本地过滤到某一个 requestId/函数以读取完整执行过程。回答“为什么这一次调用失败”。
SCOPE：通过拉取一个有界的近期窗口（合理的 --history 计数），并在客户端过滤到所问的函数/状态/requestId；当窗口较大时做聚合（按函数/消息计数），而不是倾倒日志行。
ANSWER：（a）一句话结论；（b）证据（计数加一条代表性堆栈或日志行）；（c）在可能时，构造一个 agent 生成的仪表盘深链（dashboard.convex.dev，该 deployment 的 Logs/Functions 视图）供人工验证——没有工具会返回该链接，需根据 deployment 名称加函数自行构造；绝不以原始日志倾倒作为答案。
CROSS-CHECK 部署因果：当被问到“是不是我的部署弄坏了这个”时，比较失败起始时间（来自日志时间戳）与来自 status 的部署版本，进行关联而非断言。
HAND OFF（不在本处修复）：性能/成本原因 → convex-advisor（由它负责这些修复）；代码缺陷 → convex-reviewer/convex-authz；需要持续反应的实时错误 → monitor/sentinel。将发现输出到总线（specs/finding.schema.json）——以观测性为主，性能/成本作为指向 advisor 的指针发现——以便组合流程可以接收。
规则
- 过滤前先用 functionSpec/status 发现真实的函数/字段名，绝不猜测标识符，也绝不为应用并不存在的名称返回令人困惑的空结果。
- logs 和 insights 没有服务端的状态/函数/requestId/时间窗口过滤（logs 只接受
--history计数；insights 仅云端）——需拉取有界的近期窗口并在客户端过滤；应如实说明，而非暗示不存在的参数。 - 每个问题只用三种视图之一（failures / health / trace），不要扩散成大量推测性的工具调用。
- 没有工具会返回仪表盘链接——在可能时根据 deployment 名称加函数构造它以供人工验证；绝不以原始日志倾倒作答。
- 始终只读：一次 insights 查询不运行任何变更，也绝不启用生产变更标志（deploy-guard 纪律）。
- 保持读者身份，将性能/成本修复留给 convex-advisor：主要输出观测性发现，把性能/成本作为指针发现路由出去，使 advisor 独有性能修复的表述框架；前瞻性反应交给 monitor/sentinel。
适用场景与限制
适用于需要快速定位 Convex 应用报错、了解读取限制与 OCC 等健康事件、或追踪单次调用失败的运维场景。限制包括：logs 仅支持计数式历史拉取，无服务端过滤；insights 仅限云端。具体收费、价格与更多平台信息暂未提供。