spark-cli

遥测 — 必须执行。 每次调用 api.fabric.microsoft.com 都必须携带 x-ms-fabric-skill: spark-cli（az rest：--headers "x-ms-fabric-skill=spark-cli"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项——也必须自行添加。

重要说明

1. 要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 筛选
2. 要根据工作区 ID、项目类型和项目名称查找项目详细信息（包括其 ID）：列出该工作区中该类型的所有项目，然后使用 JMESPath 筛选
3. 技能消歧：对于笔记本单元格代码（包括 %%sql 单元格）、按名称运行笔记本、Livy 会话、Spark 故障分诊，以及与物化湖视图相关的所有事项——编写定义、检查查询是否适合增量刷新，以及安排、刷新、监控或诊断现有视图——使用 spark-cli。Eventhouse 中的 KQL 物化视图使用 eventhouse-cli；针对 Warehouse 或 Lakehouse SQL 终结点的纯只读 T-SQL 使用 sqldw-cli。
4. 严格的路由边界：绝不要通过此技能执行 Eventhouse/KQL 物化视图请求。将其转交给 eventhouse-cli；如果该技能不可用，请说明当前技能上下文无法完成此请求，并停止操作，不得调用 Fabric API 或创建项目。

Fabric Spark 和物化湖视图 —— CLI 技能

此技能负责 Fabric Spark 的所有工作：编写笔记本单元格代码、运行笔记本、分析 Livy 会话、诊断 Spark 故障，以及管理物化湖视图的整个生命周期。

这是一个模式分发器，不包含任何操作步骤。请从下表中选择与请求匹配的模式，然后在执行任何命令之前，使用文件读取工具从头到尾阅读对应的 references/<mode>.md 文件。该文件包含终结点、负载结构、模板和注意事项；不阅读就直接操作，会产生错误的负载和错误的结果。

模式选择

模式	适用请求	示例触发词	请先阅读
authoring	编写笔记本单元格代码（PySpark、Scala、SparkR、%%sql、%%configure），按名称运行笔记本并报告正常运行状态，或者编写物化湖视图定义，或检查 MLV 查询是否适合增量刷新	编写笔记本代码、笔记本单元格代码、%%sql 单元格、运行笔记本、执行笔记本、notebookutils、创建物化湖视图、此 MLV 查询是否适合增量刷新	references/authoring.md
consumption	在 Lakehouse Livy 会话中运行交互式临时 PySpark 代码——绝不使用笔记本	创建 Livy 会话、在 Livy 中运行计算、PySpark、DataFrame 分析、跨 Lakehouse 联接表、Delta 时间旅行	references/consumption.md
operations	诊断失败、不健康、受到限流或运行缓慢的 Spark 笔记本 / 管道 / Livy 运行	笔记本失败、Spark Livy 健康状况、Spark OOM、为什么我的笔记本运行缓慢、作业诊断、430 限流	references/operations.md
mlv	发现或操作现有物化湖视图：Spark SQL 发现、刷新计划、按需刷新、运行历史记录、取消操作以及刷新失败分类	发现 MLV、列出物化湖视图、安排 MLV、MLV 运行历史记录、取消刷新、触发 MLV 刷新、诊断 MLV 刷新失败	references/mlv.md

模式边界规则

模式由操作对象和结果决定，而非语言。Notebook 单元格始终属于 authoring，即使单元格使用 %%sql 也是如此。Livy 会话始终属于 consumption。FAILED 或状态不健康的 Spark 运行属于 operations；成功的运行由 authoring 报告。对于物化湖视图，模式由动词决定：编写或审查定义属于 authoring；发现、安排、刷新、监控或诊断现有 MLV 属于 mlv。如果必须执行发现操作，则只有在从 references/mlv.md 读取发现命令后，才切换到 Livy 的 consumption 模式或 Notebook 的 authoring 模式。

如果请求确实涉及多种模式，请逐一处理，并在开始每部分之前阅读对应的参考资料。阅读此表后，如果仍无法确定模式，请提出一个简短的澄清问题，而不是猜测。

终端写入——不可跳过的步骤

阅读参考资料并规划更改并不代表任务已完成。每种会修改状态的模式都必须以一次状态变更调用结束。如果没有发出该调用，就没有任何内容被持久化——请明确说明这一点，而不要报告成功。

