wkgeo-cli 0.2.0 → 0.2.2

package/SKILL.md

@@ -23,6 +23,10 @@ version: 0.2.0
 * 用户说"**帮我下单**"/"买加量包"/"扩容空间"/"买流量" → `products list` → `orders create`
 * 用户说"**用钱包付**"/"余额支付"/"帮我付钱" → `orders create`（余额够会**当场付清**）+ `wallet` 复核
 * 用户说"**充值**"/"充 100 块" → `wallet recharge`（下单后**自动打开我们网站的收银台页面**，用户在那里扫码支付）
+* 用户说"**充值**"但**没说金额**、或说"**我自己选金额**"/"给我个充值链接" → `wallet recharge-link`
+  （生成**独立充值页**链接：`https://pay.wkgeo.com/recharge/?ticket=…`，用户在网页上自己选金额
+  —— ¥10 / ¥20 快捷，或自定义，**最低 ¥9.90、不设上限** —— 然后扫码支付；**不需要登录会员中心**。
+  默认**不**弹浏览器：把 `data.pay_url` 原样交给用户即可。⛔ 不要用它代替用户付款。）
 * 用户说"**查余额**"/"我的钱包"/"账单流水" → `wallet` / `wallet txns`
 * 用户说"**我的订单**"/"订单状态" → `orders list` / `orders get` / `orders check`
 * 用户说"**我授权过哪些应用**"/"取消某个应用的授权" → `apps list` / `apps revoke`
@@ -103,7 +107,7 @@ npx -y wkgeo-cli@latest skill > SKILL.md   # 直接落一份到本地，离线
 
 | 命令 | 作用 | 关键参数 |
 | --- | --- | --- |
-| `login` | 授权一次（令牌存本地 30 天） | `--device`、`--no-wait`、`--device-continue`、`--no-auto-device`、`--callback-first-wait <秒>`、`--no-browser`、`--open-browser`、`--scope`、`--timeout <秒>` |
+| `login` | 授权一次（令牌存本地 30 天；**默认浏览器回调**，设备码仅兜底） | `--device`、`--no-wait`、`--device-continue`、`--no-auto-device`、`--callback-first-wait <秒>`（可选，默认关闭）、`--no-browser`、`--open-browser`、`--scope`、`--timeout <秒>` |
 | `whoami` | 当前是谁（账号标识） | `--verbose` |
 | `logout` | 退出（删本地凭据 + 服务端吊销） | `--local-only` |
 | `config` | 生效配置 / 登录状态 | — |
@@ -113,6 +117,7 @@ npx -y wkgeo-cli@latest skill > SKILL.md   # 直接落一份到本地，离线
 | `wallet` | 余额 + 最近流水 | `--limit` `--entitlements` |
 | `wallet txns` | 钱包流水 | `--limit` |
 | `wallet recharge` | 充值下单，**并打开我们网站的收银台页面**扫码支付（**不扣款**） | `--amount-cents`（分，必填）、`--no-browser`、`--open-browser`、`--dry-run` |
+| `wallet recharge-link` | 生成**独立充值页**链接（用户在网页上**自己选金额**并扫码支付；**不扣款**、不建单） | `--open-browser`（默认**不**弹）、`--no-browser` |
 | `products list` | 能买什么 | — |
 | `orders create` | 下单（余额够**当场付清**） | `--product <代码>` `--units <份数>`（或 `--quota <键>` `--amount <数量>`）`--allow-wechat` |
 | `orders check` | 查支付结果 + 最新余额 | `<订单ID>` |
@@ -121,8 +126,21 @@ npx -y wkgeo-cli@latest skill > SKILL.md   # 直接落一份到本地，离线
 | `orders list` | 我的订单 | `--limit` `--offset` `--status` |
 | `apps list` | 我授权过的应用 | — |
 | `apps revoke` | 一键吊销某应用授权（令牌立即失效） | `<client_id>` |
+| `site use` | **选中要操作的站点**（存本地，之后的 CMS 命令默认用它；不带参数 = 看当前） | `<站点ID或域名>`、`--clear` |
+| `categories list/get/create/update/delete` | 栏目：列表 / 详情 / 新建 / 改 / 删 | 见 §7.5 |
+| `categories bind-template` | 给栏目绑定模板 html（`--clear` 解绑） | `<栏目>` `<模板文件>`、`--clear` |
+| `contents list/get/create/update/delete` | 内容：列表 / 详情 / 新建 / 改 / 删 | 见 §7.5 |
+| `assets list` / `assets upload` | 素材：列表 / 上传（签名 → 直传 OSS → 登记） | `assets upload <文件>`、`--name` |
+| `templates list/get/save` | 模板：清单 / 看源码（直出）/ 保存 | `templates get <文件>`、`templates save <文件> --file <本地>` |
+| `publish` | **看发布状态**（前台按需渲染：`published` 即上线，没有额外发布步骤） | — |
+| `import` | 老站导入（**默认 dry-run**；走本机运维脚本，**需运维权限**） | `--url`（必填）、`--apply`、`--site` |
 | `skill` | **打印给 AI 端的操作手册**（本文件原文，随包分发） | `--json`（默认纯文本原文；不受"非终端自动 JSON"影响） |
 
