Cwtwb

cwtwb

Tableau 工作簿工程，用于可复现地生成、验证和迁移 .twb / .twbx。

cwtwb 是一个 Python 工具包和模型上下文协议（MCP）服务，可通过代码或 Agent 工具调用构建 Tableau Desktop 工作簿。

它旨在作为一个工作簿工程层，而非对话式分析 Agent。重点在于本地工作流、脚本和 CI 中的可复现性、可检查性和安全自动化。

设计工作流参考

Agent 设计工作流和 design_advisor 技能参考了 Adam Mico 的 adammico-lab Tableau 工作流技能， 尤其是 Tableau Dashboard Blueprint 中从设计规范构建的方案。 cwtwb 独立地将这些理念应用于可复现的 .twb / .twbx 创作；它不依赖、不捆绑，也不复制 adammico-lab 的代码或技能 内容。cwtwb 与 Adam Mico、Salesforce 或 Tableau 均无关联。

cwtwb 中的 cw 源自 Cooper Wenhua。

作者： Cooper Wenhua <[email protected]>

网站 · 源代码 · 更新日志

Star 历史

试用示例工作流 · 阅读指南

快速开始

安装

pip install cwtwb

如果你还想使用捆绑的 Hyper 示例：

pip install "cwtwb[examples]"

如果你需要进行云端验证（上传到 Tableau Cloud/Server）：

pip install "cwtwb[validate]"

作为 MCP 服务运行

uvx cwtwb

上面的简短形式仍是最简单的选项，也是此仓库中展示的默认配置。cwtwb 是一个智能入口：在交互式终端中不带参数启动时，它会显示 CLI 帮助；由 MCP 客户端通过 stdio 启动时，它会运行服务。

使用相同的命令将服务添加到 MCP 客户端。例如：

{
  "mcpServers": {
    "cwtwb": {
      "command": "uvx",
      "args": ["cwtwb"]
    }
  }
}

对于 Claude Code：

claude mcp add cwtwb -- uvx cwtwb

对于 VSCode，在工作区或用户级 mcp.json 中添加 cwtwb，并将 uvx cwtwb 用作命令。

如果你更喜欢显式指定脚本名称，也可以使用以下等效的启动方式：

uvx cwtwb mcp
uvx --from cwtwb cwtwb-mcp
python -m cwtwb.mcp_server

作为 CLI 使用

同一个软件包还提供一流的命令行工作流，适用于需要直接操作文件而非调用 MCP 工具的人类用户、脚本、CI 和 Agent。

cwtwb --help
cwtwb doctor
cwtwb status --json
cwtwb inspect workbook.twb --json
cwtwb validate workbook.twb
cwtwb analyze workbook.twb --json
cwtwb run examples/specs/basic_cli.yaml

常见的写入命令默认要求显式指定输出路径：

cwtwb create --out output/base.twb
cwtwb chart add output/base.twb --worksheet "Sales by Category" --mark Bar --rows Category --columns "SUM(Sales)" --out output/chart.twb
cwtwb dashboard add output/chart.twb --name Overview --worksheets "Sales by Category" --out output/dashboard.twb

仅当你确实想覆盖输入工作簿时才使用 --in-place；仅当需要替换现有输出文件时才使用 --force。

在不同格式之间转换工作簿

convert 会根据文件扩展名识别 TWB、TWBX、YAML 和 JSON。它不需要 Gallery、模板或活动的编辑器会话：

cwtwb convert input.twbx --out workbook.yaml
cwtwb convert workbook.yaml --out workbook.json
cwtwb convert workbook.json --out rebuilt.twbx
cwtwb convert input.twbx --out unpacked.twb

cwtwb export input.twb --out workbook.yaml 是一个别名。原生定义也可以通过 cwtwb run workbook.yaml --out rebuilt.twb 使用。现有自动化规范仍保持原有行为。除非指定 --force，否则不会覆盖输出；转换绝不会覆盖输入文件。

Python：from cwtwb import convert_workbook，然后调用 convert_workbook("input.twbx", "workbook.yaml")。MCP 提供相同的无状态 convert_workbook(input_path, output_path, force=False) 工具。

