qiyu-cli 0.0.0-stage → 0.2.0

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 (230) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +464 -2
  3. package/dist/cli.js +248 -0
  4. package/dist/commands/api.js +770 -0
  5. package/dist/commands/auth.js +349 -0
  6. package/dist/commands/credentials-source.js +70 -0
  7. package/dist/commands/db.js +503 -0
  8. package/dist/commands/local-fallback-wiring.js +67 -0
  9. package/dist/commands/local-fallback.js +34 -0
  10. package/dist/commands/query.js +564 -0
  11. package/dist/commands/skill-specs.js +64 -0
  12. package/dist/commands/skill.js +863 -0
  13. package/dist/commands/spec-types.js +145 -0
  14. package/dist/commands/stats.js +299 -0
  15. package/dist/commands/store-flags.js +56 -0
  16. package/dist/commands/store.js +258 -0
  17. package/dist/commands/sync-run.js +479 -0
  18. package/dist/commands/sync.js +757 -0
  19. package/dist/commands/tree.js +27 -0
  20. package/dist/core/config.js +259 -0
  21. package/dist/core/credentials.js +71 -0
  22. package/dist/core/edition.js +18 -0
  23. package/dist/core/envelope.js +201 -0
  24. package/dist/core/errors.js +356 -0
  25. package/dist/core/http.js +348 -0
  26. package/dist/core/ratelimit.js +126 -0
  27. package/dist/core/registry/index.js +212 -0
  28. package/dist/core/registry/params/ai.knowledge.addKnowledge.json +88 -0
  29. package/dist/core/registry/params/ai.knowledge.deleteKnowledges.json +46 -0
  30. package/dist/core/registry/params/ai.knowledge.editChannelAnswer.json +60 -0
  31. package/dist/core/registry/params/ai.knowledge.editKnowledge.json +95 -0
  32. package/dist/core/registry/params/ai.knowledge.editKnowledgeNoSimilars.json +102 -0
  33. package/dist/core/registry/params/ai.knowledge.getCategoryTree.json +39 -0
  34. package/dist/core/registry/params/ai.knowledge.getDetail.json +46 -0
  35. package/dist/core/registry/params/ai.knowledge.search.json +67 -0
  36. package/dist/core/registry/params/ai.statistic.transferHuman.json +60 -0
  37. package/dist/core/registry/params/category.list.json +39 -0
  38. package/dist/core/registry/params/chat.queue.group.query.json +39 -0
  39. package/dist/core/registry/params/crm.modifyOrder.json +48 -0
  40. package/dist/core/registry/params/crm.modifyUser.json +48 -0
  41. package/dist/core/registry/params/crm.syncCrmInfo.json +46 -0
  42. package/dist/core/registry/params/crm.tagChange.json +74 -0
  43. package/dist/core/registry/params/data.overview.ipcc.json +32 -0
  44. package/dist/core/registry/params/data.overview.session.json +53 -0
  45. package/dist/core/registry/params/evaluation.setting.get.json +39 -0
  46. package/dist/core/registry/params/event.applyStaff.json +116 -0
  47. package/dist/core/registry/params/event.evaluate.json +74 -0
  48. package/dist/core/registry/params/event.inviteEvaluate.json +81 -0
  49. package/dist/core/registry/params/event.qcResult.json +166 -0
  50. package/dist/core/registry/params/event.queryQueueStatus.json +39 -0
  51. package/dist/core/registry/params/event.queueEnter.json +40 -0
  52. package/dist/core/registry/params/event.queueLeave.json +46 -0
  53. package/dist/core/registry/params/event.quitQueue.json +39 -0
  54. package/dist/core/registry/params/event.sessionChange.json +95 -0
  55. package/dist/core/registry/params/event.sessionData.json +452 -0
  56. package/dist/core/registry/params/event.sessionEnd.json +117 -0
  57. package/dist/core/registry/params/event.sessionStart.json +109 -0
  58. package/dist/core/registry/params/event.updateUInfo.json +46 -0
  59. package/dist/core/registry/params/export.session.check.json +7 -0
  60. package/dist/core/registry/params/export.session.json +7 -0
  61. package/dist/core/registry/params/export.session.one.json +7 -0
  62. package/dist/core/registry/params/export.session.one.message.json +7 -0
  63. package/dist/core/registry/params/get_call_order.json +50 -0
  64. package/dist/core/registry/params/get_call_user_info.json +36 -0
  65. package/dist/core/registry/params/get_order.json +50 -0
  66. package/dist/core/registry/params/get_token.json +22 -0
  67. package/dist/core/registry/params/get_user_info.json +36 -0
  68. package/dist/core/registry/params/icoutcall.callIntercept.list.json +32 -0
  69. package/dist/core/registry/params/icoutcall.dialogFlow.fuzzySearch.json +53 -0
  70. package/dist/core/registry/params/icoutcall.dialogFlow.getDialogFlowList.json +32 -0
  71. package/dist/core/registry/params/icoutcall.get.customer.json +39 -0
  72. package/dist/core/registry/params/icoutcall.get.jobdetail.json +39 -0
  73. package/dist/core/registry/params/icoutcall.get.jobproperties.json +39 -0
  74. package/dist/core/registry/params/icoutcall.history.seat.json +67 -0
  75. package/dist/core/registry/params/icoutcall.history.team.json +67 -0
  76. package/dist/core/registry/params/icoutcall.job.create.json +53 -0
  77. package/dist/core/registry/params/icoutcall.job.importcustomer.json +46 -0
  78. package/dist/core/registry/params/icoutcall.job.pause.json +39 -0
  79. package/dist/core/registry/params/icoutcall.job.readdcustomer.json +109 -0
  80. package/dist/core/registry/params/icoutcall.job.start.json +39 -0
  81. package/dist/core/registry/params/icoutcall.job.terminate.json +39 -0
  82. package/dist/core/registry/params/icoutcall.phone.getLineList.json +32 -0
  83. package/dist/core/registry/params/ipcc.calltask.add.auto.json +117 -0
  84. package/dist/core/registry/params/ipcc.calltask.add.byCustom.json +96 -0
  85. package/dist/core/registry/params/ipcc.calltask.add.byRelation.json +82 -0
  86. package/dist/core/registry/params/ipcc.calltask.add.toGroup.json +89 -0
  87. package/dist/core/registry/params/ipcc.calltask.add.toStaff.json +89 -0
  88. package/dist/core/registry/params/ipcc.calltask.get.json +47 -0
  89. package/dist/core/registry/params/ipcc.calltaskdetail.add.json +54 -0
  90. package/dist/core/registry/params/ipcc.calltaskdetail.delete.json +40 -0
  91. package/dist/core/registry/params/ipcc.calltaskdetail.get.json +54 -0
  92. package/dist/core/registry/params/ipcc.calltaskdetail.update.json +40 -0
  93. package/dist/core/registry/params/ipcc.customfield.template.get.json +47 -0
  94. package/dist/core/registry/params/ipcc.login.json +47 -0
  95. package/dist/core/registry/params/kefu.add.json +130 -0
  96. package/dist/core/registry/params/kefu.delete.json +39 -0
  97. package/dist/core/registry/params/kefu.update.json +137 -0
  98. package/dist/core/registry/params/kefu.v2.query.json +39 -0
  99. package/dist/core/registry/params/kefuGroup.add.json +39 -0
  100. package/dist/core/registry/params/kefuGroup.delete.json +39 -0
  101. package/dist/core/registry/params/kefuGroup.update.json +46 -0
  102. package/dist/core/registry/params/kefuGroup.updateKefus.json +46 -0
  103. package/dist/core/registry/params/merchant.account.login.json +53 -0
  104. package/dist/core/registry/params/merchant.changePassword.json +46 -0
  105. package/dist/core/registry/params/merchant.create.json +81 -0
  106. package/dist/core/registry/params/merchant.disable.json +39 -0
  107. package/dist/core/registry/params/merchant.enable.json +39 -0
  108. package/dist/core/registry/params/merchant.list.json +46 -0
  109. package/dist/core/registry/params/merchant.query.json +46 -0
  110. package/dist/core/registry/params/merchant.update.json +74 -0
  111. package/dist/core/registry/params/message.send.image.json +53 -0
  112. package/dist/core/registry/params/message.send.json +53 -0
  113. package/dist/core/registry/params/message.send.voice.json +53 -0
  114. package/dist/core/registry/params/message.sendFile.json +39 -0
  115. package/dist/core/registry/params/message.uploadFile.json +39 -0
  116. package/dist/core/registry/params/online.session.category.list.json +39 -0
  117. package/dist/core/registry/params/online.session.customfield.template.json +39 -0
  118. package/dist/core/registry/params/online.session.customfield.update.json +74 -0
  119. package/dist/core/registry/params/order.upload.json +40 -0
  120. package/dist/core/registry/params/push.msg.image.json +74 -0
  121. package/dist/core/registry/params/push.msg.richText.json +74 -0
  122. package/dist/core/registry/params/push.msg.text.json +74 -0
  123. package/dist/core/registry/params/receive.message.json +89 -0
  124. package/dist/core/registry/params/robot.data.getQuestionsByCategoryName.json +67 -0
  125. package/dist/core/registry/params/robot.data.knowledge.json +46 -0
  126. package/dist/core/registry/params/robot.data.kpoint.json +46 -0
  127. package/dist/core/registry/params/robot.data.queryStandardByEffectiveQuestion.json +46 -0
  128. package/dist/core/registry/params/robot.data.queryStandardQuestionList.json +46 -0
  129. package/dist/core/registry/params/robot.evaluation.comment.json +67 -0
  130. package/dist/core/registry/params/robot.evaluation.setting.json +46 -0
  131. package/dist/core/registry/params/robot.session.assist.json +74 -0
  132. package/dist/core/registry/params/robot.session.chat.json +74 -0
  133. package/dist/core/registry/params/robot.session.close.json +53 -0
  134. package/dist/core/registry/params/robot.session.commonQuestions.json +74 -0
  135. package/dist/core/registry/params/robot.session.create.json +81 -0
  136. package/dist/core/registry/params/robot.session.evaluation.json +67 -0
  137. package/dist/core/registry/params/robot.session.msgAssociate.json +46 -0
  138. package/dist/core/registry/params/robot.session.msgEvaluation.json +53 -0
  139. package/dist/core/registry/params/robot.session.msgPredict.json +74 -0
  140. package/dist/core/registry/params/robot.session.transfer.json +36 -0
  141. package/dist/core/registry/params/robot.session.uploadFile.json +32 -0
  142. package/dist/core/registry/params/robot.statistic.summary.json +53 -0
  143. package/dist/core/registry/params/robot.transfer.config.json +15 -0
  144. package/dist/core/registry/params/session.user.profile.json +39 -0
  145. package/dist/core/registry/params/settings.wxTemplates.json +46 -0
  146. package/dist/core/registry/params/smstask.create.json +53 -0
  147. package/dist/core/registry/params/smstask.status.json +39 -0
  148. package/dist/core/registry/params/staff.group.list.new.json +39 -0
  149. package/dist/core/registry/params/staff.group.members.new.json +46 -0
  150. package/dist/core/registry/params/staff.list.new.json +46 -0
  151. package/dist/core/registry/params/staff.login.json +47 -0
  152. package/dist/core/registry/params/statistic.overview.json +61 -0
  153. package/dist/core/registry/params/statistic.performance.json +82 -0
  154. package/dist/core/registry/params/statistic.salaryDetail.json +54 -0
  155. package/dist/core/registry/params/statistic.satisfaction.report.json +68 -0
  156. package/dist/core/registry/params/statistic.staffAttendance.json +75 -0
  157. package/dist/core/registry/params/statistic.staffquality.json +75 -0
  158. package/dist/core/registry/params/statistic.staffworklod.json +68 -0
  159. package/dist/core/registry/params/tag.all.json +32 -0
  160. package/dist/core/registry/params/tag.batchUpdate.json +32 -0
  161. package/dist/core/registry/params/tag.update.json +60 -0
  162. package/dist/core/registry/params/ticket.apply.json +46 -0
  163. package/dist/core/registry/params/ticket.batch.modify.json +53 -0
  164. package/dist/core/registry/params/ticket.create.json +151 -0
  165. package/dist/core/registry/params/ticket.filter.count.json +46 -0
  166. package/dist/core/registry/params/ticket.filter.list.json +46 -0
  167. package/dist/core/registry/params/ticket.finish.json +60 -0
  168. package/dist/core/registry/params/ticket.followers.update.json +60 -0
  169. package/dist/core/registry/params/ticket.list.json +74 -0
  170. package/dist/core/registry/params/ticket.log.json +39 -0
  171. package/dist/core/registry/params/ticket.modify.json +74 -0
  172. package/dist/core/registry/params/ticket.new.detail.json +39 -0
  173. package/dist/core/registry/params/ticket.reminder.json +60 -0
  174. package/dist/core/registry/params/ticket.reopen.json +67 -0
  175. package/dist/core/registry/params/ticket.reply.json +60 -0
  176. package/dist/core/registry/params/ticket.search.json +116 -0
  177. package/dist/core/registry/params/ticket.template.fields.json +39 -0
  178. package/dist/core/registry/params/ticket.template.list.json +39 -0
  179. package/dist/core/registry/params/ticket.transfer.json +74 -0
  180. package/dist/core/registry/params/track.event.set.json +32 -0
  181. package/dist/core/registry/params/wecom.robot.switch.json +43 -0
  182. package/dist/core/registry/params.js +84 -0
  183. package/dist/core/registry/specs.json +2172 -0
  184. package/dist/core/registry/validate.json +11 -0
  185. package/dist/core/registry/validation-overrides.js +98 -0
  186. package/dist/core/sanitize.js +24 -0
  187. package/dist/core/sign.js +21 -0
  188. package/dist/core/time.js +194 -0
  189. package/dist/core/validate.js +140 -0
  190. package/dist/output.js +263 -0
  191. package/dist/postinstall.js +178 -0
  192. package/dist/query/errors.js +395 -0
  193. package/dist/query/mask.js +368 -0
  194. package/dist/query/metric-catalog.js +85 -0
  195. package/dist/query/sandbox.js +544 -0
  196. package/dist/query/table-query.js +297 -0
  197. package/dist/query/time-shape.js +44 -0
  198. package/dist/schedule/install.js +377 -0
  199. package/dist/skill/check.js +429 -0
  200. package/dist/skill/detect.js +336 -0
  201. package/dist/skill/install.js +1202 -0
  202. package/dist/skill/paths.js +343 -0
  203. package/dist/skill/qiyu/SKILL.md +86 -0
  204. package/dist/skill/qiyu/errors.md +55 -0
  205. package/dist/skill/qiyu/forbidden.md +52 -0
  206. package/dist/skill/qiyu/metrics.md +65 -0
  207. package/dist/skill/qiyu/protocols.md +55 -0
  208. package/dist/skill/qiyu/setup.md +50 -0
  209. package/dist/skill/refs.js +379 -0
  210. package/dist/store/config.js +137 -0
  211. package/dist/store/duckdb.js +321 -0
  212. package/dist/store/index.js +18 -0
  213. package/dist/store/retry.js +36 -0
  214. package/dist/store/schema.js +419 -0
  215. package/dist/store/types.js +4 -0
  216. package/dist/sync/day.js +8 -0
  217. package/dist/sync/engine.js +818 -0
  218. package/dist/sync/rate-gate.js +95 -0
  219. package/dist/sync/registry.js +22 -0
  220. package/dist/sync/state.js +114 -0
  221. package/dist/sync/tasks/dim.js +186 -0
  222. package/dist/sync/tasks/knowledge.js +252 -0
  223. package/dist/sync/tasks/pace.js +66 -0
  224. package/dist/sync/tasks/pipeline.js +321 -0
  225. package/dist/sync/tasks/reports.js +448 -0
  226. package/dist/sync/tasks/sessions.js +188 -0
  227. package/dist/sync/tasks/tickets.js +219 -0
  228. package/dist/sync/types.js +1 -0
  229. package/dist/sync/windowing.js +56 -0
  230. package/package.json +52 -4