+> CMS 命令（`categories` / `contents` / `assets` / `templates` / `publish`）都要先确定站点：
+> `--site <站点ID>` > 环境变量 `WKONGAI_SITE` > 本地 `wkgeo site use`
+> > **都没有时不带站点头**（服务端用你唯一的成员站；多站会报 `cms_site_required` 让你指定）。
+> ⚠️ `--site` **只认 uuid**；域名先 `wkgeo site use <域名>` 解析。
+
 ### 示例：成功
 
 ```bash
@@ -173,6 +191,13 @@ $ npx -y wkgeo-cli@latest orders create --product storage_gb --units 10
 
 ## 5. 授权流程（**必须让用户动手的那一步**）
 
+> ★ **2026-10-18 域名统一到路径**：授权站 canonical 从 `https://oauth.wkgeo.com/` 改成
+> **`https://wkgeo.com/oauth/`**（同意页 `/oauth/authorize/`、设备码页 `/oauth/device/`）。
+> 老子域**继续可用**（老板要求并存）；CLI 以 `WKONGAI_OAUTH_WEB_BASE` 为 canonical，
+> 服务端 metadata 只提供路径 —— 所以**服务端还没部署新地址时，CLI 打印的也是新地址**。
+> 回滚一条环境变量即可：`WKONGAI_OAUTH_WEB_BASE=https://oauth.wkgeo.com`（不用改代码）。
+> ⚠️ 给用户看的地址**原样转述**，别自己把 `wkgeo.com/oauth` 改回 `oauth.wkgeo.com` 去"纠错"。
+
 ### 5.1 本地回调模式（默认）
 
 ```bash
@@ -184,11 +209,15 @@ npx -y wkgeo-cli@latest login --json --timeout 500ms   # 也可以显式写毫
 
 它会**阻塞**（默认最多 5 分钟）并输出 JSONL：
 
+> ★ **0.2.2 起：默认就是这条回调**，等多久都**不会**自动改成设备码；整段超时只报
+> `kind:"timeout"`（并在 hint 里给出"显式改用 `--device`"的下一步）。设备码只在
+> ① 显式 `--device` ② 检测到系统代理 ③ 本地回调端口真的起不来 时出现（见 §5.3 / §5.4）。
+
 ```jsonc
 // 第一行 —— 拿到它就应该**立刻**把网址交给用户（不要等命令结束！）
 // ⚠️ `authorize/` 的**尾斜杠不能丢**：它是托管侧 302（会丢掉全部 query）的分界线
 {"ok":true,"command":"login","mode":"callback","stage":"awaiting_callback",
- "authorization_url":"https://oauth.wkgeo.com/oauth/authorize/?client_id=wkgeo-cli&…",
+ "authorization_url":"https://wkgeo.com/oauth/authorize/?client_id=wkgeo-cli&…",
  "redirect_uri":"http://127.0.0.1:53682/callback","scope":"site:read site:write billing:self",
  "timeout_ms":300000,
  "user_action_required":"请让用户在浏览器中打开上面的 authorization_url，登录并点「同意」"}
@@ -239,7 +268,14 @@ npx -y wkgeo-cli@latest login --json --timeout 500ms   # 也可以显式写毫
 * 用户也可以在网页「我已授权的应用」里一键吊销（吊销后 CLI 会收到 40102）。
 * 🔒 不要把这个文件内容读出来放进任何输出/日志/第三方请求里。
 
-### 5.3 设备码模式（`login --device`）—— **代理/远程机器的首选**
+### 5.3 设备码模式（`login --device`）—— **本地读不了回调 / 代理 / 远程机器时的兜底**
+
+> ★ **默认不是设备码**：`wkgeo login` 默认走浏览器回调（授权页 + 本地 `127.0.0.1` 回调，见 §5.1）。
+> 只有这几种情况才用设备码：
+> 1. 用户**显式** `--device` / `--no-wait` / `--device-continue`；
+> 2. **检测到系统代理**（CLI 自动改道，见 §5.4；`--no-auto-device` 可关）；
+> 3. 本地回调端口**真的起不来**（CLI 自动兜底，`reason:"callback_listen_failed"`；`--no-auto-device` 可关）。
+> **等待超时不会**自动改设备码（0.2.2 起）。
 
 **什么时候用它**（不用问用户，直接选它就行）：
 
@@ -254,7 +290,7 @@ npx -y wkgeo-cli@latest login --json --timeout 500ms   # 也可以显式写毫
 # ① 交互式终端 / 你有长超时能力：一口气跑完（阻塞，最多 expires_in 秒）
 npx -y wkgeo-cli@latest login --device --json
 #    → {"stage":"awaiting_user","user_code":"ABCD-1234",
