powerbi-report-planning

Power BI 报表规划技能

此技能负责协调新建 Power BI 报表的完整生命周期：

定义 -> 检查 -> 编写规范 -> 批准 -> 构建 -> 验证 -> 发布

此技能的范围有意超出纯粹的需求收集流程：它会记录报表规范，并且在用户批准后继续实施。

必须 / 优先 / 避免

必须

• 对需要收集需求、检查依赖项、获得批准并安排构建顺序的全面报表创建工作流，使用此技能。
• 每次只提出一个有针对性的澄清问题，并在确认所需决策后停止提问。
• 锁定 _brief/report-spec.md，并在实施前获得批准。
• 将设计决策交由 powerbi-report-design 处理，将文件操作交由 powerbi-report-authoring 处理。

优先

• 根据提示、模型、现有 PBIP 文件或之前的对话轮次推断显而易见的答案，而不是再次提问。
• 在确定页面范围或视觉呈现建议之前检查语义模型。
• 将发布视为可选步骤，只有在获得批准后才继续。

避免

• 不要将此技能用于对现有 PBIR 文件进行小范围的精准修改。
• 在用户批准锁定的报表规范之前，不要开始构建。
• 不要重复 companion skills 中已有的详细视觉设计或 PBIR 编写指南。

适用场景示例

当用户想要创建新的 Power BI 报表，并且需要以下两项时，使用此技能：

1. 引导式需求收集流程。
2. 批准后进入实施的路径。

示例：

• “我们来用这个语义模型创建一份新的 Power BI 报表。”
• “帮我定义并构建一份 Power BI 报表。”
• “使用报表操作手册开始创建一份新报表。”
• “为新建 Power BI 报表创建一个可复用的工作流。”

不要将此技能用于修改现有报表页面的小任务。对于直接编写 PBIR 的任务，请使用 powerbi-report-authoring。对于不需要完整引导式工作流的视觉评审或从零开始的设计指导（例如一次性的“重新设计这个”或“这个应该是什么样子？”），请直接使用 powerbi-report-design。此技能会在第 3–4 轮中使用设计技能，但不会取代它。

必须遵守的操作规则

1. 每次只提一个问题。 对每项澄清都使用 ask_user。
2. 最多进行 3–5 轮澄清。 每轮可以有一个主要问题，并且只有在绝对必要时才追加一个后续问题。
3. 锁定规范前检查语义模型。 如果有语义模型技能或 MCP 服务可用，则使用它；否则直接检查本地 TMDL/PBIP 文件。
4. 明确检查依赖项。 不要假设 Desktop、MCP、创作功能或 Fabric 发布功能可用。
5. 构建前生成一份已锁定的 _brief/report-spec.md。
6. 实施前征求批准。 用户明确批准之前，不要开始构建。
7. 获批后端到端构建。 包括模型更改、PBIR 生成、验证、Desktop 预览、截图迭代，以及可选的 Fabric 发布。
8. 除非获得发布批准，否则本地编辑仅保留在本地。
9. 不要重复询问已知答案。 如果原始提示、检查过的文件或之前的对话轮次已经提供了受众、页面数量、交付目标、范围或设计方向，请将其记录在工作笔记中并继续。只询问真正不明确的事项或存在风险的权衡。

依赖项清单

开始实施前，记录以下状态：

依赖项	用途	必需条件
Power BI Desktop	打开／重新加载 PBIP，并通过视觉方式验证报表	始终用于本地预览
PBIP/PBIR 项目	基于文件创作报表	始终用于生成报表
TMDL 语义模型	模型持久化和源代码管理	编辑模型时必需
powerbi-modeling-mcp	检查表、列和度量值；创建度量值／列；部署语义模型	实时创作模型时必需
powerbi-report-authoring 技能	验证 PBIR、重新加载 Desktop、截取页面截图	验证报表创作时必需
powerbi-report-management 技能	创建／更新／下载 Fabric 报表	仅在发布到 Fabric 时必需
Node.js	基于生成器创作 PBIR	建议用于创建可复现的报表

