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
@@ -1,6 +1,8 @@
1
+ // src/commands/auth.ts
2
+ import { dirname } from 'node:path';
1
3
  import { ok, fail, usageFail, failFromTagged, describeArgs, setPretty, EXIT } from '../output.js';
2
- import { configPathFor, loadConfigFile, loadConfigChecked, writeConfigFile, checkPermissions, } from '../core/config.js';
3
- import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, prettyAfterSubcommand, REJECTED_FLAGS } from './spec-types.js';
4
+ import { configPathFor, loadConfigFile, loadConfigChecked, writeConfigFile, checkPermissions, isWhitespaceOnly, nonEmptyValue, resolveProfileName, shellPath, } from '../core/config.js';
5
+ import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS } from './spec-types.js';
4
6
  /** `auth login` 的业务 flag:只有 `--profile`(凭证从**环境变量**读,见命令内注释)。 */
5
7
  const LOGIN_FLAGS = [{ name: '--profile', kind: 'value' }];
6
8
  /**
@@ -32,13 +34,14 @@ const AUTH_USAGE = `用法:qiyu auth <whoami|login> [参数]
32
34
  第一次真实调用才是唯一的验证。
33
35
 
34
36
  auth login 从环境变量读取凭证(不接受 --app-key/--app-secret:命令行参数会
35
- 留在 shell 历史与进程列表里)。写入 ~/.config/qiyu/config.json,目录 0700、文件 0600。
37
+ 留在 shell 历史与进程列表里)。写入 ~/.config/qiyu/config.json:新建的目录 0700、文件 0600;
38
+ 已存在的目录不改动,但 group/other 可写(能整体替换文件)时拒绝写入。
36
39
 
37
40
  出错时 stdout 是 {"ok":false,"error":{code,kind,retryable,message,hint?}}。
38
41
  ⚠️ 请按 kind 分支,不要按 code —— code 只是个标签:它可能是服务端的
39
42
  数字码(如 14009),也可能是本 CLI 合成的词(usage / network / internal /
40
43
  auth_missing / config_insecure / confirm_required / store_locked / store_not_initialized /
41
- local_rate_limit / unknown)。合成词查不到官方错误码表。
44
+ local_rate_limit / sync_not_run / unknown)。合成词查不到官方错误码表。
42
45
 
43
46
  退出码:0 成功 · 1 业务错误 · 2 用法错误 · 3 网络错误 · 4 需要 --yes
44
47
  `;
@@ -65,15 +68,17 @@ export async function authCommand(argv) {
65
68
  // G1:--pretty 已实现,但必须写在具体子命令之后(`auth whoami --pretty`)。
66
69
  if (sub === '--pretty') {
67
70
  const unknown = argv.slice(1).filter((a) => a.startsWith('-') && a !== '--pretty' && a !== '--help' && a !== '-h');
68
- const positional = argv.slice(1).filter((a) => !a.startsWith('-'));
69
- const extra = [...unknown, ...positional];
70
- if (extra.length > 0) {
71
- return usageFail(`未知参数:${describeArgs(extra)}。--pretty 不接受额外参数`);
71
+ if (unknown.length > 0) {
72
+ return usageFail(`未知参数:${describeArgs(unknown)}。--pretty 不接受额外参数`);
72
73
  }
74
+ const badPos = prettyPositionalProblem(argv.slice(1), AUTH_SPECS);
75
+ if (badPos !== undefined)
76
+ return usageFail(badPos);
73
77
  if (argv.includes('--help') || argv.includes('-h')) {
74
78
  process.stdout.write(AUTH_USAGE);
75
79
  return EXIT.OK;
76
80
  }
81
+ // ⚠️ 位置参数按「顺序写反」引导(2026-11-07 审查)—— 见 db.ts 同款注释。
77
82
  return usageFail(prettyAfterSubcommand('auth'));
78
83
  }
79
84
  if (sub === 'login')
@@ -105,7 +110,7 @@ export async function authCommand(argv) {
105
110
  const KNOWN = new Set(GLOBAL_FLAG_NAMES);
106
111
  const unknown = argv.slice(1).filter((a) => a.startsWith('-') && !KNOWN.has(a));
107
112
  if (unknown.length > 0) {
108
- return usageFail(`未知参数:${describeArgs(unknown)}。auth whoami 不接受任何参数`);
113
+ return usageFail(`未知参数:${describeArgs(unknown)}。auth whoami 只接受 --help / --pretty,不接受其他参数`);
109
114
  }
110
115
  // ⚠️ `whoami` **不接受任何位置参数**,多出来的必须报错,不能静默忽略。
111
116
  // 实测此前 `qiyu auth whoami extra` / `--bod` / `--pretty` / `--yes`
@@ -117,7 +122,7 @@ export async function authCommand(argv) {
117
122
  // 三个子命令的参数校验必须一致 —— 只在两个上做,第三个就是漏网。
118
123
  const positional = argv.slice(1).filter((a) => !a.startsWith('-'));
119
124
  if (positional.length > 0) {
120
- return usageFail(`未知参数:${describeArgs(positional)}。auth whoami 不接受任何参数`);
125
+ return usageFail(`未知参数:${describeArgs(positional)}。auth whoami 只接受 --help / --pretty,不接受其他参数`);
121
126
  }
122
127
  // 命令行已证明合法 —— 现在 help 优先于 `--pretty`(与 `list()` 的 ② 同源)。
123
128
  if (argv.includes('--help') || argv.includes('-h')) {
@@ -206,8 +211,19 @@ async function login(argv) {
206
211
  // 与 credentials-source.ts 的口径一致 —— 两层对"空"的判定不能分叉)。
207
212
  const envKey = process.env.QIYU_APP_KEY;
208
213
  const envSecret = process.env.QIYU_APP_SECRET;
209
- const appKey = envKey !== undefined && envKey !== '' ? envKey : undefined;
210
- const appSecret = envSecret !== undefined && envSecret !== '' ? envSecret : undefined;
214
+ // ⚠️ 纯空白不是「缺」也不是「有」(A12,2026-11-06):`' '` 会穿过 nonEmptyValue,
215
+ // 此前被**原样写进配置文件**,之后每条命令都拿它去签名。拒绝并点名变量。
216
+ const blankEnv = [
217
+ ...(isWhitespaceOnly(envKey) ? ['QIYU_APP_KEY'] : []),
218
+ ...(isWhitespaceOnly(envSecret) ? ['QIYU_APP_SECRET'] : []),
219
+ ];
220
+ if (blankEnv.length > 0) {
221
+ // ⚠️ 不能建议 `unset` 后直接重跑(Codex PR #69 第七轮):login 只从环境变量读、
222
+ // 不回落配置文件,删掉变量后重跑必然又是「缺少 …」退 2。恢复动作只有「设真实值」。
223
+ return usageFail(`环境变量 ${blankEnv.join('、')} 只有空白字符(不是有效凭证),未写入配置文件`, `请把它们设为真实值后重新运行 auth login(login 只从环境变量读取,不会回落配置文件)`);
224
+ }
225
+ const appKey = nonEmptyValue(envKey);
226
+ const appSecret = nonEmptyValue(envSecret);
211
227
  // ⚠️ 缺任一即 usage(退出码 2):这是"调用方式"问题(shell 里少 export 一个),
212
228
  // 与"凭证无效"(业务错误)不同 —— 后者要发请求才知道,login 不发请求。
213
229
  // ⚠️ 必须点名叫用户 export 什么,否则它只知道"少东西"。
@@ -224,19 +240,42 @@ async function login(argv) {
224
240
  const configPath = configPathFor();
225
241
  let file;
226
242
  try {
243
+ // 权限拒绝由 `loadConfigFile` 在读取前分流(唯一读取点,带 kind + chmod hint)——
244
+ // 本 catch 的 insecure 分支因此可达(Codex 2026-11-10 第四轮 P2)。
227
245
  file = loadConfigFile(configPath).file;
228
246
  }
229
247
  catch (e) {
230
248
  // 读不出来(畸形 JSON / 未知键 / 权限拒绝)——不能"无视坏文件直接覆盖":
231
249
  // 那会静默丢掉用户手写的其它配置。如实报错,让人先修。
232
- return usageFail(`无法读取现有配置文件:${e.message}`);
250
+ // ⚠️ 不能报成 usage(退出码 2,2026-11-09 审计实测):退出码 2 的语义是「改参数
251
+ // 重来」,而换环境变量修不好损坏的 JSON;权限拒绝则是环境问题(whoami 对同一状态
252
+ // 给 config_insecure)。统一走 `config_invalid`(退出码 1)+ 点名修法,
253
+ // 权限拒绝时 hint 直指 chmod(与 `core/config.ts` 的 config_insecure hint 同口径)。
254
+ const insecure = e.kind === 'config_insecure';
255
+ // 权限拒绝的修复动作是唯一的一条 chmod —— 路径由 core 的 `insecureConfigError` 渲染
256
+ // (含 shell 引号),这里只追加“没写任何东西”这个 login 侧事实。
257
+ const coreHint = e.hint;
258
+ return fail({
259
+ code: insecure ? 'config_insecure' : 'config_invalid',
260
+ kind: insecure ? 'config_insecure' : 'config_invalid', retryable: false,
261
+ message: `无法读取现有配置文件:${e.message}`,
262
+ hint: insecure
263
+ ? `${coreHint ?? '这是配置文件权限问题,重试无用'};本次未写入任何内容`
264
+ : '先修好或移走该文件后重跑(改成合法 JSON、删掉不认识的键,或让当前用户可读);'
265
+ + '本次未写入任何内容 —— login 不会覆盖读不出来的文件,直接覆盖会丢掉你手写的其它配置',
266
+ });
233
267
  }
234
- // ⚠️ 与全局优先级一致(spec §3.2:命令行 > 环境变量 > 配置文件 > 默认)——
235
- // 此前写成 defaultProfile 优先于 QIYU_PROFILE,同一台机器上 export 过
236
- // QIYU_PROFILE 的用户会发现自己写进了别的 profile。
237
- const name = profile
238
- ?? (process.env.QIYU_PROFILE !== undefined && process.env.QIYU_PROFILE !== '' ? process.env.QIYU_PROFILE : undefined)
239
- ?? file.defaultProfile ?? 'default';
268
+ // ⚠️ 档名走**共用解析点**(2026-10-29 实测):此前这里是 `profile ?? envProfile ?? defaultProfile ?? 'default'`
269
+ // 的手写链,而 `??` 会放行空串 —— `"defaultProfile": ""`(JSON 里清空字段)时
270
+ // login 把凭证写进 `profiles[""]`,而 store / api / sync 按内置 `default` 读:
271
+ // login 与 whoami 都报 `configured: true`,第一次真实调用却报「缺少 appKey」——
272
+ // 凭证写进了**没人读的档**。共用的口径与 README 一致:空串视为未设置。
273
+ // 顺序也与 spec §3.2 一致(命令行 > 环境变量 > 配置文件 > 默认)——此前曾写成
274
+ // defaultProfile 优先于 QIYU_PROFILE,同一台机器上 export 过的用户会发现自己
275
+ // 写进了别的 profile;`resolveProfileName` 把这条顺序固化成唯一实现。
276
+ const name = resolveProfileName({
277
+ flag: profile, envProfile: process.env.QIYU_PROFILE, defaultProfile: file.defaultProfile,
278
+ }).name;
240
279
  const existing = file.profiles[name] ?? {};
241
280
  const next = {
242
281
  ...(file.defaultProfile !== undefined ? { defaultProfile: file.defaultProfile } : {}),
@@ -258,7 +297,11 @@ async function login(argv) {
258
297
  return fail({
259
298
  code: 'config_insecure', kind: 'config_insecure', retryable: false,
260
299
  message: `无法写入配置文件 ${configPath}:${msg}`,
261
- hint: '请检查路径权限(父目录可写、非符号链接),或换到 HOME 下可写的位置',
300
+ // A11(2026-11-06 审查):原文案建议「换到 HOME 下可写的位置」,但配置路径**没有通道**
301
+ // (没有 --config/环境变量可改,见 configPathFor)——那是一个做不到的动作。
302
+ hint: `请检查 ${shellPath(dirname(configPath))} 的权限:目录可写、config.json 不是符号链接。`
303
+ + '配置路径固定为 ~/.config/qiyu/config.json(由 HOME 决定),CLI 不提供改路径的参数,'
304
+ + '所以不要去找「别的路径」,先把这一处的权限修好',
262
305
  });
263
306
  }
264
307
  // 权限自检:写出的文件必须 0600,否则这次"成功"是假的(凭证已落盘且可被他人读)。
@@ -269,13 +312,29 @@ async function login(argv) {
269
312
  return fail({
270
313
  code: 'config_insecure', kind: 'config_insecure', retryable: false,
271
314
  message: `凭证已写入 ${configPath},但落盘权限不合格(${perm.reason === 'file' ? '文件' : '目录'}过宽)`,
272
- hint: `请执行 chmod ${perm.reason === 'file' ? '600 ' + configPath : '700 ' + configPath.split('/').slice(0, -1).join('/')}`,
315
+ // ⚠️ 路径必须走 shellPath 引号(CodeRabbit 2026-10-26):HOME 可含空格,
316
+ // 不引号的 chmod 在那种 HOME 下照着抄是坏的。与 core 的 insecureConfigError 同源。
317
+ hint: `请执行 chmod ${perm.reason === 'file' ? `600 ${shellPath(configPath)}` : `700 ${shellPath(dirname(configPath))}`}`,
273
318
  });
274
319
  }
275
320
  }
276
321
  catch { /* 自检失败不影响"已写入"这一事实;下一次任何命令都会再查一次 */ }