-#       "verification_uri":"https://oauth.wkgeo.com/oauth/device/",
+#       "verification_uri":"https://wkgeo.com/oauth/device/",
 #       "verification_uri_complete":"…/?user_code=ABCD-1234","open_url":"…",
 #       "expires_in":600,"interval":5,"paste_text":"请打开 … 并完成「同意授权」（短码：ABCD-1234）。",
 #       "user_action_required":"请让用户访问 … 并输入短码 ABCD-1234"}
@@ -312,7 +348,7 @@ npx -y wkgeo-cli@latest login --device-continue --json      # 用户说"点好
 **机理**：回调要求**浏览器**访问 `http://127.0.0.1:<端口>/callback?code=…`；
 全局/系统代理若没把回环地址排除，这条请求会被代理接管 → CLI 收不到 code。
 
-**CLI 已经自己处理好了**（2026-10-02 第二版加固，**默认开**）：
+**CLI 已经自己处理好了**（2026-10-02 第二版加固 + 2026-10-21 默认模式调整）：
 
 * ★ **只要检测到"生效中的系统代理"就直接改用设备码模式**（事件流里第一行就是
   `stage:"awaiting_user"`，而不是 `awaiting_callback`）；`data.auto_device.reason = "proxy_detected"`。
@@ -321,22 +357,22 @@ npx -y wkgeo-cli@latest login --device-continue --json      # 用户说"点好
   证据 `curl -x http://127.0.0.1:7890 http://127.0.0.1:1/x` → 502）。
   `proxy_warning.loopback_bypassed` / `risk` 现在**只是诊断字段**，不再代表"回调没问题"；
   `proxy_warning.loopback_bypass_trusted` 恒为 `false`。
-* ★ **回调模式首轮等待**（★ **只在检测到系统代理时才启用**，默认 **180 秒**；
-  `--callback-first-wait <秒>` / `WKONGAI_CALLBACK_FIRST_WAIT_MS` 可显式指定，
-  `0`/`off` 关闭）没等到回调 → **自动改用设备码继续**（`reason: "callback_first_wait"`），
-  用户不用再干等整段 `--timeout`；
-  ⚠️ **2026-10-03 修**：以前它**无条件**挂在 60 秒上，于是"用户读完授权页再点同意"经常超时，
-  明明没开代理也被切成设备码（老板真机原话：「现在变成设备码了，我们因为没有开任何VPN，
-  所以这个是不对的。」）。现在：**没有代理 → 不启用**（老实等满 `--timeout`），
-  用户显式指定时才照旧生效；`data.auto_device.reason == "callback_first_wait"`
-  **只可能**出现在有代理的机器上。
-  ⚠️ **切换时不再关掉本地回调监听**（同一次修复）：两条路**并存**，哪条先成功就用哪条 ——
+* ★★ **0.2.2 起：等待超时不再自动改设备码**（老板 2026-10-21 反馈）：
+  老板原话「默认的也不应该是设备授权，默认的就是那个传统的授权方式（浏览器打开授权页 +
+  本地 localhost 回调）。设备码是本地读不了/代理时才用的。」
+  ⇒ 没有代理时 `login` 会**一路等回调到 `--timeout`**（默认 300 秒），超时只报
+  `kind:"timeout"`，并在 `hint` 里给出"显式改用 `--device`"的下一步。
+  ⚠️ 历史行为（0.2.1 及更早）：有代理时"首轮等待 180 秒"到点会改设备码、整段超时也会改；
+  现在那个"首轮等待"**默认关闭**，只有用户**显式**写 `--callback-first-wait <秒>` /
+  `WKONGAI_CALLBACK_FIRST_WAIT_MS` 才启用（显式优先，`reason:"callback_first_wait"`）。
+  显式启用时仍然是**两条路并存**：本地回调监听继续保留，哪条先成功就用哪条 ——
   用户之后才点的那次【同意授权】照样能完成登录；旧逻辑在切换那一刻关了监听，用户随后点同意
-  只会看到 **ERR_CONNECTION_REFUSED**（真机截图见过的"无法访问此网站"）。
+  只会看到 **ERR_CONNECTION_REFUSED**（真机截图见过的"无法访问此网站"，2026-10-03 已修）。
   若设备码先成功，之后到达的回调会拿到一张「本次登录已经完成」的页面（不是错误页）；
   若回调先成功，设备码轮询会被停掉并说明（`ℹ️ 本地回调已经拿到令牌：设备码那条路已停止…`）。
-* 整段回调**超时**、或本地回环端口**起不来** → 同样自动改用设备码继续
-  （`reason: "callback_timeout"` / `"callback_listen_failed"`），**不会**直接失败退出；
+* 本地回环端口**真的起不来**（防火墙/安全软件/端口非法）→ 自动兜底设备码
+  （`reason: "callback_listen_failed"`），**不会**直接失败退出；
+  `--no-auto-device` 可关闭这个兜底（此时如实报 `kind:"listen"`）。
 * 换票失败 / 用户点了拒绝 → **不降级**（授权已经走到下一步了，别让用户白做一遍）；
 * 上述情况下，`meta.proxy_warning` / `data.proxy_warning` 都会告诉你原因与建议动作：
 
@@ -359,12 +395,18 @@ npx -y wkgeo-cli@latest login --device-continue --json      # 用户说"点好
 * 看到 `proxy_warning.callback_may_fail: true`：**不要**叫用户去改代理设置（很多用户不懂），
   直接按设备码流程走 —— CLI 通常已经自动切过去了；
   只有当用户明确说"我就想用浏览器回调"时，才把 `actions` 里第 2/3 条念给他；
-* 看到 `auto_device.applied: true`：可以在汇报里加一句
-  「检测到你开着代理，已自动改用设备码模式（不需要本地回调）」——如实说明，别隐瞒；
+* 看到 `auto_device.applied: true`：按 `reason` 如实说明，别隐瞒：
+  * `"proxy_detected"` → 「检测到你开着代理，已自动改用设备码模式（不需要本地回调）」；
+  * `"callback_listen_failed"` → 「本地回调端口起不来，已自动改用设备码模式继续」；
+  * `"callback_first_wait"` → **只可能**是用户自己显式开了 `--callback-first-wait`：
+    「等待到点没收到回调，已同时改用设备码（两条路哪条先成功算哪条）」。
+  * 没有 `auto_device`（`applied:false`）就是**默认的浏览器回调**，不要主动提设备码。
 * 想让 CLI **不要**自动改道（例如你确认回调一定通）：加 `--no-auto-device`，或设
   `WKONGAI_AUTO_DEVICE=0`。⚠️ 此时 CLI 会**打印警告**说"若代理接管 127.0.0.1，
-  点了【同意授权】也收不到结果"，并且**不会**再用首轮等待自愈 —— 尊重用户的选择，
-  但要**把这个风险如实转述**给他；
+  点了【同意授权】也收不到结果"，并且**不会**再用首轮等待自愈、端口起不来也**不兜底** ——
+  尊重用户的选择，但要**把这个风险如实转述**给他；
+* 用户只是**等得久**（没代理、也没报错）：**不要**自己改成设备码 —— 0.2.2 起默认就是回调，
+  等多久都不会自动变；要设备码必须**显式**加 `--device`（先问用户，别擅自换模式）；
 * 排障：`npx -y wkgeo-cli@latest config --json` 里有 `data.proxy` 与 `meta.proxy_warning`，
   是"用户机器上是不是代理挡了回调"的**唯一权威判断**（只读检测，不会改用户任何设置）。
 
@@ -450,6 +492,14 @@ Set-Content -LiteralPath "$env:USERPROFILE\.dsh\browser-open.txt" -Value "<完
 | `not_found` / `404` | 订单/站点/产品不存在 | 用 `orders list` / `products list` 重新确认 ID |
 | `bad_request` / `400` | 参数不对 | 按 `message` 修正参数；别硬改着重试 |
 | `not_deployed` | 该接口服务端还没发布 | 告诉用户"这是服务端缺口"，不要反复重试 |
+| `cms_auth` / `401`（CMS 命令） | CMS 没接受 Bearer 令牌：通常是**令牌无效**（过期/吊销/客户端停用）；只有旧部署才会是"没启用 CLI 认证" | 先 `wkgeo login` 重新授权一次（正常环境一定能解决）；仍不行再用 `whoami` 判断是否服务端旧部署，让管理员确认（**不要**反复登录十几次） |
+| `cms_site_required` / `400` | 账号有多个站点，没指定 | 先问用户是哪个站，再 `site use <站点ID>` 或 `--site <站点ID>` |
+| `cms_not_member` / `403` | 不是该站成员 / 站点 id 不对 | 让用户确认站点（`site use` 重选）；协作站要 owner 先加成员 |
+| `cms_readonly` / `403` | 站点角色是 viewer（只读） | 让 owner 在后台「用户与角色」里升为 editor；**不要**换令牌硬试 |
+| `cms_scope` / `403` | 令牌 scope 不够（如 `template:write`） | 需要更高授权：`login --scope "<原有 + 缺的>"`；已知官方 CLI 客户端没放开 `template:write` / `attachment:delete` |
+| `cms_unavailable` | CMS 地址不通 / 云函数没部署 / 返回不是 JSON | 检查 `wkgeo config` 的 `cms_base`；多半是服务端没部署，告诉用户"后台暂时连不上" |
+| `import_unavailable` | 本机没有 `tencent/cloudbase/import-site.mjs` | 告诉用户"老站导入需要运维权限/本仓库环境"，**不要**承诺普通客户能用 |
+| `import_failed` | 导入脚本非 0 退出 | 念 `hint` 与日志尾巴；dry-run 失败不动库，可安全重试 |
 | `missing_skill` | `skill` 在本包里找不到 `SKILL.md`（包被裁剪/只拷了 `lib/`） | 换官方包 `npx -y wkgeo-cli@latest skill`；**不是**命令用错了，别让用户去排查 |
 | `server` / `5xx` | 服务端错误 | 保留原文告知用户，可稍后重试 |
 | `network` | 连不上/超时 | 检查网络后重试；`message` 里是原始错误（如 `getaddrinfo ENOTFOUND`） |
@@ -493,7 +543,7 @@ npx -y wkgeo-cli@latest wallet txns --limit 3
 ```bash
 npx -y wkgeo-cli@latest wallet recharge --dry-run --amount-cents 10000   # 先彩排，确认金额
 npx -y wkgeo-cli@latest wallet recharge --amount-cents 10000             # 生成待支付订单，并把收银台地址交出来（不扣款）
-#   ★ 读 data.pay_url —— 这是**我们网站的收银台页面**（https://pay.wkgeo.com/pay/?order_id=…&token=…）。
+#   ★ 读 data.pay_url —— 这是**我们网站的收银台页面**（https://pay.wkgeo.com/?order_id=…&token=…）。
 #     ⚠️ **不要把 data.code_url 当成主流程丢给用户自己想办法**（那是微信内部支付链接，
 #        手机直接扫不了；终端二维码只是"网页打不开"时的兜底）。
 #     ★ `token=` 是服务端在下单那一刻签发的**订单支付令牌**（只对这一单有效）：
@@ -527,6 +577,29 @@ npx -y wkgeo-cli@latest orders check <order_id>                          # 用
 ⚠️ 打开 `pay_url` 的方式见 **§5.5**：CLI **默认就会尝试弹系统浏览器**（老板最终拍板走传统路线）；
    只有它**没打开成功**时，才考虑可选地在客户端**内置浏览器 / 侧边面板**里打开。
 
+#### 7.2.1 另一种：**让用户自己选金额**（`wallet recharge-link`，独立充值页）
+
+用户**没给金额**、或说"我自己选"/"给我个充值链接"时用它。它**不建单、不定金额**，
+只换一张**一次性 ticket** 并给出链接：
+
+```bash
+npx -y wkgeo-cli@latest wallet recharge-link           # 默认不弹浏览器：交接物就是链接本身
+#   ★ 读 data.pay_url —— 形如 https://pay.wkgeo.com/recharge/?ticket=…
+#     把它**原样**发给用户（或做成可点的链接）。他在那一页上：
+#       选金额（¥10 / ¥20 快捷，或自定义；最低 ¥9.90、**不设上限**）→ 提交 → 微信扫码支付。
+#     ⚠️ **不需要登录会员中心** —— 凭证就是地址里的 ticket，整条链路与登录态无关。
+#   ★ data.paste_text 是"照着念"的一句话（含完整地址），直接转述，别自己组织语言。
+#   ★ 有效期只有 10 分钟、且**用掉即失效**（一次性）：过期/已用过时页面会明确提示"请重新获取"，
+#     这时**重新跑一次本命令**拿一条新链接即可（不要反复让用户刷新旧链接）。
+#   ★ 默认**不**打开浏览器（这条命令通常跑在服务器/容器里，且交接物是链接）；
+#     确实要在本机弹出时加 --open-browser；--no-browser 优先级最高。
+#   ★ ticket 只是"建一笔充值单"的窄凭证：⛔ 不要把它当登录凭据、不要拿它去调别的 action。
+npx -y wkgeo-cli@latest orders check <order_id>        # 用户说付完了再查（order_id 从他那句"付完了"对应的单拿）
+```
+
+⚠️ **AI 永远不要替用户"确认支付成功"**：只能查。查不到就是没付。
+⚠️ 别把 `ticket` 单独展示成"验证码"念出来：它是**链接的一部分**，原样交付整条链接即可。
+
 ### 7.3 用户说"查一下我的余额和订单"
 
 ```bash
@@ -559,6 +632,61 @@ npx -y wkgeo-cli@latest apps revoke <client_id>      # 该应用所有令牌立
 
 ---
 
