siluzan-tso-cli 1.1.37-beta.14 → 1.1.37-beta.16

package/README.md

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

package/dist/index.js

@@ -5023,6 +5023,33 @@ var init_list_fetch = __esm({
   }
 });
 
+// src/commands/accounts-digest/filters.ts
+function keepDigestRow(row, opts) {
+  const { maxCpa, zeroConversions } = opts;
+  if (maxCpa == null && !zeroConversions) return true;
+  const spend = row.spend ?? 0;
+  const conv = row.conversions;
+  const cpa = row.cpa;
+  if (zeroConversions) {
+    if (spend > 0 && (conv == null || conv === 0)) return true;
+    if (maxCpa == null) return false;
+  }
+  if (maxCpa != null) {
+    if (cpa != null && cpa > maxCpa) return true;
+    if (spend > 0 && conv === 0) return true;
+    return false;
+  }
+  return false;
+}
+function countNullConversions(rows) {
+  return rows.reduce((n, r) => n + (r.conversions == null ? 1 : 0), 0);
+}
+var init_filters = __esm({
+  "src/commands/accounts-digest/filters.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/accounts-digest/run.ts
 function round2(n) {
   if (n == null) return null;
@@ -5136,7 +5163,7 @@ async function runAccountsDigest(opts) {
     const ctr = impressions && impressions > 0 && clicks != null ? clicks / impressions : null;
     const cpc = clicks && clicks > 0 && spend != null ? spend / clicks : null;
     const cpa = conversions && conversions > 0 && spend != null ? spend / conversions : null;
-    rows.push({
+    const row = {
       mediaCustomerId: id,
       name: ma.mediaCustomerName ?? bal?.name ?? ov?.mediaCustomerName ?? null,
       advertiserName: item.mag?.advertiserName ?? null,
@@ -5151,7 +5178,14 @@ async function runAccountsDigest(opts) {
       cpc: round2(cpc),
       cpa: round2(cpa),
       invalidOAuthToken: !!ma.invalidOAuthToken
-    });
+    };
+    if (!keepDigestRow(row, {
+      maxCpa: opts.maxCpa,
+      zeroConversions: opts.zeroConversions
+    })) {
+      continue;
+    }
+    rows.push(row);
   }
   rows.sort((a, b) => (b.spend ?? 0) - (a.spend ?? 0));
   const totals = rows.reduce(
@@ -5175,6 +5209,12 @@ async function runAccountsDigest(opts) {
     /** 取数策略：list = 全量翻清单后过滤，subset = 跳过翻页直接对 -a 指定的 ID 拉数据 */
     source: scannedFromList ? "list" : "subset",
     returned: rows.length,
+    nullConversionCount: countNullConversions(rows),
+    filters: {
+      minSpend,
+      maxCpa: opts.maxCpa ?? null,
+      zeroConversions: !!opts.zeroConversions
+    },
     batchChunkSize: validIds.length > 0 ? batchChunkSize : null,
     totals: {
       spend: +totals.spend.toFixed(2),
@@ -5234,13 +5274,20 @@ ${media} \u8D26\u6237\u6295\u653E\u753B\u50CF\uFF1A\u8FD4\u56DE ${rows.length} \
     balance: formatMoneyDisplay(r.balance, r.currencyCode)
   }));
   printCliTable(tableRows, cols);
+  if (meta.nullConversionCount > 0) {
+    process.stderr.write(
+      `\u26A0 \u8F6C\u5316\u5B57\u6BB5\u4E3A\u7A7A ${meta.nullConversionCount} \u6237\uFF1A\u52FF\u7528\u6570\u503C\u6BD4\u8F83 null\uFF1B\u8FC7\u6EE4\u89C1 --max-cpa / --zero-conversions
+`
+    );
+  }
   console.log(
     `
-  \u6C47\u603B\uFF1A\u6D88\u8017 ${meta.totals.spend}\uFF0C\u70B9\u51FB ${meta.totals.clicks}\uFF0C\u5C55\u793A ${meta.totals.impressions}\uFF0C\u8F6C\u5316 ${meta.totals.conversions}
+  \u6C47\u603B\uFF1A\u6D88\u8017 ${meta.totals.spend}\uFF0C\u70B9\u51FB ${meta.totals.clicks}\uFF0C\u5C55\u793A ${meta.totals.impressions}\uFF0C\u8F6C\u5316 ${meta.totals.conversions}\uFF08\u8F6C\u5316\u672A\u8FD4\u56DE ${meta.nullConversionCount} \u6237\uFF09
   \u63D0\u793A\uFF1A
     - \u91D1\u989D\u4F7F\u7528\u5404\u8D26\u6237\u4E3B\u5E01\u79CD\uFF1B\u8DE8\u5E01\u79CD\u8D26\u6237\u52A0 --json-out \u81EA\u884C\u6309 currencyCode \u805A\u5408
     - \u6307\u5B9A\u8D26\u6237\u5B50\u96C6\uFF1A--accounts <id1,id2,...>\uFF08\u4E0E list-accounts \u7684 mediaCustomerId \u4E00\u81F4\uFF09
-    - \u8FC7\u6EE4\u4F4E\u6D88\u8017\uFF1A--min-spend 10\uFF08\u53EA\u4FDD\u7559\u533A\u95F4\u5185\u6D88\u8017 > 10 \u7684\u8D26\u6237\uFF09
+    - \u8FC7\u6EE4\u4F4E\u6D88\u8017\uFF1A--min-spend 10\uFF1B\u9AD8 CPA\uFF1A--max-cpa 500\uFF1B\u96F6\u8F6C\u5316\uFF1A--zero-conversions
+    - \u65E0 --period\uFF1B\u533A\u95F4\u7528 --start/--end\uFF08\u6216 --start-date/--end-date\uFF09
 `
   );
 }
@@ -5255,23 +5302,32 @@ var init_run = __esm({
     init_media_account_batch();
     init_media_account_lookup();
     init_list_fetch();
+    init_filters();
   }
 });
 
 // src/commands/accounts-digest/_register.ts
 function register10(program2) {
   program2.command("accounts-digest").description(
-    "\u591A\u8D26\u6237\u6295\u653E\u753B\u50CF\uFF1A\u4E00\u6761\u547D\u4EE4\u62FF\u9F50\u6D88\u8017/\u70B9\u51FB/\u8F6C\u5316/\u4F59\u989D/\u6D3E\u751F\u6307\u6807\uFF08CTR/CPC/CPA\uFF09\uFF0C\u66FF\u4EE3 AI \u9010\u8D26\u6237 `list-accounts` + `stats` \u7684\u7F16\u6392\u3002\u5178\u578B\u573A\u666F\uFF1A\u300C\u8FD9 10 \u4E2A\u8D26\u6237\uFF08\u6216\u67D0\u5A92\u4F53\u5168\u90E8\u8D26\u6237\uFF09\u5E2E\u6211\u6574\u7406\u4E00\u4E0B\u300D\u3002"
+    "\u591A\u8D26\u6237\u6295\u653E\u753B\u50CF\uFF1A\u4E00\u6761\u547D\u4EE4\u62FF\u9F50\u6D88\u8017/\u70B9\u51FB/\u8F6C\u5316/\u4F59\u989D/\u6D3E\u751F\u6307\u6807\uFF08CTR/CPC/CPA\uFF09\uFF0C\u66FF\u4EE3 AI \u9010\u8D26\u6237 `list-accounts` + `stats` \u7684\u7F16\u6392\u3002\u5178\u578B\u573A\u666F\uFF1A\u300C\u8FD9 10 \u4E2A\u8D26\u6237\uFF08\u6216\u67D0\u5A92\u4F53\u5168\u90E8\u8D26\u6237\uFF09\u5E2E\u6211\u6574\u7406\u4E00\u4E0B\u300D\u3001\u8F6C\u5316\u6210\u672C/CPA/\u96F6\u8F6C\u5316\u5DE1\u68C0\u3002\u65E0 --period\uFF1B\u533A\u95F4\u7528 --start/--end\uFF08\u6216 --start-date/--end-date\uFF09\u3002"
   ).requiredOption(
     "-m, --media <type>",
     "\u5A92\u4F53\u7C7B\u578B\uFF1AGoogle | TikTok | Yandex | MetaAd | BingV2 | Kwai"
   ).option(
     "-a, --accounts <ids>",
     "\u6307\u5B9A\u8D26\u6237 mediaCustomerId\uFF0C\u9017\u53F7\u5206\u9694\uFF1B\u7559\u7A7A\u5219\u626B\u63CF\u8BE5\u5A92\u4F53\u4E0B\u5168\u90E8\u8D26\u6237"
-  ).option("--start <date>", "\u7EDF\u8BA1\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08SKILL \u8981\u6C42 AI \u5148\u4E0E\u7528\u6237\u786E\u8BA4\uFF09").option("--end <date>", "\u7EDF\u8BA1\u7ED3\u675F\u65E5\u671F YYYY-MM-DD\uFF08SKILL \u8981\u6C42 AI \u5148\u4E0E\u7528\u6237\u786E\u8BA4\uFF09").option(
+  ).option("--start <date>", "\u7EDF\u8BA1\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08SKILL \u8981\u6C42 AI \u5148\u4E0E\u7528\u6237\u786E\u8BA4\uFF09").option("--end <date>", "\u7EDF\u8BA1\u7ED3\u675F\u65E5\u671F YYYY-MM-DD\uFF08SKILL \u8981\u6C42 AI \u5148\u4E0E\u7528\u6237\u786E\u8BA4\uFF09").option("--start-date <date>", "\u540C --start\uFF08\u6587\u6863/Playbook \u517C\u5BB9\u522B\u540D\uFF09").option("--end-date <date>", "\u540C --end\uFF08\u6587\u6863/Playbook \u517C\u5BB9\u522B\u540D\uFF09").option(
     "--min-spend <n>",
     "\u8FC7\u6EE4\uFF1A\u533A\u95F4\u5185\u6D88\u8017 \u2264 \u6B64\u503C\u7684\u8D26\u6237\u4E0D\u8FD4\u56DE\uFF08\u9ED8\u8BA4 0\uFF09",
     (v) => parseFloat(v)
+  ).option(
+    "--max-cpa <n>",
+    "\u8FC7\u6EE4\uFF1A\u4FDD\u7559 CPA > \u6B64\u503C\u7684\u8D26\u6237\uFF1B\u6709\u6D88\u8017\u4E14\u8F6C\u5316\u4E3A 0 \u89C6\u4E3A\u547D\u4E2D\uFF08CPA \u65E0\u7A77\uFF09",
+    (v) => parseFloat(v)
+  ).option(
+    "--zero-conversions",
+    "\u8FC7\u6EE4\uFF1A\u4FDD\u7559\u533A\u95F4\u6D88\u8017 > 0 \u4E14\u8F6C\u5316 = 0 \u6216\u8F6C\u5316\u672A\u8FD4\u56DE\u7684\u8D26\u6237",
+    false
   ).option("--page-size <n>", "\u8D26\u6237\u6E05\u5355\u5206\u9875\u5927\u5C0F\uFF08\u9ED8\u8BA4 200\uFF0C\u4E0A\u9650 500\uFF09", (v) => parseInt(v, 10)).option("--max-pages <n>", "\u6700\u591A\u626B\u63CF\u9875\u6570\uFF08\u9ED8\u8BA4 20\uFF0C\u4E0A\u9650 200\uFF09", (v) => parseInt(v, 10)).option("-t, --token <token>", "Token\uFF08\u53EF\u9009\uFF1B\u4F18\u5148\u4E8E ~/.siluzan/config.json\uFF09").option(
     "--json-out <path>",
     "\u843D\u76D8\uFF08\u76EE\u5F55\u6216 *.json \u6587\u4EF6\u8DEF\u5F84\uFF09\u5E76\u66F4\u65B0 cli-manifest[-<\u67E5\u8BE2id>].json\uFF1B\u76EE\u5F55\u6A21\u5F0F\u6587\u4EF6\u540D\u4E3A `<section>[-<\u67E5\u8BE2id>].json`\uFF1Bstdout \u4E00\u884C\u6458\u8981 JSON\uFF0C\u542B outlineFile\uFF08TS \u5F0F\u7C7B\u578B\u5728 `*.outline.txt`\uFF09",
@@ -5282,9 +5338,11 @@ function register10(program2) {
         token: opts.token,
         media: opts.media,
         accounts: opts.accounts,
-        startDate: opts.start,
-        endDate: opts.end,
+        startDate: opts.start ?? opts.startDate,
+        endDate: opts.end ?? opts.endDate,
         minSpend: opts.minSpend,
+        maxCpa: opts.maxCpa,
+        zeroConversions: opts.zeroConversions,
         pageSize: opts.pageSize,
         maxPages: opts.maxPages,
         jsonOut: opts.jsonOut,
@@ -5307,6 +5365,7 @@ var init_accounts_digest = __esm({
     "use strict";
     init_run();
     init_list_fetch();
+    init_filters();
     init_register();
   }
 });
@@ -103436,8 +103495,8 @@ async function cmdRun(opts) {
   const result = await executeBatchRun({
     jsonOut: opts.jsonOut,
     runId: opts.runId,
-    start: opts.start,
-    end: opts.end,
+    start: opts.start ?? opts.startDate,
+    end: opts.end ?? opts.endDate,
     sections,
     explicitAccountIds: explicitIds.length > 0 ? explicitIds : void 0,
     accountConcurrency,
@@ -103612,7 +103671,7 @@ function registerGoogleAnalysisBatchCommands(program2) {
   grp.command("run").description("\u4E00\u6B21\u6027\u6279\u8DD1\uFF1A\u81EA\u52A8\u62C9\u8D26\u6237\u6E05\u5355 + \u6309\u8D26\u6237\xD7\u7EF4\u5EA6\u5E76\u53D1\u6267\u884C + \u843D\u76D8 manifest/progress").requiredOption("--json-out <baseDir>", "\u4EA7\u7269\u6839\u76EE\u5F55\uFF08\u6BCF\u4E2A runId \u4E00\u4E2A\u5B50\u76EE\u5F55\uFF09").option("--run-id <id>", "\u53EF\u9009\u81EA\u5B9A\u4E49 runId\uFF08\u7559\u7A7A\u81EA\u52A8\u751F\u6210 run-YYYYMMDD-HHmmss-<rand4>\uFF09").option(
     "-a, --accounts <ids>",
     "\u663E\u5F0F\u6307\u5B9A mediaCustomerId \u5217\u8868\uFF08\u9017\u53F7\u5206\u9694\uFF09\uFF1B\u4F20\u5165\u5219\u8DF3\u8FC7\u8D26\u6237\u6E05\u5355\u62C9\u53D6\u4E0E --min-spend \u8FC7\u6EE4"
-  ).option("--start <date>", "\u7EDF\u8BA1\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08\u5F3A\u70C8\u5EFA\u8BAE\u663E\u5F0F\u6307\u5B9A\uFF09").option("--end <date>", "\u7EDF\u8BA1\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option("--sections <list>", `\u8981\u62C9\u53D6\u7684\u7EF4\u5EA6\uFF08\u9017\u53F7\u5206\u9694\uFF09\uFF0C\u9ED8\u8BA4 ${DEFAULT_SECTIONS.join(",")}`).option(
+  ).option("--start <date>", "\u7EDF\u8BA1\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08\u5F3A\u70C8\u5EFA\u8BAE\u663E\u5F0F\u6307\u5B9A\uFF09").option("--end <date>", "\u7EDF\u8BA1\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option("--start-date <date>", "\u540C --start\uFF08\u6587\u6863/Playbook \u517C\u5BB9\u522B\u540D\uFF09").option("--end-date <date>", "\u540C --end\uFF08\u6587\u6863/Playbook \u517C\u5BB9\u522B\u540D\uFF09").option("--sections <list>", `\u8981\u62C9\u53D6\u7684\u7EF4\u5EA6\uFF08\u9017\u53F7\u5206\u9694\uFF09\uFF0C\u9ED8\u8BA4 ${DEFAULT_SECTIONS.join(",")}`).option(
     "--account-concurrency <n>",
     `\u8D26\u6237\u7EA7\u5E76\u53D1\uFF0C\u9ED8\u8BA4 ${DEFAULT_ACCOUNT_CONCURRENCY}\uFF08\u4E0A\u9650 16\uFF09`,
     (v) => parseInt(v, 10)
@@ -103681,6 +103740,13 @@ var init_google_analysis_batch = __esm({
 import * as path30 from "path";
 import { performance as performance4 } from "perf_hooks";
 import { Command } from "commander";
+function normalizeAnalysisDateOpts(opts) {
+  return {
+    ...opts,
+    start: opts.start ?? opts.startDate,
+    end: opts.end ?? opts.endDate
+  };
+}
 function resolveSectionList(sections, exclude) {
   const allNames = SECTIONS.map((s) => s.name);
   const splitClean = (s) => (s ?? "").split(",").map((x) => x.trim()).filter(Boolean);
@@ -103900,7 +103966,7 @@ function registerRunCommand() {
   ).option("-t, --token <token>", "Auth Token").option(
     "--start <date>",
     "\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08range \u7C7B\u7EF4\u5EA6\u751F\u6548\uFF1B\u7701\u7565=\u8FD1 7 \u5929\u622A\u81F3\u6628\u5929\uFF1B\u4E0E --end \u540C\u4F20\u6216\u540C\u7701\uFF09"
-  ).option("--end <date>", "\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option(
+  ).option("--end <date>", "\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option("--start-date <date>", "\u540C --start\uFF08\u6587\u6863/Playbook \u517C\u5BB9\u522B\u540D\uFF09").option("--end-date <date>", "\u540C --end\uFF08\u6587\u6863/Playbook \u517C\u5BB9\u522B\u540D\uFF09").option(
     "--sections <list>",
     "\u4EC5\u6267\u884C\u6307\u5B9A\u7EF4\u5EA6\uFF08\u9017\u53F7\u5206\u9694\uFF09\uFF0C\u5982 overview,keywords,ads\uFF1B\u7701\u7565=\u5168\u90E8 25 \u4E2A"
   ).option(
@@ -103971,20 +104037,21 @@ ${fixHint}
       );
       process.exit(1);
     }
-    const ids = parseAccountIdsForAnalysis(opts.account ?? "");
+    const normalized = normalizeAnalysisDateOpts(opts);
+    const ids = parseAccountIdsForAnalysis(normalized.account ?? "");
     if (ids.length === 0) {
       console.error("\n\u274C --account \u4E0D\u80FD\u4E3A\u7A7A\u3002\n");
       process.exit(1);
     }
     if (ids.length >= 2) {
-      if (!opts.jsonOut?.trim()) {
+      if (!normalized.jsonOut?.trim()) {
         console.error("\n\u274C \u591A\u8D26\u6237\u6A21\u5F0F\u5FC5\u987B\u4F20 --json-out <\u76EE\u5F55>\uFF08\u6309 runId \u5B50\u76EE\u5F55\u7EC4\u7EC7\u4EA7\u7269\uFF09\u3002\n");
         process.exit(1);
       }
-      await runMultiAccountViaBatch(ids, opts);
+      await runMultiAccountViaBatch(ids, normalized);
       return;
     }
-    await runAllSections({ ...opts, account: ids[0] });
+    await runAllSections({ ...normalized, account: ids[0] });
   });
 }
 function registerGoogleAnalysisCommands(program2) {
@@ -106606,6 +106673,37 @@ async function fetchAllAccountPages(media, pageSize, maxPages, config, verbose)
   return { items: allItems, total };
 }
 
+// src/commands/balance-scan/data-health.ts
+function assessBalanceScanDataHealth(input) {
+  const { scannedAccounts, validAccounts, balances } = input;
+  if (scannedAccounts <= 0) {
+    return {
+      code: "no_accounts",
+      message: "\u672A\u626B\u5230\u4EFB\u4F55\u8D26\u6237\uFF1A\u8BF7\u786E\u8BA4 -m \u5A92\u4F53\u7C7B\u578B\uFF0C\u6216\u7528 -a \u6307\u5B9A mediaCustomerId\uFF1B\u5168\u91CF\u6A21\u5F0F\u68C0\u67E5\u767B\u5F55\u4E0E list-accounts \u662F\u5426\u6709\u6570\u636E"
+    };
+  }
+  if (validAccounts <= 0) {
+    return {
+      code: "all_oauth_invalid",
+      message: "\u8D26\u6237\u5747\u56E0 OAuth \u5931\u6548\u88AB\u8DF3\u8FC7\uFF1A\u8BF7\u5728\u4E1D\u8DEF\u8D5E\u91CD\u65B0\u6388\u6743\u540E\u518D balance-scan\uFF1B\u6216\u7528 -a \u6307\u5B9A\u4ECD\u6709\u6548\u7684\u8D26\u6237"
+    };
+  }
+  if (balances.length === 0) {
+    return {
+      code: "all_balances_null",
+      message: "\u672A\u62C9\u5230\u4EFB\u4F55\u4F59\u989D\u884C\uFF1A\u8BF7\u52A0 --verbose \u67E5\u770B\u63A5\u53E3\u9519\u8BEF\uFF1B\u53EF\u8BD5 --refresh-dp \u6216 siluzan-tso login \u540E\u91CD\u8BD5"
+    };
+  }
+  const allNull = balances.every((b) => b == null);
+  if (allNull) {
+    return {
+      code: "all_balances_null",
+      message: "\u5168\u90E8\u8D26\u6237\u4F59\u989D\u4E3A null\uFF08\u63A5\u53E3\u672A\u8FD4\u56DE\u53EF\u7528\u4F59\u989D\uFF09\uFF1A\u65E0\u6CD5\u8BA1\u7B97\u7EED\u822A\u3002\u8BF7\u68C0\u67E5\u5A92\u4F53\u6388\u6743/\u8D26\u6237\u72B6\u6001\uFF0C\u52A0 --verbose \u770B\u539F\u59CB\u54CD\u5E94\uFF0C\u6216 --refresh-dp / \u91CD\u65B0 login \u540E\u91CD\u8BD5"
+    };
+  }
+  return null;
+}
+
 // src/commands/balance-scan/run.ts
 async function runBalanceScan(opts) {
   let config = loadConfig(opts.token);
@@ -106750,6 +106848,12 @@ async function runBalanceScan(opts) {
     const bd = b.remainingDays ?? Number.POSITIVE_INFINITY;
     return ad - bd;
   });
+  const balancesForHealth = validIds.map((id) => balanceMap.get(id)?.remainingAccountBudget);
+  const dataIssue = assessBalanceScanDataHealth({
+    scannedAccounts: allItems.length,
+    validAccounts: validIds.length,
+    balances: balancesForHealth
+  });
   const meta = {
     media,
     source: isSubset ? "subset" : "list",
@@ -106757,6 +106861,9 @@ async function runBalanceScan(opts) {
     validAccounts: validIds.length,
     skippedInvalidOAuth: allItems.length - validIds.length,
     hitCount: evaluated.length,
+    nullBalanceCount: balancesForHealth.filter((b) => b == null).length,
+    dataIssue: dataIssue?.code ?? null,
+    dataIssueMessage: dataIssue?.message ?? null,
     thresholds: {
       days: thresholdDays,
       minBalance,
@@ -106769,14 +106876,24 @@ async function runBalanceScan(opts) {
     totalReported: total ?? null,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  const scanPayload = { ok: true, data: { items: evaluated }, meta };
-  if (await emitCliJsonOrSnapshot(opts, {
+  const scanPayload = { ok: !dataIssue, data: { items: evaluated }, meta };
+  const wroteJson = await emitCliJsonOrSnapshot(opts, {
     section: `balance-scan-${media}`,
     commandLabel: "balance-scan",
     commandHint: media,
     payload: scanPayload,
     idSuffix: media
-  })) {
+  });
+  if (dataIssue) {
+    console.error(`
+\u274C balance-scan \u6570\u636E\u5F02\u5E38\uFF08${dataIssue.code}\uFF09\uFF1A${dataIssue.message}
+`);
+    if (wroteJson) {
+      console.error("   \u5DF2\u5199\u5165 --json-out\uFF08ok=false\uFF0C\u89C1 meta.dataIssue\uFF09\uFF1B\u8BF7\u4FEE\u590D\u540E\u91CD\u8DD1\uFF0C\u52FF\u5F53\u4F5C\u300C\u65E0\u9884\u8B66\u547D\u4E2D\u300D\u3002\n");
+    }
+    process.exit(2);
+  }
+  if (wroteJson) {
     return;
   }
   if (isSubset) {
@@ -106794,7 +106911,7 @@ ${media} \u8D26\u6237\u4F59\u989D\u626B\u63CF\u5B8C\u6210\uFF1A\u5171\u626B\u63C
     );
   }
   if (evaluated.length === 0) {
-    console.log("  \u2705 \u65E0\u547D\u4E2D\u8D26\u6237\u3002\n");
+    console.log("  \u2705 \u65E0\u547D\u4E2D\u8D26\u6237\uFF08\u9608\u503C\u5185\u65E0\u9884\u8B66\uFF1B\u6570\u636E\u5DF2\u6B63\u5E38\u8FD4\u56DE\uFF09\u3002\n");
     return;
   }
   const cols = [
@@ -116225,6 +116342,7 @@ function runPmaxCreateValidation(cfg) {
 }
 
 // src/commands/ad/pmax-image-validate.ts
+import { existsSync as existsSync3 } from "fs";
 import { isAbsolute as isAbsolute2, resolve as resolve6, dirname as dirname7 } from "path";
 
 // src/commands/ad/pmax-image-dims.ts
@@ -116384,6 +116502,12 @@ async function runPmaxImageValidation(configFile, cfg) {
       fileSizeKB = Math.ceil(b64.trim().length * 0.75 / 1024);
     } else if (pathRaw?.trim()) {
       const abs = resolveImagePath(configFile, pathRaw.trim());
+      if (!existsSync3(abs)) {
+        errors.push(
+          `${spec.label}\uFF1A\u56FE\u7247\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${abs}\uFF08\u76F8\u5BF9\u8DEF\u5F84\u76F8\u5BF9 --config-file \u6240\u5728\u76EE\u5F55\u89E3\u6790\uFF1B\u8BF7\u6539\u7528\u7EDD\u5BF9\u8DEF\u5F84\u6216\u628A\u56FE\u653E\u5230\u914D\u7F6E\u65C1\uFF09`
+        );
+        continue;
+      }
       const result = readImageDimsFromPath(abs);
       if (result) {
         dims = result;
@@ -116407,7 +116531,7 @@ async function runPmaxImageValidation(configFile, cfg) {
 // src/commands/ad/pmax-image-resolve.ts
 init_auth();
 import { basename as basename4, dirname as dirname8, isAbsolute as isAbsolute3, resolve as resolve7 } from "path";
-import { readFileSync as readFileSync10 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync10 } from "fs";
 
 // src/commands/ad/pmax-urls.ts
 function pmaxChannelTypesUrl(googleApiUrl) {
@@ -116570,7 +116694,19 @@ async function uploadPmaxImageFileBase64(config, googleApiUrl, accountId, absIma
 async function uploadPmaxImageFile(config, googleApiUrl, accountId, absImagePath, name2, verbose) {
   const fileName = basename4(absImagePath);
   const assetName = (name2 ?? fileName).trim() || fileName;
-  const fileBuffer = readFileSync10(absImagePath);
+  if (!existsSync4(absImagePath)) {
+    throw new Error(
+      `\u56FE\u7247\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${absImagePath}\uFF08\u76F8\u5BF9\u8DEF\u5F84\u76F8\u5BF9 --config-file \u6240\u5728\u76EE\u5F55\uFF1B\u8BF7\u6838\u5BF9 imagePaths \u6216\u6539\u7528\u7EDD\u5BF9\u8DEF\u5F84\uFF09`
+    );
+  }
+  let fileBuffer;
+  try {
+    fileBuffer = readFileSync10(absImagePath);
+  } catch (err) {
+    throw new Error(
+      `\u8BFB\u53D6\u56FE\u7247\u5931\u8D25\uFF08${absImagePath}\uFF09\uFF1A${err instanceof Error ? err.message : String(err)}`
+    );
+  }
   if (fileBuffer.length <= MAX_BASE64_UPLOAD_BYTES) {
     return uploadPmaxImageFileBase64(
       config,
@@ -117345,7 +117481,7 @@ function buildPmaxCreateUrl(googleApiUrl, accountId) {
 }
 
 // src/commands/ad/pmax-video-upload.ts
-import { existsSync as existsSync3, readFileSync as readFileSync13 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync13 } from "fs";
 import { basename as basename5, dirname as dirname10, isAbsolute as isAbsolute5, resolve as resolve9 } from "path";
 
 // src/commands/ad/pmax-shared.ts
@@ -117552,7 +117688,7 @@ function runPmaxVideoValidation(configFile, cfg) {
     );
   }
   const abs = resolveVideoPath(configFile, videoPath);
-  if (!existsSync3(abs)) {
+  if (!existsSync5(abs)) {
     errors.push(`videoPath \u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${abs}`);
     return { errors, warnings };
   }
@@ -117674,7 +117810,7 @@ function validatePmaxVideoPathQuick(absPath) {
   if (!VIDEO_UPLOAD_SUFFIX.test(absPath)) {
     return `videoPath \u6269\u5C55\u540D\u4E0D\u53D7\u652F\u6301\uFF0C\u8BF7\u4F7F\u7528 .mp4 / .mov / .webm / .avi / .mpeg / .mpg`;
   }
-  if (!existsSync3(absPath)) {
+  if (!existsSync5(absPath)) {
     return `\u89C6\u9891\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${absPath}`;
   }
   try {
@@ -117744,6 +117880,45 @@ async function linkPmaxVideoAfterCreate(opts) {
   }
 }
 
+// src/commands/ad/pmax-create-http-error.ts
+function classifyPmaxCreateHttpError(raw) {
+  const msg = raw.trim() || "\u672A\u77E5\u9519\u8BEF";
+  const lower = msg.toLowerCase();
+  const hints = [];
+  if (/^HTTP 400\b/i.test(msg) || lower.includes("bad request")) {
+    if (/budget|日预算|budgetamount|micros/i.test(msg)) {
+      hints.push("\u68C0\u67E5 campaign.budget / \u65E5\u9884\u7B97\u91D1\u989D\u4E0E\u5E01\u79CD\u662F\u5426\u5408\u7406");
+    }
+    if (/bidding|target.?cpa|target.?roas|maximize|出价/i.test(msg)) {
+      hints.push("\u68C0\u67E5 BiddingStrategyTypeV2 \u4E0E\u914D\u5957\u91D1\u989D\u5B57\u6BB5\uFF08tCPA/tROAS\uFF09\u662F\u5426\u9F50\u5168\u4E14\u517C\u5BB9");
+    }
+    if (/image|asset|marketing|logo|图片/i.test(msg)) {
+      hints.push("\u68C0\u67E5\u6A2A\u56FE/\u65B9\u56FE/Logo \u662F\u5426\u5DF2\u4E0A\u4F20\u6210\u529F\u3001\u89C4\u683C\u662F\u5426\u8FBE\u6807\uFF08\u5148\u8DD1 ad pmax-validate\uFF09");
+    }
+    if (/final.?url|landing|落地页|url/i.test(msg)) {
+      hints.push("\u68C0\u67E5 finalUrls \u662F\u5426\u4E3A\u53EF\u8BBF\u95EE\u7684 http(s) \u843D\u5730\u9875");
+    }
+    if (/name|duplicate|已存在|同名/i.test(msg)) {
+      hints.push("\u7CFB\u5217\u540D\u53EF\u80FD\u91CD\u590D\uFF1B\u6362\u4E00\u4E2A name \u518D\u8BD5");
+    }
+    if (/geo|location|language|地域|语言/i.test(msg)) {
+      hints.push("\u68C0\u67E5 geo / language id \u662F\u5426\u6765\u81EA ad geo resolve / \u6587\u6863\u679A\u4E3E");
+    }
+    if (hints.length === 0) {
+      hints.push(
+        "\u5E38\u89C1\uFF1A\u9884\u7B97/\u51FA\u4EF7\u4E0D\u517C\u5BB9\u3001\u56FE\u7247\u8D44\u4EA7\u65E0\u6548\u3001finalUrl \u65E0\u6548\u3001\u7CFB\u5217\u91CD\u540D\uFF1B\u5148 ad pmax-validate\uFF0C\u4ECD\u5931\u8D25\u52A0 --verbose \u770B\u7F51\u5173\u539F\u6587"
+      );
+    }
+  } else if (/^HTTP 403\b/i.test(msg)) {
+    hints.push("\u8D26\u6237\u53EF\u80FD\u65E0\u6743\u521B\u5EFA\uFF1B\u5148 account check-access -a <id>\uFF0C\u786E\u8BA4\u5728\u5F53\u524D\u4E1D\u8DEF\u8D5E\u8D26\u53F7\u4E0B");
+  } else if (/^HTTP 401\b/i.test(msg)) {
+    hints.push("\u9274\u6743\u5931\u6548\uFF1B\u6267\u884C siluzan-tso login \u540E\u91CD\u8BD5");
+  }
+  if (hints.length === 0) return msg;
+  return `${msg}
+   \u63D0\u793A\uFF1A${hints.join("\uFF1B")}`;
+}
+
 // src/commands/ad/pmax-create.ts
 function printVideoLinkRecoveryHint(accountId, assetGroupId, campaignId, youtubeTarget) {
   const cid = campaignId != null ? ` --campaign-id ${campaignId}` : "";
@@ -117831,11 +118006,10 @@ async function runAdPmaxCreate(opts) {
       opts.verbose
     );
   } catch (err) {
-    console.error(
-      `
-\u274C \u521B\u5EFA PMax \u5E7F\u544A\u7CFB\u5217\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
-`
-    );
+    const raw = err instanceof Error ? err.message : String(err);
+    console.error(`
+\u274C \u521B\u5EFA PMax \u5E7F\u544A\u7CFB\u5217\u5931\u8D25\uFF1A${classifyPmaxCreateHttpError(raw)}
+`);
     process.exit(1);
   }
   const campaignId = data["campaignId"] ?? data["campaign_id"];
@@ -119081,7 +119255,7 @@ async function runAdCampaignValidate(opts) {
 }
 
 // src/commands/ad/pmax-image-convert.ts
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5, readFileSync as readFileSync14, existsSync as existsSync4 } from "fs";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5, readFileSync as readFileSync14, existsSync as existsSync6 } from "fs";
 import { resolve as resolve10, dirname as dirname11, basename as basename7, extname } from "path";
 var SPECS = [
   { kind: "marketing", width: 1200, height: 628, fit: "cover", suffix: "_marketing" },
@@ -119142,7 +119316,7 @@ async function runAdPmaxImageConvert(opts) {
       continue;
     }
     const absInput = resolve10(src);
-    if (!existsSync4(absInput)) {
+    if (!existsSync6(absInput)) {
       console.error(`\u274C \u8F93\u5165\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${absInput}`);
       hasError = true;
       continue;
@@ -122906,6 +123080,31 @@ async function runAccountBmBind(opts) {
 // src/commands/account-manage-register.ts
 function register23(program2) {
   const accountCmd = program2.command("account").description("\u5E7F\u544A\u8D26\u6237\u7BA1\u7406\uFF1AOAuth \u6DFB\u52A0\u6388\u6743\u3001\u89E3\u9664\u5173\u8054\uFF08\u89E3\u7ED1\uFF09\u3001Google MCC \u7ED1\u5B9A/\u89E3\u7ED1\u3001\u8D26\u53F7\u5206\u4EAB");
+  accountCmd.command("list", { hidden: true }).description("\uFF08\u517C\u5BB9\u522B\u540D\uFF09\u540C list-accounts").option(
+    "-m, --media <type>",
+    "\u5A92\u4F53\u7C7B\u578B\uFF1AGoogle | TikTok | Yandex | MetaAd | BingV2 | Kwai\uFF08\u7559\u7A7A\u5219\u67E5\u8BE2\u5168\u90E8\u5A92\u4F53\uFF09"
+  ).option("-k, --keyword <text>", "\u5173\u952E\u5B57\uFF08\u516C\u53F8/\u8D26\u6237\u540D/\u8D26\u6237ID \u6A21\u7CCA\u5339\u914D\uFF09").option(
+    "-s, --status <status>",
+    "\u8D26\u6237\u72B6\u6001\uFF1Anormal\uFF08\u6B63\u5E38\uFF09| invalid\uFF08\u5931\u6548\uFF09| all\uFF08\u5168\u90E8\uFF0C\u9ED8\u8BA4\uFF09",
+    "all"
+  ).option("-p, --page <n>", "\u9875\u7801\uFF08\u9ED8\u8BA4 1\uFF09", parseInt).option("--page-size <n>", "\u6BCF\u9875\u6570\u91CF\uFF08\u9ED8\u8BA4 20\uFF09", parseInt).option("-t, --token <token>", "Token\uFF08\u53EF\u9009\uFF1B\u4F18\u5148\u4E8E ~/.siluzan/config.json\uFF09").option("--json-out <path>", "\u843D\u76D8\u76EE\u5F55\u6216 *.json\uFF1Bstdout \u4E00\u884C\u6458\u8981", void 0).option("--refresh-dp", "\u5F3A\u5236\u91CD\u62C9 Datapermission", false).option("--verbose", "\u663E\u793A\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+    async (opts) => {
+      process.stderr.write(
+        "\u2139 `account list` \u5DF2\u8F6C\u53D1\u4E3A `list-accounts`\uFF08\u8BF7\u4F18\u5148\u4F7F\u7528 list-accounts\uFF09\u3002\n"
+      );
+      await runListAccounts({
+        token: opts.token,
+        media: opts.media,
+        keyword: opts.keyword,
+        status: opts.status,
+        page: opts.page,
+        pageSize: opts.pageSize,
+        jsonOut: opts.jsonOut,
+        refreshDp: opts.refreshDp,
+        verbose: opts.verbose
+      });
+    }
+  );
   accountCmd.command("me").description(
     "\u67E5\u8BE2\u5F53\u524D\u767B\u5F55\u4E1D\u8DEF\u8D5E\u8D26\u53F7\u4FE1\u606F\uFF08GET /query/account/me\uFF09\uFF1B--check-phone \u7528\u4E8E\u6821\u9A8C\u7528\u6237\u6307\u5B9A\u7684\u4F01\u4E1A\u7BA1\u5BB6\u624B\u673A\u53F7"
   ).option("-t, --token <token>", "Auth Token").option(
@@ -131954,6 +132153,34 @@ function registerTikTokAnalysisCommands(program2) {
 // src/index.ts
 init_version();
 init_cli_json_snapshot();
+
+// src/utils/agent-compat-argv.ts
+function agentCompatFatalMessage(argv) {
+  const args = argv.slice(2);
+  if (args.includes("--period") || args.some((a) => a.startsWith("--period="))) {
+    return "\n\u274C \u6CA1\u6709 --period \u9009\u9879\u3002\u8BF7\u7528 --start/--end\uFF08\u6216\u517C\u5BB9\u522B\u540D --start-date/--end-date\uFF09\u6307\u5B9A YYYY-MM-DD \u533A\u95F4\u3002\n";
+  }
+  const cmd = args[0];
+  if (cmd === "google-ads") {
+    return "\n\u274C \u6CA1\u6709 `google-ads` \u547D\u540D\u7A7A\u95F4\u3002\u8BF7\u6539\u7528\uFF1A\n   - \u8D26\u6237\u5206\u6790\u62C9\u6570\uFF1Asiluzan-tso google-analysis \u2026\n   - \u5E7F\u544A\u7CFB\u5217/\u7EC4/\u5173\u952E\u8BCD CRUD\uFF1Asiluzan-tso ad \u2026\n   - \u5E7F\u544A\u8BCA\u65AD\u62A5\u544A\uFF1Asiluzan-tso google-ads-diagnosis \u2026\n";
+  }
+  if (cmd === "list" && (args.length === 1 || args[1]?.startsWith("-"))) {
+    return "\n\u274C \u6CA1\u6709\u9876\u5C42 `list` \u547D\u4EE4\u3002\u67E5\u8BE2\u5E7F\u544A\u8D26\u6237\u5217\u8868\u8BF7\u7528\uFF1A\n   siluzan-tso list-accounts [-m Google] [-k <id\u6216\u5173\u952E\u5B57>] --json-out <dir>\n";
+  }
+  if (cmd === "accounts") {
+    return "\n\u274C \u6CA1\u6709 `accounts` \u547D\u540D\u7A7A\u95F4\u3002\u67E5\u8BE2\u8D26\u6237\u5217\u8868\u8BF7\u7528\uFF1A\n   siluzan-tso list-accounts \u2026\n   \u591A\u8D26\u6237\u753B\u50CF\uFF1Asiluzan-tso accounts-digest \u2026\n";
+  }
+  return null;
+}
+function interceptAgentCompatArgv(argv) {
+  const msg = agentCompatFatalMessage(argv);
+  if (msg) {
+    console.error(msg);
+    process.exit(1);
+  }
+}
+
+// src/index.ts
 installProcessHandlers();
 function getVersion() {
   try {
@@ -132036,4 +132263,5 @@ function argvHasDeprecatedJsonFlag(argv) {
 if (argvHasDeprecatedJsonFlag(process.argv)) {
   rejectDeprecatedJsonFlag(true, process.argv[2] ?? "siluzan-tso");
 }
+interceptAgentCompatArgv(process.argv);
 program.parseAsync();

package/dist/skill/AGENTS.md

@@ -1,28 +1,35 @@
-# siluzan-tso — Agent 文档目录
+# siluzan-tso — 文档目录
 
-> 运行时入口：`SKILL.md` → 按路由表 Read **leaf** 文档。维护时对齐 `references/core/skill-authoring.md`。
+> 入口：`SKILL.md` → 按路由表 Read 列出的文件。改文档结构时对齐 `references/core/skill-authoring.md`。
+
+## 怎么找文档
+
+| 要做什么 | 读哪里 |
+| -------- | ------ |
+| 锁定工作流 | `SKILL.md` 路由表 |
+| 报告类话术模糊 | `references/core/intent-routing.md` |
+| 步骤与产物 | `playbooks.md`（P*）或 `workflows.md`（W*） |
+| 命令参数 / 字段 | 路由表「必读文档」 |
+| 纪律与对用户怎么说 | `references/core/agent-conventions.md` |
+| 报告结构纲要 | `report-templates/*.md`（勿读 `*.html`） |
 
 ## 启动顺序
 
 1. Read `SKILL.md` 路由表，锁定唯一工作流
-2. 报告类模糊 → Read `references/core/intent-routing.md`
-3. Read 路由行「必读文档」+ 对应 `playbooks.md` / `workflows.md` 卡片（**直接读 leaf**，不必先经 `accounts.md` 索引）
-4. 写操作 / 报告交付 / 批量拉数 → Read `references/core/agent-conventions.md` 相关节
-5. P5/P6/P7 或长 CLI：可选 `references/core/subagent-orchestration.md`
-
-## 文档域
-
-| 域 | 路径 | 何时 Read |
-| -- | ---- | --------- |
-| Core | `references/core/` | 纪律、intent-routing、playbooks、workflows |
-| Accounts | `references/accounts/` | `accounts-list` / `accounts-balance-stats` / `accounts-permissions`（`accounts.md` 仅索引） |
-| Google Ads | `references/google-ads/` | `google-ads-read` / `write` / `batch`（索引：`google-ads.md`）；`rules/` 先 README 再单文件 |
-| Analytics | `references/analytics/` | 拉数、批处理、拓词、RAG |
-| Operations | `references/operations/` | 预警、线索；自动化仅用户问起时 |
-| Templates | `report-templates/*.md`、`assets/` | 报告纲要 / JSON 契约；**禁止** Read `*.html` |
+2. 报告类模糊 → Read `intent-routing.md`
+3. Read「必读文档」+ 对应 playbook/workflow 卡片
+4. 写操作 / 报告交付 / 批量 / 对用户写结论 → Read `agent-conventions.md` 相关节
+5. P5/P6/P7 或长 CLI：可选 `subagent-orchestration.md`
 
-## 维护
+## 按域
+
+| 域 | 路径 | 说明 |
+| -- | ---- | ---- |
+| Core | `references/core/` | conventions、intent-routing、playbooks、workflows |
+| Accounts | `references/accounts/` | 直接读 `accounts-list` / `accounts-balance-stats` / `accounts-permissions` |
+| Google Ads | `references/google-ads/` | `google-ads-read` / `write` / `batch`；`rules/` 先 README 再单文件 |
+| Analytics | `references/analytics/` | 拉数、批处理、拓词 |
+| Operations | `references/operations/` | 预警、线索；自动化仅用户问起时 |
+| Templates | `report-templates/*.md`、`assets/` | 报告纲要 / JSON 契约 |
 
-- 源码：`tso-cli/assets/siluzan-ads/`
-- 纪律真相源：`references/core/agent-conventions.md`
-- 规范：`references/core/skill-authoring.md`
+源码目录：`tso-cli/assets/siluzan-ads/`。