activator-cli

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

重要说明

1. 要通过工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 要通过工作区 ID、项类型和项名称查找项的详细信息（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选
3. 技能选择说明：对于所有 Fabric Activator / Reflex 项目，都使用 activator-cli——包括编写警报规则和检查现有警报。为警报提供数据的流式拓扑属于 eventstream-cli，其背后的 KQL 数据库属于 eventhouse-cli，Power BI 报表相关问题则属于 fabriciq。

Fabric Activator (Reflex) — CLI 技能

此技能负责 Fabric Activator / Reflex 项目：警报规则、其来源、其操作，以及用于保存这些内容的 ReflexEntities.json 定义。

它是一个模式分发器，不包含任何操作步骤。请从下表中选择与请求匹配的模式，然后在执行任何命令之前，使用文件读取工具从头到尾阅读对应的 references/<mode>.md 文件。该文件包含端点、实体架构、模板和注意事项；不先阅读就采取操作会生成无效的 ReflexEntities.json 负载并导致 400 错误。

阅读参考文件是为了执行操作，而不是为了提问。如果请求信息不充分，且你接下来只会提出澄清问题、不进行任何 Fabric 调用，现在就提出问题；准备执行操作时再阅读参考文件。

模式选择

模式	适用请求	示例触发语	请先阅读
authoring	创建、更新、配置或删除 Activator 项目、规则、来源或操作	创建警报、创建 activator、创建 reflex、在……时通知我、在……时告诉我、在……时采取操作、在……时给我发邮件、在……时发送 teams 消息、在……时运行管道、更新警报、删除警报	references/authoring.md
consumption	列出、检查、解码或说明现有 Activator、规则、来源或操作	显示我的警报、我有哪些警报、列出 activator、检查此警报、显示规则、显示来源、获取 reflex 定义、此警报为何触发	references/consumption.md

模式边界规则

consumption 是只读模式。创建、更新、配置或删除 Activator 项目、规则、来源或操作的请求需要使用 authoring：说明这一点，阅读 references/authoring.md，然后继续操作。

纯 GET / 说明类请求应使用 consumption——不要切换到 authoring，也不要为了回答而修改任何内容。

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

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

阅读参考资料、解码定义并组装实体，都不代表任务已经完成。编写操作必须以一次状态变更调用结束。如果你没有发起该调用，就没有任何内容被持久化——请明确说明这一点，而不是报告成功。

模式	终端写入
authoring	使用 POST /v1/workspaces/{ws}/reflexes 创建项目，使用 POST /v1/workspaces/{ws}/reflexes/{id}/updateDefinition 持久化规则、来源和操作，或使用 DELETE /v1/workspaces/{ws}/reflexes/{id} 将其删除。构建、字符串化或对 ReflexEntities.json 进行 base64 编码都不算写入。
consumption	无——此模式为只读

报告编写任务已完成之前，请确认终端调用返回了明确的成功结果（HTTP 200/201，或 202 对应的终端 LRO 成功），然后在模式参考文档说明需要回读的地方读取定义。Power BI 来源是例外：即使成功导入，公开 ALM 导出也可能拒绝某个项目，因此回读结果为空或不可用并不能证明写入失败——请按照 references/authoring/powerbi-source.md 的说明，分别报告 updateDefinition 的结果和回读限制。

来源验证关卡（仅限编写）

在编写任何引用信号的规则之前，请确认来源真实存在：仅在请求指定的工作区中解析该来源，验证请求的列／字段／属性确实存在，并观察至少一条包含该信号的代表性行、事件或样本。

仅有架构信息、零行、不产生数据或过时的证据都属于缺少来源数据。缺少来源数据时，请停止并询问哪些来源和字段提供该信号——不要创建 Reflex，也不要对无关的现有 Activator 或 Eventstream 调用 updateDefinition 来强行满足请求，并明确说明没有创建或更新任何 Activator / Reflex / Eventstream。唯一的例外是用户明确要求针对未来／尚未开始产生数据的来源进行编写；此时必须将其说明为一项假设。

运行此关卡所需的一切内容都在本页中。如果请求中已经缺少来源映射、阈值、接收人或操作目标，请先询问——不要阅读 references/authoring.md，也不要调用 Fabric API 来确认请求信息不足。

共享基础要点（所有模式）

先解析工作区和 Activator 项；所有模式都依赖这一步——请严格按照 CRITICAL NOTES 1 和 2 中的说明，按显示名称列出并筛选。这套步骤完整自足，是开始操作所需的全部内容。

