fabriciq-ontology-consumption-cli

更新检查 — 每个会话仅检查一次（必须） 在会话中首次使用此技能时，必须先运行 check-updates 技能，然后再继续。

• GitHub Copilot CLI / VS Code：调用 check-updates 技能（例如，/fabric-skills:check-updates）。
• Claude Code / Cowork / Cursor / Windsurf / Codex：读取本地 package.json 版本，然后通过 git fetch origin main --quiet && git show origin/main:package.json（或 GitHub API）与远程版本进行比较。如果远程版本较新，请显示更新日志和更新说明。
• 如果本会话早些时候已执行过检查，则跳过。

重要说明

1. 本体目前处于 预览 阶段。项类型的值为 Ontology。线格式和限制可能会发生变化；投入生产使用前，请根据当前文档进行验证。
2. 此技能为只读。它不会调用 createItem 或 updateDefinition。如需更改架构，请委托给 fabriciq-ontology-authoring-cli。
3. 此技能不会直接查询源数据。它会枚举本体基准上下文，然后将实际数据读取操作委托给与绑定源类型匹配的每数据源使用技能（参见查询路由）。
4. 投影（本体实体上的语义查询层）尚未正式发布。正式发布前，所有数据查询都针对源表（LakehouseTable 或 KustoTable），并使用绑定的 propertyBindings[] 中声明的列。
5. 要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区并使用 JMESPath 过滤。
6. 要根据工作区 ID 和项名称查找本体项 ID：列出该工作区中所有类型为 Ontology 的项，并使用 JMESPath 过滤。

fabriciq-ontology-consumption-cli — 通过 CLI 使用 Fabric 本体

目录

任务	参考	备注
在 Fabric 中查找工作区和项目	COMMON-CLI.md § 在 Fabric 中查找工作区和项目	必需 — 枚举前先解析工作区 / 项目 ID
Fabric 拓扑与关键概念	COMMON-CORE.md § Fabric 拓扑与关键概念	工作区 → 项目层级
身份验证与令牌获取	COMMON-CORE.md § 身份验证与令牌获取	控制平面使用 https://api.fabric.microsoft.com audience
核心控制平面 REST API	COMMON-CORE.md § 核心控制平面 REST API	获取项目定义
长时间运行的操作（LRO）	COMMON-CORE.md § 长时间运行的操作（LRO）	getDefinition 返回 LRO
速率限制与节流	COMMON-CORE.md § 速率限制与节流
身份验证方案	COMMON-CLI.md § 身份验证方案	az login；获取令牌
通过 az rest 调用 Fabric 控制平面 API	COMMON-CLI.md § 通过 az rest 调用 Fabric 控制平面 API	始终传递 --resource https://api.fabric.microsoft.com
长时间运行的操作（LRO）模式	COMMON-CLI.md § 长时间运行的操作（LRO）模式	轮询 operations/{x-ms-operation-id}，直到状态为 Succeeded
注意事项与故障排除（CLI 专属）	COMMON-CLI.md § 注意事项与故障排除（CLI 专属）	令牌 audience、shell 转义
定义封装（parts、payloadType）	ITEM-DEFINITIONS-CORE.md § 定义封装	InlineBase64 parts 模式 — 本体返回此结构
本体定义树	ONTOLOGY-AUTHORING-CORE.md § 定义树	要解码的 parts 的权威文件 / 文件夹布局
EntityType 与 EntityTypeProperty 架构	ONTOLOGY-AUTHORING-CORE.md § EntityType 文件	valueType 目录、键 / 显示名称约定
DataBinding 架构与源类型映射	ONTOLOGY-AUTHORING-CORE.md § DataBinding 文件	LakehouseTable 与 KustoTable；propertyBindings[] 结构
RelationshipType 与上下文化	ONTOLOGY-AUTHORING-CORE.md § RelationshipType 文件	源 / 目标与链接表约定
连接基础知识（EH 源查询）	EVENTHOUSE-CONSUMPTION-CORE.md § 连接基础知识	用于 KustoTable 绑定的群集 URI 与数据库发现
性能最佳实践（EH 源查询）	EVENTHOUSE-CONSUMPTION-CORE.md § 性能最佳实践	时间筛选器、has 与 contains
Spark 消费模式（Lakehouse 源）	SPARK-CONSUMPTION-CORE.md	对于 LakehouseTable 绑定，委托读取
SQL 消费模式（SQL endpoint / DW）	SQLDW-CONSUMPTION-CORE.md	用于读取 LakehouseTable SQL 终结点和 Warehouse
本体概念	SKILL.md § 本体消费概念	实体 / 关系 / 绑定 / grounding 上下文
工具栈	SKILL.md § 工具栈
连接	SKILL.md § 连接	发现工作区、本体 ID；获取项目定义
消费范围	SKILL.md § 消费范围	此技能的功能与非功能
Grounding 上下文提取（深入参考）	grounding-extraction.md	解码 parts → 为 Agent 生成 grounding JSON
查询路由（深入参考）	routing.md	绑定类型 → 每个数据源对应的技能 + 查询结构
示例	examples.md	端到端 bash 方案（枚举 → 路由 → 查询）
图遍历（从锚点出发的 N 跳邻域）	graph-walks.md	锚点实体 + 跳数预算 → 组合内联读取，无需脚本
快速响应准则	SKILL.md § 快速响应准则	优先内联；仅在有状态或需要重复运行时使用脚本
必须 / 优先 / 避免 / 故障排除	SKILL.md § 必须 / 优先 / 避免 / 故障排除	大模型决策规则
Agent 工作流	SKILL.md § Agent 工作流	先 grounding 再查询的循环、架构感知型查询生成
Agent 集成说明	SKILL.md § Agent 集成说明	此技能如何与创作技能 / 各数据源技能组合使用

