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.
Files changed (70) hide show
  1. package/README.md +349 -57
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +54 -0
  4. package/dist/commands/api.js +113 -39
  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 +477 -38
  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 +182 -121
  21. package/dist/core/config.js +274 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +13 -3
  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 +122 -27
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +38 -8
  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
@@ -2,7 +2,7 @@
2
2
  //
3
3
  // 配置文件的**通用层**(G1 第三批抽取):路径解析、读文件、JSON 解析、
4
4
  // 键白名单校验、credentials/robots 块校验、权限检查、原子写。
5
- // 只 import node:fs/os/path —— 这是「commands/auth.ts 与 commands/api.ts
5
+ // 只 import node 内置 + `core/shell.js` 的 shellArg(引号单一实现点,已下沉到 core 以免违反「core 不得 import output.js」的分层守卫)—— 这是「commands/auth.ts 与 commands/api.ts
6
6
  // 不得加载 store/」这条分层红线(layering.test.ts 钉着)的解法:
7
7
  // auth/api 只 import 本文件,`store/config.ts` 内部也走这里。
8
8
  //
@@ -10,9 +10,10 @@
10
10
  // (backend/path/readOnlyRetryMs/batchSize/options 的语义校验仍在 store 侧),
11
11
  // 只提供「配置文件作为载体」的全部通用能力。错误文案与 C1 逐字兼容 ——
12
12
  // 现有 25 条 config.test.ts 一条不改地全绿是本次抽取的验收线。
13
- import { readFileSync, writeFileSync, lstatSync, statSync, existsSync, mkdirSync, renameSync, chmodSync } from 'node:fs';
13
+ import { readFileSync, writeFileSync, lstatSync, statSync, existsSync, mkdirSync, renameSync, chmodSync, accessSync, constants as fsConstants } from 'node:fs';
14
14
  import { homedir } from 'node:os';
15
15
  import { join, dirname } from 'node:path';
16
+ import { shellArg } from './shell.js';
16
17
  /** 顶层已知键 —— 未知键 fail-closed(spec §3.3)。 */
17
18
  export const KNOWN_TOP = new Set(['defaultProfile', 'profiles']);
18
19
  /** profile 内已知键:store(C1)+ credentials/robots(G1 起,`auth login` 写入)。 */
@@ -30,15 +31,42 @@ export function readConfigRaw(configPath) {
30
31
  raw = readFileSync(configPath, 'utf8');
31
32
  }
32
33
  catch (e) {
34
+ // ⚠️ EACCES/EPERM 不包成普通 Error:Windows 上 fs.access 不评估 NTFS ACL,
35
+ // 真拒绝可能出现在这里(CodeRabbit 第十三轮),必须与探测点同口径给
36
+ // config_insecure + 平台化修法(见 `permissionReadError`)。
37
+ const code = e.code;
38
+ if (code === 'EACCES' || code === 'EPERM')
39
+ throw permissionReadError(configPath);
33
40
  throw new Error(`无法读取配置文件 ${configPath}:${e instanceof Error ? e.message : String(e)}`);
34
41
  }
35
42
  try {
36
43
  return JSON.parse(raw);
37
44
  }
38
45
  catch (e) {
39
- throw new Error(`配置文件 ${configPath} 不是合法 JSON:${e instanceof Error ? e.message : String(e)}`);
46
+ // ⚠️ 绝不能把 `e.message` 附上:V8 的 JSON.parse 报错**自带出错位置附近的原文片段**
47
+ // (`Unexpected token 'F', "FAKESECRET…" is not valid JSON`)。配置文件里就有凭证,
48
+ // 原样带出等于把 appKey/appSecret 的前若干字符写进 stdout —— 违反「凭据绝不出现在
49
+ // stdout」这条红线(与 store 层 stripSqlEcho 同类:外部字节进报文前必须先剥离)。
50
+ // 只保留**位置信息**(`at position N (line L column C)`),它对定位语法错误足够,
51
+ // 且不含任何文件内容;取不到位置时退化为纯类别描述。
52
+ throw new Error(`配置文件 ${configPath} 不是合法 JSON${jsonErrorPosition(e)}`);
40
53
  }
41
54
  }
