@wkgeo/cli 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,37 @@
4
4
 
5
5
  ---
6
6
 
7
+ ## 1.1.1 · 2026-11-09
8
+
9
+ **默认域名 `.com` → `.cn`**:`wkgeo.com` 已无 A 记录、全面退役,CLI 默认地址全部改用 `https://wkgeo.cn`。
10
+
11
+ - `DEFAULT_OAUTH_WEB_BASE` / `DEFAULT_USER_WEB_BASE` → `https://wkgeo.cn/oauth`、`https://wkgeo.cn/user`;
12
+ 修复设备码授权页给出打不开网址的问题(旧默认 `https://wkgeo.com/oauth` 已不可访问)。
13
+ - 预览地址 → `https://wkgeo.cn/cms/preview/...`;模板预览、manifest `$id`、UA 域名同步 `.cn`。
14
+ - 兼容保留:`WKONGAI_OAUTH_WEB_BASE=https://oauth.wkgeo.com` 等旧站回滚开关仍可用。
15
+
16
+ ---
17
+
18
+ ## 未发布 · 2026-10-30(`sites create` 原语化,发版时把包版本从 1.1.0 提到 1.2.0)
19
+
20
+ **`sites create` 收口为「平台原语」:建站 → 可选装模板 → 可选发布;三来源(抓网址 / 解析文件)整块移出 CLI**(task-61)。
21
+
22
+ - `wkgeo sites create --name <站点名> [--lang zh-CN|en] [--template <模板key>] [--publish] [--dry-run] [--region domestic|overseas|global] [--json]`
23
+ → ① 平台通道 `createSite`(服务端分配池位 + 短域 + KV,归属固定为令牌所属用户);② `--template` 只认**模板市场已有 key**
24
+ (`templateMarketList` → `templateInstall` → `templateActivate`,填错 exit 2 并列出可用 key);③ `--publish` 建完就发
25
+ (`cmsSitePublishStart` + 轮询 `cmsSitePublishStatus`,非 success/partial 记失败)。
26
+ - `--json` 输出 `{ ok, siteId, name, prefixHost, url, published, lang, region, template, publish, steps, warnings }`;
27
+ `--dry-run` 只打印四步计划(**零写入**:不建站、不写库、不写 OSS、不发布)。
28
+ - 退出码:`0` 成功 / `1` 失败(池位满 409 `POOL_EXHAUSTED`、模板装失败、发布失败)/ `2` 用法错误 / `3` 需(重新)授权。
29
+ - **删除**:`--source` / `--key` / `--url` / `--file` / `--into`(三来源建站)、`--channel auto|platform|cms`、`--domain`
30
+ (只登记域名的旧语义)、`--max-pages` / `--work-dir` / `--no-design`;对应的抓取、zip/目录解析、多来源合并代码
31
+ (`parseSourceList` / `resolveSourcePlan` / `readTemplateDir` / `readTemplateZip` / `unzipEntries` / `stripSharedRoot` 等)一并删除。
32
+ 传旧参数会明确报「不认识的参数」并 exit 2。
33
+ - **来源分析不在 CLI**:从网址 / 文档生成站点是 A 侧(配 skill)的活,规范见 `docs/规范-建站三来源-20261031.md`(task-73 产出)。
34
+ - 建站失败时 hint 会带「站点已创建(<id>),可删:`wkgeo sites delete <id>`」;池位满会提示换 `--region overseas|global`。
35
+
36
+ ---
37
+
7
38
  ## 1.1.0 · 2026-10-30
8
39
 
9
40
  **新增 `template init`:一条命令把基础库从 npm 取到本地**(task-56/task-62)。
package/README.md CHANGED
@@ -232,16 +232,18 @@ wkgeo login --device-continue # 用上次保存的设备码换票(配合 -
232
232
  ```
233
233
  请在浏览器中完成授权(设备码模式,不需要任何回调地址):
234
234
 
235
- 1) 打开:https://wkgeo.com/oauth/device/?user_code=ABCD-1234
235
+ 1) 打开:https://wkgeo.cn/oauth/device/?user_code=ABCD-1234
236
236
  2) 如果页面没有自动填好短码,请输入:ABCD-1234
237
237
 
238
- 📋 可以直接复制这段发给 AI 端或转给用户:请打开 https://wkgeo.com/oauth/device/?user_code=ABCD-1234 并完成「同意授权」(短码:ABCD-1234)。
238
+ 📋 可以直接复制这段发给 AI 端或转给用户:请打开 https://wkgeo.cn/oauth/device/?user_code=ABCD-1234 并完成「同意授权」(短码:ABCD-1234)。
239
239
  ```
240
240
 
241
241
  > ★ **2026-10-18 域名统一到路径**:授权站 canonical 从 `https://oauth.wkgeo.com/` 改成
242
- > **`https://wkgeo.com/oauth/`**(老地址继续可用)。CLI 以 `WKONGAI_OAUTH_WEB_BASE` 为 canonical,
242
+ > **`https://wkgeo.cn/oauth/`**(老地址继续可用)。CLI 以 `WKONGAI_OAUTH_WEB_BASE` 为 canonical,
243
243
  > 服务端 metadata 给的授权地址只当"路径来源"用(详见 `lib/oauth-urls.mjs`);
244
244
  > 回滚只要一条环境变量:`WKONGAI_OAUTH_WEB_BASE=https://oauth.wkgeo.com`。