277
322
  // ⚠️ 绝不回显 appKey/appSecret —— 连末四位都不(与 whoami 同一条约束)。
278
- return ok({ configured: true, profile: name, config_path: configPath, source: 'file' });
323
+ return ok({ configured: true, profile: name, config_path: configPath, source: 'file' }, {
324
+ field_notes: {
325
+ configured: 'true 只表示两个字段都已写入配置文件,不代表它们有效'
326
+ + '(拼错的 appKey 同样返回 true)。⚠️ auth whoami 也只查「有没有配」,'
327
+ + '不能验证有效性 —— 要验证只能发一次真实请求',
328
+ profile: '写入的配置档名。选择顺序:--profile > 环境变量 QIYU_PROFILE > '
329
+ + '配置文件里声明的默认档名 > default。⚠️ 不要假定是 default;'
330
+ + '写入非 default 档不会改动顶层的默认档名 —— 之后的命令仍须用 --profile 或 '
331
+ + 'QIYU_PROFILE 指向它,否则读不到这份凭证',
332
+ config_path: '写入的配置文件路径',
333
+ source: '恒为 file —— 表示本次把凭据写进了文件。'
334
+ + '⚠️ 它不表示「下次会从文件读」:环境变量 QIYU_APP_KEY / QIYU_APP_SECRET 仍在时,'
335
+ + '后续命令优先用环境变量(auth whoami 会报 env),login 写的文件只是兜底',
336
+ },
337
+ });
279
338
  }
