semantic-model-authoring

遥测——强制要求。 每次 api.fabric.microsoft.com 调用都必须携带 x-ms-fabric-skill: semantic-model-authoring（az rest：--headers "x-ms-fabric-skill=semantic-model-authoring"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了该标头——也请务必添加。

重要说明

1. 要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 筛选
2. 要根据工作区 ID、项类型和项名称查找项的详细信息（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 筛选
3. 选择每项操作所用的工具时，始终考虑工具选择优先级。如果 MCP 可用且已连接到目标模型，请勿默认使用 TMDL 编辑或 az rest。

Power BI 语义模型创作 — CLI 技能

工作流选择器

使用此决策树，根据用户意图选择正确的工作流：

用户想要……	工作流
从头开始创建语义模型	创建新的语义模型
检查或发现模型元数据（表、列、度量值、关系）	发现语义模型元数据
添加或编辑语义模型对象（例如，度量值、表、列、关系）	修改现有模型
编写或重构 DAX 代码	修改现有模型
创建或编辑字段参数	创作字段参数
提升 DAX 查询或度量值的性能	优化 DAX 性能
根据最佳实践分析语义模型	分析最佳实践
为 AI 使用准备语义模型（Copilot / Data Agents）	语义模型 AI 就绪度
将模型部署到 Fabric 工作区	部署到 Fabric
刷新语义模型	刷新语义模型
配置数据源、参数或权限	在 Fabric 中管理语义模型
将语义模型绑定到 Fabric 连接（或解除绑定）	将语义模型绑定到连接
将语义模型定义导出为 PBIP / 获取语义模型定义	导出为 PBIP

目录

当工作流步骤需要时，按需加载这些参考资料。不要一次性全部加载。

主题	参考	加载时机
建模最佳实践	modeling-guidelines.md	创建或编辑任何模型之前
命名约定	naming-conventions.md	为表、列、度量值命名或重命名时
Direct Lake 建模	direct-lake-guidelines.md	模型连接到 OneLake 时
TMDL 编辑	tmdl-guidelines.md	生成或编辑任何 TMDL 文件之前
PBIP 项目	pbip.md	使用 PBIP 文件夹时
DAX 语言	dax-guidelines.md	编写或检查任何 DAX 代码时
字段参数	field-parameters.md	创建或编辑字段参数表（度量值选择器、动态视图）时
元数据发现（DAX INFO 函数）	metadata-discovery.md	通过 DAX INFO 函数发现模型元数据时（参见工作流：发现语义模型元数据）
DAX 性能决策指南	dax-perf-decision-guide.md	优化 DAX 时从这里开始
DAX 性能模式目录	dax-perf-patterns.md	决策指南确定候选模式后按需加载
语义模型 AI 就绪性	semantic-model-ai-readiness.md	为 Copilot 或 Data Agents 准备模型时
语义模型 REST API	semantic-model-rest-api.md	使用 az rest 进行 TMDL CRUD、刷新、参数、权限或属性检索时
连接绑定	connection-binding.md	将语义模型绑定到 Fabric 数据连接或解除绑定时（网关、云、VNet、自动、无）
查找工作区/项目	COMMON-CLI.md	解析工作区/项目 ID 时
Fabric 控制平面 API	COMMON-CLI.md	使用 az rest 模式、LRO、分页时
身份验证	COMMON-CLI.md	使用 az login 进行身份验证时
身份验证与令牌获取	COMMON-CORE.md § Authentication & Token Acquisition	受众错误会导致 401；遇到任何身份验证问题前请先阅读
核心控制平面 REST API	COMMON-CORE.md § Core Control-Plane REST APIs	包括分页、LRO 轮询和速率限制模式
定义封装	ITEM-DEFINITIONS-CORE.md	构建 TMDL 定义负载时
示例	示例	参考端到端演练。

---

工具选择优先级

优先级顺序（从高到低）：

