Agent 工程实战 on 扎塔-Zata

数据库初始化与迁移：从创建那一刻就要钉死的三件事

Thu, 23 Jul 2026 11:21:08 +0800

一句话：版本 + 字符集 + 排序规则，三件事必须在 CREATE 那一刻写死。 之后任何跨环境、迁移、同步都建立在这三件事一致的基础上。

一、三件事在四个数据库里的标准值

数据库	版本	字符集	排序规则	改的代价
MySQL 5.7	`5.7.x` LTS	`utf8mb4`	`utf8mb4_general_ci`	单 ALTER
MySQL 8.0	`8.0.x` / `8.4.x`	`utf8mb4`	`utf8mb4_0900_ai_ci`	单 ALTER
PostgreSQL	`15.x` / `16.x`	`UTF8` (client)	ICU 默认	库级改不了
SQL Server	`2019` / `2022`	见 collation	`SQL_Latin1_General_CP1_CI_AS`	可改，需重建索引

永远显式写。不能依赖"实例默认值"——开发/测试/预发/线上四个环境经常不一样。

二、emoji 演示：`utf8` ≠ `utf8mb4`

INSERT INTO users (name) VALUES ('😀'); -- 字符: 4 字节

字符集	字节数上限	结果
`latin1`	1 字节	❌ 中文都存不了
`utf8`	3 字节 ⚠️	❌ emoji 报错 `ERROR 1366`
`utf8mb4`	4 字节	✅

MySQL 的 utf8 是历史包袱，只支持 3 字节。JDBC / ORM 里写 utf8 的，emoji 入库一律失败。永远写 utf8mb4。

三、四套初始化模板（直接复制）

MySQL 5.7

CREATE DATABASE my_app
 DEFAULT CHARACTER SET utf8mb4
 DEFAULT COLLATE utf8mb4_general_ci;

CREATE TABLE users (
 id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
 name VARCHAR(64) NOT NULL,
 email VARCHAR(128) NOT NULL,
 created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 PRIMARY KEY (id),
 UNIQUE KEY uk_email (email)
) ENGINE=InnoDB
 DEFAULT CHARSET=utf8mb4
 COLLATE=utf8mb4_general_ci;

MySQL 8.0

CREATE DATABASE my_app
 DEFAULT CHARACTER SET utf8mb4
 DEFAULT COLLATE utf8mb4_0900_ai_ci;

CREATE TABLE users (
 id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
 name VARCHAR(64) NOT NULL,
 email VARCHAR(128) NOT NULL,
 payload JSON DEFAULT NULL,
 created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 PRIMARY KEY (id),
 UNIQUE KEY uk_email (email),
 -- 8.0 才支持的表达式索引
 KEY idx_payload_user_id ((CAST(payload->>'$.userId' AS CHAR(64))))
) ENGINE=InnoDB
 DEFAULT CHARSET=utf8mb4
 COLLATE=utf8mb4_0900_ai_ci;

PostgreSQL

-- 库级字符集在 CREATE DATABASE 时定型,后续改不动!
CREATE DATABASE my_app
 WITH ENCODING 'UTF8'
 LC_COLLATE = 'en_US.UTF8'
 LC_CTYPE = 'en_US.UTF8'
 TEMPLATE = template0;

CREATE TABLE users (
 id BIGSERIAL PRIMARY KEY,
 name TEXT NOT NULL,
 email TEXT NOT NULL,
 payload JSONB DEFAULT NULL,
 created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 UNIQUE (email)
);

CREATE INDEX idx_payload_user_id
 ON users ((payload->>'userId'));

PG 的字符集分两层：库级 ENCODING + 连接级 client_encoding。JDBC 必须显式：
jdbc:postgresql://host:5432/my_app?charSet=UTF8

SQL Server

-- 实例默认 collation 不一定是这个,必须显式写
CREATE DATABASE my_app
 COLLATE SQL_Latin1_General_CP1_CI_AS;
GO

CREATE TABLE users (
 id BIGINT IDENTITY(1,1) PRIMARY KEY,
 name VARCHAR(64)
 COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL,
 email VARCHAR(128)
 COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL,
 payload NVARCHAR(MAX) DEFAULT NULL,
 created_at DATETIME2(3) NOT NULL DEFAULT SYSUTCDATETIME(),
 UNIQUE (email)
);
GO

