Microsoft Fabric AI助手技能脚手架：统一开发规范与生产力提升实践

1. 项目概述：为AI编码助手量身定制的Microsoft Fabric技能脚手架

如果你和我一样，是一名经常与Microsoft Fabric打交道的开发者或数据工程师，那么你一定遇到过这样的场景：每次启动一个新的Fabric项目，或者切换到一个新的AI编码助手（比如GitHub Copilot、Claude Code或Cursor）时，都需要花大量时间重新配置、重新“训练”这个助手，让它理解Fabric特有的工作流、API调用模式和最佳实践。这个过程不仅重复、低效，而且不同助手之间的配置还难以保持一致，导致团队协作时出现“方言”差异。

kimtth/ms-fabric-skills-dev-starter这个项目，就是为了彻底解决这个痛点而生的。它不是一个通用的AI代理模板，而是一个专门为Microsoft Fabric生态构建的、开箱即用的技能脚手架。简单来说，它提供了一套预先配置好的“指令集”和“技能库”，能让你的AI编码助手瞬间变成一个精通Fabric的专家伙伴。无论是Lakehouse的Delta表操作、Warehouse的SQL开发、Eventhouse的KQL查询，还是Power BI语义模型的TMDL管理，这个Starter都为你准备好了标准化的、可复用的提示词和操作指南。

它的核心价值在于“对齐”。通过一套共享的、中心化的指令文件（.agents/instructions.md），它能确保你团队里使用不同AI助手（Copilot, Claude, Cursor, Windsurf）的所有成员，都遵循同一套Fabric开发规范和平台约定。这极大地减少了沟通成本，提升了代码质量和开发速度。对于需要快速上手Fabric、构建标准化数据工程流程的团队和个人开发者而言，这个项目无疑是一个强大的生产力倍增器。

2. 核心设计思路与架构解析

2.1 为什么是“Fabric-First”而非通用模板？

市面上已经有不少针对AI编码助手的通用提示词库或“咒语”集合，但它们往往过于宽泛，缺乏对特定平台深度工作流的支持。Fabric作为一个统一的数据分析平台，其概念和操作与传统的独立服务（如独立的Spark集群、SQL Server、Kusto）有显著不同。例如，Fabric中的Lakehouse集成了Spark、Delta Lake和OneLake存储，其API调用模式、身份验证范围（Scopes）和长运行操作（LRO）的处理方式都有其独特性。

这个Starter项目采用了“Fabric-First”的设计哲学。这意味着它的整个结构、技能分类和参考文档，都是围绕Fabric的核心组件和工作负载来组织的。它没有试图去覆盖所有的Azure服务或编程语言，而是深度聚焦于Fabric平台本身，确保提供的每一条指令都是针对Fabric场景优化过的、最实用的“干货”。这种深度垂直的设计，使得AI助手生成的代码和建议的准确性、相关性大大提高。

2.2 技能（Skills）的分层与组织逻辑

项目的技能体系设计得非常清晰，采用了平台核心技能与端点专项技能相结合的分层架构。

第一层：平台核心技能（.agents/skills/fabric-core）这是所有Fabric工作的基石。它定义了与平台交互的通用模式和约束。例如：

• 拓扑与身份验证：明确Fabric REST API的基地址（https://api.fabric.microsoft.com/v1/），并详细列出了针对不同目标（REST API、OneLake、SQL Endpoint、Kusto、Power BI XMLA）所需的不同OAuth Scope。这是很多新手容易混淆的地方，错误的Scope会导致API调用失败。
• 通用API模式：系统化地处理Fabric API的三大特性：分页（Pagination）、长运行操作（Long-Running Operations, LRO）和限流（Throttling）。例如，它指导AI助手如何解析continuationToken来遍历列表，如何轮询202 Accepted响应的Location头来跟踪异步任务状态，以及遇到429 Too Many Requests时如何根据Retry-After头进行退避重试。
• OneLake模式：指导如何通过abfss://路径与OneLake交互，这是Fabric中数据存储的统一入口。

第二层：端点专项技能（来自microsoft/skills-for-fabric）这一层针对Fabric内的具体工作负载，提供了“创作”和“消费”两种视角的技能。

• 创作型技能（*-authoring-cli）：面向开发和管理任务。例如，spark-authoring-cli指导如何创建Notebook、提交Spark作业、管理Delta表Schema；powerbi-authoring-cli则关注如何使用TMDL（Tabular Model Definition Language）创建和更新语义模型。
• 消费型技能（*-consumption-cli）：面向数据查询和分析任务。例如，sqldw-consumption-cli专注于编写高效的只读SQL查询来从Warehouse中提取数据；eventhouse-consumption-cli则聚焦于编写Kusto查询语言（KQL）来探索实时数据。

第三层：代理角色与共享参考

• 代理角色（.agents/agents/）：定义了如FabricDataEngineer、FabricAdmin、FabricAppDev等角色。这相当于为AI助手预设了不同的“人格”和专注领域。当你以数据工程师的身份工作时，可以引导助手更多地关注Medallion架构、ETL流水线设计；当你需要处理治理和成本问题时，则可以切换到FabricAdmin视角。
• 共享参考（.agents/common/）：这里存放了最底层的、原子化的参考文档，如COMMON-CLI.md中包含了使用az rest命令调用Fabric API的具体配方，ITEM-DEFINITIONS-CORE.md详细说明了Fabric中各种“项”（Item）的JSON结构。这些是构建更高级技能的“乐高积木”。

这种分层架构的好处是模块化和可复用性极强。你可以根据项目需要，灵活组合不同的技能和角色，构建出最适合当前任务的AI助手配置。

2.3 多代理统一入口的设计妙处

项目一个非常巧妙的设计是它的入口点管理。它为不同的AI编码助手提供了各自的入口文件（如.cursorrules、CLAUDE.md），但这些文件最终都路由到同一个中心文件——.agents/instructions.md。

这样做有几个显著优势：

1. 一致性：无论团队成员使用Copilot还是Cursor，他们获得的关于Fabric的核心指导和约定都是完全一致的，避免了因工具不同而产生的知识偏差。
2. 可维护性：当需要更新Fabric的最佳实践或添加新技能时，只需修改中心文件.agents/instructions.md，所有代理的配置会自动同步更新，维护成本极低。
3. 低侵入性：每个AI助手都有自己认可的配置文件格式和位置。项目通过提供符合各自规范的“桥接”文件，实现了无缝集成，用户无需改变自己的使用习惯。

注意：在实际部署时，你需要确保这些入口文件（如.cursorrules）被放置在项目根目录，并且你使用的AI助手已启用读取本地规则文件的功能。对于GitHub Copilot，通常需要将指令放在.github/copilot-instructions.md中。

3. 环境准备与快速上手实操

3.1 前置条件检查与工具安装

在开始使用这个Starter之前，你需要确保本地开发环境满足基本要求。这不仅仅是安装软件，更是理解每个组件的作用。

1. Python 3.13+项目要求Python 3.13或更高版本。我建议使用pyenv或conda这样的版本管理工具，以便在不同项目间灵活切换Python版本。

# 使用pyenv安装指定版本 pyenv install 3.13.1 pyenv local 3.13.1 # 在当前目录使用该版本

高版本Python能确保你使用最新的语言特性和库支持，这对于Fabric中较新的SDK（如ms-fabric-cli）可能很重要。

2. Azure CLI 认证这是与Fabric交互的钥匙。你需要安装Azure CLI并登录到拥有Fabric工作区访问权限的Azure订阅。

# 安装Azure CLI (如未安装) # macOS: brew install azure-cli # Ubuntu: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash # 登录 az login # 如果有多租户，使用 --tenant 参数 # az login --tenant <your-tenant-id> # 验证登录状态和默认订阅 az account show

az login会打开浏览器让你完成OAuth2认证。成功后，CLI会缓存你的凭据。

3. Microsoft Fabric 容量你需要在Azure门户中拥有一个已分配的Fabric容量（Fabric Capacity）。对于开发和测试，F2（试用版）或P1（入门版）即可。你需要知道你的Fabric工作区（Workspace）位于哪个容量下，并且你的账号在该工作区中拥有足够的权限（如管理员、成员或贡献者角色）。

4. Node.js 18+ (可选)如果你计划运行或自定义项目中的Fabric MCP（Model Context Protocol）服务器，则需要Node.js环境。MCP服务器是一个独立进程，它向AI助手（如Claude Desktop）暴露Fabric API工具，实现更强大的交互能力。

