create-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build a Prepr schema

构建 Prepr schema

Turn an agreed plan, or a concrete request ("add an Event model with a date and a location"), into models, components, enums and fields in Prepr.

将已达成一致的计划或具体请求（“添加一个包含日期和位置的 Event 模型”）转化为 Prepr 中的模型、组件、枚举和字段。

Step 0: Choose how to edit

步骤 0：选择编辑方式

A project keeps its schema in Git, in

prepr/schema/

, synced with Prepr. You can edit it in two ways, and both are fine (schema-route.md):

Live through MCP: the Prepr MCP schema tools change the environment directly. Steps 1 to 4 below; the user then runs Export so the files catch up.
In the files: you edit JSON files in
```
prepr/schema/
```
; the user runs Import to bring the change into the environment. See The file route.

Use MCP unless the user asks for a file change or wants it reviewed in a pull request first. Check Before you edit when the repository has

prepr/schema/

, and say in the first line of your plan how you edit and which sync follows.

For live changes, run the check first. If MCP is not connected, offer connect-prepr, or edit the files instead if the project has them.

If the brief is vague ("a marketing site"), run design-schema first. If a plan from design-schema is in this conversation or in

docs/prepr/schema-plan.md

, build from it and do not reopen its decisions.

项目将 schema 保存在 Git 中的

prepr/schema/

下，并与 Prepr 同步。

你可以通过两种方式进行编辑，两者都可行（schema-route.md）：

通过 MCP 实时编辑： Prepr MCP schema 工具会直接更改环境。按照下面的步骤 1 到 4 操作；随后由用户运行 Export，让文件同步更新。
通过文件编辑： 你可以编辑
```
prepr/schema/
```
下的 JSON 文件；由用户运行 Import，将更改导入环境。参见文件编辑路径。

除非用户要求进行文件更改或希望先在 pull request 中审查，否则请使用 MCP。当仓库中存在

prepr/schema/

时，请查看编辑前检查，并在计划的第一行说明你将如何编辑以及之后采用哪种同步方式。

对于实时更改，请先运行检查。如果 MCP 未连接，请提供 connect-prepr；如果项目已有 schema 文件，则改为编辑这些文件。

如果需求描述比较笼统（“一个营销网站”），请先运行 design-schema。如果本对话中或

docs/prepr/schema-plan.md

中已有来自 design-schema 的计划，请据此进行构建，不要重新讨论其中的决策。

Step 1: Read what exists

步骤 1：读取现有内容

Page through

list_schema

. For each entity the change touches, and for one or two similar existing entities, call

get_schema_entity

. From these, note:

naming: display names, API id casing, singular or plural;
reuse: components and enums the new work should use instead of duplicating;
conventions: SEO fields, slugs, how pages are composed (Stack or fixed fields);
clashes: any name the plan uses that already exists.

Mirror what you find. Report clashes and pick a different name with the user before planning.

分页浏览 list_schema。对于本次更改涉及的每个实体，以及一两个相似的现有实体，调用 get_schema_entity。根据这些信息，记录：

命名：显示名称、API id 大小写、单数或复数；
复用：新内容应使用哪些组件和枚举，以避免重复；
约定：SEO 字段、slug、页面组合方式（Stack 或固定字段）；
冲突：计划中使用的任何名称是否已经存在。

遵循发现的规范。报告冲突，并在规划前与用户共同选择其他名称。

Step 2: Design the changes

步骤 2：设计更改

Map every plan item to an entity and its fields. Choose field types with field-types.md and check the result against the anti-patterns in schema-design-principles.md.

Read each schema tool's input schema for the exact parameters. Do not rely on a remembered tool list. Server rules that shape the plan are in mcp-limits.md: an entity starts with no fields, each field is one call, types cannot change, lists replace.

Write an AI description for every model (

ai_goal

) and every text field (

ai_purpose

), following ai-context.md: what the content is for, where it appears, and its limits. Include them in the plan so the user can correct them. Prepr's AI features and every MCP client read them.

将计划中的每一项映射到实体及其字段。使用 field-types.md 选择字段类型，并对照 schema-design-principles.md 中的反模式检查结果。

读取每个 schema 工具的输入 schema，以确认准确的参数。不要依赖记忆中的工具列表。影响方案设计的服务器规则见 mcp-limits.md：实体初始没有字段；每个字段需要一次调用；类型无法更改；列表写入时会被整体替换。

按照 ai-context.md，为每个模型（

ai_goal

）和每个文本字段（

ai_purpose

