shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

FineBI 指标智能问数

FineBI 指标智能问数。当用户需要基于 FineBI 的模型指标集（数据集、表间关系、维度、度量、指标）进行「检索→指标集→指标→维度钻取→取数→结构化报告」的智能问数、指标口径查询、维度下钻、明细查询/清单探查或指标归因时使用。触发词：指标问数、查指标、FineBI 指标、指标口径、指标明细、明细查询、清单、排行、Top N、维度钻取、取数、指标血缘、问数分析、指标取值、趋势分析、分组对比、归因分析、排序、分组、趋势、下钻。

person作者: user_c2b88113hubcommunity
download下载资源包

FineBI 指标智能问数（finebi-metrics-qa）

围绕 FineBI 的「模型指标集」体系，按 FineBI 自身的分析思路做智能问数：先定位模型指标集、再确定指标、结合相关维度生成查询、校验口径时追溯血缘与明细，最终取数并输出结构化分析报告。

分析思路（四步方法论）

1. 渐进搜索

用户问数时有时会指定模型指标集，有时不会，据此分两条路径：

A. 用户指定了模型指标集

  • 直接用该指标集，跳到「确定指标/字段」环节。

B. 用户未指定模型指标集（先查全，再按需匹配）

  1. 先 finebi_search_resources 搜索所有候选模型指标集；
  2. 对每个候选指标集，finebi_get_metricset_config 一次性查全其完整结构（sections=["details","datasets","calculateFields","metrics"]），把「数据集、字段、计算字段、指标」都拿到；
  3. 按用户问题实际所需的对象去匹配、筛选：问题要的是指标（取值/趋势/分组/归因）就比对 metrics，要的是字段/计算字段（明细查询、排序、Top N）就比对 datasets[].fields[] 与 calculateFields；
  4. 若有多个候选指标集 → 让用户选择其中一个，不自动拍板；仅当唯一命中时才直接确定。

原则：先查全、再匹配，不按「问题类型」预判该查什么——避免因类型/字段归属判断偏差而漏掉真正需要的对象，导致选不到合适的指标集。

C. 定位指标集后：先判断业务场景

确定目标模型指标集后，先读它的 name、description、tags、extensionProperties 等元数据，判断该指标集属于什么业务场景（如零售连锁经营、商品销售、复购分析等），作为后续分析的业务上下文——而不是直接跳到取数。

2. 指标优先

  • 仅通过模型指标集中已有的指标来回答用户问题；
  • 不允许制造不存在的指标定义（不臆造字段、不凭空拼计算逻辑）；
  • 若用户问题不在已有指标范围内，明确提示用户「无法回答」，绝不兜底编造。

3. 校验前置（生成查询前先校验）

  • 生成查询描述时，维度必须在指标的相关维度范围内（以 finebi_get_metric_detail 返回的 related_dimensions 为准）；
  • 维度字段的过滤配置必须参考实际维度值（先 finebi_get_dimension_values 拿到真实取值，再设 filters）。

4. 整体过程

先搜模型指标集 → 确定指标 → 结合指标的相关维度生成最终指标查询；当需要校验指标计算过程时，根据数据集关系（relationships）以及指标的血缘（finebi_get_metric_lineage）确定指标的来源表与来源字段，展示指标血缘节点，并生成对应字段的明细查询（finebi_query_detail_data）。

问数场景（五大类）

智能问数按问题意图分为五类，其中「指标取值」与「明细查询」是两种不同形态，须区分对待：

| # | 场景 | 典型问法 | 返回形态 | 主要工具 | |---|------|---------|---------|---------| | ① | 明细查询 | 「单价排行前十的产品？」「毛利最低的门店名单？」 | 逐条明细记录、排序、Top N 清单 | finebi_query_detail_data | | ② | 指标取值 | 「上月销售额多少？」「19 年毛利率？」 | 聚合后的指标值（一个/一组汇总数） | finebi_query_metric_data | | ③ | 趋势分析 | 「近 6 个月销量走势？」 | 按时间维度展开的序列 | 时间维度钻取 + ①/② | | ④ | 分组对比 | 「各省门店销量？」「品类毛利对比？」 | 按维度分组聚合 | 维度钻取 + ② | | ⑤ | 归因异常 | 「为什么华东毛利下滑？」 | 变动贡献度结论 | 血缘 + 跨周期对比 |

