@wkgeo/cli 0.0.0-stage → 1.0.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 (51) hide show
  1. package/CHANGELOG.md +208 -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 +528 -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/config.mjs +351 -0
  34. package/lib/credentials.mjs +160 -0
  35. package/lib/device-store.mjs +132 -0
  36. package/lib/device.mjs +464 -0
  37. package/lib/errors.mjs +299 -0
  38. package/lib/format.mjs +339 -0
  39. package/lib/http.mjs +71 -0
  40. package/lib/index.mjs +44 -0
  41. package/lib/local-import.mjs +185 -0
  42. package/lib/login.mjs +1638 -0
  43. package/lib/oauth-urls.mjs +163 -0
  44. package/lib/page.mjs +393 -0
  45. package/lib/pkce.mjs +48 -0
  46. package/lib/proxy.mjs +454 -0
  47. package/lib/qr.mjs +31 -0
  48. package/lib/runtime.mjs +650 -0
  49. package/lib/site-state.mjs +137 -0
  50. package/package.json +53 -4
  51. package/wkgeo.mjs +17 -0
package/SKILL.md ADDED
@@ -0,0 +1,927 @@
1
+ ---
2
+ name: wkgeo-cli
3
+ description: "Use this skill when the user wants to 建站 / 创建网站 / 下单 / 购买加量包 / 钱包支付 / 充值 / 查余额 / 查钱包流水 / 查订单 / 查我已授权的应用 on the 云站(悟空AI,wkgeo.com)platform from the command line or as an AI agent. Covers installing the official CLI (npx -y @wkgeo/cli@latest or npm i -g @wkgeo/cli), one-time OAuth login (browser callback or device code), local credential storage, machine-readable JSON output and its error codes (40101 expired / 40102 revoked / 429 rate limited / 403 scope). Do NOT use for other platforms, for admin/ops actions requiring step-up (refund, price change, permission change), or for real WeChat payments (the CLI never charges money)."
4
+ description_zh: 云站平台官方命令行客户端:授权登录一次,之后建站 / 下单 / 钱包余额支付 / 充值 / 查余额 / 查订单都不再需要登录。
5
+ description_en: Official CLI for the wkgeo Cloud Site platform — one-time OAuth login, then create sites, place orders, pay from wallet balance, and check balance/orders without logging in again.
6
+ version: 1.0.0
7
+ ---
8
+
9
+ # 云站 CLI(`@wkgeo/cli`)· 给 AI 端的操作手册
10
+
11
+ > 这份文档是给**AI/自动化**用的:目标是用最少的往返,把用户的"建站/下单/支付/查余额"意图
12
+ > 变成一串**确定性的命令调用**,并在需要用户动手(浏览器点同意)时**正确地停下来**。
13
+ >
14
+ > 用户版文档在 `README.md`;本文件与 npm 包一起分发(`npx` 装完就能读到)。
15
+
16
+ ---
17
+
18
+ ## 1. 何时使用
19
+
20
+ **用**:
21
+
22
+ * 用户说"**帮我建个站**"/"创建网站"/"开一个站点" → `sites create`
23
+ * 用户说"**我有哪些站**"/"我的站点"/"管理站点" → `sites list`(默认只看**我名下**的;没有站会给 `hint:"no_sites"`,有站会让交互终端里选一个)
24
+ * 用户说"**帮我下单**"/"买加量包"/"扩容空间"/"买流量" → `products list` → `orders create`
25
+ * 用户说"**用钱包付**"/"余额支付"/"帮我付钱" → `orders create`(余额够会**当场付清**)+ `wallet` 复核
26
+ * 用户说"**充值**"/"充 100 块" → `wallet recharge`(下单后在**人类终端**里会自动打开我们网站的收银台页面,用户在那里扫码支付;CI/非交互只输出 `pay_url`)
27
+ * 用户说"**充值**"但**没说金额**、或说"**我自己选金额**"/"给我个充值链接" → `wallet recharge-link`
28
+ (生成**独立充值页**链接:`https://pay.wkgeo.com/recharge/?ticket=…`,用户在网页上自己选金额
29
+ —— ¥10 / ¥20 快捷,或自定义,**最低 ¥9.90、不设上限** —— 然后扫码支付;**不需要登录会员中心**。
30
+ 默认**不**弹浏览器:把 `data.pay_url` 原样交给用户即可。⛔ 不要用它代替用户付款。)
31
+ * 用户说"**查余额**"/"我的钱包"/"账单流水" → `wallet` / `wallet txns`
32
+ * 用户说"**我的订单**"/"订单状态" → `orders list` / `orders get` / `orders check`
33
+ * 用户说"**我授权过哪些应用**"/"取消某个应用的授权" → `apps list` / `apps revoke`
34
+ * 需要确认"现在是谁在操作" → `whoami`
35
+ * 用户问"**这个令牌能干什么 / 还剩多久 / 怎么立刻作废**" → `auth status`(账号 + scopes + 动作面)/ `auth token`(只给前 4 位 + 长度 + 到期)/ `auth revoke`(服务端吊销 + 删本地)
36
+ * 用户说"**帮我绑自己的域名**" → `domain bind <域名> --site <站点ID>`(成功只是受理,进度看 `domain status`;**通道没开会明确回 503「本次未写入,可直接重试」**,别当成功)
37
+ * **你自己需要这份手册**(换机器、上下文被截断、想确认某个参数)→ `skill`(把本文件原文打出来,见 §2)
38
+
39
+ **不要用**:
40
+
41
+ * ❌ **退款 / 关单 / 改价 / 改权限 / 调整余额**:这些是"敏感动作",需要 5 分钟内重新输密码
42
+ (step-up)。OAuth 令牌**永远过不了**(会返回 403/428)→ 让用户去网页后台做。
43
+ * ❌ **代替用户完成微信支付**:CLI 不会发起任何真实扣款,也不会模拟"支付成功"。
44
+ 它只能创建待支付订单并把支付链接交给用户。
45
+ * ❌ 其他平台的网站/订单(本 CLI 只服务 `wkgeo.com` 这一套站点与账号体系)。
46
+
47
+ ---
48
+
49
+ ## 2. 安装与调用
50
+
51
+ ```bash
52
+ # 首选(AI 端):不安装、免确认,永远拿最新版
53
+ npx -y @wkgeo/cli@latest <命令>
54
+
55
+ # 或者全局安装后用短命令
56
+ npm i -g @wkgeo/cli && wkgeo <命令>
57
+ ```
58
+
59
+ * 要求:Node ≥ 20(不需要 npm install 依赖,包内**零第三方依赖**)。
60
+ * 同机重复调用时 `npx` 会复用缓存,不再下载。
61
+ * **若某个命令的参数不确定,先跑 `npx -y @wkgeo/cli@latest <命令> --help`**(帮助与实际解析同源)。
62
+
63
+ ### ⭐ 自取手册:`wkgeo skill`
64
+
65
+ ```bash
66
+ npx -y @wkgeo/cli@latest skill # 默认:把本文件(SKILL.md)**原文**打到 stdout
67
+ npx -y @wkgeo/cli@latest skill --json # 需要结构化:data.markdown / data.path / data.bytes / data.lines
68
+ npx -y @wkgeo/cli@latest skill > SKILL.md # 直接落一份到本地,离线也能读
69
+ ```
70
+
71
+ * 它读的是**包里那一份**(路径相对 CLI 模块解析,**与 cwd 无关**),所以拿到的永远和正在运行的这个版本一致 ——
72
+ 不用再去 `node_modules` 里猜 npx 的缓存目录。
73
+ * ⚠️ `skill` **不受"非终端自动 JSON"的通用约定约束**:默认**永远**是纯文本原文(管道里也是),
74
+ 只有显式 `--json` 才包成 `{"ok":true,"command":"skill","data":{…}}`。这样 `> SKILL.md` 得到的是一份能直接读的文档,
75
+ 而不是一坨被转义的 JSON。
76
+ * ⚠️ 若报「**当前安装包里没有手册文件(SKILL.md)**」(`error.kind = "missing_skill"`,退出码 `1`):
77
+ 说明跑的是**被裁剪的包**或只拷了 `lib/` 的开发目录(正常 npm 安装包里一定有这份文件)。
78
+ 换官方包 `npx -y @wkgeo/cli@latest skill` 即可;这不是命令用错了。
79
+
80
+ ---
81
+
82
+ ## 3. 输出契约(**关键**)
83
+
84
+ 1. **非终端环境(管道 / AI 子进程)默认输出 JSON**;人类交互时自动是人类可读表格。
85
+ 要强制人类可读加 `--text`,要强制 JSON 加 `--json`。
86
+ 2. 除 `login` 与 `skill` 外,**stdout 只有一个 JSON 对象**:
87
+
88
+ ```jsonc
89
+ // 成功
90
+ { "ok": true, "command": "wallet", "data": { … }, "meta": { "base": "…", "client_id": "wkgeo-cli",
91
+ "credentials_file": "…", "duration_ms": 412 } }
92
+ // 失败(HTTP 仍是 200,错误在业务 code 里 —— 所以**不能**用 HTTP 状态判断成败)
93
+ { "ok": false, "command": "wallet", "error": { "kind": "expired", "code": 40101,
94
+ "message": "访问令牌已过期,请重新授权",
95
+ "hint": "运行 `wkgeo login` 重新授权(浏览器里通常还有登录态,点一下同意即可)",
96
+ "retry_after": null }, "meta": { … } }
97
+ ```
98
+
99
+ 3. `login` 例外:它是长跑命令,JSON 模式下输出 **JSONL 事件流**(见 §5)。
100
+ 另一个例外是 `skill`:它默认**永远**打**纯文本手册原文**(连管道里也不套信封)——
101
+ 它本身就是给人/AI 读的 markdown,套 JSON 只会更难用;要结构化就显式 `--json`
102
+ (`{"ok":true,"command":"skill","data":{"path":…,"markdown":…,"bytes":…,"lines":…}}`)。
103
+ 4. **退出码**:`0` 成功 | `1` 失败 | `2` 用法错误 | `3` 需要(重新)授权 | `4` 被限流。
104
+ 脚本里优先用退出码分支,用 `error.kind` 细分。
105
+ 5. **任何输出里都不会有令牌**(`--verbose` 也只给掩码)—— 不要试图从输出里找 token。
106
+
107
+ ---
108
+
109
+ ## 4. 命令表
110
+
111
+ | 命令 | 作用 | 关键参数 |
112
+ | --- | --- | --- |
113
+ | `login` | 授权一次(令牌存本地 30 天;**默认浏览器回调**,设备码仅兜底) | `--device`、`--no-wait`、`--device-continue`、`--no-auto-device`、`--callback-first-wait <秒>`(可选,默认关闭)、`--no-browser`、`--open-browser`、`--scope`、`--timeout <秒>` |
114
+ | `whoami` | 当前是谁(账号标识) | `--verbose` |
115
+ | `logout` | 退出(删本地凭据 + 服务端吊销) | `--local-only` |
116
+ | `auth status` | **令牌体检**:`cliWhoami` → 账号 ID / `client_id` / `scopes` / 到期 + **动作面**(`action_total`、原生/自持/转发条数、9 个动作清单原样) | `--verbose`(令牌掩码 + 文件权限) |
117
+ | `auth token` | 本地令牌**前 4 位 + 长度 + 到期时间**(完整令牌永不打印) | — |
118
+ | `auth revoke` | 立刻作废:`POST /api/oauth/revoke` + 删本地凭据(服务端失败会如实说) | `--local-only`(只删本地) |
119
+ | `config` | 生效配置 / 登录状态 | — |
120
+ | `sites list` | **站点管理入口**:默认只看**我名下的站**;没站引导建站,有站让你选一个来管理(写本地 config,等同 `site use`) | `--mine`(默认)、`--managed`、`--all`、`--limit`、`--offset`、`--with-prefix`(逐站补短域/开通状态) |
121
+ | `sites get` | 单站详情(只读):短域 / 存储位 / 开通状态 / 地区 / ESA / 证书 / 计费池 / 归属 | `<站点ID>` |
122
+ | `sites create` | 建站(**建在令牌所属用户名下**);`--channel auto`(默认)先 CMS 后回退平台,`--json` 的 `data.channel` 标明实际通道 | `--name`(必填)、`--channel auto\|platform\|cms`、`--template`、`--domain`(**只登记域名,不触发解析/证书**;不能与 `--channel cms` 同用) |
123
+ | `sites delete` | 删站(软删进回收站) | `<站点ID>` |
124
+ | `wallet` | 余额 + 最近流水 | `--limit` `--entitlements` |
125
+ | `wallet txns` | 钱包流水 | `--limit` |
126
+ | `wallet recharge` | 充值下单,**人类终端会自动打开我们网站的收银台页面**扫码支付(CI/非交互只输出链接;**不扣款**) | `--amount-cents`(分,必填)、`--no-browser`、`--open-browser`、`--dry-run` |
127
+ | `wallet recharge-link` | 生成**独立充值页**链接(用户在网页上**自己选金额**并扫码支付;**不扣款**、不建单) | `--open-browser`(默认**不**弹)、`--no-browser` |
128
+ | `products list` | 能买什么 | — |
129
+ | `orders create` | 下单(余额够**当场付清**) | `--product <代码>` `--units <份数>`(或 `--quota <键>` `--amount <数量>`)`--allow-wechat` |
130
+ | `orders check` | 查支付结果 + 最新余额 | `<订单ID>` |
131
+ | `orders pay` | 同 `orders check`(别名) | `<订单ID>` |
132
+ | `orders get` | 订单详情(不触发微信查询) | `<订单ID>` |
133
+ | `orders list` | 我的订单 | `--limit` `--offset` `--status` |
134
+ | `apps list` | 我授权过的应用 | — |
135
+ | `apps revoke` | 一键吊销某应用授权(令牌立即失效) | `<client_id>` |
136
+ | `site use` | **选中要操作的站点**(存本地,之后的 CMS 命令默认用它;不带参数 = 看当前) | `<站点ID或域名>`、`--clear` |
137
+ | `site create` | 建站 + 自持收口(池位 / 短域 / host KV 回读确认;**默认 dry-run**,`--confirm` 才真建) | `--name`、`--pool`、`--confirm` |
138
+ | `esa site` / `esa record` / `esa hostname` / `esa kv` | 确认池位对应 ESA 站点就绪(只读,**不开新站——开站花钱**)/ 建改 S3 回源记录(同值幂等,记录名必须单标签子域)/ 接 CustomHostname + 申请免费证书(幂等;**100 次/小时限流,别重试**)/ 把域名写进边缘路由 KV(`host:<域名>` → 站点目录,写后 GetKv 回读) | `--site`、`--hostname`、`--record`、`--value` |
139
+ | `categories list/get/create/update/delete` | 栏目:列表 / 详情 / 新建 / 改 / 删 | 见 §7.5 |
140
+ | `categories bind-template` | 给栏目绑定模板 html(`--clear` 解绑) | `<栏目>` `<模板文件>`、`--clear` |
141
+ | `contents list/get/create/update/delete` | 内容:列表 / 详情 / 新建 / 改 / 删 | 见 §7.5 |
142
+ | `assets list` / `assets upload` | 素材:列表 / 上传(签名 → 直传 OSS → 登记) | `assets upload <文件>`、`--name` |
143
+ | `assets sign` / `assets register` | 只取直传票据(**不上传、不登记**,agent/脚本自己 POST 文件用)/ 把已直传的 key 登记成素材(服务端会回读一次,确认文件真的在) | `sign <文件名> --bytes <字节数>`、`register <key>`、`--name` |
144
+ | `assets delete` / `assets restore` | 删素材(**默认进回收站**;`--purge --confirm` 才是彻底删除)/ 从回收站恢复(文件已被彻底删掉的会明确拒绝) | `<素材ID>`、`--purge`、`--confirm`、`--site` |
145
+ | `templates list/get/save` | 模板:清单 / 看源码(直出)/ 保存 | `templates get <文件>`、`templates save <文件> --file <本地>` |
146
+ | `publish` | **发布站点**(0.5.0 接真后端):默认 **dry-run** 只算页数;`--confirm` 才真发并轮询到结束 | `--site`、`--confirm`、`--cancel`、`--no-wait`、`--job`、`--interval`、`--wait-timeout` |
147
+ | `publish status` / `publish cancel` | 只查状态 / 取消正在跑的发布 | `--site`、`--job` |
148
+ | `publish retry` | 重发一次(旧任务不动,新建一个发布任务) | `--site`、`--job` |
149
+ | `publish jobs` / `publish jobs get` / `publish jobs cancel` | 推送任务:列表 / 看详情(默认会推进它一次)/ 取消 | `--site`、`--job`、`--limit` |
150
+ | `publish targets` / `publish targets save` | 推送目标(FTP/SFTP/S3/WebDAV)清单 / 存目标(**凭据加密落库;密码只从 stdin 读**) | `--name`、`--type`、`--host`、`--port`、`--user`、`--path`、`--site` |
151
+ | `publish targets delete` / `publish targets test` | 删推送目标(**危险:必须 `--yes`**)/ 测试能不能连上(真连,不推文件) | `<目标ID>`、`--yes`、`--site` |
152
+ | `publish push` | 把站点成品推到客户自有目标(FTP/SFTP/S3/WebDAV;异步任务) | `--target`、`--site` |
153
+ | `publish storage` / `publish storage save` / `publish storage verify` | 客户自有对象存储(OSS/COS/BOS/S3)当前配置(只读,密钥打码)/ 存(**SK 只从 stdin 读**,加密落库)/ 验证桶能不能写(真连、真写一个探测对象) | `--provider`、`--bucket`、`--region`、`--endpoint` |
154
+ | `publish storage delete` / `publish storage publish` | 解绑客户自有存储(**危险:必须 `--yes`**,站点回到平台默认桶)/ 把现有成品整批镜像到客户桶(同步一次) | `--yes`、`--confirm`、`--site` |
155
+ | `lang list` / `lang save` / `lang set-default` / `lang delete` / `lang toggle` | 站点语言:列表 / 保存(给了 `<语言ID>` 就改、没给就新建)/ 设默认 / 删(默认语言不给删)/ 启停(默认语言不能停用);**写默认 dry-run** | `[语言ID]`、`--code`、`--name`、`--default`、`--disabled`、`--off`、`--confirm`、`--site` |
156
+ | `role list` / `role save` / `role delete` | 站点角色:列表(含权限明细)/ 保存(**改角色必须带 `--permissions`**,否则会清空)/ 删(预置角色 403、有成员在用 409)。**写要 `role:write`**,不许造带「系统管理」权限的角色 | `[角色ID]`、`--name`、`--description`、`--permissions`(JSON 或 `content=view,edit`)、`--confirm`、`--site` |
157
+ | `member list` / `member update` / `member remove` | 站点成员:列表(**手机号恒为掩码** `138****8000`)/ 改角色(不能动业主·不能改自己)/ 移出本站(只删成员行,账号还在);**写默认 dry-run** | `<用户ID>`、`--role`、`--confirm`、`--site` |
158
+ | `site info` / `site info save` | 公司信息:读(字段定义 + 当前值 + 素材;**首次读会幂等补建预设字段**,与后台同行为)/ 存(只改给了的字段,`version` 自增,必填与格式校验同后台);读要 `site:read`、写要 `site:write`;**写默认 dry-run** | `--company-name`、`--site-title`、`--keywords`、`--description`、`--values <JSON>`、`--confirm`、`--site` |
159
+ | `site domain-recheck` | 提交域名重新检测(只置 `next_check_at=now()`,后台 worker 下一轮跑),可只重检一个域名;**默认 dry-run** | `[域名]`、`--confirm`、`--site` |
160
+ | `site demo-seed` / `site demo-clear` | 示例内容:导入行业示例(栏目/文章/图片/标签,按 `path` 与「栏目+slug」幂等,重复导入不重复建)/ 清空示例(**只回收 `is_demo` 与 `demo/` 前缀,客户自建内容一律不动**);**默认 dry-run** | `--demo`、`--template`、`--confirm`、`--site` |
161
+ | `site sync` | 站级同步:站点表合并后是 **no-op**(回 `skipped=merged-into-site`),留着只为兼容老脚本;**默认 dry-run** | `--confirm`、`--site` |
162
+ | `plugins list` / `plugins access` | 本站插件清单(启用/装过/分类/**模板锁**,`editor` 单选互斥会提示「已停用:xxx」)/ 插件按角色·成员的访问范围(`plugin_access`;迁移没跑时 `available:false`,按全站可见理解);读要 `site:read` | `--site`、`--key`(access 可选,给就只查这一个) |
163
+ | `plugins toggle` / `plugins settings` | 开关插件(`editor` 分类启用一个会自动停用同分类其它;**被模板依赖的插件不给关**)/ 存插件配置(按 manifest 声明的键与类型归一化,未声明的键丢掉);写要 `site:write`,**默认 dry-run** | `--key`(必填)、`--enable`/`--disable`、`--settings <JSON>`、`--confirm`、`--site` |
164
+ | `plugins market-list` / `plugins demo` | 插件市场(只出 `applies_to` 含 CMS 且对你可见的,带本站装没装·能不能升级)/ 演示链接(只读库里 `demo_url`,**不校验可达性**) | `--category`、`--keyword`、`--installed-only`、`--paid`/`--free`、`--key`(demo 必填)、`--site` |
165
+ | `plugins install` / `plugins uninstall` / `plugins upgrade` | 装(幂等:装过回 `already_installed`,不动数据不重复计数)/ 卸(**只删本站行,插件数据保留**,重装即恢复;被模板依赖的不给卸)/ 升级(把本站行版本改到市场当前版本;已最新回 400);**默认 dry-run** | `--key`(必填)、`--confirm`、`--site` |
166
+ | `logs list` | 本站操作日志(谁在哪台设备上改了什么;操作人手机号恒为掩码 `138****8000`;只读分页) | `--kind 操作\|登录\|系统`、`--page`、`--size`(10–200)、`--site` |
167
+ | `config get` / `config capabilities` | 站点参数(当前值 / 默认值 / 类型 / 选项 / 只读标记 + 允许的统计代码域名与内置 TLD 表)/ 本站能用哪些能力(会员插件·支付通道,取不到给原因码);读要 `site:read` | `--key`(get 可选,只查某参数名或类型)、`--site` |
168
+ | `config save` | 存站点参数(只改给了的键,白名单外的静默丢弃;`ipBlockList` 整段替换 ≤500 条;换了统计代码就重新进「待审核」);写要 `site:write`,**默认 dry-run** | `--set <JSON>`(必填)、`--confirm`、`--site` |
169
+ | `config review` | 审核统计代码(**双闸**:云函数要配 `REVIEW_TOKEN`,请求头要带对令牌;没配回 503「审核接口暂不可用」,令牌不对回 403);写要 `site:write`,**默认 dry-run** | `--pass`/`--reject` 二选一、`--reason`、`--review-token`(必填)、`--confirm`、`--site` |
170
+ | `overview summary` | 站点概览(栏目 / 内容 / 已发布 / 草稿 / 素材 / 分语言 / 本月上传) | `--lang`、`--site` |
171
+ | `overview traffic` | 账号级流量与费用(**只给平台管理员**,其他人 403;1 小时缓存,`--refresh` 强制重取) | `--refresh`、`--site` |
172
+ | `overview dashboard` | 数据看板快照(存储 / 流量 / 费用 / 额度 / 下次统计日期;非平台管理员看不到账号级流量费用,给 `account_restricted` + 说明) | `--site` |
173
+ | `forms list` / `forms entries` | 表单清单 / 提交记录(**默认脱敏**手机·邮箱·IP·UA) | `--site`、`--form`、`--status`、`--keyword`、`--page`、`--page-size`、`--raw --confirm` |
174
+ | `domain inspection` | 域名巡检(只读;需系统管理员,403 给人话) | `--site`(多站必须带)、`--keyword`、`--status`、`--page`、`--page-size`、`--scope all` |
175
+ | `domain bind` | **绑自有域名**(原生 `cliProvisionSiteDomain`):成功=受理开通(`provision_state` 多为 `provisioning`,进度看 `domain status`)。**平台通道没开时上游 503** ⇒ 「域名开通通道暂不可用(平台侧未开),本次未写入,可直接重试」+ `exit 1`(**不假装成功**) | `<域名>`(必填)、`--site` |
176
+ | `domain status` / `domain records` | 域名开通状态(含客户待办 TXT/CNAME)/ 每域解析与验证状态(只读) | `--site` |
177
+ | `domain dns` | 把要**客户自己去加**的解析打成 RR / Type / Value / 状态(只读,**CLI 不加 DNS**) | `--site` |
178
+ | `domain check` | 域名可注册性(只读;1~10 个,429=被限流) | `<域名…>`(必填) |
179
+ | `domain remind` | 域名到期提醒(只读;**需平台管理员**,403 → exit 3) | `--limit`(1~200,默认 50) |
180
+ | `domain search` | 查域名能不能注册 + **真实报价**(阿里云 CheckDomain,走自持 fc;只读,不下单) | `<域名…>` |
181
+ | `domain buy` | 买域名(**默认 dry-run**:校验 + 报价 + 余额预检;真下单要 `--confirm`) | `<域名>`、`--confirm`、`--years`、`--template` |
182
+ | `domain order` / `domain order create` / `domain order status` | 查注册任务状态或某域归属与到期 / 买域名并建单(**默认 dry-run**:预检 + 建单,不提交注册、不花钱)/ 看订单走到哪一步(各步时间戳 + 阿里云订单/任务号) | `<订单ID>`、`--confirm` |
183
+ | `domain charge` | 扣费(自持钱包,**幂等**:同一单重复调用不会重复扣) | `<订单ID>`、`--confirm` |
184
+ | `domain template create` / `domain template status` | 建客户实名模板(只要一张营业执照)+ 提交实名审核 / 查模板审核 + 域名侧实名(两份状态分开看) | `--name`、`--license`、`<模板ID>` |
185
+ | `domain transfer` | 快速过户(按客户模板 ID 改持有者信息,不收集资料、不走人工流) | `<域名>`、`--template`、`--confirm` |
186
+ | `domain zone list` / `domain zone add` / `domain zone update` / `domain zone delete` | **真实解析**(自持 alidns,不是"照抄表"):列出 / 加一条(写后自动回读确认,同值幂等)/ 按 RecordId 全量覆盖 / 删一条(**必须 `--yes`**,重复删幂等) | `<域名>`、`--rr`、`--type`、`--value`、`--record-id`、`--yes` |
187
+ | `domain dns credential detect` / `set` / `status` / `delete` | **域名级 DNS 凭据**:只看 NS 判断托管在哪家 / 配 AK(**先调 API 验证通过才落库**,secret 只从 stdin/交互读)/ 看状态(**永不回传 secret**)/ 删(必须 `--yes`,删后解析降级人工兜底) | `<域名>`、`--provider`、`--yes` |
188
+ | `preview` | 拼预览地址(零后端,不写任何东西) | `<路径>`、`--site`、`--open` |
189
+ | `import-v2 start` / `import-v2 status` | 老站导入 v2(默认 dry-run;`--confirm` 才提交)/ 看进度 | `--url`(必填)、`--confirm`、`--max-pages`、… / `--run`(必填) |
190
+ | `ai ping` / `ai ask` / `ai chat` | **接本机大模型**:探端点 / 单问(CLI 取数+脱敏)/ 多轮 | `--context`、`--site`、`--model`、`--base-url`;`ai ask` 需 `<问题>` |
191
+ | `context export` | 把站点上下文导出给任意模型吃(**不外传**) | `--site`、`--out`、`--format json\|md`、`--with-body`、`--context` |
192
+ | `import` | 老站导入(**默认 dry-run**;走本机运维脚本,**需运维权限**) | `--url`(必填)、`--apply`、`--site` |
193
+ | `skill` | **打印给 AI 端的操作手册**(本文件原文,随包分发) | `--json`(默认纯文本原文;不受"非终端自动 JSON"影响) |
194
+
195
+ > CMS 命令(`categories` / `contents` / `assets` / `templates` / `publish`)都要先确定站点:
196
+ > `--site <站点ID>` > 环境变量 `WKONGAI_SITE` > 本地 `wkgeo site use`
197
+ > > **都没有时不带站点头**(服务端用你唯一的成员站;多站会报 `cms_site_required` 让你指定)。
198
+ > ⚠️ `--site` **只认 uuid**;域名先 `wkgeo site use <域名>` 解析。
199
+
200
+ > **1.0.0 命令组命名**(后台动作面已全量进自持 `/cli`,`whoami.action_total = **185**`):
201
+ > 插件面命令名是 **`plugins`**(没有 `plugin` 单数);日志面是 **`logs`**(不是 `log`);
202
+ > “配置类 auth”**不是命令名** —— 它落地成 **`lang` / `role` / `member`** 三组;
203
+ > 控制台面就是 **`logs` / `config` / `overview`**(没有 `console` 命令);
204
+ > `templates.*` 与 AI 7 条**仍在 CMS 会话面**(不在本版承诺内,别假设能跑)。
205
+ > ⚠️ `wkgeo commands` **不存在**(会 `exit 2 不认识的命令`):看全量命令用 `wkgeo --help`,看单组用 `wkgeo <组> --help`。
206
+
207
+ ### 4.0 控制台命令(`logs` / `config` / `overview`,2026-10-29 task-92)
208
+
209
+ 后台"看日志 / 调参数 / 看概览"这三块,CLI 也能做,**走 `/cli` 自持通道**(不借 CMS 会话):
210
+
211
+ ```bash
212
+ wkgeo logs list # 本站操作日志(分页;手机号恒为掩码)
213
+ wkgeo config get --key statsStatus # 站点参数(当前值/默认值/类型/选项/只读标记)
214
+ wkgeo config capabilities # 本站能用哪些能力(会员插件 / 支付通道)
215
+ wkgeo config save --set '{"siteStatus":"关闭"}' # 默认 dry-run,只打印不发
216
+ wkgeo config save --set '{"siteStatus":"关闭"}' --confirm # 真发
217
+ wkgeo config review --pass --review-token "$REVIEW_TOKEN" --confirm # 审核统计代码(双闸)
218
+ wkgeo overview summary # 站点概览(栏目/内容/素材/分语言)
219
+ wkgeo overview traffic --refresh # 账号级流量与费用(**只给平台管理员**)
220
+ wkgeo overview dashboard # 数据看板快照(存储/流量/费用/额度)
221
+ ```
222
+
223
+ * 读要 `site:read`、写要 `site:write`;站点必须显式(`--site` 或 `wkgeo site use`),**不是你的站 403 `not_site_owner`**,404 只给 id(不泄露站名/业主)。
224
+ * 写命令**默认 dry-run**,`--confirm` 才发;`config review` 另需 `--review-token`(只走请求头,不打印)。
225
+ * AI 类命令(`aiLogList` 等 7 条)**本批没迁**(后台功能未完成),别假设存在。
226
+
227
+ ### 4.1 站点管理入口(`sites list`)
228
+
229
+ `sites list` 是"先看清我在哪、再决定下一步"的命令(2026-10-22 起):
230
+
231
+ * **默认 `--mine`**(只看 `owner_user_id = 我`);`--managed` = 我拥有的 + 我参与的(协作站);
232
+ `--all` = 全部可见(管理员有意义,普通账号仍受 `data_scope` 限制)。
233
+ * **CMS-only 站点也会列出来**:只在 `cms_site` 里的站,平台 `listSites` 查不到,CLI 会额外调
234
+ CMS 侧 `siteImportSites` 合并去重;这类行 `source:"cms"` / `cms_only:true`(人类输出标「仅 CMS」)。
235
+ CMS 面失败不影响列表(`data.cms_list_ok:false`),**不要**据此说"你没有站点"。
236
+ * **没有站点**:交互终端(stdout + stdin 都是 TTY)会问
237
+ `∅ 你还没有站点,是否现在创建一个?(Y/n)` → 是则依次问名称 / 模板名或 ID / 地区,调后端建站;
238
+ 优先走 **CMS 通道** `cmsCreateSite`(CLI 契约名 `createCmsSite`,一次建出 CMS 站 + 平台站),
239
+ 只有 CMS 通道回"未知动作/400"才回退 `createSite`,此时**必须如实告诉用户「CMS 站点未创建」**;
240
+ 网络 / 401 / 429 / 5xx **不回退**(那是故障,不是"服务端没这动作")。
241
+ `--json` / 非 TTY **不提问**:输出 `{"sites":[],"hint":"no_sites"}`,**exit 0**(不是错误)。
242
+ * **有站点**:交互终端列序号 → `选择要管理的站点(回车=上次)` → 写本地 config
243
+ (与 `site use` 同一条落盘路径);当前站点带 `★ 当前` 标记。`--json` / 非 TTY 不提问。
244
+ * 选站只影响**本机**(`<凭据目录>/config.json`),换机/换 `--credentials` 要重新选。
245
+ * 人类终端里"回车=上次";从没选过时回车=第 1 个(提示里会写明)。
246
+ * **短域默认不显示**(平台 `listSites` 不返回 `prefix_host`):加 `--with-prefix` 逐站补(多发几次 `getSite`,
247
+ 回包 `data.prefix_enriched = {requested,filled,failed}`);要看单站全字段用 `sites get <站点ID>`。
248
+ * **域名链路只读命令**(2026-10-28 起):`domain status`(开通状态 + 客户待办 TXT/CNAME)、
249
+ `domain records`(每域解析与验证状态)、`domain dns`(把要客户**自己去加**的记录打成 RR/Type/Value/状态)、
250
+ `domain check <域名…>`(可注册性,1~10 个)、`domain remind`(到期提醒,**需平台管理员**)。
251
+ 账号下多站时这些命令都要带 `--site <站点ID>`(等价 `x-cms-site`)。
252
+ **`domain bind` 已实现**(= 受理开通,进度看 `domain status`);**`domain unbind` / `domain repair` 仍未实现**(`releaseSiteDomain` 在 OAuth 下仍是 428 短信二次验证,不造命令 —— 解绑去会员中心,重试开通 = 再跑一次 `domain bind`,幂等)。
253
+ 解析**能写**:`domain zone add|update|delete`(自持 alidns,写后回读确认);但 `domain dns` 那份清单仍按「要客户自己去域名商加」的格式输出。
254
+
255
+ ### 4.2 端到端脚本(`cli/scripts/e2e-site.mjs`)
256
+
257
+ 建站全链路脚本,**随仓库分发、不在 npm 包里**(`package.json` 的 `files` 白名单只有 `wkgeo.mjs` / `lib` / `README.md` / `SKILL.md` / `CHANGELOG.md`):
258
+
259
+ ```bash
260
+ node scripts/e2e-site.mjs --help # 用法(参数 / 步骤 / 退出码)
261
+ node scripts/e2e-site.mjs --dry-run # 干跑:只校验参数 / 凭据 / 网关,**不建站**
262
+ node scripts/e2e-site.mjs --confirm --pool global --keep # 真建站(写一条真站点)
263
+ ```
264
+
265
+ * 链路:建站(指定池)→ `getSite` 校验 `prefix_host` / `prefix_kv_written` / `provision_state` →(可选)`domain bind`
266
+ → `publish --confirm` 并轮询 job → 轮询短域首页 HTTP 200 + 内容指纹(sha256 + 长度)→ 绑域成功再轮询客户域 → 结果表 / `--json`。
267
+ * ⚠️ **默认不删站**(脚本不提供删除);真建站必须显式 `--confirm`,`--dry-run` 零写入。
268
+
269
+ ### 示例:成功
270
+
271
+ ```bash
272
+ $ npx -y @wkgeo/cli@latest orders create --product storage_gb --units 1
273
+ {
274
+ "ok": true,
275
+ "command": "orders create",
276
+ "data": {
277
+ "order_id": "95fe2dfc-73ca-4d86-80b3-0bfbb0c36f54",
278
+ "out_trade_no": "Q1759217340123abc",
279
+ "paid": true,
280
+ "amount_cents": 100,
281
+ "amount_text": "¥1.00",
282
+ "wallet_paid_cents": 100,
283
+ "balance_before_cents": 10000,
284
+ "balance_after_cents": 9900,
285
+ "product": { "code": "storage_gb", "name": "空间容量", "unit": "GB", "unit_price_cents": 100, "quota_multiplier": 1024 },
286
+ "quota": { "quota_key": "storage_mb", "quota_amount": 1024, "units": 1 },
287
+ "message": "余额已足够,订单已直接完成"
288
+ },
289
+ "meta": { … }
290
+ }
291
+ ```
292
+
293
+ **读法**:`data.paid === true` 表示**已经用钱包付清了**;`data.order_id` 是订单号;`data.balance_after_cents` 可用来向用户汇报新余额。
294
+
295
+ ### 示例:失败(余额不足,CLI **拒绝**下单)
296
+
297
+ ```bash
298
+ $ npx -y @wkgeo/cli@latest orders create --product storage_gb --units 10
299
+ {
300
+ "ok": false,
301
+ "command": "orders create",
302
+ "error": {
303
+ "kind": "insufficient_balance",
304
+ "code": "insufficient_balance",
305
+ "message": "钱包余额不足:本单需要 ¥10.00,当前余额 ¥1.00",
306
+ "hint": "CLI **不会**发起真实微信支付。请先在网页充够余额再下单;如果确实要用微信扫码,加 --allow-wechat 创建\"待支付\"订单(CLI 只打印支付链接,不扣款,也不替你确认支付)",
307
+ "retry_after": null
308
+ },
309
+ "meta": { … }
310
+ }
311
+ ```
312
+
313
+ **读法**:不要重试、不要加 `--allow-wechat` 硬来 —— 先请用户充值(`wallet recharge`)。
314
+
315
+ ---
316
+
317
+ ## 5. 授权流程(**必须让用户动手的那一步**)
318
+
319
+ > ★ **2026-10-18 域名统一到路径**:授权站 canonical 从 `https://oauth.wkgeo.com/` 改成
320
+ > **`https://wkgeo.com/oauth/`**(同意页 `/oauth/authorize/`、设备码页 `/oauth/device/`)。
321
+ > 老子域**继续可用**(老板要求并存);CLI 以 `WKONGAI_OAUTH_WEB_BASE` 为 canonical,
322
+ > 服务端 metadata 只提供路径 —— 所以**服务端还没部署新地址时,CLI 打印的也是新地址**。
323
+ > 回滚一条环境变量即可:`WKONGAI_OAUTH_WEB_BASE=https://oauth.wkgeo.com`(不用改代码)。
324
+ > ⚠️ 给用户看的地址**原样转述**,别自己把 `wkgeo.com/oauth` 改回 `oauth.wkgeo.com` 去"纠错"。
325
+
326
+ ### 5.1 本地回调模式(默认)
327
+
328
+ ```bash
329
+ npx -y @wkgeo/cli@latest login --json
330
+ # 需要更长的等待时间:--timeout 的单位是**秒**
331
+ npx -y @wkgeo/cli@latest login --json --timeout 600 # 600 秒 = 10 分钟
332
+ npx -y @wkgeo/cli@latest login --json --timeout 500ms # 也可以显式写毫秒
333
+ ```
334
+
335
+ 它会**阻塞**(默认最多 5 分钟)并输出 JSONL:
336
+
337
+ > ★ **0.2.2 起:默认就是这条回调**,等多久都**不会**自动改成设备码;整段超时只报
338
+ > `kind:"timeout"`(并在 hint 里给出"显式改用 `--device`"的下一步)。设备码只在
339
+ > ① 显式 `--device` ② 检测到系统代理 ③ 本地回调端口真的起不来 时出现(见 §5.3 / §5.4)。
340
+
341
+ ```jsonc
342
+ // 第一行 —— 拿到它就应该**立刻**把网址交给用户(不要等命令结束!)
343
+ // ⚠️ `authorize/` 的**尾斜杠不能丢**:它是托管侧 302(会丢掉全部 query)的分界线
344
+ {"ok":true,"command":"login","mode":"callback","stage":"awaiting_callback",
345
+ "authorization_url":"https://wkgeo.com/oauth/authorize/?client_id=wkgeo-cli&…",
346
+ "redirect_uri":"http://127.0.0.1:53682/callback","scope":"site:read site:write billing:self",
347
+ "timeout_ms":300000,
348
+ "user_action_required":"请让用户在浏览器中打开上面的 authorization_url,登录并点「同意」"}
349
+ // 最后一行 —— 成功
350
+ {"ok":true,"command":"login","stage":"done","data":{"account":{"user_id":"…","email":"…"},
351
+ "expires_at":"2026-10-30T…","credentials_file":"C:\\Users\\…\\.wkongai\\credentials.json"}}
352
+ ```
353
+
354
+ > ⏱️ **`--timeout` 的单位是秒**(默认 300 秒):`--timeout 600` = 600 秒 = 10 分钟;
355
+ > 也支持显式后缀 `--timeout 600s` / `--timeout 500ms`。这个单位以前是**毫秒**,
356
+ > 于是 `--timeout 600` 变成 600 毫秒(0.8 秒就超时失败)—— 所以**要更长等待就直接写秒数**,
357
+ > 不要自己换算成毫秒。非法值(`--timeout 十分钟` / `--timeout 0`)直接报用法错误(退出码 `2`),
358
+ > 不会静默变成默认值。
359
+
360
+ > 🌐 **自动打开浏览器**(⚠️ **2026-10-21 有改动**:CI/非交互环境**不再弹**,详见 §5.5):
361
+ > * **人类终端**(stdout 是 TTY、且不在 CI 里)→ **尝试自动打开**系统浏览器;
362
+ > * **非交互 / CI**(stdout 非 TTY / 管道 / AI 子进程;或存在 `CI`、`GITHUB_ACTIONS`、
363
+ > `GITLAB_CI`、`JENKINS_URL`、`TF_BUILD`、`BUILDKITE`、`TEAMCITY_VERSION`;或
364
+ > `WKONGAI_CLI_NO_BROWSER=1`)→ **只输出链接/JSON,一个浏览器进程都不 spawn**,
365
+ > `open_browser.attempted=false`、`skipped_reason="non_interactive"`;
366
+ > * 实现是**多策略依次尝试**(每条都看退出码/错误/超时,失败静默试下一条):
367
+ > * 成功 → `✅ 已为你打开浏览器,请在那里完成授权。`(紧跟着一句"授权成功后页面会自动尝试关闭");
368
+ > * 全部失败 → `⚠️ 浏览器没能自动打开,请手动复制这个地址到浏览器完成授权:` + **紧跟一行完整 URL**
369
+ > (**绝不中断**授权;AI 场景再多一句"客户端支持内置浏览器也可以在那里打开"的**可选**提示);
370
+ > * `--no-browser` → **不打开**(`open_browser.skipped_reason = "no_browser"`,最高优先级,
371
+ > 压过 `--open-browser`);
372
+ > * `--open-browser` → 只在终端里保留显式语义(**压不过**非交互判定,CI 里写它也不弹)。
373
+ > 所以 AI **不需要**自己判断"该不该开浏览器",但**永远要**把 `authorization_url` 原文转述给用户
374
+ > (CI/非交互环境里,这一步就是**唯一**的交付方式)。
375
+
376
+ **AI 的正确做法**:
377
+
378
+ 1. 用后台/长超时方式启动 `login --json`(它会等最多 5 分钟);
379
+ 2. 读到 `stage:"awaiting_callback"` 后:
380
+ * **先看 `open_browser`**:`opened:true` = CLI 已经把系统浏览器弹出来了 → 把 `paste_text`
381
+ **原样转述给用户**("已为你打开浏览器,请在那里完成授权…")即可,**不要**自己再开一遍;
382
+ * `skipped_reason:"non_interactive"`(CI / 管道 / AI 子进程)→ **CLI 没弹、也不该弹**:
383
+ 把 `authorization_url` / `paste_text` 清楚地转给有浏览器的用户;本机收不到回调时改用 `--device`;
384
+ * `opened:false`(打开失败)→ 把那段**含完整地址**的提示念给用户,或**可选**地
385
+ 在你自己客户端的内置浏览器里打开 `authorization_url`(见 §5.5,这只是备选);
386
+ * `skipped_reason:"no_browser"` → 用户/调用方明确不要弹窗,那就**只**把完整网址清楚地给用户;
387
+ 3. **等**到 `stage:"done"` 再继续下一步命令;
388
+ 4. 用户说"我不想点"时不要重试授权 —— 只能等他点(或者用 `--device`,见 5.3)。
389
+
390
+ **用户会看到什么**:登录页(账密 / 手机号验证码 / 邮箱验证码三个页签)→ 同意页
391
+ (应用名「官方 CLI」+ 将获得的能力)→ 点「同意」→ 浏览器显示
392
+ **「✅ 授权成功,请回到终端(客户端)继续操作,本页面可以关闭了」** → 终端打印
393
+ 「✅ 授权成功,已登录:<账号>」。
394
+
395
+ ### 5.2 令牌放在哪、能用多久
396
+
397
+ * 文件:`~/.wkongai/credentials.json`(Windows `%USERPROFILE%\.wkongai\credentials.json`),权限 `0600`。
398
+ * 有效期 **30 天**(2592000 秒);**不会自动刷新** —— 过期就再 `login` 一次。
399
+ * 用户也可以在网页「我已授权的应用」里一键吊销(吊销后 CLI 会收到 40102)。
400
+ * 🔒 不要把这个文件内容读出来放进任何输出/日志/第三方请求里。
401
+ * **令牌模型没有"CLI 专用令牌"**(2026-10-28 确认):CLI 直接复用这把 OAuth access_token,服务端只存 sha256 + 到期时间。要"体检"用
402
+ `auth status`(账号 / scopes / 动作面 `action_total`)、要核对令牌是否被截断/换过用 `auth token`(只给前 4 位 + 长度)、要立刻作废用
403
+ `auth revoke`(服务端 `POST /api/oauth/revoke` + 删本地)。**任何情况下都不要把完整令牌打印出来**。
404
+
405
+ ### 5.3 设备码模式(`login --device`)—— **本地读不了回调 / 代理 / 远程机器时的兜底**
406
+
407
+ > ★ **默认不是设备码**:`wkgeo login` 默认走浏览器回调(授权页 + 本地 `127.0.0.1` 回调,见 §5.1)。
408
+ > 只有这几种情况才用设备码:
409
+ > 1. 用户**显式** `--device` / `--no-wait` / `--device-continue`;
410
+ > 2. **检测到系统代理**(CLI 自动改道,见 §5.4;`--no-auto-device` 可关);
411
+ > 3. 本地回调端口**真的起不来**(CLI 自动兜底,`reason:"callback_listen_failed"`;`--no-auto-device` 可关)。
412
+ > **等待超时不会**自动改设备码(0.2.2 起)。
413
+
414
+ **什么时候用它**(不用问用户,直接选它就行):
415
+
416
+ * CLI 跑在远程服务器 / 容器 / CI 里(本地回调打不到用户机器);
417
+ * ⭐ **用户开着代理/VPN**(CLI 会自动检测,见 §5.4)—— 回调可能被代理接管;
418
+ * 用户机器有防火墙/安全软件拦本地监听;
419
+ * 用户觉得"复制长网址"麻烦(设备码页面短码已预填,点一下就完)。
420
+
421
+ **两条用法**:
422
+
423
+ ```bash
424
+ # ① 交互式终端 / 你有长超时能力:一口气跑完(阻塞,最多 expires_in 秒)
425
+ npx -y @wkgeo/cli@latest login --device --json
426
+ # → {"stage":"awaiting_user","user_code":"ABCD-1234",
427
+ # "verification_uri":"https://wkgeo.com/oauth/device/",
428
+ # "verification_uri_complete":"…/?user_code=ABCD-1234","open_url":"…",
429
+ # "expires_in":600,"interval":5,"paste_text":"请打开 … 并完成「同意授权」(短码:ABCD-1234)。",
430
+ # "user_action_required":"请让用户访问 … 并输入短码 ABCD-1234"}
431
+ # → 最后一行 {"stage":"done","data":{…}}
432
+
433
+ # ② ★ Agent 推荐:拆成两步,**不需要长驻进程**
434
+ npx -y @wkgeo/cli@latest login --device --no-wait --json # 申请完立刻退出
435
+ # → 一条事件:no_wait:true + resume_command:"wkgeo login --device-continue"
436
+ # + pending_file + expires_at + next_step(照着 next_step 说话即可)
437
+ # (把 paste_text 原样念给用户,让他在**自己的浏览器**里点「同意」)
438
+ npx -y @wkgeo/cli@latest login --device-continue --json # 用户说"点好了"之后再领票
439
+ # → 最后一行 {"stage":"done","data":{…凭据已写入…}}
440
+ ```
441
+
442
+ **②里那一行事件 = AI 端要用的全部信息**(都在这条 `stage:"awaiting_user"` 事件上):
443
+
444
+ | 字段 | 含义 | AI 端怎么用 |
445
+ | --- | --- | --- |
446
+ | `user_code` | 短码(形如 `ABCD-1234`) | 只有当用户要手输时才念;优先给下面的完整网址 |
447
+ | `verification_uri` | 确认页地址 | 网址兜底(一般不单独用它) |
448
+ | `verification_uri_complete` | 带 `?user_code=` 的地址(短码已预填) | **优先**把这个给用户,他打开点「同意」就完 |
449
+ | `paste_text` | CLI 已经写好的一句话(含网址 + 短码 + 要做什么) | **原样念给用户**,不要自己改写 |
450
+ | `expires_in` | 短码有效期(秒,默认 600 = 10 分钟) | 过期了重新 `--device --no-wait` 申请,别硬续 |
451
+ | `interval` | 服务端建议的轮询间隔(秒) | 只影响 `--device-continue` 内部,AI 不用管 |
452
+ | `resume_command` | 下一步该跑的命令(`wkgeo login --device-continue`) | 用户说"点好了"之后再跑它 |
453
+ | `pending_file` | 短码落盘的位置(本地状态) | 排障用;**换机器/换容器就续不上**(状态在本机) |
454
+ | `next_step` | CLI 写好的"下一步怎么做" | 照着它说话,别自己组织语言 |
455
+
456
+ (另有 `open_url` = CLI 实际会打开的地址、`user_action_required` = 直接可用的用户话术、`no_wait` / `expires_at` / `proxy_warning` 等诊断字段。)
457
+
458
+ **AI 端的正确做法**:
459
+
460
+ 1. 优先用 `--device --no-wait --json`(一轮工具调用就返回,不会把用户/自己晾住);
461
+ 2. 把事件里的 `paste_text`(或 `user_action_required`)**原样转述给用户**——不要自己改写、
462
+ 不要漏掉短码或网址;
463
+ 3. 用户回"点好了"之后跑 `login --device-continue --json`,看到 `stage:"done"` 才算登录成功;
464
+ 4. 用户迟迟没点:设备码有 `expires_in`(默认 600 秒)有效期,过期就重新申请一次,
465
+ **不要**反复跑 `--device-continue`(那只会得到 `kind:"expired"`);
466
+ 5. 🔴 **不要试图替用户确认**(见下面的安全边界)。
467
+
468
+ > 🔴 **安全边界(务必理解,别越线)**:用户在确认页点「同意」这一步是
469
+ > `POST /api/oauth/device_confirm`,它**要求用户自己的平台登录会话**。
470
+ > AI 端**没有、也不该有**用户的浏览器会话,所以:
471
+ > * "用户把短码发到 AI 对话框"之后,AI 能做的是**把网址/短码清楚地转达、引导他自己去点**;
472
+ > * **不能**替用户确认(也没有任何命令能代点 —— CLI 这边根本没有这个动作)。
473
+ >
474
+ > ✅ 这条路径**已上线并端到端真跑通过**(2026-10-02,含真 CLI 子进程
475
+ > `awaiting_user → done`、重放防护、以及 `--no-wait` + `--device-continue` 全流程)。
476
+
477
+ ### 5.4 代理 / VPN 环境下怎么办(`127.0.0.1` 被代理接管)
478
+
479
+ **现象**:回调模式下用户点了「同意」,浏览器报"无法访问此网站"或没反应,
480
+ `login` 一直等到超时(`kind:"timeout"`)。
481
+
482
+ **机理**:回调要求**浏览器**访问 `http://127.0.0.1:<端口>/callback?code=…`;
483
+ 全局/系统代理若没把回环地址排除,这条请求会被代理接管 → CLI 收不到 code。
484
+
485
+ **CLI 已经自己处理好了**(2026-10-02 第二版加固 + 2026-10-21 默认模式调整):
486
+
487
+ * ★ **只要检测到"生效中的系统代理"就直接改用设备码模式**(事件流里第一行就是
488
+ `stage:"awaiting_user"`,而不是 `awaiting_callback`);`data.auto_device.reason = "proxy_detected"`。
489
+ ⚠️ **判定不看代理绕过列表**:真机上出现过"绕过列表里明明写了 `127.*;localhost`
490
+ 却仍被代理接管"(用户点了【同意授权】,CLI 一直拿不到令牌;
491
+ 证据 `curl -x http://127.0.0.1:7890 http://127.0.0.1:1/x` → 502)。
492
+ `proxy_warning.loopback_bypassed` / `risk` 现在**只是诊断字段**,不再代表"回调没问题";
493
+ `proxy_warning.loopback_bypass_trusted` 恒为 `false`。
494
+ * ★★ **0.2.2 起:等待超时不再自动改设备码**(老板 2026-10-21 反馈):
495
+ 老板原话「默认的也不应该是设备授权,默认的就是那个传统的授权方式(浏览器打开授权页 +
496
+ 本地 localhost 回调)。设备码是本地读不了/代理时才用的。」
497
+ ⇒ 没有代理时 `login` 会**一路等回调到 `--timeout`**(默认 300 秒),超时只报
498
+ `kind:"timeout"`,并在 `hint` 里给出"显式改用 `--device`"的下一步。
499
+ ⚠️ 历史行为(0.2.1 及更早):有代理时"首轮等待 180 秒"到点会改设备码、整段超时也会改;
500
+ 现在那个"首轮等待"**默认关闭**,只有用户**显式**写 `--callback-first-wait <秒>` /
501
+ `WKONGAI_CALLBACK_FIRST_WAIT_MS` 才启用(显式优先,`reason:"callback_first_wait"`)。
502
+ 显式启用时仍然是**两条路并存**:本地回调监听继续保留,哪条先成功就用哪条 ——
503
+ 用户之后才点的那次【同意授权】照样能完成登录;旧逻辑在切换那一刻关了监听,用户随后点同意
504
+ 只会看到 **ERR_CONNECTION_REFUSED**(真机截图见过的"无法访问此网站",2026-10-03 已修)。
505
+ 若设备码先成功,之后到达的回调会拿到一张「本次登录已经完成」的页面(不是错误页);
506
+ 若回调先成功,设备码轮询会被停掉并说明(`ℹ️ 本地回调已经拿到令牌:设备码那条路已停止…`)。
507
+ * 本地回环端口**真的起不来**(防火墙/安全软件/端口非法)→ 自动兜底设备码
508
+ (`reason: "callback_listen_failed"`),**不会**直接失败退出;
509
+ `--no-auto-device` 可关闭这个兜底(此时如实报 `kind:"listen"`)。
510
+ * 换票失败 / 用户点了拒绝 → **不降级**(授权已经走到下一步了,别让用户白做一遍);
511
+ * 上述情况下,`meta.proxy_warning` / `data.proxy_warning` 都会告诉你原因与建议动作:
512
+
513
+ ```jsonc
514
+ "proxy_warning": {
515
+ // ★ callback_may_fail 现在等价于 detected(与绕过列表无关)
516
+ "detected": true, "callback_may_fail": true, "loopback_bypass_trusted": false,
517
+ "risk": false, "loopback_bypassed": true, // 仅诊断
518
+ "proxy": "127.0.0.1:7890", "source": "windows-registry",
519
+ "bypass": ["localhost", "127.*", "<local>"], "actions": [
520
+ {"type":"use_device_code","label":"改用设备码模式(不需要本地回调,推荐)","command":"wkgeo login --device"},
521
+ {"type":"bypass_loopback","label":"把 127.0.0.1,localhost 加进代理绕过列表(想继续用浏览器回调模式时;注意它不保证生效)"},
522
+ {"type":"disable_proxy","label":"临时关闭代理后重试"}
523
+ ]
524
+ }
525
+ ```
526
+
527
+ **AI 端该怎么说**:
528
+
529
+ * 看到 `proxy_warning.callback_may_fail: true`:**不要**叫用户去改代理设置(很多用户不懂),
530
+ 直接按设备码流程走 —— CLI 通常已经自动切过去了;
531
+ 只有当用户明确说"我就想用浏览器回调"时,才把 `actions` 里第 2/3 条念给他;
532
+ * 看到 `auto_device.applied: true`:按 `reason` 如实说明,别隐瞒:
533
+ * `"proxy_detected"` → 「检测到你开着代理,已自动改用设备码模式(不需要本地回调)」;
534
+ * `"callback_listen_failed"` → 「本地回调端口起不来,已自动改用设备码模式继续」;
535
+ * `"callback_first_wait"` → **只可能**是用户自己显式开了 `--callback-first-wait`:
536
+ 「等待到点没收到回调,已同时改用设备码(两条路哪条先成功算哪条)」。
537
+ * 没有 `auto_device`(`applied:false`)就是**默认的浏览器回调**,不要主动提设备码。
538
+ * 想让 CLI **不要**自动改道(例如你确认回调一定通):加 `--no-auto-device`,或设
539
+ `WKONGAI_AUTO_DEVICE=0`。⚠️ 此时 CLI 会**打印警告**说"若代理接管 127.0.0.1,
540
+ 点了【同意授权】也收不到结果",并且**不会**再用首轮等待自愈、端口起不来也**不兜底** ——
541
+ 尊重用户的选择,但要**把这个风险如实转述**给他;
542
+ * 用户只是**等得久**(没代理、也没报错):**不要**自己改成设备码 —— 0.2.2 起默认就是回调,
543
+ 等多久都不会自动变;要设备码必须**显式**加 `--device`(先问用户,别擅自换模式);
544
+ * 排障:`npx -y @wkgeo/cli@latest config --json` 里有 `data.proxy` 与 `meta.proxy_warning`,
545
+ 是"用户机器上是不是代理挡了回调"的**唯一权威判断**(只读检测,不会改用户任何设置)。
546
+
547
+ ### 5.5 打开授权页 / 收银台(**给 AI 端**)
548
+
549
+ > ★ **2026-10-21 起:人类终端会自动弹系统浏览器;CI/非交互环境只输出链接**(老板真机反馈:
550
+ > 「别人在 CI 里执行 `wkgeo-cli` 的 login,默认弹出了系统默认浏览器」)。所以你的第一动作**不是**
551
+ > 去开内置浏览器,而是**看 `open_browser` 字段 + 把 `paste_text` 念给用户**:
552
+
553
+ | `open_browser` | 你该做什么 |
554
+ | --- | --- |
555
+ | `opened: true` | ✅ CLI 已经把浏览器弹出来了 → 把 `paste_text` **原样**念给用户即可,**不要**再自己开一遍 |
556
+ | `skipped_reason: "non_interactive"` | 🖥️ 这是 CI / 管道 / AI 子进程:CLI **没弹**(也不该弹)→ 把 `authorization_url` / `paste_text` 清楚地交给有浏览器的用户;本机收不到回调就用 `login --device` |
557
+ | `opened: false`(`attempted: true`) | ⚠️ 真的尝试过但没能自动打开 → 把那段**含完整地址**的提示念给用户(或可选地在你的内置浏览器里打开,见下) |
558
+ | `skipped_reason: "no_browser"` | 调用方/用户明确不要弹窗 → **只**把完整网址清楚地给用户,不要自己开浏览器 |
559
+ | `skipped_reason: null` | 真的尝试过打开(成没成看 `opened`)—— 人类终端的默认情况 |
560
+
561
+ **兜底手段(可选,**只在 CLI 没打开成功**时用)**——按 ① → ② → ③ 判断:
562
+
563
+ ```
564
+ ① 客户端【原生】支持"在内置浏览器 / 侧边面板打开 URL" → 直接用 ✔(一句话,不装任何东西)
565
+ ② 客户端不支持(DSH 就是)→ 装桥接插件 → 装完就能在【右侧】打开 ✔
566
+ ③ 都不行 → 把**完整地址**交给用户复制(说清动作是"复制到浏览器地址栏打开")
567
+ ```
568
+
569
+ * ⚠️ **这只是备选**:人类终端里 CLI 已经自动弹系统浏览器了,**不要**再叠一层"请在右侧…"的话术 ——
570
+ 那会让用户不知道该看哪个窗口。**CI / 非交互环境**里 CLI 不会弹(`skipped_reason:"non_interactive"`),
571
+ 这时把链接清楚地交给用户才是主路径。
572
+ * ① **原生就支持**:直接打开,**不需要装任何东西**;已经原生支持"应用内侧边栏"的客户端
573
+ (DSH 自带"点链接进右栏"),**让用户点一下链接**也算数。
574
+ * ② **不支持 → 装桥接插件**(DSH 的 `dsh-browser-open`):
575
+ * 装:`dsh plugin --profile desktop add <本地插件路径>`
576
+ * 自检:`curl -s http://127.0.0.1:19387/dsh-browser-open/next` —— 返回 `{"url":""}` = 通道可用 ✔
577
+ * 回滚:`dsh plugin --profile desktop remove dsh-browser-open`
578
+ * ③ 把**完整地址**清楚地给用户,并说明"复制到浏览器地址栏打开",不要只说"我把链接发给你了"。
579
+ * ✅ 传统路线的两个好处(老板为什么这么定):**稳定**(各平台都有成熟的系统启动器);
580
+ **`window.close()` 在独立浏览器里生效** —— 授权页/收银台完成后的那一屏能自己关掉。
581
+ * ★ **页面完成之后会自己关掉**(2026-10-02 老板):授权成功 / 支付成功那一屏会尝试
582
+ `window.close()`,所以**那个页面自己消失是正常的**,不要因此以为出了错。
583
+ ⚠️ 浏览器只允许脚本关闭**由脚本打开的**窗口,本页是导航过去的 ⇒ **关不掉也是常态**
584
+ (页面上有「关闭本页」按钮兜底)。两种情况都**不需要**让用户去找那个页面;
585
+ 没关掉就让他手动关掉即可。`paste_text` / 提示语里已经带了这句话,照念就行。
586
+ * **DSH 专用的一行触发**(**仅 DSH,且 `dsh-browser-open` 插件已装**,**只在 CLI 没能自动打开时**才用):
587
+
588
+ ```powershell
589
+ Set-Content -LiteralPath "$env:USERPROFILE\.dsh\browser-open.txt" -Value "<完整网址>" -NoNewline -Encoding utf8
590
+ ```
591
+
592
+ 约 **1.2 秒**后在**右侧内置浏览器**打开,收件文件会被**自动删除**(删掉 = 客户端真的执行了)。
593
+ 原理 / 三层验证 / 回滚见 [`docs/AI客户端-内置浏览器打开.md`](../docs/AI客户端-内置浏览器打开.md)。
594
+
595
+ **CLI 这边的行为(你不需要自己判断,照着字段走就行)**:
596
+
597
+ | 运行场景 | CLI 会不会自动弹**系统**浏览器 |
598
+ | --- | --- |
599
+ | **人类终端**(stdout 是 TTY、无 CI 信号) | ✅ **会尝试打开** |
600
+ | **CI / 非交互**(stdout 非 TTY / 管道 / AI 子进程;`CI`、`GITHUB_ACTIONS`、`GITLAB_CI`、`JENKINS_URL`、`TF_BUILD`、`BUILDKITE`、`TEAMCITY_VERSION` 任一存在;`WKONGAI_CLI_NO_BROWSER=1`) | ❌ **绝不弹**(`skipped_reason:"non_interactive"`,只输出链接/JSON) |
601
+ | 加了 `--no-browser` | ❌ **不打开**(**优先级最高**,压过 `--open-browser`;`skipped_reason:"no_browser"`) |
602
+ | 加了 `--open-browser` | ✅ 只在**终端**里会(⚠️ 压不过非交互判定;别依赖它去"开启") |
603
+
604
+ * **`--json` 里的结构化字段 `open_browser`**:`{attempted, opened, tried, url, skipped_reason}`
605
+ (结构与取值口径**没有变**)—— `skipped_reason` 有三种取值:
606
+ * `null` = 真的尝试过打开(成没成看 `opened`);
607
+ * `"non_interactive"` = CI / 管道 / AI 子进程,**没弹**(也不该弹);
608
+ * `"no_browser"` = 调用方/用户明确要求别打开。
609
+ * ⚠️ 历史取值 `"non_tty_agent_mode"`(2026-10-01 那版"AI 场景默认不弹")**已弃用,不会再出现**
610
+ —— 看到它说明你在读旧文档/旧版本的输出。
611
+ * 同一条事件/数据里还有 **`paste_text`**(`login` 的 `awaiting_callback` 事件、`wallet recharge` 的 `data`):
612
+ **原样念给用户**,不要自己改写。⚠️ 非交互时它是「请打开以下链接完成授权:<url>」,
613
+ **不会**说"已为你打开浏览器"(因为确实没弹)——照念即可,别自己补一句"已打开"。
614
+ * ⚠️ **不弹浏览器 ≠ 失败**,**打开失败也 ≠ 失败**:流程照旧等回调、照旧返回 `pay_url`;
615
+ CLI **绝不会**因为"没打开浏览器"而让命令失败 —— 你只要把地址送到用户眼前就对了。
616
+
617
+ ---
618
+
619
+ ## 6. 错误码 → 该做什么
620
+
621
+ | `error.kind` / `code` | 含义 | **AI 应该做的事** |
622
+ | --- | --- | --- |
623
+ | `expired` / `40101` | 令牌已过期 | 让用户重新授权:跑 `login`(**不需要**重新输密码注册;浏览器里通常还有登录态) |
624
+ | `revoked` / `40102` | 授权已被吊销 | 同上重新 `login`;并提醒用户"如果这不是你做的,去「我已授权的应用」看看" |
625
+ | `unauthenticated` / `401` | 旧版:过期/被吊销/未登录**分不出来** | 一律重新 `login`(CLI 的 `hint` 会说明这点) |
626
+ | `rate_limited` / `429` | 调用过于频繁(每令牌 60/分、写操作 20/分) | **等 `retry_after` 秒后原样重试**。⚠️ **绝对不要**重新授权 —— 限流和授权无关,重授权只会白跑一遍浏览器 |
627
+ | `forbidden` / `403` | scope 不足,或动作需要二次验证 | scope 不足 → `login --scope "site:read site:write billing:self"` 重新授权;**动钱/改权限类动作 → 明确告诉用户"这个只能你在网页后台做"** |
628
+ | `step_up` / `428` | 需要 5 分钟内重新输密码 | 同上:**AI 做不了**,让用户去网页后台 |
629
+ | `insufficient_balance` | 余额不足 | 先 `wallet` 确认,再 `wallet recharge --amount-cents N` 让用户扫码;**不要**加 `--allow-wechat` 绕过 |
630
+ | `not_found` / `404` | 订单/站点/产品不存在 | 用 `orders list` / `products list` 重新确认 ID |
631
+ | `bad_request` / `400` | 参数不对 | 按 `message` 修正参数;别硬改着重试 |
632
+ | `not_deployed` | 该接口服务端还没发布 | 告诉用户"这是服务端缺口",不要反复重试 |
633
+ | `cms_auth` / `401`(CMS 命令) | CMS 没接受 Bearer 令牌:通常是**令牌无效**(过期/吊销/客户端停用);只有旧部署才会是"没启用 CLI 认证" | 先 `wkgeo login` 重新授权一次(正常环境一定能解决);仍不行再用 `whoami` 判断是否服务端旧部署,让管理员确认(**不要**反复登录十几次) |
634
+ | `cms_site_required` / `400` | 账号有多个站点,没指定 | 先问用户是哪个站,再 `site use <站点ID>` 或 `--site <站点ID>` |
635
+ | `cms_not_member` / `403` | 不是该站成员 / 站点 id 不对 | 让用户确认站点(`site use` 重选);协作站要 owner 先加成员 |
636
+ | `cms_readonly` / `403` | 站点角色是 viewer(只读) | 让 owner 在后台「用户与角色」里升为 editor;**不要**换令牌硬试 |
637
+ | `cms_scope` / `403` | 令牌 scope 不够(如 `template:write`) | 需要更高授权:`login --scope "<原有 + 缺的>"`;已知官方 CLI 客户端没放开 `template:write` / `attachment:delete` |
638
+ | `cms_unavailable` | CMS 地址不通 / 云函数没部署 / 返回不是 JSON | 检查 `wkgeo config` 的 `cms_base`;多半是服务端没部署,告诉用户"后台暂时连不上" |
639
+ | `import_unavailable` | 本机没有 `tencent/cloudbase/import-site.mjs` | 告诉用户"老站导入需要运维权限/本仓库环境",**不要**承诺普通客户能用 |
640
+ | `import_failed` | 导入脚本非 0 退出 | 念 `hint` 与日志尾巴;dry-run 失败不动库,可安全重试 |
641
+ | `missing_skill` | `skill` 在本包里找不到 `SKILL.md`(包被裁剪/只拷了 `lib/`) | 换官方包 `npx -y @wkgeo/cli@latest skill`;**不是**命令用错了,别让用户去排查 |
642
+ | `server` / `5xx` | 服务端错误 | 保留原文告知用户,可稍后重试 |
643
+ | `domain_inspection_forbidden` / `domain_remind_forbidden`(exit 3) | 域名巡检要「系统管理员」、到期提醒要**平台管理员** | 如实说权限不够,让对应管理员跑;**不要**换成用户自己的令牌反复试 |
644
+ | `rate_limited` / 429(`domain check`) | 查域名**限流 30 次/分** | 等 `retry_after` 秒;一次最多 10 个域名 |
645
+ | `network` | 连不上/超时 | 检查网络后重试;`message` 里是原始错误(如 `getaddrinfo ENOTFOUND`) |
646
+
647
+ **通用规则**:先看 `error.hint` —— 那是 CLI 写好的"下一步";`message` 是服务端原文,
648
+ **原样转述给用户**,不要改写成"操作失败了"。
649
+
650
+ ---
651
+
652
+ ## 7. 典型工作流
653
+
654
+ ### 7.1 用户说"帮我建个站并付钱"
655
+
656
+ ```bash
657
+ # ① 先确认登录状态(没登录会 exit 3)
658
+ npx -y @wkgeo/cli@latest whoami
659
+ # exit 3 → 走 §5 的授权流程,等用户点完「同意」再继续
660
+
661
+ # ② 先看我有没有站(AI 侧一定拿到 JSON,不会提问)
662
+ npx -y @wkgeo/cli@latest sites list
663
+ # data.hint == "no_sites" → 没有站:走 sites create;否则把 data.sites 交给用户选
664
+ # ⚠️ CMS-only 站点也在 data.sites 里(source:"cms"),别只看平台面
665
+
666
+ # ③ 建站(名字由用户给;返回站点 id)
667
+ npx -y @wkgeo/cli@latest sites create --name "我的新站"
668
+ # 读 data.site.id / data.site.owner_user_id(应等于 whoami 的 user_id)
669
+ # ℹ️ 客户(customer)层已于 2026-10-27 删除:建站不需要任何归属参数,归属固定为令牌所属用户。
670
+ # ℹ️ 默认 --channel auto:先走 CMS 通道 cmsCreateSite(CMS 站 + 平台站一次建好),
671
+ # 只有 CMS 通道回「未知动作 / 400」才回退平台 createSite;网络/401/429/5xx 不回退。
672
+ # 最终走了哪条看 data.channel("cms" / "platform");只想要某一条就显式
673
+ # --channel cms 或 --channel platform。
674
+ # ⚠️ data.short_domain.kv_written === false ⇒ 短域解析没写进 KV,现在访问短域会 403/404
675
+ # (stderr 也会 warn);修复等后端 domain repair 上线。null = 旧接口没回这个字段。
676
+ # ⚠️ `--domain` 只把域名**登记**到站上(写 site.domains),**不触发解析/证书**,
677
+ # 加解析要用户自己去域名商加(用 `domain dns` 看要加什么)。
678
+
679
+ # ④ 看能买什么 + 余额够不够
680
+ npx -y @wkgeo/cli@latest products list
681
+ npx -y @wkgeo/cli@latest wallet
682
+
683
+ # ⑤ 下单(余额够就当场付清;不够会 exit 1 且 kind=insufficient_balance)
684
+ npx -y @wkgeo/cli@latest orders create --product storage_gb --units 1
685
+ # 读 data.paid / data.order_id / data.balance_after_cents
686
+
687
+ # ⑥ 复核 + 汇报
688
+ npx -y @wkgeo/cli@latest wallet txns --limit 3
689
+ ```
690
+
691
+ **每一步都必须停下来检查 `ok`**;失败时按 §6 处理,**不要**把一串命令一次性盲发。
692
+
693
+ ### 7.2 用户说"帮我充值 100 块"
694
+
695
+ ```bash
696
+ npx -y @wkgeo/cli@latest wallet recharge --dry-run --amount-cents 10000 # 先彩排,确认金额
697
+ npx -y @wkgeo/cli@latest wallet recharge --amount-cents 10000 # 生成待支付订单,并把收银台地址交出来(不扣款)
698
+ # ★ 读 data.pay_url —— 这是**我们网站的收银台页面**(https://pay.wkgeo.com/?order_id=…&token=…)。
699
+ # ⚠️ **不要把 data.code_url 当成主流程丢给用户自己想办法**(那是微信内部支付链接,
700
+ # 手机直接扫不了;终端二维码只是"网页打不开"时的兜底)。
701
+ # ★ `token=` 是服务端在下单那一刻签发的**订单支付令牌**(只对这一单有效):
702
+ # 带上它,收银台在**没有网页登录态**的环境里(新开/无痕窗口、客户端内置浏览器等)
703
+ # 也能读这一单并支付
704
+ # (老板:"以那个 token 为基础来进行支付,而不是还要他用用户名那一套")。
705
+ # ⚠️ 老服务端没有这个字段时 `pay_url` 就只有 `order_id`,那条路仍然要求网页登录。
706
+ # ⚠️ **原样打开 data.pay_url**,不要自己拆参/重拼(尾斜杠与编码都有讲究)。
707
+ # ★ 打开方式见 §5.5:**人类终端**里 CLI 会尝试弹系统浏览器;**CI/非交互**只输出链接,
708
+ # 你只要看 data.open_browser:opened:true → 把 data.paste_text(已含完整地址 +
709
+ # "已为你打开浏览器…")原样念给用户即可;skipped_reason:"non_interactive" → CLI 没弹,
710
+ # 把 data.pay_url 交给用户;opened:false → 念那段**含完整地址**的提示,
711
+ # 或可选地在自己的内置浏览器里打开 data.pay_url。
712
+ # ⚠️ `data.open_browser.skipped_reason = "no_browser"` = 调用方明确要求别弹(那就只给地址)。
713
+ # ★ **支付成功后那个页面会自己关掉**(收银台会尝试 `window.close()`):
714
+ # 关掉了是正常的,**不要**让用户去找那个页面、也不要催他"点返回";
715
+ # 没关掉就让他手动关掉即可。用户回报"付完了"之后再执行下面那条查单。
716
+ npx -y @wkgeo/cli@latest orders check <order_id> # 用户说付完了再查
717
+ # 读 data.paid / data.balance_text
718
+ ```
719
+
720
+ ⚠️ **AI 永远不要替用户"确认支付成功"**:只能查。查不到就是没付。
721
+ ⚠️ `wallet recharge` 的 `--json` 里 `order_id` / `code_url` / `pay_url` **三个都在**:
722
+ 自动化用 `pay_url`(打开自家收银台),不要把 `code_url` 当成"让用户扫码"的入口。
723
+ ⚠️ `pay_url` 上可能带 `token=`(**订单支付令牌**,见上面 §7.2 的说明)。
724
+ * 它的存在就是为了让"**没有网页登录态**"的窗口(新开/无痕窗口、客户端内置浏览器等)也能付这一单 ——
725
+ **原样打开**即可,**不要**把 `token` 单独摘出来展示、更不要放进对话正文里当"验证码"念给用户;
726
+ * 它**只**授权"读这一单的支付参数":读不到钱包、读不到订单列表、不能下单、不能取消,
727
+ 而且 30 分钟(= 订单有效期)后自动失效(失效时页面会明确说"支付链接已过期,请重新下单")。
728
+ ⚠️ 非交互/CI 环境(容器、管道、AI 子进程)**本来就不会弹**:`open_browser.skipped_reason = "non_interactive"`,`pay_url` 照常输出;
729
+ ⚠️ 终端里 `--open-browser` 保留显式语义(**非交互/CI 仍不弹**);要显式不弹用 `--no-browser`(`skipped_reason = "no_browser"`,优先级最高)。
730
+ ⚠️ 打开 `pay_url` 的方式见 **§5.5**:人类终端会自动弹系统浏览器;
731
+ 只有它**没打开成功**(或非交互环境)时,才考虑可选地在客户端**内置浏览器 / 侧边面板**里打开。
732
+
733
+ #### 7.2.1 另一种:**让用户自己选金额**(`wallet recharge-link`,独立充值页)
734
+
735
+ 用户**没给金额**、或说"我自己选"/"给我个充值链接"时用它。它**不建单、不定金额**,
736
+ 只换一张**一次性 ticket** 并给出链接:
737
+
738
+ ```bash
739
+ npx -y @wkgeo/cli@latest wallet recharge-link # 默认不弹浏览器:交接物就是链接本身
740
+ # ★ 读 data.pay_url —— 形如 https://pay.wkgeo.com/recharge/?ticket=…
741
+ # 把它**原样**发给用户(或做成可点的链接)。他在那一页上:
742
+ # 选金额(¥10 / ¥20 快捷,或自定义;最低 ¥9.90、**不设上限**)→ 提交 → 微信扫码支付。
743
+ # ⚠️ **不需要登录会员中心** —— 凭证就是地址里的 ticket,整条链路与登录态无关。
744
+ # ★ data.paste_text 是"照着念"的一句话(含完整地址),直接转述,别自己组织语言。
745
+ # ★ 有效期只有 10 分钟、且**用掉即失效**(一次性):过期/已用过时页面会明确提示"请重新获取",
746
+ # 这时**重新跑一次本命令**拿一条新链接即可(不要反复让用户刷新旧链接)。
747
+ # ★ 默认**不**打开浏览器(这条命令通常跑在服务器/容器里,且交接物是链接);
748
+ # 确实要在**人类终端**里弹出时加 --open-browser(CI/非交互仍不弹);--no-browser 优先级最高。
749
+ # ★ ticket 只是"建一笔充值单"的窄凭证:⛔ 不要把它当登录凭据、不要拿它去调别的 action。
750
+ npx -y @wkgeo/cli@latest orders check <order_id> # 用户说付完了再查(order_id 从他那句"付完了"对应的单拿)
751
+ ```
752
+
753
+ ⚠️ **AI 永远不要替用户"确认支付成功"**:只能查。查不到就是没付。
754
+ ⚠️ 别把 `ticket` 单独展示成"验证码"念出来:它是**链接的一部分**,原样交付整条链接即可。
755
+
756
+ ### 7.3 用户说"查一下我的余额和订单"
757
+
758
+ ```bash
759
+ npx -y @wkgeo/cli@latest wallet
760
+ npx -y @wkgeo/cli@latest wallet txns --limit 20
761
+ npx -y @wkgeo/cli@latest orders list --limit 10
762
+ ```
763
+
764
+ ### 7.4 用户说"取消某个应用的授权"
765
+
766
+ ```bash
767
+ npx -y @wkgeo/cli@latest apps list # 找到应用名与 client_id
768
+ npx -y @wkgeo/cli@latest apps revoke <client_id> # 该应用所有令牌立即失效
769
+ # 若吊销的是 CLI 自己(client_id=wkgeo-cli),本地凭据随之失效 → 需要重新 login
770
+ ```
771
+
772
+ **⭐ 对用户的话术(老板明确要求,务必照做)**:
773
+
774
+ * 用户想"取消授权 / 解绑 / 不想让你再访问我的账号"时,**让他直接跟 AI 说一句就行**
775
+ ("帮我取消 XX 的授权")—— AI 侧执行 `apps list` → `apps revoke`,**不要**让用户自己去敲命令、
776
+ 也不要把他指去后台找入口(他多半找不到,也看不懂);
777
+ * ⚠️ **用户可见的文案里不要出现终端命令、`client_id`、`apps revoke` 这类技术字眼**。
778
+ 用户不需要知道我们是怎么做的,只需要知道**结果**;
779
+ * ✅ 这么说:「已经帮你把「XX 助手」的授权取消了,它现在不能再访问你的云站账号。」
780
+ * ❌ 别这么说:「请运行 `wkgeo apps revoke wkgeo-cli`」/「你的 client_id 是 wkgeo-cli」/
781
+ 「我去调一下 revoke 接口」;
782
+ * 若取消的正是**当前这个 AI 所用的应用**(`apps list` 里该行 `is_current_cli: true`,
783
+ 或 `client_id` 等于 `meta.client_id`):要**额外多说一句**「这会让我的登录失效,
784
+ 如果你还想让我继续帮你操作,需要重新授权一次」—— 否则用户下次发现"AI 忽然不能用了"会困惑。
785
+
786
+ ---
787
+
788
+ ### 7.5 用户说"帮我在站上发一篇文章 / 换个模板 / 传张图"
789
+
790
+ **这是 CMS 面**(客户站后台的同一批接口)。⛔ 不要用 `orders` / `sites` 那套平台接口去做内容。
791
+
792
+ ```bash
793
+ # ① 先定站点(只属于一个站的账号可以跳过;多站必须先选,否则会报 cms_site_required)
794
+ npx -y @wkgeo/cli@latest sites list # 默认只列我名下的站(含仅 CMS 的)
795
+ npx -y @wkgeo/cli@latest site use 8f3c1a2e-4b5d-4f6a-8b7c-9d0e1f2a3b4c # 或 www.example.com
796
+ npx -y @wkgeo/cli@latest site use --json # 看当前选中的是哪个站
797
+
798
+ # ② 看结构(栏目 = 导航;内容挂在栏目下)
799
+ npx -y @wkgeo/cli@latest categories list --json # 读 data.rows[].id / name / path / kind / template_path
800
+
801
+ # ③ 写内容(默认草稿;--status published 就立刻在前台可见)
802
+ npx -y @wkgeo/cli@latest contents create --category 新闻 --title "公司参展 2026" \
803
+ --body "<p>正文…</p>" --status draft --json
804
+ # 读 data.content.id / status
805
+ # 正文较长时用 --body-file ./article.html(避免命令行转义地狱)
806
+ # 自定义字段用 --ext '{"型号":"X1"}'(键就是后台「字段管理」里的键)
807
+
808
+ # ④ 传图(三步:签名 → 直传 OSS → 登记;CLI 不碰 AK)
809
+ npx -y @wkgeo/cli@latest assets upload ./banner.jpg --json # 读 data.asset.id
810
+ npx -y @wkgeo/cli@latest contents update <内容ID> --cover <素材ID> --json
811
+
812
+ # ⑤ 改版式(模板是整段 html;改了先备份)
813
+ npx -y @wkgeo/cli@latest templates list --json # 读 data.files[].path
814
+ npx -y @wkgeo/cli@latest templates get index.html > index.html # 人类模式直出源码(备份)
815
+ npx -y @wkgeo/cli@latest templates save index.html --file ./index.html --json
816
+ npx -y @wkgeo/cli@latest categories bind-template /about/ about.html --json
817
+
818
+ # ⑥ 发布(0.5.0 起是真发布:先 dry-run 看量,再 --confirm 真发)
819
+ # ⚠️ 0.5.0 的 --confirm 有 bug:发布已提交成功、轮询时崩 `ctx.sleep is not a function`(exit 1)
820
+ # —— 0.5.1 已修。所以务必 `@latest`(或显式 `@0.5.1` 及以上),否则站点可能已被发过一次。
821
+ npx -y @wkgeo/cli@latest publish --site <站点ID> --json # 只读:算出会发多少页
822
+ npx -y @wkgeo/cli@latest publish --site <站点ID> --confirm --json # 真发,轮询到终态
823
+ ```
824
+
825
+ **怎么把这些命令的失败讲给用户**(`--json` 的 `error.kind`):
826
+
827
+ | kind | 真实含义 | 对用户怎么说 |
828
+ |---|---|---|
829
+ | `cms_site_required` | 他有多个站点,得说清是哪个 | "你的账号有多个站,这次要改哪一个?" |
830
+ | `cms_auth` | 令牌没被 CMS 接受(多半过期/吊销;旧部署才可能是"没启用 CLI 认证") | "内容后台说我的登录失效了,我帮你重新授权一次"(跑 `login`) |
831
+ | `cms_not_member` | 不是这个站的成员 / 站点 id 不对 | "这个站我没有权限,帮我确认一下是哪个站?" |
832
+ | `cms_readonly` | 他的站点角色是只读 | "你在这个站是只读权限,要改成能编辑得找站长加一下" |
833
+ | `cms_scope` | 令牌能力不够(如模板保存要 `template:write`) | "这个操作需要更高的授权范围,得重新授权一次(或让管理员放开)" |
834
+ | `cms_unavailable` | CMS 地址不通 / 云函数没部署 | "内容后台暂时连不上,可能要等运维部署" |
835
+ | `not_deployed` | 服务端版本落后(没有这个动作) | "后台那边还没更新到这个功能,稍后再试" |
836
+
837
+ **铁律(CMS 面)**:
838
+
839
+ 1. **先 `site use` 或 `--site`** —— 改错站的代价比多问一句高得多;
840
+ 2. **写内容默认草稿**(`--status draft`),用户明确说"发出去"才用 `published`;
841
+ 3. **不要顺手删**:`contents delete` / `categories delete` 前必须让用户确认对象(标题 + 栏目);
842
+ 4. **单页栏目**(`kind=page`)的内容只能改不能建;用户要"加一页"= 加子栏目,不是建内容;
843
+ 5. `import`(老站导入)**默认 dry-run**、且需要运维权限 —— 不要对普通客户承诺"我能直接导"。
844
+
845
+ ---
846
+
847
+ ### 7.6 用户说"让我本机的大模型看看这个站"
848
+
849
+ **CLI 可以接本地大模型,详见 [`../docs/CLI-本地大模型接入.md`](../docs/CLI-本地大模型接入.md)。**
850
+
851
+ ```bash
852
+ npx -y @wkgeo/cli@latest ai ping --json # ① 探本机端点(Ollama 11434 / LM Studio 1234)
853
+ npx -y @wkgeo/cli@latest ai ask "栏目结构有没有重复/空栏目?" --site <站点ID> --json
854
+ npx -y @wkgeo/cli@latest context export --format md --out ./site-context.md --site <站点ID> --json
855
+ ```
856
+
857
+ * 只连 `localhost` / `127.0.0.1` / `[::1]`;要连远程必须显式 `ai.allowRemote=true`(CLI 会警告)。
858
+ * 数据域白名单 10 个:`site,overview,categories,contents,plugins,forms,publish` 默认开;`orders` 要 `--context orders` + `ai.allowOrders=true`;**`wallet` / `users` 硬禁**,别答应。
859
+ * 导出物/回答里**不含**手机号、邮箱、IP、UA、订单号、密钥、OSS 签名 URL(`maskPii` 统一处理);日志只记元信息,不记 prompt 与回答。
860
+ * 用户问"能不能把站上数据发给 ChatGPT/云端模型"→ 先说不:CLI 只保证本机模型这条路,外发要用户自己拿 `context export` 的文件去传。
861
+
862
+ ---
863
+
864
+
865
+ ## 8. 安全(**必须遵守**)
866
+
867
+ 1. **绝不打印/转述令牌**:不要 `cat ~/.wkongai/credentials.json`,不要把它放进任何请求体或日志。
868
+ 只需要账号标识时用 `whoami`(CLI 保证只输出账号标识)。
869
+ 2. **凭据文件等同密码**:不要复制到别处、不要上传、不要提交到仓库。
870
+ 3. **回调只监听 `127.0.0.1`**(不要改 `--callback-host` 绑 `0.0.0.0`,那会把授权码暴露给同网段)。
871
+ 4. **不要绕过安全边界**:不要为了"退款/改价/提权"去想办法伪造 step-up;
872
+ 那些动作**只能由人在网页后台完成**。
873
+ 5. **不要发起真实扣款**:`login`/`wallet recharge` 只创建订单/链接;
874
+ 所有"付款"都必须由用户在**我们网站的收银台页面**用微信完成。自动化测试里**绝不**走真钱路径。
875
+ 6. **收银台是我们自己的页面**:`wallet recharge` 的正确交接物是 `pay_url`
876
+ (`https://pay.wkgeo.com/?order_id=…`),不是 `code_url`。
877
+ 不要在本地自己画一个二维码页面让用户扫 —— 那是被明确否掉的做法。
878
+ 7. **限流是保护,不是故障**:429 时按 `retry_after` 退避;**不要**用重新登录或换令牌来"绕过"限流。
879
+ 8. 遇到 `client_secret`、`authorization_code`、`access_token` 之类的字段:
880
+ 它们是凭据,**不要**记录到对话/文件里。
881
+
882
+ ---
883
+
884
+ ## 9. 常见坑速查
885
+
886
+ | 现象 | 原因 | 处理 |
887
+ | --- | --- | --- |
888
+ | `whoami` 返回 exit 3 | 还没登录 / 令牌过期 / 被吊销 | 跑 `login`,把网址给用户点同意 |
889
+ | 浏览器授权后显示"无法访问此网站" | 那一刻本机没有 CLI 在监听(login 被 Ctrl+C 或已退出);**或代理接管了 127.0.0.1** | 重新 `login`(开着代理时 CLI 会自动改设备码);并**保持它在前台**直到点完「同意」 |
890
+ | `login` 等到超时(`kind:"timeout"`) | 用户没点完,**或代理把回调吃掉了** | ★ 0.2.2 起超时**不会**自动改设备码:看 `hint` 与 `meta.proxy_warning`。若用户确认本地读不了回调,让他**显式**加 `--device` 重跑;若检测到代理,CLI 默认**已经**在第一跳直接改设备码了(除非加了 `--no-auto-device`) |
891
+ | 事件流第一行是 `awaiting_user` 而不是 `awaiting_callback` | 只有两种可能:**检测到系统代理**(CLI 直接改设备码;绕过列表写了 127.* 也照样改)或用户显式 `--device` | 按 §5.3 把 `paste_text` 转述给用户;想强制回调加 `--no-auto-device`(CLI 会警告风险) |
892
+ | 事件流是 `awaiting_callback`,然后 `data.auto_device.reason:"callback_first_wait"` | ★ **0.2.2 起只可能**是用户/调用方**显式**写了 `--callback-first-wait`(默认关闭):首轮等待没收到回调 → CLI 并发改设备码(**本地回调监听同时保留**) | 正常自愈;如实告诉用户"已同时改用设备码,两条路哪条先成功算哪条,不用重来" |
893
+ | 用户说「我**没开代理**,为什么变成设备码了」 | ★ 0.2.2 起默认就是浏览器回调,正常情况下**不会**再发生。若真出现,只可能是:① `proxy_warning.detected:true`(真探到了系统代理);② `reason:"callback_listen_failed"`(本地端口起不来);③ 用户自己显式 `--device` / `--callback-first-wait` | 按 `data.auto_device.reason` 如实解释;先看 `data.proxy_warning.detected`(`config --json` 能看来源) |
894
+ | 用户随后才点【同意授权】→ 浏览器显示 **ERR_CONNECTION_REFUSED** | ★ 2026-10-03 已修:显式首轮等待切设备码时**不再关掉**本地回调监听(旧版一关就是这个报错)。若仍出现,说明 CLI 进程已经退出(Ctrl+C / 终端关掉了) | 让用户直接在**这一次**的浏览器页面上点同意即可(监听还在),或重跑 `login`;不要让他以为授权失败 |
895
+ | `login --device-continue` 报 `kind:"expired"` | 短码过期(默认 10 分钟)或已被换过票 | 重新 `login --device --no-wait` 申请新短码;**别**反复续跑 |
896
+ | 下单直接返回 `paid:true` | 服务端设计:下单时余额足够就直接扣款并履约 | 这是正常的"钱包支付";用 `wallet` 复核余额 |
897
+ | `sites create` 报 400 参数错误 | 客户层已删,归属无需指定;400 只剩参数问题(名称/区域等) | 按错误提示补参数 |
898
+ | `sites create` 回 `data.short_domain.kv_written:false`(stderr 也有「短域解析未写入」) | 短域没写进 KV,访问短域会 403/404;CLI **没有** `domain repair` 命令(后端也无等价 OAuth 动作) | **别撒谎说"能访问"**:如实告诉用户短域暂不可用,用 `sites get <站点ID>` 复核 `prefix_host` / `prefix_kv_written`;`null` = 旧接口没回这个字段,让用户直接打开短域试 |
899
+ | `domain bind` 回 exit 1 +「域名开通通道暂不可用(平台侧未开),本次未写入,可直接重试」 | 上游 `wkgeo-domain` 的内部通道没开(部署侧 `DOMAIN_INTERNAL_CHANNEL_ENABLED=false`)⇒ 服务端 503 | **如实说"没绑上、没写入"**,别当成成功;平台开通后**直接重跑同一条命令**(`domain bind` 幂等),也可以先用 `domain status` 看现状 |
900
+ | `domain bind` 回 `platform_owned_domain`(exit 3) | 想绑平台自有域名(`wkgeo.com` 等) | 换用户自己的域名;平台自有域只有超管后台能配,别找绕过 |
901
+ | `domain bind` 回 `domain_already_bound`(exit 1) | 站点已绑了**别的**域名 | 换域要先去会员中心解绑(短信二次验证,CLI 不支持);不要反复重试 bind |
902
+ | 用户问「怎么解绑域名 / 怎么修复解析」 | `/cli` 动作面**没有** unbind / repair:解绑只有 `releaseSiteDomain`(OAuth 下 428 短信二次验证)、`retrySiteProvision` 语义是"重跑开通" | 解绑 → 引导去会员中心;重试开通 → 再跑一次 `domain bind`(幂等);查现状 → `domain status` / `domain records` / `domain dns` |
903
+ | `auth status` 的 `data.action_surface.consistent:false` | 后端 `action_total` 与明细加总对不上(服务端刚改过动作表) | 以 `data.action_lists` 明细为准,把差异报给服务端;**不要**据此说"能力丢了" |
904
+ | `domain remind` 回 `kind:"domain_remind_forbidden"`(exit 3) | 该命令要**平台管理员**(站点系统管理员不够) | 让平台管理员跑,或到超管后台看;**不要**反复重试 |
905
+ | `domain check` 回 429 / `retry_after` | 查域名限流 30 次/分 | 等 `retry_after` 秒再查;一次最多 10 个域名 |
906
+ | 用户问「域名怎么还不生效 / 要加什么解析」 | 需要看开通状态与记录 | 依次 `domain status`(状态 + 客户待办)→ `domain dns`(RR/Type/Value 照抄给用户,**CLI 不会替他加**)→ 加完再 `domain status` 复核 |
907
+ | CMS 命令报 `cms_auth`(401) | 令牌失效(过期/吊销/客户端停用);旧部署才可能是"没启用 CLI 认证桥" | 先 `wkgeo login` 重新授权一次;仍 401 再让管理员确认服务是否为新版(**别**反复 login) |
908
+ | CMS 命令报 `cms_site_required` | 账号有多个站点、没指定 | `wkgeo site use <站点ID>` 或加 `--site <站点ID>` |
909
+ | `--site` 写了域名没生效 | 后端只按**站点 id** 查,域名会被当成"没指定" | 先 `wkgeo site use <域名>` 解析成 id(CLI 已在本地挡住这种写法) |
910
+ | `templates save` / `assets list` 报 403 `cms_scope` | 令牌是**升级前签的**,缺 `template:*` / `attachment:*`(客户端与默认 scope 现已放开) | 让用户重新授权一次:`login`(默认就带全部所需能力);**不是** bug,也别改用别的通道 |
911
+ | `assets upload` 报 403 | 令牌缺 `attachment:write`(或站点角色只读) | 看 `error.kind`:`cms_scope` → 重新授权;`cms_readonly` → 找 owner 提权 |
912
+ | `import` 报 `import_unavailable` | 本机没有 `tencent/cloudbase/import-site.mjs`(npx 装的包里没有它) | 只能在本仓库机器上跑;**不要**对客户承诺"我能直接导" |
913
+ | 429 | 调用过于频繁 | 等 `retry_after` 秒;**不要**重新授权 |
914
+ | `apps list` 报"未部署" | 该环境的 data 云函数还没发版(**线上已发版并实测过**,见 README §9) | 告诉用户"这是服务端缺口",不要反复重试;`logout` 仍可清理本地登录态 |
915
+ | `skill` 报「当前安装包里没有手册文件(SKILL.md)」 | 跑的是**被裁剪的包**或只拷了 `lib/` 的开发目录(正常 npm 包一定有) | 换 `npx -y @wkgeo/cli@latest skill`;这不是命令用错了(`error.kind="missing_skill"`,退出码 1) |
916
+ | `publish --confirm` 输出 `{"kind":"internal","message":"ctx.sleep is not a function"}`(exit 1) | **0.5.0 的真 bug**:发布其实**已经提交成功**,只是轮询阶段的 `ctx.sleep` 没有默认实现 | 升级到 **≥ 0.5.1** 再跑(`npx -y @wkgeo/cli@latest`);**先**看 `publish status --json` 确认那次到底发没发,别急着重发 |
917
+ | 想升级 CLI | 全局安装不会自动升级 | 用 `npx -y @wkgeo/cli@latest`,或 `npm i -g @wkgeo/cli@latest` |
918
+
919
+ ## 云端能力(阿里云侧由云函数执行,CLI 不持有 AK)
920
+
921
+ 绑域名 / 新建 ESA 站点 / 传 OSS / 发布边缘函数 / 查配额这些**阿里云侧操作**,
922
+ 一律通过云端管理接口(FC 函数 `wkgeo-admin`)完成 —— **CLI 与桌面都不持有阿里云 AK**。
923
+
924
+ - 能力清单、权限范围(scope)、请求头要求、curl 示例、已知坑:`aliyun/fc/wkgeo-admin/README.md`
925
+ - 背景与验证记录:原《建站·云端管理接口》已归档(见 `.tmp-build/docs-archive-20261022.zip`)
926
+ - 地址 `https://wkgeo-admin-nyvdudigpb.cn-shanghai.fcapp.run`;必带 `Authorization: Bearer <平台签发的 JWT>` 与 `Date`(RFC1123)
927
+ - scope:`read` / `domain:bind` / `site:create` / `kv:write` / `oss:write` / `routine:deploy`