1. Tier 1 — 已注册 powerbi-modeling-mcp MCP -> 使用 MCP 对来自任意来源的模型执行创作操作（新建或编辑）：Power BI Desktop、Fabric 工作区或本地 PBIP 文件夹。MCP 是编辑语义模型最可靠、功能最全面的方式，可立即对实时模型生效，且不会有 TMDL 不同步的风险。

   **重要提示：**如果可以使用动态搜索工具（例如 tool_search_tool_regex），请搜索是否有匹配模式 powerbi-modeling-mcp 的可用 MCP 服务。

   这包括写入和读取／检查操作。

   • 检查或验证更改 -> 使用对应的 MCP 操作（List / Get）。
   • **反模式：**MCP 已连接时，打开、view、glob 或以其他方式读取 TMDL 文件（*.tmdl）。MCP 加载的模型才是事实来源——磁盘上的 TMDL 已过时。唯一例外是用户明确要求处理 TMDL 文件。

2. Tier 2 — 未注册 MCP + PBIP 文件夹或 Fabric 工作区 -> 直接编辑 TMDL 文件。加载 tmdl-guidelines.md 和 pbip.md。如果来源是 Fabric 工作区，使用 az rest 往返处理 TMDL（加载 semantic-model-rest-api.md）：getDefinition -> 在本地编辑 TMDL -> updateDefinition。

后备方案 — 以上条件均不满足（例如，使用 Power BI Desktop，但没有 PBIP 和 MCP） -> 停止。此配置下 Agent 无法创作模型。请告知用户执行以下任一操作：(a) 安装并注册 powerbi-modeling-mcp MCP 服务；或 (b) 将 PBIX 保存为 PBIP 项目，然后重新启动工作流。

**以下所有工作流均与工具无关。**工作流步骤描述的是意图（连接、创建、编辑、保存、部署、刷新）。执行每个步骤所用的工具由此处确定。始终选择当前环境中优先级最高的可用工具；如果更高优先级的选项可用，请勿混用工具。某些工作流会覆盖此默认优先级；在默认选择 Tier 1 之前，请务必检查工作流自身的工具选择规则。

连接到语义模型

语义模型可位于三个位置。根据工具选择优先级确定连接方式：

• Power BI Desktop：找到正在运行的 Power BI Desktop 实例，并连接到其本地模型。
• Fabric 工作区：首先，按照查找工作区和项目模式查找工作区和语义模型：列出工作区，以名称确定工作区 ID；然后列出该工作区中 SemanticModel 类型的项目，以名称确定模型 ID。接着连接到模型（实时），或导出其 TMDL 定义以供本地编辑。
• PBIP 项目：连接到 [Name].SemanticModel/definition 文件夹。加载 pbip.md 了解 PBIP 文件夹结构——仅加载包含 TMDL 代码的 [Name].SemanticModel/definition 文件夹。

保存对语义模型的更改

更改的持久化方式取决于模型所在的位置以及使用的工具层级（参见工具选择优先级）：

实时连接（Tier 1 - 通过 MCP 连接到 Desktop 或 Fabric 工作区）：

• 每次操作都会直接对实时模型应用更改。无需显式保存。
• PBIP 项目（通过 MCP 实时连接）：在会话结束时，将模型序列化回 [Name].SemanticModel/definition 文件夹。如果 PBIP 文件夹尚不存在，请按照导出为 PBIP 中的步骤先创建完整结构。

本地 TMDL 编辑（Tier 2 - 直接编辑文件或通过 az rest 往返）：

• PBIP 项目：编辑期间更改已写入 TMDL 文件。无需额外保存。
• Fabric 工作区：更改是在从服务导出的本地 TMDL 文件中进行的。请重新部署模型（加载 semantic-model-rest-api.md，了解 updateDefinition 流程），将更改推送回工作区。

---

工作流：创建新语义模型

适用情况： 用户要求从头开始创建新的语义模型。

步骤：

