fix(cli,runtime): os dev / os start / os migrate 解析出三个不同的默认数据库 —— migrate plan 因此在自己刚建的空库上报告全量 drift

[os-zhuang]

现象

在一个装好的 app 项目里（hotcrm，17.0.0-rc.5），先 objectstack start 跑起服务并完成 seed，然后按 docs/MAINTENANCE.md §3.1 的升级后检查跑 os migrate plan，得到：

ℹ Database: /home/user/hotcrm/.objectstack/data/standalone.db
ℹ Examined 22 managed table(s).

New (additive — created when you apply)
  + crm_account [create_table, 30 column(s)]
  + crm_campaign [create_table, 29 column(s)]
  ... 22 张表全部待创建
ℹ 22 table(s) to create, 0 column(s) to add

这份报告是假的。 显式指向服务真正在用的库之后：

$ os migrate plan --database-url file:/home/user/hotcrm/.objectstack/data/objectstack.db
ℹ Examined 22 managed table(s).
✓ Physical schema is in sync with metadata — nothing to migrate.

零漂移。plan 打开的是一个它自己刚刚创建的空库：

$ ls -la .objectstack/data/
-rw-r--r-- 2629632 Aug  7 12:02 objectstack.db    ← 服务在用的
-rw-r--r--    4096 Aug  7 12:01 standalone.db     ← plan 刚建的空库

根因：三个命令，三个写死的默认库名，同一个目录

