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
@@ -20,9 +20,14 @@
20
20
  // 的 `rejected_flag` 规则都在,将来若再出现"已知但显式拒绝"的 flag 直接登记),
21
21
  // 只是当前没有任何 flag 属于这一类。
22
22
  //
23
- // 本文件必须保持零依赖(只含类型、常量与几个纯函数):`core/`、`query/`、`sync/`
23
+ // 本文件保持「几乎零依赖」(只含类型、常量与几个纯函数):`core/`、`query/`、`sync/`
24
24
  // 分层红线之外,它是 commands 层里最底层的一块,被各命令模块与 `tree.ts` 的
25
25
  // `COMMAND_TREE` 共同消费。
26
+ // ⚠️ 唯一的外部依赖是 `output.ts` 的 `describeArgs`(2026-11-06 Codex 审查引入):
27
+ // 错误文案里的参数渲染必须只有一份实现(空串/纯空白要写成 `''`/`' '`),
28
+ // 在 spec-types 里再写一遍就是第二事实源。无循环 —— `output.ts` 只 import
29
+ // `core/sanitize.js`,不 import 本文件(`tests/store/layering.test.ts` 的分层规则也放行)。
30
+ import { describeArgs } from '../output.js';
26
31
  /**
27
32
  * 所有命令都接受的全局 flag(解析器里的 `KNOWN`)。
28
33
  *
@@ -77,6 +82,44 @@ export function prettyAfterSubcommand(group) {
77
82
  return `--pretty 是输出格式开关,必须写在具体子命令之后(如 \`qiyu ${group} … --pretty\`)。` +
78
83
  '写在这里没有可修饰的命令';
79
84
  }
85
+ /**
86
+ * `--pretty` 写在子命令之前的分派分支里,**位置参数**的唯一判据
87
+ *(Codex 2026-11-08 第四轮 P2 + CodeRabbit 第五轮 minor 双向收敛)。
88
+ *
89
+ * ⚠️ 只查「未知 flag」会放过位置参数:`qiyu api --pretty typo --help` 里 `typo` 不以
90
+ * `-` 开头、被忽略,随后 `--help` 以退出码 0 返回 —— 拼错的参数被静默吞掉(改动前
91
+ * api 族会报「未知参数:typo」)。故第一个裸位置 token 必须是子命令名,否则在
92
+ * **help 之前**拒绝。
93
+ *
94
+ * ⚠️ 判据只看**第一个**裸位置 token(第五轮 minor):合法子命令名之后的 token 属于
95
+ * 那条子命令的位置参数域(`db --pretty describe sessions --help` 的 `sessions`),
96
+ * `--db /tmp/x` 这类 flag **取值**也不是位置参数 —— 都不在这里判,交给 help 与
97
+ * 子命令自己的解析器。为此必须按 FlagSpec 跳过**值位**(value/repeatable 的下一个
98
+ * token 是取值,不是位置参数),否则 `sync --pretty status --db /tmp/x --help`
99
+ * 会把取值 `/tmp/x` 误判成拼错词(第五轮实测回归)。
100
+ *
101
+ * 返回 undefined = 放行(交给调用方的 help / prettyAfterSubcommand);否则返回
102
+ * usage 文案,调用方须在 help 之前拒绝。
103
+ */
104
+ export function prettyPositionalProblem(args, specs) {
105
+ const subcommands = specs.map((s) => s.path[1]).filter((n) => n !== undefined);
106
+ const valueFlags = new Set(specs.flatMap((s) => s.flags).filter((f) => f.kind !== 'bool').map((f) => f.name));
107
+ let first;
108
+ for (let i = 0; i < args.length; i++) {
109
+ const a = args[i];
110
+ if (valueFlags.has(a)) {
111
+ i++;
112
+ continue;
113
+ } // flag + 它的取值:取值不是位置参数
114
+ if (a.startsWith('-'))
115
+ continue; // 不吃值的 flag
116
+ first = a;
117
+ break;
118
+ }
119
+ if (first === undefined || subcommands.includes(first))
120
+ return undefined;
121
+ return `未知参数:${describeArgs([first])}。--pretty 不接受额外参数`;
122
+ }
80
123
  /**
81
124
  * 存储定位三件套(store 命令同族)。值位语义唯一事实源在 `store-flags.ts`:
82
125
  * `STORE_VALUE_FLAG_NAMES` 从这里派生,解析器与 spec 消费同一份,避免两边各写一遍
@@ -96,6 +139,63 @@ export const STORE_FLAGS = [
96
139
  export function valueFlagNames(flags) {
97
140
  return flags.filter((f) => f.kind === 'value' || f.kind === 'repeatable').map((f) => f.name);
98
141
  }
142
+ /**
143
+ * `--help` 模式下的参数检查(唯一实现点,2026-11-06 审查):只把**不在完整接受集里的
144
+ * flag** 与**缺值的值位 flag** 当错误;位置参数与被正确消费的取值在帮助模式下忽略
145
+ *(`tickets`、`0 3 * * *` 都是取值/位置参数,不是要检查的对象)。
146
+ *
147
+ * 帮助请求不该因为**合法参数**而失败:`qiyu db describe tickets --help` 是 Agent 想
148
+ * 看帮助的常规写法,而此前各命令的 help 分支拿 `KNOWN = GLOBAL_FLAG_NAMES` 过滤 argv,
149
+ * 于是 `tickets` / `--db` / `--schedule 0 3 * * *` 全被判成「未知参数」并退出 2;
150
+ * 同一命令行在 `api list` / `sync run` / `skill *` 上却退出 0(它们的 KNOWN 来自 spec)。
151
+ * 更重的是:`skill check` 按 `CommandSpec.flags` 判这些命令**合法**,检查器与运行时的
152
+ * 「合法调用集」因此互斥。
153
+ *
154
+ * ⚠️ **取值是否成立由该 flag 自己的规则决定**(Codex PR #69 两轮实测):
155
+ * · 默认:下一 token 以 `--` 开头 = 缺值(沿 `parseStoreFlags` 的判据)。无条件吞掉
156
+ * 下一个 token 会让 `db tables --db --bogus --help` 打印帮助并静默吞掉 `--bogus`,
157
+ * 而正常解析对同一输入判「`--db` 缺少取值」(退出码 2)—— 帮助模式不能更宽松;
158
+ * · `FlagSpec.dashValue: true`(如 `query --sql` 的 SQL 行注释):取值可以以 `--` 开头,
159
+ * 只有**恰好是已知 flag token** 才算缺值 —— 与 `query` 的 `FLAG_TOKENS` 判据同源,
160
+ * 否则 `query --sql "-- 注释\nSELECT 1" --help` 会把合法 SQL 判成「未知 flag」;
161
+ * · 值位在末尾(没有下一 token)= 缺值,帮助模式同样要报 —— 正常解析也会报。
162
+ */
163
+ export function helpArgsError(argv, flags, unknownSuffix = '') {
164
+ const known = new Set(flags.map((f) => f.name));
165
+ const values = new Set(valueFlagNames(flags));
166
+ const dashOk = new Set(flags.filter((f) => f.dashValue === true).map((f) => f.name));
167
+ const unknown = [];
168
+ const missingValue = [];
169
+ for (let i = 0; i < argv.length; i++) {
170
+ const a = argv[i];
171
+ if (a === '--help' || a === '-h')
172
+ continue;
173
+ if (!a.startsWith('-'))
174
+ continue;
175
+ if (!known.has(a)) {
176
+ unknown.push(a);
177
+ continue;
178
+ }
179
+ if (!values.has(a))
180
+ continue;
181
+ const v = argv[i + 1];
182
+ if (v === undefined) {
183
+ missingValue.push(a);
184
+ continue;
185
+ }
186
+ const flagLike = dashOk.has(a) ? known.has(v) : v.startsWith('--');
187
+ if (flagLike) {
188
+ missingValue.push(a);
189
+ continue;
190
+ }
191
+ i++; // 消费它的取值(取值本身不是参数)
192
+ }
193
+ if (missingValue.length > 0)
194
+ return `${missingValue.join('、')} 缺少取值`;
195
+ if (unknown.length > 0)
196
+ return `未知参数:${describeArgs(unknown)}${unknownSuffix}`;
197
+ return undefined;
198
+ }
99
199
  /**
100
200
  * 按最长前缀匹配命令路径:`['sync','run']` 优先于 `['sync']`。
101
201
  *
@@ -10,13 +10,14 @@
10
10
  // 每条带 source;`observed` 是本地 payload 的数据分布,不是语义;
11
11
  // · `-1` 是「该窗口没有匹配到数据」的哨兵(设计稿实测,厂商未文档化)——
12
12
  // sentinel 恒在,且 min/max 一律排除 -1(否则 Agent 会报出 -100%)。
13
- import { thrownToQueryExit, suggestNames } from '../query/errors.js';
13
+ import { thrownToQueryExit, suggestNames, missingTableCauses } from '../query/errors.js';
14
14
  import { METRIC_CATALOG, REPORT_TABLES, declareMetric } from '../query/metric-catalog.js';
15
15
  import { TABLES } from '../store/schema.js';
16
16
  import { openGuardedSession } from './db.js';
17
- import { parseStoreFlags } from './store-flags.js';
18
- import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty } from '../output.js';
19
- import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, prettyAfterSubcommand, REJECTED_FLAGS, STORE_FLAGS } from './spec-types.js';
17
+ import { DB_PATH_HELP, parseStoreFlags } from './store-flags.js';
18
+ import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty, syncRunCommand, dbTablesCommand, dbDescribeCommand, querySqlCommand, SQL_ARG_REPLACE_NOTE, metadataTimeoutHint, storeLocationFromFlags, storeLocationOf, } from '../output.js';
19
+ import { withTimeoutHint } from '../query/sandbox.js';
20
+ import { GLOBAL_FLAGS, helpArgsError, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS, STORE_FLAGS } from './spec-types.js';
20
21
  /**
21
22
  * 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu stats …` 是否真的存在。
22
23
  * `flags` 是**完整接受集**(含全局 flag),`--pretty` 同时在 `rejected` 里。
@@ -40,8 +41,8 @@ const USAGE = `用法:qiyu stats <子命令> [参数]
40
41
  ${REPORT_TABLES.join('、')}
41
42
 
42
43
  存储定位:--db / --profile / --backend(store 命令同族)。
44
+ ${DB_PATH_HELP}
43
45
  `;
44
- const KNOWN = new Set(GLOBAL_FLAG_NAMES);
45
46
  /**
46
47
  * -1 哨兵(spec §9.2,逐字)。设计稿 §6.2 用 A/B 实测证明:数据充足的 31 天窗口
47
48
  * 给出 assignedRatio=0.987,什么都匹配不到的筛选条件给出 -1.0 —— 不是负比率。
@@ -117,6 +118,92 @@ function extremeOf(v) {
117
118
  const n = Number(v);
118
119
  return Number.isFinite(n) ? n : null;
119
120
  }
121
+ /**
122
+ * `declared.<字段>.unit` 的四个取值 —— 图例的**唯一构造点**(`satisfies` 让新增取值
123
+ * 漏写释义直接编译失败)。
124
+ *
125
+ * ⚠️ 为什么必须逐值写出来:`stats fields` 的全部意义就是让 Agent **不猜单位**
126
+ * (设计稿 §9.2「单位不确定 → 查 stats fields 的 unit;绝不要猜百分比还是绝对值」)。
127
+ * 只输出 `ratio`/`count`/`ms`/`unknown` 四个英文词,等于把「猜」从字段名挪到了枚举值上:
128
+ * `ratio` 是 0–1 还是 0–100?`ms` 是毫秒还是别的?不写清,Agent 照样会把 0.987
129
+ * 报成「0.987%」或把毫秒当秒。
130
+ *
131
+ * 诚实边界(写进图例,不藏着):`ratio` 的量纲只有 `assignedRatio` 一个字段被设计稿
132
+ * §6.2 实测过(0.987 = 98.7%);其余 ratio 字段是**按名字推断**的(见 source),
133
+ * 量纲未逐一实测。⚠️ 别把 `observed` 的分布当替代证据(CodeRabbit 2026-10-27):
134
+ * 一个推断出来的 ratio 全落在 0–1,与「0–1 小数」和「数值恰好都 <1% 的百分数」
135
+ * 同样相容 —— 所以图例的动作是「报告原值并标注不确定」,不是「照 0–1 换算」。
136
+ */
137
+ export const UNIT_NOTES = {
138
+ ratio: '比率。实测样本 assignedRatio=0.987 是 0–1 的小数、不是 0–100 的百分数。'
139
+ + '⚠️ 只有该字段经设计稿实测,其余 ratio 是命名推断(见 source):observed 的 min/max '
140
+ + '只能核对一致性、不是量纲证据 —— 全都落在 0–1 时,它与「0–1 小数」和'
141
+ + '「数值恰好都 <1% 的百分数」都相容。量纲仍不明确就报告原值并标注不确定,'
142
+ + '不要自行换算成百分比',
143
+ count: '计数(整数)',
144
+ ms: '毫秒(实测样本 loginDuration 天粒度 = 86400024,即 86400000 + 24)',
145
+ unknown: '判不出单位(目录未收录、字段名后缀也推不出)—— 不是「没有单位」:'
146
+ + '报告时如实写「单位未知」,不要猜。这些字段同时列在 unknown_fields。'
147
+ // 2026-11-09 审计:此前只说「不要猜」,没有给出真能跑的核实路径;而 --sql 拒绝
148
+ // 参数占位符 `?`,用户照 SQL 习惯写 `WHERE field = ?` 会以退出码 2 失败。
149
+ // ⚠️ 命令的渲染发生在调用点(`statsFieldNotes(loc)`):写死成裸 `qiyu query --sql`
150
+ // 时,`stats fields --db X` 的提示照着执行会查**默认库**(Codex 2026-11-10 第八轮 P2)。
151
+ // 措辞按「unknown 字段是什么」核过:它们是**报表 payload 里的 JSON 键**,不是表的列
152
+ // ——实测 `SELECT unlistedMetric FROM daily_overview` 是 Binder Error,要经 `payload ->>`
153
+ // 取值。原句「显式列出该列」照着执行必然失败(Codex 2026-11-10 第九轮 P2)。
154
+ + '要看原始值判断量纲用 {@query} 把 payload 里的该字段取出来'
155
+ + '(写着 `payload ->> \'<字段>\'`,它不是表的列、直接 SELECT 字段名会报列不存在)'
156
+ // 用全角括号、不用分号:`renderNotes` 以「;」分隔各项,半角的 `; ... ` 不会被拆开;
157
+ // 而全角分号会把这条说明截成一项假的「值」(三方守卫的图例 ⊆ 枚举会红)。
158
+ + '(--sql 不接受参数占位符 `?`,过滤条件必须写成字面量。' + SQL_ARG_REPLACE_NOTE + ')',
159
+ };
160
+ /** `declared.<字段>.source` 的两个取值:标明声明是实测还是命名推断。 */
161
+ export const SOURCE_NOTES = {
162
+ 'design-doc': '设计稿实测明说(可信度最高,该条 note 通常给出出处)',
163
+ 'name-suffix': '按字段名后缀推断(*Ratio/*Radio→ratio、*Count/sessions→count、'
164
+ + '*Duration/*Time→ms)—— 是命名推断,不是实测。后缀推不出的记 unknown',
165
+ };
166
+ /** 渲染成 `a = 释义;b = 释义` —— field_notes 的单元格形态(与 api list / skill where 同款)。 */
167
+ function renderNotes(notes) {
168
+ return Object.entries(notes).map(([k, v]) => `${k} = ${v}`).join(';');
169
+ }
170
+ /**
171
+ * `stats fields` 的 `meta.field_notes`(导出供测试核对真实渲染路径 —— 测试若自写一份
172
+ * 渲染副本,生产漏渲染某个值时它照样全绿)。
173
+ */
174
+ export function statsFieldNotes(loc) {
175
+ return {
176
+ table: '本次统计的报表表名(回显输入;只接受报表域表,见命令 help 的可用表清单)。'
177
+ + '它不是「库里有哪些表」的依据 —— 那用 `db tables`;也不是「该表已同步」的证明',
178
+ sentinel: '`-1` 哨兵的含义对象:`value` 是哨兵数值(-1),`meaning` 说明它表示'
179
+ + '「该窗口或筛选条件没有匹配到数据」(厂商未文档化,实测报表面族统一)。'
180
+ + '⚠️ 不要把 -1 当负数比率或负值参与计算 —— 它表示「没有数据」,不是「小于零的数值」',
181
+ // ⚠️ 图例键的路径形态即契约:`declared` 是**按字段名分组的对象**(不是数组),
182
+ // `observed` 才是数组。写成 `declared[].unit` 指的是一个不存在的路径
183
+ // (CodeRabbit 2026-10-27 抓到;测试里有一条钉住这个形态)。
184
+ // 占位符 `{@query}` 在**调用点**渲染成本次的 `qiyu query --sql … --db <本次库>`:
185
+ // `UNIT_NOTES` 是常量、不认识本次的存储定位,模板里写死裸命令会让 `--db X` 的提示
186
+ // 照着执行时查默认库(Codex 2026-11-10 第八轮 P2)。渲染器仍是 output.ts 的唯一实现点。
187
+ // ⚠️ 替换值必须是回调:`String.replace` 的字符串替换值会解释 `$&`/`$$`/`` $` ``/`$'`/`$1`,
188
+ // 而命令里含用户给的库路径与档名 —— `/tmp/q$&.duckdb` 会被改写成 `/tmp/q{@query}.duckdb`
189
+ //(Codex / CodeRabbit 2026-11-10 第九轮,实测)。
190
+ 'declared.<字段>.unit': renderNotes(UNIT_NOTES).replace('{@query}', () => `\`${querySqlCommand(loc)}\``),
191
+ 'declared.<字段>.source': renderNotes(SOURCE_NOTES),
192
+ 'declared.<字段>.higher_is_better': '恒为 null —— 设计稿与本 CLI 都没有任何「指标越大越好还是越小越好」的上游依据,'
193
+ + '不猜(设计稿 §9.2)。不要把 null 读成「本字段恰好没测到」,也不要把 null 当 false;'
194
+ + '要判断趋势好坏只能由人给口径',
195
+ 'declared.<字段>.note': '该条声明的依据(通常只有 source=design-doc 的条目有)。null = 无出处注记',
196
+ unknown_fields: 'unit 为 unknown 的观测字段(判据是「判不出单位」,不是「目录未收录」——'
197
+ + '后缀能派生的字段即使不在目录里也不算)',
198
+ 'observed[].minus_one': '值为 -1 的行数。-1 是「该窗口或筛选条件没有匹配到数据」的哨兵'
199
+ + '(厂商未文档化),不是负数比率。等于 rows_present 说明该字段本次全是哨兵',
200
+ 'observed[].min': '排除 -1 哨兵后的最小值;全为哨兵或非数值时为 null(不是 0)——'
201
+ + 'null 时看 minus_one',
202
+ 'observed[].max': '排除 -1 哨兵后的最大值;全为哨兵或非数值时为 null(不是 0)',
203
+ 'observed[].rows_present': 'payload 中出现该键的行数(缺键、payload 为 NULL/空对象/非对象的行不计)',
204
+ 'observed[].nulls': '该键值为 JSON null 的行数',
205
+ };
206
+ }
120
207
  function declOut(d) {
121
208
  return {
122
209
  unit: d.unit,
@@ -128,9 +215,9 @@ function declOut(d) {
128
215
  async function statsFields(argv) {
129
216
  // 子命令级次序沿 db.ts:--help 分流 → --pretty 开启缩进(G1) → parseStoreFlags → 位置参数。
130
217
  if (argv.includes('--help') || argv.includes('-h')) {
131
- const extra = argv.filter((a) => !KNOWN.has(a));
132
- if (extra.length > 0)
133
- return usageFail(`未知参数:${extra.join(' ')}。--help 不接受额外参数`);
218
+ const problem = helpArgsError(argv, STATS_SPECS.flatMap((sp) => sp.flags), '。--help 不接受额外参数');
219
+ if (problem !== undefined)
220
+ return usageFail(problem);
134
221
  process.stdout.write(USAGE);
135
222
  return 0;
136
223
  }
@@ -146,13 +233,15 @@ async function statsFields(argv) {
146
233
  }
147
234
  const flagish = flags.rest.filter((a) => a.startsWith('-'));
148
235
  if (flagish.length > 0)
149
- return usageFail(`未知参数:${flagish.join(' ')}`);
236
+ return usageFail(`未知参数:${describeArgs(flagish)}`);
150
237
  if (flags.rest.length === 0) {
151
238
  return usageFail(`缺少表名:请给 stats fields <表>\n可用表:${REPORT_TABLES.join('、')}`);
152
239
  }
153
240
  if (flags.rest.length > 1)
154
- return usageFail(`未知参数:${flags.rest.slice(1).join(' ')}`);
241
+ return usageFail(`未知参数:${describeArgs(flags.rest.slice(1))}`);
155
242
  const table = sanitizeControlChars(flags.rest[0]);
243
+ // 尚未解析存储(闭集校验先于一切 I/O):诊断 hint 只能复现用户原始 flag。
244
+ const preOpenLoc = storeLocationFromFlags(flags);
156
245
  // spec §9.1:闭集校验先于一切 I/O —— 非报表表不进库、不开连接。
157
246
  if (!REPORT_TABLES.includes(table)) {
158
247
  // ⚠️ hint 必须按**这句话是否成立**来给(2026-10-18 手工验收发现,复审 Minor-1 补齐):
@@ -167,21 +256,24 @@ async function statsFields(argv) {
167
256
  const payloadCol = known?.columns.find((c) => c.name === 'payload');
168
257
  const hint = known === undefined
169
258
  ? (candidates.length > 0
170
- ? `候选:${candidates.join('、')}(stats fields 只接受报表域表;用 \`qiyu db tables\` 查看全部表)`
171
- : '用 `qiyu db tables` 查看全部表;stats fields 只接受报表域表')
259
+ ? `候选:${candidates.join('、')}(stats fields 只接受报表域表;用 `
260
+ + '`' + dbTablesCommand(preOpenLoc) + '` 查看全部表)'
261
+ : '用 `' + dbTablesCommand(preOpenLoc) + '` 查看全部表;stats fields 只接受报表域表')
172
262
  : payloadCol !== undefined && payloadCol.sensitive
173
263
  ? '该表的 payload 是整行 PII 副本:统计它没有价值且会扩大暴露面'
174
264
  : payloadCol !== undefined
175
- ? '该表的业务字段收敛在 payload 里但不属于报表域;stats fields 只做报表指标,字段清单请用 `qiyu db describe ' + table + '`'
265
+ ? '该表的业务字段收敛在 payload 里但不属于报表域;stats fields 只做报表指标,字段清单请用 `'
266
+ + dbDescribeCommand(table, preOpenLoc) + '`'
176
267
  : '该表的业务字段不是整体收敛进 payload 的(没有 payload 列),字段自描述对它没有意义';
177
268
  return usageFail(`stats fields 只接受报表域表,收到:${describeArgs([table])}\n可用表:${REPORT_TABLES.join('、')}`, hint);
178
269
  }
179
270
  const opened = await openGuardedSession({
180
271
  db: flags.db, profile: flags.profile, backend: flags.backend,
181
- });
272
+ }, metadataTimeoutHint);
182
273
  if ('exit' in opened)
183
274
  return opened.exit;
184
- const session = opened.session;
275
+ // 超时 hint 换成元数据命令的说法(本命令没有可调过滤参数,query 那句对它是死路)。
276
+ const session = withTimeoutHint(opened.session, metadataTimeoutHint(storeLocationOf(opened.dbPath, opened.profileFlag)));
185
277
  try {
186
278
  // 目标表存在性校验(spec §十一「库不存在/缺表 → store_not_initialized、退出码 1」):
187
279
  // schema_version 的库结构校验在 openGuardedSession 里已做(E 族共用,口径见 db.ts 的
@@ -194,9 +286,7 @@ async function statsFields(argv) {
194
286
  return fail({
195
287
  code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
196
288
  message: `数据库中缺表:${table}(${opened.dbPath})`,
197
- hint: '若为建库未完成(迁移未跑完),运行 qiyu store init 可补建缺失的迁移;'
198
- + '若迁移已完成而表被删或损坏,store init 不会重建该表,重新同步也只会写入失败(缺表)'
199
- + '——需重建库(删除库文件后重新 qiyu store init 并重新同步)',
289
+ hint: missingTableCauses(opened.dbPath, opened.profileFlag),
200
290
  });
201
291
  }
202
292
  const result = await session.run(observeSql(table));
@@ -236,17 +326,28 @@ async function statsFields(argv) {
236
326
  if (badJson > 0) {
237
327
  warnings.push(`该表有 ${badJson} 行 payload 不是合法 JSON,未计入统计`
238
328
  + '(正常同步写入的是 JSON 字符串;这些行可能来自旧版 CLI、外部工具或库损坏)。'
239
- + '用 `qiyu query --sql` 单独查看它们以确认成因');
329
+ + '用 `' + querySqlCommand(storeLocationOf(opened.dbPath, opened.profileFlag))
330
+ + '` 单独查看它们以确认成因(' + SQL_ARG_REPLACE_NOTE + ')');
240
331
  }
241
332
  const emptyKey = countOf(shape.empty_key);
242
333
  if (emptyKey > 0) {
334
+ // 成因按事实写:观测 SQL 只收**非空键**(`WHERE e.key <> ''`),不是「JSON 路径表达不了」——
335
+ // 空键从没进过路径表达式。且这条不承诺「其余字段」:payload 可能只有空键
336
+ //(2026-11-09 实测:`{"":1}` 时旧文案「其余字段照常统计」与下面「均无可观测字段」互相矛盾)。
243
337
  warnings.push(`该表有 ${emptyKey} 行 payload 含空字符串键 "",该键未计入统计`
244
- + '(JSON 路径无法表达空键名);其余字段照常统计');
338
+ + '(观测只收非空键);同一行里的非空键照常统计');
245
339
  }
246
340
  if (observed.length === 0) {
247
341
  const n = Number(shape.total);
248
342
  if (n === 0) {
249
- warnings.push('该表无数据;先运行 `qiyu sync run`');
343
+ warnings.push('该表无数据;先运行 `' + syncRunCommand(opened.dbPath, opened.profileFlag) + '`');
344
+ }
345
+ else if (emptyKey > 0) {
346
+ // 有行、只是空键被排除:不得把它归进「NULL / 空对象 / 非对象」(`{"":1}` 都不是)
347
+ warnings.push(`该表有 ${n} 行,但 0 个可观测字段:${emptyKey} 行 payload 只有空字符串键 ""`
348
+ + '(空键不计入统计,原因见上一行)。'
349
+ + '若这不是预期,用 `' + querySqlCommand(storeLocationOf(opened.dbPath, opened.profileFlag))
350
+ + '` 直接查看 payload(' + SQL_ARG_REPLACE_NOTE + ')');
250
351
  }
251
352
  else {
252
353
  warnings.push(`该表有 ${n} 行,但 payload 均无可观测字段(payload 为 NULL / 空对象 / 非对象)。`
@@ -261,10 +362,11 @@ async function statsFields(argv) {
261
362
  warnings.push(`观测字段数超过单次行数上限,observed/unknown_fields 只含按字段名排序的前 `
262
363
  + `${result.rows.length} 个字段;该表的字段集可能不完整`);
263
364
  }
264
- return ok({ table, sentinel: SENTINEL, declared: Object.fromEntries(declared), observed, unknown_fields: unknownFields }, { warnings });
365
+ const loc = storeLocationOf(opened.dbPath, opened.profileFlag);
366
+ return ok({ table, sentinel: SENTINEL, declared: Object.fromEntries(declared), observed, unknown_fields: unknownFields }, { field_notes: statsFieldNotes(loc), warnings });
265
367
  }
266
368
  catch (e) {
267
- return thrownToQueryExit(e, TABLES);
369
+ return thrownToQueryExit(e, TABLES, false, storeLocationOf(opened.dbPath, opened.profileFlag));
268
370
  }
269
371
  finally {
270
372
  await session.close();
@@ -273,19 +375,26 @@ async function statsFields(argv) {
273
375
  export async function statsCommand(argv) {
274
376
  setPretty(false); // G1:每条命令入口重置输出格式 —— 同一进程内多次 run(测试)不残留上一条命令的开关。
275
377
  const [sub, ...rest] = argv;
276
- if (sub === undefined || sub === '--help' || sub === '-h') {
378
+ // ⚠️ 无子命令 = 用法错误(退 2 + JSON)—— 见 store.ts 同款注释(2026-11-07 审查)。
379
+ if (sub === undefined) {
380
+ return usageFail('用法:qiyu stats <fields> [参数](`qiyu stats --help` 查看全部)', '可用子命令:fields');
381
+ }
382
+ if (sub === '--help' || sub === '-h') {
277
383
  // --help 不吞额外参数;--pretty 豁免(db.ts 同族惯例)
278
- const extra = rest.filter((a) => !KNOWN.has(a));
279
- if (extra.length > 0)
280
- return usageFail(`未知参数:${extra.join(' ')}。--help 不接受额外参数`);
384
+ const problem = helpArgsError(rest, STATS_SPECS.flatMap((sp) => sp.flags), '。--help 不接受额外参数');
385
+ if (problem !== undefined)
386
+ return usageFail(problem);
281
387
  process.stdout.write(USAGE);
282
388
  return 0;
283
389
  }
284
390
  // G1:--pretty 是输出开关,必须写在具体子命令之后(`stats fields <表> --pretty`)。
285
391
  if (sub === '--pretty') {
286
- const extra = rest.filter((a) => !KNOWN.has(a));
287
- if (extra.length > 0)
288
- return usageFail(`未知参数:${extra.join(' ')}。--pretty 不接受额外参数`);
392
+ const problem = helpArgsError(rest, STATS_SPECS.flatMap((sp) => sp.flags));
393
+ if (problem !== undefined)
394
+ return usageFail(`${problem}。--pretty 不接受额外参数`);
395
+ const badPos = prettyPositionalProblem(rest, STATS_SPECS);
396
+ if (badPos !== undefined)
397
+ return usageFail(badPos);
289
398
  if (rest.includes('--help') || rest.includes('-h')) {
290
399
  process.stdout.write(USAGE);
291
400
  return 0;
@@ -12,6 +12,16 @@
12
12
  // 完整接受集也消费 `STORE_FLAGS`,两边共用同一份才不会出现「spec 说接受、解析器
13
13
  // 不认」。
14
14
  import { STORE_FLAGS } from './spec-types.js';
15
+ /**
16
+ * `--db` 的相对路径语义 —— 各命令 `--help` 里那句话的**唯一出处**。
17
+ *
18
+ * ⚠️ 为什么必须写出来(2026-11-07 审查):`--db` 的相对路径按 **HOME** 解析
19
+ * (`store/config.ts` 的 `resolveStoreConfig`,默认库 relPath 依赖它),而用户对
20
+ * 普通命令的相对路径直觉是 **cwd** —— 两条相反的直觉同时成立,`--help` 不提,
21
+ * Agent 会把 `--db data/q.duckdb` 当成「当前目录下的库」,实际解析到
22
+ * `~/data/q.duckdb`。绝对路径与 `~` 开头不受影响,提醒要短,但要提到 `~` 也会展开。
23
+ */
24
+ export const DB_PATH_HELP = '--db 相对路径按 HOME 解析(不是当前目录):data/q.db 即 ~/data/q.db';
15
25
  /** 值位 flag 名(`--db` 等,带 `--`),顺序沿 `STORE_FLAGS`。 */
16
26
  export const STORE_VALUE_FLAG_NAMES = STORE_FLAGS.map((f) => f.name);
17
27
  // ⚠️ 模块级断言(Task 2 复审 M1,Task 3 顺带落地):`parseStoreFlags` 用 `a.slice(2)`
@@ -35,12 +45,20 @@ if (!STORE_VALUE_FLAG_NAMES.every((n) => n.startsWith('--'))) {
35
45
  */
36
46
  export function parseStoreFlags(argv) {
37
47
  const out = { rest: [] };
48
+ const seen = new Set();
38
49
  for (let i = 0; i < argv.length; i++) {
39
50
  const a = argv[i];
40
51
  if (STORE_VALUE_FLAG_NAMES.includes(a)) {
41
52
  const v = argv[i + 1];
42
53
  if (v === undefined || v.startsWith('--'))
43
54
  throw new Error(`${a} 缺少取值`);
55
+ // ⚠️ 重复出现必须报错,不得静默覆盖(2026-11-09 审计实测):
56
+ // `store status --db a.duckdb --db b.duckdb` 此前只认后一个、对前一个只字不提,
57
+ // Agent 会以为命令作用在它**第一个**给的库上(`api call --body` 的同类判据:
58
+ // 带值 flag 重复 = 有一个值被丢弃,退出码 2 换它改参数)。
59
+ if (seen.has(a))
60
+ throw new Error(`${a} 重复出现:只能给一次(不做静默覆盖)`);
61
+ seen.add(a);
44
62
  // a 已由上面的 includes 收窄为三件套之一,slice(2) 得到 db/profile/backend。
45
63
  out[a.slice(2)] = v;
46
64
  i++;
@@ -0,0 +1,38 @@
1
+ // src/commands/store-notes.ts
2
+ //
3
+ // `store init` 与 `store status` 的 `meta.field_notes` —— 存储层定位与版本信息的逐键释义。
4
+ //
5
+ // ⚠️ 为什么需要(2026-10-28 真库实测):
6
+ // · `schema_version` 是一个裸数字,没有对照基准就没有意义 —— 它要跟当前 CLI 的
7
+ // `LATEST_VERSION` 比,才知道库是不是旧版建的;
8
+ // · `tables` 只列**本 CLI 声明的表**(`TABLES`),与 `db tables` 同一组 ——
9
+ // 但库里有未声明的表时,两边数量仍会不等(多表),文案必须解释**两个方向**,
10
+ // 不能只说「不一致说明有表缺失」(2026-11-01 修:那句把 Agent 引向
11
+ // 「库不完整/需重建」,而重建会**销毁它正在观察的那些未声明表**);
12
+ // · `config_exists: false` 容易被读成「存储没配好」,其实用 `--db` / 环境变量 /
13
+ // 默认路径照样工作,`store init` 也不写配置文件。
14
+ //
15
+ // ⚠️ 释义正文不用 `;`(renderNotes 的拼接符),也不用 `**`(stdout JSON 给 Agent)。
16
+ import { LATEST_VERSION } from '../store/schema.js';
17
+ /** `store init` / `store status` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。 */
18
+ export function storeFieldNotes() {
19
+ return {
20
+ path: '实际生效的库文件路径(--db / QIYU_DB_PATH / 配置文件 / 默认值解析之后的结果),'
21
+ + '不是配置文件里的原始写法',
22
+ backend: '存储后端。当前恒为 duckdb —— 只有这一个取值,不要据此分支',
23
+ config_path: '配置文件路径。⚠️ 它不是库路径:库在 path,配置在这里',
24
+ config_exists: '命令执行时配置文件是否存在。false 不代表存储不可用 —— '
25
+ + '用 --db、环境变量或默认路径照样能工作,store init 也不写配置文件',
26
+ schema_version: `库内已应用的最高迁移版本(当前 CLI 是 ${LATEST_VERSION})。`
27
+ + '0 = 迁移记录表为空。小于当前版本说明库是旧版 CLI 建的:store init 会补建缺失的迁移,'
28
+ + '已应用的不会重放(所以它修不了「表被删」这类损坏)',
29
+ tables: '库里的表清单。只列本 CLI 声明的表(TABLES),与 db tables 列的是同一组表,'
30
+ + '含内部表 schema_version / sync_state / sync_gaps,所以两边数量应当一致。'
31
+ + '库里有而本 CLI 未声明的表(旧版 CLI 或其它工具建的)不出现在这里 —— '
32
+ + '它们在 meta.warnings 里点名,数量不一致时先读 warnings 判成因,'
33
+ + '⚠️ 不要据此断定「有表缺失」(多了表也会让数量不等,而重建库会销毁那些表)。'
34
+ + '⚠️ 形状随命令不同:store init 给表名数组(["a","b"]),store status 给 '
35
+ + '[{name, rows}] 且 rows 是真实 COUNT(*)(每次都要全表 COUNT,代价与数据量成正比,'
36
+ + '不要当高频健康检查用)',
37
+ };
38
+ }