powerbi-report-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telemetry — MANDATORY. Every
api.fabric.microsoft.com
call must carry
x-ms-fabric-skill: powerbi-report-cli
(
az rest
:
--headers "x-ms-fabric-skill=powerbi-report-cli"
), including every LRO poll,
fabric_lro
and retry. Snippets omit it — add it anyway.

CRITICAL NOTES
To find workspace details, including its ID, from a workspace name: list all workspaces, then use JMESPath filtering.

To find item details, including its ID, from a workspace ID, item type, and item name: list all items of that type in that workspace, then use JMESPath filtering.
Use
powerbi-report-cli
for the report artifact: requirements, design, PBIR/PBIP page and visual edits, preview, and publishing. Semantic model, measure, and DAX work belongs to a semantic-model skill. Natural-language questions about report data belong to
fabriciq
.

遥测 — 强制。 每次
api.fabric.microsoft.com
调用都必须携带
x-ms-fabric-skill: powerbi-report-cli
（
az rest
：
--headers "x-ms-fabric-skill=powerbi-report-cli"
），包括每次 LRO 轮询、
fabric_lro
和重试。代码片段省略了它——仍要添加。

关键说明
要从工作区名称查找工作区详情（包括其 ID），请列出所有工作区，然后使用 JMESPath 筛选。

要从工作区 ID、项类型和项名称查找项详情（包括其 ID），请列出该工作区中该类型的所有项，然后使用 JMESPath 筛选。
报表制品应使用
powerbi-report-cli
：需求、设计、PBIR/PBIP 页面和视觉对象编辑、预览及发布。语义模型、度量值和 DAX 工作应交给语义模型 skill。关于报表数据的自然语言问题应交给
fabriciq
。

Power BI Reports - CLI Skill

Power BI 报表 - CLI Skill

This skill owns the Power BI report lifecycle end to end: requirements and scope, visual design, local PBIR/PBIP authoring and preview, and report-item transport to and from Microsoft Fabric.

It is a mode dispatcher and intentionally contains no detailed procedures. Select the mode that matches the request, then read the matching mode reference end to end before acting. The mode file holds the required workflow, commands, payloads, templates, and failure rules.

此 skill 全面负责 Power BI 报表生命周期：需求与范围、视觉设计、本地 PBIR/PBIP 编写与预览，以及报表项与 Microsoft Fabric 之间的传输。

它是一个模式分发器，有意不包含详细流程。选择与请求匹配的模式，然后从头到尾阅读相应的模式参考文档后再执行操作。模式文件包含必需的工作流、命令、payload、模板和失败规则。

Mode Selection

模式选择

Mode	Use when the request...	Existing route examples	Read first
`planning`	creates a new report/dashboard and needs requirements, model/dependency inspection, scope, a page plan, and approval before implementation	create a report, build a dashboard, create from a semantic model, plan then implement, walk me through creating a report	references/planning.md, then references/planning-part-02.md
`design`	decides what a report should look like: tone, signature, page archetype, chart type, layout, color, typography, theme direction, accessibility, brand application, redesign, or critique	design a Power BI report, make the dashboard professional, choose a chart, apply a brand, redesign the report, create a design brief	references/design.md
`authoring`	reads or edits local PBIR/PBIP files, validates them, previews the report, or captures screenshots	edit PBIR, create/add a report page or visual, format a visual, add filters/slicers/bookmarks/themes, validate PBIR, preview/reload/screenshot in Desktop or service	references/authoring.md
`management`	moves a report definition to or from Fabric or manages the workspace report item	publish/upload/download PBIR or PBIP, list reports, get/update/delete a report, rebind a report	references/management.md

模式	适用于请求……	现有路由示例	首先阅读
`planning`	创建新报表/仪表板，并需要需求、模型/依赖项检查、范围、页面计划以及实施前的审批	创建报表、构建仪表板、从语义模型创建、先规划后实施、逐步指导我创建报表	references/planning.md，然后阅读 references/planning-part-02.md
`design`	决定报表应呈现的样子：基调、标志性元素、页面原型、图表类型、布局、颜色、字体、主题方向、无障碍性、品牌应用、重新设计或评审	设计 Power BI 报表、让仪表板看起来更专业、选择图表、应用品牌、重新设计报表、创建设计简报	references/design.md
`authoring`	读取或编辑本地 PBIR/PBIP 文件、验证文件、预览报表或截取屏幕截图	编辑 PBIR、创建/添加报表页面或视觉对象、设置视觉对象格式、添加筛选器/切片器/书签/主题、验证 PBIR、在 Desktop 或服务中预览/重新加载/截图	references/authoring.md
`management`	将报表定义传输到 Fabric 或从 Fabric 传输，或管理工作区报表项	发布/上传/下载 PBIR 或 PBIP、列出报表、获取/更新/删除报表、重新绑定报表	references/management.md