245
+ > ★ **2026-11-09(老板定)**:`wkgeo.com` 已无 A 记录、全面退役,默认基址统一 `.cn`
246
+ > (旧版默认 `https://wkgeo.com/oauth` 会在设备码引导页给出打不开的网址)。
245
247
 
246
248
  > ✅ 线上**已支持**这条路径(2026-10-02 实测:`metadata` 声明了 `device_authorization_endpoint`,
247
249
  > `grant_types_supported` 含 device_code,确认页 `/admin/oauth/device/` 也在)。
@@ -256,7 +258,7 @@ AI 端是**一轮一轮**工作的:一次工具调用里挂着等 10 分钟会
256
258
  # ① Agent 调用(立刻返回,进程随即退出)
257
259
  wkgeo login --device --no-wait --json
258
260
  # → {"ok":true,"command":"login","stage":"awaiting_user","user_code":"ABCD-1234",
259
- # "verification_uri":"https://wkgeo.com/oauth/device/",
261
+ # "verification_uri":"https://wkgeo.cn/oauth/device/",
260
262
  # "verification_uri_complete":"…/?user_code=ABCD-1234","paste_text":"…","expires_in":600,
261
263
  # "interval":5,"resume_command":"wkgeo login --device-continue","pending_file":"…","next_step":"…",
262
264
  # "user_action_required":"请让用户访问 … 并输入短码 ABCD-1234","no_wait":true}
@@ -295,7 +297,7 @@ wkgeo login --device-continue --json
295
297
  // 本地回调模式:第一行就给出网址,AI 可以立刻转述给用户
296
298
  // (注意 `authorize/` 的**尾斜杠**:托管侧对不带尾斜杠的目录路径会 302 且丢掉 query)
297
299
  {"ok":true,"command":"login","mode":"callback","stage":"awaiting_callback",
298
- "authorization_url":"https://wkgeo.com/oauth/authorize/?client_id=…",
300
+ "authorization_url":"https://wkgeo.cn/oauth/authorize/?client_id=…",
299
301
  "redirect_uri":"http://127.0.0.1:53682/callback",
300
302
  "user_action_required":"请让用户在浏览器中打开上面的 authorization_url,登录并点「同意」"}
301
303
  // 结束(成功)
@@ -413,8 +415,11 @@ wkgeo login --device-continue --json
413
415
  | `config` | 显示生效配置与登录状态(无令牌) | — |
414
416
  | `sites list` | **站点管理入口**:默认只看**我名下的站**;没站会引导建站,有站会让你选一个来管理(写本地 config,等同 `site use`) | `--mine`(默认)、`--managed`、`--all`、`--limit`、`--offset`、`--with-prefix`(逐站补短域 / 开通状态,多个站会多打几次 `getSite`) |
415
417
  | `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` 同用) |
418
+ | `sites create` | **建站原语**(三步,都可选):建站(平台通道分配池位 / 短域 / KV,站**建在令牌所属用户名下**)→ 装模板市场的模板 → 发布;`--json` 输出 `{ siteId, name, prefixHost, url, published }`。**来源分析不在 CLI**:不抓网址、不解析 zip/目录、不做多来源合成,见 [docs/规范-建站三来源-20261031.md](../docs/规范-建站三来源-20261031.md)(task-73 产出) | `--name`(必填)、`--lang zh-CN\|en`(默认 zh-CN)、`--template <模板key>`、`--publish`、`--dry-run`(只打印计划,零写入)、`--region domestic\|overseas\|global`(默认 domestic;池位满会提示换区) |
417
419
  | `sites delete` | 删站(服务端是**软删除**,进回收站) | `<站点ID>` |
420
+ | `sites update` | 改站点信息(目前只开放**改站名**;**默认 dry-run**,`--confirm` 才真发)。`--remark` **发不通**:服务端 `updateSite` 白名单与站点表都没有备注字段,传了会明确报缺口而不是假装成功 | `<站点ID>`、`--name`、`--confirm` |
421
+ | `sites recycle` | **回收站**:我删掉的站(软删除,可还原;非管理员只看得到自己删的) | `--limit`(1~200,默认 50)、`--offset` |
422
+ | `sites recycle restore` | 把回收站里的站还原回站点列表(**默认 dry-run**,`--confirm` 才真发;池退役/名额满 → 服务端 409 原样透传) | `<站点ID>`、`--confirm` |
418
423
  | `site use` | **选中要操作的站点**(本地记住,之后的 CMS 命令都带它;不给参数 = 看当前是哪个) | `<站点ID或域名>`、`--clear` |
419
424
  | `categories list` | 栏目列表(树序) | — |
420
425
  | `categories get` | 单个栏目详情(含栏目正文、父栏目字段) | `<栏目ID\|slug\|path\|栏目名>` |
@@ -428,10 +433,12 @@ wkgeo login --device-continue --json
428
433
  | `contents update` | 改内容(只改给了的字段) | `<内容ID>` + 上面任意字段(`--title` 也可) |
429
434
  | `contents delete` | 删内容(「单页」那一页删不掉) | `<内容ID>` |
430
435
  | `assets list` | 素材列表(默认只列图片;可看回收站) | `--kind`、`--keyword`、`--status normal\|deleted`、`--sort`、`--page`、`--page-size` |
431
- | `assets upload` | 上传素材(**签名 → 直传 OSS → 登记**,CLI 不碰 AK) | `<本地文件>`、`--name` |
436
+ | `assets upload` | 上传素材(**签名 → 直传 OSS → 登记**,CLI 不碰 AK) | `<本地文件>`、`--name`、`--role image\|css\|js\|file`(缺省按扩展名推断) |
432
437
  | `templates list` | 模板清单(默认模板 + 每个 html 的字符数) | — |
