@optima-chat/tiktok-cli 0.13.0 → 0.15.0

package/README.md

@@ -23,7 +23,7 @@ tiktok <domain> <verb> --shop <shopId> [--flags]
 | `orders list` | 订单列表（`--status --page-size --since`） |
 | `orders get --id <id>` | 订单详情 |
 | `analytics shop` | 店铺经营数据（`--from --to`，默认近30天） |
-| `analytics products` | 商品维度数据（GMV 降序） |
+| `analytics products` | 商品维度数据（GMV 降序）。`--version` 默认 `202509`；`202605` 返回 `total_performance` + 分渠道 `*_performance` 组（**组是可选的、字段名三套变体、`overall_performance` 在新版不存在**，见 spec §3.0）；未知版本本地拒，平台出新版可 `--force-version` 直接试；`--page-token` 翻页，**末页 `next_page_token` 为空串**（不是缺席） |
 | `products list` | 商品列表 |
 | `promotions list` | 促销活动。`--status` **省略 = 全部状态**（`ONGOING`/`NOT_START`/`EXPIRED`/`DEACTIVATED`；⚠️ 值写错平台**静默忽略并返回全部**，故 CLI **本地硬拒未知值**；平台将来新增值可用 `--force-status` 越过）；`--page-size`（默认 20）；`--page-token` 翻页，**末页无 `next_page_token`** |
 | `finance statements` | 结算单 |
@@ -55,6 +55,20 @@ tiktok promotions create-flashsale --shop=<id> --price=11.9    # 等号式
 
 （0.10.2 之前只认空格式，等号式会让那一格参数**静默消失**而命令照报成功，见 #11。）
 
+**每条命令只认它自己的参数**（`tiktok <命令> --help` 列出来），外加全局 `--shop` / `--apply`。
+不认的参数、多余的位置参数、`-f` 这类短参数一律**当场报 `VALIDATION`、不发请求**，并尽量给出最接近的写法：
+
+```bash
+tiktok orders list --shop <id> --days 14
+# ⇒ VALIDATION：orders list：不认 --days（这条命令没有 --days；近 N 天用起点表示，如 --from 2026-09-06 …）。…
+tiktok products get --shop <id> --product-id 1737…
+# ⇒ VALIDATION：products get：不认 --product-id（你是想用 --product 吗？）。…
+```
+
+报错体里另有 `unknown_flags` / `extra_positional` / `allowed_flags` 三个机读字段。
+（此前不认的参数被**静默丢掉**、按默认值跑出一份看起来正常的结果：`--days 14` 实际查的是 30 天，
+`--product-id` 请求的是 `/products/undefined`，见 #25。）
+
 **开关型 flag**（`--apply` / `--enable` / `--default` / `--unprocessed`）除了裸传，也能带值：
 `true`/`1`/`yes`/`on` 为真，`false`/`0`/`no`/`off`/空串为假（大小写不敏感），
 给它别的值**当场报错**而不是猜。同一个 flag 写两次以后者为准（`--apply=false --apply` 会真发）。

package/dist/index.js

@@ -3,6 +3,103 @@
 // src/commands.ts
 import { readFileSync as readFileSync2 } from "fs";
 
+// src/flags.ts
+var GLOBAL_FLAGS = ["shop", "actor", "apply", "help"];
+var ENTITY_FLAGS = ["product", "order", "package", "video", "sku", "creator", "conversation", "category", "warehouse", "shop"];
+var SYNONYMS = {
+  "limit": "page-size",
+  "size": "page-size",
+  "pagesize": "page-size",
+  "per-page": "page-size",
+  "start": "from",
+  "start-date": "from",
+  "begin": "from",
+  "since-date": "from",
+  "end": "to",
+  "end-date": "to",
+  "until": "to",
+  "qty": "quantity",
+  "shop-id": "shop",
+  "shopid": "shop",
+  "shop_id": "shop"
+};
+var DAY_MS = 864e5;
+function editDistance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+    }
+  }
+  return dp[a.length][b.length];
+}
+function suggestFlag(unknown, allowed, value, now = Date.now(), cmdName = "") {
+  const u = unknown.toLowerCase();
+  const dashed = u.replace(/_/g, "-");
+  const cands = [...allowed, ...GLOBAL_FLAGS.filter((g) => g !== "help")];
+  if (dashed === "days" && allowed.includes("from")) {
+    const n = Number(value);
+    const eg = Number.isFinite(n) && n > 0 ? new Date(now - n * DAY_MS).toISOString().slice(0, 10) : "<YYYY-MM-DD>";
+    const forms = allowed.includes("since") ? "YYYY-MM-DD \u6216 unix \u79D2" : "YYYY-MM-DD";
+    return `\u8FD9\u6761\u547D\u4EE4\u6CA1\u6709 --days\uFF1B\u8FD1 N \u5929\u7528\u8D77\u70B9\u8868\u793A\uFF0C\u5982 --from ${eg}\uFF08\u8D77\u6B62\u7528 --from / --to\uFF0C\u53D6 ${forms}\uFF09`;
+  }
+  if (dashed === "dry-run") {
+    return "\u4E0D\u9700\u8981 --dry-run\uFF1A\u5199\u547D\u4EE4\u9ED8\u8BA4\u5C31\u53EA\u9884\u89C8\u3001\u4E0D\u52A0 --apply \u4E0D\u4F1A\u771F\u53D1\uFF1B\u8BFB\u547D\u4EE4\u672C\u6765\u5C31\u4E0D\u5199\u3002\u53BB\u6389\u5B83\u5373\u53EF";
+  }
+  const syn = SYNONYMS[dashed] ?? SYNONYMS[u];
+  if (syn && cands.includes(syn)) return `--${syn}`;
+  if (dashed !== unknown && cands.includes(dashed)) return `--${dashed}`;
+  const base = dashed.replace(/-?ids?$/, "");
+  if (base && base !== dashed && ENTITY_FLAGS.includes(base) && cands.includes(base)) return `--${base}`;
+  if (dashed === "id") {
+    if (/\b(list|search|recommend)\b/.test(cmdName)) return null;
+    const ents = allowed.filter((f) => ENTITY_FLAGS.includes(f));
+    if (ents.length === 1) return `--${ents[0]}`;
+    return null;
+  }
+  let best = null;
+  let bestD = Infinity;
+  for (const f of cands) {
+    const d = editDistance(dashed, f);
+    if (d < bestD) {
+      best = f;
+      bestD = d;
+    }
+  }
+  const shortest = Math.min(dashed.length, (best ?? "").length);
+  const limit = shortest <= 3 ? 0 : shortest <= 6 ? 1 : 2;
+  const NEG = /^(un|dis|non|in)/;
+  if (best && best.replace(NEG, "") === dashed.replace(NEG, "") && best !== dashed) return null;
+  if (best && bestD <= limit) return `--${best}`;
+  return null;
+}
+function checkFlags(cmdName, args2, allowed, rest = [], now = Date.now(), noShop = false) {
+  const known = /* @__PURE__ */ new Set([...allowed, ...GLOBAL_FLAGS]);
+  const unknown = Object.keys(args2).filter((k) => !known.has(k));
+  if (unknown.length === 0 && rest.length === 0) return null;
+  const parts = [];
+  for (const k of unknown) {
+    if (k === "") {
+      parts.push(`\u4E0D\u8BA4 --=${args2[k]}\uFF08\u6CA1\u6709\u53C2\u6570\u540D\uFF09`);
+      continue;
+    }
+    const hint = suggestFlag(k, allowed, args2[k], now, cmdName);
+    parts.push(!hint ? `\u4E0D\u8BA4 --${k}` : hint.startsWith("--") ? `\u4E0D\u8BA4 --${k}\uFF08\u4F60\u662F\u60F3\u7528 ${hint} \u5417\uFF1F\uFF09` : `\u4E0D\u8BA4 --${k}\uFF08${hint}\uFF09`);
+  }
+  if (rest.length > 0) {
+    parts.push(`\u591A\u4F59\u7684\u4F4D\u7F6E\u53C2\u6570 ${rest.map((r) => JSON.stringify(r)).join(" ")}\uFF08\u672C CLI \u7684\u53C2\u6570\u90FD\u7528 --\u957F\u53C2\u6570 \u4F20\uFF0C\u4E0D\u6536\u4F4D\u7F6E\u53C2\u6570\u548C -x \u77ED\u53C2\u6570\uFF1B\u503C\u91CC\u6709\u7A7A\u683C\u5C31\u7ED9\u6574\u4E2A\u503C\u52A0\u5F15\u53F7\uFF0C\u5982 --title "Flash Sale"\uFF09`);
+  }
+  const allowedText = allowed.length ? allowed.map((f) => `--${f}`).join(" ") : "\uFF08\u6CA1\u6709\u4E13\u5C5E\u53C2\u6570\uFF09";
+  return {
+    unknown_flags: unknown,
+    extra_positional: [...rest],
+    allowed_flags: [...allowed],
+    message: `${cmdName}\uFF1A${parts.join("\uFF1B")}\u3002\u8FD9\u6761\u547D\u4EE4\u8BA4\u7684\u53C2\u6570\uFF1A${allowedText}\uFF08\u53E6\u6709\u5168\u5C40 ${noShop ? "--apply" : "--shop / --apply"}\uFF09\u3002\u26D4 \u6CA1\u53D1\u8BF7\u6C42 \u2014\u2014 \u4E0D\u8BA4\u7684\u53C2\u6570\u539F\u6765\u4F1A\u88AB\u9759\u9ED8\u4E22\u6389\u3001\u6309\u9ED8\u8BA4\u503C\u8DD1\u51FA\u4E00\u4EFD\u770B\u8D77\u6765\u6B63\u5E38\u7684\u7ED3\u679C\u3002`
+  };
+}
+
 // src/client.ts
 import { readFileSync } from "fs";
 import { homedir } from "os";
