qiyu-cli 0.2.1 → 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.
Files changed (70) hide show
  1. package/README.md +345 -56
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +54 -0
  4. package/dist/commands/api.js +112 -38
  5. package/dist/commands/auth.js +150 -28
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +112 -113
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +427 -56
  11. package/dist/commands/skill.js +445 -51
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +139 -30
  14. package/dist/commands/store-flags.js +18 -0
  15. package/dist/commands/store-notes.js +38 -0
  16. package/dist/commands/store-precheck.js +254 -0
  17. package/dist/commands/store.js +128 -75
  18. package/dist/commands/sync-notes.js +367 -0
  19. package/dist/commands/sync-run.js +155 -44
  20. package/dist/commands/sync.js +181 -120
  21. package/dist/core/config.js +274 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +1 -1
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +151 -52
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +26 -2
  29. package/dist/core/registry/params/export.session.check.json +17 -2
  30. package/dist/core/registry/params/export.session.json +24 -2
  31. package/dist/core/registry/params/export.session.one.json +10 -2
  32. package/dist/core/registry/params/export.session.one.message.json +17 -2
  33. package/dist/core/registry/specs.json +64 -42
  34. package/dist/core/shell.js +30 -0
  35. package/dist/core/time.js +1 -1
  36. package/dist/core/validate.js +21 -2
  37. package/dist/output.js +204 -28
  38. package/dist/postinstall.js +14 -5
  39. package/dist/query/errors.js +145 -45
  40. package/dist/query/mask.js +1277 -25
  41. package/dist/query/metric-catalog.js +11 -0
  42. package/dist/query/native-error.js +189 -0
  43. package/dist/query/sandbox.js +129 -24
  44. package/dist/query/table-query.js +36 -5
  45. package/dist/schedule/install.js +136 -13
  46. package/dist/skill/check.js +11 -6
  47. package/dist/skill/detect.js +89 -29
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +29 -5
  51. package/dist/skill/qiyu/errors.md +5 -4
  52. package/dist/skill/qiyu/protocols.md +57 -5
  53. package/dist/skill/qiyu/setup.md +6 -2
  54. package/dist/store/config.js +92 -16
  55. package/dist/store/duckdb.js +51 -5
  56. package/dist/store/retry.js +92 -4
  57. package/dist/store/schema.js +26 -3
  58. package/dist/sync/engine.js +257 -65
  59. package/dist/sync/registry.js +4 -0
  60. package/dist/sync/state.js +20 -0
  61. package/dist/sync/tasks/dim.js +23 -14
  62. package/dist/sync/tasks/knowledge.js +50 -8
  63. package/dist/sync/tasks/pipeline.js +29 -9
  64. package/dist/sync/tasks/reports.js +176 -49
  65. package/dist/sync/tasks/sessions.js +88 -21
  66. package/dist/sync/tasks/tickets.js +59 -8
  67. package/dist/sync/types.js +60 -1
  68. package/dist/sync/windowing.js +0 -22
  69. package/dist/sync/write-contract.js +47 -0
  70. package/package.json +1 -1
@@ -25,20 +25,23 @@
25
25
  // 输出键一律下划线命名(spec §七:range_status / gaps_count / local_rows /
26
26
  // expected_from_api / state_windows_consistent)——本仓 Agent 契约的统一形态。
27
27
  import { homedir } from 'node:os';
28
- import { statSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
28
+ import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
29
29
  import { dirname } from 'node:path';
30
+ import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing } from './store-precheck.js';
30
31
  import { SYNC_TASKS, taskById, UNSUPPORTED_DATASETS } from '../sync/registry.js';
31
32
  import { listGaps, listWatermarks } from '../sync/state.js';
33
+ import { statusFieldNotes, syncInstallFieldNotes, tasksFieldNotes, verifyFieldNotes } from './sync-notes.js';
32
34
  import { resolveStoreConfig, currentStoreEnv } from '../store/config.js';
33
35
  import { openStore } from '../store/index.js';
34
36
  import { tableByName } from '../store/schema.js';
35
37
  import { resolveCredentialsUsingFile, currentCredentialEnv } from './credentials-source.js';
36
- import { ok, fail, usageFail, setPretty } from '../output.js';
38
+ import { ok, fail, usageFail, failFromTagged, setPretty, describeArgs, syncRunCommand, } from '../output.js';
37
39
  import { runSyncRun, SYNC_RUN_USAGE, msToShanghaiIso, RUN_FLAGS } from './sync-run.js';
38
40
  import { thrownToExit } from './store.js';
