@wkgeo/cli 2.0.2 → 2.1.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/lib/errors.mjs CHANGED
@@ -1,336 +1,446 @@
1
- /**
2
- * 错误模型:把「服务端返回」翻译成「人能照做的下一步」。
3
- *
4
- * 本项目的**硬约定:HTTP 恒 200,错误在 body 的 `code` 里**(网关适配层统一信封)。
5
- * 所以判断成败**不能看 HTTP 状态码**,必须看 `body.code`。这一点踩过坑:
6
- * 早期 CLR 只看 `res.ok`,结果 403/429 全被当成"成功",然后拿着空 data 崩在下一步。
7
- *
8
- * 但有三个地方**不遵守**这个约定,必须单独处理(否则会把 OAuth 标准错误当业务码):
9
- * 1. `GET /api/oauth/userinfo` → HTTP 401 + `{error:'invalid_token', error_description}`
10
- * 2. `POST /api/oauth/token` → HTTP 400 + `{error:'invalid_grant', error_description}`
11
- * 3. `POST /api/oauth/introspect` → HTTP 200 + `{active:false}`(**不是错误**,是"无效")
12
- *
13
- * 关于"过期"这个信号,线上新旧两种版本都存在,**两种都要认**:
14
- * * 新:`40101` 令牌已过期 | `40102` 令牌已被吊销(本次另一个改动加的)
15
- * * 旧:只有 `401` + 文案"登录已过期,请重新登录"(过期/被吊销/没登录**完全一样**)
16
- * → 旧版只能给"运行 wkgeo login 重新授权"这种兼容提示,不能编造"是被吊销了"。
17
- */
18
-
19
- export const EXIT = {
20
- OK: 0,
21
- /** 一般性失败(业务错误、服务端错误、网络错误、参数不合法之外的异常) */
22
- ERROR: 1,
23
- /** 用法错误(命令/参数不对)—— 与"跑失败"区分开,脚本里好判断 */
24
- USAGE: 2,
25
- /** 需要(重新)授权:未登录 / 令牌过期 / 已被吊销 */
26
- AUTH: 3,
27
- /** 被限流:**明确不要**引导重新授权 */
28
- RATE_LIMIT: 4,
29
- };
30
-
31
- /** 需要重新授权时统一的下一步提示。命令名固定用官方 bin 名 `wkgeo`。 */
32
- export function loginHint(cmd = 'wkgeo') {
33
- return `运行 \`${cmd} login\` 重新授权(浏览器里通常还有登录态,点一下同意即可)`;
34
- }
35
-
36
- export class CliError extends Error {
37
- constructor(message, opts = {}) {
38
- super(message);
39
- this.name = 'CliError';
40
- this.kind = opts.kind || 'error';
41
- /** 服务端原始 code(数字或字符串),**必须保留**,不能吞掉 */
42
- this.code = opts.code === undefined ? null : opts.code;
43
- this.hint = opts.hint || null;
44
- this.retryAfter = opts.retryAfter === undefined ? null : opts.retryAfter;
45
- this.exitCode = opts.exitCode === undefined ? EXIT.ERROR : opts.exitCode;
46
- /** 原始响应(已脱敏),--verbose 时打印,便于排查"服务端到底说了什么" */
47
- this.raw = opts.raw === undefined ? null : opts.raw;
48
- /**
49
- * 结构化失败明细(`errorEnvelope` 会原样带进 `--json` 信封的 `error.details`)。
50
- * 典型用途:`content apply` 的 `rejected[]`、`content check` 的 `score/fixes`、
51
- * `template verify` 的动画对账 —— 让 AI 端拿到明细自己决定下一步,而不是只看一句话。
52
- */
53
- this.details = opts.details === undefined ? null : opts.details;
54
- this.cause = opts.cause;
55
- }
56
- }
57
-
58
- export class UsageError extends CliError {
59
- constructor(message, opts = {}) {
60
- super(message, { ...opts, kind: 'usage', exitCode: EXIT.USAGE });
61
- this.name = 'UsageError';
62
- }
63
- }
64
-
65
- /** 网络层失败:**保留原始 message**,绝不吞成"失败了" */
66
- export function networkError(detail, extra = {}) {
67
- return new CliError(`网络请求失败:${detail}`, {
68
- kind: 'network',
69
- hint: '检查网络/代理或稍后重试;若持续失败请确认服务是否正常(服务地址可用 --base 临时切换)',
70
- raw: extra.raw === undefined ? null : extra.raw,
71
- cause: extra.cause,
72
- });
73
- }
74
-
75
- /** 把服务端的 `code` 统一成数字(服务端有时回字符串) */
76
- function toCodeNumber(code) {
77
- if (code === undefined || code === null || code === '') return null;
78
- const n = Number(code);
79
- return Number.isFinite(n) ? n : null;
80
- }
81
-
82
- /**
83
- * "令牌无效"这一类错误(code=401 或 OAuth 标准的 invalid_token)到底该引导用户做什么。
84
- *
85
- * 背景(线上实测,2026-09-30):
86
- * * `/api/data` 与 `/api/oauth/userinfo` 现在都回 **HTTP 401 + `error:invalid_token`**,
87
- * 但 `error_description` 已经能区分:`访问令牌已被吊销,请重新授权` / 过期文案;
88
- * * 旧版则是一律 `登录已过期,请重新登录`;
89
- * * 新版的独立错误码 `40101/40102` **还没上线**(本次另一个改动在做)。
90
- * 所以这里**只按文案细化提示**,绝不编造 code —— 报告里要能说清"是文案判的还是码判的"。
91
- */
92
- function unauthenticatedClass(message, { httpStatus = 401, cmdName = 'wkgeo' } = {}) {
93
- const text = String(message || '');
94
- const base = {
95
- code: text && httpStatus ? httpStatus : httpStatus,
96
- exitCode: EXIT.AUTH,
97
- };
98
- if (/吊销|撤销|revoked/i.test(text)) {
99
- return {
100
- kind: 'revoked',
101
- ok: false,
102
- message: text,
103
- hint: `授权已被吊销,请重新登录授权:\`${cmdName} login\`(服务端没有给出可区分的错误码,是按文案判定的)`,
104
- retryAfter: null,
105
- ...base,
106
- };
107
- }
108
- if (/过期|expired/i.test(text)) {
109
- return {
110
- kind: 'expired',
111
- ok: false,
112
- message: text,
113
- hint: `${loginHint(cmdName)}(服务端没有给出可区分的错误码,是按文案判定的)`,
114
- retryAfter: null,
115
- ...base,
116
- };
117
- }
118
- return {
119
- kind: 'unauthenticated',
120
- ok: false,
121
- message: text || '登录已过期,请重新登录',
122
- hint: `${loginHint(cmdName)}(服务端只回了 401/invalid_token,"过期"与"被吊销"分不出来)`,
123
- retryAfter: null,
124
- ...base,
125
- };
126
- }
127
-
128
- /**
129
- * 判定一次响应。
130
- * @returns {{kind:string, ok:boolean, code:any, message:string, hint:string|null, retryAfter:number|null, exitCode:number}}
131
- * kind 取值:ok / network / expired / revoked / unauthenticated / rate_limited /
132
- * forbidden / step_up / bad_request / not_found / server / denied / unknown
133
- */
134
- export function classifyResponse({ httpStatus = 200, body = null, action = '', retryAfterHeader = null, cmdName = 'wkgeo' } = {}) {
135
- const ok = (extra = {}) => ({ kind: 'ok', ok: true, code: 0, message: '', hint: null, retryAfter: null, exitCode: EXIT.OK, ...extra });
136
- const bad = (kind, message, extra = {}) => ({
137
- kind,
138
- ok: false,
139
- code: extra.code === undefined ? null : extra.code,
140
- message: message || '请求失败(服务端未给出原因)',
141
- hint: extra.hint === undefined ? null : extra.hint,
142
- retryAfter: extra.retryAfter === undefined ? null : extra.retryAfter,
143
- exitCode: extra.exitCode === undefined ? EXIT.ERROR : extra.exitCode,
144
- });
145
-
146
- const retryAfterOf = (src) => {
147
- const cand = [
148
- src && src.retry_after,
149
- src && src.data && src.data.retry_after,
150
- retryAfterHeader,
151
- ];
152
- for (const c of cand) {
153
- const n = Number(c);
154
- if (Number.isFinite(n) && n >= 0) return n;
155
- }
156
- return null;
157
- };
158
-
159
- // ---- 1. 网络层(连不上/超时):没有 body,status 0 ----
160
- if (httpStatus === 0) {
161
- return bad('network', typeof body === 'string' ? body : (body && body.message) || '连接失败', {
162
- hint: '检查网络或稍后重试',
163
- });
164
- }
165
-
166
- // ---- 2. OAuth 标准错误形状(userinfo / token / revoke / introspect)----
167
- if (body && typeof body === 'object' && typeof body.error === 'string' && body.code === undefined) {
168
- const err = body.error;
169
- const desc = String(body.error_description || body.message || err);
170
- if (err === 'invalid_token') {
171
- // userinfo 的 401:OAuth 标准只有一个 invalid_token,但线上文案已经能区分吊销/过期
172
- return unauthenticatedClass(desc, { httpStatus: httpStatus || 401, cmdName });
173
- }
174
- if (err === 'slow_down') {
175
- const ra = retryAfterOf(body);
176
- return bad('rate_limited', desc, {
177
- code: 429,
178
- retryAfter: ra,
179
- hint: ra === null ? '调用过于频繁,请稍后重试(**不需要**重新授权)' : `调用过于频繁,请 ${ra} 秒后重试(**不需要**重新授权)`,
180
- exitCode: EXIT.RATE_LIMIT,
181
- });
182
- }
183
- if (err === 'invalid_grant') {
184
- return bad('bad_request', desc, {
185
- code: 400,
186
- hint: '授权码可能已过期(5 分钟)或被使用过;重新运行 `' + cmdName + ' login` 即可',
187
- exitCode: EXIT.ERROR,
188
- });
189
- }
190
- if (err === 'access_denied') {
191
- return bad('denied', desc, { code: 403, hint: '用户拒绝了授权' });
192
- }
193
- if (err === 'server_error') return bad('server', desc, { code: httpStatus || 500 });
194
- return bad('unknown', desc, { code: httpStatus, exitCode: httpStatus >= 500 ? EXIT.ERROR : EXIT.ERROR });
195
- }
196
-
197
- // ---- 3. 项目统一信封 {code, message, data} ----
198
- const codeNum = toCodeNumber(body && body.code);
199
- const message = String((body && (body.message || body.msg)) || '');
200
- const ra = retryAfterOf(body);
201
-
202
- if (codeNum === 0) return ok();
203
-
204
- if (codeNum === 40101) {
205
- return bad('expired', message || '访问令牌已过期', {
206
- code: 40101,
207
- hint: loginHint(cmdName),
208
- exitCode: EXIT.AUTH,
209
- });
210
- }
211
- if (codeNum === 40102) {
212
- return bad('revoked', message || '访问令牌已被吊销', {
213
- code: 40102,
214
- hint: `授权已被吊销,请重新登录授权:\`${cmdName} login\``,
215
- exitCode: EXIT.AUTH,
216
- });
217
- }
218
- if (codeNum === 401) {
219
- return unauthenticatedClass(message, { httpStatus: 401, cmdName });
220
- }
221
- if (codeNum === 429 || httpStatus === 429) {
222
- return bad('rate_limited', message || '调用过于频繁', {
223
- code: 429,
224
- retryAfter: ra,
225
- // ⚠️ 限流**绝不能**引导用户去重新授权:重授权解决不了限流,还会白跑一遍浏览器。
226
- hint: ra === null
227
- ? '调用过于频繁,请稍后重试(**不需要**重新授权)'
228
- : `调用过于频繁,请 ${ra} 秒后重试(**不需要**重新授权)`,
229
- exitCode: EXIT.RATE_LIMIT,
230
- });
231
- }
232
- if (codeNum === 403) {
233
- /**
234
- * 内容类自持动作(`/cli` 的 B1 45 条)的固定文案,见
235
- * `aliyun/fc/wkgeo-cli-fc/src/content-core.js` 的 `resolveContentSite()`:
236
- * 「这不是你的站点:CLI 只能操作自己名下的站(site.owner_id ≠ 当前用户)」。
237
- * 这跟 CMS 面「你不是该站点的成员」不同:CLI 根本不认成员站,只能操作 owner 是自己的站,
238
- * 所以提示要他说清"换站"而不是"找 owner 提权",更不能引导去重新授权。
239
- */
240
- if (/这不是你的站点/.test(message)) {
241
- return bad('not_site_owner', message, {
242
- code: 403,
243
- hint:
244
- 'CLI 只能操作「站点 owner 是你自己」的站(比 CMS 后台更严,成员站请在 CMS 后台操作):' +
245
- `\`${cmdName} sites list\` 里挑一个你的站,再 \`${cmdName} site use <站点ID>\` 或本次加 \`--site <站点ID>\`。`,
246
- });
247
- }
248
- // 「令牌缺少权限 site:write:请重新授权(授权 scope 需包含 site:write)」——是 scope 不够,重登即可
249
- if (/令牌缺少权限/.test(message)) {
250
- return bad('cms_scope', message, {
251
- code: 403,
252
- hint: `令牌的 scope 不够:\`${cmdName} login\` 重新授权一次(默认已含 site:write);旧令牌不会自动获得新能力。`,
253
- });
254
- }
255
- const hint = /未授予|scope|令牌范围/i.test(message)
256
- ? `令牌的能力不足(scope 收敛)。若确实需要该能力:\`${cmdName} login --scope "site:read site:write billing:self"\` 重新授权`
257
- : '权限不足:敏感动作(动钱/改权限)需要二次验证,OAuth 令牌做不到,请在网页后台操作';
258
- return bad('forbidden', message || '无权限', { code: 403, hint });
259
- }
260
- if (codeNum === 428) {
261
- return bad('step_up', message || '需要二次验证', {
262
- code: 428,
263
- hint: '该动作要求 5 分钟内重新输入密码(step-up)。CLI 令牌没有密码入口 → 请在网页后台操作',
264
- });
265
- }
266
- if (codeNum === 404) return bad('not_found', message || '资源不存在', { code: 404 });
267
- /**
268
- * ★ 2026-11-17(task-627):**409 = 状态冲突**(下单打进来才有,之前落到 `unknown`)。
269
- *
270
- * 两种要分开:
271
- * · `idempotency_mismatch` —— 同一幂等键的参数与已建订单不一致(**这一单其实已经建好了**)。
272
- * 服务端原文带实现词 `idempotency_key`,**不能照抄给用户**,翻成"别重复下单 + 怎么继续付";
273
- * · 其余(`ICP_ASSIST_OPEN_ORDER_EXISTS` 还有未完成服务单 / `VIP_ALREADY_ACTIVE` 仍在有效期)
274
- * 后端文案本身就是人话 ⇒ 原样透出,只补一句下一步。
275
- */
276
- if (codeNum === 409) {
277
- const biz = String(
278
- (body && (body.error_code || (body.data && body.data.code))) || '',
279
- );
280
- if (biz === 'idempotency_mismatch' || /idempotency/i.test(message)) {
281
- return bad(
282
- 'conflict',
283
- '这一单已经创建,请不要重复下单:订单 30 分钟内未支付会自动关闭(优惠券随之释放),' +
284
- '关闭后再重新下单即可;也可以在网页「我的订单」里继续支付。',
285
- {
286
- code: 409,
287
- hint:
288
- `先 \`${cmdName} orders list\` 看这一单在不在;待支付就去网页收银台付,` +
289
- `或 \`${cmdName} orders pay <订单号>\` 查一次状态。**不要**换个参数再下一单(会锁券、留多张待支付单)。`,
290
- },
291
- );
292
- }
293
- return bad('conflict', message || '该操作与当前状态冲突,请刷新后重试', {
294
- code: 409,
295
- hint: '按提示处理后再试;不要靠重复下单绕过(会锁券 / 留下多张待支付单)。',
296
- });
297
- }
298
- if (codeNum === 400) {
299
- // 内容类自持动作没带站点(`content-core.js` 的「缺少 siteId:CLI 内容动作必须指定站点…」)
300
- if (/缺少 siteId|指定站点/.test(message)) {
301
- return bad('cms_site_required', message, {
302
- code: 400,
303
- hint: `先 \`${cmdName} site use <站点ID>\`(记住),或本次加 \`--site <站点ID>\`;站点 ID 见 \`${cmdName} sites list\`。`,
304
- });
305
- }
306
- return bad('bad_request', message || '请求不合法', { code: 400 });
307
- }
308
- if (codeNum !== null && codeNum >= 500) return bad('server', message || `服务端错误(${codeNum})`, { code: codeNum });
309
- if (codeNum !== null) return bad('unknown', message || `未知错误(code=${codeNum})`, { code: codeNum });
310
-
311
- // ---- 4. 既没有 code 也没有 error:按 HTTP 状态兜底(例如网关 5xx 直出)----
312
- if (httpStatus >= 500) return bad('server', message || `服务端错误(HTTP ${httpStatus})`, { code: httpStatus });
313
- if (httpStatus === 401) {
314
- return unauthenticatedClass(message, { httpStatus: 401, cmdName });
315
- }
316
- if (httpStatus >= 400) return bad('unknown', message || `请求失败(HTTP ${httpStatus})`, { code: httpStatus });
317
- if (httpStatus >= 200 && httpStatus < 300) {
318
- // HTTP 200 但没有 code 字段:可能是纯 REST 形状(比如 PG REST 直出数组)。
319
- // 这种不算错,交给调用方处理 body 本身。
320
- return ok({ code: null });
321
- }
322
- return bad('unknown', message || `无法识别的响应(HTTP ${httpStatus})`, { code: httpStatus });
323
- }
324
-
325
- /** 把 classify 结果变成可抛出的 CliError */
326
- export function toCliError(classified, { action = '', raw = null } = {}) {
327
- const where = action ? `(${action})` : '';
328
- return new CliError(`${classified.message}${where ? ' ' + where : ''}`, {
329
- kind: classified.kind,
330
- code: classified.code,
331
- hint: classified.hint,
332
- retryAfter: classified.retryAfter,
333
- exitCode: classified.exitCode,
334
- raw,
335
- });
336
- }
1
+ /**
2
+ * 错误模型:把「服务端返回」翻译成「人能照做的下一步」。
3
+ *
4
+ * 本项目的**硬约定:HTTP 恒 200,错误在 body 的 `code` 里**(网关适配层统一信封)。
5
+ * 所以判断成败**不能看 HTTP 状态码**,必须看 `body.code`。这一点踩过坑:
6
+ * 早期 CLR 只看 `res.ok`,结果 403/429 全被当成"成功",然后拿着空 data 崩在下一步。
7
+ *
8
+ * 但有三个地方**不遵守**这个约定,必须单独处理(否则会把 OAuth 标准错误当业务码):
9
+ * 1. `GET /api/oauth/userinfo` → HTTP 401 + `{error:'invalid_token', error_description}`
10
+ * 2. `POST /api/oauth/token` → HTTP 400 + `{error:'invalid_grant', error_description}`
11
+ * 3. `POST /api/oauth/introspect` → HTTP 200 + `{active:false}`(**不是错误**,是"无效")
12
+ *
13
+ * 关于"过期"这个信号,线上新旧两种版本都存在,**两种都要认**:
14
+ * * 新:`40101` 令牌已过期 | `40102` 令牌已被吊销(本次另一个改动加的)
15
+ * * 旧:只有 `401` + 文案"登录已过期,请重新登录"(过期/被吊销/没登录**完全一样**)
16
+ * → 旧版只能给"运行 wkgeo login 重新授权"这种兼容提示,不能编造"是被吊销了"。
17
+ */
18
+
19
+ export const EXIT = {
20
+ OK: 0,
21
+ /** 一般性失败(业务错误、服务端错误、网络错误、参数不合法之外的异常) */
22
+ ERROR: 1,
23
+ /** 用法错误(命令/参数不对)—— 与"跑失败"区分开,脚本里好判断 */
24
+ USAGE: 2,
25
+ /** 需要(重新)授权:未登录 / 令牌过期 / 已被吊销 */
26
+ AUTH: 3,
27
+ /** 被限流:**明确不要**引导重新授权 */
28
+ RATE_LIMIT: 4,
29
+ };
30
+
31
+ /** 需要重新授权时统一的下一步提示。命令名固定用官方 bin 名 `wkgeo`。 */
32
+ export function loginHint(cmd = 'wkgeo') {
33
+ return `运行 \`${cmd} login\` 重新授权(浏览器里通常还有登录态,点一下同意即可)`;
34
+ }
35
+
36
+ export class CliError extends Error {
37
+ constructor(message, opts = {}) {
38
+ super(message);
39
+ this.name = 'CliError';
40
+ this.kind = opts.kind || 'error';
41
+ /** 服务端原始 code(数字或字符串),**必须保留**,不能吞掉 */
42
+ this.code = opts.code === undefined ? null : opts.code;
43
+ this.hint = opts.hint || null;
44
+ this.retryAfter = opts.retryAfter === undefined ? null : opts.retryAfter;
45
+ this.exitCode = opts.exitCode === undefined ? EXIT.ERROR : opts.exitCode;
46
+ /** 原始响应(已脱敏),--verbose 时打印,便于排查"服务端到底说了什么" */
47
+ this.raw = opts.raw === undefined ? null : opts.raw;
48
+ /**
49
+ * 结构化失败明细(`errorEnvelope` 会原样带进 `--json` 信封的 `error.details`)。
50
+ * 典型用途:`content apply` 的 `rejected[]`、`content check` 的 `score/fixes`、
51
+ * `template verify` 的动画对账 —— 让 AI 端拿到明细自己决定下一步,而不是只看一句话。
52
+ */
53
+ this.details = opts.details === undefined ? null : opts.details;
54
+ this.cause = opts.cause;
55
+ }
56
+ }
57
+
58
+ export class UsageError extends CliError {
59
+ constructor(message, opts = {}) {
60
+ super(message, { ...opts, kind: 'usage', exitCode: EXIT.USAGE });
61
+ this.name = 'UsageError';
62
+ }
63
+ }
64
+
65
+ /** 网络层失败:**保留原始 message**,绝不吞成"失败了" */
66
+ export function networkError(detail, extra = {}) {
67
+ return new CliError(`网络请求失败:${detail}`, {
68
+ kind: 'network',
69
+ hint: '检查网络/代理或稍后重试;若持续失败请确认服务是否正常(服务地址可用 --base 临时切换)',
70
+ raw: extra.raw === undefined ? null : extra.raw,
71
+ cause: extra.cause,
72
+ });
73
+ }
74
+
75
+ /**
76
+ * 「这个站要求按站票据(site credential)才能写入」的判定。
77
+ *
78
+ * 平台开关 `SITE_CRED_WRITE_MODE=off|pilot|all` 打开后,账号令牌写站会被
79
+ * **403 `site_credential_required`** 挡掉,只有该站的短票能写。
80
+ * 这是**权限升级**带来的正常拒绝,不是"令牌过期 / 被吊销"——绝不能引导用户去重新登录
81
+ * (重登拿到的是账号令牌,还是写不了),否则会陷入"重登 → 还是 403"的死循环。
82
+ *
83
+ * @returns {boolean}
84
+ */
85
+ export function isSiteCredentialRequired(body) {
86
+ if (!body || typeof body !== 'object') return false;
87
+ const err = typeof body.error === 'string'
88
+ ? body.error
89
+ : typeof body.code === 'string'
90
+ ? body.code
91
+ : '';
92
+ if (err === 'site_credential_required') return true;
93
+ return /site_credential_required/.test(String(body.message || body.msg || ''));
94
+ }
95
+
96
+ /** 「需要站点票据」时给的可照做的提示(不含任何 token / 内部路径细节) */
97
+ function siteCredentialRequiredHint() {
98
+ return (
99
+ '这个站点现在要求**按站票据**才能写入:在「网站运营」面板点该站点卡片进入项目对话,' +
100
+ '插件会自动为该目录签一张短票(15 分钟有效、对话还在该站目录时会自动续签);' +
101
+ '在该站点目录里运行 CLI 会自动命中这张票。账号令牌(登录态)只能读、不能写。'
102
+ );
103
+ }
104
+
105
+ /**
106
+ * ★ v14:拿 A 站的票去写 B 站(平台 403 `site_key_site_mismatch`)。
107
+ * 这是「票绑错站」,不是登录过期,更不是平台没上线——不许重试、不许当成功。
108
+ */
109
+ export function isSiteKeyMismatch(body) {
110
+ if (!body || typeof body !== 'object') return false;
111
+ const err = typeof body.error === 'string'
112
+ ? body.error
113
+ : typeof body.code === 'string'
114
+ ? body.code
115
+ : '';
116
+ if (err === 'site_key_site_mismatch') return true;
117
+ return /site_key_site_mismatch/.test(String(body.message || body.msg || ''));
118
+ }
119
+
120
+ function siteKeyMismatchHint() {
121
+ return (
122
+ '这张按站票据绑定的是另一个站点:回「网站运营」面板,点你要操作的那个站点卡片重新进入对话' +
123
+ '(会重新签该站的票)。不要拿一个站的票去写另一个站。'
124
+ );
125
+ }
126
+
127
+ /**
128
+ * ★ v14:平台在「票通过」之后又按实时管理权拒了(站点被转移 / 停用 / 删除 / 源 Key 吊销)。
129
+ * 原样翻人话;**不许重试、不许降级账号令牌、不许当成功**。
130
+ */
131
+ export const SITE_MANAGE_ERROR_CODES = ['site_not_owned', 'site_unavailable', 'site_credential_revoked'];
132
+
133
+ export function isSiteManageDenied(body) {
134
+ if (!body || typeof body !== 'object') return false;
135
+ const err = typeof body.error === 'string'
136
+ ? body.error
137
+ : typeof body.code === 'string'
138
+ ? body.code
139
+ : '';
140
+ if (SITE_MANAGE_ERROR_CODES.includes(err)) return true;
141
+ const text = String(body.message || body.msg || '');
142
+ return SITE_MANAGE_ERROR_CODES.some((code) => text.includes(code));
143
+ }
144
+
145
+ function siteManageDeniedHint() {
146
+ return (
147
+ '权限以平台实时判定为准:站点可能已被转移、被停用 / 删除,或你的 Key 已失效。' +
148
+ '去「网站运营」面板重新填 Key / 重新点站点卡片;不要重试,也不要改用别的凭据绕过。'
149
+ );
150
+ }
151
+
152
+ /** 把服务端的 `code` 统一成数字(服务端有时回字符串) */
153
+ function toCodeNumber(code) {
154
+ if (code === undefined || code === null || code === '') return null;
155
+ const n = Number(code);
156
+ return Number.isFinite(n) ? n : null;
157
+ }
158
+
159
+ /**
160
+ * "令牌无效"这一类错误(code=401 或 OAuth 标准的 invalid_token)到底该引导用户做什么。
161
+ *
162
+ * 背景(线上实测,2026-09-30):
163
+ * * `/api/data` 与 `/api/oauth/userinfo` 现在都回 **HTTP 401 + `error:invalid_token`**,
164
+ * 但 `error_description` 已经能区分:`访问令牌已被吊销,请重新授权` / 过期文案;
165
+ * * 旧版则是一律 `登录已过期,请重新登录`;
166
+ * * 新版的独立错误码 `40101/40102` **还没上线**(本次另一个改动在做)。
167
+ * 所以这里**只按文案细化提示**,绝不编造 code —— 报告里要能说清"是文案判的还是码判的"。
168
+ */
169
+ function unauthenticatedClass(message, { httpStatus = 401, cmdName = 'wkgeo' } = {}) {
170
+ const text = String(message || '');
171
+ const base = {
172
+ code: text && httpStatus ? httpStatus : httpStatus,
173
+ exitCode: EXIT.AUTH,
174
+ };
175
+ if (/吊销|撤销|revoked/i.test(text)) {
176
+ return {
177
+ kind: 'revoked',
178
+ ok: false,
179
+ message: text,
180
+ hint: `授权已被吊销,请重新登录授权:\`${cmdName} login\`(服务端没有给出可区分的错误码,是按文案判定的)`,
181
+ retryAfter: null,
182
+ ...base,
183
+ };
184
+ }
185
+ if (/过期|expired/i.test(text)) {
186
+ return {
187
+ kind: 'expired',
188
+ ok: false,
189
+ message: text,
190
+ hint: `${loginHint(cmdName)}(服务端没有给出可区分的错误码,是按文案判定的)`,
191
+ retryAfter: null,
192
+ ...base,
193
+ };
194
+ }
195
+ return {
196
+ kind: 'unauthenticated',
197
+ ok: false,
198
+ message: text || '登录已过期,请重新登录',
199
+ hint: `${loginHint(cmdName)}(服务端只回了 401/invalid_token,"过期"与"被吊销"分不出来)`,
200
+ retryAfter: null,
201
+ ...base,
202
+ };
203
+ }
204
+
205
+ /**
206
+ * 判定一次响应。
207
+ * @returns {{kind:string, ok:boolean, code:any, message:string, hint:string|null, retryAfter:number|null, exitCode:number}}
208
+ * kind 取值:ok / network / expired / revoked / unauthenticated / rate_limited /
209
+ * forbidden / step_up / bad_request / not_found / server / denied / unknown
210
+ */
211
+ export function classifyResponse({ httpStatus = 200, body = null, action = '', retryAfterHeader = null, cmdName = 'wkgeo' } = {}) {
212
+ const ok = (extra = {}) => ({ kind: 'ok', ok: true, code: 0, message: '', hint: null, retryAfter: null, exitCode: EXIT.OK, ...extra });
213
+ const bad = (kind, message, extra = {}) => ({
214
+ kind,
215
+ ok: false,
216
+ code: extra.code === undefined ? null : extra.code,
217
+ message: message || '请求失败(服务端未给出原因)',
218
+ hint: extra.hint === undefined ? null : extra.hint,
219
+ retryAfter: extra.retryAfter === undefined ? null : extra.retryAfter,
220
+ exitCode: extra.exitCode === undefined ? EXIT.ERROR : extra.exitCode,
221
+ });
222
+
223
+ const retryAfterOf = (src) => {
224
+ const cand = [
225
+ src && src.retry_after,
226
+ src && src.data && src.data.retry_after,
227
+ retryAfterHeader,
228
+ ];
229
+ for (const c of cand) {
230
+ const n = Number(c);
231
+ if (Number.isFinite(n) && n >= 0) return n;
232
+ }
233
+ return null;
234
+ };
235
+
236
+ // ---- 1. 网络层(连不上/超时):没有 body,status 0 ----
237
+ if (httpStatus === 0) {
238
+ return bad('network', typeof body === 'string' ? body : (body && body.message) || '连接失败', {
239
+ hint: '检查网络或稍后重试',
240
+ });
241
+ }
242
+
243
+ /**
244
+ * ★ v14:按站票据拒绝(403 / 401 都可能,平台开关 `SITE_CRED_WRITE_MODE` 打开后才会有)。
245
+ * 放在 OAuth 标准形状与统一信封判定**之前**,因为两种形状都可能带这个 error 标记。
246
+ */
247
+ if (isSiteCredentialRequired(body)) {
248
+ const message =
249
+ (body && typeof body === 'object' && (body.message || body.msg)) || '该站点需要按站票据才能写入';
250
+ return bad('site_credential_required', message, {
251
+ code: httpStatus || 403,
252
+ hint: siteCredentialRequiredHint(),
253
+ });
254
+ }
255
+
256
+ /** ★ v14:票绑错站(403 site_key_site_mismatch)——不重试、不当成功。 */
257
+ if (isSiteKeyMismatch(body)) {
258
+ const message =
259
+ (body && typeof body === 'object' && (body.message || body.msg)) || '这张按站票据不属于当前站点';
260
+ return bad('site_key_site_mismatch', message, {
261
+ code: httpStatus || 403,
262
+ hint: siteKeyMismatchHint(),
263
+ });
264
+ }
265
+
266
+ /** ★ v14:平台实时管理权拒(站点被转移 / 停用 / 源 Key 吊销)。 */
267
+ if (isSiteManageDenied(body)) {
268
+ const message =
269
+ (body && typeof body === 'object' && (body.message || body.msg)) || '你当前没有这个站的管理权限';
270
+ return bad('site_manage_denied', message, {
271
+ code: httpStatus || 403,
272
+ hint: siteManageDeniedHint(),
273
+ });
274
+ }
275
+
276
+ // ---- 2. OAuth 标准错误形状(userinfo / token / revoke / introspect)----
277
+ if (body && typeof body === 'object' && typeof body.error === 'string' && body.code === undefined) {
278
+ const err = body.error;
279
+ const desc = String(body.error_description || body.message || err);
280
+ if (err === 'invalid_token') {
281
+ // userinfo 的 401:OAuth 标准只有一个 invalid_token,但线上文案已经能区分吊销/过期
282
+ return unauthenticatedClass(desc, { httpStatus: httpStatus || 401, cmdName });
283
+ }
284
+ if (err === 'slow_down') {
285
+ const ra = retryAfterOf(body);
286
+ return bad('rate_limited', desc, {
287
+ code: 429,
288
+ retryAfter: ra,
289
+ hint: ra === null ? '调用过于频繁,请稍后重试(**不需要**重新授权)' : `调用过于频繁,请 ${ra} 秒后重试(**不需要**重新授权)`,
290
+ exitCode: EXIT.RATE_LIMIT,
291
+ });
292
+ }
293
+ if (err === 'invalid_grant') {
294
+ return bad('bad_request', desc, {
295
+ code: 400,
296
+ hint: '授权码可能已过期(5 分钟)或被使用过;重新运行 `' + cmdName + ' login` 即可',
297
+ exitCode: EXIT.ERROR,
298
+ });
299
+ }
300
+ if (err === 'access_denied') {
301
+ return bad('denied', desc, { code: 403, hint: '用户拒绝了授权' });
302
+ }
303
+ if (err === 'server_error') return bad('server', desc, { code: httpStatus || 500 });
304
+ return bad('unknown', desc, { code: httpStatus, exitCode: httpStatus >= 500 ? EXIT.ERROR : EXIT.ERROR });
305
+ }
306
+
307
+ // ---- 3. 项目统一信封 {code, message, data} ----
308
+ const codeNum = toCodeNumber(body && body.code);
309
+ const message = String((body && (body.message || body.msg)) || '');
310
+ const ra = retryAfterOf(body);
311
+
312
+ if (codeNum === 0) return ok();
313
+
314
+ if (codeNum === 40101) {
315
+ return bad('expired', message || '访问令牌已过期', {
316
+ code: 40101,
317
+ hint: loginHint(cmdName),
318
+ exitCode: EXIT.AUTH,
319
+ });
320
+ }
321
+ if (codeNum === 40102) {
322
+ return bad('revoked', message || '访问令牌已被吊销', {
323
+ code: 40102,
324
+ hint: `授权已被吊销,请重新登录授权:\`${cmdName} login\``,
325
+ exitCode: EXIT.AUTH,
326
+ });
327
+ }
328
+ if (codeNum === 401) {
329
+ return unauthenticatedClass(message, { httpStatus: 401, cmdName });
330
+ }
331
+ if (codeNum === 429 || httpStatus === 429) {
332
+ return bad('rate_limited', message || '调用过于频繁', {
333
+ code: 429,
334
+ retryAfter: ra,
335
+ // ⚠️ 限流**绝不能**引导用户去重新授权:重授权解决不了限流,还会白跑一遍浏览器。
336
+ hint: ra === null
337
+ ? '调用过于频繁,请稍后重试(**不需要**重新授权)'
338
+ : `调用过于频繁,请 ${ra} 秒后重试(**不需要**重新授权)`,
339
+ exitCode: EXIT.RATE_LIMIT,
340
+ });
341
+ }
342
+ if (codeNum === 403) {
343
+ /**
344
+ * 内容类自持动作(`/cli` 的 B1 45 条)的固定文案,见
345
+ * `aliyun/fc/wkgeo-cli-fc/src/content-core.js` 的 `resolveContentSite()`:
346
+ * 「这不是你的站点:CLI 只能操作自己名下的站(site.owner_id ≠ 当前用户)」。
347
+ * 这跟 CMS 面「你不是该站点的成员」不同:CLI 根本不认成员站,只能操作 owner 是自己的站,
348
+ * 所以提示要他说清"换站"而不是"找 owner 提权",更不能引导去重新授权。
349
+ */
350
+ if (/这不是你的站点/.test(message)) {
351
+ return bad('not_site_owner', message, {
352
+ code: 403,
353
+ hint:
354
+ 'CLI 只能操作「站点 owner 是你自己」的站(比 CMS 后台更严,成员站请在 CMS 后台操作):' +
355
+ `\`${cmdName} sites list\` 里挑一个你的站,再 \`${cmdName} site use <站点ID>\` 或本次加 \`--site <站点ID>\`。`,
356
+ });
357
+ }
358
+ // 「令牌缺少权限 site:write:请重新授权(授权 scope 需包含 site:write)」——是 scope 不够,重登即可
359
+ if (/令牌缺少权限/.test(message)) {
360
+ return bad('cms_scope', message, {
361
+ code: 403,
362
+ hint: `令牌的 scope 不够:\`${cmdName} login\` 重新授权一次(默认已含 site:write);旧令牌不会自动获得新能力。`,
363
+ });
364
+ }
365
+ const hint = /未授予|scope|令牌范围/i.test(message)
366
+ ? `令牌的能力不足(scope 收敛)。若确实需要该能力:\`${cmdName} login --scope "site:read site:write billing:self"\` 重新授权`
367
+ : '权限不足:敏感动作(动钱/改权限)需要二次验证,OAuth 令牌做不到,请在网页后台操作';
368
+ return bad('forbidden', message || '无权限', { code: 403, hint });
369
+ }
370
+ if (codeNum === 428) {
371
+ return bad('step_up', message || '需要二次验证', {
372
+ code: 428,
373
+ hint: '该动作要求 5 分钟内重新输入密码(step-up)。CLI 令牌没有密码入口 → 请在网页后台操作',
374
+ });
375
+ }
376
+ if (codeNum === 404) return bad('not_found', message || '资源不存在', { code: 404 });
377
+ /**
378
+ * ★ 2026-11-17(task-627):**409 = 状态冲突**(下单打进来才有,之前落到 `unknown`)。
379
+ *
380
+ * 两种要分开:
381
+ * · `idempotency_mismatch` —— 同一幂等键的参数与已建订单不一致(**这一单其实已经建好了**)。
382
+ * 服务端原文带实现词 `idempotency_key`,**不能照抄给用户**,翻成"别重复下单 + 怎么继续付";
383
+ * · 其余(`ICP_ASSIST_OPEN_ORDER_EXISTS` 还有未完成服务单 / `VIP_ALREADY_ACTIVE` 仍在有效期)
384
+ * 后端文案本身就是人话 ⇒ 原样透出,只补一句下一步。
385
+ */
386
+ if (codeNum === 409) {
387
+ const biz = String(
388
+ (body && (body.error_code || (body.data && body.data.code))) || '',
389
+ );
390
+ if (biz === 'idempotency_mismatch' || /idempotency/i.test(message)) {
391
+ return bad(
392
+ 'conflict',
393
+ '这一单已经创建,请不要重复下单:订单 30 分钟内未支付会自动关闭(优惠券随之释放),' +
394
+ '关闭后再重新下单即可;也可以在网页「我的订单」里继续支付。',
395
+ {
396
+ code: 409,
397
+ hint:
398
+ `先 \`${cmdName} orders list\` 看这一单在不在;待支付就去网页收银台付,` +
399
+ `或 \`${cmdName} orders pay <订单号>\` 查一次状态。**不要**换个参数再下一单(会锁券、留多张待支付单)。`,
400
+ },
401
+ );
402
+ }
403
+ return bad('conflict', message || '该操作与当前状态冲突,请刷新后重试', {
404
+ code: 409,
405
+ hint: '按提示处理后再试;不要靠重复下单绕过(会锁券 / 留下多张待支付单)。',
406
+ });
407
+ }
408
+ if (codeNum === 400) {
409
+ // 内容类自持动作没带站点(`content-core.js` 的「缺少 siteId:CLI 内容动作必须指定站点…」)
410
+ if (/缺少 siteId|指定站点/.test(message)) {
411
+ return bad('cms_site_required', message, {
412
+ code: 400,
413
+ hint: `先 \`${cmdName} site use <站点ID>\`(记住),或本次加 \`--site <站点ID>\`;站点 ID 见 \`${cmdName} sites list\`。`,
414
+ });
415
+ }
416
+ return bad('bad_request', message || '请求不合法', { code: 400 });
417
+ }
418
+ if (codeNum !== null && codeNum >= 500) return bad('server', message || `服务端错误(${codeNum})`, { code: codeNum });
419
+ if (codeNum !== null) return bad('unknown', message || `未知错误(code=${codeNum})`, { code: codeNum });
420
+
421
+ // ---- 4. 既没有 code 也没有 error:按 HTTP 状态兜底(例如网关 5xx 直出)----
422
+ if (httpStatus >= 500) return bad('server', message || `服务端错误(HTTP ${httpStatus})`, { code: httpStatus });
423
+ if (httpStatus === 401) {
424
+ return unauthenticatedClass(message, { httpStatus: 401, cmdName });
425
+ }
426
+ if (httpStatus >= 400) return bad('unknown', message || `请求失败(HTTP ${httpStatus})`, { code: httpStatus });
427
+ if (httpStatus >= 200 && httpStatus < 300) {
428
+ // HTTP 200 但没有 code 字段:可能是纯 REST 形状(比如 PG REST 直出数组)。
429
+ // 这种不算错,交给调用方处理 body 本身。
430
+ return ok({ code: null });
431
+ }
432
+ return bad('unknown', message || `无法识别的响应(HTTP ${httpStatus})`, { code: httpStatus });
433
+ }
434
+
435
+ /** 把 classify 结果变成可抛出的 CliError */
436
+ export function toCliError(classified, { action = '', raw = null } = {}) {
437
+ const where = action ? `(${action})` : '';
438
+ return new CliError(`${classified.message}${where ? ' ' + where : ''}`, {
439
+ kind: classified.kind,
440
+ code: classified.code,
441
+ hint: classified.hint,
442
+ retryAfter: classified.retryAfter,
443
+ exitCode: classified.exitCode,
444
+ raw,
445
+ });
446
+ }