1. 收集需求 - 与用户沟通，直到双方就以下内容达成共识：模型用途、数据源连接详细信息和架构，以及关键业务实体/事实。如果没有可用的数据源信息，请停止并使用 ask_user。不要猜测或编造。

2. 确定存储模式 - 数据源是 Fabric OneLake -> Direct Lake；否则默认使用 Import。只有在用户明确要求时才使用 DirectQuery。

3. 设计星型架构 - 确定事实表、维度表和关系键。

   • 如果事实表包含日期字段，请创建单独的日期维度表，并通过关系将其关联到事实表。如果用户未明确要求，请使用 PowerQuery/M 分区，而不是 DAX 计算表。

4. 加载适用指南 - 强制要求：在构建任何对象之前，先加载 modeling-guidelines.md（包括下面的 Tier 1 MCP 路径）；如果使用 Direct Lake，还要加载 direct-lake-guidelines.md。不要凭记忆构建。

5. 构建 - 遵循工具选择优先级：**如果有建模 MCP，优先使用它构建整个模型；否则使用 TMDL 代码编辑路径。**创建一个空数据库（兼容级别 1702+），然后对每个表按照修改现有模型中的执行顺序进行操作（分区 -> 列 -> 关系 -> 度量值）。存储模式特定要求：

   • Import / DirectQuery - 为数据源创建 M 参数（Server、Database 等），并在分区 M 代码中引用这些参数；确保列的 dataType 和 sourceColumn 映射正确。
   • Direct Lake - 使用 AzureStorage.DataLake 连接器为 Direct Lake 连接创建共享的命名表达式；使用 directLake 模式的 EntityPartitionSource，将其映射到湖屋表列。

   **一次性构建整个模型，然后部署一次。**部署前添加所有表、列、关系和度量值——不要先部署不完整的模型，再编辑并重新部署。使用 MCP 路径时，从头到尾都在会话中保留该模型。

6. 部署或保存 - 有 Fabric 工作区 -> 部署到 Fabric；否则 -> 导出为 PBIP。参见保存对语义模型的更改。使用与构建时相同的路径进行部署。

7. 验证 - 执行验证清单。

---

工作流：发现语义模型元数据

适用情形： 用户要求检查、列出或发现模型的结构，包括表、列、度量值、关系、层级结构、分区、角色或存储内部结构。在编辑前，其他工作流（修改、分析最佳实践、AI 就绪度）也会在内部使用此工作流盘点模型。

选择一种发现方法（按优先级从高到低）：

1. powerbi-modeling-mcp TOM 检查（List / Get）——当 powerbi-modeling-mcp 已注册并以写入权限连接到目标模型时，默认使用此方法。它会直接返回结构化对象模型，并与待处理的编辑保持同步，因此在创作期间优先使用。

2. DAX INFO.VIEW 函数——查询模型的 INFO.VIEW.* 元数据行集。强制要求：编写或运行任何 INFO 函数 DAX 之前，必须先加载 metadata-discovery.md。不要凭记忆编写 INFO 查询；请加载参考文档并使用其中的模式。出现以下任一情况时，优先使用此方法：

   • 你没有模型的写入权限。 powerbi-modeling-mcp 的 List / Get 操作需要写入权限；拥有生成权限时，请使用通过 dax_query_operations 工具执行的 INFO.VIEW 函数。
   • powerbi-modeling-mcp 未注册或不可用。 使用第 2 层：导出模型定义（getDefinition），并检查 .tmdl 文件中的架构元数据。

从小范围开始：先运行范围估算和 INFO.VIEW.* 查询，然后仅投影或筛选与任务相关的对象（参见 metadata-discovery.md）。

---

工作流：修改现有模型

适用情形： 用户要求添加、编辑或移除度量值、表、列、关系，编写 DAX 代码，使用 UDF 重构，或直接编辑 TMDL。

步骤：