带版本号的 cwtwb-native 格式目前表示 原生 XML 树： document.root 包含 tag、attributes、text、有序的 children 和 tail；注释、处理指令、命名空间、缩略图和未知元素都会保留。可编辑 calculation.attributes.formula 中的公式，以及区域属性中的布局几何信息。XML 属性值仍为字符串。这是一种详细的结构化格式，尚不是简化的语义工作簿 DSL；我们不声称已理解或可安全编辑 Tableau 的所有功能。 转换会绕过 TWBEditor 清理流程，也不会注入生成的注释。不保证 XML 声明写法、CDATA 写法、命名空间前缀和 ZIP 元数据逐字节不变。未知节点会保留，但不会被解释。

二进制资源会复制到 <output-name>.assets/，定义文件中会记录相对路径和 SHA-256 哈希。请将定义文件与此目录放在一起。解包后的 TWB 还会生成一个 <output-name>.resources.json 配套文件，以便保留未被引用的包内资源，供之后重新打包。必要时会重新定位文件引用；远程数据库连接仍保持远程。独立 TWB 的资源发现目前涵盖 Hyper/CSV/Excel 连接和位图区域；不会自动发现自定义扩展引用的任意外部文件。TWBX 转换会保留所有捆绑的资源文件，包括扩展名未知的文件。

已知的外部资源缺失时，文本输出会显示警告，TWBX 打包会被阻止。重复键、未知文档属性/版本、缺失或已更改的资源文件、不安全的归档路径、包含多个 TWB 的归档，以及包含 DTD 的 XML 都会明确报错。刻意更改资源后，请更新其记录的哈希。替换输出时不会清理资源目录。

转换会检查 XML 语法和资源完整性，但不会检查 Tableau 计算、字段引用语义、Desktop 加载、渲染或交互功能。请另行使用现有的验证命令和 Tableau 运行时检查。对于原生定义，run --validate 会被有意拒绝，以免让人误以为转换时执行了这些检查。

MCP 客户端稳定性

当 cwtwb 作为 MCP 服务连接时，Agent 应通过客户端直接调用其公开的 MCP 工具。不要运行 mcp call cwtwb ...、mcp list-tools cwtwb 或 gh api .../mcp/... 等 shell 命令；这些命令不属于 cwtwb，通常也无法在常规的 Claude、Codex、Cursor 或 VSCode 环境中使用。

如果 Agent 看不到 create_workbook、add_worksheet 或 save_workbook 等工具，请重启或重新连接 MCP 客户端，并检查服务器配置。清除 uv 缓存只会刷新已安装的软件包，无法修复过期的客户端工具列表。

使用现有 .twb 作为视觉参考时，Agent 不得将 Tableau XML 列实例标记复制到图表输入中。[sum:Sales:qk]、[none:Category:nk]、[mn:Order Date:ok] 或 [federated.xxx].[sum:Profit:qk] 等值都是生成的内部标记。请改用面向用户的表达式，例如 Sales、SUM(Sales)、Category 或 MONTH(Order Date)。

供 Agent 使用的实用资源：

cwtwb://tool-surface
cwtwb://skills/index
cwtwb://skills/data_quality
cwtwb://skills/design_advisor
cwtwb://skills/metric_blueprint
cwtwb://skills/dashboard_designer
cwtwb://skills/quality_review
cwtwb://skills/documentation
file://docs/tableau_all_functions.json

也提供了常见猜测 URI（例如 cwtwb://docs/manual-editing）的兼容别名，但新的提示词应优先使用 cwtwb://tool-surface 和 cwtwb://skills/index。

有关特定客户端的详细信息和完整参考，请参阅 https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md。

仪表板布局文件

现在可以使用相同的声明式 DSL，以 JSON 或 YAML 编写自定义仪表板布局。对于 Agent 工作流，请先生成布局文件，然后将该文件路径传递给 add_dashboard(layout=...)。

generate_layout_json("output/layout.json", layout_tree, ascii_preview)
generate_layout_yaml("output/layout.yaml", layout_tree, ascii_preview)

两种格式都支持相同的包装结构：

• layout_schema：规范的仪表板布局树
• _ascii_layout_preview：可选的人类／Agent 审阅辅助内容

可解释的仪表板图库

cwtwb 包含七个用于常见分析结构的图库模板。推荐结果基于明确的要求，并返回其评分、匹配原因和惩罚项；不会检查数据，也不会静默生成图表。

from cwtwb import DashboardRequirements, recommend_gallery_templates

