用途:在安全修改一个 Convex 应用之前,先快速、准确地理解它。该能力面向 schema(数据模型)与函数面(functionSpec 或导出的 query/mutation/action),避免逐文件通读带来的缓慢与误读。它只做描述,不评估好坏,判断交给审计类能力,改动交给修复类能力,可作为优化或自愈会话的第一步。
主要能力: 一、数据模型。从 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.config.ts 中安装的 @convex-dev/* 组件及其作用、http.ts 的 HTTP 路由与 crons、actions 中的外部调用(哪些 API、哪些环境变量)。 五、流程。追踪 1 至 2 条端到端代表路径,例如客户端调用 createTask → 校验 → 以调用者为范围写入 tasks → listMyTasks 通过 by_owner 索引读回。
使用方式:自动检测应用(convex/ 目录、schema.ts、是否存在部署);若有部署,可通过官方 MCP 的 functionSpec/tables 获取权威的在线函数面,否则直接读源码。任何部署读取都按 deploy-guard 归类为只读。最终以可扫描的地图形式呈现:数据模型 → 公开/内部函数 → 认证模型 → 组件/边界 → 一两条流程,并指向后续动作:审计用 convex-reviewer/convex-authz,评分用 launch-readiness,扩展用 design/convex-expert。
限制:只读,不修改应用;以 schema 与函数面为事实来源,不描述源码未体现的行为,遇到歧义会标注而非猜测;只做描述性说明,不做安全或质量评判。