1. 连接并发现——按照连接到语义模型和发现语义模型元数据进行。列出表、关系和现有度量值，并确定存储模式（它决定适用哪些准则）。
2. 加载适用的准则——始终加载 modeling-guidelines.md；如果是 Direct Lake，则加载 direct-lake-guidelines.md；直接编辑 TMDL 时，加载 tmdl-guidelines.md；进行任何 DAX 更改时（包括 UDF 重构），加载 dax-guidelines.md。
3. 规划更改——准确确定要添加、修改或移除的内容。检查名称冲突和重复项。
4. 按正确顺序执行：
   • 添加表——分区 -> 列 -> 关系 -> 度量值。
   • 添加关系——确保两侧都存在键列，且数据类型匹配；
   • 添加度量值——确认引用的列和表均存在；
5. 保存并验证——按照保存语义模型的更改和验证清单进行。

---

工作流：创作字段参数

适用场景： 用户要求创建、编辑、重新排序、重命名或删除字段参数。这是一个独立的模型侧计算表；匹配的报表切片器和视觉对象属于单独的报表工作，不在此范围内。

开始前，加载 field-parameters.md，并遵循其中定义的工作流。

步骤：

1. 连接并发现 - 按照连接到语义模型操作。创建之前，检查是否已有字段参数（携带 ParameterMetadata "kind": 2 的列），避免重复创建。
2. 转到匹配的子工作流，详见 field-parameters.md：
   • 创建新参数 -> 工作流：创建字段参数（第 1 级的 table_operations CreateFieldParameter）。
   • 编辑现有参数（添加 / 删除 / 重新排序 / 重新标记字段）-> 工作流：编辑字段参数（通过 partition_operations 重写分区；没有 UpdateFieldParameter 操作）。
   • 重命名或删除 -> 工作流：重命名或删除字段参数。
3. 保存并验证 - 按照保存语义模型更改和验证清单操作。确认这三列和 ParameterMetadata "kind": 2 均完好无损，以确保 Desktop 将该表识别为字段参数。

---

工作流：优化 DAX 性能

适用场景： 用户要求提升 DAX 查询性能、诊断运行缓慢的度量值或优化计算。

硬性要求： 需要支持跟踪的客户端（优先使用 MCP））

首先加载 dax-perf-decision-guide.md，并遵循其中定义的框架。只有在应用候选优化模式时才加载 dax-perf-patterns.md。该框架包括：

1. 用于对优化工作量进行分类的分级模型
2. 用于识别瓶颈的跟踪诊断
3. 包含候选优化技术的模式目录，以供测试和验证

---

工作流：分析最佳实践

适用场景： 用户要求根据最佳实践审查、审核或分析语义模型。

步骤：

1. 连接并盘点 - 按照连接到语义模型和发现语义模型元数据操作。记录所有表、列、关系、度量值和存储模式。
2. 加载适用指南 - 始终加载 modeling-guidelines.md；如果使用 Direct Lake，则加载 direct-lake-guidelines.md；评估命名时加载 naming-conventions.md；评估 DAX 时加载 dax-guidelines.md。
3. 评估 - 根据已加载的指南检查模型（星型架构、命名、关系基数和交叉筛选、带有 formatString 的显式度量值、列数据类型和 sourceColumn、隐藏的 FK 列、计算列与度量值的选择、Direct Lake 限制等）。
4. 按严重程度（严重、建议、可选）分组呈现发现。对于每项，说明违反的规则和建议的修复方案。等待用户批准。
5. 通过修改现有模型应用已批准的修复。
6. 保存并验证 - 按照保存语义模型更改和验证清单操作。

---

工作流：语义模型 AI 就绪度

适用场景： 用户要求让语义模型能够用于 Microsoft Fabric Copilot、Power BI Data Agent 或任何对话式 BI 体验。触发语句包括“Copilot 就绪度”“AI 就绪度”“为 AI 做准备”“为 Copilot 准备模型”。

开始前，加载 semantic-model-ai-readiness.md。

步骤：

