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
@@ -11,10 +11,20 @@
11
11
  `--limit` 或缩小时间窗口重查,不要拿样本当全量。
12
12
  - `warnings`:非空必须逐条读。它们点名「窗口内部有缺口」「区间天数不足」这类**静默失败**;
13
13
  忽略 warnings 的 Agent 会把残缺数据当事实汇报。
14
- - `masked` / `masked_columns` / `mask_warnings`:输出默认脱敏;`mask_warnings` 非空说明
15
- 脱敏可能不完整,含敏感列的结论要额外小心。
16
- - `resolved_range` / `data_coverage`:命令实际生效的时间区间、本地数据的实际覆盖范围。
17
- 报告结论时带上这两个区间,让人类知道你算的是哪段数据。
14
+ - `masked` / `masked_columns` / `mask_warnings`:输出默认脱敏;`mask_warnings` 非空时**逐条读**——
15
+ 它装两类事:**脱敏缺口**(敏感值没被打码)与**脱敏对结果的副作用**(`GROUP BY`/`DISTINCT`
16
+ 把不同原值压成同一个脱敏值,分组与计数会失真,别名分组也照样报警;非敏感列按手机号形态
17
+ 被误改)。含敏感列的结论要额外小心。两个**字面陷阱**:`masked: true` 只表示
18
+ 脱敏开关开着,**不代表有值被改写**(那看 `masked_columns`,为空是常态);`--no-mask`
19
+ 时 `mask_warnings` **恒为空**——空不等于脱敏完整,那是「根本没脱敏」,风险警告在
20
+ `warnings` 里。
21
+ - `resolved_range` / `data_coverage`:前者是**过滤边界**(不是有数据的范围),后者是
22
+ 时间列在过滤范围内的 **MIN/MAX**。⚠️ `data_coverage` 只有首尾两点、**看不见内部缺口**
23
+ ——7 天里只有第 1、7 天有数据时它照样报满区间。`iso-day` 表在**给了 `--since`/`--until`
24
+ 时**另有 `warnings` 兜底(「区间内应有 N 个自然日,实际只有 M 个有数据」),**没有时间
25
+ 过滤时这条兜底不触发**;`iso-instant` 与 `epoch-ms` 表任何情况下都没有兜底,要核对内部
26
+ 覆盖得自己按自然日 `GROUP BY` 数行。
27
+ 报告结论时带上这两个区间,让人类知道你算的是哪段数据。逐键释义见输出的 `meta.field_notes`。
18
28
  - `--sql` 通道不判定区间与覆盖:`resolved_range` 与 `data_coverage` **恒为 null**——实际
19
29
  区间以你写的 SQL 过滤为准,报告时自己写清。
20
30
 
@@ -25,7 +35,39 @@
25
35
  1. **窗口写错**:相对时间按上海时区解析,而 Agent 常跑在 UTC 容器里——「昨天」可能不是
26
36
  人类说的昨天,且不会报任何错。
27
37
  2. **本地还没同步到这段**:用 `qiyu sync status` 看水位与缺口;`qiyu sync verify` 可以核对
28
- 本地与远端的一致性(发现漂移时以非零退出码明示)。
38
+ 本地与远端的一致性——但**只有快照任务**与远端行数核对(`expected_from_api`),windowed
39
+ 任务不请求远端、只核对本地行数与同步状态记录,**drift 为空不代表与远端一致**(发现
40
+ 漂移时以非零退出码明示)。缺口先看 `gaps[].reason`:
41
+ `rate_limit_local` 等到 `detail` 里的时刻再重跑,`fetch_failed`/`write_failed`/
42
+ `count_mismatch` 重跑 `sync run` 覆盖该区间;`knowledge_row_malformed`/
43
+ `staff_id_list_malformed`/`row_missing_key`/`filter_matched_no_staff`/`export_*`
44
+ 是**成功窗上的提示**(不等于同步失败)。⚠️ 「提示」不等于「数据没缺」,两档分开读:
45
+ `knowledge_row_malformed`/`staff_id_list_malformed`/`row_missing_key` 描述的行
46
+ **确实没落库**(`detail` 是丢失规模,必须核对上游形态;`row_missing_key` 的行连
47
+ `fetched`/`written` 都不计,窗口仍可能 `complete`);`filter_matched_no_staff`/
48
+ `export_fixture_unreported`/`export_window_mismatch` **未必缺数据**(可能只是筛选
49
+ 没命中、或空窗本来就空)。不确定就读 `detail`。
50
+ - ⚠️ **`range_status` 的两个取值字面都在撒谎**(逐值释义见输出的 `meta.field_notes`):
51
+ `complete` 只表示「水位推进过」——中窗失败时它照样是 `complete`,**不是**「全窗口成功」;
52
+ `pending` 只表示「最近一次运行没推进水位」——首窗失败时后续成功窗照常落库,**不是**
53
+ 「库里没数据」;先成功一轮再跑一轮首窗失败同样回到 `pending`(watermark 保留上一轮的
54
+ 值),所以也**不是**「从未同步过」;更**不是**「正在同步」。判数据完整不要只看
55
+ `range_status`,也不要只看 `gaps`——
56
+ **空 `gaps` 不等于完整**(`windows.skipped > 0` 时可能没有缺口记录、但请求区间仍有
57
+ 未覆盖段)。要同时看覆盖范围(`sync status` 的 `resolved_range`、以及 `sync run` 的
58
+ `windows.skipped` —— status 与 verify 都不输出后者)与历史缺口的新鲜度。
59
+ - ⚠️ **`gaps` 是历史记录,不等于「当前仍缺」**:旧记录与新记录的 `reason` 相同,按
60
+ `reason` 分不出新旧;`range` 也只能说明「相关」——换边界重跑后数据可能已补齐,而旧
61
+ 缺口的 `range` 仍与你评估的区间重叠。**没有一次覆盖核对就不能确认新鲜度**:写
62
+ 「该区间有历史缺口记录,新鲜度未确认」,不要直接报成当前故障。
63
+ - ⚠️ `sync run` 的 `status: "partial"` **也覆盖「一行都没落」的全窗失败**:两个字段分开
64
+ 读——`windows.succeeded` 是成功窗数(空窗也算成功),`rows.written` 才是落库行数。
65
+ - ⚠️ **`sync verify` 的 `drift` 为空 / 退出码 0 不能当完整性证据**:对 windowed 任务
66
+ 它只核对同步状态记录(实测中窗失败的库同样给 `drift: []` + 退出码 0),快照任务另有
67
+ 上游行数核对。windowed 的完整性要另行核对两处:`sync status` 的 `gaps` 与
68
+ `resolved_range`,以及 `sync run` 的 `windows.skipped`(status/verify 都不输出它)。
69
+ - ⚠️ `locked: true` 是**残留的写者章**(上一轮被强杀),不是「正在同步中」——真持锁的
70
+ 写者会让 `sync status` 先退避等待,等到后读到的是那一轮的结果。重跑 `sync run` 即可。
29
71
  3. **真的没有数据**。
