@optima-chat/tiktok-cli 0.1.0 → 0.3.0

package/README.md

@@ -10,15 +10,16 @@ Optima agent 用来操作 TikTok 店铺的 CLI。**薄客户端**：不直连 Ti
 tiktok <domain> <verb> --shop <shopId> [--flags]
 ```
 
-- `--shop` **必填**（多店显式路由，对应 A 轨「多店必须显式选店」教训）
+- `--shop` **必填**（多店显式路由，对应 A 轨「多店必须显式选店」教训；`auth link` 除外）
 - 默认 **JSON 输出**，统一信封 `{ ok, data?, error?, meta? }`
-- `TIKTOK_BACKEND_URL` 指向 backend（默认 `http://127.0.0.1:3000`）
+- `TIKTOK_BACKEND_URL` 解析顺序：显式环境变量 > `OPTIMA_ENV` 映射（`cn-stage` → `https://tiktok-api.stage.optima.chat`；`cn-prod` → `https://tiktok-api.yzsgo.com`）> 本地默认 `http://127.0.0.1:3000`
 
 ## 命令（v1 只读）
 
 | 命令 | 说明 |
 |---|---|
-| `shops --merchant <id>` | 查商家已授权店铺 |
+| `auth link` | 生成店铺绑定授权链接（无需 --shop） |
+| `shops` | 查当前登录用户已授权店铺 |
 | `orders list` | 订单列表（`--status --page-size --since`） |
 | `orders get --id <id>` | 订单详情 |
 | `analytics shop` | 店铺经营数据（`--from --to`，默认近30天） |
@@ -27,6 +28,22 @@ tiktok <domain> <verb> --shop <shopId> [--flags]
 | `promotions list` | 促销活动（`--status`） |
 | `finance statements` | 结算单 |
 
+### 建品前置只读辅助（拼商品体用）
+
+| 命令 | 说明 |
+|---|---|
+| `products prerequisites` | 建品前置检查（店铺就绪状态） |
+| `categories recommend --title [--desc]` | 类目推荐 |
+| `categories tree [--version v2]` | 类目树 |
+| `categories attributes --category <id>` | 类目属性（看 is_requried 必填项） |
+| `categories rules --category <id>` | 类目规则（尺码表/认证/包装是否强制） |
+| `brands list [--category] [--name]` | 品牌列表 |
+| `brands recommend --title <t>` | 品牌推荐 |
+| `warehouses list` | 仓库列表（跨境认 sub_type CB_*） |
+| `shipping-templates list` | 运费模板列表 |
+| `delivery-options --warehouse <id>` | 仓库交付方式 |
+| `images upload --file <path> --use-case MAIN_IMAGE [--out <f>]` | 上传本地图 → 返回 TikTok CDN `uri`（multipart，供拼 `main_images` 用） |
+
 ## 写操作（Phase 2，安全护栏）
 
 写命令三道阀，把 A 轨「填完回读」纪律做进 CLI：
@@ -48,9 +65,15 @@ tiktok products set-price --shop <id> --product <pid> --sku <sid> --price 29.90
 | `products set-inventory` | 改 SKU 库存（`--product --sku --warehouse --quantity`） | ✓ 49→55→49 可逆 |
 | `promotions create-flashsale` | 建秒杀（`--title --product --sku --price [--limit --per-user --hours]`）。两步:建壳+加品 | ✓ 真实建成 |
 | `promotions deactivate` | 终止促销活动（`--id`）。不可逆 | ✓ |
+| `products create --body-file <json>` | **生产级建品**（完整商品体 JSON）。dry-run 内嵌 `listing_check` 预检 → `--apply` 建品 → 回读高亮 warnings | ✓ 真实上架 V.V.Love（ACTIVATE） |
+| `products add-variant --product <id> --body-file <json>` | 加规格 SKU（读现有 skus → merge → partial_edit；新 SKU 自动继承 sku_dimensions/sku_weight） | ✓ 真加变体成功 |
+| `products replace-images --product <id> --body-file <json>` | 整组换主图（main_images 整组替换，非追加） | — |
+| `products partial-edit --product <id> --body-file <json>` | 改商品字段（嵌套字段整组覆盖，未列子项会被清空） | — |
 
 均在跨境测试店真实验证（2026-09-02）：`ok/applied` → 回读确认 → 审计落库。
 
