qiyu-cli 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +433 -72
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +70 -0
  4. package/dist/commands/api.js +169 -49
  5. package/dist/commands/auth.js +151 -29
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +165 -127
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +449 -61
  11. package/dist/commands/skill.js +445 -51
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +160 -33
  14. package/dist/commands/store-flags.js +18 -0
  15. package/dist/commands/store-notes.js +38 -0
  16. package/dist/commands/store-precheck.js +321 -0
  17. package/dist/commands/store.js +165 -77
  18. package/dist/commands/sync-notes.js +374 -0
  19. package/dist/commands/sync-run.js +180 -47
  20. package/dist/commands/sync.js +232 -127
  21. package/dist/core/config.js +280 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +1 -1
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +175 -54
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +36 -2
  29. package/dist/core/registry/params/export.session.check.json +17 -2
  30. package/dist/core/registry/params/export.session.json +24 -2
  31. package/dist/core/registry/params/export.session.one.json +10 -2
  32. package/dist/core/registry/params/export.session.one.message.json +17 -2
  33. package/dist/core/registry/specs.json +65 -43
  34. package/dist/core/shell.js +30 -0
  35. package/dist/core/time.js +1 -1
  36. package/dist/core/validate.js +21 -2
  37. package/dist/output.js +215 -29
  38. package/dist/postinstall.js +14 -5
  39. package/dist/query/errors.js +145 -45
  40. package/dist/query/mask.js +1277 -25
  41. package/dist/query/metric-catalog.js +11 -0
  42. package/dist/query/native-error.js +189 -0
  43. package/dist/query/sandbox.js +148 -25
  44. package/dist/query/table-query.js +36 -5
  45. package/dist/schedule/install.js +136 -13
  46. package/dist/skill/check.js +11 -6
  47. package/dist/skill/detect.js +89 -29
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +29 -5
  51. package/dist/skill/qiyu/errors.md +5 -4
  52. package/dist/skill/qiyu/protocols.md +57 -5
  53. package/dist/skill/qiyu/setup.md +6 -2
  54. package/dist/store/config.js +92 -16
  55. package/dist/store/duckdb.js +1551 -64
  56. package/dist/store/object-kinds.js +32 -0
  57. package/dist/store/retry.js +190 -7
  58. package/dist/store/schema.js +32 -4
  59. package/dist/sync/engine.js +439 -77
  60. package/dist/sync/registry.js +6 -0
  61. package/dist/sync/state.js +20 -0
  62. package/dist/sync/tasks/dim.js +23 -14
  63. package/dist/sync/tasks/knowledge.js +50 -8
  64. package/dist/sync/tasks/pace.js +27 -0
  65. package/dist/sync/tasks/pipeline.js +29 -9
  66. package/dist/sync/tasks/reports.js +176 -49
  67. package/dist/sync/tasks/sessions.js +88 -21
  68. package/dist/sync/tasks/tickets.js +59 -8
  69. package/dist/sync/types.js +60 -1
  70. package/dist/sync/windowing.js +0 -22
  71. package/dist/sync/write-contract.js +79 -0
  72. package/package.json +2 -2
