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
package/dist/commands/sync.js
CHANGED
|
@@ -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 {
|
|
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,
|
|
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
|
-
win32=schtasks
|
|
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
|
-
/**
|
|
165
|
-
|
|
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
|
|
169
|
-
if (
|
|
170
|
-
return usageFail(
|
|
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
|
-
|
|
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 {
|
|
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
|
-
|
|
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
|
-
//
|
|
232
|
-
//
|
|
233
|
-
|
|
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
|
|
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 无该任务记录(从未同步)。请先运行:
|
|
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 成功状态一致性——重跑
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
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: '安装调度前请先跑通一次同步:
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
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:
|
|
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
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
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
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
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
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
return
|
|
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
|
|
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 };
|