55
+ /**
56
+ * 从 `JSON.parse` 的报错里**只**抽出位置后缀(`。语法错误在 position 12(第 1 行第 13 列)`)。
57
+ * 报错文本里的原文片段一律丢弃 —— 那是文件内容,可能含凭证(见 `readConfigRaw` 的说明)。
58
+ * V8 的两种形态都覆盖:新式 `… in JSON at position 5 (line 1 column 6)` 与
59
+ * 旧式 `… at position 5`;两者都无则返回空串(只留类别描述)。
60
+ */
61
+ function jsonErrorPosition(e) {
62
+ const msg = e instanceof Error ? e.message : String(e);
63
+ const m = /\bat position (\d+)(?:\s*\(line (\d+) column (\d+)\))?/.exec(msg);
64
+ if (!m)
65
+ return '';
66
+ return m[2] !== undefined
67
+ ? `。语法错误在 position ${m[1]}(第 ${m[2]} 行第 ${m[3]} 列)`
68
+ : `。语法错误在 position ${m[1]}`;
69
+ }
42
70
  function assertObject(v, label) {
43
71
  if (v === null || typeof v !== 'object' || Array.isArray(v)) {
44
72
  throw new Error(`配置文件 ${label} 必须是对象`);
@@ -55,7 +83,12 @@ export function parseConfig(raw) {
55
83
  if (!KNOWN_TOP.has(k))
56
84
  throw new Error(`配置文件未知键:${k}`);
57
85
  }
58
- const profiles = {};
86
+ // ⚠️ null 原型(2026-10-27,CodeRabbit 实测复现):普通 `{}` 上
87
+ // `profiles['constructor']` 命中的是 `Object.prototype.constructor`(非 undefined)——
88
+ // 拼错成 `--profile constructor` 会绕过「未知 profile 必须拒绝」的守卫,静默回落默认库;
89
+ // 而 `profiles['__proto__'] = block` 会**改掉原型**而不是建键。两个入口都由这一行关掉:
90
+ // 查不到继承属性,`__proto__` 也只是个普通键名。
91
+ const profiles = Object.create(null);
59
92
  if (raw.profiles !== undefined) {
60
93
  const profObj = assertObject(raw.profiles, 'profiles');
61
94
  for (const [name, prof] of Object.entries(profObj)) {
@@ -100,12 +133,163 @@ export function parseConfig(raw) {
100
133
  }
101
134
  return { defaultProfile, profiles };
102
135
  }
103
- /** 读 + 解析一步完成(文件不存在返回空结构)。**不含权限裁决**(见 `loadConfigChecked`)。 */
136
+ /**
137
+ * 读 + 解析一步完成(文件不存在返回空结构)。**不含权限过宽的裁决**(见 `loadConfigChecked`)。
138
+ *
139
+ * ⚠️ 但「读不出来**是因为权限**」在这里就要分流(Codex 2026-11-10 第四轮 P2):
140
+ * `readConfigRaw` 把读失败包成无 kind 的普通 Error,与「畸形 JSON」同一个出口 ——
141
+ * 调用方各自的「权限拒绝」分支于是全是死代码(login 报 config_invalid、store 侧被
142
+ * 包成 usage 退出码 2,而 api/sync 走另一条路报 config_insecure:同一状态三种说法)。
143
+ * 探测放在**唯一读取点**,所有调用方(auth/api/sync/store)自动同口径。
144
+ */
104
145
  export function loadConfigFile(configPath) {
146
+ assertConfigReadable(configPath);
105
147
  const exists = existsSync(configPath);
106
148
  const raw = readConfigRaw(configPath);
107
149
  return { file: parseConfig(raw), exists };
108
150
  }
151
+ /**
152
+ * 把路径渲染成**可直接粘贴进 shell** 的形态(含空白或 shell 特殊字符时加双引号)。
153
+ *
154
+ * ⚠️ 为什么 hint 里要引号(CodeRabbit 2026-10-26):配置路径来自 `HOME`,而 `HOME`
155
+ * 可以含空格(如 `/Users/John Doe`)。不引号时 hint 里的 `chmod 600 /Users/John Doe/...`
156
+ * 会被 shell 拆成多个参数 —— 用户照着抄反而得到一条 `chmod: 无法访问 'Doe/...'`,
157
+ * 而这条 hint 的全部价值就是"照着执行就能修好"。
158
+ *
159
+ * ⚠️ 导出给 `commands/auth.ts` 的写后自检用:那是**唯一**不走 `insecureConfigError`
160
+ * 的权限 hint(消息不同:凭证已经写进去了),引号规则必须同源,否则同一个 chmod
161
+ * 在一处可执行、在另一处不可执行。
162
+ */
163
+ export function shellPath(p) {
164
+ return /[\s"'`$\\]/.test(p) ? `"${p.replace(/[\\"`$]/g, '\\$&')}"` : p;
165
+ }
166
+ /**
167
+ * 权限拒绝的**唯一构造点**(两个配置解析入口共用同一句话)。
168
+ *
169
+ * ⚠️ 为什么必须共用(2026-10-26 实测):此前 `loadConfigChecked`(auth/api 走)抛带
170
+ * `kind: config_insecure` 的错误,而 `store/config.ts`(store/db/query/stats/sync 走)
171
+ * 抛**无 kind** 的普通 Error,各命令 catch 又一律 `usageFail(...)` —— 同一个危险状态
172
+ * 因此有两种行为:`auth whoami` 是退出码 1 + `kind: config_insecure` + `chmod` hint;
173
+ * 其余六条命令是退出码 2 + `kind: usage`(语义是"改参数重来")且 hint 丢失。
174
+ * Agent 会照退出码去改参数,而这件事只能由人去 chmod —— 设计稿 §3.4 与 README
175
+ * 写的都是前者,所以 store 那条路径是缺陷,不是另一种口径。
176
+ */
177
+ export function insecureConfigError(configPath, reason,
178
+ /** `dir-unreadable` 专用:路径上**最外层**被权限挡住的目录(见 `blockedAncestor`)。 */
179
+ blockedDir,
180
+ /** 测试可注入;生产恒为 `process.platform`。 */
181
+ platform = process.platform) {
182
+ const dir = dirname(configPath);
183
+ // ⚠️ 四种成因必须是四句话(CR/Codex 2026-11-10 第六轮 + 第十轮):`unreadable` 是**当前
184
+ // 用户读不了**,与「含凭证且过宽」相反(那说的是别人能读)—— 套用过宽的文案会把
185
+ // 「权限位全零、不含凭证的文件」说成凭证暴露风险,Agent 会去查一个不存在的泄露面;
186
+ // `dir-unreadable` 又是另一层(目录进不去),修法与文案都不能套用文件那一档。
187
+ // ⚠️ `dir-unreadable` 点名的必须是**真正挡路的目录**(Codex 2026-11-10 第十一轮 P2):
188
+ // `~/.config` 000 时 `accessSync(~/.config/qiyu, X_OK)` 同样 EACCES,照 `dirname` 报会
189
+ // 让人 chmod 一条**本身都执行不了**的路径(实测 `chmod: … Permission denied`)。
190
+ // ⚠️ Windows 上 EACCES/EPERM 的成因是 **ACL**(不是 POSIX 权限位),`chmod` 不存在于
191
+ // Windows —— 修法必须平台化(Codex 2026-11-10 第十二轮 P2):`icacls /reset` 恢复继承的
192
+ // ACL;引号按 win32 方言走 `shellArg`(hint 会被真的执行,引号规则只许一个实现点)。
193
+ const blocked = blockedDir ?? dir;
194
+ const win = platform === 'win32';
195
+ const what = reason === 'file'
196
+ ? `配置文件 ${configPath} 含凭证但权限过宽(group/other 有权限位;可读时其他用户就能读到 appSecret)`
197
+ : reason === 'dir'
198
+ ? `配置目录 ${dir} 权限过宽(group/other 可写,文件可被整体替换)且配置含凭证`
199
+ : reason === 'dir-unreadable'
200
+ ? win
201
+ ? `配置路径上的目录 ${blocked} 被 Windows ACL 拒绝访问(不是 POSIX 权限位,chmod 修不了它)`
202
+ : `配置目录 ${blocked} 当前用户不可搜索(它挡在配置路径上,因此读不到其中的配置文件;`
203
+ + `若它下面还有不可进入的层,修好这一层后重跑会重新点名;与文件里有没有凭证无关)`
204
+ : win
205
+ ? `配置文件 ${configPath} 被 Windows ACL 拒绝读取(不是 POSIX 权限语义,chmod 修不了它;与文件里有没有凭证无关)`
206
+ : `配置文件 ${configPath} 当前用户没有读取权限(权限位拒绝了本次读取;与文件里有没有凭证无关)`;
207
+ const fix = win && (reason === 'unreadable' || reason === 'dir-unreadable')
208
+ ? `icacls ${shellArg(reason === 'dir-unreadable' ? blocked : configPath, 'win32')} /reset`
209
+ + `(恢复继承的 ACL;也可在「属性 → 安全」里给当前用户授予读取权限)`
210
+ : reason === 'dir' || reason === 'dir-unreadable'
211
+ ? `chmod 700 ${shellPath(blocked)}`
212
+ : `chmod 600 ${shellPath(configPath)}`;
213
+ return Object.assign(new Error(`${what},已拒绝读取`), {
214
+ code: 'config_insecure', kind: 'config_insecure', retryable: false,
215
+ hint: `这是配置文件的权限问题,重试无用 —— 请执行:${fix}`,
216
+ });
217
+ }
218
+ /**
219
+ * 路径上**最外层**不可进入(不可搜索)的目录 —— 修法必须落在它身上。
220
+ *
221
+ * ⚠️ 为什么不能直接用 `dirname(configPath)`(Codex 2026-11-10 第十一轮 P2,实测):
222
+ * `~/.config` 是 000、`~/.config/qiyu` 本身 700 时,`accessSync(qiyu, X_OK)` 照样 EACCES
223
+ * (穿不过 .config),于是会被误当成「qiyu 挡路」。hint 因此建议 `chmod 700 …/qiyu` ——
224
+ * 这条命令本身都执行不了(`chmod: … Permission denied`),照做后仍读不到配置。
225
+ *
226
+ * 从配置目录逐层向上探,记下**最后一个** EACCES/EPERM 的目录(即最外层挡路者):
227
+ * 它的父目录一定是能进入的(否则循环会继续往上),所以 `chmod 700` 对它的父目录有效、
228
+ * 一定可执行。更深的层若也被挡,等这层修好后重跑会重新点名(文案里已说明)。
229
+ * 上面某一层是**别的**错误(如 ENOTDIR)时停在那里,交回既有口径。
230
+ */
231
+ function blockedAncestor(dir) {
232
+ let blocked = null;
233
+ let cur = dir;
234
+ for (;;) {
235
+ try {
236
+ accessSync(cur, fsConstants.X_OK);
237
+ return blocked; // 这一层进得去:上面记下的最深不可进入者就是真正挡路的
238
+ }
239
+ catch (e) {
240
+ const code = e.code;
241
+ if (code !== 'EACCES' && code !== 'EPERM')
242
+ return blocked;
243
+ blocked = cur;
244
+ const parent = dirname(cur);
245
+ if (parent === cur)
246
+ return blocked; // 到根了
247
+ cur = parent;
248
+ }
249
+ }
250
+ }
251
+ /**
252
+ * 「配置文件读不出来**是因为权限**」→ 转成 `insecureConfigError`(同一个 kind,但成因文案与
253
+ * 修法按「挡在哪一层」区分:读不了 ≠ 别人能读;**目录不可进入** ≠ 文件本身读不了)。
254
+ *
255
+ * ⚠️ 不能用 `existsSync` 判「有没有配置」(Codex 2026-11-10 第十轮 P2,实测):父目录
256
+ * `chmod 000` 时穿过它的 `stat` 被 EACCES 吞掉,`existsSync(文件)` 返回 **false** ——
257
+ * 于是真配置被当成「不存在」,`auth whoami` 报 `auth_missing`、store/query 回落默认库,
258
+ * 而用户真正要做的是 chmod 目录。改为直接 `accessSync`:**只有 ENOENT 才是「没有配置」**。
259
+ *
260
+ * 只按 errno 属性分流(EACCES / EPERM),不拿报文文本去挑 —— 见
261
+ * `tests/open-failure-single-source.test.ts` 的同款规则。其余 errno(如 ENOTDIR)沿用
262
+ * 旧口径「按缺失处理」:这条判据只回答「权限挡没挡住」,别的读失败不在这里另立成因。
263
+ */
264
+ export function assertConfigReadable(configPath) {
265
+ try {
266
+ accessSync(configPath, fsConstants.R_OK);
267
+ }
268
+ catch (e) {
269
+ const code = e.code;
270
+ if (code !== 'EACCES' && code !== 'EPERM')
271
+ return;
272
+ // 同样是 EACCES,挡在哪一层决定修法:目录不可进入时对文件 chmod 本身就会失败,
273
+ // 而目录又可能不是直接父目录(祖先被挡时子目录的 accessSync 一样报 EACCES)。
274
+ throw permissionReadError(configPath);
275
+ }
276
+ }
277
+ /**
278
+ * 读点上 EACCES/EPERM 的**唯一分类出口**(`assertConfigReadable` 与 `readConfigRaw` 共用)。
279
+ *
280
+ * ⚠️ 为什么读点也要分流(CodeRabbit 2026-11-11 第十三轮):Node 的 `fs.access` 在 Windows
281
+ * 上**不评估 NTFS ACL** —— ACL 拒绝时 `accessSync(R_OK)` 可能成功、真拒绝发生在后面的
282
+ * `readFileSync`。只靠探测点分流,`config_insecure`(含 icacls hint)在 Windows 上就是
283
+ * **不可达分支**:拒绝被 `readConfigRaw` 包成无 kind 的普通 Error,login 报 config_invalid、
284
+ * store 族报 usage 2 —— 「同一个危险状态,多种行为」的旧乱象全数复活。POSIX 上这也是
285
+ * 竞态的兜底(access 通过后、读之前权限被改)。
286
+ */
287
+ function permissionReadError(configPath) {
288
+ const blocked = blockedAncestor(dirname(configPath));
289
+ return blocked !== null
290
+ ? insecureConfigError(configPath, 'dir-unreadable', blocked)
291
+ : insecureConfigError(configPath, 'unreadable');
292
+ }
109
293
  /**
110
294
  * 读 + 解析 + **权限裁决**(含凭证且过宽 → 抛带 kind 的错误)。
111
295
  *
@@ -125,15 +309,8 @@ export function loadConfigChecked(configPath) {
125
309
  hasCredentials: configHasCredentials(loaded.file),
126
310
  onWarn: (m) => process.stderr.write(`${m}\n`),
127
311
  });
128
- if (!perm.ok) {
129
- const dir = dirname(configPath);
130
- const what = perm.reason === 'file' ? `配置文件 ${configPath}` : `配置目录 ${dir}`;
131
- const fix = perm.reason === 'file' ? `chmod 600 ${configPath}` : `chmod 700 ${dir}`;
132
- throw Object.assign(new Error(`${what} 含凭证但权限过宽(group/other 可访问,其他用户可读到 appSecret),已拒绝读取`), {
133
- code: 'config_insecure', kind: 'config_insecure', retryable: false,
134
- hint: `这是配置文件的权限问题,重试无用 —— 请执行:${fix}`,
135
- });
136
- }
312
+ if (!perm.ok)
313
+ throw insecureConfigError(configPath, perm.reason);
137
314
  return loaded;
138
315
  }
139
316
  /**
@@ -192,6 +369,73 @@ export function checkPermissions(configPath, opts) {
192
369
  export function configHasCredentials(file) {
193
370
  return Object.values(file.profiles).some((p) => p.credentials !== undefined);
194
371
  }
372
+ /**
373
+ * 「环境变量里的空串 = 未设置」的**唯一实现**(2026-10-29)。
374
+ *
375
+ * `export QIYU_DB_PATH=` 是 shell 里「变量没填」的典型形态,不是「把值设成空串」。
376
+ * `''` 不是 null/undefined,`??` 链会把它当有效值放行 —— 于是它**遮蔽**下一层的真实值:
377
+ * · 档名:`QIYU_PROFILE=` 让 `auth login` 把凭证写进 `profiles[""]`(没人读的档);
378
+ * · 库路径:`QIYU_DB_PATH=` 遮蔽配置文件里配好的 `store.path`,命令以「路径不能为空」
379
+ * 失败,而报错还声称 `store.path` 也是空的(真库实测)。
380
+ *
381
+ * 调用方:`resolveProfileName` / `resolveStoreConfig` / `storeArgsFor`(sync install)/
382
+ * `credentials-source` / `auth login`。新增环境变量读取一律用它,不要手写
383
+ * `x !== undefined && x !== ''`(`tests/empty-string-single-source.test.ts` 会红)。
384
+ *
385
+ * ⚠️ 只有**恰好**空串算未设置;空白串(`' '`)是非法值,凭证路径用
386
+ * `isWhitespaceOnly` 拒绝并点名来源(2026-11-06 审查:此前没有一处拒绝)。
387
+ * ⚠️ **显式 flag**(`--db ''`)不走这里:把用户明确给出的空值悄悄换成另一份资源,
388
+ * 是「静默回落」缺陷本体,不是修复。
389
+ */
390
+ export function nonEmptyValue(v) {
391
+ return v !== undefined && v !== '' ? v : undefined;
392
+ }
393
+ /**
394
+ * 「值只有空白字符」的**唯一实现**(2026-11-06 审查 A12)。
395
+ *
396
+ * 与 `nonEmptyValue`(只认**恰好**空串)分工:空串 = 未设置(回落下一层),
397
+ * 纯空白 = 用户确实给了值、但那个值不可能是凭证(`export QIYU_APP_KEY=" "`、
398
+ * 复制粘贴带上了空格)。此前注释说「由各调用方按自己的规则拒绝」,而凭证路径
399
+ * **一处都没拒绝** —— `auth whoami` 报 `configured: true`、`api call` 拿它去签名,
400
+ * 直到服务端 14001 才暴露。
401
+ *
402
+ * 凭证路径统一用它**拒绝并点名来源**(谁给的坏值修谁);路径类参数不要用它
403
+ * (`--db ' '` 有自己的报错,见 store/config.ts)。
404
+ */
405
+ export function isWhitespaceOnly(v) {
406
+ return v !== undefined && v !== '' && v.trim() === '';
407
+ }
408
+ /**
409
+ * profile 名的**唯一解析点**:`--profile` > `QIYU_PROFILE` > `defaultProfile` > 内置 `default`。
410
+ *
411
+ * ⚠️ 空串一律当**未设置**:`export QIYU_PROFILE=`(变量未设的典型形态)与
412
+ * `"defaultProfile": ""`(JSON 里清空字段)都不该选中一个名叫空串的档。
413
+ *
414
+ * ⚠️ **为什么必须只有一处**(2026-10-29 真库实测):`auth whoami` 与 `auth login` 曾各自
415
+ * 用 `??` 链重写了一遍,而 `''` 不是 null/undefined、`??` 会把它放行 —— 于是同一份配置
416
+ * 在不同命令上解出两个档名:
417
+ * · `"defaultProfile": ""` 时 `auth login` 把凭证写进 `profiles[""]`,而 `api call` /
418
+ * `store` / `sync` 按 `default` 读 —— login 报 `configured: true`、whoami 也报
419
+ * `configured: true`,可第一次真实调用报 `缺少 appKey`(凭证写进了没人读的档);
420
+ * · `QIYU_PROFILE=` 时 `auth whoami` 选中空串档 → 报 `auth_missing`,而 `api call`
421
+ * 照样从 `defaultProfile` 的档里读到凭证并发出请求 —— 同一台机器上两个命令给出
422
+ * 相反的"凭证有没有配"。
423
+ * README「配置文件」一节的空串口径(`QIYU_PROFILE=` 与 `"defaultProfile": ""` 视为未设置)
424
+ * 就是本函数的规格;四个调用点(fileProfile / resolveStoreConfig / whoami / login)共用它,
425
+ * 不得再各自写 `??` 链。
426
+ */
427
+ export function resolveProfileName(opts = {}) {
428
+ const flag = nonEmptyValue(opts.flag);
429
+ if (flag !== undefined)
430
+ return { name: flag, source: '--profile' };
431
+ const env = nonEmptyValue(opts.envProfile);
432
+ if (env !== undefined)
433
+ return { name: env, source: 'QIYU_PROFILE' };
434
+ const def = nonEmptyValue(opts.defaultProfile);
435
+ if (def !== undefined)
436
+ return { name: def, source: 'defaultProfile' };
437
+ return { name: 'default' };
438
+ }
195
439
  /**
196
440
  * 读配置里某个 profile 的块(G1:凭证与 robots 都从这里取)。
197
441
  *
@@ -200,34 +444,40 @@ export function configHasCredentials(file) {
200
444
  * ⚠️ 畸形配置**不抛**(只记 `warn`):环境变量齐备时 `api call` 仍应能工作 ——
201
445
  * 把一个坏掉的配置文件升级成"所有命令都不可用"是过度反应。
202
446
  * 但**缺凭证**的最终判定仍由 `resolveCredentials` 做,本函数不越权下结论。
447
+ *
448
+ * ⚠️ `flagProfile` 是命令行的 `--profile`,必须与 store 侧 `resolveStoreConfig`
449
+ * 走同一个 `resolveProfileName`:`QIYU_PROFILE=staging qiyu sync run --profile prod`
450
+ * 若凭证据 env 选档、库按 flag 选档,就会拿 staging 的凭证往 prod 的库里写。
451
+ * 优先级 flag > env > defaultProfile 由 `resolveProfileName` 保证(唯一实现)。
203
452
  */
204
- export function fileProfile(configPath = configPathFor(), envProfile = process.env.QIYU_PROFILE) {
453
+ export function fileProfile(configPath = configPathFor(), envProfile = process.env.QIYU_PROFILE, flagProfile) {
205
454
  let file;
206
455
  try {
207
456
  file = loadConfigChecked(configPath).file;
208
457
  }
209
458
  catch (e) {
210
- // ⚠️ 空串当未设置:`export QIYU_PROFILE=`(变量未设的典型形态)不该选中
211
- // 一个名叫 '' 的 profile —— 与凭证侧「空串视为缺失」同一口径。
212
- const name = envProfile !== undefined && envProfile !== '' ? envProfile : 'default';
459
+ // 配置读不出来时只能按 flag/env 判档名(defaultProfile 也读不到)—— 空串口径与下面同源。
460
+ const name = resolveProfileName({ flag: flagProfile, envProfile }).name;
213
461
  // 权限拒绝带 kind(`config_insecure`)→ 致命;畸形配置无 kind → 非致命。
214
462
  return e.kind !== undefined
215
463
  ? { profileName: name, fatal: e }
216
464
  : { profileName: name, warn: e.message };
217
465
  }
218
- const profileName = envProfile !== undefined && envProfile !== '' ? envProfile
219
- : file.defaultProfile !== undefined && file.defaultProfile !== '' ? file.defaultProfile
220
- : 'default';
466
+ const profileName = resolveProfileName({ flag: flagProfile, envProfile, defaultProfile: file.defaultProfile }).name;
221
467
  const profile = file.profiles[profileName];
222
468
  return profile === undefined ? { profileName } : { profileName, profile };
223
469
  }
224
470
  /** 配置里某个 profile 的凭证(`fileProfile` 的便捷视图,供 `resolveCredentials` 的第三参)。 */
225
- export function fileCredentials(configPath, envProfile) {
226
- const r = fileProfile(configPath, envProfile);
471
+ export function fileCredentials(configPath, envProfile, flagProfile) {
472
+ const r = fileProfile(configPath, envProfile, flagProfile);
227
473
  return r.profile?.credentials === undefined ? r : { ...r, creds: r.profile.credentials };
228
474
  }
229
475
  /**
230
- * 原子写配置文件:0700 目录 + 0600 临时文件 + rename 换入。
476
+ * 原子写配置文件:**新建**目录 0700 + 0600 临时文件 + rename 换入。
477
+ *
478
+ * ⚠️ 已存在的目录**不改权限**(0755 是常规 umask 产物):含凭证时真正的门禁是
479
+ * 「文件 0600 + 目录不可 group/other 写」(`checkPermissions`),目录位宽只暴露文件名、
480
+ * 读不到 appSecret。文档里「目录 0700」的措辞已按此收窄。
231
481
  *
232
482
  * ⚠️ **绝不用 writeFileSync 直写**:写一半崩溃会留下一个被截断的 config.json,
233
483
  * 下一次任何命令都起不来。临时文件与目标同目录(rename 跨文件系统才原子)。
@@ -1,10 +1,44 @@
1
+ import { isWhitespaceOnly } from './config.js';
1
2
  /**
2
- * 优先级:命令行参数 > 环境变量 > 配置文件。
3
+ * 优先级:环境变量 > 配置文件。
4
+ * ⚠️ **没有「命令行参数」这一层**,而且刻意不加:argv 会留在 shell 历史、`ps` 与 CI
5
+ * 日志里(`auth login --app-key` 被明确拒绝为未知参数,见 commands/auth.ts)。
6
+ * 2026-11-06 审查删除了旧的 `fromArgs` 形参 —— 它没有任何调用方传过非空值,
7
+ * 「预留的第三来源」只会让读代码的人以为凭证可以从命令行给。
3
8
  * 两者缺一即报错 —— 只给 appKey 就发请求必然拿 14001,不如在本地就说清楚。
4
9
  */
5
- export function resolveCredentials(fromArgs, env = {}, fromFile) {
6
- const appKey = fromArgs.appKey ?? env.appKey ?? fromFile?.appKey;
7
- const appSecret = fromArgs.appSecret ?? env.appSecret ?? fromFile?.appSecret;
10
+ export function resolveCredentials(env = {}, fromFile) {
11
+ const appKey = env.appKey ?? fromFile?.appKey;
12
+ const appSecret = env.appSecret ?? fromFile?.appSecret;
13
+ // ⚠️ 纯空白不是凭证(A12,2026-11-06):`' '` 是 truthy,此前会一路穿到签名,
14
+ // 服务端回 14001 —— 报错点离真正给坏值的地方隔了一层命令。CLI 侧的调用方
15
+ // (credentials-source / auth login / whoami)已用 `isWhitespaceOnly` 点名变量,
16
+ // 这里兜住**配置文件**里的空白值。判据必须复用同一个函数:两处各写一遍
17
+ // (`v !== undefined && v !== '' && v.trim() === ''`)迟早会分叉。
18
+ //
19
+ // ⚠️ 恢复动作必须按**来源**给(Codex PR #69 第七轮):同一条「删掉对应的…键」对
20
+ // 环境变量成立(删掉后 api/sync 回落读文件),对**配置键不成立** —— credentials
21
+ // 块要求 appKey/appSecret 同时是非空字符串,只删一个键会让整份配置被 parseConfig
22
+ // 拒绝(实测:此后 whoami 报「配置文件读取失败」、api/sync 也读不到其它档)。
23
+ const problems = [];
24
+ for (const [field, envVar, fromEnv, bad] of [
25
+ ['appKey', 'QIYU_APP_KEY', env.appKey !== undefined, isWhitespaceOnly(appKey)],
26
+ ['appSecret', 'QIYU_APP_SECRET', env.appSecret !== undefined, isWhitespaceOnly(appSecret)],
27
+ ]) {
28
+ if (!bad)
29
+ continue;
30
+ problems.push(fromEnv
31
+ // 环境变量层:删掉变量后本命令会回落到配置文件 —— 前提是文件里有这一档的凭证,
32
+ // 没有的话只是把错误挪到「缺少 …」。两条出路都写出来,不替用户假定文件里有什么。
33
+ ? `${field}(环境变量 ${envVar})只有空白字符 —— 设为真实值,或 \`unset ${envVar}\``
34
+ + ' 改用配置文件里的凭证(文件里没有的话仍会报缺少)'
35
+ // 配置文件层:不能只删单个键(整份配置会被拒)。要移除就移除整个 credentials 块。
36
+ : `${field}(配置文件)只有空白字符 —— 设为真实值,或删掉该 profile 的整个 credentials 块`
37
+ + '(只删单个键会让配置文件解析失败)');
38
+ }
39
+ if (problems.length > 0) {
40
+ throw new Error(`${problems.join(';')}。这些值都不是有效凭证`);
41
+ }
8
42
  if (!appKey) {
9
43
  throw new Error('缺少 appKey。请设置环境变量 QIYU_APP_KEY。');
10
44
  }
@@ -12,7 +12,17 @@
12
12
  // `scripts/copy-assets.mjs`(Task 13)在 tsc 之后把 dist/core/edition.js 里的
13
13
  // '0.0.0-dev' 字面量正则替换为 package.json 的 version。源码里永远保持占位值,
14
14
  // 靠测试钉住「构建产物非占位」这一契约。
15
- /** skill 正文契约版本:结构性改变才递增(spec D6)。 */
16
- export const SKILL_CONTRACT_VERSION = 1;
15
+ /**
16
+ * skill 正文契约版本:结构性改变才递增(spec D6)。
17
+ *
18
+ * 变更记录:
19
+ * · 1 —— F 子项目交付时的初版(六篇正文)。
20
+ * · 2 —— 2026-10-26:`SKILL.md` 新增「`qiyu skill where` 报出已安装正文的契约号与
21
+ * `compatible`」这一协议段落。**必须递增**:新正文要求 CLI 输出
22
+ * `data.entity.installed` 与 `data.cli_contract_version`,而 0.2.0 的 CLI 没有这些
23
+ * 字段 —— 若不递增,新正文配旧 CLI 会被 `compatible` 判成「配套」,Agent 照着读
24
+ * 会拿到 `undefined`(正是本字段要防的那种「看起来能用、实际不能用」)。
25
+ */
26
+ export const SKILL_CONTRACT_VERSION = 2;
17
27
  /** 包版本占位值;构建期被 copy-assets.mjs 替换为 package.json 的 version。 */
18
- export const PACKAGE_VERSION = '0.2.0';
28
+ export const PACKAGE_VERSION = '0.2.2';
@@ -44,14 +44,27 @@ function isEmptyPayload(v) {
44
44
  * 仅 {code,message} 一种形状就分裂成五种(JSON 对象/数组/数字/纯文本/键不存在),
45
45
  * 只按键集合分支的解析器会错四种。
46
46
  *
47
- * ⚠️ 最要命的一条:**形状 C 的端点,每一个错误也都返回 code:200**,配一段纯文本的
47
+ * ⚠️ 最要命的一条:**形状 C 的端点,错误也可能返回 code:200**,配一段纯文本的
48
48
  * message(`14501 ...`、`14004 Not found param`、`14009 api call too frequent`)。
49
49
  * 因此形状 C 上"message 解析不出 JSON"必须判为**失败**,不能当"成功但无数据"——
50
50
  * 否则 Agent 会把限流当成"这段时间没有数据",这是设计稿 §9.2 点名的头号静默失败。
51
+ *
52
+ * ⚠️ 本句此前写作「每一个错误都返回 code:200」,2026-10-30 实测 `ticket.list` 证伪:
53
+ * 它的 `staffId` 非法时返回 **`code:14100`** + 纯文本 `Bad holder staff id`。
54
+ * 判据不变(C 上 message 解析失败仍判错,且本分支先判 code、非 200 直接失败),
55
+ * 但"每一个"这个量词是错的 —— 留着它会让人以为"C 的响应只要 code 是 200 就安全"。
51
56
  */
52
57
  export function normalize(raw, envelope) {
53
58
  // 裸数组:ipcc.customfield.template.get 完全没有信封
59
+ // ⚠️ 形状 M 必须排除在外(CodeRabbit PR #66 第 4 轮):M 的契约是「载荷 = message
60
+ // 原文」,裸数组不是该契约的任何一种合法形态。若不排除,数组会在下面的 M 判定**之前**
61
+ // 被无条件当成功返回 —— 一次形态漂移被报成成功,调用方把数组当任务 key / 下载链接。
54
62
  if (Array.isArray(raw)) {
63
+ if (envelope === 'M') {
64
+ return { ok: false, code: 'unknown', payload: undefined,
65
+ messageText: '形状漂移:该接口应返回 {code, message} 信封(载荷在 message),实际是裸数组',
66
+ notFound: false };
67
+ }
55
68
  return { ok: true, code: '200', payload: raw, messageText: '', notFound: false };
56
69
  }
57
70
  if (typeof raw !== 'object' || raw === null) {
@@ -72,6 +85,40 @@ export function normalize(raw, envelope) {
72
85
  const code = String(o.code ?? 'unknown');
73
86
  const codeOk = code === '200';
74
87
  const messageText = typeof o.message === 'string' ? o.message : '';
88
+ // 形状 M:**成功载荷就是 message 原文**(纯文本,不是 JSON)。实测两处:
89
+ // `export.session` create → `{code:200, message:"<task key>"}`
90
+ // `export.session.check` check → 完成时 `{code:200, message:"<download link>"}`
91
+ // 设计稿 §7.5 逐字记载,同步流水线也按此实现(`pipeline.messageOf`)。
92
+ //
93
+ // ⚠️ 此前这两个接口被登记成形状 A(载荷在 data),而响应里**根本没有 data** ——
94
+ // 信封层落到末尾兜底:payload=undefined、`notFound:true`,stdout 里是
95
+ // `"data":null, "not_found":true, "warning":"接口返回成功但无数据"`,
96
+ // 而任务 key/下载链接(唯一有用的载荷)整条丢失。Agent 完成导出创建后拿不到 key,
97
+ // 还被明确告知"返回成功但无数据"—— 把一次成功描述成空操作。
98
+ //
99
+ // 判据:code 非 200 → 失败(message 是错误文本);message 缺失/空 → 失败(无载荷可用,
100
+ // 与形状 C 同理:不知道这是成功还是异常);否则 payload = message 原文。
101
+ // message 为空串**不**判 notFound —— 形状 M 的"空"是缺载荷,不是"查无此物"。
102
+ if (envelope === 'M') {
103
+ const nf = { notFound: false };
104
+ if (!codeOk)
105
+ return { ok: false, code, payload: undefined, messageText, ...nf };
106
+ // ⚠️ 判据必须作用在 **trim 后**的副本上(CodeRabbit PR #66):`' '` 是空载荷、
107
+ // `'OK '` 是占位符 —— 原样比对会把它们放行,下游拿它当 key/链接去下载。
108
+ // 返回的 payload 也用 trim 后的值(带空白的 key/链接必然用不了)。
109
+ const trimmed = messageText.trim();
110
+ if (!trimmed) {
111
+ return { ok: false, code, payload: undefined, messageText: '响应缺少 message', ...nf };
112
+ }
113
+ // 'OK' 是占位符:拿它当任务 key / 下载链接会让下游去下载 /openapi/export/session/OK。
114
+ // `x 校验`(流水线)与 `api call` 都必须把同一形态判为失败 —— 归一化层挡掉,
115
+ // 两边共用同一判据,不再各写一份。
116
+ if (trimmed === 'OK') {
117
+ return { ok: false, code, payload: undefined,
118
+ messageText: '响应 message 是占位符 `OK`(形态漂移),不是可用的载荷', ...nf };
119
+ }
120
+ return { ok: true, code, payload: trimmed, messageText, ...nf };
121
+ }
75
122
  // 形状 C:数据藏在 message 里的 JSON 字符串。
76
123
  // 解析成功 → 成功;解析失败 → **错误**(见上方说明),即便 code 是 200。
77
124
  if (envelope === 'C') {
@@ -120,8 +167,8 @@ export function normalize(raw, envelope) {
120
167
  }
121
168
  // 形状 A / D:数据在 data
122
169
  //
123
- // ⚠️ **但"data 为空 ⇒ not_found"这条规则只在 envelope 已实测时成立。**
124
- // envelope 为 null(未实测)的接口恰恰**全部是写接口**,而写接口的 `data` 语义
170
+ // ⚠️ **但"data 为空 ⇒ not_found"这条规则只在 envelope 已登记时成立。**
171
+ // envelope 为 null 的接口里,此前观测到的**全部是写接口**,而写接口的 `data` 语义
125
172
  // 与读接口相反 —— 设计稿 §5.4.1 的**文档依据**(这 5 个接口实测中刻意未调用):
126
173
  // · `addKnowledge` → `data` 是新 id(integer)
127
174
  // · `editKnowledge` / `editKnowledgeNoSimilars` / `editChannelAnswer` → `data` 是 `true`
@@ -133,8 +180,15 @@ export function normalize(raw, envelope) {
133
180
  // 而真相是**全部删掉了**。这是 §9.2 静默失败最危险的方向:它把一个已完成的
134
181
  // 破坏性操作描述成一次空操作。
135
182
  //
136
- // → 未实测的接口**不判 not_found**:注册表既然不知道这个接口的 `data` 语义,
137
- // 就不能假装知道。"空 data 是什么"这个问题,只有实测过才能回答。
183
+ // ⚠️ **2026-10-30 起 `envelope: null` 有两种含义**,不再等于"未经实测":
184
+ // ① 该接口的信封**从未实测**(写接口全部如此,`verified: false`);
185
+ // ② 实测过,但形状**不在 A/B/C/D 里**(`chat.queue.group.query` 的 staffInfo、
186
+ // `ipcc.customfield.template.get` 的裸数组)—— 两者都由更前面的结构分支接住,
187
+ // **根本走不到这里**,所以 null 对它们无害。
188
+ // 两种情况下这条 `data` 分支的判据都一样:**不判 not_found**。
189
+ //
190
+ // → 不知道 `data` 语义的接口**不判 not_found**:注册表既然不知道这个接口的
191
+ // `data` 语义,就不能假装知道。"空 data 是什么"这个问题,只有实测过才能回答。
138
192
  if ('data' in o) {
139
193
  return { ok: codeOk, code, payload: o.data, messageText,
140
194
  notFound: codeOk && envelope !== null && envelope !== undefined
@@ -146,7 +200,9 @@ export function normalize(raw, envelope) {
146
200
  // ⚠️ 空的 staffInfo 是"无人在线"的**正常**状态(24 个组里 15 个如此),不是 not_found
147
201
  return { ok: codeOk, code, payload: o.staffInfo, messageText, notFound: false };
148
202
  }
149
- // 宽松模式(envelope 为 undefined 或 null —— 该接口的信封未经实测):
203
+ // 宽松模式(envelope 为 undefined 或 null):该接口的信封形状未经登记 ——
204
+ // 可能是从未实测,也可能是实测确认形状不在 A/B/C/D 里(登记了非标形状的两个接口
205
+ // 由更前面的结构分支提前接住,走不到这里)。
150
206
  // 按设计稿 §9.0,此时唯一能做的就是试探 message 能否解析。
151
207
  // ⚠️ 这与形状 C 的严格语义不同:解析失败**不判错**,因为无从区分
152
208
  // "形状 C 的错误报文"与"staff.list 那种 message='OK' 的正常响应"。
@@ -173,15 +229,23 @@ export function normalize(raw, envelope) {
173
229
  }
174
230
  // 其余形状走到这里意味着"200 但无载荷"。
175
231
  //
176
- // ⚠️ **envelope 为 null(未实测)时与 data/result 两个分支取同一条规则:不判 not_found。**
232
+ // ⚠️ **envelope 为 undefined 或 null 时与 data/result 两个分支取同一条规则:不判 not_found。**
177
233
  // 设计稿 §9.0 的规则原文是"`code:200` 且无数据字段的,一律当作 not_found",但它同时
178
234
  // 写明这条规则"必须是**注册表查询**而非启发式判断"—— 它假定每个接口都登记了 `envelope`。
179
- // 在计划交付的 11 条骨架里那 5 个知识库写接口的 `envelope` 正是 `null`,生成脚本产出
180
- // 154 条时 `null` 只会更多。若这里写 `envelope !== 'D'`,`null !== 'D'` 为真,于是
235
+ // 骨架里那 5 个知识库写接口的 `envelope` 正是 `null`(未实测),生成脚本产出 154 条时
236
+ // `null` 只会更多。若这里写 `envelope !== 'D'`,`null !== 'D'` 为真,于是
181
237
  // **同一个未实测接口**会因为"载荷挂在 data 上还是完全缺席"得到相反的判定:
182
238
  // `{code:200,data:[]}` 走 data 分支判 false,`{code:200}` 走这里判 true。
183
239
  // 对未实测的写接口,`{code:200}` 无载荷恰恰可能就是"操作成功",判成 not_found 会把
184
240
  // 一次成功的写描述成"什么都没发生"—— 与 data 分支注释里那条最危险的静默失败同构。
241
+ //
242
+ // ⚠️ **2026-10-30 起 envelope:null 有第二种来源,同样依赖这条规则:**
243
+ // 实测过的接口若返回 `{code}`(无 data/result/message/staffInfo),说明该接口
244
+ // 的"成功但查无此物"与"纯确认"是**同一报文**,而 `normalize` 只收到一个 envelope
245
+ // 参数、不知道是哪个接口 —— 它无法替调用方分辨。这类接口(`msgAssociate` 的
246
+ // not-found 路径、`robot.transfer.config` 的正常空壳)靠注册表按接口登记
247
+ // `'D-nf'` / `'D'` 兑现。若某个实测接口没机会这样登记(形状是无结构分支的
248
+ // branch 提前接住),它的 notFound 取尾部兜底 —— 与 data/result 分支同规则。
185
249
  // → 与 data/result 对齐:不知道就不断言。'D' / 'D-nf' 这些**已登记**的取值照旧区分。
186
250
  //
187
251
  // ⚠️ 形状 D 这一族里**语义相反的两个接口共用同一个报文**,必须分开登记: