---
title: 元数据即代码
navTitle: 元数据即代码
---
# 元数据即代码

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

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

## 为什么说它是低代码语言{#why-language}

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

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 应该读取哪些事实源{#sources}

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

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

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

## 常见文件和任务{#files}

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

## 修改原则{#rules}

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

## 推荐阅读{#related}

1. [元数据系统](../../meta/README.md)
2. [SuccApp Super JSON](../../meta/rules/super-json.md)
3. [资源引用与路径](../../meta/rules/reference-paths.md)
4. [文件类型](../../meta/file-types/README.md)