433
438
  | `templates get` | 看模板源码(不给文件名 = 列清单;给了就直出源码) | `[模板文件名]` |
434
- | `templates save` | 新建/覆盖模板 html(≤40 万字符) | `<文件名.html>` + `--file <本地文件>` 或 `--content <源码>` |
439
+ | `templates save` | 新建/覆盖模板文件(html/css/js,≤40 万字符;可用 `assets/site.css` 这种子目录路径) | `<文件名.html\|css\|js>` + `--file <本地文件>` 或 `--content <源码>` |
440
+ | `templates pull` | **把整套模板拉到本地目录**(按模板内相对路径落盘 + 生成 `template-manifest.json` 记 sha256;二进制按 base64 还原成真文件) | `--dir`(必填)、`--template <key\|id>`、`--force`、`--site` |
441
+ | `templates push` | **把本地改动推回线上模板**(逐文件比 sha256;**默认只算计划、零写请求**,`--confirm` 才写;默认不删远端) | `--dir`(必填)、`--dry-run`、`--confirm`、`--prune`、`--site` |
435
442
  | `publish` | **发布站点**(0.5.0 起接真后端):默认 **dry-run**,只读算出会发多少页;`--confirm` 才 `cmsSitePublishStart` 并轮询 `cmsSitePublishStatus` 到终态,打印 `total/done/pagesFailed/finalizeOk` | `--site`、`--confirm`、`--cancel`、`--no-wait`、`--job <任务ID>`、`--interval`、`--wait-timeout` |
436
443
  | `publish status` | 只看发布任务状态(只读、不触发发布) | `--site`、`--job` |
437
444
  | `publish cancel` | 取消该站正在跑的发布任务(等同 `publish --cancel`) | `--site`、`--job` |
@@ -478,17 +485,26 @@ wkgeo login --device-continue --json
478
485
  | `domain dns` | 把解析记录按「**客户自己去域名商加**」的格式打出来:主机记录(RR) / 类型 / 记录值(Value) / 状态(只读,**CLI 不加 DNS**) | `--site` |
479
486
  | `domain check` | 域名可注册性(只读;一次 1~10 个,429 = 查太快被限流) | `<域名…>`(必填) |
480
487
  | `domain remind` | 域名到期提醒(只读;需**平台管理员**,403 → `exit 3` 人话) | `--limit`(1~200,默认 50) |
481
- | `preview` | 拼预览地址(`https://wkgeo.com/cms/preview/<站点ID>/<路径>`,**零后端**) | `<路径>`、`--site`、`--open` |
488
+ | `preview` | 拼预览地址(`https://wkgeo.cn/cms/preview/<站点ID>/<路径>`,**零后端**) | `<路径>`、`--site`、`--open` |
482
489
  | `import-v2 start` | 从老网站导入内容 v2(**默认 dry-run**;`--confirm` 才提交) | `--url`(必填)、`--confirm`、`--max-pages`、`--list-limit`、`--news-limit`、`--other-list-limit`、`--overwrite`、`--no-search` |
483
490
  | `import-v2 status` | 看导入 v2 任务进度(只读) | `--run`(必填) |
484
491
  | `ai ping` | 检查本机模型端点能不能用(列可用模型;**不打印 Key**) | `--base-url`、`--model` |
485
492
  | `ai ask` | 问本机大模型一个站点问题(CLI 现场取数 + 脱敏后喂模型) | `<问题>`(必填)、`--context`、`--site`、`--model`、`--base-url` |
486
493
  | `ai chat` | 与本机大模型多轮对话(非 TTY / `--json` 自动退化成一次问答) | `--context`、`--site`、`--model`、`--base-url` |
487
494
  | `context export` | 把站点上下文导成 JSON/Markdown 给任意模型吃(**不外传**) | `--site`、`--out <文件>`、`--format json\|md`、`--with-body`、`--context` |
495
+ | `crawl` | **并发抓整站**(确定性爬虫、**零模型调用**):只回标题 / 正文 / 图片 / 结构信号,**不回传整页 HTML** | `<url>`(必填)、`--max-pages`、`--concurrency`、`--page-timeout`、`--min-interval`、`--no-robots`、`--out` |
488
496
  | `import` | 老站导入(**默认 dry-run**;走本机运维脚本,需运维权限) | `--url`(必填)、`--apply`、`--site`、`--status`、`--out`、`--max-pages`、`--delay`、`--include`、`--exclude`、`--overwrite`、`--no-probe` |
489
497
  | `wallet` | 余额 + 最近流水 | `--limit`、`--entitlements` |
490
498
  | `wallet txns` | 钱包流水(普通用户自己的那份) | `--limit` |
491
499
  | `wallet recharge` | **充值下单**:返 `code_url` + **`pay_url`(自家收银台页面,带订单支付令牌 `token`;★ 人类终端默认自动打开,CI/非交互只输出链接;**支付成功后页面会自己关掉**)**(**不会自动扣款**) | `--amount-cents`(必填,单位分)、`--no-browser`、`--open-browser`、`--dry-run` |
