motherduck-build-cfa-app

构建面向客户的分析应用

从这里开始：MotherDuck 服务是否处于活动状态？

使用处于活动状态的远程 MotherDuck MCP 服务或本地 MotherDuck 服务，检查范围内的数据库、架构、粒度、键和相关指标。复用已知上下文，并将探索范围限定为所请求的工作；默认不要扫描整个工作区。根据实际数据模型塑造结果。

根据请求或当前上下文确定目标。只有当歧义会实质性影响结果时才提问。没有服务时，使用提供的架构和明确的假设进行规划；不要暗示已进行实时验证。

默认服务方案

• 3 层 CFA 为默认方案：
  • 浏览器 -> 后端 API -> MotherDuck
• 将客户路由、连接选择、服务账户使用和嵌入会话创建保留在后端。
• 在以下情况下，可以使用嵌入式 Dive：
  • 需求为只读
  • 产品需要将实时 Dive 界面嵌入应用并交付
  • 应用侧的策略和 UX 控制有限
  • 后端能够创建嵌入会话，并将管理员令牌保存在服务器端
• 仅当工作负载较小、在浏览器端运行且为只读时，才可以使用 DuckDB-Wasm。
• 单一共享 tenant_id 过滤是后备方案，而非推荐方案。
• 经过筛选的 Share 会公开精选的表／视图子集。Share 上的安全视图会根据使用者身份添加行过滤、隐藏列和掩码（对于每个客户一个服务账户的方案，使用 current_user），因此一个数据库可以为数量适中的客户提供服务。当租户需要独立的计算资源、数据生命周期或合同隔离时，默认应为每个客户使用一个数据库。
• 使用 connection_timeout 限制后端连接等待时间，以便冷启动的 Duckling 能够进行故障转移，而不是让请求一直挂起。
• 嵌入式 Dive 为只读，且无法运行 Flights；应用内操作应通过后端 API 执行。
• 对于嵌入式 Dive，请验证 postMessage 的来源／类型／负载；initial_state 仅用于可序列化为 JSON 的 UI 状态；导航、导出和持久化策略应由宿主应用负责。

工作流

1. 检查可用的 MotherDuck 服务或提供的架构上下文。
2. 阅读相关指南，探索实际数据模型，并验证将用于支撑应用的受治理定义。
3. 选择服务模式：
   • 3 层应用
   • 嵌入式 Dive
   • 仅浏览器原型
4. 设计隔离模型：
   • 每个客户一个数据库
   • 每个工作负载或服务账户一个边界
5. 定义 API 契约，列明允许使用的指标、维度、筛选条件和客户边界。
6. 选择连接路径和读取扩展策略。
7. 制定实施计划、API 契约和发布顺序。

根据请求匹配执行方式：回答、审查或规划工作应返回所请求的架构产物；构建或更改工作则应创建所请求范围内的文件或服务，并对其进行验证。对于破坏性操作、未在请求中提出的外部写入，或实质性扩大范围的操作，应先征求同意。

当此技能生成原生 DuckDB（md:）连接时，使用 custom_user_agent=agent-skills/2.6.0(harness-<harness>;llm-<llm>) 为其添加标记。如果缺少元数据，则回退使用 harness-unknown 和 llm-unknown。

输出

对于完整项目，根据请求酌情涵盖以下内容：

• 推荐的服务架构
• 隔离模型
• 连接策略
• 首个实施切片
• 验证和发布计划

对于明确要求结构化 JSON 的请求，请阅读输出契约。否则，使用适合所请求交付物的格式。

参考资料

只阅读与任务相关的章节；这些内容是指导，而非必须遵循的固定流程。

• references/CFA_IMPLEMENTATION_GUIDE.md -- 后端实施、服务账户、路由和读取扩展示例
• references/CFA_ARCHITECTURE.md -- 架构比较、隔离模型和连接路径详情

示例

仅在运行随附示例或复现其验证过程时，阅读执行参考。

• customer_routing_example.py
• customer_routing_example.ts

相关技能

仅在缺少所需能力时加载相关技能；复用已建立的上下文。

• motherduck-connect -- 选择正确的 PG 端点或原生 DuckDB 路径
• motherduck-explore -- 在选择架构前检查实时数据库和架构
• motherduck-model-data -- 设计适合分析的按客户划分的表
• motherduck-query -- 验证服务查询和对延迟敏感的聚合
• motherduck-load-data -- 为面向客户的数据刷新构建摄取路径