---

本体使用概念

Fabric 本体项在项定义中以 JSON 文件树的形式包含其架构（与创作时的形状相同）。Get Item Definition 会以 base64 编码的有效负载返回各个部分；使用流程始终是：获取 → 解码 → 解析 → 落实 → 委派。

概念	定义部分	向 Agent 提供的信息
实体类型	EntityTypes/{entityTypeId}/definition.json	逻辑类型名称、键属性（entityIdParts）、显示名称属性、静态 properties[]、timeseriesProperties[]、值类型目录
数据绑定	EntityTypes/{entityTypeId}/DataBindings/{guid}.json	为此实体类型提供支持的物理表、源类型（LakehouseTable / KustoTable）、dataBindingType（NonTimeSeries / TimeSeries）、列到属性的映射，以及——对于时间序列——时间戳列
关系类型	RelationshipTypes/{relTypeId}/definition.json	两种实体类型之间的链接（源/目标）；名称；基数提示
上下文化	RelationshipTypes/{relTypeId}/Contextualizations/{guid}.json	用于建立关系的（源键、目标键）对所在的 Lakehouse 链接表

落实上下文 = 将该树展平后，供 Agent 使用的投影：一份 JSON 摘要，大模型可据此判断 要查询哪种实体类型、哪一列存放键、要访问哪张表，以及 要调用哪项使用技能。完整结构和提取方法：grounding-extraction.md。

属性 valueType 的允许值（精确值）：String、Boolean、DateTime、Object、BigInt、Double。整数使用 BigInt（而非 Int64）；GUID 建模为 String。完整的源列 → valueType 映射，请参阅 ONTOLOGY-AUTHORING-CORE.md § EntityTypeProperty。

---

工具栈

本体使用与其他所有 CLI 技能相同的 Fabric 控制平面工具栈——规范列表（安装命令、先决条件检查、base64 辅助工具、JSON 工具）请参阅 COMMON-CLI.md § Tool Selection Rationale；az login 和令牌获取方法请参阅 COMMON-CLI.md § Authentication Recipes。

按数据源读取操作由其他流程委派——使用此技能进行枚举时，无需安装 Kusto、Spark 或 SQL CLI 工具。只有在同一会话中还调用下游使用技能时才需要这些工具。

---

连接

本体使用面向 Fabric 控制平面。你需要 工作区 ID 和 本体项 ID；其他所有信息（实体类型、绑定、源表、群集 URI）均可通过解码定义获取。

• 登录并获取 Fabric 控制平面令牌 → COMMON-CLI.md § Authentication Recipes（始终使用 --resource https://api.fabric.microsoft.com）。
• 通过 displayName 解析工作区 ID，并通过 GET /v1/workspaces/{WS_ID}/items?type=Ontology 获取本体项 ID，再按 displayName 筛选 → COMMON-CLI.md § Finding Workspaces and Items in Fabric（涵盖分页和 JMESPath 筛选）。
• 通用 az rest 调用模板 → COMMON-CLI.md § Fabric Control-Plane API via az rest。

