siluzan-tso-cli 1.1.47-beta.1 → 1.1.47-beta.2

package/README.md

@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills  # 写入自定义目录
 siluzan-tso init --force             # 强制覆盖已存在文件
 ```
 
-> **注意**：当前为测试版（1.1.47-beta.1），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+> **注意**：当前为测试版（1.1.47-beta.2），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/index.js

@@ -134230,6 +134230,87 @@ function parseTikTokNumber(value) {
   const n = Number(value);
   return Number.isFinite(n) ? n : void 0;
 }
+var TIKTOK_VALUE_METRICS = ["total_purchase_value"];
+var TIKTOK_OFFICIAL_ROAS_METRICS = [
+  "complete_payment_roas",
+  "total_active_pay_roas"
+];
+var TIKTOK_ROAS_COMPANION_METRICS = [
+  "total_purchase_value",
+  "complete_payment_roas",
+  "total_active_pay_roas"
+];
+function splitTikTokCsv(raw) {
+  return raw.split(",").map((x) => x.trim()).filter(Boolean);
+}
+function pickFirstMetric(row, keys) {
+  let fallback;
+  for (const key of keys) {
+    const value = parseTikTokNumber(row[key]);
+    if (value === void 0) continue;
+    if (value > 0) return { key, value };
+    fallback ??= { key, value };
+  }
+  return fallback;
+}
+function expandTikTokOfficialReportMetrics(metrics) {
+  const parts = splitTikTokCsv(metrics);
+  const needCompanions = parts.includes("complete_payment") || TIKTOK_ROAS_COMPANION_METRICS.some((k) => parts.includes(k));
+  if (!needCompanions) return parts.join(",");
+  for (const extra of TIKTOK_ROAS_COMPANION_METRICS) {
+    if (!parts.includes(extra)) parts.push(extra);
+  }
+  return parts.join(",");
+}
+function pickTikTokOfficialRoas(row) {
+  return pickFirstMetric(row, TIKTOK_OFFICIAL_ROAS_METRICS);
+}
+function pickTikTokRevenue(row) {
+  const picked = pickFirstMetric(row, TIKTOK_VALUE_METRICS);
+  if (!picked) return { revenue: void 0, revenueSource: void 0 };
+  return { revenue: picked.value, revenueSource: picked.key };
+}
+function attachTikTokRoasFields(row) {
+  const spend = parseTikTokNumber(row.spend);
+  const official = pickTikTokOfficialRoas(row);
+  const purchase = pickTikTokRevenue(row);
+  if (purchase.revenue !== void 0) {
+    row.revenue = purchase.revenue;
+    row.revenueSource = purchase.revenueSource;
+  } else if (official && official.value > 0 && spend !== void 0 && spend > 0) {
+    row.revenue = official.value * spend;
+    row.revenueSource = `${official.key}*spend`;
+  }
+  const revenue = parseTikTokNumber(row.revenue);
+  if (official && official.value > 0) {
+    row.roas = official.value;
+    row.roasSource = official.key;
+  } else if (spend !== void 0 && spend > 0 && revenue !== void 0) {
+    row.roas = revenue / spend;
+    row.roasSource = "computed";
+  } else if (official) {
+    row.roas = official.value;
+    row.roasSource = official.key;
+  }
+}
+function summarizeTikTokOfficialReport(items2) {
+  let spend = 0;
+  let revenue = 0;
+  let hasRevenue = false;
+  for (const row of items2) {
+    spend += parseTikTokNumber(row.spend) ?? 0;
+    const rowRevenue = parseTikTokNumber(row.revenue);
+    if (rowRevenue === void 0) continue;
+    revenue += rowRevenue;
+    hasRevenue = true;
+  }
+  return {
+    spend,
+    revenue: hasRevenue ? revenue : 0,
+    roas: spend > 0 && hasRevenue ? revenue / spend : void 0,
+    itemCount: items2.length
+  };
+}
 function flattenTikTokReportRow(row) {
   const dims = row.dimensions && typeof row.dimensions === "object" && !Array.isArray(row.dimensions) ? row.dimensions : {};
   const metrics = row.metrics && typeof row.metrics === "object" && !Array.isArray(row.metrics) ? row.metrics : {};
@@ -134238,11 +134319,7 @@ function flattenTikTokReportRow(row) {
     const n = parseTikTokNumber(v);
     out[k] = n === void 0 ? v : n;
   }
-  const spend = parseTikTokNumber(out.spend);
-  const payment = parseTikTokNumber(out.complete_payment);
-  if (spend !== void 0 && spend > 0 && payment !== void 0) {
-    out.roas = payment / spend;
-  }
+  attachTikTokRoasFields(out);
   return out;
 }
 function pickAdGroupBidField(bidType) {
@@ -134450,6 +134527,7 @@ async function fetchAdEntities(config, opts) {
   );
 }
 async function fetchOfficialReport(config, opts) {
+  const metrics = expandTikTokOfficialReportMetrics(opts.metrics);
   const base = requireTikTokApiUrl(config);
   const raw = await fetchTikTokPagedList(
     config,
@@ -134461,7 +134539,7 @@ async function fetchOfficialReport(config, opts) {
         endDate: opts.endDate,
         dataLevel: opts.dataLevel,
         dimensions: opts.dimensions,
-        metrics: opts.metrics,
+        metrics,
         serviceType: opts.serviceType,
         pageNum,
         pageSize
@@ -134471,7 +134549,8 @@ async function fetchOfficialReport(config, opts) {
   );
   return {
     items: raw.items.map(flattenTikTokReportRow),
-    totalNumber: raw.totalNumber
+    totalNumber: raw.totalNumber,
+    metrics
   };
 }
 
@@ -134725,7 +134804,7 @@ async function runTikTokOfficialReport(opts) {
   const id = assertTikTokAccountId(opts.account);
   const dataLevel = opts.dataLevel.trim();
   const dimensions = opts.dimensions.trim();
-  const metrics = opts.metrics.trim();
+  const metrics = expandTikTokOfficialReportMetrics(opts.metrics.trim());
   if (!dataLevel || !dimensions || !metrics) {
     console.error("\n\u274C --data-level / --dimensions / --metrics \u5747\u4E3A\u5FC5\u586B\u3002\n");
     process.exit(1);
@@ -134750,6 +134829,7 @@ async function runTikTokOfficialReport(opts) {
   } catch (err) {
     fail("\u67E5\u8BE2 TikTok \u5B98\u65B9\u62A5\u8868\u5931\u8D25", err);
   }
+  const totals = summarizeTikTokOfficialReport(result.items);
   const payload = {
     account: id,
     dataLevel,
@@ -134758,6 +134838,7 @@ async function runTikTokOfficialReport(opts) {
     metrics,
     startDate,
     endDate,
+    totals,
     ...wrapListJson({
       page: 1,
       pageSize,
@@ -134783,9 +134864,11 @@ TikTok \u5B98\u65B9\u62A5\u8868 ${dataLevel} ${startDate}~${endDate}\uFF08${id}\
     console.log("  \u65E0\u62A5\u8868\u884C\u3002\n");
     return;
   }
-  const dimKeys = dimensions.split(",").map((x) => x.trim()).filter(Boolean);
-  const metricKeys = metrics.split(",").map((x) => x.trim()).filter(Boolean);
-  const keys = [...dimKeys, ...metricKeys, "roas"].filter((k, i, a) => a.indexOf(k) === i);
+  const dimKeys = splitTikTokCsv(dimensions);
+  const metricKeys = splitTikTokCsv(metrics);
+  const keys = [...dimKeys, ...metricKeys, "revenue", "revenueSource", "roas", "roasSource"].filter(
+    (k, i, a) => a.indexOf(k) === i
+  );
   printCliTable(
     result.items.map((r) => {
       const row = {};
@@ -134800,7 +134883,7 @@ TikTok \u5B98\u65B9\u62A5\u8868 ${dataLevel} ${startDate}~${endDate}\uFF08${id}\
   const sampleSpend = parseTikTokNumber(result.items[0]?.spend);
   if (sampleSpend !== void 0) {
     console.log(
-      "  spend \u5DF2\u8F6C\u6570\u5B57\uFF1BROAS = complete_payment / spend\uFF08spend=0 \u4E0D\u9664\uFF09\u3002\u52FF\u6DF7\u52A0\u4E0D\u540C DataLevel\u3002\n"
+      "  spend \u5DF2\u8F6C\u6570\u5B57\u3002ROAS \u4F18\u5148\u5B98\u65B9\u5217 complete_payment_roas / total_active_pay_roas\uFF0C\u5426\u5219\u7528 total_purchase_value/spend\uFF08\u89C1 roasSource\uFF09\u3002complete_payment \u662F\u7F51\u9875\u5B8C\u4ED8\u6B21\u6570\uFF0C\u4E0D\u662F\u91D1\u989D\u3002\u591A\u884C\u6C47\u603B\u89C1 totals\uFF08\u5148\u52A0\u603B\u518D\u9664\uFF0C\u52FF\u5E73\u5747\u5404\u7EC4 roas\uFF09\u3002\u52FF\u6DF7\u52A0\u4E0D\u540C DataLevel\u3002\n"
     );
   } else {
     console.log();
@@ -134953,7 +135036,7 @@ function registerTikTokAnalysisCommands(program2) {
     "TikTokAPI \u5B98\u65B9\u62A5\u8868\uFF08GET \u2026/query/report/Tiktok/search\uFF1B\u53EF\u542B\u4ECA\u5929/\u5C0F\u65F6\uFF1B\u4E0E `run` \u7684 TSO \u770B\u677F\u5468\u671F\u62A5\u8868\u4E0D\u540C\u3002ServiceType/DataLevel/Dimensions/Metrics/\u65E5\u671F/PageSize \u5FC5\u586B\uFF09"
   ).requiredOption(...ACCOUNT_OPTION2).requiredOption("--start <date>", "\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08\u6309\u5E7F\u544A\u4E3B timezone \u81EA\u7136\u65E5\uFF09").requiredOption("--end <date>", "\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").requiredOption("--data-level <level>", "AUCTION_CAMPAIGN / AUCTION_ADGROUP / AUCTION_AD").requiredOption("--dimensions <list>", "\u9017\u53F7\u5206\u9694\uFF0C\u5982 campaign_id \u6216 adgroup_id,stat_time_hour").requiredOption(
     "--metrics <list>",
-    "\u9017\u53F7\u5206\u9694\uFF0C\u82B1\u8D39\u987B\u7528 spend\uFF08\u4E0D\u8981 stat_cost\uFF09\uFF1B\u53EF\u542B conversion,cost_per_conversion,ctr,complete_payment"
+    "\u9017\u53F7\u5206\u9694\uFF0C\u82B1\u8D39\u987B\u7528 spend\uFF08\u4E0D\u8981 stat_cost\uFF09\u3002complete_payment \u662F\u7F51\u9875\u5B8C\u4ED8\u6B21\u6570\u3002\u542B\u5B8C\u4ED8/ROAS \u65F6\u81EA\u52A8\u9644\u5E26 total_purchase_value,complete_payment_roas,total_active_pay_roas"
   ).option("--service-type <type>", "AUCTION\uFF08\u9ED8\u8BA4\uFF09\u6216 RESERVATION", "AUCTION").option("--page-size <n>", "\u6BCF\u9875\u6761\u6570\uFF0C\u9ED8\u8BA4 200\uFF0C\u4E0A\u9650 1000", (v) => parseInt(v, 10)).option("-t, --token <token>", "Auth Token").option("--json-out <path>", JSON_OUT_OPTION_DESC2).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
     async (opts) => {
       await runTikTokOfficialReport(opts);

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.47-beta.1",
-  "publishedAt": 1787219174166
+  "version": "1.1.47-beta.2",
+  "publishedAt": 1787276448425
 }

package/dist/skill/references/analytics/account-analytics.md

@@ -351,6 +351,8 @@ siluzan-tso tiktok-analysis official-report -a <mediaCustomerId> --json-out ./sn
   --data-level AUCTION_CAMPAIGN --dimensions campaign_id --metrics spend
 ```
 