node --version # 确认版本 >= 18

3.2 身份验证与访问令牌获取

与Fabric REST API交互，最核心的一步是获取有效的访问令牌（Access Token）。Starter项目推荐使用Azure CLI来获取，这是最方便且安全的方式之一。

获取API访问令牌：

az account get-access-token --resource https://api.fabric.microsoft.com

这条命令会输出一个JSON，其中包含accessToken字段。这个令牌是调用Fabric REST API的凭证。它的有效期通常是一小时。

关键点解析：

• --resource参数指定了令牌的目标资源。对于Fabric REST API，必须是https://api.fabric.microsoft.com。如果你需要访问OneLake存储，则需要获取针对https://storage.azure.com的令牌。项目中的fabric-core技能文档详细列出了所有需要的资源范围（Scopes），这是正确配置身份验证的关键。
• 在实际脚本或应用中，你通常不会手动复制令牌，而是通过Azure CLI的Python SDK (azure-identity) 或直接使用az account get-access-token命令的输出，以编程方式获取并注入到HTTP请求头中：

  # 示例：在Shell脚本中使用令牌调用API TOKEN=$(az account get-access-token --resource https://api.fabric.microsoft.com --query accessToken -o tsv) curl -H "Authorization: Bearer $TOKEN" https://api.fabric.microsoft.com/v1/workspaces

实操心得：在自动化流水线（如GitHub Actions）中，建议使用服务主体（Service Principal）进行认证，而非个人账号。你可以使用az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant-id>，然后同样用get-access-token获取令牌。务必妥善保管服务主体的密码或证书。

3.3 与你的AI编码助手集成

这是最激动人心的部分。根据你使用的AI助手，集成方式略有不同，但原理相通：让助手加载Starter提供的指令文件。

1. 对于 Cursor：Cursor会自动读取项目根目录下的.cursorrules文件。你只需要将本Starter项目克隆到本地，或者将其中的.cursorrules文件内容合并到你现有项目的规则中。Cursor会在你打开项目时应用这些规则。

2. 对于 GitHub Copilot：在项目根目录创建或更新.github/copilot-instructions.md文件。你可以直接将本Starter中.agents/instructions.md的内容复制过去，或者通过引用（如果支持）来包含。Copilot会在该代码库的上下文中参考这些指令。

3. 对于 Claude Code：类似地，在项目根目录放置CLAUDE.md文件。Claude Code会识别并利用其中的指导。

4. 对于所有助手（统一参考）：无论你使用哪个入口点，最终的核心都是.agents/instructions.md文件。我强烈建议你花时间阅读这个文件，它就像一本Fabric开发的“宪法”，定义了所有的基础规则和模式。你也可以根据自己团队的特定需求，在这个文件的基础上进行定制化增删。

集成后的效果：当你开始编写与Fabric相关的代码时，例如在Python Notebook中想要创建一个Delta表，你的AI助手会基于技能库中的spark-authoring-cli，给出符合Fabric最佳实践的代码建议，比如使用正确的spark.sql语法、包含表属性设置、甚至提示你考虑分区策略和V-Order优化，而不是生成一个通用的、可能不适用于Fabric环境的Spark代码片段。

4. 核心技能深度解析与应用场景

4.1 Lakehouse工程技能 (fabric-lakehouse)

Lakehouse是Fabric中数据工程的核心。fabric-lakehouse技能指导AI助手如何高效、正确地在此环境中工作。

Medallion架构的实现指导：技能明确倡导使用Bronze（原始）、Silver（清洗）、Gold（业务就绪）三层架构。它会指导助手生成符合各层约定的代码。

• Bronze层：建议使用自动加载模式（autoLoader）或COPY INTO命令将原始数据以Parquet或Delta格式摄入，并保留源系统的元数据（如_source_file_name,_ingestion_time）。

  # AI助手基于技能可能建议的Bronze层写入模式 df_raw = spark.read.format("parquet").load("abfss://raw@onelake.dfs.fabric.microsoft.com/...") df_raw.write.mode("append").format("delta").saveAsTable("bronze.sales_raw")

• Silver层：指导进行数据清洗、去重、类型转换和基础聚合。技能会强调使用Delta表的MERGE操作进行增量更新，并利用Change Data Feed (CDF) 来追踪数据变更。
• Gold层：专注于创建面向特定业务场景的聚合表、维度表和事实表。技能会建议使用物化视图或计划性笔记本作业来维护Gold层数据，并考虑使用V-Order优化读取性能。

