CooperFryar/tableau-vizql-bridge

# tableau-vizql-bridge **以编程方式创作 Tableau Cloud —— 无需官方 API。** 本项目完全通过代码构建 Tableau Cloud 的工作表和仪表板（图表、筛选器、 计算字段、参数、分析对象、格式）， 其原理是驱动 Tableau Cloud 自身的**内部 VizQL 命令协议**。它会在实时浏览器会话中 注入一个微型调度器，并发送与你在点击和拖拽时创作 UI 所触发的完全相同的 `tabdoc`/`tabsrv` 网络命令。 无需在关键路径上进行屏幕抓取，也没有脆弱的像素自动化 —— 直接调用 引擎。约 80 个类型化原语覆盖了大部分创作功能面。  *上方的每个图表、布局、筛选器组件以及交叉筛选连线都是通过代码创作的 —— 全程零点击。* ## 功能 - **构建图表：** 将字段拖放到任何功能区或标记编码上，设置标记类型， 更改聚合方式和日期部分，离散/连续切换。 - **数据建模：** 计算字段（包括 LOD）、组、集、数据桶、参数。 - **筛选：** 分类、范围、前 N 个、通配符、条件、相对日期、 上下文，以及应用于工作表的范围。 - **分析：** 参考/趋势线、参考区间、箱线图、平均值、中位数。 - **格式化：** 坐标轴、数字格式、特定值颜色、调色板、排序、双轴、 总计/小计。 - **组合仪表板：** 添加工作表、布局容器和对象，筛选 / 高亮 / URL / 跳转到工作表 / 参数操作，用作筛选器。 完整的可调用接口记录在 **[`API_REFERENCE.md`](API_REFERENCE.md)** 中。 ## 图库 以下所有内容均通过代码经由 VizQL 桥接驱动 Tableau Cloud 生成： | | | |---|---| |  |  | | **地理仪表板** - 带有顺序色标的填充地图。 | **堆叠条形图** - 按类别划分的销售额，按年份着色。 | |  |  | | **条形图 + 实时筛选器** - 带有多个快速筛选卡片的排名类别。 | **组合仪表板** - 四个工作表、容器和交叉筛选器。 | ## 结合 Claude 使用（推荐） 最简单的使用方法是将其作为 [Claude Code](https://claude.com/claude-code) 插件。你只需用纯英文描述你的需求，Claude 就会将其构建出来。该 插件**会在首次运行时设置自己的环境**，因此你无需进行任何 Python 操作。 在 Claude Code 中： ``` /plugin marketplace add CooperFryar/tableau-vizql-bridge /plugin install tableau@tableau-vizql-bridge ``` 然后启动它（或者直接用纯英文向 Claude 提问）： ``` /tableau:start ``` 首次运行时，Claude 会安装一个私有环境，为你打开一个浏览器以 登录 Tableau Cloud 一次（不存储密码），然后询问你是想 继续打开现有的工作簿、新建一个，还是做其他事情。接下来只需 提问：*"构建一个按地区划分的销售额条形图"*，*"添加一个前 10 名的筛选器"*，*"构建 一个对其进行交叉筛选的仪表板"*。 **要求：** 已安装 [Claude Code](https://claude.com/claude-code) 和 Python 3.11+。 在 Claude Code CLI 和 IDE 扩展中运行（不支持 claude.ai 网页版）。其 底层的库也可以直接在 Python 中使用（参见下文的“作为 Python 库 使用”）。 ## 工作原理 三层架构（`tableau_interactor/cloud/vizql/`）： | 层级 | 文件 | 职责 | |---|---|---| | 网络桥接层 | `exec.py` + `dispatcher.js` | *根据特征*查找页面内调度器（可在代码压缩器轮换中存活）并运行 `send_command(page, ns, name, params)`。 | | 原语 | `api.py` | 约 80 个类型化函数。自动刷新 UI，自动清理对话框，类型化错误。通过显示名称引用字段；隐藏了编码方面的怪癖。 | | 方案 | `recipes.py` | 由原语组成的参数化图表构建器。 | 发现/扩展工具位于其旁边：`watch.py`（捕获请求/响应 + 调度器调用），`hunt.py`（定位调度器），`capture_drop.py`。 发现新命令的方法记录在 `PROTOCOL.md` 中。 ## 作为 Python 库使用（开发者） 如果你更倾向于通过代码而不是通过 Claude 来驱动它，请直接进行设置。 需要 Python ≥ 3.11 以及一个具有创作权限的 Tableau Cloud 账号。 ``` git clone https://github.com/CooperFryar/tableau-vizql-bridge cd tableau-vizql-bridge python -m venv .venv source .venv/bin/activate pip install -e . playwright install chromium cp .env.example .env # then fill in your pod URL (credentials optional) ``` ### 用法 **1. 启动持久化浏览器会话**（登录并保持打开状态；其他所有 操作均通过 CDP 连接到此会话）： ``` NODE_OPTIONS="--no-deprecation" python -m tableau_interactor.cloud.session ``` 一个 Chromium 窗口将打开并登录到 Tableau Cloud。在该窗口中 **打开或创建一个工作簿**，以便进入创作视图，然后让它保持运行。 **2. 通过脚本驱动它。** 标准形式如下： ``` import os os.environ["NODE_OPTIONS"] = "--no-deprecation" from tableau_interactor.cloud.vizql.connect import connect_to_workbook_page from tableau_interactor.cloud.vizql import exec as ex, api pw, page = connect_to_workbook_page() try: ex.inject_dispatcher(page) # one-time per session; idempotent api.close_open_dialogs(page) # start clean sheet = api.active_sheet_name(page) api.drop_field(page, "Ship Mode", "columns", sheet) api.drop_field(page, "Sales", "rows", sheet) api.drop_field(page, "Segment", "color", sheet) api.set_mark_type(page, "bar", sheet) print(api.viz_status(page)) # verify state programmatically finally: pw.stop() ``` 这就是四次网络调用，耗时约 2 秒。使用 venv 的 Python 运行它。 ## 配置 所有配置均通过 `.env` 进行（参见 `.env.example`）：`TABLEAU_CLOUD_URL`、`TABLEAU_EMAIL`、 `TABLEAU_PASSWORD`，以及可选的 `TABLEAU_CDP_URL`（默认为 `http://localhost:9222`）。 ## 状态与注意事项 - **逆向工程且无官方支持。** 它依赖于 Tableau Cloud 私有的 内部实现，可能会在任何版本中失效。调度器是根据特征定位的， 以增强对代码压缩器更改的适应性，但无任何保证。 - **已针对一个 Pod / 数据集（Superstore）进行验证。** 跨租户行为 未经测试 —— 预期在新环境中会捕获到一些 网络变体（`PROTOCOL.md` 解释了捕获工作流）。 - **已知的棘手问题** 在代码和 `PROTOCOL.md § 已知限制` 中有内联跟踪。 ## 作者与许可 由 **Cooper Fryar** 创建。基于 [MIT 许可证](LICENSE) 发布 - 可免费 使用和改编；请保留版权/归属声明。 Tableau 和 Tableau Cloud 是 Salesforce, Inc. 的商标。本项目是一个 独立的非官方实验项目，未隶属于 Salesforce/Tableau，也未获得其认可。

标签：Tableau, 云资产清单, 工程效率, 数据可视化, 特征检测, 网络调试, 自动化, 逆向工具, 逆向工程