recommendations = recommend_gallery_templates(
    DashboardRequirements(
        primary_intent="trend",
        has_temporal_data=True,
        kpi_count=2,
        chart_count=3,
        chart_types=("Line", "Bar"),
    )
)

调用 list_worksheets 后，请使用 materialize_gallery_layout(...) 或 MCP 工具 generate_gallery_layout 绑定确切的工作表名称。生成的结果使用与 add_dashboard 接受的相同规范 DSL。

计算安全性

add_calculated_field 会在编辑 XML 之前，对用作函数调用的标识符与随附的 Tableau 目录进行核对。例如，CHR(10) 会被拒绝，并提示使用 CHAR()。这是一项轻量级的函数名称检查，并非完整的 Tableau 解析器，也不能替代 Tableau Cloud 语义验证。

仅在目标 Tableau 函数较新、尚未收录在随附目录中时，才使用 validate_formula=False。可以使用 audit_calculated_fields() 检查现有工作簿。修复操作独立进行，并且默认采用 dry_run=True。

亮点

领域	提供的功能
工作簿创作	从模板或零开始生成 .twb / .twbx 文件；添加层级、集、丰富的动态标题和参数占位符
图表构建	构建条形图、折线图、饼图、地图、KPI、双轴、分层和有序多列数据表工作簿
表计算	编写计算寻址元数据、域补全、小计和嵌套表计算依赖项
仪表板操作	通过 Python 或 MCP 添加筛选、突出显示、URL、导航、参数和集操作
安全性	验证函数名称和计算字段角色，然后在发布前验证结构、Tableau XSD（2026.1/2026.2）和 REST API 语义
仪表板图库	为七种可解释布局排序，并将准确的工作表名称绑定到规范 DSL
云端验证	REST API 语法/语义验证 + 上传到 Tableau Cloud/Server，并可选择生成截图
迁移	通过明确的步骤将现有工作簿重新指向新的数据源
MCP 支持	通过 Claude、Cursor、VSCode 或其他 MCP 客户端驱动工作簿工作流

实际演示

此 GIF 展示了 MCP 工具逐步构建仪表板的流程。

架构

                            Interfaces
  ┌───────────────────────────────────────────────────────────────┐
  │  ┌──────────────────────────┐  ┌───────────────────────────┐  │
  │  │        MCP Server        │  │      Python Library       │  │
  │  │  tools_workbook          │  │  from cwtwb.twb_editor    │  │
  │  │  tools_validate          │  │  import TWBEditor         │  │
  │  │                          │  │                           │  │
  │  │                          │  │  editor.add_...()         │  │
  │  │                          │  │  editor.configure_...()   │  │
  │  │                          │  │  editor.validate_schema() │  │
  │  │  (Claude / Cursor /      │  │  editor.save(...)         │  │
  │  │   VSCode / Claude Code)  │  │                           │  │
  │  └─────────────┬────────────┘  └──────────────┬────────────┘  │
  │                └──────────────┬────────────────┘               │
  └─────────────────────────────  ┼  ─────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                          TWBEditor                            │
  │       ParametersMixin  ·  ConnectionsMixin                    │
  │       ChartsMixin      ·  DashboardsMixin                     │
  │       validate_schema()  ·  save()                            │
  └──────────┬──────────────────┬──────────────────┬─────────────┘
             ▼                  ▼                  ▼
  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────────┐
  │  Chart Builders  │  │  Dashboard   │  │  Analysis &          │
  │                  │  │  System      │  │  Migration           │
  │  Basic  DualAxis │  │              │  │                      │
  │  Pie    Text     │  │  layouts     │  │  migration.py        │
  │  Map    Recipes  │  │  actions     │  │  twb_analyzer.py     │
  │                  │  │  dependencies│  │  capability_registry │
  └────────┬─────────┘  └──────┬───────┘  └──────────┬───────────┘
           └───────────────────┼──────────────────────┘
                               ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                    Packaged References                        │
  │    empty_template.twb  ·  Superstore XLS/Hyper                │
  │    tableau_all_functions.json  ·  dataset profiles            │
  │    vendored Tableau TWB XSD schemas (2026.1 / 2026.2)         │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                     XML Engine  (lxml)                        │
  │    template.twb/.twbx  →  patch  →  validate  →  save        │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
                      output.twb  /  output.twbx
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │               Cloud Validation (optional)                    │
  │    validate_workbook_api → REST API semantic validation      │
  │    upload_workbook       → Tableau Cloud/Server publish      │
  │    screenshot_workbook   → capture view for visual check     │
  └───────────────────────────────────────────────────────────────┘