@@ -0,0 +1,564 @@
1
+ import { suggestNames, thrownToQueryExit, driftFailureFor, emitQueryFailure } from '../query/errors.js';
2
+ import { maskQueryRows } from '../query/mask.js';
3
+ import { parseTimeArg, shanghaiIso, msToShanghaiIso, shanghaiYesterdayStart } from '../core/time.js';
4
+ import { TABLES, tableByName } from '../store/schema.js';
5
+ import { buildCoverageQuery, buildMinQuery, buildTableQuery, effectiveBound, validateGroupBy, } from '../query/table-query.js';
6
+ import { openGuardedSession } from './db.js';
7
+ import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty } from '../output.js';
8
+ import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, REJECTED_FLAGS, STORE_FLAGS, valueFlagNames } from './spec-types.js';
9
+ /**
10
+ * `query` 的业务 flag。`--group-by` 标 `repeatable`:可重复给(每次吃一个值)。
11
+ * 存储定位三件套直接用 `STORE_FLAGS`(与 `parseStoreFlags` 同一份事实源)。
12
+ */
13
+ const QUERY_FLAGS = [
14
+ { name: '--sql', kind: 'value' },
15
+ { name: '--table', kind: 'value' },
16
+ { name: '--since', kind: 'value' },
17
+ { name: '--until', kind: 'value' },
18
+ { name: '--group-by', kind: 'repeatable' },
19
+ { name: '--limit', kind: 'value' },
20
+ { name: '--timeout', kind: 'value' },
21
+ { name: '--no-mask', kind: 'bool' },
22
+ ...STORE_FLAGS,
23
+ ];
24
+ /**
25
+ * 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu query …` 是否真的存在。
26
+ * `flags` 是**完整接受集**(含全局 flag),`--pretty` 同时在 `rejected` 里。
27
+ * `query` 没有位置参数:表名走 `--table <表>` 的**值位**,不是位置参数。
28
+ */
29
+ export const QUERY_SPECS = [
30
+ {
31
+ path: ['query'],
32
+ flags: [...GLOBAL_FLAGS, ...QUERY_FLAGS],
33
+ positionals: [],
34
+ rejected: REJECTED_FLAGS,
35
+ },
36
+ ];
37
+ const USAGE = `用法:qiyu query <查询方式> [参数]
38
+
39
+ 查询方式(二选一):
40
+ query --sql <SQL> 任意只读 SQL(三层只读沙箱 + 默认脱敏 + 行数上限 + 超时)
41
+ query --table <表> 受约束查询通道(TABLES 闭集校验 + 时间过滤 + 分组计数 + 默认脱敏)
42
+
43
+ 参数:
44
+ --since <时间> 起始时间(仅 --table):Nd / yesterday / YYYY-MM-DD / ISO 8601,按 Asia/Shanghai 解析
45
+ --until <时间> 结束时间(仅 --table):同上;日期型时间列含 --until 所在自然日全天
46
+ --group-by <列> 按列分组计数(仅 --table,可重复给多列;不接受敏感列)
47
+ --limit <n> 最多返回行数,1–10000 的整数(默认 1000)
48
+ --timeout <秒> 超时秒数,非负数,0 = 无超时(默认 30)
49
+ --no-mask 关闭默认脱敏,输出原始 PII(不要写入日志或对外报表)
50
+ --db <path> / --profile <name> / --backend <name>
51
+ 存储定位(与 store / sync 命令同族)
52
+
53
+ 只接受单条 SELECT / DESCRIBE / SHOW / EXPLAIN;写操作、多语句、文件与网络访问一律被沙箱拦截。
54
+ `;
55
+ const KNOWN = new Set(GLOBAL_FLAG_NAMES);
56
+ /**
57
+ * 值位参数(缺值或值以 `--` 开头 → 报缺值,防止把下一个 flag 当取值)。
58
+ * 从 `QUERY_FLAGS` 派生而不是手写:`--db/--profile/--backend` 与 spec 的 `STORE_FLAGS`
59
+ * 同源,`--group-by` 以 `repeatable` 形态自动落入值位。
60
+ */
61
+ const VALUE_FLAGS = new Set(valueFlagNames(QUERY_FLAGS));
62
+ /**
63
+ * 全部已知 flag token(含布尔 flag 与 help/pretty)。
64
+ * 值位守卫用它区分两件事:「取值恰好是下一个 flag」(真缺值)与
65
+ * 「取值只是以 `--` 开头」(SQL 的行注释,合法输入)。
66
+ */
67
+ const FLAG_TOKENS = new Set([...VALUE_FLAGS, ...QUERY_FLAGS.map((f) => f.name), ...GLOBAL_FLAG_NAMES]);
68
+ /**
69
+ * 超时上界 = Node 定时器的最大延迟(2^31−1 ms)。超过它 setTimeout 会**溢出成 1ms**
70
+ * 立即触发 —— 用户本想「几乎不限时」却得到「立刻超时」,是静默的语义反转,必须拒绝。
71
+ */
72
+ const TIMEOUT_MAX_MS = 2_147_483_647;
73
+ /**
74
+ * 0 行警告的触发正则(spec §十):SQL 文本命中任一业务时间列名即认为这是一次
75
+ * 时间过滤查询 —— 0 行更可能是同步未覆盖该区间,而不是「那段时间真没有数据」。
76
+ */
77
+ // ⚠️ 大小写不敏感(契约审查 C-02):DuckDB 标识符不分大小写,`WHERE STARTTIME …`
78
+ // 是合法 SQL;敏感匹配会让 0 行警告静默失效(正是「0 行 ≠ 没有数据」要防的场景)。
79
+ const ZERO_ROW_TIME_RE = /\b(stat_date|work_date|hour_ts|startTime|endTime)\b/i;
80
+ /** 0 行警告的后半句(两个通道同源);前半句各自说明触发条件与实际区间。 */
81
+ const ZERO_ROW_HINT = '这不代表没有数据:同步可能未覆盖该区间——用 `qiyu sync status` 查看覆盖范围,或放宽过滤条件';
82
+ /**
83
+ * iso-day 字面量比较警告(端到端场景 F3,`--sql` 通道)。
84
+ *
85
+ * `stat_date`/`work_date` 这类 iso-day 列**列内实为 UTC `…Z` 形态**(`2026-10-12T16:00:00.000Z`
86
+ * = 上海 10/13 00:00),而 CLI 的元数据出口(`db tables.time_range`、`db describe.unit`、
87
+ * `resolved_range`)一律呈现 +08:00 形态 —— Agent 会照着自己读到的形态写
88
+ * `WHERE stat_date >= '2026-10-13T00:00:00+08:00'`,而列是 VARCHAR、按**字典序**比较:
89
+ * `'2026-10-12T16:00:00.000Z' >= '2026-10-13T00:00:00+08:00'` 为 false,整整少一天,
90
+ * 退出码 0、四道自证机制一道都不响。
91
+ *
92
+ * 判据 = SQL 文本同时含 iso-day 列名与「日期形态字面量」(纯 `YYYY-MM-DD` 或缺时刻的
93
+ * `…T00:00:00+08:00`)——即 CLI 自己教出去、却在 `--sql` 里比较错的那种写法。
94
+ * 方向安全(多警告):误报只多一句话;UTC `…Z` 形态与 `--table` 通道不受影响。
95
+ */
96
+ // ⚠️ 大小写不敏感,理由同上(`STAT_DATE >= '2026-10-13'` 同样会少一天)。
97
+ const ISO_DAY_COL_RE = /\b(stat_date|work_date)\b/i;
98
+ // ⚠️ 必须同时接受 `T` 与**空格**分隔(场景审查 4):SQL 里 `'2026-10-12 00:00:00'` 是
99
+ // 与 `'…T00:00:00'` 等价的合法写法,旧正则只认 `T` → 空格形态静默少算一天、零 warning。
100
+ const DAY_LITERAL_RE = /'\d{4}-\d{2}-\d{2}([T ]00:00:00(\.0+)?(\+08:00)?)?'/;
101
+ const ISO_DAY_LITERAL_HINT = '该列列内是 UTC `…Z` 形态的字符串(上海日零点 = 前一日 16:00Z),按字典序比较,' +
102
+ '日期字面量会**少算或漏掉当天**。要在 --sql 里过滤请写 UTC 形态(如 \'2026-10-12T16:00:00.000Z\'),' +
103
+ '或改用 `qiyu query --table <表> --since/--until`(该通道已处理取整语义)';
104
+ /**
105
+ * 截断警告(两个通道**文案必须分开**)。
106
+ *
107
+ * ⚠️ 措辞必须同时点破两件事(设计稿 §9.2「0 行是比报错危险得多的失败模式」的同源推理):
108
+ * ① 返回的行数不是全部;② **被切掉的那部分里可能正好有缺失数据的窗口**——Agent 看到
109
+ * `truncated:true` 时注意力天然落在「已返回的这些行」上,于是「同步缺口」这类只有看过
110
+ * 全量才能发现的问题被静默跳过。所以警告里要给出替代路径,而不只是说「结果被截断了」。
111
+ *
112
+ * ⚠️ 替代路径**必须在该通道、该表上真的可行**(复审 Minor-2 → PR 前审查 Important):
113
+ * · `--sql` 通道:`--since/--until/--group-by` 与 `--sql` 同用会被拒,只能让它改 SQL 的 WHERE;
114
+ * · `--table` 通道:`--since/--until` 对**无时间列的表**会被拒(25 张表里有 10 张没有
115
+ * `timeColumn`)——对这些表只能建议 `--group-by`(任何表都支持)与 `db describe`。
116
+ */
117
+ function truncationWarning(returned, limit, channel, hasTimeColumn = true) {
118
+ const head = `结果被 --limit ${limit} 截断,本次只返回 ${returned} 行(不是全部);`
119
+ + '聚合与「是否存在数据缺口」的判断都不应基于这批不完整的结果——';
120
+ if (channel === 'sql') {
121
+ return head + '请在 SQL 里加 WHERE 条件收窄,或用 `qiyu db describe <表>` 看总行数与时间范围';
122
+ }
123
+ return head + (hasTimeColumn
124
+ ? '请用 `qiyu db describe <表>` 看总行数与时间范围,或加过滤条件(--since/--until/--group-by)收窄'
125
+ : '请用 `qiyu db describe <表>` 看总行数,或用 `--group-by <列>` 聚合成计数收窄'
126
+ + '(该表没有时间列,不接受 --since/--until)');
127
+ }
128
+ function parseFlags(argv) {
129
+ const out = { noMask: false, groupBy: [], rest: [] };
130
+ for (let i = 0; i < argv.length; i++) {
131
+ const a = argv[i];
132
+ if (VALUE_FLAGS.has(a)) {
133
+ const v = argv[i + 1];
134
+ // 值位守卫(沿 store.ts / db.ts):值位缺失,或取值**恰好是已知 flag** → 报缺值,
135
+ // 否则 `query --sql --limit 2` 会把 --limit 当成 SQL 文本。
136
+ // ⚠️ `--sql` 只拒绝「恰好是已知 flag」的值:SQL 以 `--` 开头是合法行注释
137
+ // (`--sql '-- 注释\nSELECT 1'` 必须能跑)。路径/名字/数字/时间的合法取值不会以 `--`
138
+ // 开头,所以其余值位参数仍按前缀拒绝。
139
+ if (v === undefined || (a === '--sql' ? FLAG_TOKENS.has(v) : v.startsWith('--'))) {
140
+ throw new Error(`${a} 缺少取值`);
141
+ }
142
+ if (a === '--sql')
143
+ out.sql = v;
144
+ else if (a === '--table')
145
+ out.table = v;
146
+ else if (a === '--since')
147
+ out.since = v;
148
+ else if (a === '--until')
149
+ out.until = v;
150
+ else if (a === '--group-by')
151
+ out.groupBy.push(v); // 可重复(spec §六)
152
+ else if (a === '--limit')
153
+ out.limit = v;
154
+ else if (a === '--timeout')
155
+ out.timeout = v;
156
+ else if (a === '--db')
157
+ out.db = v;
158
+ else if (a === '--profile')
159
+ out.profile = v;
160
+ else
161
+ out.backend = v;
162
+ i++;
163
+ }
164
+ else if (a === '--no-mask') {
165
+ out.noMask = true;
166
+ }
167
+ else if (a === '--pretty') {
168
+ // G1:已知输出开关(不带值)。不收下会落进 rest 被报成「未知参数:--pretty」。
169
+ // 值位守卫仍优先:`--sql --pretty` 报「--sql 缺少取值」(--pretty ∈ FLAG_TOKENS)。
170
+ continue;
171
+ }
172
+ else
173
+ out.rest.push(a);
174
+ }
175
+ return out;
176
+ }
177
+ /** `--limit`:1–10000 的整数(spec §5.3;越界/非整数一律 usage,不做静默钳制)。 */
178
+ function parseLimit(raw) {
179
+ if (raw === undefined)
180
+ return 1000;
181
+ const n = Number(raw);
182
+ if (raw.trim() === '' || !Number.isInteger(n) || n < 1 || n > 10000) {
183
+ throw new Error(`--limit 必须是 1–10000 的整数,收到:${describeArgs([raw])}`);
184
+ }
185
+ return n;
186
+ }
187
+ /**
188
+ * `--timeout`:非负秒数,0 = 无超时(spec §5.3)。
189
+ * ⚠️ 极小正数(如 0.0001)四舍五入后是 0ms —— 若原样传给沙箱就变成「无超时」,
190
+ * 与用户意图相反;钳到 1ms,保证「给了正数就真的有超时」。
191
+ * ⚠️ 上界见 `TIMEOUT_MAX_MS`:超过 Node 定时器上限会溢出成立即超时,必须拒绝。
192
+ */
193
+ function parseTimeoutMs(raw) {
194
+ if (raw === undefined)
195
+ return 30_000;
196
+ const n = Number(raw);
197
+ if (raw.trim() === '' || !Number.isFinite(n) || n < 0) {
198
+ throw new Error(`--timeout 必须是非负数(秒,0 = 无超时),收到:${describeArgs([raw])}`);
199
+ }
200
+ const ms = Math.round(n * 1000);
201
+ if (ms > TIMEOUT_MAX_MS) {
202
+ throw new Error(`--timeout 过大(上限 ${TIMEOUT_MAX_MS / 1000} 秒),收到:${describeArgs([raw])};` +
203
+ '再大会溢出 Node 定时器、变成立即超时。若想不限时请用 --timeout 0');
204
+ }
205
+ return n > 0 && ms === 0 ? 1 : ms;
206
+ }
207
+ /**
208
+ * 时间参数归一(形态沿 `src/commands/sync-run.ts`):`Nd`/`yesterday` 返回完整区间
209
+ * (`--since` 取 .start、`--until` 取 .end);`YYYY-MM-DD`/ISO 返回时刻。
210
+ * 无法解析 → 抛错(命令层转 usage),不静默当成「无过滤」。
211
+ *
212
+ * ⚠️ `--until` 取区间形态时**必须减 1ms**,与 sync-run.ts 的 `.end` 不同:
213
+ * `parseTimeArg` 返回的是**半开窗口** `[start, end)`(`yesterday` = `[昨天0点, 今天0点)`)。
214
+ * sync-run 拿 `.end` 当窗口右端(半开,正确);而查询的谓词是**闭区间** `<=`,
215
+ * 直接把 `.end` 当上界会多含一天:iso-day 列取整后上界落在「今天 0 点」,正好等于
216
+ * 今天那行的 stat_date —— 用户说「只要昨天」却拿到昨天 + 今天,退出码 0、无 warning。
217
+ * 减 1ms 后 iso-day 取整得昨天 0 点(正确)、iso-instant/epoch-ms 得 `…23:59:59.999`
218
+ * (正确)。**这不是笔误,改回 `.end` 会把静默多算一天重新引入。**
219
+ */
220
+ function resolveTimeFlag(raw, label, clock) {
221
+ if (raw === undefined)
222
+ return undefined;
223
+ const v = parseTimeArg(raw, clock, label);
224
+ if (v === null) {
225
+ throw new Error(`${label} 无法解析:${describeArgs([raw])}。支持 Nd / yesterday / YYYY-MM-DD / ISO 8601(按 Asia/Shanghai)`);
226
+ }
227
+ if (typeof v !== 'object')
228
+ return v;
229
+ return label === '--since' ? v.start : v.end - 1;
230
+ }
231
+ /**
232
+ * 查表 MIN 的返回值 → epoch 毫秒(契约 B)。
233
+ * epoch-ms 列经 MIN(TRY_CAST) 出来是 BIGINT(JSON 安全值是字符串);iso 列是 ISO 字符串。
234
+ * 无值/不可解析 → null(不编造一个边界)。
235
+ */
236
+ function toEpochMs(v, kind) {
237
+ if (v === null || v === undefined || v === '')
238
+ return null;
239
+ const n = kind === 'epoch-ms' ? Number(v) : Date.parse(String(v));
240
+ return Number.isFinite(n) ? n : null;
241
+ }
242
+ /** 0 行警告(spec §十):说明**实际生效**的区间,没有完整区间时如实说明。 */
243
+ function zeroRowWarning(range, tc, until) {
244
+ if (range !== null) {
245
+ return `查询在区间 [${shanghaiIso(range[0])}, ${shanghaiIso(range[1])}] 返回 0 行。${ZERO_ROW_HINT}`;
246
+ }
247
+ if (tc !== undefined && until !== undefined) {
248
+ return `查询在上限 ${shanghaiIso(effectiveBound(tc.kind, until))}(下界未能解析)返回 0 行。${ZERO_ROW_HINT}`;
249
+ }
250
+ return `查询在给定时间条件下返回 0 行。${ZERO_ROW_HINT}`;
251
+ }
252
+ /**
253
+ * `--table` 的执行路径(spec §六):解析缺省下界 → 主查询 → 覆盖统计 → 脱敏 → 信封。
254
+ * 所有 SQL 由 `query/table-query.ts` 的纯函数构造(表/列已过闭集)。
255
+ */
256
+ async function runTableQuery(session, input) {
257
+ const { table } = input;
258
+ const tc = table.timeColumn;
259
+ const warnings = [];
260
+ // 只给 --until:先查该表时间列下界(契约 B)。空表 → 不解析,交给纯函数出 warning。
261
+ // 超时预算与主查询同一口径(--timeout 0 = 不限时)。
262
+ let tableMin;
263
+ if (tc !== undefined && input.since === undefined && input.until !== undefined) {
264
+ const minRow = (await session.run(buildMinQuery(table).sql, { timeoutMs: input.timeoutMs }))
265
+ .rows[0] ?? {};
266
+ tableMin = toEpochMs(minRow.mn, tc.kind);
267
+ }
268
+ let plan;
269
+ try {
270
+ plan = buildTableQuery({
271
+ table, since: input.since, until: input.until, tableMin,
272
+ groupBy: input.groupBy, now: input.now,
273
+ });
274
+ }
275
+ catch (e) {
276
+ return usageFail(sanitizeControlChars(e.message));
277
+ }
278
+ warnings.push(...plan.warnings);
279
+ const result = await session.run(plan.sql, {
280
+ params: plan.params, limit: input.limit, timeoutMs: input.timeoutMs,
281
+ });
282
+ // data_coverage(契约 D):表有 timeColumn 时**恒计算**,独立查询、不受 limit 截断影响;
283
+ // 过滤范围与主查询同一谓词(不是全表 MIN/MAX)。
284
+ let dataCoverage = null;
285
+ // 区间内实际覆盖的自然日数(仅 iso-day 表有值)——用于发现窗口内部的空洞(场景 F4)。
286
+ let coveredDays = null;
287
+ if (tc !== undefined) {
288
+ const cov = buildCoverageQuery({
289
+ table, since: input.since, until: input.until, tableMin, now: input.now,
290
+ });
291
+ const row = (await session.run(cov.sql, { params: cov.params, timeoutMs: input.timeoutMs }))
292
+ .rows[0] ?? {};
293
+ if (row.mn !== null && row.mn !== undefined && row.mx !== null && row.mx !== undefined) {
294
+ dataCoverage = {
295
+ min: msToShanghaiIso(row.mn),
296
+ max: msToShanghaiIso(row.mx),
297
+ };
298
+ }
299
+ if (row.days !== null && row.days !== undefined)
300
+ coveredDays = Number(row.days);
301
+ }
302
+ // 脱敏唯一出口(spec §7.2);--table 通道按列精确命中(mode.kind='table')。
303
+ const masked = maskQueryRows({
304
+ rows: result.rows, columns: result.columns,
305
+ mode: { kind: 'table', table }, noMask: input.noMask,
306
+ });
307
+ // 库漂移「声明有而实际无」(场景审查 9):`SELECT *` 只返回库里真实存在的列,
308
+ // 被删掉的列(旧版 CLI/外部工具改过库)会**静默消失**,而 `db tables`/`db describe`
309
+ // 对同一状态会警告。这里补一条,与 `--table` 通道的「表定义之外的列」警告对称。
310
+ // group-by 只返回分组列,缺列是预期行为,不检查。
311
+ const missingCols = input.groupBy.length > 0
312
+ ? []
313
+ : table.columns.map((c) => c.name).filter((n) => !result.columns.includes(n));
314
+ if (missingCols.length > 0) {
315
+ warnings.push(`库中缺列 ${missingCols.join('、')}(表 ${table.name} 的定义里有、实际没有):`
316
+ + '可能来自旧版 CLI 或库损坏;`qiyu db describe ' + table.name + '` 可核对声明与实况的差异');
317
+ }
318
+ // ⚠️ `COUNT(*)` 经 getRowObjectsJson 是**字符串**(BIGINT)—— 输出必须是 number,
319
+ // 否则 Agent 拿 `"count": "3"` 做算术会静默出错(与 db describe 的 Number() 同款)。
320
+ const rows = input.groupBy.length > 0
321
+ ? masked.rows.map((r) => ({ ...r, count: Number(r.count) }))
322
+ : masked.rows;
323
+ // 0 行 ≠ 没有数据(spec §十 / 红线 3):给了时间过滤而 0 行时附可操作提示。
324
+ if (result.rows.length === 0 && (input.since !== undefined || input.until !== undefined)) {
325
+ warnings.push(zeroRowWarning(plan.resolvedRange, tc, input.until));
326
+ }
327
+ else if (result.rows.length === 0) {
328
+ // 没给时间过滤也 0 行:spec §十 把「空表」列为 warnings 的触发条件。
329
+ // 这里必须能区分「表空」与「查询没命中」—— `--table` 通道没有 WHERE 子句(除了时间过滤),
330
+ // 所以 0 行且无时间过滤**只可能**是表里没有行。文案与 `stats fields` 的空表警告同源。
331
+ // ⚠️ 不看 warnings 是否已有其他条目(CodeRabbit inline minor):走到这里的其他警告
332
+ // 只有「库中缺列」漂移(plan.warnings 只在给了时间过滤时非空,那走上一分支)——
333
+ // 缺列说的是 schema、空表说的是数据,两件独立事实都该说;压掉后者 Agent 会把
334
+ // 「0 行」误读成缺列的副作用。
335
+ warnings.push('该表无数据;先运行 `qiyu sync run`');
336
+ }
337
+ // 窗口内部空洞(端到端场景 F4):iso-day 表 + 完整区间时,比较「区间应覆盖的自然日数」
338
+ // 与「实际有行的自然日数」。MIN/MAX 的 data_coverage 结构上看不见内部缺口 ——
339
+ // 7 天窗口缺一天时 rows 可能恰好是 7,Agent 会把 7 天汇总当成「上周」。
340
+ // 只在有行时提示:0 行已有更准确的成因警告(同步未覆盖 / 区间为空)。
341
+ //
342
+ // ⚠️ 上界缺省(只给 --since)时**必须排除今天**(CodeRabbit 终审 minor):日报任务的
343
+ // 日对齐切片会跳过当天那个不满一天的残段窗(`isResidualWindow`),所以今天那行要
344
+ // 次日 run 才出现。而缺省上界 = now 再向下取整到今天 0 点,不排除的话
345
+ // `--since 7d` 恒得到「应有 8 天、实际 7 天」——一条几乎每次都误报的警告,
346
+ // 只会教会 Agent 忽略 warnings。显式给了 --until 就按用户说的算,不做这种调整。
347
+ if (coveredDays !== null && plan.resolvedRange !== null && result.rows.length > 0) {
348
+ const hi = input.until === undefined
349
+ ? Math.min(plan.resolvedRange[1], shanghaiYesterdayStart(input.now))
350
+ : plan.resolvedRange[1];
351
+ // ⚠️ 缺口计数必须与 `expectedDays` 用**同一个上界**(正确性审查 F6):
352
+ // `coveredDays` 来自实际查询区间,缺省上界含今天;而 expectedDays 已排除今天。
353
+ // 今天只要有一行,就会把昨天的真缺口补满 → 零警告(实测:10/13–10/18 + 今天、
354
+ // 缺 10/19,`--since 7d` 输出 warnings: [])。这里按夹紧后的 hi 再算一次。
355
+ let daysInWindow = coveredDays;
356
+ if (hi < plan.resolvedRange[1]) {
357
+ const clamped = buildCoverageQuery({ ...input, until: hi });
358
+ const row = (await session.run(clamped.sql, {
359
+ params: clamped.params, timeoutMs: input.timeoutMs,
360
+ })).rows[0] ?? {};
361
+ daysInWindow = row.days === null || row.days === undefined ? coveredDays : Number(row.days);
362
+ }
363
+ const expectedDays = Math.max(0, Math.round((hi - plan.resolvedRange[0]) / 86_400_000) + 1);
364
+ if (daysInWindow < expectedDays) {
365
+ const scope = input.until === undefined ? '(不含今天:当天数据次日才同步)' : '';
366
+ warnings.push(`区间内应有 ${expectedDays} 个自然日${scope},实际只有 ${daysInWindow} 个有数据`
367
+ + '(窗口内部存在缺口);用 `qiyu sync status` 查看缺口详情,或放宽过滤条件');
368
+ }
369
+ }
370
+ // 截断不得静默(同上):`--limit` 生效时 Agent 读到的不是全量。
371
+ // 无时间列的表不能建议 --since/--until(那是条走不通的路),故传入 tc 是否存在。
372
+ if (result.truncated) {
373
+ warnings.push(truncationWarning(rows.length, input.limit, 'table', tc !== undefined));
374
+ }
375
+ // --no-mask 的风险警告属于「脱敏整体关闭」,进 meta.warnings;mask_warnings 只装
376
+ // 静态缺口警告(没脱敏就没有「脱敏不完整」可言)。spec §7.2。
377
+ const maskWarnings = input.noMask ? [] : masked.warnings;
378
+ if (input.noMask)
379
+ warnings.push(...masked.warnings);
380
+ return ok({ columns: result.columns, rows }, {
381
+ rows: rows.length,
382
+ truncated: result.truncated,
383
+ limit_applied: input.limit,
384
+ masked: !input.noMask,
385
+ masked_columns: masked.maskedColumns,
386
+ mask_warnings: maskWarnings,
387
+ warnings,
388
+ // 回显实际生效区间(不是用户原始输入):iso-day 两端都是上海日零点(契约 C)。
389
+ resolved_range: plan.resolvedRange === null
390
+ ? null
391
+ : [shanghaiIso(plan.resolvedRange[0]), shanghaiIso(plan.resolvedRange[1])],
392
+ data_coverage: dataCoverage,
393
+ });
394
+ }
395
+ export async function queryCommand(argv, deps = {}) {
396
+ setPretty(false); // G1:每条命令入口重置输出格式 —— 同一进程内多次 run(测试)不残留上一条命令的开关。
397
+ // 次序沿 store.ts / db.ts:--help 分流 → --pretty 开启缩进(G1) → parseStoreFlags → 未知参数。
398
+ // ⚠️ 本文件实际调用的是**自有的** `parseFlags`(语义故意不同:`--sql` 允许取值以 `--`
399
+ // 开头,见文件头);这一步在整条次序里的位置与 store.ts 的 parseStoreFlags 相同。
400
+ if (argv.includes('--help') || argv.includes('-h')) {
401
+ // --help 不吞额外参数;--pretty 豁免(同族惯例)。
402
+ // 措辞不用「未知参数」:`--sql` 是已知参数、只是不能与 --help 同时出现(同一条闸门)。
403
+ const extra = argv.filter((a) => !KNOWN.has(a));
404
+ if (extra.length > 0)
405
+ return usageFail(`--help 不接受额外参数:${extra.join(' ')}`);
406
+ process.stdout.write(USAGE);
407
+ return 0;
408
+ }
409
+ // G1:--pretty 已实现 —— 命令行合法即开启缩进输出(原拒绝点,次序不变)。
410
+ if (argv.includes('--pretty'))
411
+ setPretty(true);
412
+ let flags;
413
+ try {
414
+ flags = parseFlags(argv);
415
+ }
416
+ catch (e) {
417
+ return usageFail(sanitizeControlChars(e.message));
418
+ }
419
+ // describeArgs:空串/纯空白参数渲染成 `''`/`' '`,不让消息变成「未知参数:」冒号后空白。
420
+ if (flags.rest.length > 0)
421
+ return usageFail(`未知参数:${describeArgs(flags.rest)}`);
422
+ // —— 查询方式:互斥且至少给一个(spec §六)——
423
+ const { sql, table } = flags;
424
+ if (sql !== undefined && table !== undefined) {
425
+ return usageFail('--sql 与 --table 互斥,只能给一个');
426
+ }
427
+ // 时间/分组参数只属于 --table:与 --sql 同用时不能静默忽略(用户会以为过滤生效了)。
428
+ if (sql !== undefined
429
+ && (flags.since !== undefined || flags.until !== undefined || flags.groupBy.length > 0)) {
430
+ return usageFail('--since / --until / --group-by 只适用于 --table,不能与 --sql 同用;' +
431
+ '--sql 请把时间条件直接写进 SQL');
432
+ }
433
+ if (sql === undefined && table === undefined) {
434
+ return usageFail('缺少查询方式:请给 --sql <SQL> 或 --table <表>');
435
+ }
436
+ // 时钟只取一次:同一条命令里 Nd 的 end、缺省上界、区间校验必须站在同一时刻。
437
+ const nowMs = (deps.now ?? (() => Date.now()))();
438
+ // —— --table:闭集校验先于一切 I/O(拼错表/列名不必先打开库,db.ts 同款次序)——
439
+ let tableDef;
440
+ let sinceMs;
441
+ let untilMs;
442
+ if (table !== undefined) {
443
+ const name = sanitizeControlChars(table);
444
+ tableDef = tableByName(name);
445
+ if (tableDef === undefined) {
446
+ const candidates = suggestNames(name, TABLES.map((t) => t.name));
447
+ return usageFail(`未知表:${describeArgs([name])}`, candidates.length > 0 ? `候选:${candidates.join('、')}` : '用 `qiyu db tables` 查看可用表');
448
+ }
449
+ try {
450
+ validateGroupBy(tableDef, flags.groupBy);
451
+ sinceMs = resolveTimeFlag(flags.since, '--since', () => nowMs);
452
+ untilMs = resolveTimeFlag(flags.until, '--until', () => nowMs);
453
+ }
454
+ catch (e) {
455
+ return usageFail(sanitizeControlChars(e.message));
456
+ }
457
+ if (tableDef.timeColumn === undefined && (sinceMs !== undefined || untilMs !== undefined)) {
458
+ const usable = TABLES.filter((t) => t.timeColumn !== undefined).map((t) => t.name);
459
+ return usageFail(`表 ${tableDef.name} 没有时间列,不支持 --since/--until`, `支持时间过滤的表:${usable.join('、')}`);
460
+ }
461
+ }
462
+ let limit;
463
+ let timeoutMs;
464
+ try {
465
+ limit = parseLimit(flags.limit);
466
+ timeoutMs = parseTimeoutMs(flags.timeout);
467
+ }
468
+ catch (e) {
469
+ return usageFail(sanitizeControlChars(e.message));
470
+ }
471
+ // 配置解析 → 库前置检查 → 打开沙箱 → schema_version 探测:E 族三个命令共用同一条
472
+ // 路径(db.ts 的 openGuardedSession)。合并的理由见那里的注释:探测口径与文案
473
+ // 一旦三处各写一份,Agent 会在不同命令上得到互相矛盾的解释(架构审查 Important #2)。
474
+ const opened = await openGuardedSession({
475
+ db: flags.db, profile: flags.profile, backend: flags.backend,
476
+ });
477
+ if ('exit' in opened)
478
+ return opened.exit;
479
+ const session = opened.session;
480
+ try {
481
+ // 库结构校验(缺 schema_version → store_not_initialized)在 openGuardedSession 里
482
+ // 已做(E 族共用,口径见 db.ts 的注释)——这里不重复探测。
483
+ //
484
+ // ⚠️ 本命令特有的第二条:**目标表**在库中是否存在(端到端场景 F1)。
485
+ // `TABLES` 声明了它、`information_schema` 里没有 = 建库不完整或表被删,是环境问题
486
+ // 而非拼写错误。此前它会一路走到 SQL 执行、由 Catalog Error 翻译成「表 X 不存在 +
487
+ // 候选:<前缀相似的另一张表>」并返回退出码 2 —— Agent 会把库损坏读成自己写错,
488
+ // 并照候选去查一张口径完全不同的表。口径与 `stats fields` 一致(同一条 message 形态),
489
+ // hint 补上「声明有而库中无」的两种成因(不得承诺 store init 一定能修)。
490
+ if (tableDef !== undefined) {
491
+ const exists = await session.run("SELECT 1 FROM information_schema.tables WHERE table_schema='main' AND table_name='" +
492
+ tableDef.name + "'");
493
+ if (exists.rows.length === 0) {
494
+ return fail({
495
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
496
+ message: `数据库中缺表:${tableDef.name}(本表在 CLI 的表定义中存在,库里没有)`,
497
+ hint: '若为建库未完成(迁移未跑完),运行 qiyu store init 可补建缺失的迁移;'
498
+ + '若迁移已完成而表被删或损坏,store init 不会重建该表,重新同步也只会写入失败(缺表)'
499
+ + '——需重建库(删除库文件后重新 qiyu store init 并重新同步)。'
500
+ + '用 `qiyu db tables` 查看库中实际有数据的表',
501
+ });
502
+ }
503
+ }
504
+ if (tableDef !== undefined) {
505
+ return await runTableQuery(session, {
506
+ table: tableDef, since: sinceMs, until: untilMs, groupBy: flags.groupBy,
507
+ limit, timeoutMs, noMask: flags.noMask, now: nowMs,
508
+ });
509
+ }
510
+ // —— --sql 通道(上方「至少给一个」闸门 + 已返回的 --table 分支保证 sql 存在)——
511
+ const sqlText = sql;
512
+ const result = await session.run(sqlText, { limit, timeoutMs });
513
+ // 脱敏唯一出口(spec §7.2):列名级 + 值级兜底 + 缺口警告都在 mask.ts 内。
514
+ const masked = maskQueryRows({
515
+ rows: result.rows, columns: result.columns,
516
+ mode: { kind: 'sql', sql: sqlText, tables: TABLES }, noMask: flags.noMask,
517
+ });
518
+ // 0 行 ≠ 没有数据(spec §十 / 红线 3):时间过滤查询 0 行时附可操作提示。
519
+ const warnings = [];
520
+ if (result.rows.length === 0 && ZERO_ROW_TIME_RE.test(sqlText)) {
521
+ warnings.push(`查询返回 0 行,且 SQL 引用了业务时间列。${ZERO_ROW_HINT}`);
522
+ }
523
+ // iso-day 列 + 日期形态字面量 → 按字符串比较会少一天(场景 F3)。与 0 行无关:
524
+ // 非 0 行也可能已经悄悄少了一整天,这正是它危险的地方。
525
+ if (ISO_DAY_COL_RE.test(sqlText) && DAY_LITERAL_RE.test(sqlText)) {
526
+ warnings.push(ISO_DAY_LITERAL_HINT);
527
+ }
528
+ // 截断不得静默:Agent 会把「只看到前 N 行」当成事实(spec §十)。
529
+ if (result.truncated)
530
+ warnings.push(truncationWarning(masked.rows.length, limit, 'sql'));
531
+ // --no-mask 的风险警告属于「脱敏整体关闭」,进 meta.warnings;mask_warnings 只装
532
+ // 静态缺口警告(没脱敏就没有「脱敏不完整」可言)。spec §7.2。
533
+ const maskWarnings = flags.noMask ? [] : masked.warnings;
534
+ if (flags.noMask)
535
+ warnings.push(...masked.warnings);
536
+ return ok({ columns: result.columns, rows: masked.rows }, {
537
+ rows: masked.rows.length,
538
+ truncated: result.truncated,
539
+ limit_applied: limit,
540
+ masked: !flags.noMask,
541
+ masked_columns: masked.maskedColumns,
542
+ mask_warnings: maskWarnings,
543
+ warnings,
544
+ // --sql 通道无法通用判定请求区间与数据覆盖(spec §十):恒 null,不猜。
545
+ resolved_range: null,
546
+ data_coverage: null,
547
+ });
548
+ }
549
+ catch (e) {
550
+ // --table 通道的 SQL 是代码生成的:撞上库漂移时把原因说对(PR 前契约审查 Minor),
551
+ // 否则 Agent 会按「请检查 SQL 语法」去改它没写过的东西。
552
+ // `flags.noMask` 一路传到出口:转换错误会回显表里的真实值(CodeRabbit 终审 major),
553
+ // 只有显式 --no-mask 才允许原样输出。
554
+ if (tableDef !== undefined) {
555
+ const drift = driftFailureFor(tableDef, e);
556
+ if (drift !== null)
557
+ return emitQueryFailure(drift, flags.noMask);
558
+ }
559
+ return thrownToQueryExit(e, TABLES, flags.noMask);
560
+ }
561
+ finally {
562
+ await session.close();
563
+ }
564
+ }
@@ -0,0 +1,64 @@
1
+ // src/commands/skill-specs.ts —— skill 三条叶子命令的 `CommandSpec`(G3 审查 C1)。
2
+ //
3
+ // 为什么单独一个文件、而不是从 `commands/skill.ts` 导出:`skill.ts` import `tree.ts`
4
+ // (取 `COMMAND_TREE` 组装校验上下文),`tree.ts` 若反过来 import `skill.ts` 就是循环
5
+ // import。本文件是**叶子模块**:只 import `spec-types.ts`,skill.ts 与 tree.ts 各自从
6
+ // 这里取同一份事实,不经过对方。
7
+ //
8
+ // 为什么 flag 集不能在这里手写第二份:`skill.ts` 原本就有一套本地解析器(`parseFlags`
9
+ // 手写 value/repeat/bool 三类名单)。spec 与解析器各写一份,必然出现「spec 认了、解析器
10
+ // 不认」或反过来(`sync uninstall` 的 `--db` 就是前车之鉴)。所以三类名单定义在
11
+ // **本文件**,`skill.ts` 的解析器从 `skillFlagSpecs(path)` 派生——唯一事实源是 `SKILL_SPECS`,
12
+ // `tests/commands/command-tree.test.ts` 的行为式探针再钉住「spec 里的每个 flag 都被真实
13
+ // 解析器接受、且每个业务 flag 都被 spec 收录」。
14
+ //
15
+ // ⚠️ `positionals: []`:三个子命令都不接受位置参数(`skill.ts` 的 `prelude` 对任何
16
+ // 位置参数退 2「skill <sub> 不接受位置参数」)。`--link` 的取值是 agent 名而不是位置参数,
17
+ // 是 `kind: 'repeatable'` 的 flag 取值,不需要域;`--dir` 是路径,域模型表达不了自由路径,
18
+ // 校验方对 `value`/`repeatable` 的**取值**不做域比对(只比对位置参数),见 `skill/check.ts`。
19
+ import { GLOBAL_FLAGS, REJECTED_FLAGS } from './spec-types.js';
20
+ const FLAGS = {
21
+ // `--link` 可重复(点名多个 agent);`--no-link` 与它互斥,由命令层裁决(usageFail)。
22
+ install: [
23
+ ...GLOBAL_FLAGS,
24
+ { name: '--dir', kind: 'value' },
25
+ { name: '--link', kind: 'repeatable' },
26
+ { name: '--no-link', kind: 'bool' },
27
+ { name: '--force', kind: 'bool' },
28
+ { name: '--dry-run', kind: 'bool' },
29
+ ],
30
+ // `--installed` 与 `--compare` 互斥;`--dir` 只配合两者之一使用(命令层裁决)。
31
+ check: [
32
+ ...GLOBAL_FLAGS,
33
+ { name: '--installed', kind: 'bool' },
34
+ { name: '--compare', kind: 'bool' },
35
+ { name: '--dir', kind: 'value' },
36
+ ],
37
+ where: [
38
+ ...GLOBAL_FLAGS,
39
+ { name: '--dir', kind: 'value' },
40
+ ],
41
+ };
42
+ export const SKILL_SPECS = ['install', 'check', 'where'].map((sub) => ({
43
+ path: ['skill', sub],
44
+ flags: FLAGS[sub],
45
+ positionals: [],
46
+ rejected: REJECTED_FLAGS,
47
+ }));
48
+ /**
49
+ * 按子命令取三类 flag 名单,供 `skill.ts` 的解析器派生(`value`/`repeatable`/`bool`)。
50
+ *
51
+ * 分派层(`skill --help` / `skill --pretty`)只需要 `GLOBAL_FLAGS` 里的帮助开关,
52
+ * 那部分仍按 `GLOBAL_FLAG_NAMES` 派生,不经过这里。
53
+ */
54
+ export function skillFlagSpecs(sub) {
55
+ const flags = FLAGS[sub];
56
+ return {
57
+ value: flags.filter((f) => f.kind === 'value').map((f) => f.name),
58
+ repeat: flags.filter((f) => f.kind === 'repeatable').map((f) => f.name),
59
+ // `--pretty` 同时出现在 `GLOBAL_FLAGS`(因而是 bool)与 `REJECTED_FLAGS` 里:
60
+ // 解析器仍把它当已知 token 收下(G1 起它已是真实输出开关,不是「未知参数」),
61
+ // 与 spec 的建模一致(spec 里也是先 rejected 后 flags)。
62
+ bool: flags.filter((f) => f.kind === 'bool').map((f) => f.name),
63
+ };
64
+ }