获取定义（Ontology-preview LRO 注意事项）

Get Item Definition 支持长时间运行的操作。根据租户／SKU 的不同，POST 可能会直接返回定义信封（200 OK），也可能返回 202 Accepted，并附带 x-ms-operation-id 标头；如果返回 202，请轮询 https://api.fabric.microsoft.com/v1/operations/{operationId}，直到状态为 Succeeded，然后 GET …/operations/{operationId}/result 以获取 parts[] 数组。通用 LRO 流程（捕获 x-ms-operation-id、轮询、获取结果）见 COMMON-CLI.md § 长时间运行的操作（LRO）模式。

Ontology-preview 注意事项 — 优先轮询 operations/{id} 端点，而不是使用 Location 标头。 Fabric 公开的 LRO 契约支持这两种方式，但据观察，在此 Ontology LRO 中，Location 标头会重定向到 *.analysis.windows.net 主机；使用 Fabric 受众令牌轮询该地址时不稳定（间歇性返回 401/403）。请改为在 Fabric 主机上轮询 https://api.fabric.microsoft.com/v1/operations/{operationId}。如果必须跟随 Location，请使用该 URL 所要求的受众。如果轮询返回非 2xx，请读取操作的 .error 并停止 — 切勿盲目重试 POST。

此技能完整的获取与解码流程（LRO 捕获、部分解码和树重建，以及 Bash、PowerShell 和 Python 辅助程序）位于 grounding-extraction.md § 获取并解码。同级技能 fabriciq-ontology-authoring-cli 在其 LRO 标头捕获部分中记录了相同的重定向主机解决方法 — 如果修改其中一处，请确保两处内容保持同步。

源数据连接（委托处理）

实际运行数据查询（KQL / Spark SQL / T-SQL）时，请使用同级使用技能所维护的连接模式：

• Eventhouse（KustoTable 绑定）→ EVENTHOUSE-CONSUMPTION-CORE.md § 连接基础知识 + eventhouse-consumption-cli
• Lakehouse（LakehouseTable 绑定）→ sqldw-consumption-cli（默认，SQL 分析终结点）或 spark-consumption-cli（仅在用户明确需要 PySpark / DataFrame 工作时）
• Warehouse 绑定 → ❓ 当前共享 Ontology 架构中未记录（仅有 LakehouseTable 和 KustoTable）；如果遇到，请告知用户，而不要默默假定使用 sqldw-consumption-cli

委托方所需的 clusterUri、databaseName、workspaceId 和 itemId 都已包含在解码后的绑定载荷中 — 不要通过项 API 重新查找。

---

消费范围

操作	此技能	委派给
枚举实体类型、属性、键、显示名称	✅	—
枚举绑定（源类型、目标项、属性映射、时间戳）	✅	—
枚举关系和上下文关联	✅	—
生成面向大模型的 grounding JSON	✅	—
解码完整定义树以进行差异比较 / 审查	✅	—
在 Eventhouse 中查询基于本体的数据	路由	eventhouse-consumption-cli
通过 SQL endpoint（默认）在 Lakehouse 中查询基于本体的数据	路由	sqldw-consumption-cli
通过 Spark 在 Lakehouse 中查询基于本体的数据（仅限明确要求使用 Spark）	路由	spark-consumption-cli
在 Warehouse 中查询基于本体的数据	展示（❓ 共享架构中没有绑定形态）	—
创建 / 更改 / 重新绑定实体类型 / 关系	❌	fabriciq-ontology-authoring-cli
刷新本体的索引状态	❌	不在预览版 CLI 范围内

在 projections 发布之前，所有数据读取都是源查询——它们使用 propertyBindings[] 中列出的列，针对物理 LakehouseTable 或 KustoTable 运行。需要 projections 的语义功能（推断联接、派生度量）无法通过此技能使用；请向用户说明，并继续进行源级筛选。

---

上下文依据

详细步骤 + 完整 JSON 结构：grounding-extraction.md。快速索引：

主题	参考
获取 + LRO + 解码各部分	grounding-extraction.md § Fetch and Decode
在内存中重建定义树	grounding-extraction.md § Tree Reconstruction
生成 grounding JSON 摘要（实体 + 绑定 + 关系）	grounding-extraction.md § Grounding Summary Schema
比较两个本体版本	grounding-extraction.md § Diff Two Ontologies

