wkgeo-cli 0.2.0

package/lib/commands/billing.mjs

@@ -0,0 +1,421 @@
+/**
+ * 钱包命令：`wallet` / `wallet txns` / `wallet recharge`
+ *
+ * 这是"钱包余额支付"链路的**观察窗口**：每次下单/支付/退款后都用它复核余额，
+ * 报告里的"事前/事后一分不差"就是拿它的数字对比的。
+ *
+ * ⚠️ 关于"钱包流水"的接口事实（已核对服务端代码）：
+ *   * `getMyWallet` 自己就带了最近流水（`data.rows`，按时间倒序，limit 1~100）——
+ *     **普通用户看自己的流水就是走它**，这就是 `wallet txns` 的实现。
+ *   * `adminListWalletTxns` 是**管理员**接口（能力 `billing:manage`），
+ *     OAuth 令牌默认拿不到，也不该拿 —— 所以 CLI **不会**去调它。
+ *   * 服务端**没有**"我的流水分页/按时间筛选"的独立接口（只有 limit，没有 offset）。
+ *     这是个真实缺口，已写进报告。
+ */
+
+import { withTrailingSlash } from '../config.mjs';
+import { UsageError, CliError, EXIT } from '../errors.mjs';
+import { formatMoney, formatTime } from '../format.mjs';
+import { openUrlForUser, browserPasteText, browserOpenedText, browserFailedHintLines } from '../login.mjs';
+import { renderQrOptional } from '../qr.mjs';
+
+/**
+ * 拼出「我们自己的网上收银台」地址：`<webBase>/pay/?order_id=<id>&token=<支付令牌>`
+ *
+ * ## 为什么必须走这里、不许在命令里手拼
+ *
+ * 1. **尾斜杠必须在 `?` 之前**（本仓库铁律，踩过线上事故）：
+ *    前端是静态导出，产物是"每个路由一个目录"（`dist/pay/index.html`），
+ *    托管侧（OSS 静态托管 / 阿里云 ESA）对**不带尾斜杠**的目录路径会返回 302，
+ *    而这个 302 **不携带原始 query** —— 于是 `?order_id=…` 在浏览器里
+ *    根本到不了页面，用户看到的是一个"没有订单号的收银台"。
+ *    所以统一走 `withTrailingSlash()`（全项目唯一构造入口，见 `config.mjs`）。
+ * 2. 参数一律走 `URLSearchParams` 编码：手拼一旦漏编码，
+ *    订单号里任何特殊字符都会把后面的参数吃掉（登录回跳那条链踩过同样的坑）。
+ *    ⚠️ 令牌是 **base64url**，含 `-` / `_` / `.`，看着"很安全"，但**也必须编码** ——
+ *      别因为"它字面上没特殊字符"就手拼。
+ *
+ * ⚠️ 老板定的产品流程就是这条：**在网上生成订单 → 打开我们网站的收银台页面**，
+ *    而不是"在本地搞一个二维码让别人扫"。
+ *
+ * ## ★ 2026-10-02 新增第三个参数：订单支付令牌（`token`）
+ *   老板原话：「你拿到 token 之后，**以那个 token 为基础来进行支付**，
+ *   而不是还要他用**用户名那一套**来进行支付。」
+ *
+ *   现场：用户是在 **AI 客户端右侧的内置浏览器**里付这一单，那里**通常没有网页登录态**
+ *   （甚至跟他平时登录后台的账号不是同一个）。服务端在下单时把"这一单是谁的"签成
+ *   一把**只对这一单有效**的令牌（`createRechargeOrder` 的 `pay_token`）交给我们，
+ *   收银台凭它就能读这一单的支付参数 —— **不需要网页登录**。
+ *   ⚠️ 令牌只授权"读这一单的支付参数"：读不到钱包、读不到订单列表、不能下单、不能取消。
+ *
+ *   ⚠️ 幂等/兼容：服务端**没给**令牌（老版本云函数未部署 / 密钥未配置）时，
+ *      `payUrl` 照旧只有 `order_id` —— 那条路**仍然要求网页登录**，
+ *      行为与改造前逐字一致（不因为"新功能没上线"就把命令搞失败）。
+ *
+ * @param {string} webBase  前端基址。★ 2026-10-02 起传的是 `config.payWebBase`
+ *                          （`https://pay.wkgeo.com`），老站基址只是兜底
+ * @param {string} orderId  订单号
+ * @param {string} [payToken] 订单支付令牌（`pay_token`），没有就不带这个参数
+ * @returns {string|null} 订单号缺失时返回 null（没订单号就拼不出能用的收银台地址）
+ */
+export function buildPayUrl(webBase, orderId, payToken) {
+  const id = orderId === undefined || orderId === null ? '' : String(orderId).trim();
+  if (!id) return null;
+  const base = String(webBase || '').replace(/\/+$/, '');
+  const params = { order_id: id };
+  const token =
+    payToken === undefined || payToken === null ? '' : String(payToken).trim();
+  if (token) params.token = token;
+  const query = new URLSearchParams(params).toString();
+  return withTrailingSlash(`${base}/pay`) + `?${query}`;
+}
+
+const KIND_LABEL = {
+  recharge: '充值',
+  pay: '支付',
+  refund: '退款',
+  adjust: '调账',
+  grant: '赠送',
+  withdraw: '提现',
+};
+
+function normalizeTxn(r) {
+  const amount = Number(r.amount_cents) || 0;
+  return {
+    id: r.id ?? null,
+    kind: r.kind || null,
+    kind_label: KIND_LABEL[r.kind] || r.kind || null,
+    amount_cents: amount,
+    amount_text: `${amount >= 0 ? '+' : '-'}${formatMoney(Math.abs(amount))}`,
+    balance_after_cents: r.balance_after === undefined || r.balance_after === null ? null : Number(r.balance_after),
+    balance_after_text: r.balance_after === undefined || r.balance_after === null ? '-' : formatMoney(r.balance_after),
+    order_id: r.order_id || null,
+    remark: r.remark || null,
+    created_at: r.created_at || null,
+  };
+}
+
+async function loadWallet(ctx, limit) {
+  const res = await ctx.callData('getMyWallet', { limit });
+  const rows = (res && Array.isArray(res.rows) ? res.rows : []).map(normalizeTxn);
+  return { balance_cents: Number((res && res.balance_cents) || 0), rows };
+}
+
+const TXN_COLUMNS = [
+  { title: '时间', key: 'created_at', format: (v) => formatTime(v), width: 20 },
+  { title: '类型', key: 'kind_label', width: 8 },
+  { title: '金额', key: 'amount_text', width: 12 },
+  { title: '余额后', key: 'balance_after_text', width: 12 },
+  { title: '备注', key: 'remark', width: 34 },
+];
+
+/* ------------------------------------------------------------------ */
+/* wallet（总览）                                                       */
+/* ------------------------------------------------------------------ */
+
+export const walletCommand = {
+  name: 'wallet',
+  summary: '查钱包余额与最近流水（加 --entitlements 看生效中的权益）',
+  usage: 'wkgeo wallet [--limit 10] [--entitlements]',
+  flags: {
+    limit: { type: 'string', desc: '流水条数（1~100，默认 10）' },
+    entitlements: { type: 'boolean', desc: '同时列出我的权益（加量包/套餐生效情况）' },
+  },
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const limit = flags.limit !== undefined ? Number(flags.limit) : 10;
+    const wallet = await loadWallet(ctx, limit);
+
+    let entitlements = null;
+    if (flags.entitlements) {
+      try {
+        const e = await ctx.callData('listMyEntitlements', {});
+        entitlements = (e && e.rows) || [];
+      } catch (err) {
+        // 权益接口未部署/无权限时不该让"查余额"这个核心动作失败
+        out.warn(`读取权益失败（不影响余额）：${err.message}`);
+        entitlements = null;
+      }
+    }
+
+    const data = {
+      balance_cents: wallet.balance_cents,
+      balance_text: formatMoney(wallet.balance_cents),
+      rows: wallet.rows,
+      entitlements: entitlements
+        ? entitlements.map((x) => ({
+            quota_key: x.quota_key || null,
+            name: x.name || null,
+            amount: x.amount ?? null,
+            used: x.used ?? null,
+            status: x.status || null,
+            expires_at: x.expires_at || null,
+          }))
+        : undefined,
+    };
+
+    if (!out.json) {
+      out.head('钱包');
+      out.line(`  余额：${data.balance_text}`);
+      out.line('');
+      out.line('最近流水：');
+      out.table(TXN_COLUMNS, wallet.rows);
+      if (entitlements) {
+        out.line('');
+        out.line('生效中的权益：');
+        out.table(
+          [
+            { title: '配额', key: 'quota_key', width: 18 },
+            { title: '数量', key: 'amount', width: 12 },
+            { title: '状态', key: 'status', width: 10 },
+            { title: '到期', key: 'expires_at', format: (v) => formatTime(v), width: 20 },
+          ],
+          entitlements,
+        );
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* wallet txns                                                         */
+/* ------------------------------------------------------------------ */
+
+export const walletTxnsCommand = {
+  name: 'wallet txns',
+  summary: '钱包流水（走"我的钱包"接口自带的流水，普通用户即可读）',
+  usage: 'wkgeo wallet txns [--limit 20]',
+  flags: {
+    limit: { type: 'string', desc: '流水条数（1~100，默认 20）' },
+  },
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const limit = flags.limit !== undefined ? Number(flags.limit) : 20;
+    const wallet = await loadWallet(ctx, limit);
+    const data = {
+      balance_cents: wallet.balance_cents,
+      balance_text: formatMoney(wallet.balance_cents),
+      rows: wallet.rows,
+      total: wallet.rows.length,
+      note: '服务端当前只支持 limit，没有 offset/时间筛选（我的流水缺口）',
+    };
+    if (!out.json) {
+      out.head(`钱包流水（最近 ${wallet.rows.length} 条）`);
+      out.line(`  当前余额：${data.balance_text}`);
+      out.line('');
+      out.table(TXN_COLUMNS, wallet.rows);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* wallet recharge                                                     */
+/* ------------------------------------------------------------------ */
+
+export const walletRechargeCommand = {
+  name: 'wallet recharge',
+  summary:
+    '充值下单：创建一笔微信 Native 待支付订单，**并打开我们网站的收银台页面**扫码支付（不会自动扣款）',
+  usage: 'wkgeo wallet recharge --amount-cents <分> [--no-browser] [--open-browser] [--dry-run]',
+  flags: {
+    'amount-cents': { type: 'string', required: true, desc: '充值金额，单位**分**（如 100 = ¥1.00，最低 100，最高 10000000）' },
+    'no-browser': { type: 'boolean', desc: '不自动打开浏览器（自动化/无桌面环境用；地址仍会打印并放在 pay_url 里）' },
+    /**
+     * ★ 老板最终拍板走**传统路线**：默认**总是尝试打开**系统浏览器（人在终端与 AI 场景都一样），
+     *   所以本开关现在**与默认行为等价**。保留它只为两件事：
+     *     1. **显式语义**（脚本里写"我就是要弹"比依赖默认值更清楚）；
+     *     2. **兼容**既有脚本（不许删）。
+     * ⚠️ `--no-browser` 优先（关掉就是关掉，见 login.mjs 的 resolveBrowserIntent）。
+     */
+    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）' },
+    'dry-run': { type: 'boolean', desc: '只打印将要做什么，不真的创建订单' },
+  },
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const amountCents = Number(flags.amountCents);
+    if (!Number.isInteger(amountCents) || amountCents <= 0) {
+      throw new UsageError(`--amount-cents 必须是正整数（单位：分），收到：${flags.amountCents}`);
+    }
+    if (amountCents < 100) throw new UsageError('充值金额不能低于 ¥1.00（100 分）');
+    if (amountCents > 10000000) throw new UsageError('单笔充值不能超过 ¥100,000.00（10000000 分）');
+
+    if (flags.dryRun === true) {
+      const data = {
+        dry_run: true,
+        amount_cents: amountCents,
+        amount_text: formatMoney(amountCents),
+        created: false,
+        /** 真跑时会给出的收银台地址（彩排阶段还没有订单号，所以是 null） */
+        pay_url: null,
+      };
+      if (!out.json) {
+        out.head('充值（彩排，未创建订单）');
+        out.line(`  将创建一笔 ¥${(amountCents / 100).toFixed(2)} 的微信 Native 待支付订单`);
+        out.info('  去掉 --dry-run 即真正创建；创建后 CLI 会**打开我们网站的收银台页面**让你扫码支付（不会自动扣款）。');
+      }
+      ctx.done(data);
+      return data;
+    }
+
+    /**
+     * ⚠️ 这里会**在微信侧创建一笔真实的待支付商户订单**（不扣款、不自动支付）。
+     *    这是"老板要测充值"必须的能力，但绝不能在自动化测试里跑 ——
+     *    测试只在离线桩里验证请求体，真钱流程由人手动完成。
+     */
+    const res = await ctx.callData('createRechargeOrder', { amount_cents: amountCents });
+    const orderId = (res && res.order_id) || null;
+    /**
+     * ★ 我们自己的**网上收银台**地址（老板定的产品流程：走网上充值页面，
+     *   而不是在本地生成一个二维码页面让人扫）。
+     *   拼装口径与尾斜杠规则见本文件顶部的 `buildPayUrl()`。
+     *
+     * ★ 第三个参数 = 服务端在**下单那一刻**签发的订单支付令牌（`pay_token`）：
+     *   带上它，收银台在**没有网页登录态**的 AI 端内置浏览器里也能付这一单
+     *   （老板："以那个 token 为基础来进行支付，而不是还要他用用户名那一套"）。
+     *   ⚠️ 老服务端没这个字段时就是 `undefined` ⇒ 地址退回只有 `order_id` 的老形态。
+     *
+     * ★ 2026-10-02（三站拆分）：基址改用**收银台子域** `config.payWebBase`
+     *   （`https://pay.wkgeo.com`）。`config.webBase` 只作为老配置对象的兜底
+     *   （联调时 `WKONGAI_WEB_BASE` 总覆盖会把两者设成同一个值）。
+     */
+    const payUrl = buildPayUrl(
+      ctx.config && (ctx.config.payWebBase || ctx.config.webBase),
+      orderId,
+      res && res.pay_token,
+    );
+    const data = {
+      order_id: orderId,
+      out_trade_no: (res && res.out_trade_no) || null,
+      paid: !!(res && res.paid),
+      amount_cents: Number((res && res.amount_cents) || amountCents),
+      amount_text: formatMoney((res && res.amount_cents) || amountCents),
+      pay_amount_cents: res && res.pay_amount_cents !== undefined ? Number(res.pay_amount_cents) : null,
+      /** 微信侧的支付链接：**保留给自动化**，但人看的流程走 pay_url（下面那行） */
+      code_url: (res && res.code_url) || null,
+      /** ★ 收银台地址：人点它、自动化也可以直接开它 */
+      pay_url: payUrl,
+      expires_at_minutes: (res && res.expires_at_minutes) || null,
+      wallet_paid_cents: Number((res && res.wallet_paid_cents) || 0),
+      open_browser: { attempted: false, opened: false, tried: [], url: payUrl || '', skipped_reason: null },
+      /** ★ 给 AI 端"照着念"的一句话（下面 openUrlForUser 之后会按实际情况覆盖） */
+      paste_text: payUrl ? browserPasteText(payUrl, { kind: 'pay' }) : null,
+    };
+
+    /**
+     * 自动打开收银台。
+     *
+     * ⚠️ 复用 `login.mjs` 的 `openUrlForUser`（多策略 + 结果归一化 + ★「默认总是尝试打开」闸门），
+     *    **不是**在这里再写一份 spawn —— 那几个坑（cmd start 的引号、URL 里的 `&`
+     *    被 shell 吃掉、error 事件没挂）在那边已经踩过并修过，复制一份必然会再踩。
+     * ⚠️ 打开失败**绝不允许**让命令失败：地址已经完整打印（人类可读）并放在
+     *    `--json` 的 `pay_url` 里，手动复制照样能完成支付。
+     * ⚠️ 闸门在 `openUrlForUser` **内部**：这里不再自己判断"要不要开"（除了 payUrl 有没有），
+     *    否则总有一天会出现"授权不弹、支付还弹"。
+     */
+    if (payUrl) {
+      data.open_browser = await openUrlForUser(payUrl, {
+        deps: {
+          openBrowser: ctx.openBrowser,
+          spawnImpl: ctx.spawnImpl,
+          platform: ctx.platform,
+          verbose: !!(ctx.config && ctx.config.verbose),
+          /** ★ 与 login 同源的四个事实（见 login.mjs 的 resolveBrowserIntent） */
+          isTTY: ctx.isTTY === true,
+          json: out.json === true,
+          forceOpen: flags.openBrowser === true,
+          noBrowser: flags.noBrowser === true,
+        },
+        log: (m) => out.info(m),
+      });
+      data.paste_text = browserPasteText(payUrl, { kind: 'pay' });
+    }
+
+    if (!out.json) {
+      out.head('充值订单已创建');
+      out.line(`  订单号：${data.order_id}`);
+      out.line(`  金额：${data.amount_text}`);
+      out.line(`  有效期：${data.expires_at_minutes ?? '?'} 分钟`);
+      if (payUrl) {
+        out.line('');
+        out.line('  收银台（我们网站的充值页面，请在这里扫码支付）：');
+        out.line(`  ${payUrl}`);
+        if (flags.noBrowser === true) {
+          out.info('  （已按 --no-browser 跳过自动打开）请把上面这一整行复制到浏览器地址栏打开。');
+        } else if (data.open_browser.opened) {
+          // ★ 成功：明说"已经打开了"（老板最终拍板走传统路线：弹系统浏览器）
+          out.line(browserOpenedText({ kind: 'pay' }));
+        } else {
+          /**
+           * 打开失败：与 login 同一段文案（`browserFailedHintLines`）——
+           *   1. **醒目**：说清"没能自动打开"，别让用户以为还在打开中；
+           *   2. **可操作**：把**完整地址再打一遍**，并说清动作是"复制→粘贴到地址栏"；
+           *   3. 说清打开之后干什么（用微信扫码）。
+           */
+          for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: ctx.isTTY !== true })) {
+            out.line(line);
+          }
+        }
+
+        /**
+         * ★ 2026-10-02（老板）：**支付完成之后那个页面会自己关掉** —— 提前交代一句。
+         *   为什么要说：页面"自己没了"时，用户第一反应是"是不是崩了 / 是不是没付成功"；
+         *   提前说一句，这件事就变成"预期之内"。
+         *   ⚠️ 后半句"没关就手动关掉即可"**不能省**：`window.close()` 只对**脚本打开的**窗口
+         *      有效，收银台是导航过去的 ⇒ **大概率关不掉**（详见
+         *      `admin-web/src/pages/billing/pay` 的「尝试自动关闭」注释）。
+         */
+        out.info('（支付成功后页面会自动尝试关闭；没关就手动关掉即可。）');
+
+        /**
+         * 终端二维码：**只在网页打不开时**作为兜底。
+         * ⚠️ 老板明确否掉了"本地生成二维码让别人扫"当**主流程**的做法：
+         *    二维码只是收银台页面内部的一个展示件；终端里画码这条路必须降级，
+         *    而且要说清"正常应该在我们网站的收银台页面上扫"。
+         */
+        const 网页没打开 = data.open_browser.attempted && !data.open_browser.opened;
+        if (网页没打开 && data.code_url) {
+          out.line('');
+          out.info('  兜底：网页确实打不开时，也可以直接用微信扫下面这个二维码。');
+          out.info('  （正常流程请在上面那个收银台页面里扫码支付。）');
+          const qrShown = await renderQrOptional(data.code_url, out);
+          if (!qrShown) {
+            out.info('  （未安装可选的 qrcode-terminal，无法在终端画码；请用上面的收银台地址付款）');
+          }
+        }
+        out.line('');
+        out.line(`  支付完成后运行：wkgeo orders check ${data.order_id}   # 查支付结果与最新余额`);
+      } else if (data.code_url) {
+        out.warn('没有拼出收银台地址（订单号缺失），只能给出微信支付链接');
+        out.line(`  ${data.code_url}`);
+      } else {
+        out.warn('服务端没有返回 code_url（可能微信支付参数未配置），请到网页后台核对');
+      }
+      out.info('  CLI 不会替你付款，也不会模拟支付成功。');
+    } else if (payUrl) {
+      /**
+       * ★ `--json` / 非 TTY 时，**人看的那段提示不能消失**：走 stderr（`out.notice`），
+       *   stdout 依然只有机器可读 JSON；结构化字段（`pay_url` / `paste_text` / `open_browser`）
+       *   照样都在 stdout 里。
+       *
+       * ★ 老板最终拍板走传统路线后，这里的分支变成"如实播报结果"：
+       *   * `--no-browser` → 明说跳过了（地址仍要打印，用户得能复制）；
+       *   * 打开成功      → 说一句"已为你打开浏览器"；
+       *   * 打开失败      → ⚠️ 那段**含完整地址**的醒目提示（AI 端/用户就靠它手动打开）。
+       *     ⚠️ 失败提示**不能只给 JSON**：真客户不会去 `pay_url` 字段里翻地址。
+       */
+      if (flags.noBrowser === true) {
+        out.notice('（已按 --no-browser 跳过自动打开）请手动复制 pay_url 到浏览器地址栏打开。');
+      } else if (data.open_browser.opened) {
+        out.notice(browserOpenedText({ kind: 'pay' }));
+      } else {
+        for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: true })) out.notice(line);
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};

package/lib/commands/index.mjs

@@ -0,0 +1,160 @@
+/**
+ * 命令注册表 + 帮助文本。
+ *
+ * 为什么注册表要同时带着 `usage`/`flags`/`args`：
+ *   * 解析器用它做校验（未知参数直接报错，不静默忽略）
+ *   * `--help` 用它生成文本 —— **帮助与实际行为同源**，不会出现"文档写了但命令不支持"
+ */
+
+import { GLOBAL_FLAGS } from '../args.mjs';
+import { loginCommand, logoutCommand, whoamiCommand, configCommand } from './auth.mjs';
+import { sitesListCommand, sitesCreateCommand, sitesDeleteCommand } from './sites.mjs';
+import { walletCommand, walletTxnsCommand, walletRechargeCommand } from './billing.mjs';
+import {
+  productsListCommand,
+  ordersCreateCommand,
+  ordersCheckCommand,
+  ordersPayCommand,
+  ordersGetCommand,
+  ordersListCommand,
+} from './orders.mjs';
+import { appsListCommand, appsRevokeCommand } from './apps.mjs';
+import { skillCommand } from './skill.mjs';
+
+export const COMMANDS = [
+  loginCommand,
+  whoamiCommand,
+  logoutCommand,
+  sitesCreateCommand,
+  sitesListCommand,
+  sitesDeleteCommand,
+  walletCommand,
+  walletTxnsCommand,
+  walletRechargeCommand,
+  productsListCommand,
+  ordersCreateCommand,
+  ordersCheckCommand,
+  ordersPayCommand,
+  ordersGetCommand,
+  ordersListCommand,
+  appsListCommand,
+  appsRevokeCommand,
+  /**
+   * `skill`：把随包分发的 `SKILL.md` 原文打印出来（AI 端自取手册）。
+   * 放在 config 前面 —— 两者同属「（基础）」，都是"不登录也能跑"的本地命令。
+   */
+  skillCommand,
+  configCommand,
+];
+
+export const COMMAND_NAMES = COMMANDS.map((c) => c.name);
+
+/**
+ * 分组规则：两词命令（`sites create`）归到第一个词下；
+ * 单词命令如果**同时是某个分组名**（`wallet` 有 `wallet txns` 子命令）也归到自己名下。
+ * 否则归「（基础）」。这样帮助里的分组跟人的直觉一致。
+ */
+function groupOf(command) {
+  if (command.name.includes(' ')) return command.name.split(' ')[0];
+  if (COMMANDS.some((c) => c.name.startsWith(`${command.name} `))) return command.name;
+  return '（基础）';
+}
+
+/**
+ * 会"按时间等"的通用参数必须把**单位**写进帮助里。
+ *
+ * 踩过的坑：`--timeout` 原来按毫秒解释，`--timeout 600` 变成 600 毫秒（0.8 秒就超时），
+ * 而帮助里连单位都没写 —— 用户完全没法从 `--help` 看出自己写错了。
+ * 这里直接引用 `GLOBAL_FLAGS` 的描述（**帮助与解析同源**，不会出现"文档写了但行为不一样"）。
+ */
+function renderTimedGlobalFlags() {
+  return [
+    `  --timeout <时长>      ${GLOBAL_FLAGS.timeout.desc}`,
+    `  --http-timeout <毫秒> ${GLOBAL_FLAGS['http-timeout'].desc}`,
+  ];
+}
+
+/** 人类可读帮助。`wkgeo --help` / `wkgeo help` / `wkgeo sites create --help` 都走它 */
+export function renderHelp(name = null) {
+  const line = (s = '') => s;
+  const spec = name ? COMMANDS.find((c) => c.name === name) : null;
+
+  if (spec) {
+    const out = [];
+    out.push(line(`wkgeo ${spec.name} —— ${spec.summary}`));
+    out.push('');
+    out.push(line('用法：'));
+    for (const u of String(spec.usage).split('\n')) out.push(line(`  ${u}`));
+    if (spec.args && spec.args.length) {
+      out.push('');
+      out.push(line('位置参数：'));
+      for (const a of spec.args) out.push(line(`  <${a.name}>${a.required ? '（必填）' : ''}  ${a.desc || ''}`));
+    }
+    const own = Object.entries(spec.flags || {});
+    if (own.length) {
+      out.push('');
+      out.push(line('命令参数：'));
+      for (const [k, v] of own) out.push(line(`  --${k}${v.type === 'boolean' ? '' : ' <值>'}${v.required ? '（必填）' : ''}  ${v.desc || ''}`));
+    }
+    /**
+     * 命令自带的"特别说明"（可选）。目前只有 `skill` 用 ——
+     * 它**不受**"非终端自动 JSON"约定约束，必须在自己的帮助里说清楚，
+     * 否则用户按通用说明去管道里拿 JSON 会拿到 markdown（反之亦然）。
+     */
+    if (spec.notes && spec.notes.length) {
+      out.push('');
+      out.push(line('特别说明：'));
+      for (const n of spec.notes) out.push(line(`  ${n}`));
+    }
+    out.push('');
+    out.push(line('通用参数：--json / --text / --base / --client-id / --credentials / --verbose / --help'));
+    out.push(line('（默认：输出到管道/非终端时自动使用 --json）'));
+    out.push('');
+    out.push(line('带单位的通用参数（写清单位，避免"600 被当成 600 毫秒"这类误解）：'));
+    for (const l of renderTimedGlobalFlags()) out.push(line(l));
+    return out.join('\n');
+  }
+
+  const groups = new Map();
+  for (const c of COMMANDS) {
+    const g = groupOf(c);
+    if (!groups.has(g)) groups.set(g, []);
+    groups.get(g).push(c);
+  }
+
+  const out = [];
+  out.push('云站平台官方 CLI —— 授权登录一次，之后建站 / 下单 / 钱包支付 / 查余额都不用再登录');
+  out.push('');
+  out.push('用法：wkgeo <命令> [参数]');
+  out.push('');
+  for (const [g, list] of groups) {
+    out.push(`${g}：`);
+    for (const c of list) out.push(`  ${c.name.padEnd(16)} ${c.summary}`);
+    out.push('');
+  }
+  out.push('常用示例：');
+  out.push('  wkgeo login                       # 浏览器授权一次，令牌存本地（30 天）');
+  out.push('  wkgeo whoami                      # 看当前登录的是谁');
+  out.push('  wkgeo sites create --name 我的站   # 建站（返回站点 id）');
+  out.push('  wkgeo products list               # 能买什么');
+  out.push('  wkgeo orders create --product storage_mb --units 1   # 下单（余额够就当场付清）');
+  out.push('  wkgeo wallet                      # 查余额 / wallet txns 看流水');
+  out.push('  wkgeo wallet recharge --amount-cents 1000            # 充值下单（微信扫码，需人工支付）');
+  out.push('  wkgeo orders check <订单ID>        # 查支付结果 + 最新余额');
+  out.push('  wkgeo orders list                 # 我的订单');
+  /**
+   * ⚠️ 这条示例是为了让 AI 端**能自己发现**手册入口：
+   *    手册一直随包分发（package.json 的 files 里有 SKILL.md），但在加 `skill` 命令之前
+   *    没有任何命令能把它取出来 —— AI 只能去 node_modules 里翻，等于"分发了但拿不到"。
+   */
+  out.push('  wkgeo skill                       # 打印给 AI 端的操作手册（随包分发）');
+  out.push('');
+  out.push('通用参数：--json（机器可读；非终端下默认开启）/ --text（强制人类可读）');
+  out.push('          --base <url> / --client-id <id> / --credentials <path> / --verbose / --help / --version');
+  out.push('');
+  out.push('带单位的通用参数（写清单位，避免"600 被当成 600 毫秒"这类误解）：');
+  for (const l of renderTimedGlobalFlags()) out.push(l);
+  out.push('');
+  out.push('退出码：0 成功 ｜ 1 失败 ｜ 2 用法错误 ｜ 3 需要（重新）授权 ｜ 4 被限流');
+  return out.join('\n');
+}