File contents 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"的"访问用户数",取前者。
同名指标跨业务域 :若同一指标名出现在多个业务域中,用当前分析任务的业务域限定范围。
1 --- 2 name: bi-semantic-layer-guide 3 description: 语义层工具使用规范。在发现语义层工具可用、需要查询指标定义/维度信息、验证业务口径、处理指标歧义时,必须优先调用此技能。无语义层工具时不调用。 4 metadata: 5 source: https://skillmd.com/skills/agentscope-ai/bi-semantic-layer-guide 6 --- 7 8 # bi-semantic-layer-guide 9 10 ## 概述 11 12 语义层是统一管理业务语义元数据的服务,包括指标定义、维度定义、指标维度绑定和数据集映射。 13 14 --- 15 16 ## 可用工具 17 18 语义层暴露三类工具: 19 20 - **全局**:`list_domains()` 21 - **指标查询**:`list_metrics(domain)`、`search_metrics(query, domain)`、`get_metric(name, domain)`、`get_north_star_metrics(domain)` 22 - **维度查询**:`list_dimensions(domain)`、`get_dimension(name, domain)`、`list_dimensions_of_metric(name, domain)`、`get_dimension_hierarchy(name, domain)`、`get_dimension_values(name, domain)` 23 - **数据集查询**:`list_datasets(domain)`、`get_dataset_columns(name, domain)`、`get_dataset(name, domain)` 24 25 具体参数和返回格式参见工具自身描述。 26 27 --- 28 29 ## 查询策略 30 31 ### 指标匹配 32 33 在语义层中查找指标,可选策略: 34 35 - 语义检索(`search_metrics`),语义层会自动匹配同义词 36 - 查看具体业务域的北极星指标列表(`get_north_star_metrics`),从中选择最相关的 37 - 若以上均未命中,列出该域全部指标(`list_metrics`),逐一判断和分析条目的相关性。 38 39 **`no_match` 必须拦截,不得当作空结果**:语义层返回 `no_match`(或空候选集)表示 40 该指标在语义层中**不存在**,与"指标存在但当前无数据"是两件不同的事。 41 42 - 禁止把 `no_match` 当作 0、空表或"该指标无数据"继续往下分析 43 - 禁止绕过语义层自行猜测指标口径、自行拼 SQL 计算一个同名指标 44 - 先按上述三条策略换用检索方式重试;仍为 `no_match` 时,明确向用户说明该指标未在 45 语义层定义,并请其确认口径或改用已定义的近似指标 46 - 报告中不得出现以 `no_match` 指标为依据的结论 47 48 ### 指标属性确认 49 50 通过 `get_metric` 获取指标属性,重点属性: 51 52 - **是否是北极星指标**(`is_north_star`):用于角色分配 53 - **是否展示指标**(`is_display`):该指标是否应出现在展示面板中 54 - **是否展示分布**(`is_display_distribution`):展示指标时是否同时展示分布图 55 - **维度绑定**(`dimensions`):指标可拆解的维度列表,含 `is_display_dimension`、`is_contribution_dimension` 标记。 56 57 ### 维度信息获取 58 59 通过 `list_dimensions_of_metric` 获取指标可拆解的维度列表(`is_contribution_dimension=true` 的维度才可用于贡献度拆解),通过 `get_dimension_hierarchy` 获取维度间的父子层级关系。 60 61 --- 62 63 ## 消歧规则 64 65 搜索指标时可能遇到歧义,按以下规则处理: 66 67 - **匹配到多个指标**:优先选北极星指标(`is_north_star=true`)。若仍有多个候选,结合指标类型和标签综合判断,必要时向用户确认。 68 - **精确名称 vs 同义词**:若同时出现精确名称匹配和同义词匹配,精确名称优先。例如搜索"DAU",若同时命中指标名为"DAU"的指标和同义词含"DAU"的"访问用户数",取前者。 69 - **同名指标跨业务域**:若同一指标名出现在多个业务域中,用当前分析任务的业务域限定范围。
agentscope-ai/QwenPaw-Data commit 9339bc6e23
Frequently asked questions How do I install the Bi Semantic Layer Guide skill? Run npx get-skill add agentscope-ai/bi-semantic-layer-guide in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
What does the Bi Semantic Layer Guide skill do? Bi Semantic Layer Guide It is listed under Coding & Dev Tools on SkillMD.
Is Bi Semantic Layer Guide safe to use? This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
Which AI agents work with Bi Semantic Layer Guide? This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Is Bi Semantic Layer Guide free to use? Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Who published Bi Semantic Layer Guide? agentscope-ai (@agentscope-ai) published this skill. Their other Agent Skills are listed on their SkillMD profile.