qiyu-cli 0.2.2 → 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.
- package/README.md +156 -84
- package/dist/commands/api-notes.js +16 -0
- package/dist/commands/api.js +60 -14
- package/dist/commands/auth.js +1 -1
- package/dist/commands/db.js +58 -19
- package/dist/commands/query.js +25 -8
- package/dist/commands/stats.js +22 -4
- package/dist/commands/store-precheck.js +72 -5
- package/dist/commands/store.js +46 -11
- package/dist/commands/sync-notes.js +13 -6
- package/dist/commands/sync-run.js +28 -6
- package/dist/commands/sync.js +56 -12
- package/dist/core/config.js +6 -0
- package/dist/core/edition.js +1 -1
- package/dist/core/http.js +24 -2
- package/dist/core/registry/index.js +10 -0
- package/dist/core/registry/specs.json +2 -2
- package/dist/output.js +11 -1
- package/dist/query/sandbox.js +19 -1
- package/dist/store/duckdb.js +1500 -59
- package/dist/store/object-kinds.js +32 -0
- package/dist/store/retry.js +98 -3
- package/dist/store/schema.js +6 -1
- package/dist/sync/engine.js +209 -39
- package/dist/sync/registry.js +3 -1
- package/dist/sync/tasks/pace.js +27 -0
- package/dist/sync/write-contract.js +32 -0
- package/package.json +2 -2
package/dist/commands/db.js
CHANGED
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
import { resolveStoreConfig, currentStoreEnv } from '../store/config.js';
|
|
21
21
|
import { openSandbox, withTimeoutHint } from '../query/sandbox.js';
|
|
22
22
|
import { timeShapeClauses } from '../query/time-shape.js';
|
|
23
|
-
import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing, storeTablesWarnings } from './store-precheck.js';
|
|
23
|
+
import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing, storeTablesWarnings, OBJECT_KINDS_SQL, nonBaseTables, nonBaseTablesWarning, sameObjectName, catalogRows, } from './store-precheck.js';
|
|
24
24
|
import { suggestNames, thrownToQueryExit, missingTableCauses } from '../query/errors.js';
|
|
25
25
|
import { TABLES, tableByName } from '../store/schema.js';
|
|
26
26
|
import { msToShanghaiIso } from '../core/time.js';
|
|
@@ -30,7 +30,8 @@ import { describeFieldNotes, tablesFieldNotes } from './db-notes.js';
|
|
|
30
30
|
import { GLOBAL_FLAGS, helpArgsError, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS, STORE_FLAGS } from './spec-types.js';
|
|
31
31
|
/**
|
|
32
32
|
* 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu db …` 是否真的存在。
|
|
33
|
-
* `flags` 是**完整接受集**(含全局 flag
|
|
33
|
+
* `flags` 是**完整接受集**(含全局 flag);`rejected` 直接取 `REJECTED_FLAGS`(当前为空 ——
|
|
34
|
+
* `--pretty` 自 2026-10-24 G1 起已实现,不再是 rejected,见 `spec-types.ts` 顶部)。
|
|
34
35
|
* 值位解析走共享的 `parseStoreFlags`(它从 `STORE_FLAGS` 派生接受集),与这里同源。
|
|
35
36
|
*/
|
|
36
37
|
export const DB_SPECS = [
|
|
@@ -215,12 +216,15 @@ export async function openGuardedSession(flags, probeTimeoutHint) {
|
|
|
215
216
|
// 口径与实际表集查询一致:限定 table_schema='main'(别库同名表不算数)。
|
|
216
217
|
// ⚠️ 成因分形与文案走 `store-precheck.ts` 的 `schemaVersionMissing`(**唯一实现点**,
|
|
217
218
|
// 2026-10-31 收敛;此前 store/db/sync 三份已漂移出不同说法)。
|
|
218
|
-
|
|
219
|
-
|
|
219
|
+
// ⚠️ 经 `catalogRows`(不是裸 `metaHint.run`):目录超过沙箱缺省 1000 行时,那只是
|
|
220
|
+
// **截断页**;被挤掉的对象仍存在,据此判定「缺表 / 他人库」就是假归因。该 SQL 无
|
|
221
|
+
// `ORDER BY`,谁在首页不是契约。
|
|
222
|
+
const tables = await catalogRows(metaHint, "SELECT table_name FROM information_schema.tables WHERE table_schema='main'");
|
|
223
|
+
const names = tables.map((r) => String(r.table_name));
|
|
220
224
|
// ⚠️ 表名不是身份证明(2026-11-07 审查实测):别的工具也会建叫 schema_version 的表。
|
|
221
225
|
// 只有该表在场时才补查列名 —— 零表/无该表时 `schemaVersionMissing` 不需要它。
|
|
222
|
-
const versionColumns = names.
|
|
223
|
-
? (await metaHint
|
|
226
|
+
const versionColumns = names.some((n) => sameObjectName('schema_version', n))
|
|
227
|
+
? (await catalogRows(metaHint, SCHEMA_VERSION_COLUMNS_SQL)).map((r) => String(r.column_name))
|
|
224
228
|
: undefined;
|
|
225
229
|
const missing = schemaVersionMissing(config.path, names, versionColumns);
|
|
226
230
|
if (missing !== null) {
|
|
@@ -262,20 +266,32 @@ async function dbTables(argv) {
|
|
|
262
266
|
const session = withTimeoutHint(opened.session, metadataTimeoutHint(storeLocationOf(opened.dbPath, opened.profileFlag)));
|
|
263
267
|
try {
|
|
264
268
|
// 实际表集 → 与声明比对(spec §8.1「声明与实况的差异不得静默」)。
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
269
|
+
// ⚠️ 同时取**对象类型**(2026-11-14,PR #74 合并后自查):`information_schema.tables` 把
|
|
270
|
+
// view 也算作表,而下面按声明名逐表 `SELECT COUNT(*)` 会把同名 view 的本体当查询执行
|
|
271
|
+
// (实测:view 底表被删 → `query_error`、退出码 2;store 连接封锁外部访问后
|
|
272
|
+
// `read_csv_auto` 类 view 同样整条失败)。这与 `store status` 的口径必须一致:
|
|
273
|
+
// 只数基表,非基表进 warnings(`nonBaseTablesWarning` 是唯一渲染点)。
|
|
274
|
+
const actual = await catalogRows(session, OBJECT_KINDS_SQL);
|
|
275
|
+
const actualNames = actual.map((r) => String(r.table_name));
|
|
276
|
+
const nonBase = nonBaseTables(actual);
|
|
277
|
+
// 声明名 → 库内实际名(DuckDB 标识符大小写不敏感,Codex PR#76:`"SCHEMA_VERSION"` 就是
|
|
278
|
+
// `schema_version` 本身)。下面 COUNT 用声明的名字(解析器照样能解析到),只在映射处用。
|
|
279
|
+
const actualNameOf = (declared) => actualNames.find((n) => sameObjectName(n, declared));
|
|
280
|
+
const actualSet = new Set(actualNames.filter((n) => !nonBase.some((x) => sameObjectName(n, x))));
|
|
268
281
|
// ⚠️ 两半漂移的 warning 走 `storeTablesWarnings`(**唯一渲染点**,2026-11-02 收敛):
|
|
269
282
|
// 此前本命令自己拼「声明有而库中无」+ `missingTableCauses`,而 `store status`/`init`
|
|
270
283
|
// 只拼「库中有而声明无」—— 同一库两种漂移,两条命令各报一半,缺表那半在 store 上
|
|
271
284
|
// 静默。这里与 store 现在共用同一个渲染器,`declaredMissing` 也不再单独算。
|
|
272
|
-
const warnings =
|
|
285
|
+
const warnings = [
|
|
286
|
+
...(storeTablesWarnings(actualNames, opened.dbPath, opened.profileFlag) ?? []),
|
|
287
|
+
...(nonBaseTablesWarning(nonBase) ?? []),
|
|
288
|
+
];
|
|
273
289
|
// 实际列集一次查全库(25 次往返 → 1 次):时间列被删的表不能让 timeRangeOf 的
|
|
274
290
|
// `MIN("c")` 在 prepare 期抛 Binder Error 把整命令打成退出码 2(Task 7 审查
|
|
275
291
|
// Important #1)——缺列降级为 time_range null + warning。
|
|
276
|
-
const colRows = await session
|
|
292
|
+
const colRows = await catalogRows(session, "SELECT table_name, column_name FROM information_schema.columns WHERE table_schema='main'");
|
|
277
293
|
const columnsOf = new Map();
|
|
278
|
-
for (const row of colRows
|
|
294
|
+
for (const row of colRows) {
|
|
279
295
|
const tableName = String(row.table_name);
|
|
280
296
|
const columnName = String(row.column_name);
|
|
281
297
|
const set = columnsOf.get(tableName);
|
|
@@ -284,10 +300,20 @@ async function dbTables(argv) {
|
|
|
284
300
|
else
|
|
285
301
|
set.add(columnName);
|
|
286
302
|
}
|
|
303
|
+
// 声明表 → 库内该表**基表**的列集(2026-11-15):同名 view 的列在这里**不算**该表的
|
|
304
|
+
// 列 —— 否则一条列名恰好相同的 view 会让「缺列」warning 静默。取不到就返 undefined,
|
|
305
|
+
// 由调用方跳过逐列核对(该名字已由 `nonBaseTablesWarning` 点名),不报假漂移。
|
|
306
|
+
const baseColumnsOf = (declared) => {
|
|
307
|
+
const actual = actualNameOf(declared);
|
|
308
|
+
if (actual === undefined || !actualSet.has(actual))
|
|
309
|
+
return undefined;
|
|
310
|
+
return columnsOf.get(actual);
|
|
311
|
+
};
|
|
287
312
|
// 逐表:行数 + 时间范围;清单与顺序以 TABLES 为权威(裁决 R4:缺表的表整条跳过)。
|
|
288
313
|
const tables = [];
|
|
289
314
|
for (const t of TABLES) {
|
|
290
|
-
|
|
315
|
+
const actualName = actualNameOf(t.name);
|
|
316
|
+
if (actualName === undefined || !actualSet.has(actualName))
|
|
291
317
|
continue;
|
|
292
318
|
const r = await session.run(`SELECT COUNT(*) AS n FROM "${t.name}"`);
|
|
293
319
|
// ⚠️ COUNT 是 BIGINT,经 getRowObjectsJson() 是**字符串** —— 必须 Number() 收敛。
|
|
@@ -298,7 +324,7 @@ async function dbTables(argv) {
|
|
|
298
324
|
// 而 describe 才有的逐列核对在 tables 清单里缺失就是静默漂移。列集已在上面
|
|
299
325
|
// 一次查全库(columnsOf),这里只做集合差,不加往返。
|
|
300
326
|
const declaredCols = new Set(t.columns.map((c) => c.name));
|
|
301
|
-
const actualCols =
|
|
327
|
+
const actualCols = baseColumnsOf(t.name) ?? new Set();
|
|
302
328
|
// 时间列缺了由下面那条专门警告说明(它还要解释 time_range 为何置 null),
|
|
303
329
|
// 这里排除它,避免同一事实说两遍。
|
|
304
330
|
const missingCols = [...declaredCols].filter((n) => !actualCols.has(n) && n !== t.timeColumn?.name);
|
|
@@ -395,10 +421,20 @@ async function dbDescribe(argv) {
|
|
|
395
421
|
// 超时 hint 换成元数据命令的说法(本命令没有可调过滤参数,query 那句对它是死路)。
|
|
396
422
|
const session = withTimeoutHint(opened.session, metadataTimeoutHint(storeLocationOf(opened.dbPath, opened.profileFlag)));
|
|
397
423
|
try {
|
|
398
|
-
// 表名来自 `TABLES` 闭集(代码内常量),拼进字面量安全;用户输入只用于上面的闭集查找。
|
|
399
|
-
const present = (await session.run(`SELECT 1 FROM information_schema.tables WHERE table_schema='main' AND table_name='${table.name}'`))
|
|
400
|
-
.rows.length > 0;
|
|
401
424
|
const warnings = [];
|
|
425
|
+
// ⚠️ 与 `db tables` / `store status` 同口径(2026-11-15):同名对象不是基表(view 等)就
|
|
426
|
+
// **不执行它** —— 只出声明元数据、由 warnings 点名。此前只看表名在不在,一条底表已删的
|
|
427
|
+
// `daily_overview` view 会让 `COUNT(*)` 执行 view → Catalog Error → 整条命令退出 2,
|
|
428
|
+
// 报文还把 view 定义里的底表名说成「表不存在」。
|
|
429
|
+
const kinds = await catalogRows(session, OBJECT_KINDS_SQL);
|
|
430
|
+
const present = kinds.some((r) => sameObjectName(String(r.table_name), table.name));
|
|
431
|
+
const isNonBase = nonBaseTables(kinds).some((n) => sameObjectName(table.name, n));
|
|
432
|
+
if (isNonBase) {
|
|
433
|
+
warnings.push(`表 ${table.name} 在库中不是基表(view 等),本命令未执行它:以下为声明元数据`
|
|
434
|
+
+ '(row_count/time_range 无法得知,置 null)。用 `'
|
|
435
|
+
+ dbTablesCommand(storeLocationOf(opened.dbPath, opened.profileFlag))
|
|
436
|
+
+ '` 确认该名字实际是什么对象');
|
|
437
|
+
}
|
|
402
438
|
let rowCount = null;
|
|
403
439
|
let timeRange = null;
|
|
404
440
|
if (!present) {
|
|
@@ -410,6 +446,9 @@ async function dbDescribe(argv) {
|
|
|
410
446
|
warnings.push(`表 ${table.name} 在库中不存在(声明有而库中无);以下为声明元数据`
|
|
411
447
|
+ '(row_count/time_range 无法得知,置 null)。' + missingTableCauses(opened.dbPath, opened.profileFlag));
|
|
412
448
|
}
|
|
449
|
+
else if (isNonBase) {
|
|
450
|
+
// 上面已点名、row_count/time_range 保持 null —— 只出声明元数据
|
|
451
|
+
}
|
|
413
452
|
else {
|
|
414
453
|
const r = await session.run(`SELECT COUNT(*) AS n FROM "${table.name}"`);
|
|
415
454
|
// ⚠️ COUNT 是 BIGINT,经 getRowObjectsJson() 是**字符串** —— 必须 Number() 收敛。
|
|
@@ -418,8 +457,8 @@ async function dbDescribe(argv) {
|
|
|
418
457
|
// ⚠️ 必须**先于** timeRangeOf:声明的时间列若已被删,`MIN("c")` 会在 prepare 期
|
|
419
458
|
// 抛 Binder Error 把整命令打成退出码 2,row_count/columns/pii_columns 全丢——
|
|
420
459
|
// 而「时间列被删」只是「列集不一致」的子集,应降级为 warning + time_range null。
|
|
421
|
-
const actual = (await session
|
|
422
|
-
.
|
|
460
|
+
const actual = (await catalogRows(session, `SELECT column_name FROM information_schema.columns WHERE table_schema='main' AND table_name='${table.name}'`))
|
|
461
|
+
.map((row) => String(row.column_name));
|
|
423
462
|
const actualSet = new Set(actual);
|
|
424
463
|
const declaredSet = new Set(table.columns.map((c) => c.name));
|
|
425
464
|
const missing = table.columns.map((c) => c.name).filter((n) => !actualSet.has(n));
|
package/dist/commands/query.js
CHANGED
|
@@ -6,7 +6,8 @@ import { buildCoverageQuery, buildDirtyTimeQuery, buildMinQuery, buildTableQuery
|
|
|
6
6
|
import { openGuardedSession } from './db.js';
|
|
7
7
|
import { queryFieldNotes } from './query-notes.js';
|
|
8
8
|
import { DB_PATH_HELP } from './store-flags.js';
|
|
9
|
-
import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty, syncRunCommand, dbTablesCommand, dbDescribeCommand, syncStatusCommand, queryTableCommand, querySqlCommand, SQL_ARG_REPLACE_NOTE, storeLocationFromFlags, storeLocationOf, } from '../output.js';
|
|
9
|
+
import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty, syncRunCommand, dbTablesCommand, dbDescribeCommand, syncStatusCommand, queryTableCommand, querySqlCommand, SQL_ARG_REPLACE_NOTE, storeInitCommand, storeLocationFromFlags, storeLocationOf, } from '../output.js';
|
|
10
|
+
import { OBJECT_KINDS_SQL, nonBaseTables, sameObjectName, catalogRows } from './store-precheck.js';
|
|
10
11
|
import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, helpArgsError, REJECTED_FLAGS, STORE_FLAGS, valueFlagNames } from './spec-types.js';
|
|
11
12
|
/**
|
|
12
13
|
* `query` 的业务 flag。`--group-by` 标 `repeatable`:可重复给(每次吃一个值)。
|
|
@@ -28,7 +29,8 @@ const QUERY_FLAGS = [
|
|
|
28
29
|
];
|
|
29
30
|
/**
|
|
30
31
|
* 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu query …` 是否真的存在。
|
|
31
|
-
* `flags` 是**完整接受集**(含全局 flag
|
|
32
|
+
* `flags` 是**完整接受集**(含全局 flag);`rejected` 直接取 `REJECTED_FLAGS`(当前为空 ——
|
|
33
|
+
* `--pretty` 自 2026-10-24 G1 起已实现,不再是 rejected,见 `spec-types.ts` 顶部)。
|
|
32
34
|
* `query` 没有位置参数:表名走 `--table <表>` 的**值位**,不是位置参数。
|
|
33
35
|
*/
|
|
34
36
|
export const QUERY_SPECS = [
|
|
@@ -855,14 +857,29 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
855
857
|
// 并照候选去查一张口径完全不同的表。口径与 `stats fields` 一致(同一条 message 形态),
|
|
856
858
|
// hint 补上「声明有而库中无」的两种成因(不得承诺 store init 一定能修)。
|
|
857
859
|
if (tableDef !== undefined) {
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
860
|
+
// ⚠️ 同名对象不是基表也算「不能查」(2026-11-15,与 store status / db describe 同口径):
|
|
861
|
+
// `information_schema` 把 view 也算作表,一条底表已删的同名 view 会一路走到执行、
|
|
862
|
+
// 由 Catalog Error 翻译成「列 stat_date 在库中不存在」,报文把 view 定义里的底表名
|
|
863
|
+
// 说成漂移 —— Agent 会以为是自己选了坏数据,而真正要做的是换新路径重建库。
|
|
864
|
+
const kinds = await catalogRows(session, OBJECT_KINDS_SQL);
|
|
865
|
+
const exists = kinds.some((r) => sameObjectName(String(r.table_name), tableDef.name));
|
|
866
|
+
const nonBase = nonBaseTables(kinds).some((n) => sameObjectName(tableDef.name, n));
|
|
867
|
+
if (!exists || nonBase) {
|
|
861
868
|
return fail({
|
|
862
869
|
code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
|
|
863
|
-
message:
|
|
864
|
-
|
|
865
|
-
|
|
870
|
+
message: nonBase
|
|
871
|
+
? `数据库中同名对象不是基表:${tableDef.name}(view 等,本命令未执行它)`
|
|
872
|
+
: `数据库中缺表:${tableDef.name}(本表在 CLI 的表定义中存在,库里没有)`,
|
|
873
|
+
hint: nonBase
|
|
874
|
+
// 同名 view:`store init` 不会重建它(迁移已跳过),但**换新路径重建库 + sync run**
|
|
875
|
+
// 能;这段渲染与 `sync verify` 的 not_base_table detail 同口径(占位符带替换契约)。
|
|
876
|
+
? '本地同名对象不是基表(view 等),本命令未执行它。若本 CLI 的表已被同名 view 取代:'
|
|
877
|
+
+ '先备份旧库文件,再把 --db 换成新的 .duckdb 路径跑 '
|
|
878
|
+
+ storeInitCommand('<新路径>', opened.profileFlag) + ' 建库、'
|
|
879
|
+
+ syncRunCommand('<新路径>', opened.profileFlag) + ' 重新拉取(把 <新路径> 整段替换成新路径,'
|
|
880
|
+
+ '不要指回出问题的文件);用 `' + dbTablesCommand(openedLoc) + '` 可确认该名字实际是什么对象'
|
|
881
|
+
: missingTableCauses(opened.dbPath, opened.profileFlag) + '。用 `'
|
|
882
|
+
+ dbTablesCommand(openedLoc) + '` 查看库中实际有数据的表',
|
|
866
883
|
});
|
|
867
884
|
}
|
|
868
885
|
}
|
package/dist/commands/stats.js
CHANGED
|
@@ -15,12 +15,14 @@ import { METRIC_CATALOG, REPORT_TABLES, declareMetric } from '../query/metric-ca
|
|
|
15
15
|
import { TABLES } from '../store/schema.js';
|
|
16
16
|
import { openGuardedSession } from './db.js';
|
|
17
17
|
import { DB_PATH_HELP, parseStoreFlags } from './store-flags.js';
|
|
18
|
-
import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty, syncRunCommand, dbTablesCommand, dbDescribeCommand, querySqlCommand, SQL_ARG_REPLACE_NOTE, metadataTimeoutHint, storeLocationFromFlags, storeLocationOf, } from '../output.js';
|
|
18
|
+
import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty, syncRunCommand, dbTablesCommand, dbDescribeCommand, querySqlCommand, SQL_ARG_REPLACE_NOTE, metadataTimeoutHint, storeInitCommand, storeLocationFromFlags, storeLocationOf, } from '../output.js';
|
|
19
|
+
import { OBJECT_KINDS_SQL, nonBaseTables, sameObjectName, catalogRows } from './store-precheck.js';
|
|
19
20
|
import { withTimeoutHint } from '../query/sandbox.js';
|
|
20
21
|
import { GLOBAL_FLAGS, helpArgsError, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS, STORE_FLAGS } from './spec-types.js';
|
|
21
22
|
/**
|
|
22
23
|
* 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu stats …` 是否真的存在。
|
|
23
|
-
* `flags` 是**完整接受集**(含全局 flag
|
|
24
|
+
* `flags` 是**完整接受集**(含全局 flag);`rejected` 直接取 `REJECTED_FLAGS`(当前为空 ——
|
|
25
|
+
* `--pretty` 自 2026-10-24 G1 起已实现,不再是 rejected,见 `spec-types.ts` 顶部)。
|
|
24
26
|
* 位置参数的 `report-tables` 域就是 `REPORT_TABLES` 闭集,校验方据此比对正文里的表名。
|
|
25
27
|
*/
|
|
26
28
|
export const STATS_SPECS = [
|
|
@@ -278,8 +280,24 @@ async function statsFields(argv) {
|
|
|
278
280
|
// 目标表存在性校验(spec §十一「库不存在/缺表 → store_not_initialized、退出码 1」):
|
|
279
281
|
// schema_version 的库结构校验在 openGuardedSession 里已做(E 族共用,口径见 db.ts 的
|
|
280
282
|
// 注释)——这里只补本命令特有的「目标表缺」分支,并给出对 stats 有意义的 hint。
|
|
281
|
-
|
|
282
|
-
|
|
283
|
+
// ⚠️ 与 `query --table` / `store status` 同口径(2026-11-15):同名对象不是基表也不执行 ——
|
|
284
|
+
// 一条底表已删的同名 view 会一路走到 `observeSql`,报「列 payload 不存在」,把 view 定义
|
|
285
|
+
// 里的对象说成漂移(实测)。
|
|
286
|
+
const kinds = await catalogRows(session, OBJECT_KINDS_SQL);
|
|
287
|
+
const exists = kinds.some((r) => sameObjectName(String(r.table_name), table));
|
|
288
|
+
const nonBase = nonBaseTables(kinds).some((n) => sameObjectName(table, n));
|
|
289
|
+
if (nonBase) {
|
|
290
|
+
return fail({
|
|
291
|
+
code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
|
|
292
|
+
message: `数据库中同名对象不是基表:${table}(view 等,本命令未执行它)`,
|
|
293
|
+
hint: '本地同名对象不是基表(view 等),本命令未执行它。若本 CLI 的表已被同名 view 取代:'
|
|
294
|
+
+ '先备份旧库文件,再把 --db 换成新的 .duckdb 路径跑 '
|
|
295
|
+
+ storeInitCommand('<新路径>', opened.profileFlag) + ' 建库、'
|
|
296
|
+
+ syncRunCommand('<新路径>', opened.profileFlag) + ' 重新拉取(把 <新路径> 整段替换成新路径,'
|
|
297
|
+
+ '不要指回出问题的文件)',
|
|
298
|
+
});
|
|
299
|
+
}
|
|
300
|
+
if (!exists) {
|
|
283
301
|
// ⚠️ 不得承诺 store init 一定能修(审查 Important #1,与 db.ts:184-189 同款):
|
|
284
302
|
// init 只重放 `version > MAX(version)` 的迁移,已迁移到最新版后被 DROP 的表
|
|
285
303
|
// **不会**被重建(迁移已跳过,返回 ok 而表仍缺)——那是「成功但无效」的修复。
|
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
import { lstatSync, statSync } from 'node:fs';
|
|
22
22
|
import { fail, storeInitCommand } from '../output.js';
|
|
23
23
|
import { TABLES } from '../store/schema.js';
|
|
24
|
+
import { objectKinds, isBaseTable, sameObjectName } from '../store/object-kinds.js';
|
|
24
25
|
import { missingTableCauses } from '../query/errors.js';
|
|
25
26
|
/**
|
|
26
27
|
* 「库尚未初始化」的恢复命令 hint —— **唯一渲染点**。
|
|
@@ -156,10 +157,13 @@ export function statGuard(path) {
|
|
|
156
157
|
* 没问「这几张是不是本 CLI 的」。
|
|
157
158
|
*/
|
|
158
159
|
export function undeclaredTables(names) {
|
|
160
|
+
// ⚠️ 声明 vs 实际按大小写不敏感比(Codex PR#76 第四轮实测):DuckDB 里 `"SCHEMA_VERSION"`
|
|
161
|
+
// 与 `schema_version` 是同一个对象,精确比较会把它同时报成「声明有而库中无」与
|
|
162
|
+
// 「库中有而声明无」,并给出「重建库」建议。
|
|
159
163
|
const declared = new Set(TABLES.map((t) => t.name));
|
|
160
164
|
// 排序:`information_schema` 不保证顺序,`db tables` 此前自己 `.sort()`、`store`
|
|
161
165
|
// 不排序 —— 同一库两次输出 warnings 顺序不同。统一在唯一实现点排序。
|
|
162
|
-
return names.filter((n) => !declared.
|
|
166
|
+
return names.filter((n) => ![...declared].some((d) => sameObjectName(d, n))).sort();
|
|
163
167
|
}
|
|
164
168
|
/**
|
|
165
169
|
* 「声明有而库中无」的表名(以 `TABLES` 为权威、按声明顺序)。
|
|
@@ -172,8 +176,7 @@ export function undeclaredTables(names) {
|
|
|
172
176
|
* 当成没事的形态:Agent 见 warnings 为空就以为「声明与实况已对齐」。
|
|
173
177
|
*/
|
|
174
178
|
export function declaredMissingTables(names) {
|
|
175
|
-
|
|
176
|
-
return TABLES.map((t) => t.name).filter((n) => !actual.has(n));
|
|
179
|
+
return TABLES.map((t) => t.name).filter((n) => !names.some((a) => sameObjectName(n, a)));
|
|
177
180
|
}
|
|
178
181
|
/**
|
|
179
182
|
* 「库中有而声明无」的 warning 文案 —— **唯一渲染点**(`store init` / `store status` /
|
|
@@ -186,6 +189,65 @@ export function undeclaredTablesWarning(undeclared) {
|
|
|
186
189
|
return [`库中有而声明无:${undeclared.join('、')}。这些表没有元数据声明(可能来自旧版 CLI `
|
|
187
190
|
+ '或其他工具),不出现在 tables 中'];
|
|
188
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
|
+
}
|
|
189
251
|
/**
|
|
190
252
|
* 「声明 vs 实况」两个方向的 `meta.warnings` —— **唯一渲染点**(`store init` /
|
|
191
253
|
* `store status` / `db tables` 三处此前各拼一遍)。
|
|
@@ -208,8 +270,11 @@ export function storeTablesWarnings(names, path, profileFlag) {
|
|
|
208
270
|
/**
|
|
209
271
|
* 查 `schema_version` 表列名的 SQL —— **唯一字符串**(db/store/sync 三个调用点共用,
|
|
210
272
|
* 各自经自己的会话执行;判据本体在 `schemaVersionMissing`)。
|
|
273
|
+
* 列名原样返回(调用方按 `versionColumns` 判),表名匹配交给 DuckDB 解析器 —— 它在
|
|
274
|
+
* 目录表上不区分大小写,`"SCHEMA_VERSION"` 表同样会返回它的列。
|
|
211
275
|
*/
|
|
212
|
-
export const SCHEMA_VERSION_COLUMNS_SQL = "SELECT column_name FROM information_schema.columns WHERE table_schema='main'
|
|
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'";
|
|
213
278
|
/**
|
|
214
279
|
* 库结构校验:已有 `schema_version` → `null`;否则给出**按成因分形**的失败载荷。
|
|
215
280
|
*
|
|
@@ -227,7 +292,9 @@ export const SCHEMA_VERSION_COLUMNS_SQL = "SELECT column_name FROM information_s
|
|
|
227
292
|
* (`openSandbox` 的 session / `openStore` 的 store),关会话是调用方的所有权责任。
|
|
228
293
|
*/
|
|
229
294
|
export function schemaVersionMissing(path, names, versionColumns) {
|
|
230
|
-
|
|
295
|
+
// ⚠️ 存在性同样大小写不敏感(Codex PR#76,与上面列名那条同一理由):库里的
|
|
296
|
+
// `"SCHEMA_VERSION"` 表会被后续按小写名的查询解析到,按精确比较会把它当成「缺表」。
|
|
297
|
+
if (names.some((n) => sameObjectName('schema_version', n))) {
|
|
231
298
|
// ⚠️ 列名比较必须与 DuckDB 的解析规则一致(Codex 2026-11-09 第十三轮 P2,真机实测):
|
|
232
299
|
// `CREATE TABLE schema_version ("VERSION" INTEGER, …)` 反射出 `VERSION`/`Version`,
|
|
233
300
|
// 而 `SELECT MAX(version)` 照样解析成功 —— 旧的小写精确比较会把**可用的库**判成他人库、
|
package/dist/commands/store.js
CHANGED
|
@@ -6,13 +6,14 @@ import { openStore } from '../store/index.js';
|
|
|
6
6
|
import { ok, fail, usageFail, failFromTagged, sanitizeControlChars, setPretty, storeInitCommand, syncRunCommand, describeArgs, } from '../output.js';
|
|
7
7
|
import { classifyOpenFailure, openFailureHint } from '../store/retry.js';
|
|
8
8
|
import { DB_PATH_HELP, parseStoreFlags } from './store-flags.js';
|
|
9
|
-
import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing, nonRegularFileHint, undeclaredTables, storeTablesWarnings, } from './store-precheck.js';
|
|
10
|
-
import { TABLES } from '../store/schema.js';
|
|
9
|
+
import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing, nonRegularFileHint, undeclaredTables, storeTablesWarnings, OBJECT_KINDS_SQL, nonBaseTables, nonBaseTablesWarning, sameObjectName, } from './store-precheck.js';
|
|
10
|
+
import { TABLES, tableByName } from '../store/schema.js';
|
|
11
11
|
import { storeFieldNotes } from './store-notes.js';
|
|
12
12
|
import { GLOBAL_FLAGS, helpArgsError, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS, STORE_FLAGS } from './spec-types.js';
|
|
13
13
|
/**
|
|
14
14
|
* 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu store …` 是否真的存在。
|
|
15
|
-
* `flags` 是**完整接受集**(含全局 flag
|
|
15
|
+
* `flags` 是**完整接受集**(含全局 flag);`rejected` 直接取 `REJECTED_FLAGS`(当前为空 ——
|
|
16
|
+
* `--pretty` 自 2026-10-24 G1 起已实现,不再是 rejected,见 `spec-types.ts` 顶部)。
|
|
16
17
|
*/
|
|
17
18
|
export const STORE_SPECS = [
|
|
18
19
|
{
|
|
@@ -198,6 +199,13 @@ export async function storeCommand(argv) {
|
|
|
198
199
|
message: `不是普通文件:${config.path}`, hint: nonRegularFileHint(false) });
|
|
199
200
|
}
|
|
200
201
|
if (st !== undefined && st.isSymbolicLink() === true) {
|
|
202
|
+
// ⚠️ 这条检查**不是安全边界**(历史审查 PR#4「Symlink checks can be bypassed」复核):
|
|
203
|
+
// `lstat` 与随后 DuckDB 的 `create` 之间仍有 TOCTOU 窗口,能把路径换成链接的进程
|
|
204
|
+
// 同样能直接改写库里内容 —— 那已经是"同一用户权限下的任意文件写",不是本 CLI 能靠
|
|
205
|
+
// 一次 lstat 拦住的威胁。DuckDB 的打开接口没有 `O_NOFOLLOW` 之类的入口,所以这里
|
|
206
|
+
// 只做**防误用**(用户/脚本把 --db 指到链接上时立刻说清楚),并在测试里钉住拒绝行为
|
|
207
|
+
// (tests/commands/store.test.ts 的「--db 是符号链接」用例)。不要把它当成安全承诺写进
|
|
208
|
+
// 文档;真要防篡改,正确做法是给库文件与父目录设权限(0600/0700)。
|
|
201
209
|
return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
|
|
202
210
|
message: `目标是符号链接:${config.path}`, hint: '--db 目标是符号链接,请给出真实路径' });
|
|
203
211
|
}
|
|
@@ -230,12 +238,22 @@ export async function storeCommand(argv) {
|
|
|
230
238
|
// 「两边数量应当一致」就成了假话。未声明的表名进 warnings,不静默丢弃。
|
|
231
239
|
const all = await store.tables();
|
|
232
240
|
const sv = await store.query('SELECT COALESCE(MAX(version),0) AS v FROM schema_version');
|
|
233
|
-
const
|
|
234
|
-
|
|
241
|
+
const declaredNames = TABLES.map((t) => t.name);
|
|
242
|
+
// ⚠️ 同名对象不是基表(view 等)就不算「我们的表」(2026-11-14,PR #74 合并后自查):
|
|
243
|
+
// `store.tables()` 来自 `information_schema`、把 view 也算作表,init 曾把一条 view
|
|
244
|
+
// 列进自己的 tables 清单(实测),而 `store status` / `db tables` 已是「只数基表 +
|
|
245
|
+
// 非基表进 warnings」。三处清单同口径,README 的「两边数量应当一致」才成立。
|
|
246
|
+
// 同样按声明名归位(DuckDB 标识符大小写不敏感:`"TAGS"` view 就是 `tags` 这个名字)。
|
|
247
|
+
const nonBase = nonBaseTables((await store.query(OBJECT_KINDS_SQL)).rows)
|
|
248
|
+
.map((n) => tableByName(n)?.name ?? n);
|
|
249
|
+
const warnings = [
|
|
250
|
+
...(storeTablesWarnings(all, config.path, profileFlag) ?? []),
|
|
251
|
+
...(nonBaseTablesWarning(nonBase) ?? []),
|
|
252
|
+
];
|
|
235
253
|
return ok({ path: config.path, backend: config.backend, config_path: configPath,
|
|
236
254
|
config_exists: configExists,
|
|
237
255
|
schema_version: Number(sv.rows[0]?.v ?? 0),
|
|
238
|
-
tables: all.filter((n) =>
|
|
256
|
+
tables: all.filter((n) => declaredNames.some((d) => sameObjectName(d, n)) && !nonBase.includes(n)) }, warnings.length === 0
|
|
239
257
|
? { field_notes: storeFieldNotes() }
|
|
240
258
|
: { field_notes: storeFieldNotes(), warnings });
|
|
241
259
|
}
|
|
@@ -270,7 +288,7 @@ export async function storeCommand(argv) {
|
|
|
270
288
|
// ⚠️ 成因分形(他人库不引导向 init)在共享实现里,口径与 db/sync 逐字一致。
|
|
271
289
|
// ⚠️ 表名不是身份证明(2026-11-07 审查实测):他人工具的 schema_version 无 version 列时,
|
|
272
290
|
// 旧判据放行,下面的 MAX(version) 抛 Binder Error 落 internal「备份重建」—— 假归因。
|
|
273
|
-
const versionColumns = names.
|
|
291
|
+
const versionColumns = names.some((n) => sameObjectName('schema_version', n))
|
|
274
292
|
? (await store.query(SCHEMA_VERSION_COLUMNS_SQL)).rows.map((r) => String(r.column_name))
|
|
275
293
|
: undefined;
|
|
276
294
|
const missing = schemaVersionMissing(config.path, names, versionColumns);
|
|
@@ -285,22 +303,39 @@ export async function storeCommand(argv) {
|
|
|
285
303
|
// `names` 来自全库 `information_schema`(含未声明表),因此必须按声明集过滤后再 COUNT;
|
|
286
304
|
// 未声明的表名进 warnings(不得静默 —— 与 `db tables` 同口径,README 承诺要报警)。
|
|
287
305
|
const undeclared = new Set(undeclaredTables(names));
|
|
306
|
+
// ⚠️ 只数**基表**(2026-11-14,历史审查 PR#4 复核):`information_schema` 把 view 也算作
|
|
307
|
+
// 表,同名 view 会让 COUNT 执行它的本体(实测 `read_csv_auto` 的 view → IO Error →
|
|
308
|
+
// status 整条退出 1,而「库有漂移只警告」是本命令的承诺)。view/macro 与未声明表一样
|
|
309
|
+
// 进 warnings、不进 tables。
|
|
310
|
+
// ⚠️ 比对大小写不敏感(Codex PR#76 实测):一条 `"TICKETS"` view 会被 `"tickets"` 解析
|
|
311
|
+
// 到并被执行,而元数据里的名字保留原样 —— `Set.has()` 精确比会漏掉它。
|
|
312
|
+
const nonBase = nonBaseTables((await store.query(OBJECT_KINDS_SQL)).rows);
|
|
288
313
|
for (const n of names) {
|
|
289
|
-
if (undeclared.has(n))
|
|
314
|
+
if (undeclared.has(n) || nonBase.some((x) => sameObjectName(n, x)))
|
|
290
315
|
continue;
|
|
316
|
+
// ⚠️ 基表的 COUNT 失败**不**降级成警告(Codex PR#74 第三轮 P1):view 已在上面按类型
|
|
317
|
+
// 排除,所以走到这里的都是基表,数不出来就是真错(磁盘 I/O、库损坏、并发删表)——
|
|
318
|
+
// 按 spec §8.2「DuckDB 执行期错误 → internal / 退出码 1」如实失败。
|
|
319
|
+
// 把这类错误说成 warning + 退出码 0,Agent 会以为拿到的 tables 是完整的。
|
|
291
320
|
tables.push({ name: n, rows: await store.count(n) });
|
|
292
321
|
}
|
|
293
|
-
|
|
322
|
+
// ⚠️ `schema_version` 自己是 view 时**不许求值**(CodeRabbit PR#74):列检查(version 列存在)
|
|
323
|
+
// 会放行,这条 MAX(version) 仍会把 view 本体执行一遍 —— 一个 `CAST('x' AS INTEGER)` 就能
|
|
324
|
+
// 让整条 status 退出 1,把「库有漂移只警告」的承诺打穿。按缺失读,交给 warnings 点名。
|
|
325
|
+
const sv = nonBase.some((x) => sameObjectName('schema_version', x))
|
|
326
|
+
? { rows: [{ v: 0 }] }
|
|
327
|
+
: await store.query('SELECT COALESCE(MAX(version),0) AS v FROM schema_version');
|
|
294
328
|
// ⚠️ 两半漂移都进 warnings,**唯一渲染点**在 `storeTablesWarnings`(2026-11-02 实测修):
|
|
295
329
|
// 此前这里只算「库中有而声明无」,声明表被删时 tables 少了几张却零 warnings ——
|
|
296
330
|
// 同一库上 `db tables` 会警告、`store status` 报 ok 且干净,README 又教 Agent
|
|
297
331
|
// 「数量不等时先读 warnings」,于是 Agent 读到空 warnings 反而确认了「没事」。
|
|
298
332
|
const warnings = storeTablesWarnings(names, config.path, profileFlag);
|
|
333
|
+
const allWarnings = [...(warnings ?? []), ...(nonBaseTablesWarning(nonBase) ?? [])];
|
|
299
334
|
return ok({ path: config.path, backend: config.backend, config_path: configPath,
|
|
300
335
|
config_exists: configExists,
|
|
301
|
-
schema_version: Number(sv.rows[0]?.v ?? 0), tables },
|
|
336
|
+
schema_version: Number(sv.rows[0]?.v ?? 0), tables }, allWarnings.length === 0
|
|
302
337
|
? { field_notes: storeFieldNotes() }
|
|
303
|
-
: { field_notes: storeFieldNotes(), warnings });
|
|
338
|
+
: { field_notes: storeFieldNotes(), warnings: allWarnings });
|
|
304
339
|
}
|
|
305
340
|
catch (e) {
|
|
306
341
|
return thrownToExit(e, profileFlag);
|
|
@@ -165,7 +165,10 @@ export function runFieldNotes() {
|
|
|
165
165
|
+ '报告人类核对接口形态);其余可能只是筛选没命中或空窗本来为空,未必缺数据',
|
|
166
166
|
'tasks[].gaps[].reason': '缺口成因(取值与动作见 README 的 gaps 图例)',
|
|
167
167
|
'tasks[].gaps[].detail': '给人读的说明(本命令是引擎产出的原文)。⚠️ 对丢失档的 reason,'
|
|
168
|
-
+ '这里给出的是丢失规模;其余 reason
|
|
168
|
+
+ '这里给出的是丢失规模;其余 reason 下它只是描述,不代表数据缺失。'
|
|
169
|
+
+ '⚠️ `write_failed` 的 detail 若点名「库里的同名对象不是基表(view 等)」,'
|
|
170
|
+
+ '那是某张声明表已被同名 view 取代:重跑必然再失败,按 detail 给出的'
|
|
171
|
+
+ '「备份旧库 → 换新路径 store init → sync run」重建',
|
|
169
172
|
'tasks[].gaps[].range': '本命令的缺口区间已格式化成 `+08:00` ISO(与 resolved_range 同一套时间解析)。'
|
|
170
173
|
+ '⚠️ `sync status` 的同名字段不是这个形态:那边原样回显 `sync_gaps` 的 epoch 毫秒字符串'
|
|
171
174
|
+ '(引擎落库的存储值)—— 跨命令比较缺口区间前先统一形态',
|
|
@@ -206,7 +209,10 @@ export function statusFieldNotes() {
|
|
|
206
209
|
// `"2026-11-04T02:29:50.268Z"`,是 ISO 8601 UTC 字符串;反而是同条目的 range
|
|
207
210
|
// 才是 epoch 毫秒字符串。两种形态在同一个 gaps[] 元素上并存,必须分开点明。
|
|
208
211
|
'tasks[].gaps[].detail': '给人读的说明(引擎落库的原文)。⚠️ 对丢失档的 reason 它是丢失规模;'
|
|
209
|
-
+ '其余 reason
|
|
212
|
+
+ '其余 reason 下只是描述,不代表数据缺失。'
|
|
213
|
+
+ '⚠️ `write_failed` 的 detail 若点名「库里的同名对象不是基表(view 等)」,'
|
|
214
|
+
+ '那是某张声明表已被同名 view 取代:重跑必然再失败,按 detail 给出的'
|
|
215
|
+
+ '「备份旧库 → 换新路径 store init → sync run」重建',
|
|
210
216
|
'tasks[].gaps[].recorded_at': '这条缺口被记录的时刻(ISO 8601 UTC `Z` 字符串,如 '
|
|
211
217
|
+ '`2026-11-04T02:29:50.268Z`;落库时间)。⚠️ 它不是缺口所在区间的时间(那看 range —— '
|
|
212
218
|
+ '注意 range 是 epoch 毫秒字符串,两种形态),也不是「现在是否仍缺」的依据 ——'
|
|
@@ -232,16 +238,17 @@ export function verifyFieldNotes() {
|
|
|
232
238
|
return {
|
|
233
239
|
'tasks[].task': '任务 id(与 `sync tasks` 的 id 同源)',
|
|
234
240
|
'tasks[].local_rows': '本地表的行数(COUNT(*)。与 run/status 都不同 —— 那两个命令不报本地行数)。'
|
|
235
|
-
+ '⚠️ 它是当前行数:与上游不符只说明数量对不上,不说明哪几行错了(row-level
|
|
241
|
+
+ '⚠️ 它是当前行数:与上游不符只说明数量对不上,不说明哪几行错了(row-level 差异不做)。'
|
|
242
|
+
+ '本地同名对象不是基表(view 等)时为 null —— 不执行它、不报数(drift 有 not_base_table)',
|
|
236
243
|
'tasks[].state_windows_consistent': 'true = sync_state 记录为「水位已推进且 range_status=complete」。'
|
|
237
244
|
+ '⚠️ 这不代表数据完整;drift 为空 / 退出码 0 同样不能当完整性证据 —— '
|
|
238
245
|
+ '对 windowed 任务本命令只核对同步状态记录(实测中窗失败的库同样给 drift: [] 且'
|
|
239
246
|
+ '退出码 0),快照任务则另有上游行数核对。windowed 的完整性要另行核对两处:'
|
|
240
247
|
+ 'sync status 的 gaps 与 resolved_range(能否确认新鲜度见该字段的说明),'
|
|
241
248
|
+ '以及 sync run 的 windows.skipped(本命令与 status 都不输出它)',
|
|
242
|
-
'tasks[].expected_from_api': 'null
|
|
243
|
-
+ '
|
|
244
|
-
+ '
|
|
249
|
+
'tasks[].expected_from_api': 'null 有三种成因,看 drift 区分:windowed 任务不做上游全量重拉'
|
|
250
|
+
+ '(成本高,恒为 null);快照任务上游取数失败(drift 有 kind=fetch_failed);'
|
|
251
|
+
+ '本地同名对象不是基表所以没去取上游(drift 有 kind=not_base_table)',
|
|
245
252
|
'tasks[].drift[].kind': '取值与动作见 README 的 drift 图例',
|
|
246
253
|
'tasks[].drift[].detail': '给人读的中文说明;程序判断请用 kind',
|
|
247
254
|
};
|