Grounding JSON 约定——权威结构见 grounding-extraction.md § Grounding Summary Schema。路由决策会读取每个绑定中的以下字段：

• source.kind（LakehouseTable | KustoTable）——决定委派工具系列。
• source.workspaceId + source.itemId——从绑定中读取，而非从本体中读取（允许跨工作区绑定）。
• source.sourceSchema + source.sourceTableName——只有 Lakehouse 才有架构。
• source.clusterUri + source.databaseName——只有 Kusto 才有。
• dataBindingType（NonTimeSeries | TimeSeries）+ timestampColumnName——TS 路由所必需。
• propertyBindings[].sourceColumnName——本体属性到物理列的映射；在组合任何查询之前应用。
• relationshipTypes[].contextualizations[].sourceKeyRefBindings[] / targetKeyRefBindings[]——数组；允许使用复合键。联接时使用所有条目。

将此 JSON 的精简子集（而非原始的 base64 definition.parts[]）交给下游技能。

---

查询路由

深入说明和各技能调用模板：routing.md。快速决策表：

绑定源类型	dataBindingType	委派对象（默认 / 备用）	查询形式
LakehouseTable	NonTimeSeries	sqldw-consumption-cli（默认，SQL 终结点）——仅当用户明确需要 PySpark / DataFrames 时使用 spark-consumption-cli	SELECT <propertyColumns> FROM <schema>.<sourceTableName> WHERE <keyColumn> = <value>
LakehouseTable	TimeSeries	sqldw-consumption-cli（默认）——需要 Spark 专属功能时使用 spark-consumption-cli	SELECT ..., <timestampColumn> FROM <schema>.<sourceTableName> WHERE <keyColumn> = <v> AND <timestampColumn> >= DATEADD(hour,-1,SYSUTCDATETIME())
KustoTable	TimeSeries	eventhouse-consumption-cli	<sourceTableName> | where <keyColumn> == "<v>" | where <timestampColumn> > ago(1h) | project <propertyColumns>
KustoTable	NonTimeSeries	无效 — 预览版不允许这样做	拒绝请求，并告知用户本体绑定不正确
任何关系上下文关联	—	sqldw-consumption-cli（默认；关联表位于 Lakehouse 中，使用 T-SQL 连接更清晰）——备用方案为 spark-consumption-cli	SELECT <targetKeyColumns> FROM <linkTable> WHERE <sourceKeyColumns> = <source-values>，然后在后续调用中连接目标侧绑定

移交时的调用约定 — 此技能会解析源元数据，并使用目标方言构造查询，然后将两者交给委派对象。委派对象（同级技能）负责实际连接和执行。

• Eventhouse 委派对象 → 已解析的连接（clusterUri、databaseName）+ 以 sourceTableName 为目标并带有 timestampColumnName 筛选条件和键谓词的已构造 KQL 文本。
• SQL 终结点委派对象（Lakehouse 的默认方案）→ 已解析的连接（workspaceId、itemId、sourceSchema）+ 已构造 T-SQL 文本。
• Spark 委派对象（Lakehouse 的备用方案）→ 相同的已解析连接 + 已构造 Spark SQL 文本 — 使用 Spark 原生时间函数（current_timestamp() - INTERVAL 1 HOUR）；不要向 Spark 输出 T-SQL DATEADD / SYSUTCDATETIME。
• 始终在构造的查询文本中将本体属性名称转换为 propertyBindings[].sourceColumnName。委派对象只会看到物理列，不会解析本体标识符。
• 始终传递复合的 sourceKeyRefBindings[] / targetKeyRefBindings[] — 必须连接所有元素，而不只是第一个。

由于投影尚未正式发布（参见重要说明 #4），在构造委派查询之前，始终先将用户提到的本体属性名称转换回物理源列名称（通过 propertyBindings[]）。不要将本体属性名称传给同级技能 — 它不会解析这些名称。

---

必须 / 优先 / 避免 / 故障排除

必须

