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.
- package/LICENSE +21 -0
- package/README.md +464 -2
- package/dist/cli.js +248 -0
- package/dist/commands/api.js +770 -0
- package/dist/commands/auth.js +349 -0
- package/dist/commands/credentials-source.js +70 -0
- package/dist/commands/db.js +503 -0
- package/dist/commands/local-fallback-wiring.js +67 -0
- package/dist/commands/local-fallback.js +34 -0
- package/dist/commands/query.js +564 -0
- package/dist/commands/skill-specs.js +64 -0
- package/dist/commands/skill.js +863 -0
- package/dist/commands/spec-types.js +145 -0
- package/dist/commands/stats.js +299 -0
- package/dist/commands/store-flags.js +56 -0
- package/dist/commands/store.js +258 -0
- package/dist/commands/sync-run.js +479 -0
- package/dist/commands/sync.js +757 -0
- package/dist/commands/tree.js +27 -0
- package/dist/core/config.js +259 -0
- package/dist/core/credentials.js +71 -0
- package/dist/core/edition.js +18 -0
- package/dist/core/envelope.js +201 -0
- package/dist/core/errors.js +356 -0
- package/dist/core/http.js +348 -0
- package/dist/core/ratelimit.js +126 -0
- package/dist/core/registry/index.js +212 -0
- package/dist/core/registry/params/ai.knowledge.addKnowledge.json +88 -0
- package/dist/core/registry/params/ai.knowledge.deleteKnowledges.json +46 -0
- package/dist/core/registry/params/ai.knowledge.editChannelAnswer.json +60 -0
- package/dist/core/registry/params/ai.knowledge.editKnowledge.json +95 -0
- package/dist/core/registry/params/ai.knowledge.editKnowledgeNoSimilars.json +102 -0
- package/dist/core/registry/params/ai.knowledge.getCategoryTree.json +39 -0
- package/dist/core/registry/params/ai.knowledge.getDetail.json +46 -0
- package/dist/core/registry/params/ai.knowledge.search.json +67 -0
- package/dist/core/registry/params/ai.statistic.transferHuman.json +60 -0
- package/dist/core/registry/params/category.list.json +39 -0
- package/dist/core/registry/params/chat.queue.group.query.json +39 -0
- package/dist/core/registry/params/crm.modifyOrder.json +48 -0
- package/dist/core/registry/params/crm.modifyUser.json +48 -0
- package/dist/core/registry/params/crm.syncCrmInfo.json +46 -0
- package/dist/core/registry/params/crm.tagChange.json +74 -0
- package/dist/core/registry/params/data.overview.ipcc.json +32 -0
- package/dist/core/registry/params/data.overview.session.json +53 -0
- package/dist/core/registry/params/evaluation.setting.get.json +39 -0
- package/dist/core/registry/params/event.applyStaff.json +116 -0
- package/dist/core/registry/params/event.evaluate.json +74 -0
- package/dist/core/registry/params/event.inviteEvaluate.json +81 -0
- package/dist/core/registry/params/event.qcResult.json +166 -0
- package/dist/core/registry/params/event.queryQueueStatus.json +39 -0
- package/dist/core/registry/params/event.queueEnter.json +40 -0
- package/dist/core/registry/params/event.queueLeave.json +46 -0
- package/dist/core/registry/params/event.quitQueue.json +39 -0
- package/dist/core/registry/params/event.sessionChange.json +95 -0
- package/dist/core/registry/params/event.sessionData.json +452 -0
- package/dist/core/registry/params/event.sessionEnd.json +117 -0
- package/dist/core/registry/params/event.sessionStart.json +109 -0
- package/dist/core/registry/params/event.updateUInfo.json +46 -0
- package/dist/core/registry/params/export.session.check.json +7 -0
- package/dist/core/registry/params/export.session.json +7 -0
- package/dist/core/registry/params/export.session.one.json +7 -0
- package/dist/core/registry/params/export.session.one.message.json +7 -0
- package/dist/core/registry/params/get_call_order.json +50 -0
- package/dist/core/registry/params/get_call_user_info.json +36 -0
- package/dist/core/registry/params/get_order.json +50 -0
- package/dist/core/registry/params/get_token.json +22 -0
- package/dist/core/registry/params/get_user_info.json +36 -0
- package/dist/core/registry/params/icoutcall.callIntercept.list.json +32 -0
- package/dist/core/registry/params/icoutcall.dialogFlow.fuzzySearch.json +53 -0
- package/dist/core/registry/params/icoutcall.dialogFlow.getDialogFlowList.json +32 -0
- package/dist/core/registry/params/icoutcall.get.customer.json +39 -0
- package/dist/core/registry/params/icoutcall.get.jobdetail.json +39 -0
- package/dist/core/registry/params/icoutcall.get.jobproperties.json +39 -0
- package/dist/core/registry/params/icoutcall.history.seat.json +67 -0
- package/dist/core/registry/params/icoutcall.history.team.json +67 -0
- package/dist/core/registry/params/icoutcall.job.create.json +53 -0
- package/dist/core/registry/params/icoutcall.job.importcustomer.json +46 -0
- package/dist/core/registry/params/icoutcall.job.pause.json +39 -0
- package/dist/core/registry/params/icoutcall.job.readdcustomer.json +109 -0
- package/dist/core/registry/params/icoutcall.job.start.json +39 -0
- package/dist/core/registry/params/icoutcall.job.terminate.json +39 -0
- package/dist/core/registry/params/icoutcall.phone.getLineList.json +32 -0
- package/dist/core/registry/params/ipcc.calltask.add.auto.json +117 -0
- package/dist/core/registry/params/ipcc.calltask.add.byCustom.json +96 -0
- package/dist/core/registry/params/ipcc.calltask.add.byRelation.json +82 -0
- package/dist/core/registry/params/ipcc.calltask.add.toGroup.json +89 -0
- package/dist/core/registry/params/ipcc.calltask.add.toStaff.json +89 -0
- package/dist/core/registry/params/ipcc.calltask.get.json +47 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.add.json +54 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.delete.json +40 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.get.json +54 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.update.json +40 -0
- package/dist/core/registry/params/ipcc.customfield.template.get.json +47 -0
- package/dist/core/registry/params/ipcc.login.json +47 -0
- package/dist/core/registry/params/kefu.add.json +130 -0
- package/dist/core/registry/params/kefu.delete.json +39 -0
- package/dist/core/registry/params/kefu.update.json +137 -0
- package/dist/core/registry/params/kefu.v2.query.json +39 -0
- package/dist/core/registry/params/kefuGroup.add.json +39 -0
- package/dist/core/registry/params/kefuGroup.delete.json +39 -0
- package/dist/core/registry/params/kefuGroup.update.json +46 -0
- package/dist/core/registry/params/kefuGroup.updateKefus.json +46 -0
- package/dist/core/registry/params/merchant.account.login.json +53 -0
- package/dist/core/registry/params/merchant.changePassword.json +46 -0
- package/dist/core/registry/params/merchant.create.json +81 -0
- package/dist/core/registry/params/merchant.disable.json +39 -0
- package/dist/core/registry/params/merchant.enable.json +39 -0
- package/dist/core/registry/params/merchant.list.json +46 -0
- package/dist/core/registry/params/merchant.query.json +46 -0
- package/dist/core/registry/params/merchant.update.json +74 -0
- package/dist/core/registry/params/message.send.image.json +53 -0
- package/dist/core/registry/params/message.send.json +53 -0
- package/dist/core/registry/params/message.send.voice.json +53 -0
- package/dist/core/registry/params/message.sendFile.json +39 -0
- package/dist/core/registry/params/message.uploadFile.json +39 -0
- package/dist/core/registry/params/online.session.category.list.json +39 -0
- package/dist/core/registry/params/online.session.customfield.template.json +39 -0
- package/dist/core/registry/params/online.session.customfield.update.json +74 -0
- package/dist/core/registry/params/order.upload.json +40 -0
- package/dist/core/registry/params/push.msg.image.json +74 -0
- package/dist/core/registry/params/push.msg.richText.json +74 -0
- package/dist/core/registry/params/push.msg.text.json +74 -0
- package/dist/core/registry/params/receive.message.json +89 -0
- package/dist/core/registry/params/robot.data.getQuestionsByCategoryName.json +67 -0
- package/dist/core/registry/params/robot.data.knowledge.json +46 -0
- package/dist/core/registry/params/robot.data.kpoint.json +46 -0
- package/dist/core/registry/params/robot.data.queryStandardByEffectiveQuestion.json +46 -0
- package/dist/core/registry/params/robot.data.queryStandardQuestionList.json +46 -0
- package/dist/core/registry/params/robot.evaluation.comment.json +67 -0
- package/dist/core/registry/params/robot.evaluation.setting.json +46 -0
- package/dist/core/registry/params/robot.session.assist.json +74 -0
- package/dist/core/registry/params/robot.session.chat.json +74 -0
- package/dist/core/registry/params/robot.session.close.json +53 -0
- package/dist/core/registry/params/robot.session.commonQuestions.json +74 -0
- package/dist/core/registry/params/robot.session.create.json +81 -0
- package/dist/core/registry/params/robot.session.evaluation.json +67 -0
- package/dist/core/registry/params/robot.session.msgAssociate.json +46 -0
- package/dist/core/registry/params/robot.session.msgEvaluation.json +53 -0
- package/dist/core/registry/params/robot.session.msgPredict.json +74 -0
- package/dist/core/registry/params/robot.session.transfer.json +36 -0
- package/dist/core/registry/params/robot.session.uploadFile.json +32 -0
- package/dist/core/registry/params/robot.statistic.summary.json +53 -0
- package/dist/core/registry/params/robot.transfer.config.json +15 -0
- package/dist/core/registry/params/session.user.profile.json +39 -0
- package/dist/core/registry/params/settings.wxTemplates.json +46 -0
- package/dist/core/registry/params/smstask.create.json +53 -0
- package/dist/core/registry/params/smstask.status.json +39 -0
- package/dist/core/registry/params/staff.group.list.new.json +39 -0
- package/dist/core/registry/params/staff.group.members.new.json +46 -0
- package/dist/core/registry/params/staff.list.new.json +46 -0
- package/dist/core/registry/params/staff.login.json +47 -0
- package/dist/core/registry/params/statistic.overview.json +61 -0
- package/dist/core/registry/params/statistic.performance.json +82 -0
- package/dist/core/registry/params/statistic.salaryDetail.json +54 -0
- package/dist/core/registry/params/statistic.satisfaction.report.json +68 -0
- package/dist/core/registry/params/statistic.staffAttendance.json +75 -0
- package/dist/core/registry/params/statistic.staffquality.json +75 -0
- package/dist/core/registry/params/statistic.staffworklod.json +68 -0
- package/dist/core/registry/params/tag.all.json +32 -0
- package/dist/core/registry/params/tag.batchUpdate.json +32 -0
- package/dist/core/registry/params/tag.update.json +60 -0
- package/dist/core/registry/params/ticket.apply.json +46 -0
- package/dist/core/registry/params/ticket.batch.modify.json +53 -0
- package/dist/core/registry/params/ticket.create.json +151 -0
- package/dist/core/registry/params/ticket.filter.count.json +46 -0
- package/dist/core/registry/params/ticket.filter.list.json +46 -0
- package/dist/core/registry/params/ticket.finish.json +60 -0
- package/dist/core/registry/params/ticket.followers.update.json +60 -0
- package/dist/core/registry/params/ticket.list.json +74 -0
- package/dist/core/registry/params/ticket.log.json +39 -0
- package/dist/core/registry/params/ticket.modify.json +74 -0
- package/dist/core/registry/params/ticket.new.detail.json +39 -0
- package/dist/core/registry/params/ticket.reminder.json +60 -0
- package/dist/core/registry/params/ticket.reopen.json +67 -0
- package/dist/core/registry/params/ticket.reply.json +60 -0
- package/dist/core/registry/params/ticket.search.json +116 -0
- package/dist/core/registry/params/ticket.template.fields.json +39 -0
- package/dist/core/registry/params/ticket.template.list.json +39 -0
- package/dist/core/registry/params/ticket.transfer.json +74 -0
- package/dist/core/registry/params/track.event.set.json +32 -0
- package/dist/core/registry/params/wecom.robot.switch.json +43 -0
- package/dist/core/registry/params.js +84 -0
- package/dist/core/registry/specs.json +2172 -0
- package/dist/core/registry/validate.json +11 -0
- package/dist/core/registry/validation-overrides.js +98 -0
- package/dist/core/sanitize.js +24 -0
- package/dist/core/sign.js +21 -0
- package/dist/core/time.js +194 -0
- package/dist/core/validate.js +140 -0
- package/dist/output.js +263 -0
- package/dist/postinstall.js +178 -0
- package/dist/query/errors.js +395 -0
- package/dist/query/mask.js +368 -0
- package/dist/query/metric-catalog.js +85 -0
- package/dist/query/sandbox.js +544 -0
- package/dist/query/table-query.js +297 -0
- package/dist/query/time-shape.js +44 -0
- package/dist/schedule/install.js +377 -0
- package/dist/skill/check.js +429 -0
- package/dist/skill/detect.js +336 -0
- package/dist/skill/install.js +1202 -0
- package/dist/skill/paths.js +343 -0
- package/dist/skill/qiyu/SKILL.md +86 -0
- package/dist/skill/qiyu/errors.md +55 -0
- package/dist/skill/qiyu/forbidden.md +52 -0
- package/dist/skill/qiyu/metrics.md +65 -0
- package/dist/skill/qiyu/protocols.md +55 -0
- package/dist/skill/qiyu/setup.md +50 -0
- package/dist/skill/refs.js +379 -0
- package/dist/store/config.js +137 -0
- package/dist/store/duckdb.js +321 -0
- package/dist/store/index.js +18 -0
- package/dist/store/retry.js +36 -0
- package/dist/store/schema.js +419 -0
- package/dist/store/types.js +4 -0
- package/dist/sync/day.js +8 -0
- package/dist/sync/engine.js +818 -0
- package/dist/sync/rate-gate.js +95 -0
- package/dist/sync/registry.js +22 -0
- package/dist/sync/state.js +114 -0
- package/dist/sync/tasks/dim.js +186 -0
- package/dist/sync/tasks/knowledge.js +252 -0
- package/dist/sync/tasks/pace.js +66 -0
- package/dist/sync/tasks/pipeline.js +321 -0
- package/dist/sync/tasks/reports.js +448 -0
- package/dist/sync/tasks/sessions.js +188 -0
- package/dist/sync/tasks/tickets.js +219 -0
- package/dist/sync/types.js +1 -0
- package/dist/sync/windowing.js +56 -0
- package/package.json +52 -4
|
@@ -0,0 +1,356 @@
|
|
|
1
|
+
// src/core/errors.ts
|
|
2
|
+
/**
|
|
3
|
+
* 全部错误 kind 的**单一事实源**(F 子项目 Task 4)。
|
|
4
|
+
*
|
|
5
|
+
* 类型与运行时共用这一份:`ErrorKind` 由它派生,`skill check` 也拿它校验
|
|
6
|
+
* skill 正文里的 `kind: x` 引用是否真实存在(设计稿 §11.4)。
|
|
7
|
+
*
|
|
8
|
+
* 加/删成员只改这里。漏抄的保护分两档,**不是**一律都由 typecheck 兜住
|
|
9
|
+
* (复审 M-2 修正了此处早先的过度承诺):
|
|
10
|
+
* · 大多数字面量走 `fail(ErrorInput)`,而 `ErrorInput.kind` 是 `string` ——
|
|
11
|
+
* 这条路径**不**受 `ErrorKind` 约束,漏抄时 typecheck 不会报错;
|
|
12
|
+
* · 受约束的是 `classify()` 的返回值、`sandboxError(kind: ErrorKind)` 这类,
|
|
13
|
+
* 以及 `tests/core/errors.test.ts` 的 `ALL satisfies readonly ErrorKind[]`。
|
|
14
|
+
* 所以漏抄的最终防线是**测试 + typecheck 一起**,不是 typecheck 单独一条。
|
|
15
|
+
*/
|
|
16
|
+
export const ERROR_KINDS = [
|
|
17
|
+
'auth', // 凭证**无效**(14001/14002/14008/14515)—— 发出去被服务端拒了
|
|
18
|
+
'auth_missing', // 凭证**根本没配置**(本地就拦下,从未发出请求)—— 设计稿 §9.5
|
|
19
|
+
'bad_time', // 时间戳超期:core 先自动重签重试;仍失败说明本机时钟真的偏了
|
|
20
|
+
'param', // 参数错误,重试无用
|
|
21
|
+
'rate_limit', // 限流,延迟重试
|
|
22
|
+
'module_offline', // 模块未开通,永久失败
|
|
23
|
+
'window_too_large', // 时间跨度超限,调用方需自行切片后重试
|
|
24
|
+
'window_misaligned', // 时间边界没对齐自然日 —— 切片修不好,必须对齐 endTime
|
|
25
|
+
'not_in_queue', // 业务态,不是故障
|
|
26
|
+
'pending', // 异步任务未完成(如会话导出轮询),可重试
|
|
27
|
+
'route_not_found', // 服务端没有这条路由 —— 注册表的路径写错了,重试无用
|
|
28
|
+
'internal', // 服务端内部错误,退避重试
|
|
29
|
+
'network', // 网络层故障
|
|
30
|
+
'usage', // 调用方式有误(未知接口 id、--body 不合法),对应退出码 2
|
|
31
|
+
'unknown',
|
|
32
|
+
// `--yes` 门禁拒绝时的 kind —— `api.ts` 的 `fail()` 产出它,
|
|
33
|
+
// 对应 `code: 'confirm_required'`(危险接口未加 --yes),退出码 4
|
|
34
|
+
'needs_confirmation',
|
|
35
|
+
// 存储层(C1):数据库被写进程持锁(读者退避超限 / 写者立即)—— 退出码 1,可重试
|
|
36
|
+
'store_locked',
|
|
37
|
+
// 存储层(C1):库不存在 / 缺表 / 依赖缺失 / 非 DuckDB 文件 / 他人库 —— 退出码 1
|
|
38
|
+
'store_not_initialized',
|
|
39
|
+
// 查询层(E):只读查询超时(conn.interrupt 生效)—— 退出码 1;
|
|
40
|
+
// `output.ts` 的 `exitCodeFor` 不设分支,落 default(EXIT.BUSINESS)
|
|
41
|
+
'query_timeout',
|
|
42
|
+
// 同步层(D):sync status/verify 尚无成功 run 的证据 —— 退出码 1。
|
|
43
|
+
// 此前只在 `sync.ts` 里以字符串字面量出现、不在本联合里,按 kind 分支的 Agent
|
|
44
|
+
// 会收到一个未在任何类型/文档中出现的值(契约审查 C-03)。
|
|
45
|
+
'sync_not_run',
|
|
46
|
+
// 配置层(G1):配置文件**含凭证**却权限过宽(group/other 可访问,或父目录
|
|
47
|
+
// 可被整体替换)—— 退出码 1,重试无用,必须由人执行 chmod 收紧密码。
|
|
48
|
+
// ⚠️ 与 `auth_missing` 的区别:那是「没配」,这是「配了但落在不安全的位置」。
|
|
49
|
+
'config_insecure',
|
|
50
|
+
];
|
|
51
|
+
/** 抹掉服务端泄漏的内部实现细节。必须在任何 message 透出前调用。 */
|
|
52
|
+
export function redactInternal(message) {
|
|
53
|
+
let out = message;
|
|
54
|
+
// Java 包路径 / 类名:三段及以上的点分标识符(com.example.Foo.bar)
|
|
55
|
+
//
|
|
56
|
+
// ⚠️ **`{0,64}` 的上界不是可选的,是 ReDoS 防护**(2026-10-05 实测)。
|
|
57
|
+
// 写成 `[\w$]*` 时外层 `{2,}` 与内层 `*` 在**无分隔符的超长 token** 上回溯爆炸:
|
|
58
|
+
// 20 万字符的连续 `x` → 本次实测 **54 秒**(单次 classify 27 秒)。
|
|
59
|
+
// 而 `message` 是**服务端返回的不可信字段**(`String(o.message ?? o.error ?? '')`),
|
|
60
|
+
// 网关/异常上游返回一个长 token 就会让 CLI 挂死 —— Agent 侧表现为无响应而非报错。
|
|
61
|
+
// 真实形态不受影响:HTML 错误页 45K → 2ms、长 JSON 117K → 2ms(都有分隔符)。
|
|
62
|
+
// 上界 64 对 Java 标识符段绰绰有余(实际段长极少超过 30),不损失任何脱敏能力。
|
|
63
|
+
out = out.replace(/[a-zA-Z_$][\w$]{0,64}(?:\.[a-zA-Z_$][\w$]{0,64}){2,}/g, '<内部类>');
|
|
64
|
+
// 32 位十六进制的内部 hint(每次请求都不同的请求 id,不得外泄)
|
|
65
|
+
out = out.replace(/\b[0-9a-f]{32}\b/g, '<已隐藏>');
|
|
66
|
+
return out;
|
|
67
|
+
}
|
|
68
|
+
const has = (m, s) => m.includes(s);
|
|
69
|
+
/**
|
|
70
|
+
* 按 message 文本分类。code 只是二级索引 ——
|
|
71
|
+
* 设计稿 §4.3 的实测结论:同一个 code 可以承载多种语义,反之同一语义也可跨 code。
|
|
72
|
+
*
|
|
73
|
+
* ⚠️ 这里**不填冷却秒数**。实测冷却随接口变化(报表约 30 秒、ipcc 60 秒、
|
|
74
|
+
* 知识库数分钟),任何写死在这里的秒数对某类接口必然是错的。
|
|
75
|
+
* `retryAfter` 由调用方按 `RATE_LIMITS` 填。
|
|
76
|
+
*
|
|
77
|
+
* ⚠️ **设计稿在限流的 `retryable` 上自相矛盾,本计划取 `true`,理由记在这里。**
|
|
78
|
+
* · §9.1 的失败示例把 `14009` 写作 `"retryable": false`
|
|
79
|
+
* · §4.3 的原则却是「凡是 CLI 自己能吸收的错误,都不以 `retryable: true` 的形式
|
|
80
|
+
* 暴露给 Agent」,并把 14003/14500/14501 列为 core 层吸收 —— **14009 不在其中**,
|
|
81
|
+
* 因为 core 吸收不了它(冷却随接口变化,core 不替 Agent 睡)
|
|
82
|
+
* · §11.2 D「错误处理协议」表按 `retry_after` 分流:「`rate_limit`(retry_after > 60)
|
|
83
|
+
* → **不要 sleep**,改为查询本地数据库」—— 这句话预设了 `retry_after <= 60`
|
|
84
|
+
* 时**可以** sleep 后重试,也就是 `retryable: true` 的那一支
|
|
85
|
+
* ⚠️ 这张表**不在 §9.4**(§9.4 是「名称解析」,讲 `--assignee` 的重名歧义)——
|
|
86
|
+
* 它在 §11.2「Skill / 内容」下的 D 表。此前这里误标为 §9.4,已更正。
|
|
87
|
+
* → 两处(§4.3 的原则 + §11.2 D 的分流)支持 `true`,只有 §9.1 的示例写 `false`。
|
|
88
|
+
* 取 `true` 的理由:若为 `false`,§11.2 D 那条「retry_after > 60 才不要 sleep」的
|
|
89
|
+
* 分流就没有意义(既然一律不可重试,就不必按秒数分流了)。**代价**:Agent 若
|
|
90
|
+
* 只看 `retryable` 而不看 `retry_after`,会对一个 180 秒冷却的接口(知识库)
|
|
91
|
+
* 立刻重试、继续吃 14009 —— 所以 `retry_after` **必须**随 `retryable: true` 一起
|
|
92
|
+
* 给出(`call()` 已保证:命中 `rate_limit` 必填 `retryAfter`)。
|
|
93
|
+
*/
|
|
94
|
+
export function classify(code, rawMessage) {
|
|
95
|
+
const raw = rawMessage ?? '';
|
|
96
|
+
const message = redactInternal(raw);
|
|
97
|
+
const base = { code: String(code), message };
|
|
98
|
+
const rate = () => ({ ...base, kind: 'rate_limit', retryable: true });
|
|
99
|
+
const param = (hint) => ({ ...base, kind: 'param', retryable: false, hint });
|
|
100
|
+
// —— 限流:先于错误码判断,因为它横跨 14009 / 14500 / 12001 / 14402 / 8011 ——
|
|
101
|
+
if (has(message, '单位时间内请求过于频繁'))
|
|
102
|
+
return rate();
|
|
103
|
+
if (has(message, 'too frequent'))
|
|
104
|
+
return rate();
|
|
105
|
+
if (has(message, 'Forbidden For Time rate'))
|
|
106
|
+
return rate();
|
|
107
|
+
if (has(message, '查询间隔小于一分钟'))
|
|
108
|
+
return rate();
|
|
109
|
+
// ⚠️ 会话导出创建(8011)的**两种**措辞(设计稿 §4.3)。
|
|
110
|
+
// `Too many running task` 里**没有任何限流词** —— 它既不含 `too frequent`
|
|
111
|
+
// 也不含 `too fast`,只靠 `case '8011'` 命中。若该措辞出现在别的码上就会漏判,
|
|
112
|
+
// 而设计稿反复强调"限流语义横跨多个错误码、必须按文本分派"。
|
|
113
|
+
// `create too fast` 同理(`too fast` ≠ `too frequent`)。
|
|
114
|
+
if (has(message, 'create too fast'))
|
|
115
|
+
return rate();
|
|
116
|
+
if (has(message, 'Too many running task'))
|
|
117
|
+
return rate();
|
|
118
|
+
// —— 14501 有两种含义,必须先按 message 区分(设计稿 §6.2)——
|
|
119
|
+
// 跨度问题 → 调用方切片重试;对齐问题 → 必须把 endTime 对齐到自然日边界。
|
|
120
|
+
// 两者错误码相同、修复方式完全不同;一律当"跨度"会让 Agent 反复重试无效操作。
|
|
121
|
+
if (String(code) === '14501') {
|
|
122
|
+
if (has(message, 'endTime is invalid'))
|
|
123
|
+
return { ...base, kind: 'window_misaligned', retryable: false,
|
|
124
|
+
hint: 'endTime 必须对齐到自然日边界(不得晚于今天 00:00)' };
|
|
125
|
+
if (has(message, 'is invalid'))
|
|
126
|
+
return { ...base, kind: 'window_too_large', retryable: false,
|
|
127
|
+
// ⚠️ 不要写"core 会重切" —— 本计划没有自动切片(见「已知缺口」),
|
|
128
|
+
// 那样 Agent 会等一个永远不发生的重试。主用户是 Agent,hint 必须是它能执行的动作。
|
|
129
|
+
//
|
|
130
|
+
// 报文里带着服务端自己的上限(`> 31 is invalid` / `> 365 is invalid`),
|
|
131
|
+
// 所以这里直接把那个数字指出来 —— 比让 Agent 去查注册表更可靠,
|
|
132
|
+
// 因为 `maxWindowDays` 只有已实测的接口才有。
|
|
133
|
+
hint: '时间跨度超出该接口上限。报文里的数字就是上限天数(如 `> 31` 即 31 天),' +
|
|
134
|
+
'请按它切片后重试;`qiyu api list` 里带 max_window_days 的接口也标了上限' };
|
|
135
|
+
return { ...base, kind: 'unknown', retryable: false };
|
|
136
|
+
}
|
|
137
|
+
// —— 14004 与 14500 一样是多义码(设计稿 §4.3 明确要求分发表)——
|
|
138
|
+
if (String(code) === '14004') {
|
|
139
|
+
if (has(message, '超出按天获取数据的最大时间范围'))
|
|
140
|
+
// 这条措辞来自 robot.statistic.summary:文档写 30 天,实测上限是 31。
|
|
141
|
+
// ⚠️ 报错文本里**不带**数字(与 14501 不同),所以只能给具体值 ——
|
|
142
|
+
// 这个值必须与注册表里该接口的 maxWindowDays 一致,改一处要改两处。
|
|
143
|
+
return { ...base, kind: 'window_too_large', retryable: false,
|
|
144
|
+
hint: '该接口实测上限 31 天(文档写 30,实测 31)。请按 31 天切片后重试' };
|
|
145
|
+
if (has(message, 'range over limit'))
|
|
146
|
+
// ⚠️ 实测(2026-10-01):`ticket.search` 的跨度硬限是 90 天,而报文里**不带数字**
|
|
147
|
+
// (与 14501 的 `> 31 is invalid` 不同)。只说"缩小窗口"是不可执行的 ——
|
|
148
|
+
// Agent 不知道缩到多少,很可能缩到 89 天再撞一次,或者缩得太小以致漏数据。
|
|
149
|
+
// 必须指向注册表的 max_window_days,那是唯一带准确数字的地方。
|
|
150
|
+
return { ...base, kind: 'window_too_large', retryable: false,
|
|
151
|
+
// ⚠️ hint 里**不得**写「90 天」这种与注册表冲突的数字(2026-10-07 修):
|
|
152
|
+
// 注册表对 ticket.search 给的是 max_window_days: 31,而旧 hint 先抛出一个
|
|
153
|
+
// 「实测为 90 天」—— Agent 刚被 91 天窗口拒,最自然的修法是退到那个更近的 90 天,
|
|
154
|
+
// 而那正是静默少取约 58 天的路径。上限只有一个权威来源:注册表。
|
|
155
|
+
hint: '时间跨度超出该接口上限。报文里不带数字,' +
|
|
156
|
+
'请按 `qiyu api list` 里该接口的 max_window_days 切片后重试' };
|
|
157
|
+
return param('服务端拒绝了参数,请核对字段名与类型');
|
|
158
|
+
}
|
|
159
|
+
switch (String(code)) {
|
|
160
|
+
// ⚠️ 设计稿 §4.3 实测**两种 404 形态**,必须归到同一个 kind:
|
|
161
|
+
// `/openapi/*` → Spring JSON `{status,timestamp,error,message,path}`(envelope.ts 识别)
|
|
162
|
+
// `/platform/api/*` → nginx HTML(http.ts 的 res.json() 失败分支识别)
|
|
163
|
+
// 两者是同一个事实(路由不存在 = 注册表路径写错了),不能一个判 route_not_found、
|
|
164
|
+
// 另一个落 unknown —— 那样 Agent 对同一故障要写两套处理。
|
|
165
|
+
case '404':
|
|
166
|
+
return { ...base, kind: 'route_not_found', retryable: false,
|
|
167
|
+
hint: '该接口在服务端不存在。这通常是注册表的路径写错了,请报告此问题;重试无用' };
|
|
168
|
+
// ⚠️ Spring Boot 的 `BasicErrorController` 对**所有**错误状态码都返回同一个
|
|
169
|
+
// 5 键 body(`{timestamp,status,error,message,path}`),而 envelope.ts 只按
|
|
170
|
+
// body 形状识别它、不区分 status 值。因此 401/403/500/503 都会带着
|
|
171
|
+
// `code: '500'` 之类到达这里。若不在这里兜住,它们会落到 `default` → `unknown`
|
|
172
|
+
// 且 `retryable:false` —— 一个瞬时的 5xx 会被 Agent 当成"未知错误"直接放弃。
|
|
173
|
+
// 5xx 是服务端故障(可退避重试),4xx(除已单独处理的 404)是请求侧问题。
|
|
174
|
+
// ⚠️ 这里只列**实测出现过**的四个 5xx(500/502/503/504)+ 429;设计稿 §5.3 的措辞
|
|
175
|
+
// 是「5xx/429」,但 501(未实现)/505(版本不支持)本身非瞬时,纳入重试反而有害。
|
|
176
|
+
// 故本集合是"实测子集",不是"5xx 全集" —— 执行者若要扩到 501/505,须先确证它们是瞬时的。
|
|
177
|
+
// ⚠️ 这组状态码必须与 http.ts 里 `res.json()` 失败分支的 `transient` 集合**逐字一致**
|
|
178
|
+
// (两处都是 429/500/502/503/504)—— 否则同一个 500 会因代理返回 HTML 还是 Spring JSON
|
|
179
|
+
// 被判成 internal 或 network,取决于代理行为,不是调用方能解释的差异。
|
|
180
|
+
// 401/403 同理,两处都归 `auth`。
|
|
181
|
+
case '429':
|
|
182
|
+
case '500':
|
|
183
|
+
case '502':
|
|
184
|
+
case '503':
|
|
185
|
+
case '504':
|
|
186
|
+
return { ...base, kind: 'network', retryable: true,
|
|
187
|
+
hint: `服务端/网关瞬时故障(HTTP ${code}),请退避后重试` };
|
|
188
|
+
case '401':
|
|
189
|
+
case '403':
|
|
190
|
+
return { ...base, kind: 'auth', retryable: false,
|
|
191
|
+
hint: `请求被拒绝(HTTP ${code})—— 凭证或权限问题,重试无用` };
|
|
192
|
+
case '14001':
|
|
193
|
+
return { ...base, kind: 'auth', retryable: false, hint: '请检查 QIYU_APP_KEY 是否正确' };
|
|
194
|
+
case '14002':
|
|
195
|
+
return { ...base, kind: 'auth', retryable: false, hint: '签名不匹配,这是 CLI 的内部缺陷' };
|
|
196
|
+
case '14003':
|
|
197
|
+
// core 层会**先用新时间戳重签重试一次**,正常情况下 Agent 不会看到这个错误。
|
|
198
|
+
// ⚠️ 但 Agent 能看到它,就说明重签也没救回来 —— 那是**本机时钟真的偏移了**
|
|
199
|
+
// (重签只是重读同一个错误的时钟)。此时 retryable:true 是危险的:
|
|
200
|
+
// Agent 会无限重试一个它自己修不好的东西。必须给出可执行的动作。
|
|
201
|
+
// ⚠️ 必须给出可执行的动作。⚠️ **不能只给 macOS 的命令**(2026-10-06 修):
|
|
202
|
+
// 此前写的是 `sudo sntp -sS time.apple.com` —— `-sS` 是 macOS 的 sntp 语法、
|
|
203
|
+
// `time.apple.com` 是苹果的 NTP 服务器,而这是个 `npx` 分发的**跨平台** npm 包
|
|
204
|
+
// (全局约束里没有任何平台限定)。在 Linux 容器里(Agent 的常见运行环境)
|
|
205
|
+
// 这条提示会指向一个跑不通或语法不同的命令 —— 与「hint 必须指向可执行的动作」
|
|
206
|
+
// 同一条标准,只是这次错在平台假设。改为按平台给两条,并让 Agent 能自己判断。
|
|
207
|
+
return { ...base, kind: 'bad_time', retryable: false,
|
|
208
|
+
hint: '本机时钟与服务器偏差超过 5 分钟,且重签重试无效。请校对本机时间后重试:' +
|
|
209
|
+
'macOS `sudo sntp -sS time.apple.com`;Linux `sudo timedatectl set-ntp true`' +
|
|
210
|
+
'(或 `sudo ntpdate pool.ntp.org`)。校时后原样重跑即可' };
|
|
211
|
+
case '14007':
|
|
212
|
+
// ⚠️ 必须给 hint(2026-10-05 修)。设计稿 §4.3 的补充错误码表记着厂商对该接口
|
|
213
|
+
// `code` 的描述是 "user does not exist or has not applied to connect to an agent",
|
|
214
|
+
// (⚠️ 该表在 §4.3「错误处理」,不是 §5「接口注册表」—— §5 全节不含 `14007`。)
|
|
215
|
+
// **与实际返回的 message 不一致** —— 而实测对未排队的 uid **每次调用都返回它**。
|
|
216
|
+
// 所以 agent 看到它时最可能犯的错是:① 以为"用户不存在"(描述是这么写的)
|
|
217
|
+
// 于是去删用户或报错说用户没了;② 反复重试(以为偶发)。
|
|
218
|
+
// 正确动作是"该 uid 尚未接入/排队,不是故障"。相邻的 14008/14100/14003
|
|
219
|
+
// 都有具体动作,14007 原先独缺一条 —— 与其同族的"告诉 agent 该做什么",
|
|
220
|
+
// 唯独这条只给了 kind,agent 只能自己猜(多半猜成 ①)。
|
|
221
|
+
return { ...base, kind: 'not_in_queue', retryable: false,
|
|
222
|
+
hint: '该 uid 未接入/未排队,属于业务状态而非故障 —— 不要重试。' +
|
|
223
|
+
'注意:厂商对该 code 的描述是"用户不存在",但**与实际返回的 message 不一致**;' +
|
|
224
|
+
'实测对未排队的 uid 每次调用都会返回它,因此不能据此判断用户已不存在' };
|
|
225
|
+
case '14008':
|
|
226
|
+
return { ...base, kind: 'auth', retryable: false, hint: '本机 IP 不在七鱼白名单中' };
|
|
227
|
+
case '14009':
|
|
228
|
+
case '12001':
|
|
229
|
+
case '14402':
|
|
230
|
+
return rate();
|
|
231
|
+
case '14515':
|
|
232
|
+
return { ...base, kind: 'auth', retryable: false, hint: '该接口需要单独申请权限' };
|
|
233
|
+
case '14100':
|
|
234
|
+
// 设计稿 §6.2:`ticket.list` 的 staffId 必须是在职客服。
|
|
235
|
+
// 实测 status=2/3 各 14/14 返回它,`0` 与不存在的 id 也返回它。
|
|
236
|
+
// 遍历全部客服同步时约 55% 会撞上 —— 若不给出具体语义,
|
|
237
|
+
// Agent 只会看到"参数错误"而不知道该按 status=1 过滤。
|
|
238
|
+
return { ...base, kind: 'param', retryable: false,
|
|
239
|
+
hint: '该客服不在职(或 id 不存在)。请先按 status=1 过滤在职客服再重试' };
|
|
240
|
+
case '14106':
|
|
241
|
+
// 设计稿 §9.0:`ticket.new.detail` / `ticket.log` 的失败路径返回它。
|
|
242
|
+
return { ...base, kind: 'param', retryable: false,
|
|
243
|
+
hint: '工单不存在或 worksheet 参数无效' };
|
|
244
|
+
case '14403':
|
|
245
|
+
// 设计稿 §7.5:会话导出**轮询未完成**时返回它 —— 这是正常中间态,
|
|
246
|
+
// 不是错误。判成 unknown/不可重试会让 Agent 放弃一个仍在进行的导出。
|
|
247
|
+
return { ...base, kind: 'pending', retryable: true,
|
|
248
|
+
hint: '会话导出任务尚未完成,请稍后再次轮询 check 接口' };
|
|
249
|
+
// —— 补充错误码:官方 10 行错误码表里完全没有它们 ——
|
|
250
|
+
case '8011':
|
|
251
|
+
// ⚠️ 设计稿 §4.3 补充表在 `8011`(会话导出创建)下并列了两种措辞:
|
|
252
|
+
// `create too fast`(§7.5 实测:创建限频每 10 秒 6 次)与 `Too many running task`
|
|
253
|
+
// (§7.5:并发上限/队列积压 —— 阈值高、实测未复现)。**两者都按限流处理是
|
|
254
|
+
// 本计划的判断**(对 Agent 的正确动作相同:退避重试)—— 只认前一种会让
|
|
255
|
+
// Agent 拿到 retryable:false 直接放弃,而它本该退避重试。
|
|
256
|
+
// (⚠️ 2026-10-08 更正:此前写"设计稿实测两种措辞都是限流",设计稿从未这么说。)
|
|
257
|
+
return rate();
|
|
258
|
+
case '8002':
|
|
259
|
+
return { ...base, kind: 'auth', retryable: false,
|
|
260
|
+
hint: '平台电商接口需要平台版 appKey' };
|
|
261
|
+
case '67406':
|
|
262
|
+
return param('短信接口参数缺失 —— 传空数组也会触发,不只是缺 key');
|
|
263
|
+
case '14200':
|
|
264
|
+
return param('分类接口的 type 取值非法');
|
|
265
|
+
case '14301':
|
|
266
|
+
return param('会话不存在,或模板类型非法');
|
|
267
|
+
case '8012':
|
|
268
|
+
return param('呼叫任务不存在');
|
|
269
|
+
case '67506':
|
|
270
|
+
return param('smstask 一次最多传入 100 个 id');
|
|
271
|
+
case '14500': {
|
|
272
|
+
if (has(message, 'Service Offline'))
|
|
273
|
+
return { ...base, kind: 'module_offline', retryable: false, hint: '该账号未开通此模块' };
|
|
274
|
+
if (has(message, 'Param format error'))
|
|
275
|
+
return param('参数类型错误;重试无用,还会烧掉限流配额');
|
|
276
|
+
if (has(message, 'can not cast to JSONObject'))
|
|
277
|
+
return param('请求体不是合法 JSON');
|
|
278
|
+
// 跨度超限 —— 在 NPE 检查之前(避免被兜底分支误判为内部错误)
|
|
279
|
+
if (has(message, '起止时间') && has(message, '不能超过') && has(message, '天'))
|
|
280
|
+
return { ...base, kind: 'window_too_large', retryable: false,
|
|
281
|
+
hint: '时间跨度超出该接口上限(如 transferHuman 的 365 天)。请自行切片后重试' };
|
|
282
|
+
// 以 `Cannot invoke "` 前缀为键 —— NPE 措辞不止一种,不能匹配单个类名
|
|
283
|
+
if (has(message, 'Cannot invoke'))
|
|
284
|
+
return param('缺少必填参数导致的服务端空指针');
|
|
285
|
+
// ⚠️ redactInternal 会把 `java.lang.NullPointerException` 替换成 `<内部类>`,
|
|
286
|
+
// 所以这里必须在 redact 之前检查原始 message(raw)
|
|
287
|
+
if (has(raw, 'NullPointerException'))
|
|
288
|
+
return param('缺少必填参数导致的服务端空指针');
|
|
289
|
+
// ⚠️ `14500` 下有三种**措辞近似、动作相反**的「内部错误」文本,
|
|
290
|
+
// 必须显式逐个匹配,**不能**依赖它们"恰好大小写不匹配、落到尾部兜底"。
|
|
291
|
+
// 设计稿 §4.3 的分发表把前两种列为可重试:
|
|
292
|
+
// · 可重试(服务端瞬时故障)—— `Unexpected internal error, hint:`(§4.3)
|
|
293
|
+
// 与 `Internal Error, retry later`(§4.3 分派表,措辞不同、同为可重试)
|
|
294
|
+
// · 裸 `Internal error` **不在 §4.3 表内** —— 按表体它落入末行
|
|
295
|
+
// 「以上都不匹配 → 退避重试」;本计划**有意偏离**该表、判为不可重试
|
|
296
|
+
// (⚠️ 2026-10-08 更正:此前把"不可重试"写成了设计稿的规定,实为本计划
|
|
297
|
+
// 的偏离 —— 完整记录见下方「这是本计划对 §4.3 分派表的一次有意偏离」段),
|
|
298
|
+
// 依据是 §6.2 记录的两个来源(`ticket.list` 传 staffId=-1/-99、
|
|
299
|
+
// 空结果集上 `page > 1` —— 都是 Agent 改参数就能解决的)
|
|
300
|
+
// ⚠️ 此处此前把 transferHuman 的超限窗口列为第三个来源,但 §7.4.1 已显式撤回
|
|
301
|
+
// "transferHuman 364 天会失败"这一成因,且该接口真正超限时报文带数字、
|
|
302
|
+
// 已被 `起止时间`+`不能超过`+`天` 三词分支接走,不会落到这一支。
|
|
303
|
+
// 这三者只差几个字符。**可重试白名单在前、大小写不敏感兜底在后**:
|
|
304
|
+
// 显式列出两种可重试措辞,再用 `/i` 兜住其余含 "internal error" 的 ——
|
|
305
|
+
// 这样分派**不依赖** `has` 恰好大小写敏感这一巧合(谁把 `has` 改成
|
|
306
|
+
// 大小写不敏感都不会串味),且白名单里的每一行都是承载语义的,
|
|
307
|
+
// 删掉任何一行都会有测试失败。
|
|
308
|
+
//
|
|
309
|
+
// ⚠️ 设计稿在此处**自相矛盾**,本计划按 §4.3 分派表实现,并在此记录争议:
|
|
310
|
+
// §4.3 的 `14500` 分派表说 `Internal Error, retry later` 是「服务端内部错误 → 退避重试」,
|
|
311
|
+
// 但 §9.0 的 `evaluation.setting.get` 条目又记录它是该接口**缺 fromType** 时的返回
|
|
312
|
+
// —— 缺参数重试无用。两处无法同时成立。选择"可重试"的理由:§4.3 是专门的
|
|
313
|
+
// `14500` 分派表(更权威、更具体),且"缺 fromType"只在一个接口上观察到,
|
|
314
|
+
// 不足以推翻它;万一判断错误,代价只是 Agent 多退避重试几次,而非静默失败。
|
|
315
|
+
// (设计稿 §4.3 脚注**曾**把这处争议源误标成 §10.1,该脚注现已自我更正;
|
|
316
|
+
// 实际条目在 **§9.0 信封特例**,§10.1 是"增量同步"、全文不含
|
|
317
|
+
// `evaluation.setting.get`。)
|
|
318
|
+
if (has(message, 'Unexpected internal error') || has(message, 'retry later'))
|
|
319
|
+
return { ...base, kind: 'internal', retryable: true };
|
|
320
|
+
// ⚠️ 光秃秃的 `Internal error` 是**已知有歧义**的:设计稿记录了**两个**来源、
|
|
321
|
+
// 而 message 逐字相同,无法区分 ——
|
|
322
|
+
// · `ticket.list` 传 `staffId=-1`/`-99` → **参数错误**(设计稿 §6.2 表设计)
|
|
323
|
+
// · 空结果集上 `page > 1`(翻页越界)→ **参数错误**(设计稿 §6.2)
|
|
324
|
+
// ⚠️ 此前这里列过第三条"`transferHuman` 用超限窗口",**已删除**:设计稿
|
|
325
|
+
// §7.4.1 明确**撤回**了早前"transferHuman 在 364 天会失败"的说法
|
|
326
|
+
//("不存在「边界不稳定」这回事……那是错的");实测 `transferHuman` 走精确比较、
|
|
327
|
+
// 在**恰好 365 天**被拒,报文是 `14500 起止时间不能超过365天` —— 那条**带数字**,
|
|
328
|
+
// 已被本文件的 `起止时间`+`不能超过`+`天` 三词分支接走(→ window_too_large),
|
|
329
|
+
// **根本不会落到裸 `Internal error` 这一支**。把它算作本支来源是错的。
|
|
330
|
+
// 两个来源都是 Agent 自己改一改就能解决的,**重试同一个请求永远失败**。
|
|
331
|
+
// 因此这里刻意**不**标 retryable:true —— 设计稿 §4.3 的原则是
|
|
332
|
+
// "凡是 CLI 自己能吸收的错误都不以 retryable:true 暴露",而这两个连
|
|
333
|
+
// CLI 都吸收不了(它不知道是哪个接口的哪种毛病),更不能让 Agent 去撞。
|
|
334
|
+
//
|
|
335
|
+
// ⚠️ **这是本计划对 §4.3 分派表的一次有意偏离,必须显式记录。**
|
|
336
|
+
// §4.3 的 `14500` 分派表最后一行是「以上都不匹配 → 未知内部错误 → 退避重试」,
|
|
337
|
+
// 按字面,裸 `Internal error` 不匹配前面任何一行(`retry later` 那行要求含
|
|
338
|
+
// `, retry later`,`Unexpected internal error` 那行要求含 `Unexpected`),
|
|
339
|
+
// 应落入该行 → 退避重试。本计划取反方向(不可重试),依据是 §6.2 的两条实测
|
|
340
|
+
// (`staffId=-1`/`-99`、空结果集 `page > 1` 都返回这条文本,都是参数错误)。
|
|
341
|
+
// 仅读 §4.3 的执行者不会预期这个方向 —— 故在此点明:这是设计稿内部
|
|
342
|
+
// §4.3 表体与 §6.2 实测的又一次冲突,本计划择 §6.2,方向偏保守
|
|
343
|
+
// (Agent 少试几次,而非对参数错误白烧限频预算)。若将来实测发现确有
|
|
344
|
+
// 瞬时故障也返回裸 `Internal error`,应改为可重试并同步更新本节与测试。
|
|
345
|
+
if (/internal error/i.test(message)) {
|
|
346
|
+
return { ...base, kind: 'internal', retryable: false,
|
|
347
|
+
hint: '该措辞有两个已知来源:参数无效(如 ticket.list 的 staffId=-1)、' +
|
|
348
|
+
'或空结果集上翻页越界(page > 1)。' +
|
|
349
|
+
'两者都无法靠重试解决,请检查参数(含页码)后重试' };
|
|
350
|
+
}
|
|
351
|
+
return { ...base, kind: 'internal', retryable: true };
|
|
352
|
+
}
|
|
353
|
+
default:
|
|
354
|
+
return { ...base, kind: 'unknown', retryable: false };
|
|
355
|
+
}
|
|
356
|
+
}
|