500
+ | `wallet billing` | **我的账单**:当前订阅(套餐名/期间/是否过期)+ **生效配额**(套餐内 / 加量包 / 生效合计三列,`null` = **不限量**)+ 钱包余额(只读 `getMyBilling`) | — |
501
+ | `wallet debt` | **我的欠费**:金额 / 状态(待结清 / 已逾期)/ 应缴日期 / 宽限期 / 明细(只读 `getMyDebt`;**不含还款动作**,结清走会员端) | — |
502
+ | `coupons` | **我的优惠券**:默认全部券(面额/门槛/状态/到期),`--status` 按状态筛 | `--status unused\|used\|expired`、`--page`、`--page-size` |
503
+ | `coupons --usable` | **这笔单能用的券** + 抵扣/应付预览(另一条后端动作:必须给 `--kind` 与 `--amount-cents`,缺一个就本地报错;`recharge` 不能用券) | `--usable`、`--kind subscribe\|site_renew\|quota`、`--amount-cents`(单位分,**只影响筛券与预览,不参与定价**) |
504
+ | `notify list` | **我的消息**:未读数 + 列表(未读置顶;只读 `listMyNotifications`) | `--limit`(1~50,默认 20)、`--offset` |
505
+ | `notify read` | 把一条消息标为已读(**默认 dry-run**,`--confirm` 才真发;幂等,已读过回 `updated:0`) | `<消息ID>`(**纯数字**)、`--confirm` |
506
+ | `invoices list` | **我的开票**:可开票订单(合计金额)+ 我的开票申请(状态/抬头/税号/开票时间)两张表(只读;**不含开票 / 取消开票**,那是会员端的活) | `--limit`(1~100) |
507
+ | `plans list` | **套餐目录**(四张小表):订阅套餐(含各周期价)/ 站点续费价 / 加量包套餐 / 我已买的加量包;只列在售(`status=active`) | `--no-bundles`(跳过加量包那两块,少两次请求) |
492
508
  | `products list` | 能买什么(找 `--product` 该填什么) | — |
493
509
  | `orders create` | 下单(**余额够就当场用钱包付清**) | `--product <代码>` + `--units <份数>`,或 `--quota <键>` + `--amount <数量>`;`--allow-wechat` |
494
510
  | `orders check` | 查支付结果(微信侧已付则就地履约)+ 最新余额 | `<订单ID>` |
@@ -497,6 +513,15 @@ wkgeo login --device-continue --json
497
513
  | `orders list` | 我的订单 | `--limit`、`--offset`、`--status` |
498
514
  | `apps list` | 我授权过的应用(过期时间/最后使用/令牌数) | — |
499
515
  | `apps revoke` | 一键吊销某应用的授权(**令牌立即失效**) | `<client_id>` |
516
+ | `seo audit` | 审计本地站点产物目录(13 项:title/description/keywords/canonical/OG/JSON-LD/H1/标题层级/图片 alt/内链死链/llms.txt/sitemap/robots),输出 0-100 分与问题清单 | `<dir>`(默认 `.`);恒 **exit 0**,问题看 `data.issues` 与 `data.score` |
517
+ | `seo llms` | 生成 `llms.txt`(一级/二级页面 + 一句话摘要)与 `llms-full.txt`(含正文摘录) | `<dir>`、`--confirm`(默认 dry-run 只打印)、`--base-url` |
518
+ | `seo schema` | 生成 JSON-LD,写到 `<dir>/seo/schema.<type>.jsonld`(字段从目录内容/manifest 取,缺的留空不编造) | `<dir>`、`--type organization\|website\|article\|faq\|breadcrumb`(必填)、`--page`、`--confirm`(默认只打印 JSON) |
519
+ | `seo files` | 校验 `sitemap.xml`(XML 合法、`<loc>` 非空、URL 去重)与 `robots.txt`(语法、`Sitemap:` 与 sitemap 同源);**不联网** | `<dir>`;有 error 时 **exit 1**,明细在 `error.details` |
520
+ | `geo audit` | **GEO 体检**(20 项加权合计 100):AI 爬虫策略(6 个 UA 是否显式放行 / 有没有 `Disallow: /`)、`llms.txt` 与 `llms-full.txt`、语义结构(H1 唯一 / 层级不跳级 / FAQ 区块 / ul·table 可摘取)、可提取性(答案式 description / 首段直述 / 正文长度)、实体标注(JSON-LD 类型与必填字段)、其它(lang / canonical / og / alt / 内链 / title 重复);输出 `score`+`grade`+`issues[]` | `<dir>`;**报告命令恒 exit 0**(目录不存在 exit 2、没 `.html` exit 1) |
521
+ | `geo llms` | 按目录生成 `llms.txt`(分类小节 + 每页一句话摘要 + 链接)与 `llms-full.txt`(正文全文);`--check` 只校验不写 | `<dir>`、`--check`(缺/结构不全 **exit 1**)、`--base-url`、`--confirm`(默认 dry-run 只打印) |
522
+ | `geo robots` | AI 爬虫策略:`--mode allow-ai` 生成放行段、`block-ai` 生成禁止段、`show` 只看当前 AI 规则;**托管段幂等**(`# >>> wkgeo:geo-ai >>>` 重跑整段替换,段外人工规则一字不动) | `<dir>`、`--mode allow-ai\|block-ai\|show`(必填)、`--confirm`(默认只打印 diff);非法 mode **exit 2** |
523
+ | `geo brands` | 品牌在 AI 平台上的收录/引用跟踪入口(后台 API **未就绪**)。未配置 `WKGEO_GEO_API` → `status:"not_configured"` + 接口契约,**不发任何请求**;配置了才 `GET <base>/api/geo/brands?domain=&lang=` | `--domain`、`--lang`(默认 `zh-CN`);未配置恒 exit 0;配置了却没 `--domain` → exit 2;接口错 exit 1 |
524
+ | `geo report` | GEO 综合报告:`geo audit` + 品牌段(未配置则 `brands.status="skipped"`),输出 markdown 或 json | `<dir>`、`--md`(**压过自动 JSON**,可直接 `> report.md`)、`--domain`;不写文件、不联网 |
500
525
  | `skill` | **打印给 AI 端的操作手册**(`SKILL.md` 原文,随包分发) | `--json`(默认**纯文本原文**,不受"非终端自动 JSON"影响) |
