pbir-cli

使用 pbir 处理 Power BI 报表

用于探索、构建、管理和设置 Power BI 报表格式的 CLI。所有命令均使用 pbir。

**重要：**始终使用 pbir CLI 命令检查和修改报表。切勿直接编写、替换、复制或修补报表 JSON 文件。如果 CLI 不支持所需的修改操作，请停止并报告缺少的功能；不要转而编辑文件。允许通过 pbir cat、pbir get 或只读示例读取 JSON。

**重要：**首先阅读并遵循心智模型。

缺少 pbir 时

使用 uv tool install pbir-cli（或 pip install pbir-cli）安装。在所有常见情况下，包括完全缺少该命令时，都应采用这种方式。

bin/fetch.sh 会下载一个独立的便携版本。仅当尚未安装 pbir，并且无法安装时，才使用它：无法访问 PyPI 网络、没有 Python，或机器受到限制而禁止安装。便携版本不会通过 uv tool upgrade 更新，因此在可以正常安装时优先选择它，会导致用户使用过时的 CLI。如果安装失败，应修复安装问题，而不是绕过安装。

保持 Fabric CLI 为最新版本

使用 fabric-cli 插件发布到 Fabric（pbir publish）时，如果发布报告兼容性问题，请检查已安装的 Fabric CLI（fab）。仅在需要或用户要求时，才使用 uv tool upgrade ms-fabric-cli 升级，并遵守用户固定的版本。

从错误中吸取经验

在项目的记忆文件中记录关于 pbir CLI 的经验：注意事项、意外行为、用户期望和设计偏好。使用适用于相应 Agent 的路径：

• Claude Code：.claude/rules/pbir-cli.md
• Cursor：.cursor/rules/pbir-cli.mdc
• GitHub Copilot：.github/instructions/pbir-cli.instructions.md

条目应简洁且具有普遍参考价值。记忆文件不是变更日志。删除重复内容；与其重述，不如链接到参考资料和示例。

如何使用 pbir

常规工作流

1. 探索报告。报告必须采用 PBIR 格式：pbip、仅含 pbir，或包含 PBIR 元数据的 pbix。优先选择 pbir 或 pbip。每当用户提到 Power BI Desktop，或表示报告已在 Desktop 中打开时，首先运行 pbir desktop list：该命令会将每个正在运行的实例映射到其打开的文件（从而定位磁盘上的报告），并在开始任何编辑前确认桥接可用。pbir desktop 仅适用于 Windows；在 macOS 和 Linux 上不要使用（每次调用都会失败）。改为使用 pbir publish 部署到 Fabric 中的沙盒工作区，并通过 Chrome MCP 工具在浏览器中验证渲染结果。
2. 识别模型。报告通常应为连接到 Power BI 或 Fabric 中远程模型的精简报告。
3. 澄清意图。对于含糊或开放式指令，请查阅 references/vague-prompts.md，并使用 AskUserQuestion 了解预期和报告背景，然后再进行任何修改。
4. 规划更改。对于新报告、页面或视觉对象，先起草线框图或模型图，供用户批准后再构建。
5. 进行更改。查阅 references/、examples/ 中的相关文件，以及 pbi-report-design 等相关技能。
6. 验证。修改命令会验证自身写入的内容。在一批相关更改完成后、任务结束前，运行明确的 pbir validate；迭代时使用范围更小的检查，并在最终信心检查时使用 --all。若要确认视觉效果，报告在 Power BI Desktop 中打开时，优先使用本地流程：pbir desktop refresh，然后运行 pbir desktop screenshot 并检查 PNG（见下文“桌面集成”）。否则，请征求许可，将报告发布到沙盒工作区，并通过 Chrome MCP、devtools CLI 或 Playwright 检查渲染结果。
7. 迭代。预期会有多轮修改。对于含糊提示中的一步到位预期，应提出异议。
8. 记录经验。向上文提到的记忆文件中添加简洁且可泛化的条目。

当用户手动更改了报告，并要求拉取这些更改或从差异中学习时，请遵循 references/manual-roundtrip-review.md。

路径语法

pbir 使用文件系统范式来标识报告、页面、视觉对象等，并使用 glob 语法执行批量操作。

格式：ReportName.Report/PageName.Page/VisualName.Visual

