rde-data-apps

rde-data-apps

数据应用是一个 React 程序包，Metabase 会从通过远程同步连接的仓库中的 data_apps/<slug>/，在 /apps/<slug> 提供该程序包。metabase-data-apps 技能会构建它。此技能会根据 rde 已知的信息回答相关问题，因此只会询问 rde 无法知道的信息；在构建应用之前，会确保该应用读取的内容位于该仓库中，然后交接。第 4 至第 6 节在存在差异时优先于 data-apps 技能：包括架构范围、提交和推送的顺序，以及任何同步操作前的确认。

1. 实例

rde status --json：url 是实例地址（不是机密），且 version 必须为 v65+ 或 head 构建。mb auth list --json 会列出 url 与之匹配的配置文件；将其用作 $PROFILE。Metabase 仅在具备远程同步和数据应用功能的许可证下提供应用：查看 rde doctor --json 的 license 行。若没有许可证，用户可在自己的终端中运行 rde init --only license（或在本会话中运行 ! rde init --only license）激活；令牌不会进入聊天内容。同步内容需要将 remote-sync-type 设为 read-write（mb setting get remote-sync-type --json）；切换此设置属于同步变更，必须像其他同步操作一样先确认（第 6 节）。

2. 仓库

rde status --json 中的 contentRepository 是远程同步仓库的工作目录，也是 metabase-data-apps 设置指南第 1 步的答案：直接使用该目录，不要询问。当该值为 null 且许可证包含远程同步功能时，询问仓库应存放在哪里，然后运行 rde init --only git-sync --git-dir <path> --git-remote local（在 ~/.rde 内创建一个裸远程仓库，无需账户）。托管远程仓库需要 git 令牌，因此应由用户自行运行 rde init --only git-sync。rde 创建的仓库已忽略 .env.local、node_modules/ 以及数据应用不得推送的其他内容。

3. 凭据

data-apps 技能会从仓库根目录下的 .env.local 读取 DATA_APP_MB_URL 和 DATA_APP_MB_API_KEY，并禁止在对话中泄露密钥。rde 会存储 mb 使用的 API 密钥，而 rde credentials --api-key 会单独打印该密钥。当设置指南进行到凭据步骤，或检查结果显示 MISSING 时，使用以下命令填充文件，而不要询问用户；其中 <url> 来自第 1 步，<repo> 来自第 2 步。该命令只会输出 creds written，保留文件中的其他行，并确保 .env.local 已被忽略：

ROOT="$(git -C "<repo>" rev-parse --show-toplevel)" && KEY="$(rde credentials --api-key)" &&
{ grep -qxF .env.local "$ROOT/.gitignore" 2>/dev/null || echo .env.local >> "$ROOT/.gitignore"; } &&
{ if [ -f "$ROOT/.env.local" ]; then grep -v -e '^DATA_APP_MB_URL=' -e '^DATA_APP_MB_API_KEY=' "$ROOT/.env.local"; fi
  printf 'DATA_APP_MB_URL=%s\nDATA_APP_MB_API_KEY=%s\n' "<url>" "$KEY"; } > "$ROOT/.env.local.tmp" &&
mv "$ROOT/.env.local.tmp" "$ROOT/.env.local" && chmod 600 "$ROOT/.env.local" && echo "creds written"

切勿在其输出会返回给你的环境中运行 rde credentials --api-key，也绝不要打印 .env.local。该密钥归 rde 管理员所有，因此开发预览可以查看所有表；如果应用面向的受众范围较窄，请说明这一点。

4. 仓库是唯一可信来源

数据应用只能通过远程同步存在，因此这里这是必须满足的要求，而非建议：如果尚未设置，section 2 会设置远程同步；这是 rde 主动提出远程同步的唯一场景，因为用户要求构建应用。将其记录在 STATE.md 中，标记为 remote_sync。在应用之外，只有已配置远程同步时，rde 技能才会提出同步。

该 bundle 通过 ID 和类型化架构引用 Metabase 对象。基于仅存在于实例中的内容构建的应用只能在该实例中运行，无法在其他地方运行：将仓库导入另一个实例时，应用会被导入，但它读取的定义不会随之导入，因此查询会失败。所以，应用读取的所有内容都必须在构建应用前进入仓库，构建过程中创建的所有内容也都要和应用一起放进仓库。