关键区分：

  • 指标取值与「指标」绑定更紧，结果是汇总数；明细查询与「维度/字段」绑定更紧，结果是清单（排序、Top N、筛选）。
  • 明细查询同样遵守「校验前置」：先确定合法维度、参考实际维度值，再对明细字段排序/过滤；不得对不存在的字段排序。
  • 超出已有指标/字段范围，或需预测、处方类结论时，明确提示「无法回答」。

语义映射速查（务必遵守）

| 概念 | resource_type | itemType / type | 说明 | |------|--------------|------|------| | 模型指标集（metric set） | 67 | itemType=67 | 检索结果里指标集/模型均以 resourceType=67 出现；其 id 即 metricSetId，供 detail/query 工具使用 | | 指标（metric） | 65 | itemType=65 / data.type=65 | 聚合指标 aggregate=true / 明细指标 aggregate=false；检索结果会带 metricSetId 指向所属指标集 | | 维度（dimension） | 66 | itemType=66 / data.type=66 | value_type: modelField.type 32=number / 48=date / 其余 text | | 度量字段（measure） | — | businessType=2 | 数据集字段或计算字段中的度量 | | 维度字段 | — | businessType=1 | 数据集字段或计算字段中的维度字段 |

⚠️ 关键陷阱：finebi_search_resources 的 resource_type 参数枚举是 all/metric/dimension/metricset，但返回结果的 resourceType 字段值却是 67(指标集/模型)/65(指标)/66(维度) 三套编码，二者不是同一维度。定位指标集时：用 resource_type=metricset 搜索，但要从结果里取 resourceType=67 的项（其 id 即 metricSetId）；或直接搜指标，读其 metricSetId 字段反查指标集。

  • 聚合指标 aggregate=true：汇总方式已配置在指标自身（summary=true, summaryType=3=求和等），query_metric_data 直接查即可。
  • 明细指标 aggregate=false（summaryType=-1）：汇总需在数据源侧配置；查明细行用 finebi_query_detail_data。
  • 字段数据类型码：16=text、32=number、48=date。

背景知识：FineBI 元数据即业务背景

模型指标集在定义时，各层都可设置自身的描述、标签、扩展字段等元数据，它们是分析时必须优先读取的业务背景，无需在 WorkBuddy 侧另行维护：

| 层级 | 可读元数据 | 来源工具 | |------|-----------|---------| | 模型指标集 | description / tags / extensionProperties / publishPath | get_metricset_config(sections=["details"]) | | 数据集 | tags / extensionProperties / businessType(1=维度表,2=事实表) / originTable | get_metricset_config(sections=["datasets"]) | | 数据集字段 | tags / extensionProperties / businessType(1=维度,2=度量) | 同上 datasets[].fields[] | | 指标 | tags / extensionProperties / caliber 口径 | get_metric_detail | | 维度 | tags / extensionProperties / caliber 口径 / value_type | get_dimension_detail |

使用约定：

  • 定位指标集后，先读 details 的 description/tags，理解这个指标集是做什么业务的；
  • 读指标/维度时，同步看其 tags/extensionProperties 里的业务语义补充；
  • 这些元数据若为空（测试数据常见），说明业务方未填写，报告里如实标注「未配置业务描述」，不要臆造。

工具清单（mcp__finebi-metrics__*）

| 阶段 | 工具 | 用途 | |------|------|------| | 检索 | finebi_search_resources | 关键词搜指标/维度/指标集；resource_type=all/metric/dimension/metricset | | 指标集 | finebi_get_metricset_config | 指标集详情，sections: details/datasets/relationships/calculateFields/metrics | | 指标 | finebi_get_metric_detail | 单指标语义：caliber 口径、aggregate 类型、related_dimensions、tags/extensionProperties | | 指标血缘 | finebi_get_metric_lineage | 指标上游表/字段与下游依赖（影响分析/口径追溯） | | 维度 | finebi_get_dimension_detail | 单维度语义：caliber、value_type、related_metrics、tags/extensionProperties | | 维度血缘 | finebi_get_dimension_lineage | 维度上游表/字段与下游依赖 | | 维度取值 | finebi_get_dimension_values | 维度可选值（过滤前必查） | | 取数 | finebi_query_metric_data | 指标结果集（按维度分组/过滤） | | 明细 | finebi_query_detail_data | 明细行（仅明细指标/度量字段） | | 度量 | finebi_get_measure_detail | 度量字段详情 | | 连接 | check_finebi_connection | 检查 FineBI 连接状态 |

