fabric-cli-core

Fabric CLI 核心

此技能为通过 Fabric CLI（fab） 操作 Microsoft Fabric 的 AI Agent 提供安全、一致的默认设置。

1 - Fabric CLI 心智模型（路径和实体）

自动化脚本

用于核心 CLI 任务的即用型 Python 脚本。运行任意脚本时添加 --help，即可查看完整选项。

脚本	用途	用法
health_check.py	验证 CLI 安装、身份验证状态和连接情况	python scripts/health_check.py [--workspace WS]

脚本位于此技能的 scripts/ 文件夹中。

路径和实体

• 将 Fabric 视为类似文件系统的层级结构，路径中的实体后缀统一使用点号（.）（例如 .Workspace、.Folder、.SemanticModel）。
• 层级结构如下：
  • Tenant：容纳所有内容的顶级容器。
  • Workspace：个人或团队工作区，可容纳文件夹、项和工作区级元素。
  • Folder：用于整理工作区内各项内容的容器（支持约 10 层嵌套）。
  • Item：工作区或文件夹中的单个资源（例如 Notebook、SemanticModel、Lakehouse）。
  • OneLakeItem：位于 Lakehouse 中的 OneLake 存储项（表、文件等）。
• 优先使用并生成如下路径：
  • /Workspace1.Workspace/Notebook1.Notebook
  • /Workspace1.Workspace/FolderA.Folder/SemanticModel1.SemanticModel
  • /Workspace1.Workspace/FolderA.Folder/lh1.Lakehouse/Tables（OneLakeItem）
• 如果用户提供的标识符有歧义，请询问完整路径（或在说明假设的前提下进行推断）。

2 - 模式（交互模式与命令行模式）

• 明确说明用户所处的模式：
  • 交互模式的行为类似 REPL，运行命令时不带 fab 前缀。
  • 命令行模式每次调用运行一条命令，最适合用于脚本或自动化。
• 所选模式会在会话之间保留。用户退出并重新登录后，CLI 会恢复到上次使用的模式。
• 提供说明时，除非用户表示自己处于交互模式，否则请展示命令行模式下的命令。

3 - 身份验证（公开安全的指导）

• 优先采用以下身份验证方式，不要臆造其他流程：
  1. 交互式用户：fab auth login（在支持的情况下使用浏览器/WAM）。
  2. 服务主体（机密/证书）：使用环境变量或安全机制；避免将机密嵌入文件。
  3. 服务主体（联合凭据）：使用联合令牌环境变量（FAB_SPN_FEDERATED_TOKEN），不要持久化原始令牌。
  4. 托管标识：支持 Azure 托管的工作负载；无需凭据。
• 切勿要求用户在聊天中粘贴机密，也不要将其回显。

4 - 敏感数据处理（严格）

• 切勿记录或输出令牌、密码、客户端机密或原始联合令牌。
• 验证所有可能影响安全性的用户输入：
  • 路径：清理文件路径和 API 参数。
  • GUID：使用前验证资源标识符。
  • JSON：验证 JSON 输入格式是否正确。
• 如果用户分享了敏感字符串，请建议其轮换或重新生成，并将其移至安全存储中。

5 - 隐藏实体与发现

• 隐藏实体是通常不可见的特殊资源，遵循名称以点号开头的命名约定（类似于 UNIX 隐藏文件）。
• 租户级隐藏实体（从根目录访问）：
  • .capacities — fab ls .capacities / fab get .capacities/<name>.Capacity
  • .gateways — fab ls .gateways / fab get .gateways/<name>.Gateway
  • .connections — fab ls .connections / fab get .connections/<name>.Connection
  • .domains — fab ls .domains / fab get .domains/<name>.Domain
• 工作区级隐藏实体（在工作区内访问）：
  • .managedidentities — fab ls ws1.Workspace/.managedidentities
  • .managedprivateendpoints — fab ls ws1.Workspace/.managedprivateendpoints
  • .externaldatashares — fab ls ws1.Workspace/.externaldatashares
  • .sparkpools — fab ls ws1.Workspace/.sparkpools