+**建品字段坑**（实测坐实，见 [`../docs/建品字段权威规格.md`](../docs/建品字段权威规格.md)）：MY 跨境店价格用 `sale_price` 非 `amount`；`package_dimensions` 类目必填；仓库认 `sub_type=CB_*`；**品牌合规**——标题/主图的品牌须与 `brand_id` 一致，否则审核报「品牌不一致违规」（用第三方品牌名却不申报会被拒）；`add-variant` 加的新 SKU 必须带 `sku_dimensions`/`sku_weight`（建品时平台从 package 自动回填，加变体无此回填，CLI 已自动继承）。图片经 `images upload` 传本地文件（backend multipart 路由）。
+
 **秒杀字段坑**（OAS 未标、实测撞出）：商品级 `quantity_limit` 在 VARIATION 模式必须 `-1`（限量由 SKU 级控制）；秒杀价须**低于该 SKU 近 30 天最低成交价**且**不超折扣上限**。这些复杂度被 CLI 吸收，agent 一次成型。
 
 ## 错误分类（agent 靠此决策）

package/dist/index.js

@@ -1,10 +1,27 @@
 #!/usr/bin/env node
 
+// src/commands.ts
+import { readFileSync as readFileSync2 } from "fs";
+
 // src/client.ts
 import { readFileSync } from "fs";
 import { homedir } from "os";
+import { basename } from "path";
 import { join } from "path";
-var BACKEND = process.env.TIKTOK_BACKEND_URL ?? "http://127.0.0.1:3000";
+
+// src/backendUrl.ts
+var ENV_URLS = {
+  "cn-stage": "https://tiktok-api.stage.optima.chat",
+  "cn-prod": "https://tiktok-api.yzsgo.com"
+};
+function resolveBackendUrl(env2) {
+  if (env2.TIKTOK_BACKEND_URL) return env2.TIKTOK_BACKEND_URL;
+  const mapped = env2.OPTIMA_ENV && ENV_URLS[env2.OPTIMA_ENV];
+  return mapped || "http://127.0.0.1:3000";
+}
+
+// src/client.ts
+var BACKEND = resolveBackendUrl(process.env);
 function authHeaders() {
   const explicit = process.env.OPTIMA_TOKEN;
   if (explicit) return { Authorization: `Bearer ${explicit}` };
@@ -58,8 +75,47 @@ async function listShops() {
     return { ok: false, error: { code: "BACKEND_UNREACHABLE", message: e.message, retryable: true } };
   }
 }
+async function createAuthLink() {
+  try {
+    const r = await fetch(`${BACKEND}/auth/link`, { method: "POST", headers: authHeaders() });
+    if (r.status === 401) return { ok: false, error: { code: "AUTH_EXPIRED", message: "\u672A\u767B\u5F55\u6216 token \u5931\u6548", retryable: false } };
+    const body = await r.json();
+    return { ok: true, data: { authorize_url: body.authorize_url, expires_in_minutes: 15 } };
+  } catch (e) {
+    return { ok: false, error: { code: "BACKEND_UNREACHABLE", message: e.message, retryable: true } };
+  }
+}
+async function uploadImage(shop, filePath, useCase) {
+  try {
+    const buf = readFileSync(filePath);
+    const form = new FormData();
+    form.append("data", new Blob([buf]), basename(filePath));
+    form.append("use_case", useCase);
+    const r = await fetch(`${BACKEND}/proxy-upload/${shop}/image`, { method: "POST", headers: authHeaders(), body: form });
+    const body = await r.json().catch(() => ({}));
+    if (body?.code === 0) return { ok: true, data: { uri: body.data?.uri, url: body.data?.url, use_case: useCase }, meta: { shop } };
+    return { ok: false, error: { code: r.status === 401 ? "AUTH_EXPIRED" : "TIKTOK_ERROR", message: body?.message ?? body?.error ?? `HTTP ${r.status}`, retryable: false }, meta: { shop } };
+  } catch (e) {
+    return { ok: false, error: { code: "BACKEND_UNREACHABLE", message: e.message, retryable: true } };
+  }
+}
 
 // src/commands.ts
+function readBodyFile(path) {
+  return JSON.parse(readFileSync2(path, "utf8"));
+}
+function mergeSkus(existing, add) {
+  const template = existing?.[0];
+  const filledAdd = add.map((sku) => {
+    if (!template) return sku;
+    return {
+      ...sku,
+      sku_dimensions: sku.sku_dimensions ?? template.sku_dimensions,
+      sku_weight: sku.sku_weight ?? template.sku_weight
+    };
+  });
+  return [...existing, ...filledAdd];
+}
 var today = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var daysAgo = (n) => new Date(Date.now() - n * 864e5).toISOString().slice(0, 10);
 var COMMANDS = [
@@ -129,6 +185,78 @@ var COMMANDS = [
       }
     })
   },