如果某项依赖不可用，请继续规划，并将受影响的阶段标记为受阻／需手动处理。不要假装该依赖可用。

轮次结构

第 0 轮 — 设置和依赖项检查

目标：确定语义模型、报表目标以及可用工具。

只询问无法自动检查的事项：

此报表应使用哪个语义模型或数据集？

如果能找到候选项，推荐选项应具体明确。枚举范围内现有的 Fabric 语义模型和本地 .SemanticModel 文件夹，然后将它们作为选项展示，并标记最合适的选项为推荐项。示例：

• <DiscoveredSemanticModelName>（推荐）
• 另一个现有的 Fabric 语义模型
• 新建本地数据集

然后检查：

• 现有的 .pbip、.Report、.SemanticModel 文件夹。
• 是否存在 TMDL 文件。
• 是否存在 Power BI Desktop 自动化脚本。
• MCP 连接是否可用，或是否可以建立连接。
• 是否要求发布到 Fabric。

输出工作记录：

Dependency status:
- Semantic model:
- PBIP/PBIR:
- Desktop preview:
- Modeling MCP:
- Report-authoring skill:
- Fabric publishing:
- Node generator:

第 1 轮 — 受众和任务

目标：了解报表面向哪些人，以及它要支持什么决策／任务。

如果提示中已明确受众和待完成任务，请概述推断出的答案，而不要提问。否则，每次只询问缺失的信息。

受众不明确时询问：

此报表主要面向哪些人？

推荐选项：

1. 高管／领导层 — 简洁的 KPI、趋势、风险和决策
2. 分析师 — 探索、下钻、比较和表格
3. 运营人员 — 监控、异常、状态和行动队列
4. 外部受众 — 精心编排的内容、引导式叙述和尽量少的切片器
5. 爱好者／粉丝 — 杂志风格的叙述、丰富的视觉效果和排名

仅在待完成任务仍不明确时再询问：

此报表应帮助他们完成什么？

推荐选项：

1. 了解整体情况
2. 跟踪绩效
3. 发现异常值或机会
4. 比较实体或细分群体
5. 探索单条记录／个人资料
6. 为定期业务评审做准备

记录：

Audience:
Primary purpose:
Tone:
Success criteria:

第 2 轮 — 模型清单与范围

目标：检查模型并定义首版范围边界，避免再次询问用户已经提供的范围信息。

使用可用的任意模型检查能力，按以下优先顺序选择最先适用的一项：

