拆解 skills-for-fabric 的 Agents → Skills → Common 三层架构：AI 如何理解 Microsoft Fabric

skills-for-fabric 是微软推出的一组可复用 AI 技能指令与 MCP 系统，让运行在 CLI、VS Code、Claude 中的 AI 助手能够真正"读懂"并操作 Microsoft Fabric 的工作负载。本文带你逐层拆解项目核心的 Agents → Skills → Common 三层架构，看懂 AI 是如何"理解"Fabric 的：任务如何被拆分、技能如何被路由、共享知识如何被复用，最后附上快速安装方法。

三层架构一览：各层分工是什么

在 AGENTS.md 中，项目明确定义了这种混合模型（Hybrid Model）：

Agents → Skills → Common：跨工作负载的编排交给 Agents；端点级的实现深度下沉到 Skills；共享知识集中在 Common。

层级	目录	职责	一句话理解
🧑‍💼 Agents	agents/	跨工作负载的任务编排与分工	"分活的团队负责人"
🛠️ Skills	skills/	单一工作负载的完整操作能力	"干活的专科工程师"
📚 Common	common/	所有技能共享的参考资料	"团队共享 Wiki"

这种分层带来两个直接好处：Agent 保持精简（只描述如何分派任务），Skill 保持专注（只覆盖一个领域），而所有"容易踩坑的知识"沉淀在 Common 层只维护一份。

Agents 层：5 个 AI"虚拟数字员工"及其分工

agents/ 目录下有 5 个 Agent 定义文件，每个都是一个带 YAML 元信息的 Markdown 文档，相当于给 AI 配了一个"虚拟岗位"：

Agent	定位	文件
FabricDataEngineer	跨 Spark / Warehouse / Pipeline 的数据工程总调度	agents/FabricDataEngineer.agent.md
FabricMigrationEngineer	Synapse / HDInsight / Databricks 迁移总指挥	agents/FabricMigrationEngineer.agent.md
FabricAdmin	容量、治理、安全、成本等运营卓越	agents/FabricAdmin.agent.md
FabricAppDev	构建连接 Fabric 数据的全栈应用	agents/FabricAppDev.agent.md
FabricIQ	用 Power BI 报表和语义模型回答业务问题	agents/FabricIQ.agent.md

Agent 的写法套路：人设 + 委派规则 + 行为边界

以 agents/FabricDataEngineer.agent.md 为例，每个 Agent 文件都包含 4 类关键部分：

1. Personality（人设）：用自然语言塑造一个"严谨、注重验证关卡的数据工程师"形象，让 AI 输出风格稳定；
2. Delegation Rules（委派规则）：明确写出"什么活路由给哪个 skill"，例如 spark-cli 管 Notebook 与 Lakehouse，eventhouse-cli 管 KQL，fabriciq 管只读 DAX 查询（见 agents/FabricDataEngineer.agent.md#L27-L40）；
3. Must / Prefer / Avoid（行为边界）：硬性要求（如"环境变量必须参数化"）、偏好（如"增量处理 + Delta Lake"）、禁区（如"不要把跨工作负载流程当单技能任务"）。

这正是"AI 理解 Fabric"的第一层含义：Agent 不直接干活，而是先做任务分解，再把子任务精确委派给对应技能。

Skills 层：25 个专项技能包与模式路由机制

skills/ 下有 25 个技能，覆盖 SQL 数仓（sqldw-cli）、Spark 与 Lakehouse（spark-cli）、Eventhouse/KQL（eventhouse-cli）、Dataflows Gen2、Eventstream、语义模型、部署流水线、迁移（synapse-migration、databricks-migration）等几乎所有 Fabric 工作负载。

每个技能是一个独立目录，核心是一个 SKILL.md 入口文件。打开 skills/spark-cli/SKILL.md 你会发现一个精妙设计：

SKILL.md 是一个"模式分发器"（Mode Dispatcher）

spark-cli 的 SKILL.md 自身不包含任何操作步骤，只做一件事——根据请求类型把任务路由到对应的参考文档：

模式	触发场景	首先阅读
authoring	写 Notebook 单元格、运行 Notebook、定义 Materialized Lake View	references/authoring.md
consumption	在 Livy 会话中做交互式 PySpark 分析	references/consumption.md
operations	诊断失败 / OOM / 变慢的 Spark 运行	references/operations.md
mlv	管理已有的 Materialized Lake View（调度、刷新、历史）	references/mlv.md

这种"先读对应手册、再动手"的强制流程，大幅降低了 AI 生成错误 API 调用的概率。多个技能（如 skills/eventhouse-cli/SKILL.md、skills/dataflows-cli/SKILL.md）还额外提供 upgrade 等模式，按"意图选模式"是该项目的统一范式。

