---
name: bi-semantic-layer-guide
description: 语义层工具使用规范。在发现语义层工具可用、需要查询指标定义/维度信息、验证业务口径、处理指标歧义时，必须优先调用此技能。无语义层工具时不调用。
---
# bi-semantic-layer-guide

## 概述

语义层是统一管理业务语义元数据的服务，包括指标定义、维度定义、指标维度绑定和数据集映射。

---

## 可用工具

语义层暴露三类工具：

- **全局**：`list_domains()`
- **指标查询**：`list_metrics(domain)`、`search_metrics(query, domain)`、`get_metric(name, domain)`、`get_north_star_metrics(domain)`
- **维度查询**：`list_dimensions(domain)`、`get_dimension(name, domain)`、`list_dimensions_of_metric(name, domain)`、`get_dimension_hierarchy(name, domain)`、`get_dimension_values(name, domain)`
- **数据集查询**：`list_datasets(domain)`、`get_dataset_columns(name, domain)`、`get_dataset(name, domain)`

具体参数和返回格式参见工具自身描述。

---

## 查询策略

### 指标匹配

在语义层中查找指标，可选策略：

- 语义检索（`search_metrics`），语义层会自动匹配同义词
- 查看具体业务域的北极星指标列表（`get_north_star_metrics`），从中选择最相关的
- 若以上均未命中，列出该域全部指标（`list_metrics`），逐一判断和分析条目的相关性。

**`no_match` 必须拦截，不得当作空结果**：语义层返回 `no_match`（或空候选集）表示
该指标在语义层中**不存在**，与"指标存在但当前无数据"是两件不同的事。

- 禁止把 `no_match` 当作 0、空表或"该指标无数据"继续往下分析
- 禁止绕过语义层自行猜测指标口径、自行拼 SQL 计算一个同名指标
- 先按上述三条策略换用检索方式重试；仍为 `no_match` 时，明确向用户说明该指标未在
  语义层定义，并请其确认口径或改用已定义的近似指标
- 报告中不得出现以 `no_match` 指标为依据的结论

### 指标属性确认

通过 `get_metric` 获取指标属性，重点属性：

- **是否是北极星指标**（`is_north_star`）：用于角色分配
- **是否展示指标**（`is_display`）：该指标是否应出现在展示面板中
- **是否展示分布**（`is_display_distribution`）：展示指标时是否同时展示分布图
- **维度绑定**（`dimensions`）：指标可拆解的维度列表，含 `is_display_dimension`、`is_contribution_dimension` 标记。

### 维度信息获取

通过 `list_dimensions_of_metric` 获取指标可拆解的维度列表（`is_contribution_dimension=true` 的维度才可用于贡献度拆解），通过 `get_dimension_hierarchy` 获取维度间的父子层级关系。

---

## 消歧规则

搜索指标时可能遇到歧义，按以下规则处理：

- **匹配到多个指标**：优先选北极星指标（`is_north_star=true`）。若仍有多个候选，结合指标类型和标签综合判断，必要时向用户确认。
- **精确名称 vs 同义词**：若同时出现精确名称匹配和同义词匹配，精确名称优先。例如搜索"DAU"，若同时命中指标名为"DAU"的指标和同义词含"DAU"的"访问用户数"，取前者。
- **同名指标跨业务域**：若同一指标名出现在多个业务域中，用当前分析任务的业务域限定范围。