1. 确认范围并收集背景信息——通过 ask_user，根据 何时适用 部分确认使用方式（仅报表／对话式 BI／两者兼有）和模型稳定性。收集业务背景（流程、关键指标、常见自然语言问题、术语）。不得凭空编造。
2. 连接并盘点——按照连接到语义模型进行操作。记录模型内容和源位置（PBIP／Fabric 工作区／仅 Desktop）。
3. 评估并确定处理方式——按顺序逐项检查就绪度清单；针对每个差距，根据支持的编辑方式对修复进行分类（Agent 可编辑的 TOM 元数据，或由用户在 Power BI“为 AI 准备数据”UI 中配置的 AI 专属产物）。
4. 按严重程度分组呈现发现，并为每项标注处理方式（Agent 可处理／需要用户操作）。等待用户批准。
5. 应用已批准的更改——通过修改现有模型应用 TOM 元数据修复；对于 AI 指令、AI Data Schema 和 Verified Answers，指导用户在 Power BI“为 AI 准备数据”UI 中配置，并且仅在用户同意后，才根据就绪度参考提供建议；如果是仅 Desktop 的 PBIX，则指导用户操作。
6. 保存、验证并建议进行实时测试——按照保存语义模型的更改和验证清单进行操作；建议用户在 Copilot 或 Data Agent 中测试有代表性的自然语言提示词，并迭代调整。

---

工作流：导出为 PBIP

适用场景： 用户要求将语义模型导出或保存到 PBIP 项目文件夹，或者没有可供部署的 Fabric 工作区（例如，在内存中构建模型后）。

重要事实： 导出模型只会生成 TMDL 定义文件，不会创建外围的 PBIP 文件夹结构（Report 文件夹、definition.pbism、definition.pbir、.pbip 入口文件）。导出前，Agent 必须先搭建这些结构，否则生成的结果无法在 Power BI Desktop 中打开。

开始前，加载 pbip.md，并遵循其中定义的 PBIP 文件夹结构。

步骤：

1. 确定目标位置——通过 ask_user 获取目标文件夹路径和语义模型名称。如果用户只提供了文件夹，则使用模型的数据库名称作为语义模型文件夹名称。
2. 搭建 PBIP 结构——按照 pbip.md，确保存在 <Name>.SemanticModel/（包含 definition/ 和 definition.pbism）、<Name>.Report/（包含 definition/ 和使用 byPath 引用的 definition.pbir），以及 <Name>.pbip。创建所有缺失项。
3. 将 TMDL 导出到 <Name>.SemanticModel/definition/，并遵循工具选择优先级：
   • 第 1 级（MCP）——对实时模型使用 MCP 导出／保存操作。
   • 第 2 级（Fabric 工作区，无 MCP）——调用 getDefinition（加载 semantic-model-rest-api.md），并写入返回的各个部分。
   • 磁盘上已有本地 TMDL 文件——将其复制或移动到 definition/ 文件夹。
4. 验证——确认 definition/ 文件夹至少包含 model.tmdl 和表 .tmdl 文件；确认 definition.pbism、<Name>.Report/definition.pbir（其中 byPath 正确指向 ../<Name>.SemanticModel）和 <Name>.pbip 均存在，且彼此引用正确。

---

工作流：部署到 Fabric

适用场景： 用户要求将语义模型部署或发布到 Fabric 工作区。

硬性规则 — 此工作流优先于默认的工具选择优先级。 不要仅仅因为 MCP 可用就默认使用 MCP。部署路径取决于模型的来源，而不是连接了哪些工具。如果模型来源是磁盘上的 PBIP/TMDL 文件，即使当前有活动的 MCP 会话，也必须使用 Fabric REST API。

决策树（自上而下选择，恰好匹配第一项时停止）：

1. 磁盘上是否有需要部署的 PBIP / TMDL 文件？ -> 是 — 使用 Fabric REST API。 使用 az rest 调用 createItemWithDefinition（新模型）或 updateDefinition（现有模型）。加载 semantic-model-rest-api.md。
   • 原因：通过 Fabric API 直接部署 TMDL 文件更可靠、速度更快，也可避免仅为推送模型而不必要地将其加载到 MCP。
   • 不要先在 MCP 中打开 PBIP，然后再通过 MCP 部署。这是此工作流明确禁止的反模式。