30
72
 
31
73
  报告 0 行时写「查询窗口 X 到 Y 内 0 行」,并说明排除了哪几种成因;不要写「系统里没有」。
@@ -34,6 +76,16 @@
34
76
 
35
77
  - **绝不猜单位**——百分比还是绝对值、按日还是按小时,猜错数字全错。报表字段的声明单位、
36
78
  本地观测分布、哨兵值由 `qiyu stats fields <报表表>` 给出。
79
+ - **`declared.<字段>.unit` 的每个取值怎么用,看输出的 `meta.field_notes`**(那里逐值给了
80
+ 释义与动作):`ms` 是毫秒;`unknown` 是「判不出单位」而不是「没有单位」(如实写
81
+ 「单位未知」,不要猜)。`ratio` 的 0–1 量纲**只有 `assignedRatio` 经设计稿实测**——
82
+ 其余 `ratio` 是按名字推断的(`source: name-suffix`,**推断不是实测**)。`observed` 的
83
+ `min`/`max` 只能核对一致性、**不是量纲证据**:全都落在 0–1 时,它与「0–1 小数」和
84
+ 「数值恰好都 <1% 的百分数」都相容。量纲不明确就**报告原值并标注不确定**,不要自行
85
+ 换算成百分比。
86
+ `source` 就告诉你这条声明是实测(`design-doc`)还是命名推断。
87
+ - `declared.<字段>.higher_is_better` **恒为 null**——没有任何上游依据,不要据此判断指标
88
+ 好坏方向,也不要一直等它变成 true/false。
37
89
  - 哨兵值会混进聚合(例如「无处理人」用特殊编号表示,不排除就会凭空多出一个「员工」)。
38
90
  先看观测分布,再决定过滤条件。
39
91
  - 声明了但本地观测不到取值的字段,报告时写「未观测到取值」——声明是契约,不是事实。
@@ -12,11 +12,15 @@
12
12
 
13
13
  1. **缺失时问人类**。要「机器人编号清单」,不要自己编造、不要按数字区间试探、
14
14
  不要把会话里见过的编号当全量。
15
- 2. 人类把编号写进配置文件(两种写法都认):
16
- - `store.options.knowledgeRobotIds`(正整数数组)—— **优先**;
15
+ 2. 人类把编号写进配置文件(两种写法都认,都在 `profiles.<name>` 之下):
16
+ - `profiles.<name>.store.options.knowledgeRobotIds`(正整数数组)—— **优先**;
17
17
  - `profiles.<name>.robots`(`{"1000001":"机器人A"}` 映射,键是编号、值是显示名)——
18
18
  `knowledgeRobotIds` 缺席时的兜底。
19
19
 
20
+ ⚠️ **`knowledgeRobotIds` 在 `store` 块的 `options` 里面,比 `robots` 低两层** —— 两处写混
21
+ (例如把 `knowledgeRobotIds` 直接放在 `profiles.<name>` 下)会被 CLI 以
22
+ 「配置文件未知键」拒绝(退出码 2)。转述给人类时请给**完整路径**,不要只说键名。
23
+
20
24
  `qiyu sync run` 在条目数据集为空(分类树没有可依据的编号来源)时会改用这些编号逐机器人
21
25
  拉取分类树;条目数据非空时以条目数据为准。写错(非正整数)会被 CLI 以用法错误拒绝并点名
22
26
  非法元素。`qiyu auth whoami` 的 `data.robots` 会如实列出配置里的映射(未校验有效性)。
@@ -8,8 +8,8 @@
8
8
  // 一律委托 core 层 —— 这样 auth 与 store 看到的「未知键」「JSON 畸形」「权限过宽」
9
9
  // 是同一句话,不会出现两套口径。
10
10
  import { homedir } from 'node:os';
