应用库可移植到 PostgreSQL：AGENTLAB_DATABASE_URL 设成 postgresql+asyncpg://… 时整个应用库用 PostgreSQL，断点用官方的 langgraph-checkpoint-postgres（同一个库，AGENTLAB_CHECKPOINT_URL 可另给）；不设时照旧是数据目录里的 SQLite，行为不变

- 配置：database_url、checkpoint_url（启动时校验写法，只认 PostgreSQL）、连接池四项；启动日志写用的是哪种库（主机、库名、用户，不写密码）
- 引擎（db/base.make_engine）：SQLite 照旧 WAL、外键、忙等；PostgreSQL 用连接池、探活、会话时区 UTC，装上方言调整（db/postgres.py）：建表时 String(n) 是不限长的 VARCHAR（SQLite 从不查长度，导过来的存量也可能超长）、ORDER BY 里可空列的 NULL 位置照 SQLite 补写（升序在前、降序在后，窗口函数里同样）；Integer 列在 PostgreSQL 上是 BIGINT（列挂到表上时换成 with_variant，绑定参数跟着列按 BIGINT 转换）；JSON 列两边都存原文（PostgreSQL 的 json，不用 JSONB：JSONB 重排对象里的键，快照的列序、表的先后读回来就变了）；JSON 里的 NaN 写成 null、NUL 去掉（PostgreSQL 不收）
- 迁移按方言：已有的列和索引用 inspector 认；PostgreSQL 上补列的类型取模型里这一列的、缺省值取迁移表里的（布尔 0/1 换成 false/true），ADD COLUMN IF NOT EXISTS；去重语句里的布尔按方言写；部分唯一索引补 postgresql_where；init_db 在 PostgreSQL 上拿咨询锁（几个进程同时启动不撞）
- 应用库上的 SQLite 专用写法改成按方言编译的表达式（db/portable.py）：json_extract 的十几处（口径召回、出具、对账、个人应用、幂等键、访问控制、数据源变化通知、剖析任务、待办超时）换成 json_eq / json_flag / json_text，json_type 换成 json_is_string（两种库同一套带类型的比较）；能力登记的 sqlite insert 换成按会话方言的 insert_ignore；能力使用次数的 json_each 按方言分支；附件「没绑记录」的条件不靠 json 的等号；按报错文字认唯一约束的地方换成 unique_violation（按表和列认，两种库的报错都认得）
- 断点（engine/checkpoints.py）：PostgreSQL 时开 psycopg 连接池、在咨询锁里 setup；runner 只认 BaseCheckpointSaver，读断点仍只走 saver 的公开接口
- 依赖：新 extra postgres（asyncpg、psycopg[binary] 3、psycopg-pool、langgraph-checkpoint-postgres 3.1.2）；langgraph-checkpoint 卡在 <4.3（断点格式就在这个包里，postgres 包新版要 4.3，不动已装的 4.2.0）；锁文件补上新包
- 运行收尾：记 action.unknown、安排核实做完才把运行摘掉（以前先摘掉，等「不在跑了」再读事件的一方在库慢时读不到这一条）
- 测试：AGENTLAB_TEST_DATABASE_URL 时跑在 PostgreSQL 上（每个 xdist 进程建自己的库、按事件循环分的连接池 tests/pgpool.py），不设时盖掉环境里的数据库地址照旧用 SQLite；scripts/test-postgres.sh 起临时的 postgres:16 容器跑全量；sqlite_only 标记；另开连接改库的几个竞态测试、触发器测试改成两种库都能跑（tests/appdb.py）；新增 test_db_portable 守着方言调整、JSON 键序、超长字符串、大整数、NULL 排序、时区、PostgreSQL 老库迁移