• 类型后缀（.Report、.Page、.Visual）必填
• 路径中有空格时请加引号："My Report.Report/Dashboard.Page"
• 批量操作请使用 glob 模式："Report.Report/**/*.Visual"（对 set 和 rm 操作需要 --force/-f）
  • *.Visual；当前页面上的所有视觉对象
  • Page.Page/*.Visual；指定页面上的所有视觉对象
  • **/*.Visual；所有页面上的所有视觉对象
  • **/card*.Visual；名称以“card”开头的视觉对象
  • **/*.Report/**/*.Visual；所有报告中的所有视觉对象
• 使用 get 或 set 和点表示法来操作属性："Report.Report/Page.Page/Visual.Visual.title.fontSize"
• 筛选器/书签："Report.Report/filter:Name"、"Report.Report/bookmark:Name"
• 如果匹配到多个报告，请使用父文件夹前缀消除歧义
• 也可使用绝对文件系统路径："C:\Reports\Sales.Report"、"C:\Reports\Flash.pbix"（glob 不能与绝对路径组合使用）
• 工作区目标使用 .Workspace 后缀："My Workspace.Workspace/Report.Report"

关键规则

遵循以下所有规则。

0. 向用户询问澄清问题，并对一次性提示词请求提出异议。 采用迭代式、多步骤的工作方式。

1. 开始工作前检查参考资料。 找出可帮助你理解用户需求的相关参考资料和示例。

2. 绝不直接编辑报告 JSON 文件。 始终使用 pbir CLI 命令。使用 pbir cat 或 pbir get 检查 JSON 或属性；对于没有专用命令涵盖的属性，使用 pbir set。

3. 先发现，再设置。 运行 pbir schema describe <type> 列出视觉对象类型的对象，然后运行 pbir schema describe <type> <object> 查看属性名称、类型、范围和枚举值，再进行格式设置。不要猜测属性名称。

4. 优先使用主题格式设置。 应用自定义格式设置前，先检查 pbir visuals format；主题可能已设置相应属性。对于适用于某类型所有视觉对象的更改，优先使用 pbir theme set-formatting。仅将 pbir visuals title/background/border 用于单次覆盖。

5. 按需验证。 修改命令会验证其写入内容。每批完整的修改后，以及完成前，运行 pbir validate "Report.Report"。使用 --qa 检查重叠和溢出，使用 --fields 验证模型字段，最后使用 --all 进行全面检查。

6. 通过 Desktop 桥接验证渲染结果。 报告在 Power BI Desktop 中打开时，每次更改后都运行 pbir desktop refresh，除非用户要求不要这样做；然后运行 pbir desktop screenshot，并检查 PNG。验证无法发现渲染问题（重叠、截断、字段错误、格式难以辨认）；截图是证明更改按预期渲染的唯一依据。如果请求涉及多项更改，应提前询问用户是希望每步更改后刷新（以便在画布中查看进度），还是仅在最后刷新。开始循环操作前，运行一次 pbir desktop list 检查桥接是否可用；如果桥接不可用，则不要在每次更改后重试（参见下文“桥接不可用时”）。

7. 在每个 DAX 表达式中以相同方式引用对象。 在 pbir model -q 查询、报告级度量值和视觉对象计算中，列应写作 'Table'[Column]（始终包含表名并加引号），度量值应写作 [Measure]，前面不加表名。-d "Role:Table.Field" 和 --field 中的 Table.Field 格式是 pbir 绑定语法，并非 DAX；仅在这些标志中使用。

核心工作流

探索与分析

修改前先了解现有报告。添加或调整视觉对象大小前，务必检查页面尺寸和现有视觉对象的位置；不了解页面尺寸就设置位置或大小会导致错误。

pbir desktop list                                # FIRST if Desktop is mentioned: instances (PID, open file)
pbir ls                                          # Find all reports
pbir ls "Report.Report"                          # List pages/filters/theme
pbir tree "Report.Report" -v                     # Full structure with fields
pbir validate "Report.Report"                    # Health check
pbir get "Report.Report"                         # Report properties
pbir pages json "Report.Report/Page.Page"        # Check page width/height

如需深入探索，请参阅 references/exploration.md。

模型发现（绑定字段前必做）

始终查询已连接的模型，以查明正确的表、列和度量值名称。绝不要猜测字段名称。

