@guandata/tableau-migration 使用说明

把 Tableau 工作簿(.twb / .twbx)迁移到观远BI 的工具包。你拿到的是一个 自助套件:工具做已验证的自动翻译,你环境里的 AI Agent 负责编排和 兜底,你只在少数关键节点做决定。全程不需要联系工具作者。

0. 这个包里有什么

| 组件 | 作用 | |---|---| | tableau-migration tableau 子命令 | 工作簿检查、迁移评估(assess)、打包数据提取 | | tableau-migration sail-bi 子命令 | 已验证的翻译链:Tableau → Shards 中间层 → 观远迁移工程 → 发布编排 | | tableau-migration skill | 给 AI Agent 读的完整迁移手册(七阶段流程 + 故障处置) | | tableau-migration 命令 | doctor 环境自检、install-skill 一键装 skill |

工作原理一句话:确定性翻译器把 Tableau 结构翻成观远资产 (数据集 + 卡片 + 页面),AI Agent 按 skill 手册驱动全流程,翻不了的 项目显式告诉你并给出处置建议——绝不静默产出错误数字。

1. 前置条件

• 一个 AI Agent 工具:Claude Code / Codex / Cursor 任一(skill 会被 安装到 ~/.agents/skills,以上工具都会自动读取);
• Node.js ≥ 14 与 npm;
• 观远BI 账号,权限要求见 §5;
• 观远 CLI 六件套:npm install -g @guandata/guanskill && guanskill install-skill;
• Hyper 原生辅助程序随包分发:默认读取、表结构检查和无损 CSV 导出无需 Python。 引擎 hyperd 0.0.26479 不随包分发;第一次实际读取 .hyper 时从 Tableau 官方 下载固定版本 wheel,校验 SHA256、提取运行时并确认版本后缓存。wheel 只是 ZIP, 不安装 Python 包。macOS ARM64/x64、Linux x64、Windows x64 支持 Hyper; Linux ARM64 仅支持工作簿检查及 Excel/CSV,没有官方 Hyper 引擎。
• 可选:Python + tableauhyperapi:仅显式 --hyper-python 旧后端,或 replace-hyper-table-csv / apply-shards-data 的 Hyper 表写回需要。
• 可选:Tableau Desktop(用于结果对照截图,以及直连数据源的 数据导出路线 B)。

2. 安装与自检

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

npm install -g @guandata/tableau-migration
tableau-migration tableau --help
tableau-migration sail-bi -version

装完自检:

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

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

doctor 逐项检查二进制、skill、观远套件、原生 Hyper 辅助程序和引擎缓存完整性,并打印观远 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 —— 开跑前先 tableau-migration platforms 看当前平台是不是 [已内置](tableau-migration doctor 现在也会查这一项) (sail-bi 通过 cgo 链接 DuckDB,不能纯 Go 交叉编译)。

3. 快速上手(你只需要对 AI 说话)

打开你的 AI Agent(如 Claude Code),直接说:

评估这个 Tableau 工作簿能否迁移到观远:/path/to/我的报表.twbx

Agent 会自动调用 tableau-migration skill,产出一份评估报告 (assess.md):规模、红黄绿分级、数据源分类、需要你决策的清单。

确认范围后继续:

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

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

S1 评估 ──► 【决定 1】迁移范围:哪些仪表板首批/后批/放弃
S2 数据 ──► 【决定 2】直连数据源走哪条路线(见下)
S3 转换 → S4 验证 → S5 出计划(全自动,产物可审计)
S6 发布 ──► 【决定 3】确认在线发布清单(建什么数据集/页面、放哪个目录)
S7 核对 ──► 交付报告(截图 + 数值抽查 + 降级清单)

直连数据源三路线(工作簿连数据库而非内嵌数据时,Agent 会带着 评估出的连接信息和列结构与你商量):

| 路线 | 适合 | 你要做的 | |---|---|---| | A 观远直连重建(推荐) | 观远能连到同一个库 | 在观远侧录入数据库账号(凭据不经过 AI) | | B Desktop 导出 | 你有 Tableau Desktop | 按指引导出 Extract/CSV | | C 旁路 SQL 导出 | 你能用任意工具跑 SQL | 执行 Agent 生成的导出 SQL,把 CSV 放进指定目录 |

