用途
convex-explain-app 是一项描述性能力，用于在改动一个已有 Convex 应用之前先快速、准确地了解它“现在是什么”。逐行阅读十几个函数文件既慢又容易出错，本能力通过读取两个不会说谎的来源——schema（数据模型）与函数接口（functionSpec，即导出的 queries/mutations/actions）——来生成应用地图。它刻意保持描述性：只解释现状，把判断交给审计类能力，把修改交给修复类能力。它也是优化或自愈会话的自然第一步，并可作为“重新解释当前架构”的可复用步骤，供“改动你构建的东西”依赖。
工作流程
-
检测应用：定位 convex/ 目录、schema.ts，以及是否存在部署。若存在部署，通过官方 MCP 读取 functionSpec/tables 获得权威的实时接口；若不存在，则直接读取源码。任何对部署的读取都被 deploy-guard 归类为只读。
-
数据模型：从 schema.ts 列出每张表及其字段，重点是关系——哪些 v.id("other") 字段指向哪里、存在哪些索引（索引揭示预期的访问路径）。用文字画出外键图，例如“tasks 属于 projects（projectId）和 users（ownerId）；messages 属于 conversations”。
-
函数接口：枚举每个导出函数，区分 PUBLIC（query/mutation/action，即攻击/API 面）与 INTERNAL（internalQuery 等，客户端不可达），并为每个函数给出一行说明“它做什么 + 触碰什么”。公开/内部分野是新人最需要、也最容易被源码略读搞错的一点。
-
认证/归属模型：说明身份如何建立（auth.config.ts 提供者？以 tokenIdentifier 为键的 users 表？）以及归属如何强制（是否有 requireOwner 式检查？哪个字段是所有者？）。如果没有认证基础，要明确说明——这对准备改动应用的人是关键上下文。只描述模型，不审计其漏洞（那是 convex-authz 的职责）。
-
组件与外部边界：列出已安装的 @convex-dev/* 组件（convex.config.ts）及其提供的能力、HTTP 路由（http.ts）和 crons，以及 actions 中的任何外部调用（调用了哪些 API、使用了哪些环境变量）。
-
数据流：追踪 1–2 条代表性端到端路径，例如“客户端调用 createTask → 校验 → 插入到属于调用者的 tasks → listMyTasks 通过 by_owner 索引读回”，让读者看到各部分如何连接，而不只是目录式罗列。
-
呈现：以可扫读的地图形式输出（数据模型 → 公开/内部函数 → 认证模型 → 组件/边界 → 一两条数据流），且与源码保持一致。结尾指向下一步动作：convex-reviewer/convex-authz 审计、launch-readiness 评分、design/convex-expert 扩展。绝不臆造源码未展示的行为；若有歧义，明确说明而非猜测。
规则
- 以 schema 与函数接口（functionSpec/源码）为事实来源，绝不描述代码未展示的行为；遇到歧义要标记而非猜测。
- 优先呈现新人最需要、略读最易出错的两点：数据模型关系图与公开/内部函数划分。
- 明确陈述认证/归属模型，包括“没有认证基础”的情况；只做描述，审计漏洞是 convex-authz 的工作。
- 描述性而非评价性：explain-app 只映射现状，判断交给审计类能力，修改交给修复类能力。
- 只读：任何部署内省均为只读（deploy-guard），不修改应用。
- 结尾指向正确的下一步动作（审计 → reviewer/authz，评分 → launch-readiness，扩展 → design/expert）。
适用场景
需要快速了解一个现有 Convex 应用的架构，作为优化、自愈或改动前的第一步。
限制
该能力为描述性、只读；不对安全性或质量作评价，不进行修改。源码中存在歧义之处会明确标出，不臆测。