元数据即代码

SuccApp 元数据文件系统是 AI 低代码开发的核心。AI 不是直接操作数据库中的隐式状态，而是编辑本地工作区中的元数据文件，再通过 SuccApp CLI 或 SuccApp for VS Code 同步到服务器。

这些元数据文件多数是 JSON 或接近 JSON 的结构化文本。它们描述页面、仪表板、报表、数据模型、程序流、脚本、应用配置、主题、数据源和系统设置，可以理解为一套面向 SuccApp 的低代码编程语言。

为什么说它是低代码语言

元数据文件具备低代码语言的几个特征：

1. 有固定文件类型，例如 .spg、.dash、.rpt、.tbl、.query、.afl、.wfl、.theme、.jdbc。
2. 有语法和结构约束，基础结构由 JSON 语法、元数据规范和 DTS 共同描述。
3. 有类型和动态分支，例如组件 type、数据集 modelType、布局 layoutType、单元格 cellType。
4. 有引用机制，例如 referenceResources、.meta、文件路径、模型字段、组件 ID 和动作节点 ID。
5. 有运行时语义，同一段 JSON 会在设计器、预览页面、调度、权限、数据查询和发布流程中生效。

AI 修改元数据时，不能只生成“看起来合法”的 JSON，还要遵守这套语言的引用关系、历史结构和运行时约束。

AI 应该读取哪些事实源

修改元数据前，AI 应按下面顺序读取资料：

1. 当前项目规则：AGENTS.md、.agents/rules/、任务说明和团队约定。
2. 当前工作区同类文件：优先参考同项目、同目录、同版本的真实元数据。
3. 元数据手册：元数据系统、文件类型页、元数据规则和 SuccApp Super JSON。
4. DTS 类型：/dev-types/index.json 以及 types/meta/、types/api/ 下的类型定义。
5. CLI 检查结果：工作区检查、后续编译校验和服务器返回错误。
6. 产品运行结果：设计器、页面预览、脚本日志和控制台信息。

本页只说明读取顺序、编辑流程和风险边界；字段、枚举、继承、可选性和动态类型分支以 DTS 为准。

常见文件和任务

任务	常见文件	说明
做页面	.spg、.tpg、.fapp、脚本文件	关注组件树、数据集、参数、动作和引用资源。
做看板	.dash、.tbl、.query	关注图表组件、数据集、主题和模型字段。
做报表	.rpt、.tbl、.query	关注单元格、数据区域、参数、导出和打印效果。
准备数据	.tbl、.query、.jdbc	关注字段、数据源、schema、SQL 和数据权限。
修改流程	.afl、.wfl	关注节点类型、节点 ID、参数流转和错误处理。
修改脚本	.ts、.js、.action.ts、.ftl	关注运行环境、类型声明、日志和验证方式。

修改原则

1. 先定位文件类型，再打开对应文件类型页和 DTS。
2. 先读同类文件，再生成或修改结构。
3. 保留稳定标识，不随意改资源 ID、组件 ID、字段名、数据集 ID、动作节点 ID 和 .meta 中的资源 ID。
4. 新增、移动或删除文件时，同步检查相关目录 .meta 和引用路径。
5. 对大型 JSON 不做无意义全文件格式化，避免 diff 噪声。
6. 修改后至少做元数据静态检查、diff 检查和产品界面验证。

推荐阅读

1. 元数据系统
2. SuccApp Super JSON
3. 资源引用与路径
4. 文件类型