Back to Details

motherduck-build-cfa-app

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Build a Customer-Facing Analytics App

构建面向客户的分析应用

Use this skill when the user is embedding analytics into a product for external users and needs a concrete serving architecture, not just a dashboard.
This is a use-case skill. It orchestrates 
motherduck-connect
, 
motherduck-explore
, 
motherduck-model-data
, 
motherduck-query
, and 
motherduck-load-data
.
当用户需要为外部用户在产品中嵌入分析功能，且需要具体的服务架构而非仅仪表盘时，可使用本技能。
这是一个用例技能，它协调
motherduck-connect
、
motherduck-explore
、
motherduck-model-data
、
motherduck-query
和
motherduck-load-data
等技能。

Start Here: Is a MotherDuck Server Active?

开始：是否有活跃的MotherDuck服务器？

Always determine this first.
  • If a remote MotherDuck MCP server or local MotherDuck server is active, use it.
  • If the user has not said which database backs the project, ask for the target database or workspace before designing the app.
  • Then inspect the live data model:
    • databases and schemas
    • tables and views
    • columns and types
    • join keys
    • time dimensions
    • core serving metrics
  • Use that discovery to shape the serving pattern, tenant boundaries, and example code.
Do not jump straight to an architecture diagram if live data discovery is available.
If no server is active, ask for a representative schema excerpt or table list and keep assumptions explicit.
首先务必确认这一点。
  • 如果远程MotherDuck MCP服务器或本地MotherDuck服务器处于活跃状态，请直接使用它。
  • 如果用户未说明项目使用的数据库，请先询问目标数据库或工作区，再进行应用设计。
  • 随后检查实时数据模型：
    • 数据库与模式
    • 表与视图
    • 列与类型
    • 连接键
    • 时间维度
    • 核心服务指标
  • 利用这些发现结果确定服务模式、租户边界和示例代码。
如果可以进行实时数据发现，请勿直接跳到架构图环节。
如果没有活跃服务器，请用户提供代表性的模式片段或表列表，并明确说明假设条件。

Use This Skill When

适用场景

  • The user needs embedded or product-facing analytics.
  • Tenant isolation or blast radius matters.
  • Read concurrency and latency matter.
  • The project needs a backend contract, not just a Dive.
  • The requirement is stronger than an internal dashboard or a read-only embed.
  • 用户需要嵌入式或面向产品的分析功能。
  • 租户隔离或影响范围至关重要。
  • 读取并发能力和延迟性很重要。
  • 项目需要后端契约，而非仅Dive功能。
  • 需求比内部仪表盘或只读嵌入更复杂。

Default Serving Choices

默认服务选择

  • 3-tier CFA is the default:
    • browser -> backend API -> MotherDuck
  • Keep customer routing, connection selection, service-account usage, and embed-session creation on the backend.
  • Embedded Dives are acceptable when:
    • the requirement is read-only
    • the product needs a live Dive surface shipped into an app
    • app-side policy and UX control are limited
    • a backend can create embed sessions and keep admin tokens server-side
  • DuckDB-Wasm is acceptable only for small, browser-side, read-only workloads.
  • Single shared tenant_id filtering is the fallback, not the recommendation.
  • 默认采用三层CFA架构：
    • 浏览器 -> 后端API -> MotherDuck
  • 将客户路由、连接选择、服务账户使用和嵌入会话创建逻辑放在后端。
  • 在以下情况下可使用嵌入式Dive：
    • 需求为只读
    • 产品需要将实时Dive界面集成到应用中
    • 应用端的策略和UX控制有限
    • 后端可创建嵌入会话并在服务器端保存管理员令牌
  • DuckDB-Wasm仅适用于小型、浏览器端的只读工作负载。
  • 单一共享tenant_id过滤是备选方案，而非推荐方案。

Workflow

工作流程

  1. Confirm whether live MotherDuck discovery is available.
  2. Explore the actual data model that will back the app.
  3. Choose the serving pattern:
    • 3-tier app
    • embedded Dive
    • browser-only prototype
  4. Design the isolation model:
    • per customer database
    • per workload or service-account boundary
  5. Define the API contract with allowlisted metrics, dimensions, filters, and customer boundaries.
  6. Choose the connection path and read-scaling posture.
  7. Produce the implementation plan, API contract, and rollout sequence.
