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

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.3），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/index.js

@@ -105841,7 +105841,15 @@ function register5(program2) {
 // src/commands/list-accounts/_shared.ts
 init_dist();
 init_auth();
-function shouldExposeScopeActivatedSources() {
+var SCOPE_ACTIVATION_BYPASSED_HEADER = "x-scope-activation-bypassed";
+function isScopeActivationBypassed(headers) {
+  if (!headers) return false;
+  const raw = headers[SCOPE_ACTIVATION_BYPASSED_HEADER] ?? headers["X-Scope-Activation-Bypassed"];
+  const v = raw?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+function shouldExposeScopeActivatedSources(bypassed = false) {
+  if (bypassed) return false;
   return resolveCompanySourceType() === "Ctaiad";
 }
 var VALID_MEDIA_TYPES = [
@@ -105966,7 +105974,7 @@ async function fetchTikTokAccountByMediaCustomerId(config, mediaCustomerId, verb
   const match = items2.find((it) => String(it.ma?.mediaCustomerId ?? "") === id);
   return match ?? null;
 }
-function stripListAccountsEnrichmentFields(item) {
+function stripListAccountsEnrichmentFields(item, exposeScopeActivatedSources = shouldExposeScopeActivatedSources()) {
   delete item.ma.remainingAccountBudget;
   delete item.ma.platformStatus;
   delete item.ma.aritScore;
@@ -105982,7 +105990,7 @@ function stripListAccountsEnrichmentFields(item) {
   ]) {
     delete maExt[key];
   }
-  if (!shouldExposeScopeActivatedSources()) {
+  if (!exposeScopeActivatedSources) {
     delete item.ma.scopeActivatedSources;
     delete maExt["scopeActivatedSources"];
   }
@@ -106087,8 +106095,8 @@ var COL_GOOGLE_BASE = [
   { key: "shared", header: "\u5206\u4EAB" }
 ];
 var COL_GOOGLE_PACKAGE = { key: "packageStatus", header: "\u5957\u9910\u6FC0\u6D3B" };
-function googleTableColumns() {
-  if (!shouldExposeScopeActivatedSources()) return COL_GOOGLE_BASE;
+function googleTableColumns(exposePackage = shouldExposeScopeActivatedSources()) {
+  if (!exposePackage) return COL_GOOGLE_BASE;
   const authIdx = COL_GOOGLE_BASE.findIndex((c) => c.key === "authStatus");
   const cols = [...COL_GOOGLE_BASE];
   cols.splice(authIdx + 1, 0, COL_GOOGLE_PACKAGE);
@@ -106262,8 +106270,7 @@ function printTikTokTable(items2, tableOpts) {
   });
   printCliTable(rows, COL_TIKTOK, tableOpts);
 }
-function printGoogleTable(items2, tableOpts) {
-  const exposePackage = shouldExposeScopeActivatedSources();
+function printGoogleTable(items2, tableOpts, exposePackage = shouldExposeScopeActivatedSources()) {
   const rows = items2.map((item) => {
     const ma = item.ma;
     const platformStatus = ma.platformStatus ?? "-";
@@ -106289,7 +106296,7 @@ function printGoogleTable(items2, tableOpts) {
     }
     return row;
   });
-  printCliTable(rows, googleTableColumns(), tableOpts);
+  printCliTable(rows, googleTableColumns(exposePackage), tableOpts);
 }
 var COL_DEFAULT_WITH_MEDIA = [
   { key: "mediaType", header: "\u5A92\u4F53\u7C7B\u578B" },
@@ -106364,6 +106371,7 @@ async function runListAccounts(opts) {
   const platformCfg = opts.media ? PLATFORM_CONFIG[opts.media] : null;
   let items2;
   let total;
+  let scopeActivationBypassed = false;
   if (platformCfg) {
     const params = new URLSearchParams();
     for (const [k, v] of Object.entries(platformCfg.fixedParams)) {
@@ -106380,6 +106388,7 @@ async function runListAccounts(opts) {
       try {
         const res = await apiFetchWithHeaders2(url, config, {}, opts.verbose);
         items2 = res.data ?? [];
+        scopeActivationBypassed = isScopeActivationBypassed(res.headers);
         const hit = res.headers["s-total-hits"];
         if (hit !== void 0) total = parseInt(hit, 10) || void 0;
       } catch (err) {
@@ -106389,22 +106398,22 @@ async function runListAccounts(opts) {
         process.exit(1);
       }
     } else {
-      let res;
       try {
-        res = await apiFetch2(url, config, {}, opts.verbose);
+        const res = await apiFetchWithHeaders2(url, config, {}, opts.verbose);
+        items2 = Array.isArray(res.data?.mas) ? res.data.mas : [];
+        total = typeof res.data?.total === "number" ? res.data.total : void 0;
+        scopeActivationBypassed = isScopeActivationBypassed(res.headers);
+        if (opts.media === "TikTok") {
+          mergeTikTokAdList(items2, res.data?.adList);
+        } else if (opts.media === "MetaAd") {
+          mergeMetaFacebookAdList(items2, res.data?.adList);
+        }
       } catch (err) {
         console.error(`
 \u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
       }
-      items2 = Array.isArray(res?.mas) ? res.mas : [];
-      total = typeof res?.total === "number" ? res.total : void 0;
-      if (opts.media === "TikTok") {
-        mergeTikTokAdList(items2, res.adList);
-      } else if (opts.media === "MetaAd") {
-        mergeMetaFacebookAdList(items2, res.adList);
-      }
     }
   } else {
     const params = new URLSearchParams();
@@ -106416,6 +106425,7 @@ async function runListAccounts(opts) {
     try {
       const res = await apiFetchWithHeaders2(url, config, {}, opts.verbose);
       items2 = res.data ?? [];
+      scopeActivationBypassed = isScopeActivationBypassed(res.headers);
       const hit = res.headers["s-total-hits"];
       if (hit !== void 0) total = parseInt(hit, 10) || void 0;
     } catch (err) {
@@ -106425,9 +106435,10 @@ async function runListAccounts(opts) {
       process.exit(1);
     }
   }
+  const exposeScopeActivated = shouldExposeScopeActivatedSources(scopeActivationBypassed);
   if (items2.length > 0) {
     for (const item of items2) {
-      stripListAccountsEnrichmentFields(item);
+      stripListAccountsEnrichmentFields(item, exposeScopeActivated);
     }
   }
   const oauthFailWarning = (() => {
@@ -106469,7 +106480,7 @@ async function runListAccounts(opts) {
   const isKwai = opts.media === "Kwai";
   const tableBorderOpts = opts.unicode ? { plain: false } : void 0;
   if (isGoogle) {
-    printGoogleTable(items2, tableBorderOpts);
+    printGoogleTable(items2, tableBorderOpts, exposeScopeActivated);
   } else if (isYandex) {
     printYandexTable(items2, tableBorderOpts);
   } else if (isTikTok) {
@@ -134230,6 +134241,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 +134330,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 +134538,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 +134550,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 +134560,8 @@ async function fetchOfficialReport(config, opts) {
   );
   return {
     items: raw.items.map(flattenTikTokReportRow),
-    totalNumber: raw.totalNumber
+    totalNumber: raw.totalNumber,
+    metrics
   };
 }
 
@@ -134725,7 +134815,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 +134840,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 +134849,7 @@ async function runTikTokOfficialReport(opts) {
     metrics,
     startDate,
     endDate,
+    totals,
     ...wrapListJson({
       page: 1,
       pageSize,
@@ -134783,9 +134875,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 +134894,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 +135047,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.3",
+  "publishedAt": 1787282369500
 }

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.3'
 $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.3"
 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.3",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",