pbir model "Report.Report"                       # Connection info (workspace, model, thick/thin)
pbir model "Report.Report" -d                    # All tables, columns, measures
pbir model "Report.Report" -d -t Sales           # Filter to specific table
pbir model "Report.Report" -q "EVALUATE VALUES('Geography'[Region])"  # Check field values
pbir model "Report.Report" -q "EVALUATE ROW(\"Revenue\", [Total Revenue])"  # Test a measure
pbir fields list "Report.Report"                 # Fields already in use across report

路由取决于报告的模型引用：精简报告（byConnection）查询 Power BI / Fabric 服务；厚报告（byPath）查询打开该报告的 Power BI Desktop 实例中的本地 Analysis Services 引擎，因此 -q 和 -d 可完全离线地针对实时模型状态运行。本地查询需要 .NET Framework ADOMD 客户端（可从 DAX Studio 或 Desktop 安装中自动找到；可通过 PBIR_ADOMD_DIR 指定其他位置）。

如需了解完整的模型查询模式和字段绑定工作流，请参阅 references/fields-and-bindings.md。

语义模型与报告工作流（te + pbir）

使用 te 修改语义模型，使用 pbir 修改报告。模型重命名可能会在模型内部连带更新，但报告绑定仍保留旧的 Table.Field；使用 te deps --downstream，然后运行 pbir fields find/replace，并验证这两个层面。有关部署顺序和完整工作流，请参阅 references/te-cli-tandem.md。

桌面集成（刷新和截图）

当 Power BI Desktop 在 Windows 上打开 PBIP/PBIR 报表时，使用桥接工具实现最快的视觉反馈循环：

pbir desktop list
pbir desktop refresh "Report.Report"
pbir desktop screenshot "Report.Report/Page.Page" -o verify.png

每完成一批有意义的更改后，都要检查 PNG。PBIX 支持截图，但不支持刷新；macOS/Linux 不支持此桥接工具。如果无法使用，请先验证，再发布到已授权的沙盒，并检查服务中的渲染效果。有关设置、多实例行为和故障排除，请参阅 references/desktop-integration.md。

创建报表

新报表开箱即用，包含：

• sqlbi 主题（专业配色和排版）。除非用户要求使用其他主题，否则不要运行 pbir theme apply-template
• 默认的 Page 1，其中包含一个用于页面标题的 textbox 视觉对象，位置为 (20,20)，高度为 90。不要添加新的文本框；应重命名现有页面。后续视觉对象应放置在 y:120 或更低的位置，以避免与标题文本框重叠。当用户需要干净画布时，在 pbir new report 中使用 --no-title 跳过默认标题文本框

连接方式：传入 --connection "Workspace/Model.SemanticModel"，或先使用 pbir connect 设置活动连接（可选择使用 pbir profile / pbir connect --profile <name> 在已保存的连接之间切换）。设置活动连接后，可以省略连接标志。

pbir new report "Sales.Report" -c "Workspace/Model.SemanticModel"
pbir pages rename "Sales.Report/Page 1.Page" --to "Overview" -f   # Rename default page (new name via --to)
pbir add visual card "Sales.Report/Overview.Page" --title "Revenue" -d "Values:Sales.Revenue" --y 120
pbir add filter Date Year -r "Sales.Report"
pbir validate "Sales.Report"

-d "Role:Table.Field" 中的数据角色名称（例如 Values、Category、Y、Series、Indicator）取决于视觉对象类型的功能架构。对于不熟悉的视觉对象类型，运行 pbir add visual --list 或 pbir visuals bind --list-roles 以查看可用角色。CLI 匹配角色名称时不区分大小写，因此 Values: 和 values: 均可使用。

有关分步创建指南，请使用 create-pbi-report 技能。

添加和设置视觉对象格式

格式层级：基础主题 -> 自定义主题 -> 视觉对象类型默认值 -> 单个视觉对象覆盖。应用特定视觉对象格式前，务必先检查并优先采用主题级格式。使用 pbir visuals format 查看带来源标签（default/wildcard/visualType/visual）的完整级联格式。

# Add a visual with data binding (role names match the visual capability list)
pbir add visual card "Report.Report/Page.Page" --title "Total Sales" -d "Values:Sales.Revenue"

