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.
@@ -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=clock 当前或配对的另一端)——
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: clock() };
387
+ rangeOverride = { start: 0, end: now };
379
388
  }
380
389
  else if (sinceRaw !== undefined || untilRaw !== undefined) {
381
- const untilMs = untilRaw !== undefined ? parseTimeArg(untilRaw, clock, '--until') : null;
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, clock, '--since') : null;
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 ? clock()
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
- const untilEnd = parseTimeArg(untilRaw, clock, '--until');
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, [
@@ -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),`--pretty` 同时在 `rejected` 里。
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.includes('schema_version')
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
- // 凭证惰性解析:快照任务需要上游 fetch;纯 windowed 选中时不碰凭证
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 (!credOutcome.ok)
378
- return fail(credOutcome.error);
379
- creds = credOutcome.creds;
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 localRows = await store.count(t.table);
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
- if (t.kind === 'snapshot') {
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 });
@@ -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}`);
@@ -25,4 +25,4 @@
25
25
  */
26
26
  export const SKILL_CONTRACT_VERSION = 2;
27
27
  /** 包版本占位值;构建期被 copy-assets.mjs 替换为 package.json 的 version。 */
28
- export const PACKAGE_VERSION = '0.2.2';
28
+ export const PACKAGE_VERSION = '0.2.3';
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
- if (!opts.noRetry && !bucketFor(spec).tryAcquire(now())) {
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": false,
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,成功采样会向生产机器人写入会话数据(且未命中 FAQ 时 sessionId 会轮换)—— 故未继续采样。dangerous:false 只表示非破坏性,不代表无副作用。"
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
  }
@@ -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
- if (isLockError(e))
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 里。