11
- import { dirname, join, isAbsolute } from 'node:path';
12
- import { configPathFor, loadConfigFile, checkPermissions, configHasCredentials } from '../core/config.js';
11
+ import { join, isAbsolute } from 'node:path';
12
+ import { configPathFor, loadConfigFile, checkPermissions, configHasCredentials, insecureConfigError, nonEmptyValue, resolveProfileName } from '../core/config.js';
13
13
  export const DEFAULTS = {
14
14
  relPath: join('.qiyu', 'duckdb', 'qiyu.duckdb'),
15
15
  backend: 'duckdb',
@@ -30,6 +30,19 @@ function assertKnownKeys(obj, known, prefix) {
30
30
  function expandHome(p, home) {
31
31
  return p === '~' ? home : p.startsWith('~/') ? join(home, p.slice(2)) : p;
32
32
  }
33
+ /**
34
+ * 取「命令行 > 环境变量 > 配置文件 > 内置默认」的某一层,**同时返回来源**(spec §3.2)。
35
+ *
36
+ * 为什么要来源:报错得说清是哪一层坏的(见下面的空白守卫)。
37
+ * ⚠️ 环境变量层的空串已由 `nonEmptyValue`(core/config.ts,全仓唯一实现)归一成
38
+ * undefined —— 传进来的 `env.QIYU_*` 必须先过它,否则 `''` 会遮蔽配置文件里的真值。
39
+ */
40
+ function pickLayer(layers, fallback) {
41
+ for (const l of layers)
42
+ if (l.value !== undefined)
43
+ return { value: l.value, source: l.source };
44
+ return { value: fallback, source: '内置默认' };
45
+ }
33
46
  function assertPositiveInt(v, key, max) {
34
47
  if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
35
48
  throw new Error(`配置文件 ${key} 必须是正整数,实际为 ${JSON.stringify(v)}`);
@@ -75,12 +88,12 @@ export function resolveStoreConfig(opts = {}) {
75
88
  onWarn: (m) => process.stderr.write(`${m}\n`),
76
89
  });
77
90
  if (!perm.ok) {
78
- // 拒绝路径抛普通 Error(无 kind)→ 调用方按用法错误处理。
79
- // ⚠️ 文案必须点名**要执行的动作**,否则用户只知道自己错了。
80
- const dir = dirname(configPath);
81
- throw new Error(perm.reason === 'file'
82
- ? `配置文件 ${configPath} 含凭证但权限过宽(group/other 可访问),已拒绝读取 —— 请执行 chmod 600 ${configPath}`
83
- : `配置目录 ${dir} 权限过宽(group/other 可写,文件可被整体替换)且配置含凭证,已拒绝读取 —— 请执行 chmod 700 ${dir}`);
91
+ // ⚠️ 必须抛**带 kind** 的错误(2026-10-26 实测修):这里此前抛普通 Error,而各命令
92
+ // catch 一律 `usageFail(...)` —— 于是「配置含凭证且权限过宽」在 store/db/query/stats/
93
+ // sync 上被降级成退出码 2 + `kind: usage`("改参数重来")且 hint 丢失,只有
94
+ // auth/api 那条路径如实给出退出码 1 + `kind: config_insecure`。同一个危险状态两种
95
+ // 行为,Agent 会去改参数而真正的动作是 chmod。统一由 core 的构造点产出。
96
+ throw insecureConfigError(configPath, perm.reason);
84
97
  }
85
98
  }
86
99
  const profiles = file.profiles;
@@ -96,23 +109,80 @@ export function resolveStoreConfig(opts = {}) {
96
109
  throw new Error(`配置文件 profiles.${name}.store.options 必须是对象`);
97
110
  }
98
111
  }
