qiyu-cli 0.0.0-stage → 0.2.1

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 +467 -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 +908 -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 +28 -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 +371 -0
  201. package/dist/skill/install.js +1202 -0
  202. package/dist/skill/paths.js +343 -0
  203. package/dist/skill/qiyu/SKILL.md +92 -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,368 @@
1
+ /** spec §7.1:无格式敏感值的整值替换标记。导出供命令层/测试复用,避免文案漂移。 */
2
+ export const FULL = '<已脱敏>';
3
+ /** spec §7.1 的三个可识别形态。均无 g 标志 —— test 不携带 lastIndex 状态。 */
4
+ const PHONE_RE = /^1\d{10}$/;
5
+ const EMAIL_RE = /^[^@\s]+@[^@\s]+$/;
6
+ const IPV4_RE = /^\d{1,3}(\.\d{1,3}){3}$/;
7
+ /** --no-mask 的 PII 风险警告(spec §7.2)。导出供命令层/测试复用。 */
8
+ export const NO_MASK_WARNING = '输出包含未脱敏的客户 PII;不要写入日志或对外报表';
9
+ /** 缺口警告上限(spec §7.2:去重、上限 5 条)。 */
10
+ const WARNING_LIMIT = 5;
11
+ // 列名 → 规则(brief 给定,与 spec §7.1 的可识别形态对应)。用显式集合而不是
12
+ // `endsWith('Email')` 之类的模式:敏感列清单是实测出来的有限集,模式匹配会随上游
13
+ // 命名漂移误伤(例如 staff.email 不是敏感列,但名字里也有 email)。
14
+ const PHONE_COLUMNS = new Set(['userPhone', 'crmUserPhone', 'userMobile']);
15
+ const EMAIL_COLUMNS = new Set(['userEmail', 'crmUserEmail']);
16
+ export function ruleForColumn(name) {
17
+ if (PHONE_COLUMNS.has(name))
18
+ return 'phone';
19
+ if (EMAIL_COLUMNS.has(name))
20
+ return 'email';
21
+ if (name === 'fromIp')
22
+ return 'ip';
23
+ return 'full';
24
+ }
25
+ /**
26
+ * 按规则转换单个值(spec §7.1)。
27
+ * - `null`/`undefined`/空串原样返回:空值不是 PII,也避免把 null 变成字符串。
28
+ * - 非字符串原样返回:schema 的 PII 列全是 VARCHAR,数字/布尔不可能是合法输入。
29
+ * - 形态与规则不匹配(如带区号的座机走 phone 规则):**退化为整值 `<已脱敏>`**,不按位截取。
30
+ * 取舍理由:模式不匹配时无法可靠定位「该保留哪几段」,按位截取反而可能暴露更多;
31
+ * 整值替换是 spec §7.1「其余 → 整值替换」的自然延伸(tests/query/mask.test.ts 钉死)。
32
+ */
33
+ export function maskValue(v, rule) {
34
+ if (typeof v !== 'string' || v === '')
35
+ return v;
36
+ switch (rule) {
37
+ case 'phone':
38
+ return PHONE_RE.test(v) ? `${v.slice(0, 3)}****${v.slice(7)}` : FULL;
39
+ case 'email': {
40
+ if (!EMAIL_RE.test(v))
41
+ return FULL;
42
+ const at = v.indexOf('@');
43
+ return `${v[0]}***@${v.slice(at + 1)}`;
44
+ }
45
+ case 'ip': {
46
+ if (!IPV4_RE.test(v))
47
+ return FULL;
48
+ return `${v.split('.').slice(0, 3).join('.')}.*`;
49
+ }
50
+ case 'full':
51
+ return FULL;
52
+ }
53
+ }
54
+ /** 值级检测:字符串是否直接呈现为某种 PII 形态。 */
55
+ function piiRuleOf(s) {
56
+ if (PHONE_RE.test(s))
57
+ return 'phone';
58
+ if (EMAIL_RE.test(s))
59
+ return 'email';
60
+ if (IPV4_RE.test(s))
61
+ return 'ip';
62
+ return null;
63
+ }
64
+ /**
65
+ * 递归遍历 JSON 解析结果的所有字符串叶子(对象与数组),任一命中 PII 形态即真。
66
+ * 叶子先 trim 再判:与 maskCellByValue 的直接值路径一致,`" 13800138000 "` 也算命中。
67
+ */
68
+ function hasPiiLeaf(value) {
69
+ if (typeof value === 'string')
70
+ return piiRuleOf(value.trim()) !== null;
71
+ if (Array.isArray(value))
72
+ return value.some(hasPiiLeaf);
73
+ if (value !== null && typeof value === 'object')
74
+ return Object.values(value).some(hasPiiLeaf);
75
+ return false;
76
+ }
77
+ /**
78
+ * `--sql` 值级兜底(spec §7.2 第 2 层)—— 只对未被列名级命中的列调用。
79
+ * - trim 后以 `{`/`[` 开头且 JSON.parse 成功 → 遍历全部字符串叶子,任一命中即整值 `<已脱敏>`;
80
+ * 无命中 → 原值不变(报表 payload 的数字 JSON 因此不会被误杀)。
81
+ * - trim 后以 `{`/`[` 开头但 JSON.parse 失败 → 直接 `<已脱敏>`:畸形 JSON 按普通字符串走
82
+ * 邮箱规则只会改写匹配到的那一段,其余字段(含潜在 PII)原样留在输出里;整值替换才不漏。
83
+ * - 否则按普通字符串匹配手机号/邮箱/IPv4 → 按 §7.1 对应规则转换。
84
+ * ⚠️ JSON 分支必须在直接匹配之前:spec 的邮箱正则 `^[^@\s]+@[^@\s]+$` 会整串命中
85
+ * 无空白、恰含一个 `@` 的 JSON(如 `{"email":"a@x.com"}`),先走直接匹配会把整段 JSON
86
+ * 按邮箱规则改成 `{***@x.com"}` —— 既不是整值替换,还会把其余字段原样留在输出里。
87
+ * 返回原值表示「未改写」,调用方据此决定是否计入 maskedColumns。
88
+ */
89
+ function maskCellByValue(v) {
90
+ // ⚠️ 非字符串的 JSON 形态(DuckDB 的 STRUCT/LIST/MAP → JS 对象/数组)必须**整值替换**
91
+ // (security S1,Critical):`SELECT t FROM sessions t` / `SELECT [t]` / `SELECT {'a':t}`
92
+ // 的值就是整行,里面是全量 PII;而它既不是字符串(旧的 JSON 字符串分支够不着),
93
+ // 也没有列名可归属(列名级够不着)。这类形态只可能来自整行序列化 / struct_pack /
94
+ // list 聚合,没有「聚合数字」这种合法误杀场景(报表 payload 是 VARCHAR 字符串,走下面
95
+ // 的字符串分支)。漏 PII 的代价远高于误杀一个 struct,故一律整值替换。
96
+ if (Array.isArray(v))
97
+ return FULL;
98
+ if (v !== null && typeof v === 'object')
99
+ return FULL;
100
+ if (typeof v !== 'string' || v === '')
101
+ return v;
102
+ const t = v.trim();
103
+ if (t.startsWith('{') || t.startsWith('[')) {
104
+ try {
105
+ return hasPiiLeaf(JSON.parse(t)) ? FULL : v;
106
+ }
107
+ catch {
108
+ return FULL; // 畸形 JSON:无法逐字段判定,整值替换是唯一不漏的选择
109
+ }
110
+ }
111
+ const direct = piiRuleOf(t);
112
+ return direct !== null ? maskValue(t, direct) : v;
113
+ }
114
+ /** `--sql` 列名级集合:全部敏感列名并集,去掉 payload(见文件头取舍)。 */
115
+ function sqlSensitiveNames(tables) {
116
+ const names = [];
117
+ const seen = new Set();
118
+ for (const t of tables) {
119
+ for (const c of t.columns) {
120
+ if (!c.sensitive || c.name === 'payload' || seen.has(c.name))
121
+ continue;
122
+ seen.add(c.name);
123
+ names.push(c.name);
124
+ }
125
+ }
126
+ return names;
127
+ }
128
+ /**
129
+ * 对一次查询的输出行脱敏(spec §7.2)。纯函数:输入行不被就地改写;
130
+ * `noMask` 时直接返回入参数组(不拷贝,因为一个字节都不会改)。
131
+ */
132
+ export function maskQueryRows(input) {
133
+ const { rows, columns, mode, noMask } = input;
134
+ // --no-mask:脱敏整体关闭,缺口警告随之失去意义(没有「脱敏不完整」,只有「没脱敏」)。
135
+ // ⚠️ 但**形态类**警告与脱敏开关无关,必须保留(契约审查 C-06):
136
+ // `--table --no-mask` 时 `TABLES` 之外的列仍未被脱敏、仍应点名——README 明说
137
+ // 「表定义之外的列不做脱敏但会警告」,这条是数据完整性提示,不是「脱敏不完整」提示。
138
+ if (noMask) {
139
+ if (mode.kind === 'table') {
140
+ const declared = new Set(mode.table.columns.map((c) => c.name));
141
+ const undeclared = columns.filter((n) => n !== 'count' && !declared.has(n));
142
+ return {
143
+ rows,
144
+ maskedColumns: [],
145
+ warnings: [
146
+ NO_MASK_WARNING,
147
+ ...(undeclared.length > 0
148
+ ? [`输出含表定义之外的列 ${undeclared.join('、')}(可能来自旧版 CLI 或库损坏):`
149
+ + '这些列不在 `TABLES` 元数据中,本次也未做脱敏(--no-mask)']
150
+ : []),
151
+ ],
152
+ };
153
+ }
154
+ return { rows, maskedColumns: [], warnings: [NO_MASK_WARNING] };
155
+ }
156
+ if (mode.kind === 'table') {
157
+ // --table 通道:精确。只认 TableDef 的 sensitive 标记;不在 TableDef.columns 的
158
+ // 额外输出列(正常不会出现)不脱敏,但**不得静默**(审查 Minor 1)——`SELECT *` 会把
159
+ // 库里多出来的列(旧版 CLI 残留、外部工具写入)原样带出,其中可能有 PII 列,
160
+ // 而 `db describe` 对同一漂移会警告(README「声明与实况的差异不得静默」)。
161
+ // 只看 TableDef 认不出该列是不是 PII,所以只能给警告、不能脱敏——如实说。
162
+ // `count` 是 --group-by 的聚合别名(不在 TableDef.columns),不算漂移列。
163
+ const declared = new Set(mode.table.columns.map((c) => c.name));
164
+ const undeclared = columns.filter((n) => n !== 'count' && !declared.has(n));
165
+ const driftWarnings = undeclared.length > 0
166
+ ? [`输出含表定义之外的列 ${undeclared.join('、')}(可能来自旧版 CLI 或库损坏):`
167
+ + '这些列不在 `TABLES` 元数据中,未做脱敏。要核对请用 `qiyu db describe '
168
+ + mode.table.name + '`']
169
+ : [];
170
+ const sensitive = new Set(mode.table.columns.filter((c) => c.sensitive).map((c) => c.name));
171
+ const hit = columns.filter((name) => sensitive.has(name));
172
+ // maskedColumns 只收「至少有一行的值在脱敏前后不同」的列(spec line 217:
173
+ // 实际脱敏,Agent 据此判断输出是否被改写)。全 null / 全空串 / 行内缺键的列不算
174
+ //(空串走 maskValue 的「原样返回」分支,不是被改写成 `<已脱敏>`)。
175
+ const changed = new Set();
176
+ const outRows = rows.map((row) => {
177
+ const out = { ...row };
178
+ for (const name of hit) {
179
+ // 行里缺这个键就不凭空造一个(输出列与行键正常一致,防御性跳过)
180
+ if (!(name in out))
181
+ continue;
182
+ const before = out[name];
183
+ // ⚠️ 非字符串值整值替换(安全审查 Minor,2026-10-20):与 --sql 通道的 S1 规则一致。
184
+ // 类型漂移(外部工具把 userPhone 改成 BIGINT/JSON)时 maskValue 对非字符串原样返回,
185
+ // 数字形态的手机号会整值漏出且 masked_columns 为空。
186
+ out[name] = before !== null && before !== undefined && typeof before !== 'string'
187
+ ? FULL
188
+ : maskValue(before, ruleForColumn(name));
189
+ if (out[name] !== before)
190
+ changed.add(name);
191
+ }
192
+ return out;
193
+ });
194
+ return { rows: outRows, maskedColumns: hit.filter((n) => changed.has(n)), warnings: driftWarnings };
195
+ }
196
+ // --sql 通道:列名级(主防线)+ 值级兜底(别名绕过)。
197
+ // 精确大小写匹配:输出列名 = 表定义大小写(探针 12),故 `staff.username`(全小写)
198
+ // 不会命中 `sessions.userName`(驼峰)——这是「精确」而非「忽略大小写」的理由。
199
+ const sensitiveNames = sqlSensitiveNames(mode.tables);
200
+ // ⚠️ DuckDB 把重名输出列去重成 `userName:1`、`userName:2`(security S2,Critical:
201
+ // 自连接 `SELECT a.userName, b.userName FROM sessions a JOIN sessions b …` 即可触发)。
202
+ // 精确匹配会放过改名后的第 2 列 → 原始 PII 静默漏出(列名级与值级两条防线都够不着,
203
+ // 因为姓名/地址无法值级检测)。故匹配用「去掉 `:数字` 后缀的基名」。
204
+ const baseName = (n) => n.replace(/:\d+$/, '');
205
+ // ⚠️ 大小写敏感(与下方 SQL 文本匹配的规则**不同**,两边各有理由):
206
+ // 输出列名 = 表定义大小写(DuckDB 保留声明大小写,实测探针 12),所以列名级用精确比较
207
+ // 就是对的;反而是 SQL 文本的匹配必须宽松(用户写 `username` 也与 `userName` 同列)。
208
+ // 若把这里也放宽,`staff.username`(非敏感列)的输出列会被当成 sensitive 整列改写。
209
+ const nameHit = new Set(columns.filter((name) => sensitiveNames.includes(baseName(name))));
210
+ // 供缺口警告用:哪些敏感列名**真的**匹配到了输出列(含 `:N` 改名后的)。
211
+ const matchedSensitive = new Set(columns.map(baseName).filter((n) => sensitiveNames.includes(n)));
212
+ // 实际改写追踪(两条分支共用):maskedColumns 只收「至少有一行的值在脱敏前后不同」的列。
213
+ const changed = new Set();
214
+ // 整行/STRUCT/LIST 命中的列:那是「整值替换」而不是「按值形态误判业务数字」,
215
+ // 不进下面的误伤提示(场景审查 7.2 只针对字符串形态命中)。
216
+ const structuralMasked = new Set();
217
+ const outRows = rows.map((row) => {
218
+ const out = { ...row };
219
+ for (const name of columns) {
220
+ if (!(name in out))
221
+ continue;
222
+ const before = out[name];
223
+ if (nameHit.has(name)) {
224
+ // ⚠️ 列名命中不等于值可安全转换(CodeRabbit 终审 major):`SELECT t AS userName
225
+ // FROM sessions t` 把整行 STRUCT 别名成敏感列名 → 走 nameHit 分支 → `maskValue`
226
+ // 对非字符串原样返回 → 全量 PII 漏出,且 matchedSensitive 含该名使缺口警告也不触发。
227
+ // 与 maskCellByValue 的 S1 规则同一处理:**任何非字符串值整值替换**。
228
+ // ⚠️ 覆盖面必须是「所有非字符串」而不只是对象/数组(CodeRabbit 复审):
229
+ // `SELECT userPhone::DOUBLE AS userPhone FROM sessions` 返回数字 13800138000,
230
+ // maskValue 同样原样返回 —— 数字形态的手机号一样是 PII。schema 里 PII 列都是
231
+ // VARCHAR,故真实列不会走到这里;能走到的是**用户显式 cast 成非字符串**,
232
+ // 那种情形宁可整值替换(误杀无害,漏出有害)。
233
+ out[name] = before !== null && before !== undefined && typeof before !== 'string'
234
+ ? FULL
235
+ : maskValue(before, ruleForColumn(baseName(name)));
236
+ }
237
+ else {
238
+ out[name] = maskCellByValue(before);
239
+ if (out[name] !== before && (Array.isArray(before) || (before !== null && typeof before === 'object'))) {
240
+ structuralMasked.add(name);
241
+ }
242
+ }
243
+ if (out[name] !== before)
244
+ changed.add(name);
245
+ }
246
+ return out;
247
+ });
248
+ // 缺口警告:SQL 文本按词边界命中敏感列名(除 payload),但该名不在输出列名中。
249
+ // 典型:SELECT userPhone AS p、concat(userName,'x') AS n(spec §7.2「缺口声明」)。
250
+ // ⚠️ 这是警告不是防护:姓名/地址无法值级检测,别名场景仍会漏。
251
+ // ⚠️ 大小写敏感是刻意的:加 `i` 会让 `SELECT username FROM staff` 误报 `userName`
252
+ //(staff.username 不是敏感列),要消除需真正解析 SQL 标识符,超出本纯函数的职责。
253
+ const warnings = [];
254
+ // payload 缺口(审查 I-1):payload 刻意不做列名级(文件头取舍),只靠值级 JSON 检测。
255
+ // 但值级只认手机号/邮箱/IPv4 —— 会话/工单 payload 里的姓名、地址(无格式)会**整段原样**
256
+ // 输出,且 `masked_columns` 非空(手机号命中)→ Agent 看到 `masked: true` 会误以为
257
+ // payload 已脱敏。README/CHANGELOG 承诺「两条通道都默认脱敏」,不点破就是承诺了不存在的保护。
258
+ //
259
+ // ⚠️ 只在 SQL 点名了「payload 标 sensitive 的表」时警告(与既有缺口警告同一启发式:
260
+ // 看 SQL 文本,不看语义)。报表表的 payload 是聚合数字 JSON,标了 sensitive 的只有
261
+ // sessions / tickets / ticket_logs —— 对 `SELECT payload FROM daily_overview` 警告
262
+ // 是噪音,会让 Agent 学会忽略 mask_warnings。
263
+ // ⚠️ 不对 payload 脱敏本身(报表 payload 是聚合数字,整值替换会误杀)——只声明缺口。
264
+ // (noMask 已在函数入口提前返回;payload 不在 sensitiveNames,故无需再查 nameHit。)
265
+ //
266
+ // ⚠️ 只看「输出列名里有 payload」会漏掉别名与函数包装(复审 I-1 残留):
267
+ // `SELECT payload AS p FROM sessions`、`json_extract(payload,'$.userName') AS n`
268
+ // 的输出列名都不叫 payload,PII 照样整段漏出。所以判据是「输出列名含 payload
269
+ // **或** SQL 文本出现 payload 标识符(词边界)」。报表表不在此列(payload 未标
270
+ // sensitive),故 `SELECT payload FROM daily_overview` 不会吃警告。
271
+ // ⚠️ 还有第三类形态(复审定点验证记录):整行序列化 `SELECT row_to_json(t) FROM sessions t`
272
+ // ——SQL 里既无 payload 记号、输出列名也是函数表达式,但**值**就是整行 JSON。
273
+ // 判据补「脱敏**前**的原始行里存在 JSON 对象/数组字面量值」(脱敏会把命中的整段换成
274
+ // 标记、不再可解析,故必须看入参 rows)。聚合数字列(COUNT 等)不会命中。
275
+ // ⚠️ 这是启发式(与既有缺口警告同源):字符串字面量里出现 payload 也会误报——方向安全
276
+ //(多警告),且真正解析 SQL 标识符超出本纯函数的职责。
277
+ const payloadPiiTables = mode.tables
278
+ .filter((t) => t.columns.some((c) => c.name === 'payload' && c.sensitive))
279
+ .map((t) => t.name)
280
+ .filter((name) => new RegExp(`\\b${name}\\b`, 'i').test(mode.sql));
281
+ const hasJsonBlob = rows.some((row) => columns.some((name) => {
282
+ const v = row[name];
283
+ // security S1:STRUCT/LIST 是 JS 对象/数组,不是字符串 —— 也必须算「整行 JSON」,
284
+ // 否则 `SELECT t FROM sessions t` 脱敏后仍按「值已改写」放行、不再发缺口警告。
285
+ if (Array.isArray(v))
286
+ return true;
287
+ if (v !== null && typeof v === 'object')
288
+ return true;
289
+ if (typeof v !== 'string')
290
+ return false;
291
+ const t = v.trim();
292
+ if (!t.startsWith('{') && !t.startsWith('['))
293
+ return false;
294
+ try {
295
+ const parsed = JSON.parse(t);
296
+ return typeof parsed === 'object' && parsed !== null;
297
+ }
298
+ catch {
299
+ return false;
300
+ }
301
+ }));
302
+ const payloadReferenced = columns.includes('payload') || /\bpayload\b/i.test(mode.sql);
303
+ // ⚠️ 第四类绕过(安全审查 Major,2026-10-20 实测):`query()` 表函数把内层 SQL 当作
304
+ // **字符串**执行,外层文本与输出列名都看不到内层标识符——
305
+ // `SELECT * FROM query('SELECT userName AS n, userAddress AS a FROM sessions')`
306
+ // 实测输出列 `n`/`a`,SQL 文本不含 userName/userAddress/payload → 三条启发式全落空,
307
+ // 姓名/地址静默原样输出且 `mask_warnings: []`。这类「SQL 嵌套执行」的构造无法可靠
308
+ // 分析,只能声明缺口(不拒绝:query() 本身在沙箱内、仍是只读 SELECT)。
309
+ // 判据取 `query(` / `query_table(` 词边界;`COLUMNS(...) AS` 也降级为同一警告。
310
+ const nestedSql = /\bquery_table\s*\(|\bquery\s*\(/i.test(mode.sql)
311
+ || /\bCOLUMNS\s*\(/i.test(mode.sql);
312
+ if (nestedSql) {
313
+ warnings.push('SQL 使用了 query()/query_table()/COLUMNS() 这类**在其内部再执行 SQL 或批量重命名**的构造:'
314
+ + '内层引用的敏感列无法被列名级识别,姓名/地址等无格式 PII 可能未经脱敏。'
315
+ + '需要可靠脱敏请把内层查询单独执行,或改用 `qiyu query --table <表>`');
316
+ }
317
+ if ((payloadReferenced || hasJsonBlob) && payloadPiiTables.length > 0) {
318
+ warnings.push(`引用了 payload 或整行 JSON(含 PII 的表 ${payloadPiiTables.join('、')}):`
319
+ + '本通道只对 payload 做值级检测(手机号/邮箱/IPv4),其中的姓名/地址等无格式 PII 可能未脱敏'
320
+ + '(别名、JSON 提取、整行序列化都绕得过列名级)。要整值替换请用 `qiyu query --table <表>`');
321
+ }
322
+ for (const name of sensitiveNames) {
323
+ if (warnings.length >= WARNING_LIMIT)
324
+ break;
325
+ if (matchedSensitive.has(name))
326
+ continue;
327
+ // `\b` 两侧都要求非标识符字符:userPhoneBook 这类更长标识符不会误报 userPhone。
328
+ //
329
+ // ⚠️ **必须大小写不敏感**(CodeRabbit 终审 major,spec §十五.4「误报方向必须是
330
+ // 多警告而非少警告」):DuckDB 标识符不分大小写 —— 实测 `SELECT username FROM
331
+ // sessions` 输出列名是 `userName`(值已列名级脱敏),但 `SELECT username AS n` 输出
332
+ // 列名是 `n`,列名级够不着、值级无法检测姓名 → 大小写敏感时**零警告静默漏出**。
333
+ // 代价是 `SELECT username FROM staff`(staff.username 不是敏感列)会多一条误报 ——
334
+ // spec 明确要求这个方向。
335
+ if (!new RegExp(`\\b${name}\\b`, 'i').test(mode.sql))
336
+ continue;
337
+ warnings.push(`SQL 引用了敏感列 ${name},但输出列名不匹配;脱敏可能不完整,` +
338
+ '建议用 `qiyu query --table` 或保持列名原样');
339
+ }
340
+ // 分组 / 去重会把不同原值压成同一个脱敏值(场景审查 7.3,2026-10-20 实测):
341
+ // `SELECT userPhone, COUNT(*) … GROUP BY userPhone` 对 3 个不同手机号输出 3 行同一个
342
+ // `138****1111`、每行 count=1 —— Agent 会读成「只有 1 个手机号」或「数据坏了」,而
343
+ // 输出里没有任何提示。`--table --group-by` 直接拒绝敏感列正是为了这个,`--sql` 只能声明。
344
+ const grouped = /\bGROUP\s+BY\b|\bDISTINCT\b/i.test(mode.sql);
345
+ if (grouped && matchedSensitive.size > 0) {
346
+ warnings.push(`SQL 对脱敏列做了 GROUP BY / DISTINCT(${[...matchedSensitive].join('、')}):`
347
+ + '不同原值会映射成同一个脱敏值,分组结果与计数可能失真。'
348
+ + '需要准确分组请用 `--no-mask`(并自行承担 PII 风险),或改用不敏感列分组');
349
+ }
350
+ // 值级兜底命中了**非敏感列**(场景审查 7.2):11 位、以 1 开头的订单号/聚合值会被
351
+ // 当成手机号打码,而 `--table` 通道对同一列返回原值。规则本身不能放宽(放宽就漏 PII),
352
+ // 但必须告诉 Agent「这一列不是声明上的 PII,是形态命中,值可能被误改」。
353
+ //
354
+ // ⚠️ 只在 SQL **完全没有引用任何敏感列**时提示:`SELECT userPhone AS p` 的 p 也是
355
+ // 「非敏感列名」,但它显然来自敏感列,上面已有缺口警告,再报一条就是噪音。
356
+ // payload 同理(它有自己的缺口警告,且刻意不在 sensitiveNames 里)。
357
+ const referencesSensitive = sensitiveNames.some((n) => new RegExp(`\\b${n}\\b`, 'i').test(mode.sql));
358
+ const falsePositive = referencesSensitive
359
+ ? []
360
+ : [...changed].filter((n) => n !== 'payload' && !structuralMasked.has(n) && !sensitiveNames.includes(baseName(n)));
361
+ if (falsePositive.length > 0) {
362
+ warnings.push(`列 ${falsePositive.join('、')} 不在敏感列清单里,是按**值形态**(手机号/邮箱/IPv4)`
363
+ + '命中的脱敏:若它其实是订单号、聚合值等业务数字,输出值已被改写。'
364
+ + '这类列可用 `qiyu query --table` 取得原始值(该通道按列声明脱敏)');
365
+ }
366
+ const maskedColumns = columns.filter((n) => changed.has(n));
367
+ return { rows: outRows, maskedColumns, warnings };
368
+ }
@@ -0,0 +1,85 @@
1
+ // src/query/metric-catalog.ts —— 指标声明目录(spec §9.2)。
2
+ //
3
+ // 职责只有一个:把「有出处的指标声明」集中在一处,供 `stats fields` 输出。
4
+ // 三条硬规则:
5
+ // 1. 每条声明**必须带 source**:
6
+ // · 'design-doc' = 设计稿实测明说(如 assignedRatio=0.987 且 -1=无数据)
7
+ // · 'name-suffix' = 按字段名后缀推断(*Ratio/*Radio→ratio、*Count/sessions→count、
8
+ // *Duration/*Time→ms)—— 标明这是命名推断,不是实测;
9
+ // 2. `higher_is_better` **没有任何上游来源**(设计稿从未给出)→ 一律 null,不猜;
10
+ // 3. 宁缺毋滥:只收录有出处的条目,其余靠运行时后缀派生。
11
+ //
12
+ // ⚠️ 后缀派生是**启发式**:判不出单位时如实返回 'unknown',命令层据此填 unknown_fields
13
+ // ——绝不为了「输出好看」给一个编造的单位。
14
+ //
15
+ // 分层约束(spec §5.1):本文件是纯数据 + 纯函数,不 import 任何模块。
16
+ /**
17
+ * 报表域表(spec §9.1):字段自描述只对「业务字段收敛进 payload」的报表域有意义。
18
+ * 会话/工单的 payload 是 PII 副本,统计它没有价值且扩大暴露面 —— 故是**闭集**,
19
+ * 其它表一律 usage + 可用表清单。
20
+ */
21
+ export const REPORT_TABLES = [
22
+ 'daily_overview',
23
+ 'staff_workload',
24
+ 'staff_quality',
25
+ 'staff_satisfaction',
26
+ 'staff_attendance',
27
+ 'order_performance',
28
+ 'staff_salary_detail',
29
+ 'robot_summary',
30
+ 'transfer_human',
31
+ ];
32
+ /**
33
+ * 目录(按表名分组)。初始内容**宁缺毋滥**——只有设计稿实测明说的才进 'design-doc'。
34
+ *
35
+ * `assignedRatio`:设计稿 §6.2(表设计前的实测约束一节)用 31 天窗口 A/B 实测
36
+ * assignedRatio=0.987、sessions=48695;什么都匹配不到的筛选条件给出 -1。注意
37
+ * -1 是「无数据」哨兵,不是数值(spec §9.2 的 sentinel 条目同源)。
38
+ */
39
+ export const METRIC_CATALOG = {
40
+ daily_overview: {
41
+ assignedRatio: {
42
+ unit: 'ratio',
43
+ higher_is_better: null,
44
+ source: 'design-doc',
45
+ note: '设计稿 §6.2 实测 0.987;-1 = 无数据',
46
+ },
47
+ sessions: { unit: 'count', higher_is_better: null, source: 'name-suffix' },
48
+ },
49
+ };
50
+ /** 后缀 → 单位(spec §9.2;顺序即优先级,见 deriveMetric 的注释)。 */
51
+ const SUFFIX_RULES = [
52
+ ['Ratio', 'ratio'],
53
+ ['Radio', 'ratio'],
54
+ ['Count', 'count'],
55
+ ['Duration', 'ms'],
56
+ ['Time', 'ms'],
57
+ ];
58
+ /**
59
+ * 按字段名后缀派生声明(source 恒为 'name-suffix',higher_is_better 恒 null)。
60
+ *
61
+ * ⚠️ `sessions` 是**精确名**不是后缀(`sessionsCount` 走 *Count 规则,结果相同)。
62
+ * 规则按 SUFFIX_RULES 顺序匹配;互斥的后缀之间顺序无影响,写成数组是为了
63
+ * 让「新增一条规则」是加一行而不是改判断树。
64
+ */
65
+ export function deriveMetric(field) {
66
+ if (field === 'sessions')
67
+ return { unit: 'count', higher_is_better: null, source: 'name-suffix' };
68
+ for (const [suffix, unit] of SUFFIX_RULES) {
69
+ if (field.endsWith(suffix))
70
+ return { unit, higher_is_better: null, source: 'name-suffix' };
71
+ }
72
+ return { unit: 'unknown', higher_is_better: null, source: 'name-suffix' };
73
+ }
74
+ /**
75
+ * 单字段声明:目录优先,目录没有则后缀派生。
76
+ *
77
+ * ⚠️ 用 `Object.hasOwn` 而非直接下标:字段名来自本地库 payload 的键(不受信数据),
78
+ * 名为 `__proto__` / `constructor` 的键在普通对象下标里会命中原型,返回的不是声明。
79
+ */
80
+ export function declareMetric(table, field) {
81
+ const group = Object.hasOwn(METRIC_CATALOG, table) ? METRIC_CATALOG[table] : undefined;
82
+ if (group !== undefined && Object.hasOwn(group, field))
83
+ return group[field];
84
+ return deriveMetric(field);
85
+ }