+### 7.5 用户说"帮我在站上发一篇文章 / 换个模板 / 传张图"
+
+**这是 CMS 面**（客户站后台的同一批接口）。⛔ 不要用 `orders` / `sites` 那套平台接口去做内容。
+
+```bash
+# ① 先定站点（只属于一个站的账号可以跳过；多站必须先选，否则会报 cms_site_required）
+npx -y wkgeo-cli@latest site use 8f3c1a2e-4b5d-4f6a-8b7c-9d0e1f2a3b4c   # 或 www.example.com
+npx -y wkgeo-cli@latest site use --json          # 看当前选中的是哪个站
+
+# ② 看结构（栏目 = 导航；内容挂在栏目下）
+npx -y wkgeo-cli@latest categories list --json   # 读 data.rows[].id / name / path / kind / template_path
+
+# ③ 写内容（默认草稿；--status published 就立刻在前台可见）
+npx -y wkgeo-cli@latest contents create --category 新闻 --title "公司参展 2026" \
+  --body "<p>正文…</p>" --status draft --json
+#   读 data.content.id / status
+#   正文较长时用 --body-file ./article.html（避免命令行转义地狱）
+#   自定义字段用 --ext '{"型号":"X1"}'（键就是后台「字段管理」里的键）
+
+# ④ 传图（三步：签名 → 直传 OSS → 登记；CLI 不碰 AK）
+npx -y wkgeo-cli@latest assets upload ./banner.jpg --json     # 读 data.asset.id
+npx -y wkgeo-cli@latest contents update <内容ID> --cover <素材ID> --json
+
+# ⑤ 改版式（模板是整段 html；改了先备份）
+npx -y wkgeo-cli@latest templates list --json                 # 读 data.files[].path
+npx -y wkgeo-cli@latest templates get index.html > index.html # 人类模式直出源码（备份）
+npx -y wkgeo-cli@latest templates save index.html --file ./index.html --json
+npx -y wkgeo-cli@latest categories bind-template /about/ about.html --json
+
+# ⑥ 看发布状态（前台按需渲染：published 即上线，**没有**"发布"这一步）
+npx -y wkgeo-cli@latest publish --json
+```
+
+**怎么把这些命令的失败讲给用户**（`--json` 的 `error.kind`）：
+
+| kind | 真实含义 | 对用户怎么说 |
+|---|---|---|
+| `cms_site_required` | 他有多个站点，得说清是哪个 | "你的账号有多个站，这次要改哪一个？" |
+| `cms_auth` | 令牌没被 CMS 接受（多半过期/吊销；旧部署才可能是"没启用 CLI 认证"） | "内容后台说我的登录失效了，我帮你重新授权一次"（跑 `login`） |
+| `cms_not_member` | 不是这个站的成员 / 站点 id 不对 | "这个站我没有权限，帮我确认一下是哪个站？" |
+| `cms_readonly` | 他的站点角色是只读 | "你在这个站是只读权限，要改成能编辑得找站长加一下" |
+| `cms_scope` | 令牌能力不够（如模板保存要 `template:write`） | "这个操作需要更高的授权范围，得重新授权一次（或让管理员放开）" |
+| `cms_unavailable` | CMS 地址不通 / 云函数没部署 | "内容后台暂时连不上，可能要等运维部署" |
+| `not_deployed` | 服务端版本落后（没有这个动作） | "后台那边还没更新到这个功能，稍后再试" |
+
+**铁律（CMS 面）**：
+
+1. **先 `site use` 或 `--site`** —— 改错站的代价比多问一句高得多；
+2. **写内容默认草稿**（`--status draft`），用户明确说"发出去"才用 `published`；
+3. **不要顺手删**：`contents delete` / `categories delete` 前必须让用户确认对象（标题 + 栏目）；
+4. **单页栏目**（`kind=page`）的内容只能改不能建；用户要"加一页"= 加子栏目，不是建内容；
+5. `import`（老站导入）**默认 dry-run**、且需要运维权限 —— 不要对普通客户承诺"我能直接导"。
+
+---
+
 ## 8. 安全（**必须遵守**）
 
 1. **绝不打印/转述令牌**：不要 `cat ~/.wkongai/credentials.json`，不要把它放进任何请求体或日志。
@@ -570,7 +698,7 @@ npx -y wkgeo-cli@latest apps revoke <client_id>      # 该应用所有令牌立
 5. **不要发起真实扣款**：`login`/`wallet recharge` 只创建订单/链接；
    所有"付款"都必须由用户在**我们网站的收银台页面**用微信完成。自动化测试里**绝不**走真钱路径。
 6. **收银台是我们自己的页面**：`wallet recharge` 的正确交接物是 `pay_url`
-   （`https://pay.wkgeo.com/pay/?order_id=…`），不是 `code_url`。
+   （`https://pay.wkgeo.com/?order_id=…`），不是 `code_url`。
    不要在本地自己画一个二维码页面让用户扫 —— 那是被明确否掉的做法。
 7. **限流是保护，不是故障**：429 时按 `retry_after` 退避；**不要**用重新登录或换令牌来"绕过"限流。
 8. 遇到 `client_secret`、`authorization_code`、`access_token` 之类的字段：
