SQLite 夹具

只有在直接检查或灌入本地 T3 状态时才加载本参考。

选择正确的数据库

当显式指定了 --base-dir 或 --home-dir 时，运行时状态位于 <base-dir>/userdata 下，数据库路径为 <base-dir>/userdata/statev2.sqlite。<base-dir>/dev 状态目录只作为隐式开发主目录的回退，以免一次普通的 vp run dev 触及生产状态。

服务器会把 V1 的 state.sqlite 复制进 statev2.sqlite，且仅在 statev2.sqlite 缺失时才这样做。首次启动之后，编辑 state.sqlite 不会产生任何变化。

灌入之前先启动一次目标运行时，使全部迁移都已执行。使用隔离的基目录。写入之前停止服务器，以免与应用状态或活动中的投影发生竞态。

使用辅助工具

列出表：

node apps/server/scripts/t3-sqlite-state.ts query \
  --base-dir <base-dir> \
  --sql "SELECT name FROM sqlite_schema WHERE type = 'table' ORDER BY name"

写入夹具之前，先查看当前列：

node apps/server/scripts/t3-sqlite-state.ts query \
  --base-dir <base-dir> \
  --sql "PRAGMA table_info(orchestration_v2_projection_threads)"

从文件应用 SQL 夹具：

node apps/server/scripts/t3-sqlite-state.ts exec \
  --base-dir <base-dir> \
  --file /tmp/t3-seed.sql

query 和 exec 每次调用都只使用一条语句；该辅助工具会把写入包在一个事务里，并在变更成功后打印备份路径。夹具需要多条记录时，使用一条包含多行取值的插入语句。

谨慎灌入投影数据

客户端从 projection_projects 读取项目（project），其余内容都从 orchestration_v2_projection_* 各表读取：对话线程（thread）、运行、消息、回合（turn）条目、运行时请求、计划，以及提供方会话（session）。较旧的 projection_thread* 各表保存 V1 历史，服务器在启动时按每个对话线程导入一次；之后在那里所做的编辑不会到达界面。

大多数 V2 行都带有 payload_json，它必须能对照 packages/contracts/src/orchestrationV2.ts 中的模式解码。最稳妥的起点是应用自己写入的一行：通过界面创建对话线程，复制它的各行，再进行编辑。保持标识符唯一，时间戳使用 ISO 字符串，并使相关的项目、对话线程和运行 ID 彼此一致。

直接写入投影适用于短暂的视觉状态、边界情况的计数、长标题、长时间线以及类似的界面夹具。它们不会形成连贯的事件历史。不要改动事件日志（orchestration_events），也不要借直接写入投影来声称后端业务行为可用。

行为测试请使用应用的命令（command）或 API。认证状态请使用 node apps/server/src/bin.ts auth ...，而不要去编辑 auth_pairing_links 或 auth_sessions。