Mermaid 视图：

flowchart TD
    subgraph Interfaces
        MCP["MCP Server<br/>tools_workbook<br/>tools_validate"]
        PY["Python Library<br/>TWBEditor API"]
    end

    subgraph Editor["Core Editor"]
        TWB["TWBEditor<br/>parameters · connections<br/>charts · dashboards<br/>validate_schema · save"]
    end

    subgraph Builders["Workbook Systems"]
        CHARTS["Chart Builders<br/>basic · dual-axis<br/>pie · text · map · recipes"]
        DASH["Dashboard System<br/>layouts · actions<br/>dependencies"]
        ANALYSIS["Analysis & Migration<br/>migration.py<br/>twb_analyzer.py<br/>capability_registry"]
    end

    subgraph References["Packaged References"]
        REFS["empty_template.twb<br/>Superstore XLS/Hyper<br/>Tableau functions<br/>TWB XSD schemas"]
    end

    subgraph Engine["XML Engine"]
        XML["lxml patch pipeline<br/>template.twb/.twbx → patch → validate → save"]
    end

    subgraph Outputs
        OUT["output.twb / output.twbx"]
        CLOUD["Cloud Validation<br/>REST semantic validation<br/>upload · screenshot"]
    end

    MCP --> TWB
    PY --> TWB
    TWB --> CHARTS
    TWB --> DASH
    TWB --> ANALYSIS
    CHARTS --> XML
    DASH --> XML
    ANALYSIS --> XML
    REFS --> TWB
    REFS --> XML
    XML --> OUT
    OUT --> CLOUD

参考层与库一同打包，使 Agent 和脚本可以从已知良好的工作簿资源开始，解析 Tableau 计算语法，运行由 Hyper 支持的示例，并使用本地 XSD 架构进行验证，而无需依赖已检出的仓库。

Agent 架构

cwtwb 专为使用工具的 Agent 而设计，不只是用于直接调用 Python。MCP 服务为 Agent 提供小型的有状态工作簿编辑界面；技能资源则在每组工具调用之前提供特定阶段的 Tableau 指导。

Human or agent prompt
        |
        v
MCP server instructions
        |
        v
Skill resources
data_quality -> governance -> synthetic_data -> design_advisor -> metric_blueprint
-> calculation_builder -> chart_builder -> dashboard_designer -> formatting
-> validation -> quality_review -> documentation
        |
        v
Workbook tools
create/open -> list_fields -> add/configure -> layout -> save -> validate/upload
        |
        v
TWB/TWBX artifact + validation evidence

提示词说明要构建什么。技能说明如何出色地构建它。工具使工作簿更易检查且可重复操作。

打包的技能架构记录在 src/cwtwb/skills/README.md 中，其中包括工作流图，以及指导、显式修改和验证证据之间的边界。

能力边界

cwtwb 有意将其公共接口保持精简：

级别	含义
核心	用于常规 SDK 文档、示例和 MCP 工作流的稳定基础功能
高级	受支持的组合与交互模式，涉及更多组件
配方	通过 configure_chart_recipe 提供的展示模式，而不是为每种图表单独提供一个工具

当 Agent 需要确认某项图表或工作簿功能是否属于稳定接口时，请使用 list_capabilities 或 describe_capability。

设计决策

• MCP 服务采用有状态会话模型：打开或创建工作簿，通过显式工具对其进行修改，然后调用 save_workbook。
• 技能是特定阶段的操作指南，而非通用的提示词填充。
• save_workbook、validate_workbook、validate_workbook_api 和 upload_workbook 各司其职，避免 Agent 混淆写入、本地检查、语义验证和发布。
• 能力注册表明确界定产品边界，避免展示示例意外变成 API 承诺。

验证

cwtwb 提供四个级别的工作簿验证：

