pbip

PBIP 项目格式

PBIP（Power BI Project）是 Power BI 的开发者模式文件格式。它将 .pbix 二进制文件拆分为按文件夹组织的、人类可读的文本文件，从而支持源代码管理、外部编辑和多人协作。

通用重要指南

• 此技能涵盖项目结构，而非报表编辑。 使用 te 处理语义模型，使用 pbir 处理所有报表修改。切勿手动编辑 PBIR JSON。
• PBIX 是黑盒；PBIP 是透明的。 PBIX 是无法进行差异比较或外部编辑的单个二进制文件。PBIP 会将相同内容拆分为文本文件。可在 PBI Desktop 中通过 File > Save As 在两种格式间转换。
• 厚报表与薄报表： 厚报表在同一项目中包含 .Report/ + .SemanticModel/（definition.pbir 使用 byPath）。薄报表仅包含 .Report/，通过 byConnection 连接到远程模型。对于托管型/共享 BI，推荐使用薄报表。
• 一个项目可以包含多个项目项。 可以同时存在多个 .Report/ 和 .SemanticModel/ 文件夹。.pbip 文件是可选的——也可以直接打开 definition.pbir。
• 使用不带 BOM 的 UTF-8 编码。 所有文件都必须保存为不带 BOM 的 UTF-8 编码。BOM 前缀会导致某些工具解析出错。
• Git 换行符： PBI Desktop 写入 CRLF。请在 .gitattributes 中配置 core.autocrlf 或 * text=auto 以统一换行符。
• Windows 路径长度限制为 260 个字符。 请使用较短的根路径。页面/视觉对象 GUID 嵌套过深可能会超过此限制。
• Desktop 仅选择性重新加载。 对受支持的报表/模型更改使用 pbir desktop refresh；更改主题后，请关闭并重新打开 Desktop。
• 重命名会产生跨范围影响。 使用 te mv --save 重命名模型对象，然后使用 pbir fields replace 或 replace-table 更新各个报表，并验证两端。
• SparklineData 元数据选择器会在紧凑字符串中嵌入 Entity 引用，不遵循标准的 SourceRef.Entity JSON 结构，容易遗漏。
• DAX 查询文件有两个存放位置： <Name>.SemanticModel/DAXQueries/ 和 <Name>.Report/DAXQueries/。重命名时务必检查这两个位置。

处理 PBIX 文件

请将 PBIX 视为不透明的 Desktop 工件。不要解压、修改其内部内容、根据其内容重建 PBIR，也不要调用未经批准的提取引擎。围绕向第三方重新分发引擎的 Microsoft 许可/EULA 问题尚未解决。

请使用 Power BI Desktop File > Save As > Power BI Project (.pbip)，然后使用 pbir 处理生成的 .Report 文件夹，并使用 te 处理语义模型。如果无法使用 Desktop 转换，请停止操作并索要 PBIP/PBIR 源工件，而不要自行设想转换方式。

PBIX 与 PBIP 对比

方面	PBIX	PBIP
格式	单个二进制文件	文本文件文件夹
源代码管理	不便于进行差异比较	可用于 Git，差异内容便于阅读
协作	同一时间只能由一位作者操作	支持多人协作，便于合并
外部编辑	不支持	VS Code、Tabular Editor、脚本
部署	File > Publish	Git 集成、Fabric API、fabric-cicd
数据	包含缓存数据	cache.abf 已被 gitignore；Git 中仅包含元数据
转换	File > Save As > PBIP	File > Save As > PBIX

项目结构

PBIP 必须包含 .Report/ 文件夹。.SemanticModel/ 文件夹是可选的——薄报表仅包含 .Report/，并通过 definition.pbir 中的 byConnection 指向远程语义模型。

两个项目项中的 .pbi/ 子文件夹（localSettings.json、editorSettings.json、cache.abf 等）全部可选——它们是 Power BI Desktop 生成的、按用户/计算机区分的运行时状态。使用外部工具新建的 PBIP 可能不包含这些文件夹，但项目仍可在 Desktop 中正常打开。