Mode Boundary Rules

模式边界规则

Classify by intent, not by which file or tool is already open.
```
design
```
decides what the report should look like;
```
authoring
```
writes the PBIR that realizes it. Choosing a chart type is
```
design
```
; encoding it into
```
visual.json
```
is
```
authoring
```
.
Restyling or reformatting an existing local report is
```
authoring
```
, even when the request uses design language. Use
```
design
```
when the user wants advice or a design contract rather than a file change.
```
authoring
```
changes local files and performs preview/validation. It does not publish to Fabric.
```
management
```
transports definitions and manages Fabric report items. It does not invent or directly author PBIR content.
```
planning
```
owns the guided requirements-to-approval flow for a new report. A focused edit to an existing report goes directly to
```
authoring
```
.

A greenfield request can span modes in this order:

text

planning -> design -> authoring -> management

Handle one mode at a time. Announce each switch and read the new mode reference before starting that part. The

planning

approval gate is a turn boundary: never build or publish until the user explicitly approves the locked spec in a later reply.

GREENFIELD APPROVAL BARRIER — MANDATORY. When a new-report request asks to plan, build, and/or publish but the user has not approved a locked spec in a prior reply, set the current phase to
approval_pending
and keep
planning
as the only active mode. In this phase, do not load
authoring
or
management
, edit/scaffold PBIR or semantic-model files, generate synthetic data, call Fabric write APIs, or publish. Persist
_brief/report-spec.md
, ask for explicit approval, and end the turn. The build/publish wording in the original request is desired future scope, not approval to cross this barrier.

根据意图分类，而不是依据当前打开的是哪个文件或工具。
```
design
```
决定报表应该呈现的样子；
```
authoring
```
编写实现该设计的 PBIR。选择图表类型属于
```
design
```
；将其编码到
```
visual.json
```
中属于
```
authoring
```
。
对现有本地报表重新设置样式或格式属于
```
authoring
```
，即使用户请求使用了设计语言。当用户希望获得建议或设计契约，而不是进行文件更改时，使用
```
design
```
。
```
authoring
```
更改本地文件并执行预览/验证，但不发布到 Fabric。
```
management
```
传输定义并管理 Fabric 报表项，但不直接创作 PBIR 内容。
```
planning
```
负责针对新报表的引导式“需求到审批”流程。对现有报表的聚焦编辑应直接进入
```
authoring
```
。

全新项目请求可以按以下顺序跨越多个模式：

text

planning -> design -> authoring -> management

一次只处理一个模式。每次切换模式时都要明确说明，并开始新部分前阅读新的模式参考文档。

planning

的审批关卡是一个轮次边界：绝不能构建或发布，直到用户在后续回复中明确批准已锁定的规范。

全新项目审批屏障 — 强制。 当新建报表请求要求规划、构建和/或发布，但用户尚未在先前回复中批准已锁定的规范时，将当前阶段设为
approval_pending
，并仅将
planning
保持为活动模式。在此阶段，不要加载
authoring
或
management
，不要编辑或搭建 PBIR 或语义模型文件，不要生成合成数据，不要调用 Fabric 写入 API，也不要发布。保存
_brief/report-spec.md
，请求明确批准，然后结束本轮。原始请求中关于构建/发布的表述代表未来期望范围，并不构成越过此屏障的批准。

Required Deliverable by Mode

各模式必须交付的成果

Mode	Completion requirement
`planning`	Persist `_brief/report-spec.md` or the user-named equivalent, ask for explicit approval, and stop before implementation.
`design`	Produce the complete `Design Brief:` contract, including `design_identity` and a page archetype/layout contract for every page. Do not edit PBIR or call Fabric APIs.
`authoring`	Persist the requested PBIR/PBIP changes, validate each logical batch, then complete the selected preview and screenshot-review workflow required by the authoring reference. Do not publish.
`management`	Complete the requested Fabric report operation, including LRO polling and documented readback verification.

模式	完成要求
`planning`	保存 `_brief/report-spec.md` 或用户指定的等效文件，请求明确批准，并在实施前停止。
`design`	产出完整的 `Design Brief:` 契约，其中包含 `design_identity` ，以及每个页面的页面原型/布局契约。不要编辑 PBIR 或调用 Fabric API。
`authoring`	保存请求的 PBIR/PBIP 更改，验证每个逻辑批次，然后完成 authoring 参考文档要求的所选预览和截图审查工作流。不要发布。
`management`	完成请求的 Fabric 报表操作，包括 LRO 轮询和记录在案的回读验证。