501
526
 
502
527
  ### 站点管理入口(`sites list`,2026-10-22 起)
@@ -539,7 +564,7 @@ wkgeo login --device-continue --json
539
564
 
540
565
  `--site` 等价 `x-cms-site`:账号下有多站时**必须带**,否则服务端可能报「需要指定站点」。
541
566
 
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` 定位,必要时重发建站。
567
+ > **短域 KV 告警**:建站后端若回 `prefix_kv_written:false`,说明短域解析没写进 KV,**现在访问会 403/404**。`sites create` 只保证把结果说清楚(`--json` 里有 `prefixHost` / `url`),KV 是否写成功按 `wkgeo sites get <站点ID>` 的 `prefix_host` / `prefix_kv_written` 定位;**没有** `domain repair` 命令 —— 后端也没有等价的 OAuth 可调动作,确认短域打不开就重发建站。
543
568
 
544
569
  ### 令牌体检与绑域(`auth *` / `domain bind`,2026-10-28 新增)
545
570
 
@@ -574,6 +599,42 @@ wkgeo auth revoke --local-only # 只删本地
574
599
  * 平台自有域名(`wkgeo.com` 等)→ 403 `platform_owned_domain`(`exit 3`);站点已绑了**别的**域名 → 409(换域要先去会员中心解绑,短信二次验证,CLI 不支持)。
575
600
  * **没有** `domain unbind` / `domain repair`:`/cli` 的动作面里没有等价动作(解绑只有 `releaseSiteDomain`,OAuth 下照样 428)。**"重试开通"就是再跑一次 `domain bind`**(后端幂等,同站同域重复调用会复用记录、不重置状态)。
576
601
 
602
+ ### 抓整站:`wkgeo crawl`(2026-11-01 · task-84)
603
+
604
+ **一句话**:抓老站别再「一页一次模型往返」——`crawl` 是代码并发(默认 6、上限 10)、**零模型调用**,
605
+ 只把「标题 / 正文 / 图片 / 结构信号」抓回来,**整页 HTML 在抓取器里就丢掉**(不回传,也不落盘)。
606
+
607
+ ```bash
608
+ wkgeo crawl https://old-site.com --json # 抓完直接吐结构化结果
609
+ wkgeo crawl https://old-site.com --max-pages 60 --out .tmp-build/crawl.json
610
+ wkgeo crawl https://old-site.com --concurrency 4 --page-timeout 20000 --min-interval 300
611
+ ```
612
+
613
+ | 默认 | 值 | 说明 |
614
+ | --- | --- | --- |
615
+ | `--max-pages` | 150 | 上限 2000 |
616
+ | `--concurrency` | 6 | 上限 10;**命中 429 自动降到 2**(只降不升) |
617
+ | `--page-timeout` | 15000ms | 最小 1000;**不是**全局的 `--timeout`(那个是登录回调) |
618
+ | `--min-interval` | 150ms | 同 host 两次请求的最小间隔;robots 的 `Crawl-delay` 更大时以它为准 |
619
+ | robots | 遵从 | `Disallow` 的路径不抓,记进 `failures`;只有自有站才加 `--no-robots` |
620
+
621
+ **返回**(`--json` 时在信封 `data` 里):`{ url, entry, stats, pages[], failures[] }`。
622
+ `stats` 里有并发起止/峰值、`throttled`、`pagesPerSecond`、跳过统计(重复/外站/扩展名/超深)、`robots`、`retries`、`rateLimited`;
623
+ `stats.modelCalls` **恒为 0**。`pages[]` 每项是 `{url, title, description, chars, text, markdown, images[], headings[], signals{}}`,
624
+ **没有 `html` / `bodyHtml`**。
625
+
626
+ **实测(30 页夹具站、每页 500ms TTFB、2026-11-01 本机)**:
627
+
628
+ | 并发 | 同 host 间隔 | 墙钟 | 吞吐 | 失败率 |
629
+ | --- | --- | --- | --- | --- |
630
+ | 1(串行) | 150ms | 15.34s | 1.96 页/秒 | 0% |
631
+ | 3 | 150ms | 5.82s(**2.64×**) | 5.16 页/秒 | 0% |
632
+ | 6 | 150ms | 5.28s(**2.91×**) | 5.69 页/秒 | 0% |
633
+ | 6 | 0 | 3.13s(**4.90×**) | 9.58 页/秒 | 0% |
634
+
635
+ **规矩**:抓站一律调 `wkgeo crawl --json`(或让它写 `--out`),**不要逐页抓、不要一页一次模型**;
636
+ 批量抽取按 10–20 页/次送模型,失败页再单独托底。抓完要**写进 CMS** 才走 `wkgeo import` / `wkgeo import-v2`(那条链才有三档容错与 AI 托底)。
637
+ 合规不变:只抓企业站,政府 / 教育 / 军队 / 协会域名与黑名单、内网地址会被闸门直接拒。
577
638
  ### CMS 命令(栏目 / 内容 / 素材 / 模板)怎么用
578
639
 
579
640
  **三步就够**(AI 端也是这三步):
@@ -591,11 +652,23 @@ wkgeo publish --confirm # ④ 真发:轮询到结束,打印 to
591
652
  > 只属于**一个**站点的账号可以跳过 ①:不带 `x-cms-site` 时服务端会用那唯一一个成员站;
592
653
  > 有多个成员站又不指定 → 报 `cms_site_required` 并教你选(不替你猜,免得改了 A 站以为改的是 B 站)。
593
654
 
655
+ **样式 / 脚本放哪**(页面 HTML 由服务端 cms 渲染器出,CLI 只负责把源文件传上去):
656
+
657
+ - 站点的 `assets/site.css`、`assets/site.js` 用 **`templates save`** 传(可带子目录路径,最大 40 万字符);
658
+ 图片仍走 `assets upload`(`templates save` 不收图片)。
659
+ - 发布时服务端默认把模板里的 CSS/JS **合并外链化**成 `<站点ID>/assets/css/site-<hash>.css`、
660
+ `assets/js/site-<hash>.js`,页面只留 `<link>` / `<script src>` 外链(开关 `PUBLISH_EXTERNAL_ASSETS`,置 `0` 关)。
661
+ 旧 hash 产物在发布收尾时清掉,不用 CLI 干预。
662
+ - 建站/发布后 CLI 会探一次首页,断言有 `/assets/css/site-...css`:没有只**告警**(多半是开关关了或读到旧产物),
663
+ 不中断流程;`--json` 下看 `data.asset_bundle`。
664
+ - `assets upload --role css|js|image|file` 的 role 目前只是**透传**(服务端素材表还没收这一列),
665
+ 去重与认领仍按显示名(manifest 里按 `(sha256, role)` 在本地先去一遍重)。
666
+
594
667
  **接口契约(写代码/排障时看这张表)**
595
668
 
596
669
  | 项 | 值 |
597
670
  | --- | --- |
598
- | 地址 | `POST https://api.wkgeo.com/cms/<action>`(`--cms-base` / `WKONGAI_CMS_BASE` 可改;老写法 `/api/cms/<action>` 继续兼容) |
671
+ | 地址 | `POST https://api.wkgeo.cn/cms/<action>`(`--cms-base` / `WKONGAI_CMS_BASE` 可改;老写法 `/api/cms/<action>` 继续兼容) |
599
672
  | 动作名 | 就是云函数动作表的键:`categoryList` / `categorySave` / `contentList` / `contentSave` / `assetSign` / `assetRegister` / `templateGet` / `templateFileSave` / `overview` … |
