qiyu-cli 0.2.0 → 0.2.2
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 +349 -57
- package/dist/cli.js +48 -7
- package/dist/commands/api-notes.js +54 -0
- package/dist/commands/api.js +113 -39
- package/dist/commands/auth.js +150 -28
- package/dist/commands/credentials-source.js +30 -5
- package/dist/commands/db-notes.js +75 -0
- package/dist/commands/db.js +112 -113
- package/dist/commands/query-notes.js +58 -0
- package/dist/commands/query.js +427 -56
- package/dist/commands/skill.js +477 -38
- package/dist/commands/spec-types.js +101 -1
- package/dist/commands/stats.js +139 -30
- package/dist/commands/store-flags.js +18 -0
- package/dist/commands/store-notes.js +38 -0
- package/dist/commands/store-precheck.js +254 -0
- package/dist/commands/store.js +128 -75
- package/dist/commands/sync-notes.js +367 -0
- package/dist/commands/sync-run.js +155 -44
- package/dist/commands/sync.js +182 -121
- package/dist/core/config.js +274 -24
- package/dist/core/credentials.js +38 -4
- package/dist/core/edition.js +13 -3
- package/dist/core/envelope.js +73 -9
- package/dist/core/errors.js +73 -16
- package/dist/core/http.js +151 -52
- package/dist/core/ratelimit.js +5 -1
- package/dist/core/registry/index.js +26 -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 +64 -42
- 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 +204 -28
- 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 +129 -24
- 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 +122 -27
- package/dist/skill/install.js +233 -43
- package/dist/skill/paths.js +54 -0
- package/dist/skill/qiyu/SKILL.md +38 -8
- 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 +51 -5
- package/dist/store/retry.js +92 -4
- package/dist/store/schema.js +26 -3
- package/dist/sync/engine.js +257 -65
- package/dist/sync/registry.js +4 -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/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 +47 -0
- package/package.json +1 -1
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// src/sync/tasks/sessions.ts
|
|
2
2
|
// D-T10:会话导出任务声明(spec §5.3)—— 唯一走四步流水线的 windowed 任务。
|
|
3
3
|
// 实测事实(设计稿 §7.5):
|
|
4
|
-
// ①
|
|
4
|
+
// ① 窗口跨度必须 **<** 6 天(恰 144.0h 报 14004,143.9999h 通过)→ maxWindowDays=6,
|
|
5
|
+
// 且 fetch 把请求收成 end−1(跨度 6 天 − 1ms,见 fetchSessions 内注释);
|
|
5
6
|
// ② 相邻窗口必须重叠 1 天(跨窗口长会话会漏,实测 5 会话/16 消息)→ overlapDays=1,
|
|
6
7
|
// 重叠行由按 session.id 的 upsert 幂等吸收(**去重按 session.id,绝不能按导出任务 key**);
|
|
7
8
|
// ③ **导出按 endTime 过滤**(判定式 window.start <= endTime <= window.end)→ 水位字段 endTime;
|
|
@@ -19,6 +20,20 @@ const isoOf = (ms) => new Date(ms).toISOString();
|
|
|
19
20
|
const strOrNull = (v) => v === null || v === undefined ? null : typeof v === 'string' ? v : JSON.stringify(v);
|
|
20
21
|
/** 空串主键/键列拒绝(C 低-7):`''` 是合法的 VARCHAR 值,会写出一行能被反复覆盖的同键行。 */
|
|
21
22
|
const isEmptyKey = (v) => v === null || v === undefined || v === '';
|
|
23
|
+
/**
|
|
24
|
+
* 会话行的主键取值:导出原生字段是 `id`,已投影行是 `session_id`。
|
|
25
|
+
* ⚠️ 规则**只在这里定义一份**:fetch 侧的丢弃判据与 `sessionRow` 的投影必须同源 ——
|
|
26
|
+
* 两处各写一份 `a ?? b` 时,写反了次序(fetch 用 `session_id ?? id`、投影用
|
|
27
|
+
* `id ?? session_id`)会让 `{id:'', session_id:'x'}` 在 fetch 被判「有键」、在 enrich
|
|
28
|
+
* 被判「缺键」,又回到「written < expected → 整窗 count_mismatch 回滚」的老路。
|
|
29
|
+
* 语义:取**第一个非空**候选 —— 空串不是键,但别名里有值就说明这行有键可用。
|
|
30
|
+
*/
|
|
31
|
+
function sessionKeyOf(src) {
|
|
32
|
+
for (const v of [src.id, src.session_id])
|
|
33
|
+
if (!isEmptyKey(v))
|
|
34
|
+
return v;
|
|
35
|
+
return undefined;
|
|
36
|
+
}
|
|
22
37
|
/** categoryDetail 归一化:"a / b / c / d" → "a/b/c/d"(导出 " / " 带空格 → /one 无空格)。 */
|
|
23
38
|
export function normalizeCategoryDetail(v) {
|
|
24
39
|
if (v === null || v === undefined || v === '')
|
|
@@ -52,7 +67,7 @@ export function deriveSessionType(staffId) {
|
|
|
52
67
|
* ⚠️ 本函数是纯投影(红线 1:同输入同输出)—— synchronized_at 从输入行透传
|
|
53
68
|
*(fetch 在进 enrich 前统一盖章,enrich 直测两调用相等);输入无戳则为 null(列可空)。 */
|
|
54
69
|
function sessionRow(src) {
|
|
55
|
-
const id = src
|
|
70
|
+
const id = sessionKeyOf(src);
|
|
56
71
|
// 键缺失/空串行:丢弃且不计入 fetched(与 apiCount 口径一致;C 低-7)
|
|
57
72
|
if (isEmptyKey(id))
|
|
58
73
|
return null;
|
|
@@ -80,7 +95,18 @@ async function fetchSessions(w, ctx) {
|
|
|
80
95
|
throw new Error('sessions.export 需要 fetchZip 注入(下载走 ZIP 二进制通道,与 JSON 信封层不同构)——生产接线归 sync run 编排层');
|
|
81
96
|
}
|
|
82
97
|
const nowIso = nowIsoOf(ctx);
|
|
83
|
-
|
|
98
|
+
// ⚠️ 引擎的 Range 是**半开**区间 [start, end),导出接口的判定式却是**闭**区间
|
|
99
|
+
// `window.start <= endTime <= window.end`(本文件第 ③ 条实测)。把 `w.end` 原样发出去
|
|
100
|
+
// 有两处错:① 多覆盖 1ms —— endTime == w.end 的行该归下一窗(下一窗起点是
|
|
101
|
+
// end − overlap,重叠幂等会吸收,但请求窗口与实际覆盖对不上);② 窗口跨度**恰好等于**
|
|
102
|
+
// maxWindowDays × 86400000 —— 实测服务端严格拒绝这个边界:跨度 518400000ms(144.0h)
|
|
103
|
+
// → `14004 Timestamp interval limit`,518399999ms(143.9999h)通过。2026-11-08 用真实
|
|
104
|
+
// 凭证复现:`sync run sessions.export` 每个 6 天窗都 fetch_failed(底层 Timestamp
|
|
105
|
+
// interval limit),水位冻结、一行不落。半开 → 闭区间的正确映射就是 `end − 1`,它同时
|
|
106
|
+
// 把跨度降到上限之内;1ms 窗保持原样(`end − 1 == start` 会撞 start==end 的 14004)。
|
|
107
|
+
// fixture 核对与 gap 文案一律用 `req`(服务端声明回显的是实际请求值),不用 `w`。
|
|
108
|
+
const req = { start: w.start, end: Math.max(w.start + 1, w.end - 1) };
|
|
109
|
+
const { sessions, fixture } = await runExportPipeline(req, {
|
|
84
110
|
credentials: ctx.credentials,
|
|
85
111
|
fetchZip: sctx.fetchZip,
|
|
86
112
|
pollIntervalMs: sctx.pollIntervalMs,
|
|
@@ -89,10 +115,29 @@ async function fetchSessions(w, ctx) {
|
|
|
89
115
|
gate: ctx.gate,
|
|
90
116
|
clock: ctx.clock,
|
|
91
117
|
});
|
|
118
|
+
// ⚠️ 缺 id 的行必须在 fetch 侧就丢弃并计数(2026-11-04 修)。此前它们留到 enrich
|
|
119
|
+
// 才被 `sessionRow` 丢掉,而 `apiCount` 已经按**丢弃前**的行数取好 —— 引擎的配对
|
|
120
|
+
// 基线于是包含永远不会落库的行:written < expected → 整窗 count_mismatch 回滚,
|
|
121
|
+
// 且 gap 只说「应写 N 行、实际写入 M 行」,不点名真正的原因(缺 id)。
|
|
122
|
+
// 现在与 reports 族同一口径:先过滤、apiCount 取过滤后行数、丢弃记 row_missing_key。
|
|
123
|
+
const withId = [];
|
|
124
|
+
let dropped = 0;
|
|
125
|
+
for (const r of sessions) {
|
|
126
|
+
// ⚠️ 必须走 `sessionKeyOf`,不能就地写 `r.session_id ?? r.id`(CodeRabbit PR #67 抓到):
|
|
127
|
+
// 两处各写一份时次序写反,`{id: 7, session_id: ''}` 会在 fetch 判「缺键」而
|
|
128
|
+
// `sessionRow` 判「有键」—— 合法行被丢弃、水位照常推进,且这条路径绕过 enrich 单测。
|
|
129
|
+
if (isEmptyKey(sessionKeyOf(r)))
|
|
130
|
+
dropped++;
|
|
131
|
+
else
|
|
132
|
+
withId.push(r);
|
|
133
|
+
}
|
|
92
134
|
// synchronized_at 在 fetch 侧按窗统一盖章(单值、确定性于本窗)——enrich 是纯投影
|
|
93
135
|
//(红线 1:同输入行永远同输出),只透传该戳;原始行直出(session.id 键、未投影)。
|
|
94
|
-
const stamped =
|
|
95
|
-
const base = { rows: stamped, apiCount:
|
|
136
|
+
const stamped = withId.map((r) => ({ ...r, synchronized_at: nowIso }));
|
|
137
|
+
const base = { rows: stamped, apiCount: withId.length };
|
|
138
|
+
const dropNote = dropped > 0
|
|
139
|
+
? `${dropped} 行缺 id(主键列,缺键或空串)被丢弃、未落库(已从上文的行数统计中扣除)`
|
|
140
|
+
: '';
|
|
96
141
|
// —— C-8:尾部标记行(fixture)= 导出自己的窗口声明,与请求窗口核对 ——
|
|
97
142
|
// 实测形态(private/raw/session.txt,4687 行样本):**完整导出必然带这一行**,恰好一行、
|
|
98
143
|
// 紧随全部 JSON 行之后,声明一个 24h 窗口。因此「带了它」是正常形态,不是异常;
|
|
@@ -100,38 +145,53 @@ async function fetchSessions(w, ctx) {
|
|
|
100
145
|
// ⚠️ fixture 非空 ⇒ 必然可解析(parseJsonl 与这里共用 parseExportFixture 判形态,
|
|
101
146
|
// 不会各写一套正则)——所以没有「fixture 解析不出」的分支,那是不可达代码。
|
|
102
147
|
const declared = fixture === undefined ? null : parseExportFixture(fixture);
|
|
103
|
-
if (declared !== null && (declared.start >
|
|
148
|
+
if (declared !== null && (declared.start > req.start || declared.end < req.end)) {
|
|
104
149
|
// 声明的窗口不覆盖本窗请求 → 本窗数据可疑(服务端实测会按(企业,窗口)复用已计算的
|
|
105
150
|
// 导出结果,同参数重复创建返回不同 key 相同数据)→ 宁可失败:fetch 抛错由引擎包装成
|
|
106
151
|
// 中文 gap(failDetail)+ 水位冻结(contiguousBroken),绝不把来路不明的行写进库。
|
|
107
152
|
throw new Error(`会话导出格式漂移(${fixture}):导出声明的窗口 ` +
|
|
108
153
|
`[${isoOf(declared.start)}, ${isoOf(declared.end)}] 未覆盖请求窗口 ` +
|
|
109
|
-
`[${isoOf(
|
|
154
|
+
`[${isoOf(req.start)}, ${isoOf(req.end)}] —— 本窗数据可疑,拒绝落库`);
|
|
110
155
|
}
|
|
111
156
|
if (fixture === undefined) {
|
|
112
157
|
// 完整导出应带尾部标记(见上);缺失 = 导出流没有声明它覆盖到哪 —— 空窗可能是真空、
|
|
113
158
|
// 也可能是流被截断在行边界(逐行 JSON 解析对截断在行中间的情况已显式失败)。
|
|
114
159
|
// 不判失败(历史样本可能无),但绝不静默:记一条 gap,让两类空窗可区分。
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
160
|
+
// ⚠️ 两条提示用**数组**带出(CodeRabbit PR #67):丢弃行(row_missing_key,真的少了)
|
|
161
|
+
// 与缺 fixture(export_fixture_unreported,覆盖无从核对)互不覆盖 —— 压成一条会让
|
|
162
|
+
// 消费方按 reason 分支时永远漏掉另一类信号。引擎逐条落 sync_gaps、逐条可分支。
|
|
163
|
+
const hints = [{
|
|
118
164
|
reason: 'export_fixture_unreported',
|
|
119
165
|
detail: `导出流未上报尾部标记行(完整导出末尾应有一行 startTime=…,endTime=… 声明导出窗口):` +
|
|
120
|
-
`本窗 ${
|
|
121
|
-
`请求窗口 [${isoOf(
|
|
122
|
-
}
|
|
123
|
-
|
|
166
|
+
`本窗 ${withId.length} 行数据的窗口覆盖无从核对 —— 空窗可能确实是空,也可能是导出流被截断在行边界。` +
|
|
167
|
+
`请求窗口 [${isoOf(req.start)}, ${isoOf(req.end)}]`,
|
|
168
|
+
}];
|
|
169
|
+
if (dropped > 0) {
|
|
170
|
+
hints.push({ reason: 'row_missing_key', detail: `sessions.export: ${dropNote} —— 上游响应形态漂移(正常导出每行都带 id),请核对接口返回` });
|
|
171
|
+
}
|
|
172
|
+
return { ...base, gapHint: hints };
|
|
124
173
|
}
|
|
125
|
-
if (declared !== null && (declared.start <
|
|
174
|
+
if (declared !== null && (declared.start < req.start || declared.end > req.end)) {
|
|
126
175
|
// 覆盖成立但宽于请求:多出来的行由 session_id 幂等 upsert 吸收(与 overlapDays 同机制),
|
|
127
176
|
// 数据不受损 —— 但「服务端改了窗口」这件事必须可见,记 gap 并带上标记行原文。
|
|
128
|
-
|
|
129
|
-
...base,
|
|
130
|
-
gapHint: {
|
|
177
|
+
const hints = [{
|
|
131
178
|
reason: 'export_window_mismatch',
|
|
132
179
|
detail: `导出声明的窗口 [${isoOf(declared.start)}, ${isoOf(declared.end)}] 宽于请求窗口 ` +
|
|
133
|
-
`[${isoOf(
|
|
180
|
+
`[${isoOf(req.start)}, ${isoOf(req.end)}](重叠行由 session_id 幂等吸收)`,
|
|
134
181
|
fixture,
|
|
182
|
+
}];
|
|
183
|
+
if (dropped > 0) {
|
|
184
|
+
hints.push({ reason: 'row_missing_key', detail: `sessions.export: ${dropNote} —— 上游响应形态漂移(正常导出每行都带 id),请核对接口返回` });
|
|
185
|
+
}
|
|
186
|
+
return { ...base, gapHint: hints };
|
|
187
|
+
}
|
|
188
|
+
if (dropped > 0) {
|
|
189
|
+
return {
|
|
190
|
+
...base,
|
|
191
|
+
gapHint: {
|
|
192
|
+
reason: 'row_missing_key',
|
|
193
|
+
detail: `sessions.export: ${dropNote} —— 上游响应形态漂移(正常导出每行都带 id),` +
|
|
194
|
+
'请核对接口返回;本次按已落库的行覆盖窗口',
|
|
135
195
|
},
|
|
136
196
|
};
|
|
137
197
|
}
|
|
@@ -157,8 +217,9 @@ export function assertFixtureGranularity(task) {
|
|
|
157
217
|
}
|
|
158
218
|
/**
|
|
159
219
|
* enrich:投影 + 确定性派生(红线 1 推论:同输入行永远同输出)。
|
|
160
|
-
* 派生 session_type(staffId 数字判别)+ categoryDetail
|
|
161
|
-
|
|
220
|
+
* 派生 session_type(staffId 数字判别)+ categoryDetail 归一化。缺 id 行在 **fetch 侧**
|
|
221
|
+
* 已丢弃并记 row_missing_key(此前留到这里才丢,与 apiCount 口径不一致会导致整窗
|
|
222
|
+
* count_mismatch 回滚);这里保留 null 兜底,正常输入不会触发。synchronized_at 从输入行透传
|
|
162
223
|
*(fetch 已统一盖章),无戳直测时为 null —— 本函数不含任何时钟读取。
|
|
163
224
|
*/
|
|
164
225
|
function enrichSession(src) {
|
|
@@ -173,6 +234,12 @@ export const SESSIONS_TASKS = [
|
|
|
173
234
|
primaryKey: ['session_id'],
|
|
174
235
|
// 闸门键 = 主驱动路径(create 是限频的那一个:10 秒 6 次);check 显式登记为无限频。
|
|
175
236
|
endpoint: 'export.session',
|
|
237
|
+
// ⚠️ 闸门必须覆盖 fetch 实际调用的**每个** endpoint(2026-11-02 实测修):
|
|
238
|
+
// `export.session` 被限流时 penalize 写的是它自己的冷却行,只声明一个键时引擎
|
|
239
|
+
// 恰好读的就是它 —— 但流水线还会调 `export.session.check`(登记为无限频,
|
|
240
|
+
// 理论上不会被 penalize)。把它一并声明是**为了让守卫能双向核对**
|
|
241
|
+
// (tests/sync/gate-keys.test.ts 按 fetch 实际调用的 id 集合比对),不是多余的。
|
|
242
|
+
gateEndpoints: ['export.session', 'export.session.check'],
|
|
176
243
|
write: { kind: 'upsertRows' },
|
|
177
244
|
fetch: fetchSessions,
|
|
178
245
|
enrich: enrichSession,
|
|
@@ -37,8 +37,11 @@ function assertOpWindow(w) {
|
|
|
37
37
|
throw usageError(`工单 op 窗口无效:opEnd 缺省/为 0 时服务端会静默返回全量,` +
|
|
38
38
|
`opStart<=0(1970 哨兵)会被静默钳制(窗口 start=${w.start}, end=${w.end})`);
|
|
39
39
|
}
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
// ⚠️ 零宽窗(start === end)同样拒绝(2026-11-09 审计):它的 opStart 不早于 opEnd,
|
|
41
|
+
// 若被发出去,服务端对它是否等于「未传 opEnd」没有契约保证 —— 姊妹管线
|
|
42
|
+
// (pipeline.ts 的会话导出)对同一形态已经是 `w.end <= w.start` 拒绝,两处判据必须同向。
|
|
43
|
+
if (w.start >= w.end) {
|
|
44
|
+
throw usageError(`工单 op 窗口无效(opStart 必须早于 opEnd):start=${w.start} >= end=${w.end}`);
|
|
42
45
|
}
|
|
43
46
|
}
|
|
44
47
|
/** usage 错误(退出码 2):本地参数问题,重试无用。 */
|
|
@@ -136,12 +139,39 @@ async function fetchTickets(w, ctx) {
|
|
|
136
139
|
assertOpWindow(w);
|
|
137
140
|
const nowIso = nowIsoOf(ctx);
|
|
138
141
|
const out = [];
|
|
142
|
+
let dropped = 0;
|
|
139
143
|
for (const r of await searchAllPages(w, ctx)) {
|
|
140
144
|
const row = ticketRow(r, nowIso);
|
|
141
145
|
if (row)
|
|
142
146
|
out.push(row);
|
|
147
|
+
else
|
|
148
|
+
dropped++;
|
|
143
149
|
}
|
|
144
|
-
return { rows: out, apiCount: out.length };
|
|
150
|
+
return { rows: out, apiCount: out.length, ...droppedTicketHint('tickets.search', dropped, 'id') };
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* 行被丢弃(缺主键列)时的 task gapHint(`row_missing_key`)。
|
|
154
|
+
*
|
|
155
|
+
* ⚠️ 与 reports.ts 的 `droppedHint` 同形(审查 #5,2026-11-03):`apiCount` 取的是过滤后
|
|
156
|
+
* 的行数,配对核对恒等 → 缺键行静默消失、窗口仍 complete。这些行真的没落库,必须留痕。
|
|
157
|
+
* (两处各写一份是有意的:tickets 与 reports 是两个任务文件,分层上不互相 import;
|
|
158
|
+
* `tests/sync-enums.test.ts` 保证 reason 值同属一个枚举、README 图例只释义一次。)
|
|
159
|
+
*/
|
|
160
|
+
function droppedTicketHint(taskId, dropped, keyName, skippedTickets = 0) {
|
|
161
|
+
if (dropped === 0 && skippedTickets === 0)
|
|
162
|
+
return {};
|
|
163
|
+
const parts = [];
|
|
164
|
+
if (dropped > 0)
|
|
165
|
+
parts.push(`${dropped} 行缺 ${keyName}(主键列,缺键或空串)被丢弃、未落库`);
|
|
166
|
+
if (skippedTickets > 0)
|
|
167
|
+
parts.push(`${skippedTickets} 张 touched 工单缺 ${keyName},其日志整单未拉取(规模未知)`);
|
|
168
|
+
return {
|
|
169
|
+
gapHint: {
|
|
170
|
+
reason: 'row_missing_key',
|
|
171
|
+
detail: `${taskId}: ${parts.join(';')}`
|
|
172
|
+
+ ' —— 上游响应形态漂移,请核对接口返回;本次按已落库的行覆盖窗口',
|
|
173
|
+
},
|
|
174
|
+
};
|
|
145
175
|
}
|
|
146
176
|
/**
|
|
147
177
|
* ticket.logs 任务 fetch:先用同窗口的 search 找出 touched 工单(窗口内有操作 = op 语义),
|
|
@@ -153,12 +183,20 @@ async function fetchTicketLogs(w, ctx) {
|
|
|
153
183
|
const nowIso = nowIsoOf(ctx);
|
|
154
184
|
// —— touched 工单:与 tickets.search 同窗同分页(同一份实现,短读/翻页上限语义一致)——
|
|
155
185
|
const touched = [];
|
|
186
|
+
let skippedTickets = 0;
|
|
156
187
|
for (const r of await searchAllPages(w, ctx)) {
|
|
157
|
-
|
|
158
|
-
|
|
188
|
+
// 缺 id 的 touched 工单:**它的日志整单拉不到**(CodeRabbit #61)。这不是「丢了日志
|
|
189
|
+
// 行」(行都没请求过),必须与 droppedLogs 分开计数并留痕——否则本轮 complete 而
|
|
190
|
+
// 这张工单的日志一行都没有。
|
|
191
|
+
if (isEmptyKey(r.id)) {
|
|
192
|
+
skippedTickets++;
|
|
193
|
+
continue;
|
|
194
|
+
}
|
|
195
|
+
touched.push(String(r.id));
|
|
159
196
|
}
|
|
160
197
|
// —— 逐单拉日志 ——
|
|
161
198
|
const out = [];
|
|
199
|
+
let droppedLogs = 0;
|
|
162
200
|
for (const tid of touched) {
|
|
163
201
|
const res = await callPaced('ticket.log', { ticketId: Number(tid) }, ctx);
|
|
164
202
|
// ticket.log 信封未实测(registry envelope=null)→ 宽松模式载荷;data 数组形态按实测 §10.3。
|
|
@@ -179,12 +217,20 @@ async function fetchTicketLogs(w, ctx) {
|
|
|
179
217
|
}
|
|
180
218
|
for (const r of rows) {
|
|
181
219
|
const logId = r.id;
|
|
182
|
-
|
|
183
|
-
|
|
220
|
+
// 键缺失/空串行:丢弃、计数并留痕(审查 #5)——否则这一单的日志无声消失(C 低-7)。
|
|
221
|
+
if (isEmptyKey(logId)) {
|
|
222
|
+
droppedLogs++;
|
|
223
|
+
continue;
|
|
224
|
+
}
|
|
184
225
|
out.push({ ticket_id: tid, log_id: String(logId), payload: JSON.stringify(r), synchronized_at: nowIso });
|
|
185
226
|
}
|
|
186
227
|
}
|
|
187
|
-
return {
|
|
228
|
+
return {
|
|
229
|
+
rows: out, apiCount: out.length,
|
|
230
|
+
// 两种丢失合成一条缺口(引擎每窗只有一个 gapHint):缺 id 的日志行 + 因缺 id 而
|
|
231
|
+
// 整单没拉日志的 touched 工单。detail 分开点名,规模不可混为一谈。
|
|
232
|
+
...droppedTicketHint('ticket.logs', droppedLogs, 'id', skippedTickets),
|
|
233
|
+
};
|
|
188
234
|
}
|
|
189
235
|
export const TICKET_TASKS = [
|
|
190
236
|
{
|
|
@@ -208,6 +254,11 @@ export const TICKET_TASKS = [
|
|
|
208
254
|
// 同路径任务共享冷却(B 中-6):touched 集合与逐单日志都经 ticket.search / ticket.log,
|
|
209
255
|
// 闸门键取主要驱动路径 ticket.search(与 tickets.search 任务同键,交替调用照样被拦)。
|
|
210
256
|
endpoint: 'ticket.search',
|
|
257
|
+
// ⚠️ 闸门必须覆盖 fetch 实际调用的**每个** endpoint(2026-11-02 实测修):逐单日志
|
|
258
|
+
// 的 `ticket.log` 被限流时 penalize 写的是 `__ratelimit__:ticket.log`,只声明
|
|
259
|
+
// `ticket.search` 会让引擎读不到那把冷却、下一窗照旧超发(实测:冷却行在库而
|
|
260
|
+
// acquire('ticket.search') 放行,随后又发 4 次 ticket.log)。
|
|
261
|
+
gateEndpoints: ['ticket.search', 'ticket.log'],
|
|
211
262
|
windowStartFloorDays: 31,
|
|
212
263
|
write: { kind: 'upsertRows' },
|
|
213
264
|
fetch: fetchTicketLogs,
|
package/dist/sync/types.js
CHANGED
|
@@ -1 +1,60 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* `sync run` 每任务的 `status` 取值(闭集)。
|
|
3
|
+
*
|
|
4
|
+
* ⚠️ 运行时数组而不是裸联合类型:这是**输出数据里的机器值**,Agent 要按它分支
|
|
5
|
+
* (重跑 / 报告人类 / 放弃)。值域必须能在运行时导出,图例与测试才能双向核对。
|
|
6
|
+
*
|
|
7
|
+
* ⚠️⚠️ **`partial` 的字面语义是「部分成功」,但它同样覆盖「一行都没落」**:
|
|
8
|
+
* windowed 任务的引擎对「全部窗口都失败」也产出 `partial`(`succeeded: 0,
|
|
9
|
+
* failed: N`)——`failed` 只留给连窗口循环都进不去的异常路径(快照任务的限频闸门拦截)。
|
|
10
|
+
* 2026-10-27 实测:`tickets.search --since 1d` 全窗失败 → `status: "partial"`、
|
|
11
|
+
* `windows: {succeeded: 0, failed: 1}`、退出码 1。所以判「这次到底有没有拿到数据」
|
|
12
|
+
* 要看 `windows.succeeded` 或退出码,**不要**看 `status` 的字面。
|
|
13
|
+
*/
|
|
14
|
+
export const RUN_STATUSES = ['complete', 'partial', 'failed'];
|
|
15
|
+
/**
|
|
16
|
+
* 任务层 `gapHint.reason` 的**全部取值**(业务提示类缺口)。
|
|
17
|
+
*
|
|
18
|
+
* ⚠️ 与引擎侧四个失败原因(`ENGINE_GAP_REASONS`,见 engine.ts)共同构成
|
|
19
|
+
* `sync_gaps.reason` / `sync status` 的 `gaps[].reason` / `sync run` 的 `gaps[].reason`
|
|
20
|
+
* 的完整值域 —— 消费方(Agent)按值分支,所以这里的每个值都必须在 README 图例里有
|
|
21
|
+
* 释义与动作(`tests/sync-enums.test.ts` 钉住两个方向:枚举 ⊆ 图例、图例 ⊆ 枚举)。
|
|
22
|
+
*
|
|
23
|
+
* 与失败类缺口的区别:这些是**成功窗上的提示** —— 窗口数据照常提交,`gaps` 非空
|
|
24
|
+
* 不等于同步失败。此前类型是 `string`、引擎用 `as WindowGapReason` 强转,把
|
|
25
|
+
* 「类型只声明四个」的谎报压了下去(2026-10-27 修)。
|
|
26
|
+
*
|
|
27
|
+
* ⚠️⚠️ 「提示」**不等于**「数据没缺」——这一族里有两档,消费方的动作不同,
|
|
28
|
+
* 合并成一句「数据未必缺」是误导(2026-11-02 审查):
|
|
29
|
+
* · **确实没落库**(`TASK_GAP_LOSSY_REASONS`):描述的行/成员**真的没进库**,
|
|
30
|
+
* `detail` 是丢失规模,必须核对上游形态;
|
|
31
|
+
* · **未必缺数据**(其余):可能只是筛选没命中、或空窗本来就空,按 `detail` 判断。
|
|
32
|
+
* 两档在 README 图例段有各自的一句话,`tests/sync-enums.test.ts` 双向核对
|
|
33
|
+
* (常量改了而 README 没改 → 红)。
|
|
34
|
+
*/
|
|
35
|
+
export const TASK_GAP_REASONS = [
|
|
36
|
+
'knowledge_row_malformed', // 快照映射时缺键列的行被丢弃(响应形态漂移)
|
|
37
|
+
'staff_id_list_malformed', // staffIdList 非数组(整组)或成员 id 为空(该成员)→ 这些成员未落库
|
|
38
|
+
'row_missing_key', // 窗口任务(报表/工单)映射时行缺主键列(缺键/空串)→ 该行被丢弃、未落库
|
|
39
|
+
'filter_matched_no_staff', // 报表筛选条件未命中任何客服(本窗按 0 行记)
|
|
40
|
+
'export_fixture_unreported', // 导出流未上报窗口声明行(空窗可能真空也可能被截断)
|
|
41
|
+
'export_window_mismatch', // 导出声明的窗口宽于请求(重叠行幂等吸收)
|
|
42
|
+
];
|
|
43
|
+
/**
|
|
44
|
+
* `TASK_GAP_REASONS` 里「**描述的行确实没落库**」的那一档(其余是「未必缺数据」的提示)。
|
|
45
|
+
*
|
|
46
|
+
* 判据是任务层对行的处理:`knowledge_row_malformed` 丢弃缺键列的行、
|
|
47
|
+
* `staff_id_list_malformed` 丢弃整组(非数组时)或空 id 成员、
|
|
48
|
+
* `row_missing_key` 丢弃窗口任务里缺主键列的行 —— 这些行不会以任何形式进库;
|
|
49
|
+
* 而 `filter_matched_no_staff`(上游本就没命中)、
|
|
50
|
+
* `export_window_mismatch`(重叠行被幂等 upsert 吸收,数据在库里)都不属于这一档,
|
|
51
|
+
* `export_fixture_unreported` 是「该不该有行」尚不可知,同样不在这一档。
|
|
52
|
+
*
|
|
53
|
+
* `tests/sync-enums.test.ts` 钉住它与 `TASK_GAP_REASONS` 的关系是**真划分**
|
|
54
|
+
* (非空、真子集),并核对 README 两档文案与它一致 —— 单一出处,不得在别处重抄一份。
|
|
55
|
+
*/
|
|
56
|
+
export const TASK_GAP_LOSSY_REASONS = [
|
|
57
|
+
'knowledge_row_malformed',
|
|
58
|
+
'staff_id_list_malformed',
|
|
59
|
+
'row_missing_key',
|
|
60
|
+
];
|
package/dist/sync/windowing.js
CHANGED
|
@@ -32,25 +32,3 @@ export function sliceByMaxWindow(range, maxWindowDays, overlapDays) {
|
|
|
32
32
|
}
|
|
33
33
|
return windows;
|
|
34
34
|
}
|
|
35
|
-
/**
|
|
36
|
-
* 合并相邻(start == 前者 end)与重叠的区间,保留缝隙。
|
|
37
|
-
* 输入不要求有序,结果按 start 升序。
|
|
38
|
-
*/
|
|
39
|
-
export function mergeRanges(rs) {
|
|
40
|
-
if (rs.length === 0)
|
|
41
|
-
return [];
|
|
42
|
-
const sorted = [...rs].sort((a, b) => a.start - b.start);
|
|
43
|
-
const merged = [{ ...sorted[0] }];
|
|
44
|
-
for (let i = 1; i < sorted.length; i++) {
|
|
45
|
-
const last = merged[merged.length - 1];
|
|
46
|
-
const cur = sorted[i];
|
|
47
|
-
if (cur.start <= last.end) {
|
|
48
|
-
// 相邻或重叠:延伸右端(含完全包含的情形)
|
|
49
|
-
last.end = Math.max(last.end, cur.end);
|
|
50
|
-
}
|
|
51
|
-
else {
|
|
52
|
-
merged.push({ ...cur });
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
return merged;
|
|
56
|
-
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { TABLES } from '../store/schema.js';
|
|
2
|
+
/** 返回该任务写策略声明违反的契约(空数组 = 通过)。 */
|
|
3
|
+
export function writeContractViolations(task) {
|
|
4
|
+
const write = task.write;
|
|
5
|
+
if (write.kind !== 'deleteRangeInsert')
|
|
6
|
+
return [];
|
|
7
|
+
const out = [];
|
|
8
|
+
if ('instantColumn' in write) {
|
|
9
|
+
const table = TABLES.find((t) => t.name === task.table);
|
|
10
|
+
if (table === undefined) {
|
|
11
|
+
out.push(`${task.id}:instantColumn 指向的表 '${task.table}' 不在 TABLES 里`);
|
|
12
|
+
return out;
|
|
13
|
+
}
|
|
14
|
+
if (!table.columns.some((c) => c.name === write.instantColumn)) {
|
|
15
|
+
out.push(`${task.id}:instantColumn '${write.instantColumn}' 不是表 '${task.table}' 的列`);
|
|
16
|
+
}
|
|
17
|
+
else if (table.timeColumn?.name !== write.instantColumn
|
|
18
|
+
|| table.timeColumn.kind !== 'iso-instant') {
|
|
19
|
+
out.push(`${task.id}:instantColumn '${write.instantColumn}' 必须是表 '${task.table}' 声明的`
|
|
20
|
+
+ ` timeColumn 且 kind='iso-instant'(删除值与 new Date(ms).toISOString() 同形的前提)`);
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
else {
|
|
24
|
+
// 两条独立判据(CodeRabbit #59 三轮):漏声明 rangeAlign 不会落进「对齐」分支,
|
|
25
|
+
// 引擎于是拿 `toISOString()` 的瞬时串(…T00:00:00.000Z)去比日粒度列值(YYYY-MM-DD)——
|
|
26
|
+
// 字符串前缀关系让窗起点**那一整日**的行永远删不掉(陈旧行),窗口仍报 complete。
|
|
27
|
+
if (write.rangeAlign !== 'shanghaiDay') {
|
|
28
|
+
out.push(`${task.id}:按日粒度范围列(${write.rangeColumns.join(', ')})删旧必须声明`
|
|
29
|
+
+ ` rangeAlign='shanghaiDay' —— 否则引擎用 ISO 瞬时串与日粒度列值比较,`
|
|
30
|
+
+ `窗起点那一日的行永远删不掉(静默留陈旧行、窗口仍 complete);`
|
|
31
|
+
+ `行内若有逐行时间列,改用 instantColumn`);
|
|
32
|
+
}
|
|
33
|
+
if (task.windowAlign !== 'shanghaiDay') {
|
|
34
|
+
out.push(`${task.id}:按日粒度范围列删旧只在窗起止都落上海日界时精确,`
|
|
35
|
+
+ `但任务未声明 windowAlign='shanghaiDay' —— 边界日会被相邻窗整片删掉;`
|
|
36
|
+
+ `让窗对齐到日界,或改用 instantColumn(行内有逐行时间列时)`);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
return out;
|
|
40
|
+
}
|
|
41
|
+
/** 注册表加载期守卫:任一任务违反契约即抛错(fail-fast,绝不带着错误声明起跑)。 */
|
|
42
|
+
export function assertWriteContracts(tasks) {
|
|
43
|
+
const violations = tasks.flatMap((t) => writeContractViolations(t));
|
|
44
|
+
if (violations.length > 0) {
|
|
45
|
+
throw new Error(`同步任务写策略声明违反契约:\n- ${violations.join('\n- ')}`);
|
|
46
|
+
}
|
|
47
|
+
}
|