motherduck-create-dive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create and Manage MotherDuck Dives

创建与管理MotherDuck Dives

Use this skill when the user needs a persistent, shareable, editable Dive rather than a one-off chart. Dives are live React + SQL data apps inside MotherDuck; they can be built conversationally, edited from existing workspace content, managed as code, shared with teammates, or embedded in another application.

当用户需要一个持久化、可共享、可编辑的Dive而非一次性图表时，使用此技能。Dives是MotherDuck内的实时React + SQL数据应用；它们可以通过对话方式构建、从现有工作区内容编辑、以代码形式管理、与队友共享，或嵌入到其他应用程序中。

Source Of Truth

事实来源

Prefer current MotherDuck Dive docs first.
If MotherDuck MCP is available, call
```
get_dive_guide
```
before generating, saving, or updating a Dive.
Use the blessed Dives example repo as the reference implementation for local preview, Dives-as-code layout, metadata, CI previews, and deploy scripts.
Use Dives SQL functions when the user wants a scriptable SQL-native create/read/update/delete workflow instead of MCP tools.
Treat ordinary Dives and embedded Dives separately: current public materials say Dives are available on all plans, while embedding requires a Business plan.
Keep authoring, local-preview, required-resource, sharing, versioning, code-management, and embedding guidance aligned with current docs.

优先参考当前的MotherDuck Dive文档。
如果MotherDuck MCP可用，在生成、保存或更新Dive前调用
```
get_dive_guide
```
。
使用官方认可的Dives示例仓库作为本地预览、Dives-as-code布局、元数据、CI预览和部署脚本的参考实现。
当用户需要可脚本化的SQL原生增删改查工作流而非MCP工具时，使用Dives SQL函数。
将普通Dives和嵌入式Dives分开处理：当前公开资料显示所有套餐都可使用Dives，而嵌入功能需要Business套餐。
确保创作、本地预览、所需资源、共享、版本控制、代码管理和嵌入指南与当前文档保持一致。

Default Posture

默认准则

First classify the job: new Dive, existing Dive edit, Dives-as-code workflow, team sharing, or embedding.
Validate the underlying SQL and schema first with
```
motherduck-explore
```
and
```
motherduck-query
```
; a good Dive starts with a correct query.
Keep Dive queries fully qualified and SQL-heavy; let React handle presentation, not data reshaping.
Treat the component contract as React +
```
useSQLQuery
```
, a default export, supported runtime libraries, explicit loading/empty/error states, and no browser-side secrets.
When local preview uses
```
REQUIRED_DATABASES
```
, keep the export on one line and mirror the real share dependencies in metadata or save/update inputs. Avoid aliases that collide with existing database names.
Start from a named theme direction such as
```
Corporate Dashboard
```
,
```
Tufte Minimal
```
, or
```
FT Salmon
```
instead of vague visual prompts.
Prefer one query per visual section or interaction surface rather than one giant cross-purpose query.
Preview locally before saving when the environment supports it.
For existing Dives, read the current content and version metadata before overwriting anything. MCP
```
list_dives
```
returns
```
current_version
```
, and
```
read_dive
```
can fetch historical versions.
Treat embedded Dives as the first-choice path when a product needs a live read-only Dive surface with a backend-created embed session. Move to
```
motherduck-build-cfa-app
```
when the app needs custom API contracts, writes, non-Dive routing, tenant policy enforcement, or richer authorization.
For shared repos or CI/CD, use a service-account token so Dive ownership is not tied to one human user.

首先对任务进行分类：新建Dive、编辑现有Dive、Dives-as-code工作流、团队共享或嵌入。
先使用
```
motherduck-explore
```
和
```
motherduck-query
```
验证底层SQL和架构；优质Dive始于正确的查询。
保持Dive查询完全限定且以SQL为主；让React负责展示，而非数据重塑。
遵循组件约定：React +
```
useSQLQuery
```
、默认导出、支持的运行时库、明确的加载/空数据/错误状态，且不包含浏览器端密钥。
当本地预览使用
```
REQUIRED_DATABASES
```
时，将导出保持在一行，并在元数据或保存/更新输入中镜像真实的共享依赖关系。避免与现有数据库名称冲突的别名。
从明确的主题方向入手，例如
```
Corporate Dashboard
```
、
```
Tufte Minimal
```
或
```
FT Salmon
```
，而非模糊的视觉提示。
优先为每个可视化区域或交互界面设置一个查询，而非一个庞大的通用查询。
当环境支持时，先在本地预览再保存。
对于现有Dives，在覆盖任何内容前先读取当前内容和版本元数据。MCP的
```
list_dives
```
会返回
```
current_version
```
，
```
read_dive
```
可获取历史版本。
当产品需要一个由后端创建的嵌入会话的实时只读Dive界面时，优先选择嵌入式Dives路径。当应用需要自定义API契约、写入操作、非Dive路由、租户策略执行或更丰富的授权机制时，使用
```
motherduck-build-cfa-app
```
。
对于共享仓库或CI/CD，使用服务账户令牌，确保Dive所有权不绑定到单个用户。

Workflow

工作流程

Classify the delivery path: workspace Dive, edit existing Dive, Dives-as-code, share with teammates, or embed in an app.
Explore the live schema and validate the core SQL first.
Call
```
get_dive_guide
```
if MCP is available, then design the story, sections, interactions, and theme.
Build or edit the Dive component, using local preview/hot reload when possible.
Save, update, or deploy only after queries, loading states, required resources, and visual behavior are correct.
If teammates or application users need access, configure the underlying shares or embed-session flow explicitly.

确定交付路径：工作区Dive、编辑现有Dive、Dives-as-code、与队友共享或嵌入到应用中。
先探索实时架构并验证核心SQL。
如果MCP可用，调用
```
get_dive_guide
```
，然后设计叙事、板块、交互和主题。
构建或编辑Dive组件，尽可能使用本地预览/热重载。
仅在查询、加载状态、所需资源和视觉行为都正确后，再保存、更新或部署。
如果队友或应用用户需要访问，明确配置底层共享或嵌入会话流程。

Open Next

后续参考

```
references/DIVE_DESIGN_GUIDE.md
```
for authoring workflows,
```
useSQLQuery
```
mechanics, Dives-as-code, editing/version history, sharing, embedding, SQL functions, theming prompts, chart-selection rules, loading/error states, layout patterns, and implementation gotchas

```
references/DIVE_DESIGN_GUIDE.md
```
包含创作工作流、
```
useSQLQuery
```
机制、Dives-as-code、编辑/版本历史、共享、嵌入、SQL函数、主题提示、图表选择规则、加载/错误状态、布局模式和实现注意事项