• 路由到此处前必须明确要求提供本体上下文 — 提示词必须提及“ontology”（或通过 ID／名称引用某个本体项）。没有本体上下文的通用“Fabric IQ”或报表／数据集提示词不属于本体任务；应转交给匹配的数据技能（例如，Power BI 报表应交给 powerbi-consumption-cli）。这样可避免共享的“Fabric IQ”品牌导致此技能被过度触发。
• 路由含糊的提示词前先澄清 — 如果用户要求“显示飞机读数”，而多个实体类型都绑定到类似飞机的表，请询问要使用哪种实体类型／绑定。擅自猜测会导致数据错误。
• 获取定义前先解析 WS_ID 和 ONT_ID — 硬编码 GUID 是最常见的失败原因之一。
• 对 getDefinition 遵循 LRO 模式 — 返回带有 x-ms-operation-id 的 202 属于正常情况；不要将其视为成功。轮询 operations/{operationId}，直到状态为 Succeeded，然后 GET …/operations/{operationId}/result。优先轮询 operations/{operationId}，而不是原始的 Location（使用 Fabric 受众令牌时，重定向到 analysis.windows.net 可能不稳定）；如果跟随 Location，请使用该 URL 所需的受众。在轮询失败／返回非 2xx 时，读取 .error 并停止——切勿盲目重试。
• 回答前解码所有相关部分 — 切勿依据本体的缓存局部视图作答。调用方可能在你上次读取后添加或修改了实体类型。
• 生成任何 KQL／Spark SQL／T-SQL 前，通过 propertyBindings[] 将本体属性名称映射到源列名称。同级的消费技能只能看到物理列。
• 遵循绑定类型 — TimeSeries 要求在 timestampColumnName 上设置时间筛选条件。省略该条件会导致全表扫描，而且下游技能通常会拒绝执行。
• 保留每个绑定的 workspaceId + itemId — 本体绑定可能引用与本体位于不同工作区的源项；不要假设它们位于同一工作区。
• 发起元数据调用前先查阅内存中的 grounding — 会话中解码 grounding JSON 后，后续所有遍历／查询都应从 grounding 读取源列名称、关联表名称、项 GUID、clusterUri 和 databaseName，而不是重新调用 list items／get eventhouse。重复获取已有元数据是导致调用次数膨胀的首要原因。
• 源 URL 中使用 GUID，而非易读名称 — 许多租户启用了 FriendlyNameSupportDisabled，会静默拒绝 OneLake DFS／Fabric REST URL 中类似 MyLakehouse.Lakehouse 的名称。始终从 grounding 获取 GUID，并将其代入 URL。

建议

• 对于包含 |、" 或换行符的下游 KQL／SQL 负载，使用 az rest 和 --body @file.json。内联 --body 会因 Shell 转义而失效——请参阅 EVENTHOUSE-CONSUMPTION-CORE.md。
• 将 grounding 摘要 JSON（参见上文的架构）交给其他 Agent，而非原始的 definition.json 转储。
• 首次读取任意实体的数据时使用 take 100 / TOP 100，然后再细化查询。
• 对于只读消费任务，优先使用内联 az rest / curl，而非 Python 脚本——图遍历、单实体查找和临时扇出读取应在 Shell 中组合完成，REST 调用不超过约 15 次。仅当任务具有状态（封装组装、ID 映射、用户希望可重复运行的 LRO）时才使用脚本。请参阅 快速响应规范 和 graph-walks.md。
• 在单次会话期间缓存已解码的定义 — 本体定义比源数据小几个数量级，而且很少会在任务中途发生变化。如果用户提到正在进行创作操作，则重新获取。
• 仅对绑定的源列使用 project / SELECT，不要查询整个物理表——本体绑定意味着明确的列白名单。

避免

• 使用本体属性名称查询源表 — 物理架构中不存在这些名称。始终通过 propertyBindings[] 查询。
• 在读取 TimeSeries / KustoTable 时省略 where <timestampColumn> > ago(...) — 对流式表进行全表扫描是最常见的查询失败原因。
• 在一次委托调用中跨数据源类型联接 — 如果某个关系的两端位于不同的源类型中，委托无法表达该联接。分别获取两端的数据，然后在 Agent 中联接。
• 使用此技能修改本体 — 所有架构更改都应转交给 fabriciq-ontology-authoring-cli。
• 将原始 base64 部分传递给下游技能 / 模型 — 始终先解码并整理为 grounding JSON。
• 悄然忽略未知的部分路径 — 新的预览版可能会增加部分类型；可以记录后继续，但要向用户指出新的部分名称。

故障排查

