@guandata/powerbi-migration 使用说明

把 PowerBI 报表(.pbix)迁移到观远BI 的工具包。你拿到的是一个自助套件: 工具做已验证的自动翻译(含大部分 DAX),你环境里的 AI Agent 负责编排、 翻译 DAX 长尾并逐个数值核对,你只在少数关键节点做决定。全程不需要 联系工具作者。

0. 这个包里有什么

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

与 Tableau 包的关键差异:PowerBI 的度量(DAX)有一部分必然需要 AI 逐个翻译——这不是缺陷而是标准流程:工具导出无法自动翻译的度量工单, AI 翻成 SQL 后重新转换,每一个都要做数值核对才允许发布。 微软 7 个官方样例(234 个度量)实测:全部自动覆盖,0 个需要 AI; 真实企业报表的复杂度量会进入 AI 闭环,报告中全程可追溯。

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 -version

装完自检:

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);darwin-x64 / linux-x64 / linux-arm64 需要在有对应 C 交叉工具链的机器上重建(sail-bi 通过 cgo 链接 DuckDB,不能纯 Go 交叉编译)。 包的 os 字段允许在 linux 上安装,但没内置制品时每条命令都会以 该平台的制品未随包分发 退出 1 —— 开跑前先 powerbi-migration platforms 看当前平台是不是 [已内置](powerbi-migration doctor 现在也会查这一项) (sail-bi 通过 cgo 链接 DuckDB,不能纯 Go 交叉编译)。

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 的 Power Query(M)清洗逻辑没有可靠的机器 翻译——工具不假装能翻。两条路线:

| 路线 | 含义 | 适合 | |---|---|---| | 快照(默认) | 用提取出的数据快照建观远数据集 | 演示、一次性迁移、M 只做轻处理 | | 重建 | AI 读 M 原文,在观远侧用直连/ETL 重建数据管道 | 需要持续刷新;源头数据库可达 |

5. 观远账号权限要求

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

6. 如何验收结果

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

7. 常见问题

| 问题 | 处置 | |---|---| | 提示 PBIR 新格式不支持 | 在 PowerBI Desktop 关闭"增强型报表格式"预览特性后另存 .pbix | | Python 版本报错(3.13+) | 复制错误里的 uv 命令建 3.12 隔离环境 | | 提取失败(pbixray 解码异常) | 按 Agent 给出的降级阶梯:Desktop 另存旧格式 → 仅迁结构 → 逐表人工导出 | | 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 卡,保真高, 需目标 BI 开"高级 SQL 查询"开关)与 native(观远原生卡,可在观远内 编辑,数据为物化快照)均可用,emit 默认 both 两者都出,发布时择一或 并存(native 版页面带 native 后缀)。地图等个别组件在 native 模式下 以单组件 SDK 卡承载。