variable-library-cli

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

重要说明

1. 要根据工作区名称查找工作区详情（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选。
2. 要根据工作区 ID、项类型和项名称查找项详情（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选。
3. Variable Library 有两个平面：Git 中的定义文件，以及工作区中的活动值集项状态。不要将活动值集视为 Git 编辑。定义平面为 authoring；项状态平面为 operations。
4. Variable Library 定义请求必须完全省略 format 字段。不要发送 format: null。
5. 技能消歧：所有 Variable Library 相关事项都使用 variable-library-cli，包括消费者引用中的 Variable Library 部分。消费者项本身的深度创作应使用其他技能：管道使用 pipeline-migration，笔记本使用 spark-cli，Dataflow Gen2 使用 dataflows-cli，Git 生命周期使用 git-integration-operations-cli，部署管道机制使用 deployment-pipelines-authoring-cli。
6. 对于信息不充分的创建请求，创建前先澄清。如果“设置／创建 Variable Library”的请求未说明变量名称、类型、默认值和值集，请先提出澄清问题或提供结构化选项，再进行创建。不要臆造配置并在未确认意图的情况下静默创建项。（具体且完整的请求无需确认。）
7. 生成读取 Boolean Variable Library 值的消费者代码（笔记本、UDF）时，应使用 str(value).lower() == "true" 进行防御性转换。切勿对字符串使用 bool(value)：在 Python 中，所有非空字符串都为真，包括 "false"，因此 bool("false") 始终为 True。
8. 不要写入与变量默认值相同的值集覆盖值。覆盖会固定该值：写入后，后续对默认值的编辑将不再应用于该值集，因此冗余覆盖会在无提示的情况下让值集退出继承。请省略覆盖，让值集继承默认值。仅在值确实不同时才覆盖。

Fabric Variable Library——CLI 技能

此技能负责 Fabric Variable Library 项：定义和值集、消费者引用中的 VL 部分、活动值集项状态，以及 Variable Library CI/CD 行为。

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

每个会话只需阅读一次。已阅读的文件会保留在上下文中，因此后续轮次无需再次阅读。

模式选择

模式	在请求……时使用	示例触发词	先阅读此文档
authoring	创建或更改库定义：变量、默认值、类型、值集覆盖文件、settings.json	创建变量库、添加变量、valueSets、variableOverrides、valueSetsOrder、updateDefinition	references/authoring.md
consumption	将变量接入使用方项，或说明使用方如何解析变量	libraryVariables、notebookutils variableLibrary、管道表达式、Dataflow Gen2 / copy job / shortcut / UDF / Plan 引用	references/consumption.md
operations	读取或切换活动值集，或涉及阶段、Git 序列化和部署	活动值集、activeValueSetName、提升到 prod、各阶段的值、Git diff、fabric-cicd	references/operations.md

模式边界规则

根据所属层面而不是用词进行分类。提及值集的请求，如果更改覆盖文件，则属于 authoring；如果更改工作区中哪个值集处于活动状态，则属于 operations。创建 valueSets/prod.json 属于 authoring；让 prod 工作区指向该文件则属于 operations。

consumption 仅涵盖引用中 Variable Library 一侧的内容。编写使用方项自身的定义属于该项对应的技能（CRITICAL NOTES 5）。

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

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

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