四、迁移报错 4 种「症状 → 原因 → 修复」

🔴 症状 1：emoji / 中文入库乱码或报错

-- 报错信息
ERROR 1366 (HY000): Incorrect string value: '\xF0\x9F\x98\x80' for column 'name'

项	内容
原因	表字符集不是 `utf8mb4`
修复	`ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;`
预防	JDBC 连接串 `characterEncoding=utf8`、表级显式 `CHARSET=utf8mb4`

🔴 症状 2：`ORDER BY name` 顺序变了 / `WHERE col='...'` 命中行数变化

项	内容
原因	排序规则从 `general_ci` → `0900_ai_ci`，UCA 9.0 比较更激进
修复	`ORDER BY name COLLATE utf8mb4_bin` 锁定；或应用层排序
预防	业务层不依赖 DB 排序结果做正确性判断

🔴 症状 3：`INSERT` 截断字符串 → 整个应用雪崩

项	内容
原因	8.0 默认 `STRICT_TRANS_TABLES`，截断从 warning 变 error
修复	灰度期间 `SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION,...';`
预防	上线前用真实流量回放，发现 silent-truncate 全部修掉

🔴 症状 4：本地能连，CI/线上连不上

项	内容
原因	5.7 `mysql_native_password` → 8.0 `caching_sha2_password`
修复	升级 JDBC/ORM 驱动；禁掉 `mysql_native_password`
临时方案	`ALTER USER 'app'@'%' IDENTIFIED WITH mysql_native_password BY 'xxx';`

五、其他数据库的独有坑（速查）

数据库	坑	一句话修复
PG	字符串默认大小写敏感	`LOWER(name) = LOWER(?)` 或用 `citext`
PG	10+ 隐式类型转换收紧	所有比较显式 `CAST`
PG	`BIGSERIAL ≠ AUTO_INCREMENT`	跨库迁移重置序列或改 UUID
SQL Server	collation 在 3 个层级设置	列级 `COLLATE ...` 钉死
SQL Server	`DATETIME` vs `DATETIME2`	迁移时零日期映射为 `NULL`
SQL Server	`OFFSET` 在大表慢	永远用 keyset 分页（`WHERE id > last_id`）

六、迁移前 5 分钟 checklist（直接跑）

MySQL

-- 1. 实例信息
SELECT @@version, @@character_set_server, @@collation_server, @@sql_mode;

-- 2. 找出非 utf8mb4 的表
SELECT table_schema, table_name, table_collation, CCSA.character_set_name
FROM information_schema.tables T
JOIN information_schema.collation_character_set_applicability CCSA
 ON CCSA.collation_name = T.table_collation
WHERE table_schema NOT IN ('mysql','sys','information_schema','performance_schema')
 AND CCSA.character_set_name != 'utf8mb4';

-- 3. 找出表达式索引 (8.0+ 特性)
SELECT * FROM information_schema.statistics
WHERE expression IS NOT NULL
 AND table_schema NOT IN ('mysql','sys','information_schema','performance_schema');

-- 4. 找出 mysql_native_password 账号
SELECT user, host, plugin FROM mysql.user WHERE plugin = 'mysql_native_password';

PostgreSQL

SELECT version();
SELECT datname, datcollate, datctype
FROM pg_database WHERE datistemplate = false;
SELECT * FROM users WHERE length(name) = 0 OR name IS NULL;

SQL Server

SELECT SERVERPROPERTY('Collation') AS server_collation;
SELECT name, collation_name FROM sys.databases;
SELECT * FROM dbo.users WHERE created_at < '1900-01-01';

七、迁移流程（七步走）

1. 备份 (mysqldump --single-transaction --hex-blob)
 ↓
2. 准备目标实例 (兼容 sql_mode)
 ↓
3. 导入备份 (不要用 source,用 mysql ... < backup.sql)
 ↓
4. 跑上面的 checklist SQL
 ↓
5. CONVERT 字符集 + 验证表达式索引兼容
 ↓
6. 灰度切流量 5% → 20% → 100%
 ↓
7. 完全切完后再升级 ORM / 驱动

回滚三件套：

