如何校验元数据文件的合法性

AI 修改 .dash、.spg、.tbl、.rpt 等元数据文件后，如果不想等到浏览器预览时才发现表达式、组件配置或模型结构错误，可以先用 SuccApp CLI 做一次服务器编译校验。校验会把本地文件内容发送到当前服务器编译，不保存文件，也不修改服务器上的元数据内容。

适用场景

遇到以下情况时，先做元数据合法性校验：

1. AI 修改了仪表板、页面、报表、模型、表单或主题等 JSON 元数据文件。
2. 浏览器预览或设计器打开时报错，需要在终端里拿到结构化错误信息。
3. 推送测试服务器前，希望先拦截 JSON 语法、版本升级、表达式和编译阶段的错误。
4. 需要让 AI Agent 读取 --json 结果并继续修复文件。

图片、附件、普通脚本和非 JSON 文件不适合使用这个命令校验。它也不能证明业务口径、数据结果、权限和页面交互一定正确。

前置条件

执行校验前确认：

1. 当前目录在 SuccApp 工作区内。
2. 工作区已经配置活跃服务器，并已完成登录。
3. 要校验的文件在本地工作区中存在。
4. 文件路径属于当前服务器已知的元数据项目范围。

如果还没有准备工作区，先阅读连接服务器与下载元数据。

执行校验

在工作区根目录或子目录执行：

succapp workspace file compile path/to/file.dash

也可以一次校验多个文件：

succapp workspace file compile path/to/page.spg path/to/model.tbl

需要给 AI Agent 或脚本读取时，使用 JSON 输出：

succapp workspace file compile path/to/file.dash --json

命令会读取本地文件内容，按文件路径确定服务器上的元数据类型和编译上下文，然后调用服务器编译逻辑。服务器会先按当前版本尝试升级传入内容，再执行对应的编译校验。

提示

workspace file compile 不会把本地内容保存到服务器。校验通过后，仍然需要执行 succapp workspace push <path>，浏览器预览才能看到本地修改后的服务器版本。

查看校验结果

校验通过时，结果会显示通过文件数和失败文件数。校验失败时，CLI 会返回非 0 退出码，并展示失败文件、编译器和错误信息。

JSON 输出中重点看这些字段：

字段	说明
summary.files	本次校验的文件数量。
summary.passed	通过校验的文件数量。
summary.failed	未通过校验的文件数量。
items[].remotePath	文件对应的服务器元数据路径。
items[].type	服务器识别到的元数据类型，例如 dash、spg、tbl。
items[].compiler	本次使用的编译器，常见为 nodejs 或 java。
items[].success	当前文件是否通过编译校验。
items[].errorInfo	服务器返回的结构化错误信息。

success: false 表示文件内容没有通过校验。此时命令退出码非 0 是预期行为，不要把它当作 CLI 连接失败或程序崩溃。

根据错误修复

定位问题时按以下顺序看：

1. 先看 items[].remotePath，确认是哪一个文件失败。
2. 再看 items[].errorInfo.message、errorCode 或 className，确认错误类型。
3. 如果 errorInfo.locationPath 中包含文件路径、组件、字段或表达式位置，优先按该位置检查。
4. 修改本地文件后重新执行 succapp workspace file compile <path>。
5. 校验通过后，再执行 succapp workspace push <path> 并打开浏览器验证。

常见修复方向：

错误现象	处理方向
JSON 解析失败	检查逗号、引号、括号、注释和文件编码。
版本升级失败	对照同类文件或先执行 succapp workspace file upgrade --dry-run <path>。
表达式报错	检查参数、字段名、函数名、运算符和字符串引号。
组件或布局配置报错	对照同类型页面、仪表板或报表中的组件结构。
模型结构报错	检查 .tbl 的模型类型、字段、维键、度量、数据源和物理表配置。

校验通过后还要做什么

元数据合法性校验只说明文件能通过服务器编译。继续交付前还需要：

1. 用 Diff 审查 确认修改范围。
2. 用 引用检查 确认资源、字段、数据集和脚本引用没有被破坏。
3. 执行 succapp workspace push <path> 推送到测试服务器。
4. 按预览文件在浏览器或设计器中验证运行效果。
5. 关键业务流程继续做产品验证。