When this skill produces a native DuckDB (
md:
) connection, watermark it with 
custom_user_agent=agent-skills/2.1.0(harness-<harness>;llm-<llm>)
. If metadata is missing, fall back to 
harness-unknown
and 
llm-unknown
.
  1. 确认是否可以进行实时MotherDuck数据发现。
  2. 探索为应用提供支撑的实际数据模型。
  3. 选择服务模式：
    • 三层应用
    • 嵌入式Dive
    • 纯浏览器原型
  4. 设计隔离模型：
    • 每个客户对应独立数据库
    • 按工作负载或服务账户划分边界
  5. 定义API契约，包含允许的指标、维度、过滤器和客户边界。
  6. 选择连接路径和读取扩展策略。
  7. 生成实施计划、API契约和部署顺序。
当本技能生成原生DuckDB（
md:
）连接时，需添加水印
custom_user_agent=agent-skills/2.1.0(harness-<harness>;llm-<llm>)
。如果元数据缺失，则默认使用
harness-unknown
和
llm-unknown
。

Output

输出

The output of this skill should be:
  • a recommended serving architecture
  • the isolation model
  • the connection strategy
  • the first implementation slice
  • the validation and rollout plan
If the caller explicitly asks for structured JSON, return raw JSON only with no Markdown fences or prose before/after it. This is mainly for automated tests, regression checks, or downstream tooling that needs a stable machine-readable shape. Normal human-facing use of the skill can stay in prose unless JSON is explicitly requested.
Use this exact top-level shape when JSON is requested:
json
{
  "summary": {},
  "assumptions": [],
  "implementation_plan": [],
  "validation_plan": [],
  "risks": []
}
本技能的输出应包含：
  • 推荐的服务架构
  • 隔离模型
  • 连接策略
  • 首个实施切片
  • 验证与部署计划
如果调用者明确要求结构化JSON，则仅返回原始JSON，前后不要添加Markdown围栏或说明文字。 这主要用于自动化测试、回归检查或需要稳定机器可读格式的下游工具。除非明确要求JSON，否则面向普通用户的技能输出可采用 prose 格式。
当要求返回JSON时，请使用以下顶层结构：
json
{
  "summary": {},
  "assumptions": [],
  "implementation_plan": [],
  "validation_plan": [],
  "risks": []
}

References

参考资料

  • references/CFA_IMPLEMENTATION_GUIDE.md
    -- preserved detailed implementation content that used to live in this skill
  • references/CFA_ARCHITECTURE.md
    -- architecture comparison, isolation model, and connection-path detail
  • references/CFA_IMPLEMENTATION_GUIDE.md
    -- 保留了原属于本技能的详细实施内容
  • references/CFA_ARCHITECTURE.md
    -- 架构对比、隔离模型和连接路径细节

Runnable Artifact

可运行工件

  • artifacts/customer_routing_example.py
    -- MotherDuck-backed Python example showing per-customer routing with separate database namespaces
  • artifacts/customer_routing_example.ts
    -- TypeScript companion artifact with the same routing contract and output shape
Run it with:
bash
uv run --with duckdb python skills/motherduck-build-cfa-app/artifacts/customer_routing_example.py
Run the same artifact against temporary MotherDuck databases:
bash
MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
uv run --with duckdb python skills/motherduck-build-cfa-app/artifacts/customer_routing_example.py
Validate the TypeScript companion artifact:
bash
uv run scripts/test_typescript_artifacts.py
  • artifacts/customer_routing_example.py
    -- 基于MotherDuck的Python示例，展示如何通过独立数据库命名空间实现按客户路由
  • artifacts/customer_routing_example.ts
    -- TypeScript配套工件，具有相同的路由契约和输出格式
运行方式：
bash
uv run --with duckdb python skills/motherduck-build-cfa-app/artifacts/customer_routing_example.py
针对临时MotherDuck数据库运行同一工件：
bash
MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
uv run --with duckdb python skills/motherduck-build-cfa-app/artifacts/customer_routing_example.py
验证TypeScript配套工件：
bash
uv run scripts/test_typescript_artifacts.py

Related Skills

相关技能

  • motherduck-connect
    -- choose the correct PG endpoint or native DuckDB path
  • motherduck-explore
    -- inspect the live database and schema before choosing an architecture
  • motherduck-model-data
    -- design analytics-ready per-customer tables
  • motherduck-query
    -- validate serving queries and latency-sensitive aggregations
  • motherduck-load-data
    -- build ingestion paths for customer-facing data refresh
  • motherduck-connect
    -- 选择正确的PG端点或原生DuckDB路径
  • motherduck-explore
    -- 在选择架构前检查实时数据库和模式
  • motherduck-model-data
    -- 设计适用于分析场景的按客户划分的表
  • motherduck-query
    -- 验证服务查询和对延迟敏感的聚合操作
  • motherduck-load-data
    -- 构建面向客户的数据刷新 ingestion 路径