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 个 function 文件既慢又容易出错。此 capability 通过读取两个可靠的来源，快速准确地生成应用地图：schema（数据模型）和 function surface（

functionSpec

／导出的 queries/mutations/actions）。它刻意保持描述性（DESCRIPTIVE）——只解释现状，将判断交给 audit capabilities，将修改交给 fixers。它也是 optimize 或 self-heal session 的自然第一步，并且是 'change what you built' 所依赖的可复用 're-explain the current architecture'。

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
```
，并判断是否存在 deployment。如果存在，可通过 official MCP 获取权威的 live surface（
```
functionSpec
```
/
```
tables
```
）；如果不存在，则直接读取 source。deploy-guard 会将任何 deployment introspection 归类为只读。
数据模型：从
```
schema.ts
```
中列出每张表及其字段，尤其是它们的关系——哪些
```
v.id("other")
```
字段指向何处，以及存在哪些 indexes（indexes 会揭示预期的访问路径）。用文字绘制外键关系图：'tasks 属于 projects（projectId）和 users（ownerId）；messages 属于 conversations'。
函数接口面：枚举每个 exported function，区分 PUBLIC（query/mutation/action——攻击面/API surface）与 INTERNAL（internalQuery/...——客户端不可访问），并为每个函数提供一行说明：'它做什么 + 它接触什么'。public/internal 划分是新手最需要了解、也最容易因粗略浏览源码而弄错的关键点。
Auth／Ownership 模型：说明 identity 如何建立（
```
auth.config.ts
```
provider？以 tokenIdentifier 为键的 users 表？），以及 ownership 如何强制执行（是否存在 requireOwner 风格的检查？哪个字段是 owner 字段？）。如果完全没有 auth 基础，请直接说明——对于任何准备修改应用的人而言，这都是关键上下文。（仅描述该模型；不要审计漏洞——那是 convex-authz 的职责。）
Components 与外部连接：列出已安装的
```
@convex-dev/*
```
components（convex.config.ts）及其提供的功能、HTTP routes（
```
http.ts
```
）、crons，以及 actions 中的所有 external calls（调用哪些 API、使用哪些 env vars）。
Flow：追踪 1–2 条具有代表性的端到端路径（'客户端调用 createTask → 验证 → 插入按调用者限定范围的 tasks → listMyTasks 通过 by_owner index 将其读回'），让读者看到各部分如何连接起来，而不只是逐项罗列。
以便于扫描的 map 呈现（数据模型 → public/internal functions → auth 模型 → components/edges → 一到两条 flow），并确保内容与 source 一致。最后指向相应的后续 verb：使用 convex-reviewer/convex-authz 进行 audit，使用 launch-readiness 进行评分，使用 design/convex-expert 进行扩展。绝不能虚构 source 未显示的行为；如果存在歧义，应直接说明，而不是猜测。

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 + function surface（functionSpec/source）视为 source of truth——绝不描述代码未显示的行为；有歧义时予以标记，而不是猜测。
首先呈现新手最需要、而粗略浏览最容易弄错的两项内容：数据模型关系图，以及 public/internal function 划分。
直接说明 auth/ownership 模型，包括在确实没有基础时指出 'there is no auth foundation'——但仅做描述；漏洞审计由 convex-authz 负责。
做描述而非评价：explain-app 负责呈现现状，并将判断交给 audit capabilities，将修改交给 fixers。
只读：任何 deployment introspection 都是只读的（deploy-guard）；不会修改应用。
最后指向正确的后续 verb（audit → reviewer/authz，score → launch-readiness，extend → design/expert）。