模式	终端写入
authoring	对于现有 Notebook，使用 POST .../notebooks/{id}/updateDefinition 保存单元格；新建 Notebook 需要先调用 POST /v1/workspaces/{ws}/items；对于运行请求，通过 Jobs API 触发作业。将单元格代码打印到聊天中不等于保存或运行。
consumption	无——此模式为只读
operations	无——此模式为只读
mlv	对于按需刷新，调用 POST /v1/workspaces/{ws}/lakehouses/{lakehouse}/jobs/refreshMaterializedLakeViews/instances；对于计划请求，调用相应的创建、更新或删除接口。报告计划内容并不代表已创建计划。

报告任务完成之前，请确认终端调用已成功返回；如果参考资料说明需要回读，也请回读操作对象，以证明更改已生效。

通用要点（适用于所有模式）

首先解析工作区和项；所有模式都依赖这一步。

任务	参考资料	说明
在 Fabric 中查找工作区和项	COMMON-CLI.md	必读——解析任何工作区或项 ID 之前必须阅读
Fabric 拓扑与关键概念	COMMON-CORE.md	项类型、工作区、容量
环境 URL	COMMON-CORE.md	主权云／非公有云主机
身份验证与令牌获取	COMMON-CORE.md	audience 错误会导致 401；遇到任何身份验证问题前请阅读
身份验证操作指南	COMMON-CLI.md	az login 流程和令牌获取
核心控制平面 REST API	COMMON-CORE.md	分页、LRO 轮询、速率限制
注意事项与故障排除	COMMON-CLI.md	az rest audience、Shell 转义、令牌过期

规则

MUST

• 在执行任何操作之前，先从上表中准确选择一种模式。
• 将“设置我的数据”这类模糊请求视为范围不足。询问用户想要的工件、来源、目标位置和结果；绝不要通过查找并运行现有笔记本或作业来推断意图。
• 在该模式的第一个命令之前，先从头到尾阅读 references/<mode>.md，并将其作为你调用的第一个工具。只完整读取一次：不要重新打开，不要再次 grep，也不要逐页浏览。你已经读过它。
• 对加载的所有其他文件也遵循只读一次的原则，包括嵌套的 references/<mode>/*.md 子参考文件和共享的 common/*.md 文件：只打开确实需要的文件，每个文件从头到尾读取一次，之后绝不 grep 或重新打开。
• 通过列出并筛选来解析工作区和项目 ID，绝不要猜测 GUID。
• 将任何 Eventhouse/KQL 物化视图请求路由后立即停止。不可用的同级技能是阻止继续操作的边界，并不代表可以直接实现其工作负载。
• 请求跨越边界时，明确宣布模式切换。
• 将参考文件视为操作说明，而非交付内容。阅读后，针对实时工作区运行其中记载的命令，并报告实际结果。只引用参考文件内容而不执行操作，并不能回答请求。

PREFER

• 选择能够满足请求的最精简模式。
• 恰好只阅读一个模式参考文件。只有当请求确实涉及多个模式时，才加载第二个，并在加载前说明原因。
• 在首次回复中报告你选择的模式，以便用户纠正。

AVOID

• 仅依据此调度器采取行动——它有意省略了操作细节。
• 用参考文件摘要代替实际执行操作。
• 重新读取或再次 grep 已加载的参考文件；这会浪费轮次和令牌。
• 在只读模式下进行任何修改。
• 为此类工作加载其他技能（参见 CRITICAL NOTES 3）。
• 在所属技能不可用时，通过原始 REST 调用尝试处理范围外的请求。指出所属技能并停止；不要擅自通过在 spark-cli 范围之外创建 Fabric 工件来变通。

示例

用户请求	模式	要阅读的参考文件
“编写一个笔记本单元，读取 bronze 表并写入 silver Delta 表。”	authoring	references/authoring.md
“创建一个 Livy 会话，并统计 lakehouse 中不同客户的数量。”	consumption	references/consumption.md
“我的笔记本运行因 OOM 失败了——查明原因。”	operations	references/operations.md
“这个物化湖景查询是否已准备好进行增量刷新？”	authoring	references/authoring.md
“显示列出 schema silver 中 MLV 的 Spark SQL 命令。”	mlv	references/mlv.md
“为 lakehouse MLV 血缘安排每晚刷新，并显示其运行历史。”	mlv	references/mlv.md