用途:该技能用于通过 MotherDuck 控制平面 REST API 管理服务账号、令牌、Duckling 配置、活动账号信息以及 Dive 嵌入会话。SQL 与数据平面查询不走 REST API,而应通过数据库连接完成。
主要能力:创建服务账号(POST /v1/users)、创建服务账号令牌、查看活动账号、调整 Duckling 的 read_write 与 read_scaling 配置、生成 Dive 嵌入会话。默认基址为 https://api.motherduck.com,使用 Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN} 认证,管理员读写令牌须保存在后端管理的密钥中,禁止使用 read-scaling 令牌做管理操作。
使用方式:先判断任务类型(账号开通、令牌管理、Duckling 规格、活动账号检查或 Dive 嵌入),从环境解析管理员令牌并确定目标用户名或 dive_id。配置变更采用先读后写;修改 Duckling 配置时先读当前配置,再同时提交 read_write 与 read_scaling。令牌权限需先核对:用户可为自身创建令牌,管理员可为服务账号创建令牌,但不能通过 API 为其他非服务账号成员创建令牌。若已连接 MotherDuck MCP,优先使用其管理工具,先调用 get_user_admin_guide。
适用场景:组织管理员进行账号与令牌治理、Duckling 规格调整、Dive 嵌入会话签发等控制平面操作。
限制与注意:以当前官方文档或 https://api.motherduck.com/docs/specs 的 OpenAPI 规范为准,端点可用性、预览状态、令牌字段与角色要求仅在规范或文档支持时才视为当前有效。切勿在日志、浏览器代码、客户端包或提交文件中暴露生成的访问令牌。删除用户会永久删除该用户及其全部数据,破坏性删除须经用户确认。Dive 嵌入的 initial_state 须可 JSON 序列化并符合文档大小限制,iframe 状态、导航与导出消息需在宿主应用中校验。API 错误应按状态码与响应体如实呈现,不得用成功形态的兜底掩盖 400、401、403、404 或 500。账号注册流程与组织管理 REST API 相互独立,不得因缺少管理员令牌而创建账号。相关技能包括 motherduck-query、motherduck-connect、motherduck-security-governance 与 motherduck-create-dive。