@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;
• 可选:Python 3(仅当工作簿内嵌 .hyper/.tde 提取时需要,工具会在 需要时给出精确的安装命令。为什么需要:Hyper 是 Tableau 专有列存格式, 官方只提供 tableauhyperapi SDK(Python/Java/C++,含闭源原生库), 没有可打包的纯 Go 读取实现;不含 hyper 的工作簿全程零 Python);
• 可选: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、观远套件、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 —— 开跑前先 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 报 NO_PYTHON / MISSING_LIB | 复制错误里的 uv 命令执行(建隔离环境,不动系统 Python) | | 发布时 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 发布数据源、行级权限 方案。评估阶段会把这些逐项列给你,不会开工后才发现。