# ALWAYS check theme cascade first; see what formatting already applies
pbir visuals format "Report.Report/Page.Page/Visual.Visual"

# Set formatting in the THEME (preferred; applies to all visuals of this type)
pbir theme set-formatting "Report.Report" "card.*.border.radius" --value 8

# Only format bespoke if genuinely one-off
pbir visuals title "Report.Report/Page.Page/Visual.Visual" --text "Revenue" --fontSize 14 --show

# Bind more fields
pbir visuals bind "Report.Report/Page.Page/Visual.Visual" -a "Category:Products.ProductName"

# Validate after changes
pbir validate "Report.Report"

# If the report is open in Desktop, confirm the rendering
pbir desktop refresh "Report.Report"
pbir desktop screenshot "Report.Report/Page.Page" -o verify.png   # then Read verify.png

有关批量创建视觉对象，请参阅 references/add-new-visual.md。 有关格式设置工作流，请参阅 references/format-visuals.md（主题优先的方法、属性发现、glob 模式）。

快速渲染仪表板循环

有关对渲染器敏感的迭代、发布节奏、New Card 选择器、SVG 表格密度以及仅显示最新数据点的折线标签，请参阅 references/rendered-dashboard-loop.md。

视觉对象组

视觉对象组将多个视觉对象绑定在一起，使其可以一起移动和缩放。当一组视觉对象需要作为一个整体运行时（例如标题栏、KPI 行、图表加注释）请使用视觉对象组。

pbir visuals group "Report.Report/Page.Page" --list                       # List groups on page
pbir visuals group "Report.Report/Page.Page" --create "KPI Group"         # Create empty group
pbir visuals group "Report.Report/Page.Page/Group.Visual" --add "Card.Visual" --add "KPI.Visual"
pbir visuals group "Report.Report/Page.Page/Group.Visual" --remove "Card.Visual"
pbir visuals group "Report.Report/Page.Page/Visual.Visual" --ungroup      # Remove this visual from its group
pbir visuals group "Report.Report/Page.Page/Group.Visual" --ungroup       # Ungroup all members and delete the group

默认模式为 ScaleMode；如需其他行为，可使用 --mode 覆盖。

样式预设

样式预设会一步应用一组精心挑选的格式设置。当用户希望多个视觉对象的外观保持一致，但不想逐一指定每个属性时，请使用预设。

pbir visuals preset --list                                        # Available presets
pbir visuals preset "Report.Report/Page.Page/Visual.Visual" --name minimal
pbir visuals preset "Report.Report/**/*.Visual" --name presentation

预设带有主题；搭配 pbir theme apply-template 使用，可实现完整的视觉一致性。

属性发现（格式设置前必做）

每种视觉对象类型都有数十个对象和数百个属性。设置值之前，请使用架构发现工作流找到正确的对象和属性名称。不要猜测属性名称。

# Step 1: What objects exist for this visual type? (objects + property counts)
pbir schema describe "lineChart"

# Step 2: What properties does an object have? (includes types, ranges, enums, descriptions)
pbir schema describe "lineChart" "lineStyles"

# Step 3: What's currently set on a live visual? (shows source: default/wildcard/visualType/visual)
pbir visuals format "Report.Report/Page.Page/Visual.Visual"
pbir visuals format "Report.Report/Page.Page/Visual.Visual" -v   # Include unset (None) properties
pbir visuals format "Report.Report/Page.Page/Visual.Visual" -p lineStyles  # Filter to object

# Step 4: Fuzzy search for a property by name
pbir visuals properties -s "marker"

对于内置视觉对象，有效类型 ID 和各类型 objects 名称的权威列表来自 Microsoft 的核心视觉对象目录（由 CLI 捆绑并固定版本）。编写内容前，请使用它确认类型或对象名称是否存在：

pbir schema types                       # Built-in visual + entity type ids (--vco for universal container objects, --selectors for selector objects)
pbir schema describe "barChart"         # Valid objects + their properties for one type
pbir schema roles "barChart"            # Data roles the type accepts (required? multiple? Column/Measure)
pbir schema describe "tableEx" --json   # Full JSON for agent consumption

pbir schema describe 使用此核心目录（这是 pbir set 强制执行的权威来源），并结合主题架构补充值范围和枚举信息。自定义视觉对象不在目录范围内。

