@optima-chat/tiktok-cli 0.12.0 → 0.14.0

package/README.md

@@ -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";
@@ -33,7 +130,7 @@ function authHeaders() {
   return {};
 }
 function classify(status, body, shop) {
-  const meta = { shop, tiktok_request_id: body?.request_id };
+  const meta = { shop, tiktok_request_id: body?.request_id, http_status: status };
   if (status === 0 || body?.code === 0) {
     return { ok: true, data: body.data, meta };
   }
@@ -209,9 +306,14 @@ 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);
@@ -222,6 +324,7 @@ 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 +346,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 +363,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 +373,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 +394,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 +403,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 +417,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 +427,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 +453,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 +471,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 +484,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 +502,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 +520,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 +539,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 +552,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 +565,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),
@@ -453,6 +577,7 @@ var COMMANDS = [
   {
     name: "analytics products",
     summary: "\u5546\u54C1\u7EF4\u5EA6\u7ECF\u8425\u6570\u636E\uFF08\u6309 GMV \u964D\u5E8F\uFF09",
+    flags: ["from", "page-size", "to"],
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop_products/performance", {
       query: {
         start_date_ge: args2.from ?? daysAgo(30),
@@ -466,6 +591,7 @@ var COMMANDS = [
   {
     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 +606,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 +618,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 +629,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 +641,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 +656,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 +668,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 +683,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 +695,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 +707,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 +723,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 +738,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 +770,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 +784,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 +815,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 +824,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 +832,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 +840,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 +853,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 +861,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 +884,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 +898,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);
@@ -766,9 +920,77 @@ var COMMANDS = [
     },
     readback: ({ shop, args: args2 }) => proxy("POST", shop, "/promotion/202309/activities/search", { body: { status: "NOT_START", page_size: 20 } })
   },
+  {
+    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 }) => {
+      const { begin, end } = discountWindow(args2);
+      return [
+        { step: "1/2 \u5EFA\u6D3B\u52A8\u58F3", method: "POST", path: "/promotion/202309/activities", body: discountActivityBody(args2, begin, end) },
+        { step: "2/2 \u52A0\u5546\u54C1+\u4E00\u53E3\u4EF7", method: "PUT", path: "/promotion/202309/activities/{activity_id}/products", body: discountProductsBody(args2), human: discountHuman(args2) }
+      ];
+    },
+    run: async ({ shop, args: args2 }) => {
+      const { begin, end } = discountWindow(args2);
+      const submitted = submittedSkus(args2);
+      const created = await proxy("POST", shop, "/promotion/202309/activities", { body: discountActivityBody(args2, begin, end) });
+      if (!created.ok) {
+        const err = created.error;
+        switch (createFailureVerdict(created)) {
+          case "maybe_landed":
+            return { ...created, error: { ...err, message: `${err.message} ${DISCOUNT_TEXT.maybeLanded}` } };
+          case "dup":
+            return { ...created, error: { ...err, message: `${err.message} ${await dupSelfCheck(shop, args2.title, submitted)}` } };
+          case "rejected":
+            return created;
+        }
+      }
+      const activityId = created.data?.activity_id;
+      if (!activityId) {
+        return {
+          ok: false,
+          error: { code: "TIKTOK_ERROR", message: DISCOUNT_TEXT.noCreateId(args2.title), retryable: false },
+          meta: created.meta
+        };
+      }
+      const withProducts = await proxy("PUT", shop, `/promotion/202309/activities/${activityId}/products`, {
+        body: { ...discountProductsBody(args2), activity_id: activityId }
+        // F5：body 里要重复传
+      });
+      const rb = await proxy("GET", shop, `/promotion/202309/activities/${activityId}`, {});
+      const readback = rb.ok ? rb.data : { error: rb.error };
+      if (!withProducts.ok) {
+        const { retry_after_s: _dropped, ...err } = withProducts.error;
+        let note;
+        const c = rb.ok ? compareReadback(submitted, rb.data) : null;
+        if (!c) note = DISCOUNT_TEXT.addFailReadbackFailed(shop, activityId);
+        else {
+          if (c.missing.length === 0 && c.mismatched.length === 0) note = DISCOUNT_TEXT.addFailAllAttached(submitted.length, activityId);
+          else if (c.missing.length === submitted.length && c.productCount === 0) note = DISCOUNT_TEXT.addFailNoneAttached(shop, activityId);
+          else note = DISCOUNT_TEXT.addFailPartial(problemsText(c), shop, activityId);
+        }
+        return { ok: false, error: { ...err, retryable: false }, data: { activity_id: activityId, readback, note }, meta: withProducts.meta };
+      }
+      const ours = [];
+      const diff = rb.ok ? compareReadback(submitted, rb.data) : null;
+      if (!diff) ours.push(DISCOUNT_TEXT.readbackFailed(activityId));
+      else {
+        const problems = problemsText(diff);
+        if (problems) ours.push(DISCOUNT_TEXT.readbackDiffers(activityId, problems));
+      }
+      const putData = withProducts.data ?? {};
+      const data = { ...putData, activity_id: activityId, readback };
+      if (ours.length > 0) data.warnings = mergeWarnings(putData.warnings, ours);
+      return { ok: true, data, meta: withProducts.meta };
+    }
+  },
   {
     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: {} })