600
673
  | 鉴权 | `Authorization: Bearer <OAuth 令牌>`(从本地凭据取;**不是** Cookie,也不存第二套账号) |
601
674
  | 站点 | `x-cms-site: <站点ID>`(**必须是 id**;传域名会被后端当成"没指定")。**没选站时这个头不带** —— 服务端按你的成员关系判定(单站自动走、多站报 400)。body 里**不传** `site_id`(后端故意忽略) |
@@ -619,7 +692,7 @@ wkgeo publish --confirm # ④ 真发:轮询到结束,打印 to
619
692
  > "kind":"cms_auth","code":401,
620
693
  > "message":"CMS 接口没有接受 CLI 的授权令牌(categoryList):…",
621
694
  > "hint":"① 最常见的原因是令牌已过期 / 被吊销:运行 `wkgeo login` 重新授权即可;② 若刚授权仍报 401(且 `wkgeo whoami` 正常),说明服务端是**旧部署** —— 还没启用 CLI 认证桥…"},
622
- > "meta":{"cms_base":"https://api.wkgeo.com/cms","site_file":"…\\.wkongai\\config.json"}}
695
+ > "meta":{"cms_base":"https://api.wkgeo.cn/cms","site_file":"…\\.wkongai\\config.json"}}
623
696
  > ```
624
697
  >
625
698
  > 退出码 **3**(与"需要授权"同一档),AI 端据此就能判断"该重新授权"。
@@ -636,6 +709,62 @@ wkgeo publish --confirm # ④ 真发:轮询到结束,打印 to
636
709
  * 服务端的所有约束**一条都不会被 CLI 放宽**:系统栏目只能隐藏不能删、单页内容只能改不能建、
637
710
  绑定模板必须是本站已有的 html、内容 `published` 即上线(前台是服务端按需渲染)。
638
711
 
712
+ ### 模板改本地:`templates pull` / `templates push`(2026-11-01 老板单)
713
+
714
+ 老板 2026-11-01 定:「我不需要在线编辑那一块……如果我编辑的话,我就在我的 CLI 里面去编辑,本地电脑绑定客户端 + CLI。」
715
+ ⇒ **CMS 里点开 Monaco 改模板的入口已下线**(只藏入口,服务端 `templateFileSave` 保留),
716
+ 模板编辑改成「拉整包到本地 → 用自己的编辑器改 → 推回 → 发布」。
717
+
718
+ ```bash
719
+ wkgeo site use <站点ID> # ① 选站(或每条命令加 --site)
720
+
721
+ wkgeo templates pull --dir ./my-template # ② 拉当前启用那套到本地目录
722
+ wkgeo templates pull --dir ./tpl --template qbk-enterprise # 或指定 key / id
723
+ wkgeo templates pull --dir ./tpl --force # 目录非空(默认拒绝)
724
+
725
+ # ③ 在 ./my-template 里用你的 VS Code / Cursor / 任何编辑器改
726
+ # pages/index.html、partials/header.html、assets/style.css、template.json ……
727
+
728
+ wkgeo templates push --dir ./my-template --dry-run # ④ 只看差异:新增/改动/远端多余/未变(零写请求,exit 0)
729
+ wkgeo templates push --dir ./my-template --confirm # ⑤ 真写(逐文件 templateFileSave)
730
+ wkgeo publish --confirm # ⑥ 使改动生效(只 push 不发布,线上还是旧的)
731
+ ```
732
+
733
+ **`template-manifest.json` 长什么样**(pull 生成,push 靠它对账;**别手工改**):
734
+
735
+ ```json
736
+ {
737
+ "version": 1,
738
+ "siteId": "11111111-2222-4333-8444-555555555555",
739
+ "templateId": "tpl-1",
740
+ "key": "demo-key",
741
+ "contentHash": "<按 path 排序后对「path + sha256」再 sha256 的 64 位十六进制>",
742
+ "pulledAt": "2026-11-01T08:00:00.000Z",
743
+ "files": [
744
+ { "path": "pages/index.html", "bytes": 54, "sha256": "…", "encoding": "utf8" },
745
+ { "path": "assets/images/dot.png", "bytes": 68, "sha256": "…", "encoding": "base64" }
746
+ ]
747
+ }
748
+ ```
749
+
750
+ 要点(踩过就知道为什么这么定):
751
+
752
+ * **推的是"manifest 里那套模板"**(`templateId` 跟着走);manifest 没记 id 时才落到"当前启用"那套,
753
+ 避免 A 站拉、B 站推这种串台。
754
+ * **跨站直接拒**:push 会先比 `manifest.siteId` 与当前站(`--site` / `site use`),不一致就拒绝并让你切回去,
755
+ **一个读/写请求都不发**——防止在 B 站改 A 站的模板。
756
+ * **默认零写请求**:`push` 不加 `--confirm` 只打印计划并 **exit 2**(`error.kind = "confirm_required"`),
757
+ `--dry-run` 打印计划 **exit 0**——脚本里能区分"忘了确认"和"真失败"。
758
+ * **默认不删远端**:本地删掉的文件只算 `removed`;`--prune` 才进 `plan.willDelete`。
759
+ 服务端目前**没有删除模板文件的动作**,所以 `--prune` 只列出来 + 告警,不会真删。
760
+ * **二进制**:`png/jpg/webp/gif/ico/woff/woff2/ttf/eot/mp4…` 在 pull 时按 base64 **还原成真文件**(不是把 base64 文本写进去);
761
+ `svg` 按文本处理。但**推不上去**——服务端 `templateFileSave` 只收 `.html/.css/.js/.json`,
762
+ 图片请走 `wkgeo assets upload`(push 会在计划里标出来并报"第几个文件")。
763
+ * **安全**:路径必须过白名单(拒绝对路径 / 盘符 / 反斜杠 / `..` / `.` / 空段 / `%` / 控制字符;
764
+ 整条 ≤200 字符、单段 ≤64 字符),落盘前**再校验一次"没跑出目标目录"**;单文件上限沿用服务端 40 万字符(二进制 40 万字节)。
765
+ * **失败不半途而废**:逐文件写,失败会报「第几个文件 + 路径 + 原因」(**不打印文件正文**),已写的照写;
766
+ 只要有一个失败就**不回写 manifest 的 `contentHash/pushedAt`**,下次 push 还能算对差异。
767
+
639
768
  ### 控制台命令(`logs` / `config` / `overview`,2026-10-29 task-92 新增)
640
769
 
641
770
  后台里"看日志 / 调参数 / 看概览"这三块,现在也能在命令行里做,**走的都是 `/cli` 自持通道**(不再借 CMS 会话):
@@ -693,7 +822,7 @@ wkgeo overview dashboard # 数据看板快照(存储 / 流量
693
822
  "created_at": "2026-09-30T07:29:07.1+00:00" }
694
823
  ]
695
824
  },
696
- "meta": { "base": "https://api.wkgeo.com", "client_id": "wkgeo-cli",
825
+ "meta": { "base": "https://api.wkgeo.cn", "client_id": "wkgeo-cli",
697
826
  "credentials_file": "C:\\Users\\…\\.wkongai\\credentials.json", "duration_ms": 412 }
698
827
  }
699
828
  ```