架构描述包含实用说明（例如，将误差线用作目标线，以及 title.text 支持由度量值驱动的动态值）。使用 --json 输出完整描述。

如需离线查阅每种视觉对象类型的所有属性，请参阅 references/property-catalogue.md。该文件是快照；pbir schema types 和 pbir schema describe 才是权威来源。

批量修改（Glob 模式）

# Set property on ALL visuals in report (glob requires -f)
pbir set "Report.Report/**/*.Visual.title.show" --value false -f

# Find all card visuals
pbir find "Report.Report/**/card*.Visual"

# Format all visuals on a page
pbir visuals title "Report.Report/Page.Page" --show --fontSize 12

条件批量操作（--where）

--where 可筛选 glob 操作所针对的视觉对象。set 和所有 visuals 属性命令均支持此选项。

pbir set "Report.Report/**/*.Visual.title.fontSize" --value 16 --where "visual_type=card" -f
pbir visuals legend "Report.Report/**/*.Visual" --show --where "width__gt=400"
pbir visuals resize "Report.Report/**/*.Visual" --width 350 --height 250 --where "visual_type=card"

谓词运算符：=、__lt、__gt、__lte、__gte、__in=a|b|c、__contains、__icontains。使用逗号组合（按 AND 处理）：--where "visual_type=card,width__gt=300"。完整运算符列表见 references/format-visuals.md。

条件格式设置

# Find out what a container accepts before writing to it
pbir schema describe barChart.dataPoint          # "Conditional formatting:" line at the bottom

# Create CF (structural; use pbir visuals cf)
pbir visuals cf "Visual" --measure "labels.color _Fmt.StatusColor"
pbir visuals cf "Visual" --gradient --field "Table.Field" --min-color bad --max-color good
pbir visuals cf "Visual" --data-bars --field "Table.Field"
pbir visuals cf "Visual" --image --field "_SVG.Bullet"          # measure-driven image or SVG

# Read / edit / remove CF (dot-path; use pbir set / pbir get)
pbir get "Visual.dataPoint.fill.cf"                             # summary
pbir set "Visual.dataPoint.fill.cf.gradient.min.color" --value "bad"
pbir set "Visual.dataPoint.fill.cf" --remove                    # or --clear
pbir get "Report.Report/**/*.Visual.**.cf"                       # bulk read

条件格式设置远不止数据点颜色：标题、副标题、边框、工具提示、坐标轴边界、参考线值、数据标签文本和误差线样式都接受度量值。对于任何单个容器，pbir schema describe <type>.<container> 都是权威说明；其中带星号的属性已通过呈现报表验证，而非根据目录推断得出。

当驱动格式设置的字段不是被格式化的字段时（例如，使用辅助度量值着色的网格列、组合图的次要系列），请使用 --target-field 指定目标；否则，该条目会应用于驱动字段，Desktop 会将其呈现在错误的列上：

pbir visuals cf "Grid.Visual" --rules --field "Sales.Margin %" --rule "lt 0 bad" \
  --on values.backColor --target-field "Sales.Revenue"

有关渐变／规则／图标／数据条／图像选项、复制／删除／转换和最佳实践，请参阅 references/conditional-formatting.md。

视觉对象操作、书签和钻取

pbir visuals action "Visual" --type PageNavigation --target "Details"  # Set action
pbir add bookmark "Report.Report" "Q1 View"                           # Create bookmark
pbir bookmarks page "Report.Report" "Q1 View" "Details"               # Set bookmark target page
pbir pages drillthrough "Report.Report/Details.Page" --table T --field F # Add drillthrough
pbir pages set-tooltip "Report.Report/Tooltip.Page"                   # Configure tooltip

有关书签管理，请参阅 references/bookmarks.md。

筛选器

pbir add filter Table Field -r "Report.Report"                        # Categorical
pbir add filter T F -r "R.Report" --type TopN --n 10 --by-table T2 --by-field F2  # TopN
pbir add filter T F -r "R.Report" --type Advanced --operator GreaterThan --values 1000
pbir add filter Date Date -r "R.Report" --type RelativeDate --period Last30Days

创建筛选器时，会根据已连接的语义模型验证字段。如果无法完成验证（连接缺失、模型无法访问），命令会安全失败，而不会生成未经验证的筛选器。只有当用户明确需要绕过验证时，才使用 --no-validate。

