@guandata/powerbi-migration 使用说明

把 PowerBI 报表迁移到观远BI 的工具包。版本 0.4.1。支持范围和验收边界见下文,不承诺任意报表自动等价。 变更与验收边界见 CHANGELOG.md。 旧 .pbix、新 .pbix(PBIR 增强格式) 和 PBIP 工程目录(X.pbip + X.Report/ + X.SemanticModel/)都直接收, 不需要在 Desktop 里另存。你拿到的是一个自助套件: 工具做已验证的自动翻译(含大部分 DAX),你环境里的 AI Agent 负责编排、 翻译 DAX 长尾并逐个数值核对,你只在少数关键节点做决定。全程不需要 联系工具作者。

0. 这个包里有什么

| 组件 | 作用 | |---|---| | powerbi-migration powerbi 子命令 | 报表检查(零依赖读 .pbix / PBIR / PBIP)、迁移评估、模型/数据提取编排 | | vendor/pbix-extract | PBIX 数据模型解码器(随包同步的上游副本,含 DAX 原文导出) | | powerbi-migration skill | 给 AI Agent 读的完整迁移手册(含 DAX AI 翻译闭环协议) | | powerbi-migration 命令 | doctor 环境自检、install-skill 一键装 skill |

与 Tableau 包的关键差异:PowerBI 的度量(DAX)有一部分必然需要 AI 逐个翻译——这不是缺陷而是标准流程:工具导出无法自动翻译的度量工单, AI 翻成 SQL 后重新转换,每一个都要做数值核对才允许发布。 历史官方样例的转换覆盖统计只说明当时的样例范围,不代表任意报表数值正确。 本版本以 AdventureWorks Sales 的 Service 实测基准核对日期筛选、 Customers % 与 Date Role 三种日期关系,每个报表仍需按实际筛选数值验收。

1. 前置条件

• 一个 AI Agent 工具:Claude Code / Codex / Cursor 任一;
• Node.js ≥ 14 与 npm;
• Python ≤ 3.12(硬要求:PBIX 数据模型解码库 pbixray 的 C 扩展 不支持 3.13+;工具会给出用 uv 建隔离环境的精确命令,不动系统 Python);
• 观远BI 账号 + 观远 CLI 六件套 (npm install -g @guandata/guanskill && guanskill install-skill);
• sail-bi 命令:本包已内置(binaries/,与 tableau-migration 包 各自使用包内制品,多包共存无冲突);
• 可选:PowerBI Desktop(数值核对基线)。

2. 安装与自检

每个迁移包只注册自己的 powerbi-migration 入口,可以一起安装或分别安装,无需 --force。 内部工具通过子命令调用,始终使用本包 binaries/<工具>-<平台>-<架构>[.exe],不依赖 PATH 上的同名工具或其他迁移包。

npm install -g @guandata/powerbi-migration
powerbi-migration powerbi --help
powerbi-migration sail-bi --help

装完自检:

powerbi-migration install-skill     # 把 skill 装进 ~/.agents/skills(全局安装时会自动执行一次)
powerbi-migration doctor            # 环境自检,期望全绿

每次 npm run build 之后都要重跑 install-skill —— build 只更新包内 skills/,不会刷新 ~/.agents/skills/ 里 agent 真正读的那份;两份漂开时 agent 会拿着旧手册跑新二进制。doctor 会逐字节比对这两份并在不一致时报红。

doctor 逐项检查二进制、skill、观远套件、Python,并打印观远 CLI 的版本号 ——全局 link 的二进制不随源码自动更新,版本号是发现"改了没生效"的唯一线索。 它会核对本包产物来源和文件完整性;PATH 上其他版本的 sail-bi 不参与调用。红项会给出修复命令。

观远连接:guancli auth login(支持账密 / uIdToken / PAT),多环境用 guancli auth use <环境名> 切换。

内置平台

包内 binaries/ 按 <工具>-<平台>-<架构> 命名,一个平台只有在两个二进制 都齐时才会被打进包里——只有一半的平台会在构建时被剔除,免得命令装上了却在 流程中段失败。当前构建默认只出 darwin-arm64 与 win32-x64(见 npm/lib/build-support.js 的 DEFAULT_PLATFORM_KEYS);其他平台需显式构建。构建可使用纯 Go 降级路径, 实际能力以包内 CAPABILITIES.json 与 doctor 输出为准;完整本地执行能力 仍取决于 DuckDB/C 工具链。未内置制品的平台会明确报错。 Windows 制品经过交叉编译与指纹校验,本版本验收不包含 Windows 实机执行。

包内 skill 包含所引用的共享设计和 Tableau 操作手册,安装后无需源码仓库。 doctor、构建检查和预发布检查会验证这些文档的路径与指纹。

3. 快速上手

对你的 AI Agent 说:

评估这个 PowerBI 报表能否迁移到观远:/path/to/我的报表.pbix

首次评估若提示"未提供 model.json",Agent 会先引导完成一次模型提取 (需要 §1 的 Python 环境),再给出完整评估:页面/视觉清点、 度量三色预分层(自动 / 自动但需抽查 / 预计进 AI 翻译)、 数据模式判定。之后:

按评估结果迁移,目标环境 <guancli 环境名>,发布到 <目录名>

4. 流程与你的四个决定点

S1 评估 ──► 【决定 1】迁移范围 + 自定义视觉的占位接受度
S2 提取 ──► 【决定 2】数据路线:真实源重建(默认)或明确接受快照
S3 转换(自动,导出 DAX 工单)
S3.5 AI 翻译闭环 ──► 【决定 3】审阅 AI 翻译核对台账(每单:DAX ↔ SQL ↔ 数值判定)
S4 验证 → S5 出计划(自动)
S6 发布 ──► 【决定 4】确认在线发布清单
S7 核对 ──► 交付报告

