bpa-rules

最佳实践分析器规则

为 Tabular Editor 和 Power BI 语义模型创建和改进 BPA（最佳实践分析器）规则的专家指南。

何时使用此技能

在任务涉及以下内容时自动启用：

• 为语义模型验证创建新的 BPA 规则
• 为模型、团队或组织推荐或选择 BPA 规则
• 改进或调试 BPA 规则表达式
• 编写 FixExpression 以自动修复规则违规
• 了解 TMDL 文件中的 BPA 注释
• 根据最佳实践分析语义模型
• 将临时检查转换为可复用的 BPA 规则
• 审计或发现所有来源（内置、URL、模型、用户、计算机）中的 BPA 规则

主要工作流：交互式问答探索（双钻石）

重要：不要立即生成 BPA 规则。 这是一个需求收集过程。使用 AskUserQuestion 工具，与用户进行多轮迭代式对话。在充分了解用户的业务、团队、模型和优先事项之前，持续提问。只有在此之后，才能开始生成规则。

工作流遵循双钻石模式：

1. 发散——广泛了解用户的背景、组织和目标
2. 收敛——缩小范围，明确具体的优先事项和限制
3. 发散——探索模型结构并确定候选规则领域
4. 收敛——选择并生成最终的定制规则集

钻石 1：需求收集（阶段 1-2）

阶段 1：了解用户和组织

每轮调用 AskUserQuestion，提出 2-4 个问题。每轮结束后，查看答案并提出后续问题。在组织背景明确之前，不要进入阶段 2。 持续提问，直到充分了解情况。

第 1 轮——目标和受众：

询问主要目标以及规则的使用者。示例 AskUserQuestion 调用：

• 问题 1：“这些 BPA 规则的主要目标是什么？”——选项：“为我的团队设置 BPA”、“改进特定模型”、“创建治理/合规规则”（其他）
• 问题 2：“谁会使用这些规则？”——选项：“独立开发者”、“小型团队（2-5 人）”、“大型组织/多个团队”（其他）
• 问题 3：“你使用哪些工具？”——选项：“Tabular Editor 3”、“Tabular Editor 2”、“CI/CD 中的 TE CLI”、“Fabric 笔记本”

第 2 轮——标准和现有规则：

根据第 1 轮的答案，询问相关规范和现有规则。示例：

• 问题 1：“你们是否有现有的命名规范？”——选项：“有，且已有文档记录”、“有，但较为非正式/临时”、“目前还没有规范”（其他）
• 问题 2：“你们是否已在使用 BPA 规则？”——选项：“有，在 Tabular Editor 中使用”、“有，来自 URL/仓库”、“没有现有规则”（其他）
• 问题 3：“哪些类别最重要？”——multiSelect: true——选项：“性能”、“元数据/文档”、“DAX 质量”、“命名规范”

第 3 轮及后续——根据需要追问：

如果用户已有规则，询问文件路径或 URL，并读取规则。如果用户提到了命名规范，询问具体内容。如果用户提到了 CI/CD，询问流水线设置。持续调用 AskUserQuestion，直到充分了解组织情况。

阶段 2：调查模型

完成阶段 1 后，使用 AskUserQuestion 确定如何访问模型：

• 问题："您的语义模型以何种方式提供？" —— 选项："已发布到 Fabric / Power BI Service"、"本地 PBIP（.tmdl 文件）"、"本地 .pbix 文件"、"我有一个 model.bim 文件"

然后根据答案调查模型：

答案	操作
已发布到 Fabric	使用 AskUserQuestion 获取工作区和模型名称。然后使用 fab CLI 远程检查——加载 fabric-cli 技能并阅读 references/model-investigation.md，了解具体命令。
本地 PBIP	使用 AskUserQuestion 获取 .SemanticModel/definition/ 文件夹的路径。然后使用 Read/Grep 工具直接读取 TMDL 文件。
仅有本地 .pbix	引导用户在 Power BI Desktop 中另存为 PBIP：文件 > 另存为 > Power BI 项目 (*.pbip)。然后询问生成的文件夹路径。详细步骤请参阅 references/model-investigation.md。
model.bim 文件	使用 AskUserQuestion 获取文件路径。然后使用 jq 解析，或直接读取。
尚无模型	跳过模型调查；仅根据组织背景生成通用规则。