Rules

规则

MUST

必须

Select the narrowest mode that fully covers the current request.
Read
```
references/<mode>.md
```
end to end before the first command or file edit in that mode. When an already-loaded mode explicitly routes one narrow cross-mode operation to a named topic reference, treat that topic reference as the complete handoff; do not load the target mode's umbrella file unless the work expands beyond that operation.
In
```
planning
```
mode, also read
```
references/planning-part-02.md
```
before producing
```
_brief/report-spec.md
```
; it contains the required canonical design contract and approval checks.
Across a multi-turn task, retain a compact working state containing resolved workspace/item/model IDs, local and downloaded paths, and references already read. Reuse it in later turns unless the user explicitly requests a fresh query or the preceding operation invalidated a value.
Preserve every argument and safety boundary documented by the selected mode.
Announce and perform an explicit mode switch when the request crosses a boundary.
Use the
```
powerbi-report-author
```
CLI metadata and validation surfaces instead of guessing PBIR schemas, roles, formatting properties, selectors, or enum values.
Keep local edits local unless the user explicitly requests publishing.
Resolve Fabric workspace and item IDs by listing and filtering rather than guessing identifiers.
Produce the artifact the user requested; reading or summarizing a reference is not task completion.

选择能够完整覆盖当前请求的最窄模式。
在该模式下首次执行命令或编辑文件之前，从头到尾阅读
```
references/<mode>.md
```
。当已加载的模式明确将某个范围狭窄的跨模式操作转交给指定主题参考文档时，将该主题参考文档视为完整交接；除非工作范围超出该操作，否则不要加载目标模式的总览文件。
在
```
planning
```
模式下，生成
```
_brief/report-spec.md
```
前还要阅读
```
references/planning-part-02.md
```
；其中包含必需的规范化设计契约和审批检查。
跨多轮任务，保留一份紧凑的工作状态，其中包含已解析的工作区/项/模型 ID、本地及下载路径，以及已读参考文档。除非用户明确要求重新查询，或前一操作使某个值失效，否则在后续轮次中复用该状态。
保留所选模式记录的每个参数和安全边界。
当请求跨越模式边界时，明确说明并执行模式切换。
使用
```
powerbi-report-author
```
CLI 的元数据和验证接口，而不是猜测 PBIR schema、角色、格式化属性、选择器或枚举值。
除非用户明确请求发布，否则将本地更改保留在本地。
通过列出并筛选来解析 Fabric 工作区和项 ID，而不是猜测标识符。
产出用户请求的成果；阅读或总结参考文档并不代表任务完成。

PREFER

优先

Infer facts already present in the prompt, semantic model, existing PBIP, or prior approved spec instead of asking again.
Load only the selected mode and its directly relevant topic references.
Reuse reference guidance already loaded in the current task. Open a new reference only when the requested operation or an observed mismatch requires it.
Preserve the user's existing project structure, schemas, host, operation, binding, and delivery target unless the selected mode explicitly requires a change.

推断提示、语义模型、现有 PBIP 或先前已批准规范中已存在的事实，而不是再次询问。
仅加载选定模式及其直接相关的主题参考文档。
复用当前任务中已加载的参考指南。只有当请求的操作或观察到的不匹配情况要求时，才打开新的参考文档。
保留用户现有的项目结构、schema、host、operation、binding 和 delivery target，除非选定模式明确要求更改。

AVOID

避免

Acting from this dispatcher without reading the selected mode reference.
Reloading this dispatcher, a mode file, or a topic reference already read in the current task solely because the conversation advanced to a later turn.
Loading a retired sibling skill name; planning, design, authoring, and management are modes of this skill.
Editing PBIR or calling Fabric APIs in
```
planning
```
or
```
design
```
.
Publishing from
```
authoring
```
, or authoring PBIR content from
```
management
```
.
Bypassing the planning approval gate because the original request also asked to build or publish.

未经阅读选定模式参考文档就依据此分发器执行操作。
仅因对话推进到后续轮次，就重新加载已读过的此分发器、模式文件或主题参考文档。
加载已退役的同级 skill 名称；
```
planning
```
、
```
design
```
、
```
authoring
```
和
```
management
```
都是此 skill 的模式。
在
```
planning
```
或
```
design
```
模式下编辑 PBIR 或调用 Fabric API。
从
```
authoring
```
模式发布，或从
```
management
```
模式直接创作 PBIR 内容。
因为原始请求同时要求构建或发布，就绕过 planning 审批关卡。