39
- import { currentPlatform, runScheduleCommand, planInstall, planUninstall, } from '../schedule/install.js';
40
- import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, prettyAfterSubcommand, REJECTED_FLAGS, STORE_FLAGS, valueFlagNames } from './spec-types.js';
41
- import { STORE_VALUE_FLAG_NAMES } from './store-flags.js';
41
+ import { currentPlatform, parseCron, runScheduleCommand, planInstall, planUninstall, } from '../schedule/install.js';
42
+ import { GLOBAL_FLAGS, helpArgsError, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS, STORE_FLAGS, valueFlagNames } from './spec-types.js';
43
+ import { DB_PATH_HELP, STORE_VALUE_FLAG_NAMES } from './store-flags.js';
44
+ import { nonEmptyValue } from '../core/config.js';
42
45
  /** `sync install` 的业务 flag。 */
43
46
  const INSTALL_FLAGS = [
44
47
  { name: '--schedule', kind: 'value' },
@@ -125,11 +128,11 @@ const USAGE = `用法:qiyu sync <子命令> [参数]
125
128
 
126
129
  CRON 为 5 段(分 时 日 月 周),支持 * / 数字 / a-b / a-b/k / */k / 逗号列表。
127
130
  存储定位:--db / --profile / --backend(store 命令同族)。
131
+ ${DB_PATH_HELP}
128
132
  install 的平台形态:darwin=launchd plist、linux=systemd unit+timer(crontab 兜底)、
129
133
  win32=schtasks。安装前置:库已初始化且至少成功同步过一次(sync_state 有
130
134
  range_status=complete 或 last_synced_at 非空的行;全败的 run 只留 pending,不算跑通)。
131
135
  `;
132
- const KNOWN = new Set(GLOBAL_FLAG_NAMES);
133
136
  function parseSubFlags(argv, valueFlags, boolFlags = []) {
134
137
  const out = { values: {}, flags: new Set(), rest: [] };
135
138
  for (let i = 0; i < argv.length; i++) {
@@ -161,13 +164,19 @@ function parseSubFlags(argv, valueFlags, boolFlags = []) {
161
164
  }
162
165
  return out;
163
166
  }
164
- /** 子命令的 --help 分流:--help 在则打 USAGE;带非 KNOWN 额外参数 → usage。 */
165
- function subHelp(argv) {
167
+ /**
168
+ * 子命令的 --help 分流:--help 在则打 USAGE;只有**未知 flag** 才算额外参数。
169
+ *
170
+ * ⚠️ 此前拿 `GLOBAL_FLAG_NAMES` 过滤 argv:`sync install --schedule "0 3 * * *" --help`
171
+ * 退 2 并说「未知参数:--schedule、0 3 * * *」—— 一个帮助请求被自己的合法参数判了死刑
172
+ *(2026-11-06 审查;`api list --all --help` 却退 0)。完整接受集从 spec 取。
173
+ */
174
+ function subHelp(argv, sub) {
166
175
  if (!argv.includes('--help') && !argv.includes('-h'))
167
176
  return null;
168
- const extra = argv.filter((a) => !KNOWN.has(a));
169
- if (extra.length > 0)
170
- return usageFail(`未知参数:${extra.join(' ')}。--help 不接受额外参数`);
177
+ const problem = helpArgsError(argv, SYNC_SPECS.find((sp) => sp.path[1] === sub)?.flags ?? GLOBAL_FLAGS, '。--help 不接受额外参数');
178
+ if (problem !== undefined)
179
+ return usageFail(problem);
171
180
  process.stdout.write(USAGE);
172
181
  return 0;
173
182
  }
@@ -175,7 +184,9 @@ function subHelp(argv) {
175
184
  function selectTasks(ids) {
176
185
  const unknown = ids.filter((id) => taskById(id) === undefined);
177
186
  if (unknown.length > 0) {
178
- return usageFail(`未知任务:${unknown.join('、')}\n可用任务:${SYNC_TASKS.map((t) => t.id).join('、')}`);
187
+ // describeArgs 渲染取值(空串 → `''`):`sync status ''` 此前冒号后空白,
188
+ // Agent 读不出自己传了什么(sync-run.ts 同款,2026-10-29)。
189
+ return usageFail(`未知任务:${describeArgs(unknown)}\n可用任务:${SYNC_TASKS.map((t) => t.id).join('、')}`);
179
190
  }
180
191
  return ids.length > 0 ? ids.map((id) => taskById(id)) : SYNC_TASKS;
181
192
  }
@@ -184,60 +195,34 @@ function resolveConfig(flags) {
184
195
  flags,
185
196
  env: currentStoreEnv(),
186
197
  });
187
- return { path: resolved.config.path, backend: resolved.config.backend, config: resolved.config };
198
+ return {
199
+ path: resolved.config.path, backend: resolved.config.backend, config: resolved.config,
200
+ ...(resolved.profileFlag !== undefined ? { profileFlag: resolved.profileFlag } : {}),
201
+ };
188
202
  }
189
203
  /** 只读命令的库前置检查(statSync 分流沿 store status;hint 统一指 store init,spec §九)。 */
190
- function statGuard(path) {
191
- let st;
192
- try {
193
- st = statSync(path);
194
- }
195
- catch (e) {
196
- if (e.code === 'ENOENT') {
197
- return fail({
198
- code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
199
- message: `数据库文件不存在:${path}`,
200
- hint: '数据库尚未初始化。请先运行:qiyu store init',
201
- });
202
- }
203
- return fail({
204
- code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
205
- message: `无法访问 ${path}:${e instanceof Error ? e.message : String(e)}`,
206
- hint: '请检查路径权限(只读命令不需要写权限)',
207
- });
208
- }
209
- if (!st.isFile()) {
210
- return fail({
211
- code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
212
- message: `不是普通文件:${path}`,
213
- hint: '--db 指向的不是普通文件,请给出 .duckdb 数据库文件路径',
214
- });
215
- }
216
- return null;
217
- }
218
204
  /** 打开 ro 库;结构不完整(缺 schema_version)视为「不是本 CLI 创建的库」。 */
219
- async function openRo(config) {
205
+ async function openRo(config, profileFlag) {
220
206
  let store;
221
207
  try {
222
208
  store = await openStore(config, 'ro');
223
209
  }
224
210
  catch (e) {
225
- return { code: thrownToExit(e) };
211
+ return { code: thrownToExit(e, profileFlag) };
226
212
  }
227
213
  try {
228
214
  const names = await store.tables();
229
- if (!names.includes('schema_version')) {
215
+ // ⚠️ 表名不是身份证明(2026-11-07 审查实测):他人工具的 schema_version 可能没有
216
+ // version 列 —— 只认表名会让后续查询落 internal,把「不是本 CLI 的库」说成损坏。
217
+ const versionColumns = names.includes('schema_version')
218
+ ? (await store.query(SCHEMA_VERSION_COLUMNS_SQL)).rows.map((r) => String(r.column_name))
219
+ : undefined;
220
+ const missing = schemaVersionMissing(config.path, names, versionColumns);
221
+ if (missing !== null) {
230
222
  await store.close();
231
- // 成因分形(store.ts 同款):有表无 schema_version 是他人库——store init 会再次
232
- // 拒绝(duckdb.ts init 的他人库防线),引导过去就是 store init → sync status 死循环;
233
- // 空库(无任何表)才是「init 可补」的成因。
234
- return { code: fail({
235
- code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
236
- message: `数据库结构不完整(缺表):${config.path}`,
237
- hint: names.length > 0
238
- ? '目标数据库不是本 CLI 创建的,请换 --db 路径'
239
- : '空库(无任何表)。请先运行:qiyu store init',
240
- }) };
223
+ // 成因分形在共享实现里(有表无 schema_version = 他人库 → 换路径;
224
+ // 零表才是「init 可补」)。关 store 是调用方的所有权责任,故在此 fail。
225
+ return { code: fail(missing) };
241
226
  }
242
227
  return { store };
243
228
  }
@@ -246,7 +231,7 @@ async function openRo(config) {
246
231
  await store.close();
247
232
  }
248
233
  catch { /* 清理错误不掩盖原异常 */ }
249
- return { code: thrownToExit(e) };
234
+ return { code: thrownToExit(e, profileFlag) };
250
235
  }
251
236
  }
252
237
  // —— sync status ——
@@ -263,7 +248,7 @@ function resolvedRangeOut(st) {
263
248
  return [msToShanghaiIso(s), msToShanghaiIso(e)];
264
249
  }
265
250
  async function syncStatus(argv) {
266
- const help = subHelp(argv);
251
+ const help = subHelp(argv, 'status');
267
252
  if (help !== null)
268
253
  return help;
269
254
  let parsed;
@@ -283,14 +268,17 @@ async function syncStatus(argv) {
283
268
  let resolved;
284
269
  try {
285
270
  resolved = resolveConfig({ db: parsed.values['--db'], profile: parsed.values['--profile'], backend: parsed.values['--backend'] });
271
+ // ⚠️ failFromTagged(不是 usageFail):配置层会抛带 `kind: config_insecure` 的错误
272
+ // (含凭证且权限过宽 —— 退出码 1、只能由人 chmod)。包成 usageFail 会把它降级成
273
+ // 「改参数重来」退出码 2 并丢掉 hint,与 auth/api 那条路径的说法相反。
286
274
  }
287
275
  catch (e) {
288
- return usageFail(e.message);
276
+ return failFromTagged(e);
289
277
  }
290
278
  const guarded = statGuard(resolved.path);
291
279
  if (guarded !== null)
292
280
  return guarded;
293
- const opened = await openRo(resolved.config);
281
+ const opened = await openRo(resolved.config, resolved.profileFlag);
294
282
  if (opened.code !== undefined || !opened.store)
295
283
  return opened.code ?? 1;
296
284
  const store = opened.store;
@@ -328,7 +316,7 @@ async function syncStatus(argv) {
328
316
  locked: (st?.lockedBy ?? null) !== null,
329
317
  };
330
318
  });
331
- return ok({ tasks: tasksOut });
319
+ return ok({ tasks: tasksOut }, { field_notes: statusFieldNotes() });
332
320
  }
333
321
  catch (e) {
334
322
  return thrownToExit(e);
@@ -337,8 +325,20 @@ async function syncStatus(argv) {
337
325
  await store.close();
338
326
  }
339
327
  }
328
+ // —— sync verify ——
329
+ /**
330
+ * `sync verify` 的 `drift[].kind` 全部取值 —— Agent 按值分支,所以每个值都必须在
331
+ * README 图例里有释义与动作(`tests/sync-enums.test.ts` 双向钉住:枚举 ⊆ 图例、
332
+ * 图例 ⊆ 枚举)。
333
+ */
334
+ export const DRIFT_KINDS = [
335
+ 'not_synced', // sync_state 无该任务记录(从未同步)
336
+ 'state_pending', // 上次运行未完成/中断(range_status 非 complete)
337
+ 'count_mismatch', // 本地行数 ≠ 上游行数(仅快照任务做上游核对)
338
+ 'fetch_failed', // 上游取数失败 —— 无法核对 ≠ 一致
339
+ ];
340
340
  async function syncVerify(argv) {
341
- const help = subHelp(argv);
341
+ const help = subHelp(argv, 'verify');
342
342
  if (help !== null)
343
343
  return help;
344
344
  let parsed;
@@ -354,27 +354,34 @@ async function syncVerify(argv) {
354
354
  const tasks = selectTasks(parsed.rest);
355
355
  if (typeof tasks === 'number')
356
356
  return tasks;
357
+ // —— store 配置解析(**先于**凭证)——
358
+ // ⚠️ 次序即归因(Codex PR #69):`--profile typo` 是参数错误(usage,退出码 2),
359
+ // 缺凭证是环境错误(auth_missing,退出码 1)。凭证侧按 `--profile` 选档后报
360
+ // 「缺少 appKey」会把拼错的档名说成「没配凭证」—— 参数错误必须排在环境错误之前。
361
+ let resolved;
362
+ try {
363
+ resolved = resolveConfig({ db: parsed.values['--db'], profile: parsed.values['--profile'], backend: parsed.values['--backend'] });
364
+ // ⚠️ failFromTagged(不是 usageFail):配置层会抛带 `kind: config_insecure` 的错误
365
+ // (含凭证且权限过宽 —— 退出码 1、只能由人 chmod)。包成 usageFail 会把它降级成
366
+ // 「改参数重来」退出码 2 并丢掉 hint,与 auth/api 那条路径的说法相反。
367
+ }
368
+ catch (e) {
369
+ return failFromTagged(e);
370
+ }
357
371
  // 凭证惰性解析:快照任务需要上游 fetch;纯 windowed 选中时不碰凭证
358
372
  //(归因准确:本地核对不该因缺环境变量失败)。
359
373
  const needsUpstream = tasks.some((t) => t.kind === 'snapshot');
360
374
  let creds;
361
375
  if (needsUpstream) {
362
- const credOutcome = resolveCredentialsUsingFile(currentCredentialEnv());
376
+ const credOutcome = resolveCredentialsUsingFile(currentCredentialEnv(), { profile: parsed.values['--profile'] });
363
377
  if (!credOutcome.ok)
364
378
  return fail(credOutcome.error);
365
379
  creds = credOutcome.creds;
366
380
  }
367
- let resolved;
368
- try {
369
- resolved = resolveConfig({ db: parsed.values['--db'], profile: parsed.values['--profile'], backend: parsed.values['--backend'] });
370
- }
371
- catch (e) {
372
- return usageFail(e.message);
373
- }
374
381
  const guarded = statGuard(resolved.path);
375
382
  if (guarded !== null)
376
383
  return guarded;
377
- const opened = await openRo(resolved.config);
384
+ const opened = await openRo(resolved.config, resolved.profileFlag);
378
385
  if (opened.code !== undefined || !opened.store)
379
386
  return opened.code ?? 1;
380
387
  const store = opened.store;
@@ -389,7 +396,8 @@ async function syncVerify(argv) {
389
396
  if (st === undefined) {
390
397
  drift.push({
391
398
  kind: 'not_synced',
392
- detail: 'sync_state 无该任务记录(从未同步)。请先运行:qiyu sync run',
399
+ detail: 'sync_state 无该任务记录(从未同步)。请先运行:'
400
+ + syncRunCommand(resolved.path, resolved.profileFlag),
393
401
  });
394
402
  }
395
403
  else if (!stateConsistent) {
@@ -397,7 +405,8 @@ async function syncVerify(argv) {
397
405
  kind: 'state_pending',
398
406
  detail: `sync_state.range_status=${st.rangeStatus ?? 'null'}(最后一次运行未完成或中断)。`
399
407
  + (t.kind === 'windowed'
400
- ? 'windowed 任务不做上游全量重拉(成本高):核对方式为本地行数与 sync_state 成功状态一致性——重跑 qiyu sync run 补全后再 verify。'
408
+ ? 'windowed 任务不做上游全量重拉(成本高):核对方式为本地行数与 sync_state 成功状态一致性——重跑 '
409
+ + syncRunCommand(resolved.path, resolved.profileFlag) + ' 补全后再 verify。'
401
410
  : '快照任务将以上游取数核对本地行数。'),
402
411
  });
403
412
  }
@@ -430,7 +439,7 @@ async function syncVerify(argv) {
430
439
  drift,
431
440
  });
432
441
  }
433
- const code = ok({ tasks: tasksOut });
442
+ const code = ok({ tasks: tasksOut }, { field_notes: verifyFieldNotes() });
434
443
  const hasDrift = tasksOut.some((t) => t.drift.length > 0);
435
444
  return hasDrift ? 1 : code;
436
445
  }
@@ -459,7 +468,9 @@ const INSTALL_STORE_PASSTHROUGH = STORE_VALUE_FLAGS;
459
468
  * 这里只固化「env 派生」:配置文件 store.path(HOME 下,调度任务自己读得到)与
460
469
  * 内置默认值**不固化**(批 4 裁定:默认值固化会引入漂移)。
461
470
  * 实现约束:**不读配置文件内容来生成参数**(配置路径不固化,调度任务自己会读它);
462
- * env 已给但解析失败/为空时由 resolveConfig 在更早处抛 usage,不会走到这里。
471
+ * env 已给但解析失败时由 resolveConfig 在更早处抛 usage,不会走到这里。
472
+ * ⚠️ env 值为**空串**不算「已给」(2026-10-29):空串视为未设置,这条来源整体不成立
473
+ * —— 否则固化的是**回落后的**配置文件/默认值,等于把安装当时的配置悄悄钉进调度命令。
463
474
  * 同一 flag 只在 flag 缺席时才补 env 派生值 —— 显式 flag 永远优先(与 resolveStoreConfig
464
475
  * 的 flags > env 优先级一致),不会出现两个 --db。
465
476
  */
@@ -473,15 +484,26 @@ function storeArgsFor(parsed, resolved) {
473
484
  push(f, v);
474
485
  }
475
486
  // ② env 派生 → 固化解析结果(仅当对应 flag 未给)
476
- if (parsed.values['--db'] === undefined && process.env.QIYU_DB_PATH !== undefined) {
487
+ // ⚠️ 空串视为未设置(2026-10-29,与下面的 --profile 同一条口径):`QIYU_DB_PATH=` 时
488
+ // resolveStoreConfig 会正确回落到配置文件/默认值,但这里若照烘 `--db <解析结果>`,
489
+ // 调度命令就被钉死在**安装当时**的路径上 —— 之后改配置文件的 store.path 不再生效,
490
+ // 且用户从未设过的变量变成了一个显式 flag。
491
+ if (parsed.values['--db'] === undefined && nonEmptyValue(process.env.QIYU_DB_PATH) !== undefined) {
477
492
  // 固化的是 resolveStoreConfig 解析后的**绝对路径**(env 的相对路径/`~` 已展开)——
478
493
  // 调度任务的 cwd 与 HOME 都可能不同,相对路径会指向别处。
479
494
  push('--db', resolved.path);
480
495
  }
481
- if (parsed.values['--profile'] === undefined && process.env.QIYU_PROFILE !== undefined) {
482
- push('--profile', process.env.QIYU_PROFILE);
483
- }
484
- if (parsed.values['--backend'] === undefined && process.env.QIYU_STORE_BACKEND !== undefined) {
496
+ // ⚠️ 空串视为未设置(2026-10-29 实测修):`export QIYU_PROFILE=` 是 shell 里"变量没填"
497
+ // 的典型形态。此前只判 `!== undefined`,于是 `--profile` **带一个空取值**被烘进调度命令:
498
+ // sync run --profile "" → 每次调度执行都报「--profile 不能为空」退出码 2,
499
+ // 而安装时(dry-run 与 --yes 都一样)不报任何错 —— 装完才开始永久失败。
500
+ // 判据与 `resolveProfileName` 的空串口径同源(core/config.ts)。
501
+ if (parsed.values['--profile'] === undefined) {
502
+ const envProfile = nonEmptyValue(process.env.QIYU_PROFILE);
503
+ if (envProfile !== undefined)
504
+ push('--profile', envProfile);
505
+ }
506
+ if (parsed.values['--backend'] === undefined && nonEmptyValue(process.env.QIYU_STORE_BACKEND) !== undefined) {
485
507
  // backend 当前唯一合法值 duckdb(resolveStoreConfig 已校验),固化解析结果而非原始 env 值。
486
508
  push('--backend', resolved.backend);
487
509
  }
@@ -495,11 +517,11 @@ function storeArgsFor(parsed, resolved) {
495
517
  * 同步过的库上,探测名不副实(且 hint 会劝用户「先跑通一次」却已经被放行)。
496
518
  * 冷却行(`__ratelimit__:` 前缀)本就不是任务行,按前缀排除。
497
519
  */
498
- async function probeSynced(config, path) {
520
+ async function probeSynced(config, path, profileFlag) {
499
521
  const guarded = statGuard(path);
500
522
  if (guarded !== null)
501
523
  return guarded;
502
- const opened = await openRo(config);
524
+ const opened = await openRo(config, profileFlag);
503
525
  if (opened.code !== undefined || !opened.store)
504
526
  return opened.code ?? 1;
505
527
  const store = opened.store;
@@ -511,7 +533,7 @@ async function probeSynced(config, path) {
511
533
  return fail({
512
534
  code: 'sync_not_run', kind: 'sync_not_run', retryable: false,
513
535
  message: '尚未成功同步过任何任务(sync_state 无 range_status=complete 且无 last_synced_at 的记录)',
514
- hint: '安装调度前请先跑通一次同步:qiyu sync run',
536
+ hint: '安装调度前请先跑通一次同步:' + syncRunCommand(path, profileFlag),
515
537
  });
516
538
  }
517
539
  return null;
@@ -523,7 +545,7 @@ async function probeSynced(config, path) {
523
545
  /** 命令行形态(输出用):argv 以空格连接(含空格的部分已按 shellQuote 引住)。 */
524
546
  const commandText = (argv) => argv.join(' ');
525
547
  async function syncInstall(argv) {
526
- const help = subHelp(argv);
548
+ const help = subHelp(argv, 'install');
527
549
  if (help !== null)
528
550
  return help;
529
551
  let parsed;
@@ -534,7 +556,7 @@ async function syncInstall(argv) {
534
556
  return usageFail(e.message);
535
557
  }
536
558
  if (parsed.rest.length > 0)
537
- return usageFail(`未知参数:${parsed.rest.join(' ')}`);
559
+ return usageFail(`未知参数:${describeArgs(parsed.rest)}`);
538
560
  // G1:--pretty 已实现(原拒绝点在 parseSubFlags 的 throw)。
539
561
  if (parsed.flags.has('--pretty'))
540
562
  setPretty(true);
@@ -542,6 +564,18 @@ async function syncInstall(argv) {
542
564
  if (schedule === undefined) {
543
565
  return usageFail('缺少 --schedule CRON(5 段:分 时 日 月 周)', '例如:qiyu sync install --schedule "*/30 * * * *"');
544
566
  }
567
+ // ⚠️ cron 解析必须**先于一切 I/O**(2026-10-29 实测修):闭集(`--schedule` 的语法)
568
+ // 校验写在 probeSynced 之后时,未同步过的库上 `sync install --schedule '不是 cron'`
569
+ // 报的是 `sync_not_run`(退出码 1,「先去跑一次同步」)—— 而真正错的是参数,Agent 会
570
+ // 照 hint 去跑一次全量同步、再回来才看到 cron 错误(白跑一轮,且第一次的报错指向
571
+ // 了错误的动作)。query 的 `--table` 早已是同款次序(「闭集校验先于一切 I/O」)。
572
+ // 渲染走 describeArgs:`--schedule ''` 否则是「实际 1 段:」冒号后空白。
573
+ try {
574
+ parseCron(schedule);
575
+ }
576
+ catch (e) {
577
+ return usageFail(e.message);
578
+ }
545
579
  const yes = parsed.flags.has('--yes');
546
580
  let platform;
547
581
  try {
@@ -554,16 +588,19 @@ async function syncInstall(argv) {
554
588
  let config;
555
589
  let path;
556
590
  let backend;
591
+ let profileFlag;
557
592
  try {
558
593
  const r = resolveConfig({ db: parsed.values['--db'], profile: parsed.values['--profile'], backend: parsed.values['--backend'] });
559
594
  config = r.config;
560
595
  path = r.path;
561
596
  backend = r.backend;
597
+ profileFlag = r.profileFlag;
598
+ // ⚠️ 同 syncStatus:带 kind 的错误(config_insecure)必须如实透出。
562
599
  }
563
600
  catch (e) {
564
- return usageFail(e.message);
601
+ return failFromTagged(e);
565
602
  }
566
- const probe = await probeSynced(config, path);
603
+ const probe = await probeSynced(config, path, profileFlag);
567
604
  if (probe !== null)
568
605
  return probe;
569
606
  // 计划生成(cron 解析 / 平台映射失败 → usage)
@@ -592,7 +629,7 @@ async function syncInstall(argv) {
592
629
  entries: plan.entries,
593
630
  commands: plan.commands.map((c) => ({ command: commandText(c), executed: false, ok: null, error: null })),
594
631
  notes: [...plan.notes, envNote, '这是 dry-run:未写入任何文件、未执行任何命令。加 --yes 实际安装。'],
595
- });
632
+ }, { field_notes: syncInstallFieldNotes('install-dry') });
596
633
  }
597
634
  // --yes:写文件 + 执行命令(逐条记结果,失败不中断、退出码如实报 1)
598
635
  const installed = [];
@@ -614,11 +651,11 @@ async function syncInstall(argv) {
614
651
  const code = ok({
615
652
  platform, schedule, dry_run: false,
616
653
  installed, commands: cmdResults, notes: [...plan.notes, envNote],
617
- });
654
+ }, { field_notes: syncInstallFieldNotes('install-real') });
618
655
  return cmdResults.some((c) => !c.ok) ? 1 : code;
619
656
  }
620
657
  async function syncUninstall(argv) {
621
- const help = subHelp(argv);
658
+ const help = subHelp(argv, 'uninstall');
622
659
  if (help !== null)
623
660
  return help;
624
661
  let parsed;
@@ -629,7 +666,7 @@ async function syncUninstall(argv) {
629
666
  return usageFail(e.message);
630
667
  }
631
668
  if (parsed.rest.length > 0)
632
- return usageFail(`未知参数:${parsed.rest.join(' ')}`);
669
+ return usageFail(`未知参数:${describeArgs(parsed.rest)}`);
633
670
  // G1:--pretty 已实现(原拒绝点在 parseSubFlags 的 throw)。
634
671
  if (parsed.flags.has('--pretty'))
635
672
  setPretty(true);
@@ -647,22 +684,33 @@ async function syncUninstall(argv) {
647
684
  platform, dry_run: true,
648
685
  remove: plan.remove,
649
686
  commands: plan.commands.map((c) => ({ command: commandText(c), executed: false, ok: null, error: null })),
687
+ // 条件键:只有 linux 有「删完之后」的命令(daemon-reload),其余平台不出现。
688
+ ...(plan.postRemoveCommands.length > 0
689
+ ? { post_remove_commands: plan.postRemoveCommands.map((c) => ({ command: commandText(c), executed: false, ok: null, error: null })) }
690
+ : {}),
650
691
  notes: [...plan.notes, '这是 dry-run:未删除任何文件、未执行任何命令。加 --yes 实际卸载。'],
651
- });
692
+ }, { field_notes: syncInstallFieldNotes('uninstall-dry') });
652
693
  }
694
+ // 「装没装」的判据:darwin/linux 看条目文件是否存在;win32 没有文件条目可探测
695
+ // (plan.remove 恒为空),任务是否存在只能由 schtasks /Delete 本身回答 —— 不存在时
696
+ // 它报错、落进 commands[].ok=false。所以 win32 一律执行卸载命令,否则已安装的任务
697
+ // 永远删不掉,还会被误报成「未安装」。
653
698
  const anyInstalled = plan.remove.some((r) => r.exists);
699
+ const willRun = anyInstalled || platform === 'win32';
654
700
  const cmdResults = [];
655
- if (anyInstalled) {
656
- // 卸载次序:先停调度器(unload/disable),再删文件
657
- for (const c of plan.commands) {
658
- try {
659
- runScheduleCommand(c);
660
- cmdResults.push({ command: commandText(c), executed: true, ok: true, error: null });
661
- }
662
- catch (e) {
663
- cmdResults.push({ command: commandText(c), executed: true, ok: false, error: e instanceof Error ? e.message : String(e) });
664
- }
701
+ const runOne = (c) => {
702
+ try {
703
+ runScheduleCommand(c);
704
+ cmdResults.push({ command: commandText(c), executed: true, ok: true, error: null });
705
+ }
706
+ catch (e) {
707
+ cmdResults.push({ command: commandText(c), executed: true, ok: false, error: e instanceof Error ? e.message : String(e) });
665
708
  }
709
+ };
710
+ if (willRun) {
711
+ // 卸载次序:先停调度器(unload/disable),再删文件,最后跑「删完之后」的命令。
712
+ for (const c of plan.commands)
713
+ runOne(c);
666
714
  }
667
715
  const removed = [];
668
716
  const absent = [];
@@ -673,34 +721,48 @@ async function syncUninstall(argv) {
673
721
  else
674
722
  absent.push(r.path);
675
723
  }
724
+ if (willRun) {
725
+ // ⚠️ postRemoveCommands(linux 的 daemon-reload)必须在删除之后 —— 见 planUninstall
726
+ // 的注释:提前跑等于重新加载即将被删的 unit,删完后再没人让 systemd 忘掉它。
727
+ for (const c of plan.postRemoveCommands)
728
+ runOne(c);
729
+ }
676
730
  const code = ok({
677
731
  platform, dry_run: false, removed,
678
732
  absent: absent.length > 0 ? absent : undefined,
679
- commands: cmdResults, notes: anyInstalled ? plan.notes : ['未安装(无条目文件):未执行任何命令。'],
680
- });
733
+ commands: cmdResults, notes: willRun ? plan.notes : ['未安装(无条目文件):未执行任何命令。'],
734
+ }, { field_notes: syncInstallFieldNotes('uninstall-real') });
681
735
  return cmdResults.some((c) => !c.ok) ? 1 : code;
682
736
  }
683
737
  export async function syncCommand(argv) {
684
738
  setPretty(false); // G1:每条命令入口重置输出格式 —— 同一进程内多次 run(测试)不残留上一条命令的开关。
685
739
  const [sub, ...rest] = argv;
686
- if (sub === undefined || sub === '--help' || sub === '-h') {
687
- const extra = rest.filter((a) => !KNOWN.has(a));
688
- if (extra.length > 0)
689
- return usageFail(`未知参数:${extra.join(' ')}。--help 不接受额外参数`);
740
+ // ⚠️ 无子命令 = 用法错误(退 2 + JSON)—— 见 store.ts 同款注释(2026-11-07 审查:
741
+ // 四个命令族曾与 `--help` 共用分支,裸文本进 stdout、退 0,与顶层和 api/auth 相反)。
742
+ if (sub === undefined) {
743
+ return usageFail(`用法:qiyu sync <tasks|run|status|verify|install|uninstall> [参数]`
744
+ + '(`qiyu sync --help` 查看全部)');
745
+ }
746
+ if (sub === '--help' || sub === '-h') {
747
+ const problem = helpArgsError(rest, SYNC_SPECS.flatMap((sp) => sp.flags), '。--help 不接受额外参数');
748
+ if (problem !== undefined)
749
+ return usageFail(problem);
690
750
  process.stdout.write(USAGE);
691
751
  return 0;
692
752
  }
693
753
  // G1:--pretty 是输出开关,必须写在具体子命令之后(`sync status --pretty`)。
694
754
  if (sub === '--pretty') {
695
- const unknown = rest.filter((a) => a.startsWith('-') && !KNOWN.has(a));
696
- const positional = rest.filter((a) => !a.startsWith('-'));
697
- if (unknown.length + positional.length > 0) {
698
- return usageFail(`未知参数:${[...unknown, ...positional].join(' ')}。--pretty 不接受额外参数`);
699
- }
755
+ const problem = helpArgsError(rest, SYNC_SPECS.flatMap((sp) => sp.flags));
756
+ if (problem !== undefined)
757
+ return usageFail(`${problem}。--pretty 不接受额外参数`);
758
+ const badPos = prettyPositionalProblem(rest, SYNC_SPECS);
759
+ if (badPos !== undefined)
760
+ return usageFail(badPos);
700
761
  if (rest.includes('--help') || rest.includes('-h')) {
701
762
  process.stdout.write(USAGE);
702
763
  return 0;
703
764
  }
765
+ // ⚠️ 位置参数一律按「顺序写反」引导(2026-11-07 审查)—— 见 db.ts 同款注释。
704
766
  return usageFail(prettyAfterSubcommand('sync'));
705
767
  }
706
768
  if (sub !== 'tasks' && sub !== 'run' && sub !== 'status' && sub !== 'verify'
@@ -718,20 +780,19 @@ export async function syncCommand(argv) {
718
780
  if (sub === 'uninstall')
719
781
  return syncUninstall(rest);
720
782
  // —— tasks ——
721
- if (rest.includes('--help') || rest.includes('-h')) {
722
- const rawRest = rest.filter((a) => !KNOWN.has(a));
723
- if (rawRest.length > 0)
724
- return usageFail(`未知参数:${rawRest.join(' ')}`);
725
- process.stdout.write(USAGE);
726
- return 0;
727
- }
783
+ // ⚠️ 用 `sync tasks` **自己**的 spec(`subHelp`),不是全族并集(Codex PR #69 第四轮):
784
+ // 并集会把兄弟命令的 flag(`--full` / `--db`)当成合法参数,`sync tasks --full --help`
785
+ // 退 0 打印帮助,而正常解析与 `skill check` 都判它非法 —— 运行时与契约校验再次分叉。
786
+ const tasksHelp = subHelp(rest, 'tasks');
787
+ if (tasksHelp !== null)
788
+ return tasksHelp;
728
789
  // G1:--pretty 已实现 —— 原拒绝点开启缩进输出。
729
790
  if (rest.includes('--pretty'))
730
791
  setPretty(true);
731
792
  try {
732
793
  const parsed = parseSubFlags(rest, TASKS_VALUE_FLAGS);
733
794
  if (parsed.rest.length > 0)
734
- return usageFail(`未知参数:${parsed.rest.join(' ')}`);
795
+ return usageFail(`未知参数:${describeArgs(parsed.rest)}`);
735
796
  }
736
797
  catch (e) {
737
798
  return usageFail(e.message);
@@ -752,6 +813,6 @@ export async function syncCommand(argv) {
752
813
  .filter((c) => c.sensitive === true).map((c) => c.name),
753
814
  }));
754
815
  const unsupported = UNSUPPORTED_DATASETS.map((u) => ({ id: u.id, unsupported: u.reason }));
755
- return ok({ tasks, unsupported });
816
+ return ok({ tasks, unsupported }, { field_notes: tasksFieldNotes() });
756
817
  }
757
818
  export { SYNC_RUN_USAGE };