@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/README.md CHANGED
@@ -1,3 +1,1042 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # 云站官方 CLI(`@wkgeo/cli`)
2
+
3
+ > 命令行/桌面端/**给 AI 端**用的官方客户端。
4
+ > **授权登录一次**(浏览器点一次「同意」)→ 令牌存本地 30 天 → 之后**建站 / 下单 / 钱包余额支付 / 查余额 / 查订单**全程不用再登录。
5
+
6
+ * 技术形态:Node.js,**零第三方依赖**(只用 Node 内置模块),Node ≥ 18(推荐 20+)
7
+ * 授权方式:OAuth 授权码 + **PKCE**(公共客户端,**代码里没有任何 client_secret**)
8
+ * 默认授权:**浏览器打开授权页 + 本地 `127.0.0.1` 回调**(等多久都不会自动改成设备码);设备码只在
9
+ 显式 `--device`、检测到系统代理、或本地回调端口真的起不来时兜底(见 §3.2)
10
+ * 另一种授权:**设备码**(`login --device`,不需要回调地址,**对代理/防火墙免疫**;见 §3.2)
11
+ * ⭐ **开着代理也能成功**:**只要检测到系统代理就直接改用设备码**(不看代理绕过列表),用户什么都不用做(见 §3.4)
12
+ * 输出:人类可读 + **稳定 JSON**(默认非终端环境自动 JSON),失败也是结构化 JSON
13
+
14
+ ---
15
+
16
+ ## 0. 给 AI 端的最短路径(TL;DR)
17
+
18
+ ```bash
19
+ npx -y @wkgeo/cli@latest login # 1) 打印/打开授权网址,等用户点「同意」
20
+ npx -y @wkgeo/cli@latest whoami # 2) 确认是谁(只显示账号标识,不打印令牌)
21
+ npx -y @wkgeo/cli@latest wallet # 3) 查余额
22
+ npx -y @wkgeo/cli@latest sites create --name 我的站
23
+ npx -y @wkgeo/cli@latest products list
24
+ npx -y @wkgeo/cli@latest orders create --product storage_gb --units 1 # 余额够就当场付清
25
+ npx -y @wkgeo/cli@latest orders list
26
+ ```
27
+
28
+ * **所有命令都在非终端(管道/AI 子进程)下自动输出 JSON**;人看的时候自动是人类可读表格。
29
+ * 退出码:**0** 成功 | **1** 失败 | **2** 用法错误 | **3** 需要(重新)授权 | **4** 被限流。
30
+ * 失败 JSON:`{"ok":false,"command":"...","error":{"kind","code","message","hint","retry_after"},"meta":{...}}`
31
+ —— `hint` 是"下一步该做什么",AI 可以直接照做。
32
+ * 完整的给 AI 的说明书见 [`SKILL.md`](./SKILL.md);**也可以一条命令直接取出来**:
33
+ `npx -y @wkgeo/cli@latest skill`(默认打**纯文本原文**;`--json` 时在 `data.markdown` 里)。
34
+
35
+ ---
36
+
37
+ ## 1. 安装与分发(三条路径,主线是 npm)
38
+
39
+ | 形态 | 适合谁 | 怎么装 | 体积 | 备注 |
40
+ | --- | --- | --- | --- | --- |
41
+ | **① npm 包(主线)** | 开发者、我们自己的 **AI 端**、有 Node 的任何环境 | `npx -y @wkgeo/cli@latest <命令>` 或 `npm i -g @wkgeo/cli` | ~51 KB | **一种形态覆盖全平台**;升级只需改 `@latest` |
42
+ | ② zip 单文件(备用) | 有 Node、但不想用 npm 的普通用户 | 解压 → 双击 `wkgeo.cmd` / `./wkgeo.sh` | ~64 KB | 无需 `npm install`;仍需机器有 Node 18+ |
43
+ | ③ exe 独立可执行(备用) | **完全没有 Node**、也不想装 Node 的人 | 下载对应平台的二进制直接跑 | **60~100 MB / 平台** | 每个平台要分别打包,发版成本最高 |
44
+
45
+ ### ① npm(推荐)
46
+
47
+ ```bash
48
+ # 不安装,直接跑(AI 端首选:-y 免掉安装确认,避免自动化卡住)
49
+ npx -y @wkgeo/cli@latest --help
50
+
51
+ # 或全局安装后用短命令
52
+ npm i -g @wkgeo/cli
53
+ wkgeo --help
54
+ ```
55
+
56
+ 包内容用 `package.json` 的 **`files` 白名单**收口(`wkgeo.mjs` + `lib/` + `README.md` + `SKILL.md`),
57
+ **不含**测试、脚本、`dist/`、任何凭据。核对方式:
58
+
59
+ ```bash
60
+ cd cli && npm pack --dry-run # 输出即为"将要发布的确切文件清单"
61
+ ```
62
+
63
+ > ⚠️ **取舍:发 npm = 源码公开**。npm 上的包任何人都能下载查看(我们的包是纯客户端、零密钥,
64
+ > 公开不影响安全;但如果你不想让别人看到实现细节,就只能走 zip/exe 私有分发)。
65
+ > 另一个取舍:一旦某个版本被别人依赖,**不能随意删除**(见「发布流程」)。
66
+
67
+ ### ② zip(备用,给有 Node 的普通用户)
68
+
69
+ ```bash
70
+ cd cli && npm run build:zip
71
+ # → cli/dist/wkgeo-cli-1.0.0.zip(含入口 + lib + README + 快速开始.txt + wkgeo.cmd/.sh)
72
+ ```
73
+
74
+ 用户侧:解压 → 双击 `wkgeo.cmd`(Windows)或 `./wkgeo.sh`(macOS/Linux)→ 按提示 `login`。
75
+ ⚠️ **仍然需要机器上有 Node 18+**(zip 里去掉了 `node_modules`,因为本来就没有依赖)。
76
+
77
+ ### ③ exe(备用,给完全没 Node 的非技术客户)
78
+
79
+ ```bash
80
+ cd cli && npm run build:exe # 打印三种方案的完整命令与取舍(零副作用)
81
+ cd cli && node scripts/build-exe.mjs --sea # 跑 Node SEA 的离线两步(生成 blob + 复制 node 壳)
82
+ ```
83
+
84
+ 推荐 **Node SEA**(官方)或 `bun build --compile`(最省事),**不推荐 `pkg`**(已停止维护)。
85
+ ⚠️ **每个平台(Windows/Linux/macOS)必须分别打包,二进制互不通用**,且 macOS 还要 x64/arm64 分开;
86
+ 产物 60~100 MB。脚本不会替你下载任何大依赖(postject/bun 需要时自己装)。
87
+
88
+ ### 版本与升级策略
89
+
90
+ * 当前版本 **`1.0.0`**(`cli/package.json`,**2026-10-30 已发布到 npm 组织 `@wkgeo`**):在 0.6.0 之上把后台**整块搬进 CLI** —— 内容 45 / 素材 18 / 发布 16 / 配置类 auth 11 / 站点 7 / 插件 9 / 控制台 8 七批动作全部由自持云函数 `wkgeo-cli-fc` 进程内执行(不再借 `/cms` 会话转发,因而计入 `cli_action_usage`),**`whoami.action_total` 150 → 185**,新增 / 补齐 `assets`、`publish`、`site info`、`plugins`、`config`、`logs`、`overview`、`lang`/`role`/`member` 命令组;上一个版本 **`0.6.0`**(2026-10-28:`/cli` 收口 + `auth` 命令组 + `domain bind` + 域名成交链路);更早的补丁版 **`0.5.1`**(2026-10-26:修 0.5.0 的 `publish --confirm` 轮询崩溃 `ctx.sleep is not a function`)。
91
+ * **本版只加命令、不改契约**:原有命令 / 参数 / `--json` 信封 / 退出码与 0.6.0 完全一致,AI 端继续用 `npx -y @wkgeo/cli@latest` 即可;逐批明细与已知缺口见 [`CHANGELOG.md`](./CHANGELOG.md) 顶部「1.0.0」。
92
+ * **同一个版本号不能覆盖**:改了代码必须 `npm version patch|minor|major` 再发布。
93
+ * AI 端统一用 **`npx -y @wkgeo/cli@latest`** → 每次自动拿最新版;
94
+ **全局安装的用户不会自动升级**(要手动 `npm i -g @wkgeo/cli@latest`)。
95
+ * 发布后 **几秒~几分钟** 生效(npm CDN 缓存);⚠️ **72 小时后基本无法删除**,只能 `deprecate` + 发修正版。
96
+ * 详细步骤(含 2FA、包名检查、发布前安全检查清单)见 **[`发布流程.md`](./发布流程.md)**。
97
+
98
+ #### 版本记录
99
+
100
+ | 版本 | 日期 | 变更 |
101
+ | --- | --- | --- |
102
+ | **1.0.0** | 2026-10-30 | **本版是 scoped 新包**:包名 `@wkgeo/cli`(npm 组织 `@wkgeo`),命令 / 参数 / `--json` 信封 / 退出码与旧包最后一版完全一致;`license` 改 MIT、随包附 `LICENSE`、`engines.node` 为 `>=18`。以下是本版带来的动作面: **七批后台动作全量进自持面(动作面 150 → 185)**。① **插件类 9 条**(task-91 / B5):`plugins` 从 2 条扩到 **9 条**(`list` / `access` / `toggle` / `settings` / `market-list` / `install` / `uninstall` / `upgrade` / `demo`),全部由 `wkgeo-cli-fc/src/plugin-core.js`(逐字复制 CMS handler,生成器拼装)执行,**不再借 `/cms` 转发**,因此进 `cli_action_usage` 计数;权限:4 条读 `site:read`,5 条写 `site:write`(服务端另校验 `site.owner_id`:他人站 403 `not_site_owner`,站名/业主一概不回);写命令一律**默认 dry-run**,`--confirm` 才真发;**9 条全迁、无不迁条目**(`pluginMarketDemo` 只读库里 `demo_url`,不下载外链)。② **站点类 7 条**(task-90 / B4):新增 `site info`、`site info save`、`site domain-recheck`、`site demo-seed`、`site demo-clear`、`site sync`,并把 `domain inspection` 从 `/cms` 切到 `/cli` 的 `cmsSiteDomainInspectionList`;**不迁** `cmsCreateSite`(`site create` 已是原生动作,迁会双写 `site` / `cms_site_member`)与 `cmsSiteDomainCheck`(`domain check` 已走原生 `siteDomainCheck`)。③ **控制台类 8 条**(task-92 / B7):新增 `logs list`、`config get\|save\|review\|capabilities`、`overview summary\|traffic\|dashboard`;平台管理员判定改成真查库(`isPlatformAdminUser`)⇒ `traffic` / `dashboard` 的平台门禁照样成立;6 条只读**不写审计**,只有 `configSave` / `configReview` 落 `admin_audit_log`;`configReview` 另带 `x-review-token` 双闸(未配 `REVIEW_TOKEN` 回 503)。动作面推进:**150(0.6.0)→ 168(B4)→ 177(B5)→ 185(B7)**;域名级 DNS 凭据 4 条按后端口径不计入(`auth status` 单列 `uncounted_self_hosted`),`/cli` 可见动作实际 189 = 185 + 4。 |
103
+ | **0.6.0** | 2026-10-28 | **CLI 收口到自己的云函数 `wkgeo-cli-fc`(网关 `/cli`)**。① 业务面从 `/user` `/order` `/domain` 收敛到 `/cli`(`WKONGAI_LEGACY_ENDPOINTS=1` 才走老路径),动作面 **150 条**(原生 + 自持重建 + 金融面白名单转发)。② 新增 **`auth` 命令组**:`auth status`(`cliWhoami`:账号 / `client_id` / `scopes` / 到期 / 动作面体检)、`auth token`(只给前 4 位 + 长度 + 到期)、`auth revoke`(`POST /api/oauth/revoke` + 删本地)。③ 新增 **`domain bind`**(原生 `cliProvisionSiteDomain`;平台通道没开时上游 503 → 明确「本次未写入,可直接重试」+ exit 1)。④ 新增 `sites get`、`domain status\|records\|dns\|check\|remind`(只读)、`sites list --with-prefix`、`sites create --channel auto\|platform\|cms`。⑤ 新增建站端到端脚本 `cli/scripts/e2e-site.mjs`(建站 → 校验短域 → 可选绑域 → 发布 → 盯首页 200 + 指纹;**默认不删站**、真建站需 `--confirm`)。**令牌模型不变**(OAuth access_token,30 天)。 |
104
+ | **0.5.1** | 2026-10-26 | **修 `publish --confirm` 崩在轮询**。0.5.0 在**发布已经提交成功之后**抛 `{"kind":"internal","message":"ctx.sleep is not a function"}`(exit 1):`lib/cli.mjs` 逐字透传 `sleep: io.sleep`,而生产入口 `wkgeo.mjs` 调 `run(argv)` 不传 `io`,`undefined` 覆盖了默认值;`lib/runtime.mjs` 的 `sleep` 默认值本身也是 `undefined`。修法:**所有可选注入项在 runtime 层落地默认实现**(`sleep`/`now`/`random`/`log`/`clock`/`fetchImpl` 等,非法值一律归一化),`cli.mjs` 只透传真的给了的注入项(`undefined` 不出现,`false`/`0` 保留)。新增 8 条回归(含「不传 io 的 publish --confirm 端到端」)。**命令、参数、`--json` 信封、退出码全部不变**。 |
105
+ | **0.5.0** | 2026-10-26 | **发布接真后端 + 本地大模型**。① `publish` 不再是"只看 overview":默认 **dry-run**(只读算页面数),`--confirm` 才调 `cmsSitePublishStart` 并轮询 `cmsSitePublishStatus` 到终态,打印 `total/done/pagesFailed/finalizeOk`;另有 `publish status` / `publish cancel` / `--cancel`;**站点必须显式**(没 `--site` 也没 `site use` 就报用法错误,绝不猜站)。② 新增 `plugins list\|toggle`(`pluginList`/`pluginToggle`,`editor` 单选互斥会提示「已停用:xxx」)、`forms list\|entries`(`/form` 前缀;**手机/邮箱/IP/UA 默认脱敏**,`--raw` 必须再加 `--confirm`)、`domain inspection`(`cmsSiteDomainInspectionList`;403 → 人话「需要系统管理员权限」而不是堆栈)、`preview <path>`(零后端拼预览地址,`--open`)、`import-v2 start\|status`(`importV2Start`/`importV2Get`,默认 dry-run)。③ **本地大模型**:`ai ping\|ask\|chat` + `context export`(只连本机、上下文白名单 10 域、日志只记元信息),详见 [`../docs/CLI-本地大模型接入.md`](../docs/CLI-本地大模型接入.md)。④ 修 6 处过时项:`fnOf()` 支持 `/form` `/ai` `/member` `/channel` `/ai-tools` 五个新网关前缀;`config.version` 改为读 `package.json`;`CMS_ACTIONS` 补新动作;`CATEGORY_FIELDS` 补 `cover/attachments/fields_enabled/max_depth/template_path/seo_jsonld/link_category_id/link_plugin_key/link_plugin_sub`;`categories` 加 `--link-plugin/--link-plugin-sub`;新增 `CHANGELOG.md`。 |
106
+ | **0.4.0** | 2026-10-22 | **修「建站只建平台站」**:`sites list` 的建站引导把 CMS 动作 `cmsCreateSite` 误发到平台 `/api/data`(永远回"未知动作")→ 改为走 **CMS 通道** `ctx.cmsCall('createCmsSite', …, {noSite:true})`,一次建出 CMS 站 + 平台站(`cms_site` / 成员行 / 内置模板 / `public.site`)。仅当 CMS 通道回"未知动作/400"才回退平台 `createSite` 并提示「CMS 站点未创建」;网络 / 401 / 429 / 5xx 不回退。新增 `cmsCall(..., {noSite:true})` 无站点模式(建站时本地可能残留旧站点 id,带 `x-cms-site` 会被服务端按成员关系 403 挡掉)。 |
107
+ | 0.3.0 | 2026-10-22 | **默认 API 基址从腾讯 CloudBase 网关切到阿里云 `https://api.wkgeo.com`**(`lib/config.mjs` 的 `DEFAULT_BASE`)。切换前已逐路径门禁比对:`/api/data`、`/api/oauth/{metadata,userinfo,token,introspect,revoke,device_authorization}` 与未知路径 404 的状态码 / JSON 形状新旧完全一致。CMS 基址本来就是 `https://api.wkgeo.com/cms`,未变。旧网关可用 `WKONGAI_BASE=https://wkongai-….tcloudbase.com` 临时覆盖回滚。 |
108
+ | 0.2.4 | 2026-10-21 | 本地回调端口被占用自动换端口;绑定失败不再静默改设备码;成功页 / 失败页都自动关闭。 |
109
+ | 0.2.3 | 2026-10-21 | CI / 非交互环境(`CI` 等环境变量或 `WKONGAI_CLI_NO_BROWSER=1`)不再自动打开浏览器,只输出链接 / JSON。 |
110
+ | 0.2.2 | 2026-10-21 | 默认授权模式改回浏览器回调:等待超时不再自动改设备码;`--callback-first-wait` 变为默认关闭的显式可选。 |
111
+ | 0.2.1 | — | 代理场景下自动改设备码(首轮等待 180 秒)。 |
112
+ | 0.2.0 | 2026-10-02 | 设备码授权端到端上线(申请 / 确认 / 换票 / 重放)。 |
113
+
114
+ ---
115
+
116
+ ## 2. 不发布也能测(三种本地方式)
117
+
118
+ | 方式 | 命令 | 像不像真安装 | 适合什么时候 |
119
+ | --- | --- | --- | --- |
120
+ | ① **直接跑** | `node cli/wkgeo.mjs login` | 不像 | 改完立刻验证,最快 |
121
+ | ② **全局软链** | `cd cli && npm link` → 之后直接敲 `wkgeo login` | **最像**(真实 shim、真实 PATH) | 想验证"装完之后是什么体验";改代码即时生效 |
122
+ | ③ **打包彩排 ⭐** | `cd cli && npm pack` → `npm i -g ./wkgeo-cli-1.0.0.tgz` | **就是真安装** | **发布前必做**:同时验证"包里文件齐不齐、有没有混进不该有的东西" |
123
+
124
+ ```bash
125
+ # ① 直接跑
126
+ node cli/wkgeo.mjs --help
127
+
128
+ # ② npm link(卸载:npm unlink -g @wkgeo/cli)
129
+ cd cli && npm link && wkgeo --version
130
+
131
+ # ③ 打包彩排(发布前必做)
132
+ cd cli
133
+ npm test # 离线单测全绿(约 500 条)
134
+ npm pack --dry-run # 看清单:只会包含 wkgeo.mjs / lib / README.md / SKILL.md / CHANGELOG.md / LICENSE
135
+ npm pack # 产出 wkgeo-cli-1.0.0.tgz
136
+ npm i -g ./wkgeo-cli-1.0.0.tgz
137
+ wkgeo login && wkgeo wallet && wkgeo logout # 走一遍真链路
138
+ npm uninstall -g @wkgeo/cli
139
+ ```
140
+
141
+ > 第 ③ 步是**唯一**能证明"发出去的包能跑"的方式(①②都绕过 `files` 白名单)。
142
+
143
+ ---
144
+
145
+ ## 3. 登录与授权
146
+
147
+ ### 3.1 本地回调模式(默认,推荐)
148
+
149
+ ```bash
150
+ wkgeo login
151
+ ```
152
+
153
+ 会发生什么(**用户实际会看到的东西**):
154
+
155
+ 1. 终端打印一条授权网址(**人在终端时**会尽力自动打开浏览器;**CI/管道/AI 子进程只输出链接**,见下);
156
+ 2. 浏览器里是**我们自己的登录页**:支持「账密登录 / 手机号登录 / 邮箱登录」三个页签
157
+ (手机号/邮箱是**验证码登录**,验证码由平台下发到已绑定的手机/邮箱);
158
+ 3. 登录后进入**同意页**,显示应用名「官方 CLI」和将获得的权限,点「同意」;
159
+ 4. 浏览器跳回 `http://127.0.0.1:53682/callback` —— CLI 的本地小服务会显示
160
+ **「✅ 授权成功 / 请回到终端(客户端)继续操作,本页面可以关闭了」** 的中文页面;
161
+ 5. 终端显示「✅ 授权成功,已登录:<账号>」,令牌写入 `~/.wkongai/credentials.json`(0600)。
162
+
163
+ 于是"点同意"这件事**只需要 30 天做一次**(之后令牌过期或被吊销才需要重来)。
164
+
165
+ > ★ **0.2.2 起:默认就是这条本地回调路径**,`wkgeo login` **不会**因为"等了一会儿"
166
+ > 自动变成设备码。设备码只在三种情况出现:① 显式 `--device`;② 检测到系统代理
167
+ > (自动改道,`--no-auto-device` 可关,见 §3.4);③ 本地回调端口**真的起不来**
168
+ > (自动兜底,`--no-auto-device` 可关)。整段等待超时只报 `kind:"timeout"`,不再自动改道。
169
+
170
+ 选项:
171
+
172
+ | 选项 | 说明 |
173
+ | --- | --- |
174
+ | `--device` | 用**设备码模式**(RFC 8628):不需要本地回调地址/端口;本地读不了回调时的兜底(见 §3.2) |
175
+ | `--no-browser` | **不打开浏览器**(优先级最高,压过 `--open-browser`)。⚠️ 非交互/CI 环境本来就不会打开,这个开关主要用于终端/脚本显式表态 |
176
+ | `--open-browser` | 强制尝试打开系统浏览器(⚠️ **只在人类终端生效**;CI/非交互环境仍不打开;保留显式语义与兼容) |
177
+ | `--scope "site:read site:write billing:self"` | 申请的能力范围(默认就是这三个,够建站+下单+支付) |
178
+ | `--client-id <id>` | 换一个 OAuth 客户端(默认 `wkgeo-cli`) |
179
+ | `--callback-port <n>` | 本地回调端口(默认 53682;被占用会自动退到随机端口) |
180
+ | `--timeout <秒>` | 等待授权的超时。**默认单位是秒**:`--timeout 600` = 600 秒;也支持显式后缀 `600s` / `500ms`;默认 300 秒(5 分钟)。非法值直接报用法错误(退出码 2),不会静默兜底 |
181
+
182
+ > ⚠️ **单位踩过的坑**:`--timeout` 早期按**毫秒**解释,于是 `--timeout 600` 变成 600 毫秒 ——
183
+ > 0.8 秒就超时失败,而帮助里连单位都没写。现在**默认按秒**,并把单位写进了 `--help`。
184
+
185
+ > ⚠️ **自动打开浏览器**:**多策略依次尝试**(Windows:`rundll32 url.dll,FileProtocolHandler <url>` → `cmd /c start "" "<url>"` → `powershell -NoProfile -Command Start-Process`;
186
+ > macOS:`open` → `open -a Safari`;Linux:`xdg-open` → `sensible-browser` → `x-www-browser`),每条都看**退出码/错误/超时**,失败**静默**试下一条。
187
+ > ⚠️ Windows 那条 `cmd` 的**引号必须在字符串里**:`&` 在 cmd 里是命令分隔符 ——
188
+ > 授权 URL 的 6 个参数会被当成"另一条命令"吃掉,浏览器打开的是光秃秃的
189
+ > `/admin/oauth/authorize`(页面显示「授权请求不完整」)。
190
+ > 全部失败才提示,且**只 warn**(`⚠️ 浏览器没能自动打开…` 后面紧跟**完整 URL** 供复制),**绝不中断**授权流程。
191
+ >
192
+ > ★ **2026-10-21 起:非交互 / CI 环境默认不弹浏览器**(老板真机反馈「别人在 CI 里执行
193
+ > `wkgeo-cli` 的 login,默认弹出了系统默认浏览器」):
194
+ > * **人类终端**(`stdout.isTTY` 为真、且不在 CI 里)→ 照旧**尝试自动打开**系统浏览器(老体验不变);
195
+ > * **非交互 / CI** → **只输出授权链接/JSON,一个浏览器进程都不 spawn**。判定(满足任一):
196
+ > * `stdout.isTTY` 为假(管道 / 重定向 / AI 子进程 / CI 日志采集);
197
+ > * 存在任一 CI 环境变量(**存在即判定**):`CI`、`GITHUB_ACTIONS`、`GITLAB_CI`、`JENKINS_URL`、`TF_BUILD`、`BUILDKITE`、`TEAMCITY_VERSION`;
198
+ > * `WKONGAI_CLI_NO_BROWSER=1`(`true/yes/on` 也认)。
199
+ > 此时 `open_browser.attempted=false`、`skipped_reason:"non_interactive"`(字段结构不变),
200
+ > 并打印「把授权链接转给有浏览器的用户 / 改用 `wkgeo login --device`」的可照做提示;
201
+ > * `--no-browser` → **不打开**(`skipped_reason:"no_browser"`,**优先级最高**,压过 `--open-browser`);
202
+ > * `--open-browser` **保留**,但只在终端里保留显式语义(**压不过**非交互判定:CI 里写它也不弹);
203
+ > * `--json` 的 `open_browser.skipped_reason` 合法值:`null`(真尝试过)/ `"no_browser"` / `"non_interactive"`
204
+ > (2026-10-01 那版的 `"non_tty_agent_mode"` **已弃用**);
205
+ > * 打开成功 → `✅ 已为你打开浏览器,请在那里完成授权。`;打开失败 → ⚠️ 一段**含完整 URL** 的醒目提示
206
+ > (AI 场景再多一句"客户端支持内置浏览器也可以在那里打开"的**可选**提示,不是主路径);
207
+ > * 非交互时 `paste_text` 是「请打开以下链接完成授权:<url>」**而不是**「已为你打开浏览器」——
208
+ > 屏幕上什么都没弹,说"已打开"会让用户以为链接坏了;
209
+ > * ⚠️ **不弹浏览器 ≠ 失败**、**打开失败也 ≠ 失败**:地址照旧完整打印、流程照旧等回调/照旧返回 `pay_url`,
210
+ > 命令**绝不会**因此失败(回调 / 设备码的判定逻辑也完全不受影响)。
211
+
212
+ > ⚠️ 回调**只监听 `127.0.0.1`**(绝不 `0.0.0.0`);`state` 每次随机并在本地回调时**强校验**
213
+ > (服务端只负责原样回传,防 CSRF 是客户端自己的责任)。
214
+ > 端口被占用会自动换随机端口 —— 服务端按 RFC 8252 对回环地址**忽略端口**比对。
215
+
216
+ ### 3.2 设备码模式(`--device`)—— **本地读不了回调 / 代理 / 远程机器时的兜底**
217
+
218
+ > ★ **默认不是设备码**:`wkgeo login` 默认走浏览器回调(§3.1)。设备码只在:
219
+ > ① 显式 `--device` / `--no-wait` / `--device-continue`;② 检测到系统代理(CLI 自动,§3.4);
220
+ > ③ 本地回调端口真的起不来(CLI 自动兜底,`reason:"callback_listen_failed"`)。
221
+ > **等待超时不会**自动改设备码(0.2.2 起)。
222
+
223
+ ```bash
224
+ wkgeo login --device # 申请短码 → 打印网址/短码 → 轮询到出结果(人盯着终端时用这条)
225
+ wkgeo login --device --no-wait # ★ 只申请短码就退出(AI 端友好,见下)
226
+ wkgeo login --device-continue # 用上次保存的设备码换票(配合 --no-wait)
227
+ ```
228
+
229
+ 一条**不需要任何回调地址/监听端口**的授权路径:CLI 申请一个短码(如 `ABCD-1234`),
230
+ 打印一段**可以直接复制**的话:
231
+
232
+ ```
233
+ 请在浏览器中完成授权(设备码模式,不需要任何回调地址):
234
+
235
+ 1) 打开:https://wkgeo.com/oauth/device/?user_code=ABCD-1234
236
+ 2) 如果页面没有自动填好短码,请输入:ABCD-1234
237
+
238
+ 📋 可以直接复制这段发给 AI 端或转给用户:请打开 https://wkgeo.com/oauth/device/?user_code=ABCD-1234 并完成「同意授权」(短码:ABCD-1234)。
239
+ ```
240
+
241
+ > ★ **2026-10-18 域名统一到路径**:授权站 canonical 从 `https://oauth.wkgeo.com/` 改成
242
+ > **`https://wkgeo.com/oauth/`**(老地址继续可用)。CLI 以 `WKONGAI_OAUTH_WEB_BASE` 为 canonical,
243
+ > 服务端 metadata 给的授权地址只当"路径来源"用(详见 `lib/oauth-urls.mjs`);
244
+ > 回滚只要一条环境变量:`WKONGAI_OAUTH_WEB_BASE=https://oauth.wkgeo.com`。
245
+
246
+ > ✅ 线上**已支持**这条路径(2026-10-02 实测:`metadata` 声明了 `device_authorization_endpoint`,
247
+ > `grant_types_supported` 含 device_code,确认页 `/admin/oauth/device/` 也在)。
248
+ > 端到端真跑记录见云函数测试目录的 `aliyun/fc/_tests/oauth-device-live-e2e.js`(默认只读,`OAUTH_DEVICE_E2E_LIVE=1` 才实跑)。
249
+
250
+ #### `--no-wait` + `--device-continue`:给 **AI 端(Agent)** 用的"先给码、后领票"
251
+
252
+ AI 端是**一轮一轮**工作的:一次工具调用里挂着等 10 分钟会把用户晾住,也容易撞工具超时。
253
+ 所以拆成两条命令,**中间不需要任何长驻进程**:
254
+
255
+ ```bash
256
+ # ① Agent 调用(立刻返回,进程随即退出)
257
+ wkgeo login --device --no-wait --json
258
+ # → {"ok":true,"command":"login","stage":"awaiting_user","user_code":"ABCD-1234",
259
+ # "verification_uri":"https://wkgeo.com/oauth/device/",
260
+ # "verification_uri_complete":"…/?user_code=ABCD-1234","paste_text":"…","expires_in":600,
261
+ # "interval":5,"resume_command":"wkgeo login --device-continue","pending_file":"…","next_step":"…",
262
+ # "user_action_required":"请让用户访问 … 并输入短码 ABCD-1234","no_wait":true}
263
+
264
+ # ② Agent 把 paste_text(或 user_action_required)原样念给用户,让他在**自己的浏览器**里点「同意」
265
+
266
+ # ③ 用户说"点好了"之后,Agent 领票
267
+ wkgeo login --device-continue --json
268
+ # → {"ok":true,"command":"login","stage":"done","data":{…凭据已写入…}}
269
+ ```
270
+
271
+ * 状态文件写在凭据文件旁边(`<credentials.json>.device-pending.json`,**0600**),
272
+ 所以第二步与第三步之间**隔多久都行**(只要没超过 `expires_in`,默认 10 分钟);
273
+ * 交互式终端里**不必**拆开用:直接 `login --device` 一口气跑完更省事;
274
+ * ⚠️ `--no-wait` **隐含**设备码模式(回调模式没有"先返回、稍后再领"这回事)。
275
+
276
+ > 🔴 **安全边界(AI 端必须知道)**:`device_confirm`(用户在页面上点「同意」这一步)
277
+ > **需要用户自己的平台登录会话**。AI 端**没有、也不该有**用户的浏览器会话,
278
+ > 所以"用户把短码发到 AI 对话框"之后,AI 端能做的是**把网址 + 短码清楚地转达给他、
279
+ > 引导他自己去点确认**;**不能**替用户点同意。CLI 只负责"申请码 + 等结果"。
280
+
281
+ #### 设备码模式与回调模式的差别(一眼看懂)
282
+
283
+ | | 本地回调(默认) | 设备码(`--device`) |
284
+ | --- | --- | --- |
285
+ | 需要本地监听端口 | 需要(127.0.0.1:53682) | **不需要** |
286
+ | 需要浏览器能访问 127.0.0.1 | 需要(⚠️ 代理/防火墙可能挡住) | **不需要** |
287
+ | 用户操作 | 点一下「同意」 | 打开网址(短码已预填)+ 点一下「同意」 |
288
+ | 适合 | 本机有浏览器、网络干净 | 远程/容器/CI、**开着代理**、防火墙受限 |
289
+
290
+ ### 3.3 登录状态的输出(JSON 事件流)
291
+
292
+ `login` 是唯一会**长时间阻塞**的命令,所以 JSON 模式下它输出 **JSONL 事件流**(每行一个 JSON):
293
+
294
+ ```jsonc
295
+ // 本地回调模式:第一行就给出网址,AI 可以立刻转述给用户
296
+ // (注意 `authorize/` 的**尾斜杠**:托管侧对不带尾斜杠的目录路径会 302 且丢掉 query)
297
+ {"ok":true,"command":"login","mode":"callback","stage":"awaiting_callback",
298
+ "authorization_url":"https://wkgeo.com/oauth/authorize/?client_id=…",
299
+ "redirect_uri":"http://127.0.0.1:53682/callback",
300
+ "user_action_required":"请让用户在浏览器中打开上面的 authorization_url,登录并点「同意」"}
301
+ // 结束(成功)
302
+ {"ok":true,"command":"login","stage":"done","data":{"account":{…},"expires_at":"2026-10-30T…","credentials_file":"…"}}
303
+ ```
304
+
305
+ 设备码模式第一行是 `stage:"awaiting_user"`,带 `user_code` / `verification_uri` /
306
+ `verification_uri_complete` / `open_url` / `expires_in` / `interval` / `paste_text`。
307
+ 失败时输出 `{"ok":false,"command":"login","error":{…}}` 并返回非 0 退出码。
308
+
309
+ ### 3.4 ⭐ 代理 / VPN 环境下怎么办(`127.0.0.1` 被代理接管)
310
+
311
+ **现象**:用户在同意页点了「同意」,浏览器却报"无法访问此网站"或干脆没反应,
312
+ **终端一直卡在"等待你在浏览器里完成授权…",最后超时失败**。
313
+
314
+ **机理**:本地回调模式要求**浏览器**访问 `http://127.0.0.1:<端口>/callback?code=…`。
315
+ 多数代理默认绕过回环地址,但**全局/系统代理 + 绕过列表为空**时,浏览器会把这条回环请求
316
+ 也交给代理 → CLI 的本地服务永远收不到 `code`。**问题在浏览器那一侧,不在 CLI 出网**。
317
+
318
+ **CLI 的处理(2026-10-02 第二版加固;2026-10-21 默认回调调整)**:
319
+
320
+ 1. **检测**(只读,绝不改你的代理设置):Windows 读注册表 `…\Internet Settings` 的
321
+ `ProxyEnable`/`ProxyServer`/`ProxyOverride`/`AutoConfigURL`;macOS 读 `scutil --proxy`;
322
+ 三平台都看 `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY`/`NO_PROXY`(大小写都认)。
323
+ 2. ★ **只要检测到"生效中的代理"就直接改设备码** —— **不再看绕过列表**。
324
+ 真机教训(2026-10-02):老板的 `ProxyOverride` 里**写着** `localhost;127.*`,
325
+ 旧版据此判"安全"、走了回调,结果他点了【同意授权】之后 CLI **一直拿不到令牌**;
326
+ 独立探测 `curl -x http://127.0.0.1:7890 http://127.0.0.1:1/x` **返回 502**,
327
+ 说明那台机器上的代理**会尝试接管回环请求**(绕过列表并没有真正生效)。
328
+ ⇒ 结论:**"绕过列表里有 127.*"不等于绕过一定生效**(不同代理软件/浏览器解释不一致)。
329
+ 宁可让你多按一次短码,也绝不让你卡在"点了同意却没反应"。
330
+ `risk` / `loopback_bypassed` 仍在 `--json` 里**只作诊断上报**,不再作为放行回调的依据。
331
+ 3. ⭐ **自动改用设备码模式**(**默认开**,用户什么都不用做):
332
+ ```
333
+ ⚠️ 检测到系统代理(127.0.0.1:7890)。为避免“点了同意却一直收不到结果”,已自动改用【设备码模式】。
334
+ 想强制用浏览器回调模式:加 --no-auto-device,并把 127.0.0.1,localhost 加入代理绕过列表。
335
+ (检测详情:源=windows-registry 代理=127.0.0.1:7890 绕过列表=localhost,127.*,<local>;
336
+ ⚠️ 绕过列表里就算写了 127.*/localhost 也不再作为放行回调的依据 —— 真机上出现过"写了却仍被代理接管"。)
337
+ ```
338
+ 4. ⭐ **等待超时不再自动改设备码(0.2.2,老板 2026-10-21 反馈)**:
339
+ 老板原话「默认的也不应该是设备授权,默认的就是那个传统的授权方式(浏览器打开授权页 +
340
+ 本地 localhost 回调)。设备码是本地读不了/代理时才用的。」
341
+ ⇒ 没有代理时 `login` 会**一路等回调到 `--timeout`**(默认 300 秒);超时只报
342
+ `kind:"timeout"`,并在 `hint` 里给出"显式改用 `--device`"的下一步,**不会**偷偷改道。
343
+ ⚠️ 历史行为(0.2.1 及更早):有代理时"首轮等待 180 秒"到点会改设备码、整段超时也会改。
344
+ 现在这个"首轮等待"**默认关闭**:只有你**显式**写 `--callback-first-wait 90` 或
345
+ `WKONGAI_CALLBACK_FIRST_WAIT_MS=90000` 才启用(**显式优先**,`reason:"callback_first_wait"`)。
346
+ 显式启用时仍然是**两条路并存**:本地回调监听**继续保留**,**哪条先成功就用哪条** ——
347
+ 你之后才点【同意授权】照样能完成登录。旧版在切换那一刻就把监听关了,于是你之后点同意
348
+ 浏览器只会显示 **ERR_CONNECTION_REFUSED**("无法访问此网站",2026-10-03 已修);
349
+ 若设备码先成功,之后到达的回调会看到一张「本次登录已经完成」的页面。
350
+ 5. ⭐ **本地回调端口真的起不来**(防火墙/安全软件/端口非法)→ 自动兜底设备码
351
+ (`reason:"callback_listen_failed"`),**不会**直接失败退出;
352
+ **换票失败、用户点了拒绝这类"已经走到下一步"的错误不会降级**(避免让你白做一遍)。
353
+ 6. **不想被自动改道**:加 `--no-auto-device`,或设 `WKONGAI_AUTO_DEVICE=0`。
354
+ ⚠️ 此时 CLI 会**明确警告**"若代理会接管 127.0.0.1,点了【同意授权】也收不到结果",
355
+ 并且**关掉**第 4 条的自愈与第 5 条的端口兜底(你要求只走回调,就不会背着你偷偷改道)。
356
+ 7. **排障入口**:`wkgeo config` 会直接打印本机代理情况与结论(`--json` 里是
357
+ `data.proxy` / `meta.proxy_warning`),支持同学让用户跑这一条就能判断。
358
+
359
+ `--json` 里的结构化字段(AI 端据此判断"是不是代理的锅、该让用户做什么"):
360
+
361
+ ```jsonc
362
+ "proxy_warning": {
363
+ // ★ callback_may_fail 现在**等价于 detected**(与绕过列表无关)
364
+ "detected": true, "callback_may_fail": true, "loopback_bypass_trusted": false,
365
+ // 下面两个只作诊断(如实反映"绕过列表写了什么",但不影响是否降级)
366
+ "risk": false, "loopback_bypassed": true,
367
+ "platform": "win32", "proxy": "127.0.0.1:7890", "source": "windows-registry",
368
+ "bypass": ["localhost", "127.*", "<local>"],
369
+ // 诊断用:哪些来源"看起来没有绕过回环"(旧口径的判定依据,现在只作参考)
370
+ "risky_sources": [],
371
+ "actions": [
372
+ { "type": "use_device_code", "label": "改用设备码模式(不需要本地回调,推荐)", "command": "wkgeo login --device" },
373
+ { "type": "bypass_loopback", "label": "把 127.0.0.1,localhost 加进代理绕过列表(想继续用浏览器回调模式时;注意它不保证生效)" },
374
+ { "type": "disable_proxy", "label": "临时关闭代理后重试" }
375
+ ]
376
+ }
377
+ ```
378
+
379
+ 失败时的 `error.hint` 里也会带上同样的三选一(例如回调超时的 JSON 错误信封里,
380
+ `meta.proxy_warning` 依然在)。
381
+
382
+ > ★ **0.2.2 兼容字段**:`data.auto_device` 形状**不变**(`{applied, reason}`),`mode` 仍是
383
+ > `"callback"` / `"device"`,**没有删除任何既有字段**。`reason` 现在只会是:
384
+ > `"proxy_detected"`(检测到代理)/ `"callback_listen_failed"`(本地端口起不来)/
385
+ > `"callback_first_wait"`(仅用户显式 `--callback-first-wait` 时)/ `null`。
386
+ > 历史取值 `"callback_timeout"` **不再产生**(0.2.2 起超时不改道;老脚本把它当"回调失败后的
387
+ > 设备码兜底"读到的语义不变)。
388
+
389
+ > ⚠️ 两个容易误读的点:
390
+ > 1. **CLI 自己的出网不受系统代理影响**:Node 的 fetch(undici)默认既不读系统代理、
391
+ > 也不读 `HTTP_PROXY`(要 Node ≥ 24 的 `--use-env-proxy` / `NODE_USE_ENV_PROXY=1`)。
392
+ > 我们检测代理是**为了浏览器那一侧的回调**,不是去改 CLI 的网络行为。
393
+ > 2. **PAC 只能保守判定**:绕过规则写在自动配置脚本里,零依赖无法求值,所以命中 PAC 时
394
+ > 一律按"有风险"处理(代价只是一次设备码授权,仍然顺畅)。
395
+
396
+ ---
397
+
398
+ ## 4. 命令表
399
+
400
+ > 记法:`<必填>` / `[可选]`。所有命令都支持 `--json`(默认非终端下开启)、`--text`(强制人类可读)、
401
+ > `--base <url>`、`--client-id <id>`、`--credentials <path>`、`--verbose`。
402
+ > **任何命令都不会打印令牌**。
403
+ > 带单位的通用参数:`--timeout <秒>`(默认秒,支持 `600s` / `500ms`)、`--http-timeout <毫秒>`。
404
+
405
+ | 命令 | 作用 | 关键参数 |
406
+ | --- | --- | --- |
407
+ | `login` | 授权一次,令牌存本地(**默认浏览器回调**;设备码仅兜底) | `--device`、`--no-wait`、`--device-continue`、`--auto-device`/`--no-auto-device`、`--callback-first-wait <秒>`(可选,默认关闭)、`--no-browser`、`--open-browser`、`--scope`、`--callback-port`、`--timeout <秒>` |
408
+ | `whoami` | 当前登录的是谁(账号标识) | `--verbose`(额外显示令牌**掩码**与文件权限) |
409
+ | `logout` | 删本地凭据(默认还调服务端吊销) | `--local-only` |
410
+ | `auth status` | **令牌体检**:调 `cliWhoami` 打印账号 ID / `client_id` / `scopes` / 到期时间 + **CLI 动作面**(`action_total` 合计、原生/自持/转发各自条数、9 个动作清单原样透出) | `--verbose`(令牌**掩码** + 凭据文件权限) |
411
+ | `auth token` | 本地令牌的**前 4 位 + 长度 + 到期时间**(足够确认"换没换过/有没有被截断",抄不走令牌) | — |
412
+ | `auth revoke` | **立刻作废**:`POST /api/oauth/revoke` 服务端吊销 + 删本地凭据;服务端失败会如实说(令牌到期也会自动失效) | `--local-only`(只删本地,不调服务端) |
413
+ | `config` | 显示生效配置与登录状态(无令牌) | — |
414
+ | `sites list` | **站点管理入口**:默认只看**我名下的站**;没站会引导建站,有站会让你选一个来管理(写本地 config,等同 `site use`) | `--mine`(默认)、`--managed`、`--all`、`--limit`、`--offset`、`--with-prefix`(逐站补短域 / 开通状态,多个站会多打几次 `getSite`) |
415
+ | `sites get` | 单站详情(只读):短域 / 存储位 / 开通状态 / 地区 / ESA / 证书 / 计费池 / 归属;`--json` 的 `data.detail` 是后端 `getSite` 原样字段(只剔除 `settings` 等 5 个大 JSON 块) | `<站点ID>` |
416
+ | `sites create` | 建站(**建在令牌所属用户名下**)。`--channel auto`(默认)先走 CMS 通道、明确不支持才回退平台;`--json` 的 `data.channel` 标明实际通道 | `--name`(必填)、`--channel auto\|platform\|cms`、`--template`、`--domain`(**只登记,不触发解析/证书**;不能与 `--channel cms` 同用) |
417
+ | `sites delete` | 删站(服务端是**软删除**,进回收站) | `<站点ID>` |
418
+ | `site use` | **选中要操作的站点**(本地记住,之后的 CMS 命令都带它;不给参数 = 看当前是哪个) | `<站点ID或域名>`、`--clear` |
419
+ | `categories list` | 栏目列表(树序) | — |
420
+ | `categories get` | 单个栏目详情(含栏目正文、父栏目字段) | `<栏目ID\|slug\|path\|栏目名>` |
421
+ | `categories create` | 新建栏目 | `--name`(必填)、`--parent`、`--kind channel\|list\|page`、`--slug`、`--status`、`--sort`、`--icon`、`--link-url`、`--link-category`、`--link-plugin`、`--link-plugin-sub`、`--seo-description`、`--seo-keywords`、`--seo-jsonld`、`--sub-title`、`--cover`、`--attachments`、`--no-in-menu`、`--no-fields-enabled`、`--max-depth`、`--template-path`、`--body`/`--body-file` |
422
+ | `categories update` | 改栏目(只改给了的字段) | `<栏目>` + 上面任意字段 |
423
+ | `categories delete` | 删栏目(系统栏目/有子栏目或内容时被拒) | `<栏目>` |
424
+ | `categories bind-template` | 给栏目绑定模板 html(`--clear` = 解绑) | `<栏目>` `<模板文件>`、`--clear` |
425
+ | `contents list` | 内容列表(不含正文) | `--category`、`--status`、`--keyword`、`--page`、`--page-size`、`--sort views_desc`、`--include-children`、`--owner-page` |
426
+ | `contents get` | 单条内容详情(正文/附件/SEO/自定义字段) | `<内容ID>` |
427
+ | `contents create` | 新建内容(默认草稿) | `--title`(必填)、`--category`(必填)、`--status`、`--body`/`--body-file`、`--description`、`--keywords`、`--sub-title`、`--cover`、`--video`、`--usage`、`--attachments`、`--ext`、`--pinned`、`--sort` |
428
+ | `contents update` | 改内容(只改给了的字段) | `<内容ID>` + 上面任意字段(`--title` 也可) |
429
+ | `contents delete` | 删内容(「单页」那一页删不掉) | `<内容ID>` |
430
+ | `assets list` | 素材列表(默认只列图片;可看回收站) | `--kind`、`--keyword`、`--status normal\|deleted`、`--sort`、`--page`、`--page-size` |
431
+ | `assets upload` | 上传素材(**签名 → 直传 OSS → 登记**,CLI 不碰 AK) | `<本地文件>`、`--name` |
432
+ | `templates list` | 模板清单(默认模板 + 每个 html 的字符数) | — |
433
+ | `templates get` | 看模板源码(不给文件名 = 列清单;给了就直出源码) | `[模板文件名]` |
434
+ | `templates save` | 新建/覆盖模板 html(≤40 万字符) | `<文件名.html>` + `--file <本地文件>` 或 `--content <源码>` |
435
+ | `publish` | **发布站点**(0.5.0 起接真后端):默认 **dry-run**,只读算出会发多少页;`--confirm` 才 `cmsSitePublishStart` 并轮询 `cmsSitePublishStatus` 到终态,打印 `total/done/pagesFailed/finalizeOk` | `--site`、`--confirm`、`--cancel`、`--no-wait`、`--job <任务ID>`、`--interval`、`--wait-timeout` |
436
+ | `publish status` | 只看发布任务状态(只读、不触发发布) | `--site`、`--job` |
437
+ | `publish cancel` | 取消该站正在跑的发布任务(等同 `publish --cancel`) | `--site`、`--job` |
438
+ | `lang list` | 站点语言列表(代码 / 名称 / 是否默认 / 是否启用;需要 `site:read`) | `--site` |
439
+ | `lang save` | 保存语言:给了 `<语言ID>` 就改、没给就新建(新建需 `--code` + `--name`;**默认 dry-run**) | `[语言ID]`、`--code`、`--name`、`--default`、`--disabled`、`--confirm`、`--site` |
440
+ | `lang set-default` | 把某语言设为默认(自动取消原默认并置为启用;**默认 dry-run**) | `<语言ID>`、`--confirm`、`--site` |
441
+ | `lang delete` | 删语言(**默认语言不给删**;会连带删该语言的翻译;**默认 dry-run**) | `<语言ID>`、`--confirm`、`--site` |
442
+ | `lang toggle` | 启用 / 停用语言(默认语言不能停用;**默认 dry-run**) | `<语言ID>`、`--off`、`--confirm`、`--site` |
443
+ | `role list` | 站点角色列表(含权限明细与成员数;`permissions` 是 **CLI 内部英文码**,需要 `site:read`) | `--site` |
444
+ | `role save` | 保存站点角色:给了 `<角色ID>` 就改、没给就新建(**需要 `role:write`**;改角色**必须**带 `--permissions`,否则会清空权限;**默认 dry-run**) | `[角色ID]`、`--name`、`--description`、`--permissions`(JSON 或 `content=view,edit`)、`--confirm`、`--site` |
445
+ | `role delete` | 删角色(预置角色 403;还有成员在用回 409;**需要 `role:write`**;**默认 dry-run**) | `<角色ID>`、`--confirm`、`--site` |
446
+ | `member list` | 站点成员列表(**手机号恒为掩码** `138****8000`,不提供看明文;需要 `site:read`) | `--site` |
447
+ | `member update` | 改成员角色(只能本站角色;不能动业主 / 不能改自己;平台级字段一律 400;**默认 dry-run**) | `<用户ID>`、`--role`、`--confirm`、`--site` |
448
+ | `member remove` | 把成员移出本站(**只删成员行**,账号与别的站不受影响;**默认 dry-run**) | `<用户ID>`、`--confirm`、`--site` |
449
+ | `site info` | 公司信息(字段定义 + 当前值 + 素材;首次读会幂等补建 `cms_field` 预设字段,与后台同行为) | `--site` |
450
+ | `site info save` | 存公司信息(只改给了的字段,`version` 自增;必填/格式校验与后台一致;**默认 dry-run**) | `--company-name`、`--site-title`、`--keywords`、`--description`、`--values <JSON>`、`--confirm`、`--site` |
451
+ | `site domain-recheck` | 提交域名重新检测(只置 `next_check_at=now()`,后台 worker 下一轮跑;可只重检一个域名;**默认 dry-run**) | `[域名]`、`--confirm`、`--site` |
452
+ | `site demo-seed` | 导入行业示例内容(栏目/文章/图片/标签;按 `path`、`(栏目,slug)` 幂等,重复导入不重复建;**默认 dry-run**) | `--demo`、`--template`、`--confirm`、`--site` |
453
+ | `site demo-clear` | 清空示例内容(只回收 `is_demo` / `demo/` 前缀,**客户自建内容一律不动**;**默认 dry-run**) | `--confirm`、`--site` |
454
+ | `site sync` | 站级同步(站点表合并后是 no-op,回 `skipped=merged-into-site`;**默认 dry-run**) | `--confirm`、`--site` |
455
+ | `plugins list` | 本站插件(启用/装过/分类/模板锁;`editor` 单选互斥会提示「已停用:xxx」) | `--site` |
456
+ | `plugins access` | 插件按角色/成员的访问范围(`plugin_access`;迁移没跑时 `available:false`,按"全站可见"理解) | `--key`(可选,给就只查这一个插件)、`--site` |
457
+ | `plugins toggle` | 开关插件(`editor` 分类启用一个会自动停用同分类其它;被模板依赖的插件不给关) | `--key`(必填)、`--enable`/`--disable`、`--confirm`、`--site` |
458
+ | `plugins settings` | 存插件配置(按插件 manifest 声明的键与类型归一化,未声明的键丢掉) | `--key`(必填)、`--settings <JSON>`(必填)、`--confirm`、`--site` |
459
+ | `plugins market-list` | 插件市场(只出 `applies_to` 含 CMS、且对你可见的;带本站装没装/能不能升级) | `--category`、`--keyword`、`--installed-only`、`--paid`/`--free`、`--site` |
460
+ | `plugins install` | 装插件(幂等:装过就回 `already_installed`,不动数据、不重复计数) | `--key`(必填)、`--confirm`、`--site` |
461
+ | `plugins uninstall` | 卸插件(**只删本站那行,插件数据保留**,重装即恢复;被模板依赖的不给卸) | `--key`(必填)、`--confirm`、`--site` |
462
+ | `plugins upgrade` | 升级插件(把本站行版本改到市场当前版本;已是最新会 400) | `--key`(必填)、`--confirm`、`--site` |
463
+ | `plugins demo` | 插件演示链接(只读库里 `demo_url`,**CLI 不校验可达性**) | `--key`(必填)、`--site` |
464
+ | `logs list` | 本站操作日志(谁在哪台设备上改了什么;操作人手机号恒为掩码 `138****8000`;只读分页) | `--kind 操作\|登录\|系统`、`--page`、`--size`(10–200,默认 50)、`--site` |
465
+ | `config get` | 站点参数(读):每个参数的当前值 + 默认值 + 类型 + 选项 + 只读标记;附带允许的统计代码域名与内置 TLD 表 | `--key`(只查某个参数名或类型)、`--site` |
466
+ | `config save` | 存站点参数(只改给了的键,白名单外的键静默丢弃;`ipBlockList` 整段替换、最多 500 条;**换了统计代码就重新进「待审核」**;**默认 dry-run**) | `--set <JSON>`(必填)、`--confirm`、`--site` |
467
+ | `config review` | 审核统计代码(**双闸**:云函数要配 `REVIEW_TOKEN`、请求头要带对令牌;没配回 503「审核接口暂不可用」,令牌不对回 403;**默认 dry-run**) | `--pass`/`--reject` 二选一、`--reason`、`--review-token`(必填)、`--confirm`、`--site` |
468
+ | `config capabilities` | 本站能用哪些后台能力(会员插件是否启用、有没有可用支付通道,取不到给原因码) | `--site` |
469
+ | `overview summary` | 站点概览(栏目数、内容/已发布/草稿、素材数量与容量、分语言统计、本月上传) | `--lang`、`--site` |
470
+ | `overview traffic` | 账号级流量与费用(**只给平台管理员**,其他人 403;账单 1 小时缓存,`--refresh` 强制重取;单位为 GB 与元) | `--refresh`、`--site` |
471
+ | `overview dashboard` | 数据看板快照(每日 01:00 快照:存储、流量、费用、额度、下一次统计日期;非平台管理员看不到账号级流量与费用,会给 `account_restricted` 说明) | `--site` |
472
+ | `forms list` | 本站表单(字段、提交数、未读数) | `--site` |
473
+ | `forms entries` | 表单提交记录(**默认脱敏**:手机/邮箱/IP/浏览器标识) | `--form`、`--status new\|read`、`--keyword`、`--page`、`--page-size`、`--raw --confirm` |
474
+ | `domain inspection` | 域名巡检结果(只读;需「系统管理员」权限,403 给人话) | `--site`(多站账号必须带,等价 `x-cms-site`)、`--keyword`、`--status pending\|resolved\|verified\|failed\|timeout`、`--page`、`--page-size`、`--scope all` |
475
+ | `domain bind` | **绑自有域名**(原生动作 `cliProvisionSiteDomain`,免 OAuth 的 428 短信二次验证):成功只表示"受理开通",`provision_state` 一般是 `provisioning`,进度看 `domain status`。**平台侧通道没开时上游回 503** ⇒ 打印「域名开通通道暂不可用(平台侧未开),本次未写入,可直接重试」并 `exit 1`(**不假装成功**) | `<域名>`(必填)、`--site` |
476
+ | `domain status` | 域名开通状态(只读):`provision_state` / 步骤 / ESA / 证书 / 离线原因 / `last_error` / 尝试次数 / 客户待办(要加的 TXT、CNAME)/ 日志末 5 条 | `--site` |
477
+ | `domain records` | 已绑域名的解析记录与验证状态(只读):每域 TXT / CNAME / 证书 / ESA;没绑域名时给后端 `hint` | `--site` |
478
+ | `domain dns` | 把解析记录按「**客户自己去域名商加**」的格式打出来:主机记录(RR) / 类型 / 记录值(Value) / 状态(只读,**CLI 不加 DNS**) | `--site` |
479
+ | `domain check` | 域名可注册性(只读;一次 1~10 个,429 = 查太快被限流) | `<域名…>`(必填) |
480
+ | `domain remind` | 域名到期提醒(只读;需**平台管理员**,403 → `exit 3` 人话) | `--limit`(1~200,默认 50) |
481
+ | `preview` | 拼预览地址(`https://wkgeo.com/cms/preview/<站点ID>/<路径>`,**零后端**) | `<路径>`、`--site`、`--open` |
482
+ | `import-v2 start` | 从老网站导入内容 v2(**默认 dry-run**;`--confirm` 才提交) | `--url`(必填)、`--confirm`、`--max-pages`、`--list-limit`、`--news-limit`、`--other-list-limit`、`--overwrite`、`--no-search` |
483
+ | `import-v2 status` | 看导入 v2 任务进度(只读) | `--run`(必填) |
484
+ | `ai ping` | 检查本机模型端点能不能用(列可用模型;**不打印 Key**) | `--base-url`、`--model` |
485
+ | `ai ask` | 问本机大模型一个站点问题(CLI 现场取数 + 脱敏后喂模型) | `<问题>`(必填)、`--context`、`--site`、`--model`、`--base-url` |
486
+ | `ai chat` | 与本机大模型多轮对话(非 TTY / `--json` 自动退化成一次问答) | `--context`、`--site`、`--model`、`--base-url` |
487
+ | `context export` | 把站点上下文导成 JSON/Markdown 给任意模型吃(**不外传**) | `--site`、`--out <文件>`、`--format json\|md`、`--with-body`、`--context` |
488
+ | `import` | 老站导入(**默认 dry-run**;走本机运维脚本,需运维权限) | `--url`(必填)、`--apply`、`--site`、`--status`、`--out`、`--max-pages`、`--delay`、`--include`、`--exclude`、`--overwrite`、`--no-probe` |
489
+ | `wallet` | 余额 + 最近流水 | `--limit`、`--entitlements` |
490
+ | `wallet txns` | 钱包流水(普通用户自己的那份) | `--limit` |
491
+ | `wallet recharge` | **充值下单**:返 `code_url` + **`pay_url`(自家收银台页面,带订单支付令牌 `token`;★ 人类终端默认自动打开,CI/非交互只输出链接;**支付成功后页面会自己关掉**)**(**不会自动扣款**) | `--amount-cents`(必填,单位分)、`--no-browser`、`--open-browser`、`--dry-run` |
492
+ | `products list` | 能买什么(找 `--product` 该填什么) | — |
493
+ | `orders create` | 下单(**余额够就当场用钱包付清**) | `--product <代码>` + `--units <份数>`,或 `--quota <键>` + `--amount <数量>`;`--allow-wechat` |
494
+ | `orders check` | 查支付结果(微信侧已付则就地履约)+ 最新余额 | `<订单ID>` |
495
+ | `orders pay` | 同上(**`orders check` 的别名**,任务表里叫 pay) | `<订单ID>` |
496
+ | `orders get` | 订单详情(翻自己的订单列表,**不触发微信查询**) | `<订单ID>`、`--max-scan` |
497
+ | `orders list` | 我的订单 | `--limit`、`--offset`、`--status` |
498
+ | `apps list` | 我授权过的应用(过期时间/最后使用/令牌数) | — |
499
+ | `apps revoke` | 一键吊销某应用的授权(**令牌立即失效**) | `<client_id>` |
500
+ | `skill` | **打印给 AI 端的操作手册**(`SKILL.md` 原文,随包分发) | `--json`(默认**纯文本原文**,不受"非终端自动 JSON"影响) |
501
+
502
+ ### 站点管理入口(`sites list`,2026-10-22 起)
503
+
504
+ `sites list` 不只是"列一下":它是**先确认身份、再决定下一步**的入口。
505
+
506
+ | 场景 | 交互终端(stdout + stdin 都是 TTY) | `--json` / 非 TTY(AI、管道) |
507
+ | --- | --- | --- |
508
+ | **没有站点** | 提示 `∅ 你还没有站点,是否现在创建一个?(Y/n)`;回车=是 → 依次问**名称 / 模板名或 ID / 地区** → 优先走 **CMS 通道** `cmsCreateSite`(CMS 站 + 平台站一次建好),只有 CMS 通道回"未知动作/400"才回退 `createSite` 并**明确提示「CMS 站点未创建」**;网络 / 401 / 429 / 5xx 不回退 | **不提问**,输出 `{"sites":[],"hint":"no_sites"}`,**exit 0**(AI 据此进入建站流程) |
509
+ | **有站点** | 列序号 → `选择要管理的站点(回车=上次)` → 写本地 config(与 `wkgeo site use` 同一条落盘路径);当前站点带 `★ 当前` 标记 | **不提问**,`data.sites` / `data.rows` 给全部站点,`data.current_site_id` 给当前选择 |
510
+
511
+ 过滤口径(**默认 `--mine`**):
512
+
513
+ | 参数 | 含义 | 请求 / 兜底 |
514
+ | --- | --- | --- |
515
+ | `--mine`(默认) | 只列 `owner_user_id = 我` 的站 | `listSites {mine:true}`;若服务端还是旧版没过滤,CLI **本地再按 owner 收窄**(`data.mine_fallback:true`) |
516
+ | `--managed` | 我拥有的 + 我参与的(协作站) | `listSites {includeManaged:true}`;服务端不认这个参数时退化为"我拥有的",协作站由 CMS 侧补上 |
517
+ | `--all` | 全部可见站点(管理员有意义;普通账号仍受 `data_scope` 限制) | 不传 `mine` / `includeManaged` |
518
+
519
+ * **CMS-only 站点也能看到**:有的站只在 `cms_site` 里(平台 `listSites` 永远查不到)。CLI 会**额外**调 CMS 侧的
520
+ `siteImportSites`("还没选站时列我能编辑的站"),按站点 id 合并去重;这类行 `source:"cms"`、`cms_only:true`,
521
+ 人类输出里标「仅 CMS」。CMS 侧这次调用失败**不影响**平台面列表(`data.cms_list_ok:false` + `cms_list_error`),
522
+ 所以"没站"的结论不会被 CMS 面故障伪造出来。
523
+ * `data.total` 是**合并后的实际条数**;分页前的服务端总数在 `data.server_total`。
524
+ * 交互提问只在"stdout 是 TTY、stdin 也是 TTY、且没有 `--json`"时发生 —— 任何一条不满足就**绝不**等键盘输入。
525
+ * **短域要显式补**:平台 `listSites` 不返回 `prefix_host`,所以列表默认那列是 `-`;加 **`--with-prefix`** 会逐站调 `getSite` 补齐(`data.prefix_enriched = {requested,filled,failed}`,站点多时多打几次接口)。
526
+ * 要看**单站全字段**用 `wkgeo sites get <站点ID>`(人读版分块打印;`--json` 的 `data.detail` 是后端 `getSite` 原样字段,只剔除 `settings`/`theme`/`layout`/`info`/`template_config` 五个大 JSON 块)。
527
+
528
+ ### 域名只读命令(`domain status|records|dns|check|remind`)
529
+
530
+ 客户自有域名这条链路的**观察窗口**。**全部只读**:CLI 不会替你加 DNS,也不会绑/解绑域名。
531
+
532
+ | 命令 | 什么时候用 | 看什么 |
533
+ | --- | --- | --- |
534
+ | `wkgeo domain status` | 「我的域名怎么还没生效」 | `provision_state` / 步骤 / ESA / 证书 / 离线原因 / `last_error` / 尝试次数;有 `customer_todo` 就列出**要加哪些 TXT / CNAME** |
535
+ | `wkgeo domain records` | 想核对每条记录验没验过 | 每域 TXT / CNAME / 证书 / ESA + `verify_checked_at` / `next_check_at`;没绑域名时原样给后端 `hint` |
536
+ | `wkgeo domain dns` | 要**照着抄**去域名商加记录 | 只打 主机记录(RR) / 类型 / 记录值(Value) / 状态(已生效 / 未生效 / 未知) |
537
+ | `wkgeo domain check <域名…>` | 买域名前探一下 | `available` + `reason`(`self` / `taken` / `platform_owned` / `invalid`);一次 1~10 个 |
538
+ | `wkgeo domain remind` | 运营查哪些域名快到期 | 30 / 7 / 1 天档位;**需平台管理员**,否则 `exit 3` |
539
+
540
+ `--site` 等价 `x-cms-site`:账号下有多站时**必须带**,否则服务端可能报「需要指定站点」。
541
+
542
+ > **短域 KV 告警**:`sites create` 之后如果后端回 `prefix_kv_written:false`,说明短域解析没写进 KV,**现在访问会 403/404**。当前 CLI 只保证**把这件事明确喊出来**(`--json` 在 stderr 的 warn 里,`data.short_domain.kv_written` 也能查);**没有** `domain repair` 命令 —— 后端也没有等价的 OAuth 可调动作,先按 `wkgeo sites get <站点ID>` 的 `prefix_host` / `prefix_kv_written` 定位,必要时重发建站。
543
+
544
+ ### 令牌体检与绑域(`auth *` / `domain bind`,2026-10-28 新增)
545
+
546
+ **令牌模型没有变**:CLI 用的就是 `wkgeo login` 拿到的 **OAuth access_token**(服务端只存 sha256 + 过期时间,TTL 30 天),**没有**"CLI 专用令牌"、也没有 `cli-token.json`。新增的三条 `auth` 命令只是把**已经有的东西**查清楚:
547
+
548
+ ```bash
549
+ wkgeo auth status # 我现在是谁 + 这个令牌在 CLI 自己的函数(wkgeo-cli-fc)里能干什么
550
+ wkgeo auth token # 只给前 4 位 + 长度 + 到期时间(完整令牌永不打印)
551
+ wkgeo auth revoke # 服务端吊销(POST /api/oauth/revoke)+ 删本地凭据
552
+ wkgeo auth revoke --local-only # 只删本地
553
+ ```
554
+
555
+ `auth status` 的 `data.action_surface` 是**动作面体检**(口径与 [`../docs/规范-CLI-通道与动作映射-20261028.md`](../docs/规范-CLI-通道与动作映射-20261028.md) 一致):
556
+
557
+ | 字段 | 含义 |
558
+ | --- | --- |
559
+ | `action_total` | 后端 `cliWhoami` 报的合计(当前 **185** 条),**原样透出** |
560
+ | `native` / `self_hosted` / `forwarded` | 原生(按 scope 过滤后的 `actions`)/ 自持(进程内重建的各批次)/ 金融面白名单转 `wkgeo-order` |
561
+ | `batches` | 自持各批 + 转发各多少条(`user` / `domain` / `ops` / `dns_credential` / `content` / `asset` / `publish` / `config_auth` / `site` / `plugin` / `console` / `finance_forwarded`) |
562
+ | `uncounted_self_hosted` | **不计入** `action_total` 的那批(目前只有域名级 DNS 凭据 4 条 —— 后端口径如此,单列出来免得看着像丢动作) |
563
+ | `consistent` | 明细加总(原生 + 自持 + 转发,**不含** `dns_credential`)与 `action_total` 是否对得上;对不上时标 `false`(服务端刚改动作表就会出现) |
564
+ | `action_lists` | 各批动作数组**原样**(agent 可直接按清单挑动作,不截断、不重排) |
565
+
566
+ `auth status --json` 里还有 `fn:"wkgeo-cli-fc"` / `via`(确认"到底打没打到自己的函数")、`token_ttl_hint`,以及 `whoami` 原始返回。
567
+
568
+ **绑自有域名**:`wkgeo domain bind <域名> --site <站点ID>`
569
+
570
+ * 后端动作是**原生 `cliProvisionSiteDomain`**(`wkgeo-cli-fc` 接,代执行 `wkgeo-domain` 的内部开通编排),不受 OAuth 「绑域要短信二次验证」的限制。
571
+ * 成功只是**受理**:`provision_state` 通常是 `provisioning`,看进度用 `wkgeo domain status`,要客户去域名商加的解析用 `wkgeo domain dns`。
572
+ * **通道依赖**:内部通道由部署侧 `DOMAIN_INTERNAL_CHANNEL_ENABLED` 控制,**当前线上仍是 `false`** ⇒ 上游回 503,CLI 打印
573
+ 「域名开通通道暂不可用(平台侧未开),本次未写入,可直接重试」并 `exit 1`(**本次没有写入任何东西,平台开通后直接重跑同一条命令**)。
574
+ * 平台自有域名(`wkgeo.com` 等)→ 403 `platform_owned_domain`(`exit 3`);站点已绑了**别的**域名 → 409(换域要先去会员中心解绑,短信二次验证,CLI 不支持)。
575
+ * **没有** `domain unbind` / `domain repair`:`/cli` 的动作面里没有等价动作(解绑只有 `releaseSiteDomain`,OAuth 下照样 428)。**"重试开通"就是再跑一次 `domain bind`**(后端幂等,同站同域重复调用会复用记录、不重置状态)。
576
+
577
+ ### CMS 命令(栏目 / 内容 / 素材 / 模板)怎么用
578
+
579
+ **三步就够**(AI 端也是这三步):
580
+
581
+ ```bash
582
+ wkgeo site use www.example.com # ① 选站(本地记住;也可每条命令加 --site <站点ID>)
583
+ wkgeo categories list # ② 看结构
584
+ wkgeo contents create --category 新闻 --title "标题" --status published --body "<p>正文</p>"
585
+ wkgeo assets upload ./banner.jpg # 传图 → 拿素材 ID → 再 --cover 挂到内容上
586
+ wkgeo templates list / get / save # 改版式(后端动作已就绪)
587
+ wkgeo publish # ③ 先 dry-run:算一下会发多少页(不写任何东西)
588
+ wkgeo publish --confirm # ④ 真发:轮询到结束,打印 total/done/pagesFailed/finalizeOk
589
+ ```
590
+
591
+ > 只属于**一个**站点的账号可以跳过 ①:不带 `x-cms-site` 时服务端会用那唯一一个成员站;
592
+ > 有多个成员站又不指定 → 报 `cms_site_required` 并教你选(不替你猜,免得改了 A 站以为改的是 B 站)。
593
+
594
+ **接口契约(写代码/排障时看这张表)**
595
+
596
+ | 项 | 值 |
597
+ | --- | --- |
598
+ | 地址 | `POST https://api.wkgeo.com/cms/<action>`(`--cms-base` / `WKONGAI_CMS_BASE` 可改;老写法 `/api/cms/<action>` 继续兼容) |
599
+ | 动作名 | 就是云函数动作表的键:`categoryList` / `categorySave` / `contentList` / `contentSave` / `assetSign` / `assetRegister` / `templateGet` / `templateFileSave` / `overview` … |
600
+ | 鉴权 | `Authorization: Bearer <OAuth 令牌>`(从本地凭据取;**不是** Cookie,也不存第二套账号) |
601
+ | 站点 | `x-cms-site: <站点ID>`(**必须是 id**;传域名会被后端当成"没指定")。**没选站时这个头不带** —— 服务端按你的成员关系判定(单站自动走、多站报 400)。body 里**不传** `site_id`(后端故意忽略) |
602
+ | 响应 | 统一信封 `{code, message, data}`,`code === 0` 才算成功(与 `/api/data` 同一个约定) |
603
+
604
+ > ✅ **认证桥已上线(2026-10-18 下午部署,已实测)**:CMS 云函数现在认
605
+ > `Authorization: Bearer <OAuth 令牌>` → 用户 → `cms_site_member`,
606
+ > **与浏览器同一套角色/权限**(额外受 OAuth scope 收紧)。
607
+ > 实测证据(只读命令、真实站点):
608
+ > * `wkgeo categories list --site <站点ID>` → `ok:true`(返回 17 个栏目);
609
+ > * `wkgeo contents list --site <站点ID> --page-size 3` → `ok:true`(`total: 6`);
610
+ > * `wkgeo publish --site <站点ID>` → `ok:true`(读到 6 条已发布);
611
+ > * 不带站点 → 服务端回 `400 这个账号有 N 个站点,请用 x-cms-site 头…` → CLI 译成 `cms_site_required`;
612
+ > * 站点 id 不存在 / 不是成员 → `403` → CLI 译成 `cms_not_member`。
613
+ >
614
+ > 桥上线后 **401 只剩一种含义:令牌无效**(过期/被吊销/客户端被停用)。此时 CLI 仍会给一段
615
+ > 两可的提示(也覆盖"旧部署没启用桥"那种情况),但正常环境下照它 ① 重新 `login` 即可:
616
+ >
617
+ > ```json
618
+ > {"ok":false,"command":"categories list","error":{
619
+ > "kind":"cms_auth","code":401,
620
+ > "message":"CMS 接口没有接受 CLI 的授权令牌(categoryList):…",
621
+ > "hint":"① 最常见的原因是令牌已过期 / 被吊销:运行 `wkgeo login` 重新授权即可;② 若刚授权仍报 401(且 `wkgeo whoami` 正常),说明服务端是**旧部署** —— 还没启用 CLI 认证桥…"},
622
+ > "meta":{"cms_base":"https://api.wkgeo.com/cms","site_file":"…\\.wkongai\\config.json"}}
623
+ > ```
624
+ >
625
+ > 退出码 **3**(与"需要授权"同一档),AI 端据此就能判断"该重新授权"。
626
+ >
627
+ > ⚠️ **升级前授权的旧令牌缺少 CMS 的 scope**(`template:read/write`、`attachment:read/write`):
628
+ > 表现是 `templates list` / `assets list` 报 `cms_scope`(403)。
629
+ > **重新 `wkgeo login` 一次即可** —— CLI 现在的默认 scope 已含这三组,客户端 `allowed_scopes` 也已放开。
630
+
631
+ **输出与安全**
632
+
633
+ * 默认人类可读表格;`--json`(非终端下自动)输出**一个** JSON 信封,`data` 里是原始字段(AI 直接用);
634
+ * `templates get <文件名>` 在人类模式下**直出模板源码**(可以 `> index.html` 存下来);
635
+ * **不打印令牌**;`assets upload` 也不打印 OSS 的 AccessKey(CLI 只拿票据,AK 只在云函数里);
636
+ * 服务端的所有约束**一条都不会被 CLI 放宽**:系统栏目只能隐藏不能删、单页内容只能改不能建、
637
+ 绑定模板必须是本站已有的 html、内容 `published` 即上线(前台是服务端按需渲染)。
638
+
639
+ ### 控制台命令(`logs` / `config` / `overview`,2026-10-29 task-92 新增)
640
+
641
+ 后台里"看日志 / 调参数 / 看概览"这三块,现在也能在命令行里做,**走的都是 `/cli` 自持通道**(不再借 CMS 会话):
642
+
643
+ ```bash
644
+ wkgeo logs list # 本站最近操作日志(分页;手机号恒为掩码)
645
+ wkgeo logs list --kind 登录 --size 100 # 只看登录日志,一页 100 条
646
+ wkgeo config get # 站点参数:当前值 / 默认值 / 类型 / 选项 / 只读标记
647
+ wkgeo config get --key statsStatus # 只关心某个参数(也可以按类型筛:--key 文本)
648
+ wkgeo config save --set '{"siteStatus":"关闭","watermarkEnabled":true}' # 默认 dry-run
649
+ wkgeo config save --set '{"siteStatus":"关闭"}' --confirm # 真发
650
+ wkgeo config review --pass --review-token "$REVIEW_TOKEN" --confirm # 审核统计代码
651
+ wkgeo config capabilities # 本站能用哪些能力(会员插件 / 支付通道)
652
+ wkgeo overview summary # 栏目 / 内容 / 素材 / 分语言 概览
653
+ wkgeo overview traffic --refresh # 账号级流量与费用(**只给平台管理员**)
654
+ wkgeo overview dashboard # 数据看板快照(存储 / 流量 / 费用 / 额度)
655
+ ```
656
+
657
+ **三条口径**(照做就不会踩坑):
658
+
659
+ 1. **写命令默认 dry-run**:`config save` / `config review` 不加 `--confirm` 只打印"将要发什么",一个写请求都不发;`--json` 时给 `{"dry_run":true,…}`。
660
+ 2. **站点必须显式**:跟其它自持命令一样用 `wkgeo site use <站点ID>` 记住,或每条加 `--site <站点ID>`;**不是你的站一律 403 `not_site_owner`**,站不存在 / 已删除回 404(文案只给 id,不泄露站名与业主)。
661
+ 3. **权限面照旧**:读(`logs list` / `config get` / `overview *` / `config capabilities`)要 `site:read`,写(`config save` / `config review`)要 `site:write`;`overview traffic` 与 `overview dashboard` 里的账号级流量/费用**只给平台管理员**(普通用户回 403,看板里对应字段是 `null` + `account_restricted` 说明)。
662
+ 4. `config review` 是**双闸**:云函数要配环境变量 `REVIEW_TOKEN`,请求头要带对 `--review-token`;没配回 503「审核接口暂不可用」,令牌不对回 403。令牌只走请求头,**不进 body、不打印、不写日志**。
663
+
664
+ > AI 类命令(`aiLogList` 等 7 条)后台功能还没做完(老板 2026-10-29),本批**没有**迁、CLI 也**不提供**对应子命令 —— 别在脚本里当它存在。
665
+
666
+ ### 「钱包余额支付」到底发生在哪一步(**别被命令名骗了**)
667
+
668
+ 服务端 `placeOrder()` 的行为是:**下单时就先用余额抵扣**,余额够就立刻 `moveWallet(-金额)` +
669
+ 履约,直接返回 `paid:true`。也就是说:
670
+
671
+ * **`orders create` 就已经完成了"用钱包支付"**(返回值里的 `paid` 说明结果);
672
+ * `orders pay` / `orders check` 只是对**未支付**的订单做"查单/收敛状态"(如微信侧已付而本地还是 pending → 就地履约);
673
+ * CLI **永远不会**自己扫微信码、也不会发起任何真实扣款;余额不足时**默认直接拒绝下单**,
674
+ 只有显式加 `--allow-wechat` 才会创建"待扫码"订单(并只打印链接)。
675
+ * ⚠️ 服务端**没有**"把余额补到一个已存在的 pending 订单上"的 action,所以 CLI 也没有这个命令
676
+ (要做需要服务端新增接口,见 §9)。
677
+
678
+ ### JSON 出入参示例
679
+
680
+ 成功(`wkgeo wallet`):
681
+
682
+ ```json
683
+ {
684
+ "ok": true,
685
+ "command": "wallet",
686
+ "data": {
687
+ "balance_cents": 10000,
688
+ "balance_text": "¥100.00",
689
+ "rows": [
690
+ { "id": 12, "kind": "pay", "kind_label": "支付", "amount_cents": -100,
691
+ "amount_text": "-¥1.00", "balance_after_cents": 9900, "balance_after_text": "¥99.00",
692
+ "order_id": "95fe2dfc-…", "remark": "加购 空间容量 1GB(余额抵扣)",
693
+ "created_at": "2026-09-30T07:29:07.1+00:00" }
694
+ ]
695
+ },
696
+ "meta": { "base": "https://api.wkgeo.com", "client_id": "wkgeo-cli",
697
+ "credentials_file": "C:\\Users\\…\\.wkongai\\credentials.json", "duration_ms": 412 }
698
+ }
699
+ ```
700
+
701
+ 失败(令牌过期):
702
+
703
+ ```json
704
+ {
705
+ "ok": false,
706
+ "command": "wallet",
707
+ "error": {
708
+ "kind": "expired",
709
+ "code": 40101,
710
+ "message": "访问令牌已过期,请重新授权",
711
+ "hint": "运行 `wkgeo login` 重新授权(浏览器里通常还有登录态,点一下同意即可)",
712
+ "retry_after": null
713
+ },
714
+ "meta": { "base": "https://…", "client_id": "wkgeo-cli", "credentials_file": "…", "duration_ms": 88 }
715
+ }
716
+ ```
717
+
718
+ ---
719
+
720
+ ## 4.9 接本地大模型(0.5.0 新增,可选)
721
+
722
+ CLI 不只是"给 AI 用的命令行"——它也能**把本站数据喂给本机跑的模型**,全程不经过任何云厂商。
723
+ 两个入口:`wkgeo ai ask`(一问一答,CLI 现场取数 + 脱敏)与 `wkgeo context export`(导出一份上下文文件,丢给任意模型)。
724
+ 完整说明、Ollama / LM Studio 两套可复制示例、"能读到哪些数据"表格见 **[`../docs/CLI-本地大模型接入.md`](../docs/CLI-本地大模型接入.md)**。
725
+
726
+ ```bash
727
+ # ① 本机起 Ollama(另开一个窗口;LM Studio 见文档)
728
+ ollama pull qwen2.5:7b && ollama serve
729
+
730
+ # ② 确认 CLI 能连上(只打模型清单,不打 Key)
731
+ wkgeo ai ping
732
+
733
+ # ③ 问一句(默认取 7 个数据域:站点/概览/栏目/内容/插件/表单/发布)
734
+ wkgeo ai ask "这个站的栏目结构有什么问题?" --site <站点ID>
735
+
736
+ # ④ 只想导一份上下文给我的模型吃
737
+ wkgeo context export --format md --out .\site-context.md
738
+ ```
739
+
740
+ **边界(写死在代码里,不是口头承诺)**:只连 `localhost` / `127.0.0.1` / `[::1]`(要连远程必须显式 `ai.allowRemote=true` 且 CLI 会警告);上下文只有 10 个数据域名,其中 `wallet`(钱包流水)、`users`(账号明细)**硬禁**,`orders`(订单明细)要 `--context orders` + `ai.allowOrders=true`;日志只记时长/模型/字符数,**不记 prompt 与回答**;导出物只写到你指定的文件,CLI **不上传任何地方**。
741
+
742
+ ---
743
+
744
+ ## 5. 错误处理速查(**照着 `hint` 做就行**)
745
+
746
+ | 服务端返回 | `kind` | 退出码 | 应该怎么做 |
747
+ | --- | --- | --- | --- |
748
+ | `code=40101` 令牌已过期 | `expired` | 3 | **重新 `login`**(不要重新输密码登录) |
749
+ | `code=40102` 令牌已被吊销 | `revoked` | 3 | **重新 `login`**;若你没主动吊销过,提醒用户去「我已授权的应用」页看看 |
750
+ | `code=401` + 文案"登录已过期"(旧版) | `unauthenticated` | 3 | 旧版分不清过期/吊销/未登录 → 一律 **重新 `login`**(CLI 会在 hint 里说明这一点) |
751
+ | HTTP 401 `invalid_token`(userinfo 等标准端点) | `revoked` / `expired` / `unauthenticated` | 3 | 同上;CLI 会**按服务端文案**细化(文案说"已被吊销"就归类 revoked) |
752
+ | `code=429` 调用过于频繁 | `rate_limited` | 4 | **等 `retry_after` 秒后重试**。⚠️ **绝对不要**引导用户重新授权(重授权解决不了限流) |
753
+ | `code=403` 权限/scope 不足 | `forbidden` | 1 | 需要该能力就 `login --scope "…"` 重新授权;若是"动钱/改权限"类动作,**只能去网页后台做** |
754
+ | `code=428` 需要二次验证 | `step_up` | 1 | 该动作要求 5 分钟内重新输密码,**OAuth 令牌永远过不了** → 网页后台操作 |
755
+ | `code=400/404` | `bad_request` / `not_found` | 1 | 参数/资源问题,`message` 是服务端原文 |
756
+ | `code≥500` | `server` | 1 | 服务端错误,保留原文;可稍后重试 |
757
+ | 连不上/超时 | `network` | 1 | 检查网络;原始 message 会原样保留(如 `getaddrinfo ENOTFOUND`) |
758
+ | 动作未登记(新功能没发版) | `not_deployed` | 1 | **服务端缺口**,不是命令用错(`apps list/revoke` 已实测可用) |
759
+ | CMS 命令:`code=401`(Bearer 令牌未被接受) | `cms_auth` | 3 | 先确认 `wkgeo whoami` 正常;**正常就说明服务端还没启用 CLI 认证桥**(令牌 → CMS 站点成员),找管理员,别反复 `login` |
760
+ | CMS 命令:网关 404 / 响应不是 JSON | `cms_unavailable` | 1 | 多半是 CMS 基址不对或云函数 `cms` 没部署;`wkgeo config` 里看 `cms_base`(`--cms-base` 可临时改) |
761
+ | CMS 命令:403「你不是该站点的成员」 | `cms_not_member` | 1 | 站点选错了 / 还没被邀请:`wkgeo site use <正确站点ID>`;协作站要 owner 先加你 |
762
+ | CMS 命令:403「只读账号不能修改…」 | `cms_readonly` | 1 | 你的站点角色是 viewer:让 owner 在后台「用户与角色」里升为 editor |
763
+ | CMS 命令:403「该令牌没有执行「X」的权限(需要 site:write)」 | `cms_scope` | 1 | 令牌 scope 不够:**重新 `wkgeo login`**(默认已含 site / template / attachment 三组)。升级前的旧令牌不会自动带上新能力 |
764
+ | CMS 命令:400「这个账号有 N 个站点,请用 x-cms-site…」 | `cms_site_required` | 1 | 多站账号必须指定站点:`wkgeo site use <站点ID>` 或本命令加 `--site <站点ID>` |
765
+ | `import`:找不到本机导入脚本 | `import_unavailable` | 1 | 只有本仓库机器上才有 `tencent/cloudbase/import-site.mjs`;或用 `WKONGAI_IMPORT_SCRIPT` 指定路径 |
766
+ | `import`:脚本非 0 退出 | `import_failed` | 1 | 看报错里的日志尾巴(url 打不开 / 目标站不存在 / 没有数据库凭证 / 触发 robots 限制);dry-run 失败不动库 |
767
+ | `publish`:任务终态是 `failed` / `partial` | `publish_failed` | 1 | 看输出的 `pages_failed` 与 `errors`(每条的 `path` + `message`);修完再 `publish --confirm`,后端是幂等的 |
768
+ | `publish`:等太久没到终态 | `publish_timeout` | 1 | 加 `--wait-timeout`,或先 `publish status` 看进度(发布本身还在跑);连不上就别重复发,后端有活跃任务会直接复用 |
769
+ | `forms`:`/form` 只认后台登录态 | `form_backend_gap` | 3 | **后端缺口**(插件函数还没接 Bearer 桥),文档见 §9.15;暂时用网页后台看表单提交 |
770
+ | `domain inspection`:403 | `domain_inspection_forbidden` | 3 | 需要「系统管理」权限 + 平台管理员或站点系统管理员;普通账号只能找管理员看 |
771
+ | `domain remind`:403 | `domain_remind_forbidden` | 3 | 只有**平台管理员**能查全平台域名到期提醒;让平台管理员跑,或到超管后台看 |
772
+ | `ai`:连不上本机模型 | `ai_unreachable` | 1 | `ollama serve` 起了吗?端口对不对(Ollama 11434 / LM Studio 1234)?`wkgeo ai ping` 先探一下 |
773
+ | `ai`:模型不存在 | `ai_not_found` | 1 | `ollama list` 看有哪些,然后 `--model` 指定,或 `ollama pull qwen2.5:7b` |
774
+ | `ai`:上下文超限 | `ai_context_too_long` | 1 | 缩 `--context`(少取几个域),或换长上下文模型;`maxContextChars` 也可调 |
775
+ | `ai`:要连非本机地址 | `ai_remote_blocked` | 1 | 默认只允许 localhost(防止数据外流);确实要连内网/远程,在 `~/.wkongai/config.json` 里设 `ai.allowRemote: true`,CLI 会打印警告 |
776
+
777
+ **所有这些错误都不会打印令牌**:错误里只带 `code` / `message` / `hint`。
778
+
779
+ ---
780
+
781
+ ## 6. 凭据文件与安全
782
+
783
+ | 项 | 事实 |
784
+ | --- | --- |
785
+ | 位置 | `~/.wkongai/credentials.json`(Windows:`%USERPROFILE%\.wkongai\credentials.json`);可用 `WKONGAI_CREDENTIALS` 或 `--credentials` 改 |
786
+ | 权限 | 目录 `0700`、文件 **`0600`**。⚠️ 这在 POSIX 上有效;**Windows 上 NTFS 的 `chmod` 基本是空操作**,实际靠用户目录 ACL 保护 —— 这点如实写明,不假装在 Windows 上也成立(`whoami --verbose` 会显示"无法判断(Windows)") |
787
+ | 内容 | `access_token` / `refresh_token` / `scope` / `expires_at` / 账号标识;写入用**原子写**(先写临时文件再 rename,避免半截 JSON) |
788
+ | 站点选择 | **另一个文件**:`<凭据目录>/config.json`(默认 `~/.wkongai/config.json`,`wkgeo site use` 写入)。它只是"操作上下文",**不含秘密**;`logout` 不会删它,重新 `login` 也不会丢 |
789
+ | 令牌 | 30 天有效(`expires_in=2592000`)。CLI **不会**自动刷新(老板口径:过期就重新授权,30 天已经够长) |
790
+ | 绝不出现明文令牌的地方 | 终端输出(含 `--verbose`,只给**掩码** `AbCdEf…(43 位)`)、错误信息、JSON 输出、日志 |
791
+ | 公共客户端 | 代码里**没有 client_secret**,只用 PKCE(`code_verifier` 只在内存里,换票后就丢) |
792
+ | 回调 | 只监听 `127.0.0.1`;`state` 每次随机并强校验 |
793
+ | 吊销 | `logout` 会调 `POST /api/oauth/revoke`;网页端「我已授权的应用」也能一键吊销(实测可用) |
794
+
795
+ > 安全提醒:凭据文件等同密码 —— **不要**把它复制到别的机器、**不要**提交进仓库、**不要**发给任何第三方。
796
+
797
+ ---
798
+
799
+ ## 7. 端到端自测(老板要亲自验的路径)
800
+
801
+ ### 路径 ① 授权登录(手机验证码那条路)
802
+
803
+ | 步骤 | 在 CLI/终端做什么 | 在浏览器看到什么 | 期望结果 |
804
+ | --- | --- | --- | --- |
805
+ | 1 | `node cli/wkgeo.mjs login`(或 `npx -y @wkgeo/cli@latest login`) | — | 终端打印授权网址,并尝试自动打开浏览器 |
806
+ | 2 | — | 若未登录 → 平台的登录页(三个页签:**账密 / 手机号登录 / 邮箱登录**)。选「手机号登录」→ 填手机号 → 点「获取验证码」→ 填收到的验证码 → 登录 | 登录成功,跳到同意页 |
807
+ | 3 | — | 同意页显示应用名「官方 CLI(命令行工具)」和将授予的能力(读取站点/管理站点/账户充值与支付) | 点「同意」 |
808
+ | 4 | — | 跳回 `http://127.0.0.1:53682/callback`,显示 **「✅ 授权成功 / 请回到终端(客户端)继续操作,本页面可以关闭了」** | **不能**是"无法访问此网站"(若有,说明 CLI 已经退出/超时 —— 请保持 `login` 在前台运行) |
809
+ | 5 | 终端显示「✅ 授权成功,已登录:<账号>」 | 关闭页面即可 | 凭据写入 `~/.wkongai/credentials.json` |
810
+
811
+ > ⚠️ 若第 4 步看到浏览器错误页:原因是**那一刻本机没有 CLI 在监听 53682**
812
+ > (比如 `login` 被 Ctrl+C、或超过 5 分钟超时)。重新 `login` 并在点到「同意」前保持它在前台即可。
813
+
814
+ ### 路径 ② 充值(生成订单 → **打开自家收银台页面** → 支付 → 余额增加)
815
+
816
+ > ⚠️ **真钱步骤,只能人工做**:CLI 只负责"创建待支付订单 + 打开我们网站的收银台页面",
817
+ > **绝不代替你付款**,自动化测试里也**绝不**跑这条路径。
818
+
819
+ | 步骤 | 命令 / 操作 | 期望结果 |
820
+ | --- | --- | --- |
821
+ | 1 | `wkgeo wallet`(记下当前余额,例如 ¥100.00) | 打印余额与流水 |
822
+ | 2 | `wkgeo wallet recharge --amount-cents 1000 --dry-run` | 只打印"将创建 ¥10.00 订单",**不产生任何订单** |
823
+ | 3 | `wkgeo wallet recharge --amount-cents 1000` | 返回 `order_id` / `code_url` / **`pay_url`**;**人类终端**下会自动在浏览器打开 `pay_url` —— 也就是我们自己的收银台 `https://pay.wkgeo.com/?order_id=…&token=…`(CI/非交互只输出链接,不弹) |
824
+ | 4 | 在**收银台页面**用手机微信扫码支付 ¥10.00(人工) | 页面自动检测到支付成功;**支付成功后页面会自动尝试关闭**(关不掉就手动关掉即可);`pay_url` 里的订单号在任何设备/浏览器打开都能看到同一笔单 |
825
+ | 5 | `wkgeo orders check <order_id>` | `paid:true` + **最新余额 = 原余额 + 1000 分** |
826
+ | 6 | `wkgeo wallet txns` | 出现一条 `kind=recharge`、金额 `+¥10.00` 的流水 |
827
+ | 7 | 网页端登录同一账号 → 钱包页 | 余额与第 5 步一致 |
828
+
829
+ > **为什么是"打开我们网站的收银台"而不是"在终端画二维码"**:
830
+ > 老板明确否掉了"本地生成一个二维码页面让别人扫"的做法 —— 充值必须走**我们网上的充值页面**。
831
+ > 终端二维码只在"浏览器确实打不开"时作为**兜底**出现(文案会写明这一点)。
832
+ > `--no-browser` 用于无桌面环境:**不打开**,`pay_url` 照常输出。
833
+ > ★ **2026-10-21 起:人类终端默认尝试弹系统浏览器;非交互/CI 只输出链接**(与 login 同一道闸门):
834
+ > * 非交互判定(同 §3.1):stdout 非 TTY / CI 环境变量 / `WKONGAI_CLI_NO_BROWSER=1`
835
+ > ⇒ `open_browser.skipped_reason = "non_interactive"`,**一个进程都不 spawn**,并提示"把收银台链接交给用户";
836
+ > * 打开成功 → `✅ 已为你打开浏览器,请在那里完成支付(微信扫码)。`;
837
+ > * 打开失败 → ⚠️ 一段**含完整收银台地址**的醒目提示(走 stderr,stdout 仍然只有机器可读 JSON);
838
+ > * `--no-browser` → `skipped_reason = "no_browser"`(最高优先级);
839
+ > * `--open-browser` 保留,但只在终端里生效(非交互仍不弹)。
840
+ >
841
+ > ★ **`pay_url` 上的 `token=`(2026-10-02 新增)**:服务端在**下单那一刻**把"这一单是谁的"
842
+ > 签成一把**只对这一单有效**的令牌(`createRechargeOrder` 返回的 `pay_token`),
843
+ > 收银台凭它就能在**没有网页登录态**的环境里读这一单的支付参数 ——
844
+ > 这正是老板要的"**以那个 token 为基础来进行支付,而不是还要他用用户名那一套**"
845
+ > (典型场景:新开的/无痕的浏览器窗口,那里通常没有登录态)。
846
+ > ⚠️ 它**只**授权"读这一单的支付参数":读不到钱包、读不到订单列表、不能下单、不能取消,
847
+ > 30 分钟(= 订单有效期)后自动失效(失效时收银台会明确说"支付链接已过期")。
848
+ > ⚠️ 老服务端没有 `pay_token` 时 `pay_url` 只有 `order_id`,那条路**仍然要求网页登录**(行为不变)。
849
+ >
850
+ > ★ **支付成功后页面会自己关掉**(老板 2026-10-02):
851
+ > 「我支付也成功了,但**支付成功之后,他也应该关闭**……**支付成功直接关闭就可以了**。那个跳也直接关闭可以了。」
852
+ > 收银台不再跳"我的订单",而是显示一屏完成态并尝试 `window.close()`;
853
+ > ⚠️ 浏览器只允许脚本关闭**由脚本打开的**窗口,所以**关不掉是常态** —— 页面上有「关闭本页」按钮兜底,
854
+ > CLI 的提示语里也会带上"没关就手动关掉即可"。
855
+
856
+ ### 路径 ③ 网页端能看到账户信息
857
+
858
+ 浏览器打开 `https://wkgeo.com/user/`(老地址 `https://user.wkgeo.com/` 同样可用)
859
+ → 登录同一账号 → 依次核对:
860
+
861
+ - **个人中心/账号信息**:邮箱或手机号、昵称与 CLI 里 `whoami` 显示的一致;
862
+ - **钱包/账单**:余额 = `wkgeo wallet` 的余额;订单列表里能看到 CLI 下的单(同一个 `订单号`);
863
+ - **站点**:`wkgeo sites create` 建的站在"我的站点"里可见,并且**归属是自己**;
864
+ - **我已授权的应用**:能看到「官方 CLI(命令行工具)」,含过期时间/最后使用时间,可一键吊销(实测可用)。
865
+
866
+ ### 路径 ④ CLI 端能查到余额 / 流水 / 订单
867
+
868
+ ```bash
869
+ wkgeo whoami # 账号标识(不显示令牌)
870
+ wkgeo wallet # 余额 + 最近流水
871
+ wkgeo wallet txns --limit 20
872
+ wkgeo orders list --limit 10
873
+ wkgeo orders get <订单ID>
874
+ wkgeo orders check <订单ID> # 顺带显示最新余额
875
+ wkgeo apps list # 我授权了哪些应用
876
+ wkgeo logout # 退出(删本地凭据 + 服务端吊销)
877
+ ```
878
+
879
+ ---
880
+
881
+ ## 8. 开发者
882
+
883
+ ```
884
+ cli/
885
+ ├── wkgeo.mjs 可执行入口(bin;薄到只剩一行调用)
886
+ ├── package.json name/bin/files/engines/scripts(无 dependencies)
887
+ ├── lib/
888
+ │ ├── cli.mjs 入口逻辑(帮助/版本/错误收口/退出码)
889
+ │ ├── runtime.mjs 运行期上下文 + 输出契约(人类/JSON 两套)
890
+ │ ├── args.mjs 手写参数解析 + 命令 spec 校验
891
+ │ ├── config.mjs 默认值/环境变量/命令行覆盖
892
+ │ ├── errors.mjs ★ 错误码 → 提示 的映射(本项目最容易出事的地方)
893
+ │ ├── credentials.mjs 凭据文件(0600/原子写)
894
+ │ ├── api.mjs /api/data + /api/oauth/* 封装
895
+ │ ├── http.mjs 超时/JSON/错误不吞
896
+ │ ├── login.mjs 本地回调授权(起服务、校验 state、换票、成功页)
897
+ │ ├── proxy.mjs ★ 系统代理检测(只读;判定"回调会不会被代理接管")
898
+ │ ├── device.mjs 设备码授权(RFC 8628:申请 / 交给用户 / 轮询三步可拆开)
899
+ │ ├── device-store.mjs ★ `--no-wait` 的待完成状态(0600,支撑 --device-continue)
900
+ │ ├── pkce.mjs verifier/S256/state
901
+ │ ├── qr.mjs 可选终端二维码(有则用、无则略)
902
+ │ ├── format.mjs 金额/掩码/脱敏/表格
903
+ │ └── commands/ 各命令实现(auth/sites/billing/orders/apps)
904
+ ├── test/*.test.mjs 离线单测(node:test,零依赖)
905
+ ├── scripts/
906
+ │ ├── e2e-site.mjs 建站全链路端到端(建站→短域→可选绑域→发布→首页 200+指纹;**默认不删站**,真跑要 --confirm)
907
+ │ ├── live-verify.mjs 真环境**可逆**端到端验证(--write 才做写操作)
908
+ │ ├── live-sql.mjs 只读 SQL 排查工具(写语句直接拒绝)
909
+ │ ├── build-zip.mjs 打 zip(自实现 ZIP 写入,零依赖)
910
+ │ └── build-exe.mjs 独立可执行方案(默认只打印,`--sea` 跑离线两步)
911
+ └── docs/设备码授权-服务端最小方案.md
912
+ ```
913
+
914
+ ```bash
915
+ cd cli
916
+ npm test # 离线单测(499 个用例,约 9 秒)
917
+ node scripts/e2e-site.mjs --help # 建站全链路脚本的用法(含参数/步骤/退出码)
918
+ node scripts/e2e-site.mjs --dry-run # 干跑:只校验参数/凭据/网关,**不建站**
919
+ node scripts/e2e-site.mjs --confirm --pool global --keep # 真建站(**留给验收**:会写一条真站点,默认不删)
920
+ node scripts/build-zip.mjs # 打 zip(带安全闸门扫描)
921
+ node scripts/live-verify.mjs # 真环境只读验证(需本机测试账号,见发布流程 §7)
922
+ node scripts/live-verify.mjs --write # 追加可逆写操作(建站→下单→支付→退款→回收,零残留)
923
+ node scripts/live-sql.mjs --sql "select …" # 只读查库(只允许 SELECT)
924
+ ```
925
+
926
+ 设备码这条路的**真环境**端到端验证在云函数测试目录(默认只读,实跑需显式开关):
927
+
928
+ ```bash
929
+ node aliyun/fc/_tests/oauth-device-live-e2e.js # 只读预检(零副作用)
930
+ $env:OAUTH_DEVICE_E2E_LIVE='1' # 实跑:造临时用户 + 真跑 CLI
931
+ $env:OAUTH_DEVICE_E2E_CONFIRM='yes-i-accept-creating-a-temp-user'
932
+ node aliyun/fc/_tests/oauth-device-live-e2e.js # 结束按 sub 全量清理并回读复核
933
+ ```
934
+
935
+ 环境变量(都有默认值,通常不用设):
936
+
937
+ | 变量 | 默认 | 说明 |
938
+ | --- | --- | --- |
939
+ | `WKONGAI_BASE` | `https://api.wkgeo.com` | API 基址(**2026-10-22 起走阿里云 FC**;旧腾讯网关可填 `https://wkongai-….ap-shanghai.app.tcloudbase.com` 临时回滚) |
940
+ | `WKONGAI_OAUTH_WEB_BASE` | `https://wkgeo.com/oauth` | **授权站**基址(同意页 / 设备码页兜底地址)。2026-10-18 域名统一到路径后默认走新路径;老地址 `https://oauth.wkgeo.com` 仍可用,回滚就把它设成老地址 |
941
+ | `WKONGAI_PAY_WEB_BASE` | `https://pay.wkgeo.com` | **收银台**基址(`pay_url` 的域名;**支付独立,路径化没动**) |
942
+ | `WKONGAI_USER_WEB_BASE` | `https://wkgeo.com/user` | **会员站**基址(登录页 / 我的订单等)。老地址 `https://user.wkgeo.com` 仍可用 |
943
+ | `WKONGAI_WEB_BASE` | 未设置 | ⚠️ **总覆盖**:设了它上面三个基址**全部**用它(联调 / 回滚用)。它**不再**指向老站 |
944
+ | `WKONGAI_CLIENT_ID` | `wkgeo-cli` | OAuth 客户端 id |
945
+ | `WKONGAI_SCOPE` | `site:read site:write billing:self` | 申请的能力 |
946
+ | `WKONGAI_CREDENTIALS` | `~/.wkongai/credentials.json` | 凭据文件路径 |
947
+ | `WKONGAI_CALLBACK_PORT` | `53682` | 本地回调端口 |
948
+ | `WKONGAI_LOGIN_TIMEOUT_MS` | `300000` | 等待授权超时(⚠️ 变量名里带 `MS`,所以这里填**毫秒**;命令行 `--timeout` 填的是**秒**) |
949
+ | `WKONGAI_CALLBACK_FIRST_WAIT_MS` | 未设置 | ★ **可选**的"首轮等待"(毫秒,**默认关闭**):只有显式设了它(或命令行 `--callback-first-wait`),这段时间没等到回调才会自动改用设备码继续(**本地回调监听会同时保留**);`0` 关闭(等价于 `--callback-first-wait 0`)。⚠️ **未设置时一律不启用**(0.2.2 起:等待超时不再自动改设备码;老板 2026-10-21:「默认的就是那个传统的授权方式」) |
950
+ | `WKONGAI_AUTO_DEVICE` | `1`(开) | 检测到系统代理时是否自动改用设备码;设 `0`/`false`/`no`/`off` 关闭(等价于 `--no-auto-device`,会打印"代理可能吃掉回调"的警告) |
951
+ | `WKONGAI_CLI_NO_BROWSER` | 未设置 | ★ **2026-10-21**:设 `1`/`true`/`yes`/`on` = **不自动打开浏览器**(`open_browser.skipped_reason = "non_interactive"`)。给"没有 CI 环境变量但确实在无浏览器环境"的容器/远程场景用 |
952
+ | `CI` / `GITHUB_ACTIONS` / `GITLAB_CI` / `JENKINS_URL` / `TF_BUILD` / `BUILDKITE` / `TEAMCITY_VERSION` | 未设置 | ★ **2026-10-21**:**存在任一即判定为非交互**(不看值)→ **不自动打开浏览器**,只输出链接/JSON |
953
+ | `NO_COLOR` | — | 设了就不上色 |
954
+
955
+ ---
956
+
957
+ ## 9. 已知缺口 / 未验证项(**不假装验证过**)
958
+
959
+ | # | 项 | 现状 | 谁来处理 |
960
+ | --- | --- | --- | --- |
961
+ | 1 | **设备码端点** | ✅ **已上线并端到端真跑通过**(2026-10-02:metadata 声明 + 申请/确认/换票/重放全绿,真 CLI 子进程 `stage:"done"`)。协议细节见 `docs/设备码授权-服务端最小方案.md`(该文档已更新为"已实现") | 已完成;回归用 `_tests/oauth-device-live-e2e.js` |
962
+ | 1b | **代理自动降级 / 默认回调** | ✅ 已实现(**检测到代理即改设备码**,不再相信绕过列表;本地回调端口起不来自动兜底)。2026-10-02 **真机翻车已复现并加固**(老板机器:绕过列表写了 `127.*` 却仍被代理接管,证据 `curl -x …7890 http://127.0.0.1:1/x` → 502)。★ 2026-10-21 **默认模式已改回传统回调**(0.2.2):**等待超时不再自动改设备码**;设备码只由①显式 `--device`②检测到代理③本地回调端口真的起不来触发;`--callback-first-wait` 变成**默认关闭**的显式可选自愈;切设备码时**保留本地回调监听**,两条路并存先到先得(旧版关掉监听 ⇒ 用户之后点【同意授权】得到 ERR_CONNECTION_REFUSED) | 已完成(单测:默认 callback / `--device` 强制 / 端口失败兜底 / `--no-auto-device` 不兜底 / 超时不改道);建议老板真机跑一次 `wkgeo login` 验收"默认就是浏览器回调" |
963
+ | 1c | **设备码页"没有完成态/不自动关"** | ⚠️ 老板 2026-10-02 反馈:点完设备码页的【同意授权】后页面**不给明确的完成态、也不自动关**,用户不知道要不要继续等。**并行改动**已在 `admin-web/src/pages/device/index.tsx` 补上终态卡片(`✅ 授权成功` + "本页面可以关闭了" + 返回首页)。本轮 CLI 侧**未改前端** | 见下面 §9.1 的补充建议(可选) |
964
+ | 2 | **错误码 40101/40102** | `/api/data` **已返回 40102**(实测"访问令牌已被吊销,请重新授权");但 `userinfo` 仍是标准 `401 invalid_token`(靠文案区分)。CLI 两条路都兼容 | 服务端(可选,统一到 40101/40102) |
965
+ | 3 | **`listMyOAuthAuthorizations.token_count` 虚高** | 该 SQL 用 `count(*)` 统计 `left join lateral unnest(t.scopes)` 后的行数 → **数的是 scope 个数,不是令牌数**(实测:1 把令牌、3 个 scope → 显示"3 把")。正确写法 `count(distinct t.access_token_hash)` | **主线程/服务端** |
966
+ | 4 | **`apps revoke` 会连带清掉同意记忆** | 服务端设计如此(避免"取消授权"变成假动作)。副作用:下次 `login` 会重新弹同意页 | 已知,接受 |
967
+ | 5 | **没有"用余额补付一个 pending 订单"的接口** | `placeOrder` 的余额抵扣只在建单那一刻发生;CLI 因此没有对应命令 | 需服务端新增 action(可选) |
968
+ | 6 | **普通用户没有独立的"我的流水分页"接口** | 只有 `getMyWallet` 自带 `limit`(无 offset/时间筛选);`adminListWalletTxns` 是管理员接口(`billing:manage`) | 服务端(可选) |
969
+ | 7 | **客户层已删除(2026-10-27)** | 建站不再需要 `customer_id`;旧 CLI 的 `--customer` 指引与「无法确定所属客户」文案随之删除,服务端错误原样透传 | 已解决 |
970
+ | 8 | **Windows 上 0600 权限无法真正生效** | NTFS 的 chmod 是空操作,靠用户目录 ACL;`whoami --verbose` 会如实说"无法判断(Windows)" | 已知 |
971
+ | 9 | **真实微信支付全流程** | 按红线**没有**跑真钱:`wallet recharge` 只用离线桩验证了请求体,真钱路径由老板手动测(§7 路径②) | 人工 |
972
+ | 10 | **exe 产物** | 只验证了 `--sea` 能生成 blob + 复制 node 壳(93MB),**没有**真装 postject 注入、也没在无 Node 机器上跑 | 需要时再做 |
973
+ | 11 | **`login` 的浏览器交互本身** | 真环境验证脚本扮演了"浏览器/同意页"的角色(调 authorize/consent),**HTML 页面本身的点击**没有被自动化覆盖(同意页由前端/另一个改动负责) | 人工(§7 路径①) |
974
+ | 12 | **CMS 认证桥(Bearer → 站点成员)** | ✅ **已上线并实测**(2026-10-18 下午):`categories list` / `contents list` / `publish` 用 Bearer + `x-cms-site` 真跑成功;多站未指定 → 400(CLI 译成 `cms_site_required`)。⚠️ 15:15 首次实测时线上还是旧函数(401 老文案),15:22 复测已通 —— 排障时先看 401 的**文案** | 已完成(后端 `resolveIdentity`) |
975
+ | 13 | **CMS 写操作 / 导入没有真接口验证** | 只读命令已真跑;**写操作**(建栏目/发内容/传素材/存模板)与**导入**没有真跑(会改数据/需数据库凭证)。它们由 66 条离线单测覆盖,**不声称已端到端验证** | 需要时人工验收(写库前先 `site use` 选对站) |
976
+ | 13b | **旧令牌缺 CMS scope** | 2026-10-18 之前授权的令牌只有 `site:read/site:write/billing:self` ⇒ `templates list` / `assets list` 报 `cms_scope`(403)。**重新 `wkgeo login` 即可**(默认 scope 与客户端 `allowed_scopes` 都已补齐) | 用户侧一次重新授权 |
977
+ | 14 | **`import` 走本机运维脚本** | 后端**没有**带鉴权的 HTTP 导入入口,CLI 调用本仓库的 `tencent/cloudbase/import-site.mjs`(`service_role` 直连库,需运维权限)。命令默认 dry-run、只增不毁;客户/AI 端不应当用它 | 后端补 HTTP 导入动作(`docs/规划-CLI与AI建站.md` §5.2) |
978
+ | 15 | **静态发布 / 客户自有域名** | ✅ **0.5.0 起可用了**:`publish` 走 `cmsSitePublishStart` → 轮询 `cmsSitePublishStatus`(`summary` 里有 `pagesFailed` / `finalizeOk`),`--cancel` / `publish cancel` 可中止;域名这块的**只读**能力已补齐:`sites get`(短域 / KV / 存储位 / 开通状态)、`domain status` / `domain records` / `domain dns`(要客户自己加的 TXT-CNAME 清单)/ `domain check`(可注册性)/ `domain remind`(到期提醒,需平台管理员)/ `domain inspection`(巡检,需「系统管理员」)。⚠️ 仍需服务端配 `INNER_PUBLISH_SECRET`,未配时后端 fail-closed 回 503(CLI 会原样报出来)。**绑域写操作 0.6.0 已接**(`domain bind` → 原生 `cliProvisionSiteDomain`);`unbind` / `repair` 仍缺后端动作,见 #16 / #17 | 后端(unbind 动作 / repair 语义) |
979
+ | 16 | **`domain bind` 的平台通道仍关着** | `wkgeo-cli-fc` 把绑域代执行交给 `wkgeo-domain` 的内部通道,线上 `DOMAIN_INTERNAL_CHANNEL_ENABLED` **目前是 false** ⇒ 上游回 503,CLI 打印「域名开通通道暂不可用(平台侧未开),本次未写入,可直接重试」并 `exit 1`。**CLI 侧没有假装成功的分支**;通道一开,同一条命令直接可用(`domain bind` 幂等) | 部署侧开开关(权限复核后) |
980
+ | 17 | **没有 `domain unbind` / `domain repair`** | `/cli` 动作面里**没有**等价动作:解绑只有 `releaseSiteDomain`(OAuth 下 428 短信二次验证,未收录);`retrySiteProvision` 的语义是"重跑一次开通"而不是"修复",**不另造命令**。等价做法:重试 = 再跑 `domain bind`(幂等);解绑 = 会员中心 →「我的授权/我的站点」自助解绑(短信二次验证) | 后端补 unbind 动作 + 权限模型 |
981
+ | 18 | **客户域自动写 DNS / 证书 / 备案** | CLI **不写** DNS(只打印要客户自己加的 TXT / CNAME 清单,见 `domain dns`);证书与 ESA 编排都在 `wkgeo-domain` 侧,CLI 只观察(`domain status` 的 `cert_status` / `esa_status`);**备案**不在 CLI 能力范围(国内加速需要客户自行备案,平台侧校验) | 平台侧;CLI 只读 |
982
+ | 19 | **平台自有域策略** | `wkgeo.com` / `wkgeo.com.cn` 等平台自有域名,CLI 绑域一律 403 `platform_owned_domain`(`exit 3`)——只有超管后台能配,CLI **故意不提供**绕过入口 | 产品策略(已定) |
983
+
984
+ ### 9.1 ⚠️ 设备码页"没有完成态 / 不自动关"(**建议改法,本轮 CLI 侧未改动**)
985
+
986
+ **现象**(老板 2026-10-02 反馈,原话:"他没有自动关…也没有说授权成功"):
987
+ 用户在**设备码页**点了【同意授权】之后,页面**既不自动关闭、也不给明确的"授权成功"终态**,
988
+ 于是用户不知道自己到底成了没有 —— 而 CLI 那边其实已经可以拿令牌了(可能已经在轮询中成功)。
989
+
990
+ **为什么 CLI 侧不能替它解决**:设备码流程里 CLI 完全不掌控那个页面(它由 `admin-web` 渲染),
991
+ CLI 只能在终端/事件流里说"已在等待你确认"。**页面本身**必须给出终态。
992
+
993
+ **现状与补充建议(本轮 CLI 侧只写建议,**没有**动前端;并行改动已加终态卡片)**:
994
+
995
+ 1. ✅(并行改动已做)**确认成功后给明确终态**:「✅ 授权成功 / 请回到客户端继续操作,本页面可以关闭了」——
996
+ 与回调模式的 `page.mjs` 成功页保持同一口径(**先确认成功再宣告**,失败要显示失败)。
997
+ 2. (建议,可选)**给一个显式的"关闭本页"按钮**:`window.close()` 只对脚本打开的窗口有效,
998
+ 所以按钮是兜底,自动关只作增强(`setTimeout` + `try/catch`,失败时按钮仍可用)。
999
+ 3. (建议,可选)**别把"轮询中"当成终态**:设备码页面只能知道"用户确认了",
1000
+ 最好补一句「如果客户端还在等待,请等它显示『授权成功』」,避免用户提前关掉终端。
1001
+ 4. 🔴 **不要在这一页回显任何令牌 / device_code**(沿用 `lib/page.mjs` 的安全底线)。
1002
+
1003
+ **验证建议**:真机跑一次 `wkgeo login --device`(或 `--no-wait` + `--device-continue`),
1004
+ 确认点完【同意授权】后页面**明确说成功**,并且用户可以一键关闭。
1005
+
1006
+ ---
1007
+
1008
+ ## 10. 常见问题
1009
+
1010
+ **Q:`npx` 每次都要下载吗?**
1011
+ A:`npx -y @wkgeo/cli@latest` 会检查并复用 npm 缓存;要长期使用建议 `npm i -g @wkgeo/cli`。
1012
+
1013
+ **Q:令牌提示过期/被吊销怎么办?**
1014
+ A:`wkgeo login` 再来一次即可 —— 浏览器里通常还有登录态,点一下「同意」就完事。**不需要**重新输密码注册。
1015
+
1016
+ **Q:提示"调用过于频繁"要不要重新登录?**
1017
+ A:**不要**。那是限流(每令牌 60/分、写操作 20/分),按 `retry_after` 等几秒就好。
1018
+
1019
+ **Q:为什么下单就直接扣钱了?**
1020
+ A:服务端设计如此:下单时余额够就直接扣款并履约(返回 `paid:true`)。这正是"钱包余额支付"最顺的形态;
1021
+ 余额不够时 CLI 会**默认拒绝下单**,避免产生一张要扫码的单。
1022
+
1023
+ **Q:`sites create` 报「站点名称不能为空」/ 其他 400?**
1024
+ A:**客户(customer)层已于 2026-10-27 删除**,建站不再需要 `--customer`,站点归属固定为令牌所属用户;
1025
+ 400 现在只剩参数问题(名称缺了、区域不合法等),按提示补参数即可。
1026
+
1027
+ **Q:`categories list` 报 401 / `cms_auth`?**
1028
+ A:认证桥**已上线**(2026-10-18 下午实测通过),所以 401 现在基本只有一种含义:**令牌无效**
1029
+ (过期 / 被吊销 / 客户端被停用)→ `wkgeo login` 重新授权即可。
1030
+ 只有当服务端还是**旧部署**(没启用 Bearer 桥)时,才会出现"`whoami` 正常、CMS 却一律 401",
1031
+ 这时才需要找管理员确认部署(CLI 侧不用改,也不用反复登录)。
1032
+
1033
+ **Q:CMS 命令报 `cms_site_required`(账号有多个站点)?**
1034
+ A:那就是"没指定站点、而你有多个成员站"——服务端不替你猜。
1035
+ 先选一次:`wkgeo site use <站点ID或域名>`(存进 `~/.wkongai/config.json`);
1036
+ 多站来回切时不必改本地记录:任意命令加 `--site <站点ID>` 只影响这一次。
1037
+ ⚠️ `--site` **只认站点 ID(uuid)**;域名请先用 `site use <域名>` 解析。
1038
+ (只属于**一个**站点的账号不用选:不带站点头时服务端会直接用那唯一一个。)
1039
+
1040
+ **Q:`assets upload` 会让我填 OSS 的 AK 吗?**
1041
+ A:**不会**。流程是"云函数签一张 10 分钟的直传票据 → CLI 按票据把文件 POST 到 OSS → 回云函数登记"。
1042
+ CLI 侧既不保存也不打印 AccessKey(和"桌面/CLI 永远拿不到 AK"同一条边界)。