• 建议使用 ls -a / ls --all 显示隐藏资源。

6 - 错误与故障排除指南

• 描述故障时，请说明：
  • 命令尝试执行的操作
  • 可能的原因
  • 下一步可采取的操作
• 如果 CLI 显示错误代码或消息，请保持原样，不要改写掉关键标识符。（Fabric CLI 强调错误代码和消息的稳定性。）
• 如果 API 错误包含请求 ID，请一并提供，以便调试。

7 - Agent 输出规范

• 默认提供简洁、可运行的步骤。
• 建议命令时，请说明：
  • 前置条件（身份验证、正确的工作区/路径）
  • 预期结果
  • 验证方法（例如，后续执行 fab ls / fab get）

8 - 安全默认规则

• 建议执行删除、覆盖或更改访问权限/权限的命令前，请先征求用户同意。
• 如果用户明确确认，在可能的情况下，请附上清晰的回滚说明。

9 - 平台与故障排除参考

• 支持的平台：Windows、Linux、macOS。
• 支持的 shell：zsh、bash、PowerShell、cmd（Windows 命令提示符）。
• Python 版本：3.10、3.11、3.12、3.13、3.14。
• CLI 文件存储（有助于故障排除）：
  • 配置文件存储在 ~/.config/fab/：
    • cache.bin — 加密的身份验证令牌缓存
    • config.json — 非敏感 CLI 设置
    • auth.json — 非敏感身份验证信息
    • context-<session_id> — 命令行模式会话的路径上下文
  • 调试日志写入以下位置：
    • Windows：%AppData%/fabcli_debug.log
    • macOS：~/Library/Logs/fabcli_debug.log
    • Linux：~/.local/state/fabcli_debug.log

10 - 关键操作规则

• 首次运行：执行命令前，始终运行 fab auth status 验证身份验证状态。如果尚未通过身份验证，请让用户运行 fab auth login。
• 先了解，再执行：首次使用命令时，始终使用 fab --help 和 fab <command> --help 了解其语法。
• 从简单开始：先单独尝试基本的 fab 命令，再进行管道操作或命令串联。
• 非交互模式：使用编码 Agent 时，请以命令行模式运行 fab。交互模式无法用于自动化。
• 强制标志：如果命令支持 -f 标志，请在执行时使用，以非交互方式运行（跳过确认提示）。
• 操作前先验证：如果工作区或项目名称不明确，请先询问用户，然后使用 fab ls 或 fab exists 进行验证，再继续操作。
• 权限错误：如果命令因权限受阻，请停止并询问用户；切勿尝试绕过权限限制。

11 - 常见项目类型

扩展名	描述
.Workspace	工作区容器
.Folder	工作区中的文件夹
.SemanticModel	Power BI 数据集/语义模型
.Report	Power BI 报表
.Dashboard	Power BI 仪表板
.Notebook	Fabric 笔记本
.Lakehouse	Lakehouse
.Warehouse	数据仓库
.DataPipeline	数据管道
.SparkJobDefinition	Spark 作业定义
.Eventstream	实时事件流
.KQLDatabase	KQL 数据库
.MLModel	ML 模型
.MLExperiment	ML 实验
.Capacity	Fabric 容量（隐藏）
.Gateway	数据网关（隐藏）
.Connection	连接（隐藏）

使用 fab desc .<ItemType> 探索任意项目类型。

12 - 命令参考

如需详细的命令语法和实际示例，请参阅：

• 快速入门指南 — 常见任务的复制粘贴示例
• 完整命令参考 — 所有命令及其标志和模式
• 语义模型 — TMDL、DAX 查询、刷新、存储模式
• 笔记本 — 作业执行、参数、计划安排
• 报表 — 导出、导入、重新绑定到模型
• 工作区 — 创建、管理、权限
• 数据查询 — DAX 和 Lakehouse 表查询
• API 参考 — 直接 REST API 访问模式
• 创建工作区 — 工作区创建工作流