convex-explain-app

解释这个 Convex 应用

在安全地修改应用之前，你必须先了解它是什么——而从头到尾阅读 15 个函数文件既慢又容易出错。此能力通过读取两个不会说谎的信息源，快速、准确地绘制应用地图：schema（数据模型）和函数表面（functionSpec / 导出的查询、变更和操作）。它有意保持描述性——解释现状，将判断交给审计能力，将修改交给修复工具。它也是优化或自愈会话自然的第一步，也是可重复使用的“重新解释当前架构”步骤；“修改你构建的内容”会依赖它。

工作流

1. 检测应用：查找 convex/ 目录、schema.ts，并确认是否存在部署（若存在，通过官方 MCP 获取的 functionSpec/tables 提供权威的实时函数表面；若不存在，则直接读取源代码）。deploy-guard 会将任何部署读取归类为只读。
2. 数据模型：从 schema.ts 中列出每张表的所有字段，以及至关重要的关系——哪些 v.id("other") 字段指向哪里，以及存在哪些索引（索引能揭示预期的访问路径）。用文字绘制外键关系图：“任务属于项目（projectId）和用户（ownerId）；消息属于对话”。
3. 函数表面：枚举每个导出的函数，区分公开函数（query/mutation/action——攻击面/API 表面）和内部函数（internalQuery/...——客户端无法访问），并为每个函数用一句话说明“它做什么 + 它会访问什么”。公开/内部的划分是新手最需要了解、也最容易在快速浏览源码时弄错的一点。
4. 身份验证/所有权模型：说明如何确定身份（是否有 auth.config.ts 提供方？是否有以 tokenIdentifier 为键的 users 表？），以及如何执行所有权检查（是否有类似 requireOwner 的检查？哪个字段代表所有者？）。如果没有身份验证基础，请明确说明——对于任何准备修改应用的人来说，这是影响重大的背景信息。（描述模型；不要审计其中的漏洞——那是 convex-authz 的工作。）
5. 组件和外部连接：列出已安装的 @convex-dev/* 组件（convex.config.ts）及其提供的功能、HTTP 路由（http.ts）和定时任务，以及操作中的任何外部调用（涉及哪些 API、哪些环境变量）。
6. 流程：追踪 1–2 条有代表性的端到端路径（“客户端调用 createTask → 验证 → 在限定为调用者的数据范围内插入 tasks → listMyTasks 通过 by_owner 索引读回数据”），让读者看到各个环节如何衔接，而不只是看到一份目录。
7. 以便于浏览的地图形式呈现（数据模型 → 公开/内部函数 → 身份验证模型 → 组件/外部连接 → 一两个流程），并确保内容与源码一致。最后指出接下来的操作：使用 convex-reviewer/convex-authz 进行审计，使用 launch-readiness 评分，使用 design/convex-expert 扩展。绝不虚构源码未体现的行为；遇到含糊之处，应如实说明，而不是猜测。

规则

• 以 schema 和函数表面（functionSpec/源码）为事实依据——绝不描述代码未体现的行为；遇到不明确之处，应标明而不是猜测。
• 开篇说明新手最需要了解、也最容易在快速浏览时弄错的两件事：数据模型的关系图，以及公开函数与内部函数的划分。
• 明确说明身份验证/所有权模型；若没有身份验证基础，也要明确指出——但只需描述；审计漏洞是 convex-authz 的职责。
• 保持描述性，而非评价性：explain-app 负责映射现状，并将判断交给审计能力，将修改交给修复工具。
• 只读：任何部署检查都必须是只读的（deploy-guard）；不得修改应用。
• 最后指出合适的下一步操作（审计 → reviewer/authz，评分 → launch-readiness，扩展 → design/expert）。