用途
在安全地改动一个 Convex 应用之前,需要先准确理解它的结构。逐行阅读大量函数文件既慢又容易出错。该能力通过读取两个最可靠的信息源——schema(数据模型)和函数表面(functionSpec 或导出的查询/变更/动作)——快速生成应用架构地图。它刻意保持描述性:只解释现状,判断交给审计能力,修改交给修复能力;也是优化或自愈会话的自然第一步,以及“重新解释当前架构”的可复用能力。
工作流程
- 识别应用:检查 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)和定时任务,以及动作中的外部调用(哪些 API、哪些环境变量)。
- 流程:追踪 1-2 条代表性端到端路径(例如“客户端调用 createTask → 校验 → 插入到调用者范围内的 tasks → listMyTasks 通过 by_owner 索引读回”),让读者看到各部分的连接关系,而不仅是目录。
- 呈现:以可扫描的地图形式输出(数据模型 → 公有/内部函数 → 认证模型 → 组件/边界 → 1-2 条流程),准确对应源码。最后指向下一步动作:convex-reviewer/convex-authz 审计、launch-readiness 评分、design/convex-expert 扩展。绝不编造源码未展示的行为;若有歧义,明确说明而非猜测。
规则
- 以 schema + 函数表面(functionSpec/源码)为唯一事实来源,不描述代码未展示的行为;标记歧义而非猜测。
- 优先呈现新人最需要且最容易弄错的两点:数据模型关系图和公有 vs 内部函数划分。
- 明确陈述认证/所有权模型,包括“没有认证基础”的情况——但只描述;审计漏洞是 convex-authz 的职责。
- 描述性而非评价性:explain-app 梳理现状,判断交给审计能力,修改交给修复能力。
- 只读:任何部署内省均为只读(deploy-guard),不修改应用。
- 结尾指向正确的下一步动作(审计 → reviewer/authz,评分 → launch-readiness,扩展 → design/expert)。
适用场景
- 接手或修改一个已有的 Convex 应用前,快速建立架构认知。
- 作为优化、自愈或重构会话的第一步。
- 需要可复用的“当前架构说明”时。
限制
- 仅做描述,不进行安全审计、评分或修改。
- 输出准确性受限于源码和 functionSpec 的完整性;源码未展示的行为不会被推断。
- 部署内省为只读,不会改变应用状态。