@@ -584,15 +712,31 @@ npx -y wkgeo-cli@latest apps revoke <client_id>      # 该应用所有令牌立
 | --- | --- | --- |
 | `whoami` 返回 exit 3 | 还没登录 / 令牌过期 / 被吊销 | 跑 `login`，把网址给用户点同意 |
 | 浏览器授权后显示"无法访问此网站" | 那一刻本机没有 CLI 在监听（login 被 Ctrl+C 或已退出）；**或代理接管了 127.0.0.1** | 重新 `login`（开着代理时 CLI 会自动改设备码）；并**保持它在前台**直到点完「同意」 |
-| `login` 等到超时（`kind:"timeout"`） | 用户没点完，**或代理把回调吃掉了** | 看 `hint` 与 `meta.proxy_warning`：只要检测到代理，CLI 默认**已经**直接改设备码了；若用户加了 `--no-auto-device`，就把"代理可能吃掉回调"的警告转述给他 |
-| 事件流第一行是 `awaiting_user` 而不是 `awaiting_callback` | 检测到系统代理 → **CLI 直接改用了设备码**（设计行为，不是出错；**绕过列表写了 127.* 也照样改**） | 按 §5.3 把 `paste_text` 转述给用户；想强制回调加 `--no-auto-device`（CLI 会警告风险） |
-| 事件流是 `awaiting_callback`，然后 `data.auto_device.reason:"callback_first_wait"` | ★ 只在**检测到代理**时才会发生：首轮等待（默认 180 秒，可 `--callback-first-wait` 指定）没收到回调 → CLI 自动改设备码继续（**本地回调监听同时保留**） | 正常自愈；如实告诉用户"已同时改用设备码，两条路哪条先成功算哪条，不用重来" |
-| 用户说「我**没开代理**，为什么变成设备码了」 | ★ 2026-10-03 已修：没有代理时 CLI **不再**启用首轮等待自愈（旧版默认 60 秒会误切）。若仍出现 `proxy_warning.detected:true`，那就是真的探到了系统代理（`config --json` 里能看来源） | 先看 `data.proxy_warning.detected`：为 `true` 才是代理的锅；为 `false` 却有 `reason:"callback_first_wait"` ⇒ 只可能是用户自己写了 `--callback-first-wait` |
-| 用户随后才点【同意授权】→ 浏览器显示 **ERR_CONNECTION_REFUSED** | ★ 2026-10-03 已修：切设备码时**不再关掉**本地回调监听（旧版一关就是这个报错）。若仍出现，说明 CLI 进程已经退出（Ctrl+C / 终端关掉了） | 让用户直接在**这一次**的浏览器页面上点同意即可（监听还在），或重跑 `login`；不要让他以为授权失败 |
+| `login` 等到超时（`kind:"timeout"`） | 用户没点完，**或代理把回调吃掉了** | ★ 0.2.2 起超时**不会**自动改设备码：看 `hint` 与 `meta.proxy_warning`。若用户确认本地读不了回调，让他**显式**加 `--device` 重跑；若检测到代理，CLI 默认**已经**在第一跳直接改设备码了（除非加了 `--no-auto-device`） |
+| 事件流第一行是 `awaiting_user` 而不是 `awaiting_callback` | 只有两种可能：**检测到系统代理**（CLI 直接改设备码；绕过列表写了 127.* 也照样改）或用户显式 `--device` | 按 §5.3 把 `paste_text` 转述给用户；想强制回调加 `--no-auto-device`（CLI 会警告风险） |
+| 事件流是 `awaiting_callback`，然后 `data.auto_device.reason:"callback_first_wait"` | ★ **0.2.2 起只可能**是用户/调用方**显式**写了 `--callback-first-wait`（默认关闭）：首轮等待没收到回调 → CLI 并发改设备码（**本地回调监听同时保留**） | 正常自愈；如实告诉用户"已同时改用设备码，两条路哪条先成功算哪条，不用重来" |
+| 用户说「我**没开代理**，为什么变成设备码了」 | ★ 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` 能看来源） |
+| 用户随后才点【同意授权】→ 浏览器显示 **ERR_CONNECTION_REFUSED** | ★ 2026-10-03 已修：显式首轮等待切设备码时**不再关掉**本地回调监听（旧版一关就是这个报错）。若仍出现，说明 CLI 进程已经退出（Ctrl+C / 终端关掉了） | 让用户直接在**这一次**的浏览器页面上点同意即可（监听还在），或重跑 `login`；不要让他以为授权失败 |
 | `login --device-continue` 报 `kind:"expired"` | 短码过期（默认 10 分钟）或已被换过票 | 重新 `login --device --no-wait` 申请新短码；**别**反复续跑 |
 | 下单直接返回 `paid:true` | 服务端设计：下单时余额足够就直接扣款并履约 | 这是正常的"钱包支付"；用 `wallet` 复核余额 |
 | `sites create` 报 400「无法确定所属客户」 | `owner/admin` 这类账号必须显式指定客户 | 加 `--customer <客户ID>` |
+| CMS 命令报 `cms_auth`（401） | 令牌失效（过期/吊销/客户端停用）；旧部署才可能是"没启用 CLI 认证桥" | 先 `wkgeo login` 重新授权一次；仍 401 再让管理员确认服务是否为新版（**别**反复 login） |
+| CMS 命令报 `cms_site_required` | 账号有多个站点、没指定 | `wkgeo site use <站点ID>` 或加 `--site <站点ID>` |
+| `--site` 写了域名没生效 | 后端只按**站点 id** 查，域名会被当成"没指定" | 先 `wkgeo site use <域名>` 解析成 id（CLI 已在本地挡住这种写法） |
+| `templates save` / `assets list` 报 403 `cms_scope` | 令牌是**升级前签的**，缺 `template:*` / `attachment:*`（客户端与默认 scope 现已放开） | 让用户重新授权一次：`login`（默认就带全部所需能力）；**不是** bug，也别改用别的通道 |
+| `assets upload` 报 403 | 令牌缺 `attachment:write`（或站点角色只读） | 看 `error.kind`：`cms_scope` → 重新授权；`cms_readonly` → 找 owner 提权 |
+| `import` 报 `import_unavailable` | 本机没有 `tencent/cloudbase/import-site.mjs`（npx 装的包里没有它） | 只能在本仓库机器上跑；**不要**对客户承诺"我能直接导" |
 | 429 | 调用过于频繁 | 等 `retry_after` 秒；**不要**重新授权 |
 | `apps list` 报"未部署" | 该环境的 data 云函数还没发版（**线上已发版并实测过**，见 README §9） | 告诉用户"这是服务端缺口"，不要反复重试；`logout` 仍可清理本地登录态 |
 | `skill` 报「当前安装包里没有手册文件（SKILL.md）」 | 跑的是**被裁剪的包**或只拷了 `lib/` 的开发目录（正常 npm 包一定有） | 换 `npx -y wkgeo-cli@latest skill`；这不是命令用错了（`error.kind="missing_skill"`，退出码 1） |
 | 想升级 CLI | 全局安装不会自动升级 | 用 `npx -y wkgeo-cli@latest`，或 `npm i -g wkgeo-cli@latest` |
+
+## 云端能力（阿里云侧由云函数执行，CLI 不持有 AK）
+
+绑域名 / 新建 ESA 站点 / 传 OSS / 发布边缘函数 / 查配额这些**阿里云侧操作**，
+一律通过云端管理接口（FC 函数 `wkgeo-admin`）完成 —— **CLI 与桌面都不持有阿里云 AK**。
+
+- 能力清单、权限范围（scope）、请求头要求、curl 示例、已知坑：`aliyun/fc/wkgeo-admin/README.md`
+- 背景与验证记录：`docs/建站-云端管理接口.md`
+- 地址 `https://wkgeo-admin-nyvdudigpb.cn-shanghai.fcapp.run`；必带 `Authorization: Bearer <平台签发的 JWT>` 与 `Date`（RFC1123）
+- scope：`read` / `domain:bind` / `site:create` / `kv:write` / `oss:write` / `routine:deploy`

