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
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// src/store/object-kinds.ts —— 库内对象类型(基表 / view …)的**唯一实现点**
|
|
2
|
+
// (2026-11-14,Codex PR#76)。
|
|
3
|
+
//
|
|
4
|
+
// 为什么在 store/ 而不是 commands/:`store/duckdb.ts` 的 `init()` 自身也必须判断
|
|
5
|
+
// 「这个对象是不是基表」(他人库指纹不认同名 view),而 `store/` 不得 import
|
|
6
|
+
// `commands/`。SQL 字符串在 `commands/store-precheck.ts` 的 `OBJECT_KINDS_SQL`
|
|
7
|
+
// (那里按命令层用法导出),本模块只放**判据**——两边共用这一份。
|
|
8
|
+
export function objectKinds(rows) {
|
|
9
|
+
return rows.map((r) => ({ name: String(r.table_name), type: String(r.table_type ?? '') }));
|
|
10
|
+
}
|
|
11
|
+
/** 是否为基表(类型缺失一律按「不是」处理 —— 宁可多拦,不可漏拦)。 */
|
|
12
|
+
export function isBaseTable(o) {
|
|
13
|
+
return o.type.toUpperCase() === 'BASE TABLE';
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* 是否为同一个对象名(DuckDB 标识符大小写不敏感)。
|
|
17
|
+
*
|
|
18
|
+
* ⚠️ 实测(Codex PR#76):`CREATE VIEW "TICKETS"` 之后 `SELECT COUNT(*) FROM "tickets"`
|
|
19
|
+
* 执行的就是这条 view —— 元数据里的名字是 `TICKETS`,本 CLI 的声明名全是小写,
|
|
20
|
+
* 精确字符串比较会漏掉它并继续执行 view 本体。所有「声明名 ↔ 库内对象」的比对都走这里。
|
|
21
|
+
*
|
|
22
|
+
* ⚠️ **只折叠 ASCII A–Z**(CodeRabbit PR#76 第二轮):DuckDB 的标识符大小写不敏感只针对
|
|
23
|
+
* ASCII 字母 —— 实测引号建的 `"ticKets"`(U+212A KELVIN SIGN)与 `"tickets"` 是两个对象,
|
|
24
|
+
* 而 JS 的 `toLowerCase()` 会把它折叠成 `tickets`(`"ticKets".toLowerCase() === "tickets"`),
|
|
25
|
+
* 于是两条同名字符串上本存在一个名字含 `K` 的基表、一个含 `K` 的 view 时,会把基表也当成
|
|
26
|
+
* 非基表跳过。用 `replace(/[A-Z]/g, …)` 替代 `toLowerCase()` / `localeCompare`(后者同样做
|
|
27
|
+
* Unicode 折叠与区域设置相关的排序)。
|
|
28
|
+
*/
|
|
29
|
+
export function sameObjectName(a, b) {
|
|
30
|
+
return foldAscii(a) === foldAscii(b);
|
|
31
|
+
}
|
|
32
|
+
const foldAscii = (s) => s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
|
package/dist/store/retry.js
CHANGED
|
@@ -103,22 +103,117 @@ export function classifyOpenFailure(e) {
|
|
|
103
103
|
return null;
|
|
104
104
|
}
|
|
105
105
|
const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
106
|
+
/** 单次尝试超时:`isRetryable` 之外由 `retryWithBackoff` 自行按可重试处理。 */
|
|
107
|
+
class AttemptTimeout extends Error {
|
|
108
|
+
constructor(ms) { super(`打开超过 ${ms}ms 未返回`); }
|
|
109
|
+
}
|
|
110
|
+
function withAttemptTimeout(p, ms) {
|
|
111
|
+
if (ms === undefined)
|
|
112
|
+
return p;
|
|
113
|
+
let timer;
|
|
114
|
+
// ⚠️ **不要 unref**(CodeRabbit PR#74 第二轮 major,实测确认):
|
|
115
|
+
// 计时器在 `finally` 里就被 `clearTimeout`,活不过这次尝试,unref 省不下任何东西;
|
|
116
|
+
// 而一旦尝试本身不持有任何活跃 handle(`new Promise(() => {})`、某些原生卡住形态),
|
|
117
|
+
// unref 的计时器会让 Node **直接退出**(实测:探针脚本 0.1s 退出、超时回调从未执行)——
|
|
118
|
+
// CLI 于是静默 exit 0、一个字都不吐,比「一直挂着」更难诊断。
|
|
119
|
+
// ⚠️ 残余边界(如实记录):被放弃的原生调用若仍持有活跃句柄,进程可能在打出
|
|
120
|
+
// `store_locked` 之后**仍不立刻退出** —— CLI 刻意不用 `process.exit`(会截断 stdout,
|
|
121
|
+
// 见 `src/cli.ts` 入口注释),所以这里换到的是「结论一定给出」,不是「进程一定立刻结束」。
|
|
122
|
+
// 为什么不用「拿到结论后宽限几秒再硬退出」补这一刀(CodeRabbit PR#74 第七轮提过):
|
|
123
|
+
// 那需要在入口调 `process.exit`,与 `tests/cli.test.ts` 的架构不变量直接冲突,而那条
|
|
124
|
+
// 不变量来自**实测事故**(管道输出 392846 字节只写出 131072,退出码仍 0、JSON 断在中间)。
|
|
125
|
+
// 「大输出被静默截断」比「错误已报出但进程多活一会儿」更贵:前者让 Agent 拿到坏 JSON
|
|
126
|
+
// 且以为成功,后者只是慢。所以这里保留残余边界,不引入退出兜底。
|
|
127
|
+
const timeout = new Promise((_, reject) => {
|
|
128
|
+
timer = setTimeout(() => reject(new AttemptTimeout(ms)), ms);
|
|
129
|
+
});
|
|
130
|
+
return Promise.race([p, timeout]).finally(() => { if (timer !== undefined)
|
|
131
|
+
clearTimeout(timer); });
|
|
132
|
+
}
|
|
106
133
|
/** 有界重试:可重试错误按固定间隔重试至 maxMs,超限抛最后一个错误。 */
|
|
107
134
|
export async function retryWithBackoff(opts) {
|
|
135
|
+
// 被放弃、还没交回清理的尝试(超时时刻 → 那次尝试的 promise)。清理时机见 `settle`。
|
|
136
|
+
const pendingAbandoned = [];
|
|
137
|
+
return settle(runLoop(opts, pendingAbandoned), pendingAbandoned, opts.onAbandoned);
|
|
138
|
+
}
|
|
139
|
+
async function runLoop(opts, pendingAbandoned) {
|
|
108
140
|
const intervalMs = opts.intervalMs ?? 200;
|
|
109
141
|
const sleep = opts.sleep ?? defaultSleep;
|
|
110
142
|
const now = opts.now ?? (() => Date.now());
|
|
111
143
|
const start = now();
|
|
144
|
+
const onAbandoned = opts.onAbandoned;
|
|
145
|
+
// 上一次失败的「预算耗尽时该抛什么」。⚠️ 循环顶部还要再查一次(Codex PR#74 第三轮 P2):
|
|
146
|
+
// `sleep` 可能比 `intervalMs` 长得多(进程被挂起、注入的 sleeper 把时钟推过头),
|
|
147
|
+
// 这时预算其实已经用光,但旧的判据只在**失败之后**比 —— 会再发起一次新的 `tryOpen`,
|
|
148
|
+
// 等于在 `readOnlyRetryMs` 到期后还去打开数据库(真实副作用:抢锁、起原生线程)。
|
|
149
|
+
let exhausted;
|
|
112
150
|
for (;;) {
|
|
151
|
+
if (exhausted !== undefined && now() - start >= opts.maxMs)
|
|
152
|
+
throw exhausted.err;
|
|
153
|
+
let attempt;
|
|
154
|
+
try {
|
|
155
|
+
attempt = opts.tryOpen();
|
|
156
|
+
}
|
|
157
|
+
catch (e) {
|
|
158
|
+
// 同步抛出也按普通失败处理(此前会直接冒泡、绕过预算判断)
|
|
159
|
+
attempt = Promise.reject(e);
|
|
160
|
+
}
|
|
161
|
+
// 这个 promise 之前超时过一次、现在又被当作新尝试(`tryOpen` 复用)→ 仍算放弃,
|
|
162
|
+
// 记下最早的超时时刻并把它从待清理表里取出来,等这一次的结果落定后再判。
|
|
163
|
+
const againAt = pendingAbandoned.find((x) => x.p === attempt)?.at;
|
|
164
|
+
if (againAt !== undefined) {
|
|
165
|
+
pendingAbandoned.splice(pendingAbandoned.findIndex((x) => x.p === attempt), 1);
|
|
166
|
+
}
|
|
167
|
+
// 单次尝试的上限还要被**剩余总预算**夹住(CodeRabbit PR#74):否则 30s 预算里
|
|
168
|
+
// 前面撞锁花掉 29s 后,下一次尝试仍能再跑满 30s —— 实际等待近 60s。
|
|
169
|
+
// `Math.max(1, …)` 只是兜住「剩余预算已 ≤0」的病态输入(1ms 的一次尝试仍是有界的);
|
|
170
|
+
// 「预算已耗尽却还发起新尝试」由循环顶部的 `exhausted` 判据挡住,不靠这个下限。
|
|
171
|
+
const remainingMs = opts.maxMs - (now() - start);
|
|
172
|
+
const attemptCap = opts.attemptMs === undefined ? undefined
|
|
173
|
+
: Math.max(1, Math.min(opts.attemptMs, remainingMs));
|
|
113
174
|
try {
|
|
114
|
-
return await
|
|
175
|
+
return await withAttemptTimeout(attempt, attemptCap);
|
|
115
176
|
}
|
|
116
177
|
catch (e) {
|
|
117
|
-
|
|
178
|
+
const timedOut = e instanceof AttemptTimeout;
|
|
179
|
+
if (timedOut && onAbandoned !== undefined) {
|
|
180
|
+
// 只**登记**,此刻不注册清理(见 `settle` 的注释):它可能被下一次尝试复用并成为结果。
|
|
181
|
+
pendingAbandoned.push({ at: againAt ?? now(), p: attempt });
|
|
182
|
+
}
|
|
183
|
+
if (!timedOut && !opts.isRetryable(e))
|
|
118
184
|
throw e;
|
|
185
|
+
// 超时且没有更具体的成因时,给调用方一个可识别的锁语义(与既有 store_locked 包装同源)
|
|
186
|
+
// 用自有字段而不是标准的 `cause`(那应该是 Error,写成字符串会误导诊断)
|
|
187
|
+
const budgetSpent = timedOut
|
|
188
|
+
// 报文用**实际生效的**那一档上限(`attemptCap` 可能被剩余预算夹小),
|
|
189
|
+
// 不是配置里的 `attemptMs` —— 否则日志说「等了 30000ms」而实际只等了 400ms。
|
|
190
|
+
? Object.assign(new Error(`打开超时(本次尝试 ${attemptCap ?? opts.attemptMs}ms 内未返回,等待 ${opts.maxMs}ms 后放弃)`), { timedOut: true })
|
|
191
|
+
: e;
|
|
192
|
+
exhausted = { err: budgetSpent };
|
|
119
193
|
if (now() - start + intervalMs > opts.maxMs)
|
|
120
|
-
throw
|
|
194
|
+
throw budgetSpent;
|
|
121
195
|
await sleep(intervalMs);
|
|
122
196
|
}
|
|
123
197
|
}
|
|
124
198
|
}
|
|
199
|
+
/**
|
|
200
|
+
* 重试循环的收尾:把**没被返回**的放弃尝试交回清理。
|
|
201
|
+
*
|
|
202
|
+
* 为什么不直接写在循环体的 `finally` 里:`return` 的 `finally` 会在值交给调用方之前跑 ——
|
|
203
|
+
* 只要把「本次返回的那个 promise」也一并清理,调用方拿到的就是关掉的连接。这里改成
|
|
204
|
+
* 「循环只负责登记放弃者,收尾统一处理」,并用 `pending` 里已经剔除「已复用的那个」来保证
|
|
205
|
+
* 不会误关;三条出口(成功返回 / 不可重试抛错 / 预算耗尽抛错)由同一个 `finally` 覆盖。
|
|
206
|
+
*/
|
|
207
|
+
async function settle(loop, pending, onAbandoned) {
|
|
208
|
+
try {
|
|
209
|
+
return await loop;
|
|
210
|
+
}
|
|
211
|
+
finally {
|
|
212
|
+
if (onAbandoned !== undefined) {
|
|
213
|
+
for (const x of pending) {
|
|
214
|
+
const done = x.p.then((v) => onAbandoned(v), () => { });
|
|
215
|
+
done.catch(() => { });
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
}
|
package/dist/store/schema.js
CHANGED
|
@@ -321,7 +321,12 @@ export const TABLES = [
|
|
|
321
321
|
},
|
|
322
322
|
];
|
|
323
323
|
export function tableByName(name) {
|
|
324
|
-
|
|
324
|
+
// 名字匹配按 DuckDB 的标识符规则:仅折叠 ASCII A–Z,不做 Unicode 折叠(Codex PR#76;
|
|
325
|
+
// 判据与 `store/object-kinds.ts` 的 `sameObjectName` 同一规则 —— schema.ts 在本模块内
|
|
326
|
+
// 不能再依赖 duckdb 层,故就地实现;`tests/store/object-kinds.test.ts` 双向钉住两者一致)。
|
|
327
|
+
const fold = (x) => x.replace(/[A-Z]/g, (c) => c.toLowerCase());
|
|
328
|
+
const key = fold(name);
|
|
329
|
+
return TABLES.find((t) => fold(t.name) === key);
|
|
325
330
|
}
|
|
326
331
|
/** v1 基线批次(C1 交付的四张);v3/v5 起的数据表批次不进 v1 建表循环。 */
|
|
327
332
|
export const V1_TABLES = ['schema_version', 'sync_state', 'sync_gaps', 'tags'];
|
package/dist/sync/engine.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { readWatermark, markPending, advanceWatermark, recordGap, clearGap, clearLock, } from './state.js';
|
|
2
2
|
import { sliceByMaxWindow } from './windowing.js';
|
|
3
3
|
import { isLockError } from '../store/retry.js';
|
|
4
|
+
import { storeInitCommand, syncRunCommand } from '../output.js';
|
|
4
5
|
import { clampGateWait } from './rate-gate.js';
|
|
5
6
|
import { shanghaiDayIso, shanghaiDayStart, shanghaiYesterdayStart } from './day.js';
|
|
6
7
|
const DAY = 86_400_000;
|
|
@@ -71,6 +72,19 @@ function resolveRangeStart(task, ctx, state, requested, nowMs) {
|
|
|
71
72
|
}
|
|
72
73
|
return floorRangeStart(task, start, requested.end, nowMs);
|
|
73
74
|
}
|
|
75
|
+
/**
|
|
76
|
+
* 任意拒绝值 → 文本;**转换本身抛**(`Object.create(null)` 没有 `Symbol.toPrimitive`)时交回
|
|
77
|
+
* 占位说明(CR 第五十四轮 store 侧同一形态的引擎收口)。错误路径上的「值转文本」不得自己
|
|
78
|
+
* 成为新的主失败 —— 否则本次运行连 partial / gap 都报不出来。
|
|
79
|
+
*/
|
|
80
|
+
function textOf(e) {
|
|
81
|
+
try {
|
|
82
|
+
return e instanceof Error ? e.message : String(e);
|
|
83
|
+
}
|
|
84
|
+
catch {
|
|
85
|
+
return `(无法转成文本的拒绝值,typeof=${typeof e})`;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
74
88
|
/**
|
|
75
89
|
* gap detail 的中文包装(C 低-2):gap 要进 stdout 与持久层(sync_gaps),
|
|
76
90
|
* 而失败原因可能是任意来源 —— `fetch failed`、DuckDB 的英文原文、上游报文片段。
|
|
@@ -78,9 +92,53 @@ function resolveRangeStart(task, ctx, state, requested, nowMs) {
|
|
|
78
92
|
* ⚠️ 引擎自己抛的中文结论(配对核对/本地限频)不包装 —— 再套一层只会变噪音。
|
|
79
93
|
*/
|
|
80
94
|
function failDetail(label, e) {
|
|
81
|
-
const raw =
|
|
95
|
+
const raw = textOf(e);
|
|
82
96
|
return `${label}(底层:${raw})`;
|
|
83
97
|
}
|
|
98
|
+
/**
|
|
99
|
+
* fetch 失败的原因分派:`callPaced` 在**真正要调用**的端点冷却时抛 `rate_limit_local`
|
|
100
|
+
* (Sourcery PR#58 复核,2026-11-15)。那是「本窗没发请求 / 已发部分请求但未落库」的
|
|
101
|
+
* 限频,不是取数失败 —— 记成 fetch_failed 会让 Agent 去查接口形态而不是等冷却。
|
|
102
|
+
*/
|
|
103
|
+
function fetchGapReason(e) {
|
|
104
|
+
return safeKindOf(e) === 'rate_limit_local' ? 'rate_limit_local' : 'fetch_failed';
|
|
105
|
+
}
|
|
106
|
+
function fetchGapDetail(e) {
|
|
107
|
+
return fetchGapReason(e) === 'rate_limit_local'
|
|
108
|
+
? textOf(e)
|
|
109
|
+
: failDetail('取数失败', e);
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* DuckDB 对「INSERT / DELETE 的目标不是基表」(同名 view 等)的原文:
|
|
113
|
+
* `Catalog Error: tags is not an table`(实测,2026-11-15;DELETE 侧另有
|
|
114
|
+
* `Binder Error: Can only delete from base table`)。
|
|
115
|
+
* ⚠️ 匹配前先剥一层可能的包装前缀?不需要:两个 store 路径(`upsert` 的 usage 包装只发生在
|
|
116
|
+
* 列校验,而 view 的列集若对得上就一路走到 INSERT)与 `delete` 都直接抛驱动原文。
|
|
117
|
+
*/
|
|
118
|
+
function isNotAnTableError(raw) {
|
|
119
|
+
return /\bis not an table\b|\bCan only delete from base table\b/i.test(raw);
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* `write_failed` 的 detail(唯一渲染点):普通落库失败保持原有的 `落库失败(底层:…)`;
|
|
123
|
+
* 目标对象不是基表时**点名成因**并给出与 `sync verify` 的 `not_base_table`、
|
|
124
|
+
* `query --table`、`stats fields` 同一套恢复动作 —— 否则 Agent 只会反复重跑 `sync run`。
|
|
125
|
+
* 不回显 DuckDB 原文里被操作的对象名(那是用户自己的表名,不是故障点;原文对 Agent 无益)。
|
|
126
|
+
*/
|
|
127
|
+
function writeFailedDetail(e, ctx) {
|
|
128
|
+
const raw = textOf(e);
|
|
129
|
+
if (!isNotAnTableError(raw))
|
|
130
|
+
return failDetail('落库失败', e);
|
|
131
|
+
const loc = ctx.storeLocation;
|
|
132
|
+
const rebuild = loc === undefined
|
|
133
|
+
? '先备份旧库文件,再把 --db 换成新的 .duckdb 路径跑 qiyu store init 建库、'
|
|
134
|
+
+ 'qiyu sync run 重新拉取(不要指回出问题的文件)'
|
|
135
|
+
: '先备份旧库文件,再把 --db 换成新的 .duckdb 路径跑 '
|
|
136
|
+
+ storeInitCommand('<新路径>', loc.profileFlag) + ' 建库、'
|
|
137
|
+
+ syncRunCommand('<新路径>', loc.profileFlag) + ' 重新拉取'
|
|
138
|
+
+ '(把 <新路径> 整段替换成新路径,不要指回出问题的文件)';
|
|
139
|
+
return '落库失败:本 CLI 的一张声明表在库里不是基表(view 等,写入被库拒绝)。'
|
|
140
|
+
+ '执行它的主体会读到旧数据或直接失败。' + rebuild;
|
|
141
|
+
}
|
|
84
142
|
/**
|
|
85
143
|
* 写策略落地(事务内调用):deleteRangeInsert 按声明基准删旧 + upsert;upsertRows 直接 upsert。
|
|
86
144
|
* ⚠️ 窗口是**半开** [start, end),而删除条件是闭区间 —— 上界一律取「最后 1ms」:
|
|
@@ -182,16 +240,58 @@ async function withRetries(ctx, op, retryable = () => true) {
|
|
|
182
240
|
* 于是引擎重试真正覆盖的是 core 无法归类/无法重试的那一类:撞锁(store_locked)
|
|
183
241
|
* 与任务层显式标注 retryable 的瞬时错误。
|
|
184
242
|
*/
|
|
243
|
+
/**
|
|
244
|
+
* 实例已退役(稳定 `code`)—— **两层重试判据的最高优先终止条件**(Codex 第七轮 P2,真驱动
|
|
245
|
+
* 注入实测):回滚未确认的撞锁失败会保留原 `kind`(`store_locked`)并打上
|
|
246
|
+
* `code=store_retired`;若只按 kind 判「撞锁可重试」,就会再碰**已退役的同一实例** ——
|
|
247
|
+
* 第二次尝试撞上「Store 已退役」,把主失败与「先核对再重放」整段换掉。
|
|
248
|
+
*/
|
|
249
|
+
/**
|
|
250
|
+
* 安全读取拒绝值上的字符串字段(**唯一实现点**,CR 第六十五轮 / Codex 第十二轮 P2):
|
|
251
|
+
* 拒绝值可能是 `null` / `undefined`(读属性直接 TypeError),也可能是 getter 抛异常的对象 ——
|
|
252
|
+
* 错误路径上的判据自己成了新的主失败,就会把原始错误整段换掉。读不出来一律按「不匹配」。
|
|
253
|
+
* ⚠️ 不只是 `code`:`kind` / `hint` / `retryable` 同样被判据读,一律经这里
|
|
254
|
+
*(实测事故:`query` 以 `null` 拒绝时 `fetchGapReason` 的 `(e as {kind}).kind` 抛
|
|
255
|
+
* `Cannot read properties of null (reading 'kind')`,原始拒绝值整段丢失)。
|
|
256
|
+
*/
|
|
257
|
+
const safeStringField = (e, field) => {
|
|
258
|
+
if (e === null || (typeof e !== 'object' && typeof e !== 'function'))
|
|
259
|
+
return undefined;
|
|
260
|
+
try {
|
|
261
|
+
const v = e[field];
|
|
262
|
+
return typeof v === 'string' ? v : undefined;
|
|
263
|
+
}
|
|
264
|
+
catch {
|
|
265
|
+
return undefined;
|
|
266
|
+
}
|
|
267
|
+
};
|
|
268
|
+
const safeBoolField = (e, field) => {
|
|
269
|
+
if (e === null || (typeof e !== 'object' && typeof e !== 'function'))
|
|
270
|
+
return undefined;
|
|
271
|
+
try {
|
|
272
|
+
const v = e[field];
|
|
273
|
+
return typeof v === 'boolean' ? v : undefined;
|
|
274
|
+
}
|
|
275
|
+
catch {
|
|
276
|
+
return undefined;
|
|
277
|
+
}
|
|
278
|
+
};
|
|
279
|
+
const safeCodeOf = (e) => safeStringField(e, 'code');
|
|
280
|
+
const safeKindOf = (e) => safeStringField(e, 'kind');
|
|
281
|
+
const isRetiredFailure = (e) => safeCodeOf(e) === 'store_retired';
|
|
185
282
|
function isTransient(e) {
|
|
186
|
-
|
|
187
|
-
|
|
283
|
+
if (isRetiredFailure(e))
|
|
284
|
+
return false;
|
|
285
|
+
const kind = safeKindOf(e);
|
|
286
|
+
if (kind === 'store_locked')
|
|
188
287
|
return true;
|
|
189
|
-
if (
|
|
288
|
+
if (kind === 'rate_limit' || kind === 'network')
|
|
190
289
|
return false;
|
|
191
|
-
return
|
|
290
|
+
return safeBoolField(e, 'retryable') === true;
|
|
192
291
|
}
|
|
193
292
|
/** store 事务的撞锁重试(B 中-4,spec §6.3:C1 写者无内置重试,重试调度归 D 层)。 */
|
|
194
|
-
const storeRetryable = (e) =>
|
|
293
|
+
const storeRetryable = (e) => !isRetiredFailure(e)
|
|
294
|
+
&& (safeKindOf(e) === 'store_locked' || isLockError(e));
|
|
195
295
|
const withStoreRetries = (ctx, op) => withRetries(ctx, op, storeRetryable);
|
|
196
296
|
/** 本窗 gap 落库 + 收集(独立事务:本窗已回滚,gap 不能混进失败事务)。 */
|
|
197
297
|
async function storeGap(ctx, task, w, reason, detail, gaps) {
|
|
@@ -201,6 +301,51 @@ async function storeGap(ctx, task, w, reason, detail, gaps) {
|
|
|
201
301
|
}));
|
|
202
302
|
gaps.push(info);
|
|
203
303
|
}
|
|
304
|
+
/**
|
|
305
|
+
* Store 连接已退役(事务状态无法确认,存储层拒绝一切后续语句)—— 判据是存储层打的
|
|
306
|
+
* 稳定 `code`,不按报文文本匹配(文案随成因变化,code 不变)。
|
|
307
|
+
* ⚠️ 为什么引擎必须认它(CR 第四十一轮 major 的追问,真驱动注入实测):落库事务的
|
|
308
|
+
* COMMIT 结果未知时 Store 当场退役;随后的 **gap 落库**与**清锁**都会撞上退役。
|
|
309
|
+
* 若让这两条次生失败照常上抛,用户看到的会是「Store 已退役,请关闭重建后再试」——
|
|
310
|
+
* 把原始失败里的「写入可能已落库,不要按失败直接重试(可能重复写),核对后再决定是否
|
|
311
|
+
* 重放」整段换掉,恰好诱导重复写。
|
|
312
|
+
*/
|
|
313
|
+
const isStoreRetired = (e) => safeCodeOf(e) === 'store_retired';
|
|
314
|
+
/**
|
|
315
|
+
* 记本窗 gap;连接已退役时 gap 写不进去,**把本窗的原始失败原样交回**(它带着恢复指令)。
|
|
316
|
+
* 其它 error 照旧上抛 —— 那是 gap 真正的写入失败,不能吞。
|
|
317
|
+
*/
|
|
318
|
+
async function storeGapOrPrimary(ctx, task, w, reason, detail, gaps, primary) {
|
|
319
|
+
try {
|
|
320
|
+
await storeGap(ctx, task, w, reason, detail, gaps);
|
|
321
|
+
}
|
|
322
|
+
catch (e) {
|
|
323
|
+
if (!isStoreRetired(e))
|
|
324
|
+
throw e;
|
|
325
|
+
// 主失败本身已让实例退役(它先退役、gap 写是次生)→ 原样交回主失败(它带着恢复指令)。
|
|
326
|
+
if (isStoreRetired(primary))
|
|
327
|
+
throw primary;
|
|
328
|
+
// ⚠️ 否则是**补记缺口这次事务首次**让实例退役(COMMIT 结果未知,CR 第五十一轮 major #2):
|
|
329
|
+
// 两条事实都必须交回 —— 只留主失败会静默丢掉「缺口记录可能没落库、实例已退役、后续窗口
|
|
330
|
+
// 写不进」;只留退役文案又丢掉主失败。合并成一条,`code`/`kind` 让编排层识别退役。
|
|
331
|
+
const primaryMsg = textOf(primary);
|
|
332
|
+
// ⚠️ **不得断言 COMMIT 已下发**(Codex 第五轮 P1,隔离探针实测):补记缺口的事务也可能
|
|
333
|
+
// 在 INSERT 阶段就失败、ROLLBACK 又未确认(SQL 序列里根本没有 COMMIT)—— 摘要必须用
|
|
334
|
+
// 那条错误**自己的**成因(提交结果未知 / 回滚未能确认),否则恢复动作被误导。
|
|
335
|
+
const gapMsg = textOf(e);
|
|
336
|
+
const wrapped = new Error(`${primaryMsg} —— 补记缺口时实例退役(${gapMsg})`, { cause: primary });
|
|
337
|
+
wrapped.kind = safeKindOf(e) ?? 'internal';
|
|
338
|
+
wrapped.retryable = false;
|
|
339
|
+
wrapped.code = 'store_retired';
|
|
340
|
+
const eh = safeStringField(e, 'hint');
|
|
341
|
+
const ph = safeStringField(primary, 'hint');
|
|
342
|
+
const hints = [eh, ph].filter((h) => typeof h === 'string');
|
|
343
|
+
wrapped.hint = hints.length > 0
|
|
344
|
+
? hints.join(';')
|
|
345
|
+
: '关闭并重建 Store 实例,先核对数据(本窗写入是否落库)再决定是否重放;后续窗口需要重跑';
|
|
346
|
+
throw wrapped;
|
|
347
|
+
}
|
|
348
|
+
}
|
|
204
349
|
/**
|
|
205
350
|
* gapHint → sync_gaps.detail(C-8):hint 带 `fixture`(会话导出的尾部标记行原文)时
|
|
206
351
|
* 追加标注 —— 「为什么可疑」在 detail 正文、「可疑的那行原文」在其后,同一行可见。
|
|
@@ -219,24 +364,34 @@ function gapHintDetail(hint) {
|
|
|
219
364
|
*/
|
|
220
365
|
const GATE_WAIT_BUDGET = 3;
|
|
221
366
|
const GATE_WAIT_FALLBACK_MS = 1_000;
|
|
367
|
+
/**
|
|
368
|
+
* 任务的**首次请求端点**(`gateKeysOf` 的首键):fetch 前的**快速失败**预检只看这一把键。
|
|
369
|
+
*
|
|
370
|
+
* ⚠️ 为什么不再预检**全部**声明键(Sourcery PR#58 复核,2026-11-15 实测):声明式地
|
|
371
|
+
* 在 fetch 前检查 `gateEndpoints` 全部键,会把「本次根本不会调用」的端点冷却也算成失败 ——
|
|
372
|
+
* 实测 `ticket.template.fields` 冷却 + 模板列表为空时,`dim.ticket_template_fields`
|
|
373
|
+
* 一发请求都不发就被记成 `failed` + `rate_limit_local`,而空快照本该删掉旧字段行。
|
|
374
|
+
* 次要端点改由 `callPaced` 在**真正调用前**逐一拦(那里才是「会不会调用」的唯一答案)。
|
|
375
|
+
* 主端点预检保留:常见成因(主端点冷却)仍然在发请求前就失败,语义没变。
|
|
376
|
+
*/
|
|
222
377
|
async function acquireGated(ctx, task) {
|
|
223
|
-
//
|
|
224
|
-
//
|
|
225
|
-
//
|
|
226
|
-
//
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
378
|
+
// 首键 = 任务**实际先请求**的那个端点(`gateEndpoints` 缺省回退成 `[endpoint ?? id]`;
|
|
379
|
+
// 多端点任务的声明按「先调的在前」写,实测 dim.ticket_template_fields 先 list 后 fields)。
|
|
380
|
+
// ⚠️ 不要改成「`endpoint` 声明的那个」:`dim.ticket_template_fields` 的 `endpoint` 是
|
|
381
|
+
// `ticket.template.fields`,而它第一次发的是 `ticket.template.list` —— 预检要拦的是
|
|
382
|
+
// 「马上要发的这一发」,声明字段只是写库/文档归属。
|
|
383
|
+
const key = gateKeysOf(task)[0];
|
|
384
|
+
for (let waits = 0;; waits++) {
|
|
385
|
+
try {
|
|
386
|
+
// 冷却是持久化的:读库也在 store 上,撞锁走同一有界重试(B 中-4)。
|
|
387
|
+
await withStoreRetries(ctx, () => ctx.gate.acquire(key));
|
|
388
|
+
return;
|
|
389
|
+
}
|
|
390
|
+
catch (e) {
|
|
391
|
+
if (safeKindOf(e) !== 'rate_limit_local' || waits >= GATE_WAIT_BUDGET)
|
|
392
|
+
throw e;
|
|
393
|
+
const wait = clampGateWait(e.retryAfter ?? 0) || GATE_WAIT_FALLBACK_MS;
|
|
394
|
+
await engineSleep(ctx, wait);
|
|
240
395
|
}
|
|
241
396
|
}
|
|
242
397
|
}
|
|
@@ -545,10 +700,12 @@ async function runWindowed(task, ctx) {
|
|
|
545
700
|
await acquireGated(ctx, task);
|
|
546
701
|
}
|
|
547
702
|
catch (e) {
|
|
548
|
-
if (e
|
|
703
|
+
if (safeKindOf(e) === 'rate_limit_local') {
|
|
549
704
|
failed++;
|
|
550
705
|
contiguousBroken = true;
|
|
551
|
-
|
|
706
|
+
// ⚠️ **次生的退役错误不得顶掉这里的原始失败**(CR 第六十三轮 major):限频
|
|
707
|
+
// 预算耗尽本身带恢复指令;补记缺口的事务若首次让实例退役,两条事实合并交回。
|
|
708
|
+
await storeGapOrPrimary(ctx, task, w, 'rate_limit_local', e.message, gaps, e);
|
|
552
709
|
continue;
|
|
553
710
|
}
|
|
554
711
|
throw e;
|
|
@@ -561,7 +718,7 @@ async function runWindowed(task, ctx) {
|
|
|
561
718
|
catch (e) {
|
|
562
719
|
failed++;
|
|
563
720
|
contiguousBroken = true;
|
|
564
|
-
await
|
|
721
|
+
await storeGapOrPrimary(ctx, task, w, fetchGapReason(e), fetchGapDetail(e), gaps, e);
|
|
565
722
|
continue;
|
|
566
723
|
}
|
|
567
724
|
// —— enrich 过滤 + 同事务落库(红线 2/3)——
|
|
@@ -589,11 +746,11 @@ async function runWindowed(task, ctx) {
|
|
|
589
746
|
catch (e) {
|
|
590
747
|
failed++;
|
|
591
748
|
contiguousBroken = true;
|
|
592
|
-
const isMismatch = e
|
|
749
|
+
const isMismatch = safeCodeOf(e) === 'count_mismatch';
|
|
593
750
|
// 行数统计口径(brief 钉死用例):mismatch 时 written 记「应写行数」(kept)——
|
|
594
751
|
// 实际行已随事务回滚,计入的是本窗参与核对的落库意图行数。
|
|
595
752
|
writtenTotal += kept.length;
|
|
596
|
-
await
|
|
753
|
+
await storeGapOrPrimary(ctx, task, w, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? textOf(e) : writeFailedDetail(e, ctx), gaps, e);
|
|
597
754
|
continue;
|
|
598
755
|
}
|
|
599
756
|
resolvedEndOut = watermarkMs;
|
|
@@ -670,7 +827,7 @@ async function runSnapshot(task, ctx) {
|
|
|
670
827
|
await acquireGated(ctx, task);
|
|
671
828
|
}
|
|
672
829
|
catch (e) {
|
|
673
|
-
if (e
|
|
830
|
+
if (safeKindOf(e) === 'rate_limit_local') {
|
|
674
831
|
// 快照也要留下可查的状态行(E 中-1):门都没进就放弃时,若库里连一行都没有,
|
|
675
832
|
// 建一行 pending(盖章后立即清章)——「这个任务本轮被本地冷却拦下了」必须可查,
|
|
676
833
|
// 而不是 status 里什么都看不到。
|
|
@@ -681,7 +838,7 @@ async function runSnapshot(task, ctx) {
|
|
|
681
838
|
}));
|
|
682
839
|
await releaseLock(ctx, task);
|
|
683
840
|
}
|
|
684
|
-
await
|
|
841
|
+
await storeGapOrPrimary(ctx, task, resolvedRange, 'rate_limit_local', e.message, gaps, e);
|
|
685
842
|
return snapshotResult(task, resolvedRange, gaps, 0, 0, 0, 1, 'failed');
|
|
686
843
|
}
|
|
687
844
|
throw e;
|
|
@@ -699,7 +856,7 @@ async function runSnapshot(task, ctx) {
|
|
|
699
856
|
fetchRes = await withRetries(ctx, () => fetchWithFakeEmptyRetry(task, ref, ctx), isTransient);
|
|
700
857
|
}
|
|
701
858
|
catch (e) {
|
|
702
|
-
await
|
|
859
|
+
await storeGapOrPrimary(ctx, task, resolvedRange, fetchGapReason(e), fetchGapDetail(e), gaps, e);
|
|
703
860
|
return snapshotResult(task, resolvedRange, gaps, 0, 0, 0, 1, 'failed');
|
|
704
861
|
}
|
|
705
862
|
const { kept } = applyEnrich(task, fetchRes.rows);
|
|
@@ -725,8 +882,8 @@ async function runSnapshot(task, ctx) {
|
|
|
725
882
|
}));
|
|
726
883
|
}
|
|
727
884
|
catch (e) {
|
|
728
|
-
const isMismatch = e
|
|
729
|
-
await
|
|
885
|
+
const isMismatch = safeCodeOf(e) === 'count_mismatch';
|
|
886
|
+
await storeGapOrPrimary(ctx, task, resolvedRange, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? textOf(e) : writeFailedDetail(e, ctx), gaps, e);
|
|
730
887
|
return snapshotResult(task, resolvedRange, gaps, fetchRes.rows.length, 0, 0, 1, 'failed');
|
|
731
888
|
}
|
|
732
889
|
// gapHint(如 dim.staff_group_members 的 staffIdList 形态漂移):成功快照也落提示。
|
|
@@ -749,7 +906,20 @@ async function runSnapshot(task, ctx) {
|
|
|
749
906
|
* 无行(如空范围空跑、或在 markPending 之前就抛错)时不动库 —— 不为清章凭空建一行。
|
|
750
907
|
*/
|
|
751
908
|
async function releaseLock(ctx, task) {
|
|
752
|
-
|
|
909
|
+
// ⚠️ **读水位失败**才可能是主失败的次生结果(CR 第四十一轮 major;第五十一轮 major #5
|
|
910
|
+
// 细化):本函数在 `finally` 里,若实例在进入这里**之前**就已退役,读水位的 store_retired
|
|
911
|
+
// 纯属次生 —— 吞掉,才能保住主失败里「核对数据后再决定是否重放」的恢复指令。
|
|
912
|
+
let st;
|
|
913
|
+
try {
|
|
914
|
+
st = await readWatermark(ctx.store, task.id);
|
|
915
|
+
}
|
|
916
|
+
catch (e) {
|
|
917
|
+
if (isStoreRetired(e))
|
|
918
|
+
return;
|
|
919
|
+
throw e;
|
|
920
|
+
}
|
|
921
|
+
// 读水位成功说明实例此前可用 —— 随后清锁事务里的 store_retired 是本函数**首次**让实例退役
|
|
922
|
+
//(COMMIT 结果未知),不是次生结果:必须上抛,否则本次 run 被报成 complete、写者锁可能没清。
|
|
753
923
|
if (st.watermark === null && st.rangeStatus === null && st.lastSyncedAt === null)
|
|
754
924
|
return;
|
|
755
925
|
await withStoreRetries(ctx, () => ctx.store.transaction(async (tx) => {
|
|
@@ -912,10 +1082,10 @@ export async function runRotated(tasks, ctx) {
|
|
|
912
1082
|
await acquireGated(ctx, task);
|
|
913
1083
|
}
|
|
914
1084
|
catch (e) {
|
|
915
|
-
if (e
|
|
1085
|
+
if (safeKindOf(e) === 'rate_limit_local') {
|
|
916
1086
|
plan.failed++;
|
|
917
1087
|
plan.contiguousBroken = true;
|
|
918
|
-
await
|
|
1088
|
+
await storeGapOrPrimary(ctx, task, w, 'rate_limit_local', e.message, plan.gaps, e);
|
|
919
1089
|
continue;
|
|
920
1090
|
}
|
|
921
1091
|
throw e;
|
|
@@ -928,7 +1098,7 @@ export async function runRotated(tasks, ctx) {
|
|
|
928
1098
|
catch (e) {
|
|
929
1099
|
plan.failed++;
|
|
930
1100
|
plan.contiguousBroken = true;
|
|
931
|
-
await
|
|
1101
|
+
await storeGapOrPrimary(ctx, task, w, fetchGapReason(e), fetchGapDetail(e), plan.gaps, e);
|
|
932
1102
|
continue;
|
|
933
1103
|
}
|
|
934
1104
|
const { kept } = applyEnrich(task, fetchRes.rows);
|
|
@@ -952,9 +1122,9 @@ export async function runRotated(tasks, ctx) {
|
|
|
952
1122
|
catch (e) {
|
|
953
1123
|
plan.failed++;
|
|
954
1124
|
plan.contiguousBroken = true;
|
|
955
|
-
const isMismatch = e
|
|
1125
|
+
const isMismatch = safeCodeOf(e) === 'count_mismatch';
|
|
956
1126
|
plan.written += kept.length;
|
|
957
|
-
await
|
|
1127
|
+
await storeGapOrPrimary(ctx, task, w, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? e.message : writeFailedDetail(e, { storeLocation: ctx.storeLocation }), plan.gaps, e);
|
|
958
1128
|
continue;
|
|
959
1129
|
}
|
|
960
1130
|
for (const h of (Array.isArray(fetchRes.gapHint) ? fetchRes.gapHint : [fetchRes.gapHint])) {
|
package/dist/sync/registry.js
CHANGED
|
@@ -3,7 +3,7 @@ import { REPORT_TASKS } from './tasks/reports.js';
|
|
|
3
3
|
import { TICKET_TASKS } from './tasks/tickets.js';
|
|
4
4
|
import { SESSIONS_TASKS } from './tasks/sessions.js';
|
|
5
5
|
import { KNOWLEDGE_TASKS } from './tasks/knowledge.js';
|
|
6
|
-
import { assertWriteContracts } from './write-contract.js';
|
|
6
|
+
import { assertWriteContracts, assertGateContracts } from './write-contract.js';
|
|
7
7
|
/** 全量同步任务注册表:dim 6 + reports 9 + tickets 2 + sessions 1 + knowledge 3 = 21。 */
|
|
8
8
|
export const SYNC_TASKS = [
|
|
9
9
|
...DIM_TASKS,
|
|
@@ -15,6 +15,8 @@ export const SYNC_TASKS = [
|
|
|
15
15
|
// 写策略声明前提的加载期校验(`write-contract.ts`):声明错了就在此炸,
|
|
16
16
|
// 而不是在某个真实租户的边界日里静默丢/留数据。
|
|
17
17
|
assertWriteContracts(SYNC_TASKS);
|
|
18
|
+
// 闸门键:声明了就必须非空且含主端点(Sourcery PR#58;空列表会静默回退成单键)。
|
|
19
|
+
assertGateContracts(SYNC_TASKS);
|
|
18
20
|
/** 按 id 取任务(sync run <id> 的分派入口)。 */
|
|
19
21
|
export function taskById(id) {
|
|
20
22
|
return SYNC_TASKS.find((t) => t.id === id);
|
package/dist/sync/tasks/pace.js
CHANGED
|
@@ -41,6 +41,33 @@ export function nowIsoOf(ctx) {
|
|
|
41
41
|
* `gate.acquire(task.endpoint)` 必须落在同一把键上,冷却才拦得住下一次调用。
|
|
42
42
|
*/
|
|
43
43
|
export async function callPaced(endpointId, body, ctx, attempt = 0) {
|
|
44
|
+
// ⚠️ 真正要调用时才查这个端点的冷却(Sourcery PR#58 复核,2026-11-15 实测):引擎在
|
|
45
|
+
// fetch 前只预检主端点(按全部声明键预检会误伤「本次不调用」的端点,见 `acquireGated`)。
|
|
46
|
+
// 这里 15 处任务调用全经本函数 —— 是「会不会调用」的唯一准确答案。
|
|
47
|
+
// ⚠️ 只在**首次尝试**查(`attempt === 0`):重试路径上的等待已经为这次的 retryAfter
|
|
48
|
+
// 付过时间,再查会撞上「我们自己的 penalize 刚写下的冷却行」把自己锁死(实测:
|
|
49
|
+
// 14009 → penalize 写冷却 → 紧随的重试被自己的冷却拦住 → 整窗 partial)。
|
|
50
|
+
if (ctx.gate !== undefined && attempt === 0) {
|
|
51
|
+
for (let waits = 0;; waits++) {
|
|
52
|
+
let cooled = null;
|
|
53
|
+
try {
|
|
54
|
+
await ctx.gate.acquire(endpointId);
|
|
55
|
+
}
|
|
56
|
+
catch (e) {
|
|
57
|
+
cooled = e;
|
|
58
|
+
if (cooled.kind !== 'rate_limit_local')
|
|
59
|
+
throw e;
|
|
60
|
+
}
|
|
61
|
+
if (cooled === null)
|
|
62
|
+
break;
|
|
63
|
+
// 有界等待(复用引擎的预算口径):到点重查,预算耗尽才上抛 —— 上抛后由引擎记
|
|
64
|
+
// `rate_limit_local` gap(不是 fetch_failed),本窗不落任何数据。
|
|
65
|
+
if (waits >= MAX_PACE_ATTEMPTS)
|
|
66
|
+
throw cooled;
|
|
67
|
+
const seconds = Math.ceil((cooled.retryAfter ?? 0) / 1000);
|
|
68
|
+
await sleep(clampGateWait((seconds + 1) * 1000) || GATE_WAIT_MIN_MS);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
44
71
|
try {
|
|
45
72
|
return await call(byId(endpointId), body, { credentials: ctx.credentials });
|
|
46
73
|
}
|
|
@@ -45,3 +45,35 @@ export function assertWriteContracts(tasks) {
|
|
|
45
45
|
throw new Error(`同步任务写策略声明违反契约:\n- ${violations.join('\n- ')}`);
|
|
46
46
|
}
|
|
47
47
|
}
|
|
48
|
+
/**
|
|
49
|
+
* 闸门键声明的前提(加载期校验,2026-11-15,Sourcery PR#58 复核):
|
|
50
|
+
* `gateEndpoints` 一旦声明就必须**非空**且包含主端点。空数组/漏写会静默回退成
|
|
51
|
+
* `[endpoint ?? id]`,多端点任务的次要端点冷却就永远读不到(实测形态见
|
|
52
|
+
* `tests/sync/gate-keys.test.ts` 文件头)。
|
|
53
|
+
* 不声明 `gateEndpoints` 仍是合法的「单端点任务」形态(21 个里 18 个如此);
|
|
54
|
+
* 要挡住的是「声明了但声明不完整」——那是唯一一种「看起来配了、实际没配上」的写法。
|
|
55
|
+
*/
|
|
56
|
+
export function gateContractViolations(tasks) {
|
|
57
|
+
const out = [];
|
|
58
|
+
for (const t of tasks) {
|
|
59
|
+
if (t.gateEndpoints === undefined)
|
|
60
|
+
continue; // 单端点任务:合法,回退到 [endpoint ?? id]
|
|
61
|
+
if (!Array.isArray(t.gateEndpoints) || t.gateEndpoints.length === 0) {
|
|
62
|
+
out.push(`${t.id}:gateEndpoints 声明为空 —— 会静默回退成单键,多端点任务的次要冷却读不到;`
|
|
63
|
+
+ '不需要闸门多键时请删掉该字段');
|
|
64
|
+
continue;
|
|
65
|
+
}
|
|
66
|
+
const primary = t.endpoint ?? t.id;
|
|
67
|
+
if (!t.gateEndpoints.includes(primary)) {
|
|
68
|
+
out.push(`${t.id}:gateEndpoints 未包含主端点 ${primary}(声明:${t.gateEndpoints.join('、')})——`
|
|
69
|
+
+ '主端点的冷却会被漏读');
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
return out;
|
|
73
|
+
}
|
|
74
|
+
export function assertGateContracts(tasks) {
|
|
75
|
+
const violations = gateContractViolations(tasks);
|
|
76
|
+
if (violations.length > 0) {
|
|
77
|
+
throw new Error(`同步任务闸门键声明违反契约:\n- ${violations.join('\n- ')}`);
|
|
78
|
+
}
|
|
79
|
+
}
|