@wkgeo/cli 0.0.0-stage → 1.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.
Files changed (54) hide show
  1. package/CHANGELOG.md +223 -0
  2. package/LICENSE +21 -0
  3. package/README.md +1042 -3
  4. package/SKILL.md +927 -0
  5. package/lib/ai/client.mjs +161 -0
  6. package/lib/ai/config.mjs +221 -0
  7. package/lib/ai/context.mjs +468 -0
  8. package/lib/ai/log.mjs +53 -0
  9. package/lib/api.mjs +339 -0
  10. package/lib/args.mjs +235 -0
  11. package/lib/cli.mjs +168 -0
  12. package/lib/cms.mjs +330 -0
  13. package/lib/commands/ai.mjs +392 -0
  14. package/lib/commands/apps.mjs +116 -0
  15. package/lib/commands/auth.mjs +1288 -0
  16. package/lib/commands/billing.mjs +666 -0
  17. package/lib/commands/cms.mjs +2533 -0
  18. package/lib/commands/config-auth.mjs +621 -0
  19. package/lib/commands/config.mjs +434 -0
  20. package/lib/commands/dnscred.mjs +428 -0
  21. package/lib/commands/domainops.mjs +546 -0
  22. package/lib/commands/domainorder.mjs +439 -0
  23. package/lib/commands/import.mjs +164 -0
  24. package/lib/commands/index.mjs +541 -0
  25. package/lib/commands/logs.mjs +141 -0
  26. package/lib/commands/orders.mjs +444 -0
  27. package/lib/commands/overview.mjs +394 -0
  28. package/lib/commands/plugins.mjs +678 -0
  29. package/lib/commands/site.mjs +435 -0
  30. package/lib/commands/siteops.mjs +1012 -0
  31. package/lib/commands/sites.mjs +905 -0
  32. package/lib/commands/skill.mjs +119 -0
  33. package/lib/commands/template.mjs +258 -0
  34. package/lib/config.mjs +351 -0
  35. package/lib/credentials.mjs +160 -0
  36. package/lib/device-store.mjs +132 -0
  37. package/lib/device.mjs +464 -0
  38. package/lib/errors.mjs +299 -0
  39. package/lib/format.mjs +339 -0
  40. package/lib/http.mjs +71 -0
  41. package/lib/index.mjs +44 -0
  42. package/lib/local-import.mjs +185 -0
  43. package/lib/login.mjs +1638 -0
  44. package/lib/oauth-urls.mjs +163 -0
  45. package/lib/page.mjs +393 -0
  46. package/lib/pkce.mjs +48 -0
  47. package/lib/proxy.mjs +454 -0
  48. package/lib/qr.mjs +31 -0
  49. package/lib/runtime.mjs +650 -0
  50. package/lib/site-state.mjs +137 -0
  51. package/lib/tar.mjs +207 -0
  52. package/lib/template-package.mjs +522 -0
  53. package/package.json +53 -4
  54. package/wkgeo.mjs +17 -0