scripts/test-postgres.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# 后端测试跑在 PostgreSQL 上（应用库和断点库都是 PostgreSQL）：本机 docker 起一个临时的 postgres:16 容器，只绑
+# 127.0.0.1 的随机端口、数据放内存里，跑完（出错、Ctrl+C 也一样）删掉容器，留镜像。
+#
+#   scripts/test-postgres.sh                          全量，-n auto
+#   scripts/test-postgres.sh tests/test_db_portable.py -x   参数原样交给 pytest（给了参数就不再加 -n auto）
+#   PYTHON=/path/to/python scripts/test-postgres.sh   指定装着后端依赖（含 [postgres]、[dev]）的 Python，缺省 python
+#   AGENTLAB_PG_IMAGE=postgres:16 …                   换镜像（要本机已经有，这里不拉）
+#
+# 测试怎么用这个库见 backend/tests/conftest.py：AGENTLAB_TEST_DATABASE_URL 给的是管理用的库，每个 xdist 进程在上面
+# 建自己的库（库名加 _gw0 之类的后缀），测试结束删掉。只对 SQLite 成立的测试标了 sqlite_only，这里跳过。
+# 不碰 scripts/dialect-it.sh 的容器（那边叫 agentlab-dialect-it-*）。
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PY="${PYTHON:-python}"
+IMAGE="${AGENTLAB_PG_IMAGE:-postgres:16}"
+NAME="agentlab-pgtest-$$"
+USER_NAME="agentlab"
+PASS="pgtest-only"
+DB="agentlab_test"
+
+command -v docker >/dev/null || { echo "缺少 docker"; exit 1; }
+docker image inspect "$IMAGE" >/dev/null 2>&1 || { echo "本机没有镜像 ${IMAGE}（这个脚本不拉镜像）：先 docker pull ${IMAGE}"; exit 1; }
+
+cleanup() { docker rm -f "$NAME" >/dev/null 2>&1 || true; }
+trap cleanup EXIT INT TERM
+
+# fsync、同步提交都关掉：测试库用完就扔，不需要落盘的保证。连接数放宽：每个 xdist 进程不用连接池（每个测试一个事件循环），
+# 但同一时刻会开好几条，断点库还各有一个小池子。认证用 trust（只绑 127.0.0.1、用完即删的库）：不用连接池时每次查库都
+# 新建连接，SCRAM 握手一次十几毫秒，trust 三毫秒，一次运行几十次查库，差出来的够让计时类的测试越界
+docker run -d --name "$NAME" -e POSTGRES_USER="$USER_NAME" -e POSTGRES_PASSWORD="$PASS" -e POSTGRES_DB="$DB" \
+  -e POSTGRES_HOST_AUTH_METHOD=trust \
+  -p 127.0.0.1::5432 --tmpfs /var/lib/postgresql/data:rw "$IMAGE" \
+  -c fsync=off -c synchronous_commit=off -c full_page_writes=off -c max_connections=1000 -c shared_buffers=256MB \
+  >/dev/null
+
+for _ in $(seq 1 60); do
+  if docker exec "$NAME" pg_isready -U "$USER_NAME" -d "$DB" -h 127.0.0.1 >/dev/null 2>&1; then break; fi
+  sleep 0.5
+done
+docker exec "$NAME" pg_isready -U "$USER_NAME" -d "$DB" -h 127.0.0.1 >/dev/null || { echo "PostgreSQL 没起来"; docker logs "$NAME" | tail -20; exit 1; }
+PORT="$(docker port "$NAME" 5432/tcp | head -1 | sed 's/.*://')"
+
+export AGENTLAB_TEST_DATABASE_URL="postgresql+asyncpg://$USER_NAME:$PASS@127.0.0.1:$PORT/$DB"
+echo "测试库：127.0.0.1:${PORT}/${DB}（容器 ${NAME}，结束后删除）"
+
+cd "$ROOT/backend"
+args=("$@")
+[ ${#args[@]} -eq 0 ] && args=(-n auto)
+# 同 README「开发与验证」：环境里的密钥不带进测试
+env -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL -u ANTHROPIC_AUTH_TOKEN -u OPENAI_API_KEY \
+  "$PY" -m pytest "${args[@]}"