@@ -776,6 +998,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",
@@ -789,6 +1012,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"]) }),
@@ -803,6 +1027,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 }) => {
@@ -816,6 +1041,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 } }),
@@ -824,6 +1050,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"]) }),
@@ -833,6 +1060,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) },
@@ -842,11 +1070,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) },
@@ -856,11 +1086,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) },
@@ -870,6 +1102,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: {
@@ -881,11 +1114,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) },
@@ -895,6 +1130,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) },
@@ -904,6 +1140,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) },
@@ -913,12 +1150,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",
@@ -937,6 +1176,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",
@@ -952,6 +1192,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",
@@ -964,6 +1205,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",
@@ -976,6 +1218,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",
@@ -990,6 +1233,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",
@@ -1004,6 +1248,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 }) => [{
@@ -1024,6 +1269,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",
@@ -1042,6 +1288,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",
@@ -1054,6 +1301,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",
@@ -1070,6 +1318,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"],
@@ -1087,6 +1336,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);
@@ -1095,16 +1345,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）。
@@ -1112,6 +1365,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 } };
@@ -1181,9 +1435,254 @@ function findCommand(tokens) {
   }
   return null;
 }
+var DISCOUNT_FLAGS = ["shop", "apply", "actor", "title", "product", "price", "days"];
+var PRICE_ITEM = /^(?:([^:,\s/]+)\/)?([^:,\s/]+):(0|[1-9]\d*)(?:\.(\d{1,2}))?$/;
+function parsePriceItems(raw, defaultProduct) {
+  const items = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const part of raw.split(",")) {
+    const m = PRICE_ITEM.exec(part);
+    if (!m) {
+      return { ok: false, message: `--price \u6BCF\u4E00\u9879\u5FC5\u987B\u662F <skuId>:<\u4E00\u53E3\u4EF7> \u6216 <productId>/<skuId>:<\u4E00\u53E3\u4EF7>\uFF08\u5341\u8FDB\u5236\u6570\u5B57\uFF0C\u6700\u591A\u4E24\u4F4D\u5C0F\u6570\u3001\u4E0D\u8981\u524D\u5BFC\u96F6\uFF0C\u5982 25.42\uFF09\uFF0C\u591A\u9879\u7528\u9017\u53F7\u8FDE\u63A5\u3001\u5404\u9879\u4E4B\u95F4\u4E0D\u8981\u6709\u7A7A\u683C\uFF0C\u5982 --price 173707:29.90,173708:32.00\uFF1B\u6536\u5230\u300C${part}\u300D` };
+    }
+    const [, explicitPid, sid, intPart, frac] = m;
+    if (explicitPid && defaultProduct && explicitPid !== defaultProduct) {
+      return { ok: false, message: `--price \u7684\u300C${part}\u300D\u6307\u5B9A\u4E86\u5546\u54C1 ${explicitPid}\uFF0C\u4E0E --product ${defaultProduct} \u4E0D\u4E00\u81F4\uFF1B\u591A\u5546\u54C1\u8BF7\u628A --product \u53BB\u6389\u3001\u6BCF\u9879\u90FD\u5199\u6210 <productId>/<skuId>:<\u4EF7>` };
+    }
+    const pid = explicitPid ?? defaultProduct;
+    if (!pid) {
+      return { ok: false, message: `--price \u7684\u300C${part}\u300D\u6CA1\u5E26 productId\uFF0C\u800C\u4F60\u4E5F\u6CA1\u4F20 --product\uFF1B\u8981\u4E48\u52A0 --product\uFF0C\u8981\u4E48\u5199\u6210 <productId>/<skuId>:<\u4EF7>` };
+    }
+    const amount = frac === void 0 ? intPart : `${intPart}.${frac}`;
+    if (!(Number(amount) > 0)) return { ok: false, message: `--price \u7684\u4E00\u53E3\u4EF7\u5FC5\u987B\u5927\u4E8E 0\uFF1B\u6536\u5230\u300C${part}\u300D` };
+    if (seen.has(sid)) return { ok: false, message: `--price \u91CC\u540C\u4E00\u4E2A skuId \u91CD\u590D\u51FA\u73B0\uFF1A${sid}` };
+    seen.add(sid);
+    items.push({ pid, sid, amount });
+  }
+  return { ok: true, items };
+}
+function discountWindow(args2) {
+  const now = Math.floor(Date.now() / 1e3);
+  const begin = now + 900;
+  const end = begin + Number(args2.days ?? 180) * 86400;
+  return { begin, end };
+}
+function discountActivityBody(args2, begin, end) {
+  return {
+    title: args2.title,
+    activity_type: "FIXED_PRICE",
+    product_level: "VARIATION",
+    begin_time: begin,
+    end_time: end
+  };
+}
+function discountProductsBody(args2) {
+  const parsed = parsePriceItems(args2.price ?? "", args2.product);
+  const items = parsed.ok ? parsed.items : [];
+  const order = [];
+  const byPid = /* @__PURE__ */ new Map();
+  for (const it of items) {
+    if (!byPid.has(it.pid)) {
+      byPid.set(it.pid, []);
+      order.push(it.pid);
+    }
+    byPid.get(it.pid).push({ sid: it.sid, amount: it.amount });
+  }
+  return {
+    products: order.map((pid) => ({
+      id: pid,
+      quantity_limit: -1,
+      quantity_per_user: -1,
+      skus: byPid.get(pid).map((it) => ({
+        id: it.sid,
+        activity_price_amount: it.amount,
+        // 🔴 写侧裸串；读回叫 activity_price.amount（F4）
+        quantity_limit: -1,
+        quantity_per_user: -1
+      }))
+    }))
+  };
+}
+function discountHuman(args2) {
+  const parsed = parsePriceItems(args2.price ?? "", args2.product);
+  const days = Number(args2.days ?? 180);
+  const list = parsed.ok ? parsed.items.map((it) => `\u5546\u54C1 ${it.pid} \u7684 SKU ${it.sid} \u552E\u4EF7\u5B9A\u4E3A ${it.amount}`).join("\uFF1B") : "\uFF08--price \u89E3\u6790\u5931\u8D25\uFF09";
+  return `${list}\u3002\u539F\u4EF7\u5C06\u663E\u793A\u4E3A\u5212\u7EBF\u4EF7\u3002\u6D3B\u52A8\u5171 ${days} \u5929\uFF0C\u4ECE 15 \u5206\u949F\u540E\u5F00\u59CB \u2014\u2014 \u521A\u5EFA\u5B8C\u53BB\u5546\u54C1\u9875\u770B\u4EF7\u683C\u6CA1\u53D8\u662F\u6B63\u5E38\u7684\uFF0C\u90A3\u65F6\u6D3B\u52A8\u8FD8\u662F NOT_START\u3002`;
+}
+function validateCreateDiscount(ctx2) {
+  const { args: args2, rest } = ctx2;
+  for (const k of Object.keys(args2)) {
+    if (DISCOUNT_FLAGS.includes(k)) continue;
+    if (k === "percent") {
+      return { ok: false, message: "\u672C\u7248\u4E0D\u652F\u6301\u767E\u5206\u6BD4\u6298\u6263\uFF08--percent\uFF09\u3002\u8BF7\u5148\u7528 tiktok products get --shop <id> --product <pid> \u53D6 SKU \u6302\u724C\u4EF7\uFF0C\u81EA\u884C\u6298\u7B97\uFF08\u4FDD\u7559\u4E24\u4F4D\u5C0F\u6570\uFF09\u540E\u8D70 --price <skuId>:<\u6298\u540E\u4EF7>" };
+    }
+    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" };
+    }
+    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"` };
+  }
+  for (const k of ["title", "price"]) {
+    const v = args2[k];
+    if (!v || v === "true" || !v.trim()) {
+      return { ok: false, message: `--${k} \u5FC5\u586B\uFF0C\u4E14\u5FC5\u987B\u5E26\u503C\uFF08\u53EA\u5199 --${k} \u4E0D\u7ED9\u503C\u4F1A\u88AB\u89E3\u6790\u6210\u5B57\u7B26\u4E32 "true"\uFF0C\u5199\u6210 --${k}= \u5219\u662F\u7A7A\u503C\uFF0C\u4E24\u79CD\u90FD\u4E0D\u7B97\uFF09` };
+    }
+  }
+  if (args2.title !== args2.title.trim()) {
+    return { ok: false, message: `--title \u9996\u5C3E\u4E0D\u80FD\u6709\u7A7A\u767D\uFF08\u6536\u5230\u300C${args2.title}\u300D\uFF09\uFF1A\u649E\u91CD\u540D\u65F6 CLI \u6309\u6807\u9898\u4E25\u683C\u76F8\u7B49\u67E5\u540C\u540D\u6D3B\u52A8\uFF0C\u5E73\u53F0\u82E5\u53BB\u6389\u9996\u5C3E\u7A7A\u767D\u5C31\u4F1A\u5BF9\u4E0D\u4E0A\u3002\u8BF7\u53BB\u6389\u9996\u5C3E\u7A7A\u767D\u540E\u91CD\u8DD1` };
+  }
+  if ("product" in args2 && (!args2.product || args2.product === "true")) {
+    return { ok: false, message: `--product \u5FC5\u586B\uFF0C\u4E14\u5FC5\u987B\u5E26\u503C\uFF08\u53EA\u5199 --product \u4E0D\u7ED9\u503C\u4F1A\u88AB\u89E3\u6790\u6210\u5B57\u7B26\u4E32 "true"\uFF0C\u5199\u6210 --product= \u5219\u662F\u7A7A\u503C\uFF0C\u4E24\u79CD\u90FD\u4E0D\u7B97\uFF09` };
+  }
+  if (args2.product?.includes(",")) {
+    return { ok: false, message: "--product \u53EA\u6536\u4E00\u4E2A\u5546\u54C1 id\uFF1B\u591A\u5546\u54C1\u8BF7\u5728 --price \u91CC\u5199 <productId>/<skuId>:<\u4EF7>" };
+  }
+  const parsed = parsePriceItems(args2.price, args2.product);
+  if (!parsed.ok) return parsed;
+  if ("days" in args2) {
+    const raw = args2.days;
+    const n = Number(raw);
+    if (!/^\d+$/.test(raw) || !(n >= 1 && n <= 180)) {
+      return { ok: false, message: `--days \u5FC5\u987B\u662F 1\u2013180 \u7684\u6574\u6570\uFF08\u6536\u5230\u300C${raw}\u300D\uFF09` };
+    }
+  }
+  return { ok: true };
+}
+var deactivateCmd = (shop, id) => `\`tiktok promotions deactivate --shop ${shop} --id ${id} --apply\``;
+var DISCOUNT_TEXT = {
+  // ⑤ 建壳可能已落。标题 = 幂等键：原标题重跑，最坏撞一次重名，不会多出一条活动。
+  maybeLanded: "\u26A0\uFE0F \u5EFA\u58F3\u8BF7\u6C42\u53EF\u80FD\u5DF2\u7ECF\u843D\u5230\u5E73\u53F0\u2014\u2014\u522B\u6362\u6807\u9898\uFF0C\u76F4\u63A5\u7528\u539F\u6807\u9898\u91CD\u8DD1\u539F\u547D\u4EE4\uFF1A\u6CA1\u843D\u5C31\u4F1A\u6B63\u5E38\u5EFA\u6210\uFF1B\u82E5\u5DF2\u843D\uFF0C\u91CD\u8DD1\u4F1A\u649E\u91CD\u540D\uFF0C\u90A3\u6761\u63D0\u793A\u4F1A\u544A\u8BC9\u4F60\u4E0B\u4E00\u6B65\u3002",
+  // ⑥
+  noCreateId: (title) => `\u5EFA\u58F3\u8FD4\u56DE\u6210\u529F\u4F46\u6CA1\u62FF\u5230 activity_id \u2014\u2014 \u26A0\uFE0F \u5E73\u53F0\u4E0A\u5F88\u53EF\u80FD\u5DF2\u7ECF\u6709\u8FD9\u6761\u58F3\u4E86\uFF08\u6807\u9898\u300C${title}\u300D\uFF09\u3002\u522B\u6362\u6807\u9898\uFF0C\u76F4\u63A5\u7528\u539F\u6807\u9898\u91CD\u8DD1\u539F\u547D\u4EE4\uFF1A\u91CD\u8DD1\u4F1A\u649E\u91CD\u540D\uFF0C\u90A3\u6761\u63D0\u793A\u4F1A\u544A\u8BC9\u4F60\u4E0B\u4E00\u6B65\u3002`,
+  // ⑦ 撞重名后自查的六种结论（前面由调用方拼上平台原文 + 一个半角空格）
+  dupSame: (title, aid, status) => `\u26A0\uFE0F \u540C\u540D\u6D3B\u52A8\u300C${title}\u300D\u5DF2\u5B58\u5728\uFF08\u6D3B\u52A8 ${aid}\uFF0C${status}\uFF09\uFF0C\u6302\u7684\u5546\u54C1\u4E0E\u672C\u6B21\u63D0\u4EA4\u5B8C\u5168\u4E00\u81F4\u2014\u2014\u8FD9\u5C31\u662F\u4F60\u8981\u7684\u6D3B\u52A8\uFF0C\u5DF2\u7ECF\u5EFA\u597D\u4E86\uFF1A\u522B\u91CD\u5EFA\u3002`,
+  dupEmpty: (title, aid, status, shop) => `\u26A0\uFE0F \u540C\u540D\u6D3B\u52A8\u300C${title}\u300D\u5DF2\u5B58\u5728\uFF08\u6D3B\u52A8 ${aid}\uFF0C${status}\uFF09\uFF0C\u4F46\u5B83\u662F\u4E00\u6761\u7A7A\u58F3\uFF08\u6CA1\u6709\u4EFB\u4F55\u5546\u54C1\uFF09\u2014\u2014\u5148\u6E05\u7406\uFF1A${deactivateCmd(shop, aid)}\uFF0C\u518D\u7528\u539F\u6807\u9898\u91CD\u8DD1\u539F\u547D\u4EE4\uFF1B\u91CD\u8DD1\u82E5\u53C8\u649E\u91CD\u540D\uFF0C\u6362\u4E2A\u6807\u9898\u3002`,
+  dupOwner: (title, aid, status, problems) => `\u26A0\uFE0F \u540C\u540D\u6D3B\u52A8\u300C${title}\u300D\u5DF2\u5B58\u5728\uFF08\u6D3B\u52A8 ${aid}\uFF0C${status}\uFF09\uFF0C\u6302\u7684\u5546\u54C1\u4E0E\u672C\u6B21\u63D0\u4EA4\u4E0D\u4E00\u81F4\uFF1A${problems}\u2014\u2014\u522B\u52A8\u5B83\uFF0C\u4E5F\u5148\u522B\u91CD\u5EFA\uFF1A\u628A\u5B83\u544A\u8BC9\u5E97\u4E3B\uFF0C\u95EE\u662F\u5C31\u7528\u8FD9\u6761\uFF0C\u8FD8\u662F\u6362\u4E2A\u6807\u9898\u53E6\u5EFA\u3002`,
+  dupRetitle: (title) => `\u26A0\uFE0F \u672A\u5F00\u59CB / \u8FDB\u884C\u4E2D\u7684\u6D3B\u52A8\u91CC\u6CA1\u6709\u300C${title}\u300D\u2014\u2014\u8FD9\u4E2A\u6807\u9898\u88AB\u4E00\u6761\u5DF2\u7EC8\u6B62\u6216\u5DF2\u8FC7\u671F\u7684\u6D3B\u52A8\u5360\u7740\uFF0C\u6362\u4E2A\u6807\u9898\u91CD\u8DD1\u539F\u547D\u4EE4\u3002`,
+  dupUnclear: (title, queryError) => `\u26A0\uFE0F \u540C\u540D\u6D3B\u52A8\u300C${title}\u300D\u5DF2\u5B58\u5728\uFF0C\u4F46\u6CA1\u80FD\u67E5\u6E05\u5B83\u7684\u72B6\u6001\uFF08${queryError}\uFF09\u2014\u2014\u522B\u6362\u6807\u9898\u3001\u522B\u91CD\u5EFA\uFF0C\u7A0D\u540E\u7528\u539F\u6807\u9898\u91CD\u8DD1\u539F\u547D\u4EE4\u518D\u770B\uFF1B\u8FDE\u7EED\u4E24\u6B21\u90FD\u662F\u8FD9\u53E5\uFF0C\u5C31\u5982\u5B9E\u544A\u8BC9\u5E97\u4E3B\u300C\u6D3B\u52A8\u53EF\u80FD\u5DF2\u5EFA\uFF0C\u4F46\u67E5\u4E0D\u6E05\u300D\u3002`,
+  dupMulti: (title, found) => `\u26A0\uFE0F \u672A\u5F00\u59CB / \u8FDB\u884C\u4E2D\u7684\u6D3B\u52A8\u91CC\u6709 ${found.length} \u6761\u53EB\u300C${title}\u300D\uFF08${found.map((a) => `${a.id}\uFF1A${a.status}`).join("\uFF1B")}\uFF09\u2014\u2014\u522B\u52A8\u5B83\u4EEC\uFF0C\u4E5F\u5148\u522B\u91CD\u5EFA\uFF1A\u628A\u5B83\u4EEC\u544A\u8BC9\u5E97\u4E3B\uFF0C\u95EE\u600E\u4E48\u5904\u7406\u3002`,
+  // ⑧ 加品失败后按回读下结论
+  addFailAllAttached: (n, id) => `\u52A0\u5546\u54C1\u62A5\u4E86\u9519\uFF0C\u4F46\u56DE\u8BFB\u663E\u793A\u63D0\u4EA4\u7684 ${n} \u4E2A SKU \u90FD\u5DF2\u6309\u4EF7\u6302\u4E0A\uFF08\u6D3B\u52A8 ${id} \u7EA6 15 \u5206\u949F\u540E\u5F00\u59CB\uFF09\u2014\u2014\u522B\u6E05\u7406\uFF0C\u4E5F\u522B\u91CD\u8DD1\u672C\u547D\u4EE4\u3002`,
+  addFailNoneAttached: (shop, id) => `\u52A0\u5546\u54C1\u5931\u8D25\uFF0C\u56DE\u8BFB\u663E\u793A\u6CA1\u6709\u4EFB\u4F55\u5546\u54C1\u6302\u4E0A\u2014\u2014\u6D3B\u52A8 ${id} \u662F\u4E00\u6761\u7A7A\u58F3\u3002\u5148\u6E05\u7406\uFF1A${deactivateCmd(shop, id)}\uFF1B\u518D\u6309\u4E0A\u9762\u7684\u5E73\u53F0\u62A5\u9519\u6539\u6B63\u53C2\u6570\u540E\u91CD\u8DD1\u539F\u547D\u4EE4\uFF08\u53EA\u6709\u9650\u6D41\u3001\u7F51\u7EDC\u7C7B\u62A5\u9519\u624D\u539F\u6837\u91CD\u8DD1\uFF09\u3002\u522B\u76F4\u63A5\u91CD\u8DD1\uFF1A\u4F1A\u649E\u91CD\u540D\u6216\u518D\u5EFA\u4E00\u4E2A\u58F3\u3002`,
+  addFailPartial: (problems, shop, id) => `\u52A0\u5546\u54C1\u62A5\u4E86\u9519\uFF0C\u56DE\u8BFB\u663E\u793A\u6CA1\u6709\u5168\u90E8\u6302\u4E0A\uFF1A${problems}\u3002\u672C\u547D\u4EE4\u4E0D\u80FD\u5F80\u5DF2\u6709\u6D3B\u52A8\u8865\u5546\u54C1\uFF0C\u8BF7\u5E97\u4E3B\u4E8C\u9009\u4E00\uFF1A\u4FDD\u7559\u6D3B\u52A8 ${id}\uFF08\u7F3A\u7684 SKU \u4E0D\u6253\u6298\uFF0C\u4EF7\u683C\u4E0D\u7B26\u7684\u6309\u8BFB\u56DE\u7684\u4EF7\u683C\u751F\u6548\uFF09\uFF0C\u6216\u6E05\u7406\u540E\u6574\u6761\u91CD\u5EFA\uFF1A${deactivateCmd(shop, id)}\uFF0C\u6E05\u7406\u540E\u6309\u4E0A\u9762\u7684\u5E73\u53F0\u62A5\u9519\u6539\u6B63\u53C2\u6570\u518D\u91CD\u8DD1\u539F\u547D\u4EE4\u3002\u522B\u76F4\u63A5\u91CD\u8DD1\u672C\u547D\u4EE4\u3002`,
+  addFailReadbackFailed: (shop, id) => `\u52A0\u5546\u54C1\u5931\u8D25\uFF0C\u56DE\u8BFB\u4E5F\u5931\u8D25\u4E86\uFF0C\u67E5\u4E0D\u5230\u6D3B\u52A8 ${id} \u91CC\u5546\u54C1\u6709\u6CA1\u6709\u6302\u4E0A\u3002\u522B\u91CD\u8DD1\u672C\u547D\u4EE4\uFF08\u4F1A\u518D\u5EFA\u4E00\u4E2A\u58F3\uFF09\uFF0C\u4E5F\u5148\u522B\u6E05\u7406\uFF1A\u5982\u5B9E\u544A\u8BC9\u5E97\u4E3B\u300C\u6D3B\u52A8\u5DF2\u5EFA\uFF0C\u5546\u54C1\u662F\u5426\u6302\u4E0A\u672A\u80FD\u786E\u8BA4\u300D\uFF0C\u8BF7\u5E97\u4E3B\u5728\u5356\u5BB6\u540E\u53F0\u770B\u8FD9\u6761\u6D3B\u52A8\u91CC\u6709\u6CA1\u6709\u5546\u54C1\uFF1B\u786E\u8BA4\u6CA1\u6302\u4E0A\u518D\u6E05\u7406\uFF1A${deactivateCmd(shop, id)}\u3002`,
+  // ⑨ 成功路径的 warnings
+  readbackFailed: (id) => `\u6D3B\u52A8 ${id} \u5DF2\u5EFA\u6210\u3001\u5546\u54C1\u5DF2\u63D0\u4EA4\uFF0C\u4F46\u56DE\u8BFB\u5931\u8D25\uFF0C\u672A\u80FD\u9A8C\u8BC1\u5546\u54C1\u662F\u5426\u6302\u4E0A\u2014\u2014\u4E0D\u8981\u91CD\u5EFA\u6D3B\u52A8\uFF1B\u5982\u5B9E\u544A\u8BC9\u5E97\u4E3B\u300C\u5DF2\u5EFA\uFF0C\u5546\u54C1\u662F\u5426\u6302\u4E0A\u672A\u80FD\u786E\u8BA4\u300D\u3002`,
+  readbackDiffers: (id, problems) => `\u6D3B\u52A8 ${id} \u5DF2\u5EFA\u6210\uFF0C\u4F46\u56DE\u8BFB\u4E0E\u63D0\u4EA4\u4E0D\u4E00\u81F4\uFF1A${problems}\u2014\u2014\u4E0D\u8981\u91CD\u5EFA\u6D3B\u52A8\uFF1B\u5982\u5B9E\u544A\u8BC9\u5E97\u4E3B\u54EA\u4E9B SKU \u672A\u786E\u8BA4\u6302\u4E0A\u3002`
+};
+var OBSERVED_REJECT_CODES = /* @__PURE__ */ new Set([
+  36009004,
+  36009009,
+  36009010,
+  17029001,
+  17029004,
+  17029010,
+  17029021,
+  17029022,
+  17029043,
+  17029044,
+  17029063,
+  105002,
+  106001,
+  105005
+]);
+var DUP_NAME_CODE = 17029004;
+function createFailureVerdict(env2) {
+  const err = env2.error;
+  const status = env2.meta?.http_status;
+  if (status === void 0) return "maybe_landed";
+  if (err.code === "RATE_LIMITED") return "maybe_landed";
+  if (status >= 500) return "maybe_landed";
+  const m = err.code === "TIKTOK_ERROR" ? /^\[(\d+)\]/.exec(err.message) : null;
+  const code = m ? Number(m[1]) : void 0;
+  if (status >= 400) return code === DUP_NAME_CODE ? "dup" : "rejected";
+  if (err.code === "AUTH_EXPIRED") return "rejected";
+  if (code !== void 0 && OBSERVED_REJECT_CODES.has(code)) return code === DUP_NAME_CODE ? "dup" : "rejected";
+  return "maybe_landed";
+}
+function submittedSkus(args2) {
+  return discountProductsBody(args2).products.flatMap((p) => p.skus.map((s) => ({ sid: s.id, amount: s.activity_price_amount })));
+}
+function compareReadback(submitted, readback) {
+  const products = readback?.products;
+  if (!Array.isArray(products)) return null;
+  const skus = products.flatMap((p) => Array.isArray(p?.skus) ? p.skus : []);
+  const mine = new Set(submitted.map((s) => s.sid));
+  const byId = /* @__PURE__ */ new Map();
+  const extra = [];
+  for (const s of skus) {
+    const id = String(s?.id);
+    if ((byId.has(id) || !mine.has(id)) && !extra.includes(id)) extra.push(id);
+    if (!byId.has(id)) byId.set(id, s);
+  }
+  const diff = { missing: [], mismatched: [], extra, total: skus.length, productCount: products.length };
+  for (const { sid, amount } of submitted) {
+    const hit = byId.get(sid);
+    if (!hit) {
+      diff.missing.push(sid);
+      continue;
+    }
+    const raw = hit.activity_price?.amount;
+    const got = raw === void 0 || raw === null || raw === "" ? void 0 : String(raw);
+    if (got === void 0 || Number(got) !== Number(amount)) diff.mismatched.push({ sid, submitted: amount, readback: got });
+  }
+  return diff;
+}
+function problemsText(d) {
+  const parts = [];
+  if (d.missing.length) parts.push(`\u7F3A ${d.missing.join("\u3001")}`);
+  if (d.mismatched.length) {
+    parts.push(`\u91D1\u989D\u4E0D\u7B26 ${d.mismatched.map((m) => `${m.sid}\uFF08\u63D0\u4EA4 ${m.submitted}\uFF0C\u8BFB\u56DE ${m.readback ?? "\u65E0\u91D1\u989D"}\uFF09`).join("\u3001")}`);
+  }
+  return parts.join("\uFF1B");
+}
+function mergeWarnings(existing, ours) {
+  if (existing === null || existing === void 0) return ours;
+  if (Array.isArray(existing)) return [...existing, ...ours];
+  return [existing, ...ours];
+}
+var DUP_SEARCH_MAX_PAGES = 10;
+async function dupSelfCheck(shop, title, submitted) {
+  const found = /* @__PURE__ */ new Map();
+  for (const status of ["NOT_START", "ONGOING"]) {
+    let token;
+    for (let page = 1; ; page++) {
+      const r = await proxy("POST", shop, "/promotion/202309/activities/search", {
+        body: { status, page_size: 50, ...token ? { page_token: token } : {} }
+      });
+      if (!r.ok) return DISCOUNT_TEXT.dupUnclear(title, r.error.message);
+      const d2 = r.data ?? {};
+      for (const a of Array.isArray(d2.activities) ? d2.activities : []) {
+        if (a?.title === title) found.set(String(a.id), { id: String(a.id), status: String(a.status) });
+      }
+      token = d2.next_page_token ? String(d2.next_page_token) : void 0;
+      if (!token) break;
+      if (page === DUP_SEARCH_MAX_PAGES) return DISCOUNT_TEXT.dupUnclear(title, `\u540C\u540D\u81EA\u67E5\u7FFB\u4E86 ${DUP_SEARCH_MAX_PAGES} \u9875\u4ECD\u672A\u7FFB\u5B8C`);
+    }
+  }
+  if (found.size === 0) return DISCOUNT_TEXT.dupRetitle(title);
+  if (found.size > 1) return DISCOUNT_TEXT.dupMulti(title, [...found.values()].sort((a, b) => Number(a.status !== "NOT_START") - Number(b.status !== "NOT_START")));
+  const [hit] = found.values();
+  const g = await proxy("GET", shop, `/promotion/202309/activities/${hit.id}`, {});
+  if (!g.ok) return DISCOUNT_TEXT.dupUnclear(title, g.error.message);
+  const d = compareReadback(submitted, g.data);
+  if (!d) return DISCOUNT_TEXT.dupUnclear(title, "\u56DE\u8BFB\u7F3A products \u5B57\u6BB5");
+  if (d.missing.length === 0 && d.mismatched.length === 0 && d.total === submitted.length) {
+    return DISCOUNT_TEXT.dupSame(title, hit.id, hit.status);
+  }
+  if (d.productCount === 0) return DISCOUNT_TEXT.dupEmpty(title, hit.id, hit.status, shop);
+  return DISCOUNT_TEXT.dupOwner(title, hit.id, hit.status, problemsText(d) || `\u591A\u51FA ${d.extra.join("\u3001")}`);
+}
 
 // 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 = [];