99
- const profileName = flags.profile ?? env.QIYU_PROFILE ?? file.defaultProfile ?? 'default';
100
- const prof = profiles[profileName] ?? {};
112
+ // ⚠️ 点名的 profile 必须存在(2026-10-27 实测修):此前 `profiles[profileName] ?? {}`
113
+ // 把「profile 拼错」和「profile 存在但没配 store」合并成同一个静默回落 ——
114
+ // `--profile prodd`(少一个字母)会读到**默认库**并返回 `ok:true` 与其中的数据,
115
+ // Agent 看不出自己读错了库;`store init --profile prodd` 还会在默认路径上创建
116
+ // 一个用户从未配置的库。与全仓「未知名字必须拒绝并给候选」一致(未知表/未知任务/
117
+ // 未知接口 id/未知后端/未知配置键),也与 §3.3「拼错的配置键静默无效等于让用户
118
+ // 以为设置生效了」同一条理由。
119
+ //
120
+ // 边界(刻意保留的回落):
121
+ // · 配置文件不存在 → `loadConfigFile` 给出空 file,`profiles` 为空,
122
+ // 下面的 `available.length > 0` 直接放行(首次运行)—— 所以不需要再判
123
+ // `configExists`(实测删掉该条件全绿:它与长度判据完全冗余,留着是死条件);
124
+ // · 配置文件存在但 `profiles` 为空 → 同上(空配置没有可选项);
125
+ // · profile 存在但缺 store 块 → 走默认(tests/store/config.test.ts 钉着);
126
+ // · 未点名任何 profile(连 defaultProfile 都没有)→ 用内置 `default`,不查。
127
+ // ⚠️ 空串口径与 auth 侧逐字一致:`--profile ''` 是 usage 错误(`auth login` 的
128
+ // normalizeProfile 同样报「--profile 不能为空」);`QIYU_PROFILE=`(变量未设的
129
+ // 典型形态)与 `defaultProfile: ''` 当未设置 —— 档名解析走 core 的
130
+ // `resolveProfileName`(唯一实现),凭证侧与 store 侧不得对同一份配置给出两种解读。
131
+ if (flags.profile !== undefined && flags.profile.trim() === '') {
132
+ throw new Error('--profile 不能为空');
133
+ }
134
+ const namedProfile = resolveProfileName({
135
+ flag: flags.profile, envProfile: env.QIYU_PROFILE, defaultProfile: file.defaultProfile,
136
+ });
137
+ const profileName = namedProfile.name;
138
+ if (namedProfile.source !== undefined) {
139
+ const available = Object.keys(profiles);
140
+ // ⚠️ own-property 判据(2026-10-27,CodeRabbit):`profiles[x] === undefined` 会被
141
+ // 原型链绕过 —— `--profile constructor` / `toString` 命中 `Object.prototype` 上的
142
+ // 继承属性,守卫放行后回落默认库。parseConfig 已改用 null 原型对象,这里是第二道锁
143
+ // (resolveStoreConfig 的 profiles 只来自 parseConfig,但判据本身不该依赖来源)。
144
+ if (available.length > 0 && !Object.hasOwn(profiles, profileName)) {
145
+ throw new Error(`配置文件里没有 profile ${JSON.stringify(profileName)}(来自 ${namedProfile.source};` +
146
+ `现有:${available.join('、')})—— 检查拼写,或先在配置文件里加上这个 profile`);
147
+ }
148
+ }
149
+ const prof = Object.hasOwn(profiles, profileName) ? profiles[profileName] : {};
101
150
  const storeBlock = (prof.store ?? {});
102
- const rawBackend = flags.backend ?? env.QIYU_STORE_BACKEND ?? storeBlock.backend ?? DEFAULTS.backend;
151
+ // backend 的类型守卫与 path 同款(此前只有 path 有):配置写 123 / {} 时,
152
+ // `未知后端:[object Object]。目前仅支持 duckdb` 既不点名键路径、也读不出坏了什么。
153
+ if (storeBlock.backend !== undefined && typeof storeBlock.backend !== 'string') {
154
+ throw new Error(`配置文件 profiles.${profileName}.store.backend 必须是字符串`);
155
+ }
156
+ const backend = pickLayer([
157
+ { source: '--backend', value: flags.backend },
158
+ { source: 'QIYU_STORE_BACKEND', value: nonEmptyValue(env.QIYU_STORE_BACKEND) },
159
+ { source: `配置文件 profiles.${profileName}.store.backend`, value: storeBlock.backend },
160
+ ], DEFAULTS.backend);
161
+ const rawBackend = backend.value;
103
162
  if (rawBackend !== 'duckdb') {
104
- throw new Error(`未知后端:${rawBackend}。目前仅支持 duckdb`);
163
+ throw new Error(`未知后端:${JSON.stringify(rawBackend)}(来自 ${backend.source})。目前仅支持 duckdb`);
105
164
  }
106
165
  // ⚠️ path 类型守卫(K 组 M1):配置写数字/对象时,expandHome 会对非字符串调
107
166
  // startsWith 抛裸英文 TypeError,且不点名键路径 —— 违反 fail-closed 点名键路径约定。
108
167
  if (storeBlock.path !== undefined && typeof storeBlock.path !== 'string') {
109
168
  throw new Error(`配置文件 profiles.${profileName}.store.path 必须是字符串`);
110
169
  }
111
- const rawPath = flags.db ?? env.QIYU_DB_PATH ?? storeBlock.path ?? DEFAULTS.relPath;
112
- // ⚠️ 空串守卫(K 组 M4):`--db ""`(脚本里变量未设的典型形态)会穿过所有前置检查
113
- // 直达 DuckDB,产出难懂的底层错误。空串不是合法路径,usage 拒绝。
170
+ const path = pickLayer([
171
+ { source: '--db', value: flags.db },
172
+ { source: 'QIYU_DB_PATH', value: nonEmptyValue(env.QIYU_DB_PATH) },
173
+ { source: `配置文件 profiles.${profileName}.store.path`, value: storeBlock.path },
174
+ ], DEFAULTS.relPath);
175
+ const rawPath = path.value;
176
+ // ⚠️ 空串守卫(K 组 M4):空白值会穿过所有前置检查直达 DuckDB,产出难懂的底层错误。
177
+ // 空串不是合法路径,usage 拒绝。
178
+ // ⚠️ 文案点名**真正给了空白值的那一层**(2026-10-29 实测修):此前写死
179
+ // 「--db / QIYU_DB_PATH / store.path 均为空」—— 而实测 store.path 明明配了值,
180
+ // 是被 `QIYU_DB_PATH=` 遮蔽的(报错把三层一起指控,Agent 会去改没坏的那层)。
181
+ // ⚠️ 环境变量的**空串**到不了这里(`nonEmptyValue` 已视为未设置);能到这里的是
182
+ // 显式 flag 的空白值、空白串环境变量(`' '`)、以及配置文件里的空白 path。
114
183
  if (rawPath.trim() === '') {
115
- throw new Error('数据库路径不能为空(--db / QIYU_DB_PATH / store.path 均为空)');
184
+ throw new Error(`数据库路径不能为空:${path.source} 给了空白值 ${JSON.stringify(rawPath)}。`
185
+ + '空串不是合法路径 —— 想回落到下一层:别传这个 flag / unset 这个变量 / 删掉这个配置键');
116
186
  }
