SuperAPI AI 工具集

motherduck-build-cfa-app

数据与分析

查看项目

更新于 10-16 01:19

技能介绍

用途:该技能面向“客户可见分析应用(CFA,Customer-Facing Analytics)”的构建与规划,帮助把 MotherDuck 分析能力嵌入到面向客户的产品中,重点是租户隔离、后端路由与 Serving API 设计。

主要能力与默认方案:默认采用三层架构——browser -> backend API -> MotherDuck,客户路由、连接选择、服务账号使用以及 embed 会话创建都保留在后端。嵌入式 Dive 在满足只读、需要把实时 Dive 界面交付到应用、应用侧策略与 UX 控制有限、且后端能创建 embed 会话并把 admin token 留在服务端时可用。DuckDB-Wasm 仅适用于小型、浏览器侧、只读的工作负载。单一共享 tenant_id 过滤只是兜底方案,并非推荐做法;过滤后的 Share 可向单一受众暴露精选表/视图子集,但它不是行级租户隔离,不同受众需要独立 Share 或更强的结构性边界。

使用方式与流程:先使用可用的远程 MotherDuck MCP 服务器或本地 MotherDuck 服务器检查范围内的数据库、schema、粒度、键与相关指标,复用已知上下文,不要默认扫描整个工作区;若没有服务器,则依据提供的 schema 和明确假设做规划,不要暗示已完成实时验证。随后阅读相关 Guides、探索实际数据模型并验证将支撑应用的受治理定义;选择服务模式(三层应用、嵌入式 Dive、纯浏览器原型);设计隔离模型(按客户数据库、按工作负载或服务账号边界);定义 API 契约(允许列出的指标、维度、过滤条件和客户边界);确定连接路径与读取扩展姿态;最后产出实施计划、API 契约和上线顺序。

限制与注意事项:destructive 操作、未请求的外部写入或重大范围扩展前需先询问。嵌入式 Dive 需校验 postMessage 的 origin/type/payload,initial_state 仅限可 JSON 序列化的 UI 状态,导航、导出与持久化策略留在宿主应用。产生原生 DuckDB(md:)连接时需以 custom_user_agent=agent-skills/2.6.0(harness-<harness>;llm-<llm>) 标记;元数据缺失时回退为 harness-unknown 与 llm-unknown。

交付物:完整任务需覆盖推荐的服务架构、隔离模型、连接策略、首个实现切片及验证与上线计划;显式结构化 JSON 请求请读取输出契约,否则使用契合所需交付物的格式。参考资料包括 CFA_IMPLEMENTATION_GUIDE.md(后端实现、服务账号、路由与读取扩展示例)与 CFA_ARCHITECTURE.md(架构对比、隔离模型与连接路径细节),示例有 customer_routing_example.py 与 customer_routing_example.ts。相关技能包括 motherduck-connect、motherduck-explore、motherduck-model-data、motherduck-query、motherduck-load-data,仅在缺少能力时按需加载。