从模型中提取的信息（读取文件、grep 模式、统计对象数量）：

• 表数量、度量值数量、列数量
• 存储模式（Import、DirectQuery、Direct Lake、混合）
• 元数据完整度（说明、显示文件夹、格式字符串）
• 正在使用的 DAX 模式（CALCULATE、FILTER/ALL、计算组、UDF）
• 关系模式（双向、多对多、非活动）
• 已定义的 RLS 角色
• 当前使用的命名约定
• 已嵌入 model.tmdl 的现有 BPA 注释

调查模型后，向用户总结调查结果，并使用 AskUserQuestion 确认分析是否准确，以及是否有任何遗漏。

菱形 2：规则生成（阶段 3-4）

阶段 3：确定优先级并提出建议

根据收集到的所有信息，按优先级提出规则类别建议。生成任何规则之前，使用 AskUserQuestion 让用户确认或调整。

**按与用户背景的相关性对类别排序。**例如：

如果模型中有许多度量值没有说明，且用户重视治理：

1. 元数据（高优先级——许多对象缺少说明）
2. 治理（高优先级——用户目标）
3. 性能（中优先级——发现了一些未使用的隐藏列）
4. DAX 表达式（中优先级——发现了一些 FILTER/ALL 模式）
5. 命名约定（低优先级——模型已遵循一致的命名方式）

使用 AskUserQuestion 询问：

• 要包含哪些类别（multiSelect）
• 为每个类别设定何种严重程度（或由技能决定）
• 是否应包含 FixExpressions（有些团队更倾向于手动修复）

在用户确认优先级之前，不要生成规则。

阶段 4：生成规则

仅在完成阶段 1-3 后，生成适合具体情况的 BPA 规则。每条规则都应：

• 说明其与用户的特定模型和背景相关的原因
• 在安全且实用时包含 FixExpression（如果用户选择启用）
• 根据用户说明的优先级设置严重程度
• 在规则 ID 和名称中使用组织的命名约定

生成规则后，使用 AskUserQuestion 询问：

• 是否需要调整、移除或添加任何规则
• 将输出保存到何处（用户级、计算机级、嵌入模型，或 URL）
• 是否使用 scripts/validate_rules.py 进行验证

持续迭代规则集，直到用户满意为止。继续调用 AskUserQuestion 进行优化。

何时跳过问答

仅在以下情况跳过完整的问答流程：

• 用户请求一条具体、定义明确的规则（例如“编写一条检查未添加描述的度量值的规则”）
• 用户请求改进或调试现有表达式
• 用户请求审核现有规则
• 用户在请求中提供了所有上下文

即使在这些情况下，如果请求含糊不清，也要使用 AskUserQuestion 提出澄清问题。

重要事项

• 在建议规则表达式之前，务必验证表达式
• 针对目标范围（度量值、列、表等）测试表达式
• 确保 FixExpression 不会导致数据丢失或破坏模型
• 使用较新的 TOM 属性时，请考虑 CompatibilityLevel

Tabular Editor 兼容性

BPA 规则文件必须遵循特定的格式要求，Tabular Editor 才能正确加载。未遵循这些规则的文件可能会显示空的规则集合，或完全无法加载。

换行符（必须使用 CRLF）

Windows 上的 Tabular Editor 要求使用 Windows 换行符（CRLF，\r\n）。仅使用 Unix 换行符（LF）的文件将无法加载，或会显示空的规则集合。

将文件转换为 CRLF：

# macOS/Linux
sed -i 's/$/\r/' rules.json

# Or use the validation script
python scripts/validate_rules.py --fix rules.json

文件路径

在 Tabular Editor 中添加规则文件时：

• 使用绝对路径（例如，C:\BPARules\my-rules.json）
• 避免使用 ..\..\.. 这样的相对路径——TE 可能无法解析这些路径
• URL 可可靠使用（例如，https://raw.githubusercontent.com/...）

JSON 格式要求

**不要添加额外属性：**TE 的 JSON 解析器非常严格。只能使用允许的字段：

