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
package/dist/output.js ADDED
@@ -0,0 +1,263 @@
1
+ export const EXIT = {
2
+ OK: 0, // 成功
3
+ BUSINESS: 1, // 业务错误
4
+ USAGE: 2, // 用法错误
5
+ NETWORK: 3, // 网络错误
6
+ NEEDS_CONFIRM: 4, // 需要 --yes
7
+ };
8
+ /**
9
+ * 输出是否缩进(`--pretty`,G1 交付)。
10
+ *
11
+ * ⚠️ **为什么是模块级开关 + 各命令自设,而不是在 `cli.ts` 统一检测**:
12
+ * ① `--pretty` 的**值位语义**必须由各命令自己的解析器裁决 —— `--body --pretty`
13
+ * 里的 `--pretty` 是 body 的值(`api call` 实测报「不是合法 JSON」),
14
+ * cli.ts 在分派前扫描 argv 会把它误当成开关;
15
+ * ② 命令模块的测试直接调用 `xxxCommand(argv)`(不经 cli.ts),入口层统一检测
16
+ * 在那些测试里根本不会跑;
17
+ * ③ 各命令原有的「未知/位置参数 → help → --pretty」次序必须逐字保留 ——
18
+ * 设置点就放在**原先拒绝 `--pretty` 的同一位置**,次序天然不变。
19
+ *
20
+ * 生命周期:每条命令入口在函数开头 `setPretty(false)` 重置(同一进程内
21
+ * `run()` 会被测试反复调用,不重置会让上一条命令的开关泄漏到下一条)。
22
+ * 进程级只有一次真实设置点:命令在「命令行已证明合法」之后调用 `setPretty(true)`。
23
+ */
24
+ let prettyOutput = false;
25
+ /** 设置输出是否缩进。命令入口以 `false` 重置,原拒绝点以 `true` 打开。 */
26
+ export function setPretty(on) {
27
+ prettyOutput = on;
28
+ }
29
+ function write(obj) {
30
+ process.stdout.write(JSON.stringify(obj, null, prettyOutput ? 2 : undefined) + '\n');
31
+ }
32
+ /**
33
+ * 把一组参数渲染进错误消息,**保证空串与空白参数不会被渲染成"什么都没有"**。
34
+ *
35
+ * ⚠️ **为什么需要它**(2026-10-05 补,实测):此前各处直接写
36
+ * `` `${argv.join('、')}` ``,于是 `qiyu api list "$UNSET"`(shell 变量未设置,
37
+ * 展开成空串)得到一句 **`未知参数:。`** —— 冒号后面什么都没有。Agent 收到的是
38
+ * 一个**没有指名任何东西**的用法错误:它不知道该改哪个参数,因为消息里根本没有参数。
39
+ * 而"用法错误"的全部价值就是告诉 Agent **改哪里**(退出码 2 的语义是"改参数重来")。
40
+ * 空白参数(`" "`、`"\t"`)同样渲染成不可见的字符,效果相同。
41
+ *
42
+ * 修法:空串与**纯空白**都写成 `'…'`(空串即 `''`)—— 引号让它们不再是"什么都没有",
43
+ * `未知参数:''。` / `未知参数:' '。` 至少指出"你传了一个空/空白参数"这个可操作的事实。
44
+ * 其余参数原样(报错要能直接照抄进命令行)。
45
+ *
46
+ * ⚠️ **空白这条是 2026-10-08 才真正兑现的**:本注释从写下那天起就写着"空白参数同样"
47
+ * 有问题,而实现只处理了空串 —— `qiyu api list " "` 报「未知参数: 。」,
48
+ * 参数名不可见。注释承诺了、实现没做(变异表 ㊿ 实测:只回退空串分支,
49
+ * 空白测试立即变红)。**"其余原样"不含纯空白** —— 纯空白没有"原样"可言,它原样就是不可见。
50
+ */
51
+ export function describeArgs(args) {
52
+ return args.map((a) => (a.trim() === '' ? `'${a}'` : a)).join('、');
53
+ }
54
+ /** 把不受信文本(调用方 body 的字段名等)中的终端控制字符抹成占位,防止 stderr 注入 ANSI/OSC 序列。 */
55
+ export { sanitizeControlChars, sanitizeMessage, stripSqlEcho } from './core/sanitize.js';
56
+ // usageFail 的出口净化要用(re-export 不建立本地绑定)。
57
+ import { sanitizeMessage } from './core/sanitize.js';
58
+ export function ok(data, meta) {
59
+ // ⚠️ `data` 必须**始终存在**,即便值是 undefined 也写成 null。
60
+ // 设计稿 §9.1 的成功形态是 `{ok, data, meta}` —— 三个键都在。
61
+ // 若直接 `{ ok: true, data }`,JS 的 JSON.stringify 会把值为 undefined 的键**整个丢掉**,
62
+ // 于是 `ok(undefined)` 产出 `{"ok":true}`,Agent 无法区分
63
+ // "这个接口没有载荷"(robot.transfer.config 实测就是这样)与"我解析错了"。
64
+ // 这与本计划在信封层反复强调的「`data` 键缺失是一种有意义的编码」是同一件事 ——
65
+ // 输出层不能自己制造那种歧义。
66
+ const withSkill = mergeSkillWarning(meta);
67
+ write(withSkill === undefined
68
+ ? { ok: true, data: data ?? null }
69
+ : { ok: true, data: data ?? null, meta: withSkill });
70
+ return EXIT.OK;
71
+ }
72
+ /**
73
+ * 待并入下一次成功输出 `meta.warnings` 的安装态提示(Task 10,spec D2.1)。
74
+ *
75
+ * ⚠️ **为什么是模块级注入而不是 `ok()` 自己探测**:`output.ts` 属于 CLI 输出层,
76
+ * 而探测在 `skill/`(叶子层)。分层红线(Task 14 用测试钉住)要求
77
+ * `output.ts`/`core/`/`commands/` 不得 import `skill/` —— 直接在这里
78
+ * `import { skillWarning } from './skill/detect.js'` 会让这条红线失守。所以由
79
+ * `cli.ts`(允许 import 两边)探测后经 `setSkillWarning()` 注入一句纯文本,
80
+ * `ok()` 只负责合并。探测本身只发生一次、且在命令启动时(缓存见 detect.ts)。
81
+ *
82
+ * 生命周期是**进程级**:cli.ts 在 `run()` 开头设一次,进程内所有成功输出都带上
83
+ * 同一条提示;测试用 `setSkillWarning(undefined)` 清除。
84
+ */
85
+ let pendingSkillWarning;
86
+ /** 设置(或清除,传 undefined)下一次及后续成功输出要带的安装态提示。 */
87
+ export function setSkillWarning(text) {
88
+ pendingSkillWarning = text;
89
+ }
90
+ /**
91
+ * 把 `pendingSkillWarning` 合并进 `meta.warnings`。
92
+ *
93
+ * 不变量(brief 逐条要求,测试钉住):
94
+ * · `pendingSkillWarning === undefined` → 返回**原样的** meta(不新建空 meta、
95
+ * 不补空 warnings 数组)——大量现有断言是 `toEqual({...})`,多一个键就全红;
96
+ * · meta 是普通对象 → **复制**出新对象再合并(不改调用方的对象),已有
97
+ * `warnings` 数组则 append,否则新建;
98
+ * · meta 不是对象(字符串/数组/null 等)→ 原样返回,不硬塞提示;
99
+ * · meta 为 undefined 且有提示 → 新建 `{ warnings: [提示] }`(这是提示唯一
100
+ * 能出现的通道,也是唯一允许新建 meta 的情形)。
101
+ *
102
+ * ⚠️ **元素形状跟随既有数组保持同质**(审查 I3,控制器裁定):不同命令的
103
+ * `meta.warnings` 形状不同——`api call` 是结构化对象数组
104
+ * (`{ kind, field?, message }`,见 api.ts),其余命令多为字符串数组。消费者按
105
+ * 自己的形状读:`api call` 的消费者按 `w.kind` 过滤,若往对象数组里塞一个裸字符串,
106
+ * `w.kind` 就是 `undefined`,静默丢失(或更糟:字符串被当对象取值)。所以:
107
+ * ① 没有 warnings → 新建字符串数组 `[text]`;
108
+ * ② 有数组且**首元素是非 null 对象** → 按对象形状 append
109
+ * `{ kind: 'skill_drift', message: text }`(与 api.ts 同形);
110
+ * ③ 其余(空数组 / 字符串数组 / 首元素是 null 等)→ append 字符串。
111
+ * 每个命令的 warnings 数组因此保持自身同质,两类读者都不被破坏。
112
+ */
113
+ function mergeSkillWarning(meta) {
114
+ if (pendingSkillWarning === undefined)
115
+ return meta;
116
+ if (meta === undefined)
117
+ return { warnings: [pendingSkillWarning] };
118
+ // 数组也是 object,但它不是「meta 对象」——不能给它挂 warnings 键(JSON 里
119
+ // 数组的可枚举自有属性会被序列化掉一部分,形态不可预期)。只认普通对象。
120
+ if (typeof meta !== 'object' || meta === null || Array.isArray(meta))
121
+ return meta;
122
+ const existing = meta.warnings;
123
+ let warnings;
124
+ if (!Array.isArray(existing)) {
125
+ warnings = [pendingSkillWarning];
126
+ }
127
+ else if (existing.length > 0 && isPlainObject(existing[0])) {
128
+ // 既有元素是结构化对象:保持同形,新元素带 kind 便于消费者过滤。
129
+ warnings = [...existing, { kind: 'skill_drift', message: pendingSkillWarning }];
130
+ }
131
+ else {
132
+ warnings = [...existing, pendingSkillWarning];
133
+ }
134
+ return { ...meta, warnings };
135
+ }
136
+ /** 非 null 的普通对象(数组不算——它是容器,不是元素形状)。 */
137
+ function isPlainObject(value) {
138
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
139
+ }
140
+ function exitCodeFor(kind) {
141
+ switch (kind) {
142
+ case 'network': return EXIT.NETWORK;
143
+ // 用法错误(未知接口 id、--body 不是合法 JSON 等)必须与业务错误分开:
144
+ // Agent 靠退出码决定"改参数重来"还是"别重试了",混在一起会让它做错决定。
145
+ case 'usage': return EXIT.USAGE;
146
+ // ⚠️ 这里**故意没有** `needs_confirmation` 分支 —— 退出码 4 不由 kind 决定,
147
+ // 而由 `confirmRequired` 决定(见下方 `fail()`)。这样「退出码 4」与
148
+ // 「带齐四个确认字段」永远是同一个条件,不会出现「返回 4 却没告诉 Agent
149
+ // 确认什么」的情况。`ErrorInput.kind` 是 `string`(刻意解耦),拼错成
150
+ // `needs_confirm` 不报编译错;靠 kind 判 4 就更容易静默出错。
151
+ default: return EXIT.BUSINESS;
152
+ }
153
+ }
154
+ export function fail(error) {
155
+ // 入参驼峰、出参下划线。这一层改写是刻意的:
156
+ // 内部改字段名不会破坏 Agent 契约,反之亦然。
157
+ const e = {
158
+ code: error.code, kind: error.kind, retryable: error.retryable, message: error.message,
159
+ };
160
+ if (error.hint)
161
+ e.hint = error.hint;
162
+ if (error.retryAfter)
163
+ e.retry_after = error.retryAfter;
164
+ if (error.retryStrategy)
165
+ e.retry_strategy = error.retryStrategy;
166
+ if (error.fallback)
167
+ e.fallback = error.fallback;
168
+ // ⚠️ 确认字段与退出码必须由**同一个判据**决定,不能是两个独立闸门。
169
+ // 设计稿 §9.1 要求退出码 4 **必须**携带 `confirm_required`/`confirm_arg`/`risk`/`target`
170
+ // 且 `retryable: false`。此前 `exitCodeFor(kind)` 与 `if (error.confirmRequired)` 互相独立,
171
+ // 于是 `fail({ kind:'needs_confirmation', retryable:false })`(忘给 confirmRequired)
172
+ // **合法通过类型检查、返回退出码 4、输出里一个确认字段都没有** ——
173
+ // Agent 收到「要确认」却不告诉它确认什么、怎么确认。
174
+ // 现在以 `confirmRequired` 为唯一判据:给了它就补齐四字段 + 强制 retryable=false +
175
+ // 返回 4;没给它就绝不会返回 4(`exitCodeFor` 仍按 kind 分派,但它刻意没有
176
+ // `needs_confirmation` 分支 —— 退出码 4 只由 `confirmRequired` 决定,见上方该函数内注释)。
177
+ if (error.confirmRequired) {
178
+ e.confirm_required = true;
179
+ e.confirm_arg = '--yes';
180
+ e.risk = 'irreversible';
181
+ e.target = error.target ?? '';
182
+ // ⚠️ 硬置为 false,不接受调用方给别的值 —— 让人工确认一个不可逆操作失败后
183
+ // 自动重试,是最坏的结果(重复执行)。设计稿把这条写成「必须」。
184
+ e.retryable = false;
185
+ write({ ok: false, error: e });
186
+ return EXIT.NEEDS_CONFIRM;
187
+ }
188
+ write({ ok: false, error: e });
189
+ return exitCodeFor(error.kind);
190
+ }
191
+ /**
192
+ * 用法错误(退出码 2)的统一出口。
193
+ *
194
+ * ⚠️ **为什么必须与 `fail()` 分开、又必须也写 stdout**(2026-10-05 修,实测发现):
195
+ *
196
+ * 全局约束写着「其余任何情况下 stdout 都必须是合法 JSON —— 包括所有错误输出(错误是
197
+ * `{ok:false,error}` 形态的 JSON,**不是纯文本**)」,而「不要用 stderr 是否为空来判断
198
+ * 成败,只认退出码与 **stdout 的 JSON**」也写在计划里。但此前**只有**未知接口 id 这一条
199
+ * 用法错误走了 stdout JSON(因为它是 `byId()` 抛异常、被 `callOne` 的 catch 里的 `fail()`
200
+ * 兜住),其余每一条用法错误 —— 顶层无子命令 / 未知子命令、`api` 未知子命令、
201
+ * `api call` 缺 id、flag 写在 id 前、`--body` 重复 / 缺值 / 非法 JSON、未知参数、
202
+ * 位置参数、`auth whoami` 多余参数 —— **一律只写 stderr 纯文本、stdout 空**。
203
+ *
204
+ * 后果可复现:`qiyu api call ticket.search --bogus | jq .` —— Agent 按计划教的方式读
205
+ * stdout 的 JSON,拿到的却是**空输入**(jq 报 `parse error: Unexpected end of JSON input`),
206
+ * 退出码 2 还落在管道里传不出去。同一条契约,"未知接口 id"满足、"未知参数"不满足 ——
207
+ * **是同一族错误里两种行为**,正是本计划反复在修的「说明/行为与承诺不符」。
208
+ *
209
+ * 修法:stderr 仍写人类可读文本(`git`/`docker` 的用户习惯、且测试里多处
210
+ * `expect(err).toContain(…)` 正钉着它),
211
+ * 同时把**同一句话**作为 `{ok:false,error:{code:'usage',kind:'usage',...}}` 写进 stdout。
212
+ * 这样两类读者都照顾到:人看 stderr,Agent 按契约读 stdout 的 JSON。
213
+ */
214
+ /**
215
+ * 「带 kind 的错误走 `fail()`,其余走 `usageFail()`」的统一出口(G1)。
216
+ *
217
+ * ⚠️ 为什么需要它:各命令的 catch 此前一律 `usageFail((e as Error).message)` ——
218
+ * 于是**带 kind 的错误**(如 `config_insecure`:配置含凭证但权限过宽,退出码 1、
219
+ * 只能由人 chmod 修)被降级成"用法错误,改参数重来"(退出码 2)。Agent 照退出码
220
+ * 的语义去改参数,而这件事与参数无关。
221
+ * → 有 `kind` 就如实透传(含 hint/retryable),没有才当用法错误。
222
+ */
223
+ export function failFromTagged(e) {
224
+ const err = e;
225
+ if (err.kind) {
226
+ return fail({
227
+ code: err.code ?? 'unknown', kind: err.kind, retryable: err.retryable ?? false,
228
+ message: err.message ?? String(e), hint: err.hint,
229
+ });
230
+ }
231
+ return usageFail(sanitizeMessage(err.message ?? String(e)));
232
+ }
233
+ export function usageFail(message, hint) {
234
+ // ⚠️ stderr 是不受信文本进终端的主通道(security S4):未知参数、未知表名、DuckDB 原文
235
+ // 都拼进 message,未经净化就能注入 ANSI/OSC 序列。净化必须在**出口**做一次,
236
+ // 而不是靠每个调用点自觉补 —— 实测 `db describe` / `query --table` 的未知表路径补了、
237
+ // 而同文件的 `未知参数` / `--help` 多余参数路径没补,两种行为并存正是缺口的来源。
238
+ const safe = sanitizeMessage(message);
239
+ process.stderr.write(safe.endsWith('\n') ? safe : safe + '\n');
240
+ // ⚠️ 用法错误**永远是紧凑 JSON**,即使 `--pretty` 已开启(CodeRabbit 2026-10-25 实测发现)。
241
+ // 契约写在 README「输出格式」与设计稿 §11.2:`--pretty` 只修饰**成功输出**,
242
+ // 用法错误(退出码 2)保持紧凑 —— 理由不是审美,而是"先修参数,再看格式":
243
+ // 一个带缩进的错误信封恰好出现在"你这条命令根本没跑起来"的时刻,
244
+ // 而 Agent 判断格式是否生效时会拿它当"格式化已生效"的证据。
245
+ // 此前有多条分支在 `setPretty(true)` **之后**才报用法错误(如 `api schema --pretty`
246
+ // 缺 id、`auth login --pretty` 缺环境变量),那些路径输出的就是缩进错误信封。
247
+ // 现在在唯一的出口处强制收窄 —— 逐个调用点调整次序既脆弱又会随新分支漂移。
248
+ const prevPretty = prettyOutput;
249
+ prettyOutput = false;
250
+ try {
251
+ return fail({
252
+ code: 'usage', kind: 'usage', retryable: false,
253
+ // message 去尾换行 —— stdout 的 JSON 里不该带控制字符;stderr 的文本保留换行便于阅读。
254
+ message: safe.replace(/\n+$/, ''),
255
+ ...(hint !== undefined ? { hint: sanitizeMessage(hint) } : {}),
256
+ });
257
+ }
258
+ finally {
259
+ // 还原:用法错误是命令的终点,但同进程内连续多次 `run()`(测试里常见)时,
260
+ // 下一条命令不该因为上一条报了个用法错误就丢掉它的 `--pretty`。
261
+ prettyOutput = prevPretty;
262
+ }
263
+ }
@@ -0,0 +1,178 @@
1
+ // src/postinstall.ts —— npm 全局安装后的便利路径:尽力而为地装一次 skill。
2
+ //
3
+ // 定位(spec D7 / C4 / C5):postinstall **不是** skill 安装的主路径,只是「用户
4
+ // `npm i -g qiyu-cli` 之后大概率顺手装了 skill」的锦上添花:
5
+ // · npm 12 / pnpm 12 / bun 默认**阻断**安装脚本(实测,spec C4),它大多数时候
6
+ // 根本不会跑;
7
+ // · 即使跑,默认安装下 stderr 被 npm 吞掉(除非 `--foreground-scripts`);
8
+ // · npx 场景下 postinstall 失败会让整个调用静默退出码 1(spec C4 实测)。
9
+ // 所以本文件遵守唯一一条硬约束:**任何输入、任何失败都返回 0,绝不阻断 npm 安装**。
10
+ // 真正的兜底是首次运行检测(detect.ts 的 meta.warnings:未安装/已过期提示),
11
+ // 主路径是显式命令 `qiyu skill install`。
12
+ //
13
+ // 判据(只有 npm 提供这两个变量,spec C6):
14
+ // · `npm_config_global === 'true'` —— 全局安装才自动装;局部依赖(某个项目的
15
+ // devDependency)不该往用户 home 里写东西;
16
+ // · `npm_command !== 'exec'` —— npx 执行时不装(临时借用的场景,写 home 是越权)。
17
+ // pnpm/yarn/bun 不提供这两个变量(bun 连 npm_lifecycle_event 都是 null),于是
18
+ // 判据自然落空 → 只提示、不写任何文件,与 spec「降级为不区分、只提示」一致。
19
+ //
20
+ // 自定义实体位置:读 `npm_config_qiyu_skill_dir`。命令行 flag 形式
21
+ // `--qiyu-skill-dir=` 在 npm 12 会 EUNKNOWNCONFIG 直接失败(spec C5),环境变量是
22
+ // 唯一跨版本可用的通路。环境变量名按 spec D8 的约定「统一转小写比对」——Windows
23
+ // 环境变量名大小写不敏感;npm 自己会把配置名里的 `-` 归一化成 `_`,所以读取时
24
+ // 键名统一 `toLowerCase().replace(/-/g, '_')` 后再查,`npm_config_qiyu-skill-dir`
25
+ // 这类变体同样命中。归一化实现在 `skill/paths.ts` 的 `envIndex`(与漂移探测共用)。
26
+ //
27
+ // 分层:本文件是**顶层入口**(与 cli.ts 同级),import `skill/install.ts`——与
28
+ // `qiyu skill install` 是同一份安装逻辑,不是复制代码。纯函数 `runPostinstall`
29
+ // 由入口守卫调用:不收 `process.env`、不调 `process.exit`、不调 `homedir()`,
30
+ // 测试可以完全注入(临时 home + 字面量 env),不会碰真实 `~`,也不会杀进程。
31
+ import { realpathSync } from 'node:fs';
32
+ import { homedir } from 'node:os';
33
+ import { pathToFileURL } from 'node:url';
34
+ import { PACKAGE_VERSION } from './core/edition.js';
35
+ import { resolveEntityDirSources, resolveSkillSourceDir } from './skill/detect.js';
36
+ import { installSkill } from './skill/install.js';
37
+ import { envIndex } from './skill/paths.js';
38
+ /** 中文提示统一写 stderr(stdout 不归 postinstall 用,npm 也只看 stderr)。 */
39
+ function note(message) {
40
+ process.stderr.write(`qiyu-cli: ${message}\n`);
41
+ }
42
+ /**
43
+ * postinstall 的全部行为。返回**永远**是 0(唯一的非 0 出口不存在):调用方
44
+ * (入口守卫)把它赋给 `process.exitCode`,失败只写 stderr。
45
+ *
46
+ * 键名归一化(小写 + `-`→`_`)已抽到 `skill/paths.ts` 的 `envIndex`——与
47
+ * `skill/detect.ts` 的漂移探测共用同一套规则(终审 I2:两处各写一份必然漂移)。
48
+ *
49
+ * 分支:
50
+ * 1. npx(`npm_command === 'exec'`)→ 提示,不写任何文件——**判据优先于全局标记**
51
+ * (npx 下 npm 也可能带 global 标记,但「临时借用」语义更重要);
52
+ * 2. 非全局安装(`npm_config_global !== 'true'`)→ 提示,不写任何文件;
53
+ * 3. 包内 skill 源目录不存在 → 提示,不抛(被裁剪的运行环境里这是正常现象);
54
+ * 4. 否则调用与 `qiyu skill install` 相同的 `installSkill`;`force` 恒 false
55
+ * ——自动路径绝不覆盖用户可能改过的正文(覆盖需要用户显式 `--force`)。
56
+ * 任何异常(权限、路径异常、安装失败)都收敛成一行中文提示 + 返回 0。
57
+ */
58
+ export async function runPostinstall(opts) {
59
+ try {
60
+ const env = envIndex(opts.env);
61
+ // npx 判据**先于**全局标记:npx 下 npm 也可能带 global 标记,但「临时借用」语义
62
+ // 更重要——不往 home 写东西。先判 exec 还能让提示文案说出真实原因。
63
+ if (env.get('npm_command') === 'exec') {
64
+ note('通过 npx 执行,跳过 skill 自动安装;需要时运行 `qiyu skill install`');
65
+ return 0;
66
+ }
67
+ if (env.get('npm_config_global') !== 'true') {
68
+ note('非全局安装(或包管理器不提供 npm 环境变量),跳过 skill 自动安装;需要时运行 `qiyu skill install`');
69
+ return 0;
70
+ }
71
+ const sourceDir = opts.sourceDir ?? resolveSkillSourceDir();
72
+ if (sourceDir === undefined) {
73
+ note('包内 skill 目录缺失,跳过 skill 自动安装;需要时运行 `qiyu skill install`');
74
+ return 0;
75
+ }
76
+ // 自定义实体位置:走全仓唯一的实体解析(`skill/detect.ts` 的 `resolveEntityDirSources`,
77
+ // G3 审查 C3)。相对路径按 `opts.cwd`(= `INIT_CWD ?? cwd`)解析成绝对路径——installSkill
78
+ // 内部所有路径运算都按绝对路径处理,绝对输入不受基准影响。
79
+ // `testGate: false`:postinstall 的 env 是 npm 给的(判据已由上面的 npx / 全局标记挡过)。
80
+ // 让它吃测试门会和 `npm test` 自己设的 `INIT_CWD` / `VITEST` 冲突,测试永远覆盖不到安装分支。
81
+ // 默认位置不在这里拼:落回 `default` 时交给 installSkill 按 `opts.home` 取
82
+ // `defaultEntityDir`(同一份事实,不在本文件重写一遍路径)。
83
+ const resolution = resolveEntityDirSources({
84
+ env: opts.env,
85
+ home: opts.home,
86
+ baseDir: opts.cwd ?? process.cwd(),
87
+ testGate: false,
88
+ });
89
+ const entityDir = !resolution.decided || resolution.source === 'default' ? undefined : resolution.dir;
90
+ const result = await installSkill({
91
+ home: opts.home,
92
+ sourceDir,
93
+ // 源码态是占位值 '0.0.0-dev',发布态由 copy-assets.mjs 注入真实版本。
94
+ version: PACKAGE_VERSION,
95
+ force: false,
96
+ ...(entityDir !== undefined ? { entityDir } : {}),
97
+ });
98
+ // 措辞按**实际**结果(审查 B2):计划要写、实际零写入时 status 是 skipped,
99
+ // 说「已是最新,跳过」是谎报——此时正文其实没跟上包内版本。
100
+ const label = result.status === 'skipped'
101
+ ? (result.plannedStatus === 'skipped' ? '已是最新,跳过' : '未完成更新(详见下方提示)')
102
+ : `已安装(${result.status})`;
103
+ note(`skill ${label}:${result.entityDir}`);
104
+ if (result.warnings.length > 0) {
105
+ // 零链接(审查 B3 / #58)等提示同样要出现在 npm 自动安装路径上。
106
+ note(`安装提示:${result.warnings.join(';')}`);
107
+ }
108
+ return 0;
109
+ }
110
+ catch (err) {
111
+ // 失败绝不阻断安装:一行中文提示(含原因)就够了,细节交给用户主动跑
112
+ // `qiyu skill install` 时再暴露。
113
+ const reason = err instanceof Error ? err.message : String(err);
114
+ note(`skill 自动安装失败(${reason}),不影响本次安装;稍后可运行 \`qiyu skill install\``);
115
+ return 0;
116
+ }
117
+ }
118
+ /**
119
+ * 本进程是否把 postinstall.js 当入口运行(`node dist/postinstall.js`)。与
120
+ * `src/cli.ts` 末尾同一手法:`pathToFileURL(realpathSync(argv[1]))` 与
121
+ * `import.meta.url` 比较(realpath 消掉符号链接与相对写法的差异)。
122
+ *
123
+ * 外层包 try/catch:argv[1] 不存在时 realpathSync 抛 ENOENT——入口判定失败只能是
124
+ * 「没被当入口」,不能反过来把进程搞挂(与「任何路径 exit 0」同一条底线)。
125
+ *
126
+ * `argv` / `moduleUrl` 可注入(D3.11):默认就是 `process.argv` 与 `import.meta.url`
127
+ * (行为不变),注入缝让「真分支 / 假分支」可以在**不 spawn 子进程**的前提下各钉一条。
128
+ * 子进程方式也能测,但它要跑真实的 npm 安装判据与真实 home——注入更稳、也更符合
129
+ * 本仓库「测试绝不碰真实 ~」的硬约束。
130
+ */
131
+ export function isEntry(argv = process.argv, moduleUrl = import.meta.url) {
132
+ const argv1 = argv[1];
133
+ if (argv1 === undefined || argv1 === '')
134
+ return false;
135
+ try {
136
+ return moduleUrl === pathToFileURL(realpathSync(argv1)).href;
137
+ }
138
+ catch {
139
+ return false;
140
+ }
141
+ }
142
+ /**
143
+ * 入口接线:把「进程状态 → runPostinstall 的输入」这一步单独导出,供测试直接钉住
144
+ * (复审 N3:此前接线段零覆盖,变异「去掉 `INIT_CWD ??`」可存活)。
145
+ *
146
+ * 三个职责:
147
+ * 1. `cwd` 取 `INIT_CWD ?? process.cwd()`——npm 生命周期脚本的 cwd 是包根
148
+ * (`node_modules/qiyu-cli`),`INIT_CWD` 才是用户执行 install 的目录(审查 M2);
149
+ * 2. **任何异常都收敛成 0**,包括取 `process.cwd()` 本身抛错(cwd 被删的场景,
150
+ * 复审 N1 实测过:写在实参位置会在 `.catch()` 之外,退 1、阻断安装);
151
+ * 3. 恒返回数字,调用方直接赋给 `process.exitCode`。
152
+ *
153
+ * `cwd` 参数仅供测试注入进程 cwd;生产入口不传,走 `process.cwd()`。
154
+ */
155
+ export async function mainEntry(opts) {
156
+ try {
157
+ // 优先级:`INIT_CWD`(npm 提供的用户目录)> 注入的进程 cwd(测试用)> `process.cwd()`。
158
+ // `opts.cwd` 代表「进程 cwd 的替身」,语义上低于 env 里的 INIT_CWD —— 顺序写反
159
+ // 会让用户在 npm 生命周期里设相对路径时落到包根(M2 的原始病症)。
160
+ const base = opts.env.INIT_CWD ?? opts.cwd ?? process.cwd();
161
+ return await runPostinstall({
162
+ env: opts.env,
163
+ home: opts.home,
164
+ cwd: base,
165
+ ...(opts.sourceDir !== undefined ? { sourceDir: opts.sourceDir } : {}),
166
+ });
167
+ }
168
+ catch {
169
+ // 连「取 cwd 失败」都在这里被兜住 —— postinstall 绝不阻断 npm 安装。
170
+ return 0;
171
+ }
172
+ }
173
+ if (isEntry()) {
174
+ // 连 catch 兜底都返回 0:postinstall 在任何情况下都不得阻断 npm 安装。
175
+ // 用 `process.exitCode` 而不是 `process.exit`(与 cli.ts 同理:设 exitCode 后
176
+ // 让事件循环自然结束,stdout/stderr 先排空再退出)。
177
+ process.exitCode = await mainEntry({ env: process.env, home: homedir() });
178
+ }