@optima-chat/tiktok-cli 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# tiktok-cli
+
+Optima agent 用来操作 TikTok 店铺的 CLI。**薄客户端**：不直连 TikTok、不持凭证，一切经 [tiktok-backend](../tiktok-backend) 的 `/proxy`（backend 解析 shop → 取 token → 签名 → 转发）。
+
+这是「把 xuhao repo 的浏览器 skill 改成 CLI」的落地——agent 一行命令拉到真实店铺数据，替代紫鸟 + Playwright。
+
+## 用法
+
+```bash
+tiktok <domain> <verb> --shop <shopId> [--flags]
+```
+
+- `--shop` **必填**（多店显式路由，对应 A 轨「多店必须显式选店」教训）
+- 默认 **JSON 输出**，统一信封 `{ ok, data?, error?, meta? }`
+- `TIKTOK_BACKEND_URL` 指向 backend（默认 `http://127.0.0.1:3000`）
+
+## 命令（v1 只读）
+
+| 命令 | 说明 |
+|---|---|
+| `shops --merchant <id>` | 查商家已授权店铺 |
+| `orders list` | 订单列表（`--status --page-size --since`） |
+| `orders get --id <id>` | 订单详情 |
+| `analytics shop` | 店铺经营数据（`--from --to`，默认近30天） |
+| `analytics products` | 商品维度数据（GMV 降序） |
+| `products list` | 商品列表 |
+| `promotions list` | 促销活动（`--status`） |
+| `finance statements` | 结算单 |
+
+## 写操作（Phase 2，安全护栏）
+
+写命令三道阀，把 A 轨「填完回读」纪律做进 CLI：
+
+1. **默认 dry-run** —— 不加 `--apply` 只打印将提交的 payload，不碰真实店铺
+2. `--apply` 才真发
+3. **成功后自动回读** —— 写完 GET 回资源，输出 `readback` 供 agent/人核对是否生效
+
+```bash
+# 预览（安全）
+tiktok products set-price --shop <id> --product <pid> --sku <sid> --price 29.90
+# 确认后执行
+tiktok products set-price --shop <id> --product <pid> --sku <sid> --price 29.90 --apply
+```
+
+| 命令 | 说明 | 验证 |
+|---|---|---|
+| `products set-price` | 改 SKU 售价（`--product --sku --price [--currency]`） | ✓ 改价+回读 |
+| `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`）。不可逆 | ✓ |
+
+均在跨境测试店真实验证（2026-09-02）：`ok/applied` → 回读确认 → 审计落库。
+
+**秒杀字段坑**（OAS 未标、实测撞出）：商品级 `quantity_limit` 在 VARIATION 模式必须 `-1`（限量由 SKU 级控制）；秒杀价须**低于该 SKU 近 30 天最低成交价**且**不超折扣上限**。这些复杂度被 CLI 吸收，agent 一次成型。
+
+## 错误分类（agent 靠此决策）
+
+`error.code` + `retryable` 让 agent 判断重试还是停止：
+
+| code | 含义 | retryable |
+|---|---|---|
+| `RATE_LIMITED` | 限流 | ✅（带 retry_after_s） |
+| `BACKEND_UNREACHABLE` | 连不上 backend | ✅ |
+| `AUTH_EXPIRED` | token/授权失效 | ❌ 需重授权 |
+| `SHOP_NOT_AUTHORIZED` | 无此店授权 | ❌ |
+| `VALIDATION` | 参数/业务错误 | ❌ |
+| `TIKTOK_ERROR` | TikTok 其他错误（透传码） | ❌ |
+
+## 命令 → 端点映射
+
+命令定义见 `src/commands.ts`，每条对应一个 TikTok 端点，逐条对齐 xuhao repo 的浏览器 skill（见 [接口草案](../docs/tiktok-backend-接口草案.md)）。加命令只动这张表。

