motherduck-manage-guides

管理 MotherDuck 指南

权威来源

• 优先参考最新的 MotherDuck 指南文档和 MCP 工具说明。
• 通过 MCP 执行分析查询时，先调用 get_query_guide，再编写 SQL；随后只遍历相关主题和指南。
• get_dive_guide 和 get_flight_guide 会自动包含保留的 dives 和 flights 主题摘要；除非需要更深入的上下文，否则不要单独加载这些主题。

默认原则

• 仅当指导内容适用于广泛场景时，才保留一份简短的根级导览指南。将特定领域知识放在浅层、描述性主题下。
• 新指南默认设置为 access = 'user'。组织可见性需要明确请求和所需的管理员权限；使用 set_guide_access（MCP）或在 motherduck guide push 中使用 --access 来更改。
• 将 Flights 创建的表记录在 data-sources 主题下（而非用于存放编写规范的 flights 主题）：包括来源、用途、粒度、关键列、转换、刷新行为和注意事项，并引用相关表、创建该表的 Flight 以及使用该表的 Dive。如果该表的数据库拥有共享，则使用 organization 访问权限；否则使用 user。
• 每份指南围绕一个连贯的主题编写，并采用有区分度的标题和描述。优先列出规则、经过测试的 SQL 和明确指出的陷阱。
• 将引用附加到指南所涉及的数据库、共享、架构、表、列、Dives、Flights 或其他指南，以便 Agent 在恰当的时机发现这些内容。
• 在将指南作为可信内容提供之前，先根据实时工作区验证引用对象和可执行 SQL。
• 使用版本注释说明指导内容变更的原因。更新前先阅读现有内容，避免覆盖并发修改。
• 如果可以使用 shell，且指南应存放在 Git 中或像代码一样接受审查，请使用 motherduck guide（参见 motherduck-cli）：在本地编辑 guide.md，使用 --version-description 执行 push，并将提交 SHA 作为 --external-id 传入，以便每个版本都能追溯到相应变更。

工作流

1. 检查 get_query_guide 或 list_guides，了解可见的主题树并避免重复。
2. 起草变更前，先阅读相关指南版本和引用对象。
3. 选择范围最窄且有用的主题；仅在组织级导览中将主题留空。
4. 起草简洁的 Markdown，将业务术语对应到准确的目录对象和经过验证的 SQL。
5. 对于创建或更新请求，通过 MCP 或文档中说明的 SQL 函数应用变更，并回读确认。
6. 验证元数据、访问权限、引用、当前版本和变更注释。对于查询任务，遵循指南，并根据实时架构验证最终 SQL。

对于回答、审查或规划请求，只需检查并起草，不要创建或修改指南。对于明确的创建或更新请求，执行范围内的变更并进行验证；删除内容或将可见范围扩大到授权受众之外之前，应先征求确认。明确的组织发布请求即表示已授权面向该受众发布，但仍需具备管理员权限。

参考资料

只阅读当前任务所需的参考资料章节。

• 阅读 references/GUIDES_PLAYBOOK.md，了解主题设计、访问权限治理、引用、MCP/SQL 操作、版本管理和质量检查。

相关技能

仅在缺少相应能力时加载相关技能；重用已有上下文。

• motherduck-explore：验证引用的目录对象
• motherduck-query：测试 SQL 并执行遵循指南的分析
• motherduck-create-dive 和 motherduck-create-flight：了解保留主题的规范
• motherduck-security-governance：了解组织可见性和权限边界