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,212 @@
1
+ import raw from './specs.json' with { type: 'json' };
2
+ /**
3
+ * 校验并载入注册表。
4
+ *
5
+ * ⚠️ 不能只写 `raw as EndpointSpec[]` —— 那是纯编译期断言,运行时零校验。
6
+ * 生成脚本产出的 154 条若漏了 `dangerous`,门禁会静默 fail-open,
7
+ * 而 `qiyu api call` 正是唯一的写操作入口。宁可加载时炸,也不要运行时静默放行。
8
+ */
9
+ export function loadSpecs(raw) {
10
+ if (!Array.isArray(raw))
11
+ throw new Error('specs.json 顶层必须是数组');
12
+ const seen = new Set();
13
+ const seenPage = new Set();
14
+ return raw.map((e, i) => {
15
+ const o = e;
16
+ if (typeof o.id !== 'string' || !o.id)
17
+ throw new Error(`specs.json[${i}] 缺少 id`);
18
+ if (seen.has(o.id))
19
+ throw new Error(`specs.json 存在重复 id:${o.id}`);
20
+ seen.add(o.id);
21
+ if (o.pageId !== undefined) {
22
+ if (typeof o.pageId !== 'string' || !/^api-\d+$/.test(o.pageId)) {
23
+ throw new Error(`specs.json[${o.id}] 的 pageId 非法:${o.pageId}`);
24
+ }
25
+ if (seenPage.has(o.pageId))
26
+ throw new Error(`specs.json 存在重复 pageId:${o.pageId}`);
27
+ seenPage.add(o.pageId);
28
+ }
29
+ if (typeof o.dangerous !== 'boolean') {
30
+ throw new Error(`specs.json[${o.id}] 缺少 dangerous 字段。` +
31
+ '该字段决定 --yes 门禁是否生效,不允许省略 —— 未知即视为危险。');
32
+ }
33
+ if (typeof o.callable !== 'boolean')
34
+ throw new Error(`specs.json[${o.id}] 缺少 callable`);
35
+ // ⚠️ `callable: true` 却没有路径,是生成脚本可能产出的畸形组合。
36
+ // 它不会在加载时暴露,而是在**调用时**拼出 `https://qiyukf.comnull?...`
37
+ // 发出去 —— 服务端返回一个与真实原因毫无关系的错误。
38
+ // 与 dangerous 同理:宁可加载时炸,也不要运行时静默发一个错误的请求。
39
+ if (o.callable === true && !o.path) {
40
+ throw new Error(`specs.json[${o.id}] 标记为可调用,但缺少 path。` +
41
+ '没有路径就无法拼出请求 URL,这一定是生成脚本的缺陷。');
42
+ }
43
+ // ⚠️ `path` 必须**以 `/` 开头的字符串**。上面那条只判了 truthy —— 实测
44
+ // `path: 123` 能通过校验,然后在 `call()` 里被模板串拼成
45
+ // `https://qiyukf.com123?appKey=...`:**请求照常发出去**,命中一个与真实
46
+ // 原因毫无关系的地址(`qiyukf.com123` 这个主机根本不存在,或者被 DNS 解析到
47
+ // 别处)。这正是上面 `null` 那条注释描述的同一种后果,只是入口换了 ——
48
+ // 只判 truthy 挡不住"非空但不是字符串"的值。
49
+ // 同理,不以 `/` 开头的相对路径会拼出 `https://qiyukf.comopenapi/...`,
50
+ // 同样是一个看似正常却错误的 URL。生成脚本取的是 OpenAPI 的 `paths:` 键,
51
+ // 正常一定是 `/` 开头 —— 不是的话就该在加载时炸。
52
+ //
53
+ // ⚠️ **`path` 键必须存在**(2026-10-08 修)—— 此前判据是
54
+ // `o.path !== null && o.path !== undefined`,**键整个缺失时被放行**。
55
+ // 而 `EndpointSpec.path` 的类型是 `string | null`(必填、无 `?`),
56
+ // `api list` 又**无条件**输出 `path: e.path` —— `undefined` 在
57
+ // `JSON.stringify` 里会让该键**整个消失**,Agent 拿到一行**没有 path 键**的记录。
58
+ // 这与 `verified` 那条「不允许省略」是**同一个理由**(注释就在下面几行),
59
+ // 却唯独漏了 `path`:`field_notes.path` 只声明了 `null`(未收录)与 `"/"`
60
+ // (入站占位符)两种形态,Agent 对一个"没有 path 键"的行无从判断该按哪种理解。
61
+ // 实测确认(2026-10-08):删掉 `path` 键后 `loadSpecs` 放行、输出里无 `path`。
62
+ // → 判据改为「键必须在,且值是 null 或以 `/` 开头的字符串」。
63
+ if (!('path' in o)) {
64
+ throw new Error(`specs.json[${o.id}] 缺少 path 字段。` +
65
+ '它必须是 / 开头的字符串或显式的 null(null = 文档页未提供可用路径)。' +
66
+ '省略会让该键在 api list 的 JSON 输出里整个消失,Agent 无从判断含义。');
67
+ }
68
+ if (o.path !== null) {
69
+ if (typeof o.path !== 'string' || !o.path.startsWith('/')) {
70
+ throw new Error(`specs.json[${o.id}] 的 path 必须是 / 开头的字符串或 null,` +
71
+ `实际是 ${JSON.stringify(o.path)}。` +
72
+ '错误的 path 会被拼进 URL 照常发出去,服务端返回一个与真实原因无关的错误。');
73
+ }
74
+ }
75
+ // ⚠️ `verified` 必须显式给出。它区分"实测过、可依赖"与"只有文档依据",
76
+ // 而 `api list` 会把它原样输出给 Agent —— `undefined` 在 JSON 里会**整个丢键**
77
+ // (`JSON.stringify({verified: undefined})` → `{}`),Agent 看到的是一个
78
+ // 连字段都没有的记录,无从判断可信度。与 `dangerous` 同理:不允许省略。
79
+ if (typeof o.verified !== 'boolean') {
80
+ throw new Error(`specs.json[${o.id}] 缺少 verified 字段(true=已实测 / false=成功路径未实测,` +
81
+ `实测范围见该行 note)。` +
82
+ '它会被 api list 输出给 Agent,缺失时该键会在 JSON 里消失。');
83
+ }
84
+ // ⚠️ `maxWindowDays` 是**天数**,必须是非负数字。实测 `"31"`(字符串)能通过
85
+ // 加载,然后在 `api list` 里原样输出 `"max_window_days": "31"` ——
86
+ // Agent 按 `span <= "31" * 86400000` 算会得到 NaN,切片逻辑静默失效;
87
+ // 而负数则会让任何窗口都被判为超限。
88
+ //
89
+ // ⚠️ **`null` 也必须被拒**(2026-10-05 修):此前守卫写成
90
+ // `!== undefined && !== null`,`null` 被**跳过校验**,可 `api list` 的判据是
91
+ // `e.maxWindowDays !== undefined`(`null !== undefined` 为真)—— 于是
92
+ // `"maxWindowDays": null` 会被原样输出成 `"max_window_days": null`。
93
+ // 而 `field_notes.max_window_days` 明写「未输出该键的接口没有已知上限」,
94
+ // 类型也是 `maxWindowDays?: number` —— 三处互相矛盾,Agent 拿到一个既不是
95
+ // 数字、也不是"没有该键"的值。本计划的约定是「**缺键 = 没有已知上限**」,
96
+ // 所以 `null` 是非法写法,必须在加载时炸,而不是漏到输出层。
97
+ if (o.maxWindowDays !== undefined) {
98
+ if (typeof o.maxWindowDays !== 'number' || !Number.isFinite(o.maxWindowDays) || o.maxWindowDays < 0) {
99
+ // ⚠️ 消息里**不得**用 Markdown 加粗(2026-10-06 修)。加载期的抛错发生在
100
+ // 任何输出层之前 —— specs.json 畸形时它以未捕获异常的形式**随堆栈原样进终端**
101
+ // (Node 默认打印器),`**` 会在那里显示成字面星号。与 help 文本同一条规则:
102
+ // 输出给谁看,就按谁的格式写 —— 崩溃栈也是纯文本通道,哨兵在
103
+ // tests/core/registry.test.ts 的「loadSpecs 的抛错消息不得含 Markdown」。
104
+ throw new Error(`specs.json[${o.id}] 的 maxWindowDays 必须是非负有限数字,或整个省略该键` +
105
+ `(省略 = 没有已知上限);不接受 null。实际是 ${JSON.stringify(o.maxWindowDays)}。`);
106
+ }
107
+ }
108
+ // ⚠️ `category` 是**可选**的(4 个文档外接口没有文档页、自然没有分组),
109
+ // 但**存在时必须是非空字符串**。判据与 `maxWindowDays` 同型:`null` 也必须拒 ——
110
+ // `api list` 的判据是 `e.category !== undefined`,`null` 会漏到输出层,
111
+ // 而 `field_notes.category` 明写「缺失 = 文档页无分组」。三处口径必须一致。
112
+ if (o.category !== undefined) {
113
+ if (typeof o.category !== 'string' || o.category.trim() === '') {
114
+ throw new Error(`specs.json[${o.id}] 的 category 必须是非空字符串,或整个省略该键` +
115
+ `(省略 = 文档页无分组);不接受 null。实际是 ${JSON.stringify(o.category)}。`);
116
+ }
117
+ }
118
+ // ⚠️ 入站推送(`direction: 'inbound'`)是七鱼回调我方,**不存在可主动调用的 URL**。
119
+ // 它的 path 是占位符 `"/"`(truthy),上面那条 `callable && !path` 拦不住它 ——
120
+ // 误标 callable 会拼出 `https://qiyukf.com/?appKey=...` 发出去。矛盾组合必须在加载时炸。
121
+ if (o.direction === 'inbound' && o.callable === true) {
122
+ throw new Error(`specs.json[${o.id}] 是入站接口(direction: inbound)却被标为可调用。` +
123
+ '入站接口由七鱼回调我方,不存在可调用的 URL —— 这一定是生成脚本的缺陷。');
124
+ }
125
+ // ⚠️ envelope 是**枚举**,拼错的值(`'d'`、`'A '`、`'E'`)不会报错,
126
+ // 而是静默退化成"未实测"的宽松模式。对形状 C 的接口,宽松模式会把
127
+ // message 里的 JSON 字符串**当成载荷原样返回**,Agent 拿到的是一段字符串
128
+ // 而不是解析后的对象 —— 而它无从知道这是因为注册表拼错了字。
129
+ // 与 dangerous 同理:枚举值必须在加载时校验,不能靠运行时兜底。
130
+ const ENVELOPES = new Set(['A', 'B', 'C', 'D', 'D-nf']);
131
+ if (o.envelope !== null && !ENVELOPES.has(o.envelope)) {
132
+ throw new Error(`specs.json[${o.id}] 的 envelope 取值非法:${JSON.stringify(o.envelope)}。` +
133
+ `合法值为 ${[...ENVELOPES].join('/')} 或 null(未实测)。`);
134
+ }
135
+ // ⚠️ `title` 是 `assertConfirmed` 错误消息的一部分(`接口 id(title)是危险操作`),
136
+ // 也是 `api list` 输出的唯一人类可读标识。缺失时门禁消息会输出 `(undefined)`。
137
+ if (typeof o.title !== 'string' || !o.title) {
138
+ throw new Error(`specs.json[${o.id}] 缺少 title —— 门禁与 api list 都依赖它`);
139
+ }
140
+ // ⚠️ `direction` 拼错会让接口从 `api list` 的默认过滤器里**静默消失**
141
+ // (默认只列 `callable && direction === 'outbound'`),Agent 据此以为
142
+ // "这个功能不存在" —— 这是 §9.2 头号静默失败在注册表层的变体。
143
+ if (o.direction !== 'outbound' && o.direction !== 'inbound') {
144
+ throw new Error(`specs.json[${o.id}] 的 direction 取值非法:${JSON.stringify(o.direction)}。` +
145
+ '合法值为 outbound / inbound —— 拼错会让接口从 api list 里静默消失。');
146
+ }
147
+ // ⚠️ `method` 缺失时 undici 默认 GET;若请求带 body 会抛
148
+ // "Request with GET/HEAD method cannot have body" —— 一个与真实原因
149
+ // (注册表缺字段)毫无关系的错误。
150
+ // ⚠️ **154 条里只有 1 条 GET**(`get_token`,2026-10-24 核实):它是
151
+ // `direction: inbound` + `callable: false`,生产上不可达。`call()` 的
152
+ // GET 分支(不带 body 发送 + 签名 `md5('')`)目前只由**合成 spec 的测试**
153
+ // 覆盖(http.test.ts),不是线上实测 —— 如实记录,别把它读成"GET 已实测"。
154
+ if (o.method !== 'POST' && o.method !== 'GET') {
155
+ throw new Error(`specs.json[${o.id}] 的 method 取值非法:${JSON.stringify(o.method)}。` +
156
+ '合法值为 POST / GET。');
157
+ }
158
+ // ⚠️ `auth` 本计划的 `call()` **不读**(见「已知缺口」),但枚举必须合法:
159
+ // 生成脚本产出 154 条时,一个拼错的 auth 会让"该接口是否需要签名"失去依据。
160
+ if (o.auth !== 'checksum' && o.auth !== 'eventType' && o.auth !== 'none') {
161
+ throw new Error(`specs.json[${o.id}] 的 auth 取值非法:${JSON.stringify(o.auth)}。` +
162
+ '合法值为 checksum / eventType / none。');
163
+ }
164
+ return o;
165
+ });
166
+ }
167
+ const SPECS = loadSpecs(raw);
168
+ const INDEX = new Map(SPECS.map((e) => [e.id, e]));
169
+ export function allEndpoints() {
170
+ return SPECS;
171
+ }
172
+ /** 未知 id 直接抛错 —— 静默返回 undefined 会让调用方崩在离病根很远的地方。 */
173
+ export function byId(id) {
174
+ const spec = INDEX.get(id);
175
+ if (!spec) {
176
+ // ⚠️ 空白 id 必须渲染成可见形式(2026-10-08 修,规则同 output.ts 的 describeArgs):
177
+ // `api call " "` 此前报「未知接口: 。可用 …」—— 冒号后不可见,Agent 无从知道
178
+ // 自己传的是空白(多半是 shell 变量展开成了空格)。
179
+ // ⚠️ 本文件在任务 6、output.ts 在任务 9,**无法 import describeArgs** —— 手写同一规则;
180
+ // 将来若调整 describeArgs 的渲染,记得这里有一份副本(同 cli.ts 任务 1 的手写 JSON)。
181
+ const shown = id.trim() === '' ? `'${id}'` : id;
182
+ throw new Error(`未知接口:${shown}。可用 \`qiyu api list\` 查看全部接口 id。`);
183
+ }
184
+ return spec;
185
+ }
186
+ export function assertCallable(spec) {
187
+ if (!spec.callable) {
188
+ throw new Error(`接口 ${spec.id} 不可主动调用` +
189
+ (spec.path ? `(方向:${spec.direction})` : `(文档未提供可用路径)`));
190
+ }
191
+ // ⚠️ `callable: true` 但 `path: null` 是**生成脚本可能产出的畸形组合**
192
+ // (文档页没有可用路径,却被标成可调用)。`call()` 里是 `${BASE}${spec.path}?...`,
193
+ // path 为 null 时会拼出 `https://qiyukf.comnull?appKey=...` —— 请求照样发出去,
194
+ // 服务端返回一个与真实原因无关的错误。必须在本地拦下,而不是让它变成网络请求。
195
+ if (!spec.path) {
196
+ throw new Error(`接口 ${spec.id} 标记为可调用,但注册表里没有它的路径(path 为 null)。` +
197
+ '这是注册表数据错误,请检查生成脚本。');
198
+ }
199
+ }
200
+ export function assertConfirmed(spec, confirmed) {
201
+ if (spec.dangerous && !confirmed) {
202
+ // ⚠️ 这里**只挂两个键**,两个都真的被读:
203
+ // · `needsConfirmation` —— api.ts 用它分流到 fail() 的 needs_confirmation 分支
204
+ // · `target` —— api.ts 读它(`err.target ?? id`)填出参的 target
205
+ // ⚠️ **不要在这里再挂 `confirmArg: '--yes'`。** 它曾在这里,但全仓没有任何读取点 ——
206
+ // 出参的 `confirm_arg` 是 `fail()` 自己硬编码的(见 output.ts)。留着它会制造
207
+ // **两个真相来源**:将来若把确认参数从 `--yes` 改掉,必须同时改两处,而死的这一处
208
+ // 会静默变错、无人发现。这与 `ErrorInput` 不再收 `confirmArg`/`risk` 是同一次清理
209
+ // (那两个键也曾是死键)—— 只是当时漏了抛错点这一处。
210
+ throw Object.assign(new Error(`接口 ${spec.id}(${spec.title})是危险操作,需要显式确认`), { needsConfirmation: true, target: spec.id });
211
+ }
212
+ }
@@ -0,0 +1,88 @@
1
+ {
2
+ "params": [
3
+ {
4
+ "name": "appKey",
5
+ "in": "query",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "企业的appKey",
9
+ "example": "{{appKey}}"
10
+ },
11
+ {
12
+ "name": "time",
13
+ "in": "query",
14
+ "required": true,
15
+ "type": "string",
16
+ "description": "当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数,1463217187",
17
+ "example": "{{time}}"
18
+ },
19
+ {
20
+ "name": "checksum",
21
+ "in": "query",
22
+ "required": true,
23
+ "type": "string",
24
+ "description": "SHA1(appSecret + md5 + time), 三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写).示例2f13932c4b7c6888b12360a85261a11b8b543f64 ",
25
+ "example": "{{checksum}} "
26
+ },
27
+ {
28
+ "name": "robotId",
29
+ "in": "body",
30
+ "required": true,
31
+ "type": "integer",
32
+ "description": "机器人id"
33
+ },
34
+ {
35
+ "name": "name",
36
+ "in": "body",
37
+ "required": true,
38
+ "type": "string",
39
+ "description": "问题name"
40
+ },
41
+ {
42
+ "name": "answer",
43
+ "in": "body",
44
+ "required": true,
45
+ "type": "string",
46
+ "description": "机器人答案,最大长度限制为3500字"
47
+ },
48
+ {
49
+ "name": "similars",
50
+ "in": "body",
51
+ "required": true,
52
+ "type": "array",
53
+ "description": "相似问,可多个,如:[\"相似问1\", \"相似问2\"],单个标准问你最多设置200个相似问;单个相似问最大长度限制为50字符"
54
+ },
55
+ {
56
+ "name": "validitySwitch",
57
+ "in": "body",
58
+ "required": true,
59
+ "type": "integer",
60
+ "description": "0-无效,1-(生效时间和失效时间都不为空表示有效期有效,否则永久有效"
61
+ },
62
+ {
63
+ "name": "effectiveTime",
64
+ "in": "body",
65
+ "required": false,
66
+ "type": "integer",
67
+ "description": "生效时间 Long类型,精确到毫秒,与failureTime需同时存在或同时不存在"
68
+ },
69
+ {
70
+ "name": "failureTime",
71
+ "in": "body",
72
+ "required": false,
73
+ "type": "integer",
74
+ "description": "失效时间Long类型,精确到毫秒,与effectiveTime需同时存在或同时不存在"
75
+ },
76
+ {
77
+ "name": "categoryId",
78
+ "in": "body",
79
+ "required": true,
80
+ "type": "integer",
81
+ "description": "分类id"
82
+ }
83
+ ],
84
+ "responseShape": {
85
+ "kind": "object"
86
+ },
87
+ "bodyKind": "json"
88
+ }
@@ -0,0 +1,46 @@
1
+ {
2
+ "params": [
3
+ {
4
+ "name": "appKey",
5
+ "in": "query",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "企业的appKey",
9
+ "example": "{{appKey}}"
10
+ },
11
+ {
12
+ "name": "time",
13
+ "in": "query",
14
+ "required": true,
15
+ "type": "string",
16
+ "description": "当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数,1463217187",
17
+ "example": "{{time}}"
18
+ },
19
+ {
20
+ "name": "checksum",
21
+ "in": "query",
22
+ "required": true,
23
+ "type": "string",
24
+ "description": "SHA1(appSecret + md5 + time), 三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写).示例2f13932c4b7c6888b12360a85261a11b8b543f64 ",
25
+ "example": "{{checksum}} "
26
+ },
27
+ {
28
+ "name": "robotId",
29
+ "in": "body",
30
+ "required": true,
31
+ "type": "integer",
32
+ "description": "机器人id"
33
+ },
34
+ {
35
+ "name": "knowledgeIds",
36
+ "in": "body",
37
+ "required": true,
38
+ "type": "array",
39
+ "description": "标准问id的集合"
40
+ }
41
+ ],
42
+ "responseShape": {
43
+ "kind": "object"
44
+ },
45
+ "bodyKind": "json"
46
+ }
@@ -0,0 +1,60 @@
1
+ {
2
+ "params": [
3
+ {
4
+ "name": "appKey",
5
+ "in": "query",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "企业的appKey",
9
+ "example": "{{appKey}}"
10
+ },
11
+ {
12
+ "name": "time",
13
+ "in": "query",
14
+ "required": true,
15
+ "type": "string",
16
+ "description": "当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数,1463217187",
17
+ "example": "{{time}}"
18
+ },
19
+ {
20
+ "name": "checksum",
21
+ "in": "query",
22
+ "required": true,
23
+ "type": "string",
24
+ "description": "SHA1(appSecret + md5 + time), 三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写).示例2f13932c4b7c6888b12360a85261a11b8b543f64 ",
25
+ "example": "{{checksum}} "
26
+ },
27
+ {
28
+ "name": "robotId",
29
+ "in": "body",
30
+ "required": true,
31
+ "type": "integer",
32
+ "description": "机器人id"
33
+ },
34
+ {
35
+ "name": "knowledgeId",
36
+ "in": "body",
37
+ "required": true,
38
+ "type": "integer",
39
+ "description": "标准问id"
40
+ },
41
+ {
42
+ "name": "ruleType",
43
+ "in": "body",
44
+ "required": true,
45
+ "type": "integer",
46
+ "description": "规则答案类型 1:标签答案"
47
+ },
48
+ {
49
+ "name": "channelAnswers",
50
+ "in": "body",
51
+ "required": true,
52
+ "type": "array",
53
+ "description": "规则答案详情列表,不能超过20个。 1.规则答案为空数组时则清空该标准问的规则答案。 2.规则答案不为空时,将该问题的规则答案更新为本次传的内容,历史内容清空"
54
+ }
55
+ ],
56
+ "responseShape": {
57
+ "kind": "object"
58
+ },
59
+ "bodyKind": "json"
60
+ }
@@ -0,0 +1,95 @@
1
+ {
2
+ "params": [
3
+ {
4
+ "name": "appKey",
5
+ "in": "query",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "企业的appKey",
9
+ "example": "{{appKey}}"
10
+ },
11
+ {
12
+ "name": "time",
13
+ "in": "query",
14
+ "required": true,
15
+ "type": "string",
16
+ "description": "当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数,1463217187",
17
+ "example": "{{time}}"
18
+ },
19
+ {
20
+ "name": "checksum",
21
+ "in": "query",
22
+ "required": true,
23
+ "type": "string",
24
+ "description": "SHA1(appSecret + md5 + time), 三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写).示例2f13932c4b7c6888b12360a85261a11b8b543f64 ",
25
+ "example": "{{checksum}} "
26
+ },
27
+ {
28
+ "name": "id",
29
+ "in": "body",
30
+ "required": true,
31
+ "type": "integer",
32
+ "description": "更新的问题id"
33
+ },
34
+ {
35
+ "name": "robotId",
36
+ "in": "body",
37
+ "required": true,
38
+ "type": "integer",
39
+ "description": "机器人id"
40
+ },
41
+ {
42
+ "name": "name",
43
+ "in": "body",
44
+ "required": true,
45
+ "type": "string",
46
+ "description": "问题name"
47
+ },
48
+ {
49
+ "name": "answer",
50
+ "in": "body",
51
+ "required": true,
52
+ "type": "string",
53
+ "description": "答案,最大长度限制为3500字"
54
+ },
55
+ {
56
+ "name": "similars",
57
+ "in": "body",
58
+ "required": false,
59
+ "type": "array",
60
+ "description": "相似问,可多个,如:[\"相似问1\", \"相似问2\"],单个标准问你最多设置200个相似问;单个相似问最大长度限制为50字符,传[]清空相似问,不传该字段不更新"
61
+ },
62
+ {
63
+ "name": "validitySwitch",
64
+ "in": "body",
65
+ "required": true,
66
+ "type": "integer",
67
+ "description": "0-无效,1-生效时间和失效时间都不为空表示有效期有效,否则永久有效"
68
+ },
69
+ {
70
+ "name": "effectiveTime",
71
+ "in": "body",
72
+ "required": false,
73
+ "type": "integer",
74
+ "description": "生效时间 Long类型,精确到毫秒"
75
+ },
76
+ {
77
+ "name": "failureTime",
78
+ "in": "body",
79
+ "required": false,
80
+ "type": "integer",
81
+ "description": "失效时间Long类型,精确到毫"
82
+ },
83
+ {
84
+ "name": "categoryId",
85
+ "in": "body",
86
+ "required": true,
87
+ "type": "integer",
88
+ "description": "分类id"
89
+ }
90
+ ],
91
+ "responseShape": {
92
+ "kind": "object"
93
+ },
94
+ "bodyKind": "json"
95
+ }
@@ -0,0 +1,102 @@
1
+ {
2
+ "params": [
3
+ {
4
+ "name": "appKey",
5
+ "in": "query",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "企业的appKey",
9
+ "example": "{{appKey}}"
10
+ },
11
+ {
12
+ "name": "time",
13
+ "in": "query",
14
+ "required": true,
15
+ "type": "string",
16
+ "description": "当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数,1463217187",
17
+ "example": "{{time}}"
18
+ },
19
+ {
20
+ "name": "checksum",
21
+ "in": "query",
22
+ "required": true,
23
+ "type": "string",
24
+ "description": "SHA1(appSecret + md5 + time), 三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写).示例2f13932c4b7c6888b12360a85261a11b8b543f64 ",
25
+ "example": "{{checksum}} "
26
+ },
27
+ {
28
+ "name": "id",
29
+ "in": "body",
30
+ "required": true,
31
+ "type": "integer",
32
+ "description": "更新的问题id"
33
+ },
34
+ {
35
+ "name": "robotId",
36
+ "in": "body",
37
+ "required": true,
38
+ "type": "integer",
39
+ "description": "机器人id"
40
+ },
41
+ {
42
+ "name": "question",
43
+ "in": "body",
44
+ "required": true,
45
+ "type": "string",
46
+ "description": "问题"
47
+ },
48
+ {
49
+ "name": "answer",
50
+ "in": "body",
51
+ "required": true,
52
+ "type": "string",
53
+ "description": "答案,最大长度限制为3500字"
54
+ },
55
+ {
56
+ "name": "validitySwitch",
57
+ "in": "body",
58
+ "required": true,
59
+ "type": "integer",
60
+ "description": "0-无效,1-生效时间和失效时间都不为空表示有效期有效,否则永久有效"
61
+ },
62
+ {
63
+ "name": "effectiveTime",
64
+ "in": "body",
65
+ "required": false,
66
+ "type": "integer",
67
+ "description": "生效时间 Long类型,精确到毫秒"
68
+ },
69
+ {
70
+ "name": "failureTime",
71
+ "in": "body",
72
+ "required": false,
73
+ "type": "integer",
74
+ "description": "失效时间Long类型,精确到毫"
75
+ },
76
+ {
77
+ "name": "categoryId",
78
+ "in": "body",
79
+ "required": true,
80
+ "type": "integer",
81
+ "description": "分类id"
82
+ },
83
+ {
84
+ "name": "ruleType",
85
+ "in": "body",
86
+ "required": true,
87
+ "type": "integer",
88
+ "description": "规则答案类型 1:标签答案"
89
+ },
90
+ {
91
+ "name": "channelAnswers",
92
+ "in": "body",
93
+ "required": true,
94
+ "type": "array",
95
+ "description": "规则答案详情列表,不能超过20个。 1.规则答案为空数组时则清空该标准问的规则答案。 2.规则答案不为空时,将该问题的规则答案更新为本次传的内容,历史内容清空"
96
+ }
97
+ ],
98
+ "responseShape": {
99
+ "kind": "object"
100
+ },
101
+ "bodyKind": "json"
102
+ }
@@ -0,0 +1,39 @@
1
+ {
2
+ "params": [
3
+ {
4
+ "name": "appKey",
5
+ "in": "query",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "企业的appKey",
9
+ "example": "{{appKey}}"
10
+ },
11
+ {
12
+ "name": "time",
13
+ "in": "query",
14
+ "required": true,
15
+ "type": "string",
16
+ "description": "当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数,1463217187",
17
+ "example": "{{time}}"
18
+ },
19
+ {
20
+ "name": "checksum",
21
+ "in": "query",
22
+ "required": true,
23
+ "type": "string",
24
+ "description": "SHA1(appSecret + md5 + time), 三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写).示例2f13932c4b7c6888b12360a85261a11b8b543f64 ",
25
+ "example": "{{checksum}} "
26
+ },
27
+ {
28
+ "name": "robotId",
29
+ "in": "body",
30
+ "required": true,
31
+ "type": "integer",
32
+ "description": "机器人id"
33
+ }
34
+ ],
35
+ "responseShape": {
36
+ "kind": "object"
37
+ },
38
+ "bodyKind": "json"
39
+ }