## 模块 3：Text2SQL 场景：用 Agent 玩转分支

这一模块会把场景收敛到一个经典的 Text2SQL 或数据库设计问题：为一个全新的 Todo App 设计数据库，并允许 Agent 并行探索多种方案，然后从中选出一个继续演进。

本模块需要你在 Jupyter Notebook 中完成（Notebook 会驱动 Agent 创建/管理分支，并在分支上运行 SQL）。

### 3.1 打开 Notebook

1. 点击 [VS Code](${LAB:HTTPS_REVERSE_PROXY_URL}?next=${LAB:"/vscode/?folder=/root/tidb-lab-branches"|urlencode} "VS Code") 打开 IDE。

   > [!TIP]
   > 出现提示时，请在弹窗中点击 `Yes, I trust the authors`（是的，我信任这些作者）。

2. 在左侧 `EXPLORER` 中打开：
   - `todo_branch_story.ipynb`
   - tidb_agent.py`（建议同时打开，便于对照 Agent 有哪些工具）
3. 打开 Notebook 后，点击右上角的 `Select Kernel`，选择 `Python Environments...`，并选中推荐的 `Python 3.11.x` 解释器。
4. 之后请严格按 Notebook 内的步骤执行（建议从上到下逐个 Cell 运行）。

   > [!TIP]
   > 建议你提前复制保存 `todo_branch_story.ipynb` 和 `tidb_agent.py` 的内容，方便在实验结束后仍可访问。

### 3.2 Storyline：三路并行 + 选路继续演进

在 `todo_branch_story.ipynb` 里，我们会围绕一个全新的 Todo App 做数据库设计探索。

**数据背景（Data Involved）**：

- `todos`：待办事项（例如标题、状态、截止时间、创建/更新时间等）
- `users`：用户信息（用于把 todo 归属/分配给用户）
- `extensions`：标签（tags）、清单项（checklist items）等

随后，你会完成以下故事线：

1. **Step 1：并行生成 3 种 Todo 存储方案（3 个分支）**
   - Agent 会创建 3 个分支：`todo_minimal`、`todo_tags`、`todo_checklists`
   - 每个分支代表一种不同建模思路，并会在分支里创建表、插入示例数据
2. **Step 1（检查与选择）：对比三个分支并选择一个作为“基线”**
   - Notebook 会展示每个分支的表与样例数据，便于你做取舍
3. **Step 2：从你选中的基线继续分叉，加上用户体系（2 个子分支）**
   - 以你选中的父分支为起点，再创建两个子分支：
     - `{base}_owners`：每个 todo 只有一个 owner（单人拥有）
     - `{base}_assignments`：todo 与用户多对多（可协作分配）
   - Agent 会在子分支里创建 `users` 表、建立外键/关联表，并插入示例数据
4. **Step 3：可视化分支树**
   - Notebook 会把当前集群里的分支 lineage 可视化出来，帮助你理解“从哪分、分到哪、最后选了哪条路”

### 3.3 你需要关注的核心代码（展示材料）

本实验的展示代码其中最核心的是：

- `tidb_agent.py`
  - 用 Strands Agents 把 TiDB 能力封装成工具：`create_branch` / `create_branch_from_display_name` / `run_sql_on_branch` 等
  - 关键点：对分支执行 SQL 时，必须走分支的连接信息，避免把 DDL/DML 误跑到默认分支
- `todo_branch_story.ipynb`
  - 用“提示词 + 工具调用”的方式驱动分支式 Schema 探索，而不是手写固定 SQL 流程