@wkgeo/cli 1.1.2 → 1.1.4

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.
@@ -241,10 +241,10 @@ export const domainOrderCommand = {
241
241
  /* ============================== 云解析(真写) ============================== */
242
242
 
243
243
  const DNS_FLAGS = {
244
- domain: { type: 'string', desc: '完整域名(服务端按最长后缀找 zone,如 cli-e2e.wkago.com ⇒ zone wkago.com)' },
244
+ domain: { type: 'string', desc: '完整域名(服务端按最长后缀找 zone,如 demo.example.com ⇒ zone example.com)' },
245
245
  type: { type: 'string', desc: '记录类型:A / AAAA / CNAME / TXT / MX / SRV / CAA' },
246
246
  value: { type: 'string', desc: '记录值(CNAME 填目标域名,TXT 填文本)' },
247
- rr: { type: 'string', desc: '主机记录(不填就从域名里推:cli-e2e.wkago.com ⇒ cli-e2e)' },
247
+ rr: { type: 'string', desc: '主机记录(不填就从域名里推:demo.example.com ⇒ demo)' },
248
248
  ttl: { type: 'string', desc: 'TTL 秒(600–86400,默认 600)' },
249
249
  'record-id': { type: 'string', desc: '记录 ID(update / delete 必填,来自 domain zone list)' },
250
250
  yes: { type: 'boolean', desc: '删除必须显式确认' },
@@ -255,7 +255,7 @@ export const domainZoneListCommand = {
255
255
  summary: '列账号里某个域名的真实解析记录(自持 alidns,不是"照抄表")',
256
256
  usage: 'wkgeo domain zone list --domain <域名> [--type <类型>] [--rr <主机记录>] [--json]',
257
257
  flags: { domain: DNS_FLAGS.domain, type: DNS_FLAGS.type, rr: DNS_FLAGS.rr },
258
- examples: ['wkgeo domain zone list --domain wkago.com', 'wkgeo domain zone list --domain cli-e2e.wkago.com --type CNAME'],
258
+ examples: ['wkgeo domain zone list --domain example.com', 'wkgeo domain zone list --domain demo.example.com --type CNAME'],
259
259
  notes: ['只想看"我还该加哪几条解析"?用 `wkgeo domain dns`(那张是给客户照抄的表)。'],
260
260
  async run(ctx) {
261
261
  const { out, flags } = ctx;
@@ -290,8 +290,8 @@ export const domainZoneAddCommand = {
290
290
  usage: 'wkgeo domain zone add --domain <域名> --type <类型> --value <值> [--rr <主机>] [--ttl <秒>] [--json]',
291
291
  flags: { domain: DNS_FLAGS.domain, type: DNS_FLAGS.type, value: DNS_FLAGS.value, rr: DNS_FLAGS.rr, ttl: DNS_FLAGS.ttl },
292
292
  examples: [
293
- 'wkgeo domain zone add --domain cli-e2e.wkago.com --type CNAME --value c-cli-e2e.intl.wkgeo.com.cn',
294
- 'wkgeo domain zone add --domain _verify.wkago.com --type TXT --value "verify=abc"',
293
+ 'wkgeo domain zone add --domain demo.example.com --type CNAME --value c-demo.intl.wkgeo.com.cn',
294
+ 'wkgeo domain zone add --domain _verify.example.com --type TXT --value "verify=abc"',
295
295
  ],
296
296
  notes: [
297
297
  '写完立刻回读:**回读值不符会报 502**(这时记录可能已经写进去了,先去 `domain zone list` 看一眼,别急着重加)。',
@@ -358,7 +358,7 @@ export const domainZoneDeleteCommand = {
358
358
  summary: '删一条解析(必须 --yes;重复删是幂等的)',
359
359
  usage: 'wkgeo domain zone delete --domain <域名> --record-id <记录ID> --yes',
360
360
  flags: { domain: DNS_FLAGS.domain, 'record-id': DNS_FLAGS['record-id'], yes: DNS_FLAGS.yes },
361
- examples: ['wkgeo domain zone delete --domain cli-e2e.wkago.com --record-id 8123456 --yes'],
361
+ examples: ['wkgeo domain zone delete --domain demo.example.com --record-id 8123456 --yes'],
362
362
  notes: ['删错一条解析 = 线上事故,所以这里强制 `--yes`。'],
363
363
  async run(ctx) {
364
364
  const { out, flags } = ctx;
@@ -382,7 +382,7 @@ export const domainZoneDeleteCommand = {
382
382
  const ESA_FLAGS = {
383
383
  pool: { type: 'string', desc: '池位:id / set_code / 站点名(如 intl-1、intl.wkgeo.com.cn)' },
384
384
  site: { type: 'string', desc: '站点 id(与 --pool 二选一)' },
385
- host: { type: 'string', desc: '要接的完整域名(如 cli-e2e.wkago.com)' },
385
+ host: { type: 'string', desc: '要接的完整域名(如 demo.example.com)' },
386
386
  endpoint: { type: 'string', desc: '回源桶端点(默认复用池行 origin 记录)' },
387
387
  'record-id': { type: 'string', desc: 'ESA 回源记录 id(不填按记录名自动查)' },
388
388
  'no-cert': { type: 'boolean', desc: '不申请免费证书(只接域名)' },
@@ -419,7 +419,7 @@ export const esaRecordCommand = {
419
419
  summary: '建/改 ESA 的 S3 回源记录(同值幂等;记录名必须是单标签子域)',
420
420
  usage: 'wkgeo esa record --pool <池位> --host <域名> [--endpoint <桶端点>]',
421
421
  flags: { pool: ESA_FLAGS.pool, site: ESA_FLAGS.site, host: ESA_FLAGS.host, endpoint: ESA_FLAGS.endpoint },
422
- examples: ['wkgeo esa record --pool intl-1 --host cli-e2e.wkago.com'],
422
+ examples: ['wkgeo esa record --pool intl-1 --host demo.example.com'],
423
423
  notes: [
424
424
  '记录名 = `c-<slug>.<池域>`(单标签,ESA 的硬要求);HostPolicy 必须是 follow_origin_domain。',
425
425
  '写后回读:源站类型 / Data / HostPolicy 任何一项不符都会报错。',
@@ -450,7 +450,7 @@ export const esaHostnameCommand = {
450
450
  summary: '接 CustomHostname + 申请免费证书(幂等;100 次/小时限流,别重试)',
451
451
  usage: 'wkgeo esa hostname --pool <池位> --host <域名> [--record-id <id>] [--no-cert]',
452
452
  flags: { pool: ESA_FLAGS.pool, site: ESA_FLAGS.site, host: ESA_FLAGS.host, 'record-id': ESA_FLAGS['record-id'], 'no-cert': ESA_FLAGS['no-cert'] },
453
- examples: ['wkgeo esa hostname --pool intl-1 --host cli-e2e.wkago.com'],
453
+ examples: ['wkgeo esa hostname --pool intl-1 --host demo.example.com'],
454
454
  notes: [
455
455
  '**先有回源记录再接域名**:没回源记录也没给 --record-id 会直接 400(避免接出个黑洞)。',
456
456
  '证书是免费 DV,DNS 必须先解析到 ESA 才能签下来;签不下来不会假装成功。',
@@ -484,7 +484,7 @@ export const esaKvCommand = {
484
484
  summary: '把域名写进边缘路由 KV(`host:<域名>` → 站点目录,写后 GetKv 回读)',
485
485
  usage: 'wkgeo esa kv --host <域名> --site-id <站点id>',
486
486
  flags: { host: ESA_FLAGS.host, 'site-id': { type: 'string', desc: '站点 id(KV 的值就是它,边缘据此改写路径)' } },
487
- examples: ['wkgeo esa kv --host cli-e2e.wkago.com --site-id 8f0c…'],
487
+ examples: ['wkgeo esa kv --host demo.example.com --site-id 8f0c…'],
488
488
  notes: [
489
489
  'KV 值是**站点 id**(= 桶里的顶层目录),边缘路由器命中后把 `/<path>` 改写成 `/<siteId>/<path>`。',
490
490
  'BatchPutKv 回 200 只代表"收到",不代表生效 —— 所以这里强制 GetKv 回读,读不到就是失败。',
@@ -202,6 +202,14 @@ import {
202
202
  import { contentCheckCommand, contentFillCommand } from './content.mjs';
203
203
  /* `content apply` 本体在 `cli/lib/manifest-apply.mjs`(只管建站内容契约;模板契约那条已拆成 `content fill`) */
204
204
  import { contentApplyCommand } from '../manifest-apply.mjs';
205
+ /**
206
+ * ★ 2026-11-10(老板单「数据交换」):`data` 组 = 三类运营数据的**只读**导出。
207
+ * chat AI 客服会话 / 单会话消息(`/aikefu` → MaxKB 只读库;正文默认脱敏、IP 只给掩码);
208
+ * stats 访问统计按日 PV / UV / IP 唯一数 + Top 页面 / 来源(`/analytics` → `statRange`);
209
+ * usage 大模型消耗按日 / 模型 / 站点(`/admin` → `llmCostSummary`,需 scope `llm:cost_read`)。
210
+ * 统一参数:`--site <ID|域名>` / `--from` / `--to` / `--page` `/`--limit` / `--json|--text` / `--out <csv|json>`。
211
+ */
212
+ import { DATA_COMMANDS } from './data.mjs';
205
213
  /**
206
214
  * ★ 2026-10-30(task-4):\`seo\` 组 = **本地站点产物**的 SEO 工具,四条纯本地命令(不联网、不写库)。
207
215
  * audit 13 项加权评分 + issues[](报告命令,恒 exit 0);
@@ -238,6 +246,8 @@ export const COMMANDS = [
238
246
  contentApplyCommand,
239
247
  contentFillCommand,
240
248
  contentCheckCommand,
249
+ /* ★ 2026-11-10:数据交换三件套(chat / stats / usage,全部只读) */
250
+ ...DATA_COMMANDS,
241
251
  /* ★ task-4:本地站点产物的 SEO 工具(audit / llms / schema / files),不联网、不写库 */
242
252
  ...seoCommands,
243
253
  /* ★ task-5:本地站点产物的 GEO 工具(audit / llms / robots / brands / report),不联网、不写库 */
@@ -464,6 +474,8 @@ const GROUP_SUMMARY = {
464
474
  overview: '站点总览:栏目内容素材计数 / 账号级流量账单(仅平台管理员)/ 控制台首页快照(只读)',
465
475
  content:
466
476
  '内容原语:apply = 建站清单(site-manifest.json)落站 · fill = 模板内容契约(sections[]/pages[])填库 · check 契约↔库↔前台自检 + 9 维评分(两条写命令默认 dry-run、逐栏目 upsert、幂等、未知字段拒绝)',
477
+ data:
478
+ '数据交换(只读):chat = AI 客服会话/单会话消息(正文默认脱敏、IP 只给掩码)· stats = 按日 PV/UV/IP 唯一数 + Top 页面/来源 · usage = 按日/模型/站点的大模型请求数/token/费用(需 scope llm:cost_read);`--out` 落 CSV/JSON',
467
479
  template:
468
480
  '模板工具链:init 取基础库 / validate 契约九关 / capture 载图 / verify 像素自比 / score 评分 / anim 动画 / pack 打包 / publish 发布 / preview 预览',
469
481
  templates:
@@ -837,7 +837,9 @@ export const plansListCommand = {
837
837
  *
838
838
  * ⚠️ 只开放 `--name`(改站名)。**`--remark` 目前发不通,CLI 必须如实报缺口**:
839
839
  * 服务端 `updateSite` 的字段白名单是
840
- * `name / template_id / status / settings / domain / domains / expires_at / asset_storage_mode`
840
+ * `name / template_id / settings / domain / domains / expires_at / asset_storage_mode`
841
+ * (★ 2026-11-11 task-85:`status` 已移出白名单,显式传会回 400 `STATUS_NOT_EDITABLE`,
842
+ * 上下架走 `siteOffline` / `siteOnline`)
841
843
  * —— 没有 remark;`public.site` 表里也没有这一列(remark 只存在于 customer / wallet_txn /
842
844
  * user_debt / invoice_request / site_quota_purchase 这些别的表)。
843
845
  * 白名单外的 key 会被**静默忽略**,所以"传了就返回成功"是假成功。与其假装能改备注,
@@ -16,10 +16,11 @@
16
16
  import { camel } from '../args.mjs';
17
17
  import { CliError, EXIT, UsageError } from '../errors.mjs';
18
18
  import { maskPii, maskPiiDeep, formatTime } from '../format.mjs';
19
+ import { PLATFORM_WEB_ORIGIN } from '../hosts.mjs';
19
20
  import { openUrlForUser } from '../login.mjs';
20
21
 
21
22
  /** 表单后台函数(`wkgeo-plugin-contact-form`)认的来源;不给会被 `checkAdminOrigin` 403 */
22
- const FORM_ORIGIN = 'https://wkgeo.cn';
23
+ const FORM_ORIGIN = PLATFORM_WEB_ORIGIN;
23
24
 
24
25
  const SITE_FLAG = {
25
26
  site: { type: 'string', desc: '站点 ID(默认用 `wkgeo site use` 选中的站点,可用 WKONGAI_SITE 覆盖)' },
@@ -824,7 +825,7 @@ export const previewCommand = {
824
825
  },
825
826
  examples: ['wkgeo preview /about/', 'wkgeo preview news/2026/ --site <站点ID> --open'],
826
827
  notes: [
827
- '地址形如 `https://wkgeo.cn/cms/preview/<站点ID>/<路径>`,走预览通道:**看的是草稿态**,不影响线上。',
828
+ `地址形如 \`${PLATFORM_WEB_ORIGIN}/cms/preview/<站点ID>/<路径>\`,走预览通道:**看的是草稿态**,不影响线上。`,
828
829
  '零后端调用:只拼字符串,不产生任何写操作。',
829
830
  '`--open` 用的是系统默认浏览器;CI / 非交互环境会自动跳过(不会卡住)。',
830
831
  ],
@@ -836,7 +837,7 @@ export const previewCommand = {
836
837
  rel = rel.replace(/^https?:\/\/[^/]+/i, '');
837
838
  rel = rel.replace(/^\/+/, '');
838
839
 
839
- const url = `https://wkgeo.cn/cms/preview/${site.id}/${rel}`;
840
+ const url = `${PLATFORM_WEB_ORIGIN}/cms/preview/${site.id}/${rel}`;
840
841
  const payload = { site_id: site.id, path: `/${rel}`, url };
841
842
 
842
843
  if (!out.json) {
@@ -33,6 +33,7 @@
33
33
 
34
34
  import { CliError, UsageError } from '../errors.mjs';
35
35
  import { formatTime } from '../format.mjs';
36
+ import { SITE_PREVIEW_SUFFIX } from '../hosts.mjs';
36
37
  import { readSiteState } from '../site-state.mjs';
37
38
  import { runSiteCreate } from '../site-create.mjs';
38
39
  import { rememberSite } from './cms.mjs';
@@ -682,7 +683,7 @@ export const sitesGetCommand = {
682
683
  'wkgeo sites get <站点ID> --json # 机器可读:site + detail 全量标量字段',
683
684
  ],
684
685
  notes: [
685
- '`prefix_host` = 平台分配的短域(`<名字>.<地区>.wkgeo.com.cn`),`custom_domain` = 你自己登记的域名;**两套解析**,短域打不开不代表自有域名没配好,反之亦然。',
686
+ `\`prefix_host\` = 平台分配的站点短域(2026-11-09 起**唯一地址** = \`<slug>.${SITE_PREVIEW_SUFFIX}\`),\`custom_domain\` = 你自己登记的域名;**两套解析**,短域打不开不代表自有域名没配好,反之亦然。`,
686
687
  '`provision_state`:`none` 没进过开通流程 / `provisioning` 开通中 / `active` 已开通 / `failed` 失败;卡在哪一步看 `provision_step`。',
687
688
  '`settings` / `theme` / `layout` / `info` / `template_config` 这几个大 JSON 块**不输出**(可能存第三方 Key),要看去 CMS 后台;其余 `getSite` 字段全部在 `--json` 的 `detail` 里。',
688
689
  ],
@@ -757,7 +758,7 @@ export const sitesCreateCommand = {
757
758
  template: { type: 'string', desc: '模板市场里的模板 key(可选;不传就是空站)' },
758
759
  publish: { type: 'boolean', desc: '建完立即发布,并实测短域首页(HTTP 码 / 字节 / 标题)' },
759
760
  'dry-run': { type: 'boolean', desc: '只打印计划:不建站、不写库、不写 OSS' },
760
- region: { type: 'string', desc: '区域/池位:domestic(默认,cn1)/ overseas(intl)/ global;国内池满了换 overseas' },
761
+ region: { type: 'string', desc: `区域/池位:domestic(默认)/ overseas / global(只决定池位,站点地址恒为 <slug>.${SITE_PREVIEW_SUFFIX});国内池满了换 overseas` },
761
762
  },
762
763
  examples: [
763
764
  'wkgeo sites create --name 我的站 --lang zh-CN',
@@ -728,7 +728,7 @@ export const templateValidateCommand = {
728
728
  args: [],
729
729
  flags: {
730
730
  dir: { type: 'string', desc: '模板目录' },
731
- base: { type: 'string', desc: '_base 目录(默认自动找 templates/_base;用于 assets/base 逐字节比对)' },
731
+ base: { type: 'string', desc: '基础库目录(默认自动找 templates/base;用于 assets/base 逐字节比对)' },
732
732
  'no-design': { type: 'boolean', desc: '不要求 design/ 截图(只适合自查,pack 仍会要求)' },
733
733
  },
734
734
  examples: ['wkgeo template validate --dir ./tpl/qbk-mirror', 'wkgeo template validate --dir ./tpl/demo --json'],
@@ -783,7 +783,7 @@ export const templatePackCommand = {
783
783
  },
784
784
  examples: ['wkgeo template pack --dir ./tpl/qbk-mirror', 'wkgeo template pack --dir ./tpl/qbk-mirror --out .tmp-build/t142/qbk.zip'],
785
785
  notes: [
786
- '打包前把 `templates/_base/assets/**` 逐字节同步到 `<模板>/assets/base/`(§3 约定,validate/pack 都查)。',
786
+ '打包前把 `templates/base/assets/**` 逐字节同步到 `<模板>/assets/base/`(§3 约定,validate/pack 都查)。',
787
787
  'zip 内必有:template.json、pages/、partials/、assets/(含 assets/base/base.css)、design/*.png。',
788
788
  'zip 自己写(zlib deflateRaw + 自算 CRC32):不 npm install、不依赖外部 archiver。',
789
789
  ],
package/lib/config.mjs CHANGED
@@ -16,6 +16,7 @@ import path from 'node:path';
16
16
  import { readFileSync } from 'node:fs';
17
17
 
18
18
  import { UsageError } from './errors.mjs';
19
+ import { PLATFORM_WEB_ORIGIN } from './hosts.mjs';
19
20
 
20
21
  /**
21
22
  * 线上 API 基址(业务接口 `/api/data`、OAuth 服务端 `/api/oauth/*` 都在这个域下)。
@@ -77,9 +78,9 @@ export const DEFAULT_CMS_BASE = 'https://api.wkgeo.cn/cms';
77
78
  * ⇒ 所以统一走 `oauth-urls.mjs` 的 `canonicalOauthUrl()`:
78
79
  * **这里(配置基址)是 canonical,服务端只提供路径**。
79
80
  */
80
- export const DEFAULT_OAUTH_WEB_BASE = 'https://wkgeo.cn/oauth';
81
+ export const DEFAULT_OAUTH_WEB_BASE = `${PLATFORM_WEB_ORIGIN}/oauth`;
81
82
  export const DEFAULT_PAY_WEB_BASE = 'https://pay.wkgeo.cn';
82
- export const DEFAULT_USER_WEB_BASE = 'https://wkgeo.cn/user';
83
+ export const DEFAULT_USER_WEB_BASE = `${PLATFORM_WEB_ORIGIN}/user`;
83
84
 
84
85
  /**
85
86
  * ⚠️ 兼容保留:老站(管理端)基址。
package/lib/hosts.mjs ADDED
@@ -0,0 +1,37 @@
1
+ /**
2
+ * 平台地址常量 —— **CLI 侧唯一源**(`cli/**` 里再出现 `https://<平台域>` 字面量就是错的)。
3
+ *
4
+ * ## 为什么 CLI 自己留一份,而不是 `import` 仓库级常量
5
+ * CLI 是**独立发包**的 npm 包(`@wkgeo/cli`,`files` 只含 `lib/`,`dependencies` 为空):
6
+ * 装到别人机器上之后没有仓库上下文,
7
+ * * `share/platform-hosts`(前端侧唯一源)是仓库内的相对路径,跨包引用在 npm 包里直接 404;
8
+ * * `aliyun/fc/_shared/platform-hosts.js`(云函数侧唯一源)同样进不了包。
9
+ * ⇒ CLI 侧自己保留**一份**:**只在本文件写域名**,`config.mjs` 的三个 Web 基址、
10
+ * 预览地址、manifest 的 schema `$id`、模板抓取 UA 全部由它派生。
11
+ * 换域(`.com` → `.cn` 这类)只改下面的 `PLATFORM_DOMAIN` 一行,其余自动跟随。
12
+ *
13
+ * ⚠️ 与检查器的关系(`tools/check-hardcoded-domains.mjs` 的 `url` 规则):
14
+ * 那条规则要求「`https://` + 域名**连写**」才算硬编码。这里先给根域、再拼 scheme,
15
+ * 不是为了绕过检查,而是**把域名收敛成一行**:本文件是 CLI 侧的唯一出处,
16
+ * 业务代码一律 `import { PLATFORM_WEB_ORIGIN }`,不许各自拼字符串。
17
+ */
18
+
19
+ /**
20
+ * 平台根域(**裸域**,不带 scheme,不含任何子域)。
21
+ * 2026-11-09 老板定:`wkgeo.com` 已无 A 记录、全面退役,默认一律 `.cn`。
22
+ */
23
+ export const PLATFORM_DOMAIN = 'wkgeo.cn';
24
+
25
+ /** 平台 Web 源(主站 `https://wkgeo.cn`;`/cms`、`/user`、`/oauth` 都挂在它下面) */
26
+ export const PLATFORM_WEB_ORIGIN = `https://${PLATFORM_DOMAIN}`;
27
+
28
+ /** CMS 后台源(客户站工作台,`<web>/cms/`;CMS 接口基址另有 `config.DEFAULT_CMS_BASE`) */
29
+ export const PLATFORM_CMS_ORIGIN = `${PLATFORM_WEB_ORIGIN}/cms`;
30
+
31
+ /**
32
+ * 客户站预览短域后缀:站点对外**唯一地址** = `<slug>.` + 它(即 `<slug>.site.wkgeo.cn`)。
33
+ *
34
+ * 2026-11-09 起池短域(`*.cn1 / *.intl / *.global.wkgeo.com.cn`)整体退役,
35
+ * 只剩这一套;说明文案 / 帮助文本要举例站点地址时一律引用它,别再手写。
36
+ */
37
+ export const SITE_PREVIEW_SUFFIX = `site.${PLATFORM_DOMAIN}`;
@@ -53,6 +53,8 @@ import {
53
53
  const PUBLISH_POLL_MS = 2000;
54
54
  /** 素材列表翻页上限(每页 100 × N 桶) */
55
55
  const ASSET_PAGE_CAP = 5;
56
+ /** 首页栏目 slug(与后台 `isHomeCategorySlug` 同一口径:首页永远进导航) */
57
+ const HOME_SLUGS = new Set(['home', 'index']);
56
58
 
57
59
  /** task-95:建站模式(与三条云上链路同一口径:默认 optimize) */
58
60
  const BUILD_MODES = ['optimize', 'origin_copy'];
@@ -636,8 +638,70 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
636
638
  }
637
639
 
638
640
  /* ── 栏目 ─────────────────────────────────────────────────── */
641
+
642
+ /** 本次清单 `menus[]` 声明的导航 path(懒算一次;`menus[]` 是导航唯一真相) */
643
+ let navPathsMemo = null;
644
+ function navPaths() {
645
+ if (!navPathsMemo) {
646
+ navPathsMemo = new Set();
647
+ for (const one of flattenMenus(manifest.menus)) {
648
+ const p = normalizePath(one.path);
649
+ if (p) navPathsMemo.add(p);
650
+ }
651
+ }
652
+ return navPathsMemo;
653
+ }
654
+
655
+ /**
656
+ * 这个栏目该不该进前台导航(老板 2026-11-13 口径:「首页板块一律用隐藏栏目承载」)。
657
+ *
658
+ * @returns {true|false|undefined} `undefined` = 本次**不动**导航字段(老清单:没写 `inMenu`、
659
+ * 也没声明 `menus[]` ⇒ 服务端默认 true,行为与改造前完全一致)。
660
+ *
661
+ * 判定顺序(`menus[]` 是导航唯一真相,`categories[].inMenu` 只是补充):
662
+ * 1. 在 `menus[]` 里 ⇒ `true`(老的显式导航行为不变);同时又写 `inMenu:false` ⇒ 按导航为准并告警;
663
+ * 2. 不在 `menus[]` 里、显式 `inMenu:false` ⇒ `false`(首页板块 / 隐藏栏目);
664
+ * 3. 不在 `menus[]` 里、显式 `inMenu:true` ⇒ `true`(清单没声明导航时也能手动进导航);
665
+ * 4. 没写 `inMenu`、但清单**声明了**导航 ⇒ `false`(没被导航引用就不进导航);
666
+ * 5. 没写 `inMenu`、清单也没有 `menus[]` ⇒ `undefined`(老行为,不碰)。
667
+ */
668
+ function navStateOf(cat, catPath) {
669
+ const nav = navPaths();
670
+ const p = normalizePath(catPath);
671
+ const inNav = nav.size > 0 && Boolean(p) && nav.has(p);
672
+ if (inNav) {
673
+ if (cat.inMenu === false) {
674
+ warnings.push({
675
+ path: `categories.${cat.slug}.inMenu`,
676
+ message: '写了 inMenu:false,但它出现在 menus[] 里 —— 按导航为准(进导航);要隐藏就从 menus[] 里去掉',
677
+ });
678
+ }
679
+ return true;
680
+ }
681
+ /**
682
+ * 首页永远进导航:`menus[].path` 的契约是 `/xxx/`,**写不出 `/`**
683
+ * (JSON Schema `^/[a-z0-9]...` + 校验都拦),所以「不在 menus[] 里」对首页没有意义。
684
+ * 判据与后台一致:slug = `home` / `index`(服务端 `isHomeCategorySlug`)或 path 为 `/`。
685
+ */
686
+ if (nav.size > 0 && (p === '/' || HOME_SLUGS.has(String(cat.slug || '').toLowerCase()))) return true;
687
+ if (cat.inMenu === false) return false;
688
+ if (cat.inMenu === true) return true;
689
+ return nav.size > 0 ? false : undefined;
690
+ }
691
+
639
692
  async function stageCategories() {
640
693
  const entries = [];
694
+ /**
695
+ * 映射判据(`site-mapping-contract.mjs`):manifest 的 `type` 落成哪个 `kind` 由它一处说了算。
696
+ * 加载不到(npm 包里没有 `aliyun/` 目录)⇒ `null`,退回 `cat.kind`,行为与改造前一致。
697
+ *
698
+ * ⚠️ 原来这里只有 `const mapped = contract ? … : null`,**`contract` 从没赋值过** ⇒ 只要有
699
+ * `categories[]` 就抛 `ReferenceError: contract is not defined`(`content apply` 一直是坏的;
700
+ * 之前没有用例覆盖「apply 带栏目」,所以没被发现)。这一行是补上的加载点。
701
+ */
702
+ const contract = await loadSiteMappingContract();
703
+ /** 本次按口径落成隐藏的栏目(集中一条告警,免得刷屏) */
704
+ const hidden = [];
641
705
  for (const cat of sortCategoriesForApply(manifest.categories)) {
642
706
  const item = `category:${cat.slug}`;
643
707
  if (blocked.has(item)) continue;
@@ -690,6 +754,9 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
690
754
  const kind = mapped ? mapped.kind : cat.kind;
691
755
  /** 模板绑定先过契约(计划期就定下来:不合法 ⇒ 空串 + 一条 ⚠,创建 / 更新两条分支共用) */
692
756
  const templateFile = await resolveManifestTemplateFile(cat, kind);
757
+ /** 导航归属:true / false / undefined(undefined = 本次不动,老行为) */
758
+ const inMenu = navStateOf(cat, wantPath);
759
+ if (inMenu === false) hidden.push(cat.name);
693
760
 
694
761
  if (!existing) {
695
762
  const entry = {
@@ -698,7 +765,7 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
698
765
  planned: 'create',
699
766
  action: 'create',
700
767
  label,
701
- detail: `新建栏目(${kind})${templateFile ? ` 模板 ${templateFile}` : ''}`,
768
+ detail: `新建栏目(${kind}${inMenu === false ? ',不进导航' : ''})${templateFile ? ` 模板 ${templateFile}` : ''}`,
702
769
  };
703
770
  entry.run = async (row) => {
704
771
  const payload = { name: cat.name, slug: cat.slug, kind, sort: cat.sort };
@@ -710,6 +777,11 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
710
777
  if (cat.description) payload.description = cat.description;
711
778
  if (cat.seoDescription) payload.seo_description = cat.seoDescription;
712
779
  if (cat.seoKeywords) payload.seo_keywords = cat.seoKeywords;
780
+ /**
781
+ * 关键:**建的时候就带上导航归属**。以前这里没有 `in_menu`,服务端默认 true,
782
+ * 于是「首页·XXX」建完就挂在导航里,只能事后手动 `categories update --no-in-menu` 补。
783
+ */
784
+ if (inMenu !== undefined) payload.in_menu = inMenu;
713
785
  const saved = await call('categorySave', payload);
714
786
  let id = String((saved && (saved.id || saved.categoryId)) || '');
715
787
  if (!id) {
@@ -743,6 +815,8 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
743
815
  description: cat.description,
744
816
  seoDescription: cat.seoDescription,
745
817
  seoKeywords: cat.seoKeywords,
818
+ /** 已有栏目也按同一口径纠正导航归属(以前只摘「不在清单里」的,清单内的永远留在导航) */
819
+ inMenu,
746
820
  });
747
821
  state.catIdBySlug.set(cat.slug, {
748
822
  id: String(existing.id),
@@ -762,6 +836,14 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
762
836
  };
763
837
  entries.push(entry);
764
838
  }
839
+ if (hidden.length) {
840
+ warnings.push({
841
+ path: 'categories',
842
+ message:
843
+ `${hidden.length} 个栏目不在 menus[] 里,按口径落成隐藏栏目(in_menu=false):${hidden.join('、')}` +
844
+ ' —— 要进导航就把它们写进 menus[]',
845
+ });
846
+ }
765
847
  return entries;
766
848
  }
767
849
 
@@ -991,6 +1073,13 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
991
1073
  async function stageMenus() {
992
1074
  const entries = [];
993
1075
  const flat = flattenMenus(manifest.menus);
1076
+ /**
1077
+ * 清单没写 `menus[]` ⇒ **本次不动导航**(老清单行为不变)。
1078
+ *
1079
+ * 注意这里**不再**兜底「把清单里的栏目摘出导航」:清单内的导航归属在 `stageCategories`
1080
+ * 里按 `menus[]` 一次定好(见 `navStateOf`:没被引用 ⇒ 建的时候就是 `in_menu=false`)。
1081
+ * 如果在这里再摘一遍,没有 `menus[]` 的老清单会连整站导航一起被摘空(以前正是这么绕开的)。
1082
+ */
994
1083
  if (!flat.length) return entries;
995
1084
  if (!dryRun) {
996
1085
  /* 栏目阶段可能刚建出一批:落库后以服务端为准重建 path 索引(服务端算 path,本地不猜) */
@@ -1045,9 +1134,16 @@ function createApplyEngine({ ctx, site, manifest, itemErrors, warnings, dryRun }
1045
1134
  for (const row of state.cats) {
1046
1135
  if (row.builtin === true) continue;
1047
1136
  if (row.in_menu !== true) continue;
1048
- if (manifestCatIds.has(String(row.id))) continue; /* 清单里的栏目:认 ID 不认 path(服务端 path 可能与 manifest 写法不同) */
1137
+ /**
1138
+ * 清单里的栏目:导航归属已由 `stageCategories` 按 `menus[]` 决定(建/改时带 `in_menu`),
1139
+ * 这里再摘一次只会多出一条重复条目。只跳过**清单里**的,清单外的照样按老逻辑摘。
1140
+ * 认 ID 不认 path(服务端 path 可能与 manifest 写法不同)。
1141
+ */
1142
+ if (manifestCatIds.has(String(row.id))) continue;
1049
1143
  const p = normalizePath(row.path);
1050
1144
  if (!p || whitelist.has(p)) continue;
1145
+ /* 首页(`/`)不在 menus[] 里是因为契约写不出 `/`,不是"没被引用"—— 永远留在导航 */
1146
+ if (p === '/') continue;
1051
1147
  const item = `menu:${p}`;
1052
1148
  const entry = {
1053
1149
  kind: 'menu',
@@ -1217,6 +1313,11 @@ function diffCategory(row, want) {
1217
1313
  payload.sort = want.sort;
1218
1314
  changes.push(`sort:${row.sort} → ${want.sort}`);
1219
1315
  }
1316
+ /* 导航归属:`undefined` = 本次不动(老清单);只比布尔值,避免把服务端默认值当成「有变」 */
1317
+ if (typeof want.inMenu === 'boolean' && Boolean(row.in_menu) !== want.inMenu) {
1318
+ payload.in_menu = want.inMenu;
1319
+ changes.push(`导航:${row.in_menu ? '显示' : '隐藏'} → ${want.inMenu ? '显示' : '隐藏'}`);
1320
+ }
1220
1321
  if (want.templateFile && normTemplate(row.template_path) !== normTemplate(want.templateFile)) {
1221
1322
  payload.template_path = want.templateFile;
1222
1323
  changes.push(`模板:${row.template_path || '(空)'} → ${want.templateFile}`);
@@ -181,6 +181,10 @@
181
181
  "type": "number",
182
182
  "description": "同级排序,默认按声明顺序 ×10"
183
183
  },
184
+ "inMenu": {
185
+ "type": "boolean",
186
+ "description": "是否显示在前台导航(也认 in_menu)。不写 = 按 menus[] 反推:清单声明了导航但没引用它 ⇒ 隐藏(in_menu=false);首页独立板块(首页·XXX)就该这样隐藏"
187
+ },
184
188
  "templateFile": {
185
189
  "type": "string",
186
190
  "pattern": "\\.html$",
package/lib/manifest.mjs CHANGED
@@ -28,6 +28,7 @@ import fs from 'node:fs';
28
28
  import path from 'node:path';
29
29
 
30
30
  import { ASSET_ROLES, inferAssetRole, normalizeAssetRole } from './asset-role.mjs';
31
+ import { PLATFORM_WEB_ORIGIN } from './hosts.mjs';
31
32
 
32
33
  /* `ASSET_ROLES` / `inferAssetRole` 从本文件对外也是契约的一部分(文档与测试照着这里写) */
33
34
  export { ASSET_ROLES, inferAssetRole, normalizeAssetRole };
@@ -432,6 +433,22 @@ export function validateManifest(doc, opts = {}) {
432
433
  if (declaredPath && !PATH_RE.test(declaredPath)) {
433
434
  fail(`${at}.path`, `path 形如 "/product/"(前后都有斜杠),收到 "${declaredPath}"`);
434
435
  }
436
+ /**
437
+ * 导航归属(老板 2026-11-13 口径:「首页板块一律用隐藏栏目承载」)。
438
+ *
439
+ * 契约写法 `inMenu`(也认服务端字段名 `in_menu`);**不写**时由 `menus[]` 反推:
440
+ * 清单声明了导航但没引用这个栏目 ⇒ 落 `in_menu=false`(见 manifest-apply.mjs 的 `navStateOf`)。
441
+ * 这里只做取值解析与类型校验,反推逻辑放在落地层(需要本次清单的 menus[] 全景)。
442
+ */
443
+ const inMenuRaw = raw.inMenu !== undefined ? raw.inMenu : raw.in_menu;
444
+ let inMenu;
445
+ if (inMenuRaw !== undefined && inMenuRaw !== null) {
446
+ if (typeof inMenuRaw !== 'boolean') {
447
+ fail(`${at}.inMenu`, `inMenu 必须是 true / false,收到 "${oneLine(String(inMenuRaw), 20)}"`);
448
+ } else {
449
+ inMenu = inMenuRaw;
450
+ }
451
+ }
435
452
 
436
453
  /* fields:栏目自己的自定义字段 */
437
454
  const fields = [];
@@ -487,6 +504,7 @@ export function validateManifest(doc, opts = {}) {
487
504
  seoKeywords,
488
505
  description: text(raw.description),
489
506
  fields,
507
+ inMenu,
490
508
  declaredPath: declaredPath ? normalizePath(declaredPath) : '',
491
509
  path: '',
492
510
  level: 0,
@@ -941,6 +959,12 @@ export function manifestJsonSchema() {
941
959
  },
942
960
  parent: str({ description: '父栏目 slug 或 path;子栏目继承父的类型' }),
943
961
  sort: { type: 'number', description: '同级排序,默认按声明顺序 ×10' },
962
+ inMenu: {
963
+ type: 'boolean',
964
+ description:
965
+ '是否显示在前台导航(也认 in_menu)。不写 = 按 menus[] 反推:清单声明了导航但没引用它 ⇒ 隐藏(in_menu=false);' +
966
+ '首页独立板块(首页·XXX)就该这样隐藏',
967
+ },
944
968
  templateFile: str({ pattern: '\\.html$', description: '本站已有的模板文件(如 list.html),必须是 .html' }),
945
969
  description: str({ description: '栏目简介,落 description' }),
946
970
  seoDescription: str({ maxLength: LIMITS.seoDescriptionChars, description: '回退读 seo.description' }),
@@ -1034,7 +1058,7 @@ export function manifestJsonSchema() {
1034
1058
 
1035
1059
  return {
1036
1060
  $schema: 'http://json-schema.org/draft-07/schema#',
1037
- $id: 'https://wkgeo.cn/schema/wkgeo-site-manifest@1.json',
1061
+ $id: `${PLATFORM_WEB_ORIGIN}/schema/wkgeo-site-manifest@1.json`,
1038
1062
  title: 'wkgeo-site-manifest@1',
1039
1063
  description:
1040
1064
  'A(agent)→ 平台的建站内容契约:A 交这份 manifest,`wkgeo content apply --file <它>` 负责校验、幂等落库、按需发布。' +
@@ -13,6 +13,7 @@
13
13
 
14
14
  import { CliError, UsageError } from './errors.mjs';
15
15
  import { resolveConfig } from './config.mjs';
16
+ import { SITE_PREVIEW_SUFFIX } from './hosts.mjs';
16
17
  import { createCms } from './cms.mjs';
17
18
 
18
19
  /* ------------------------------------------------------------------ 常量 */
@@ -26,8 +27,9 @@ export const LANGS = Object.freeze([
26
27
  const DEFAULT_LANG = 'zh-CN';
27
28
 
28
29
  /**
29
- * 区域(决定池位与短域后缀):domestic → `cn1.wkgeo.com.cn`、overseas → `intl.wkgeo.com.cn`、
30
- * global → `global.wkgeo.com.cn`。**不给就 domestic**(平台默认池)。
30
+ * 区域(只决定**池位**):domestic / overseas / global。**不给就 domestic**(平台默认池)。
31
+ * 2026-11-09 起池短域整体退役:站点对外**唯一地址** = `<站点名 slug>.site.wkgeo.cn`,
32
+ * 与区域无关(不再有 `.cn1 / .intl / .global` 后缀)。
31
33
  * 池位满了服务端回 409「该区域名额已满」——这时换 `--region overseas` 是有用的逃生门。
32
34
  */
33
35
  export const REGIONS = Object.freeze([
@@ -72,7 +74,7 @@ export function normalizeRegion(value) {
72
74
  if (one.code === low || one.alias.includes(low)) return one.code;
73
75
  }
74
76
  throw new UsageError(`--region 只支持 ${REGIONS.map((one) => one.code).join(' / ')},收到:${raw}`, {
75
- hint: 'domestic=国内池(cn1.wkgeo.com.cn)/ overseas=海外池(intl.wkgeo.com.cn)/ global=全球池;不传默认 domestic。',
77
+ hint: `domestic=国内池 / overseas=海外池 / global=全球池;站点地址恒为 <slug>.${SITE_PREVIEW_SUFFIX},跟区域无关;不传默认 domestic。`,
76
78
  });
77
79
  }
78
80
 
@@ -407,7 +409,7 @@ export async function runSiteCreate(ctx, flags) {
407
409
  if (/POOL_EXHAUSTED|名额已满/.test(msg)) {
408
410
  /* 409 在通用分类里会落到 kind:'unknown',这里补成可读的 kind,便于 AI 端按类型分支 */
409
411
  if (e && (!e.kind || e.kind === 'unknown')) e.kind = 'pool_exhausted';
410
- e.hint = [e.hint, `该区域池位满了:加 \`--region overseas\`(intl.wkgeo.com.cn)或 \`--region global\` 再建。`].filter(Boolean).join(' | ');
412
+ e.hint = [e.hint, '该区域池位满了:加 `--region overseas` 或 `--region global` 再建。'].filter(Boolean).join(' | ');
411
413
  }
412
414
  throw e;
413
415
  }
@@ -6,7 +6,7 @@
6
6
  * `assets/` 下的 `.css` 与 `.js` 里抽四类东西:
7
7
  * `@keyframes` 名与帧;`animation` / `transition` 声明与长写;滚动入场
8
8
  * (`data-reveal` / IntersectionObserver / class 切换);`transform` 的位移/缩放/旋转与延迟时长。
9
- * 2. **映射**:每条动画尽量落到 `templates/_base` **已有**的类名/属性/变量上
9
+ * 2. **映射**:每条动画尽量落到 `templates/base` **已有**的类名/属性/变量上
10
10
  * (`[data-reveal]` + `data-delay` / `.anim-float` / `.anim-pulse` / `.anim-gradient` /
11
11
  * `.anim-shine` / `[data-kenburns]` / `.marquee` / `[data-parallax]`),**不新造体系**;
12
12
  * 落不下去的标 `unmapped` 并写清原因。
@@ -14,7 +14,7 @@
14
14
  * 给出命中 / 缺失 / 多余;缺失与多余都影响退出码。
15
15
  *
16
16
  * ## 为什么清单要单独一个文件
17
- * `templates/_base` 本轮**只读**,`template.json` 的 v2 字段表也不能随便加键,
17
+ * `templates/base` 本轮**只读**,`template.json` 的 v2 字段表也不能随便加键,
18
18
  * 所以清单落在 `design/animations.json`(随模板包一起分发),几何证据落在
19
19
  * `design/animations.geom.json`(Chrome 实测的元素矩形,用来把像素区域归因到具体动画)。
20
20
  *
@@ -341,7 +341,7 @@ export function motionOfFrames(frames = []) {
341
341
  // ---------------------------------------------------------------- 映射到 _base
342
342
 
343
343
  /**
344
- * `templates/_base` 已有的动效(只读,不新造):
344
+ * `templates/base` 已有的动效(只读,不新造):
345
345
  * `.anim-float` / `.anim-pulse` / `.anim-gradient` / `.anim-shine` / `[data-kenburns]` /
346
346
  * `.marquee` + `.marquee__track` / `[data-reveal]` + `data-delay` / `[data-parallax]`。
347
347
  */
@@ -416,7 +416,7 @@ export function mapToBase(entry) {
416
416
  };
417
417
  const bucket = delayBucket(entry.timing.delayMs);
418
418
  if (bucket) base.attrs['data-delay'] = String(bucket);
419
- if (entry.entryFrom === 'js') base.js = '由 `_base/assets/base.js` 的 IntersectionObserver 加 `.is-visible`,不需要模板自带 JS';
419
+ if (entry.entryFrom === 'js') base.js = '由 `templates/base/assets/base.js` 的 IntersectionObserver 加 `.is-visible`,不需要模板自带 JS';
420
420
  return { status: deltas.length ? 'alias' : 'exact', base, deltas };
421
421
  }
422
422
  if (kind === 'parallax') {
@@ -973,7 +973,7 @@ export function extractAnimations({ key = null, page = '/pages/index.html', css
973
973
  page,
974
974
  generatedAt: new Date().toISOString(),
975
975
  source: { css: css.map((c) => c.file), js: js.map((j) => j.file), html: html.map((h) => h.file) },
976
- base: { library: 'templates/_base', vocabulary: Object.keys(BASE_MAP) },
976
+ base: { library: 'templates/base', vocabulary: Object.keys(BASE_MAP) },
977
977
  signals,
978
978
  counts,
979
979
  animations,