模式	终端写入
authoring	对于新建库，使用 POST /v1/workspaces/{ws}/items 并设置 type: "VariableLibrary"；对于保存编辑，使用 POST /v1/workspaces/{ws}/items/{id}/updateDefinition。这两个请求都会发送 base64 定义部分，且必须省略 format。在本地构建 JSON 不会写入任何内容。
consumption	由该项对应的技能负责调用使用方项自身的更新接口。本技能的交付内容是应放入其中的正确引用约定。
operations	使用 PATCH /v1/workspaces/{ws}/variableLibraries/{id} 并传入 {"properties":{"activeValueSetName":"<name>"}}。这是项状态：它不会编辑 settings.json、variables.json 或 valueSets/*.json，也不会出现在 Git diff 中。

在报告任务完成之前，请确认终端调用已成功返回，并读取产物以证明更改已生效。对于 operations，请使用 GET /variableLibraries/{id} 读取状态：通用的 /items/{id} 不会返回 properties，因此不会显示活动值集。

所有模式通用的基本事项

先解析工作区和项；所有模式都依赖它们。

任务	参考资料	备注
在 Fabric 中查找工作区和项	COMMON-CLI.md	必须——解析任何工作区或项 ID 前先阅读
Fabric 拓扑与关键概念	COMMON-CORE.md	项类型、工作区、容量
身份验证与令牌获取	COMMON-CORE.md	受众不正确会导致 401；遇到任何身份验证问题前先阅读
身份验证操作指南	COMMON-CLI.md	az login 流程和令牌获取
使用 az rest 调用 Fabric REST API	COMMON-CLI.md	此技能的主要访问方式
核心控制平面 REST API	COMMON-CORE.md	分页、LRO 轮询、速率限制
长时间运行的操作（LRO）	COMMON-CLI.md	创建和定义 API 可能返回 202
VariableLibrary 项定义	ITEM-DEFINITIONS-CORE.md	规范的部分路径和字段名称
注意事项与故障排除	COMMON-CLI.md	az rest 受众、Shell 转义、令牌过期

规则

必须

• 在执行任何操作前，先从上表中准确选择一种模式。
• 在执行该模式的第一条命令前，先完整阅读 references/<mode>.md，并将其作为你的第一个工具调用。一次性完整阅读，且只读一次：不要重新打开、再次 grep 或逐页翻阅。你已经拿到该文件。
• 通过列出并筛选来解析工作区和项 ID，绝不要猜测 GUID。
• 请求跨越模式边界时，明确宣布切换模式。
• 将参考资料视为操作说明，而非交付成果。阅读后，在实时工作区中运行文档所述命令，并报告真实结果。
• 使用规范的部分名称 variables.json、settings.json 和 valueSets/<name>.json；默认值使用 value，值集覆盖使用 variableOverrides。
• 按用户指定的名称生成用户要求的每项产物，并保留其标题，即使结果为“无”。

优先

• 选择能够满足请求的最精简模式。
• 恰好只阅读一种模式的参考资料。只有当请求确实跨越多种模式时才加载第二份，并在加载前说明原因。
• 在首次回复中说明你选择的模式，让用户可以纠正。
• 使用 Python 或 jq 生成 JSON 请求体，以确保 base64 负载为有效 UTF-8 且引号格式稳定。
• 对于完整的部署自动化，建议使用 fabric-cicd，而不是在此处手动实现。

避免

• 仅依据此分派说明采取操作——其中有意省略了操作细节。
• 将值集覆盖转换为字符串。每个 variableOverrides[].value 都必须使用变量的原生 JSON 类型；即使 REST 文档将该字段列为 String，字符串化的布尔值或数字仍会被拒绝，并返回 InvalidContent (InvalidValueOrTypeMismatch)。
• 在 Variable Library 定义中使用 defaultValue、values 或 format。
• 使用 Fabric fab CLI 命令语法。该 CLI 确实存在，但此处尚未验证 Variable Library 命令的格式。
• 深度编写使用方项定义（重要说明 5）。
• 重新阅读或再次 grep 已加载的参考资料；这会消耗轮次和令牌。

示例

用户请求	模式	要阅读的参考文档
“创建一个变量库，其中包含 dev 和 prod 值集。”	authoring	references/authoring.md
“将 target_path 变量接入我的数据摄取流水线。”	consumption	references/consumption.md
“部署后，让 prod 工作区指向 prod 值集。”	operations	references/operations.md
“为什么我的 Git diff 没有显示值集切换？”	operations	references/operations.md
“添加一个布尔标志变量，然后从笔记本中读取它。”	authoring，然后是 consumption	两份参考文档，逐一阅读