Delta表操作的最佳实践：

• Schema演化：指导使用spark.databricks.delta.schema.autoMerge.enabled或在write操作中指定mergeSchema选项来安全地添加新列。
• 优化与压缩：建议定期运行OPTIMIZE命令来合并小文件，并使用VACUUM清理旧版本（注意保留期）。技能会提醒你VACUUM是不可逆的。
• Shortcuts使用：指导如何创建指向外部数据源（如Azure Data Lake Storage Gen2）的Shortcuts，实现虚拟化而不移动数据。

注意事项与避坑：

• V-Order：Fabric的Lakehouse默认启用V-Order写入优化。技能会提醒你，这是一个写入时的优化，能显著提升后续读取（尤其是列式查询）的性能，但你可能无法在非Fabric的Spark环境中直接读取V-Ordered的文件。对于需要跨平台共享的数据，需要考虑这一点。
• PySpark vs. Spark SQL：技能会引导你根据任务复杂度选择。对于简单的ETL，使用Spark SQL（spark.sql()）可能更直观且易于被AI助手理解；对于复杂的业务逻辑，使用PySpark DataFrame API可能更灵活。助手会根据上下文给出合适的建议。

4.2 Warehouse与SQL端点技能 (sqldw-authoring-cli/sqldw-consumption-clli)

Fabric Warehouse提供了完整的T-SQL表面区域，但与传统SQL Server仍有差异。这些技能帮助AI助手理解这些边界。

创作视角（Authoring）：

• DDL限制：指导助手了解Fabric Warehouse中支持的T-SQL DDL子集。例如，创建表时，它可能会建议使用CREATE TABLE ... WITH (DISTRIBUTION = ROUND_ROBIN, ...)，并提醒你某些高级索引选项或文件组语法可能不可用。
• 存储过程与视图：指导编写存储过程和视图，但会强调需要在Fabric的上下文中测试，因为并非所有系统存储过程或动态管理视图（DMV）都可用。
• 数据加载：推荐使用COPY INTO语句从OneLake中的文件高效加载数据到Warehouse表，并生成包含错误处理（ERRORFILE）的完整语句。

消费视角（Consumption）：

• 查询优化：指导编写针对大规模数据优化的查询，例如避免使用SELECT *，提倡使用明确的列清单；建议使用合适的WHERE子句和JOIN条件来利用分布键（如果表是哈希分布的）。
• 连接管理：提醒注意SQL端点的连接限制和查询超时设置，对于长时间运行的查询，建议拆分为更小的批次或使用异步执行模式。

一个典型场景：当你对AI助手说：“为Fabric Warehouse写一个查询，计算每个产品类别的月销售额”，基于sqldw-consumption-cli技能，它生成的代码可能不仅包括基本的GROUP BY，还会建议你：

1. 检查相关表是否已设置合适的分布键以减少数据移动。
2. 使用APPROX_COUNT_DISTINCT（如果可用）来快速估算唯一客户数，而不是精确但昂贵的COUNT(DISTINCT ...)。
3. 提醒你将结果写入到一个新的表或临时表中，以便在Power BI中直接连接，而不是每次都运行复杂查询。

4.3 Power BI语义模型技能 (powerbi-authoring-cli)

对于需要将数据模型与Power BI集成的场景，这项技能至关重要。它专注于TMDL（Tabular Model Definition Language）——一种用于定义语义模型的YAML格式。

TMDL开发流程：技能会指导AI助手遵循“代码优先”的模型开发方式。

1. 初始化：使用pbi-toolsCLI或Fabric API从现有的Power BI数据集（.pbix）提取TMDL定义。
2. 版本控制：将TMDL文件（.tmdl）纳入Git版本控制。AI助手可以帮助你编写有意义的提交信息，比如“新增SalesAmount度量值”或“修改Product维度的层次结构”。
3. 编辑与验证：在YAML文件中直接编辑表、列、度量值、关系等。AI助手可以基于技能，在你添加一个新的度量值时，自动建议正确的DAX格式、格式字符串，并提醒你将其放入正确的显示文件夹（Display Folder）。

   # AI助手可能帮助生成或补全的TMDL片段 measures: - name: Total Sales expression: SUMX ( 'Sales', 'Sales'[Quantity] * 'Sales'[Unit Price] ) formatString: $#,##0.00 displayFolder: "Sales Metrics"