package/lib/args.mjs

@@ -20,6 +20,11 @@ import { UsageError } from './errors.mjs';
 /** 全局标志：任何命令都接受（写在 spec 之外，避免每个命令重复声明） */
 export const GLOBAL_FLAGS = {
   base: { type: 'string', desc: 'API 基址（默认线上网关，可用 WKONGAI_BASE 覆盖）' },
+  /**
+   * CMS 面是**另一个云函数 / 另一个域名**（新写法 `https://api.wkgeo.com/cms`），
+   * 所以单独给一个基址开关：联调 / 换环境时不用去改平台面的 `--base`。
+   */
+  'cms-base': { type: 'string', desc: 'CMS 接口基址（默认 https://api.wkgeo.com/cms，可用 WKONGAI_CMS_BASE 覆盖）' },
   'web-base': { type: 'string', desc: '前端基址（授权页兜底地址）' },
   'client-id': { type: 'string', desc: 'OAuth 客户端 id（默认 wkgeo-cli）' },
   scope: { type: 'string', desc: '申请的能力范围（空格分隔）' },

package/lib/cli.mjs

@@ -98,6 +98,11 @@ export async function run(argv = [], io = {}) {
        */
       platform: io.platform,
       exec: io.exec,
+      /**
+       * `wkgeo import` 起子进程的注入点（同步；生产默认 `spawnSync`）。
+       * 单测注入它就能验证"脚本参数怎么拼、退出码怎么转述"，不真的去起子进程抓网站。
+       */
+      runScript: io.runScript,
       /** 同上：`skill` 手册位置的注入点（单测验证"包里没有手册"分支时用，见 lib/commands/skill.mjs） */
       skillUrl: io.skillUrl,
     });