@@ -209,19 +306,26 @@ function fillEmptyList(data, listKey) {
   if (!(listKey in d)) d[listKey] = [];
 }
 function commandUsage(cmd) {
-  return `tiktok ${cmd.name} --shop <shopId> [--flags]
+  const flags = cmd.flags?.length ? cmd.flags.map((f) => `--${f}`).join(" ") : "\uFF08\u6CA1\u6709\u4E13\u5C5E\u53C2\u6570\uFF09";
+  const shop = cmd.noShop ? "" : " --shop <shopId>";
+  const globals = cmd.noShop ? "--apply" : "--shop / --apply";
+  return `tiktok ${cmd.name}${shop} [--flags]
 
 ${cmd.summary}
+
+\u8BA4\u7684\u53C2\u6570\uFF1A${flags}\uFF08\u53E6\u6709\u5168\u5C40 ${globals}\uFF09\uFF1B\u4E0D\u8BA4\u7684\u4F1A\u5F53\u573A\u62A5\u9519\u3002
 `;
 }
 var today = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var daysAgo = (n) => new Date(Date.now() - n * 864e5).toISOString().slice(0, 10);
 var toEpoch = (v) => /^\d+$/.test(v) ? Number(v) : Math.floor(Date.parse(v) / 1e3);
 var PROMOTION_STATUSES = /* @__PURE__ */ new Set(["ONGOING", "NOT_START", "EXPIRED", "DEACTIVATED"]);
+var ANALYTICS_PRODUCT_VERSIONS = /* @__PURE__ */ new Set(["202509", "202605"]);
 var COMMANDS = [
   {
     name: "orders list",
     summary: "\u8BA2\u5355\u5217\u8868\uFF08\u9ED8\u8BA4\u8FD130\u5929\u3001\u6309\u521B\u5EFA\u65F6\u95F4\u5012\u5E8F\uFF1B--from/--to\uFF08unix\u79D2\u6216YYYY-MM-DD\uFF09--status --page-size --sort-order ASC/DESC --sort-field create_time/update_time\uFF09",
+    flags: ["from", "page-size", "page-token", "since", "sort-field", "sort-order", "status", "to"],
     listKey: "orders",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/order/202309/orders/search", {
       query: {
@@ -243,12 +347,14 @@ var COMMANDS = [
   {
     name: "orders get",
     summary: "\u8BA2\u5355\u8BE6\u60C5\uFF08--id \u5FC5\u586B\uFF09",
+    flags: ["id"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/order/202309/orders/detail", { query: { ids: args2.id } })
   },
   // ── 售后（退货/取消）只读 ──
   {
     name: "orders cancellations",
     summary: "\u53D6\u6D88\u5355\u5217\u8868\uFF08--status \u53EF\u9009\uFF0C--page-size\uFF09",
+    flags: ["page-size", "status"],
     listKey: "cancellations",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/return_refund/202309/cancellations/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -258,6 +364,7 @@ var COMMANDS = [
   {
     name: "orders returns",
     summary: "\u9000\u8D27\u5355\u5217\u8868\uFF08--status \u53EF\u9009\uFF0C--page-size\uFF09",
+    flags: ["page-size", "status"],
     listKey: "return_orders",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/return_refund/202309/returns/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -267,16 +374,19 @@ var COMMANDS = [
   {
     name: "orders return-records",
     summary: "\u9000\u8D27\u5355\u5904\u7406\u8BB0\u5F55\uFF08--id return_id\uFF09",
+    flags: ["id"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/return_refund/202309/returns/${args2.id}/records`, {})
   },
   {
     name: "orders aftersale-eligibility",
     summary: "\u8BA2\u5355\u552E\u540E\u8D44\u683C\uFF08--order id\uFF09",
+    flags: ["order"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/return_refund/202512/orders/${args2.order}/aftersale_eligibility`, {})
   },
   {
     name: "orders reject-reasons",
     summary: "\u9A73\u56DE\u53D6\u6D88/\u9000\u8D27\u7684\u5408\u6CD5\u7406\u7531\uFF08--id return_or_cancel_id\uFF09",
+    flags: ["id"],
     listKey: "reasons",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/return_refund/202309/reject_reasons", {
       query: { return_or_cancel_id: args2.id }
@@ -285,6 +395,7 @@ var COMMANDS = [
   {
     name: "orders refund-calculate",
     summary: "\u8BA1\u7B97\u9000\u6B3E\u989D\uFF08--body-file calc.json\uFF09",
+    flags: ["body-file"],
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/return_refund/202309/refunds/calculate", {
       body: readBodyFile(args2["body-file"])
     })
@@ -293,11 +404,13 @@ var COMMANDS = [
   {
     name: "orders tracking",
     summary: "\u8BA2\u5355\u7269\u6D41\u8DDF\u8E2A\uFF08--order id\uFF09",
+    flags: ["order"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/fulfillment/202309/orders/${args2.order}/tracking`, {})
   },
   {
     name: "orders shipping-services",
     summary: "\u8BA2\u5355\u53EF\u7528\u627F\u8FD0/\u914D\u9001\u670D\u52A1\uFF08--order id\uFF09",
+    flags: ["order"],
     run: ({ shop, args: args2 }) => proxy("POST", shop, `/fulfillment/202309/orders/${args2.order}/shipping_services/query`, {
       body: {}
     })
@@ -305,6 +418,7 @@ var COMMANDS = [
   {
     name: "packages search",
     summary: "\u5305\u88F9\u5217\u8868\uFF08--page-size\uFF09",
+    flags: ["page-size"],
     listKey: "packages",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/fulfillment/202309/packages/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -314,17 +428,20 @@ var COMMANDS = [
   {
     name: "packages get",
     summary: "\u5305\u88F9\u8BE6\u60C5\uFF08--package id\uFF09",
+    flags: ["package"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/fulfillment/202309/packages/${args2.package}`, {})
   },
   {
     name: "packages documents",
     summary: "\u5305\u88F9\u7269\u6D41\u9762\u5355\uFF08--package id\uFF09",
+    flags: ["package"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/fulfillment/202309/packages/${args2.package}/shipping_documents`, {})
   },
   // ── 售后审批 / 发货 写（不可逆，默认 dry-run，--apply 才提交）──
   {
     name: "orders cancel-approve",
     summary: "\u6279\u51C6\u53D6\u6D88\u5355\uFF08--id cancel_id\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u6279\u3002\u4E0D\u53EF\u9006",
+    flags: ["id"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u6279\u51C6\u53D6\u6D88\u5355",
@@ -337,6 +454,7 @@ var COMMANDS = [
   {
     name: "orders cancel-reject",
     summary: "\u9A73\u56DE\u53D6\u6D88\u5355\uFF08--id --reason\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u9A73\u3002\u4E0D\u53EF\u9006",
+    flags: ["id", "reason"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u9A73\u56DE\u53D6\u6D88\u5355",
@@ -354,6 +472,7 @@ var COMMANDS = [
   {
     name: "orders return-approve",
     summary: "\u6279\u51C6\u9000\u8D27\u5355\uFF08--id return_id\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u6279\u3002\u4E0D\u53EF\u9006",
+    flags: ["id"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u6279\u51C6\u9000\u8D27\u5355",
@@ -366,6 +485,7 @@ var COMMANDS = [
   {
     name: "orders return-reject",
     summary: "\u9A73\u56DE\u9000\u8D27\u5355\uFF08--id --reason\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u9A73\u3002\u4E0D\u53EF\u9006",
+    flags: ["id", "reason"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u9A73\u56DE\u9000\u8D27\u5355",
@@ -383,6 +503,7 @@ var COMMANDS = [
   {
     name: "orders create-package",
     summary: "\u4E3A\u8BA2\u5355\u5EFA\u5305\u88F9\uFF08--order id --body-file pkg.json\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u5EFA\u3002\u4EC5\u76F4\u53D1\u5546\u5BB6\uFF08\u7269\u6D41\u9ED8\u8BA4 ERP \u7BA1\uFF09",
+    flags: ["body-file", "order"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u5EFA\u5305\u88F9",
@@ -400,6 +521,7 @@ var COMMANDS = [
   {
     name: "packages ship",
     summary: "\u53D1\u8D27\uFF08--package id --body-file ship.json\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1\u3002\u4E0D\u53EF\u9006\uFF0C\u4EC5\u76F4\u53D1\u5546\u5BB6",
+    flags: ["body-file", "package"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u53D1\u8D27",
@@ -418,6 +540,7 @@ var COMMANDS = [
   {
     name: "events",
     summary: "\u67E5\u5E97\u94FA webhook \u4E8B\u4EF6\uFF08--type \u9017\u53F7\u5206\u9694 --since 1d/unix --unprocessed --limit\uFF09",
+    flags: ["limit", "since", "type", "unprocessed"],
     run: ({ shop, args: args2 }) => {
       const q = {};
       if (args2.type) q.type = args2.type;
@@ -430,6 +553,7 @@ var COMMANDS = [
   {
     name: "events ack",
     summary: "\u6807\u4E8B\u4EF6\u5DF2\u5904\u7406\uFF08--ids id1,id2 \u6216 --before <ts>\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u6807",
+    flags: ["before", "ids"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u6807\u4E8B\u4EF6\u5DF2\u5904\u7406",
@@ -442,6 +566,7 @@ var COMMANDS = [
   {
     name: "analytics shop",
     summary: "\u5E97\u94FA\u7ECF\u8425\u6570\u636E\uFF08--from --to\uFF0C\u9ED8\u8BA4\u8FD130\u5929\uFF09",
+    flags: ["from", "granularity", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop/performance", {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -452,20 +577,49 @@ var COMMANDS = [
   },
   {
     name: "analytics products",
-    summary: "\u5546\u54C1\u7EF4\u5EA6\u7ECF\u8425\u6570\u636E\uFF08\u6309 GMV \u964D\u5E8F\uFF09",
-    run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop_products/performance", {
-      query: {
-        start_date_ge: args2.from ?? daysAgo(30),
-        end_date_lt: args2.to ?? today(),
-        sort_field: "gmv",
-        sort_order: "DESC",
-        page_size: args2["page-size"] ?? "20"
+    summary: "\u5546\u54C1\u7EF4\u5EA6\u7ECF\u8425\u6570\u636E\uFF08\u6309 GMV \u964D\u5E8F\uFF1B--from --to \u9ED8\u8BA4\u8FD130\u5929\uFF1B--version 202509 \u9ED8\u8BA4\uFF5C202605 = \u5546\u54C1\u7EA7 key \u6362\u6210 total_performance + \u5206\u6E20\u9053 *_performance \u7EC4\uFF08\u7EC4\u53EF\u9009\u3001\u5B57\u6BB5\u540D\u6709\u4E09\u5957\u53D8\u4F53\uFF09\uFF0C\u672A\u77E5\u7248\u672C\u672C\u5730\u62D2\u3001\u5E73\u53F0\u5C06\u6765\u51FA\u65B0\u7248\u53EF\u7528 --force-version \u76F4\u63A5\u8BD5\uFF1B--page-size \u9ED8\u8BA420\uFF1B--page-token \u7FFB\u9875\uFF0C\u672B\u9875 next_page_token \u4E3A\u7A7A\u4E32\uFF09",
+    flags: ["force-version", "from", "page-size", "page-token", "to", "version"],
+    listKey: "products",
+    run: ({ shop, args: args2 }) => {
+      const ver = args2.version ? String(args2.version) : "202509";
+      if (!/^\d{6}$/.test(ver)) {
+        return Promise.resolve({
+          ok: false,
+          error: {
+            code: "VALIDATION",
+            message: `--version \u5FC5\u987B\u662F 6 \u4F4D\u6570\u5B57\uFF08\u5DF2\u77E5\u53D6\u503C\uFF1A${[...ANALYTICS_PRODUCT_VERSIONS].join(" / ")}\uFF09\uFF0C\u6536\u5230 ${JSON.stringify(ver)}\u3002\u26D4 \u683C\u5F0F\u4E0D\u5408\u6CD5\u65F6 --force-version \u4E5F\u4E0D\u653E\u884C\uFF0C\u4E0D\u53D1\u8BF7\u6C42\u3002`,
+            retryable: false
+          }
+        });
       }
-    })
+      if (!ANALYTICS_PRODUCT_VERSIONS.has(ver) && !args2["force-version"]) {
+        return Promise.resolve({
+          ok: false,
+          error: {
+            code: "VALIDATION",
+            message: `\u672A\u77E5\u7684 --version ${JSON.stringify(ver)}\uFF1B\u5DF2\u77E5\u53D6\u503C\uFF1A${[...ANALYTICS_PRODUCT_VERSIONS].join(" / ")}\u3002\u5E73\u53F0\u82E5\u5DF2\u53D1\u5E03\u65B0\u7248\u672C\uFF0C\u53EF\u52A0 --force-version \u76F4\u63A5\u8BD5\uFF08\u7248\u672C\u4E0D\u5BF9\u5E73\u53F0\u4F1A\u660E\u786E\u56DE 36009004\uFF09\u3002\u672C\u5730\u62D2\uFF0C\u4E0D\u53D1\u8BF7\u6C42\u3002`,
+            retryable: false
+          }
+        });
+      }
+      return proxy("GET", shop, `/analytics/${ver}/shop_products/performance`, {
+        query: {
+          start_date_ge: args2.from ?? daysAgo(30),
+          end_date_lt: args2.to ?? today(),
+          sort_field: "gmv",
+          sort_order: "DESC",
+          page_size: args2["page-size"] ?? "20",
+          // 有值才带（照 analytics videos）。实测（spec §3.0 用例 07）：第 1 页 token 翻到第 2 页零交集；
+          // 🔴 末页 next_page_token **键在、值为空串 ""**（不是缺席，与 promotions list 不同构）。
+          ...args2["page-token"] ? { page_token: args2["page-token"] } : {}
+        }
+      });
+    }
   },
   {
     name: "analytics videos",
     summary: "\u5185\u5BB9\u89C6\u9891\u7EF4\u5EA6\u7ECF\u8425\u6570\u636E\uFF08shop_videos\uFF0C--from --to\uFF0C\u9ED8\u8BA4\u8FD130\u5929\uFF0C\u6309 GMV \u964D\u5E8F\uFF1B--sort-field --sort-order --page-size --page-token\uFF09",
+    flags: ["from", "page-size", "page-token", "sort-field", "sort-order", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop_videos/performance", {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -480,6 +634,7 @@ var COMMANDS = [
   {
     name: "analytics videos-overview",
     summary: "\u5185\u5BB9\u89C6\u9891\u6574\u4F53\u6982\u89C8\uFF08shop_videos overview\uFF1B--from --to --granularity\uFF09",
+    flags: ["from", "granularity", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop_videos/overview_performance", {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -491,6 +646,7 @@ var COMMANDS = [
   {
     name: "analytics video",
     summary: "\u5355\u6761\u89C6\u9891\u7ECF\u8425\u660E\u7EC6\uFF08--video video_id \u5FC5\u586B\uFF1B--from --to\uFF09",
+    flags: ["from", "to", "video"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/analytics/202509/shop_videos/${args2.video}/performance`, {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -501,6 +657,7 @@ var COMMANDS = [
   {
     name: "analytics video-products",
     summary: "\u5355\u6761\u89C6\u9891\u5E26\u8D27\u5546\u54C1\u8868\u73B0\uFF08--video video_id \u5FC5\u586B\uFF1B--from --to --page-size\uFF09",
+    flags: ["from", "page-size", "to", "video"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/analytics/202509/shop_videos/${args2.video}/products/performance`, {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -512,6 +669,7 @@ var COMMANDS = [
   {
     name: "analytics lives",
     summary: "\u76F4\u64AD\u7EF4\u5EA6\u7ECF\u8425\u6570\u636E\uFF08shop_lives\uFF0C--from --to\uFF0C\u9ED8\u8BA4\u8FD130\u5929\uFF0C\u6309 GMV \u964D\u5E8F\uFF1B--sort-field --sort-order --page-size --page-token\uFF09",
+    flags: ["from", "page-size", "page-token", "sort-field", "sort-order", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop_lives/performance", {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -526,6 +684,7 @@ var COMMANDS = [
   {
     name: "analytics lives-overview",
     summary: "\u76F4\u64AD\u6574\u4F53\u6982\u89C8\uFF08shop_lives overview\uFF1B--from --to --granularity\uFF09",
+    flags: ["from", "granularity", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop_lives/overview_performance", {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -537,6 +696,7 @@ var COMMANDS = [
   {
     name: "analytics skus",
     summary: "SKU \u7EF4\u5EA6\u7ECF\u8425\u6570\u636E\uFF08shop_skus\uFF0C--from --to\uFF0C\u9ED8\u8BA4\u8FD130\u5929\uFF0C\u6309 GMV \u964D\u5E8F\uFF1B--sort-field --sort-order --page-size --page-token\uFF09",
+    flags: ["from", "page-size", "page-token", "sort-field", "sort-order", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop_skus/performance", {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -551,6 +711,7 @@ var COMMANDS = [
   {
     name: "analytics sku",
     summary: "\u5355\u4E2A SKU \u7ECF\u8425\u660E\u7EC6\uFF08--sku sku_id \u5FC5\u586B\uFF1B--from --to --granularity\uFF09",
+    flags: ["from", "granularity", "sku", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/analytics/202509/shop_skus/${args2.sku}/performance`, {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -562,6 +723,7 @@ var COMMANDS = [
   {
     name: "analytics product",
     summary: "\u5355\u4E2A\u5546\u54C1\u7ECF\u8425\u660E\u7EC6\uFF08--product product_id \u5FC5\u586B\uFF1B--from --to --granularity\uFF09",
+    flags: ["from", "granularity", "product", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/analytics/202509/shop_products/${args2.product}/performance`, {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -573,11 +735,13 @@ var COMMANDS = [
   {
     name: "analytics shop-hourly",
     summary: "\u5E97\u94FA\u67D0\u5929\u5206\u65F6\uFF08\u9010\u5C0F\u65F6\uFF09\u7ECF\u8425\u6570\u636E\uFF08--date YYYY-MM-DD\uFF0C\u9ED8\u8BA4\u6628\u5929\uFF09",
+    flags: ["date"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/analytics/202510/shop/performance/${args2.date ?? daysAgo(1)}/performance_per_hour`, {})
   },
   {
     name: "products list",
     summary: "\u5546\u54C1\u5217\u8868\uFF08--status ACTIVATE \u53EA\u53D6\u5728\u552E\uFF1B\u4E0D\u4F20\u8FD4\u6240\u6709\u542B DELETED\uFF0C\u5199\u64CD\u4F5C\u524D\u52A1\u5FC5\u7B5B ACTIVATE\uFF09",
+    flags: ["page-size", "status"],
     listKey: "products",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/products/search", {
       query: { page_size: args2["page-size"] ?? "20" },
@@ -587,11 +751,13 @@ var COMMANDS = [
   {
     name: "products get",
     summary: "\u5355\u4E2A\u5546\u54C1\u5B8C\u6574\u8BE6\u60C5\uFF08--product id\uFF1B\u9010\u5B57\u6BB5\u56DE\u8BFB\u7528\uFF1A\u6807\u9898/\u63CF\u8FF0/\u56FE/SKU/\u4EF7/\u5E93\u5B58/\u91CD\u91CF/\u5C3A\u5BF8/\u5C5E\u6027\uFF09",
+    flags: ["product"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/products/${args2.product}`, {})
   },
   {
     name: "products diagnose",
     summary: "\u5546\u54C1\u5B98\u65B9\u95EE\u9898\u8BCA\u65AD\uFF08--product \u9017\u53F7\u5206\u9694\u672C\u5E97\u81EA\u6709\u5546\u54C1 id\uFF09",
+    flags: ["product"],
     listKey: "products",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202405/products/diagnoses", {
       query: { product_ids: String(args2.product ?? "") }
@@ -600,6 +766,7 @@ var COMMANDS = [
   {
     name: "promotions list",
     summary: "\u4FC3\u9500\u6D3B\u52A8\u5217\u8868\uFF08--status \u7701\u7565=\u5168\u90E8\u72B6\u6001\uFF5CONGOING/NOT_START/EXPIRED/DEACTIVATED\uFF0C\u53D6\u503C\u533A\u5206\u5927\u5C0F\u5199\u4E14\u4E0D trim\uFF0C\u672A\u77E5\u503C\u672C\u5730\u62D2\u3001\u5E73\u53F0\u4F1A\u9759\u9ED8\u8FD4\u56DE\u5168\u90E8\uFF1B--force-status \u8D8A\u8FC7\u672C\u5730\u6821\u9A8C\uFF1B--page-size \u9ED8\u8BA420\uFF1B--page-token \u7FFB\u9875\uFF0C\u672B\u9875\u65E0 next_page_token\uFF09",
+    flags: ["force-status", "page-size", "page-token", "status"],
     listKey: "activities",
     run: ({ shop, args: args2 }) => {
       const st = args2.status ? String(args2.status) : "";
@@ -631,6 +798,7 @@ var COMMANDS = [
   {
     name: "finance statements",
     summary: "\u7ED3\u7B97\u5355\u5217\u8868",
+    flags: ["page-size", "sort-field", "sort-order"],
     listKey: "statements",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/finance/202309/statements", {
       query: {
@@ -644,22 +812,26 @@ var COMMANDS = [
   {
     name: "seller status",
     summary: "\u8D26\u53F7/\u5E97\u94FA\u72B6\u6001\uFF08seller_status/shop_statuses/tax_form_status\uFF09",
+    flags: [],
     run: ({ shop }) => proxy("GET", shop, "/seller/202508/status", {})
   },
   {
     name: "seller permissions",
     summary: "\u5DF2\u6388\u6743\u6743\u9650\u5217\u8868",
+    flags: [],
     run: ({ shop }) => proxy("GET", shop, "/seller/202309/permissions", {})
   },
   // ===== 建品前置只读辅助命令 =====
   {
     name: "products prerequisites",
     summary: "\u5EFA\u54C1\u524D\u7F6E\u68C0\u67E5",
+    flags: [],
     run: ({ shop }) => proxy("GET", shop, "/product/202312/prerequisites", {})
   },
   {
     name: "categories recommend",
     summary: "\u7C7B\u76EE\u63A8\u8350\uFF08--title [--desc]\uFF09",
+    flags: ["desc", "title"],
     listKey: "categories",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/categories/recommend", {
       body: {
@@ -671,6 +843,7 @@ var COMMANDS = [
   {
     name: "categories tree",
     summary: "\u7C7B\u76EE\u6811\uFF08--version v2\uFF09",
+    flags: ["version"],
     listKey: "categories",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202309/categories", {
       query: { category_version: args2.version ?? "v2" }
@@ -679,6 +852,7 @@ var COMMANDS = [
   {
     name: "categories attributes",
     summary: "\u7C7B\u76EE\u5C5E\u6027\uFF08--category\uFF09",
+    flags: ["category", "version"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/categories/${args2.category}/attributes`, {
       query: { category_version: args2.version ?? "v2" }
     })
@@ -686,6 +860,7 @@ var COMMANDS = [
   {
     name: "categories rules",
     summary: "\u7C7B\u76EE\u89C4\u5219\uFF08--category\uFF09",
+    flags: ["category", "version"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/categories/${args2.category}/rules`, {
       query: { category_version: args2.version ?? "v2" }
     })
@@ -693,6 +868,7 @@ var COMMANDS = [
   {
     name: "brands list",
     summary: "\u54C1\u724C\u5217\u8868\uFF08[--category] [--name]\uFF09",
+    flags: ["category", "name", "page-size"],
     listKey: "brands",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202309/brands", {
       query: {
@@ -705,6 +881,7 @@ var COMMANDS = [
   {
     name: "brands recommend",
     summary: "\u54C1\u724C\u63A8\u8350\uFF08--title\uFF09",
+    flags: ["title"],
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/brands/recommend", {
       body: { product_title: args2.title }
     })
@@ -712,18 +889,21 @@ var COMMANDS = [
   {
     name: "warehouses list",
     summary: "\u4ED3\u5E93\u5217\u8868\uFF08\u8DE8\u5883\u8BA4 sub_type CB_*\uFF09",
+    flags: [],
     listKey: "warehouses",
     run: ({ shop }) => proxy("GET", shop, "/logistics/202309/warehouses", {})
   },
   {
     name: "shipping-templates list",
     summary: "\u8FD0\u8D39\u6A21\u677F\u5217\u8868",
+    flags: [],
     listKey: "templates",
     run: ({ shop }) => proxy("GET", shop, "/logistics/202510/seller_templates", {})
   },
   {
     name: "delivery-options",
     summary: "\u4ED3\u5E93\u4EA4\u4ED8\u65B9\u5F0F\uFF08--warehouse\uFF09",
+    flags: ["warehouse"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/logistics/202309/warehouses/${args2.warehouse}/delivery_options`, {
       query: { scope: "PRODUCT" }
     })
@@ -732,6 +912,7 @@ var COMMANDS = [
   {
     name: "products set-price",
     summary: "\u6539 SKU \u552E\u4EF7\uFF08--product --sku --price [--currency MYR]\uFF09\u3002\u5199\u64CD\u4F5C,\u9ED8\u8BA4 dry-run",
+    flags: ["currency", "price", "product", "sku"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u6539\u4EF7",
@@ -745,6 +926,7 @@ var COMMANDS = [
   {
     name: "promotions create-flashsale",
     summary: "\u5EFA\u79D2\u6740\u6D3B\u52A8\uFF08--title --product --sku --price [--limit] [--hours 48]\uFF09\u3002\u4E24\u6B65:\u5EFA\u58F3+\u52A0\u54C1",
+    flags: ["hours", "limit", "per-user", "price", "product", "sku", "start-in-min", "title"],
     write: true,
     preview: ({ args: args2 }) => {
       const { begin, end } = flashWindow(args2);
@@ -769,6 +951,7 @@ var COMMANDS = [
   {
     name: "promotions create-discount",
     summary: "\u5EFA\u5546\u54C1\u6298\u6263\u6D3B\u52A8 FIXED_PRICE\uFF08--title [--product] --price <skuId>:<\u4E00\u53E3\u4EF7>|<productId>/<skuId>:<\u4E00\u53E3\u4EF7>[,...] [--days 180]\uFF09\u3002\u4E24\u6B65:\u5EFA\u58F3+\u52A0\u54C1\uFF0C\u53EF\u591A\u5546\u54C1",
+    flags: ["days", "price", "product", "title"],
     write: true,
     validate: validateCreateDiscount,
     preview: ({ args: args2 }) => {
@@ -835,6 +1018,7 @@ var COMMANDS = [
   {
     name: "promotions deactivate",
     summary: "\u7EC8\u6B62/\u505C\u7528\u4FC3\u9500\u6D3B\u52A8\uFF08--id \u5FC5\u586B\uFF09\u3002\u4E0D\u53EF\u9006",
+    flags: ["id"],
     write: true,
     preview: ({ args: args2 }) => [{ step: "\u7EC8\u6B62\u6D3B\u52A8", method: "POST", path: `/promotion/202309/activities/${args2.id}/deactivate`, body: {} }],
     run: ({ shop, args: args2 }) => proxy("POST", shop, `/promotion/202309/activities/${args2.id}/deactivate`, { body: {} })
@@ -842,6 +1026,7 @@ var COMMANDS = [
   {
     name: "products set-inventory",
     summary: "\u6539 SKU \u5E93\u5B58\uFF08--product --sku --warehouse --quantity\uFF09\u3002\u5199\u64CD\u4F5C,\u9ED8\u8BA4 dry-run",
+    flags: ["product", "quantity", "sku", "warehouse"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u6539\u5E93\u5B58",
@@ -855,6 +1040,7 @@ var COMMANDS = [
   {
     name: "products create",
     summary: "\u5EFA\u54C1\uFF08--body-file [--apply]\uFF09\u3002dry-run \u8DD1 listing_check \u9884\u68C0\uFF1B\u5199\u64CD\u4F5C\u3002\u26A0\uFE0F --apply \u5373\u5EFA\u5B8C\u76F4\u63A5\u4E0A\u67B6\u9001\u5BA1\uFF1B\u7528\u6237\u8981\u5B58\u8349\u7A3F\u5C31\u505C\u624B\u95EE\u7528\u6237\uFF08#1958\uFF09",
+    flags: ["body-file"],
     write: true,
     preview: () => [{ step: "listing_check \u9884\u68C0 \u2192 \u5EFA\u54C1", method: "POST", path: "/product/202309/products/listing_check", body: void 0 }],
     precheck: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/products/listing_check", { body: readBodyFile(args2["body-file"]) }),
@@ -869,6 +1055,7 @@ var COMMANDS = [
   {
     name: "products add-variant",
     summary: "\u7ED9\u5546\u54C1\u52A0\u89C4\u683C SKU\uFF08--product --body-file skus-delta.json [--apply]\uFF09\u3002\u26A0\uFE0F --apply \u5373\u9001\u5BA1\u4E0A\u67B6\uFF1B\u7528\u6237\u8981\u5B58\u8349\u7A3F\u5C31\u505C\u624B\u95EE\u7528\u6237\uFF08#1958\uFF09",
+    flags: ["body-file", "product"],
     write: true,
     preview: () => [{ step: "\u8BFB\u73B0\u6709 skus \u2192 append \u2192 partial_edit\u3002\u26A0\uFE0F \u9ED8\u8BA4 save_mode=LISTING\uFF1A--apply \u5373\u9001\u5BA1\u4E0A\u67B6\uFF08DRAFT \u5546\u54C1\u4F1A\u88AB\u63D0\u4EA4\uFF09\uFF1B\u672C\u547D\u4EE4\u81EA\u6784 body\uFF0Cbody-file \u91CC\u7684 save_mode \u4E0D\u900F\u4F20\u3001\u5199\u4E86\u4E5F\u65E0\u6548\u3002\u82E5\u7528\u6237\u8981\u6C42\u5B58\u8349\u7A3F/\u522B\u63D0\u4EA4 \u2192 \u4E0D\u8981 --apply\uFF0C\u505C\u624B\u95EE\u7528\u6237\uFF08#1958\uFF09", method: "POST", path: "/product/202309/products/{id}/partial_edit" }],
     run: async ({ shop, args: args2 }) => {
@@ -882,6 +1069,7 @@ var COMMANDS = [
   {
     name: "products replace-images",
     summary: "\u6574\u7EC4\u6362\u4E3B\u56FE\uFF08--product --body-file images.json [--apply]\uFF09\u3002\u26A0\uFE0F --apply \u5373\u9001\u5BA1\u4E0A\u67B6\uFF1B\u7528\u6237\u8981\u5B58\u8349\u7A3F\u5C31\u505C\u624B\u95EE\u7528\u6237\uFF08#1958\uFF09",
+    flags: ["body-file", "product"],
     write: true,
     preview: () => [{ step: "main_images \u6574\u7EC4\u66FF\u6362 \u2192 partial_edit\u3002\u26A0\uFE0F \u9ED8\u8BA4 save_mode=LISTING\uFF1A--apply \u5373\u9001\u5BA1\u4E0A\u67B6\uFF08DRAFT \u5546\u54C1\u4F1A\u88AB\u63D0\u4EA4\uFF09\uFF1B\u672C\u547D\u4EE4\u81EA\u6784 body\uFF0Cbody-file \u91CC\u7684 save_mode \u4E0D\u900F\u4F20\u3001\u5199\u4E86\u4E5F\u65E0\u6548\u3002\u82E5\u7528\u6237\u8981\u6C42\u5B58\u8349\u7A3F/\u522B\u63D0\u4EA4 \u2192 \u4E0D\u8981 --apply\uFF0C\u505C\u624B\u95EE\u7528\u6237\uFF08#1958\uFF09", method: "POST", path: "/product/202309/products/{id}/partial_edit" }],
     run: ({ shop, args: args2 }) => proxy("POST", shop, `/product/202309/products/${args2.product}/partial_edit`, { body: { main_images: readBodyFile(args2["body-file"]).main_images } }),
@@ -890,6 +1078,7 @@ var COMMANDS = [
   {
     name: "products partial-edit",
     summary: "\u6539\u5546\u54C1\u5B57\u6BB5\uFF08--product --body-file patch.json [--apply]\uFF09\u3002\u26A0\uFE0F --apply \u5373\u9001\u5BA1\u4E0A\u67B6\uFF1B\u7528\u6237\u8981\u5B58\u8349\u7A3F\u5C31\u505C\u624B\u95EE\u7528\u6237\uFF08#1958\uFF09",
+    flags: ["body-file", "product"],
     write: true,
     preview: ({ args: args2 }) => [{ step: "partial_edit\uFF08\u5D4C\u5957\u5B57\u6BB5\u672A\u5217\u5B50\u9879\u4F1A\u88AB\u6E05\u7A7A\uFF09\u3002\u26A0\uFE0F \u9ED8\u8BA4 save_mode=LISTING\uFF1A--apply \u5373\u9001\u5BA1\u4E0A\u67B6\uFF08DRAFT \u5546\u54C1\u4F1A\u88AB\u63D0\u4EA4\uFF09\u3002\u82E5\u7528\u6237\u8981\u6C42\u5B58\u8349\u7A3F/\u522B\u63D0\u4EA4 \u2192 \u4E0D\u8981 --apply\uFF0C\u505C\u624B\u95EE\u7528\u6237\uFF08#1958\uFF09", method: "POST", path: `/product/202309/products/${args2.product}/partial_edit`, body: readBodyFile(args2["body-file"]) }],
     run: ({ shop, args: args2 }) => proxy("POST", shop, `/product/202309/products/${args2.product}/partial_edit`, { body: readBodyFile(args2["body-file"]) }),
@@ -899,6 +1088,7 @@ var COMMANDS = [
   {
     name: "affiliate creators search",
     summary: "\u8054\u76DF\u5E7F\u573A\u627E\u8FBE\u4EBA\uFF08--keyword\uFF0C--page-size 12|20\uFF0C\u9ED8\u8BA4 12\uFF09",
+    flags: ["keyword", "page-size"],
     listKey: "creators",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202508/marketplace_creators/search", {
       query: { page_size: String(args2["page-size"] ?? 12) },
@@ -908,11 +1098,13 @@ var COMMANDS = [
   {
     name: "affiliate creators perf",
     summary: "\u8FBE\u4EBA\u5E26\u8D27\u8868\u73B0\u8BE6\u60C5\uFF08--creator \u5FC5\u586B\uFF0Ccreator_open_id\uFF09",
+    flags: ["creator"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/affiliate_seller/202508/marketplace_creators/${args2.creator}`, {})
   },
   {
     name: "affiliate target-collab search",
     summary: "\u5B9A\u5411\u9080\u7EA6\u5217\u8868\uFF08--status collaboration_status\uFF0C\u5982 ONGOING/EXPIRING/VALID/CANCELING/COMPLETED\uFF1B--page-size\uFF09",
+    flags: ["page-size", "status"],
     listKey: "target_collaborations",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202508/target_collaborations/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -922,11 +1114,13 @@ var COMMANDS = [
   {
     name: "affiliate target-collab query",
     summary: "\u5B9A\u5411\u9080\u7EA6\u8BE6\u60C5\uFF08--id \u5FC5\u586B\uFF09",
+    flags: ["id"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/affiliate_seller/202508/target_collaborations/${args2.id}`, {})
   },
   {
     name: "affiliate samples search",
     summary: "\u6837\u54C1\u7533\u8BF7\u5217\u8868\uFF08--page-size\uFF09",
+    flags: ["page-size"],
     listKey: "sample_applications",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202508/sample_applications/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -936,6 +1130,7 @@ var COMMANDS = [
   {
     name: "affiliate dm list",
     summary: "\u79C1\u4FE1\u4F1A\u8BDD\u5217\u8868\uFF08--page-size\uFF0C--status conversation_status \u53EF\u9009\uFF09\u3002\u26A0\uFE0F\u7248\u672C\u56FA\u5B9A 202412",
+    flags: ["page-size", "status"],
     listKey: "conversations",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/affiliate_seller/202412/conversations", {
       query: {
@@ -947,11 +1142,13 @@ var COMMANDS = [
   {
     name: "affiliate dm messages",
     summary: "\u4F1A\u8BDD\u6D88\u606F\u8BB0\u5F55\uFF08--conversation \u5FC5\u586B\uFF0Cconversation_id\uFF09",
+    flags: ["conversation"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, `/affiliate_seller/202412/conversation/${args2.conversation}/messages`, {})
   },
   {
     name: "affiliate orders search",
     summary: "\u8054\u76DF\u8BA2\u5355\u5217\u8868\uFF08\u4F63\u91D1\u660E\u7EC6\uFF0C--page-size\uFF09",
+    flags: ["page-size"],
     listKey: "orders",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202410/orders/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -961,6 +1158,7 @@ var COMMANDS = [
   {
     name: "affiliate open-collab products-search",
     summary: "\u516C\u5F00\u5408\u4F5C\u53EF\u8BBE\u4F63\u54C1\u5217\u8868\uFF08--page-size\uFF09",
+    flags: ["page-size"],
     listKey: "products",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202405/open_collaborations/products/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -970,6 +1168,7 @@ var COMMANDS = [
   {
     name: "affiliate open-collab search",
     summary: "\u516C\u5F00\u5408\u4F5C\u751F\u6548\u5217\u8868\uFF08\u542B current_commission\uFF0C--page-size\uFF09",
+    flags: ["page-size"],
     listKey: "open_collaborations",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202412/open_collaborations/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
@@ -979,12 +1178,14 @@ var COMMANDS = [
   {
     name: "affiliate open-collab settings get",
     summary: "\u516C\u5F00\u5408\u4F5C\u5168\u5C40\u8BBE\u7F6E\uFF08\u81EA\u52A8\u65B0\u589E\u54C1\u9ED8\u8BA4\u4F63\u91D1\uFF09",
+    flags: [],
     run: ({ shop }) => proxy("GET", shop, "/affiliate_seller/202409/open_collaboration_settings", {})
   },
   // ===== 联盟写命令（managing-affiliate-program，三道阀：dry-run 预览 → --apply 提交 → 回读） =====
   {
     name: "affiliate target-collab create",
     summary: "\u53D1\u5B9A\u5411\u9080\u7EA6\uFF08--body-file collab.json\uFF0C\u542B creator_user_open_ids[]/products[]/free_sample_rule\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    flags: ["body-file"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u53D1\u5B9A\u5411\u9080\u7EA6",
@@ -1003,6 +1204,7 @@ var COMMANDS = [
   {
     name: "affiliate target-collab update",
     summary: "\u6539\u5B9A\u5411\u9080\u7EA6\uFF08--id --body-file collab.json\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u63D0\u4EA4",
+    flags: ["body-file", "id"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u6539\u5B9A\u5411\u9080\u7EA6",
@@ -1018,6 +1220,7 @@ var COMMANDS = [
   {
     name: "affiliate target-collab remove",
     summary: "\u64A4\u56DE\u5B9A\u5411\u9080\u7EA6\uFF08--id \u5FC5\u586B\uFF0C\u64A4\u56DE\u5B89\u5168\u7F51\uFF09\u3002\u4E0D\u53EF\u9006\uFF0C\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    flags: ["id"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u64A4\u56DE\u5B9A\u5411\u9080\u7EA6",
@@ -1030,6 +1233,7 @@ var COMMANDS = [
   {
     name: "affiliate target-collab link",
     summary: "\u751F\u6210\u5B9A\u5411\u9080\u7EA6\u5206\u4EAB\u94FE\u63A5\uFF08--id \u5FC5\u586B\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    flags: ["id"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u751F\u6210\u9080\u7EA6\u94FE\u63A5",
@@ -1042,6 +1246,7 @@ var COMMANDS = [
   {
     name: "affiliate dm open",
     summary: "\u5F00\u8FBE\u4EBA\u79C1\u4FE1\u4F1A\u8BDD\uFF08--creator \u5FC5\u586B\uFF0Ccreator_open_id\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    flags: ["creator"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u5F00\u79C1\u4FE1\u4F1A\u8BDD",
@@ -1056,6 +1261,7 @@ var COMMANDS = [
   {
     name: "affiliate dm send",
     summary: "\u7ED9\u8FBE\u4EBA\u53D1\u79C1\u4FE1\uFF08--conversation --content [--msg-type TEXT]\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    flags: ["content", "conversation", "msg-type"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u53D1\u79C1\u4FE1",
@@ -1070,6 +1276,7 @@ var COMMANDS = [
   {
     name: "affiliate samples review",
     summary: "\u5BA1\u6279\u6837\u54C1\u7533\u8BF7\uFF08--id application_id --result review_result [--reject-reason]\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    flags: ["id", "reject-reason", "result"],
     listKey: "sample_applications",
     write: true,
     preview: ({ args: args2 }) => [{
@@ -1090,6 +1297,7 @@ var COMMANDS = [
   {
     name: "affiliate open-collab set-commission",
     summary: "\u6309\u54C1\u8BBE\u516C\u5F00\u5408\u4F5C\u4F63\u91D1\u7387\uFF08--product product_id --rate\uFF0C\u5355\u4F4D=\u767E\u5206\u6BD4\xD7100\uFF0C\u5982 1350=13.5%\uFF0C\u8303\u56F4 800-8000\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u5B58",
+    flags: ["product", "rate"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u8BBE\u6309\u54C1\u516C\u5F00\u5408\u4F5C\u4F63\u91D1",
@@ -1108,6 +1316,7 @@ var COMMANDS = [
   {
     name: "affiliate open-collab remove",
     summary: "\u79FB\u9664\u54C1\u7684\u516C\u5F00\u5408\u4F5C\uFF08--product product_id\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    flags: ["product"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u79FB\u9664\u516C\u5F00\u5408\u4F5C",
@@ -1120,6 +1329,7 @@ var COMMANDS = [
   {
     name: "affiliate open-collab settings edit",
     summary: "\u6539\u516C\u5F00\u5408\u4F5C\u5168\u5C40\u9ED8\u8BA4\uFF08\u81EA\u52A8\u65B0\u589E\u54C1\u4F63\u91D1\uFF0C--rate --enable true|false\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u5B58",
+    flags: ["enable", "rate"],
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u6539\u5168\u5C40\u9ED8\u8BA4",
@@ -1136,6 +1346,7 @@ var COMMANDS = [
   {
     name: "apps add",
     summary: "\u767B\u8BB0\u4E00\u4E2A TikTok App\uFF08--service-id --app-key --app-secret --type --label\uFF0C[--markets a,b] [--redirect] [--owner-entity] [--default]\uFF09",
+    flags: ["app-key", "app-secret", "default", "label", "markets", "owner-entity", "redirect", "service-id", "type"],
     run: ({ args: args2 }) => adminApps("POST", {
       body: {
         serviceId: args2["service-id"],
@@ -1153,6 +1364,7 @@ var COMMANDS = [
   {
     name: "apps set-shop",
     summary: "\u9884\u7F6E shop\u2192app \u6620\u5C04\uFF08--shop shopId --app serviceId [--note]\uFF09\u2014\u2014auth link \u65F6\u6309\u5E97\u89E3\u6790\u7528\u54EA\u4E2A app",
+    flags: ["app", "note"],
     run: ({ args: args2 }) => {
       if (!args2.shop || !args2.app) return Promise.resolve({ ok: false, error: { code: "VALIDATION", message: "--shop \u548C --app\uFF08serviceId\uFF09\u5FC5\u586B", retryable: false } });
       return setShopApp(args2.shop, args2.app, args2.note);
@@ -1161,16 +1373,19 @@ var COMMANDS = [
   {
     name: "apps list",
     summary: "\u5217\u51FA\u5DF2\u767B\u8BB0\u7684 TikTok App\uFF08admin\uFF0C\u542B appKey/status\uFF09",
+    flags: [],
     run: () => adminApps("GET")
   },
   {
     name: "apps available",
     summary: "\u5217\u51FA\u53EF\u9009 App\uFF08\u7528\u6237\u9274\u6743\uFF0C\u4EC5 active\uFF0C\u65E0 secret\uFF09\u2014\u2014\u9009 serviceId \u4F20\u7ED9 auth link --app",
+    flags: [],
     run: () => availableApps()
   },
   {
     name: "apps disable",
     summary: "\u505C\u7528\u4E00\u4E2A TikTok App\uFF08--id\uFF09",
+    flags: ["id"],
     run: ({ args: args2 }) => adminApps("PATCH", { id: args2.id, body: { status: "disabled" } })
   },
   // ── auth link：skill 只传 --shop，backend 按 shop 解析用哪个 app（custom 映射→默认 public）。
@@ -1178,6 +1393,7 @@ var COMMANDS = [
   {
     name: "auth link",
     summary: "\u751F\u6210\u5E97\u94FA\u7ED1\u5B9A\u6388\u6743\u94FE\u63A5\uFF08--shop shopId\uFF0Cbackend \u6309\u5E97\u5B9A app\uFF1B--app serviceId \u53EF\u9009\u8986\u76D6\uFF09",
+    flags: ["app"],
     run: async ({ args: args2 }) => {
       if (!args2.shop && !args2.app) {
         return { ok: false, error: { code: "VALIDATION", message: "--shop\uFF08shopId\uFF09\u5FC5\u586B\uFF08\u6216 --app \u8986\u76D6\uFF09", retryable: false } };
@@ -1331,7 +1547,10 @@ function validateCreateDiscount(ctx2) {
     if (k === "sku") {
       return { ok: false, message: "\u672C\u547D\u4EE4\u6CA1\u6709 --sku\uFF1AskuId \u5199\u5728 --price \u91CC\uFF0C\u5982 --price 173707:29.90\uFF08\u6CA1\u4F20 --product \u65F6\u6BCF\u9879\u90FD\u8981\u5E26 productId\uFF0C\u5982 --price 1737048/173707:29.90\uFF09" };
     }
-    return { ok: false, message: `\u4E0D\u652F\u6301\u7684\u53C2\u6570 --${k}\uFF1B\u672C\u547D\u4EE4\u53EA\u8BA4 ${DISCOUNT_FLAGS.map((f) => "--" + f).join(" ")}` };
+    const own = DISCOUNT_FLAGS.filter((f) => !GLOBAL_FLAGS.includes(f));
+    const hint = suggestFlag(k, own, args2[k], Date.now(), "promotions create-discount");
+    const tip = !hint ? "" : hint.startsWith("--") ? `\uFF08\u4F60\u662F\u60F3\u7528 ${hint} \u5417\uFF1F\uFF09` : `\uFF08${hint}\uFF09`;
+    return { ok: false, message: `\u4E0D\u652F\u6301\u7684\u53C2\u6570 --${k}${tip}\uFF1B\u672C\u547D\u4EE4\u53EA\u8BA4 ${DISCOUNT_FLAGS.map((f) => "--" + f).join(" ")}` };
   }
   if (rest && rest.length > 0) {
     return { ok: false, message: `\u591A\u4F59\u7684\u4F4D\u7F6E\u53C2\u6570\u300C${rest.join(" ")}\u300D\u2014\u2014\u6BCF\u4E2A\u53C2\u6570\u53EA\u80FD\u5E26\u4E00\u4E2A\u503C\u3002\u591A\u4E2A SKU \u8981\u7528\u9017\u53F7\u8FDE\u6210\u4E00\u4E2A --price\uFF0C\u5982 --price A:12,B:15\uFF08\u4E0D\u80FD\u7528\u7A7A\u683C\u5206\u9694\uFF09\uFF1B\u82E5\u662F\u6807\u9898\u7B49\u503C\u91CC\u542B\u7A7A\u683C\uFF0C\u7ED9\u6574\u4E2A\u503C\u52A0\u5F15\u53F7\uFF0C\u5982 --title "Momo Sale"` };
@@ -1490,6 +1709,8 @@ async function dupSelfCheck(shop, title, submitted) {
 
 // src/index.ts
 var NO_SHOP_COMMANDS = /* @__PURE__ */ new Set(["auth link", "apps add", "apps list", "apps disable", "apps available", "apps set-shop"]);
+var SHOP_OPTIONAL_BUT_READ = /* @__PURE__ */ new Set(["auth link", "apps set-shop"]);
+var mentionsShop = (name) => !NO_SHOP_COMMANDS.has(name) || SHOP_OPTIONAL_BUT_READ.has(name);
 function parseFlags(tokens) {
   const args2 = {};
   const positional2 = [];
@@ -1512,7 +1733,7 @@ function parseFlags(tokens) {
   }
   return { args: args2, positional: positional2 };
 }
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["apply", "default", "unprocessed", "enable", "force-status"]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["apply", "default", "unprocessed", "enable", "force-status", "force-version"]);
 var FLAG_TRUE = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
 var FLAG_FALSE = /* @__PURE__ */ new Set(["false", "0", "no", "off", ""]);
 function normalizeBooleanFlags(args2) {
@@ -1547,6 +1768,7 @@ function usage() {
   for (const c of COMMANDS) lines.push(`  ${c.name.padEnd(22)} ${c.summary}`);
   lines.push(`  ${"shops".padEnd(22)} \u67E5\u5F53\u524D\u767B\u5F55\u7528\u6237\u5DF2\u6388\u6743\u5E97\u94FA`);
   lines.push(`  ${"images upload".padEnd(22)} \u4E0A\u4F20\u672C\u5730\u56FE\u7247\uFF08--file --use-case [--out]\uFF09`);
+  lines.push("", "\u6BCF\u6761\u547D\u4EE4\u53EA\u8BA4\u5B83\u81EA\u5DF1\u7684\u53C2\u6570\uFF08`tiktok <\u547D\u4EE4> --help` \u770B\uFF09\uFF0C\u4E0D\u8BA4\u7684\u4F1A\u5F53\u573A\u62A5 VALIDATION \u2014\u2014 \u4E0D\u4F1A\u518D\u88AB\u9759\u9ED8\u4E22\u6389\u3002");
   lines.push("", "\u901A\u7528\uFF1A--shop \u5FC5\u586B\uFF08\u9664 shops / auth link / apps add|list|disable\uFF09\uFF1B\u9ED8\u8BA4 JSON \u8F93\u51FA\uFF1BTIKTOK_BACKEND_URL \u663E\u5F0F\u6307\u5B9A backend\uFF08\u672A\u8BBE\u5219\u6309 OPTIMA_ENV \u6620\u5C04 cn-stage/cn-prod\uFF0C\u5426\u5219 localhost\uFF09\u3002");
   process.stderr.write(lines.join("\n") + "\n");
 }
@@ -1556,11 +1778,40 @@ if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
   process.exit(argv.length === 0 ? 1 : 0);
 }
 var { args, positional } = parseFlags(argv);
+var wantsHelp = argv.includes("--help") || argv.includes("-h") || "help" in args;
+function rejectUnknownFlags(cmdName, allowed, rest, noShop = false) {
+  const v = checkFlags(cmdName, args, allowed, rest, Date.now(), noShop);
+  if (!v) return;
+  out({
+    ok: false,
+    error: {
+      code: "VALIDATION",
+      message: v.message,
+      retryable: false,
+      unknown_flags: v.unknown_flags,
+      extra_positional: v.extra_positional,
+      allowed_flags: v.allowed_flags
+    }
+  });
+  process.exit(1);
+}
+var IMAGES_UPLOAD = { name: "images upload", summary: "\u4E0A\u4F20\u672C\u5730\u56FE\u7247\uFF08--file <\u8DEF\u5F84> [--use-case MAIN_IMAGE] [--out <\u8FFD\u52A0\u5199\u5165\u7684 jsonl>]\uFF09", flags: ["file", "use-case", "out"] };
+var SHOPS = { name: "shops", summary: "\u67E5\u5F53\u524D\u767B\u5F55\u7528\u6237\u5DF2\u6388\u6743\u5E97\u94FA\uFF08\u4E0D\u9700\u8981 --shop\uFF09", flags: [], noShop: true };
 if (positional[0] === "shops") {
+  if (wantsHelp) {
+    process.stderr.write(commandUsage(SHOPS));
+    process.exit(0);
+  }
+  rejectUnknownFlags(SHOPS.name, SHOPS.flags, positional.slice(1), true);
   out(await listShops());
   process.exit(0);
 }
 if (positional[0] === "images" && positional[1] === "upload") {
+  if (wantsHelp) {
+    process.stderr.write(commandUsage(IMAGES_UPLOAD));
+    process.exit(0);
+  }
+  rejectUnknownFlags(IMAGES_UPLOAD.name, IMAGES_UPLOAD.flags, positional.slice(2));
   if (!args.file) {
     out({ ok: false, error: { code: "VALIDATION", message: "\u7F3A\u5C11 --file", retryable: false } });
     process.exit(1);
@@ -1577,14 +1828,12 @@ if (positional[0] === "images" && positional[1] === "upload") {
   out(r);
   process.exit(0);
 }
-var wantsHelp = argv.includes("--help") || argv.includes("-h");
 var match = findCommand(positional);
 if (wantsHelp) {
-  if (match) process.stderr.write(commandUsage(match.cmd));
+  if (match) process.stderr.write(commandUsage({ ...match.cmd, noShop: !mentionsShop(match.cmd.name) }));
   else usage();
   process.exit(0);
 }
-normalizeBooleanFlags(args);
 if (!match) {
   out({ ok: false, error: { code: "VALIDATION", message: `\u672A\u77E5\u547D\u4EE4: ${positional.join(" ")}`, retryable: false } });
   usage();
@@ -1596,6 +1845,8 @@ if (verdict && !verdict.ok) {
   out({ ok: false, error: { code: "VALIDATION", message: verdict.message, retryable: false } });
   process.exit(1);
 }
+rejectUnknownFlags(match.cmd.name, match.cmd.flags, match.rest, !mentionsShop(match.cmd.name));
+normalizeBooleanFlags(args);
 if (!args.shop && !NO_SHOP_COMMANDS.has(match.cmd.name)) {
   out({ ok: false, error: { code: "VALIDATION", message: "\u7F3A\u5C11 --shop\uFF08\u591A\u5E97\u663E\u5F0F\u8DEF\u7531\uFF09", retryable: false } });
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/tiktok-cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "TikTok Shop CLI for Optima agents — 经 tiktok-backend 操作店铺",
   "type": "module",
   "bin": {