2. 模型是否已加载到活动的 MCP 会话中（例如刚在内存中构建完成，或当前正在通过 MCP 编辑），且没有涉及 PBIP/TMDL 文件？ -> 使用 MCP 工具进行部署，并指定目标工作区和语义模型名称。
3. 模型是否在 Power BI Desktop 中处于活动状态，且尚未保存为 PBIP？ -> 如果 MCP 已连接到 Desktop，使用 MCP Deploy。如果 MCP 不可用，指示用户先另存为 PBIP，然后从步骤 1 重新开始此工作流。

通过列出工作区中类型为 SemanticModel 的项目，验证部署是否成功。

只部署一次；部署操作不是幂等的。 重试部署会创建一个同名的第二个模型，之后部署会失败并提示 There are multiple datasets named '<name>'。如果遇到此错误，不要盲目重试：列出工作区的语义模型，删除所有同名重复项，然后从干净状态部署一次。如果要部署的模型可能已存在，请在单次部署之前删除现有的同名模型。

---

工作流：刷新语义模型

适用场景： 用户要求刷新语义模型中的数据。

只有在 Desktop 或 Fabric Service 中操作活动模型时才能刷新。如果使用本地 TMDL 文件，请先部署模型。

根据工具选择优先级触发刷新：

• Power BI Desktop：仅 Tier 1（MCP）— 使用 MCP Refresh 操作。
• Fabric Service：Tier 1（MCP Refresh 操作），或回退到 Power BI Enhanced Refresh API（加载 semantic-model-rest-api.md）。

如果刷新因凭据错误而失败，立即停止，并指示用户在 Power BI Service 中手动配置数据源连接。不要尝试以编程方式重试或绕过凭据错误。

---

工作流：在 Fabric 中管理语义模型

适用场景： 用户要求在 Fabric Service 中配置数据源、更新参数或管理语义模型的权限。

硬性规则 — 此工作流优先于默认的工具选择优先级。 不要默认使用 MCP（Tier 1），应优先使用 az rest 和 REST API。

数据源和参数

通过 Power BI REST API 获取/更新数据源和参数。加载 semantic-model-rest-api.md。

权限

通过 Power BI REST API 列出/授予/更新数据集用户权限。加载 semantic-model-rest-api.md。

连接绑定

加载 connection-binding.md 并遵循其中的说明。该参考文档涵盖前提条件、bindConnection 终结点、发现 -> 匹配 -> 绑定 -> 验证步骤、所有 connectivityType 值、解除绑定模式和故障排除。

关键规则（详情请参阅参考文档）：

• 使用 Fabric Bind Semantic Model Connection REST API（取代旧版 Power BI BindToGateway）。
• 每个数据源引用发送一个绑定请求——该 API 不支持批量绑定。
• 通过 List Item Connections 发现模型的数据源引用，然后将 connectionDetails 与 List Connections 进行匹配，找到目标 id。如果没有匹配项，请先创建连接。
• 通过重新列出项连接并触发刷新来验证。

---

验证清单

创建或修改模型后运行：

始终执行（适用于 PBIP、Desktop 和 Fabric Service）：

1. 检查 PBIP 结构——如果模型来自 PBIP 文件夹，请确保文件夹结构和文件正确（请参阅 pbip.md）。
2. 依据建模指南进行验证——针对每项更改重新检查 modeling-guidelines.md（Direct Lake 模型还需检查 direct-lake-guidelines.md）。

仅在连接到 Analysis Services 数据库时执行（Power BI Desktop 或 Fabric Service）：