）编写 AI 描述：说明内容的用途、出现位置及其限制。将这些描述加入计划，以便用户进行修正。Prepr 的 AI 功能和所有 MCP 客户端都会读取这些描述。

Step 3: Plan, confirm, apply, verify

步骤 3：规划、确认、应用、验证

Follow write-safety.md exactly:

Plan: name the environment, then list entities in dependency order (enums and components before the models that use them), each with its fields.
Confirm: wait for an explicit yes.
Apply: create each entity, then its fields one call each. Stop at the first error.
Verify:
```
get_schema_entity
```
on each entity you touched and compare it with the plan.

严格遵循 write-safety.md：

规划：指定环境，然后按依赖顺序列出实体（枚举和组件位于使用它们的模型之前），并列出每个实体的字段。
确认：等待用户明确同意。
应用：创建每个实体，然后每次调用一次来创建其字段。出现第一个错误时立即停止。
验证：对每个已更改的实体调用
```
get_schema_entity
```
，并与计划进行比较。

Changing an existing schema

更改现有 schema

Adding a field: read the entity, plan the one field, same loop.
Adding enum options or allowed reference types: read the current list, merge, write the merged list. A write replaces the list.
Changing a field's type: not possible in place. Plan a new field, content migration through manage-content, then deleting the old field.
Deleting: see Deletes. Always the two-step confirm.

添加字段：读取实体，规划这个字段，并执行相同流程。
添加枚举选项或允许的引用类型：读取当前列表，合并后写入合并后的列表。写入会替换整个列表。
更改字段类型：无法原地更改。先规划新字段，通过 manage-content 迁移内容，然后删除旧字段。
删除：参见删除。始终执行两步确认。

Step 4: Report

步骤 4：报告

List what now exists, in the environment you named, and what the user should do next:

If the repository has
prepr/schema/
: tell the user to run Export in Prepr and pull it, so the files catch up with your live change. Until then the next Import would overwrite it.
If it has none: suggest setting up Git sync with sync-schema when the project is shared or headed for production.
Then: review it (
```
review-schema
```
), or create first content (
```
manage-content
```
).

列出指定环境中现在存在的内容，以及用户接下来应执行的操作：

如果仓库中存在
prepr/schema/
：告诉用户在 Prepr 中运行 Export，然后拉取变更，使文件与实时更改同步。在完成此操作之前，下一次 Import 会覆盖这些实时更改。
如果不存在该目录： 当项目需要共享或即将投入生产时，建议使用 sync-schema 设置 Git 同步。
随后：审查 schema（
```
review-schema
```
），或创建第一批内容（
```
manage-content
```
）。

The file route

文件编辑路径

Start from the current state. Ask the user to run Export (or pull the branch Prepr exports to) before you edit. If MCP is connected, compare the files with the live schema and report any drift before you change anything.
Read what exists in
```
prepr/schema/
```
, as in Step 1: naming, reuse, conventions, clashes.
Design the changes as in Step 2, then write them in the format of schema-files.md: one file per entity, the file named after the entity, a new
```
ref
```
(UUID) for each new entity, existing
```
ref
```
values untouched.
Plan, confirm, write. Show the plan (files to add, change and delete, and which entities and fields an import will remove), wait for an explicit yes, then write the files. Deleting a file deletes its entity on the next import when no content uses it.
Validate with the official workflow (see sync-schema) and read Validation is not import.
Hand off. A commit is not a sync. Tell the user which environment must run Import, and that sync-schema covers the import, its impact assessment and verifying the result. Do not report the change as live.

从当前状态开始。 编辑前，请让用户运行 Export（或拉取 Prepr 导出内容所在的分支）。如果 MCP 已连接，请将文件与实时 schema 进行比较，并在更改前报告任何偏差。
读取现有内容。 按照步骤 1 的方式读取
```
prepr/schema/
```
中的内容，包括命名、复用、约定和冲突。
设计更改。 按照步骤 2 的方式设计更改，然后按照 schema-files.md 中规定的格式写入：每个实体一个文件，文件名以实体名称命名；每个新实体使用新的
```
ref
```
（UUID），现有
```
ref
```
值保持不变。
规划、确认、写入。 展示计划（要添加、修改和删除的文件，以及 Import 将删除哪些实体和字段），等待用户明确同意，然后写入文件。删除文件后，如果下次 Import 时没有内容使用该实体，则会删除该实体。
验证。 使用官方工作流进行验证（参见 sync-schema），并阅读验证不等同于导入。
交接。 Commit 不等于同步。告诉用户必须在哪个环境中运行 Import；sync-schema 涵盖导入、影响评估和结果验证。不要将更改报告为已实时生效。