+**ROAS 口径**（对齐 [网页事件](https://ads.tiktok.com/help/article/page-events?lang=zh) / [应用内事件](https://ads.tiktok.com/help/article/in-app-events?lang=zh)）：`--metrics` 含完付或 ROAS 时 CLI 自动附带 `total_purchase_value,complete_payment_roas,total_active_pay_roas`。落盘行有 `revenue` / `revenueSource` / `roas` / `roasSource`，多行汇总在 `totals`（先加总 spend/revenue 再除）。`complete_payment` 是网页支付完成**次数**；金额用 `total_purchase_value`（总付费价值）。ROAS 优先官方列 `complete_payment_roas` / `total_active_pay_roas`。**禁止** `complete_payment/spend`，**禁止**把完付=0 判成「像素没回传」，**禁止**对各组 `roas` 取平均。不确定时先 `adgroup-entities` 看 `optimization_event`。
+
 ---
 
 ## Bing（BingV2）账户分析

package/dist/skill/references/operations/hosted-automation-tiktok.md

@@ -107,7 +107,7 @@ siluzan-tso tiktok-analysis official-report -a <mediaCustomerId> --json-out ./sn
   --data-level AUCTION_CAMPAIGN --dimensions campaign_id,stat_time_hour --metrics spend
 ```
 
-广告效果（CPA 用 `cost_per_conversion` 或 `spend/conversion`；ROAS 落盘里已自算 `complete_payment/spend`）：
+广告效果（CPA 用 `cost_per_conversion` 或 `spend/conversion`；**ROAS 用落盘 `roas` / `totals.roas`**）：
 
 ```bash
 siluzan-tso tiktok-analysis official-report -a <mediaCustomerId> --json-out ./snap-tt \
@@ -116,7 +116,7 @@ siluzan-tso tiktok-analysis official-report -a <mediaCustomerId> --json-out ./sn
   --metrics spend,conversion,cost_per_conversion,complete_payment,ctr
 ```
 
-非完付目标的 `complete_payment` 常为 0，ROAS 不能当通用门槛。出价在组，广告层只能关停（本批 CLI **不**关停）。
+`--metrics` 含完付/ROAS 时 CLI 自动附带 `total_purchase_value,complete_payment_roas,total_active_pay_roas`。口径对齐 Ads Manager：`complete_payment` 是网页支付完成**次数**（不是金额）；ROAS 优先官方列 `complete_payment_roas`（网页）/ `total_active_pay_roas`（App 付费），否则 `total_purchase_value/spend`。多行用 `totals`（先加总再除），**禁止**对各组 `roas` 取平均。**`complete_payment=0` 不是像素坏了**——App / `ACTIVE_PAY` 看 `total_purchase_value`。不确定优化目标时先 `adgroup-entities` 看 `optimization_event`。出价在组，广告层只能关停（本批 CLI **不**关停）。
 
 根因分解（含小时时起止仍须同一天，必须翻完页；CLI 已自动翻）：
 

package/dist/skill/scripts/install.ps1

@@ -9,7 +9,7 @@ $ErrorActionPreference = 'Stop'
 # -- Package info (injected at build time) ------------------------------------
 $PKG_NAME    = 'siluzan-tso-cli'
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-$PKG_VERSION = '1.1.47-beta.1'
+$PKG_VERSION = '1.1.47-beta.2'
 $CLI_BIN     = 'siluzan-tso'
 $SKILL_LABEL = 'Siluzan TSO'
 $INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'

package/dist/skill/scripts/install.sh

@@ -9,7 +9,7 @@ set -euo pipefail
 # -- Package info (injected at build time) ------------------------------------
 readonly PKG_NAME="siluzan-tso-cli"
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-readonly PKG_VERSION="1.1.47-beta.1"
+readonly PKG_VERSION="1.1.47-beta.2"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
 readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.1.47-beta.1",
+  "version": "1.1.47-beta.2",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",