117
187
  const readOnlyRetryMs = storeBlock.readOnlyRetryMs === undefined
118
188
  ? DEFAULTS.readOnlyRetryMs
@@ -121,6 +191,11 @@ export function resolveStoreConfig(opts = {}) {
121
191
  ? DEFAULTS.batchSize
122
192
  : assertPositiveInt(storeBlock.batchSize, `profiles.${profileName}.store.batchSize`, 100_000);
123
193
  // 相对路径(内置默认 relPath)按 home 解析;~ 前缀展开为 home(M-6)
194
+ // ⚠️ 刻意不按 cwd 解析(2026-11-07 审查):`--db` 的值会被固化进**调度条目**
195
+ //(sync install),而调度任务的 cwd 不一定是安装时的 cwd;相对 HOME 是唯一在
196
+ // 交互与调度两侧稳定一致的基准。代价是与其他命令「相对路径按 cwd」的直觉相反 ——
197
+ // 所以各命令的 --help 必须写明这一点(`DB_PATH_FLAG_HELP`),否则 Agent 会以为
198
+ // `--db data/q.db` 指向当前目录,实际建到了 ~/data/q.db。
124
199
  const expanded = expandHome(rawPath, home);
125
200
  const finalPath = isAbsolute(expanded) ? expanded : join(home, expanded);
126
201
  return {
@@ -133,5 +208,6 @@ export function resolveStoreConfig(opts = {}) {
133
208
  },
134
209
  configPath,
135
210
  configExists,
211
+ ...(namedProfile.source !== undefined ? { profileFlag: profileName } : {}),
136
212
  };
137
213
  }
@@ -81,7 +81,7 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
81
81
  const err = new Error(`数据库被写进程占用(等待 ${cfg.readOnlyRetryMs}ms 后超时):${cfg.path}`);
82
82
  err.kind = 'store_locked';
83
83
  err.retryable = true;
84
- err.hint = '请稍后重试;等待上限可经配置文件 readOnlyRetryMs(默认 30000 毫秒)调整,或用 --db 指向其他数据库文件';
84
+ err.hint = '请稍后重试;等待上限可经配置文件 profiles.<name>.store.readOnlyRetryMs(默认 30000 毫秒)调整,或用 --db 指向其他数据库文件';
85
85
  throw err;
86
86
  }
87
87
  throw e;
@@ -96,10 +96,15 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
96
96
  }
