analytics

analytics

GrowthBook 产品分析、分析仪表板和指标目录的领域路由器。工作流位于 references/ 中。阅读此路由器，选择一个工作流，然后阅读对应文件并按其中说明操作。

Analytics 使用 v1 API — 使用 /api/v1/product-analytics/search、/columns 和 /column-values 进行发现；使用指标、事实表、数据源和漏斗的 /api/v1/product-analytics/*-exploration 端点生成图表；使用 /api/v1/product-analytics/explorations/:id 轮询；使用 /dashboards 访问已保存的图表页面（创建除外，创建使用 POST /api/v2/dashboards；v1 创建接口已弃用）；使用 /fact-metrics 和 /fact-tables 访问目录。该 API 还提供 SQL 探索，但此技能不会构造或执行任意 SQL 探索负载。

所有 API 调用都通过随附的辅助工具进行。在 Claude Code 插件安装中，它位于 ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call（插件根目录）。通过 npx skills install 安装时，它位于相对于此技能目录的 scripts/gb-call。解析一次该路径，并在引用示例中出现 gb-call 时替换为该路径；不要假设 gb-call 位于 PATH 中。它会先从环境中读取 GB_API_KEY，然后回退到 ~/.config/growthbook/.env（由 gb-setup 写入）；环境变量优先。

当工作流需要根据相对根路径构造 GrowthBook UI 链接时，支持 shell 的运行时应在每次对话中调用一次 gb-call app-origin，并在工作流和领域交接期间保留返回的可信来源，然后将其添加到每个路径前。如果上下文中已有该来源，则重复使用；不要为每个链接都调用一次命令。已知可信应用来源的嵌入式适配器或 MCP 适配器可以直接解析路径。切勿从 GB_API_URL 推导应用来源；如果 app-origin 因自托管配置不完整而拒绝执行，请转至 gb-setup。API 返回的 explorationUrl 值已经是完整链接，必须原样使用。

选择工作流

阅读此文档	用户希望
references/metric-search.md	浏览、查找或审核指标和事实表——清单、特定定义，或“我可以绘制什么图表”的初步梳理（只读）
references/metric-create.md	创建事实指标，必要时先创建其底层事实表（会写入配置）
references/analytics-explore.md	实际运行图表，并报告数据以及深层链接
references/dashboard-create.md	构建新仪表板——将多个图表保存在同一页面上（会写入仪表板）
references/dashboard-edit.md	修改现有仪表板：添加或移除图表、替换指标、更改时间范围、重命名
references/sql-query.md	在没有指标或探索配置能回答问题时，针对数据仓库运行临时 SQL（最后手段）

当用户提到一个你尚未解析的指标时，先阅读 metric-search.md。它会为 analytics-explore 或 metric-create 提供稳定的定义。如果用户已经明确指定了具体指标，只想查看数据，则直接进入 analytics-explore.md。

一个图表还是多个？单个问题使用 analytics-explore 生成一个图表。“跟踪”“监控”“报告”，或需要一起关注两个或更多事项，意味着要创建仪表板。根据仪表板是否已存在来选择：尚无 ID 时使用 dashboard-create，已有 ID 时使用 dashboard-edit。

仅当现有指标或探索配置无法回答问题时，才使用 sql-query.md——例如自定义联接、未建模的表，或探索配置无法表达的聚合。

通用约定

• 仅事实指标可以绘制图表。 fact__... ID 可在 Product Analytics 中使用；/api/v1/metrics 中的旧版 met_... 指标虽可用于实验，但无法绘制图表。绝不要承诺可以为这类指标绘制图表。
• 探索限定于数据源，且数据源必须是 SQL 数据仓库。 Mixpanel 和 Google Analytics 数据源无法运行探索。
• 在工作流之间传递 ID，而不是显示名称。 名称并非唯一。事实指标 ID 始终以 fact__ 开头；事实表 ID 默认以 ftb_... 开头，但也可以自定义，因此不要按此前缀筛选。
• 每个 ID 都必须来自查询结果或用户的 @ 提及，绝不要自行构造。 有些 ID 可读性很强（fact__demo-d7-purchase-retention），容易让人猜成 fact__AverageOrderValue；这类猜测不会解析出任何结果，而且错误出现得既迟又隐晦。
• 先发现，再构造。 使用 Product Analytics 搜索和列查询，并在使用任何具体筛选值或拆分值之前调用列值查询。绝不要猜测值。
• 创建前先检查。 如果已有含义相同且 official: true 的指标，优先使用它，而不是添加重复指标。
• 探索 POST 返回 200 不一定表示成功。 根据 exploration.status 分支处理；按 ID 轮询状态为 running 的探索，显示 error，并注意 cache=required 可能返回 exploration: null。
• 谨慎处理工作流端点的 404。 /product-analytics/search 返回 404，表示服务端版本早于这些端点。/columns、/column-values 或 /explorations/:id 返回 404，也可能表示资源不存在或无法访问。显示错误并停止；绝不要尝试绕过访问检查、改用未公开的端点，或重新 POST 正在运行的探索。
• 数值洞察应使用返回的完整结果行。 不要根据图表预览、截断的摘要或配置推断数值。
• 每轮用户对话最多成功生成一张图表。 允许进行发现、轮询，以及一次空结果重试；一旦成功生成一项非空探索结果，除非用户在后续轮次明确要求另一张图表，否则应根据该结果作答。
• 始终为每个 dataset.values[] 条目显式设置 unit——只有这一层接受该字段；在配置本身设置 unit 会被拒绝。对于指标，严格遵循 /columns 的结果：当 metrics[].needsUnit 为 true 时，选择返回的 userIdTypes 条目；为 false 时，默认设为 null。unit 是标识符类型，绝不是 currency 这样的值格式。服务端不会为缺失的 unit 补默认值。
• 日期范围的 predefined 是封闭列表，所有出现该字段的地方均如此： today、yesterday、last7Days、last30Days、last90Days、last12Months、lastCalendarYear、customLookback、customDateRange。任何其他名称都会被拒绝，因此列表以外的所有时间范围都必须使用 customLookback，并设置 lookbackValue 和 lookbackUnit（hour、day、week、month）。
• dimensionType 是封闭集合，且不包含 "dimension"： date、dynamic、static、slice。目前仅支持前两种——日期轴应为 { "dimensionType": "date", "column": null, "dateGranularity": "auto" }，按列拆分应为 { "dimensionType": "dynamic", "column": "browser", "maxValues": 5 }。把字段命名为你想要分组的内容，正是验证器会拒绝的猜法。
• 绝不要原样重发被拒绝的调用。 400 错误是确定性的：相同请求体会产生相同错误，因此如果重试时没有修改消息指出的字段，只会浪费用户的对话轮次。读取 body.message，准确修正其中指出的内容，然后再发送一次。如果消息未说明有效值，或者同一字段被拒绝两次，就此停止——说明哪个字段失败以及你尝试了什么，然后询问用户，不要再猜第三次。询问该字段：验证错误会指出它拒绝的字段；询问其他字段（例如列名或指标选择）无法解决问题，只会导致收到答复后同一调用再次失败。
• 调整图表样式无需额外成本。 缓存匹配会忽略 chartType，因此同一查询使用不同图表类型会命中缓存。绝不要仅为调整样式而重新查询。
• 仪表板的图表区块包含 config，不包含结果。 创建和更新调用都会在服务端运行每张图表，因此绝不要先 POST 探索，仅为了获取图块所需的 ID。
• 更新会替换仪表板的整个区块列表。 写入仪表板的同一轮对话中，应先读取该仪表板，并列出要保留的每个图块；但对于未更改的图块，应使用 { "id": "dshblk_…" } 传递，而不是完整复制；每个 ID 最多列出一次。
• 只有用户提出要求时才更改仪表板的 owner。 调用 POST /api/v2/dashboards 创建时不设置 owner，默认使用 API 密钥所属用户，除非用户指定了其他人。除非用户要求重新分配仪表板，否则绝不要在更新请求体中填写 owner 或 ownerEmail。对于管理员，多余的 owner 会悄然将仪表板转交给其他人。
• **仪表板不像指标和探索那样限定于某个数据源，**但其中的每张图表都限定于数据源。

只读与写入

metric-search 严格只读。analytics-explore 会运行数据仓库查询，但不会更改 GrowthBook 配置——它不会创建指标、事实表或仪表板。sql-query 也类似：它不会修改数据仓库中的数据，但会执行可能成本高昂的查询，并根据查询结果保存一个 GrowthBook 探索对象。metric-create 会写入组织可见的事实表和事实指标定义，dashboard-create / dashboard-edit 会写入仪表板；这三种工具在每次写入前都必须用通俗语言概述变更，并征得确认。

请注意，探索会执行真实的数据仓库查询，因此即使不写入任何内容，也会耗费用户的时间和金钱；而写入仪表板时，每个图表区块都会运行一次查询。请按照参考文件中的说明限定范围，不要进行推测性的扩展查询。

移交

• experiments 技能——当问题涉及 A/B 测试结果解读，或图表显示出值得测试的情况时。
• feature-flags 技能——当用户转而询问如何发布或为数据所涉及的内容设置门控时。
• gb-setup——当 gb-call 报告 GB_API_KEY 缺失或无效时。