280
339
  function whoami() {
281
340
  const configPath = configPathFor();
@@ -297,14 +356,57 @@ function whoami() {
297
356
  const envKey = process.env.QIYU_APP_KEY;
298
357
  const envSecret = process.env.QIYU_APP_SECRET;
299
358
  const envProfile = process.env.QIYU_PROFILE;
300
- const profileName = envProfile ?? file?.defaultProfile ?? 'default';
359
+ // ⚠️ A12(2026-11-06):纯空白是 truthy,此前报 `configured: true`、source=env ——
360
+ // 而 api/sync 的凭证合流现在会拒绝它。whoami 必须与它们同答,否则又是一份
361
+ // 「谁都说配好了、只有真调用失败」的分叉。
362
+ const blankEnv = [
363
+ ...(isWhitespaceOnly(envKey) ? ['QIYU_APP_KEY'] : []),
364
+ ...(isWhitespaceOnly(envSecret) ? ['QIYU_APP_SECRET'] : []),
365
+ ];
366
+ if (blankEnv.length > 0) {
367
+ return fail({
368
+ code: 'auth_missing', kind: 'auth_missing', retryable: false,
369
+ message: `环境变量 ${blankEnv.join('、')} 只有空白字符(不是有效凭证)`,
370
+ hint: `请把它们设为真实值;若本意是不设置,用 \`unset ${blankEnv.join(' ')}\``
371
+ + ' 删除变量,让配置文件的凭证生效',
372
+ });
373
+ }
374
+ // ⚠️ 档名解析**必须走共用点**(2026-10-29 实测):此前这里是 `envProfile ?? defaultProfile ?? 'default'`,
375
+ // 而 `''` 不是 null/undefined、`??` 会把它放行 —— `QIYU_PROFILE=`(变量未设的典型形态)
376
+ // 于是选中一个名叫空串的档,报 `auth_missing`,而同一台机器上的 `api call` 按
377
+ // `defaultProfile` 读到凭证并发出请求:两个命令给出相反的"凭证有没有配"。
378
+ const profileName = resolveProfileName({
379
+ envProfile, defaultProfile: file?.defaultProfile,
380
+ }).name;
301
381
  const profBlock = file?.profiles[profileName];
302
382
  const fileKey = profBlock?.credentials?.appKey;
303
383
  const fileSecret = profBlock?.credentials?.appSecret;
304
- const fromEnvKey = envKey !== undefined && envKey !== '';
305
- const fromEnvSecret = envSecret !== undefined && envSecret !== '';
306
- const fromFileKey = fileKey !== undefined && fileKey !== '';
307
- const fromFileSecret = fileSecret !== undefined && fileSecret !== '';
384
+ const fromEnvKey = nonEmptyValue(envKey) !== undefined;
385
+ const fromEnvSecret = nonEmptyValue(envSecret) !== undefined;
386
+ const fromFileKey = nonEmptyValue(fileKey) !== undefined;
387
+ const fromFileSecret = nonEmptyValue(fileSecret) !== undefined;
388
+ // ⚠️ 配置文件里同一档的纯空白值也要拒绝(Codex PR #69):只查环境变量时,配置文件里
389
+ // `" "` 会被 `nonEmptyValue` 当成「有」,whoami 报 configured:true,而 api/sync 的
390
+ // `resolveCredentials` 会拒绝它 —— 又是「谁都说配好了、只有真调用失败」的分叉。
391
+ // ⚠️ 只在**该字段真的会取文件这一层**时才拒(逐字段优先级 env > file):环境变量已给值时
392
+ // 文件里的空白不会被选中,`api call` 也照常成功 —— 那时报错就是把好状态说成坏的。
393
+ const blankFile = [
394
+ ...(!fromEnvKey && isWhitespaceOnly(fileKey) ? ['appKey'] : []),
395
+ ...(!fromEnvSecret && isWhitespaceOnly(fileSecret) ? ['appSecret'] : []),
396
+ ];
397
+ if (blankFile.length > 0) {
398
+ return fail({
399
+ code: 'auth_missing', kind: 'auth_missing', retryable: false,
400
+ message: `配置文件里 profile ${JSON.stringify(profileName)} 的 ${blankFile.join('、')}`
401
+ + ' 只有空白字符(不是有效凭证)',
402
+ // ⚠️ 不能建议「删掉这个键」再改用环境变量(Codex PR #69 第七轮):`credentials`
403
+ // 块要求 appKey / appSecret 同时是非空字符串,只删一个键会让 parseConfig 拒绝
404
+ // 整份配置(实测:随后 whoami 报「配置文件读取失败」,api/sync 也读不到其它档)。
405
+ // 要改用环境变量,删的必须是**整个 credentials 块**。
406
+ hint: `请在该档里把它设为真实值;若要改用环境变量(环境变量优先于配置文件),`
407
+ + `删掉该档的整个 credentials 块(只删单个键会让配置文件解析失败):${configPathFor()}`,
408
+ });
409
+ }
308
410
  const configured = (fromEnvKey || fromFileKey) && (fromEnvSecret || fromFileSecret);
309
411
  if (!configured) {
310
412
  const detail = configError !== undefined
@@ -339,10 +441,30 @@ function whoami() {
339
441
  profile: profileName,
340
442
  robots,
341
443
  }, {
444
+ // ⚠️ 配置文件读取失败**必须在成功路径上也可见**(2026-11-02 审查实测):
445
+ // 凭证齐全时 env 那两票足以让 configured 为 true,畸形配置(非法 JSON / 未知键)
446
+ // 被吞进 `configError` —— 上一段代码只在 `!configured` 时把它拼进 message,
447
+ // 成功路径完全不提,而 `robots` 静默变成 `[]`。实测:配置文件是
448
+ // `{ "profiles": {...}, "unknownKey": 1 }` 时,whoami 输出
449
+ // `{configured:true, source:"env", profile:"default", robots:[]}`,
450
+ // 图例却只说「空数组有两种成因」—— Agent 会得出「该档没配 robots」,
451
+ // 而真相是**配置根本没读成功**(那个档里可能配了 robots)。
452
+ ...(configError !== undefined ? { warnings: [`配置文件读取失败(${configError}),本次的 profile / robots 均按「文件不存在」处理`] } : {}),
342
453
  field_notes: {
343
454
  source: 'env = 两个字段都来自环境变量;file = 都来自配置文件;mixed = 各来自一处(合法组合)',
455
+ profile: '本次解析出的配置档名。选择顺序:环境变量 QIYU_PROFILE > 配置文件里声明的默认档名 > '
456
+ + '内置 default(空串一律视为未设置)。'
457
+ + '⚠️ 它只表示「本命令会去读哪个档」,**不保证该档在配置文件里存在** —— 环境变量给了一个'
458
+ + '配置文件里没有的名字(拼错)时,本命令照样按 env 凭证报 configured,但这时 robots 必为空,'
459
+ + '且只要配置文件里**已有其它档**,store / db / sync / query 对同一个名字就会以退出码 2 拒绝'
460
+ + '(它们要读该档的 store 块)。注意后者的成立条件是「已有其它档」:配置文件的 profiles 为空时'
461
+ + '它们按内置默认路径照常工作,不报错',
344
462
  robots: '来自配置文件的 profiles.<name>.robots 映射(robotId → 显示名),**未校验有效性**、' +
345
- '未与本地库比对;sync run 在 store.options.knowledgeRobotIds 缺席时回退使用它',
463
+ '未与本地库比对;sync run 在 profiles.<name>.store.options.knowledgeRobotIds 缺席时回退使用它。'
464
+ + '⚠️ 空数组有三种成因:该档没配 robots,该档在配置文件里根本不存在(见 profile 的说明),'
465
+ + '或**配置文件读取失败**(畸形 JSON / 未知键)—— 第三种会在 meta.warnings 里点名,'
466
+ + '先读 warnings 再判断。⚠️ **权限不足不在其列**:含凭证且权限过宽时本命令直接以 '
467
+ + 'config_insecure **报错**(走 failFromTagged),根本到不了这个成功形态',
346
468
  configured: 'true 只表示"两个字段都有值",**不代表**它们有效 —— 拼错的 appKey 同样返回 true',
347
469
  },
348
470
  });
@@ -13,7 +13,7 @@
13
13
  // 不能因为 env 恰好齐备就替用户瞒下它。读文件的前提(env 缺项)意味着
14
14
  // 这条只会在「真的要用的文件」上触发。
15
15
  import { resolveCredentials } from '../core/credentials.js';
16
- import { fileCredentials } from '../core/config.js';
16
+ import { fileCredentials, isWhitespaceOnly, nonEmptyValue } from '../core/config.js';
17
17
  /**
18
18
  * 当前进程的凭证环境变量(架构审查 M-3 的同款收口:调用方应传
19
19
  * `currentCredentialEnv()`,需要注入的测试自己传对象 —— 缺省 env 是静默忽略,
@@ -22,15 +22,40 @@ import { fileCredentials } from '../core/config.js';
22
22
  export function currentCredentialEnv() {
23
23
  return { appKey: process.env.QIYU_APP_KEY, appSecret: process.env.QIYU_APP_SECRET };
24
24
  }
25
- /** env 里该字段是否有**非空**值(空串视为未设置 —— shell 里变量未设的典型形态)。 */
26
- const has = (v) => v !== undefined && v !== '';
25
+ /** env 里该字段是否有**非空**值(空串视为未设置 —— 判据的唯一实现在 core/config.ts)。 */
26
+ const has = (v) => nonEmptyValue(v) !== undefined;
27
27
  export function resolveCredentialsUsingFile(env = currentCredentialEnv(), opts = {}) {
28
28
  const envKey = has(env.appKey);
29
29
  const envSecret = has(env.appSecret);
30
+ // ⚠️ 纯空白(A12,2026-11-06):`' '` 是 truthy,此前被当成「已配置」,
31
+ // 于是既不读文件、也不报缺凭证,直到服务端 14001 才暴露。它也不是「未设置」——
32
+ // 用户确实给了值,只是给错了:**拒绝并点名变量**,而不是悄悄回落到配置文件。
33
+ const blank = [
34
+ ...(isWhitespaceOnly(env.appKey) ? ['QIYU_APP_KEY'] : []),
35
+ ...(isWhitespaceOnly(env.appSecret) ? ['QIYU_APP_SECRET'] : []),
36
+ ];
37
+ if (blank.length > 0) {
38
+ return {
39
+ ok: false,
40
+ error: {
41
+ code: 'auth_missing', kind: 'auth_missing', retryable: false,
42
+ message: `环境变量 ${blank.join('、')} 只有空白字符(不是有效凭证)`,
43
+ hint: `请把它们设为真实值;若本意是不设置,用 \`unset ${blank.join(' ')}\``
44
+ + ' 删除变量,让配置文件的凭证生效',
45
+ },
46
+ };
47
+ }
30
48
  let fromFile;
31
49
  let configWarn;
32
50
  if (!envKey || !envSecret) {
33
- const r = fileCredentials(opts.configPath);
51
+ // ⚠️ `opts.profile` 是命令行的 `--profile`,必须传进来:只按 QIYU_PROFILE/defaultProfile
52
+ // 选档会让凭证与 store 选到不同的 profile(`QIYU_PROFILE=staging … --profile prod`
53
+ // → staging 的凭证写 prod 的库)。缺省 `undefined` 时行为与旧版逐字一致。
54
+ // `envProfile` 可注入只为测试不碰真实 `QIYU_PROFILE`(生产调用点一律走缺省)。
55
+ const envProfile = opts.envProfile !== undefined
56
+ ? opts.envProfile
57
+ : nonEmptyValue(process.env.QIYU_PROFILE);
58
+ const r = fileCredentials(opts.configPath, envProfile, opts.profile);
34
59
  if (r.fatal !== undefined) {
35
60
  // 权限拒绝带 kind(config_insecure):如实透出 —— 退出码 1、hint 点名 chmod。
36
61
  const t = r.fatal;
@@ -48,7 +73,7 @@ export function resolveCredentialsUsingFile(env = currentCredentialEnv(), opts =
48
73
  try {
49
74
  // 空串视为未设置传给 resolveCredentials:`??` 链会把 '' 当有效值放行,
50
75
  // 随后 `if (!appKey)` 又按缺失报错 —— 两层对"空"的判定不一致,先归一。
51
- const creds = resolveCredentials({}, {
76
+ const creds = resolveCredentials({
52
77
  appKey: has(env.appKey) ? env.appKey : undefined,
53
78
  appSecret: has(env.appSecret) ? env.appSecret : undefined,
54
79
  }, fromFile);
@@ -0,0 +1,75 @@
1
+ /** 渲染成 `a = 释义;b = 释义` —— field_notes 的单元格形态(与 query / sync / stats 同款)。 */
2
+ function renderNotes(notes) {
3
+ return Object.entries(notes).map(([k, v]) => `${k} = ${v}`).join(';');
4
+ }
5
+ /**
6
+ * `time_column.kind` 三个取值(2026-10-28 真库实测的存储形态)。
7
+ *
8
+ * 导出供测试双向核对(枚举 ⊆ 图例、图例 ⊆ 枚举)。
9
+ */
10
+ export const TIME_COLUMN_KINDS = ['iso-day', 'iso-instant', 'epoch-ms'];
11
+ export const TIME_COLUMN_KIND_NOTES = {
12
+ 'iso-day': '库内存的是 UTC 瞬时串(上海自然日零点 = 前一日 16:00Z),所有元数据出口展示为 '
13
+ + '+08:00。⚠️ 在 --sql 里直接按字符串比较时要用 UTC 形态,否则会少算一天',
14
+ 'iso-instant': 'ISO 8601 时刻串,可带 Z 或 +08:00 偏移。取值按解析后的时刻排序,'
15
+ + '不按字符串字典序(混合偏移下两者相反)',
16
+ 'epoch-ms': '毫秒时间戳的数字字符串(列类型是 VARCHAR,内容是 BIGINT)。比较前先 CAST 成整数',
17
+ };
18
+ /** `db describe` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。 */
19
+ export function describeFieldNotes() {
20
+ return {
21
+ grain: '声明里的行粒度(一行代表什么)。来自本 CLI 的表定义,不是从数据推出来的,'
22
+ + '表不在库中时它照样输出',
23
+ primary_key: '声明里的主键列。同样是声明:库里被删表或改过约束时这里不会变',
24
+ columns: '声明元数据(来自本 CLI 的表定义),不是库里的实况:表不在库中、列被删或多出列时'
25
+ + '这里照旧输出声明值,实况差异只在 warnings 里点名。columns / pii_columns / time_column'
26
+ + '三者都是声明——要判断「库里真实有什么」只能看 warnings',
27
+ 'columns[].type': '声明里的列类型(VARCHAR 等)。同样是声明,不是从库里读出来的',
28
+ 'columns[].nullable': '声明里的可空性。null 值是否真的允许由库决定,这里不反映实况',
29
+ 'columns[].sensitive': 'true = 声明为敏感 PII。声明值,不是库里的实况。'
30
+ + '⚠️ 可靠的按列脱敏只对 query --table 默认成立(--no-mask 可关闭,'
31
+ + '关闭后输出就是原始 PII)。query --sql 不走列白名单,只有列名级与值级兜底,'
32
+ + '别把 --sql 的输出当成已脱敏',
33
+ 'columns[].unit': '声明里的单位或形态说明(自由文本)。null = 该列没有声明单位,'
34
+ + '不代表「无单位」',
35
+ 'columns[].observed_enum': '声明里记录的上游观测取值。null = 没记录。'
36
+ + '⚠️ 它是观测记录不是约束:列里出现列表之外的值不算错误',
37
+ 'columns[].note': '声明里的补充说明。null = 没有',
38
+ pii_columns: '敏感列的名单(从 columns 派生,同样是声明)。'
39
+ + '⚠️ query --table 默认按列精确脱敏(--no-mask 可关闭,关闭后就是原始 PII),'
40
+ + '而 query --sql 不走列白名单、只有列名级与值级兜底——不要把 --sql 的输出当成已脱敏。'
41
+ + '一律不要 SELECT *',
42
+ // ⚠️ 枚举释义挂在 `time_column.kind` 上(2026-11-05 审查修):枚举值属于 kind 字段,
43
+ // 挂在 `time_column` 上会被反向解析读成「time_column 本身有三个取值」,而它实际是
44
+ // `{name, kind}` 或 null。本键只讲字段本身与 null 的含义。
45
+ time_column: '声明里的时间列({name, kind},来自本 CLI 的表定义,不是库里的实况)。'
46
+ + 'null = 该表没有声明时间列(此时 time_range 也为 null,不能按时间过滤)。'
47
+ + 'kind 的三个取值见 time_column.kind',
48
+ // ⚠️ 本单元格必须是**纯枚举**(`a = 释义;b = 释义`):反向解析靠这个形状。
49
+ // 「它也是声明」这条已写进 columns 与 time_column 的释义,别塞回这里。
50
+ 'time_column.kind': renderNotes(TIME_COLUMN_KIND_NOTES),
51
+ row_count: '库中该表的真实行数(COUNT(*),不是估算)。null = 表不在库中,'
52
+ + '这是唯一的 null 成因。此时 columns 等字段仍是声明元数据,不要当成库里有这张表',
53
+ time_range: '时间列在整表范围内的 MIN/MAX(+08:00 ISO,只算形态合法的行)。'
54
+ + '⚠️ 它是整表首尾,不是「你关心的区间」。null 有四种成因,靠别的字段区分:'
55
+ + '表没有声明时间列(time_column 为 null)、表不在库中(row_count 为 null)、'
56
+ + '时间列被删(warnings 点名少列)、没有一行的时间值能过形态谓词'
57
+ + '(row_count 为 0 或全为脏值/NULL)',
58
+ };
59
+ }
60
+ /** `db tables` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。 */
61
+ export function tablesFieldNotes() {
62
+ return {
63
+ tables: '库中真实存在的表,顺序以本 CLI 的表定义为准。⚠️ 声明有而库中无的表'
64
+ + '不在这里,只在 warnings 里点名——所以「清单里没有某张表」不等于「这张表不存在」',
65
+ 'tables[].rows': '该表的真实行数(COUNT(*),不是估算)',
66
+ 'tables[].grain': '声明里的行粒度说明(一行代表什么)。声明,不是从数据推出来的',
67
+ 'tables[].time_range': '时间列在整表范围内的 MIN/MAX(+08:00 ISO,只算形态合法的行)。'
68
+ + 'null 有三种成因:表没有声明时间列、时间列被删(warnings 点名)、'
69
+ + '没有一行的时间值能过形态谓词(空表,或全是脏值/NULL —— 脏值另有 warning 报数量)。'
70
+ + '注意这里没有「表不在库中」这一种:那种表根本不会出现在 tables 里',
71
+ 'tables[].pii_columns': '敏感列的名单(声明)。⚠️ 按列精确脱敏只对 query --table 默认成立'
72
+ + '(--no-mask 可关闭,关闭后就是原始 PII),query --sql 不走列白名单,'
73
+ + '别把它的输出当成已脱敏',
74
+ };
75
+ }