@@ -1241,6 +1740,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");
 }
@@ -1250,11 +1750,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);
@@ -1271,24 +1800,29 @@ 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();
   process.exit(1);
 }
+var ctx = { shop: args.shop ?? "", args, actor: args.actor, rest: match.rest };
+var verdict = match.cmd.validate?.(ctx);
+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);
 }
-var ctx = { shop: args.shop ?? "", args, actor: args.actor };
 if (match.cmd.write && !("apply" in args)) {
   if (match.cmd.precheck) {
     const pc = await match.cmd.precheck(ctx);
@@ -1314,7 +1848,7 @@ fillEmptyList(env.data, match.cmd.listKey);
 if (match.cmd.write && env.ok) {
   const result = { ...env, applied: true };
   if (env.data?.warnings?.length) {
-    result.warnings_alert = "\u26A0\uFE0F \u6709\u5B57\u6BB5\u88AB\u9759\u9ED8\u5904\u7406\uFF0C\u89C1 warnings";
+    result.warnings_alert = "\u26A0\uFE0F \u6709\u8B66\u544A\uFF0C\u89C1 data.warnings";
   }
   if (match.cmd.readback) {
     const rb = await match.cmd.readback(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/tiktok-cli",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "TikTok Shop CLI for Optima agents — 经 tiktok-backend 操作店铺",
   "type": "module",
   "bin": {
@@ -30,7 +30,8 @@
     "directory": "tiktok-cli"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "engines": {
     "node": ">=20"