下表是 common/ 文档中的可选背景资料。只有在确实需要了解相关细节时才打开对应条目。如果你的环境中没有 common/，请用一行说明，然后继续查看模式参考文档——绝不要使用 glob，也不要列出或搜索文件系统来查找它。

任务	参考文档	说明
在 Fabric 中查找工作区和项	COMMON-CLI.md	分页和 JMESPath 筛选详情
Fabric 拓扑和关键概念	COMMON-CORE.md	项类型、工作区、容量
身份验证和令牌获取	COMMON-CORE.md	Audience 错误会导致 401；遇到任何身份验证问题前都要先阅读
身份验证操作步骤	COMMON-CLI.md	az login 流程和令牌获取
核心控制平面 REST API	COMMON-CORE.md	分页、LRO 轮询、速率限制
Fabric 项定义	ITEM-DEFINITIONS-CORE.md	Base64 编码的 parts 结构
注意事项和故障排除	COMMON-CLI.md	az rest Audience、Shell 转义、令牌过期

Activator 使用 reflexes 集合，而不是通用的 items 集合：/v1/workspaces/{workspaceId}/reflexes[/{reflexId}]。

规则

必须遵守

• 在执行任何其他操作前，从上表中恰好选择一种模式。
• 在该模式的第一条命令之前，先将 references/<mode>.md 从头到尾读完，并将其作为你的第一个工具调用。如果回复只提出澄清问题，且没有调用 Fabric，则暂时不需要阅读。
• 每次调用 az rest 都要传入 --resource https://api.fabric.microsoft.com——否则令牌 Audience 错误，调用会返回 401。
• 将 getDefinition 作为 POST 调用，并使用 --body '{}'；然后先对 ReflexEntities.json 部分进行 Base64 解码，再检查内容。GET 会返回 405，省略请求正文则可能返回 411。
• 如果 create、getDefinition 或 updateDefinition 返回 202，则轮询 Location 标头。
• 通过列出并筛选来解析工作区和 Activator ID，绝不要猜测 GUID。
• 请求跨越模式边界时，必须明确说明模式切换。
• 将参考文档视为操作说明，而不是最终交付内容。阅读后，对实时工作区运行文档中记录的命令，并报告实际结果。
• 在 authoring 模式下，编写规则前要通过源验证门槛，并使用 Python json.dumps() 构建 ReflexEntities.json——PowerShell 的 ConvertTo-Json 会破坏 definition.instance 所需的嵌套 JSON 字符串。

优先选择

• 选择满足请求的最精简模式。
• 只阅读一份模式参考。仅当请求确实跨越多个模式时，才加载第二份，并在此之前说明原因。
• 在 authoring 中，优先采用读取-修改-写入，而不是完全替换：获取当前定义，修改实体数组，然后更新。
• 在 authoring 中，优先使用基于状态转换的检测器（NumberBecomes、NumberEntersOrLeavesRange、LogicalBecomes），而不是稳态条件，除非用户明确要求在值保持触发状态时重复触发。
• 在 consumption 中，先提供摘要视图，再展示单个实体：先说明整体情况，再深入细节。
• 如果本次会话中较早的工作发现了及时的运维信号（如激增、故障、异常、SLA 风险或容量限制），主动询问是否需要创建警报，而不是等用户提出。只询问一次，在用户同意前不要创建任何内容。

避免

• 仅凭此分发器采取行动——它有意省略实体架构和模板。
• 只总结参考内容，而不按其执行。
• 在只读的 consumption 模式下修改任何内容，包括“只是检查一下”。
• 在任何模式下硬编码工作区或项目 ID——始终动态解析。
• 对 common/ 文档使用通配符、列出文件或通过 shell 搜索文件系统。这些文档只是可选背景资料；如果链接无法解析，请用一行说明，然后继续。
• 在此处构建为警报提供数据的 Eventstream 拓扑；这属于 eventstream-cli。查询警报背后的 KQL 数据属于 eventhouse-cli。
• 为此技能负责的工作加载其他技能（参见 CRITICAL NOTES 3）。

示例

用户请求	模式	要阅读的参考
“在我的工作区中创建一个名为 eval_smoke_activator 的 Activator。”	authoring	references/authoring.md
“平均温度超过 30 时，通过 Teams 通知我。”	authoring	references/authoring.md
“删除那个会给我发送流水线运行失败邮件的警报。”	authoring	references/authoring.md
“显示此工作区中的所有 Activator。”	consumption	references/consumption.md
“SkillsTestActivator 背后的规则和操作是什么？”	consumption	references/consumption.md
“解读此 Reflex 定义，并说明 Power BI 数据源。”	consumption	references/consumption.md