主题
元数据系统
元数据系统是 SuccApp 保存和管理项目资源的底层文件体系。页面、仪表板、报表、数据模型、程序流、工作流、主题、数据源和项目配置，都会以约定目录下的元数据文件保存。本目录说明 SuccApp 元数据文件系统的项目组织、文件存储、元数据规则、文件类型和直接维护规则。
AI 低代码开发的本质，是 AI Agent 在本地工作区中生成、修改和维护这些元数据文件。SuccApp CLI 和 SuccApp for VS Code 则基于同一套文件体系完成拉取、编辑、差异检查、同步和发布。理解元数据系统后，开发者和 AI Agent 才能在不打开设计器的情况下定位资源、判断引用关系、批量调整结构，并用 DTS、同类文件、静态检查和产品界面验证修改结果。
元数据系统相关文档重点说明：元数据项目如何组织、不同文件类型如何识别、字段结构以什么为准、直接维护时要遵守哪些规范等。如果需要了解 AI 如何安排任务、使用工具、检查差异、协作和发布，请阅读AI 低代码开发。
直接操作元数据文件的优势
直接面对元数据文件进行操作，不是替代浏览器中的图形化设计器，而是补充一种更适合结构化修改、批量维护和 AI Agent 参与的工作方式。相比人工在浏览器中逐项点击配置，文件级操作有这些优势：
- 结构可检索：可以直接搜索页面、模型、字段、表达式、动作节点和引用路径，定位设计器界面不容易看到的底层关系。
- 版本可管理：元数据文件可以纳入 Git，通过分支、提交和标签管理版本，用 diff 审查字段、组件、权限、配置和资源引用的变化，并在需要时回退到历史版本。
- 批量可自动化：适合批量调整页面、模型、配置、主题、资源路径、命名和目录结构，避免在浏览器中重复点击。
- AI 更容易参与：AI Agent 可以读取同类文件、DTS 和项目规则，生成或修改页面、数据模型、动作流、配置文件和迁移脚本。
- 环境更容易隔离同步：测试环境和生产环境可以基于同一组元数据文件做隔离部署、差异比对和受控同步，减少只存在于某次浏览器操作中的隐式状态。
浏览器图形化界面仍然很重要。人工调整页面细节、检查视觉效果、验收 AI Agent 的产出、测试交互和用户体验时，都应在产品设计器、预览页面或对应功能界面中完成。文件级修改解决的是“结构如何被准确维护”，图形化界面验证的是“这些结构运行后是否符合业务和体验预期”。
元数据规则
阅读元数据文档时，不需要一开始就记住所有字段。先建立这些基础认识：
| 需要认识的内容 | 先读哪里 |
|---|---|
| 新建文件时如何根据需求判断文件大类和具体文件类型 | 根据需求判断文件类型 |
| 新建、修改、移动或重命名文件时应遵守哪些规范 | 文件新建和修改规范 |
元数据项目是什么、什么时候需要新建项目、普通项目和 sysdata 有什么区别 | 元数据项目 |
项目目录如何组织，app/、data/、settings/ 等目录分别放什么 | 元数据项目 |
| 文件名、目录名、后缀、资源命名有什么约定 | 命名约定 |
| 文件内部如何表达组件、数据集、动作和引用资源 | SuccApp Super JSON |
.meta 保存什么，移动、重命名或删除资源时为什么要一起检查 | .meta 资源元信息 |
外部资源引用、路径前缀和 referenceResources 应该怎么写 | 资源引用与路径 |
innerResources 这类内嵌完整资源内容应该怎么写 | 内嵌资源 |
这些内容统一收在元数据规则中。遇到具体文件时，先用规则判断它属于哪个项目、哪个目录、哪类资源，再继续看文件类型和格式规范。
文件类型
SuccApp 元数据文件不只包括 JSON，也包括 .js、.ts、.less、.css、.png 等脚本、样式和静态资源。新建或维护元数据文件时，先从要解决的需求出发，判断它属于数据与模型、页面与应用、报表与可视化、后端流程、配置元信息还是静态资源，再选择具体文件类型。
确定文件类型后，再根据文件所属项目、应用目录、后缀、约定文件名和目录资源边界，确认它应该放在哪个位置。完整选择流程见根据需求判断文件类型；完整分类、判断线索和各类型说明见文件类型概述。
修改方式
新建、修改、移动或重命名元数据文件时，应遵守文件新建和修改规范。先确认文件类型，再进入对应文件类型页查找格式规范、DTS、脚本 API 或资源引用规则；不要只靠搜索替换批量调整，也不要为了局部修改格式化整份元数据文件。
推荐做法：
- 先根据需求确认文件大类、具体文件类型和存放位置。
- 打开对应文件类型页，了解用途、格式规范、常见位置和编辑注意事项。
- 属于 SuccApp Super JSON 的文件，结合 DTS 确认字段结构；后端脚本结合后端脚本 API 索引确认可用接口。
- 修改时读取当前文件、同目录同类文件、相关
.meta、引用方和被引用资源，保持小步变更。 - 使用
succapp命令或 SuccApp for VS Code 的 Changes / diff 视图检查差异，推送到测试环境后在设计器、预览页面或对应功能界面验证运行效果。
工具入口见 SuccApp CLI 和 SuccApp for VS Code。完整的 AI 修改、检查、同步和发布流程见AI 低代码开发。