<ProjectName>/
+-- <Name>.pbip                              # Entry point (references .Report folder) — optional
+-- .gitignore                               # Recommended; excludes .pbi/localSettings.json and cache.abf
+-- <Name>.SemanticModel/                    # OPTIONAL — absent for thin reports
|   +-- .pbi/                                # All contents OPTIONAL, per-user runtime state
|   |   +-- localSettings.json               # User-specific (gitignored)
|   |   +-- editorSettings.json              # Editor settings (committed)
|   |   +-- cache.abf                        # Data cache (gitignored)
|   |   +-- unappliedChanges.json            # Pending Power Query changes
|   |   +-- daxQueries.json                  # DAX query view tab settings
|   |   +-- tmdlscripts.json                 # TMDL view script tab settings
|   +-- definition.pbism                     # SM entry point (required if .SemanticModel exists)
|   +-- definition/                          # TMDL format (preferred) — see tmdl skill
|   +-- model.bim                            # TMSL format (legacy alt to definition/, mutually exclusive)
|   +-- diagramLayout.json                   # SM diagram (no external edit)
|   +-- DAXQueries/                          # .dax files from DAX query view
|   +-- TMDLScripts/                         # .tmdl files from TMDL view
|   +-- Copilot/                             # Copilot tooling metadata
|   +-- .platform                            # Fabric identity (displayName, logicalId)
+-- <Name>.Report/                           # REQUIRED
|   +-- .pbi/                                # OPTIONAL runtime state
|   |   +-- localSettings.json               # User-specific (gitignored)
|   +-- definition.pbir                      # Report entry point (required for PBIR format)
|   +-- definition/                          # PBIR format — see pbir-format skill
|   |   +-- report.json
|   |   +-- version.json
|   |   +-- pages/
|   |   |   +-- pages.json
|   |   |   +-- <page-slug>/                 # See "Page folder naming" below
|   |   |   |   +-- page.json
|   |   |   |   +-- visuals/...
|   +-- report.json                          # PBIR-Legacy format (legacy alt to definition/)
|   +-- mobileState.json                     # Mobile layout (no external edit)
|   +-- semanticModelDiagramLayout.json      # Diagram positions (table renames)
|   +-- CustomVisuals/                       # Private custom visual metadata
|   +-- StaticResources/
|   |   +-- SharedResources/                 # Base themes, shared resources
|   |   |   +-- BaseThemes/<name>.json       # Resolution path: <report>/StaticResources/SharedResources/<item.path>
|   |   +-- RegisteredResources/             # Custom themes, images, .pbiviz files
|   +-- DAXQueries/                          # .dax files from report DAX query view
|   +-- .platform                            # Fabric identity

页面文件夹命名

Power BI Desktop 默认会为新页面、视觉对象、书签和筛选器文件夹使用不透明的 20 位十六进制 slug（例如 847663d71e27e0840063）。根据 Microsoft 文档，这些名称可以重命名为易读名称，但替换后的名称必须满足以下要求：

• 正则表达式： ^[\w-]+$——只能包含单词字符（字母、数字、下划线）或连字符。
• 不能包含空格、点号或其他标点符号。 不符合此规则的名称会被 Power BI Desktop 静默忽略，页面或视觉对象也会从加载的报表中消失。这是最难诊断的一类问题，因为不会弹出错误对话框。
• 文件夹名称必须与 name 字段完全匹配（区分大小写）。 文件夹可以不带后缀（<slug>/），也可以带 .Page 后缀（<slug>.Page/）——两种形式在磁盘上都有效。pbir-cli 在 CLI 路径语法中使用 .Page 后缀；当前 Desktop 保存的文件不带此后缀。
• pages.json.pageOrder 条目必须引用 slug，而非显示名称。activePageName 必须是 pageOrder 中的某个条目。
• 外部重命名后，请重启 Desktop。 Power BI Desktop 在打开期间不会检测文件更改。

请使用 pbir pages rename 重命名页面；此命令会负责更新跨报表引用。不要重命名文件夹或手动修改相关 JSON。

SharedResources 路径解析

resourcePackages[] 中列出的项目会相对于以下路径进行解析：

<Report>/StaticResources/<package_type>/<item.path>

对于包含项目 { "path": "BaseThemes/Fluent2-CY26SU03.json" } 的 SharedResources 包，Power BI Desktop 会查找：

<Report>/StaticResources/SharedResources/BaseThemes/Fluent2-CY26SU03.json

资源文件缺失是常见的阻断性错误。 如果 report.json 声明了 themeCollection.baseTheme.type = "SharedResources"，并指向磁盘上不存在的资源，报表将无法打开。validate_pbip.py 会对此进行明确检查。

常见任务的阅读指南

任务	阅读内容
转换 PBIX 源文件	上文的处理 PBIX 文件——使用 Desktop 另存为；无需提取
了解入口文件结构	references/pbip-file-types.md——.pbip、.pbir、.pbism、.platform JSON 结构、版本属性、byPath 与 byConnection
重命名表、度量值或列	te mv --save，然后执行 pbir fields replace 或 replace-table；参考文档仅用于了解验证范围
分支或复制 PBIP 项目	references/pbip-file-types.md——更新 .pbip 路径、.pbir byPath、.platform logicalId 和 displayName
使用 Copilot 工具文件	references/copilot-folder.md——AI 指令、已验证答案、架构、提示词示例
编辑 TMDL 模型文件	tmdl 技能——语法、编写方法、列属性、命名约定
更改 PBIR 报表	pbir-cli 技能——所有报表变更；pbir-format 仅提供只读的架构上下文
重命名后验证引用是否完好	下方的 Grep 命令

分支 PBIP 项目