标准分析流程（对应四步方法论）

  1. 渐进搜索 · 定位指标集：用户指定指标集则直接采用；未指定则 finebi_search_resources(keyword, resource_type=metricset) 搜索所有候选指标集 → 对每个候选 finebi_get_metricset_config(sections=["details","datasets","calculateFields","metrics"]) 一次查全结构 → 按问题所需对象匹配（要指标比 metrics，要字段/计算字段比 datasets[].fields[] + calculateFields）→ 筛选合适指标集。多候选时让用户选择，唯一命中才直接确定。
    • 定位后先判断业务场景：读指标集的 name + description + tags + extensionProperties，判断它属于什么业务场景（如零售连锁经营、商品销售、复购分析等），作为后续分析的业务上下文。
  2. 确定指标：在目标指标集内，finebi_get_metric_detail 确认目标指标的 caliber 口径、aggregate 类型、related_dimensions。若用户问题所需指标不存在 → 提示无法回答，终止。
  3. 校验前置 · 确定维度：从 related_dimensions 中取合法维度 → finebi_get_dimension_detail 看 value_type → 需过滤时先 finebi_get_dimension_values 拿真实取值再设 filters。维度必须在相关维度范围内。
  4. 生成查询并取数：按场景选择——指标取值/趋势/分组/归因走 finebi_query_metric_data（聚合结果）；**明细查询（排序、Top N、清单）**走 finebi_query_detail_data（逐条明细），带 dimension_ids、filters、source、排序/分页参数。
  5. 口径校验（按需）：需校验指标计算过程时，用 finebi_get_metricset_config(sections=["relationships"]) 看数据集关系 + finebi_get_metric_lineage 定来源表/来源字段 → 展示血缘节点 → 用 finebi_query_detail_data 生成对应来源字段的明细查询。
  6. 结构化报告：按下方固定格式输出。

取数参数要点

  • finebi_query_metric_data(metric_set_id, metric_ids, dimension_ids?, filters?, source?, page_index?, page_size?)
  • filters（AND 组合）：field_id + op + values + value_type。text 用 in/contains/eq 等；number 用 between/eq/gt 等；date 用 before/after/between，值用 "YYYY-MM-DD"。
  • source（可选，需分组/汇总时提供每字段一项）：field_id、name、type(16/32/48)、resource_type(65/66)、aggregate。
    • 日期分组：group: {type}（type=6 年/7 季/8 月/17 年月…）。
    • 明细指标汇总：summary: {type}（3=求和…27=分位数，27 需 paras:["0.95"]）；仅明细指标生效，聚合指标忽略。
    • ⚠️ 实战经验：明细指标（aggregate=false）取数时，source 里必须显式给 summary，否则返回的数值是未汇总的原始值/无法正确聚合。

结构化报告格式（固定五段）

  1. 解释后的问题 + 时间/范围（复述用户意图）。
  2. 用到的指标/指标集（名称 + ID，附其 description/tags 业务背景）。
  3. 结果值（表格呈现：维度列 + 指标值；涨红跌绿按需）。
  4. 口径与血缘发现（若读了 caliber / lineage）。
  5. 局限说明（现有指标答不了、元数据未配置、口径未定等）。

风格：中文、表格化、突出「关键发现 + 可执行洞察」，接受直接技术纠错。

关于指标集 ID（不硬编码，每次动态检索）

MCP 中配置的 BI 服务会变化，指标集及其 ID 也会随之变化/失效（MetricSetAbsentException 即表示 ID 已不存在）。因此 skill 中不写死任何已知指标集，每次问数都从 finebi_search_resources 动态检索开始，用名称/描述/标签等元数据做语义定位，绝不依赖记忆中的旧 ID。