存储：SQLite、迁移与运行时归属

MiniMax Code 没有常驻服务进程，每个 mcode 都自己打开数据目录、自己拼一套运行时（见进程内入口）。存储层因此要回答三件事：东西放在哪；库结构怎样随版本升级；同一个目录被两个进程同时打开时，谁的工作算数。packages/local-runtime-v2/src/infra 下 100 个文件、20599 行就是答案，其中 db 目录独占 12686 行。

怎么用：数据目录

命令行的数据目录默认是 ~/.minimax-code（packages/tui/src/runtime/data-dir.ts:21），环境变量 MINIMAX_DATA_DIR 优先、MAVIS_DATA_DIR 其次，可以改到别处（runtime/data-dir.ts:28）。选定后 CLI 会把两个变量都写回进程环境（packages/tui/src/cli/environment.ts:58），第一代宿主启动时也再写一遍 MINIMAX_DATA_DIR（packages/local-runtime/src/runtime/host-factory.ts:67），这样共享配置代码里的 getDataDir（packages/config/src/config.ts:1476）、技能模板里的 {{DATA_DIR}} 都落在同一处。

数据目录里与本篇相关的内容：

会话历史的 JSONL 布局归会话系统讲，最后一行的旧数据归第一代运行时与 OpenCode 遗产讲。

一个库，两本迁移账

驱动是 better-sqlite3 12.11.1，上面套一层 drizzle-orm（packages/local-runtime-v2/package.json:105、同文件第 107 行）。DatabaseClient 第一次被访问时才打开库文件，并设好三条 PRAGMA（client.ts:116）：

// v1 and v2 temporarily access the same database through separate connections; keep PRAGMAs aligned.
sqlite.exec(`
  PRAGMA journal_mode = WAL;
  PRAGMA busy_timeout = 5000;
  PRAGMA foreign_keys = ON;
`);

注释点明了一件事：第一代运行时也打开同一个文件。packages/local-runtime/src/persistence/db.ts:545 的 resolveLocalRuntimeDbPath 解析出的正是 v2/sqlite/runtime-state.sqlite，PRAGMA 一字不差（db.ts:549）。两代代码各记各的迁移：第一代写 local_runtime_schema_migrations（db.ts:559），第二代写 local_runtime_v2_schema_migrations。目录约定里还声明了 session-index.sqlite、usage-state.sqlite、legacy-import.sqlite 三个库（packages/shared/src/local-runtime-paths.ts:58），但代码里没有任何地方打开它们。Electron 需要自带重编译的原生模块时，可以用 MAVIS_SQLITE3_MODULE_PATH 指定 better-sqlite3 的位置（client.ts:139）。

表按领域分文件放在 infra/db/schema/，主要几组：

手写迁移

迁移没有用 drizzle-kit 的运行时迁移器，packages/local-runtime-v2/src/infra/db/migrate.ts:23 的注释列了三条理由：

Why not drizzle-kit migrate():

1. It reads the migration directory from fs at runtime, which is unfriendly to Electron asar.
2. We must coexist with v1 data; some migrations backfill data rather than only applying DDL.
3. Keep runtime dependencies minimal: only drizzle-orm + better-sqlite3.

每条迁移是一个 { version, name, up }，up 可以是 SQL 字符串，也可以是函数（用于回填数据）。runMigrations 逐条执行，关键在事务里的二次确认（migrate.ts:48）：

