MotherDuck用Guides补齐Data Agent看不到的业务上下文

预览

此功能处于预览阶段，可能会发生变化。

通过指南，您可以捕获从模式中不可见的领域知识：您的组织如何定义MRR、要连接哪些表、避免哪些列、数据中的常见陷阱，或者“客户”在您的工作领域中意味着什么。指南也适用于个人偏好：您的Dive风格、您的Flight约定、您希望结果格式化的方式。

指南是存储在MotherDuck中的Markdown文档，AI代理在处理您的数据之前会读取这些文档。您只需编写一次指南；之后，每个代理会话都会通过MCP服务器自动获取。无需在每个聊天中反复复制粘贴上下文。组织共享的指南使组织中的每个代理在相同的定义上保持一致；私有指南则个性化定制代理以适应您的工作方式。

前提条件​

• 拥有MotherDuck账户，并已连接MCP服务器到AI客户端，如Claude、Cursor或Claude Code。
• 拥有共享组织范围指南的权限（用于向整个组织发布指南）。

使用主题组织指南​

主题是让代理发现指南而不浪费令牌的有效方式。代理不会预先加载所有指南，而是调用list_guides(topic)，代理会看到带有指南数量的主题树，并钻取看起来与任务相关的主题。这称为渐进式披露，在您执行以下操作时效果最佳：

• 选择描述性强的主题名称。 代理仅根据名称决定是否打开revenue-billing，因此revenue-billing优于misc或team-docs。
• 保持结构易于遍历。 少量命名良好的顶级主题，每个主题下有一到两个层级，比深度或碎片化的树更容易导航。主题不具备唯一性——任意数量的指南都可以共享同一个主题。
• 将根主题保留给真正通用的指南。 没有主题的指南会在每个get_query_guide概览中单独列出：代理最容易找到，但会在每个会话中占用空间。仅在指南非常通用，不属于任何特定领域时，才将主题留空，例如公司描述、公司所在领域的独特属性、数据平台概述或组织范围的SQL约定。

- data-quality/ (1 guide)
- revenue-billing/ (2 guides)
- revenue-billing/forecasting/ (1 guide)
- "Data platform overview" — what lives where in our warehouse (organization, uuid: a1b2c3d4-...)

(no topic)              One orientation guide: the definitions an agent needs first,
                        per-schema notes, the join graph, and pointers to everything below
definitions/            A glossary of terms that maps common language to your data
<domain>/               How bundles of metrics are computed, one topic per area:
                        revenue-billing/, sales-funnel/, product-usage/
<database>/<schema>/    Information related to a specific database, schema, and so on

Create a Dive guide that says that I prefer dark-themed Dives with compact number formatting

Create an org-wide guide with topic "revenue-billing" that explains:
- MRR is calculated from the subscriptions table using status = 'active' and trial_end IS NULL
- ARR is MRR × 12
- The billing schema is in the billing database, main schema
- Never join subscriptions to invoices for revenue — use subscriptions directly

SELECT
  id,
  topic,
  current_version
FROM
  MD_CREATE_GUIDE (
    topic = 'revenue-billing',
    title = 'MRR and ARR Definitions',
    description = 'How monthly and annual recurring revenue are calculated',
    content = '
# MRR and ARR definitions

MRR is the sum of all active subscription amounts normalized to a monthly value.

Key rules:
- Use the subscriptions table, not invoices
- Filter to status = active
- Exclude trial subscriptions (trial_end IS NULL)
',
    access = 'user'
  );

What guides does my organization have?

SELECT id, topic, title, description, access FROM MD_LIST_GUIDES();

SELECT id, title FROM MD_LIST_GUIDES(topic = 'revenue-billing');

SELECT title, content
FROM MD_GET_GUIDE(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890');

Update the MRR guide to add a section on expansion MRR

SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  content = '...(full updated markdown)...',
  change_comment = 'Add expansion MRR section'
);

Rename billing.main.orders to billing.main.customer_orders in the MRR guide

SELECT topic, title
FROM MD_UPDATE_GUIDE_METADATA(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  topic = 'customer-orders',
  title = 'Customer Order Filters'
);

SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  "references" = [
    {
      'type': 'catalog',
      'url': 'md:billing',
      'schema': 'main',
      'table': 'subscriptions',
      'description': 'Primary source for subscription revenue data'
    },
    {
      'type': 'catalog',
      'url': 'md:billing',
      'schema': 'main',
      'table': 'subscriptions',
      'column': 'amount',
      'description': 'Monthly subscription amount in cents'
    }
  ]
);

SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
  "references" = [
    {
      'type': 'catalog',
      'url': 'md:_share/sample_data/23b0d623-1361-421d-ae77-62d701d471e6',
      'schema': 'hn',
      'table': 'hacker_news',
      'description': 'Hacker News sample data shared by MotherDuck'
    }
  ]
);

SELECT id, title
FROM MD_LIST_GUIDES(
  reference = {
    'type': 'catalog',
    'url': 'md:billing',
    'schema': 'main',
    'table': 'subscriptions'
  }
);

SELECT access
FROM MD_SET_GUIDE_ACCESS(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  access = 'organization'
);

SELECT success
FROM MD_DELETE_GUIDE(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890');