级别	说明	要求
1. 本地 XSD	根据官方 Tableau TWB XSD 架构验证（支持版本识别：2026.1 或 2026.2）	无（内置）
2. REST API 语法验证	通过 Tableau Cloud REST API 验证 XML 语法	Tableau 凭据 + Tableau Cloud 2026.2+
3. REST API 语义验证	无需发布即可进行完整的语义验证——.twb 的默认云端检查	Tableau 凭据 + Tableau Cloud 2026.2+
4. 上传 + 截图	发布到 Tableau Cloud/Server 并截取视图图像	Tableau 凭据 + pip install "cwtwb[validate]"

# Level 1 — Local XSD (in-memory, no save required)
result = editor.validate_schema()
print(result.to_text())

# Level 3 — REST API semantic validation
from cwtwb.validate.uploader import TableauUploader
uploader = TableauUploader(env_path="project/.env")
result = uploader.validate("output.twb", validation_level="semantic")

# Save with local XSD validation; REST API semantic validation also runs when .env is configured
editor.save("output.twb")

# MCP tools
validate_workbook(file_path="output.twb")                                       # Local XSD validation
validate_workbook_api(twb_path="output.twb", validation_level="semantic")        # Default cloud semantic validation, no publish
validate_workbook_api(twb_path="output.twb", env_path="project/.env")            # Runtime credentials
upload_workbook(twb_path="output.twb")                                          # Publish/openability evidence or TWBX validation
screenshot_workbook(workbook_id="...", view_name="Sheet 1")                     # Visual check after upload_workbook

常见问题

.twb 和 .twbx 有什么区别？

.twb 是工作簿 XML。.twbx 是打包版本，会将工作簿与提取数据和图像打包在一起。

validate_workbook 会保存文件吗？

不会。validate_workbook() 会对当前内存中的工作簿或现有的 .twb / .twbx 文件执行本地 XSD 验证，不会写入输出文件。写入文件的工具是 save_workbook()。

save() 会执行什么验证？

save() 会在替换最终输出文件之前自动执行本地 XSD 验证。对于 .twb 输出，如果已配置 Tableau 凭据且服务器支持，还会执行 REST API 语义验证。如果要直接请求 Tableau Cloud/Server 验证步骤，请使用 validate_workbook_api(..., validation_level="semantic")。

upload_workbook 有什么用途？

upload_workbook 会将 .twb 或 .twbx 发布到 Tableau Cloud/Server。只有在明确需要发布/可打开性证明、用于截图的工作簿 ID，或 .twbx 包验证时才使用它。对于默认的 .twb 云端语义检查，建议使用 validate_workbook_api，因为它不会发布或存储工作簿。需要运行 pip install "cwtwb[validate]"，并通过环境变量、显式指定的 env_path、TABLEAU_ENV_FILE 或工作簿旁的 .env 文件提供 Tableau 凭据。

如何设置 Tableau Cloud/Server 验证？

1. 安装：pip install "cwtwb[validate]"
2. 将 .env.example 复制为 .env
3. 填写 Tableau Cloud/Server PAT 凭据
4. 调用 save_workbook 写入 .twb 或 .twbx
5. 调用 validate_workbook_api 执行默认的 REST API 语义验证；只有在还需要发布/可打开性证明、截图或 .twbx 验证时，才调用 upload_workbook

凭据查找顺序为：显式指定的 env_path、环境变量、TABLEAU_ENV_FILE、工作簿同级目录下的 .env、当前工作目录下的 .env、cwtwb 项目中的 .env，最后是用户主目录下的 .env。对于一次性 MCP 调用，建议使用 env_path，而不是编辑 MCP 服务配置并重启服务。

如果验证报告缺少 tableauserverclient，请先调用 get_mcp_status。它会报告 MCP 进程使用的 Python 可执行文件、cwtwb 版本，以及 Tableau 客户端是否可导入，但不会暴露凭据。更改 env_path 仅在运行时生效，无需重启 MCP；在其他 Python 环境中安装依赖无法修复正在运行的服务，因此请将验证扩展安装到 get_mcp_status 报告的解释器中，并且只有在运行时或工具架构发生变化时才重新连接。

何时应使用 uvx cwtwb，何时应使用 python -m cwtwb.mcp_server？

常规 MCP 工作流使用 uvx cwtwb。无需 uvx 的本地测试则使用 python -m cwtwb.mcp_server。

为保持向后兼容，uvx --from cwtwb cwtwb-mcp、python -m cwtwb.server 和 python -m cwtwb.mcp 仍可使用。

完整指南在哪里？

请参阅在线指南。

文档

• 指南
• 更新日志