motherduck-create-dive

创建和管理 MotherDuck Dive

主要参考来源

• 优先查阅最新的 MotherDuck Dive 文档。
• **不可妥协的顺序：**如果 MotherDuck MCP 可用，必须先调用 get_dive_guide，然后再编写 Dive 代码；每次调用 save_dive 或 update_dive 前也必须先调用该工具。该指南定义了当前的组件 API 和运行时库。
• get_dive_guide 还会提供保留的 dives 指南主题中的相关约定。若这些约定与用户的明确要求不冲突，请遵循。
• 将经过认可的 Dives 示例仓库用作本地预览、Dives 即代码的目录布局、元数据、CI 预览和部署脚本的参考实现。
• 如果用户希望采用可通过脚本编写、以 SQL 为原生方式的创建／读取／更新／删除工作流，而非使用 MCP 工具，请使用 Dives SQL 函数。
• 将普通 Dives 和嵌入式 Dives 分开处理。承诺推出嵌入式 Dives 前，请确认当前套餐权益；不要沿用记忆中的套餐名称或可用性说明。

默认原则

• 首先判断任务类型：新建 Dive、编辑现有 Dive、Dives-as-code 工作流、团队共享或嵌入。
• 先使用 motherduck-explore 和 motherduck-query 验证底层 SQL 和架构；正确的查询是打造优质 Dive 的起点。
• Dive 查询应使用完整限定名称并以 SQL 为主；让 React 负责呈现，而不是重塑数据。
• 遵循组件契约：使用 React 和 useSQLQuery、默认导出、受支持的运行时库、明确处理加载、空数据和错误状态，且不在浏览器端存放密钥。
• 新建的 Dive 默认处于 Draft 状态。只有当所需交付内容包含发布时，才将验证通过的 Dive 升级为 Ready。只有管理员可以将 Dive 标记为 Endorsed；绝不要自行为 Agent 创建的 Dive 背书。
• 复用现有成果时，优先选择 Endorsed 的 Dive，其次选择 Ready 的 Dive。Archived 的 Dive 已退役，默认不会列入 Agent 列表，除非用户明确要求。
• 本地预览使用 REQUIRED_DATABASES 时，导出内容应保持单行，并在元数据或保存／更新输入中同步反映实际的共享依赖项。避免使用与现有数据库名称冲突的别名。
• 对现有 Dive 进行范围明确的编辑时，应保留其视觉风格。新建 Dive 时，应根据受众选择具体的主题方向。
• 每个可视化区块或交互界面优先使用一个查询，而不是使用一个用途过于宽泛的大型查询。
• 如果环境支持，保存前应在本地预览。
• 对于现有 Dive，在覆盖任何内容前，应先读取当前内容和版本元数据。MCP list_dives 会返回 current_version，read_dive 可以读取历史版本。针对性编辑应使用 edit_dive_content（精确文本替换），完整重写则使用 update_dive。
• 只有在用例需要时才添加导出控件：在查询结果上使用 exportAs，或使用 useExport hook（CSV、JSON、Parquet、XLSX），并由点击操作启动。不要创建 Blob URL、隐藏的锚点或 COPY TO 导出。
• Dive SQL 仅支持只读操作。对于审批记录、提交表单或刷新管道等操作，应通过按钮使用 useRunFlight 启动由 Dive 所有者控制的 Flight，并使用 useFlightRun 跟踪运行状态（来自 @motherduck/react-sql-query）。硬编码 Flight ID，仅传递字符串配置值；运行待处理时禁用控件，渲染 hook 的 error，并在运行成功后重新运行受影响的查询。查看者需要 run 授权：先建议授权对象，并仅在用户确认后授予。嵌入式 Dive 无法运行 Flight。
• 查看者可以在 Dive 标题栏中打开 AI Chat。它可以查看 Dive 的查询、数据和当前筛选条件，并能编辑 Dive，每次更改都会保留在版本历史中。清晰的区块标题、查询名称和 Dive 描述有助于提升回答质量。
• 如果产品需要通过后端创建嵌入会话来提供实时、只读的 Dive 界面，应优先选择嵌入式 Dive。若应用需要自定义 API 契约、写入功能、非 Dive 路由、租户策略执行或更丰富的授权，则改用 motherduck-build-cfa-app。
• 对于共享代码仓库或 CI/CD，应使用服务账户令牌，避免将 Dive 所有权绑定到某个个人用户。

工作流

1. 选择所需的交付路径：工作区 Dive、编辑现有内容、以代码形式管理 Dives、写回操作、共享或嵌入。仅执行该路径；图表请求本身并不授权共享、嵌入或写回。
2. 探索实时架构，并先验证核心 SQL。
3. 如果 MCP 可用，调用 get_dive_guide，然后设计故事、章节、交互和主题。
4. 构建或编辑 Dive 组件；尽可能使用本地预览／热重载。
5. 只有在查询、加载状态、所需资源和视觉行为均正确后，才调用 save_dive、update_dive 或进行部署。
6. 回读生成的 URL、版本和状态。如果所请求的交付包含发布，请通过具有写入权限的路径将已验证的 Draft 提升为 Ready。
7. 如果队友或应用用户需要访问权限，请检查三项：他们能否查看 Dive、每个 REQUIRED_DATABASES 条目是否都是他们有权读取的共享数据库，以及他们是否对 Dive 运行的每个 Flight 都拥有 run 授权。优先使用自有数据库的现有共享项（MD_INFORMATION_SCHEMA.OWNED_SHARES）。如果用户要求与整个组织共享 Dive 的数据，share_dive_data 会创建组织范围的共享项，并通过一次调用更新 Dive；对于受限受众，请使用 motherduck-share-data；对于应用用户，请使用嵌入会话流程。

对于回答、审查或规划请求，请在完成所要求的设计或代码产物后停止。对于创建、更新或部署请求，请通过预览和验证完成所请求且属于范围内的操作；如果请求未授权破坏性替换或范围更广的外部发布，请先询问。

参考资料

只阅读当前任务所需的参考章节。

• 阅读 references/DIVE_DESIGN_GUIDE.md，了解创作工作流、useSQLQuery 机制、以代码形式管理 Dives、编辑／版本历史、共享、嵌入、使用 Flights 写回、Agent Chat、SQL 函数、主题提示词、图表选择规则、加载／错误状态、布局模式和实现注意事项

相关技能

仅在缺少相应能力时加载相关技能；复用已有上下文。

• motherduck-explore：在可视化数据之前，发现实际使用的表、视图和维度
• motherduck-query：验证每个 Dive 章节将运行的 SQL
• motherduck-design-dive：移动优先布局、浅色／深色主题、筛选器界面、可复用组件和响应式 QA
• motherduck-build-dashboard：适用于实际需要组合多个章节来构建仪表板的任务
• motherduck-build-cfa-app：适用于需要为每位客户隔离数据或控制后端策略的完整产品界面
• motherduck-cli：适用于 Agent 拥有 Shell 且应将 Dive 源代码保存在本地文件中的情况
• motherduck-create-flight：创建写回按钮所运行的 Flight
• motherduck-manage-guides：管理可复用的个人或组织 Dive 规范