数据路线说明:默认通过 powerbi sources plan 识别源、逐表选择直连或 ETL 重建,再比较源端与提取快照。M 原文作为重建依据,不承诺自动翻译 M。 源不可达时才与用户确认快照退路,记录数据时点及刷新限制。

Power BI Service 的接入目前是数值基准链路:powerbi reference queries 生成 DAX, reference fetch 经 executeQueries 取数,reference compare 对比迁移结果。 需要有权限的用户登录;它不包含 workspace 自动发现、在线下载报表、完整语义模型 抽取或增量同步。Service 报表仍需完整 PBIX/PBIP/模型数据作为转换输入。

5. 观远账号权限要求

与 Tableau 包相同:数据集创建/导入 + 页面发布必需;SuperApp 应用发布 可选(无则自动用资产内联模式)。

6. 如何验收结果

• migration-report.md:页面清单(成功/降级/跳过)+ DAX 翻译台账 (确定性 N / 机械化 M / AI 改写 K / 放弃 J,每个 AI 改写附核对记录);
• AI 改写的度量在发布前逐个做过数值核对(与相同数据时点、相同筛选的 PowerBI Service/Desktop 读数 对照;自洽检查不能替代源端核对),未核对的一律不发布、在报告标注;
• 已知口径差异会写明:BLANK 与 NULL 的显示差异、数据快照时点等。

7. 常见问题

| 问题 | 处置 | |---|---| | 提示 PBIR 新格式不支持 | 不应再出现:新 .pbix(PBIR)与 PBIP 工程目录已原生支持。仍报就是包内二进制过旧,升级本包 | | PBIP 工程取不到模型 | X.SemanticModel/.pbi/cache.abf 是 Desktop 本地缓存,常不在 git 里。在 Desktop 打开一次工程写出缓存,或直接提供 model.json | | Python 版本报错(3.13+) | 复制错误里的 uv 命令建 3.12 隔离环境 | | 提取失败(pbixray 解码异常) | 按 Agent 给出的降级阶梯:仅迁结构 → 逐表人工导出 | | DirectQuery 报表 | 包内无数据模型:在 Desktop 切成 Import 模式另存后重新评估(推荐),或只迁结构、数据在观远侧直连重建 | | 大表 CSV 上传超时 | 先设 GUANCLI_UPLOAD_TIMEOUT=<秒> 调大上传超时重试;仍失败让 Agent 分块导入(首块建数据集,其余追加);或数据走重建路线不落地 | | 自定义视觉(.pbiviz)没迁过来 | 属明示边界:无通用宿主,默认表格/文本占位;高价值视觉可让 Agent 在观远侧做等价实现 | | AI 翻译的度量数字存疑 | 报告里有该度量的核对台账(翻译依据 + 核对轴 + 双方数值);可要求 Agent 换一个切片再核对 |

8. 支持边界(如实告知)

• 自动覆盖:常见视觉类型、DAX 基础聚合/算术/逻辑层、CALCULATE 常见 形态、ALL 族清除、常用时间智能(YTD/同期)、RANKX、what-if 参数、 计算列(物化)、关系模型;
• AI 闭环处理:超出上述的复杂 DAX(嵌套 CALCULATE 链、EARLIER 等) ——逐单翻译、逐单核对、全程留痕;
• 明示不做:DirectQuery/复合模型直迁、.pbiviz 自定义视觉宿主、 Power Query M 自动翻译、行级安全自动搬迁。评估阶段全部提前列出。

页面出版双模式:custom 用整页 SDK 卡与卡片池取数;查询必须满足池卡表达 条件,越界查询按规则走实时 SQL。native 用观远原生卡绑定单表/ETL 宽表, 默认拒绝预计算快照;不支持的卡型或表达式需明确降级。两种模式都应按目标 BI 能力检查并在发布后验收。AdventureWorks 已在 bwu_20261022_verify 隔离资源验证 Spark SQL、日期多选、Date Role 切换和失败发布阻断;Service 基准为 2026-10-22 保存的真实结果,后续复测复用该基准,不宣称每次重新在线取数。

计算组评估:calculation-groups 仍保守标红,表示评估器尚未证明可以迁移。 先跑转换器,powerbi.dateRole 表示单选关系切换已转换;逐角色、逐日期范围核对 后才能接受。仅支持约束内的 SELECTEDMEASURE/USERELATIONSHIP 组合,不扩展 承诺到多选、复杂优先级、时间智能计算项或任意编辑交互。Date Role 在 Service 基准、本地执行器与 bwu Spark 之间已核对,且已验证目标页面保留日期选择后 切换 Order/Due/Ship 三种角色。其他报表和环境仍须单独验收。

AdventureWorks 的完整页面使用 -emit-mode custom 出计划已通过。native 检查明确 拒绝 3 个不能安全实时绑定的查询(日期角色参数、跨表聚合和无销售日期成员保留), 其余 7 个可绑定宽表。该拒绝是数值保护,不能用预计算或占位冒充完整迁移。

库存类报表新增受限的净正值 SKU 条件计数、单排序 RANK/ORDERBY 和视觉 ScopedEval 百分比支持,均需按实际筛选核对。库存分析样例的 custom 已核对;native 的完整交付 采用专项手工编排的原始事实分支、拆分卡和全局参数,不属于通用自动 native 能力。 跨事实或窗口表达式无法安全绑定时仍明确拒绝;matrix 的分组汇总行尚未复现。