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
|
@@ -368,21 +368,30 @@ export async function runSyncRun(argv) {
|
|
|
368
368
|
return storeInitFail(e, resolved.config.path);
|
|
369
369
|
}
|
|
370
370
|
// —— 区间合成(时钟注入点:parseTimeArg 接受 clock;Nd/yesterday 已带区间,
|
|
371
|
-
// YYYY-MM-DD/ISO 只给起点 → end
|
|
371
|
+
// YYYY-MM-DD/ISO 只给起点 → end 取本次区间合成的 now 或配对的另一端)——
|
|
372
372
|
// ⚠️ 判据用 `!== undefined`(「给了」)而非真值:上面已把空白取值拦成 usage,
|
|
373
373
|
// 两边用同一种判据才不会在日后又分叉出一个静默分支。
|
|
374
|
+
//
|
|
375
|
+
// ⚠️ **整段只读一次时钟**(2026-11-11 CI 实测修):`--since 1d` 由 parseTimeArg 内部
|
|
376
|
+
// 的 clock() 算出 `end`,此前这个 end 被丢掉、`--until` 缺省时又调一次 clock()——
|
|
377
|
+
// 两次 Date.now() 之间只要过去 ≥1ms,区间就从「1 天」变成「1 天 + ε」,
|
|
378
|
+
// `sliceByMaxWindow(…, 6, 1)` 于是切出第二窗(起点 = end−1d,几乎与首窗重合),
|
|
379
|
+
// 被 contained 合并;覆盖窗失败时按 skipped 结算 → `windows.total` 从 1 变 2。
|
|
380
|
+
// 区间两端必须来自**同一时刻**,否则「最近 N 天」的窗数取决于解析耗时。
|
|
381
|
+
const now = clock();
|
|
382
|
+
const clockAt = () => now;
|
|
374
383
|
let rangeOverride;
|
|
375
384
|
const sinceRaw = flags['--since'];
|
|
376
385
|
const untilRaw = flags['--until'];
|
|
377
386
|
if (flags['--full'] !== undefined) {
|
|
378
|
-
rangeOverride = { start: 0, end:
|
|
387
|
+
rangeOverride = { start: 0, end: now };
|
|
379
388
|
}
|
|
380
389
|
else if (sinceRaw !== undefined || untilRaw !== undefined) {
|
|
381
|
-
const untilMs = untilRaw !== undefined ? parseTimeArg(untilRaw,
|
|
390
|
+
const untilMs = untilRaw !== undefined ? parseTimeArg(untilRaw, clockAt, '--until') : null;
|
|
382
391
|
if (untilRaw !== undefined && untilMs === null) {
|
|
383
392
|
return usageFail(`--until 无法解析:${describeArgs([untilRaw])}。支持 Nd / yesterday / YYYY-MM-DD / ISO 8601`);
|
|
384
393
|
}
|
|
385
|
-
const sinceMs = sinceRaw !== undefined ? parseTimeArg(sinceRaw,
|
|
394
|
+
const sinceMs = sinceRaw !== undefined ? parseTimeArg(sinceRaw, clockAt, '--since') : null;
|
|
386
395
|
if (sinceRaw !== undefined && sinceMs === null) {
|
|
387
396
|
return usageFail(`--since 无法解析:${describeArgs([sinceRaw])}。支持 Nd / yesterday / YYYY-MM-DD / ISO 8601`);
|
|
388
397
|
}
|
|
@@ -391,7 +400,7 @@ export async function runSyncRun(argv) {
|
|
|
391
400
|
// end=now;成对:[since 时刻, until 时刻];--since 带 Nd 区间时用其 start。
|
|
392
401
|
const start = sinceMs === null ? 0
|
|
393
402
|
: typeof sinceMs === 'object' ? sinceMs.start : sinceMs;
|
|
394
|
-
const end = untilMs === null ?
|
|
403
|
+
const end = untilMs === null ? now
|
|
395
404
|
: typeof untilMs === 'object' ? untilMs.end : untilMs;
|
|
396
405
|
if (start >= end) {
|
|
397
406
|
return usageFail(`区间无效:解析后的起点不早于终点(start=${shanghaiIso(start)} >= end=${shanghaiIso(end)})`, EMPTY_RANGE_HINT);
|
|
@@ -430,6 +439,8 @@ export async function runSyncRun(argv) {
|
|
|
430
439
|
credentials: creds,
|
|
431
440
|
gate: new RateGate(store, clock),
|
|
432
441
|
clock,
|
|
442
|
+
// gap detail 的恢复动作要复现本次库选择(裸命令会去操作默认库)
|
|
443
|
+
storeLocation: { db: resolved.config.path, ...(resolved.profileFlag !== undefined ? { profileFlag: resolved.profileFlag } : {}) },
|
|
433
444
|
};
|
|
434
445
|
const onProgress = flags['--quiet'] === undefined
|
|
435
446
|
? (line) => { process.stderr.write(line + '\n'); }
|
|
@@ -453,6 +464,10 @@ export async function runSyncRun(argv) {
|
|
|
453
464
|
for (const t of selected) {
|
|
454
465
|
if (t.windowStartFloorDays === undefined)
|
|
455
466
|
continue;
|
|
467
|
+
// ⚠️ 这里**当场读钟**,不用区间合成的 `now`(Codex 2026-11-12 P2):本 note 是在
|
|
468
|
+
// 预测**引擎**的 `windowStartFloorDays` 钳制,而引擎按任务**执行时刻**的
|
|
469
|
+
// `nowOf(ctx)` 计算。整轮同步若跨过上海午夜,越早的钟越容易把「明天就能拉到」
|
|
470
|
+
// 说成「永远拉不到」。读得越晚越接近引擎的判据。
|
|
456
471
|
const floor = clock() - t.windowStartFloorDays * DAY_MS;
|
|
457
472
|
if (rangeOverride.end <= floor) {
|
|
458
473
|
floorNotes.set(t.id, [
|
|
@@ -469,7 +484,9 @@ export async function runSyncRun(argv) {
|
|
|
469
484
|
// 而输出是 complete、gaps 为空 —— 必须用 notes 把这一条说在明处,并给出真能用的写法。
|
|
470
485
|
const untilNotes = new Map();
|
|
471
486
|
if (rangeOverride !== undefined && untilRaw !== undefined) {
|
|
472
|
-
|
|
487
|
+
// 与区间合成同一时刻(clockAt):再读一次 clock 可能跨过上海日界,
|
|
488
|
+
// 提示会描述一个与实际区间不同的日子。
|
|
489
|
+
const untilEnd = parseTimeArg(untilRaw, clockAt, '--until');
|
|
473
490
|
// 只对「日期 / ISO 时刻」这两种定点写法提示:Nd / yesterday 解析成区间(end=now),
|
|
474
491
|
// 那是「最近 N 天」的常规用法,今天不满一天属既有语义(每日残段由次日 run 补全),
|
|
475
492
|
// 每次都提示只会变成噪音。
|
|
@@ -484,6 +501,11 @@ export async function runSyncRun(argv) {
|
|
|
484
501
|
// 旧文案一律劝「写到次日 0 点」,照做后提示消失、该日仍未同步)。
|
|
485
502
|
const dayStart = shanghaiDayStart(boundary);
|
|
486
503
|
if (t.windowEndClamp === 'shanghaiYesterday') {
|
|
504
|
+
// ⚠️ 当场读钟(Codex 2026-11-12 P2):本 note 预测的是引擎 `windowEndLimit`
|
|
505
|
+
// = `shanghaiYesterdayStart(nowOf(ctx))`,而 `nowOf(ctx)` 是任务**执行时刻**。
|
|
506
|
+
// 整轮同步跨过上海午夜时,早先采样的 now 会让上限停在昨天,提示于是误报
|
|
507
|
+
// 「调整 --until 也无法拉到」——而午夜后引擎上限已前移一天,把 --until 写到
|
|
508
|
+
// 次日 0 点其实能同步该整日。读得越晚越接近引擎的判据。
|
|
487
509
|
const limit = shanghaiYesterdayStart(clock());
|
|
488
510
|
if (dayStart >= limit) {
|
|
489
511
|
untilNotes.set(t.id, [
|
package/dist/commands/sync.js
CHANGED
|
@@ -10,7 +10,8 @@
|
|
|
10
10
|
// · verify 对 snapshot 任务做三方核对(本地表行数 / 上游任务 fetch 的 apiCount /
|
|
11
11
|
// sync_state 状态),对 windowed 任务不做上游全量重拉(成本高),只核对
|
|
12
12
|
// local_rows 与 sync_state 成功状态的一致性——expected_from_api 为 null,
|
|
13
|
-
// drift 非空时 detail
|
|
13
|
+
// drift 非空时 detail 说明核对方式;本地同名对象不是基表(view 等)时不计数、
|
|
14
|
+
// 也不为它发上游请求,drift 报 not_base_table(无法核对 ≠ 一致);
|
|
14
15
|
// · install/uninstall 的平台条目生成与命令执行在 src/schedule/install.ts,
|
|
15
16
|
// 平台检测与外部命令均为注入点(__setPlatform/__setRun);
|
|
16
17
|
// · install 前置探测(E 高-1):**必须存在真实成功证据** —— sync_state 有
|
|
@@ -27,7 +28,7 @@
|
|
|
27
28
|
import { homedir } from 'node:os';
|
|
28
29
|
import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
|
|
29
30
|
import { dirname } from 'node:path';
|
|
30
|
-
import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing } from './store-precheck.js';
|
|
31
|
+
import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing, OBJECT_KINDS_SQL, nonBaseTables, sameObjectName } from './store-precheck.js';
|
|
31
32
|
import { SYNC_TASKS, taskById, UNSUPPORTED_DATASETS } from '../sync/registry.js';
|
|
32
33
|
import { listGaps, listWatermarks } from '../sync/state.js';
|
|
33
34
|
import { statusFieldNotes, syncInstallFieldNotes, tasksFieldNotes, verifyFieldNotes } from './sync-notes.js';
|
|
@@ -35,7 +36,7 @@ import { resolveStoreConfig, currentStoreEnv } from '../store/config.js';
|
|
|
35
36
|
import { openStore } from '../store/index.js';
|
|
36
37
|
import { tableByName } from '../store/schema.js';
|
|
37
38
|
import { resolveCredentialsUsingFile, currentCredentialEnv } from './credentials-source.js';
|
|
38
|
-
import { ok, fail, usageFail, failFromTagged, setPretty, describeArgs, syncRunCommand, } from '../output.js';
|
|
39
|
+
import { ok, fail, usageFail, failFromTagged, setPretty, describeArgs, syncRunCommand, storeInitCommand, storeLocationOf, dbTablesCommand, } from '../output.js';
|
|
39
40
|
import { runSyncRun, SYNC_RUN_USAGE, msToShanghaiIso, RUN_FLAGS } from './sync-run.js';
|
|
40
41
|
import { thrownToExit } from './store.js';
|
|
41
42
|
import { currentPlatform, parseCron, runScheduleCommand, planInstall, planUninstall, } from '../schedule/install.js';
|
|
@@ -54,7 +55,8 @@ const UNINSTALL_FLAGS = [{ name: '--yes', kind: 'bool' }];
|
|
|
54
55
|
const TASKS_FLAGS = [...GLOBAL_FLAGS];
|
|
55
56
|
/**
|
|
56
57
|
* 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu sync …` 是否真的存在。
|
|
57
|
-
* `flags` 是**完整接受集**(含全局 flag
|
|
58
|
+
* `flags` 是**完整接受集**(含全局 flag);`rejected` 直接取 `REJECTED_FLAGS`(当前为空 ——
|
|
59
|
+
* `--pretty` 自 2026-10-24 G1 起已实现,不再是 rejected,见 `spec-types.ts` 顶部)。
|
|
58
60
|
*
|
|
59
61
|
* ⚠️ `sync run` 的 spec 在这里而不在 `sync-run.ts`:spec 描述的是**命令路径**,而路径的
|
|
60
62
|
* 分派在 `syncCommand`;`runSyncRun` 只拿到剥掉 `run` 之后的参数。解析器的 flag 常量由
|
|
@@ -141,6 +143,13 @@ function parseSubFlags(argv, valueFlags, boolFlags = []) {
|
|
|
141
143
|
const v = argv[i + 1];
|
|
142
144
|
if (v === undefined || v.startsWith('--'))
|
|
143
145
|
throw new Error(`${a} 缺少取值`);
|
|
146
|
+
// ⚠️ 重复的取值参数必须报错(2026-11-14,历史审查 PR#4/PR#71 复核):此前静默覆盖,
|
|
147
|
+
// 而 `store` / `query` / `sync run` 三处都拒绝(`store-flags.ts`、`query.ts`、
|
|
148
|
+
// `sync-run.ts`)—— 同一个输入在不同子命令上两种行为。判据是「重复会不会丢掉一个值」,
|
|
149
|
+
// 布尔 flag 反复出现是幂等的,不在其列。
|
|
150
|
+
if (Object.hasOwn(out.values, a)) {
|
|
151
|
+
throw new Error(`${a} 重复出现:只能给一次(不做静默覆盖)`);
|
|
152
|
+
}
|
|
144
153
|
out.values[a] = v;
|
|
145
154
|
i++;
|
|
146
155
|
}
|
|
@@ -214,7 +223,7 @@ async function openRo(config, profileFlag) {
|
|
|
214
223
|
const names = await store.tables();
|
|
215
224
|
// ⚠️ 表名不是身份证明(2026-11-07 审查实测):他人工具的 schema_version 可能没有
|
|
216
225
|
// version 列 —— 只认表名会让后续查询落 internal,把「不是本 CLI 的库」说成损坏。
|
|
217
|
-
const versionColumns = names.
|
|
226
|
+
const versionColumns = names.some((n) => sameObjectName('schema_version', n))
|
|
218
227
|
? (await store.query(SCHEMA_VERSION_COLUMNS_SQL)).rows.map((r) => String(r.column_name))
|
|
219
228
|
: undefined;
|
|
220
229
|
const missing = schemaVersionMissing(config.path, names, versionColumns);
|
|
@@ -336,6 +345,7 @@ export const DRIFT_KINDS = [
|
|
|
336
345
|
'state_pending', // 上次运行未完成/中断(range_status 非 complete)
|
|
337
346
|
'count_mismatch', // 本地行数 ≠ 上游行数(仅快照任务做上游核对)
|
|
338
347
|
'fetch_failed', // 上游取数失败 —— 无法核对 ≠ 一致
|
|
348
|
+
'not_base_table', // 本地同名对象不是基表(view 等)—— 不计数、不核对
|
|
339
349
|
];
|
|
340
350
|
async function syncVerify(argv) {
|
|
341
351
|
const help = subHelp(argv, 'verify');
|
|
@@ -368,15 +378,19 @@ async function syncVerify(argv) {
|
|
|
368
378
|
catch (e) {
|
|
369
379
|
return failFromTagged(e);
|
|
370
380
|
}
|
|
371
|
-
//
|
|
372
|
-
|
|
381
|
+
// 凭证懒解析(Codex PR#76 第三轮):只有**真的会发上游请求**的快照任务才算。凭证是
|
|
382
|
+
// 环境问题(auth_missing,退出码 1),而「本地同名对象不是基表」是本地可诊断的 drift ——
|
|
383
|
+
// 若后者成立,先报 auth_missing 会把真正的结论盖住。先解析一次(保持「库打不开时凭证问题
|
|
384
|
+
// 不抢先」的既有次序),**用不用**由下面的循环按实际需要决定;用不上就只告警。
|
|
373
385
|
const needsUpstream = tasks.some((t) => t.kind === 'snapshot');
|
|
374
386
|
let creds;
|
|
387
|
+
let credError = null;
|
|
375
388
|
if (needsUpstream) {
|
|
376
389
|
const credOutcome = resolveCredentialsUsingFile(currentCredentialEnv(), { profile: parsed.values['--profile'] });
|
|
377
|
-
if (
|
|
378
|
-
|
|
379
|
-
|
|
390
|
+
if (credOutcome.ok)
|
|
391
|
+
creds = credOutcome.creds;
|
|
392
|
+
else
|
|
393
|
+
credError = credOutcome.error;
|
|
380
394
|
}
|
|
381
395
|
const guarded = statGuard(resolved.path);
|
|
382
396
|
if (guarded !== null)
|
|
@@ -387,12 +401,40 @@ async function syncVerify(argv) {
|
|
|
387
401
|
const store = opened.store;
|
|
388
402
|
try {
|
|
389
403
|
const states = await listWatermarks(store);
|
|
404
|
+
// ⚠️ 只对**基表**做 COUNT(2026-11-14,PR #75 合并后自查):`information_schema` 把 view
|
|
405
|
+
// 也算作表,同名 view 的 `COUNT(*)` 会把 view 本体当查询执行 —— 底表被删/读外部文件时
|
|
406
|
+
// verify 整条落 internal(实测报文还把 view 定义里的底表名说成存储损坏、建议「备份重建」)。
|
|
407
|
+
// `store status` / `store init` / `db tables` 已是「只认基表、非基表进 warnings」,
|
|
408
|
+
// verify 同口径:数不出来就不报数,按 drift 点名(无法核对 ≠ 一致,沿 fetch_failed 的语义)。
|
|
409
|
+
// ⚠️ 按大小写不敏感比对(Codex PR#76 实测):一条 `"TICKETS"` view 会被 `"tickets"`
|
|
410
|
+
// 解析到并被执行,所以这里不能 `Set.has()` 精确比名字。
|
|
411
|
+
const nonBases = nonBaseTables((await store.query(OBJECT_KINDS_SQL)).rows);
|
|
412
|
+
const isNonBaseTask = (t) => nonBases.some((n) => sameObjectName(t.table, n));
|
|
413
|
+
// 凭证缺失只在**确实要发上游请求**时才致命:所有选中的快照任务本地都不是基表时,
|
|
414
|
+
// 本命令根本用不上凭证 —— 如实报 drift(not_base_table)比报 auth_missing 更有用。
|
|
415
|
+
if (credError !== null && !tasks.filter((t) => t.kind === 'snapshot').every(isNonBaseTask)) {
|
|
416
|
+
return fail(credError);
|
|
417
|
+
}
|
|
418
|
+
const loc = storeLocationOf(resolved.path, resolved.profileFlag);
|
|
390
419
|
const tasksOut = [];
|
|
391
420
|
for (const t of tasks) {
|
|
392
|
-
const
|
|
421
|
+
const isNonBase = isNonBaseTask(t);
|
|
422
|
+
const localRows = isNonBase ? null : await store.count(t.table);
|
|
393
423
|
const st = states.get(t.id);
|
|
394
424
|
const stateConsistent = st !== undefined && st.rangeStatus === 'complete' && st.watermark !== null;
|
|
395
425
|
const drift = [];
|
|
426
|
+
if (isNonBase) {
|
|
427
|
+
drift.push({
|
|
428
|
+
kind: 'not_base_table',
|
|
429
|
+
detail: `本地 ${t.table} 不是基表(view 等),未做行数核对 —— 执行它的主体会读到`
|
|
430
|
+
+ '错误数据或直接失败,所以「无法核对」不等于一致。用 `' + dbTablesCommand(loc)
|
|
431
|
+
+ '` 确认该名字实际是什么对象(非基表会在 meta.warnings 点名);若本 CLI 的表已被'
|
|
432
|
+
+ '同名 view 取代:先备份旧库文件,再把 --db 换成新的 .duckdb 路径跑 '
|
|
433
|
+
+ storeInitCommand('<新路径>', resolved.profileFlag) + ' 建库、'
|
|
434
|
+
+ syncRunCommand('<新路径>', resolved.profileFlag) + ' 重新拉取'
|
|
435
|
+
+ '(把 <新路径> 整段替换成新路径,不要指回出问题的文件)',
|
|
436
|
+
});
|
|
437
|
+
}
|
|
396
438
|
if (st === undefined) {
|
|
397
439
|
drift.push({
|
|
398
440
|
kind: 'not_synced',
|
|
@@ -411,7 +453,9 @@ async function syncVerify(argv) {
|
|
|
411
453
|
});
|
|
412
454
|
}
|
|
413
455
|
let expectedFromApi = null;
|
|
414
|
-
|
|
456
|
+
// 本地没有可数的表时无从核对:不再为此花一次上游请求(`localRows === null` 时
|
|
457
|
+
// `null !== number` 恒真,会白白把每条快照任务打成 count_mismatch)。
|
|
458
|
+
if (t.kind === 'snapshot' && localRows !== null) {
|
|
415
459
|
// 上游取数 = 任务 fetch(配对口径沿引擎:apiCount 为准,缺省取行数)。
|
|
416
460
|
try {
|
|
417
461
|
const res = await t.fetch({ start: 0, end: Date.now(), index: 0, total: 1 }, { store, credentials: creds });
|
package/dist/core/config.js
CHANGED
|
@@ -79,6 +79,12 @@ function assertObject(v, label) {
|
|
|
79
79
|
* `store/config.ts` 的领域知识,本文件只保证「它是一个对象、键已知」。
|
|
80
80
|
*/
|
|
81
81
|
export function parseConfig(raw) {
|
|
82
|
+
// ⚠️ 顶层形态必须先验(2026-11-14,历史审查 PR#4 复核):`readConfigRaw` 只保证
|
|
83
|
+
// 「是合法 JSON」,`as Record<string, unknown>` 是**强转**。此前标量(`42` / `"x"`)
|
|
84
|
+
// 的 `Object.keys` 是 `[]`,被静默当成空配置 → 所有调用方回落默认库/默认 robots;
|
|
85
|
+
// `null` 更糟:`Object.keys(null)` 抛 TypeError,经 `failFromTagged` 成「用法错误」,
|
|
86
|
+
// Agent 会以为自己参数写错了。配置文件写坏 ≠ 没配。
|
|
87
|
+
assertObject(raw, '顶层');
|
|
82
88
|
for (const k of Object.keys(raw)) {
|
|
83
89
|
if (!KNOWN_TOP.has(k))
|
|
84
90
|
throw new Error(`配置文件未知键:${k}`);
|
package/dist/core/edition.js
CHANGED
package/dist/core/http.js
CHANGED
|
@@ -220,12 +220,30 @@ export async function call(spec, body, opts) {
|
|
|
220
220
|
// 返回 undefined,fetch 收到的就是 `body: undefined`,签名口径 `md5('')`。
|
|
221
221
|
// 不再写 `GET ? undefined : buildBody(body)`:有守卫在,那是恒等分支。
|
|
222
222
|
const bodyStr = buildBody(body);
|
|
223
|
-
|
|
223
|
+
/**
|
|
224
|
+
* 取一次本地限频令牌;取不到按 `local_rate_limit` 抛出(退出码 1、可重试,带精确等待)。
|
|
225
|
+
*
|
|
226
|
+
* ⚠️ **每次出站请求都要经过这里**(2026-11-14,历史审查 PR#58 复核 + 独立核实):
|
|
227
|
+
* 此前只在进入重试循环前取一次,而四条网络重试分支每条都会再发一个真实请求 ——
|
|
228
|
+
* 限频表里可发多次的接口(`data.overview.ipcc` 10/60s、`export.session` 6/10s、
|
|
229
|
+
* `ai.knowledge.getDetail` 10/s)一次逻辑调用最多发出 3 个请求、只占 1 个令牌,等于
|
|
230
|
+
* 绕过预算;超发在 sync 同进程反复调用时累积,正是「宁可慢,不超发」要挡的。
|
|
231
|
+
* `callPaced` 认得这个 code,会按 retryAfter 等待后重来(等待 + 重来是**有界**的:
|
|
232
|
+
* 它最多重来 3 次,每次进入 `call()` 又最多 3 个网络请求 → 单次任务调用最多 12 个出站
|
|
233
|
+
* 请求,且每一步都仍受令牌桶约束;不会因为「重试被预算拦住」而无限循环)。
|
|
234
|
+
* ⚠️ 14003 重签重试**不走这里**:那是**未执行**的鉴权重试(服务端在执行前拒绝),
|
|
235
|
+
* 把它计入预算会让时钟偏移的写接口直接失败在这里 —— 与它的唯一目的相反。
|
|
236
|
+
*/
|
|
237
|
+
const acquireToken = () => {
|
|
238
|
+
if (bucketFor(spec).tryAcquire(now()))
|
|
239
|
+
return;
|
|
224
240
|
const waitMs = bucketFor(spec).nextAvailableAt(now());
|
|
225
241
|
throw Object.assign(new Error(`接口 ${spec.id} 触发本地限频,还需等待约 ${Math.ceil(waitMs / 1000)} 秒`), { code: 'local_rate_limit', kind: 'rate_limit', retryable: true,
|
|
226
242
|
// 本地令牌桶算出的精确等待(不是猜的)—— source: 'local'
|
|
227
243
|
retryAfter: { seconds: Math.ceil(waitMs / 1000), source: 'local' } });
|
|
228
|
-
}
|
|
244
|
+
};
|
|
245
|
+
if (!opts.noRetry)
|
|
246
|
+
acquireToken();
|
|
229
247
|
let signedTime = Math.floor(now() / 1000);
|
|
230
248
|
// 两个独立的预算:网络重试与 14003 重签重试互不挤占。
|
|
231
249
|
// 共用一个计数器会让"先网络失败一次"把重签重试的机会吃掉。
|
|
@@ -279,6 +297,7 @@ export async function call(spec, body, opts) {
|
|
|
279
297
|
if (opts.noRetry || networkAttempts >= 2)
|
|
280
298
|
throw Object.assign(new Error(err.message), err);
|
|
281
299
|
await sleep(networkBackoffMs(networkAttempts));
|
|
300
|
+
acquireToken();
|
|
282
301
|
networkAttempts++;
|
|
283
302
|
continue;
|
|
284
303
|
}
|
|
@@ -311,6 +330,7 @@ export async function call(spec, body, opts) {
|
|
|
311
330
|
if (opts.noRetry || networkAttempts >= 2)
|
|
312
331
|
throw Object.assign(new Error(err.message), err);
|
|
313
332
|
await sleep(networkBackoffMs(networkAttempts));
|
|
333
|
+
acquireToken();
|
|
314
334
|
networkAttempts++;
|
|
315
335
|
continue;
|
|
316
336
|
}
|
|
@@ -367,6 +387,7 @@ export async function call(spec, body, opts) {
|
|
|
367
387
|
// 现在四支的预算一致(同一 `networkAttempts`)。
|
|
368
388
|
if (transient && !opts.noRetry && networkAttempts < 2) {
|
|
369
389
|
await sleep(networkBackoffMs(networkAttempts));
|
|
390
|
+
acquireToken();
|
|
370
391
|
networkAttempts++;
|
|
371
392
|
continue;
|
|
372
393
|
}
|
|
@@ -431,6 +452,7 @@ export async function call(spec, body, opts) {
|
|
|
431
452
|
// 429 不在其中:它归 rate_limit(未执行、需按冷却等待),不自动重试。
|
|
432
453
|
if (err.kind === 'network' && !opts.noRetry && networkAttempts < 2) {
|
|
433
454
|
await sleep(networkBackoffMs(networkAttempts));
|
|
455
|
+
acquireToken();
|
|
434
456
|
networkAttempts++;
|
|
435
457
|
continue;
|
|
436
458
|
}
|
|
@@ -192,6 +192,16 @@ const INDEX = new Map(SPECS.map((e) => [e.id, e]));
|
|
|
192
192
|
export function allEndpoints() {
|
|
193
193
|
return SPECS;
|
|
194
194
|
}
|
|
195
|
+
/**
|
|
196
|
+
* 按 id 查,找不到返回 `undefined`(不抛)。
|
|
197
|
+
*
|
|
198
|
+
* ⚠️ 用途只有一处(2026-11-13):调用方在**抛错的那些出口**上也要知道接口是否实测
|
|
199
|
+
* (`api call` 的用法错误早于 `byId()` 返回),那种场合不能用抛错的 `byId`。
|
|
200
|
+
* 其余地方仍用 `byId` —— 静默返回 undefined 会让调用方崩在离病根很远的地方。
|
|
201
|
+
*/
|
|
202
|
+
export function byIdOrUndefined(id) {
|
|
203
|
+
return typeof id === 'string' ? INDEX.get(id) : undefined;
|
|
204
|
+
}
|
|
195
205
|
/** 未知 id 直接抛错 —— 静默返回 undefined 会让调用方崩在离病根很远的地方。 */
|
|
196
206
|
export function byId(id) {
|
|
197
207
|
const spec = INDEX.get(id);
|
|
@@ -1481,12 +1481,12 @@
|
|
|
1481
1481
|
"path": "/openapi/robot/session/chat",
|
|
1482
1482
|
"direction": "outbound",
|
|
1483
1483
|
"callable": true,
|
|
1484
|
-
"dangerous":
|
|
1484
|
+
"dangerous": true,
|
|
1485
1485
|
"auth": "checksum",
|
|
1486
1486
|
"verified": false,
|
|
1487
1487
|
"envelope": null,
|
|
1488
1488
|
"category": "机器人/消息接口/会话类接口",
|
|
1489
|
-
"note": "成功路径未实测(2026-10-30):`msg` 传字符串返回 `{code:14004, message:\"body内容json解析错误\"}` —— 必须传**对象** `{\"msgType\":\"text\",\"msgBody\":{\"content\":\"…\"}}`(此前已实测记录;厂商文档把 msg 标成 type:string,是错的)。⚠️ 该接口**不是只读**:会话不存在时会**自动创建真实会话**并返回 sessionId
|
|
1489
|
+
"note": "成功路径未实测(2026-10-30):`msg` 传字符串返回 `{code:14004, message:\"body内容json解析错误\"}` —— 必须传**对象** `{\"msgType\":\"text\",\"msgBody\":{\"content\":\"…\"}}`(此前已实测记录;厂商文档把 msg 标成 type:string,是错的)。⚠️ 该接口**不是只读**:会话不存在时会**自动创建真实会话**并返回 sessionId,成功调用会向生产机器人写入会话数据(且未命中 FAQ 时 sessionId 会轮换)—— 故未继续采样。**2026-11-19 改判 `dangerous: false → true`**:此前登记为 false 并附注「只表示非破坏性、不代表无副作用」,但 §5.2 对 `dangerous` 的定义是「**写**/破坏性操作 → 需要 --yes」—— 它会写(自动建会话),且同族的 `robot.session.create` 就是 true。误分类的代价是一次不动声色的生产写入被门禁放行,因此按定义收口,`--yes` 门禁自此生效。"
|
|
1490
1490
|
},
|
|
1491
1491
|
{
|
|
1492
1492
|
"id": "robot.session.close",
|
package/dist/output.js
CHANGED
|
@@ -327,6 +327,15 @@ export function fail(error) {
|
|
|
327
327
|
e.retry_strategy = error.retryStrategy;
|
|
328
328
|
if (error.fallback)
|
|
329
329
|
e.fallback = error.fallback;
|
|
330
|
+
if (error.unverifiedEndpoint) {
|
|
331
|
+
// ⚠️ 键名是 `unverified_endpoint`,语义是「**未**实测」—— 必须取反。
|
|
332
|
+
// 2026-11-13 实测踩过:这里曾直接赋 `verified`,于是已实测接口输出 `true`、
|
|
333
|
+
// 未实测输出 `false`,与成功路径(未实测才给 `true`)正好相反。
|
|
334
|
+
// 错误路径显式给 true/false:已实测的接口也要说 false,Agent 才不用去猜
|
|
335
|
+
// 「键不出现」是什么意思(见 `ErrorInput.unverifiedEndpoint` 的注释)。
|
|
336
|
+
e.unverified_endpoint = !error.unverifiedEndpoint.verified;
|
|
337
|
+
e.endpoint = sanitizeMessage(error.unverifiedEndpoint.id);
|
|
338
|
+
}
|
|
330
339
|
// ⚠️ 确认字段与退出码必须由**同一个判据**决定,不能是两个独立闸门。
|
|
331
340
|
// 设计稿 §9.1 要求退出码 4 **必须**携带 `confirm_required`/`confirm_arg`/`risk`/`target`
|
|
332
341
|
// 且 `retryable: false`。此前 `exitCodeFor(kind)` 与 `if (error.confirmRequired)` 互相独立,
|
|
@@ -422,7 +431,7 @@ export function failFromTagged(e) {
|
|
|
422
431
|
}
|
|
423
432
|
return usageFail(sanitizeMessage(err.message ?? String(e)));
|
|
424
433
|
}
|
|
425
|
-
export function usageFail(message, hint) {
|
|
434
|
+
export function usageFail(message, hint, unverifiedEndpoint) {
|
|
426
435
|
// ⚠️ stderr 是不受信文本进终端的主通道(security S4):未知参数、未知表名、DuckDB 原文
|
|
427
436
|
// 都拼进 message,未经净化就能注入 ANSI/OSC 序列。净化必须在**出口**做一次,
|
|
428
437
|
// 而不是靠每个调用点自觉补 —— 实测 `db describe` / `query --table` 的未知表路径补了、
|
|
@@ -435,5 +444,6 @@ export function usageFail(message, hint) {
|
|
|
435
444
|
// message 去尾换行 —— stdout 的 JSON 里不该带控制字符;stderr 的文本保留换行便于阅读。
|
|
436
445
|
message: safe.replace(/\n+$/, ''),
|
|
437
446
|
...(hint !== undefined ? { hint: sanitizeMessage(hint) } : {}),
|
|
447
|
+
...(unverifiedEndpoint !== undefined ? { unverifiedEndpoint } : {}),
|
|
438
448
|
});
|
|
439
449
|
}
|
package/dist/query/sandbox.js
CHANGED
|
@@ -392,6 +392,22 @@ export async function openSandbox(cfg, deps = {}) {
|
|
|
392
392
|
tryOpen: open,
|
|
393
393
|
isRetryable: isLockError,
|
|
394
394
|
maxMs: cfg.readOnlyRetryMs,
|
|
395
|
+
// ⚠️ `attemptMs` 必须传(CodeRabbit PR#74 第三轮):不传时 `withAttemptTimeout` 直接返回
|
|
396
|
+
// 原 promise,截止时间只会在**抛错后**才比较 —— `create`/`connect` 卡住(网络盘、卡死的
|
|
397
|
+
// 锁等待)就没有任何上界,`qiyu query` / `db tables` / `stats` 会无限挂着。
|
|
398
|
+
// `store` 那条路径早已传,此处漏掉的后果是「有界打开」只覆盖了一半的只读命令。
|
|
399
|
+
attemptMs: cfg.readOnlyRetryMs,
|
|
400
|
+
// 超时被放弃的尝试若稍后成功,交回关掉(否则多一个锁持有者)。
|
|
401
|
+
onAbandoned: (r) => {
|
|
402
|
+
try {
|
|
403
|
+
r.conn.closeSync?.();
|
|
404
|
+
}
|
|
405
|
+
catch { /* 清理失败不掩盖原错误 */ }
|
|
406
|
+
try {
|
|
407
|
+
r.inst.closeSync?.();
|
|
408
|
+
}
|
|
409
|
+
catch { /* 同上 */ }
|
|
410
|
+
},
|
|
395
411
|
sleep: deps.sleep,
|
|
396
412
|
now: deps.now,
|
|
397
413
|
});
|
|
@@ -399,7 +415,9 @@ export async function openSandbox(cfg, deps = {}) {
|
|
|
399
415
|
conn = r.conn;
|
|
400
416
|
}
|
|
401
417
|
catch (e) {
|
|
402
|
-
|
|
418
|
+
// 打开超时与撞锁是同一类后果(等不到库),走同一条 store_locked 出口 ——
|
|
419
|
+
// 否则超时会落到下面的 `classifyOpenFailure`,识别不出 → 变成「库不存在」类的误导。
|
|
420
|
+
if (isLockError(e) || e.timedOut === true)
|
|
403
421
|
throw lockedError(cfg);
|
|
404
422
|
// 其余打开失败(库不存在 / 非 DuckDB 文件 / 权限)→ store_not_initialized(spec §十一:
|
|
405
423
|
// 库不存在 → 退出码 1、hint 指 `qiyu store init`)。底层原文保留在 message 里。
|