4. 部署：指导使用Fabric API或pbi-tools将更新后的TMDL部署回Fabric工作区，触发语义模型刷新。

注意事项：

• 混合模式：技能会提醒你，如果语义模型使用了DirectQuery或混合模式，TMDL中定义的一些计算列或度量值可能需要后端数据源的支持，部署前需验证。
• 增量刷新策略：指导配置增量刷新策略（RangeStart/End参数），AI助手可以帮助编写用于分区过滤的M查询或SQL语句。

4.4 端到端Medallion架构技能 (e2e-medallion-architecture)

这是将多个技能串联起来的综合技能。它指导AI助手如何设计一个从数据摄入到业务洞察的完整流程。

场景示例：构建一个销售分析管道

1. 数据摄入（Bronze）：助手基于spark-authoring-cli，建议使用Fabric数据管道或Notebook，通过COPY INTO或Spark作业将CSV/JSON销售数据从外部存储加载到Lakehouse的Bronze区，并添加审计列。
2. 数据清洗与整合（Silver）：助手基于fabric-lakehouse技能，建议创建一个Notebook，读取Bronze表，进行数据质量检查（去重、处理空值、标准化货币和日期），将清洗后的数据写入Silver区的Delta表，并建立与产品维度表、客户维度表的关系。
3. 业务聚合（Gold）：助手建议在Warehouse中创建物化视图，或者使用Spark SQL进行复杂的聚合计算（如计算客户生命周期价值、产品关联性），将结果写入Gold区的表或直接作为Power BI的查询视图。
4. 语义模型与报告（Power BI）：助手基于powerbi-authoring-cli技能，指导创建或更新TMDL，将Gold层的表作为数据源引入，定义度量值（如YoY增长率、利润率）和层次结构，最后部署到Fabric工作区并配置定时刷新。
5. 编排与监控：助手可能还会建议使用Fabric数据工厂的管道来编排上述Notebook和SQL脚本的执行顺序，并设置警报监控作业失败或数据延迟。

这个技能的价值在于，它让AI助手具备了“架构师”的视野，能够在你描述一个业务目标时，给出一个连贯的、符合Fabric最佳实践的技术实现方案草图，而不仅仅是生成一段孤立的代码。

5. MCP服务器配置与高级工作流

5.1 MCP是什么？为什么需要它？

MCP（Model Context Protocol）是一个新兴的开放协议，它允许像Claude、Cursor这样的AI助手连接到外部工具、数据库和API，从而极大地扩展了助手的能力边界。你可以把它想象成给AI助手安装了一个“插件系统”。

在这个Starter的上下文中，Fabric MCP服务器就是一个专门的插件，它让AI助手能够：

• 发现API：动态查询Fabric REST API的端点、参数和模式，无需你事先记忆所有细节。
• 执行操作：在获得你授权后，直接通过助手界面执行创建Workspace、运行Notebook、查询数据等操作。
• 获取上下文：将Fabric工作区中的元数据（如表结构、Pipeline定义）作为上下文提供给助手，使它的建议更具针对性。

例如，你可以直接对Claude说：“使用Fabric MCP，列出我‘Sales-Analytics’工作区中的所有Lakehouse”，它就能通过MCP服务器调用Fabric API并返回结果。

5.2 配置与注册MCP服务器

项目中的mcp-setup/目录提供了快速配置的脚本和模板。

1. 使用提供的脚本（以Claude Desktop为例）：假设你已经运行了一个Fabric MCP服务器（例如通过npm install -g fabric-pro-dev-mcp-server安装并运行），它监听在http://localhost:3000。

• Windows (PowerShell):

  cd /path/to/ms-fabric-skills-dev-starter .\mcp-setup\register-fabric-mcp.ps1 -ServerUrl "http://localhost:3000" -ServerName "my-fabric-server"

  这个脚本会修改Claude Desktop的配置文件（通常在%APPDATA%\Claude\claude_desktop_config.json），添加MCP服务器配置。
• macOS/Linux (Bash):

  cd /path/to/ms-fabric-skills-dev-starter ./mcp-setup/register-fabric-mcp.sh --server-url "http://localhost:3000" --server-name "my-fabric-server"