若要更改筛选器类型，请先删除再重新创建。完整筛选器参考请参阅 references/filters.md。

审计报表

pbir validate "Report.Report"                       # Structure, schema, fields, QA (use --all)
pbir bpa run "Report.Report"                        # Best Practice Analyzer rule sweep
pbir bpa run "Report.Report" --fix --save           # Apply safe automatic fixes
pbir tree "Report.Report" -v                        # Structure + field bindings
pbir theme colors "Report.Report"                   # Palette and usage
pbir color list "Report.Report"                     # Every hard-coded color literal and where it is used
pbir fields list "Report.Report"                    # Fields in use
pbir dax measures list "Report.Report"              # Extension measures
pbir filters list "Report.Report"                   # Filters at every scope

BPA 规则通过 pbir bpa rules list/ignore/unignore 管理；忽略的规则按报表分别设置。完整审计清单请参阅 references/audit-report.md。

命令参考

完整的命令参考位于 references/cli-reference.md。使用不熟悉的命令前，务必先运行 pbir <command> --help；帮助文本是标志名称和默认值的权威来源。

命令组速览：

Getting started:     config (show, init, set, paths), connect (+ --profile), profile, new
Browse and query:    ls (+ --tree), find, get, cat, model     # `tree` is an alias of `ls --tree`
Modify:              set, add, mv, cp, rm, visuals, pages
Data:                fields, filters, dax, bookmarks, annotations
Theme and style:     theme (colors, fonts, set-colors, set-fonts, set-formatting, apply-template), color (list, replace), fonts (list, replace, clear, available)
Schema discovery:    schema (= capabilities) (types, describe, roles, status, upgrade), visuals properties, visuals format
Workflow ops:        validate, backup, restore, publish, download, batch, open, bpa, usage
Desktop (Windows):   desktop (list/status, refresh/reload, screenshot)

不太显而易见的命令组说明：

• connect / profile：pbir connect "Report.Report" 会设置活动上下文，因此后续命令可以省略报表路径。pbir profile 可保存和切换已命名的连接（pbir connect --profile dev）。
• visuals group：视觉对象组可让用户一起缩放和定位多个视觉对象。请参阅下文的“视觉对象组”工作流。
• visuals preset：已命名的样式预设（minimal、bold、clean、emphasis、presentation）可一步应用经过精心挑选的格式设置。
• bpa：最佳实践分析器。pbir bpa run "Report.Report" 会报告规则违规；--fix --save 会应用安全修复。pbir bpa rules list/ignore/unignore 可管理规则集。
• color：pbir color list 会列出每个硬编码颜色字面值及其使用位置；pbir color replace --from <hex> --to <hex> 会在整个报表中替换指定颜色（可使用 --theme/--report 限定范围）。这与 theme 命令组不同，后者编辑主题 JSON，而不是行内字面值。
• fonts：这是 color 命令组对应的排版命令组。pbir fonts list 会审查报表和主题中的字体系列、字号和字重；pbir fonts replace --from --to 会在所有位置替换字体系列；pbir fonts clear 会移除各视觉对象的字体/格式覆盖，使其应用主题默认值。若要设置主题自身的字体，请使用 pbir theme set-fonts。
• batch：pbir batch 会针对 glob 匹配的目标运行经过审核的 JSON 规范（version: 2），其中包含多个步骤；plan 会打印 plan_digest，而 run --plan-digest 会拒绝执行与计划不符的操作。可用它进行可重复、可审计的批量编辑；请参阅 references/cli-reference.md 中的“批处理自动化”部分。
• config paths：会显示此操作系统上配置、身份验证状态、模板、备份和缓存的存放位置。自 0.9.30 起，存储采用平台原生方式；切勿假定路径为 ~/.pbir/。
• usage：pbir usage "Report.Report"（或工作区 / 已发布的报表）会通过你的 az login 令牌，从 Power BI 服务获取浏览次数、查看者、页面和加载时间。--model 会添加工作区使用情况指标模型，以提供更丰富的详细信息（需要 Contributor 或更高权限，并会生成一个隐藏模型）。此命令依赖未公开的服务遥测数据。

全局标志