1. 复制项目文件夹——用新名称复制整个根文件夹。
2. 重命名项目文件夹——将 .Report/ 和 .SemanticModel/ 子文件夹重命名为与新项目名称一致。
3. 重命名并更新 .pbip——重命名 .pbip 文件，并更新 artifacts[].report.path，使其指向重命名后的 .Report 文件夹。
4. 更新 .pbir——如果报表使用 byPath，请更新路径，使其指向重命名后的 .SemanticModel 文件夹。
5. 更新 .platform 文件——在每个 .platform 文件中，将 displayName 设置为新项目名称。如果要作为单独的 Fabric 项目部署，请重新生成 logicalId（新的 GUID）。

验证

有两个验证工具，可搭配使用：

1. scripts/validate_pbip.py — 项目级验证器，用于检查跨领域事项：.pbip 根文件、.platform 标识、语义模型格式（TMDL 或 TMSL）、datasetReference 解析、磁盘上的主题资源解析、孤立页面文件夹，以及忽略页面名称的正则规则（Power BI Desktop 会静默忽略不符合 ^[\w-]+$ 的页面名称）。如果 pbir validate 位于 PATH 中，则会委托它进行深度 .Report 架构验证。

   python3 scripts/validate_pbip.py <path-to-.pbip-or-project>           # validate
   python3 scripts/validate_pbip.py <path> --fix                         # scaffold .gitignore
   python3 scripts/validate_pbip.py <path> --json                        # machine-readable
   python3 scripts/validate_pbip.py <path> --no-pbir-cli                 # skip delegation
   

   退出代码：0 表示无问题，1 表示只有警告，2 表示存在错误，3 表示用法错误。

2. pbir validate <Report.Report>（来自 pbir-cli 技能）— 用于 .Report 文件夹的规范 JSON 架构和 PBIR 结构验证器。检查 JSON 语法、架构合规性、必填字段，以及可选的 --qa / --fields / --strict 检查。

3. pbip-validator Agent — 在重命名后需要交互式、由大模型驱动的孤立引用检查，或需要推理整个项目而非生成确定性报告时使用。

**pbir validate 的已知问题：**如果项目的 .pbi/localSettings.json 使用的架构版本比 pbir-cli 内置的版本更新，pbir validate 会返回 SCHEMA_UNSUPPORTED。传入 --allow-download-schemas 以便按需获取缺失的架构，或忽略 .pbi/ 文件（这些文件属于每用户的运行时状态，不是已提交定义的一部分）。

每次重命名或派生操作后，都要验证不存在旧引用。

# Search for old name across all project files
grep -r "Old Name" "Project.Report/" "Project.SemanticModel/" --include="*.json" --include="*.tmdl" --include="*.dax"

# Search with word boundaries to avoid partial matches
grep -rP "\bOld Name\b" "Project.Report/" "Project.SemanticModel/"

# Look for old name in single-quoted DAX references
grep -r "'Old Name'" --include="*.tmdl" --include="*.dax"

常见的遗漏位置：

1. SparklineData 元数据 —— 标准 JSON 结构之外的紧凑字符串格式
2. 条件格式表达式 —— 嵌套在 Conditional.Cases 中的 Entity 引用
3. 筛选器配置 —— filterConfig 部分中的页面级和视觉对象级筛选器
4. 排序定义 —— 视觉对象 JSON 中的 sortDefinition 块
5. Report 文件夹中的 DAX 查询 —— 第二个 DAX 查询位置
6. 文化设置文件中的 linguisticMetadata —— 嵌入式 JSON 中的 ConceptualEntity 和 ConceptualProperty

相关技能

此插件内：

• tmdl —— 直接编辑 .tmdl 文件时使用的 TMDL 语法、编写和编辑规则
• pbir-format —— PBIR JSON 格式、visual.json、主题、筛选器和报表扩展

其他插件：

• semantic-models 插件 —— 用于语义模型开发的工具和工作流（命名约定、模型质量）。适用于处理实际模型内容，而不只是其文件格式。
• pbi-desktop 插件 —— 通过 TOM/ADOMD.NET 连接到 Power BI Desktop 的本地 Analysis Services 实例
• tabular-editor 插件 —— Tabular Editor CLI、C# 脚本、BPA 规则和文档搜索

参考资料

项目结构：

• references/pbip-file-types.md —— 入口文件结构（.pbip、.pbir、.pbism、.platform）、.pbi/ 子文件夹、DAXQueries/、TMDLScripts/、model.bim、.gitignore、版本属性、JSON 示例
• references/copilot-folder.md —— Copilot/ 文件夹结构（AI 指令、已验证答案、架构、提示词示例）

重命名操作：

• references/rename-cascade.md —— 各重命名级联位置的详细前后对比示例（TMDL + 报表文件）

**获取文档：**如需获取最新的 PBIP 参考文档，请搜索 https://learn.microsoft.com 并获取相关页面。根据用户的请求进行搜索，并按需执行多次搜索，以确保在继续操作前掌握足够的上下文。

外部参考资料：

• PBIP 概述（Microsoft Learn）
• 语义模型文件夹（Microsoft Learn）
• 报表文件夹（Microsoft Learn）