+  // ===== 建品前置只读辅助命令 =====
+  {
+    name: "products prerequisites",
+    summary: "\u5EFA\u54C1\u524D\u7F6E\u68C0\u67E5",
+    run: ({ shop }) => proxy("GET", shop, "/product/202312/prerequisites", {})
+  },
+  {
+    name: "categories recommend",
+    summary: "\u7C7B\u76EE\u63A8\u8350\uFF08--title [--desc]\uFF09",
+    run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/categories/recommend", {
+      body: {
+        product_title: args2.title,
+        ...args2.desc ? { description: args2.desc } : {}
+      }
+    })
+  },
+  {
+    name: "categories tree",
+    summary: "\u7C7B\u76EE\u6811\uFF08--version v2\uFF09",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202309/categories", {
+      query: { category_version: args2.version ?? "v2" }
+    })
+  },
+  {
+    name: "categories attributes",
+    summary: "\u7C7B\u76EE\u5C5E\u6027\uFF08--category\uFF09",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/categories/${args2.category}/attributes`, {
+      query: { category_version: args2.version ?? "v2" }
+    })
+  },
+  {
+    name: "categories rules",
+    summary: "\u7C7B\u76EE\u89C4\u5219\uFF08--category\uFF09",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/categories/${args2.category}/rules`, {
+      query: { category_version: args2.version ?? "v2" }
+    })
+  },
+  {
+    name: "brands list",
+    summary: "\u54C1\u724C\u5217\u8868\uFF08[--category] [--name]\uFF09",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202309/brands", {
+      query: {
+        page_size: args2["page-size"] ?? "50",
+        ...args2.category ? { category_id: args2.category } : {},
+        ...args2.name ? { brand_name: args2.name } : {}
+      }
+    })
+  },
+  {
+    name: "brands recommend",
+    summary: "\u54C1\u724C\u63A8\u8350\uFF08--title\uFF09",
+    run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/brands/recommend", {
+      body: { product_title: args2.title }
+    })
+  },
+  {
+    name: "warehouses list",
+    summary: "\u4ED3\u5E93\u5217\u8868\uFF08\u8DE8\u5883\u8BA4 sub_type CB_*\uFF09",
+    run: ({ shop }) => proxy("GET", shop, "/logistics/202309/warehouses", {})
+  },
+  {
+    name: "shipping-templates list",
+    summary: "\u8FD0\u8D39\u6A21\u677F\u5217\u8868",
+    run: ({ shop }) => proxy("GET", shop, "/logistics/202510/seller_templates", {})
+  },
+  {
+    name: "delivery-options",
+    summary: "\u4ED3\u5E93\u4EA4\u4ED8\u65B9\u5F0F\uFF08--warehouse\uFF09",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, `/logistics/202309/warehouses/${args2.warehouse}/delivery_options`, {
+      query: { scope: "PRODUCT" }
+    })
+  },
   // ===== 写操作（Phase 2）：默认 --dry-run，--apply 才真发，成功后回读 =====
   {
     name: "products set-price",
@@ -186,6 +314,49 @@ var COMMANDS = [
     }],
     run: ({ shop, args: args2 }) => proxy("POST", shop, `/product/202309/products/${args2.product}/inventory/update`, { body: inventoryBody(args2) }),
     readback: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/products/${args2.product}`, {})
+  },
+  {
+    name: "products create",
+    summary: "\u5EFA\u54C1\uFF08--body-file [--apply]\uFF09\u3002dry-run \u8DD1 listing_check \u9884\u68C0\uFF1B\u5199\u64CD\u4F5C",
+    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"]) }),
+    run: async ({ shop, args: args2 }) => {
+      const body = readBodyFile(args2["body-file"]);
+      return proxy("POST", shop, "/product/202309/products", { body });
+    },
+    readback: async ({ shop, args: args2 }) => {
+      return proxy("POST", shop, "/product/202309/products/search", { query: { page_size: "5" }, body: {} });
+    }
+  },
+  {
+    name: "products add-variant",
+    summary: "\u7ED9\u5546\u54C1\u52A0\u89C4\u683C SKU\uFF08--product --body-file skus-delta.json [--apply]\uFF09",
+    write: true,
+    preview: () => [{ step: "\u8BFB\u73B0\u6709 skus \u2192 append \u2192 partial_edit", method: "POST", path: "/product/202309/products/{id}/partial_edit" }],
+    run: async ({ shop, args: args2 }) => {
+      const cur = await proxy("GET", shop, `/product/202309/products/${args2.product}`, {});
+      if (!cur.ok) return cur;
+      const merged = mergeSkus(cur.data?.skus ?? [], readBodyFile(args2["body-file"]).skus ?? []);
+      return proxy("POST", shop, `/product/202309/products/${args2.product}/partial_edit`, { body: { skus: merged } });
+    },
+    readback: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/products/${args2.product}`, {})
+  },
+  {
+    name: "products replace-images",
+    summary: "\u6574\u7EC4\u6362\u4E3B\u56FE\uFF08--product --body-file images.json [--apply]\uFF09",
+    write: true,
+    preview: () => [{ step: "main_images \u6574\u7EC4\u66FF\u6362 \u2192 partial_edit", 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 } }),
+    readback: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/products/${args2.product}`, {})
+  },
+  {
+    name: "products partial-edit",
+    summary: "\u6539\u5546\u54C1\u5B57\u6BB5\uFF08--product --body-file patch.json [--apply]\uFF09\u3002\u5D4C\u5957\u5B57\u6BB5\u6574\u7EC4\u8986\u76D6",
+    write: true,
+    preview: ({ args: args2 }) => [{ step: "partial_edit\uFF08\u5D4C\u5957\u5B57\u6BB5\u672A\u5217\u5B50\u9879\u4F1A\u88AB\u6E05\u7A7A\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"]) }),
+    readback: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/products/${args2.product}`, {})
   }
 ];
 function inventoryBody(args2) {
@@ -268,7 +439,9 @@ function usage() {
   const lines = ["tiktok <domain> <verb> --shop <shopId> [--flags]", "", "\u547D\u4EE4\uFF1A"];
   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("", "\u901A\u7528\uFF1A--shop \u5FC5\u586B\uFF08\u9664 shops\uFF09\uFF1B\u9ED8\u8BA4 JSON \u8F93\u51FA\uFF1BTIKTOK_BACKEND_URL \u6307\u5411 backend\u3002");
+  lines.push(`  ${"auth link".padEnd(22)} \u751F\u6210\u5E97\u94FA\u7ED1\u5B9A\u6388\u6743\u94FE\u63A5\uFF08\u53D1\u7ED9\u5546\u5BB6\u70B9\u51FB\uFF09`);
+  lines.push(`  ${"images upload".padEnd(22)} \u4E0A\u4F20\u672C\u5730\u56FE\u7247\uFF08--file --use-case [--out]\uFF09`);
+  lines.push("", "\u901A\u7528\uFF1A--shop \u5FC5\u586B\uFF08\u9664 shops / auth link\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");
 }
 var argv = process.argv.slice(2);
@@ -281,6 +454,27 @@ if (positional[0] === "shops") {
   out(await listShops());
   process.exit(0);
 }
+if (positional[0] === "auth" && positional[1] === "link") {
+  out(await createAuthLink());
+  process.exit(0);
+}
+if (positional[0] === "images" && positional[1] === "upload") {
+  if (!args.file) {
+    out({ ok: false, error: { code: "VALIDATION", message: "\u7F3A\u5C11 --file", retryable: false } });
+    process.exit(1);
+  }
+  if (!args.shop) {
+    out({ ok: false, error: { code: "VALIDATION", message: "\u7F3A\u5C11 --shop", retryable: false } });
+    process.exit(1);
+  }
+  const r = await uploadImage(args.shop, args.file, args["use-case"] ?? "MAIN_IMAGE");
+  if (r.ok && args.out) {
+    const { appendFileSync } = await import("fs");
+    appendFileSync(args.out, JSON.stringify(r.data) + "\n");
+  }
+  out(r);
+  process.exit(0);
+}
 var match = findCommand(positional);
 if (!match) {
   out({ ok: false, error: { code: "VALIDATION", message: `\u672A\u77E5\u547D\u4EE4: ${positional.join(" ")}`, retryable: false } });
@@ -293,6 +487,16 @@ if (!args.shop) {
 }
 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);
+    out({
+      ok: true,
+      dry_run: true,
+      precheck: pc.ok ? pc.data : { error: pc.error },
+      message: "listing_check \u9884\u68C0\u7ED3\u679C\uFF0C\u786E\u8BA4\u540E\u52A0 --apply \u6267\u884C\u3002"
+    });
+    process.exit(0);
+  }
   const plan = match.cmd.preview?.(ctx);
   out({
     ok: true,
@@ -303,9 +507,16 @@ if (match.cmd.write && !("apply" in args)) {
   process.exit(0);
 }
 var env = await match.cmd.run(ctx);
-if (match.cmd.write && env.ok && match.cmd.readback) {
-  const rb = await match.cmd.readback(ctx);
-  out({ ...env, applied: true, readback: rb.ok ? rb.data : { error: rb.error } });
+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";
+  }
+  if (match.cmd.readback) {
+    const rb = await match.cmd.readback(ctx);
+    result.readback = rb.ok ? rb.data : { error: rb.error };
+  }
+  out(result);
 } else {
   out(env);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/tiktok-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TikTok Shop CLI for Optima agents — 经 tiktok-backend 操作店铺",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "build": "tsup src/index.ts --format esm --clean",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.mts",
     "prepublishOnly": "npm run build"
   },
   "author": "Optima Commerce Team",