保留 7 天以上源端快照

迁移脚本幂等（跑两遍不报错也不丢数据）

DNS / 负载均衡能秒级切回

八、Agent 系统特别提醒

#	提醒	一句话
1	向量存储	别用原生 PG/MySQL 向量扩展做主索引,规模上来性能不行
2	对话历史	高频追加→单独 `messages` 表+定期归档
3	状态机持久化 (LangGraph checkpoint)	高频 UPDATE 同一行 → `SKIP LOCKED` + 多分片
4	审计 / Trace 表	可能比业务表大 10 倍 → 单独 schema + TTL + 列存

速查表

┌────────────────────────────────────────────┐
│ 创建数据库那一刻要钉死的三件事: │
│ │
│ VERSION → 5.7 / 8.0 / PG15 / 2019 │
│ CHARSET → utf8mb4 (永远,别用 utf8) │
│ COLLATION → utf8mb4_0900_ai_ci (8.0) │
│ │
│ 任何"看起来能跑"的 SQL 上生产前必查: │
│ │
│ EXPLAIN + CHARSET + COLLATION + TIMEOUT │
└────────────────────────────────────────────┘

下一篇：Tool Calling 工程化——从 schema 设计到 Human-in-the-loop 的具体落地。

参考

Agent 工程实战开篇：从 Demo 到生产还有多远

Thu, 23 Jul 2026 10:31:54 +0800

这是 Agent 工程实战系列的第一篇。我会把在生产环境里踩过的坑、验证过的方案，按主题整理成可复用的工程手册。

一句话定义 Agent 工程

Agent 工程 = 把一个在本地能跑 80% 的 LLM 循环，变成一个在真实流量下 99% 可用、可观测、可评估、可控成本的服务。

把这句话拆开，至少有五件事要做：

可控 — 输出可控、行为可控、失败可控
可观测 — 每一步都留下 trace，事后能复盘
可评估 — 不是"看着还不错"，是有数据证明它确实不错
可扩展 — 用户从 10 个到 10 万个，延迟和成本不会爆
可治理 — 安全、合规、可解释、可下线

下面聊聊从 Demo 走到生产最容易翻车的几个点。

1. 别再把 Prompt 当成"代码"

Demo 阶段你可以在 system prompt 里写一段 200 字的话，模型听话；但到了生产：

不同模型的 instruction-following 能力差异巨大
用户输入会污染 prompt 结构（prompt injection）
Prompt 一改，行为就会漂移，且没人能精确描述改了什么

工程化做法：

Prompt 模板独立仓库管理，版本化（每条上线记录到变更日志）
把"工具说明"、“角色设定”、“业务规则”、“用户输入"在拼接时显式分段，而不是塞进同一个 f-string
关键 prompt 用 LLM 评审 / 回归集 守门，而不是靠人肉感觉

2. Tool Calling 不是 `if name == "...":`

很多 Demo 是这样的：

if "天气" in user_input:
 return get_weather(...)

这种"伪 function calling"看起来工作，但生产里会立刻暴露问题：

用户可以构造输入绕过规则
没有 schema 校验，模型幻觉出来的参数会直接打到下游
没有权限隔离，所有工具对所有 prompt 开放

工程化做法：

用真正的 tool/function schema（OpenAI / Anthropic 风格），让模型输出结构化参数
用 Pydantic / Zod 在边界做参数校验
工具分级别：只读工具 / 写工具 / 外部副作用工具，按风险分桶调用
高风险工具强制 Human-in-the-loop 确认

3. Agent Loop 必须有上限

最经典的 bug：

用户问了一个含糊的问题 →
Agent 没拿到足够信息 →
Agent 又去调用工具 →
工具又返回模糊结果 →
Agent 再调工具 →
... → token 烧光 / 循环 100 次 / 超时

工程化做法：

显式设置 max_steps（建议 ≤ 10）
区分"成功终止”、“最大步数终止”、“循环检测终止”
检测到重复 state（同一组工具调用两次以上）→ 主动 break 并 fallback 到"我不知道"
关键决策点强制 reflection / self-critique，但要限制其调用次数

4. 可观测性：先有 Trace，再谈优化

没有 trace 的 Agent 优化就是"蒙眼调参"。生产里至少要有：