命令	默认数据库	出处
os dev	<projectRoot>/.objectstack/data/**dev.db**	packages/cli/src/commands/dev.ts:37（resolveDefaultDevDbUrl，用于 dev.ts:301，由 dev-default-db.test.ts 钉住）
os start	<projectRoot>/.objectstack/data/**objectstack.db**	packages/cli/src/commands/start.ts:193
os migrate *	<projectRoot>/.objectstack/data/**standalone.db**	packages/runtime/src/standalone-stack.ts:222（resolveDatabaseUrl）

三条路径谁都不从 objectstack.config.ts 解析数据源，各自 fallback 到一个不同的硬编码文件名，而且三个文件落在同一个目录里。

这不是「独立工具不认识你的项目」：migrate plan 明明读了项目配置 —— 它把整个应用的元数据注册表都加载了（[Registry] Registered data: app.objectstack.hotcrm:crm_account 等 20 余行）。它读了 A 的元数据定义，然后拿去 diff B 的物理现状。

二阶损害：#3917 的占用检查守着一个不会被占用的文件

packages/cli/src/utils/sqlite-occupancy.ts:9 的动机注释写的是：

the overwhelmingly common shape of a dev machine is a pnpm dev server holding the same .objectstack/data/standalone.db open while the operator runs a migration in another terminal

这个前提在默认路径下不成立。pnpm dev（os dev）持有的是 dev.db，os migrate apply 打开的是 standalone.db。两者在默认配置下永远不会争用同一个文件，所以 #3917 那套 /proc / lsof 占用检测在它自己描述的那个主场景里不可能触发。

（守卫本身不是废的 —— 如果操作者显式把 OS_DATABASE_URL 指到同一个文件，它照常工作。失效的是它的默认路径场景，也就是注释里说的「压倒性常见」的那个。）

为什么这条比「输出看着怪」严重

失败方向是反的。 真相是「零漂移」，输出是「22 张表全部待创建」。它不会让人漏掉问题，它会让人以为升级把数据库干掉了。照着 §3.1 走的操作者，最可能的下一步是去回滚一个根本没坏的东西。

它有写副作用。 plan 号称 dry-run，但解析路径上的空库会被建出来。跑第二次看到的还是同一份假报告，而且现在磁盘上真有这么个文件，更像「就该是这样」。

它正在长配套逻辑。 sqlite-occupancy.ts 已经把 standalone.db 当成事实写进了注释和实现。这类分叉每多待一个版本，就多一处把它当既定行为的代码。

给操作者的判别式（在修好之前）

看到 os migrate plan 报「所有表都待创建」而应用明明在正常跑 —— 那是指错库了，不是数据库坏了。确认办法是看输出第一行的 ℹ Database: 路径是不是服务实际在用的那个（os start 启动横幅里的 Driver: ... → <path>）。

显式指定时注意 scheme 只认 file:：

os migrate plan --database-url file:/abs/path/.objectstack/data/objectstack.db

sqlite:// 会被拒（Unsupported database URL scheme ... Supported schemes: memory://, postgres://, pg://, mongodb://, mongodb+srv://, file:）。错误信息本身合格，但 sqlite:// 大概是这个场景下最自然的猜测，值得一并考虑接受。

修复方向（供讨论，未认领）

核心是「一个项目的数据库」应当只有一处解析。倾向于把三条 fallback 收敛到一个共享函数，并让它优先读项目配置声明的数据源；默认文件名统一（保留其余两个作为兼容读取，或在检测到旧文件时给出迁移提示，避免既有 dev 环境的数据凭空「消失」）。

兼容性需要考虑：已经存在 dev.db / standalone.db 的本地环境，统一之后不能表现为数据丢失。

修好后建议补的钉子：一条断言 dev / start / migrate 在同一 projectRoot 下解析出同一个 URL 的测试 —— 这正是现有 dev-default-db.test.ts 只钉住自己那一条、因而没能发现分叉的原因。

复现

# 任一 objectstack app 项目内
objectstack build && objectstack start      # 记下横幅里的 Driver 路径
# 另一个终端
os migrate plan                             # 报告全量 create_table
ls .objectstack/data/                       # 多出一个空的 standalone.db

发现于 hotcrm 升级到 17.0.0-rc.5 时（objectstack-ai/hotcrm#1056）走 MAINTENANCE.md §3.1 的升级后漂移检查。仅记录，未认领。

[os-zhuang]

Triage: pm:queue · domain:cli · target:v17

Classification — concrete defect, named landing sites, scripted repro ⇒ auto-queue. Nothing here needs a maintainer ruling: the three fallbacks disagree with each other, and no reading of the product makes that intentional. The fix shape (converge on one resolver, keep the other two filenames readable for compatibility) is engineering judgment for the dev, not a product call.

Routing — every landing site is in packages/cli + packages/runtime ⇒ domain:cli (both packages sit on the domain:cli row of the SKILL domain table). Anchors re-read on origin/main (eb7613c), not in the shared worktree:

claim	verified on origin/main
os dev → dev.db	packages/cli/src/commands/dev.ts:37 export function resolveDefaultDevDbUrl(, consumed at dev.ts:301
os start → objectstack.db	packages/cli/src/commands/start.ts:193 ?? \file:${path.join(homeDir, 'data', 'objectstack.db')}``
os migrate * → standalone.db	packages/runtime/src/standalone-stack.ts:338 and :340 — the project-root branch is .objectstack/data/standalone.db. Line drift only: the body cites :222; the function now sits ~116 lines lower. Same file, same function, claim intact.
occupancy guard premise	packages/cli/src/utils/sqlite-occupancy.ts:9 still carries the .objectstack/data/standalone.db comment verbatim ⇒ the second-order finding stands as written

Stale-premise check: the defect is live on origin/main. All four anchors resolve; no merge has converged the three fallbacks.

Dedup — searched all three repos (open issues and open PRs) for standalone.db, resolveDatabaseUrl, "default database". One neighbour, not a duplicate: #6345 (pm:queue / domain:cli) covers divergence of the explicit driver selection (--database-driver / OS_DATABASE_DRIVER) between the CLI and the standalone stack. This card covers divergence of the default database URL when nothing is set — a different axis of the same resolver. No open PR touches either file. Both cards land in packages/cli/src/commands/* and packages/runtime/src/standalone-stack.ts, so serialize them (same-file collision), and whichever lands second should re-read the other's resolver rather than adding a third.

target:v17 — blocking. Criterion ④: docs/MAINTENANCE.md §3.1 is the documented post-upgrade check, and following it on a healthy install reports "22 tables to create". The failure direction is inverted — it does not hide a problem, it invents one, and the documented next step for an operator who believes it is to roll back a database that is fine. The dry-run write side effect (an empty standalone.db appears on disk) makes the false report look more authoritative on the second run, not less.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

PM 分诊(domain:cli 席,会话 session_017uFVNMmTxLpmfQYiuKM1Yx):事实无争议,但收敛方案需要维护者拍板 —— 转 needs-user-decision,不派发。

缺陷本身不需要讨论:一个自称 dry-run 的命令既报告了反方向的假事实(真相零漂移,输出「22 张表全部待创建」),又在磁盘上留下了写副作用(它自己刚建的空库)。照 MAINTENANCE.md §3.1 走的操作者,下一步最可能去回滚一个没坏的东西。这条该修。

不派发的原因是修复路径上有一个用户可见的兼容性岔口,而开发 agent 无权替维护者选:

岔口 1 —— 统一后的默认文件名取哪个? 三个命令今天各写死一个(dev.db / objectstack.db / standalone.db),且落在同一目录。选任何一个,另外两个的存量本地环境在升级后都会指向一个不存在的新文件,于是看到一个空库 —— 表现和「数据没了」无法区分。这正是 issue 正文自己点出的「不能表现为数据丢失」。

岔口 2 —— 存量文件怎么处置? 正文列了两条,代价完全不同:

• 兼容读取:新逻辑找不到统一名时,回退去读旧名。零操作成本,但把三分叉变成「一主两备」,分叉并没有真正消失,sqlite-occupancy.ts 那类配套逻辑仍要面对多个候选;
• 迁移提示:检测到旧文件就停下来告诉操作者怎么办。真正收敛,但引入一次交互式中断,且要决定 os migrate 在非交互(CI)下的行为。

岔口 3(顺带,正文也提了) —— --database-url 是否接受 sqlite://。现在只认 file:,报错信息本身合格,但 sqlite:// 大概是这个场景下最自然的猜测。这条可以独立决定。

我的倾向(供参考,不替代裁定):优先读 objectstack.config.ts 声明的数据源是三条路径都缺的那一环,这半边没有岔口,可以先落;默认文件名的统一与存量处置是另一半,等裁定。若维护者认可这个切法,我可以把它拆成两张卡,把无争议的那半立刻派出去。

二阶事实一并记录,供裁定时参考:packages/cli/src/utils/sqlite-occupancy.ts:9 的动机注释把「pnpm dev 持有 standalone.db」写成了「压倒性常见」的主场景,而默认路径下 os dev 持有的是 dev.db —— 该守卫在它自己描述的主场景里不可能触发。#3917 的这套检测是否要跟着一起收敛,属于同一次裁定的范围。

---

Generated by Claude Code

[os-project-manager]

维护者裁定落地(2026-08-08,cli 席存档)—— 三岔口全部裁定,needs-user-decision 摘除,卡转可派

1. 统一默认文件名:objectstack.db。 os start(服务进程)已在用它;服务库是另两个命令理应对齐的地面真相。
2. 存量文件处置:兼容读取 + 一行响亮提示,不做交互式中断(CI 非交互安全)。统一名不存在而旧名(dev.db / standalone.db)存在时,读旧文件并明示正在读哪个、如何迁移;存量环境不得表现为数据丢失。
3. --database-url 接受 sqlite:// 作为 file: 别名(归一化;对真正不支持的 scheme,报错文案保持精确)。

实施范围按 issue 的修复方向:三条 fallback 收敛到一个共享解析函数,优先读 objectstack.config.ts 声明的数据源,再走统一 fallback;补「dev / start / migrate 在同一 projectRoot 解析出同一 URL」的钉子测试;sqlite-occupancy.ts:9 的动机注释按新现实更新(统一后其描述的主场景重新成立)。

派发将于配额窗口重置(07:20Z)后执行。

---

Generated by Claude Code

[os-project-manager]

CLAIM — dev agent, session session_017uFVNMmTxLpmfQYiuKM1Yx, branch claude/issue-6469-unified-db-resolution.

按 2026-08-08 维护者裁定(comment 5225112344)实施:统一默认库名 objectstack.db、共享解析函数(显式 URL/env → objectstack.config.ts 数据源 → 统一默认)、旧库兼容读取 + 响亮提示(无交互中断)、sqlite:// 归一化为 file:、三命令同 URL 钉子测试、sqlite-occupancy.ts 注释更新。

---

Generated by Claude Code