症状	修复方法
az rest 返回 401 Unauthorized	执行 az login；确认控制平面调用使用 --resource "https://api.fabric.microsoft.com"（委托时则使用匹配的下游受众，EH 使用 https://kusto.kusto.windows.net）。
getDefinition 返回 202 且没有响应正文	这是预期行为 — 遵循 LRO 模式；捕获 x-ms-operation-id，并轮询 operations/{operationId}，直至状态为 Succeeded，然后 GET …/operations/{operationId}/result。优先使用 operations/{operationId}；如果轮询 Location，请使用该 URL 要求的受众（analysis.windows.net 重定向可能无法使用 Fabric 受众令牌）。
getDefinition 返回 403 Forbidden	本体需要 Contributor 或 本体项上的 Reader，并且需要工作区访问权限。请申请角色分配。
definition.parts[] 为空	已创建该项，但未添加实体类型。请告知用户，并建议先运行 fabriciq-ontology-authoring-cli。
下游 KQL 返回 0 行，但源表有数据	检查绑定中的 sourceTableName 大小写是否正确，以及绑定中的 clusterUri / databaseName 是否与实时群集一致。大小写不匹配会导致结果静默为空。
SELECT <propertyName> 失败并提示 "invalid column"	你传入的是本体属性名称，而非源列名称。请通过 propertyBindings[].sourceColumnName 进行映射。
关系遍历返回的行数远少于预期	Contextualization 的 sourceTableName（Lakehouse 链接表）可能为空或已过期；在归咎于本体之前，先使用 sqldw-consumption-cli 检查。
绑定与实时 Eventhouse 的 itemId / clusterUri 不匹配	后端 Eventhouse 已重新创建；本体需要更新。请转交给 fabriciq-ontology-authoring-cli。
Base64 解码后得到二进制乱码	部分载荷不是 InlineBase64；请检查 payloadType。如果是 VsixPackage 或未知类型，请跳过并发出警告。

---

Agentic 工作流

快速响应准则

读取数据是只读操作，应该感觉很快。默认模式是在 Shell 中内联组合，而不是使用 Python 包装器。使用脚本前，请先查看以下清单：

情况	内联（az rest / curl）	Python / Shell 脚本
查询单个实体	✅	❌
读取时间序列窗口	✅	❌
图遍历，跳数 ≤ 2（参见 graph-walks.md）	✅	❌
跨源关系遍历（LH 键 → KQL 扇出）	✅	❌
提取 Grounding JSON（一次性）	✅	❌
用户希望重复运行的 LRO getDefinition 轮询循环	➖	✅
本体编写 / 修改（35 部分信封，ID 交叉引用）	❌	✅（转交给 fabriciq-ontology-authoring-cli）
长时间运行的播种 / 批量加载，带重试和检查点	❌	✅

优先内联原则

1. 组合，不要编写脚本。 每个 REST 调用都应独立表达明确含义；使用 && / | / jq 串联，而不是封装到 .py 中。
2. 并行执行扇出。 独立的读取操作（链接表查询、按实体类型执行 IN 列表读取）应使用 & 和 wait，而不是按顺序运行 for 循环。
3. 每组只进行一次往返。 使用 WHERE id IN (...)，而不是 N×WHERE id = '...'。
4. 在本次会话中缓存 Grounding JSON——它在各次查询之间不会变化，重新获取会使每次遍历的延迟翻倍。
5. 尽早流式呈现。 锚点行和第一组邻居一返回就立即显示；不要等整个遍历完成后才呈现。
6. 除非用户要求，否则不要编写脚本。 如果用户说“保存以便稍后使用”或“每晚重新运行”，再将其封装成脚本。否则，让操作保持为可在聊天中重放的 Shell 命令。

如果某项任务看起来需要超过约 20 次 REST 调用、超过 2 跳，或需要在多次调用之间保留状态，请在编写脚本前告知用户——这通常意味着应该缩小问题范围，而不是自动化处理。

“先 Ground，再查询”流程

当用户要求通过本体视角查询数据时：

Step 1 → Resolve WS_ID + ONT_ID (list workspaces, list items type=Ontology)
Step 2 → getDefinition (LRO) → decode all parts → reconstruct tree
Step 3 → Build grounding JSON (entities, properties, bindings, relationships)
Step 4 → Disambiguate with the user if multiple entity types / bindings could satisfy the intent
Step 5 → For the chosen entity type + binding:
           a. Remap ontology property names → source column names
           b. Compose the source query (KQL / Spark SQL / T-SQL)
           c. Hand off to the matching sibling consumption skill with minimal fields