3. 测试新增度量值——对每个新增度量值运行简单的 DAX 查询，验证其是否返回预期结果（例如，EVALUATE { [Measure Name] }）。仅处理本地 TMDL/PBIP 文件时跳过此步骤。
4. 测试表刷新——新建表时，触发刷新，以验证分区、数据源表达式和列映射是否正确。刷新失败通常表明 sourceColumn 名称不匹配、M 表达式无效，或 Direct Lake 实体引用不正确。仅处理本地 TMDL/PBIP 文件时跳过此步骤。

如果任何检查未通过，请修复问题并重新运行验证。

---

必须/优先/避免

必须

• 开始前了解数据源架构——在设计或修改模型前，分析源表、列和数据类型。
• 遵循建模指南——创建或编辑任何模型前，加载 modeling-guidelines.md；应用星型架构设计、命名约定以及列和度量值规则
• 遵循工具选择优先级——始终选择当前环境中可用的最高优先级工具层级；若更高优先级的选项可用，则不要混用层级

优先

• 优先采用星型架构，而非雪花架构或平面表——维度反规范化，并使用单列关系键
• 与现有模型模式保持一致——编辑现有模型时，沿用其命名约定和结构，而不是强加新的约定
• 优先使用 TMDL 格式，而非 TMSL——基于文本、便于查看差异，在 Fabric 中优先使用
• 更改后进行验证——使用工作流：发现语义模型元数据确认对象已创建。

避免