for (const migration of migrations) {
  if (applied.has(migration.version)) continue;
  rawDb.exec('BEGIN IMMEDIATE');
  try {
    if (isMigrationApplied(rawDb, migration.version)) {
      rawDb.exec('COMMIT');
      applied.add(migration.version);
      continue;
    }

BEGIN IMMEDIATE 一开始就拿写锁。两个进程同时启动时，后到的那个等到锁以后先在锁内重新查一次版本表，发现已经跑过就直接提交跳过。迁移失败则 ROLLBACK 并把异常抛出去，启动随之失败。

注册表 packages/local-runtime-v2/src/infra/db/migrations.ts:38 共 35 条，版本号从 1 到 36，唯独没有 19。编号里能看到多分支并行开发的痕迹：几个已发布的分支占用过同一个版本号，而运行器只认版本号，于是有了一批“撞号修复”迁移，用新版本号把表以 CREATE TABLE IF NOT EXISTS 再建一遍。m0027 的注释（packages/local-runtime-v2/src/infra/db/migrations/session/migration-0027-repair-task-session-bindings-version-collision.ts:4）：

Some published profiles already recorded version 20 for an unrelated repair. Re-assert the Task binding table under a new version so those profiles converge without rewriting migration history or deleting existing data.

m0030、m0031 等也是同一类修复。启动时的完整顺序在 initializeDatabase（packages/local-runtime-v2/src/infra/db/initialize.ts:60）：

1. 有待执行的迁移就先备份整库（下一节）。
2. 停用没有下次运行时间的旧定时任务。
3. 先跑版本 7 之前的迁移，修好旧的项目偏好和格式损坏的会话记录，再跑版本 15 之前的迁移，修会话的项目元数据；这些修复都要赶在对应的回填迁移之前。
4. 处理一个已发布分支占用版本 16 却没建表的情况（initialize.ts:150），然后跑完全部迁移。
5. assertDatabaseSchemaConsistent（packages/local-runtime-v2/src/infra/db/schema-consistency.ts:282）逐项核对表、列、索引、触发器、虚表，以及已下线的表确实不存在，不一致就拒绝启动。

在打开这个库之前，还有一步由第一代代码完成的目录布局迁移 ensureCurrentLocalRuntimeDataMigratedToV2OrThrow（packages/local-runtime/src/persistence/migration/v2-migration.ts:152），失败时抛出带 current_local_runtime_v2_migration_failed: 前缀的错误（v2-migration.ts:149）。各阶段耗时会写进启动计时日志，见进程内入口。

迁移前备份

createDatabaseBackupIfPending（backup.ts:67）只在有待执行迁移时工作：用 SQLite 的在线备份接口（client.ts:83）把库复制到 v2/sqlite/backups/runtime-state-before-v2-migration-<毫秒时间戳>-<UUID>.sqlite，再开一个独立的只读连接跑 PRAGMA integrity_check，结果必须恰好是一行 ok（client.ts:88）。备份目录链上任何一级是符号链接都算不安全，直接放弃（backup.ts:80）。备份失败时删掉半成品，抛出 LOCAL_RUNTIME_V2_DATABASE_BACKUP_FAILED（backup.ts:15），迁移不会在没有备份的情况下进行。

旧备份的清理放到就绪之后：运行时登记一个 migration-backup-retention 维护任务（packages/local-runtime-v2/src/runtime.ts:283），调用 pruneSupersededDatabaseBackups（backup.ts:121）。它只删比本次备份更早、且文件名符合格式的备份，每删一个之前都重新核对本次备份的文件身份（设备号、inode、大小、时间戳）没变（backup.ts:159）。没有迁移的正常启动不创建备份，也不清理。

运行时归属：谁的工作还活着

同一个数据目录可以同时跑好几个 mcode，存储层不选出唯一的“主进程”，而是给每个进程发一份租约，再把租约身份写进它领走的每一份工作里。createRuntimeOwnerIdentity（identity.ts:70）做三件事：

1. 以 wx（文件已存在即失败）和 0600 权限写出 v2/runtime-owner-leases/<instanceId>.owner（identity.ts:89）。内容是一行裸 PID 再加一行 JSON；保留裸 PID 行是为了让回滚后的旧版本也能读懂（packages/local-runtime-v2/src/infra/runtime-owner/runtime-owner-lease.ts:22）。
2. 用 proper-lockfile 锁住这个文件，过期时间 10 秒（identity.ts:11），心跳间隔取过期时间的三分之一、至少 1 秒（identity.ts:98）。锁被判定失守时通知所有监听者，运行时记一条错误日志后自行关闭（src/runtime.ts:492）。
3. 发放所有者 ID，格式是 kind:pid:instanceId.operationId（identity.ts:41），kind 只有四种：turn-lease、session-delete、queue-claim、background-task（identity.ts:13）。

这些 ID 写在会话锁、队列认领、后台任务等记录上（packages/local-runtime-v2/src/services.ts:913、services.ts:921、packages/local-runtime-v2/src/service/session-system/owner.ts:563）。别的进程遇到一条带 ID 的记录，靠下面这段判断主人是否还活着（identity.ts:53）：

return (ownerId) => {
  const parsed = parseOwnerId(ownerId);
  if (!parsed) return ownerId.startsWith('session-delete:') ? false : undefined;
  if (!parsed.instanceId) return options.isProcessAlive(parsed.pid);
  const leaseState = options.getInstanceLeaseState(parsed.instanceId);
  const currentInstance =
    parsed.pid === options.currentPid && parsed.instanceId === options.currentInstanceId;
  // Compromise revokes authority, but does not prove that this process finished draining.
  if (currentInstance) return leaseState !== 'missing';
  if (leaseState === 'missing') return false;
  if (!options.isProcessAlive(parsed.pid)) return false;
  // A delayed heartbeat is not proof that this exact foreign owner died.
  // Its process must close the lease or exit before another Runtime may recover its work.
  return true;
};

判定偏保守：租约文件不在，或者进程已经不存在（process.kill(pid, 0)），才算死；心跳迟到不算。租约文件在正常关闭时删除（identity.ts:163），进程崩溃会留下文件，但进程不在了同样判死。以回合为例：会话锁表 local_runtime_session_locks 每个会话一行，记录所有者 ID 和过期时间，默认租期 30 分钟，运行期间续约（packages/local-runtime-v2/src/service/turn-system/persistence/turn.repository.ts:37）；进程启动时扫描在自己启动之前拿到的锁，主人已死的就回收（packages/local-runtime-v2/src/service/turn-system/persistence/turn-lease-recovery.ts:87）；删除会话时若锁属于另一个还活着的进程，就直接报错拒绝（turn.repository.ts:808）。锁的获取与续约细节见回合系统。

租约里还有一个可选的进程启动令牌：Linux 取启动 ID 加进程启动时刻，macOS 用 ps -o lstart= 并强制 UTC，Windows 没有探针，只能退回裸 PID（packages/local-runtime-v2/src/infra/runtime-owner/process-start-time.ts:39）。它给“数据目录代际切换”用：switchRootlessV2Generation 在切换前调用 assertRuntimeOwnersStopped，只要有一个活着的租约就以 ROOTLESS_V2_OWNERS_ACTIVE 拒绝（packages/local-runtime-v2/src/infra/runtime-owner/rootless-v2-generation-fence.ts:120），令牌用来识破被复用的 PID。启动路径上的整目录检查点已经拿掉，注释说这个模块留给一个自带操作围栏的命令行工具（src/runtime.ts:169）；包入口导出了 switchRootlessV2Generation，但公开源码里找不到调用方。

还有一把更粗的锁。启动时的 Agent 定义切换在 withAgentStorageLock 里进行（packages/local-runtime-v2/src/compat/v1/runtime.ts:125），底下是第一代的 withAgentNameConflictMigrationLock：直接用 proper-lockfile 锁数据目录本身（packages/local-runtime/src/persistence/migration/agent-name-conflict-migration.ts:197），过期时间 30 分钟，最多重试 120 次（agent-name-conflict-migration.ts:40）。两个进程同时冷启动时，后到者在这里排队。

其他基础设施

• JSONL：infra/file 提供三种写法。追加 appendJsonl 明说不做跨进程加锁，调用方必须按文件串行（packages/local-runtime-v2/src/infra/file/jsonl.ts:73）；整体替换 replaceFileAtomically 先写同目录的临时文件并落盘，再改名覆盖（jsonl.ts:149）；首次发布 publishFileIfAbsent 用硬链接原子地“目标不存在才创建”（jsonl.ts:193）。
• 历史来源选择：同一会话的历史可能同时存在于新 JSONL、旧账本快照、SQLite 行、SQLite 大字段四处，selectCanonicalHistorySource（packages/local-runtime-v2/src/infra/file/canonical-history-source.ts:16）按这个顺序取第一个有权威数据的来源，选中之后读失败也不再往下回退。
• Git：packages/local-runtime-v2/src/infra/git/fork-worktree-adapter.ts:38 只服务会话分叉，用 git worktree add -b 在仓库根的 .worktrees/ 下建新工作树（fork-worktree-adapter.ts:136、fork-worktree-adapter.ts:194），参数以数组传给 git，从不经过 Shell 字符串。
• SSE 缓冲：BoundedRing 默认保留 512 条、2 MiB（packages/local-runtime-v2/src/infra/sse/bounded-ring.ts:52），会话事件流把上限放宽到 2000 帧、8 MiB（packages/local-runtime-v2/src/service/session-system/stream/session-frame-retention.ts:4）；每个订阅者自己的队列默认 128 条、512 KiB，溢出时以 SubscriberOverflowError 断开（packages/local-runtime-v2/src/infra/sse/subscriber-registry.ts:42）。
• 调度器：infra/scheduler 用 croner 计算触发时间，作业存在 local_runtime_v2_scheduler_jobs 表，只在 Electron 宿主上创建（packages/local-runtime-v2/src/background-runtime.ts:15）。

保留与清理

清理全部放在运行时就绪之后：startMaintenance 先让出一轮事件循环（background-runtime.ts:109），再并行跑已登记的维护任务，任何一个失败只记警告。一共三项：

没有列进来的就不会被自动删除：会话记录、JSONL 历史、旧版 sqlite.db 都一直留着。回合差异清理的注释（storage-retention.ts:22）说得很直白：

One bounded post-ready pass over current Turn Diff state. Migrated Session history is intentionally outside automatic retention and is never read here.

需要腾空间时只能手动删会话，或者直接清理数据目录。

下一篇：第一代运行时与 OpenCode 遗产——同一个库文件的另一位使用者，以及旧会话怎样被迁成 pi 会话。