• ID、Name、Category、Description、Severity、Scope、Expression
• FixExpression、CompatibilityLevel、Source、Remarks

避免使用以下模式：

// BAD: _comment fields not allowed
{ "_comment": "Section header", "ID": "RULE1", ... }

// BAD: Runtime fields (TE adds these, don't include them)
{ "ID": "RULE1", "ObjectCount": 0, "ErrorMessage": null, ... }

// GOOD: FixExpression can be null or omitted
{ "ID": "RULE1", "FixExpression": null, ... }
{ "ID": "RULE1", "Name": "...", "Severity": 2, "Scope": "Measure", "Expression": "..." }

注意：FixExpression: null 有效。ErrorMessage 和 ObjectCount 是 TE 添加的运行时字段——不要将它们包含在规则定义中。

Regex 表达式语法

在表达式中使用 RegEx.IsMatch() 时：

**不要使用 @ 前缀：**不要使用 C# 逐字字符串前缀

// BAD: @ prefix not supported
RegEx.IsMatch(Expression, @"FILTER\s*\(\s*ALL")

// GOOD: Standard escaping
RegEx.IsMatch(Expression, "FILTER\\s*\\(\\s*ALL")

**不要使用 RegexOptions 参数：**TE 不支持 options 参数

// BAD: RegexOptions not supported
RegEx.IsMatch(Name, "^DATE$", RegexOptions.IgnoreCase)

// GOOD: Use inline flag or pattern only
RegEx.IsMatch(Name, "(?i)^DATE$")
RegEx.IsMatch(Name, "^(DATE|date|Date)$")

正确的范围名称

使用 TOM 枚举中的准确范围名称。常见错误：

错误	正确
Role	ModelRole
Member	ModelRoleMember
Expression	NamedExpression
DataSource	ProviderDataSource 或 StructuredDataSource

注意：Column 是有效的向后兼容别名，对应 DataColumn, CalculatedColumn, CalculatedTableColumn。

验证脚本

使用验证脚本检查并修复 TE 兼容性问题：

# Check for issues
python scripts/validate_rules.py rules.json

# Auto-fix issues (CRLF, remove nulls, remove _comment)
python scripts/validate_rules.py --fix rules.json

脚本会检查：

• 换行符（CRLF）
• 不含 _comment 字段
• 可选字段不含 null 值
• 有效的范围名称
• 表达式语法警告

关于 BPA 规则

• BPA 规则为 Power BI 和 Fabric 中的语义模型定义自动化 QA/QC 测试
• BPA 规则适用于 Tabular Editor 2、3、CLI 或 Fabric 笔记本
• 规则表达式使用 Tabular Editor 的 C# 或 Fabric 笔记本的 Python 编写
• 使用 Tabular Editor 定义和使用 BPA 规则更佳，因为规则可供用户采取行动、忽略或修复，并且已集成到 IDE 中

文件位置

BPA 规则可以存在于多个位置（按优先级顺序评估）：

位置	路径 / 来源	描述
内置最佳实践	TE3 内部	Tabular Editor 3 随附的默认规则
URL	任何有效的 URL（例如，https://raw.githubusercontent.com/TabularEditor/BestPracticeRules/master/BPARules-standard.json）	从网络加载的远程规则集合
当前模型中的规则	见下文	嵌入模型元数据中的规则
本地用户规则	%LocalAppData%\TabularEditor3\BPARules.json	Windows 上特定于用户的规则
本地计算机规则	%ProgramData%\TabularEditor3\BPARules.json	适用于所有用户的计算机范围规则

有关内置规则 ID（TE3 中的 27 条规则）、模型嵌入规则格式、跨平台文件访问以及所有文件位置的详细信息，请参阅 references/te-compatibility.md。

快速参考

有关规则 JSON 结构、有效的范围值、严重性级别、兼容性级别和类别前缀，请参阅 references/quick-reference.md。

有关表达式语法（Dynamic LINQ、TOM 属性、字符串／布尔值／集合检查、Tokenize()、DependsOn、ReferencedBy），请参阅 references/expression-syntax.md。

TMDL 注释

可以通过注释将 BPA 规则嵌入 TMDL 文件：