1. 如果已安装语义模型创作技能，则使用该技能。
2. 建模 MCP 服务（例如 powerbi-modeling-mcp-*）——连接到实时模型，列出表、列、度量值和关系，并运行 DAX 进行实时验证。
3. 如果无法建立实时连接，则直接读取本地 TMDL 文件（definition/model.tmdl、definition/tables/*.tmdl、definition/relationships.tmdl）。

不要在面向用户的提示词中硬编码工具名称——描述检查意图，让 Agent 选择可用工具。

总结：

Facts:
- table, grain, keys, useful measures

Dimensions:
- date/time, geography, entity, category, owner, status, segment

Existing measures:
- core available measures

Likely missing model work:
- measures
- calculated columns
- relationship fixes
- sort columns
- helper fields for slicers/search

Risks:
- nulls/sparsity
- inactive relationships
- high-cardinality slicers
- fields that will not filter as expected

检查后，根据原始请求和先前的回答推断首版范围。如果用户已经提供了页数、报表类型或内容边界（例如“构建一个 4 页仪表板”），不要单独询问范围问题。相反，在工作笔记中总结范围边界：

First-build scope:
- <focused first build / standard report / operational app / narrative report>
- inferred from: <user prompt | prior answer | model shape>
- included now:
- deferred:

仅当边界不明确、范围过广或存在风险时，才询问范围问题。如需询问，请根据检查所得模型提供定制选项，而不要给出通用的首版选项。例如：

该模型支持销售、产品、地理区域、折扣和盈利能力分析。 首版应聚焦于高管绩效，还是也要深入探索产品和客户？

第 3 轮 — 叙事与页面规划

目标：根据模型和范围制定页面架构。

调用或明确参考 powerbi-report-design，以获取页面级类型选择和构成指导。视觉类型选择由设计技能负责；不要在此重复其选择表。利用第 2 轮的数据形态，提出 2–3 种报表结构选项供用户确认。

设计技能提供的五种类型为：高管摘要、运营监控、分析画布、叙事故事、对比基准。对于布局变体、多类型报表和跨页面变体轮换，请遵循设计技能的类型和构成指导。

仅在应用第 2 轮推断出的首版范围后，才提出问题：

我们应采用哪种报表结构？

提出 2–3 种有名称的组合（例如，多领域需求可采用高管概览 + 分析探索 + 对比排名；聚焦型需求可采用单页高管概览）。根据第 1–2 轮的内容推荐一种，并标注 (推荐)。

用户选择后，在答复中拟定页面列表：

Proposed pages:
1. <Page> — archetype — purpose — core visuals — fields/measures
2. <Page> — archetype — purpose — core visuals — fields/measures
<repeat for each approved page>

记录切片器和交互：

• 全局切片器
• 页面专属切片器
• 高基数维度的搜索／前缀切片器
• 钻取／配置文件页面
• 必要时添加书签／导航

第 4 轮 — 设计识别、无障碍性与交付

目标：确定设计识别、无障碍基线和交付目标。

调用或明确咨询 powerbi-report-design，以确定设计识别和主题方向。设计识别（调性 + 标志性元素）由设计技能负责——不要在此另行创造一套词汇。根据设计技能的识别指南选择调性 + 标志性元素组合，然后向用户说明。

询问：

这份报告应该给人什么感觉？

根据第 1–2 轮确定的受众和领域，提供 2–3 个具体的识别选项。每个选项都要说明报告的感觉，以及它所对应的一个标志性视觉手法。推荐其中一个，并标注 (Recommended)。

如果用户有品牌指南，应提供一个以品牌为主导的选项，而不是选择通用调性。

仅在交付目标不明确时，询问：

完成后的报告应该放在哪里？

推荐选项：

1. 先仅创建本地 PBIP
2. 发布到现有 Fabric 工作区
3. 在 Fabric 中创建新的语义模型 + 报告
4. 更新现有 Fabric 报告
5. 先在本地构建，稍后再决定是否发布

设计默认项（来自设计技能的注意事项和基础主题；除非用户另行指定，否则自动应用）：

• 使用无障碍对比度（每组文字/背景组合至少满足 WCAG AA）。
• 避免红底红字和低对比度配色。
• 优先使用 Azure Map，而不是已弃用的 map/filledMap 视觉对象。
• 为每个图表添加替代文本。
• 对基数较高的字段使用可搜索的下拉切片器。
• 仅对类别较少的字段使用平铺/列表切片器。
• 将详细表格放在页面靠下的位置。
• 保持报告交互可预测且一致。

设计契约关卡

在生成供审批的 _brief/report-spec.md 之前，先从 powerbi-report-design 获取规范的 Design Brief: YAML 块。规划器可以向设计技能提供需求、模型清单、页面目标和用户约束，但不得另行编写一套相互竞争的详细设计框架。

规范设计块必须包含：

• generated_by: powerbi-report-design
• contract_version
• pages[] 中为页面计划里的每个页面各提供一个条目
• pages[].layout_contract.canvas
• pages[].layout_contract.grid.regions
• pages[].layout_contract.placements
• pages[].layout_contract.space_audit
• 每个页面各有一个带非空标题文本的 page_title 文本框 placement
• 切片器 placement 位于右上角的 filters 区域或有充分理由的筛选栏中
• 不得在最大或最显眼的主视觉区域中放置仅显示单个值的 cardVisual，除非设计将其标记为包含上下文和理由的复合 KPI 处理方式
• 不得包含未解决的占位符、省略号或仅有文字说明的线框图

如果设计块缺少上述任何项目，请先停止并修订设计契约，再请求审批或调用 powerbi-report-authoring。

锁定报告规格输出

完成第 0–4 轮后，生成一个文件并将其保存到当前工作目录下的 ./_brief/：

• ./_brief/report-spec.md — 供审批和实施交接使用的唯一事实来源。

report-spec.md 包含两个层次：

1. Markdown 章节，用于用户审批和提供易读的上下文。
2. 一个围栏式 yaml 块，其中包含 powerbi-report-design 返回的完整 Design Brief:——这是 powerbi-report-authoring 使用的规范实施契约。

如果 Markdown 文字与嵌入的 YAML 不一致，请在构建前修正 report-spec.md。不要让编写 Agent 在相互冲突的指示中自行选择。

如果 Agent 运行时提供专用的会话/暂存文件夹（例如由运行框架注入的 session-state 路径），也可以在其中写入副本，方便用户查看；但除非每个后续编写步骤都明确携带备用绝对路径，否则规范实施交接文件仍为 ./_brief/report-spec.md。

report-spec.md 模板

用户审批文档和 Agent 交接契约。Markdown 记录签核粒度；其中嵌入的 YAML 记录精确的实现意图。

# Report Spec

## Report identity
- Report name:
- Semantic model:
- Audience:
- Primary purpose:
- Delivery target:

## User decisions and constraints
- Scope:
- Page count:
- Interactivity:
- Design direction:
- Publishing:
- Tooling:
- Model edit permissions:
- Accessibility:
- Data caveats:

## Narrative
- Core story:
- Audience promise:
- Key questions answered:

## Design identity (from `powerbi-report-design` Step 1)
- Tone: <named entry from tone-catalog, e.g. "Editorial Newsroom">
- Signature: <one defining move, e.g. "tabular numerals + display serif headlines">
- Brownfield delta (if applicable): <current_tone → target_tone>

## Page plan (archetypes from `powerbi-report-design` Step 3)
1. Page name
   - Archetype:                      <Executive Summary | Analytical Canvas | …>
   - Layout variant (A/B/C):         <plus one-sentence variant_rationale>
   - Purpose:
   - Visuals:
   - Fields/measures:
   - Slicers/interactions:

## Design system summary
- Theme name + base palette (1–2 lines):
- Color semantics (which measure → which color, 1–2 lines):
- Typography pairing (display + body):
- Layout pattern (grid + gutter + density):
- Accessibility commitments:

## Model requirements
- Existing measures:
- New measures:
- New calculated columns:
- Relationship/sort requirements:

## Canonical design contract

Paste the exact fenced `yaml` block produced by `powerbi-report-design` here.
Do not rewrite it from planner memory and do not replace its mechanical
`layout_contract` with a freeform ASCII wireframe.

The YAML block is authoritative for implementation. `powerbi-report-authoring`
must implement this block; surrounding prose is context and conflict detection.

## Implementation notes

- Model changes:
- PBIR/report authoring:
- Validation:
- Desktop screenshot verification:
- Publishing boundary:
- Risks:

审批前的必要验收检查

编写审批问题前，请确认规范满足以下所有要求。如果有任何一项未通过，请先修正 report-spec.md 和嵌入的 Design Brief: 块，再请求审批。

• 代码块以 Design Brief: 开头。
• 包含 generated_by: powerbi-report-design 和 contract_version。
• 每个 Markdown 页面都有对应的 pages[] 条目。
• 每个页面都有 layout_contract.canvas、layout_contract.grid.regions 和 layout_contract.placements。
• 每个页面都有 layout_contract.space_audit，其中 unplaced_regions 为空，并明确说明留白／平衡的理由。
• 每个页面都有一个带有非空标题文本的 page_title 文本框放置项。
• 切片器位于右上角的 filters 区域或有合理说明的筛选栏中；没有数据视觉对象放置在切片器／标题带区域下方。
• 除非 YAML 明确描述了包含上下文的复合 KPI 设计，否则单值 cardVisual 不得占据最大／主视觉区域。
• 已审批的 YAML 不含省略号（...）、未解决的占位符，也不遗漏 Markdown 中承诺的页面／视觉对象。

审批关卡

编写 report-spec.md 后，只提出一个审批问题，且必须完全按照以下内容：

批准此报告规范，以便我开始构建吗？

建议选项：

1. 批准 — 开始构建
2. 修改受众／目的
3. 修改范围／页面规划
4. 修改设计／交付

在用户批准前，不要调用创作或发布技能。

审批后的实现

用户批准后，按以下顺序执行：

1. 重新读取已批准的规范报告（通常为 _brief/report-spec.md， 或明确传递的其他绝对路径），并提取其中嵌入的 Design Brief: YAML 块。开始创作前，确认其中包含 generated_by: powerbi-report-design、contract_version，每个页面都有已填充的 layout_contract 和 space_audit。对于从零开始的项目，确认画布为 FHD（1920 x 1080），除非用户选择了其他尺寸；并确认最大／主视觉区域不是单值 cardVisual。
2. 将第一个实现待办事项标记为进行中。
3. 连接语义模型。
4. 按优先顺序，使用可用的模型创作路径创建／更新所需度量值和计算列：语义模型创作技能、建模 MCP 服务或直接编辑 TMDL。
5. 尽可能使用 DAX 验证每项模型变更。
6. 更改计算列或度量值后，使用所选工具支持的轻量级重新计算方式（例如，使用 refreshType=Calculate 执行 XMLA 刷新），除非明确要求且可以安全执行完整源数据刷新。
7. 将模型变更导出为 TMDL。
8. 如果导出生成了扁平的 TMDL 布局，请将其重组为 definition/database.tmdl、definition/model.tmdl、 definition/relationships.tmdl 和 definition/tables/*.tmdl。
9. 搭建或复制 PBIP/PBIR 报告结构。
10. 依照 powerbi-report-authoring 指引创作 PBIR。
11. 生成报告文件。
12. 验证所需文件和 JSON。
13. 在 Power BI Desktop 中打开／重新加载。
14. 对页面进行截图。
15. 修复视觉对象、切片器、数据绑定、无障碍性和布局问题。
16. 仅当已批准的交付目标包含发布时，才进行发布。

Fabric 发布规则

仅当已批准的交付目标包含发布时才进行发布。将发布步骤交由 powerbi-report-management 处理；不要使用此技能编写 Fabric REST 调用 或 definition.pbir byConnection 负载。请参阅 powerbi-report-management，了解权威的 byConnection 架构 （最简 API 格式和用于本地 Desktop 验证的完整 XMLA 格式）、LRO 轮询和主题上传规则。

调用 powerbi-report-management 时需遵守的规划器级规则：

• 动态解析工作区、报表和语义模型；不要将 ID 硬编码。
• 创建/更新时包含所有 PBIR 定义部分；切勿发送不完整定义。
• 自定义主题上传路径必须与 report.json 中引用的路径完全一致。
• 对长时间运行的操作使用 --verbose，并轮询 LRO，直至达到终态（Succeeded / Failed）。
• 操作完成后，清理所有临时发布脚本或负载文件。

验证标准

满足以下条件后，报表才算完成：

• 必需的 PBIP/PBIR 文件均已存在。
• 所有 JSON 均可解析。
• definition.pbir 指向预期的语义模型。
• 页面和视觉对象的生成数量符合预期。
• Power BI Desktop 可以打开 .pbip。
• Desktop 重新加载成功。
• 至少成功截取封面以及任何新创作页面的屏幕截图。
• 如果已发布，Fabric LRO 返回 Succeeded。

反模式和注意事项

• 与手动编辑单个视觉对象 JSON 文件相比，生成 PBIR 更安全。
• Desktop 重新加载前，必须先保存模型更改。
• DAX 筛选方向可能导致基于事实表标志的维度聚合出错。
• 高基数切片器需要搜索或前缀筛选。
• Desktop 验证能够发现 JSON 验证无法发现的问题。
• Fabric 发布对 byConnection 架构和主题路径十分敏感。