顶层标志；放在子命令之前：pbir -q new report ...，而不是 pbir new report -q ...

-q / --quiet: suppress animations, tips, spinners (agent-friendly)
--output-format text|json: structured stdout for commands that support it
--error-format text|json: structured stderr where supported
--debug: enable tracebacks and timing
--rawdog: skip EVERY validation check (umbrella for --skip all)
--skip <category>: skip validation categories (repeatable, comma-separated): structure, schema, schema-version, fields, enums, qa, roles, layout, theme

pbir 会在修改操作时隐式执行验证。对于有意为之的情况，可使用 --skip/--rawdog 放宽验证，例如使用 pbir --skip fields set ... 创建字段尚未加入模型的视觉对象。这些是全局标志，因此必须放在子命令之前。与其使用 --rawdog，不如优先修复根本问题。

特定命令的输出标志（如 --json 或 -F json）以及修改标志（如 -f/--force）应放在相应子命令之后。请查看 pbir <command> --help；它们不是全局标志。

常见错误

• 角色名称不区分大小写，但应与功能列表匹配。 使用 pbir add visual --list 或 pbir visuals bind --list-roles，查看目标可视化类型的角色标识符（例如 Values、Category、Y、Series）。
• pbir cat 不支持筛选器或书签。 请改用 pbir filters list --json 或 pbir bookmarks json。
• pbir publish 使用位置参数，而非 --workspace。正确用法：pbir publish "Report.Report" "Workspace.Workspace/Report.Report" -f。
• pbir filters list 没有 -v 标志。 详细输出请使用 --json。
• 不要先转换为 PBIX 再发布 PBIR 文件夹。 如果要转换为 PBIX，请直接发布 .pbix 文件。如果要发布 PBIR，请完全跳过转换。
• pbir pages rename 只会重命名文件夹；不会更改页面 ID 或显示名称。重命名单个页面文件夹时，请使用 --to。
• 针对服务连接模型执行 DMV 查询会失败。 对于精简报表（byConnection），pbir model -q 仅运行 EVALUATE DAX；INFO.TABLES() 和其他 DMV 会从服务返回 400，架构则来自 TMDL。请使用 pbir model -d 检查架构。对于厚报表（byPath），在 Desktop 中打开后查询的是本地引擎，此时会使用实时架构。
• pbir desktop refresh 不适用于 PBIX 文件。 Desktop 只会从磁盘重新加载 PBIP/PBIR 定义；PBIX 实例仅支持 pbir desktop screenshot。
• 使用不熟悉的命令前，务必先运行 pbir <command> --help，以确认准确语法。
• 写入操作即使有效，也可能不会被渲染器采用。 现代可视化对象使用实例选择器。在当前版本的 pbir 中，优先使用普通路径（它会正确处理已知对象）；如果旧版本能够读取该值，但 Power BI 忽略了它，请对照 pbir cat 的结果，并显式使用 .id(default).。
• 原生表格值没有垂直对齐属性。 不要自行添加 values.verticalAlignment；请使用 pbir visuals table-density 减小图像高度或行内边距，或者仅在无障碍性和维护方面的权衡可以接受时，才将所有受影响的单元格设为 SVG。

用户交互

对于会改变视觉呈现、字段映射、主题与本地设置的作用范围，或 Deneb 与核心功能之间取舍的选项，请先澄清。执行不可逆的 visuals clear-formatting 前请先确认；对于分批进行的工作，请协商好刷新／发布的频率。如果用户的意图确实不明确，请使用 references/vague-prompts.md。

验证

更改数据的命令会验证自身写入的内容。完成一批连贯的更改后、结束前，运行 pbir validate "Report.Report"。这样可以检查损坏的字段引用、无效 JSON、架构违规和结构问题，无需在每条小命令后重复完整扫描报告。

(no flags): structure + schema validation
--fields: also validate fields exist in model with correct types (Column/Measure)
--qa: also run quality-assurance rules (overlap/overflow, hidden visuals, visual filters, field counts, layout and role-cardinality heuristics)
--semantic: also check visual type ids + objects/visualContainerObjects names against the core visual catalog
--all: structure + schema + fields + QA + semantic
--strict: every non-advisory warning becomes a failure (core-catalog advisories stay warnings)
--json / --tree: output format
--allow-download-schemas: download missing schemas on the fly