• 应用可以读取的内容。 Library 中已发布的表及其字段元数据、度量和分段；归档在 Library 的 Metrics 集合中的指标；应用会运行其操作的模型（位于已同步集合中）。除此之外，不能读取其他内容。
• “在仓库中”的含义。 Library 集合包含 is_remote_synced: true（在 mb git-sync status --json 中显示为 synced_collections），内容已导出，并且 git pull 已将其拉入工作树：文件确实位于 databases/…/tables/<table>/ 和 collections/… 下，且已经检查确认，而非仅凭假设。
• 度量和分段需要已发布的表（参见 rde 技能的 references/remote-sync.md 中的 “What belongs in git”）。如果 Library 不可用（mb library get --json 失败），则将指标归档到已同步的集合中，并说明度量和分段无法纳入仓库。
• 应用自身的集合也要同步。 npm run build 会运行 sync-resources，将每个 queries/ 定义保存为 Data App: <slug> 中的问题。将该集合标记为与应用同步；每次构建创建或更改问题后，mb git-sync dirty --json 都会将其列出，以便导出。如果问题始终没有出现在其中，就在交接说明中如实说明，而不要尝试绕过这一限制。
• 架构范围。 仅根据 Library 范围生成 metabase.data.ts：使用 include-data-library=true、include-metric-library=true 或 library-collections=<ids>；如果应用会运行操作，则还需使用 include-models=true。绝不能使用 database=<id>：它会直接读取实例中的表，无论这些表是否已同步；这正是导致应用基于仓库中不存在的内容构建的原因。
• 构建过程中发现缺少实体（度量、分段、指标、已发布的表、操作）时，应回到 rde 技能：在 Library 中创建该实体，通过其关卡，完成同步（sections 5 和 6），执行 git pull，重新生成架构，然后继续。绝不能为了让 UI 能继续而临时创建实体。
• 在编写第一行应用代码之前，应用所需的每个实体都必须存在于根据 Library 范围生成的架构中，且对应文件必须位于工作树中。如果缺少任何实体，请停止并返回 rde。

5. 安全同步

远程同步不会合并任何内容，也不会解决冲突。实例端（每次导入或导出前要检查什么、先执行哪一步，以及未经用户同意绝不使用 --force）和暂存区交接：请参阅 rde 技能的 references/remote-sync.md 中的“每一步之前”和“暂存”。在这里，Metabase 导出后执行的 git push 也会被拒绝，而且有两个写入者会推送到同一个远程仓库：Metabase 导出和应用提交，因此要让它们步调一致：

• 工作树端。 应用的提交只涉及 data_apps/<slug>/；绝不手动编辑导出的 Metabase YAML。拉取 Metabase 导出前：git stash --include-untracked、git pull --ff-only、git stash pop。每次 git push 前：再次执行 git pull --ff-only。如果拉取无法快进，就停止：报告两边的历史记录，不要合并或强制推送。
• 交付顺序：每一步都从干净状态开始：npm run build（可能会创建应用问题）→ 导出实例的脏文件集（应用问题和任何新定义）→ 在工作树中暂存、拉取、恢复暂存内容 → 提交应用（包括 resources_metadata.json）→ 拉取、推送 → mb git-sync import → 打开 <url>/apps/<slug>。
• 分支。 实例只跟踪一个分支（mb git-sync status --json，branch）。只有在明确同意的情况下，才导出或推送到 main 或 master；否则执行 mb git-sync create-branch agent/<slug>，并将应用推送到同一个分支，让内容和应用一起发布。

6. 涉及同步的操作前先征求同意

每个同步步骤，包括每次 git push 到同步远程仓库，都必须事先获得批准；每个同步点都要单独确认：请参阅 rde 技能的 references/remote-sync.md 中的“每个同步步骤前都要征求同意”。用户说“这项任务剩余操作都可以”后，要记录这一同意，不必再次询问；如果用户没有明确同意剩余操作，则要在下一个同步点再次询问。

如果用户在构建前说“暂时不要”，唯一可行的路径是仅提供开发预览，并注明它只在此实例上运行，在导入该仓库的任何地方都会出错。在它读取的内容完成同步前，不要将任何内容推送到同步分支。

7. 交接

metabase-data-apps 技能为每个步骤提供了一份指南；应用代码请遵循相应指南，但第 4 至 6 节优先：

步骤	metabase-data-apps 中的指南
还没有应用：创建、搭建脚手架、设置	setup/setup.md
应用读取 Metabase 表、指标、度量或分组（生成的 metabase.data.ts）	semantic-layer/semantic-layer.md，并使用第 4 节中的 Library 范围
多个页面	routing/routing.md
写入操作：表单、更新、删除、已保存的操作	actions/actions.md

8. 应用背后的数据

应用读取语义层发布到 Library 的内容。如果应用要展示的某个数值尚无对应的指标或度量定义，应先返回 rde 技能（其语义层操作手册；如果来源是原始数据，则先清理表），然后遵循第 4 至 6 节将定义写入仓库，这样应用就能按 ID 查询定义，而不会在 queries/ 中重新推导。如果 rde 技能使用 ./.scratch/STATE.md，请在其中记录应用的 slug、读取的 ID、同步的集合以及每项同步决策。

9. 交付

设置指南以提交和推送结束；按照第 5 节的顺序，在第 6 节征求同意后执行。使用 rde 的本地远程仓库时，推送会进入 ~/.rde 中的裸仓库；随后，mb --profile $PROFILE git-sync import --json 会将应用导入 Metabase，应用可在 <url>/apps/<slug> 打开。交接时要说明同步了什么、同步到哪个分支，以及对应的提交。