package/dist/index.js

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+
+// src/client.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var BACKEND = process.env.TIKTOK_BACKEND_URL ?? "http://127.0.0.1:3000";
+function authHeaders() {
+  const explicit = process.env.OPTIMA_TOKEN;
+  if (explicit) return { Authorization: `Bearer ${explicit}` };
+  try {
+    const t = JSON.parse(readFileSync(join(homedir(), ".optima", "token.json"), "utf8"));
+    if (t.access_token) return { Authorization: `Bearer ${t.access_token}` };
+  } catch {
+  }
+  return {};
+}
+function classify(status, body, shop) {
+  const meta = { shop, tiktok_request_id: body?.request_id };
+  if (status === 0 || body?.code === 0) {
+    return { ok: true, data: body.data, meta };
+  }
+  if (status === 404) return { ok: false, error: { code: "SHOP_NOT_AUTHORIZED", message: body?.error ?? "\u5E97\u94FA\u672A\u6388\u6743", retryable: false }, meta };
+  if (status === 403) return { ok: false, error: { code: "VALIDATION", message: body?.error ?? "\u8DEF\u5F84\u4E0D\u5141\u8BB8", retryable: false }, meta };
+  const tc = body?.code;
+  const msg = body?.message ?? body?.error ?? `HTTP ${status}`;
+  if (tc === 36009002 || status === 429) return { ok: false, error: { code: "RATE_LIMITED", message: msg, retryable: true, retry_after_s: 30 }, meta };
+  if (tc === 105002 || tc === 105005 || status === 401) return { ok: false, error: { code: "AUTH_EXPIRED", message: msg, retryable: false }, meta };
+  if (typeof tc === "number" && tc >= 1e5) return { ok: false, error: { code: "TIKTOK_ERROR", message: `[${tc}] ${msg}`, retryable: false }, meta };
+  return { ok: false, error: { code: "VALIDATION", message: msg, retryable: false }, meta };
+}
+async function proxy(method, shop, path, opts = {}) {
+  const qs = opts.query ? "?" + new URLSearchParams(opts.query) : "";
+  const url = `${BACKEND}/proxy/${shop}${path}${qs}`;
+  try {
+    const r = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        "x-optima-actor": opts.actor ?? process.env.USER ?? "cli",
+        ...authHeaders()
+      },
+      body: method === "POST" || method === "PUT" ? JSON.stringify(opts.body ?? {}) : void 0
+    });
+    const body = await r.json().catch(() => ({}));
+    return classify(r.status, body, shop);
+  } catch (e) {
+    return { ok: false, error: { code: "BACKEND_UNREACHABLE", message: `\u8FDE\u4E0D\u4E0A backend ${BACKEND}: ${e.message}`, retryable: true } };
+  }
+}
+async function listShops() {
+  try {
+    const r = await fetch(`${BACKEND}/auth/shops`, { 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: body.shops };
+  } catch (e) {
+    return { ok: false, error: { code: "BACKEND_UNREACHABLE", message: e.message, retryable: true } };
+  }
+}
+
+// src/commands.ts
+var today = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+var daysAgo = (n) => new Date(Date.now() - n * 864e5).toISOString().slice(0, 10);
+var COMMANDS = [
+  {
+    name: "orders list",
+    summary: "\u8BA2\u5355\u5217\u8868\uFF08\u9ED8\u8BA4\u8FD130\u5929\uFF0C\u53EF --status --page-size\uFF09",
+    run: ({ shop, args: args2 }) => proxy("POST", shop, "/order/202309/orders/search", {
+      query: { page_size: args2["page-size"] ?? "20" },
+      body: {
+        ...args2.status ? { order_status: args2.status } : {},
+        create_time_ge: args2.since ? Number(args2.since) : Math.floor(Date.parse(daysAgo(30)) / 1e3)
+      }
+    })
+  },
+  {
+    name: "orders get",
+    summary: "\u8BA2\u5355\u8BE6\u60C5\uFF08--id \u5FC5\u586B\uFF09",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, "/order/202309/orders/detail", { query: { ids: args2.id } })
+  },
+  {
+    name: "analytics shop",
+    summary: "\u5E97\u94FA\u7ECF\u8425\u6570\u636E\uFF08--from --to\uFF0C\u9ED8\u8BA4\u8FD130\u5929\uFF09",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, "/analytics/202509/shop/performance", {
+      query: {
+        start_date_ge: args2.from ?? daysAgo(30),
+        end_date_lt: args2.to ?? today(),
+        granularity: args2.granularity ?? "ALL"
+      }
+    })
+  },
+  {
+    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"
+      }
+    })
+  },
+  {
+    name: "products list",
+    summary: "\u5546\u54C1\u5217\u8868",
+    run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/products/search", {
+      query: { page_size: args2["page-size"] ?? "20" },
+      body: {}
+    })
+  },
+  {
+    name: "promotions list",
+    summary: "\u4FC3\u9500\u6D3B\u52A8\u5217\u8868\uFF08--status ONGOING/NOT_START/EXPIRED\uFF09",
+    run: ({ shop, args: args2 }) => proxy("POST", shop, "/promotion/202309/activities/search", {
+      body: { status: args2.status ?? "ONGOING", page_size: Number(args2["page-size"] ?? 20) }
+    })
+  },
+  {
+    name: "finance statements",
+    summary: "\u7ED3\u7B97\u5355\u5217\u8868",
+    run: ({ shop, args: args2 }) => proxy("GET", shop, "/finance/202309/statements", {
+      query: {
+        page_size: args2["page-size"] ?? "20",
+        sort_field: args2["sort-field"] ?? "statement_time",
+        sort_order: args2["sort-order"] ?? "DESC"
+      }
+    })
+  },
+  // ===== 写操作（Phase 2）：默认 --dry-run，--apply 才真发，成功后回读 =====
+  {
+    name: "products set-price",
+    summary: "\u6539 SKU \u552E\u4EF7\uFF08--product --sku --price [--currency MYR]\uFF09\u3002\u5199\u64CD\u4F5C,\u9ED8\u8BA4 dry-run",
+    write: true,
+    preview: ({ args: args2 }) => [{
+      step: "\u6539\u4EF7",
+      method: "POST",
+      path: `/product/202309/products/${args2.product}/prices/update`,
+      body: priceBody(args2)
+    }],
+    run: ({ shop, args: args2 }) => proxy("POST", shop, `/product/202309/products/${args2.product}/prices/update`, { body: priceBody(args2) }),
+    readback: ({ shop, args: args2 }) => proxy("GET", shop, `/product/202309/products/${args2.product}`, {})
+  },
+  {
+    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",
+    write: true,
+    preview: ({ args: args2 }) => {
+      const { begin, end } = flashWindow(args2);
+      return [
+        { step: "1/2 \u5EFA\u6D3B\u52A8\u58F3", method: "POST", path: "/promotion/202309/activities", body: flashActivityBody(args2, begin, end) },
+        { step: "2/2 \u52A0\u5546\u54C1+\u79D2\u6740\u4EF7", method: "PUT", path: "/promotion/202309/activities/{activity_id}/products", body: flashProductsBody(args2) }
+      ];
+    },
+    run: async ({ shop, args: args2 }) => {
+      const { begin, end } = flashWindow(args2);
+      const created = await proxy("POST", shop, "/promotion/202309/activities", { body: flashActivityBody(args2, begin, end) });
+      if (!created.ok) return created;
+      const activityId = created.data?.activity_id ?? created.data?.activity?.id;
+      if (!activityId) return { ok: false, error: { code: "TIKTOK_ERROR", message: "\u5EFA\u6D3B\u52A8\u6210\u529F\u4F46\u672A\u62FF\u5230 activity_id", retryable: false }, meta: created.meta };
+      const withProducts = await proxy("PUT", shop, `/promotion/202309/activities/${activityId}/products`, {
+        body: { ...flashProductsBody(args2), activity_id: activityId }
+      });
+      return withProducts.ok ? { ok: true, data: { activity_id: activityId, ...withProducts.data }, meta: withProducts.meta } : { ...withProducts, data: { activity_id: activityId, note: "\u6D3B\u52A8\u58F3\u5DF2\u5EFA\u4F46\u52A0\u5546\u54C1\u5931\u8D25\uFF0C\u53EF promotions deactivate \u6E05\u7406" } };
+    },
+    readback: ({ shop, args: args2 }) => proxy("POST", shop, "/promotion/202309/activities/search", { body: { status: "NOT_START", page_size: 20 } })
+  },
+  {
+    name: "promotions deactivate",
+    summary: "\u7EC8\u6B62/\u505C\u7528\u4FC3\u9500\u6D3B\u52A8\uFF08--id \u5FC5\u586B\uFF09\u3002\u4E0D\u53EF\u9006",
+    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: {} })
+  },
+  {
+    name: "products set-inventory",
+    summary: "\u6539 SKU \u5E93\u5B58\uFF08--product --sku --warehouse --quantity\uFF09\u3002\u5199\u64CD\u4F5C,\u9ED8\u8BA4 dry-run",
+    write: true,
+    preview: ({ args: args2 }) => [{
+      step: "\u6539\u5E93\u5B58",
+      method: "POST",
+      path: `/product/202309/products/${args2.product}/inventory/update`,
+      body: inventoryBody(args2)
+    }],
+    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}`, {})
+  }
+];
+function inventoryBody(args2) {
+  return {
+    skus: [{
+      id: args2.sku,
+      inventory: [{ warehouse_id: args2.warehouse, quantity: Number(args2.quantity) }]
+    }]
+  };
+}
+function flashWindow(args2) {
+  const now = Math.floor(Date.now() / 1e3);
+  const begin = now + Number(args2["start-in-min"] ?? 15) * 60;
+  const end = begin + Number(args2.hours ?? 48) * 3600;
+  return { begin, end };
+}
+function flashActivityBody(args2, begin, end) {
+  return {
+    title: args2.title,
+    activity_type: "FLASHSALE",
+    product_level: "VARIATION",
+    // 指定 SKU 参与
+    begin_time: begin,
+    end_time: end
+  };
+}
+function flashProductsBody(args2) {
+  const limit = Number(args2.limit ?? 100);
+  const perUser = Number(args2["per-user"] ?? 1);
+  return {
+    products: [{
+      id: args2.product,
+      quantity_limit: -1,
+      quantity_per_user: perUser,
+      skus: [{
+        id: args2.sku,
+        activity_price_amount: args2.price,
+        quantity_limit: limit,
+        quantity_per_user: perUser
+      }]
+    }]
+  };
+}
+function priceBody(args2) {
+  return {
+    skus: [{ id: args2.sku, price: { amount: args2.price, currency: args2.currency ?? "MYR" } }]
+  };
+}
+function findCommand(tokens) {
+  for (const cmd of [...COMMANDS].sort((a, b) => b.name.length - a.name.length)) {
+    const parts = cmd.name.split(" ");
+    if (parts.every((p, i) => tokens[i] === p)) {
+      return { cmd, rest: tokens.slice(parts.length) };
+    }
+  }
+  return null;
+}
+
+// src/index.ts
+function parseFlags(tokens) {
+  const args2 = {};
+  const positional2 = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.startsWith("--")) {
+      const key = t.slice(2);
+      const next = tokens[i + 1];
+      if (next && !next.startsWith("--")) {
+        args2[key] = next;
+        i++;
+      } else args2[key] = "true";
+    } else positional2.push(t);
+  }
+  return { args: args2, positional: positional2 };
+}
+function out(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+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");
+  process.stderr.write(lines.join("\n") + "\n");
+}
+var argv = process.argv.slice(2);
+if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+  usage();
+  process.exit(argv.length === 0 ? 1 : 0);
+}
+var { args, positional } = parseFlags(argv);
+if (positional[0] === "shops") {
+  out(await listShops());
+  process.exit(0);
+}
+var match = findCommand(positional);
+if (!match) {
+  out({ ok: false, error: { code: "VALIDATION", message: `\u672A\u77E5\u547D\u4EE4: ${positional.join(" ")}`, retryable: false } });
+  usage();
+  process.exit(1);
+}
+if (!args.shop) {
+  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)) {
+  const plan = match.cmd.preview?.(ctx);
+  out({
+    ok: true,
+    dry_run: true,
+    message: "\u672A\u52A0 --apply\uFF0C\u4EC5\u9884\u89C8\u3002\u786E\u8BA4\u65E0\u8BEF\u540E\u52A0 --apply \u6267\u884C\u3002",
+    plan
+  });
+  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 } });
+} else {
+  out(env);
+}
+process.exit(env.ok ? 0 : 1);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@optima-chat/tiktok-cli",
+  "version": "0.1.0",
+  "description": "TikTok Shop CLI for Optima agents — 经 tiktok-backend 操作店铺",
+  "type": "module",
+  "bin": {
+    "tiktok": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Optima Commerce Team",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Optima-Chat/tiktok-api-integration.git",
+    "directory": "tiktok-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}