## 模块 3：确保智能体结构化数据的持久化

本模块为附加模块，旨在展示通过 TiDB Cloud CLI 为你的智能体快速开通专属 Starter 数据库集群是多么简单。虽然智能体通常偏好“本地优先”的轻量数据库方案，但实际上，小型、云原生、持久化数据库才是更优的选择——它相当于智能体的数据库层，“一次创建，随时可用，随处挂载”。

文件系统非常适合存储代码、构建产物和可恢复的工作区，而数据库则更适合持久化和查询结构化的状态。在本模块中，我们将借助 `ti db` 创建 TiDB Cloud Starter 实例，再结合 TiDB Cloud 文件系统，为 Hermes 提供完整的统一智能体存储层。

### 步骤 1：为你的智能体创建一个新的 Starter 集群

- 进入 **[终端 2](ssh://monitor1-ssh#2)**，执行以下命令，创建一个 Starter 集群，并新建名为 `sol` 的数据库，准备好 SQL 用户凭证，并为你的智能体生成数据库连接 URL。

> [!TIP]
> TiDB Cloud Starter 集群是无服务器的、兼容 MySQL 的数据库集群。善用 `ti` CLI 的 `--wait`、`--query` 和 `--output` 等参数能够大大简化自动化流程。多个命令步骤可组合为单个脚本，一站式编排。

```bash
# 创建 TiDB Cloud Starter 集群
read DB_CLUSTER_ID <<< "$(ti db create-db-cluster \
   --db-cluster-name hermes-data \
   --db-cluster-type starter \
   --region aws-${LAB:REGION_CODE} \
   --wait \
   --query "id" \
   --output text \
   )"

# 创建预定义角色的 SQL 用户 - admin、read_only、read_write
ti db create-db-sql-users \
   --db-cluster-id $DB_CLUSTER_ID \
   --region aws-${LAB:REGION_CODE}

# 为智能体创建数据库，库名为 ‘sol’
ti db execute-sql-statement \
   --db-cluster-id $DB_CLUSTER_ID \
   --sql "CREATE DATABASE sol" \
   --admin \
   --transport mysql \
   --region aws-${LAB:REGION_CODE}

# 生成给智能体用的数据库连接 URL
read DATABASE_URL <<< "$(ti db format-db-connection-string \
   --db-cluster-id $DB_CLUSTER_ID \
   --read-write \
   --database sol \
   --query "connection_string" \
   --output text \
   )"

# 将 DATABASE_URL 写入环境变量，供 hermes 使用
echo DATABASE_URL=$DATABASE_URL >> .hermes/.env
```

```output
{
  "cluster_id": "xxxxxxxxxxxxxx",
  "users": {
    "admin": {
...
    },
    "read_only": {
...
    },
    "read_write": {
...
    }
  }
}
{
  "fields": [],
  "rows": [],
  "row_count": 0,
  "transport": "mysql",
  "access_mode": "admin",
  "cluster_id": "xxxxxxxxxxxxxxx"
}
```

### 步骤 2：让智能体连接数据库

- 返回 **[终端 1](ssh://monitor1-ssh#1)**，启动 Hermes。

> [!NOTE]
> 为方便 Hermes 实验和排查问题，本实验特意降低了安全级别，DATABASE URL 中的密码 Hermes 可读取。

```bash
export HERMES_REDACT_SECRETS=false
hermes chat
```

- 再次检查环境变量，你应能看到新增的 `DATABASE_URL` 变量。

```text
执行 env
```

```output
...
- DATABASE_URL: mysql://XXXXXX.ti_rw:***@gateway01.${LAB:REGION_CODE}.prod.aws.tidbcloud.com:4000/sol?ssl-mode=VERIFY_IDENTITY
...
```

- 由于 Starter 数据库兼容 MySQL，智能体无需学习新技能——只需有 `DATABASE_URL` 即可直接访问数据库。

### 步骤 3：挑战任务

- 最后的挑战来了！请指示 Hermes 将支持第 2 模块“太阳系程序”所需的数据结构和数据迁移到刚刚创建的 `sol` 数据库。
- 这是一个小型数据库迁移项目，请耐心等待智能体思考与执行。
- 你也可以采用自己的独特迁移方法。
- 推荐提示如下：

```text
将 TiDB Cloud 文件系统挂载到 /workspace，然后使用一个可接受 Database URL 的 Python 程序，把/workspace下的太阳系Python程序的数据结构和数据迁移到sol数据库中。
```

> [!NOTE]
> 根据本实验所采用的大模型，迁移任务大约需要 5 分钟完成。如果遇到智能体返回 ⚠️  Response truncated (finish_reason='length') - model hit max output tokens，请忽略。

- 当智能体确认迁移成功后，切换回 **[终端 2](ssh://monitor1-ssh#2)**。检查智能体创建了哪些表，结果可能与你看到的不同，请关注 agent 生成的表名。示例输出中包含了 `moons` 和 `planets` 表，但你实际看到的结果可能会有所不同。

```bash
read DB_CLUSTER_ID <<< "$(ti db list-db-clusters \
  --db-cluster-type starter \
  --region aws-${LAB:REGION_CODE} \
  --query "clusters[?display_name=='hermes-data'].id" \
  --output text \
  )"

ti db execute-sql-statement \
  --sql "SHOW TABLES FROM sol" \
  --region aws-${LAB:REGION_CODE} \
  --admin \
  --db-cluster-id $DB_CLUSTER_ID \
  --output text
```

```output
+---------------+
| Tables_in_sol |
+---------------+
| moons         |
| planets       |
+---------------+
```

- 如果你确认有名为 planets 的表，可以用如下命令查询其数据行：

```bash
ti db execute-sql-statement \
  --sql "SELECT name, description FROM sol.planets" \
  --admin \
  --db-cluster-id $DB_CLUSTER_ID \
  --output text
```

> [!NOTE]
> 上述命令假定表名为 `planets` 且有 `name` 与 `description` 列，但实际表结构可能因 agent 的实现而异。如果未查询到结果，请自行用 SQL 探索表结构，或向 Hermes 咨询正确的表名和字段。

```output
+---------+--------------------------------------------------------------------------------------------------------------+
| name    | description                                                                                                  |
+---------+--------------------------------------------------------------------------------------------------------------+
| Mercury | Mercury has no natural satellites.                                                                           |
| Venus   | Venus has no natural satellites.                                                                             |
| Earth   | Earth has one natural satellite, the Moon, which is the fifth largest moon in the Solar System.              |
| Mars    | Mars has two small moons, Phobos and Deimos, which are thought to be captured asteroids.                     |
| Jupiter | Jupiter has 95 confirmed moons, including the four large Galilean moons: Io, Europa, Ganymede, and Callisto. |
| Saturn  | Saturn has 146 confirmed moons, including Titan, the second-largest moon in the Solar System.                |
| Uranus  | Uranus has 27 known moons, with the five largest being Titania, Oberon, Umbriel, Ariel, and Miranda.         |
| Neptune | Neptune has 14 known moons, with Triton being the largest and the only large moon with a retrograde orbit.   |
+---------+--------------------------------------------------------------------------------------------------------------+
8 rows in set
```

- 你也可以通过 [web 控制台](https://tidbcloud.com/tidbs) 进入 `hermes-data` 集群，点击 SQL Editor 在线浏览 `sol` 库的结构和数据。

### 步骤 4：头脑风暴

- 回到 **[终端 1](ssh://monitor1-ssh#1)** 的 Hermes 提示符。

- 现在 Hermes 智能体已经拥有两种“零基础设施、可扩展、持久化”的存储能力，询问它如何利用新能力改进记忆机制。

```text
结合 TiDB Cloud 文件系统与 TiDB Cloud Starter，你觉得有哪些提升你的记忆管理机制的思路？
```

- 下面是一个随机示例（实际内容可能不同，但确实有参考价值）：

```output
╭─ ⚕ Hermes ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
好问题！将 TiDB Cloud 文件系统和 TiDB Cloud Starter 结合起来，为创造一个显著更强大的记忆系统带来了诸多可能性。

1. 多层次记忆架构

当前局限：
- 记忆总长度仅 2200 个字符
- 结构扁平、无组织
- 没有优先级与时间递进的划分
- 无法查询或筛选记忆

利用 TiDB Cloud 构建的增强架构：

┌─────────────────────────────────────┐
│       第一层：活跃记忆               │
│     （上下文内存，2200 字符）        │
│   高优先级、高频访问信息             │
└─────────────────────────────────────┘
                 │
┌─────────────────────────────────────┐
│    第二层：结构化记忆                │
│  （TiDB Cloud Starter 数据库）       │
│   分类、元数据、关系                 │
└─────────────────────────────────────┘
                 │
┌─────────────────────────────────────┐
│    第三层：归档记忆                  │
...

可实施方案示例：

阶段一：数据库集成
...

阶段二：文件系统集成
...

阶段三：智能记忆管理
...

阶段四：高级特性
...

此系统的核心优势：

1. 存储无限：突破 2200 字符限制
2. 智能检索：获取相关记忆而非全量堆叠
3. 版本控制：可回滚到历史记忆状态
4. 关系映射：理解记忆间的关系
5. 自优化：自动清理和重组信息
6. 会话互通：不同 Hermes 实例间共享经验
7. 审计追踪：记录记忆创建、修改和使用历史
```

- 实验到此告一段落。现在你应该已经基本理解下面这张结构图了。

```mermaid
---
title: Coding 智能体统一存储层
---
flowchart LR
  subgraph region["云区域"]
    style region stroke-dasharray: 5 5
    subgraph temporary["短暂层——Agent 沙箱环境"]
      FS_CLIENT["文件"]
      DB_CLIENT["结构化数据"]
    end
    subgraph persistent["TiDB Cloud 持久层——可扩展，永远在线"]
      FS["文件系统"]
      DB["Starter 数据库"]
    end
    FS_CLIENT -->|FUSE & POSIX| FS
    DB_CLIENT -->|SQL| DB
  end
```

- 请继续进入清理部分。