用 YAML 表示格式创建/编辑/校验 Metabase…

当你需要创建、编辑、理解或校验 Metabase Representation Format 的 YAML 文件（serdes 序列化/反序列化）时使用。

适用场景

解决思路

1. 把每个实体写成一个 YAML 文件，整个内容是一棵 YAML 文件树；格式是跨 Metabase 实例可移植的：数字数据库 ID 被替换为人类可读的名称和 entity ID。
2. 按 11 种实体类型建模：Collection（用 parent_id 组织层级，命名空间为 null/"snippets"/"transforms"）、Card（question/model/metric，含 MBQL 或 native 的 dataset_query 与 display 类型）、Dashboard（24 列网格布局，含 dashcards 与 parameters，可带 tabs）、Document（ProseMirror AST 富文本，可用 cardEmbed 嵌入卡片、smartLink 链接实体）、Segment（限定到某表的保存过滤器，单阶段 pMBQL 只含 source-table 和 filters）、Measure（限定到某表的保存聚合，单阶段 pMBQL 只含 source-table 和恰好一个 aggregation）、Snippet（可复用 SQL 片段，通过 {{snippet: Name}} 引用）、Transform（把 MBQL/native 查询或 Python 脚本结果物化到数据库表）、TransformTag（分类标签，内置 hourly/daily/weekly/monthly 或 null 自定义）、TransformJob（按标签匹配执行 transform 的 cron 定时任务）、PythonLibrary（供 Python transform 使用的共享 Python 源文件）。
3. 牢记文件夹布局只是装饰性的：实体在 Metabase 中的位置完全由字段决定，而不是 YAML 文件在目录树中的位置；移动文件而不改字段不会改变任何东西，改字段而不移动文件也仍然正确。始终以字段为准。
4. 用 collection_id（某个 collection 的 entity_id）决定实体归属的集合，null 或省略表示根集合。
5. 用 collection 自身的 parent_id（且只有它）设置该 collection 的父级；导入时忽略 collection 在文件夹树中的位置，没有 parent_id 或 parent_id: null 时无论文件夹嵌套多深都会成为根级 collection；要嵌套就把 parent_id 设为父 collection 的 entity_id。
6. 用 card 上的 dashboard_id 或 document_id 把卡片嵌套到仪表盘或文档下；这种卡片还必须把 collection_id 设为与父级 collection_id 一致；一张卡片绝不能同时设置两者。
7. 在磁盘上把嵌套在仪表盘/文档下的卡片放在父 YAML 旁边的子文件夹里（如 my_dashboard/card.yaml 与 my_dashboard.yaml 并列），但这只是为了人类导航，Metabase 读取的仍是字段。
8. 只把 YAML 放在这些顶层目录中才会被导入：collections/（所有用户内容，按命名空间分为 main/、snippets/、transforms/）、databases/（只导入每张表下的 segments/ 和 measures/ 子目录）、python_libraries/（也接受 python-libraries/）、transforms/（含 transform_jobs/ 和 transform_tags/）；其他位置一律忽略。
9. 为每个实体写顶层 serdes/meta 数组来编码其身份路径，每项为 {id, model, label?}，label 是名称的 slug 化形式，在以 NanoID 为键的实体上存在；validate-schema 依据 serdes/meta 判断每个文件的实体类型，完整规则（含嵌套实体与复合身份路径）见 spec.md。
10. 当编辑涉及 MBQL 查询形态（stages、字段引用、joins、表达式、聚合、filter/expression 操作符、时间分桶、分箱）、native 查询与 template tags（text、number、date、boolean、dimension、temporal-unit、card、snippet、table）、可视化设置、点击行为、仪表盘/卡片参数时，去读随技能附带的 spec.md（上游来源为 @metabase/representations npm 包）。
11. 按需读取 spec.md，不要提前打开：只在即将读取或修改上述实体的内容文件时打开（例如用户要求编辑卡片、添加 dashcard、调整 transform 等隐含 YAML 编辑的任务）；不要在会话开始时或与 representation YAML 无关的任务中打开。
12. 如果随附副本看起来落后于上游包，按技能自带 README.md 中记录的 extract-spec 方法刷新。
13. 用内置 CLI 校验编辑：npx @metabase/representations validate-schema --folder <path>，传入顶层导出文件夹或 git 仓库根目录；它会遍历上述导入路径，读取每个文件的 serdes/meta 以选择正确的校验规则，失败时以非零码退出；优先用它而不是手动核对字段形态，它几乎瞬时完成，每次编辑后、编辑之间、或对文件形态不确定时都可随时调用，无需攒批。
14. 用内置 CLI 为每个实体的 entity_id 生成 21 字符 NanoID：npx @metabase/representations generate-entity-id（可用 --count 5 一次生成多个）。
15. 对格式中需要 v4 UUID 而非 NanoID 的字段（尤其是 MBQL 聚合子句上的 lib/uuid，会被 order-by 和后续阶段引用，以及仪表盘/卡片参数上的 id），用 npx @metabase/representations generate-uuid 生成（可用 --count 3 一次生成多个）。

适用边界 · 注意事项

• 任务与 representation YAML 无关时，不要打开 spec.md。
• 不要在会话开始时提前打开 spec.md，应按需读取。
• 不要依赖文件夹位置来判断实体归属，也不要手动核对字段形态而不运行 validate-schema。