另外还有一个隐蔽但重要的设计：每一次对 Fabric REST API 的调用都必须携带 x-ms-fabric-skill: <技能名> 请求头（见 common/COMMON-CLI.md#L32-L59），用于在服务端把流量归属到具体技能——相当于给 AI 的每次操作"盖了技能章"，便于微软侧统计和排障。

Common 层：避免知识重复的"共享大脑"

common/ 是整份仓库里唯一的事实来源，包含通用 CLI 模式、REST API 规范、Item 定义结构等，典型文件有：

文件	内容	谁在用
common/COMMON-CORE.md	Fabric 拓扑（Tenant/Capacity/Workspace/Item/OneLake）、环境 URL、各工作负载的 Token Audience 表、控制面 REST API 规范	全部技能
common/COMMON-CLI.md	把 REST 规范翻译成可直接复制的 az rest / curl / jq 命令，含认证配方与排错	全部技能
common/ITEM-DEFINITIONS-CORE.md	各类 Item 的 Definition 信封与各 Item 类型的定义结构	创建/更新 Item 的技能
common/SQLDW-AUTHORING-CORE.md、common/SPARK-NOTEBOOK-AUTHORING-CORE.md 等	按工作负载 × 模式拆分的核心参考	对应 CLI 技能

技能通过相对路径链接引用 Common，例如 spark-cli 的 SKILL.md 中直接链接 ../../common/COMMON-CORE.md#authentication--token-acquisition。这样做的价值：

• 单一事实来源：Token audience 写错导致 401 是最常见的坑，Common 只维护一份，25 个技能全部受益；
• 按需加载：AI 只在进入某模式时才读取对应参考文件，节省上下文 token；
• 安装时自动重写：通过 APM 安装单个技能时，apm.yml 声明的包根目录机制会让这些 ../../common/ 链接自动改写为物化副本，单技能安装也不"掉链子"。

完整流程：一次请求如何穿过三层

以仓库自带的示例提示词 prompt_examples/NYCTaxi_MedallionArchitecture.txt 为例（"为 NYC 出租车数据设计奖牌架构"），整个链路是这样的：

1. 入口：AI 读取 AGENTS.md（Copilot/Claude 等工具克隆仓库后自动发现 CLAUDE.md、GEMINI.md 等入口文件）；
2. Agent 编排：判定为跨工作负载的数据工程任务 → 交给 FabricDataEngineer，它把任务拆成"建 Lakehouse + 写 Bronze/Silver/Gold Notebook + 调度"等子任务；
3. Skill 执行：spark-cli 被激活，先按模式表读取 references/authoring.md，同时引用 Common 层的拓扑与认证知识；
4. 落地调用：执行 az rest 调用 Fabric REST API，并带上 x-ms-fabric-skill: spark-cli 归属头；
5. 需要实时工具时：MCP 服务器（如 FabricIQ、fabric-sqlendpoint）提供对数据源和 API 的实时工具访问，配置见 mcp-setup/README.md。

安装指南：如何在 AI 工具中启用 Fabric 技能

项目提供两种安装方式，均不需要阅读源码即可上手（完整说明见 README.md）：

方式一：Copilot CLI 插件（推荐，整包安装）

/plugin marketplace add microsoft/skills-for-fabric
/plugin install fabric-skills@fabric-collection

Power BI 报表/语义模型创作另有独立包 powerbi-authoring@fabric-collection。

方式二：APM 单技能安装（按需启用）

apm install microsoft/skills-for-fabric --skill sqldw-cli --target claude

--skill 参数可重复使用，逐个激活你需要的技能；技能会落到 .agents/skills/<name>/，共享参考资料由 APM 物化并自动重写链接。

架构启示：为什么三层比"一个大文档"更好

拆解完三层架构，可以看到 skills-for-fabric 背后的设计哲学：

• 🎯 职责分离：Agent 管"分活"，Skill 管"干活"，Common 管"常识"，互不越界；
• 📦 可组合性：25 个技能可以单独安装、独立演进，新增工作负载不用动已有技能；
• 🧭 路由即治理：模式分发器 + 委派规则 + 硬边界（如"KQL 物化视图禁止在 spark-cli 内执行"）让 AI 的行为可预期、可审计；
• 🔁 单一事实来源：所有易错知识集中在 Common，链接自动重写保证单技能安装也完整可用。

这套 Agents → Skills → Common 的范式，本质上是把资深 Fabric 团队的"组织知识"翻译成了 AI 可以执行的指令体系——这也是"让 AI 真正理解 Microsoft Fabric"的核心答案。