annotation BestPracticeAnalyzer = [{ "ID": "...", ... }]
annotation BestPracticeAnalyzer_IgnoreRules = {"RuleIDs":["RULE1","RULE2"]}
annotation BestPracticeAnalyzer_ExternalRuleFiles = ["https://..."]

有关完整的注释模式，请参阅 references/tmdl-annotations.md。

工作流

推荐：交互式规则生成

为获得最佳效果，请遵循上文的主要工作流：交互式问答探索。通过 AskUserQuestion 迭代收集上下文、调查模型，然后生成有针对性的规则。

创建单条规则（直接创建）

当用户请求特定规则，且无需完整探索时：

1. 确定要强制执行的最佳实践
2. 确定合适的 Scope
3. 编写用于检测违规的 Expression
4. 可选编写用于自动修复的 FixExpression
5. 使用示例模型进行测试
6. 将规则添加到规则集合中

改进现有规则

1. 了解当前规则的意图
2. 找出误报或遗漏的情况
3. 优化 Expression 逻辑
4. 确认 FixExpression 不会造成副作用
5. 进行全面测试

其他资源

参考文件

如需详细的语法和模式，请参阅：

• references/model-investigation.md - 通过 Fabric CLI 或本地 .bim/.tmdl 文件调查模型；指导用户另存为 PBIP；模型分析清单
• references/te-compatibility.md - Tabular Editor 兼容性（CRLF、文件路径、JSON 格式、正则表达式、范围名称、验证、内置规则、文件位置、跨平台访问）
• references/quick-reference.md - 规则 JSON 结构、有效范围、严重性级别、兼容性级别、类别前缀、表达式语法概述
• schema/bparules-schema.json - 用于验证 BPA 规则文件的 JSON Schema（Draft-07）（临时位置）
• references/rule-schema.md - BPA 规则字段说明（便于阅读）
• references/expression-syntax.md - Dynamic LINQ 表达式语法、TOM 属性、Tokenize()、DependsOn、ReferencedBy
• references/tmdl-annotations.md - TMDL 格式中的 BPA 注释

示例文件

examples/ 中的可用示例：

• examples/comprehensive-rules.json - 涵盖所有类别的 30 多条可用于生产环境的规则
• examples/model-with-bpa-annotations.tmdl - 展示所有注释模式的 TMDL 文件

脚本

实用脚本：

• /scripts/bpa_rules_audit.py - 全面审计所有来源（内置、URL、模型、用户、计算机）的 BPA 规则。支持 Windows、WSL 和通过 Parallels 运行的 macOS。输出 ASCII 报告和 JSON 导出文件。
• scripts/validate_rules.py - 验证 BPA 规则 JSON 文件是否符合架构要求

审计脚本用法：

# Basic audit
python scripts/bpa_rules_audit.py /path/to/model

# Export to JSON
python scripts/bpa_rules_audit.py /path/to/model --json output.json

# Quiet mode (summary only)
python scripts/bpa_rules_audit.py /path/to/model --quiet

相关命令

• /suggest-rule - 根据描述生成 BPA 规则

相关 Agent

• bpa-expression-helper——调试和改进 BPA 表达式

获取文档

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

外部参考资料

• Tabular Editor BPA 入门指南
• Tabular Editor BPA 视图
• BPA 示例规则表达式
• TabularEditor BPA 源代码
• BPA 规则仓库
• TabularEditor 文档仓库
• Power BI 语义模型检查清单

规则示例

没有描述的度量值

{
  "ID": "META_MEASURE_NO_DESCRIPTION",
  "Name": "Measure has no description",
  "Category": "Metadata",
  "Description": "All measures should have descriptions for documentation.",
  "Severity": 2,
  "Scope": "Measure",
  "Expression": "string.IsNullOrWhitespace(Description)"
}

已隐藏的未使用列

{
  "ID": "PERF_UNUSED_HIDDEN_COLUMN",
  "Name": "Remove hidden columns not used",
  "Category": "Performance",
  "Description": "Hidden columns with no references waste memory.",
  "Severity": 3,
  "Scope": "Column",
  "Expression": "IsHidden and ReferencedBy.Count = 0 and not UsedInRelationships.Any()",
  "FixExpression": "Delete()"
}