更改数据时也会隐式运行相同的检查。如需有意跳过某个类别，请在子命令前使用全局标志：--skip <category>（structure, schema, schema-version, fields, enums, qa, roles, layout, theme；可重复使用，以逗号分隔）或 --rawdog（跳过全部检查）。优先修复问题根源，而不是跳过检查。

--semantic 基于 CLI 随附并固定版本的核心视觉对象目录。它会将无法识别的 visualType、objects 和 visualContainerObjects 名称标记为提示性警告（未列出的属性标记为信息）；--strict 会将这些提示性问题保留为警告，同时对其他所有问题报错。包含 NaN 或 Infinity 的文件会被判定为无效 JSON 并拒绝；仅包含度量值的条形图和柱形图有效，不再被标记为无法呈现。该目录为预览版，可能落后于产品，因此看似合理但未知的名称和自定义视觉对象仍可能有效。请将语义检查结果视为快速创作检查，而非硬性门槛。

架构版本错误：运行 pbir schema fetch --yes，然后运行 pbir schema upgrade "Report.Report" 进行修复。

pbir validate 检查的是结构，而非呈现效果。当报告在 Power BI Desktop 中打开时，每次验证后都要执行桥接循环：pbir desktop refresh、pbir desktop screenshot，然后查看 PNG。未确认更改的呈现效果前，不要报告更改已完成。

参考文件

references/cli-reference.md: full syntax for any command with all flags
references/exploration.md: exploring an unfamiliar report systematically
references/desktop-integration.md: driving Power BI Desktop; canvas refresh, page screenshots, auto-refresh, local model queries, troubleshooting
references/manual-roundtrip-review.md: safe pull-down and semantic comparison of user edits; New Card and table-width lessons
references/rendered-dashboard-loop.md: short validate/query/render batches; publish cadence and renderer-sensitive patterns
references/create-new-report.md: building a report from scratch
references/layout.md: choosing a visual type for the question, then sizing and placing it on the canvas
references/add-new-visual.md: adding visuals, layout patterns, bulk creation
references/add-image.md: registering image resources, page and visual backgrounds, image visuals
references/visual-groups.md: visual groups (create, add/remove members, ungroup)
references/visual-presets.md: style presets (minimal, bold, clean, emphasis, presentation)
references/fields-and-bindings.md: field binding, Column vs Measure types, swapping fields, rebinding
references/te-cli-tandem.md: coordinated semantic-model and report changes with te + pbir; renames, moves, additions, removals, validation order
references/format-visuals.md: formatting workflow, property discovery, glob patterns, --where predicates
references/conditional-formatting.md: CF types, measure-based CF, copy/remove/update/convert
references/reference-lines.md: reference-line entries on chart axes; pbir visuals reference-line and styling via pbir set
references/error-bars.md: error bars and bullet markers on chart visuals; pbir visuals error-bars and styling via pbir set
references/modifying-theme.md: theme inspection, colors, text classes, fonts
references/apply-theme.md: applying/copying/saving theme templates
references/converting-reports.md: format conversion, thick/thin split, merge, rebind
references/thin-report-measures.md: extension measures for CF, conditional rendering
references/visual-calculations.md: visual calculations (RUNNINGSUM, RANK, etc.)
references/filters.md: filter types (Categorical, TopN, Advanced, RelativeDate), management, pane styling
references/bookmarks.md: bookmark management, copying, button references
references/audit-report.md: report quality audit checklist
references/bpa.md: Best Practice Analyzer; running rules, applying safe fixes, managing the rule set
references/vague-prompts.md: handling underspecified prompts; targeted questions, sensible defaults
references/property-catalogue.md: offline property snapshot; universal containers and discovery commands
references/visualTypes/*.md: per-visual-type design rules, CLI commands, and best practices
examples/visuals/default/*.json: read-only examples of minimal visual structures with theme defaults
examples/visuals/formatted/*.json: read-only examples of formatting, CF, filters, and advanced patterns; reproduce them with CLI commands, never by copying JSON into a report

相关技能

• pbi-report-design：用于了解报告设计最佳实践和指南
• pbip-format：用于了解 PBIP 结构，不用于绕过 pbir 报告更改操作
• create-pbi-report：用于按照分步说明创建新报告