Complete Reference Index

完整参考索引

Open every relevant reference directly from this index. Files named

part-XX

continue the named topic.

直接从本索引打开每个相关参考文档。名为

part-XX

的文件延续对应主题。

Authoring

创作

```
authoring/authoring-workflows
```
```
authoring/bookmark
```
```
authoring/button-part-02
```
```
authoring/button-part-03
```
```
authoring/button
```
```
authoring/card-part-02
```
```
authoring/card-part-03
```
```
authoring/card
```
```
authoring/cartesian-part-02
```
```
authoring/cartesian-part-03
```
```
authoring/cartesian-part-04
```
```
authoring/cartesian
```
```
authoring/color-strategy
```

authoring/conditional-formatting-part-02

authoring/conditional-formatting-part-03

authoring/conditional-formatting-part-04

authoring/conditional-formatting-part-05

authoring/conditional-formatting-part-06

authoring/conditional-formatting-part-07

```
authoring/conditional-formatting
```
```
authoring/custom-visuals
```
```
authoring/expressions
```
```
authoring/field-parameters
```
```
authoring/filter-pane
```
```
authoring/filters
```
```
authoring/formatting-overview
```
```
authoring/formatting-part-02
```
```
authoring/formatting
```
```
authoring/image
```
```
authoring/kpi
```
```
authoring/map
```
```
authoring/model-binding
```
```
authoring/page-formatting
```
```
authoring/powerbi-desktop
```

authoring/powerbi-report-author-cli-part-02

```
authoring/powerbi-report-author-cli
```
```
authoring/preview-part-02
```
```
authoring/preview-part-03
```
```
authoring/preview-part-04
```
```
authoring/preview
```
```
authoring/re-theming-part-02
```
```
authoring/re-theming-part-03
```
```
authoring/re-theming
```
```
authoring/screenshot-review
```
```
authoring/shape
```
```
authoring/slicers-part-02
```
```
authoring/slicers
```
```
authoring/table
```
```
authoring/textbox
```
```
authoring/theming-part-02
```
```
authoring/theming
```
```
authoring/version-control
```

```
authoring/authoring-workflows
```
```
authoring/bookmark
```
```
authoring/button-part-02
```
```
authoring/button-part-03
```
```
authoring/button
```
```
authoring/card-part-02
```
```
authoring/card-part-03
```
```
authoring/card
```
```
authoring/cartesian-part-02
```
```
authoring/cartesian-part-03
```
```
authoring/cartesian-part-04
```
```
authoring/cartesian
```
```
authoring/color-strategy
```

authoring/conditional-formatting-part-02

authoring/conditional-formatting-part-03

authoring/conditional-formatting-part-04

authoring/conditional-formatting-part-05

authoring/conditional-formatting-part-06

authoring/conditional-formatting-part-07

```
authoring/conditional-formatting
```
```
authoring/custom-visuals
```
```
authoring/expressions
```
```
authoring/field-parameters
```
```
authoring/filter-pane
```
```
authoring/filters
```
```
authoring/formatting-overview
```
```
authoring/formatting-part-02
```
```
authoring/formatting
```
```
authoring/image
```
```
authoring/kpi
```
```
authoring/map
```
```
authoring/model-binding
```
```
authoring/page-formatting
```
```
authoring/powerbi-desktop
```

authoring/powerbi-report-author-cli-part-02

```
authoring/powerbi-report-author-cli
```
```
authoring/preview-part-02
```
```
authoring/preview-part-03
```
```
authoring/preview-part-04
```
```
authoring/preview
```
```
authoring/re-theming-part-02
```
```
authoring/re-theming-part-03
```
```
authoring/re-theming
```
```
authoring/screenshot-review
```
```
authoring/shape
```
```
authoring/slicers-part-02
```
```
authoring/slicers
```
```
authoring/table
```
```
authoring/textbox
```
```
authoring/theming-part-02
```
```
authoring/theming
```
```
authoring/version-control
```

Design

设计

```
design/accessibility
```
```
design/anti-patterns
```
```
design/archetype-composition
```
```
design/archetypes/analytical-canvas
```

design/archetypes/comparative-benchmark-part-02

```
design/archetypes/comparative-benchmark
```
```
design/archetypes/executive-summary
```
```
design/archetypes/narrative-story
```
```
design/archetypes/operational-monitor
```
```
design/brownfield
```
```
design/chart-selection
```
```
design/color
```
```
design/design-brief-part-02
```
```
design/design-brief
```
```
design/interactivity
```
```
design/layout
```
```
design/pre-flight-checklist
```
```
design/signatures
```
```
design/tone-catalog
```
```
design/typography
```
```
design/visual-cookbook-part-02
```
```
design/visual-cookbook
```