Span：每一次 LLM 调用、工具调用、记忆读写的输入 / 输出 / 耗时 / token
Trace ID：贯穿一次完整任务的所有 span
成本字段：每次调用的 input/output token 与单价
失败分类：timeout / 工具异常 / 解析失败 / 内容安全拦截

推荐起步就用 LangSmith、Langfuse、Arize Phoenix 这类平台之一，自建成本不低。

5. 评估不是上线后再想的事

生产里最容易回答不出的问题：“这个版本比上个版本到底好了多少？”

最小可用的评估体系：

离线评测集：50~200 个有标准答案或参考回答的 case，回归门禁
LLM-as-judge：用一个更强的模型给输出打分，但要注意：评分模型本身也会偏
线上指标：任务成功率、人工接管率、单任务成本、p95 延迟
红队 / 注入集：专门挑 prompt injection 与越权场景，定期跑

6. 成本治理：模型路由 + 缓存 + 流式

Agent 系统烧钱的速度比传统服务快得多，因为：

多轮 LLM 调用 × 长上下文 × 复杂工具链
“小问题用大模型"是常态浪费

工程化做法：

模型路由：简单任务走小模型（如分类、提取），复杂任务才走大模型
语义缓存：相似 query 直接返回上次结果，注意要带 cache key 的失效策略
流式输出：长生成场景下，TTFT 比总时长更重要
预算熔断：单任务 / 单用户 / 单租户的 token 上限，超限自动降级

7. 安全：默认假设你的 Prompt 会被攻破

不要把系统提示视为秘密，它一定会被泄露
不要让 LLM 决定要不要执行高风险工具（删库、转账、发邮件），必须硬规则守门
必须对工具返回值做清洗——它也是用户可控输入
必须审计日志：谁、什么时候、通过哪个 agent、调了哪个工具、传了什么参数

这个系列接下来会写什么？

按上面七个主题，每个都会展开成一篇实战文章，配可运行示例：

Prompt 工程化：从 f-string 到模板系统
Tool Calling 工程化：schema、权限、Human-in-the-loop
Agent Loop 设计：状态机视角的 ReAct
可观测性实战：Langfuse / LangSmith 接入
评估体系搭建：离线集 + LLM-judge + 线上指标
成本与性能：模型路由、缓存、流式
安全与合规：Prompt injection 防护与审计

如果你也在做 Agent，欢迎把你踩过的坑写在评论区——下一篇我会挑留言里出现最多的那个话题。

Agent 工程实战 on 扎塔-Zata

数据库初始化与迁移：从创建那一刻就要钉死的三件事

一、三件事在四个数据库里的标准值

二、emoji 演示：utf8 ≠ utf8mb4

三、四套初始化模板（直接复制）

MySQL 5.7

MySQL 8.0

PostgreSQL

SQL Server

四、迁移报错 4 种「症状 → 原因 → 修复」

🔴 症状 1：emoji / 中文入库乱码或报错

🔴 症状 2：ORDER BY name 顺序变了 / WHERE col='...' 命中行数变化

🔴 症状 3：INSERT 截断字符串 → 整个应用雪崩

🔴 症状 4：本地能连，CI/线上连不上

五、其他数据库的独有坑（速查）

六、迁移前 5 分钟 checklist（直接跑）

MySQL

PostgreSQL

SQL Server

七、迁移流程（七步走）

八、Agent 系统特别提醒

速查表

参考

Agent 工程实战开篇：从 Demo 到生产还有多远

一句话定义 Agent 工程

1. 别再把 Prompt 当成"代码"

2. Tool Calling 不是 if name == "...":

3. Agent Loop 必须有上限

4. 可观测性：先有 Trace，再谈优化

5. 评估不是上线后再想的事

6. 成本治理：模型路由 + 缓存 + 流式

7. 安全：默认假设你的 Prompt 会被攻破

这个系列接下来会写什么？

参考

二、emoji 演示：`utf8` ≠ `utf8mb4`

🔴 症状 2：`ORDER BY name` 顺序变了 / `WHERE col='...'` 命中行数变化

🔴 症状 3：`INSERT` 截断字符串 → 整个应用雪崩

2. Tool Calling 不是 `if name == "...":`