Step 6 → Post-process results back into ontology-property naming for the user (optional but helpful)

感知架构的查询生成

完成 Grounding 后，使用 propertyBindings[] 中记录的物理列生成查询，切勿使用本体名称：

Entity type "Aircraft" with binding:
  source kind = KustoTable
  sourceTableName = "AircraftReadings"
  timestampColumnName = "PreciseTimestamp"
  propertyBindings: { AltitudeFt → SourceColumn "Temp_C", TailNumber → SourceColumn "AssetId" }

User intent: "show altitude excursions on aircraft N42ZA in the last hour"

Generated KQL (delegated to eventhouse-consumption-cli):
  AircraftReadings
  | where AssetId == "N42ZA"
  | where PreciseTimestamp > ago(1h)
  | project PreciseTimestamp, Temp_C
  | where Temp_C > 80

关系遍历

Relationship "operates" (Airline → Aircraft)
Contextualization: LakehouseTable "HubAircraftAssignment" with (AirlineId, TailNumber) columns
  AND two entity-type bindings (Airline on LakehouseTable "Airlines", Aircraft on KustoTable "AircraftReadings")

User intent: "which aircraft does Airline 'ZA' operate and what's their latest reading?"

Step 1: sqldw-consumption-cli → SELECT TailNumber FROM HubAircraftAssignment WHERE AirlineId = 'ZA'
Step 2: eventhouse-consumption-cli → AircraftReadings | where AssetId in (<TankIds>) | summarize arg_max(PreciseTimestamp, *) by AssetId
Step 3: Merge results in the agent; present with ontology-level column names.

完整的端到端 Bash 示例（枚举 → Grounding → 路由 → 查询）见 examples.md。对于“展示与 X 相关的所有内容”这类提示词，请直接使用 graph-walks.md 中的 N 跳遍历。

图遍历（从锚点开始的 N 跳遍历）

当用户给出一个实例（“Panel7”、“飞机 N42ZA”、“客户 1234”）并询问其邻域——而非单个列——时，请使用专门的图遍历模式，而不是针对每个问题临时设计流程。

Anchor → relationships touching anchor (from grounding JSON, in-memory)
       → linking-table reads (parallel, one per relationship)
       → IN-list reads of neighbor entities (one per EntityType)
       → optional KustoTable telemetry sweep (one per EntityType with TS binding)

对于 hop=1，这通常不超过 10 次往返，并且可以保持内联。完整算法、扇出模板、跳数预算以及 Panel7 示例见 graph-walks.md。

---

示例

端到端的完整示例（枚举本体 → 构建 Grounding JSON → 将源表查询路由到正确的同级读取技能 → 遍历 Lakehouse 与 Eventhouse 之间的关系）见 examples.md。从锚点实例开始的 N 跳邻域遍历（类似 Panel7 的示例）见 graph-walks.md。完整的获取与解码脚本见 grounding-extraction.md。按绑定类型分类的调用模板见 routing.md。

---

Agent 集成说明

• 此技能对本体项仅提供只读访问。所有创作操作（创建、更改、重新绑定、重命名）都应由 fabriciq-ontology-authoring-cli 负责——请委派给它。
• 此技能不会自行执行数据查询。它会生成依据上下文和路由决策；实际源查询由你委派的各数据源消费技能执行。
• 支持的下游技能（预览版）：eventhouse-consumption-cli、spark-consumption-cli、sqldw-consumption-cli。目前尚无独立的图消费技能——如果用户要求对关系执行图结构查询，请说明此限制，并改用通过 Lakehouse / SQL 对各边执行联接。
• 编排 Agent 应向此技能提供工作区名称 / ID和本体显示名称 / ID；此技能将返回可供后续委派调用复用的依据 JSON，无需重新获取定义。
• 如果在会话中途怀疑发生了创作操作（例如，用户运行 fabriciq-ontology-authoring-cli 后又回来查询），请重新执行依据检查——缓存的定义已过期。
• 如果用户环境中配置了 Fabric KQL MCP 服务，可在 Eventhouse 委派环节用它替代 az rest。仓库默认的 mcp-setup/mcp-config-template.json 不会注册 fabric-kql 服务，因此不要假定该名称存在。无论哪种情况，它都无法处理本体控制平面调用，因此获取 / 依据检查步骤仍需使用 az rest。