@@ -0,0 +1,321 @@
1
+ // src/commands/store-precheck.ts —— 只读命令的「库前置检查」:**唯一实现点**
2
+ // (2026-10-31,PR #54)。
3
+ //
4
+ // 背景(起因 × 九个命令逐条对照的 E2E 矩阵实测):这套前置检查此前在**三个文件**里
5
+ // 各写了一份 —— `commands/db.ts`(E 族四命令共用)、`commands/sync.ts`(sync 三命令)、
6
+ // `commands/store.ts` 的 status 路径。复制出来的那几份已经漂移,其中一处是**事实错误**:
7
+ // · `store status --db <FIFO>` / `--db /dev/null` 说「**--db 指向的是目录**而非数据库文件」,
8
+ // 而那个路径根本不是目录(`mkfifo`、字符设备实测)—— 判据是 `!isFile()`(覆盖
9
+ // 命名管道 / 设备 / 套接字),文案却按「目录」这一种成因写死;
10
+ // · 同一成因在其余八个命令上是「指向的不是普通文件」—— **同一输入两种说法**,
11
+ // 且前一种把 Agent 引向「我传了个目录」这个不存在的方向;
12
+ // · 「缺 schema_version」同理:`store status` 说「请运行:qiyu store init」,
13
+ // 其余命令说「空库(无任何表)。请先运行:…」。
14
+ // 形态归属:「同一份解码规则复制到多处 → 同一输入两个结论」。
15
+ // 同族前科:`nonEmptyValue` 空串判据(`tests/empty-string-single-source.test.ts`)、
16
+ // profile 名解析(PR #41)、打开失败成因(PR #53)。
17
+ //
18
+ // ⚠️ **本模块只服务只读命令**。`store init` 的前置检查是**另一条规则**(用 `lstatSync`
19
+ // 拒绝符号链接 + 建父目录,出口是「写」),结构不并入此处;它只复用本模块的两条
20
+ // **非普通文件**文案,免得同一成因在 init 与只读命令上说两套话。
21
+ import { lstatSync, statSync } from 'node:fs';
22
+ import { fail, storeInitCommand } from '../output.js';
23
+ import { TABLES } from '../store/schema.js';
24
+ import { objectKinds, isBaseTable, sameObjectName } from '../store/object-kinds.js';
25
+ import { missingTableCauses } from '../query/errors.js';
26
+ /**
27
+ * 「库尚未初始化」的恢复命令 hint —— **唯一渲染点**。
28
+ *
29
+ * 两个产地共用这一句:① 本模块 `statGuard` 的 ENOENT 分支;② `sync-run.ts` 的
30
+ * `storeInitFail` 兜底(store 打开失败但底层没带 hint 时)。两处成因不同、**动作相同**
31
+ * (都是「跑一次 store init」),文案因此也必须同源 —— 各写一份就是下一次漂移的种子
32
+ * (本轮 `store-precheck-single-source.test.ts` 的指纹扫描正是从 `sync-run.ts` 抓到它的)。
33
+ */
34
+ export function storeNotInitializedHint(path) {
35
+ return '数据库尚未初始化。请先运行:' + storeInitCommand(path);
36
+ }
37
+ /** `--db` 指向**目录**时的 hint。 */
38
+ export const DIRECTORY_DB_HINT = '--db 指向的是目录而非数据库文件,请给出 .duckdb 数据库文件路径';
39
+ /**
40
+ * `--db` 指向目录以外的非普通文件(命名管道 / 设备 / 套接字)时的 hint。
41
+ * ⚠️ **不能**与 `DIRECTORY_DB_HINT` 合并成一句:「是目录」对 FIFO 是**假话**,
42
+ * Agent 会去查自己是不是传了目录(它没有),而真正要做的只是换个路径。
43
+ */
44
+ export const NON_REGULAR_DB_HINT = '--db 指向的不是普通文件(命名管道 / 设备 / 套接字等特殊文件),请给出 .duckdb 数据库文件路径';
45
+ /**
46
+ * 非普通文件的 hint —— 按 `stat` 的**实际结果**分形。
47
+ * 判据只问「是不是普通文件」,成因却有两种;把一种当成全部就是本轮修的那个错。
48
+ */
49
+ export function nonRegularFileHint(isDirectory) {
50
+ return isDirectory ? DIRECTORY_DB_HINT : NON_REGULAR_DB_HINT;
51
+ }
52
+ /**
53
+ * `statSync` 失败(ENOENT 之外)的 hint —— **按 errno 分形**。
54
+ *
55
+ * ⚠️ 2026-11-07 审查实测:此前所有非 ENOENT 错误一律说「请检查路径权限」,
56
+ * 而实测 `statSync` 的失败原因至少还有三种,逐字报文(macOS):
57
+ * · `ELOOP: too many symbolic links encountered`(`ln -s loop loop`)
58
+ * · `ENOTDIR: not a directory`(`plain.txt/child`)
59
+ * · `ENAMETOOLONG: name too long`(300 字符路径)
60
+ * 这三种都不是权限问题 —— 让 Agent 去查权限,它会在一个没有权限问题的地方白找一轮。
61
+ * 判据只问「能不能 stat」,成因必须由 errno 说出来。
62
+ * 未归类的 errno 如实说「未专门归类」,不猜成权限。
63
+ */
64
+ export function statFailureHint(errno) {
65
+ switch (errno) {
66
+ case 'EACCES':
67
+ case 'EPERM':
68
+ return '请检查路径权限(只读命令不需要写权限)';
69
+ case 'ELOOP':
70
+ return '路径中存在符号链接成环(ELOOP),stat 无法解析 —— 请改用真实路径,或先修掉循环链接';
71
+ case 'ENOTDIR':
72
+ return '路径中有一段不是目录(ENOTDIR)—— 请检查 --db 的拼写(它可能把文件当成了目录)';
73
+ case 'ENAMETOOLONG':
74
+ return '路径过长(ENAMETOOLONG)—— 请缩短 --db 路径';
75
+ default:
76
+ return `无法访问该路径(errno=${errno ?? '未知'}):本 CLI 只按 errno 归类了权限 / 链接成环 /`
77
+ + '路径中有非目录段 / 路径过长四种,其余请按报文里的系统错误码定位';
78
+ }
79
+ }
80
+ /**
81
+ * 断链符号链接的 hint(`statGuard` 的 ENOENT 分流用);不是断链时返回 `null`。
82
+ *
83
+ * 只读命令对断链必须说「链接目标不存在」,**不得**指向 `store init` ——
84
+ * `store init` 拒绝符号链接(`目标是符号链接,请给出真实路径`),照 hint 执行只会换一句错。
85
+ * `lstat` 本身再失败(父目录不存在等)时同样返回 `null`,交回「路径不存在」原分支。
86
+ */
87
+ function danglingSymlinkHint(path) {
88
+ let lst;
89
+ try {
90
+ lst = lstatSync(path);
91
+ }
92
+ catch {
93
+ return null;
94
+ }
95
+ if (!lst.isSymbolicLink())
96
+ return null;
97
+ return `路径是一个符号链接,但它指向的目标不存在(stat 跟随链接后得到 ENOENT)。`
98
+ + '请改用真实路径,或把链接改指向存在的库;`store init` 不接受符号链接路径,'
99
+ + '照「先运行 store init」执行只会得到第二条错误';
100
+ }
101
+ /**
102
+ * 只读命令的库前置检查(`statSync` 的 ENOENT / 非普通文件 / 其余 errno 三分)。
103
+ * 合格(是一个普通文件)→ `null`,调用方继续打开库。
104
+ *
105
+ * hint 一律指向 `qiyu store init` 的**完整命令**(带本次 `--db` 绝对路径)——
106
+ * 裸命令会作用在默认库上,逐字执行即死循环(`tests/store-hint-selection.test.ts`)。
107
+ */
108
+ export function statGuard(path) {
109
+ let st;
110
+ try {
111
+ st = statSync(path);
112
+ }
113
+ catch (e) {
114
+ if (e.code === 'ENOENT') {
115
+ // ⚠️ 断链符号链接的 `statSync` 也抛 ENOENT(跟随链接后目标不存在),与「路径真的
116
+ // 不存在」在 errno 上无法区分 —— 但两者该给的 hint 相反(2026-11-09 审计实测):
117
+ // 前者说「请运行 store init」,而 `store init` 自己 lstat 出是符号链接、拒绝执行,
118
+ // 用户被两条 hint 锁进死循环。先 lstat 一次分流:lstat 层存在 → 一定是断链。
119
+ const link = danglingSymlinkHint(path);
120
+ if (link !== null) {
121
+ return fail({
122
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
123
+ message: `符号链接指向不存在的目标:${path}`,
124
+ hint: link,
125
+ });
126
+ }
127
+ return fail({
128
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
129
+ message: `数据库文件不存在:${path}`,
130
+ hint: storeNotInitializedHint(path),
131
+ });
132
+ }
133
+ return fail({
134
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
135
+ message: `无法访问 ${path}:${e instanceof Error ? e.message : String(e)}`,
136
+ hint: statFailureHint(e.code),
137
+ });
138
+ }
139
+ if (!st.isFile()) {
140
+ return fail({
141
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
142
+ message: `不是普通文件:${path}`,
143
+ hint: nonRegularFileHint(st.isDirectory()),
144
+ });
145
+ }
146
+ return null;
147
+ }
148
+ /**
149
+ * 库里**本 CLI 未声明**的表名(`TABLES` 之外)。
150
+ *
151
+ * ⚠️ 为什么必须是共享实现(2026-11-01 实测修):`store status` 与 `store init` 都用
152
+ * **全库** `information_schema` 拿表名,但 `store.count()` 内部走 `assertTable` ——
153
+ * 库里有未声明的表时抛 `usage`(`未知表:xxx`,退出码 2),于是 `store status` 在
154
+ * **库恰好有漂移时整条命令失败**(连 `schema_version` 都拿不到)。而 `db tables` 对
155
+ * 同一状态只是把它列进 warnings ——「库中有而声明无」是全仓一致认可**要警告不失败**的
156
+ * 漂移状态(`db tables` 的实现与 README 都这么写)。成因:判据只问了「库里有几张表」,
157
+ * 没问「这几张是不是本 CLI 的」。
158
+ */
159
+ export function undeclaredTables(names) {
160
+ // ⚠️ 声明 vs 实际按大小写不敏感比(Codex PR#76 第四轮实测):DuckDB 里 `"SCHEMA_VERSION"`
161
+ // 与 `schema_version` 是同一个对象,精确比较会把它同时报成「声明有而库中无」与
162
+ // 「库中有而声明无」,并给出「重建库」建议。
163
+ const declared = new Set(TABLES.map((t) => t.name));
164
+ // 排序:`information_schema` 不保证顺序,`db tables` 此前自己 `.sort()`、`store`
165
+ // 不排序 —— 同一库两次输出 warnings 顺序不同。统一在唯一实现点排序。
166
+ return names.filter((n) => ![...declared].some((d) => sameObjectName(d, n))).sort();
167
+ }
168
+ /**
169
+ * 「声明有而库中无」的表名(以 `TABLES` 为权威、按声明顺序)。
170
+ *
171
+ * ⚠️ 为什么必须是共享实现(2026-11-02 实测修):`db tables` / `db describe` 会把它
172
+ * 列进 warnings 并给出成因与对策(`missingTableCauses`),而 `store status` / `store init`
173
+ * 此前只算了「库中有而声明无」那一半 —— 同一库、同一时刻,`db tables` 警告
174
+ * `tickets` 不在,`store status` 却报 `ok` 且零 warnings(README 承诺两边表集一致,
175
+ * 缺表时恰恰不一致,而 Agent 拿到的却是干净的成功)。只说一半漂移是比不说更容易被
176
+ * 当成没事的形态:Agent 见 warnings 为空就以为「声明与实况已对齐」。
177
+ */
178
+ export function declaredMissingTables(names) {
179
+ return TABLES.map((t) => t.name).filter((n) => !names.some((a) => sameObjectName(n, a)));
180
+ }
181
+ /**
182
+ * 「库中有而声明无」的 warning 文案 —— **唯一渲染点**(`store init` / `store status` /
183
+ * `db tables` 共用;`db tables` 走下面的 `storeTablesWarnings`)。
184
+ * 空数组 → `undefined`(不产生 `meta.warnings` 键:该键是**条件键**)。
185
+ */
186
+ export function undeclaredTablesWarning(undeclared) {
187
+ if (undeclared.length === 0)
188
+ return undefined;
189
+ return [`库中有而声明无:${undeclared.join('、')}。这些表没有元数据声明(可能来自旧版 CLI `
190
+ + '或其他工具),不出现在 tables 中'];
191
+ }
192
+ /**
193
+ * 库内对象的**类型**清单 SQL —— 与 `SCHEMA_VERSION_COLUMNS_SQL` 同款:唯一字符串,
194
+ * 由各命令经自己的会话执行,判据本体在下面的纯函数里。
195
+ *
196
+ * ⚠️ 必须查出**元数据里的原样名字**(不是 `lower(table_name)`,Codex PR#76):DuckDB 的
197
+ * 标识符大小写不敏感 —— 引号建的 `"TICKETS"` view 会被 `"tickets"` 解析到(实测
198
+ * `SELECT COUNT(*) FROM "tickets"` 执行的是那个 view),而本 CLI 的表名全是小写。
199
+ * 判据见 `nonBaseTables()`:按「声明 vs 实际」比对,声明名一律小写,所以元数据必须保留原样。
200
+ */
201
+ export const OBJECT_KINDS_SQL = "SELECT table_name, table_type FROM information_schema.tables WHERE table_schema='main'";
202
+ /**
203
+ * 目录类 SQL(`OBJECT_KINDS_SQL` / `SCHEMA_VERSION_COLUMNS_SQL`)经查询沙箱执行时的行数上限 ——
204
+ * **必须显式传**(CodeRabbit + Codex PR#78 实测):`SandboxSession.run` 缺省 `limit: 1000`,
205
+ * 一个 1125 个对象的库会返回 1000 行并置 `truncated: true`(探针实测),于是目标表若排在
206
+ * 截断之后就被误报成「缺表」。10000 是 `run` 允许的最大值;对象数超过它仍会截断,
207
+ * 判定前必须检查 `truncated`(沿 `catalogRows()` 的 fail-closed 处理)。
208
+ *
209
+ * `store.query()`(非沙箱路径)没有行数上限,不需要这个常量。
210
+ */
211
+ export const CATALOG_ROW_LIMIT = 10000;
212
+ /**
213
+ * 目录查询的**唯一读取点**(沙箱路径):显式放大上限,并拒绝在截断结果上做「存不存在 /
214
+ * 是不是基表」的判定 —— 截断页当成完整目录,会把真实存在的表说成缺失(假归因)。
215
+ */
216
+ export async function catalogRows(session, sql) {
217
+ const r = await session.run(sql, { limit: CATALOG_ROW_LIMIT });
218
+ if (r.truncated) {
219
+ throw Object.assign(new Error(`库内对象超过 ${CATALOG_ROW_LIMIT} 个,目录查询被截断,无法可靠判定表是否存在`), { kind: 'internal', retryable: false,
220
+ hint: '请在库侧减少对象数量(例如删除测试用的临时表)后重试;本地库只是缓存,'
221
+ + '换一个 --db 指向新建的库也能绕过' });
222
+ }
223
+ return r.rows;
224
+ }
225
+ /**
226
+ * 从 `OBJECT_KINDS_SQL` 的结果里挑出**不是基表**的对象(view / 外部表等)。
227
+ *
228
+ * ⚠️ 为什么(2026-11-14,历史审查 PR#4 复核实测):`store status` 对全库逐表 COUNT,
229
+ * 而 `information_schema.tables` **把 view 也算作表** —— 一条与声明表同名的 view 会作为
230
+ * `COUNT(*)` 的**本体**以用户权限执行(实测:含 `read_csv_auto(…/probe.csv)` 的 `tags`
231
+ * view 让 status 抛 IO Error、整条命令退出 1,而「库有漂移只警告、不失败」是对外承诺)。
232
+ * 表名匹配 ≠ 对象类型匹配:计数前必须先按类型过滤,不是基表就不执行它。
233
+ *
234
+ * ⚠️ 大小写(Codex PR#76 实测确认):DuckDB 标识符大小写不敏感 —— 一条 `"TICKETS"` view
235
+ * 会在 `COUNT(*) FROM "tickets"` 时被执行,而元数据里的名字是 `TICKETS`、本 CLI 的声明名
236
+ * 全是小写。调用方用**声明名**去比对时(`store status` / `db tables` / `store init` /
237
+ * `sync verify` / `detectForeignStore`),必须用 `sameObjectName()`,不能 `Set.has()` 精确比。
238
+ */
239
+ export function nonBaseTables(rows) {
240
+ return objectKinds(rows).filter((o) => !isBaseTable(o)).map((o) => o.name).sort();
241
+ }
242
+ /** 名字比对的大小写规则唯一实现点在 `store/object-kinds.ts`,此处经上面的 import 再导出。 */
243
+ export { sameObjectName };
244
+ /** 「同名对象不是基表」的警告(空数组 → `undefined`,与 `undeclaredTablesWarning` 同约定)。 */
245
+ export function nonBaseTablesWarning(nonBase) {
246
+ if (nonBase.length === 0)
247
+ return undefined;
248
+ return [`库中有同名对象但不是基表(view 等):${nonBase.join('、')}。这些对象不被计数、`
249
+ + '不出现在 tables 中'];
250
+ }
251
+ /**
252
+ * 「声明 vs 实况」两个方向的 `meta.warnings` —— **唯一渲染点**(`store init` /
253
+ * `store status` / `db tables` 三处此前各拼一遍)。
254
+ *
255
+ * 两半都必须在场:只报「库中有而声明无」会让缺表静默(见 `declaredMissingTables` 的说明)。
256
+ * 缺表那半的成因与对策**不得**自带一份,取 `query/errors.ts` 的 `missingTableCauses()`
257
+ * (与 db/query/stats 四个出口逐字同源 —— tests/missing-table-causes.test.ts 钉着)。
258
+ * 两半都为空 → `undefined`(`meta.warnings` 是条件键)。
259
+ */
260
+ export function storeTablesWarnings(names, path, profileFlag) {
261
+ const warnings = [];
262
+ const missing = declaredMissingTables(names);
263
+ if (missing.length > 0) {
264
+ warnings.push(`声明有而库中无:${missing.join('、')}。这些表不出现在 tables 中。`
265
+ + missingTableCauses(path, profileFlag));
266
+ }
267
+ warnings.push(...(undeclaredTablesWarning(undeclaredTables(names)) ?? []));
268
+ return warnings.length > 0 ? warnings : undefined;
269
+ }
270
+ /**
271
+ * 查 `schema_version` 表列名的 SQL —— **唯一字符串**(db/store/sync 三个调用点共用,
272
+ * 各自经自己的会话执行;判据本体在 `schemaVersionMissing`)。
273
+ * 列名原样返回(调用方按 `versionColumns` 判),表名匹配交给 DuckDB 解析器 —— 它在
274
+ * 目录表上不区分大小写,`"SCHEMA_VERSION"` 表同样会返回它的列。
275
+ */
276
+ export const SCHEMA_VERSION_COLUMNS_SQL = "SELECT column_name FROM information_schema.columns WHERE table_schema='main' "
277
+ + "AND lower(table_name)='schema_version'";
278
+ /**
279
+ * 库结构校验:已有 `schema_version` → `null`;否则给出**按成因分形**的失败载荷。
280
+ *
281
+ * ⚠️ **成因必须分形**:「有表但无 `schema_version`」是**他人库** —— `store init` 会再次
282
+ * 拒绝(`store/duckdb.ts` 的他人库防线),把它一并引导向 `store init` 就是
283
+ * `store init` → 原命令的死循环;「零表」才是 `init` 可补的成因。
284
+ *
285
+ * ⚠️ **表名不是身份证明**(2026-11-07 审查实测):别的工具也会建叫 `schema_version`
286
+ * 的表。探针实测 `schema_version(version_id, applied_at)` 的库:旧判据放行,`store status`
287
+ * 落 internal「存储操作失败(底层:Binder Error: … version not found)」+「备份重建」hint
288
+ * —— 把一个只是**不是本 CLI 的库**说成损坏缓存。调用方用 `SCHEMA_VERSION_COLUMNS_SQL`
289
+ * 查到列名后传 `versionColumns`;**没传**时保持旧判据(不猜)。
290
+ *
291
+ * ⚠️ 返回载荷而不是自己 `fail()`:调用方失败前还得先关掉自己持有的会话
292
+ * (`openSandbox` 的 session / `openStore` 的 store),关会话是调用方的所有权责任。
293
+ */
294
+ export function schemaVersionMissing(path, names, versionColumns) {
295
+ // ⚠️ 存在性同样大小写不敏感(Codex PR#76,与上面列名那条同一理由):库里的
296
+ // `"SCHEMA_VERSION"` 表会被后续按小写名的查询解析到,按精确比较会把它当成「缺表」。
297
+ if (names.some((n) => sameObjectName('schema_version', n))) {
298
+ // ⚠️ 列名比较必须与 DuckDB 的解析规则一致(Codex 2026-11-09 第十三轮 P2,真机实测):
299
+ // `CREATE TABLE schema_version ("VERSION" INTEGER, …)` 反射出 `VERSION`/`Version`,
300
+ // 而 `SELECT MAX(version)` 照样解析成功 —— 旧的小写精确比较会把**可用的库**判成他人库、
301
+ // 挡住全部读命令。反例同样实测过:带空格的 `" version"` / `"version "` 与 `version_id`
302
+ // 确实解析失败,只有大小写变体不可区分。
303
+ if (versionColumns !== undefined
304
+ && !versionColumns.some((c) => c.toLowerCase() === 'version')) {
305
+ return {
306
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
307
+ message: `目标数据库不是本 CLI 创建的(schema_version 表缺少 version 列,`
308
+ + `实际列:${versionColumns.join('、')}):${path}`,
309
+ hint: '目标数据库不是本 CLI 创建的,请换 --db 路径',
310
+ };
311
+ }
312
+ return null;
313
+ }
314
+ return {
315
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
316
+ message: `数据库结构不完整(缺表):${path}`,
317
+ hint: names.length > 0
318
+ ? '目标数据库不是本 CLI 创建的,请换 --db 路径'
319
+ : '空库(无任何表)。请先运行:' + storeInitCommand(path),
320
+ };
321
+ }