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,145 @@
1
+ // src/commands/spec-types.ts —— F 组「技能契约校验」的类型底座:`CommandSpec` 是命令
2
+ // 接受哪些 flag / 位置参数的**唯一事实源**,由 `skill check` 用它比对 skill 正文里的
3
+ // `qiyu …` 引用(spec design D4)。
4
+ //
5
+ // 为什么不继续从 usage 散文里正则解析:散文已经与实现漂移了至少三处(顶层 USAGE 漏写
6
+ // `db`/`sync status` 的 store 三件套;`api schema` 曾写着 `[--pretty]` 却拒绝它——
7
+ // 该 flag 已于 2026-10-24 实现,此处保留这段漂移史作为该建模决定的例证)。
8
+ // 再扫一遍散文只会把「必然失败的命令」判成合法。
9
+ //
10
+ // 三条建模约束(不满足就退化成第二事实源):
11
+ // · `CommandSpec.flags` 必须是该命令的**完整接受集**,不是「额外的」flag。只记差异的话,
12
+ // skill 里写 `` `qiyu api list --no-validate` ``(真实用法错误)会被判通过。
13
+ // · 「完整」**包含全局 flag**:各命令组装 spec 时写成 `[...GLOBAL_FLAGS, ...业务 flag]`。
14
+ // 校验方只查这一份,不再另行合并(两处各合一次是漂移的来源)。若一个 flag 同时
15
+ // 出现在 `rejected` 与 `flags` 里,必须**先查 `rejected`**,否则会把它判合法——
16
+ // `--pretty` 曾是这种情形(现已实现,不再属于 `rejected`;次序规则保留)。
17
+ // · `--pretty` 曾建模成 `rejected`(承诺过、未实现):每个模块都用 `usageFail` 拒绝它,
18
+ // spec §11.2 E 也明令不要用。**2026-10-24(G1)起它已实现**(缩进 JSON),
19
+ // `REJECTED_FLAGS` 清空为空数组 —— **机制保留**(`rejected` 字段与 `skill check`
20
+ // 的 `rejected_flag` 规则都在,将来若再出现"已知但显式拒绝"的 flag 直接登记),
21
+ // 只是当前没有任何 flag 属于这一类。
22
+ //
23
+ // 本文件必须保持零依赖(只含类型、常量与几个纯函数):`core/`、`query/`、`sync/`
24
+ // 分层红线之外,它是 commands 层里最底层的一块,被各命令模块与 `tree.ts` 的
25
+ // `COMMAND_TREE` 共同消费。
26
+ /**
27
+ * 所有命令都接受的全局 flag(解析器里的 `KNOWN`)。
28
+ *
29
+ * ⚠️ `--pretty` 曾同时出现在 `REJECTED_FLAGS` 里,校验方必须先查 `rejected` 再查
30
+ * `flags`。**2026-10-24(G1)起它已实现**,`REJECTED_FLAGS` 为空 —— 顺序规则保留
31
+ * (机制仍在),将来再有"已知但显式拒绝"的 flag 时仍然先查 `rejected`。
32
+ */
33
+ export const GLOBAL_FLAGS = [
34
+ { name: '--help', kind: 'bool' },
35
+ { name: '-h', kind: 'bool' },
36
+ { name: '--pretty', kind: 'bool' },
37
+ ];
38
+ /**
39
+ * `GLOBAL_FLAGS` 的名字集合,供各解析器的 `KNOWN` 使用。
40
+ *
41
+ * 派生而不是手写:解析器的「已知 token 集」与 spec 的「完整接受集」必须同源,
42
+ * 否则加一个全局 flag 时两处会各自漂移(`--pretty` 就是这样同时存在于两者里的)。
43
+ */
44
+ export const GLOBAL_FLAG_NAMES = GLOBAL_FLAGS.map((f) => f.name);
45
+ /**
46
+ * 渲染「可用:…」错误文案里的 flag 清单。
47
+ *
48
+ * 为什么放在这里:文案里那份清单过去是手写的,与解析器接受的 flag 是**两份**事实源
49
+ * (`sync run` 的 `可用:--full --since …` 与它的解析条件各写一遍)。现在两边都从
50
+ * 同一个模块级 `FlagSpec[]` 派生,加 flag 时不会出现「解析器认了、文案没提」。
51
+ *
52
+ * `separator` 由调用方给:`api` 族用「、」,`sync run` 的历史文案用空格——**最终字符串
53
+ * 必须与改造前逐字一致**,多个测试钉着它们(如 `api.test.ts` 的 `可用:--body`)。
54
+ *
55
+ * ⚠️ 目前只有 `api list` 与 `sync run` 用它;`api call` / `api schema` 的文案带取值
56
+ * 占位符或点名的是 `rejected` flag,**保持字面量**(见 `api.ts` 的说明)。
57
+ */
58
+ export function renderFlagNames(flags, opts = {}) {
59
+ return flags.map((f) => f.name).join(opts.separator ?? '、');
60
+ }
61
+ /** 显式拒绝的 flag。**当前为空**(`--pretty` 已于 2026-10-24 实现),机制保留:
62
+ * 「已知但显式拒绝」是独立的错误类别(区别于「未知参数」),将来有新成员时直接登记这里,
63
+ * `skill check` 的 `rejected_flag` 规则会自动生效。 */
64
+ export const REJECTED_FLAGS = [];
65
+ /**
66
+ * `--pretty` 被写在**子命令之前**时的统一话术(G1)。
67
+ *
68
+ * 为什么不是「未知子命令」:`--pretty` 是真实存在、已实现的**输出格式开关**,
69
+ * 把它说成"未知子命令"是一句事实错误。它也确实不能改整个命令组 —— 输出开关
70
+ * 必须挂在**具体的那条叶命令**上(`store init --pretty`),因为要格式化的是
71
+ * 那条命令的 JSON。所以回答"怎么写才有效",而不是"你写错了"。
72
+ *
73
+ * 分派层的 8 个伪命令分支(cli/api/auth/store/sync/db/stats/skill)共用这一句,
74
+ * 同一形状的输入在各层得到同一答案。
75
+ */
76
+ export function prettyAfterSubcommand(group) {
77
+ return `--pretty 是输出格式开关,必须写在具体子命令之后(如 \`qiyu ${group} … --pretty\`)。` +
78
+ '写在这里没有可修饰的命令';
79
+ }
80
+ /**
81
+ * 存储定位三件套(store 命令同族)。值位语义唯一事实源在 `store-flags.ts`:
82
+ * `STORE_VALUE_FLAG_NAMES` 从这里派生,解析器与 spec 消费同一份,避免两边各写一遍
83
+ * `'--db' || '--profile' || '--backend'` 而漂移。
84
+ */
85
+ export const STORE_FLAGS = [
86
+ { name: '--db', kind: 'value' },
87
+ { name: '--profile', kind: 'value' },
88
+ { name: '--backend', kind: 'value' },
89
+ ];
90
+ /**
91
+ * 从一份 flag 清单里取出**吃值的** flag 名(`kind: 'value'` 或 `'repeatable'`)。
92
+ *
93
+ * `query` 的解析器用它派生 `VALUE_FLAGS`:可重复的 `--group-by` 与普通值位一样吃一个
94
+ * 值,只是可重复,所以两者同属「值位」。解析器不再自己手写一份值位名单。
95
+ */
96
+ export function valueFlagNames(flags) {
97
+ return flags.filter((f) => f.kind === 'value' || f.kind === 'repeatable').map((f) => f.name);
98
+ }
99
+ /**
100
+ * 按最长前缀匹配命令路径:`['sync','run']` 优先于 `['sync']`。
101
+ *
102
+ * 用**原始 argv** 逐位比较,不预先滤掉 flag:真实分派取 argv[0] 当子命令
103
+ * (`db.ts` / `sync.ts` 的 `const [sub, ...rest] = argv`),`qiyu db --profile tables`
104
+ * 会报「未知子命令:--profile」并退出 2。若先滤掉 flag 再匹配,这里会误命中
105
+ * `['db','tables']`——把一条运行时必然失败的命令判成合法,正是 skill check 要防的假阴性。
106
+ *
107
+ * 两条约束:
108
+ * · 路径位(i < path.length)出现以 `-` 开头的 token 即不命中;
109
+ * · 分组命令(tree 里还有更深的 spec)的子命令位不能是 flag:`sync --db x run` 里
110
+ * `--db` 落在 `sync` 的子命令位,真实分派同样报未知子命令。
111
+ * 路径之后的位置参数不参与比较(`db describe sessions` 的 `sessions`),所以位置参数
112
+ * 恰好等于某个命令名时也不会把路径凑长——tree 里没有那条 spec 就不命中。
113
+ *
114
+ * ⚠️ **tree 不变量:不得存在既是叶命令、又是更深 spec 前缀的 path。**
115
+ * 分组判定 `isGroup` 只看「tree 里有没有更深的 spec」,分不清「更深 spec 挂在哪个
116
+ * 父层」:若 tree 里同时有 `['sync']` 与 `['sync','run']`,`['sync']` 会被当作分组,
117
+ * 于是 `sync --db x run` 虽然真实分派取 argv[0]=`sync`、把 `run` 当位置参数跑,
118
+ * 却被判成不命中——合法 flag 被误拒(Task 1 复审 N-2)。真实分派(`const [sub, ...rest]
119
+ * = argv`)本就只有「叶命令 / 分组」两种形状,所以这条不变量不损失表达力。
120
+ * `tests/commands/command-tree.test.ts` 有断言钉住它;`spec-types.test.ts` 的 fixture
121
+ * 含 `['sync']` 只是为了单独测试 `isGroup` 分支的行为,不是合法的生产 tree。
122
+ */
123
+ export function findSpec(tree, argv) {
124
+ let best;
125
+ for (const spec of tree) {
126
+ if (spec.path.length > argv.length)
127
+ continue;
128
+ let matched = true;
129
+ for (let i = 0; i < spec.path.length; i++) {
130
+ const token = argv[i];
131
+ if (token.startsWith('-') || token !== spec.path[i]) {
132
+ matched = false;
133
+ break;
134
+ }
135
+ }
136
+ if (!matched)
137
+ continue;
138
+ const isGroup = tree.some((other) => other.path.length > spec.path.length && spec.path.every((seg, i) => other.path[i] === seg));
139
+ if (isGroup && argv[spec.path.length]?.startsWith('-'))
140
+ continue;
141
+ if (!best || spec.path.length > best.path.length)
142
+ best = spec;
143
+ }
144
+ return best;
145
+ }
@@ -0,0 +1,299 @@
1
+ // src/commands/stats.ts —— E-T10:`stats fields <table>`(spec §九)。
2
+ //
3
+ // 形态沿 db.ts / query.ts:parseStoreFlags(值位守卫)→ usageFail/fail 双通道 →
4
+ // 查询层统一错误出口 thrownToQueryExit。
5
+ //
6
+ // 三条硬约束:
7
+ // · 只统计**报表域表**(REPORT_TABLES 闭集,spec §9.1)——会话/工单的 payload 是
8
+ // PII 副本,统计它没有价值且扩大暴露面;其它表 → usage + 可用表清单;
9
+ // · 声明与观测分离(spec §9.2):`declared` 来自代码内受控目录(metric-catalog),
10
+ // 每条带 source;`observed` 是本地 payload 的数据分布,不是语义;
11
+ // · `-1` 是「该窗口没有匹配到数据」的哨兵(设计稿实测,厂商未文档化)——
12
+ // sentinel 恒在,且 min/max 一律排除 -1(否则 Agent 会报出 -100%)。
13
+ import { thrownToQueryExit, suggestNames } from '../query/errors.js';
14
+ import { METRIC_CATALOG, REPORT_TABLES, declareMetric } from '../query/metric-catalog.js';
15
+ import { TABLES } from '../store/schema.js';
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';
20
+ /**
21
+ * 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu stats …` 是否真的存在。
22
+ * `flags` 是**完整接受集**(含全局 flag),`--pretty` 同时在 `rejected` 里。
23
+ * 位置参数的 `report-tables` 域就是 `REPORT_TABLES` 闭集,校验方据此比对正文里的表名。
24
+ */
25
+ export const STATS_SPECS = [
26
+ {
27
+ path: ['stats', 'fields'],
28
+ flags: [...GLOBAL_FLAGS, ...STORE_FLAGS],
29
+ positionals: [{ name: '报表表', domain: 'report-tables' }],
30
+ rejected: REJECTED_FLAGS,
31
+ },
32
+ ];
33
+ const USAGE = `用法:qiyu stats <子命令> [参数]
34
+
35
+ 子命令:
36
+ stats fields <表> [--db <path>] [--profile <name>] [--backend <name>]
37
+ 指标声明(带出处)+ 本地观测分布 + -1 哨兵
38
+
39
+ 可用表(报表域,payload 内业务字段):
40
+ ${REPORT_TABLES.join('、')}
41
+
42
+ 存储定位:--db / --profile / --backend(store 命令同族)。
43
+ `;
44
+ const KNOWN = new Set(GLOBAL_FLAG_NAMES);
45
+ /**
46
+ * -1 哨兵(spec §9.2,逐字)。设计稿 §6.2 用 A/B 实测证明:数据充足的 31 天窗口
47
+ * 给出 assignedRatio=0.987,什么都匹配不到的筛选条件给出 -1.0 —— 不是负比率。
48
+ */
49
+ const SENTINEL = {
50
+ value: -1,
51
+ meaning: '该窗口或筛选条件没有匹配到数据(设计稿 §6.2 实测:报表面族统一哨兵,厂商未文档化)',
52
+ };
53
+ /**
54
+ * 观测 SQL(spec §9.2 原型 SQL,探针 17 实测通过)。
55
+ *
56
+ * 逐字段统计(不是逐行取值):
57
+ * · `rows_present`:payload 中出现该键的行数(缺键不出现;payload 为 SQL NULL /
58
+ * `{}`/数组/标量的行不贡献任何字段行);
59
+ * · `minus_one`:数值恰为 -1 的行数(哨兵);
60
+ * · `nulls`:JSON null 的行数(`json_each` 的 `type = 'NULL'`);
61
+ * · `min`/`max`:**排除 -1** 后的数值极值;非数值字段为 null(不报错)。
62
+ *
63
+ * ⚠️ 表名来自 REPORT_TABLES 闭集,是代码内常量,不承载外部输入。
64
+ *
65
+ * ⚠️ 用 `json_each` 展开、**不拼 JSON 路径**(CodeRabbit nitpick,2026-10-19 探针复核):
66
+ * 早先的写法是 `json_keys` 逐键取,键名来自库里的 payload(不受信),必须按 JSON 路径
67
+ * 语法转义后再 `json_extract`。实测(2026-10-18,DuckDB 1.5.6-r.1)转义写错就有两种病:
68
+ * · `a"b` / 尾随 `\` → `JSON path error`,**整条命令失败**(一个畸形键名杀掉全部统计);
69
+ * · `a\\b`(键内含连续反斜杠)→ 路径静默返回 NULL,非空值被计成 nulls ——
70
+ * **静默错数**,比报错更糟。
71
+ * `json_each` 直接给出 `key`/`value`/`type`,键名不进路径语法,整类缺陷消失;
72
+ * 顺带每行只展开一次(旧写法对每个键重复解析 payload)。
73
+ * ⚠️ 实测对照(2026-10-19,含 `b"c`、`x\y`、空键、JSON null、-1、非法 JSON、数组、标量):
74
+ * 新旧两版输出**逐字相同**,仅 `TRY(json_type(payload)) = 'OBJECT'` 把非对象行挡在外面。
75
+ * `min/max` 走 `e.value ->> '$'`(JSON 值转文本再转 DOUBLE),非数值自然为 NULL。
76
+ */
77
+ function observeSql(table) {
78
+ return `WITH kv AS (
79
+ SELECT e.key AS k, e.value AS raw, e.type AS jt,
80
+ TRY_CAST(e.value ->> '$' AS DOUBLE) AS num
81
+ FROM (SELECT payload FROM "${table}" WHERE TRY(json_type(payload)) = 'OBJECT') t,
82
+ json_each(t.payload) AS e
83
+ WHERE e.key <> ''
84
+ )
85
+ SELECT k AS field, COUNT(*) AS rows_present,
86
+ SUM(CASE WHEN num = -1 THEN 1 ELSE 0 END) AS minus_one,
87
+ SUM(CASE WHEN jt = 'NULL' THEN 1 ELSE 0 END) AS nulls,
88
+ MIN(CASE WHEN num <> -1 THEN num END) AS min,
89
+ MAX(CASE WHEN num <> -1 THEN num END) AS max
90
+ FROM kv GROUP BY k ORDER BY k`;
91
+ }
92
+ /**
93
+ * 库形态计数(edge cases F1/F2):一行 payload 不是合法 JSON、或含空键 `""` ——
94
+ * 前者让 `json_keys` 抛 `Malformed JSON`,**一行坏数据会杀掉整条命令**(连不依赖数据的
95
+ * `declared` 都拿不到);后者拼出 `$.""` 路径、抛 `JSON path error`,同样整命令失败。
96
+ * 观测 SQL 已用 `TRY`/过滤兜住这两类,本查询负责点名成因并进 `meta.warnings`
97
+ * (「有坏行」与「表为空」是不同的事实,不能混成一句)。
98
+ */
99
+ function shapeSql(table) {
100
+ return `SELECT
101
+ COUNT(*) AS total,
102
+ COUNT(*) FILTER (
103
+ WHERE payload IS NOT NULL AND TRY(json_valid(payload)) IS NOT TRUE) AS bad_json,
104
+ COUNT(*) FILTER (
105
+ WHERE TRY(json_valid(payload)) IS TRUE AND
106
+ EXISTS (SELECT 1 FROM unnest(TRY(json_keys(payload))) AS j(k) WHERE j.k = '')) AS empty_key
107
+ FROM "${table}"`;
108
+ }
109
+ /** COUNT/SUM 经 getRowObjectsJson() 是**字符串**(BIGINT/DECIMAL 的 JSON 形态)→ Number() 收敛。 */
110
+ function countOf(v) {
111
+ return Number(v);
112
+ }
113
+ /** MIN/MAX:DOUBLE 或 null;null 原样保留(非数值字段没有极值,不编造 0)。 */
114
+ function extremeOf(v) {
115
+ if (v === null || v === undefined)
116
+ return null;
117
+ const n = Number(v);
118
+ return Number.isFinite(n) ? n : null;
119
+ }
120
+ function declOut(d) {
121
+ return {
122
+ unit: d.unit,
123
+ higher_is_better: d.higher_is_better,
124
+ source: d.source,
125
+ note: d.note ?? null,
126
+ };
127
+ }
128
+ async function statsFields(argv) {
129
+ // 子命令级次序沿 db.ts:--help 分流 → --pretty 开启缩进(G1) → parseStoreFlags → 位置参数。
130
+ 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 不接受额外参数`);
134
+ process.stdout.write(USAGE);
135
+ return 0;
136
+ }
137
+ // G1:--pretty 已实现 —— 原拒绝点开启缩进输出(次序不变:help → 这里 → 值位解析)。
138
+ if (argv.includes('--pretty'))
139
+ setPretty(true);
140
+ let flags;
141
+ try {
142
+ flags = parseStoreFlags(argv);
143
+ }
144
+ catch (e) {
145
+ return usageFail(sanitizeControlChars(e.message));
146
+ }
147
+ const flagish = flags.rest.filter((a) => a.startsWith('-'));
148
+ if (flagish.length > 0)
149
+ return usageFail(`未知参数:${flagish.join(' ')}`);
150
+ if (flags.rest.length === 0) {
151
+ return usageFail(`缺少表名:请给 stats fields <表>\n可用表:${REPORT_TABLES.join('、')}`);
152
+ }
153
+ if (flags.rest.length > 1)
154
+ return usageFail(`未知参数:${flags.rest.slice(1).join(' ')}`);
155
+ const table = sanitizeControlChars(flags.rest[0]);
156
+ // spec §9.1:闭集校验先于一切 I/O —— 非报表表不进库、不开连接。
157
+ if (!REPORT_TABLES.includes(table)) {
158
+ // ⚠️ hint 必须按**这句话是否成立**来给(2026-10-18 手工验收发现,复审 Minor-1 补齐):
159
+ // 固定写「会话/工单的 payload 是 PII 副本」对 `staff`/`tags` 这类维度表是假话
160
+ //(它们没有 payload 列),对表名拼错更是毫无信息量。按「有无 payload 列 + 是否敏感」三分:
161
+ // · 表名未知 → 候选;
162
+ // · 有敏感 payload(sessions/tickets/ticket_logs)→ PII 理由;
163
+ // · 有**非敏感** payload(knowledge_* 三表)→ 不能说「没有 payload 列」——那与 schema 相反;
164
+ // · 无 payload 列(staff/tags/sync_state 等维度/元数据表)→ 收敛说明。
165
+ const known = TABLES.find((t) => t.name === table);
166
+ const candidates = known === undefined ? suggestNames(table, TABLES.map((t) => t.name)) : [];
167
+ const payloadCol = known?.columns.find((c) => c.name === 'payload');
168
+ const hint = known === undefined
169
+ ? (candidates.length > 0
170
+ ? `候选:${candidates.join('、')}(stats fields 只接受报表域表;用 \`qiyu db tables\` 查看全部表)`
171
+ : '用 `qiyu db tables` 查看全部表;stats fields 只接受报表域表')
172
+ : payloadCol !== undefined && payloadCol.sensitive
173
+ ? '该表的 payload 是整行 PII 副本:统计它没有价值且会扩大暴露面'
174
+ : payloadCol !== undefined
175
+ ? '该表的业务字段收敛在 payload 里但不属于报表域;stats fields 只做报表指标,字段清单请用 `qiyu db describe ' + table + '`'
176
+ : '该表的业务字段不是整体收敛进 payload 的(没有 payload 列),字段自描述对它没有意义';
177
+ return usageFail(`stats fields 只接受报表域表,收到:${describeArgs([table])}\n可用表:${REPORT_TABLES.join('、')}`, hint);
178
+ }
179
+ const opened = await openGuardedSession({
180
+ db: flags.db, profile: flags.profile, backend: flags.backend,
181
+ });
182
+ if ('exit' in opened)
183
+ return opened.exit;
184
+ const session = opened.session;
185
+ try {
186
+ // 目标表存在性校验(spec §十一「库不存在/缺表 → store_not_initialized、退出码 1」):
187
+ // schema_version 的库结构校验在 openGuardedSession 里已做(E 族共用,口径见 db.ts 的
188
+ // 注释)——这里只补本命令特有的「目标表缺」分支,并给出对 stats 有意义的 hint。
189
+ const target = await session.run(`SELECT 1 FROM information_schema.tables WHERE table_schema='main' AND table_name='${table}'`);
190
+ if (target.rows.length === 0) {
191
+ // ⚠️ 不得承诺 store init 一定能修(审查 Important #1,与 db.ts:184-189 同款):
192
+ // init 只重放 `version > MAX(version)` 的迁移,已迁移到最新版后被 DROP 的表
193
+ // **不会**被重建(迁移已跳过,返回 ok 而表仍缺)——那是「成功但无效」的修复。
194
+ return fail({
195
+ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
196
+ message: `数据库中缺表:${table}(${opened.dbPath})`,
197
+ hint: '若为建库未完成(迁移未跑完),运行 qiyu store init 可补建缺失的迁移;'
198
+ + '若迁移已完成而表被删或损坏,store init 不会重建该表,重新同步也只会写入失败(缺表)'
199
+ + '——需重建库(删除库文件后重新 qiyu store init 并重新同步)',
200
+ });
201
+ }
202
+ const result = await session.run(observeSql(table));
203
+ const shape = (await session.run(shapeSql(table))).rows[0] ?? {};
204
+ const observed = result.rows.map((r) => ({
205
+ field: String(r.field),
206
+ rows_present: countOf(r.rows_present),
207
+ minus_one: countOf(r.minus_one),
208
+ nulls: countOf(r.nulls),
209
+ min: extremeOf(r.min),
210
+ max: extremeOf(r.max),
211
+ }));
212
+ // declared = 目录声明(即便该表当前没有数据,声明也不依赖数据)+ 每个观测字段。
213
+ // ⚠️ 用 Map 而非普通对象累积:payload 的键名不受信,名为 `__proto__` 的键经
214
+ // `obj[k] = v` 赋值会**改原型而不是建自有键**(实测:该字段从输出里静默消失,
215
+ // 违反「每个 observed 字段都要在 declared 里有一条」)。`Object.fromEntries(Map)`
216
+ // 保留它为自有键,JSON.stringify 也能正常序列化。
217
+ const declared = new Map();
218
+ const group = Object.hasOwn(METRIC_CATALOG, table) ? METRIC_CATALOG[table] : undefined;
219
+ if (group !== undefined) {
220
+ for (const [field, d] of Object.entries(group))
221
+ declared.set(field, declOut(d));
222
+ }
223
+ for (const o of observed)
224
+ declared.set(o.field, declOut(declareMetric(table, o.field)));
225
+ // unknown_fields:目录(含后缀派生)判不出单位的字段 —— Agent 据此知道
226
+ // 「哪些字段没有单位信息」。observed 已按 field 排序,过滤保序。
227
+ const unknownFields = observed
228
+ .filter((o) => declared.get(o.field)?.unit === 'unknown')
229
+ .map((o) => o.field);
230
+ // 空结果有两种成因,警告必须分开说(「没有行」与「有行但 payload 没有可观测键」
231
+ // 是不同的事实,前者指向同步、后者指向 payload 落库形态)。
232
+ const warnings = [];
233
+ // 坏行先点名(edge cases F1/F2):它们不进 observed,但**必须**说明成因 ——
234
+ // 否则 Agent 会把「统计里少了几行」当成「那些字段就是没数据」。
235
+ const badJson = countOf(shape.bad_json);
236
+ if (badJson > 0) {
237
+ warnings.push(`该表有 ${badJson} 行 payload 不是合法 JSON,未计入统计`
238
+ + '(正常同步写入的是 JSON 字符串;这些行可能来自旧版 CLI、外部工具或库损坏)。'
239
+ + '用 `qiyu query --sql` 单独查看它们以确认成因');
240
+ }
241
+ const emptyKey = countOf(shape.empty_key);
242
+ if (emptyKey > 0) {
243
+ warnings.push(`该表有 ${emptyKey} 行 payload 含空字符串键 "",该键未计入统计`
244
+ + '(JSON 路径无法表达空键名);其余字段照常统计');
245
+ }
246
+ if (observed.length === 0) {
247
+ const n = Number(shape.total);
248
+ if (n === 0) {
249
+ warnings.push('该表无数据;先运行 `qiyu sync run`');
250
+ }
251
+ else {
252
+ warnings.push(`该表有 ${n} 行,但 payload 均无可观测字段(payload 为 NULL / 空对象 / 非对象)。`
253
+ + '字段自描述需要 payload 内的 JSON 键;请确认同步写入的是报表原始 JSON');
254
+ }
255
+ }
256
+ // 观测 SQL 一行 = 一个字段;沙箱默认行数上限(1000)超限即截断。
257
+ // 报表 payload 实测几十个键,正常不会触发 —— 但截断不得静默(Agent 会把
258
+ // 「只看到 N 个字段」当成事实)。⚠️ 文案不写死上限值:N 取自实际返回行数
259
+ // (上限是沙箱的默认值,不是本命令的契约);declared 还含目录声明、可能多于 N。
260
+ if (result.truncated) {
261
+ warnings.push(`观测字段数超过单次行数上限,observed/unknown_fields 只含按字段名排序的前 `
262
+ + `${result.rows.length} 个字段;该表的字段集可能不完整`);
263
+ }
264
+ return ok({ table, sentinel: SENTINEL, declared: Object.fromEntries(declared), observed, unknown_fields: unknownFields }, { warnings });
265
+ }
266
+ catch (e) {
267
+ return thrownToQueryExit(e, TABLES);
268
+ }
269
+ finally {
270
+ await session.close();
271
+ }
272
+ }
273
+ export async function statsCommand(argv) {
274
+ setPretty(false); // G1:每条命令入口重置输出格式 —— 同一进程内多次 run(测试)不残留上一条命令的开关。
275
+ const [sub, ...rest] = argv;
276
+ if (sub === undefined || sub === '--help' || sub === '-h') {
277
+ // --help 不吞额外参数;--pretty 豁免(db.ts 同族惯例)
278
+ const extra = rest.filter((a) => !KNOWN.has(a));
279
+ if (extra.length > 0)
280
+ return usageFail(`未知参数:${extra.join(' ')}。--help 不接受额外参数`);
281
+ process.stdout.write(USAGE);
282
+ return 0;
283
+ }
284
+ // G1:--pretty 是输出开关,必须写在具体子命令之后(`stats fields <表> --pretty`)。
285
+ if (sub === '--pretty') {
286
+ const extra = rest.filter((a) => !KNOWN.has(a));
287
+ if (extra.length > 0)
288
+ return usageFail(`未知参数:${extra.join(' ')}。--pretty 不接受额外参数`);
289
+ if (rest.includes('--help') || rest.includes('-h')) {
290
+ process.stdout.write(USAGE);
291
+ return 0;
292
+ }
293
+ return usageFail(prettyAfterSubcommand('stats'));
294
+ }
295
+ if (sub !== 'fields') {
296
+ return usageFail(`未知子命令:${sub}\n可用子命令:fields`);
297
+ }
298
+ return statsFields(rest);
299
+ }
@@ -0,0 +1,56 @@
1
+ // src/commands/store-flags.ts —— `--db / --profile / --backend` 的值位解析。
2
+ //
3
+ // 此前 db.ts / store.ts / stats.ts 各有一份逐字相同的 `parseFlags`,三处还各有
4
+ // 「改动必须同步另两处」的互指注释(架构审查 M-2)。新增共享定位 flag 时漏改任何
5
+ // 一份,那条命令会静默把它当位置参数(不报错、把下一个 token 吃成路径)——这类
6
+ // 漂移没有任何测试能替人拦住,所以收成唯一一份。
7
+ //
8
+ // ⚠️ query.ts 里也有一个 parseFlags,**不合并**:它是第四份但语义有意不同
9
+ // (`FLAG_TOKENS` 值位守卫,接受的 flag 集也不同)。
10
+ //
11
+ // 接受的 flag 名从 `STORE_FLAGS` 派生而不是在这里再手写一遍:`CommandSpec` 的
12
+ // 完整接受集也消费 `STORE_FLAGS`,两边共用同一份才不会出现「spec 说接受、解析器
13
+ // 不认」。
14
+ import { STORE_FLAGS } from './spec-types.js';
15
+ /** 值位 flag 名(`--db` 等,带 `--`),顺序沿 `STORE_FLAGS`。 */
16
+ export const STORE_VALUE_FLAG_NAMES = STORE_FLAGS.map((f) => f.name);
17
+ // ⚠️ 模块级断言(Task 2 复审 M1,Task 3 顺带落地):`parseStoreFlags` 用 `a.slice(2)`
18
+ // 推键名,前提是每个名字都以 `--` 开头。若将来给 `STORE_FLAGS` 加一个短 flag(如 `-x`),
19
+ // `slice(2)` 会把键写成空串并静默落进结果对象(复审实测:`{ rest: [], '': 'v' }`),
20
+ // 既不报错也不被消费。这里 fail fast —— 这是编程错误,不该等到 Agent 拿到空串键才发现。
21
+ if (!STORE_VALUE_FLAG_NAMES.every((n) => n.startsWith('--'))) {
22
+ throw new Error(`STORE_FLAGS 含非 -- 前缀的名字:${STORE_VALUE_FLAG_NAMES.join('、')}`);
23
+ }
24
+ /**
25
+ * 把 `--db/--profile/--backend` 及其值位从 argv 里剥出来,其余 token 原序进 `rest`
26
+ * (由调用方判「未知参数」还是「位置参数」)。
27
+ *
28
+ * 值位守卫(沿 store.ts 的 v1 计划缺陷与 B 的 isBodyValue 惯例):值位缺失或以 `--`
29
+ * 开头 → 报缺值。否则 `store init --db --profile x` 会把 `--profile` 当成路径。
30
+ * ⚠️ 错误文案 `${flag} 缺少取值` 逐字保持——多个既有测试钉着它。
31
+ *
32
+ * `--pretty` 是已知布尔开关(G1 实现后收下,不再进 `rest`):它不带值,进了 `rest`
33
+ * 会被调用方当未知参数误拒。值位守卫仍先于它 —— `store init --db --pretty` 报
34
+ * 「--db 缺少取值」,与 `--profile` 同款(下一个 token 以 `--` 开头即缺值)。
35
+ */
36
+ export function parseStoreFlags(argv) {
37
+ const out = { rest: [] };
38
+ for (let i = 0; i < argv.length; i++) {
39
+ const a = argv[i];
40
+ if (STORE_VALUE_FLAG_NAMES.includes(a)) {
41
+ const v = argv[i + 1];
42
+ if (v === undefined || v.startsWith('--'))
43
+ throw new Error(`${a} 缺少取值`);
44
+ // a 已由上面的 includes 收窄为三件套之一,slice(2) 得到 db/profile/backend。
45
+ out[a.slice(2)] = v;
46
+ i++;
47
+ }
48
+ else if (a === '--pretty') {
49
+ // G1:已实现的输出开关 —— 解析层收下;开启动作在命令层(原拒绝点 setPretty(true))。
50
+ continue;
51
+ }
52
+ else
53
+ out.rest.push(a);
54
+ }
55
+ return out;
56
+ }