package/lib/cli.mjs ADDED
@@ -0,0 +1,168 @@
1
+ /**
2
+ * CLI 入口逻辑(与 `process` 解耦,方便单测直接调 `run(argv, {stdout: 假对象})`)。
3
+ *
4
+ * 退出码(写进 README / SKILL.md,AI 端可以据此分支):
5
+ * 0 成功 | 1 失败 | 2 用法错误 | 3 需要(重新)授权 | 4 被限流
6
+ */
7
+
8
+ import fs from 'node:fs';
9
+ import { parseArgv, resolveCommand } from './args.mjs';
10
+ import { createRuntime, createOutput } from './runtime.mjs';
11
+ import { COMMANDS, renderHelp } from './commands/index.mjs';
12
+ import { CliError, EXIT } from './errors.mjs';
13
+ import { DEFAULT_BASE, DEFAULT_CLIENT_ID } from './config.mjs';
14
+
15
+ function readVersion() {
16
+ try {
17
+ const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
18
+ return pkg.version || '0.0.0';
19
+ } catch {
20
+ return '0.0.0';
21
+ }
22
+ }
23
+
24
+ /**
25
+ * 从调用方给的 `io` 里挑出**真的给了**的注入项(`undefined` 一律丢掉)。
26
+ *
27
+ * ★ 0.5.1 修复的正是这里:以前是逐字写 `sleep: io.sleep` —— `wkgeo.mjs` 调 `run(argv)`
28
+ * 时 `io` 是 `{}`,于是"注入"了一个 `undefined`,`createRuntime` 收到
29
+ * `sleep: undefined`(解构默认值只对"没这个键"生效,对"键在值是 undefined"**不**生效),
30
+ * `publish --confirm` 的轮询 `await ctx.sleep(...)` 直接崩:`ctx.sleep is not a function`。
31
+ *
32
+ * 现在两端都兜住:
33
+ * 1. 这里:`undefined` 字段不出现,缺省值交回 `createRuntime`(见 lib/runtime.mjs 的 defaultSleep / fnOr);
34
+ * 2. runtime:即使有人硬塞 `sleep: undefined` 也归一化成默认实现 —— 任何调用方漏传都不会崩。
35
+ *
36
+ * `false` / `0` / `''` 这些**有语义的值**照常保留(如 `openBrowser: false` = `--no-browser`)。
37
+ */
38
+ export function pickInjectables(io = {}) {
39
+ const injectable = {
40
+ /** 交互提问的注入点(生产 = readline;单测注入固定答案,见 lib/runtime.mjs) */
41
+ ask: io.ask,
42
+ fetchImpl: io.fetchImpl,
43
+ now: io.now,
44
+ /** 随机源 / 诊断日志(0.5.1 起与 now/sleep 一样:可注入 + 有默认实现) */
45
+ random: io.random,
46
+ log: io.log,
47
+ openBrowser: io.openBrowser,
48
+ /** `child_process.spawn` 的注入点(只为单测:验证"AI 场景一次都不 spawn 浏览器") */
49
+ spawnImpl: io.spawnImpl,
50
+ /** ★ 0.5.1:轮询等待(发布 / 设备码)。生产不传 → runtime 的 `defaultSleep` */
51
+ sleep: io.sleep,
52
+ /**
53
+ * 「设备码先成功后,本地回调监听再多留多久」的注入点(毫秒;见 lib/login.mjs 的
54
+ * DEFAULT_POST_DEVICE_GRACE_MS)。生产不传 = 默认 3 秒;单测注入小值即可确定性地
55
+ * 验证"迟到的回调拿到已完成页"(不必真的等 3 秒)。
56
+ */
57
+ postDeviceGraceMs: io.postDeviceGraceMs,
58
+ /**
59
+ * 代理检测的注入点(见 lib/proxy.mjs)。生产上不传,走 `process.platform` + 真 `reg/scutil`;
60
+ * 单测传入才能在任意平台上验证 Windows/macOS 的解析分支,且不去起真子进程。
61
+ */
62
+ platform: io.platform,
63
+ exec: io.exec,
64
+ /**
65
+ * `wkgeo import` 起子进程的注入点(同步;生产默认 `spawnSync`)。
66
+ * 单测注入它就能验证"脚本参数怎么拼、退出码怎么转述",不真的去起子进程抓网站。
67
+ */
68
+ runScript: io.runScript,
69
+ /** 同上:`skill` 手册位置的注入点(单测验证"包里没有手册"分支时用,见 lib/commands/skill.mjs) */
70
+ skillUrl: io.skillUrl,
71
+ };
72
+ return Object.fromEntries(Object.entries(injectable).filter(([, v]) => v !== undefined));
73
+ }
74
+
75
+ export async function run(argv = [], io = {}) {
76
+ const stdout = io.stdout || process.stdout;
77
+ const stderr = io.stderr || process.stderr;
78
+ const stdin = io.stdin || process.stdin;
79
+ const env = io.env || process.env;
80
+
81
+ // 先按"最保守"的方式猜输出模式:即使后面解析失败,报错也应该是机器可读的
82
+ const jsonRequested = argv.includes('--json') || argv.includes('-j');
83
+ const textForced = argv.includes('--text');
84
+ let json = jsonRequested || (!textForced && !stdout.isTTY);
85
+
86
+ const fallbackOut = (j) =>
87
+ createOutput({
88
+ stdout,
89
+ stderr,
90
+ json: j,
91
+ color: false,
92
+ // 解析都没成功时也要给出"当前会打哪个环境",否则 AI 端拿到的 meta 是空的
93
+ meta: () => ({
94
+ base: env.WKONGAI_BASE || DEFAULT_BASE,
95
+ client_id: env.WKONGAI_CLIENT_ID || DEFAULT_CLIENT_ID,
96
+ }),
97
+ });
98
+
99
+ let commandName = null;
100
+ let runtime = null;
101
+
102
+ try {
103
+ const parsed = parseArgv(argv);
104
+
105
+ if (parsed.flags.version === true || parsed.positionals[0] === 'version') {
106
+ stdout.write(`@wkgeo/cli ${readVersion()}\n`);
107
+ return EXIT.OK;
108
+ }
109
+
110
+ // 帮助:`--help` / `-h` / `help` / `help <命令>` / `<命令> --help`
111
+ if (parsed.flags.help === true || parsed.positionals[0] === 'help') {
112
+ let want = null;
113
+ if (parsed.positionals[0] === 'help') {
114
+ want = parsed.positionals.slice(1).join(' ') || null;
115
+ } else {
116
+ // `wkgeo wallet txns --help` 要能显示 wallet txns 的帮助(不是总帮助)
117
+ try {
118
+ const hit = resolveCommand(COMMANDS, parsed.positionals);
119
+ want = hit ? hit.spec.name : parsed.positionals.join(' ') || null;
120
+ } catch {
121
+ want = parsed.positionals.join(' ') || null;
122
+ }
123
+ }
124
+ stdout.write(renderHelp(want) + '\n');
125
+ return EXIT.OK;
126
+ }
127
+
128
+ commandName = parsed.positionals.join(' ') || null;
129
+ runtime = createRuntime({
130
+ argv,
131
+ commands: COMMANDS,
132
+ env,
133
+ stdout,
134
+ stderr,
135
+ stdin,
136
+ ...pickInjectables(io),
137
+ });
138
+ json = runtime.out.json;
139
+ commandName = runtime.spec.name;
140
+
141
+ await runtime.spec.run(runtime);
142
+ return EXIT.OK;
143
+ } catch (err) {
144
+ const out = runtime ? runtime.out : fallbackOut(json);
145
+ const e =
146
+ err instanceof CliError
147
+ ? err
148
+ : new CliError((err && err.message) || String(err), {
149
+ kind: 'internal',
150
+ hint: '这是 CLI 内部错误;请带上完整命令与输出反馈',
151
+ cause: err,
152
+ });
153
+
154
+ out.emitErr(commandName, e);
155
+
156
+ if (e.showHelp && !json) {
157
+ stderr.write('\n' + renderHelp() + '\n');
158
+ }
159
+ if (e.kind === 'usage' && !e.hint) {
160
+ // 用法错误给一条"下一步",人/AI 都不用去猜
161
+ stderr.write('提示:运行 `wkgeo --help` 看所有命令,或 `wkgeo <命令> --help` 看单个命令。\n');
162
+ }
163
+ if (runtime && runtime.flags.verbose && err && err.stack) {
164
+ stderr.write(err.stack + '\n');
165
+ }
166
+ return e.exitCode === undefined ? EXIT.ERROR : e.exitCode;
167
+ }
168
+ }
package/lib/cms.mjs ADDED
@@ -0,0 +1,330 @@
1
+ /**
2
+ * CMS 接口客户端 —— 客户站后台那一套动作(栏目 / 内容 / 素材 / 模板)。
3
+ *
4
+ * ## 接口形态(照 `aliyun/fc/wkgeo-cms/src/index.js` 的动作表,别自己编)
5
+ * `POST {CMS_BASE}/<action>`,JSON body,响应统一信封 `{code, message, data}`,
6
+ * `code === 0` 才算成功 —— 与 `/api/data` 完全同一套约定。
7
+ * `CMS_BASE` 默认 `https://api.wkgeo.com/cms`(`--cms-base` / `WKONGAI_CMS_BASE` 可覆盖),
8
+ * 动作名就是动作表的键(`categoryList` / `contentSave` / `templateGet` …),**URL 最后一段就是动作名**:
9
+ * 云函数支持"从路径取动作"(`actionFromPath`),所以 `/api/cms/categoryList` 与
10
+ * `body.action = 'categoryList'` 等价;这里用路径写法,身体里只放业务参数(干净、可读)。
11
+ *
12
+ * ## 认证(**当前最大的外部依赖**)
13
+ * CLI 手里只有 OAuth 的 Bearer 令牌,而 CMS 原本只认 `cms_session` Cookie。
14
+ * 两条通道由**另一个任务**在 `aliyun/fc/wkgeo-cms/src` 里加:"Bearer 令牌 → 用户 → 站点成员"。
15
+ * ⇒ 所以这里有两条硬规矩:
16
+ * 1. 请求一律带 `Authorization: Bearer <token>`(桥上线后立刻可用,CLI 侧一行不用改);
17
+ * 2. **桥还没上线时(服务端回 401)必须给一句人能照做的话**,不能把
18
+ * "登录已过期,请重新登录" 原样甩出去 —— 那句话会让用户以为是自己令牌的问题,
19
+ * 而真实原因多半是"服务端还没启用 CLI 认证"(见 `cmsAuthCliError`)。
20
+ *
21
+ * ## 站点边界
22
+ * 站 id 一律走 **`x-cms-site` 头**(`resolveSite` 的第一优先级)。
23
+ * ⚠️ 头的值必须是**站点 id(uuid)**:后端先按 `id::text` 精确查,再按 Host 兜底;
24
+ * CLI 没有 Host,所以传域名等于没传(这是踩不出响声的坑,`runtime.cmsSite()` 里提前挡掉)。
25
+ *
26
+ * ## 为什么错误翻译放在这一层
27
+ * 命令层有十几个,逐个写"401 怎么说"迟早写歪。所有 CMS 响应只在 `unwrap()` 一处判定,
28
+ * 命令层拿到的要么是 `data`,要么是一个**带中文 hint 的 CliError**。
29
+ */
30
+
31
+ import { request } from './http.mjs';
32
+ import { CliError, EXIT, classifyResponse, networkError, toCliError } from './errors.mjs';
33
+
34
+ /**
35
+ * 动作名(与 `aliyun/fc/wkgeo-cms/src/index.js` 的 `actionTable` 一一对应)。
36
+ *
37
+ * 只列 CLI 用到的那些 —— 全表在云函数里,这里不是"权威清单",
38
+ * 但用它代替散落在命令层的中英混排字符串,避免 `categorylist` 这类大小写手滑(后端会回"未知动作")。
39
+ */
40
+ export const CMS_ACTIONS = {
41
+ // 概览(发布状态用)
42
+ overview: 'overview',
43
+ // 站点会话身份(2026-10-21 命名治理:`me` → `cmsMe`;旧名已下线,调用回 400)
44
+ me: 'cmsMe',
45
+ // 栏目
46
+ categoryList: 'categoryList',
47
+ categoryGet: 'categoryGet',
48
+ categorySave: 'categorySave',
49
+ categoryDelete: 'categoryDelete',
50
+ // 内容
51
+ contentList: 'contentList',
52
+ contentGet: 'contentGet',
53
+ contentSave: 'contentSave',
54
+ contentDelete: 'contentDelete',
55
+ // 素材(图片直传:签名 → 直传 OSS → 登记)
56
+ assetSign: 'assetSign',
57
+ assetRegister: 'assetRegister',
58
+ assetList: 'assetList',
59
+ // 模板
60
+ templateList: 'templateList',
61
+ templateGet: 'templateGet',
62
+ templateFileSave: 'templateFileSave',
63
+ // 前台渲染(免登录,发布说明里要引用它)
64
+ pageRender: 'pageRender',
65
+ // 发布(0.5.0:静态发布链路——start 建任务、status 轮询、cancel 取消)
66
+ publishStart: 'cmsSitePublishStart',
67
+ publishStatus: 'cmsSitePublishStatus',
68
+ publishCancel: 'cmsSitePublishCancel',
69
+ // 插件(插件中心)
70
+ pluginList: 'pluginList',
71
+ pluginToggle: 'pluginToggle',
72
+ // 域名巡检(只读;要「系统管理」权限,普通账号 403)
73
+ domainInspectionList: 'cmsSiteDomainInspectionList',
74
+ // 老网站导入 v2
75
+ importV2Start: 'importV2Start',
76
+ importV2Get: 'importV2Get',
77
+ };
78
+
79
+ /**
80
+ * 「服务端没接受 CLI 的令牌」时给的话。
81
+ *
82
+ * ## 为什么不能只写"请重新登录"
83
+ * 把令牌问题和服务端没上线混成一句,会让用户白跑一遍浏览器授权:
84
+ * `whoami` 明明正常、`categories list` 却永远 401 —— 那是**桥没上线**,重登一万次也没用。
85
+ *
86
+ * ## 为什么同时给两种可能
87
+ * 本地能判定的只有"凭据没过期"(`requireAuth` 已经挡掉了本地过期的),
88
+ * 但服务端吊销 / 令牌被清掉是本地看不出来的。所以按可能性排序给两条路,
89
+ * 并明确说"CLI 侧不需要改"——省得用户去装新版、改 base。
90
+ */
91
+ function cmsAuthCliError(action, raw) {
92
+ const text = String((raw && raw.message) || '服务端没有给出原因');
93
+ return new CliError(`CMS 接口没有接受 CLI 的授权令牌(${action}):${text}`, {
94
+ kind: 'cms_auth',
95
+ code: (raw && raw.code !== undefined && raw.code !== null) ? raw.code : 401,
96
+ exitCode: EXIT.AUTH,
97
+ hint:
98
+ '① 最常见的原因是令牌已过期 / 被吊销:运行 `wkgeo login` 重新授权即可;' +
99
+ '② 若刚授权仍报 401(且 `wkgeo whoami` 正常),说明服务端是**旧部署** —— ' +
100
+ '还没启用 CLI 认证桥(OAuth Bearer 令牌 → CMS 站点成员),联系管理员升级云函数 `cms` 即可,CLI 侧不需要改。',
101
+ raw: { action, body: raw },
102
+ });
103
+ }
104
+
105
+ /**
106
+ * 「接口本身摸不到」时给的话(地址错 / 云函数没部署 / 网关返回 HTML)。
107
+ *
108
+ * 这一类**不是**令牌问题,绝不能引导去重新授权 —— 否则用户会陷入"重登 → 还是失败"的死循环。
109
+ */
110
+ function cmsUnavailableError(action, res) {
111
+ const status = res && res.status ? res.status : 0;
112
+ const snippet = String((res && res.text) || '').replace(/\s+/g, ' ').slice(0, 200);
113
+ return new CliError(`CMS 接口不可用(${action},HTTP ${status || '无响应'})${snippet ? `:${snippet}` : ''}`, {
114
+ kind: 'cms_unavailable',
115
+ code: status || null,
116
+ hint:
117
+ '检查 `wkgeo config` 里的 CMS 基址(默认 `https://api.wkgeo.com/cms`,' +
118
+ '可用 `--cms-base` / `WKONGAI_CMS_BASE` 临时切换);若地址没错,多半是云函数 `cms` 还没部署。',
119
+ });
120
+ }
121
+
122
+ /**
123
+ * **403 的三种含义要分开说**(Bearer 桥上线后这三种都会真实出现,混成一句就没法照做)。
124
+ *
125
+ * 1. 「你不是该站点的成员」/「你不是任何 CMS 站点的成员」→ 站点选错了 / 还没被邀请;
126
+ * 2. 「只读账号不能修改…」→ 站点角色是 viewer(有权限但只读);
127
+ * 3. 「该令牌没有执行「X」的权限(需要 site:write …)」→ **scope** 不够,得重新授权。
128
+ *
129
+ * 另外 400 有一种固定文案:「这个账号有 N 个站点,请用 x-cms-site 头或 body._site 指定」——
130
+ * 那是"没选站 + 多成员站",引导用户去 `wkgeo site use`。
131
+ */
132
+ function cmsPolicyError(action, body) {
133
+ const message = String((body && body.message) || '无权限');
134
+ const code = body && body.code !== undefined ? body.code : 403;
135
+
136
+ if (/不是该站点的成员|不是任何 CMS 站点的成员/.test(message)) {
137
+ return new CliError(`CMS 拒绝访问(${action}):${message}`, {
138
+ kind: 'cms_not_member',
139
+ code,
140
+ hint:
141
+ '站点 ID 不对或你不是它的成员:用 `wkgeo site use <正确的站点ID>` 重新选(`--site` 只影响一次);' +
142
+ '如果是别人邀请你协作的站,需要该站 owner 先在后台把你加进成员。',
143
+ });
144
+ }
145
+ if (/只读账号/.test(message)) {
146
+ return new CliError(`CMS 拒绝写入(${action}):${message}`, {
147
+ kind: 'cms_readonly',
148
+ code,
149
+ hint: '你这个站点角色是 viewer(只读):让该站 owner 在后台「用户与角色」里把你提升为 editor。',
150
+ });
151
+ }
152
+ if (/没有执行|需要\s*site:write|需要\s*template:write|需要\s*attachment/.test(message)) {
153
+ return new CliError(`CMS 拒绝执行(${action}):${message}`, {
154
+ kind: 'cms_scope',
155
+ code,
156
+ hint:
157
+ '令牌的能力(scope)不够:直接 `wkgeo login` 重新授权一次即可' +
158
+ '(CLI 现在的默认 scope 已含 site / template / attachment 三组);' +
159
+ '要精确控制就写 `wkgeo login --scope "<原有 scope> <缺的那个>"`。' +
160
+ '⚠️ 升级前授权的**旧令牌**不会自动获得新能力,必须重新 login。',
161
+ });
162
+ }
163
+ if (/请用\s*x-cms-site|指定站点/.test(message)) {
164
+ return new CliError(`还没有确定站点(${action}):${message}`, {
165
+ kind: 'cms_site_required',
166
+ code,
167
+ hint: '你的账号有多个站点,必须指明一个:`wkgeo site use <站点ID>`(记住),或本命令加 `--site <站点ID>`。',
168
+ });
169
+ }
170
+ return null;
171
+ }
172
+
173
+ /**
174
+ * 建一个 CMS 客户端。
175
+ *
176
+ * @param {object} args
177
+ * @param {object} args.config `resolveConfig()` 的结果(只用 `cmsBase` / `httpTimeoutMs`)
178
+ * @param {Function} [args.fetchImpl]
179
+ */
180
+ export function createCms({ config, fetchImpl = globalThis.fetch } = {}) {
181
+ const base = String((config && config.cmsBase) || '').replace(/\/+$/, '');
182
+ const timeoutMs = (config && config.httpTimeoutMs) || 30000;
183
+
184
+ async function raw(url, options = {}) {
185
+ return request(url, { ...options, fetchImpl, timeoutMs: options.timeoutMs ?? timeoutMs });
186
+ }
187
+
188
+ /**
189
+ * 判定成败 + 翻译错误(**全模块唯一一处**)。
190
+ * @returns `{code,message,data}` 里的 `data`(没有就是 null)
191
+ */
192
+ function unwrap(res, action) {
193
+ if (res.networkError) throw networkError(res.networkError, { raw: res });
194
+
195
+ /**
196
+ * 没有 JSON 响应体 = 打到的不是 CMS 云函数:
197
+ * * 网关 404 / 502 的 HTML 错误页;
198
+ * * 或者云函数没部署、路径没配。
199
+ * 这两种都不该按"业务错误"处理(也就不会有 code 可看)。
200
+ */
201
+ if (!res.body) {
202
+ if (res.status >= 200 && res.status < 300) {
203
+ // 200 但空体:极少见(网关吞了响应),当成功但无数据,别硬报错
204
+ return null;
205
+ }
206
+ throw cmsUnavailableError(action, res);
207
+ }
208
+
209
+ const cls = classifyResponse({
210
+ httpStatus: res.status,
211
+ body: res.body,
212
+ action,
213
+ retryAfterHeader:
214
+ res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null,
215
+ cmdName: (config && config.cmdName) || 'wkgeo',
216
+ });
217
+
218
+ if (cls.ok) {
219
+ const body = res.body;
220
+ return body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body;
221
+ }
222
+
223
+ /**
224
+ * 401 家族:可能是令牌真过期,也可能是桥没上线/没部署 —— 单独一段话(见 cmsAuthCliError)
225
+ */
226
+ if (cls.kind === 'expired' || cls.kind === 'revoked' || cls.kind === 'unauthenticated') {
227
+ throw cmsAuthCliError(action, res.body);
228
+ }
229
+
230
+ /**
231
+ * 403 / 400 里有几类**含义完全不同**的业务拒绝(不是成员 / 只读角色 / scope 不够 / 没定站),
232
+ * 通用 hint("scope 不足"或"去网页后台做")会把它们全说错 —— 先按文案细分。
233
+ */
234
+ if (cls.kind === 'forbidden' || cls.kind === 'bad_request' || cls.code === 403 || cls.code === 400) {
235
+ const policy = cmsPolicyError(action, res.body);
236
+ if (policy) throw policy;
237
+ }
238
+
239
+ /**
240
+ * 「未知动作」= CLI 与服务端版本不一致(新动作还没部署)。
241
+ * 这条错误原本是 `未知动作:templateFileSave`,对用户等于没说,所以补一句"是服务端缺口"。
242
+ */
243
+ if (String(cls.message || '').includes('未知动作')) {
244
+ throw new CliError(`服务端还没有这个动作:${action}`, {
245
+ kind: 'not_deployed',
246
+ code: cls.code,
247
+ hint: '这是**服务端缺口**(云函数 `cms` 版本落后),不是命令写错;等后端部署后重试,CLI 不需要升级。',
248
+ });
249
+ }
250
+
251
+ throw toCliError(cls, { action, raw: { status: res.status, body: res.body } });
252
+ }
253
+
254
+ return {
255
+ base,
256
+
257
+ /**
258
+ * 调一个 CMS 动作。
259
+ *
260
+ * @param {string} action 动作名(用 `CMS_ACTIONS` 里的常量,别手写)
261
+ * @param {object} [body] 业务参数(**不要**往这里塞 `site_id`:后端一律忽略,站点走 `x-cms-site`)
262
+ * @param {{token?:string, siteId?:string}} [opts]
263
+ * @returns {Promise<any>} 信封里的 `data`
264
+ */
265
+ async call(action, body = {}, { token, siteId } = {}) {
266
+ if (!action) throw new CliError('内部错误:缺少 CMS 动作名');
267
+ if (!base) throw new CliError('内部错误:CMS 基址为空(检查 WKONGAI_CMS_BASE)');
268
+ const headers = {
269
+ 'Content-Type': 'application/json',
270
+ Accept: 'application/json',
271
+ };
272
+ if (token) headers.Authorization = `Bearer ${token}`;
273
+ if (siteId) headers['x-cms-site'] = String(siteId);
274
+ const res = await raw(`${base}/${action}`, {
275
+ method: 'POST',
276
+ headers,
277
+ body: JSON.stringify(body || {}),
278
+ });
279
+ return unwrap(res, action);
280
+ },
281
+ };
282
+ }
283
+
284
+ /**
285
+ * 把文件真正传上 OSS(**直传**:CLI 不碰 AK,也不会把二进制塞进云函数请求体)。
286
+ *
287
+ * 流程(与 `aliyun/fc/wkgeo-cms/src` 的 `signDirectUpload` 对应):
288
+ * ① `assetSign` 拿票据(key / uploadUrl / fields 都锁死,10 分钟过期);
289
+ * ② 用 `multipart/form-data` POST 到 OSS(`fields` 在前,`file` **必须是最后一个字段**,
290
+ * OSS 的 PostObject 要求如此);
291
+ * ③ 回 `assetRegister` 落库(它会回读一次 OSS,确认文件真的在)。
292
+ *
293
+ * ⚠️ `fields` 里有 `Content-Type`,而 multipart 的每个字段都要有自己的一段 — 直接
294
+ * `form.append('Content-Type', ...)` 是对的(OSS 把它当表单字段读),**不要**改成请求头,
295
+ * 改了就破坏 boundary。
296
+ *
297
+ * @param {object} args
298
+ * @param {{uploadUrl:string, fields:Record<string,string>, mime:string}} args.ticket
299
+ * @param {Buffer} args.buffer 文件字节
300
+ * @param {string} args.fileName 文件名(客户端名,用来给 OSS 那一段命名)
301
+ * @returns {Promise<{status:number, text:string}>}
302
+ */
303
+ export async function uploadToOss({ ticket, buffer, fileName, fetchImpl = globalThis.fetch, timeoutMs = 120000 }) {
304
+ const form = new FormData();
305
+ for (const [k, v] of Object.entries((ticket && ticket.fields) || {})) {
306
+ if (v === undefined || v === null) continue;
307
+ form.append(String(k), String(v));
308
+ }
309
+ /** `file` 必须最后追加(OSS PostObject 的约定) */
310
+ form.append('file', new Blob([buffer], { type: (ticket && ticket.mime) || 'application/octet-stream' }), String(fileName || 'file'));
311
+
312
+ const res = await request(String(ticket.uploadUrl), {
313
+ method: 'POST',
314
+ body: form,
315
+ /** ⚠️ 这里**绝不能**设 Content-Type:boundary 由 fetch 自己生成 */
316
+ headers: {},
317
+ fetchImpl,
318
+ timeoutMs,
319
+ });
320
+ if (res.networkError) throw networkError(`上传到素材库失败:${res.networkError}`, { raw: res });
321
+ if (res.status < 200 || res.status >= 300) {
322
+ const snippet = String(res.text || '').replace(/\s+/g, ' ').slice(0, 300);
323
+ throw new CliError(`上传到素材库失败(OSS HTTP ${res.status})${snippet ? `:${snippet}` : ''}`, {
324
+ kind: 'upload_failed',
325
+ code: res.status,
326
+ hint: '票据 10 分钟过期,重新运行本命令即可;若一直是 403,检查素材桶的跨域/签名配置(服务端 OSS_ACCESS_KEY_*)',
327
+ });
328
+ }
329
+ return { status: res.status, text: String(res.text || '').slice(0, 200) };
330
+ }