2. 手动配置：你也可以参考mcp-setup/mcp-config-template.json模板，手动编辑你的AI助手配置。关键配置项包括：

{ "mcpServers": { "my-fabric-server": { "command": "npx", "args": ["-y", "fabric-pro-dev-mcp-server"], "env": { "FABRIC_ACCESS_TOKEN": "<YOUR_TOKEN_OR_AUTH_METHOD>" } } } }

重要安全提示：FABRIC_ACCESS_TOKEN环境变量用于MCP服务器向Fabric API认证。绝对不要将硬编码的令牌提交到版本控制系统。应该使用环境变量注入、密钥管理服务或让MCP服务器启动时通过Azure CLI/MSI等方式动态获取令牌。

3. 验证配置：重启你的AI助手（如Claude Desktop），通常可以在助手的设置或关于页面看到已连接的MCP工具。在对话中，你可以尝试询问：“你能使用Fabric MCP工具做什么？” 助手应该能列出可用的Fabric相关操作。

5.3 结合技能与MCP的增强工作流

当技能库（提供知识和模式）与MCP服务器（提供执行能力）结合时，会产生强大的化学反应。

工作流示例：创建一个新的Lakehouse并初始化表结构

1. 对话发起：你对AI助手说：“我想在‘Dev’工作区创建一个名为‘CustomerData’的新Lakehouse，并在里面创建一个名为‘customers’的Delta表，包含id、name、email和created_at字段。”
2. 技能指导：助手首先调用fabric-core和fabric-lakehouse技能库中的知识，理解创建Lakehouse需要调用哪个REST API（POST /v1/workspaces/{workspaceId}/items），以及创建Delta表的正确Spark SQL语法。
3. MCP执行：助手通过MCP服务器，首先查询“Dev”工作区的ID，然后调用创建Lakehouse的API。接着，它可能会建议并执行一个Notebook代码片段，在该Lakehouse中运行CREATE TABLE customers ... USING DELTA语句。
4. 结果反馈与下一步：助手通过MCP获取操作结果，并反馈给你：“Lakehouse ‘CustomerData’已创建，ID为xxx。Delta表‘customers’也已创建成功。接下来是否需要我帮你设置一个增量数据加载的Pipeline？”

这个过程中，你无需离开聊天界面，也无需手动查找API文档或编写完整的脚本。AI助手在技能库的指导下，通过MCP作为执行臂，完成了一系列复杂的操作。

注意事项：

• 权限边界：MCP服务器通常以当前登录用户的身份执行操作。确保你了解并信任MCP服务器的代码，因为它将拥有你令牌所代表的权限。最好在开发或测试环境中先行试用。
• 错误处理：MCP协议仍在发展中，网络错误或API变更可能导致操作失败。技能库中关于错误处理（如重试、检查状态码）的指导同样适用于MCP触发的操作。你需要教导助手如何处理这些异常情况。

6. 常见问题、排查技巧与最佳实践

6.1 身份验证与权限问题

这是新手最常遇到的拦路虎。

问题1：API调用返回401 Unauthorized或403 Forbidden。

• 排查步骤：
  1. 检查令牌有效性：运行az account get-access-token --resource https://api.fabric.microsoft.com --query expiresOn查看令牌是否过期。令牌默认有效期为1小时，过期后需重新获取。
  2. 检查资源范围：确认你获取令牌时使用的--resource参数与你要调用的API匹配。调用Fabric REST API用https://api.fabric.microsoft.com；读写OneLake文件需要用https://storage.azure.com。
  3. 检查权限：在Azure门户中，确认你的账号在目标Fabric工作区中至少拥有“成员”或“贡献者”角色。对于某些管理操作，可能需要“管理员”角色。同时，确保你的Azure订阅下的Fabric容量有足够的可用资源。
• 最佳实践：在脚本开头，总是先验证令牌或重新获取。对于长时间运行的作业，实现令牌刷新逻辑。

问题2：在Notebook中使用PySpark时，访问OneLake路径失败。

