2026-04-30beginner10 分钟

04｜cwprep 与 cwtwb 基础案例：先 Python，再 MCP

先用 Python 跑通底层接口，再用 MCP 让 AI 调用同一套能力，这是小白最稳的上手路径。

你将学到什么

为什么先学 Python 接口，而不是一上来只用提示词
如何跑通一个最小的 cwprep Python 案例
如何跑通一个最小的 cwtwb Python 案例
为什么 MCP 是“基于这些接口”的 AI 调用层

前置条件

已完成前两篇（Python/uv/IDE/Agent + MCP 基础配置）
可访问以下在线示例目录：

- cwprep examples： https://github.com/imgwho/cwprep/tree/main/examples - cwtwb examples： https://github.com/imgwho/cwtwb/tree/master/examples

先讲清楚：为什么 Python 接口是必要的

先跑 Python 接口的价值很直接：

更稳定：脚本能跑通，说明底层能力可用
更可控：你能精确控制输入、参数和输出路径
更好排错：失败时更容易定位是数据问题、参数问题还是环境问题
更可复用：后续可做模板、自动化、团队标准流程

一句话：MCP 不是另一套能力，它调用的是同一套底层接口。

Python 案例 A：cwprep（先做数据流）

建议先跑这个最小案例思路（对应 cwprep/examples/quick_start.py）：

from cwprep import TFLBuilder, TFLPackager

builder = TFLBuilder(flow_name="quick_start_demo")
conn = builder.add_connection(host="localhost", username="root", dbname="demo")
orders = builder.add_input_table("orders", "orders", conn)
builder.add_output_server("output", orders, "orders_datasource")

flow, display, meta = builder.build()
TFLPackager.save_tfl("./quick_start_demo.tfl", flow, display, meta)

如果你想看更完整的清洗案例，可以看 cwprep examples 下的：

demo_basic.py
demo_cleaning.py

预期结果：

生成 .tfl 或 .tflx 文件
能在 Tableau Prep 中打开

Python 案例 B：cwtwb（再做工作簿）

建议先跑一个最小工作簿案例（对应 cwtwb/examples/scripts/demo_connections.py）：

from cwtwb import create_workbook, set_excel_connection, add_worksheet, configure_chart, save_workbook

create_workbook()
set_excel_connection(filepath="Sample - Superstore.xls", sheet_name="Orders")
add_worksheet(worksheet_name="Sales by Category")
configure_chart(
    worksheet_name="Sales by Category",
    mark_type="bar",
    rows=["Category"],
    columns=["SUM(Sales)"],
)
save_workbook(output_path="sales_by_category.twb")

如果你想看稍微完整一点的布局案例，可看 cwtwb examples/scripts 下的：

demo_declarative_layout.py
demo_auto_layout4.py

预期结果：

生成 .twb 或 .twbx 文件
能在 Tableau Desktop 中打开

再讲 MCP：它基于同一套接口

当 Python 案例跑通后，再用 MCP 会更顺：

对业务同学更友好：可以直接用自然语言描述需求
对协作更高效：agent 可以直接调用工具完成动作
对排错更清晰：MCP 失败时，回到 Python 案例即可快速验证底层能力

MCP 案例：与上面一一对应

本篇建议先用 cwprep 做 MCP 验证，再做 cwtwb：

cwprep prompts： https://github.com/imgwho/cwprep/blob/main/examples/prompts.md
cwtwb prompts： https://github.com/imgwho/cwtwb/tree/master/examples/prompts

执行顺序建议：

从 cwprep prompts 里选一个最小案例
确认生成结果文件
从 cwtwb prompts 里选一个最小案例
确认工作簿输出

验证清单

Python 侧成功生成 .tfl/.tflx
Python 侧成功生成 .twb/.twbx
MCP 侧触发了真实工具调用（而不是纯文本建议）
你能解释这句话：Python 接口是基础，MCP 是调用方式

常见问题（小白版）

Python 能跑但 MCP 不能跑：通常是 MCP 配置或客户端重启问题
MCP 有结果但文件不对：先回到 Python 案例确认参数与数据
仍然不会配置：把报错贴给 AI agent，让它给你“下一步最小改动”