convex-insights

用自然语言查询日志和健康状况

部署已经记录了发生的情况；Agent 只需提出合适的问题。此功能是对官方 Convex MCP 只读工具（logs、insights、functionSpec、status）的严谨封装，可将运维问题转化为范围明确、能返回证据的查询，并提供答案，让人类只需点击一次即可在仪表板中核验。它借鉴了实际应用中表现最佳的可观测性 MCP 模式：先发现字段再查询、只提供三种视图而非十五种工具、输出节省 token，并在每个答案中附上仪表板深层链接。

工作流

1. 防护：deploy-guard 步骤 0-1 —— 确认并说明正在读取哪个部署。读取日志／insights 为只读操作；执行 insights 流程时，绝不要启用生产环境变更标志。
2. 查询前先发现 —— 绝不猜测标识符。使用 functionSpec 列出真实函数名称，并使用 status 查看部署／版本。事先说明工具限制：logs 仅接受 --history <n>（数量，不是时间范围）、--success、--jsonl、--prod、--deployment——没有服务端状态／函数／requestId／时间筛选；insights 不支持函数筛选，且仅适用于云端开发／生产环境和用户身份验证。因此，应获取近期窗口的数据，再在客户端筛选。
3. 选择三种视图之一，获取原始窗口数据，然后在本地筛选：
   • 故障视图 → logs --history <n> --jsonl，然后在本地保留故障记录，并按函数和错误消息分组，返回计数及每组的第一条堆栈信息。用于回答“哪些地方在报错”“部署后出现了哪些故障”。
   • 健康视图 → insights（仅云端）：查看已类型化的 72 小时读取限制／OCC 事件。呈现并排序这些事件，但性能／成本的根本原因和修复方案应交给 convex-advisor——将其作为指针型发现结果输出，不要在此处负责性能修复的分析。
   • 跟踪视图 → logs --history <n> --jsonl，然后在本地筛选出一个 requestId／函数，以读取完整执行记录。用于回答“这次调用为何失败”。
4. 限定范围：获取有界的近期窗口（选择合理的 --history 数量），并在客户端筛选所询问的函数／状态／requestId；窗口较大时，按函数／消息汇总计数，而不是倾倒所有日志行。
5. 作答时提供：(a) 一句话结论；(b) 证据（计数和一条有代表性的堆栈／日志行）；(c) 尽可能提供 Agent 根据部署名称和函数构造的仪表板深层链接（dashboard.convex.dev 中该部署的 Logs／Functions 视图），供人类核验——没有工具会返回此链接，因此需自行构建；绝不要把原始日志倾倒出来作为答案。
6. 用户询问“我的部署是否导致了这个问题”时，交叉核对部署因果关系：将故障开始时间（来自日志时间戳）与 status 返回的部署版本对比；说明相关性，不要断言因果关系。
7. 移交处理，不要在此处修复：性能／成本原因 → convex-advisor（负责此类修复）；代码缺陷 → convex-reviewer／convex-authz；后续需响应的实时错误 → monitor／sentinel。将发现结果发布到总线上（specs/finding.schema.json）——主要标记为 observability，性能／成本问题则作为指向 advisor 的指针型发现结果——以便复合流程接收。

规则

• 过滤前先发现真实的函数/字段名称（functionSpec/status）——绝不猜测标识符，也绝不因应用中不存在某个名称而返回令人困惑的空结果。
• logs 和 insights 没有服务端状态/函数/requestId/时间范围筛选（logs 仅接受 --history COUNT；insights 仅限云端）——获取有界的近期数据窗口，并在客户端筛选；应明确说明这一点，而不是暗示存在并不存在的参数。
• 每个问题只选择三种视图之一（故障 / 健康状况 / 跟踪）——不要发起大量推测性的工具调用。
• 没有工具会返回仪表板链接——条件允许时，根据部署名称和函数构造链接，供人工核验；绝不以原始日志转储作答。
• 始终只读：insights 检查不会执行任何变更，也绝不会启用生产环境变更标志（deploy-guard 纪律）。
• 只做信息读取，并将性能/成本优化交由 convex-advisor：主要输出 observability，将性能/成本问题作为 POINTER 发现转交，以确保性能修复方案的表述由 advisor 独家负责；面向未来的响应交由 monitor/sentinel。