97
97
  catch (e) {
98
98
  if (isLockError(e)) {
99
- const err = new Error(`数据库被写进程占用:${cfg.path}`);
99
+ // ⚠️ 写者撞锁时**持有者不一定是写进程**(2026-11-05 审查实测):DuckDB 是
100
+ // 「写者独占 / 读者共享」——一个以 READ_ONLY 打开的进程同样会挡住写者。
101
+ // 旧文案「数据库被写进程占用 / 另一个进程持有写锁」把只读持有者说成了写者,
102
+ // Agent 会按错误的原因去等一个并不存在的同步任务。持有者身份不在这条错误里
103
+ // 猜测,只如实说「被其他进程占用」并给出可执行的排查动作。
104
+ const err = new Error(`数据库被其他进程占用:${cfg.path}`);
100
105
  err.kind = 'store_locked';
101
106
  err.retryable = true;
102
- err.hint = '另一个进程持有数据库写锁。请等该进程退出后重试';
107
+ err.hint = '另一个进程正持有该数据库的锁(持有者不一定是写进程:只读会话同样会挡住写者)。请等它退出后重试;可用 lsof 该库文件查看持库进程';
103
108
  throw err;
104
109
  }
105
110
  throw e;
@@ -157,6 +162,47 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
157
162
  const nonKey = cols.filter((x) => !t.primaryKey.includes(x));
158
163
  const setClause = nonKey.map((x) => `"${x}" = excluded."${x}"`).join(', ');
159
164
  const pk = t.primaryKey.map((x) => `"${x}"`).join(', ');
165
+ // ⚠️ 同批重复主键必须先收敛(2026-11-04 修):DuckDB 的多行 `INSERT ... ON CONFLICT
166
+ // DO UPDATE` 在同一语句里遇到重复键时**保留第一条**(实测:两条 id=1 的行写入后是
167
+ // 第一条的值),而分批写入(batchSize=1)时后一条会覆盖前一条 —— 同一批数据的结果
168
+ // 取决于 batchSize 配置。这里统一成「后出现的行获胜」(与逐条写入的直觉一致),
169
+ // 且只发一条 INSERT,结果与 batchSize 无关。
170
+ // ⚠️ 键必须按**列的存储类型**归一化,不能按 JS 的 typeof(CodeRabbit PR #65):
171
+ // VARCHAR 主键列里 number 1 与 string '1' 存进去是同一个值;若按 typeof 区分,
172
+ // 它们在同一批里不会合并(DuckDB 保留第一条),而 batchSize=1 时后者获胜 ——
173
+ // 又变回 batchSize 相关。数值列(今天只有 schema_version.version 是 INTEGER)
174
+ // 用 BigInt 归一化整数串:既不让 '01' 与 1 分成两键,也不因 Number 丢精度把
175
+ // 两个不同的大整数误合成一个。非整数形态(病态输入)退回 Number。
176
+ const pkTypes = t.primaryKey.map((c) => t.columns.find((x) => x.name === c).type);
177
+ const isNumeric = (ty) => /^(TINYINT|SMALLINT|INTEGER|BIGINT|HUGEINT|UTINYINT|USMALLINT|UINTEGER|UBIGINT|FLOAT|REAL|DOUBLE|DECIMAL)/i.test(ty);
178
+ const normKey = (v, ty) => {
179
+ const raw = typeof v === 'bigint' ? v.toString() : String(v);
180
+ if (!isNumeric(ty))
181
+ return raw;
182
+ const t = raw.trim();
183
+ if (/^[+-]?\d+$/.test(t)) {
184
+ try {
185
+ return BigInt(t).toString();
186
+ }
187
+ catch { /* 超出 BigInt 范围,退回 Number */ }
188
+ }
189
+ return String(Number(t));
190
+ };
191
+ const seen = new Map();
192
+ const uniq = [];
193
+ for (const r of rows) {
194
+ // ⚠️ 用 JSON.stringify 序列化元组,不用分隔符 join(CodeRabbit PR #65):
195
+ // 多列 VARCHAR 主键时 delimiter 区分不了复合列自身的值(如 `as:b,c` 与
196
+ // `a,bs:c` 撞 key)。`JSON.stringify` 的换码天然无歧义。
197
+ const k = JSON.stringify(t.primaryKey.map((c, idx) => normKey(r[c], pkTypes[idx])));
198
+ const at = seen.get(k);
199
+ if (at === undefined) {
200
+ seen.set(k, uniq.length);
201
+ uniq.push(r);
202
+ }
203
+ else
204
+ uniq[at] = r;
205
+ }
160
206
  let written = 0;
161
207
  // ⚠️ 切批规则(M2 修,与 spec §5.3 对齐):**batchSize 是首选切批尺寸**,
162
208
  // 65000 参数硬顶无条件兜底 —— 实际行数 = min(batchSize, floor(65000/cols))。
@@ -166,8 +212,8 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
166
212
  // 65000 是保守值:实测该版本上限 ≥70000,勿据此放大(Q 组 Q-低-1)。
167
213
  const hardCap = Math.max(1, Math.floor(65000 / cols.length));
168
214
  const rowsPerStmt = Math.max(1, Math.min(cfg.batchSize, hardCap));
169
- for (let i = 0; i < rows.length; i += rowsPerStmt) {
170
- const batch = rows.slice(i, i + rowsPerStmt);
215
+ for (let i = 0; i < uniq.length; i += rowsPerStmt) {
216
+ const batch = uniq.slice(i, i + rowsPerStmt);
171
217
  const placeholders = batch.map(() => `(${cols.map(() => '?').join(', ')})`).join(', ');
172
218
  const params = batch.flatMap((r) => cols.map((k) => r[k] ?? null));
173
219
  await store.execSql(`INSERT INTO "${t.name}" (${quoted}) VALUES ${placeholders} ON CONFLICT (${pk}) DO UPDATE SET ${setClause}`, params);
@@ -1,19 +1,107 @@
1
1
  // src/store/retry.ts
2
2
  // ⚠️ 曲线是**固定间隔**(实测 2.6s/13 次成功 ≈ 200ms 间隔,spec §5.2)——
3
3
  // 不是指数:指数曲线在剩余预算不足时会大幅越过 maxMs。
4
- /** 锁冲突的识别规则(spec §5.2 定死):message 含 `Conflicting lock`。 */
4
+ /**
5
+ * 锁冲突的识别:**模板**匹配,不是子串搜索。
6
+ *
7
+ * 真实报文(跨进程真持锁,@duckdb/node-api 1.5.6-r.1)。**两种平台形态**(都逐字实测):
8
+ * · macOS:`IO Error: Could not set lock on file "<路径>": Conflicting lock is held in
9
+ * /Users/x/.nvm/…/bin/node (PID 83991) by user x. See also https://…`
10
+ * · Linux:`… Conflicting lock is held in /opt/hostedtoolcache/node/24.22.1/x64/bin/node
11
+ * (PID 4894). See also https://…` —— **没有 ` by user ` 那段**。
12
+ * 首版判据锚了三段(含 ` by user `),那是**只在本机探针过**的产物:CI 立刻在
13
+ * Node 20.12/22/24 上全红(同一个用例在我这里是绿的)。教训与「采样源按平台核对」同族 ——
14
+ * 探针跑在哪个平台,判据就只对那个平台成立。现只锚两段跨平台实测都有的骨架。
15
+ *
16
+ * ⚠️⚠️ **不能**只搜 `Conflicting lock` 子串(2026-11-01 实测,形态「报文里嵌了用户给的
17
+ * 路径」):DuckDB 的**其它**报文同样把库路径原文嵌进去 ——
18
+ * `IO Error: The file "/tmp/Conflicting lock/q.db" exists, but it is not a valid
19
+ * DuckDB database file!`(路径里恰好含这两个词)。子串判于是把**非 DuckDB 文件**
20
+ * 判成撞锁:`db tables` / `store status` 会**白白退避 30 秒**再报「数据库被写进程占用」,
21
+ * `retryable: true` 还把 Agent 引向「稍后重试」—— 而真相是那个路径根本不是数据库文件,
22
+ * 重试一万次也一样。实测:`db tables --db '/tmp/qreview/Conflicting lock/q.db'` 耗时
23
+ * 30.1s、`kind: store_locked`;同一份内容放在不含该词的路径上 0.4s 就给出正确的
24
+ * `store_not_initialized`。
25
+ *
26
+ * 判据锚 DuckDB 自己的**模板骨架**:句首 `IO Error: Could not set lock on file "<路径>": `
27
+ * 与紧随的 `Conflicting lock is held in `。两段都不在路径里,第二种报文命中不了
28
+ *(`not a valid DuckDB database file` 那句句首是 `The file `)。
29
+ * ⚠️ 边界如实记录:路径由用户给出且会被原文嵌入,理论上可以构造一个路径让这句看起来
30
+ * 也像别的报文;但那要求整条报文**以** `IO Error: Could not set lock on file "` 开头,
31
+ * 而只有锁报文会这样开头 —— 放宽的代价(上面那 30 秒假锁 + 假 retryable)则是实测发生的。
32
+ *
33
+ * 与 spec §5.2 原文「message 含 `Conflicting lock`」的偏离是**有意**的:那句话写于
34
+ * 判据只有一处消费点、且假设报文只可能是锁报文的时候。
35
+ */
5
36
  export function isLockError(e) {
6
37
  const msg = e instanceof Error ? e.message : String(e);
7
- return msg.includes('Conflicting lock');
38
+ return /^IO Error: Could not set lock on file "[\s\S]*": Conflicting lock is held in /i.test(msg);
8
39
  }
9
- /** 识别 ERR_MODULE_NOT_FOUND 并取出缺失的 specifier(spec §5.1 的二分规则)。 */
40
+ /**
41
+ * 识别「模块找不到」并取出缺失的 specifier(spec §5.1 的二分规则)。
42
+ *
43
+ * ⚠️ **两种错误码都要认**(2026-10-31 实测修):此前只认 `ERR_MODULE_NOT_FOUND`,
44
+ * 而那只可能在 **ESM 解析**阶段出现 —— 能命中它的 specifier 恒是 `@duckdb/node-api`
45
+ * 本身(整个包不装时)。**平台 binding 缺失**是另一条路径:`@duckdb/node-bindings`
46
+ * 用的是 **CJS `require`**(`duckdb.js` 里 `require('@duckdb/node-bindings-<平台>/duckdb.node')`),
47
+ * 抛出的 `e.code` 是 **`MODULE_NOT_FOUND`**(无 `ERR_` 前缀)。实测(删掉平台包后真跑):
48
+ * · `code = "MODULE_NOT_FOUND"`
49
+ * · `msg = "Cannot find module '@duckdb/node-bindings-darwin-x64/duckdb.node'"`
50
+ * 只认 ESM 码时这条一路返回 null → `depError` 的二分退化成单一分支,**「当前平台无预编译包」
51
+ * 那句 hint 在生产上从未被执行过**,Agent 拿到的是「未安装 DuckDB 依赖,请 npm install
52
+ * @duckdb/node-api」—— 而 `@duckdb/node-api` **本来就装着**(缺的是它的平台子包),
53
+ * 照 hint 重装修不好。这正是该分支存在的唯一理由(optionalDependency 在不支持的平台漏装)。
54
+ *
55
+ * 报文两种形态都覆盖:ESM 是 `Cannot find package '…'`、CJS 是 `Cannot find module '…'`
56
+ * (注意 binding 那条的 specifier 带 `/duckdb.node` 后缀,`startsWith('@duckdb/node-bindings')`
57
+ * 仍然成立)。
58
+ */
10
59
  export function isModuleNotFound(e) {
11
60
  const err = e;
12
- if (err?.code !== 'ERR_MODULE_NOT_FOUND')
61
+ if (err?.code !== 'ERR_MODULE_NOT_FOUND' && err?.code !== 'MODULE_NOT_FOUND')
13
62
  return null;
14
63
  const m = /Cannot find (?:package|module) '([^']+)'/.exec(err.message ?? '');
15
64
  return { missing: m?.[1] ?? '' };
16
65
  }
66
+ /** 「不是 DuckDB 数据库文件」的 hint(单一文案,store/query 共用)。 */
67
+ export const NOT_DUCKDB_HINT = '该路径已存在且不是 DuckDB 数据库,请换 --db 路径';
68
+ /**
69
+ * 「权限不足」的 hint(单一文案,store/query 共用)。
70
+ * ⚠️ 保持**读写中性**:`status`/`query` 是只读命令,说「写权限」会把只读者引向 `store init`。
71
+ */
72
+ export const PERMISSION_HINT = '请检查路径与所在目录的读写权限(磁盘只读也会导致无法打开)';
73
+ /**
74
+ * 「文件已损坏」的 hint(单一文案,store/query/sync 共用)。
75
+ *
76
+ * ⚠️ 2026-11-05 审查修:此前「截断 / 页校验和不对」两类报文既不匹配权限、也不匹配
77
+ * 「非 DuckDB 文件」,落进各命令自己的兜底 —— `store status` 说「数据库执行期错误,
78
+ * 请用 store status 检查」(拿自己查自己),`query` 说「请确认文件存在且由本 CLI 创建
79
+ * (store init)」—— 而对已损坏的文件原地跑 `store init` 打开同样失败,是条死路。
80
+ * hint 必须先给备份(文件里是用户已同步的数据),再给可执行的恢复路径(新路径重建)。
81
+ */
82
+ export const CORRUPT_HINT = '该文件已损坏(写入中断、磁盘写满、复制不完整都会造成),原地跑 store init 修不好,查询也会失败。请先备份该文件留档,再用 --db 指向一个新路径跑 store init 重建 —— 本地库只是缓存,之后带同一个 --db <新路径> 跑 qiyu sync run 重新拉取(不带 --db 的 sync run 仍会读到这个损坏的文件)';
83
+ const OPEN_FAILURE_HINTS = {
84
+ not_duckdb: NOT_DUCKDB_HINT,
85
+ permission: PERMISSION_HINT,
86
+ corrupt: CORRUPT_HINT,
87
+ };
88
+ /** 成因 → hint 的唯一映射点(`Record` 保证新增成因时编译期就漏不掉)。 */
89
+ export function openFailureHint(f) {
90
+ return OPEN_FAILURE_HINTS[f.cause];
91
+ }
92
+ export function classifyOpenFailure(e) {
93
+ const msg = e instanceof Error ? e.message : String(e);
94
+ if (/is not a valid DuckDB database file!?$/.test(msg))
95
+ return { cause: 'not_duckdb' };
96
+ if (/:\s*(Permission denied|Operation not permitted|Read-only file system)\s*$/.test(msg)) {
97
+ return { cause: 'permission' };
98
+ }
99
+ if (/^IO Error: Could not read enough bytes from file "/.test(msg))
100
+ return { cause: 'corrupt' };
101
+ if (/^IO Error: Corrupt database file:/.test(msg))
102
+ return { cause: 'corrupt' };
103
+ return null;
104
+ }
17
105
  const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
18
106
  /** 有界重试:可重试错误按固定间隔重试至 maxMs,超限抛最后一个错误。 */
19
107
  export async function retryWithBackoff(opts) {
@@ -36,11 +36,13 @@ export const TABLES = [
36
36
  {
37
37
  name: 'sync_gaps',
38
38
  columns: [col('dataset', 'VARCHAR', false), col('range_start', 'VARCHAR', false), col('range_end', 'VARCHAR'),
39
- col('reason', 'VARCHAR'), col('recorded_at', 'VARCHAR'),
39
+ // reason 进主键(v10):同一窗可能同时缺行(row_missing_key)与缺 fixture
40
+ // (export_fixture_unreported)—— 两类提示互不覆盖,一窗一行会互相覆盖。
41
+ col('reason', 'VARCHAR', false), col('recorded_at', 'VARCHAR'),
40
42
  // D-T3:缺口诊断详情(recordGap 的 detail 落点)。
41
43
  col('detail', 'VARCHAR')],
42
- primaryKey: ['dataset', 'range_start'],
43
- grain: '每个缺口区间一行',
44
+ primaryKey: ['dataset', 'range_start', 'reason'],
45
+ grain: '每个「缺口区间 × 原因」一行(同一窗可能有多条互不覆盖的提示)',
44
46
  },
45
47
  {
46
48
  name: 'tags',
@@ -413,6 +415,27 @@ export const MIGRATIONS = [
413
415
  await exec('ALTER TABLE "sync_state" ADD COLUMN IF NOT EXISTS "resolved_range_end" VARCHAR');
414
416
  },
415
417
  },
418
+ // v10(2026-11-05,CodeRabbit PR #67):sync_gaps 主键补 reason —— 同一窗可能同时
419
+ // 缺行(row_missing_key)与缺 fixture(export_fixture_unreported),两类提示互不
420
+ // 覆盖;旧主键 (dataset, range_start) 让后写的一条覆盖前一条,消费方按 reason 分支
421
+ // 时永远漏一类。DuckDB 不能 ALTER PRIMARY KEY → 重建表。
422
+ // ⚠️ 幂等性:新库的 v1 已按新主键建表,本迁移照常跑(copy → drop → rename 对同构
423
+ // 表是恒等变换)。reason 为 NULL 的历史行 COALESCE 成 'unknown'(缺 reason 的缺口行
424
+ // 对消费方本来就没有可分支的信息,且主键列不能为 NULL)。
425
+ {
426
+ version: 10,
427
+ up: async (exec) => {
428
+ await exec(`CREATE TABLE "sync_gaps_v10" (
429
+ "dataset" VARCHAR NOT NULL, "range_start" VARCHAR NOT NULL, "range_end" VARCHAR,
430
+ "reason" VARCHAR NOT NULL, "recorded_at" VARCHAR, "detail" VARCHAR,
431
+ PRIMARY KEY ("dataset", "range_start", "reason"))`);
432
+ await exec(`INSERT INTO "sync_gaps_v10" ("dataset", "range_start", "range_end", "reason", "recorded_at", "detail")
433
+ SELECT "dataset", "range_start", "range_end", COALESCE("reason", 'unknown'), "recorded_at", "detail"
434
+ FROM "sync_gaps"`);
435
+ await exec('DROP TABLE "sync_gaps"');
436
+ await exec('ALTER TABLE "sync_gaps_v10" RENAME TO "sync_gaps"');
437
+ },
438
+ },
416
439
  ];
417
440
  // ⚠️ E 交付后仍无命令层调用方(`db describe` 展示的是 `TABLES` 的列定义,不是迁移版本号);
418
441
  // 现由 `tests/store/schema.test.ts` 与迁移一致性断言消费。保留导出(L2)。