• 原因：Notebook会话可能使用不同的身份上下文（如工作区身份）。虽然通过az login获取了个人令牌，但Spark作业运行时可能未继承该认证。
• 解决方案：
  1. 确保工作区已启用“计算”并配置了正确的身份。
  2. 对于需要访问外部ADLS Gen2的数据，优先使用Lakehouse的Shortcuts功能。Shortcuts在Fabric内部管理身份验证，无需在代码中处理令牌。
  3. 如果必须直接使用abfss路径，考虑使用工作区系统分配的管理标识（MSI），并通过Spark配置传递认证信息（此方法较复杂，参考官方文档）。

6.2 API调用模式与错误处理

问题3：列表API只返回了部分结果。

• 原因：Fabric REST API的列表接口（如列出工作区中的所有项）普遍使用分页。默认返回第一页（通常最多100条记录）。
• 解决方案：遵循fabric-core技能中的分页模式。你需要检查响应头或响应体中的continuationToken字段。如果存在，则在后续请求的URL中添加?continuationToken=<token_value>参数，直到continuationToken为null。

  # 伪代码示例 items = [] continuation_token = None while True: url = "https://api.fabric.microsoft.com/v1/workspaces/{id}/items" if continuation_token: url += f"?continuationToken={continuation_token}" response = make_request(url) items.extend(response.json()["value"]) continuation_token = response.json().get("continuationToken") if not continuation_token: break

问题4：创建或删除操作返回202 Accepted后，如何知道是否成功？

• 原因：这是长运行操作（LRO）。Fabric异步处理这些请求，立即返回一个任务ID和状态查询地址。
• 解决方案：
  1. 从202响应的Location头或x-ms-operation-id头获取操作ID。
  2. 向Location指向的URL发起轮询GET请求。
  3. 持续轮询，直到响应状态为200且返回体中的status字段为Succeeded或Failed。注意遵循Retry-After头的建议间隔，避免触发限流。

问题5：请求频繁失败，返回429 Too Many Requests。

• 原因：触发了Fabric API的速率限制。
• 解决方案：
  1. 立即停止：收到429后，必须停止发送请求。
  2. 读取Retry-After头：该头会告诉你需要等待多少秒（或一个时间戳）。
  3. 实现退避策略：等待指定的时间后重试。可以考虑使用指数退避策略增加重试间隔。
  4. 优化请求模式：批量获取数据（如果API支持）、缓存频繁访问的元数据、减少不必要的API调用。

6.3 开发与协作最佳实践

1. 技能库的定制化：不要将Starter项目视为一成不变的。你应该将其作为基础，根据自己团队的技术栈和业务规范进行裁剪和扩充。

• 添加公司内部规范：例如，你们公司可能规定所有Delta表都必须包含etl_batch_id和updated_ts字段。你可以将这个规则添加到fabric-lakehouse技能的YAML frontmatter或指导文本中。
• 集成内部工具：如果你们有内部的包管理或部署系统，可以创建新的技能文件来指导AI助手如何使用这些工具与Fabric交互。

2. 将技能库纳入CI/CD：为了确保团队一致性，可以将.agents/目录作为子模块（Git Submodule）引入到各个项目仓库中。这样，当中心技能库更新时，所有项目可以通过更新子模块来同步最新规范。在CI流水线中，可以添加一个检查步骤，确保项目中的AI助手配置文件与中心技能库的版本兼容。

3. 结合Infrastructure as Code (IaC)：对于Fabric工作区、容量、网关等资源的创建，建议使用Bicep、Terraform或Azure Resource Manager (ARM) 模板。你可以训练AI助手理解这些IaC模板，并基于技能库中的模式，帮助你编写或修改模板代码，实现Fabric环境的可重复部署。

4. 文档与知识传承：这个Starter项目本身就是一个极好的活文档。鼓励团队成员在遇到新的Fabric使用模式或解决了一个棘手问题后，将经验总结成新的“技能”或补充到现有技能中，提交回共享库。这样，AI助手就能学习到整个团队积累的集体智慧，让新成员也能快速达到资深成员的水平。

踩过的坑：早期我们曾尝试为每个项目单独维护一套AI助手提示词，结果很快出现了碎片化和不一致。后来我们采用了类似本Starter的中心化共享技能库模式，并建立了简单的评审流程（对.agents/目录的修改需要团队核心成员Review），才真正实现了知识沉淀和工具效能的规模化提升。记住，工具的目的是赋能，而不是增加负担。从一个小而精的技能子集开始，在实践中逐步完善，是最有效的落地方式。