• 硬编码工作区/项 ID——通过 API 动态解析
• MCP 已连接时读取 TMDL 文件——Tier 1 MCP 会话处于活动状态时，对 *.tmdl 使用 view/glob 属于反模式（请参阅工具选择优先级）。
• 已注册 MCP 时手动编写 TMDL 文件——使用 create/edit/文件写入工具来搭建 model.tmdl、database.tmdl、relationships.tmdl 或 tables/*.tmdl 属于 Tier 1 反模式，新建模型时也不例外。应通过 MCP 工具构建并导出。

拒绝

• 管理 RLS/OLS 角色成员身份——不要建议使用 REST 调用、az rest URL、MCP 操作或 TMDL 更改来向安全角色添加或移除用户或组。此请求超出此处的处理范围，应拒绝并引导用户前往 Power BI 门户。

---

示例

范围说明——示例使用 az rest 进行发现，以解析 ID 并发现 Fabric 元数据（参见 COMMON-CLI.md § 查找工作区和项）。语义模型定义的编写通过 工具选择优先级 进行：Tier 1 优先使用 powerbi-modeling-mcp MCP（如果可用），Tier 2 则通过 getDefinition / updateDefinition 编辑 TMDL。

示例 1：修改现有语义模型

提示词：“为工作区 Marketing 中的语义模型 Sales 的所有可聚合列创建基础度量值。”

Agent 响应——遵循工作流：修改现有模型。

1. 通过 az rest 发现 ID。
2. 按照连接到语义模型和工具选择优先级中的说明连接到模型。注册了 powerbi-modeling-mcp 后，直接通过 MCP 连接到 Fabric 工作区模型（Tier 1）。否则回退到 Tier 2（getDefinition -> 在本地编辑 TMDL）。
3. 检查并规划——通过当前工具层级列出表和列；识别可聚合列（数值列、非外键、非隐藏的代理 ID），并遵循 modeling-guidelines.md 和 naming-conventions.md，为每列确定使用 SUM / AVERAGE / MIN / MAX。编写 DAX 前先加载 dax-guidelines.md。
4. 按照工作流：修改现有模型的说明添加度量值。
   • Tier 1（MCP）：为每个新度量值调用工具创建操作，并提供 expression、formatString 和目标表。不要手动编写 TMDL。
   • Tier 2（无 MCP）：直接编辑表的 .tmdl 文件，并通过 updateDefinition REST API 往返更新。
5. 按照保存语义模型的更改的说明保存并验证。

---

示例 2：从 Fabric Lakehouse 创建新的语义模型

提示词：“在工作区 Marketing 中创建新的 Power BI 语义模型，使用同一工作区中的 SalesLakehouse 作为数据源。”

Agent 响应——遵循工作流：创建新的语义模型。

1. 通过 az rest 发现工作区和 Lakehouse ID。
2. 发现 Lakehouse 架构——通过 Lakehouse OneLake API 或 Lakehouse 的 SQL Endpoint 列出表和列。记录表名、列名和数据类型——这些信息决定语义模型表、列定义和分区元数据。
3. 按照工具选择优先级选择工具层级：完整构建时优先使用 Tier 1（powerbi-modeling-mcp）。仅在未注册 MCP 时才使用 Tier 2（先搭建 PBIP/TMDL 脚手架，然后部署）。
4. 按照工作流：创建新的语义模型中的说明构建模型——数据源是 OneLake，因此存储模式为 Direct Lake（加载 direct-lake-guidelines.md 和 modeling-guidelines.md）。根据 Lakehouse 表设计星型架构，然后：
   • 创建空数据库。
   • 为 Lakehouse 连接创建一个共享的命名表达式。
   • 对于每个表：添加 EntityPartitionSource（模式为 directLake）-> 将列映射到 Lakehouse 列 -> 创建关系 -> 创建度量值。
5. 按照工作流：部署到 Fabric的说明部署：
6. 按照验证清单进行验证——确认模型显示在工作区中，并触发初始刷新以验证 Direct Lake 列映射已正确解析。

---

示例 3：将语义模型绑定到 Fabric 连接

提示词：“将工作区 Marketing 中的语义模型 Sales 绑定到 sql-prod 连接。”

Agent 响应 - 遵循 工作流：在 Fabric 中管理语义模型 § 连接绑定。不使用 MCP - 此工作流优先于 工具选择优先级，且仅使用 REST。

1. 通过 az rest 查找工作区和模型 ID。

2. 在 Fabric 中通过匹配服务器名称查找目标连接：

   SERVER="sql-prod"
   CONN_ID=$(az rest --method get --resource "https://api.fabric.microsoft.com" \
     --url "https://api.fabric.microsoft.com/v1/connections" \
     --query "value[?connectionDetails.path | contains(@, '$SERVER')] | [0].id" -o tsv)
   

   如果没有匹配的连接，停止并提示用户先按照 connection-binding.md 创建连接。

3. 按照 工作流：在 Fabric 中管理语义模型 § 连接绑定 执行绑定 - 加载 connection-binding.md，并遵循查找 -> 匹配 -> 绑定 -> 验证流程：

   • 列出模型的数据源引用（List Item Connections）。
   • 对于 connectionDetails 与 $CONN_ID 匹配的每个引用，调用 Fabric bindConnection 端点，每个数据源引用发送一个请求（不批量绑定）。

4. 验证 - 重新列出项目连接以确认绑定，并提示用户按照 工作流：刷新语义模型 触发刷新。凭据错误 -> 停止并引导用户前往 Service portal（参见 TROUBLESHOOTING）。

---

故障排除

症状	解决方法
MCP 连接失败	回退到 TMDL 编辑（参见工具选择优先级）。告知用户已回退。
TMDL 验证错误	查看错误详情，修复语法，然后重新验证。加载 tmdl-guidelines.md。
403 Forbidden / identity None	用户需要 Contributor 或更高角色 - 立即停止。不要重试。
401 Unauthorized	正确设置一次 --resource 受众（参见 semantic-model-rest-api.md）。如果受众正确后问题仍然存在，则表示缺少权限 - 停止并告知用户。不要循环重试。
202 Accepted 但没有结果	轮询 LRO，直到完成。
更新 Definition 后缺少部分内容	必须包含所有部分 - 已修改和未修改的部分。
刷新凭据错误	引导用户前往 Service portal 进行配置。不要重试。
度量值中的 DAX 错误	检查列名和表名引用（区分大小写）。确认所引用的对象存在。
部署失败	检查工作区权限、模型兼容级别和 Direct Lake 表达式源引用。
缺少数据源	确认 M 参数或命名表达式已正确定义。