@@ -820,7 +949,7 @@ wkgeo context export --format md --out .\site-context.md
820
949
  | --- | --- | --- |
821
950
  | 1 | `wkgeo wallet`(记下当前余额,例如 ¥100.00) | 打印余额与流水 |
822
951
  | 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/非交互只输出链接,不弹) |
952
+ | 3 | `wkgeo wallet recharge --amount-cents 1000` | 返回 `order_id` / `code_url` / **`pay_url`**;**人类终端**下会自动在浏览器打开 `pay_url` —— 也就是我们自己的收银台 `https://pay.wkgeo.cn/?order_id=…&token=…`(CI/非交互只输出链接,不弹) |
824
953
  | 4 | 在**收银台页面**用手机微信扫码支付 ¥10.00(人工) | 页面自动检测到支付成功;**支付成功后页面会自动尝试关闭**(关不掉就手动关掉即可);`pay_url` 里的订单号在任何设备/浏览器打开都能看到同一笔单 |
825
954
  | 5 | `wkgeo orders check <order_id>` | `paid:true` + **最新余额 = 原余额 + 1000 分** |
826
955
  | 6 | `wkgeo wallet txns` | 出现一条 `kind=recharge`、金额 `+¥10.00` 的流水 |
@@ -855,7 +984,7 @@ wkgeo context export --format md --out .\site-context.md
855
984
 