5. 观远账号权限要求

| 权限 | 必需性 | 说明 | |---|---|---| | 数据集创建/导入 | 必需 | guands 建数据集 | | 页面/卡片发布 | 必需 | guanvis 发布 | | SuperApp 应用发布 | 可选 | 没有也能迁:工具自动改用资产内联模式(已实测,含美国地图卡);有此权限时多页迁移的卡片体积更优 |

6. 如何验收结果

• 每次迁移产出 migration-report.md:每个页面 成功/降级/跳过 + 原因;
• 跳过不是失败:例如 R/Python 外部计算、个别无对应卡型的组件, 会显式列出并给出人工处置建议;
• 数值验收:报告含关键指标与源数据的对照;你也可以让 Agent "抽查 <页面> 的 <指标> 与 Tableau 中的数字对照";
• 每一步的中间产物都在迁移工作区目录里,可中断、可恢复、可复核。

7. 常见问题

| 问题 | 处置 | |---|---| | doctor 有红项 | 按红项后面的命令逐个修;全绿再开始 | | Hyper 首次下载失败 / 缓存损坏 | tableau-migration tableau hyper status 查看状态,联网后 tableau-migration tableau hyper install 重试;不跳过 SHA256 校验 | | 发布时 SuperApp 403 | 你的账号没有应用发布权限;告诉 Agent"用 inline 模式",或找管理员开权限 | | 大数据量 CSV 上传超时 | 先设 GUANCLI_UPLOAD_TIMEOUT=<秒> 调大上传超时重试;仍失败让 Agent 分块导入(首块建数据集,其余追加);或走直连路线 A 数据不落地 | | 页面发布了但有的卡片没出现 | 看报告的降级清单——通常是该组件在评估时已标黄/红并说明了原因 | | 数字对不上 | 先核对口径(时区/货币/筛选器默认值/数据快照时点),仍不符则把最小复现发给工具提供方 | | .twb 提示"外部文件" | .twb 不含数据;提供数据文件原件,或在 Desktop 里另存为 .twbx |

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

• 自动覆盖:常见图型、计算字段(约 180 函数)、FIXED LOD、表计算、 筛选器/参数/动作、仪表板布局、故事;
• 有条件(会降级或换实现):INCLUDE/EXCLUDE LOD、非中国行政区地图、 RAWSQL、递归 PREVIOUS_VALUE;
• 需人工决策:R/Python 外部计算、Tableau Server 发布数据源、行级权限 方案。评估阶段会把这些逐项列给你,不会开工后才发现。

Hyper 运行时与源码构建

# 离线前预下载;安装包或 doctor 不会自行下载引擎
tableau-migration tableau hyper install
# JSON 状态,只读且不联网
tableau-migration tableau hyper status

默认缓存位于 os.UserCacheDir()/guandata/hyper/<版本>/<平台>; TABLEAU_HYPER_CACHE_DIR 可指定缓存根目录。每次使用验证缓存文件 SHA256; 并发安装使用进程退出时释放的文件锁,安装成功前不暴露临时目录。 下载失败不会回退 Python。完整缓存可复制到离线机器的同平台目录。

构建迁移包需 Rust >= 1.88、protoc 和各目标的 Rust 标准库/链接器。 辅助程序的 Cargo.lock 与 Hyper API Git 提交固定并纳入源码控制。 默认 macOS ARM64 + Windows x64 构建在 macOS 还需:

rustup target add aarch64-apple-darwin x86_64-pc-windows-gnu
# x86_64-w64-mingw32-gcc 必须可用

从源码直接运行 Go CLI 时,先构建 tableau/hyper-helper,设置 TABLEAU_HYPER_HELPER 为其 target/release/tableau-hyper 绝对路径。 npm 启动器固定使用本包的 helper,不查 PATH 或其他迁移包。 Rust helper 保留 NULL/空字符串和浮点精度,不会使用默认 COPY CSV 导出。 Binary、geography、interval、array 等尚未验证的类型明确报告 UNSUPPORTED_TYPE。