```
design/accessibility
```
```
design/anti-patterns
```
```
design/archetype-composition
```
```
design/archetypes/analytical-canvas
```

design/archetypes/comparative-benchmark-part-02

```
design/archetypes/comparative-benchmark
```
```
design/archetypes/executive-summary
```
```
design/archetypes/narrative-story
```
```
design/archetypes/operational-monitor
```
```
design/brownfield
```
```
design/chart-selection
```
```
design/color
```
```
design/design-brief-part-02
```
```
design/design-brief
```
```
design/interactivity
```
```
design/layout
```
```
design/pre-flight-checklist
```
```
design/signatures
```
```
design/tone-catalog
```
```
design/typography
```
```
design/visual-cookbook-part-02
```
```
design/visual-cookbook
```

Mode Guides

模式指南

```
authoring-part-02
```
```
authoring-part-03
```
```
authoring-part-04
```
```
authoring
```
```
design
```
```
management-part-02
```
```
management-part-03
```
```
management-part-04
```
```
management
```
```
planning-part-02
```
```
planning
```

```
authoring-part-02
```
```
authoring-part-03
```
```
authoring-part-04
```
```
authoring
```
```
design
```
```
management-part-02
```
```
management-part-03
```
```
management-part-04
```
```
management
```
```
planning-part-02
```
```
planning
```

Examples

示例

User request	Mode
"Create a new executive report from this semantic model."	`planning`
"Design an operational page and choose the right charts."	`design`
"Add a KPI page to this PBIP, validate it, and take screenshots."	`authoring`
"Publish this local PBIP to my Fabric workspace and rebind it."	`management`

用户请求	模式
"基于此语义模型创建新的高管报表。"	`planning`
"设计运营页面并选择合适的图表。"	`design`
"为此 PBIP 添加 KPI 页面，验证并截取屏幕截图。"	`authoring`
"将此本地 PBIP 发布到我的 Fabric 工作区并重新绑定。"	`management`

Route Compatibility

路由兼容性

The merged skill preserves the four previous route surfaces. Treat the following phrases as explicit aliases for the corresponding mode:

Mode	Preserved route phrases
`planning`	create a report; build a report; create a dashboard; create a new report from scratch; create a report from a semantic model or dataset link; build a report for this model; make me a dashboard; plan then implement; walk me through creating a report
`design`	design Power BI report; make dashboard look professional; choose chart type; apply brand to report; redesign report; create design brief; Power BI report design archetype
`authoring`	edit PBIR; create Power BI report page; add visual to PBIP; format report visual; validate Power BI report; preview Power BI report; Power BI Desktop preview status; preview report in service; preview report in browser; screenshot report page; screenshot all report pages; list preview hosts; implement dashboard in PBIP; add dashboard visuals to report; implement an approved PBIP report spec; edit PBIR pages/visuals; edit a Power BI report
`management`	upload PBIR report definition; upload Power BI report; download PBIR definition; publish PBIR definition; publish Power BI report to Fabric; manage Power BI reports; list workspace reports

合并后的 skill 保留了此前的四个路由入口。将以下短语视为对应模式的显式别名：

模式	保留的路由短语
`planning`	创建报表；构建报表；创建仪表板；从头创建新报表；从语义模型或数据集链接创建报表；针对此模型构建报表；为我制作仪表板；先规划后实施；逐步指导我创建报表
`design`	设计 Power BI 报表；让仪表板看起来更专业；选择图表类型；向报表应用品牌；重新设计报表；创建设计简报；Power BI 报表设计原型
`authoring`	编辑 PBIR；创建 Power BI 报表页面；向 PBIP 添加视觉对象；设置报表视觉对象格式；验证 Power BI 报表；预览 Power BI 报表；Power BI Desktop 预览状态；在服务中预览报表；在浏览器中预览报表；截取报表页面屏幕截图；截取所有报表页面的屏幕截图；列出预览主机；在 PBIP 中实现仪表板；向报表添加仪表板视觉对象；实现已批准的 PBIP 报表规范；编辑 PBIR 页面/视觉对象；编辑 Power BI 报表
`management`	上传 PBIR 报表定义；上传 Power BI 报表；下载 PBIR 定义；发布 PBIR 定义；将 Power BI 报表发布到 Fabric；管理 Power BI 报表；列出工作区报表