convex-explain-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explain this Convex app

解析此Convex应用

Before you can safely change an app you have to know what it is — and reading 15 function files top-to-bottom is slow and error-prone. This capability produces the map fast and accurately by reading the two sources that can't lie: the schema (the data model) and the function surface (

functionSpec

/ the exported queries/mutations/actions). It is deliberately DESCRIPTIVE — it explains what IS, hands judgment to the audit capabilities and changes to the fixers. It is also the natural first step of an optimize or self-heal session, and the reusable 're-explain the current architecture' that 'change what you built' depends on.

在安全修改应用之前，你必须先了解它的全貌——而逐行阅读15个函数文件既缓慢又容易出错。该功能通过读取两个最可靠的信息源：schema（数据模型）和函数接口（

functionSpec

/ 导出的查询/变更/操作函数），快速且准确地生成应用架构图。它仅用于描述现状——解释应用当前的状态，将评估工作交给审计功能，修改工作交给修复功能。它也是优化或自愈流程的自然第一步，同时是“修改已构建内容”所依赖的可复用“重新解析当前架构”功能。

Workflow

工作流程

DETECT the app: the
```
convex/
```
directory,
```
schema.ts
```
, and whether a deployment exists (if one does,
```
functionSpec
```
/
```
tables
```
via the official MCP give the authoritative live surface; if not, read the source directly). deploy-guard classifies any deployment read as read-only.
DATA MODEL: from
```
schema.ts
```
, list every table with its fields and, crucially, its RELATIONSHIPS — which
```
v.id("other")
```
fields point where, and which indexes exist (indexes reveal the intended access paths). Draw the foreign-key graph in words: 'tasks belong to projects (projectId) and users (ownerId); messages belong to conversations'.
FUNCTION SURFACE: enumerate every exported function, split PUBLIC (query/mutation/action — the attack/API surface) from INTERNAL (internalQuery/... — not client-reachable), and for each give a one-line 'what it does + what it touches'. The public/internal split is the single most important thing a newcomer needs and the thing source-skimming most often gets wrong.
AUTH / OWNERSHIP MODEL: state how identity is established (auth.config.ts provider? a users table keyed by tokenIdentifier?) and how ownership is enforced (is there a requireOwner-style check? which field is the owner?). Say plainly if there is NO auth foundation — that is load-bearing context for anyone about to change the app. (Describe the model; do not audit it for holes — that's convex-authz.)
COMPONENTS + EXTERNAL EDGES: list the
```
@convex-dev/*
```
components installed (convex.config.ts) and what they provide, the HTTP routes (http.ts) and crons, and any external calls in actions (which APIs, which env vars).
FLOW: trace 1-2 representative end-to-end paths ('client calls createTask → validates → inserts into tasks scoped to the caller → listMyTasks reads it back by the by_owner index') so the reader sees the moving parts connected, not just catalogued.
PRESENT as a scannable map (data model → public/internal functions → auth model → components/edges → a flow or two), accurate to the source. End by pointing at the next verbs: convex-reviewer/convex-authz to audit it, launch-readiness to score it, design/convex-expert to extend it. Never invent behavior the source doesn't show; if something is ambiguous, say so rather than guessing.

检测应用：识别
```
convex/
```
目录、
```
schema.ts
```
，以及是否存在部署实例（若存在，则通过官方MCP获取权威的实时接口
```
functionSpec
```
/
```
tables
```
；若不存在，则直接读取源代码）。deploy-guard会将所有部署实例的读取操作标记为只读。
数据模型：从
```
schema.ts
```
中列出每个表及其字段，关键是它们的关联关系——哪些
```
v.id("other")
```
字段指向哪个表，以及存在哪些索引（索引揭示了预期的访问路径）。用文字描述外键关系图：'tasks表属于projects表（通过projectId字段）和users表（通过ownerId字段）；messages表属于conversations表'。
函数接口：枚举所有导出的函数，区分公开函数（query/mutation/action——即对外暴露的API/攻击面）和内部函数（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进行扩展。切勿编造源代码中未体现的行为；若存在歧义，应明确说明而非猜测。

Rules

规则

Read the schema + function surface (functionSpec/source) as the source of truth — never describe behavior the code doesn't show; flag ambiguity instead of guessing.
Lead with the two things a newcomer most needs and skimming most often gets wrong: the data-model relationship graph and the public-vs-internal function split.
State the auth/ownership model plainly, including 'there is no auth foundation' when that's the case — but DESCRIBE it; auditing it for holes is convex-authz's job.
Descriptive, not evaluative: explain-app maps what IS and hands judgment to the audit capabilities and changes to the fixers.
Read-only: any deployment introspection is read-only (deploy-guard); the app is not modified.
End by pointing at the right next verb (audit → reviewer/authz, score → launch-readiness, extend → design/expert).

以schema + 函数接口（functionSpec/源代码）为唯一可信来源——切勿描述代码未体现的行为；若存在歧义，应标记出来而非猜测。
优先展示新手最需要且浏览源代码时最容易出错的两项信息：数据模型关联图和公开/内部函数的区分。
清晰说明认证/所有权模型，包括在没有认证基础时明确指出——但仅做描述；审计漏洞是convex-authz的工作。
仅做描述，不做评估：explain-app仅映射现状，将评估工作交给审计功能，修改工作交给修复功能。
只读操作：任何对部署实例的内省操作都是只读的（由deploy-guard保障）；不会修改应用。
最后指明合适的下一步操作（审计→reviewer/authz，评分→launch-readiness，扩展→design/expert）。