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.
- package/README.md +433 -72
- package/dist/cli.js +48 -7
- package/dist/commands/api-notes.js +70 -0
- package/dist/commands/api.js +169 -49
- package/dist/commands/auth.js +151 -29
- package/dist/commands/credentials-source.js +30 -5
- package/dist/commands/db-notes.js +75 -0
- package/dist/commands/db.js +165 -127
- package/dist/commands/query-notes.js +58 -0
- package/dist/commands/query.js +449 -61
- package/dist/commands/skill.js +445 -51
- package/dist/commands/spec-types.js +101 -1
- package/dist/commands/stats.js +160 -33
- package/dist/commands/store-flags.js +18 -0
- package/dist/commands/store-notes.js +38 -0
- package/dist/commands/store-precheck.js +321 -0
- package/dist/commands/store.js +165 -77
- package/dist/commands/sync-notes.js +374 -0
- package/dist/commands/sync-run.js +180 -47
- package/dist/commands/sync.js +232 -127
- package/dist/core/config.js +280 -24
- package/dist/core/credentials.js +38 -4
- package/dist/core/edition.js +1 -1
- package/dist/core/envelope.js +73 -9
- package/dist/core/errors.js +73 -16
- package/dist/core/http.js +175 -54
- package/dist/core/ratelimit.js +5 -1
- package/dist/core/registry/index.js +36 -2
- package/dist/core/registry/params/export.session.check.json +17 -2
- package/dist/core/registry/params/export.session.json +24 -2
- package/dist/core/registry/params/export.session.one.json +10 -2
- package/dist/core/registry/params/export.session.one.message.json +17 -2
- package/dist/core/registry/specs.json +65 -43
- package/dist/core/shell.js +30 -0
- package/dist/core/time.js +1 -1
- package/dist/core/validate.js +21 -2
- package/dist/output.js +215 -29
- package/dist/postinstall.js +14 -5
- package/dist/query/errors.js +145 -45
- package/dist/query/mask.js +1277 -25
- package/dist/query/metric-catalog.js +11 -0
- package/dist/query/native-error.js +189 -0
- package/dist/query/sandbox.js +148 -25
- package/dist/query/table-query.js +36 -5
- package/dist/schedule/install.js +136 -13
- package/dist/skill/check.js +11 -6
- package/dist/skill/detect.js +89 -29
- package/dist/skill/install.js +233 -43
- package/dist/skill/paths.js +54 -0
- package/dist/skill/qiyu/SKILL.md +29 -5
- package/dist/skill/qiyu/errors.md +5 -4
- package/dist/skill/qiyu/protocols.md +57 -5
- package/dist/skill/qiyu/setup.md +6 -2
- package/dist/store/config.js +92 -16
- package/dist/store/duckdb.js +1551 -64
- package/dist/store/object-kinds.js +32 -0
- package/dist/store/retry.js +190 -7
- package/dist/store/schema.js +32 -4
- package/dist/sync/engine.js +439 -77
- package/dist/sync/registry.js +6 -0
- package/dist/sync/state.js +20 -0
- package/dist/sync/tasks/dim.js +23 -14
- package/dist/sync/tasks/knowledge.js +50 -8
- package/dist/sync/tasks/pace.js +27 -0
- package/dist/sync/tasks/pipeline.js +29 -9
- package/dist/sync/tasks/reports.js +176 -49
- package/dist/sync/tasks/sessions.js +88 -21
- package/dist/sync/tasks/tickets.js +59 -8
- package/dist/sync/types.js +60 -1
- package/dist/sync/windowing.js +0 -22
- package/dist/sync/write-contract.js +79 -0
- package/package.json +2 -2
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
// 值导入(不是 type):业务提示类的 reason 名要**逐名**渲染进图例 ——
|
|
2
|
+
// 位置指代(「后四个」)依赖 README 图例表的排列,而那个排列没有守卫(见下方注释)。
|
|
3
|
+
// `sync/types.js` 是纯常量 + 类型模块,无副作用、不引入环。
|
|
4
|
+
import { TASK_GAP_LOSSY_REASONS, TASK_GAP_REASONS } from '../sync/types.js';
|
|
5
|
+
/** 渲染成 `a = 释义;b = 释义` —— field_notes 的单元格形态(与 api list / skill where 同款)。 */
|
|
6
|
+
function renderNotes(notes) {
|
|
7
|
+
return Object.entries(notes).map(([k, v]) => `${k} = ${v}`).join(';');
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* `range_status` 三个取值(含 null)的释义。
|
|
11
|
+
*
|
|
12
|
+
* ⚠️ 两个取值的字面都在撒谎,图例必须把**真实语义**写出来(2026-10-27 实测):
|
|
13
|
+
* · `complete` ≠ 「全窗口成功」(设计稿 §6.1 的原话):引擎每个成功窗都
|
|
14
|
+
* `advanceWatermark`,它无条件写 complete。3 窗中窗失败 → run 报 partial,
|
|
15
|
+
* 而 range_status 仍是 complete。它只说明「水位推进过」。
|
|
16
|
+
* · `pending` ≠ 「一行都没写」:首窗失败时 watermarkRange 为 null,后续成功窗
|
|
17
|
+
* 照常落库但不推水位 → pending 而表里有数据。它只说明「水位没动过」。
|
|
18
|
+
* · `null` = 该任务在 sync_state 里**没有行**(从未跑过,或只跑过被跳过的残段窗)。
|
|
19
|
+
* 所以判「这段数据完整吗」不能只看 `gaps`:`windows.skipped > 0` 时可能 gaps 为空,
|
|
20
|
+
* 但请求区间仍有未覆盖段。必须综合三个判据:
|
|
21
|
+
* 1. 覆盖是否完整?→ `resolved_range.end >= 请求 end` 且 `windows.skipped = 0`
|
|
22
|
+
* 2. 历史缺口是否还成立?→ 把每条 gap 的 range 与请求区间对照;对不上或说不清就写「新鲜度未确认」
|
|
23
|
+
* 3. 空 gaps 是否意味着完整?→ 不一定!若 skipped > 0 或有其他未完成路径,仍是残缺。
|
|
24
|
+
*/
|
|
25
|
+
export const RANGE_STATUS_NOTES = {
|
|
26
|
+
pending: '最近一次运行没有成功推进水位(有可执行窗口的轮次开跑就把状态置 pending,只有成功窗才推回'
|
|
27
|
+
+ ' complete。无可执行窗口的轮次——全部窗都是残段被跳过或被上限丢弃——不置 pending)。'
|
|
28
|
+
+ '⚠️ 三种误读都要避免。① 不代表库里没有数据:首窗失败时后续成功窗照常落库、'
|
|
29
|
+
+ '只是不推水位(实测 3 窗首窗失败 → pending 且表里有 2 行)。② 不代表「从未同步过」:'
|
|
30
|
+
+ '先成功一轮、再跑一轮首窗失败,同样回到 pending 而 watermark 保留着上一轮的值'
|
|
31
|
+
+ '(实测 watermark 仍是上一轮的 1970-01-04)。③ 不代表「正在同步」:运行中的写者会让'
|
|
32
|
+
+ '本命令先退避等待、等到后读到的是那一轮的结果',
|
|
33
|
+
complete: '水位推进过。⚠️ 不代表「全窗口成功」:引擎每个成功窗都写 complete,'
|
|
34
|
+
+ '中窗失败时 run 报 partial 而这里仍是 complete(实测)。判定数据完整要综合三个判据:'
|
|
35
|
+
+ '覆盖范围(resolved_range / windows.skipped)、历史缺口新鲜度(按 range 对照)与'
|
|
36
|
+
+ '空 gaps 的真实含义(skipped > 0 时可能 gaps 为空但仍有未覆盖段)。',
|
|
37
|
+
'null': '该任务在 sync_state 里没有行(从未运行过,或只跑过被跳过的残段窗)。'
|
|
38
|
+
+ '与 pending 不同:pending 至少有 markPending 写过行',
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* `sync run` 的 `status` 三个取值的释义。
|
|
42
|
+
*
|
|
43
|
+
* ⚠️ `partial` 字面是「部分成功」,但它同样覆盖「一行都没落」:windowed 任务的引擎
|
|
44
|
+
* 对「全部窗口都失败」也产出 partial(succeeded: 0),`failed` 只留给连窗口循环都
|
|
45
|
+
* 进不去的异常路径(快照任务的限频闸门拦截)。实测 `tickets.search --since 1d`
|
|
46
|
+
* 全窗失败 → status=partial、windows.succeeded=0、退出码 1。
|
|
47
|
+
*/
|
|
48
|
+
export const RUN_STATUS_NOTES = {
|
|
49
|
+
complete: '没有失败窗口(windows.failed = 0)。⚠️ 它不保证「全部窗口都跑了」:'
|
|
50
|
+
+ 'windows.skipped 可能大于 0(残段窗或整窗晚于末端上限被跳过)。判实际覆盖要看 skipped,'
|
|
51
|
+
+ '见该字段的说明',
|
|
52
|
+
partial: '至少一个窗口失败。⚠️ 它也覆盖「一行都没落」的全窗失败(succeeded=0)——'
|
|
53
|
+
+ '不要按这个字面判断结果。两个字段分开读:windows.succeeded = 成功窗数'
|
|
54
|
+
+ '(空窗也算成功,所以它大于 0 不代表有行)。rows.written = 写入行数'
|
|
55
|
+
+ '(成功窗记实际写入,count_mismatch / write_failed 的失败窗记「应写行数」、已随事务回滚 '
|
|
56
|
+
+ '—— 这两类失败窗存在时它偏大。fetch_failed / rate_limit_local 的失败窗没有应写行数,不计入)',
|
|
57
|
+
failed: '快照任务的失败路径(快照没有窗口循环,所以不会出现 partial):本地限频闸门拦截、'
|
|
58
|
+
+ '上游取数失败、落库失败或行数核对不符。windowed 任务不会给出 failed —— 全窗失败也是'
|
|
59
|
+
+ ' partial(见上一条)',
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* `watermark` 的释义(run 与 status 共用 —— 两个命令的这两列直接取自 `sync_state`,
|
|
63
|
+
* 形态完全相同)。
|
|
64
|
+
*
|
|
65
|
+
* ⚠️ 必须点名**时间形态与相邻字段不一致**(2026-10-28 实测):同一任务条目里
|
|
66
|
+
* `resolved_range` 是 `+08:00` 形态,而 `watermark` 与 `last_synced_at` 是
|
|
67
|
+
* 引擎写库时的 **UTC `Z`** 形态。两者可以表示**同一时刻**:
|
|
68
|
+
* 实测 `watermark: "2025-10-09T08:53:20.000Z"` 与
|
|
69
|
+
* `resolved_range[1]: "2025-10-09T16:53:20+08:00"` 是同一瞬间。
|
|
70
|
+
* 按字符串比较会得出相反结论(`"08:…Z" < "16:…+08:00"`),必须先解析成时刻再比。
|
|
71
|
+
*
|
|
72
|
+
* ⚠️ 只点名 `resolved_range`(两个命令里都是 `+08:00`)。**不写 `gaps[].range`**:
|
|
73
|
+
* 它两个命令形态不同 —— run 格式化成 `+08:00`(sync-run.ts 的 taskOut),status
|
|
74
|
+
* 原样回显 `sync_gaps` 的 epoch 毫秒字符串(sync.ts 的 gap 组装)。共用一段话就会
|
|
75
|
+
* 对其中一个说谎(CodeRabbit 2026-10-28)。那半边由各命令自己的
|
|
76
|
+
* `tasks[].gaps[].range` 图例承担。
|
|
77
|
+
*/
|
|
78
|
+
const WATERMARK_NOTE = '上次成功推进到的时间点(引擎写库的原样字符串,UTC `Z` 形态)。'
|
|
79
|
+
+ '⚠️ 与同一行里的 resolved_range(`+08:00` 形态)写法不同:'
|
|
80
|
+
+ '两者可以是同一时刻,直接按字符串比较会得出相反结论 —— 先解析成时刻再比。'
|
|
81
|
+
+ 'null = 从未成功推进(或 v9 之前的旧记录)';
|
|
82
|
+
/**
|
|
83
|
+
* `last_synced_at` 的释义(run 与 status 共用 —— 同一份 `sync_state` 列)。
|
|
84
|
+
*
|
|
85
|
+
* ⚠️ 三点必须说清(2026-10-28 真库实测 + CodeRabbit 复核):
|
|
86
|
+
* 1) 它与 watermark 不是同一个量:watermark 是「数据覆盖到哪」(数据面的位置),
|
|
87
|
+
* 它是「那次成功提交发生在什么时候」(运行面的时间)。
|
|
88
|
+
* 2) 它按**成功窗**更新、不按轮:引擎在每个带水位写入的成功窗提交事务里写它
|
|
89
|
+
* (engine.ts 的 commitWindow → advanceWatermark)。所以一轮里有部分窗口失败
|
|
90
|
+
* (status=partial)时它照样被更新 —— 实测中窗失败(1、3 成,2 败)→
|
|
91
|
+
* status=partial 而它已是末个成功窗的提交时刻。
|
|
92
|
+
* 3) 它也**不严格等于「水位值上次前进的时刻」**:断链后的成功窗仍刷新它,而水位
|
|
93
|
+
* 冻结在连续成功末端 —— 实测同一轮里 watermark 停在首窗末端(1970-01-02)、
|
|
94
|
+
* last_synced_at 却是末窗提交时刻(晚 3 分多)。所以它可能晚于水位实际前进的时刻。
|
|
95
|
+
* 「整轮没有任何带水位写入的成功提交」才不动它:首窗即失败(后续成功窗不再写水位)、
|
|
96
|
+
* 全窗失败、快照失败、窗口全是被跳过的残段窗 —— 保留上一轮的值(从未推进过则 null)。
|
|
97
|
+
* 早前这里写的是「失败轮不更新它」,对 partial 轮是错的。
|
|
98
|
+
*/
|
|
99
|
+
const LAST_SYNCED_AT_NOTE = '上次成功提交同步事务的时刻(UTC `Z` 形态 —— 引擎在每个带水位写入的成功窗里写它,不是整轮跑完才写)。'
|
|
100
|
+
+ '⚠️ 与 watermark 是两个不同的量:watermark 是「数据覆盖到哪」,它是「那次提交发生在什么时候」。'
|
|
101
|
+
+ '⚠️ 一轮里有部分窗口失败(status=partial)时它照样会被更新(实测:中窗失败 → partial 而它已是末个成功窗的提交时刻)。'
|
|
102
|
+
+ '⚠️ 它也可能晚于水位实际前进的时刻:断链后的成功窗仍刷新它,而水位冻结在连续成功末端(实测同一轮里两者相差数分钟)'
|
|
103
|
+
+ '只有整轮没有任何带水位写入的成功提交(首窗即失败 / 全窗失败 / 快照失败 / 窗口全是被跳过的残段窗)'
|
|
104
|
+
+ '才保留上一轮的值(从未推进过则 null)';
|
|
105
|
+
/** `sync run` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。 */
|
|
106
|
+
export function runFieldNotes() {
|
|
107
|
+
return {
|
|
108
|
+
'tasks[].task': '任务 id(与 `sync tasks` 的 id 同源)',
|
|
109
|
+
'tasks[].status': renderNotes(RUN_STATUS_NOTES),
|
|
110
|
+
// ⚠️ windows / rows 是嵌套对象,此前只解释了 windows.skipped 与 status 里顺带提到的
|
|
111
|
+
// 字段(2026-11-04 反向 sweep 实测:total/succeeded/failed 与 rows.* 全部裸奔)。
|
|
112
|
+
// 这四个数是 Agent 判「这次到底拿到没有」的依据,必须各自可见。
|
|
113
|
+
// ⚠️ 这条释义里不能有换行:`meta.field_notes` 的值是 JSON 字符串,内部换行会让
|
|
114
|
+
// Agent/工具把一句定义读成两段(CodeRabbit 2026-11-11,此前是源码折行残留的 `\n`)。
|
|
115
|
+
'tasks[].windows.total': '本轮计入的窗口总数(= succeeded + failed + skipped)——'
|
|
116
|
+
+ '不含被重叠区合并的窗(那是 contained;物理切出的窗数 = total + contained)',
|
|
117
|
+
'tasks[].windows.succeeded': '成功窗数。⚠️ 空窗也算成功,所以 > 0 不代表有数据 —— 结合 rows.written 与 windows.failed 判断',
|
|
118
|
+
'tasks[].windows.failed': '失败窗数(失败会在 gaps 里逐条记录)',
|
|
119
|
+
'tasks[].windows.skipped': '没跑的窗数,三种成因:① 残段窗(日对齐任务被显式区间钳出的'
|
|
120
|
+
+ '非日界首/末段);② 整窗晚于末端上限被丢弃的窗(windowEndClamp:考勤/绩效请求到'
|
|
121
|
+
+ '「今天」时);③ 覆盖它的那一窗失败了 —— 它原本落在前一窗的回看重叠区、被合并,'
|
|
122
|
+
+ '覆盖窗成功时算 contained,失败时就是「该拉的没拉」,改记 skipped 并逐窗出'
|
|
123
|
+
+ '「须重跑补齐」进度行。三种都跳过不 fetch、不写库、不推水位,但计入 total'
|
|
124
|
+
+ '(total = succeeded + failed + skipped);stderr 进度行按成因逐种点名。'
|
|
125
|
+
+ '⚠️ ③ 出现时本轮 status 必为 partial,看 gaps 找到失败的覆盖窗',
|
|
126
|
+
'tasks[].windows.contained': '完全落进前一窗回看重叠区、被合并的窗数(仅 > 0 时出现)。'
|
|
127
|
+
+ '这些窗不执行 —— 覆盖它的那一窗成功时数据已由那一窗覆盖(overlapDays > 0 的任务,'
|
|
128
|
+
+ '如工单 3 天回看),所以既不是 succeeded 也不是 skipped(skipped 才代表「该拉的没拉」);'
|
|
129
|
+
+ '覆盖窗失败时它们改记 skipped 并逐窗出进度行;'
|
|
130
|
+
+ '它不计入 total —— 物理切出的窗数 = total + contained',
|
|
131
|
+
// ⚠️ 2026-11-04 自查修正:初版把 written 说成「真正落库的行数」—— 而引擎对
|
|
132
|
+
// count_mismatch / write_failed 的失败窗记的是「参与核对的应写行数」(kept),
|
|
133
|
+
// 那批行已随事务回滚、实际没落库(sync/engine.ts 的 catch 分支与 brief 钉死用例)。
|
|
134
|
+
'tasks[].rows.fetched': '本轮进入引擎的行数(fetch 内部投影/丢行之后、enrich 之前)——'
|
|
135
|
+
+ '不是「上游返回的行数」:fetch 侧丢掉的键缺失行不计入这里,它们由 gaps 的 detail 报规模;'
|
|
136
|
+
+ '与 written 不等通常说明有行被本地决策淘汰',
|
|
137
|
+
'tasks[].rows.written': '本轮写入的行数。⚠️ 记法:成功窗记实际写入;count_mismatch / write_failed 的失败窗记'
|
|
138
|
+
+ '「参与核对的应写行数」—— 那批行已随事务回滚、实际没落库(这两类失败窗存在时它偏大;'
|
|
139
|
+
+ 'fetch_failed / rate_limit_local 的失败窗没有应写行数,不计入)。'
|
|
140
|
+
+ '⚠️ 快照任务(tasks[].windows.total 恒为 1)的这两类失败窗记 0 —— 快照失败即整体回滚,'
|
|
141
|
+
+ '没有「部分写入」可言,所以它偏小而不是偏大。'
|
|
142
|
+
+ '为 0 可能是「窗口都成功、只是上游没数据」',
|
|
143
|
+
'tasks[].notes': '本任务的逐条说明(恒在、可为空数组),有意跳过而非故障,看到它不代表本轮失败。'
|
|
144
|
+
+ '来源一:请求区间早于接口下界——把「区间不可得」与「同步故障」分开。'
|
|
145
|
+
+ '来源二:日对齐任务遇到非上海日界的 --until,两档:'
|
|
146
|
+
+ '① 该日不早于末端上限——拉不到,调整 --until 无用,要等上限自然前移(次日)再跑增量;'
|
|
147
|
+
+ '② 其余——末窗是半个自然日、按残段窗跳过(不拉、不写),该日未同步,'
|
|
148
|
+
+ '结果里 complete 与 gaps 为空都不代表这段已同步,要含该日请把 --until 写到次日 0 点。'
|
|
149
|
+
+ '末段有无被跳过看 windows.skipped(残段窗与整窗晚于上限都计入),不要只凭本数组为空判断',
|
|
150
|
+
'tasks[].resolved_range': '本轮请求的水位区间(start = 水位/请求起点语义,'
|
|
151
|
+
+ '日对齐任务的首残段可能被跳过、start 前缀不会自动前移,所以它不是「已覆盖」的保证)。'
|
|
152
|
+
+ '末端与水位同源:出现失败窗后水位冻结在连续成功末端,因此它可能早于你请求的 end。'
|
|
153
|
+
+ '评估真实覆盖要看 end 与 windows.skipped,不要只看 start',
|
|
154
|
+
'tasks[].gaps': '本轮失败/提示的缺口逐条记录(每条的 reason 取值见 README 图例)。'
|
|
155
|
+
+ 'gaps 非空不等于同步失败:'
|
|
156
|
+
// ⚠️ 逐名渲染,不用「后四个」(2026-11-01 审查):位置指代依赖 README 图例表的
|
|
157
|
+
// 排列顺序,而图的顺序**没有**任何守卫(`sync-enums.test.ts` 双向核对用
|
|
158
|
+
// `sort()`,允许重排);且 Agent 读的是 run 输出,手里未必有那张表 ——
|
|
159
|
+
// 「后四个」在它那里无法解析。名字从 `TASK_GAP_REASONS` 渲染,加了值也同步。
|
|
160
|
+
+ TASK_GAP_REASONS.join(' / ') + ' 这些是成功窗上的业务提示(窗口数据照常提交)。'
|
|
161
|
+
// ⚠️ 2026-11-02 审查:「提示」不等于「数据没缺」——把两档合并成一句会让 Agent
|
|
162
|
+
// 低估 `knowledge_row_malformed` / `staff_id_list_malformed`(这些行**确实没落库**,
|
|
163
|
+
// 必须核对上游形态)。丢失档从 `TASK_GAP_LOSSY_REASONS` 渲染,与 README/skill 同源。
|
|
164
|
+
+ `其中 ${TASK_GAP_LOSSY_REASONS.join(' / ')} 描述的行确实没落库(detail 是丢失规模,`
|
|
165
|
+
+ '报告人类核对接口形态);其余可能只是筛选没命中或空窗本来为空,未必缺数据',
|
|
166
|
+
'tasks[].gaps[].reason': '缺口成因(取值与动作见 README 的 gaps 图例)',
|
|
167
|
+
'tasks[].gaps[].detail': '给人读的说明(本命令是引擎产出的原文)。⚠️ 对丢失档的 reason,'
|
|
168
|
+
+ '这里给出的是丢失规模;其余 reason 下它只是描述,不代表数据缺失。'
|
|
169
|
+
+ '⚠️ `write_failed` 的 detail 若点名「库里的同名对象不是基表(view 等)」,'
|
|
170
|
+
+ '那是某张声明表已被同名 view 取代:重跑必然再失败,按 detail 给出的'
|
|
171
|
+
+ '「备份旧库 → 换新路径 store init → sync run」重建',
|
|
172
|
+
'tasks[].gaps[].range': '本命令的缺口区间已格式化成 `+08:00` ISO(与 resolved_range 同一套时间解析)。'
|
|
173
|
+
+ '⚠️ `sync status` 的同名字段不是这个形态:那边原样回显 `sync_gaps` 的 epoch 毫秒字符串'
|
|
174
|
+
+ '(引擎落库的存储值)—— 跨命令比较缺口区间前先统一形态',
|
|
175
|
+
'tasks[].watermark': WATERMARK_NOTE,
|
|
176
|
+
'tasks[].last_synced_at': LAST_SYNCED_AT_NOTE,
|
|
177
|
+
truncated: '恒为 false —— sync run 不按 --limit 截断任务列表(这是与 query 的同名字段'
|
|
178
|
+
+ '语义不同之处,那边才是「只拿到截断样本」)',
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* `sync status` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。
|
|
183
|
+
*
|
|
184
|
+
* ⚠️ 图例键是**指向输出的路径**,不是字段名:`sync status` 的 data 是 `{tasks:[...]}`,
|
|
185
|
+
* 所有字段都挂在任务条目上,所以必须写 `tasks[].x`。早前这里写的是裸字段名
|
|
186
|
+
* (`range_status` / `locked` / `gaps` …)—— 按该路径去 data 里找什么也找不到,
|
|
187
|
+
* 图例等于没有。2026-10-28 修正(同型缺陷:stats 的 `declared[].unit`)。
|
|
188
|
+
*/
|
|
189
|
+
export function statusFieldNotes() {
|
|
190
|
+
return {
|
|
191
|
+
'tasks[].task': '任务 id(与 `sync tasks` 的 id 同源,用它对上任务)',
|
|
192
|
+
'tasks[].range_status': renderNotes(RANGE_STATUS_NOTES),
|
|
193
|
+
'tasks[].watermark': WATERMARK_NOTE,
|
|
194
|
+
'tasks[].last_synced_at': LAST_SYNCED_AT_NOTE,
|
|
195
|
+
'tasks[].locked': 'true = sync_state 里有残留的写者章(上一轮运行被强杀,来不及清)。'
|
|
196
|
+
+ '⚠️ 这不是「正在同步中」:真正持有写锁的进程会让本命令先退避等待'
|
|
197
|
+
+ '(readOnlyRetryMs,默认 30 秒)——等到了说明那一轮已结束、章也清了(返回 false),'
|
|
198
|
+
+ '等不到才报 store_locked。所以看到 true 说明写锁当前是空的、章是残留的,'
|
|
199
|
+
+ '重跑 sync run 即可(引擎会重新盖章)',
|
|
200
|
+
'tasks[].gaps': 'sync_gaps 里的历史缺口。⚠️ 它是历史记录、不等于当前仍缺:成功窗只清它自己那个'
|
|
201
|
+
+ '起点的缺口,换窗口边界重跑不会清掉旧起点的记录——旧记录的 reason 与新记录相同,'
|
|
202
|
+
+ '按 reason 区分不出新旧。range 也只能说明「相关」:换边界重跑后数据可能已补齐,'
|
|
203
|
+
+ '而旧缺口的 range 仍与你要评估的区间重叠。所以没有一次覆盖核对就不能确认新鲜度——'
|
|
204
|
+
+ '报「该区间有历史缺口记录,新鲜度未确认」,不要直接报成当前故障',
|
|
205
|
+
// ⚠️ 缺口元素的 detail / recorded_at 此前没有释义(2026-11-04 反向 sweep 实测)。
|
|
206
|
+
// recorded_at 是**落库时刻**(历史记录的时间戳,不是缺口所在区间的时间)。
|
|
207
|
+
// ⚠️⚠️ 2026-11-04 自查修正:初版写成「epoch 毫秒数」,而落库值是
|
|
208
|
+
// `new Date(...).toISOString()`(sync/state.ts recordGap)—— 实测形态
|
|
209
|
+
// `"2026-11-04T02:29:50.268Z"`,是 ISO 8601 UTC 字符串;反而是同条目的 range
|
|
210
|
+
// 才是 epoch 毫秒字符串。两种形态在同一个 gaps[] 元素上并存,必须分开点明。
|
|
211
|
+
'tasks[].gaps[].detail': '给人读的说明(引擎落库的原文)。⚠️ 对丢失档的 reason 它是丢失规模;'
|
|
212
|
+
+ '其余 reason 下只是描述,不代表数据缺失。'
|
|
213
|
+
+ '⚠️ `write_failed` 的 detail 若点名「库里的同名对象不是基表(view 等)」,'
|
|
214
|
+
+ '那是某张声明表已被同名 view 取代:重跑必然再失败,按 detail 给出的'
|
|
215
|
+
+ '「备份旧库 → 换新路径 store init → sync run」重建',
|
|
216
|
+
'tasks[].gaps[].recorded_at': '这条缺口被记录的时刻(ISO 8601 UTC `Z` 字符串,如 '
|
|
217
|
+
+ '`2026-11-04T02:29:50.268Z`;落库时间)。⚠️ 它不是缺口所在区间的时间(那看 range —— '
|
|
218
|
+
+ '注意 range 是 epoch 毫秒字符串,两种形态),也不是「现在是否仍缺」的依据 ——'
|
|
219
|
+
+ '它只说明这条历史记录是何时写下的',
|
|
220
|
+
'tasks[].gaps[].reason': '取值与动作见 README 的 gaps 图例(与 sync run 的 gaps[].reason 同一组值)',
|
|
221
|
+
'tasks[].gaps[].range': '原样回显 sync_gaps 的存储值(epoch 毫秒字符串),不是 run 输出的'
|
|
222
|
+
+ ' +08:00 ISO 形态 —— 要比较请先按同一形态解析',
|
|
223
|
+
'tasks[].gaps_count': '`gaps` 数组的长度快照(既有消费者用)。与 `gaps` 恒等 —— '
|
|
224
|
+
+ '不确定就用 `gaps.length`,不要把它当成「当前仍缺的条数」',
|
|
225
|
+
'tasks[].resolved_range': '上次成功推进的水位区间。⚠️ start 是水位起点语义、含可能被跳过的首残段'
|
|
226
|
+
+ '前缀(实测:日对齐任务从非日界起点跑 → skipped=2 而 start 仍等于请求起点),'
|
|
227
|
+
+ '所以它不是「已覆盖」的保证;本命令不输出 windows.skipped,判实际覆盖要看 '
|
|
228
|
+
+ 'sync run 的 windows.skipped。null = 尚无成功推进(或 v9 之前的旧记录)',
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
/**
|
|
232
|
+
* `sync verify` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。
|
|
233
|
+
*
|
|
234
|
+
* ⚠️ 图例键是**指向输出的路径**:`sync verify` 的 data 也是 `{tasks:[...]}`,所有字段都挂在任务条目上。
|
|
235
|
+
* 早前写的是裸字段名 (`state_windows_consistent` / `expected_from_api` …) —— 按该路径什么也找不到。
|
|
236
|
+
*/
|
|
237
|
+
export function verifyFieldNotes() {
|
|
238
|
+
return {
|
|
239
|
+
'tasks[].task': '任务 id(与 `sync tasks` 的 id 同源)',
|
|
240
|
+
'tasks[].local_rows': '本地表的行数(COUNT(*)。与 run/status 都不同 —— 那两个命令不报本地行数)。'
|
|
241
|
+
+ '⚠️ 它是当前行数:与上游不符只说明数量对不上,不说明哪几行错了(row-level 差异不做)。'
|
|
242
|
+
+ '本地同名对象不是基表(view 等)时为 null —— 不执行它、不报数(drift 有 not_base_table)',
|
|
243
|
+
'tasks[].state_windows_consistent': 'true = sync_state 记录为「水位已推进且 range_status=complete」。'
|
|
244
|
+
+ '⚠️ 这不代表数据完整;drift 为空 / 退出码 0 同样不能当完整性证据 —— '
|
|
245
|
+
+ '对 windowed 任务本命令只核对同步状态记录(实测中窗失败的库同样给 drift: [] 且'
|
|
246
|
+
+ '退出码 0),快照任务则另有上游行数核对。windowed 的完整性要另行核对两处:'
|
|
247
|
+
+ 'sync status 的 gaps 与 resolved_range(能否确认新鲜度见该字段的说明),'
|
|
248
|
+
+ '以及 sync run 的 windows.skipped(本命令与 status 都不输出它)',
|
|
249
|
+
'tasks[].expected_from_api': 'null 有三种成因,看 drift 区分:windowed 任务不做上游全量重拉'
|
|
250
|
+
+ '(成本高,恒为 null);快照任务上游取数失败(drift 有 kind=fetch_failed);'
|
|
251
|
+
+ '本地同名对象不是基表所以没去取上游(drift 有 kind=not_base_table)',
|
|
252
|
+
'tasks[].drift[].kind': '取值与动作见 README 的 drift 图例',
|
|
253
|
+
'tasks[].drift[].detail': '给人读的中文说明;程序判断请用 kind',
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
/** `sync tasks` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。 */
|
|
257
|
+
export function tasksFieldNotes() {
|
|
258
|
+
return {
|
|
259
|
+
'tasks[].kind': 'windowed = 窗口型:按时间切片增量拉,有水位;'
|
|
260
|
+
+ 'snapshot = 快照型:全量拉取、全删重插(幂等)。'
|
|
261
|
+
+ '⚠️ 读 verify 的输出前必须先看它:只有 snapshot 的 expected_from_api 有意义',
|
|
262
|
+
// ⚠️ 这两个是窗口型专属参数,此前完全没有释义(2026-11-04 反向 sweep 实测)。
|
|
263
|
+
// 快照任务上它们是 null —— 不是「无上限 / 不重叠」,而是「这个概念对它不适用」。
|
|
264
|
+
// ⚠️ 2026-11-04 自查修正:初版说「撞上游 14501 时也按它判断是不是切宽了」——
|
|
265
|
+
// 引擎没有这段逻辑:撞 14501 只会作为 fetch_failed gap 记下来(不会自动重切)。
|
|
266
|
+
'tasks[].maxWindowDays': '窗口型任务的单窗最大天数(切窗依据)。null = 快照任务(没有窗口概念),'
|
|
267
|
+
+ '不是「不限宽」。sync run 按它切片;真撞上上游 14501(窗口过宽)不会自动重切,'
|
|
268
|
+
+ '只会作为 fetch_failed gap 记在该任务下',
|
|
269
|
+
'tasks[].overlapDays': '窗口型任务相邻窗口的重叠天数(幂等写入吸收重复)。null = 快照任务。'
|
|
270
|
+
+ '0 = 窗口首尾相接、不重叠',
|
|
271
|
+
unsupported: '明确不做同步的数据集及原因(不是遗漏)。目前唯一取值 realtime = '
|
|
272
|
+
+ '实时快照,数据随推随逝、不可回放——这类数据只能走 api call 实时取,别去 sync run 里找',
|
|
273
|
+
// ⚠️ 不得写成「任务声明的时间列名」(2026-11-07 审查):tickets / ticket_logs 声明的
|
|
274
|
+
// 是 `op_end`,而这两张表只有 ticket_id / payload / 若干 PII 列 / synchronized_at ——
|
|
275
|
+
// 照着去 `query --table tickets` 里找 op_end 会扑空。它是**请求参数**的窗口端点。
|
|
276
|
+
'tasks[].watermark.field': '水位取自请求参数里的哪个时间端点(windowed 任务取窗口端点的 '
|
|
277
|
+
+ 'opEnd / endTime,snapshot 任务取 synchronized_at),不是库表的列 —— tickets / '
|
|
278
|
+
+ 'ticket_logs 的表里没有 op_end。'
|
|
279
|
+
+ '⚠️ 本命令的 `watermark` 是对象 `{field, initial}`,而 `sync run` / `sync status` 的'
|
|
280
|
+
+ ' `tasks[].watermark` 是字符串或 null(上次成功推进到的时刻,UTC `Z`;'
|
|
281
|
+
+ 'null = 从未成功推进)—— 同名字段形状随命令不同,'
|
|
282
|
+
+ '不要把这里的对象当成水位值',
|
|
283
|
+
'tasks[].watermark.initial': '恒为 null —— 全部 21 个任务都没有声明初始水位'
|
|
284
|
+
+ '(首跑从 0 或 --since 起;声明了 windowStartFloorDays 的任务还会被抬到'
|
|
285
|
+
+ ' now − N 天,因为接口物理上给不出更早的数据)。看到非 null 才需要按它解释续跑起点',
|
|
286
|
+
'tasks[].sensitive_columns': '该表标注为敏感的 PII 列清单(来自 schema 的声明闭集)。'
|
|
287
|
+
+ '查询这些列会默认脱敏;不要 SELECT *',
|
|
288
|
+
};
|
|
289
|
+
}
|
|
290
|
+
/**
|
|
291
|
+
* `sync install` / `sync uninstall` 的四种输出形态。
|
|
292
|
+
*
|
|
293
|
+
* ⚠️ 为什么按模式分开(与 `skill install` 的 `installFieldNotes(mode)` 同款):
|
|
294
|
+
* 四个分支的键集**各不相同** —— dry-run 有 `entries`/`remove` 而没有 `installed`/`removed`,
|
|
295
|
+
* 真实安装有 `installed` 而没有 `entries`。一份图例解释四个不存在的键,就是「声明了但
|
|
296
|
+
* 没人读」的反向形态。
|
|
297
|
+
*/
|
|
298
|
+
export const SYNC_INSTALL_MODES = ['install-dry', 'install-real', 'uninstall-dry', 'uninstall-real'];
|
|
299
|
+
/** 四个分支共用的命令条目释义(`commands[]` 的每一项)。 */
|
|
300
|
+
const SYNC_COMMAND_NOTES = {
|
|
301
|
+
'commands[].command': '将要执行(dry-run)或已执行(--yes)的命令:argv 按单个空格拼接的可读形式,'
|
|
302
|
+
+ '内含空格或引号的值没有加外层引号 —— 不能直接粘进 shell 执行(真实执行走 argv 数组,'
|
|
303
|
+
+ '见该条的 executed/ok)。win32 的 /TR 值本身就是一条命令串,转述给人类时要按目标 shell 自行引号化',
|
|
304
|
+
'commands[].executed': '是否真的执行了这条命令。dry-run 恒为 false。--yes 下每条被列出的都执行了'
|
|
305
|
+
+ '(uninstall 在 darwin/linux「从未安装」时整条 commands 为空数组 —— 没有可停的调度器,'
|
|
306
|
+
+ '不是执行失败。win32 没有文件条目可探测,卸载命令总是执行:任务不存在时 schtasks 自己报错,'
|
|
307
|
+
+ '落进 ok=false)',
|
|
308
|
+
'commands[].ok': '三值:null = 未执行(dry-run),true = 执行成功,false = 执行失败。'
|
|
309
|
+
+ '⚠️ null 既不是成功也不是失败,别按布尔值用',
|
|
310
|
+
'commands[].error': '失败原因。未执行或成功时为 null',
|
|
311
|
+
};
|
|
312
|
+
const INSTALL_ENV_NOTE = '给人读的说明。恒含一条「调度条目不继承你的 shell 环境」——'
|
|
313
|
+
+ '凭证走 QIYU_APP_KEY / QIYU_APP_SECRET 时要确认调度上下文能拿到,本条目不写入任何凭证';
|
|
314
|
+
/** `sync install` / `sync uninstall` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。 */
|
|
315
|
+
export function syncInstallFieldNotes(mode) {
|
|
316
|
+
const base = {
|
|
317
|
+
platform: '调度平台:darwin = launchd,linux = systemd,win32 = schtasks。'
|
|
318
|
+
+ '其他平台在命令入口直接报不支持(退出码 2),不会有本输出',
|
|
319
|
+
dry_run: '执行模式:true = 只打印计划,零写入、零执行。false = 真的执行了(写/删文件、跑 commands[])。'
|
|
320
|
+
+ '⚠️ 它不回答「现在装没装」—— dry-run 什么都不改(已装过也一样只出计划),'
|
|
321
|
+
+ 'uninstall --yes 在从未安装时同样是 false。false 时本次操作做了什么,看操作结果字段'
|
|
322
|
+
+ '(install 是 installed,uninstall 是 removed / absent)与 commands[]。'
|
|
323
|
+
+ '退出码 1 只表示 commands[] 里至少一条执行失败(dry-run 恒 0)',
|
|
324
|
+
...SYNC_COMMAND_NOTES,
|
|
325
|
+
};
|
|
326
|
+
switch (mode) {
|
|
327
|
+
case 'install-dry':
|
|
328
|
+
return {
|
|
329
|
+
...base,
|
|
330
|
+
schedule: '回显的 cron 表达式(原样)',
|
|
331
|
+
'entries[].path': '将要写入的条目文件路径(dry-run 下文件尚未创建)',
|
|
332
|
+
'entries[].content': '将要写入的完整文件内容(dry-run 只回显,没有写盘)',
|
|
333
|
+
notes: INSTALL_ENV_NOTE,
|
|
334
|
+
};
|
|
335
|
+
case 'install-real':
|
|
336
|
+
return {
|
|
337
|
+
...base,
|
|
338
|
+
schedule: '回显的 cron 表达式(原样)',
|
|
339
|
+
installed: '已写入的条目文件路径。文件在命令执行之前写入,所以即便随后某条命令失败'
|
|
340
|
+
+ '(退出码 1),这些文件也已经写进去了。⚠️ 写入成功不等于调度已生效(launchd 需 load,'
|
|
341
|
+
+ 'systemd 需 enable,见 commands[] 的结果)',
|
|
342
|
+
notes: INSTALL_ENV_NOTE,
|
|
343
|
+
};
|
|
344
|
+
case 'uninstall-dry':
|
|
345
|
+
return {
|
|
346
|
+
...base,
|
|
347
|
+
'remove[].path': '计划要删除的条目文件路径(dry-run 下文件尚未删除)',
|
|
348
|
+
'remove[].exists': '计划生成那一刻探测到的存在性(true = 当时文件在)。'
|
|
349
|
+
+ '这是探测快照不是承诺:--yes 会重新探测一次,删除动作对所有条目都执行'
|
|
350
|
+
+ '(rmSync force,不存在也不报错),removed 与 absent 按那一次探测的 exists 划分',
|
|
351
|
+
post_remove_commands: '必须在「删除条目文件之后」执行的命令(条件键:只有 linux 有,'
|
|
352
|
+
+ '即 daemon-reload —— 先 reload 只会重新加载即将被删的 unit)。'
|
|
353
|
+
+ '执行次序是:commands → 删除 remove[] → post_remove_commands。'
|
|
354
|
+
+ '--yes 的结果里全部按这个次序汇总进 commands[]',
|
|
355
|
+
// 元素形状与 commands[] 完全相同(command/executed/ok/error):释义从同一份常量
|
|
356
|
+
// 派生,避免两处各写一份文案、改一边漏一边。差异只在「什么时候执行」,由上面的
|
|
357
|
+
// 顶层键说明。
|
|
358
|
+
...Object.fromEntries(Object.entries(SYNC_COMMAND_NOTES).map(([k, v]) => [k.replace(/^commands\[\]\./, 'post_remove_commands[].'), v])),
|
|
359
|
+
notes: '给人读的说明。darwin/linux 含卸载次序(先停调度器,再删文件),win32 说明 schtasks 的行为',
|
|
360
|
+
};
|
|
361
|
+
case 'uninstall-real':
|
|
362
|
+
return {
|
|
363
|
+
...base,
|
|
364
|
+
removed: '计划探测时存在、且删除调用未报错的文件路径',
|
|
365
|
+
absent: '计划探测时就不存在、因此没删的文件路径。⚠️ 这是条件键:为空时整个键不出现 ——'
|
|
366
|
+
+ '不出现就是「没有这类路径」,不是字段缺失(win32 无文件条目,恒不出现)',
|
|
367
|
+
commands: '已执行的卸载命令,按真实执行次序排列:先停调度器(unload/disable),'
|
|
368
|
+
+ '再删除 remove[] 里的文件,最后是 linux 的 daemon-reload(删完之后才 reload)',
|
|
369
|
+
notes: '给人读的说明。darwin/linux 从未安装(探测不到条目文件)时只有一条'
|
|
370
|
+
+ '「未安装(无条目文件):未执行任何命令」,此时 commands 为空数组。'
|
|
371
|
+
+ 'win32 没有文件条目可探测,无法在卸载前判断装没装,notes 恒为计划里的说明',
|
|
372
|
+
};
|
|
373
|
+
}
|
|
374
|
+
}
|