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

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

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

前提条件​

• 一个已经将MCP服务器连接到Claude、Cursor或Claude Code等AI客户端的MotherDuck账户
• 共享组织级指南的权限（用于向整个组织发布指南）

使用主题组织指南​

主题是代理发现指南的有效方式，而不会浪费令牌。它不会预先加载所有指南，而是调用list_guides(topic)，代理会看到带指南计数的主题树，并深入查看与任务相关的主题。这称为渐进式披露，在以下情况下效果最佳：

• 选择描述性主题名称。代理仅根据名称决定是否打开revenue-billing，因此revenue-billing优于misc或team-docs。
• 保持结构易于遍历。少量命名良好的顶级主题，下面有1-2个级别，比深层或碎片化的树更容易导航。主题不要求唯一性——任意数量的指南可以共享一个主题。
• 将根目录保留给真正通用的指南。没有主题的指南在每个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');