856
985
  ### 路径 ③ 网页端能看到账户信息
857
986
 
858
- 浏览器打开 `https://wkgeo.com/user/`(老地址 `https://user.wkgeo.com/` 同样可用)
987
+ 浏览器打开 `https://wkgeo.cn/user/`(老地址 `https://user.wkgeo.cn/` 同样可用)
859
988
  → 登录同一账号 → 依次核对:
860
989
 
861
990
  - **个人中心/账号信息**:邮箱或手机号、昵称与 CLI 里 `whoami` 显示的一致;
@@ -936,10 +1065,10 @@ node aliyun/fc/_tests/oauth-device-live-e2e.js # 结束按 su
936
1065
 
937
1066
  | 变量 | 默认 | 说明 |
938
1067
  | --- | --- | --- |
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` 仍可用 |
1068
+ | `WKONGAI_BASE` | `https://api.wkgeo.cn` | API 基址(**2026-10-22 起走阿里云 FC**;旧腾讯网关可填 `https://wkongai-….ap-shanghai.app.tcloudbase.com` 临时回滚) |
1069
+ | `WKONGAI_OAUTH_WEB_BASE` | `https://wkgeo.cn/oauth` | **授权站**基址(同意页 / 设备码页兜底地址)。2026-10-18 域名统一到路径后默认走新路径;老地址 `https://oauth.wkgeo.com` 仍可用,回滚就把它设成老地址 |
1070
+ | `WKONGAI_PAY_WEB_BASE` | `https://pay.wkgeo.cn` | **收银台**基址(`pay_url` 的域名;**支付独立**;2026-11-05 起统一 `.cn`,旧域 `.com` 由 ESA 301 过来) |
1071
+ | `WKONGAI_USER_WEB_BASE` | `https://wkgeo.cn/user` | **会员站**基址(登录页 / 我的订单等)。老地址 `https://user.wkgeo.com` 仍可用 |
943
1072
  | `WKONGAI_WEB_BASE` | 未设置 | ⚠️ **总覆盖**:设了它上面三个基址**全部**用它(联调 / 回滚用)。它**不再**指向老站 |
944
1073
  | `WKONGAI_CLIENT_ID` | `wkgeo-cli` | OAuth 客户端 id |
945
1074
  | `WKONGAI_SCOPE` | `site:read site:write billing:self` | 申请的能力 |
@@ -980,6 +1109,9 @@ node aliyun/fc/_tests/oauth-device-live-e2e.js # 结束按 su
980
1109
  | 17 | **没有 `domain unbind` / `domain repair`** | `/cli` 动作面里**没有**等价动作:解绑只有 `releaseSiteDomain`(OAuth 下 428 短信二次验证,未收录);`retrySiteProvision` 的语义是"重跑一次开通"而不是"修复",**不另造命令**。等价做法:重试 = 再跑 `domain bind`(幂等);解绑 = 会员中心 →「我的授权/我的站点」自助解绑(短信二次验证) | 后端补 unbind 动作 + 权限模型 |
981
1110
  | 18 | **客户域自动写 DNS / 证书 / 备案** | CLI **不写** DNS(只打印要客户自己加的 TXT / CNAME 清单,见 `domain dns`);证书与 ESA 编排都在 `wkgeo-domain` 侧,CLI 只观察(`domain status` 的 `cert_status` / `esa_status`);**备案**不在 CLI 能力范围(国内加速需要客户自行备案,平台侧校验) | 平台侧;CLI 只读 |
982
1111
  | 19 | **平台自有域策略** | `wkgeo.com` / `wkgeo.com.cn` 等平台自有域名,CLI 绑域一律 403 `platform_owned_domain`(`exit 3`)——只有超管后台能配,CLI **故意不提供**绕过入口 | 产品策略(已定) |
1112
+ | 20 | **站点备注(`sites update --remark`)发不通** | 服务端 `updateSite` 的字段白名单是 `name / template_id / status / settings / domain / domains / expires_at / asset_storage_mode`,**没有 `remark`**;`public.site` 表里也没有这一列(`remark` 只出现在 `wallet_txn` / `user_debt` / `invoice_request` / `site_quota_purchase` 等别的表)。白名单外的 key 会被**静默忽略** ⇒ CLI 传了也是假成功,所以 `sites update --remark` **直接报缺口**(`kind:"unsupported"`、`exit 1`、一个请求都不发)。也**没有**用 `settings.remark` 变通:`settings` 是整块覆盖,读-改-写会吞掉原有设置 | 后端加列 + 加白名单(另开任务) |
1113
+ | 21 | **`purgeSite`(彻底删站)刻意没有 CLI 命令** | 服务端只允许 `role==='owner'` 调,非 owner 会回「彻底删除只能由管理员操作;你可以把它还原回站点列表」。CLI 只给**可逆**的 `sites delete`(进回收站)与 `sites recycle restore`,不给不可逆入口 | 产品策略(已定) |
1114
+ | 22 | **开票 / 取消开票 / 优惠券核销不做** | 开票要填抬头、税号、收件信息,交互式拼字段易错且难撤销;券核销发生在下单接口内部(用 CLI 传的金额去核销等于绕过服务端的重算)。CLI 只做**只读**的 `invoices list` 与 `coupons [--usable]`,写动作留在会员端 | 有意为之 |
983
1115
 
984
1116
  ### 9.1 ⚠️ 设备码页"没有完成态 / 不自动关"(**建议改法,本轮 CLI 侧未改动**)
985
1117