wkgeo-cli 0.2.0 → 0.2.1

package/lib/commands/cms.mjs

@@ -0,0 +1,1265 @@
+/**
+ * CMS 命令（客户站后台的内容管理面）：栏目 / 内容 / 素材 / 模板 / 发布 / 选站。
+ *
+ * ## 这一层的三条口径
+ *   1. **站点必须先定**：所有 CMS 动作都落在"一个站"上。来源优先级
+ *      `--site <站点ID>` > `WKONGAI_SITE` > 本地 `wkgeo site use` 记住的那个。
+ *      一个都没有就**当场报用法错误**，并且只说一句能照做的话 —— 不猜、不默认。
+ *   2. **动作名照抄云函数动作表**（`tencent/functions/cms/index.js` 的 `actionTable`），
+ *      参数名也照抄后台前端（`CMS/src/service/api/cms.ts`）——
+ *      两边一旦不一致，用户看到的是"参数传了但没生效"这种最难查的错。
+ *   3. **默认人类可读表格，`--json` 给原始数据**（信封由 `runtime.done()` 统一包）。
+ *
+ * ## 与后台网页的关系
+ *   命令**不是**另一套业务逻辑：它就是后台那几个按钮的同一批接口。
+ *   所以后台的约束在 CLI 上**一条都不会松**（系统栏目不能删、单页内容只能改不能建、
+ *   绑定模板必须是本站已有的 html …）—— 这些都由服务端拦，CLI 只是把原因如实转给用户。
+ *
+ * ## 别在这里做的事
+ *   * ❌ 不往请求 body 里塞 `site_id`：后端**故意忽略**它，站点边界只认 `x-cms-site` 和会话；
+ *   * ❌ 不自己拼 CMS 地址：走 `runtime.cmsCall()`（它管 Bearer 令牌、站点头、错误翻译）；
+ *   * ❌ 不在 CLI 里"补一条内容"绕过单页限制：那是故意绕过后端校验。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { camel } from '../args.mjs';
+import { uploadToOss } from '../cms.mjs';
+import { CliError, UsageError } from '../errors.mjs';
+import { formatTime } from '../format.mjs';
+import { clearSiteState, readSiteState, writeSiteState } from '../site-state.mjs';
+
+/* ------------------------------------------------------------------ 公共小工具 */
+
+/** 站点/资源 id 的形状（后端到处用 uuid 做参数类型，先本地挡一道比让 PG 报 22P02 友好） */
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+export function looksLikeUuid(v) {
+  return UUID_RE.test(String(v || '').trim());
+}
+
+/** 所有 CMS 命令共用的 `--site`（默认取 `wkgeo site use` 选中的站点） */
+const SITE_FLAG = {
+  site: {
+    type: 'string',
+    desc: '站点 ID（uuid；默认用 `wkgeo site use` 选中的站点，可用 WKONGAI_SITE 覆盖）',
+  },
+};
+
+const CATEGORY_KIND_LABEL = { channel: '频道页', list: '列表页', page: '单页' };
+const CONTENT_STATUS_LABEL = { draft: '草稿', published: '已发布', hidden: '隐藏' };
+
+/** 站点那一行的提示文本（人类输出用） */
+function siteText(site) {
+  if (!site) return '';
+  /** 没显式选站：服务端按令牌的成员关系判定（见 runtime.cmsSite 的第 4 档） */
+  if (!site.id) return '由服务端按你的成员关系自动判定';
+  return site.label ? `${site.label}（${site.id}）` : site.id;
+}
+
+/** 信封里的 `site_id`：没显式选站时是 `null`（真实站点由服务端定，返回行里自带 site_id） */
+function siteIdOf(site) {
+  return site && site.id ? site.id : null;
+}
+
+/** 按 1024 进制给人看的容量 */
+export function formatBytes(n) {
+  const num = Number(n);
+  if (!Number.isFinite(num) || num < 0) return '-';
+  if (num < 1024) return `${num} B`;
+  if (num < 1024 * 1024) return `${(num / 1024).toFixed(1)} KB`;
+  return `${(num / 1024 / 1024).toFixed(2)} MB`;
+}
+
+/** 读一个文本文件（`--body-file` / `--file` 用）；失败给能照做的中文错误 */
+function readTextFile(flagName, filePath) {
+  const abs = path.resolve(String(filePath));
+  try {
+    return fs.readFileSync(abs, 'utf8');
+  } catch (e) {
+    throw new CliError(`读不到文件：${abs}`, {
+      kind: 'io',
+      hint: `${flagName} 需要一个可读的文件路径（${(e && e.code) || (e && e.message) || '未知原因'}）`,
+    });
+  }
+}
+
+/** `--ext` 这类"整段 JSON"参数 */
+function parseJsonObjectFlag(name, raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(raw));
+  } catch (e) {
+    throw new UsageError(`参数 ${name} 需要一段 JSON 对象，收到：${String(raw).slice(0, 80)}（${e.message}）`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new UsageError(`参数 ${name} 需要一个 JSON **对象**（形如 {"型号":"X1"}），不是数组或标量`);
+  }
+  return parsed;
+}
+
+/** 逗号分隔 → 字符串数组（`--usage home,featured`） */
+function splitList(raw) {
+  return String(raw == null ? '' : raw)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** `--body` / `--body-file` 二选一 → 正文；没给就 undefined（= 不传，后端保持原样） */
+function resolveBodyFlag(ctx) {
+  const hasInline = ctx.flags.body !== undefined;
+  const hasFile = ctx.flags.bodyFile !== undefined;
+  if (hasInline && hasFile) throw new UsageError('--body 与 --body-file 只能给一个');
+  if (hasFile) return readTextFile('--body-file', ctx.flags.bodyFile);
+  return hasInline ? String(ctx.flags.body) : undefined;
+}
+
+/**
+ * 把「字段表 + flags」变成请求体：**只放用户真的给了的键**。
+ *
+ * 为什么不能一律塞 `undefined`：`categorySave` / `contentSave` 的语义是
+ * "没传的保持原样"，塞一个 `null` 进去等于**清空**（`pickValue` 认的是 `undefined`）。
+ *
+ * ⚠️ 字段表的键是**命令行写法**（`in-menu` / `seo-description`），而解析后的 flags 是 camelCase
+ *    （`inMenu` / `seoDescription`）—— 必须过 `camel()`，否则读到的永远是 undefined，
+ *    表现成"参数传了但没生效"（这条踩过一次，专门写在这）。
+ */
+function pickFields(flags, table, payload) {
+  for (const [flagKey, bodyKey, kind] of table) {
+    const v = flags[camel(flagKey)];
+    if (v === undefined) continue;
+    if (kind === 'num') {
+      const n = Number(v);
+      if (!Number.isFinite(n)) throw new UsageError(`参数 --${flagKey} 需要数字，收到：${v}`);
+      payload[bodyKey] = n;
+    } else if (kind === 'bool') {
+      payload[bodyKey] = v === true;
+    } else if (kind === 'list') {
+      payload[bodyKey] = splitList(v);
+    } else {
+      payload[bodyKey] = String(v);
+    }
+  }
+  return payload;
+}
+
+/* ------------------------------------------------------------------ 站点 */
+
+/**
+ * `wkgeo site use`：把"以后操作哪个站"记在本地。
+ *
+ * 为什么要这一步（而不是每条命令都问）：CMS 的动作**必须**有站点上下文，
+ * 而 CLI 没有登录 Cookie；把选择显式化之后，多站用户不会出现"改了 A 站以为改的是 B 站"。
+ *
+ * 域名 → id 的解析走平台面的 `listSites`（**自己名下**的站）。
+ * ⚠️ 如果这个站是"别人邀请你协作的"，`listSites` 里没有 ⇒ 只能用站点 ID 选（文案里已写明）。
+ */
+export const siteUseCommand = {
+  name: 'site use',
+  summary: '选中要操作的站点（本地记住，之后的 CMS 命令都带它）',
+  usage: 'wkgeo site use <站点ID或域名>\nwkgeo site use             # 看当前选中的是哪个站\nwkgeo site use --clear     # 取消选中',
+  args: [{ name: 'site', required: false, desc: '站点 ID（uuid）、自有域名、临时域名或站点名' }],
+  flags: {
+    clear: { type: 'boolean', desc: '取消当前选中的站点' },
+  },
+  examples: [
+    'wkgeo site use 8f3c1a2e-4b5d-4f6a-8b7c-9d0e1f2a3b4c',
+    'wkgeo site use www.example.com',
+    'wkgeo site use            # 只查询，不改',
+    'wkgeo categories list --site 8f3c…   # 不改本地选择，临时指定',
+  ],
+  notes: [
+    '选择存在 `<凭据目录>/config.json`（默认 `~/.wkongai/config.json`），与令牌文件分开：logout 不会清掉它。',
+    '域名解析只查**你自己名下**的站；协作站的域名查不到时，请改用站点 ID。',
+  ],
+  async run(ctx) {
+    const { out } = ctx;
+
+    if (ctx.flags.clear) {
+      const had = clearSiteState(ctx.siteStateFile);
+      const data = { cleared: had, site: null, state_file: ctx.siteStateFile };
+      if (out.json) ctx.done(data);
+      else if (had) out.ok('已取消选中的站点（后续 CMS 命令需要重新 `wkgeo site use` 或加 `--site`）');
+      else out.info('本来就没有选中任何站点，无需取消。');
+      return data;
+    }
+
+    const wanted = String(ctx.positional.site || '').trim();
+    if (!wanted) {
+      const current = readSiteState(ctx.siteStateFile);
+      const data = { site: current, state_file: ctx.siteStateFile, selected: Boolean(current) };
+      if (out.json) ctx.done(data);
+      else if (current) {
+        out.head('当前选中的站点');
+        out.line(`  站点：${siteText(current)}`);
+        out.line(`  选择时间：${formatTime(current.saved_at)}`);
+        out.line(`  记录文件：${ctx.siteStateFile}`);
+      } else {
+        out.info('还没有选中站点：运行 `wkgeo site use <站点ID或域名>`，或在命令里加 `--site <站点ID>`。');
+      }
+      return data;
+    }
+
+    /** ① ID 直接认（**不查库**：协作站也可能不在 listSites 里，那是正常情况） */
+    let site = null;
+    let matchedBy = '';
+    if (looksLikeUuid(wanted)) {
+      site = { id: wanted, label: '' };
+      matchedBy = 'id';
+    } else {
+      /** ② 域名 / 站点名 → 查平台面的站点列表再匹配 */
+      const res = await ctx.callData('listSites', { limit: 200 });
+      const rows = (res && Array.isArray(res.rows) ? res.rows : []).map((r) => r || {});
+      site = matchSiteRow(rows, wanted);
+      matchedBy = site ? site.matched_by : '';
+      if (!site) {
+        throw new CliError(`没有找到站点「${wanted}」（按 id / 域名 / 站点名都没匹配上）`, {
+          kind: 'not_found',
+          code: 404,
+          hint:
+            rows.length
+              ? `你名下的站：${rows
+                  .slice(0, 10)
+                  .map((r) => `${r.name || '(未命名)'}=${r.id}`)
+                  .join('；')}${rows.length > 10 ? ` …共 ${rows.length} 个` : ''}；也可以直接给站点 ID。`
+              : '当前账号名下没有站点（协作站不在列表里）—— 请直接用站点 ID。',
+        });
+      }
+    }
+
+    writeSiteState(ctx.siteStateFile, site);
+    const data = {
+      site: { id: site.id, label: site.label || '' },
+      matched_by: matchedBy,
+      state_file: ctx.siteStateFile,
+    };
+    if (out.json) ctx.done(data);
+    else {
+      out.ok(`已选中站点：${siteText(site)}`);
+      out.info(`  记录文件：${ctx.siteStateFile}（之后的 CMS 命令默认都用这个站）`);
+      out.info('  临时换站：任意 CMS 命令加 `--site <站点ID>`。');
+    }
+    return data;
+  },
+};
+
+/**
+ * 在一堆站点行里按「域名 / 临时域名 / 站点名」找唯一一个。
+ *
+ * @returns {{id:string, label:string, matched_by:string}|null}
+ */
+export function matchSiteRow(rows, wanted) {
+  const needle = normalizeSiteRef(wanted);
+  if (!needle) return null;
+  for (const row of rows || []) {
+    const id = String(row.id || '');
+    if (!id) continue;
+    const label = String(row.name || '') || String(row.domain || '');
+    const domains = [];
+    if (row.domain) domains.push(String(row.domain));
+    if (Array.isArray(row.domains)) for (const d of row.domains) if (d) domains.push(String(d));
+    if (row.prefix_host) domains.push(String(row.prefix_host));
+    for (const d of domains) {
+      if (normalizeSiteRef(d) === needle) return { id, label, matched_by: 'domain' };
+    }
+    if (String(row.name || '').trim() === String(wanted).trim()) return { id, label, matched_by: 'name' };
+  }
+  return null;
+}
+
+/** 域名归一：去掉协议、`/` 尾巴、大小写 —— 用户粘一条网址进来也能匹配 */
+function normalizeSiteRef(v) {
+  return String(v || '')
+    .trim()
+    .replace(/^https?:\/\//i, '')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+}
+
+/* ------------------------------------------------------------------ 栏目 */
+
+/** 取本站栏目全表（`categoryList` 返回的是**数组**，不是 `{rows}`） */
+async function fetchCategories(ctx) {
+  const res = await ctx.cmsCall('categoryList');
+  const rows = Array.isArray(res) ? res : res && Array.isArray(res.rows) ? res.rows : [];
+  return rows.map((r) => r || {});
+}
+
+/**
+ * 栏目引用 → 栏目行（支持 栏目 ID / slug / path / 栏目名）。
+ *
+ * 为什么要这么宽：AI 端手里常常只有「新闻」这个栏目名或 `/news/` 这个路径，
+ * 逼它先去记一个 uuid 没有意义 —— 而全表本来就在一次调用里拿回来了。
+ */
+export async function resolveCategory(ctx, ref) {
+  const wanted = String(ref || '').trim();
+  if (!wanted) throw new UsageError('缺少栏目（可以给栏目 ID、slug、path 或栏目名）');
+  const rows = await fetchCategories(ctx);
+  const low = wanted.toLowerCase();
+  const trimPath = (s) => String(s || '').replace(/^\/+|\/+$/g, '').toLowerCase();
+  const hit =
+    rows.find((r) => String(r.id) === wanted) ||
+    rows.find((r) => String(r.slug || '').toLowerCase() === low) ||
+    rows.find((r) => trimPath(r.path) === trimPath(wanted)) ||
+    rows.find((r) => String(r.name || '') === wanted);
+  if (hit) return hit;
+  throw new CliError(`没有找到栏目「${wanted}」`, {
+    kind: 'not_found',
+    code: 404,
+    hint: rows.length
+      ? `当前栏目：${rows
+          .slice(0, 20)
+          .map((r) => `${r.name || '(未命名)'}(${r.path || r.slug || r.id})`)
+          .join('、')}${rows.length > 20 ? ' …' : ''}`
+      : '这个站还没有栏目：先 `wkgeo categories create --name 首页 --kind channel`，或在后台启用默认栏目。',
+  });
+}
+
+export const categoriesListCommand = {
+  name: 'categories list',
+  summary: '栏目列表（树序：按 level / sort 排）',
+  usage: 'wkgeo categories list [--site <站点ID>]',
+  flags: { ...SITE_FLAG },
+  examples: ['wkgeo categories list', 'wkgeo categories list --json', 'wkgeo categories list --site 8f3c…'],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const rows = await fetchCategories(ctx);
+    const data = { site_id: siteIdOf(site), rows, total: rows.length };
+
+    if (!out.json) {
+      out.head(`栏目列表（${rows.length} 个 · 站点 ${siteText(site)}）`);
+      out.table(
+        [
+          { title: '名称', key: 'name', width: 26, format: (v, row) => `${'  '.repeat(Math.max(0, (Number(row.level) || 1) - 1))}${v || ''}` },
+          { title: '路径', key: 'path', width: 20 },
+          { title: '类型', key: 'kind', width: 8, format: (v) => CATEGORY_KIND_LABEL[v] || v || '-' },
+          { title: '状态', key: 'status', width: 6, format: (v) => (v === 'hide' ? '隐藏' : '显示') },
+          { title: '绑定模板', key: 'template_path', width: 14 },
+          { title: '栏目 ID', key: 'id', width: 38 },
+        ],
+        rows,
+      );
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const categoriesGetCommand = {
+  name: 'categories get',
+  summary: '单个栏目详情（含栏目正文与父栏目启用的字段）',
+  usage: 'wkgeo categories get <栏目ID|slug|path|栏目名> [--site <站点ID>]',
+  args: [{ name: 'category', required: true, desc: '栏目 ID / slug / path（如 /news/）/ 栏目名' }],
+  flags: { ...SITE_FLAG },
+  examples: ['wkgeo categories get /news/', 'wkgeo categories get 8f3c1a2e-… --json'],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const row = await resolveCategory(ctx, ctx.positional.category);
+    /** 详情要单独调一次：正文在 cms_richtext 里，`categoryList` 故意不带（列表会被拖慢） */
+    const one = await ctx.cmsCall('categoryGet', { id: String(row.id) });
+    const data = { site_id: siteIdOf(site), category: one };
+
+    if (!out.json) {
+      out.head(`栏目：${one.name || row.name || ''}`);
+      const lines = [
+        ['栏目 ID', one.id],
+        ['路径', one.path],
+        ['slug', one.slug],
+        ['类型', CATEGORY_KIND_LABEL[one.kind] || one.kind || '-'],
+        ['状态', one.status === 'hide' ? '隐藏' : '显示'],
+        ['在菜单里', one.in_menu ? '是' : '否'],
+        ['绑定模板', one.template_path || '（按类型自动选）'],
+        ['副标题', one.sub_title || '-'],
+        ['SEO 描述', one.seo_description || '-'],
+        ['SEO 关键词', one.seo_keywords || '-'],
+        ['更新时间', formatTime(one.updated_at)],
+      ];
+      for (const [k, v] of lines) out.line(`  ${k}：${v === undefined || v === null || v === '' ? '-' : v}`);
+      if (one.body) {
+        out.line('  栏目正文：');
+        out.line(String(one.body));
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/** `categorySave` 支持的字段（flag → body 键） */
+const CATEGORY_FIELDS = [
+  ['name', 'name', 'str'],
+  ['slug', 'slug', 'str'],
+  ['parent', 'parent_id', 'str'],
+  ['kind', 'kind', 'str'],
+  ['status', 'status', 'str'],
+  ['sort', 'sort', 'num'],
+  ['icon', 'icon', 'str'],
+  ['link-url', 'link_url', 'str'],
+  ['description', 'description', 'str'],
+  ['sub-title', 'sub_title', 'str'],
+  ['seo-description', 'seo_description', 'str'],
+  ['seo-keywords', 'seo_keywords', 'str'],
+  ['in-menu', 'in_menu', 'bool'],
+  ['featured', 'featured', 'bool'],
+];
+
+/** 栏目命令共用的字段参数（新建/修改同源，避免两处写歪） */
+const CATEGORY_FIELD_FLAGS = {
+  slug: { type: 'string', desc: 'URL 片段（不传由服务端按名字生成）' },
+  parent: { type: 'string', desc: '上级栏目 ID（不传 = 一级栏目）' },
+  kind: { type: 'string', desc: '页面类型：channel 频道页 / list 列表页 / page 单页（只有一级栏目能定）' },
+  status: { type: 'string', desc: '显示状态：show 显示 / hide 隐藏' },
+  sort: { type: 'string', desc: '排序（小的在前）' },
+  icon: { type: 'string', desc: '菜单图标（iconify 名，如 mdi:home-outline）' },
+  'link-url': { type: 'string', desc: '外链地址（http/https；给了就是"点它直接跳走"的栏目）' },
+  description: { type: 'string', desc: '栏目描述（也当前台 SEO 的 description 备选）' },
+  'sub-title': { type: 'string', desc: '副标题（下拉菜单第二行小字）' },
+  'seo-description': { type: 'string', desc: 'SEO 描述（≤500 字）' },
+  'seo-keywords': { type: 'string', desc: 'SEO 关键词（逗号分隔，≤300 字）' },
+  'in-menu': { type: 'boolean', desc: '是否显示在前台导航菜单里（默认是；关掉用 --no-in-menu）' },
+  featured: { type: 'boolean', desc: '是否推荐（频道页取数用；默认是）' },
+  body: { type: 'string', desc: '栏目正文（富文本 HTML）' },
+  'body-file': { type: 'string', desc: '从本地文件读栏目正文（与 --body 二选一）' },
+};
+
+export const categoriesCreateCommand = {
+  name: 'categories create',
+  summary: '新建栏目',
+  usage: 'wkgeo categories create --name <栏目名> [--parent <上级栏目ID>] [--kind channel|list|page] [其他字段…]',
+  flags: {
+    name: { type: 'string', required: true, desc: '栏目名（≤100 字）' },
+    ...CATEGORY_FIELD_FLAGS,
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo categories create --name 新闻 --kind list --seo-description "公司新闻动态"',
+    'wkgeo categories create --name 公司简介 --kind page --parent <关于我们的ID>',
+    'wkgeo categories create --name 产品 --slug product --body-file ./product.html',
+  ],
+  notes: [
+    '单页（page）栏目会自动带一条"只能编辑、不能新建也不能删除"的内容；要加一页 = 给它加子栏目。',
+    '首页（slug=home）的页面类型会被服务端锁定为 channel。',
+  ],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const payload = pickFields(flags, CATEGORY_FIELDS, { name: String(flags.name) });
+    const body = resolveBodyFlag(ctx);
+    if (body !== undefined) payload.body = body;
+
+    const one = await ctx.cmsCall('categorySave', payload);
+    const data = { site_id: siteIdOf(site), category: one };
+    if (!out.json) {
+      out.ok(`栏目已创建：${(one && one.name) || payload.name}`);
+      out.line(`  栏目 ID：${(one && one.id) || '-'}`);
+      out.line(`  路径：${(one && one.path) || '-'}（类型 ${CATEGORY_KIND_LABEL[(one && one.kind) || ''] || (one && one.kind) || '-'}）`);
+      out.info('  下一步：`wkgeo contents create --category <栏目ID> --title …`，或 `wkgeo categories bind-template <栏目> index.html`。');
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const categoriesUpdateCommand = {
+  name: 'categories update',
+  summary: '修改栏目（只改给了的字段，其余保持原样）',
+  usage: 'wkgeo categories update <栏目ID|slug|path> [--name …] [--status show|hide] [其他字段…]',
+  args: [{ name: 'category', required: true, desc: '栏目 ID / slug / path / 栏目名' }],
+  flags: {
+    /** `name` 单独声明：新建时是**必填**，修改时不能必填（"没传的保持原样"） */
+    name: { type: 'string', desc: '新栏目名（≤100 字）' },
+    ...CATEGORY_FIELD_FLAGS,
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo categories update /news/ --name 新闻中心',
+    'wkgeo categories update 8f3c1a2e-… --no-in-menu   # 不显示在前台菜单',
+  ],
+  notes: ['"没传的字段保持原样"是服务端口径，所以改名不会顺手把描述清空；要清空请显式传空串（如 --description ""）。'],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const row = await resolveCategory(ctx, ctx.positional.category);
+    const payload = pickFields(flags, CATEGORY_FIELDS, { id: String(row.id) });
+    const body = resolveBodyFlag(ctx);
+    if (body !== undefined) payload.body = body;
+
+    if (Object.keys(payload).length <= 1) {
+      throw new UsageError(
+        '没有要改的字段：至少给一个（--name / --slug / --status / --sort / --seo-description / --body …）',
+      );
+    }
+
+    const one = await ctx.cmsCall('categorySave', payload);
+    const data = { site_id: siteIdOf(site), category_id: String(row.id), changed: Object.keys(payload).filter((k) => k !== 'id'), category: one };
+    if (!out.json) {
+      out.ok(`栏目已更新：${(one && one.name) || row.name}（${data.changed.join(', ')}）`);
+      out.line(`  栏目 ID：${row.id}`);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const categoriesDeleteCommand = {
+  name: 'categories delete',
+  summary: '删除栏目（系统栏目 / 还有子栏目或内容时服务端会拒绝）',
+  usage: 'wkgeo categories delete <栏目ID|slug|path> [--site <站点ID>]',
+  args: [{ name: 'category', required: true, desc: '栏目 ID / slug / path / 栏目名' }],
+  flags: { ...SITE_FLAG },
+  examples: ['wkgeo categories delete /old/', 'wkgeo categories delete 8f3c1a2e-… --json'],
+  notes: [
+    '系统预置栏目**只能隐藏不能删**；下面还有子栏目 / 普通内容时也会被拒（先把它们挪走或删掉）。',
+    '单页栏目自己的那一页内容会跟着栏目一起删（那是唯一正规的做法）。',
+  ],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const row = await resolveCategory(ctx, ctx.positional.category);
+    const res = await ctx.cmsCall('categoryDelete', { id: String(row.id) });
+    const data = { site_id: siteIdOf(site), id: String(row.id), name: row.name || '', deleted: !!(res && res.deleted) };
+    if (!out.json) {
+      out.ok(`栏目已删除：${data.name || data.id}`);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/**
+ * 栏目绑定模板文件（`categorySave.template_path`）。
+ *
+ * 为什么单独一条命令：后台最常做的一件事是"把这一栏换成另一套版式"，
+ * 而 `template_path` 藏在保存接口里 —— 让 AI 为改一个字段去拼整个栏目表单没必要，
+ * 也容易把别的字段（描述 / SEO）顺手清掉。
+ */
+export const categoriesBindTemplateCommand = {
+  name: 'categories bind-template',
+  summary: '给栏目绑定模板文件（不给 <模板文件> + --clear = 解绑，回到"按栏目类型自动选"）',
+  usage: 'wkgeo categories bind-template <栏目ID|slug|path> <模板文件名>\nwkgeo categories bind-template <栏目> --clear',
+  args: [
+    { name: 'category', required: true, desc: '栏目 ID / slug / path / 栏目名' },
+    { name: 'template', required: false, desc: '模板文件名，如 about.html（必须是本站模板里已有的文件）' },
+  ],
+  flags: {
+    clear: { type: 'boolean', desc: '解绑（清空 template_path，回到按栏目类型自动选模板）' },
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo categories bind-template /about/ about.html',
+    'wkgeo categories bind-template 新闻 news-list.html',
+    'wkgeo categories bind-template /about/ --clear',
+    'wkgeo templates list    # 先看本站有哪些 html',
+  ],
+  notes: [
+    '模板文件白名单：`字母/数字/中划线/下划线 + .html`；文件不存在时服务端会拒绝 —— 这里先查一次并列出可选文件。',
+    '不绑定时按栏目类型自动选：频道页 index.html、单页 about.html、列表页/内容页 content.html。',
+  ],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const row = await resolveCategory(ctx, ctx.positional.category);
+    const clear = flags.clear === true;
+    const wanted = String(ctx.positional.template || '').trim();
+
+    if (!clear && !wanted) {
+      throw new UsageError('缺少参数 <模板文件>（要解绑请加 --clear）\n用法：wkgeo categories bind-template <栏目> <模板文件名>');
+    }
+    if (clear && wanted) {
+      throw new UsageError('--clear 与 <模板文件> 只能给一个（要绑定就写文件名，要解绑就只给 --clear）');
+    }
+
+    let templatePath = '';
+    if (!clear) {
+      if (!/^[A-Za-z0-9_-]+\.html$/.test(wanted)) {
+        throw new UsageError(`模板文件名不合法：${wanted}\n只允许 字母/数字/中划线/下划线 + .html，例如 about.html`);
+      }
+      /** 先查一次本站模板，把"没有这个文件"变成一句带候选的错误（服务端也会查，但它的报错没有候选列表） */
+      const tpl = await ctx.cmsCall('templateGet', {});
+      const files = (tpl && Array.isArray(tpl.files) ? tpl.files : []).map((f) => String((f && f.path) || ''));
+      if (!files.includes(wanted)) {
+        throw new CliError(`本站模板里没有「${wanted}」`, {
+          kind: 'not_found',
+          code: 404,
+          hint: files.length
+            ? `现有模板文件：${files.join(' / ')}；要新建它用 \`wkgeo templates save ${wanted} --file <本地文件>\``
+            : '本站还没有模板文件：先 `wkgeo templates save index.html --file <本地文件>`（或先跑 `wkgeo templates list` 让服务端 seed 默认模板）',
+        });
+      }
+      templatePath = wanted;
+    }
+
+    const one = await ctx.cmsCall('categorySave', { id: String(row.id), template_path: templatePath });
+    const data = {
+      site_id: siteIdOf(site),
+      category_id: String(row.id),
+      category_name: row.name || '',
+      template_path: templatePath || null,
+      cleared: clear,
+      category: one,
+    };
+    if (!out.json) {
+      if (clear) out.ok(`已解绑模板：${row.name || data.category_id}（回到按栏目类型自动选）`);
+      else out.ok(`已绑定模板：${row.name || data.category_id} → ${templatePath}`);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ 内容 */
+
+export const contentsListCommand = {
+  name: 'contents list',
+  summary: '内容列表（可按栏目 / 状态 / 关键词筛；不含正文）',
+  usage: 'wkgeo contents list [--category <栏目>] [--status draft|published|hidden] [--keyword 词] [--page 1] [--page-size 20]',
+  flags: {
+    category: { type: 'string', desc: '只看这个栏目（ID / slug / path / 栏目名）' },
+    status: { type: 'string', desc: '状态：draft 草稿 / published 已发布 / hidden 隐藏' },
+    keyword: { type: 'string', desc: '标题关键词' },
+    page: { type: 'string', desc: '页码（默认 1）' },
+    'page-size': { type: 'string', desc: '每页条数（默认 20，最多 100）' },
+    sort: { type: 'string', desc: '排序：views_desc 访问量降序 / views_asc 升序（默认置顶→排序→ID）' },
+    'include-children': { type: 'boolean', desc: '连下级栏目的内容一起列' },
+    'owner-page': { type: 'boolean', desc: '只看"单页栏目那一页"（单页栏目专用）' },
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo contents list --status draft',
+    'wkgeo contents list --category 新闻 --page-size 50',
+    'wkgeo contents list --keyword 展会 --include-children --json',
+  ],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const payload = {};
+    if (flags.category !== undefined) payload.categoryId = String((await resolveCategory(ctx, flags.category)).id);
+    if (flags.status !== undefined) payload.status = String(flags.status);
+    if (flags.keyword !== undefined) payload.keyword = String(flags.keyword);
+    if (flags.page !== undefined) payload.page = Number(flags.page);
+    if (flags.pageSize !== undefined) payload.pageSize = Number(flags.pageSize);
+    if (flags.sort !== undefined) payload.sort = String(flags.sort);
+    if (flags.includeChildren !== undefined) payload.includeChildren = flags.includeChildren === true;
+    if (flags.ownerPage !== undefined) payload.ownerPage = flags.ownerPage === true;
+
+    const res = await ctx.cmsCall('contentList', payload);
+    const rows = (res && Array.isArray(res.rows) ? res.rows : []).map((r) => r || {});
+    const data = {
+      site_id: siteIdOf(site),
+      rows,
+      total: (res && res.total) || rows.length,
+      page: (res && res.page) || payload.page || 1,
+      page_size: (res && res.pageSize) || payload.pageSize || 20,
+    };
+
+    if (!out.json) {
+      out.head(`内容列表（共 ${data.total} 条 · 第 ${data.page} 页 ${rows.length} 条 · 站点 ${siteText(site)}）`);
+      out.table(
+        [
+          { title: '标题', key: 'title', width: 34 },
+          { title: '栏目', key: 'category_name', width: 14 },
+          { title: '状态', key: 'status', width: 8, format: (v) => CONTENT_STATUS_LABEL[v] || v || '-' },
+          { title: '更新时间', key: 'updated_at', format: (v) => formatTime(v), width: 20 },
+          { title: '内容 ID', key: 'id', width: 38 },
+        ],
+        rows,
+      );
+      if (data.total > data.page * data.page_size) {
+        out.info(`  下一页：--page ${data.page + 1}`);
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const contentsGetCommand = {
+  name: 'contents get',
+  summary: '单条内容详情（含正文、附件、SEO、自定义字段）',
+  usage: 'wkgeo contents get <内容ID> [--site <站点ID>]',
+  args: [{ name: 'id', required: true, desc: '内容 ID（uuid）' }],
+  flags: { ...SITE_FLAG },
+  examples: ['wkgeo contents get 8f3c1a2e-…', 'wkgeo contents get 8f3c1a2e-… --json'],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const id = String(ctx.positional.id || '').trim();
+    if (!looksLikeUuid(id)) {
+      throw new UsageError(`内容 ID 应该是 uuid，收到：${id}\n先 'wkgeo contents list' 找到它`);
+    }
+    const one = await ctx.cmsCall('contentGet', { id });
+    const data = { site_id: siteIdOf(site), content: one };
+    if (!out.json) {
+      out.head(`内容：${one.title || ''}`);
+      const ext = (one && one.ext) || {};
+      const lines = [
+        ['内容 ID', one.id],
+        ['栏目', one.category_name || one.category_id],
+        ['slug', one.slug],
+        ['状态', CONTENT_STATUS_LABEL[one.status] || one.status],
+        ['置顶', one.pinned ? '是' : '否'],
+        ['访问量', one.views],
+        ['关键词', one.keywords || ext.keywords || '-'],
+        ['封面', one.cover_url || ext.cover_asset_id || '-'],
+        ['更新时间', formatTime(one.updated_at)],
+      ];
+      for (const [k, v] of lines) out.line(`  ${k}：${v === undefined || v === null || v === '' ? '-' : v}`);
+      if (one.body) {
+        out.line('  正文：');
+        out.line(String(one.body));
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/** `contentSave` 支持的字段（flag → body 键） */
+const CONTENT_FIELDS = [
+  ['slug', 'slug', 'str'],
+  ['status', 'status', 'str'],
+  ['description', 'description', 'str'],
+  ['keywords', 'keywords', 'str'],
+  ['sub-title', 'sub_title', 'str'],
+  ['cover', 'cover_asset_id', 'str'],
+  ['video', 'video_asset_id', 'str'],
+  ['usage', 'usage', 'list'],
+  ['sort', 'sort', 'num'],
+  ['pinned', 'pinned', 'bool'],
+  ['attachments', 'attachments', 'list'],
+];
+
+/** 内容命令共用的字段参数 */
+const CONTENT_FIELD_FLAGS = {
+  slug: { type: 'string', desc: 'URL 片段（不传由服务端生成）' },
+  status: { type: 'string', desc: '状态：draft 草稿（默认）/ published 已发布 / hidden 隐藏' },
+  description: { type: 'string', desc: '描述（列表页简介 + SEO description，≤500 字）' },
+  keywords: { type: 'string', desc: '关键词（≤300 字）' },
+  'sub-title': { type: 'string', desc: '副标题' },
+  cover: { type: 'string', desc: '封面素材 ID（先用 `wkgeo assets upload` 传图拿 id）' },
+  video: { type: 'string', desc: '视频素材 ID' },
+  usage: { type: 'string', desc: '用途/位置，逗号分隔：home 首页、list 列表、featured 推荐' },
+  sort: { type: 'string', desc: '排序（小的在前）' },
+  pinned: { type: 'boolean', desc: '置顶' },
+  attachments: { type: 'string', desc: '多图：素材 ID 逗号分隔（整体替换）' },
+  ext: { type: 'string', desc: '自定义字段（JSON 对象，如 {"型号":"X1"}；与内置字段同名时以 --ext 为准）' },
+  body: { type: 'string', desc: '正文（富文本 HTML）' },
+  'body-file': { type: 'string', desc: '从本地文件读正文（与 --body 二选一）' },
+};
+
+/** 把内容相关的 flags 收成 `contentSave` 的请求体 */
+function buildContentPayload(ctx, base) {
+  const payload = pickFields(ctx.flags, CONTENT_FIELDS, { ...base });
+  const body = resolveBodyFlag(ctx);
+  if (body !== undefined) payload.body = body;
+  if (ctx.flags.ext !== undefined) payload.ext = parseJsonObjectFlag('--ext', ctx.flags.ext);
+  return payload;
+}
+
+export const contentsCreateCommand = {
+  name: 'contents create',
+  summary: '新建内容（默认草稿；状态给 published 就立刻在前台可见）',
+  usage: 'wkgeo contents create --category <栏目> --title <标题> [--body …|--body-file 文件] [--status draft|published]',
+  flags: {
+    title: { type: 'string', required: true, desc: '标题（≤200 字）' },
+    category: { type: 'string', required: true, desc: '所属栏目（ID / slug / path / 栏目名）' },
+    ...CONTENT_FIELD_FLAGS,
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo contents create --category 新闻 --title "公司参展 2026" --status published --body "<p>正文…</p>"',
+    'wkgeo contents create --category /news/ --title 新品发布 --body-file ./article.html --cover <素材ID>',
+    'wkgeo contents create --category 产品 --title X1 --ext \'{"型号":"X1","价格":"999"}\' --json',
+  ],
+  notes: [
+    '「单页」栏目（含它下面的子栏目）**不能新建内容** —— 那是栏目自带的一页，只能 `contents update` 改。',
+    '前台是服务端按需渲染：`--status published` 保存即上线，不需要额外的发布步骤（见 `wkgeo publish`）。',
+  ],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const category = await resolveCategory(ctx, flags.category);
+    const payload = buildContentPayload(ctx, {
+      title: String(flags.title),
+      category_id: String(category.id),
+    });
+    const one = await ctx.cmsCall('contentSave', payload);
+    const data = { site_id: siteIdOf(site), content: one };
+    if (!out.json) {
+      out.ok(`内容已保存：${(one && one.title) || payload.title}`);
+      out.line(`  内容 ID：${(one && one.id) || '-'}`);
+      out.line(`  栏目：${category.name || category.path || category.id}`);
+      out.line(`  状态：${CONTENT_STATUS_LABEL[(one && one.status) || payload.status] || (one && one.status) || payload.status || 'draft'}`);
+      if ((one && one.status) === 'published') out.info('  已发布：前台（服务端按需渲染）已经能打开这一页。');
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const contentsUpdateCommand = {
+  name: 'contents update',
+  summary: '修改内容（只改给了的字段，其余保持原样）',
+  usage: 'wkgeo contents update <内容ID> [--title …] [--status …] [--body …] [其他字段…]',
+  args: [{ name: 'id', required: true, desc: '内容 ID（uuid）' }],
+  flags: {
+    title: { type: 'string', desc: '新标题（≤200 字）' },
+    category: { type: 'string', desc: '换栏目（单页那一页不能搬家，服务端会按归属栏目写）' },
+    ...CONTENT_FIELD_FLAGS,
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo contents update 8f3c1a2e-… --status published',
+    'wkgeo contents update 8f3c1a2e-… --title "新标题" --body-file ./v2.html',
+  ],
+  notes: ['服务端口径是"没传的字段保持原样"；要清空某字段请显式传空串（如 --description ""）。'],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const id = String(ctx.positional.id || '').trim();
+    if (!looksLikeUuid(id)) {
+      throw new UsageError(`内容 ID 应该是 uuid，收到：${id}\n先 'wkgeo contents list' 找到它`);
+    }
+    const base = { id };
+    if (flags.title !== undefined) base.title = String(flags.title);
+    if (flags.category !== undefined) base.category_id = String((await resolveCategory(ctx, flags.category)).id);
+    const payload = buildContentPayload(ctx, base);
+
+    if (Object.keys(payload).length <= 1) {
+      throw new UsageError('没有要改的字段：至少给一个（--title / --status / --body / --description / --ext …）');
+    }
+
+    const one = await ctx.cmsCall('contentSave', payload);
+    const data = {
+      site_id: siteIdOf(site),
+      content_id: id,
+      changed: Object.keys(payload).filter((k) => k !== 'id'),
+      content: one,
+    };
+    if (!out.json) {
+      out.ok(`内容已更新：${(one && one.title) || id}（${data.changed.join(', ')}）`);
+      out.line(`  状态：${CONTENT_STATUS_LABEL[(one && one.status) || ''] || (one && one.status) || '-'}`);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const contentsDeleteCommand = {
+  name: 'contents delete',
+  summary: '删除内容（「单页」那一页删不掉 —— 要去栏目管理删栏目）',
+  usage: 'wkgeo contents delete <内容ID> [--site <站点ID>]',
+  args: [{ name: 'id', required: true, desc: '内容 ID（uuid）' }],
+  flags: { ...SITE_FLAG },
+  examples: ['wkgeo contents delete 8f3c1a2e-…', 'wkgeo contents delete 8f3c1a2e-… --json'],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const id = String(ctx.positional.id || '').trim();
+    if (!looksLikeUuid(id)) throw new UsageError(`内容 ID 应该是 uuid，收到：${id}`);
+    const res = await ctx.cmsCall('contentDelete', { id });
+    const data = { site_id: siteIdOf(site), id, deleted: !!(res && res.deleted) };
+    if (!out.json) out.ok(`内容已删除：${id}`);
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ 素材 */
+
+export const assetsListCommand = {
+  name: 'assets list',
+  summary: '素材列表（默认只列图片；可看回收站）',
+  usage: 'wkgeo assets list [--kind 图片|视频|文档|PDF|压缩包|""] [--keyword 词] [--status normal|deleted] [--page 1] [--page-size 60]',
+  flags: {
+    kind: { type: 'string', desc: '类型：图片（默认）/ 视频 / 文档 / PDF / 压缩包；给空串 "" = 全部类型' },
+    keyword: { type: 'string', desc: '按名称 / 文件路径搜' },
+    status: { type: 'string', desc: 'normal 在用（默认）/ deleted 回收站' },
+    sort: { type: 'string', desc: '排序：date_desc（默认）/ date_asc / size_desc / size_asc / name_asc / name_desc' },
+    page: { type: 'string', desc: '页码（默认 1）' },
+    'page-size': { type: 'string', desc: '每页条数（默认 60，最多 200）' },
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo assets list',
+    'wkgeo assets list --kind 视频 --keyword 宣传',
+    'wkgeo assets list --status deleted',
+    'wkgeo assets list --kind "" --page-size 200 --json',
+  ],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const payload = {};
+    if (flags.kind !== undefined) payload.kind = String(flags.kind);
+    if (flags.keyword !== undefined) payload.keyword = String(flags.keyword);
+    if (flags.status !== undefined) payload.status = String(flags.status);
+    if (flags.sort !== undefined) payload.sort = String(flags.sort);
+    if (flags.page !== undefined) payload.page = Number(flags.page);
+    if (flags.pageSize !== undefined) payload.pageSize = Number(flags.pageSize);
+
+    const res = await ctx.cmsCall('assetList', payload);
+    const rows = (res && Array.isArray(res.rows) ? res.rows : []).map((r) => r || {});
+    const data = {
+      site_id: siteIdOf(site),
+      rows,
+      total: (res && res.total) || rows.length,
+      page: (res && res.page) || payload.page || 1,
+      page_size: (res && res.pageSize) || payload.pageSize || 60,
+      asset_host: (res && res.assetHost) || '',
+      kind_counts: (res && res.kindCounts) || [],
+      trash_count: res && res.trashCount !== undefined ? res.trashCount : null,
+    };
+
+    if (!out.json) {
+      out.head(`素材列表（共 ${data.total} 条 · 第 ${data.page} 页 ${rows.length} 条 · 站点 ${siteText(site)}）`);
+      out.table(
+        [
+          { title: '名称', key: 'name', width: 28 },
+          { title: '类型', key: 'kind', width: 8 },
+          { title: '大小', key: 'size', width: 10, format: (v) => formatBytes(v) },
+          { title: '尺寸', key: 'width', width: 12, format: (v, row) => (row.width && row.height ? `${row.width}×${row.height}` : '-') },
+          { title: '身份ID', key: 'slug', width: 12 },
+          { title: '上传时间', key: 'created_at', format: (v) => formatTime(v), width: 20 },
+          { title: '素材 ID', key: 'id', width: 38 },
+        ],
+        rows,
+      );
+      if (data.trash_count) out.info(`  回收站里还有 ${data.trash_count} 个（--status deleted 查看）。`);
+      if (data.total > data.page * data.page_size) out.info(`  下一页：--page ${data.page + 1}`);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/** 服务端单文件上限（见 `tencent/functions/cms` 的 allowedExtensions 表：最大 200MB 的视频/压缩包） */
+const MAX_UPLOAD_BYTES = 200 * 1024 * 1024;
+
+export const assetsUploadCommand = {
+  name: 'assets upload',
+  summary: '上传素材（签名 → 直传 OSS → 登记；CLI 不碰 AK，二进制不进云函数）',
+  usage: 'wkgeo assets upload <本地文件> [--name 显示名] [--site <站点ID>]',
+  args: [{ name: 'file', required: true, desc: '本地文件路径（图片 / 视频 / 文档 / PDF / 压缩包）' }],
+  flags: {
+    name: { type: 'string', desc: '素材显示名（默认取文件名）' },
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo assets upload ./logo.png',
+    'wkgeo assets upload "D:\\图\\展会.jpg" --name 展会现场',
+    'wkgeo assets upload ./brochure.pdf --json   # 拿 id 去挂内容：contents update <id> --attachments <素材ID>',
+  ],
+  notes: [
+    '三步走：`assetSign` 取票据（锁 key/大小，10 分钟）→ 用票据把文件 POST 到 OSS → `assetRegister` 落库并回读校验。',
+    'CLI 只做搬运：既不保存也不打印 OSS 的 AccessKey（AK 只在云函数里）。',
+    '支持的扩展名与上限由服务端决定（图片 10MB / PDF 50MB / 视频 200MB …）。',
+  ],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const filePath = path.resolve(String(ctx.positional.file || ''));
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch (e) {
+      throw new CliError(`读不到文件：${filePath}`, {
+        kind: 'io',
+        hint: `检查路径是否正确（${(e && e.code) || (e && e.message) || '未知原因'}）`,
+      });
+    }
+    if (!stat.isFile()) throw new UsageError(`不是普通文件：${filePath}`);
+    if (stat.size <= 0) throw new UsageError(`文件是空的：${filePath}`);
+    if (stat.size > MAX_UPLOAD_BYTES) {
+      throw new UsageError(`文件 ${formatBytes(stat.size)} 超过服务端单文件上限 ${formatBytes(MAX_UPLOAD_BYTES)}`);
+    }
+
+    const fileName = path.basename(filePath);
+    const displayName = String(flags.name || fileName).trim() || fileName;
+
+    /** ① 取直传票据（fileName 决定 kind / mime，bytes 让服务端提前挡掉超限） */
+    const ticket = await ctx.cmsCall('assetSign', { fileName, bytes: stat.size });
+    if (!ticket || !ticket.key || !ticket.uploadUrl) {
+      throw new CliError('服务端没有返回直传票据（assetSign）', {
+        kind: 'bad_response',
+        hint: '检查云函数 `cms` 的素材库配置（OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET / 桶与地域）',
+      });
+    }
+
+    /** ② 直传 OSS（CLI 只拿票据，不持 AK） */
+    const buffer = fs.readFileSync(filePath);
+    await uploadToOss({ ticket, buffer, fileName, fetchImpl: ctx.fetchImpl });
+
+    /** ③ 登记落库（服务端会回读一次 OSS，确认文件真的在） */
+    const asset = await ctx.cmsCall('assetRegister', { key: ticket.key, name: displayName });
+    const data = {
+      site_id: siteIdOf(site),
+      asset,
+      key: ticket.key,
+      url: (asset && asset.url) || ticket.url || '',
+    };
+
+    if (!out.json) {
+      out.ok(`素材已上传：${(asset && asset.name) || displayName}`);
+      out.line(`  素材 ID：${(asset && asset.id) || '-'}`);
+      out.line(`  类型：${(asset && asset.kind) || ticket.kind || '-'}（${formatBytes(stat.size)}）`);
+      out.line(`  地址：${data.url || '-'}`);
+      out.info(`  引用它：\`wkgeo contents update <内容ID> --cover ${(asset && asset.id) || '<素材ID>'}\``);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ 模板 */
+
+/** 取默认模板（含全部文件源码）—— `templateGet` 不传 templateId 就是默认模板 */
+async function fetchDefaultTemplate(ctx) {
+  return ctx.cmsCall('templateGet', {});
+}
+
+export const templatesListCommand = {
+  name: 'templates list',
+  summary: '模板列表（默认模板 + 每个 html 的字符数）',
+  usage: 'wkgeo templates list [--site <站点ID>]',
+  flags: { ...SITE_FLAG },
+  examples: ['wkgeo templates list', 'wkgeo templates list --json'],
+  notes: [
+    '一个站的模板就是一套 html（index.html / about.html / content.html…），第一次调用时服务端会自动 seed 一套，所以不会"没有模板"。',
+    '要看源码用 `wkgeo templates get <文件名>`；要改/新建用 `wkgeo templates save <文件名> --file <本地文件>`。',
+  ],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const res = (await ctx.cmsCall('templateList')) || {};
+    const templates = Array.isArray(res.templates) ? res.templates : [];
+    const files = Array.isArray(res.files) ? res.files : [];
+    const data = {
+      site_id: siteIdOf(site),
+      template_id: res.templateId || null,
+      templates,
+      files: files.map((f) => ({ id: f.id, path: f.path, chars: String(f.content || '').length, updated_at: f.updatedAt || null })),
+      auto_files: res.autoFiles || {},
+    };
+
+    if (!out.json) {
+      out.head(`模板（站点 ${siteText(site)}）`);
+      out.line(`  默认模板：${(templates.find((t) => t.isDefault) || templates[0] || {}).name || '-'}（id ${data.template_id || '-'}）`);
+      out.table(
+        [
+          { title: '模板文件', key: 'path', width: 24 },
+          { title: '字符数', key: 'chars', width: 10 },
+          { title: '更新时间', key: 'updated_at', format: (v) => formatTime(v), width: 20 },
+          { title: '文件 ID', key: 'id', width: 38 },
+        ],
+        data.files,
+      );
+      const auto = Object.entries(data.auto_files || {});
+      if (auto.length) {
+        out.info(`  自动档（栏目没绑模板时按类型选）：${auto.map(([k, v]) => `${CATEGORY_KIND_LABEL[k] || k}→${v}`).join('、')}`);
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const templatesGetCommand = {
+  name: 'templates get',
+  summary: '看模板文件源码（不给文件名 = 只列文件清单）',
+  usage: 'wkgeo templates get [模板文件名] [--site <站点ID>]',
+  args: [{ name: 'path', required: false, desc: '模板文件名，如 index.html；不给就只列清单' }],
+  flags: { ...SITE_FLAG },
+  examples: [
+    'wkgeo templates get',
+    'wkgeo templates get index.html',
+    'wkgeo templates get about.html > about.html',
+  ],
+  notes: [
+    '给了文件名时，**人类可读模式输出的是源码原文**（可以直接 `> 文件` 存下来），不受"非终端自动 JSON"影响；',
+    '`--json` 下仍然是一个标准信封（`data.content` 里是源码）。模板语法见 docs/功能-模板.md。',
+  ],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const wanted = String(ctx.positional.path || '').trim();
+    const tpl = (await fetchDefaultTemplate(ctx)) || {};
+    const files = Array.isArray(tpl.files) ? tpl.files : [];
+
+    if (!wanted) {
+      const data = {
+        site_id: siteIdOf(site),
+        template: { id: tpl.id || null, name: tpl.name || '', is_default: !!tpl.isDefault },
+        files: files.map((f) => ({ id: f.id, path: f.path, chars: String(f.content || '').length, updated_at: f.updatedAt || null })),
+      };
+      if (!out.json) {
+        out.head(`模板文件（${data.template.name || '默认模板'} · 站点 ${siteText(site)}）`);
+        out.table(
+          [
+            { title: '模板文件', key: 'path', width: 24 },
+            { title: '字符数', key: 'chars', width: 10 },
+            { title: '更新时间', key: 'updated_at', format: (v) => formatTime(v), width: 20 },
+          ],
+          data.files,
+        );
+        out.info('  看源码：`wkgeo templates get <文件名>`');
+      }
+      ctx.done(data);
+      return data;
+    }
+
+    const hit = files.find((f) => String(f.path || '') === wanted);
+    if (!hit) {
+      throw new CliError(`模板里没有「${wanted}」`, {
+        kind: 'not_found',
+        code: 404,
+        hint: files.length
+          ? `现有模板文件：${files.map((f) => f.path).join(' / ')}（新建用 \`wkgeo templates save ${wanted} --file <本地文件>\`）`
+          : '这个站还没有任何模板文件（先跑 `wkgeo templates list` 触发服务端 seed 默认模板）',
+      });
+    }
+
+    const data = {
+      site_id: siteIdOf(site),
+      template: { id: tpl.id || null, name: tpl.name || '', is_default: !!tpl.isDefault },
+      path: hit.path,
+      chars: String(hit.content || '').length,
+      updated_at: hit.updatedAt || null,
+      content: String(hit.content || ''),
+    };
+    if (!out.json) {
+      /** 原文直出（可重定向）；不加任何表头，避免污染模板源码 */
+      out.plain(data.content.endsWith('\n') ? data.content : data.content + '\n');
+    } else {
+      ctx.done(data);
+    }
+    return data;
+  },
+};
+
+/** 服务端上限：`templateMaxBytes = 400 * 1024`（按**字符**算） */
+const TEMPLATE_MAX_CHARS = 400 * 1024;
+
+export const templatesSaveCommand = {
+  name: 'templates save',
+  summary: '新建 / 覆盖一个模板 html（≤40 万字符，写操作会记系统日志）',
+  usage: 'wkgeo templates save <模板文件名.html> (--file <本地文件> | --content <源码>) [--site <站点ID>]',
+  args: [{ name: 'path', required: true, desc: '模板文件名，如 index.html（字母/数字/中划线/下划线 + .html）' }],
+  flags: {
+    file: { type: 'string', desc: '从本地文件读源码' },
+    content: { type: 'string', desc: '直接给源码（与 --file 二选一；适合短模板）' },
+    ...SITE_FLAG,
+  },
+  examples: [
+    'wkgeo templates save index.html --file ./index.html',
+    'wkgeo templates save about.html --content "<!doctype html><h1>{{ category.name }}</h1>"',
+  ],
+  notes: [
+    '同名文件直接覆盖（服务端 `on conflict do update`）；改坏了用 `wkgeo templates get <文件名>` 先取回旧源码备份。',
+    '模板语法与可用变量见 docs/功能-模板.md（`{{ category.name }}` / `{{#each contents}}` 等）。',
+  ],
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const site = ctx.cmsSite();
+    const filePath = String(ctx.positional.path || '').trim();
+    if (!/^[A-Za-z0-9_-]+\.html$/.test(filePath)) {
+      throw new UsageError(
+        `模板文件名不合法：${filePath || '(空)'}\n只允许 字母/数字/中划线/下划线 + .html，例如 index.html / news-list.html`,
+      );
+    }
+    const hasFile = flags.file !== undefined;
+    const hasContent = flags.content !== undefined;
+    if (hasFile === hasContent) {
+      throw new UsageError('--file 与 --content 必须且只能给一个\n用法：wkgeo templates save index.html --file ./index.html');
+    }
+    const content = hasFile ? readTextFile('--file', flags.file) : String(flags.content);
+    if (content.length > TEMPLATE_MAX_CHARS) {
+      throw new UsageError(`模板太长了：${content.length} 字符，服务端上限 ${TEMPLATE_MAX_CHARS} 字符`);
+    }
+
+    const saved = await ctx.cmsCall('templateFileSave', { path: filePath, content });
+    const data = {
+      site_id: siteIdOf(site),
+      path: (saved && saved.path) || filePath,
+      file_id: (saved && saved.id) || null,
+      chars: content.length,
+      updated_at: (saved && saved.updatedAt) || null,
+    };
+    if (!out.json) {
+      out.ok(`模板已保存：${data.path}（${data.chars} 字符）`);
+      out.line(`  文件 ID：${data.file_id || '-'}`);
+      if (data.updated_at) out.line(`  更新时间：${formatTime(data.updated_at)}`);
+      out.info(`  让栏目用它：\`wkgeo categories bind-template <栏目> ${data.path}\``);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ 发布 */
+
+/**
+ * `publish` —— **不硬造静态发布**。
+ *
+ * 事实（2026-10-18 复核）：P4 的前台是**服务端按需渲染**（`pageRender`），
+ * 内容状态改成 `published` 就已经上线了，**没有"发布"这一步**。
+ * 真正还需要"发布"的是另一件事：**静态化 + 推 OSS/CDN + 客户自有域名**，
+ * 那需要一个"输入站点 ID、一次幂等跑完"的后端动作（还没做）。
+ *
+ * 所以这条命令现在做两件诚实事：
+ *   1. 用 `overview`（只读）把"现在线上是什么状态"报清楚（多少已发布 / 多少草稿）；
+ *   2. 明确告诉用户"为什么不需要发布"，以及静态发布缺什么 —— 不假装成功。
+ */
+export const publishCommand = {
+  name: 'publish',
+  summary: '看发布状态（前台是按需渲染：内容 published 即上线，没有额外的发布步骤）',
+  usage: 'wkgeo publish [--site <站点ID>]',
+  flags: { ...SITE_FLAG },
+  examples: ['wkgeo publish', 'wkgeo publish --json'],
+  notes: [
+    '**不会**做静态化 / 推 CDN：那需要一个"输入站点 ID、一次幂等跑完"的后端动作（尚未实现）。',
+    '想让内容上线：`wkgeo contents update <内容ID> --status published`（保存即生效）。',
+  ],
+  async run(ctx) {
+    const { out } = ctx;
+    const site = ctx.cmsSite();
+    const res = (await ctx.cmsCall('overview')) || {};
+    const data = {
+      site_id: siteIdOf(site),
+      site_name: res.siteName || site.label || '',
+      render_mode: 'on-demand',
+      effective_immediately: true,
+      counts: {
+        categories: res.categories || 0,
+        contents: res.contents || 0,
+        published: res.published || 0,
+        drafts: res.drafts || 0,
+        assets: res.assets || 0,
+      },
+      static_publish: {
+        available: false,
+        missing_backend_action: '按站点 ID 幂等跑完的"静态化 + 推 OSS/CDN"动作（规划-Agent与开放接口.md 第 4 条）',
+        hint: '需要静态化 / 绑客户自有域名时，先请后端补这个动作；CLI 侧不硬造。',
+      },
+      message:
+        '本站前台是服务端按需渲染（pageRender）：内容状态 = published 就已经上线，不需要额外的发布步骤。' +
+        '静态化与客户自有域名需要后端补一个幂等发布动作，当前 CLI 不做。',
+    };
+
+    if (!out.json) {
+      out.head(`发布状态（站点 ${data.site_name ? `${data.site_name}（${site.id}）` : site.id}）`);
+      out.line(`  栏目 ${data.counts.categories} 个 ｜ 内容 ${data.counts.contents} 条（已发布 ${data.counts.published} / 草稿 ${data.counts.drafts}）｜ 素材 ${data.counts.assets} 个`);
+      out.line('');
+      out.line('  渲染方式：服务端按需渲染（pageRender）—— 内容改为 published **即刻生效**，没有"发布"这一步。');
+      out.line('  所以这条命令只报状态，不会推送任何东西。');
+      out.line('');
+      out.line('  要让内容上线：wkgeo contents update <内容ID> --status published');
+      out.line('  静态化 / 推 CDN / 客户自有域名：需要后端补"按站点幂等发布"的动作，目前没有（CLI 不硬造）。');
+    }
+    ctx.done(data);
+    return data;
+  },
+};