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

package/README.md

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

package/dist/index.js

@@ -4816,6 +4816,19 @@ function normalizeNumericMediaCustomerId(raw) {
   if (!looksLikeNumericMediaCustomerId(raw)) return null;
   return stripMediaCustomerIdDecorators(raw);
 }
+function requireNumericMediaCustomerId(raw, label = "-a, --account") {
+  const trimmed = raw?.toString().trim() ?? "";
+  if (!trimmed) {
+    throw new Error(`\u8BF7\u6307\u5B9A\u5A92\u4F53\u8D26\u6237 ID\uFF08${label}\uFF09`);
+  }
+  const id = normalizeNumericMediaCustomerId(trimmed);
+  if (!id) {
+    throw new Error(
+      `\u5A92\u4F53\u8D26\u6237 ID \u5FC5\u987B\u4E3A\u7EAF\u6570\u5B57\uFF08Google CID \u53EF\u542B\u8FDE\u5B57\u7B26\uFF0C\u5982 123-456-7890\uFF1B\u52FF\u4F20 entityId/UUID\uFF09\uFF1A${trimmed}`
+    );
+  }
+  return id;
+}
 function looksLikeEntityIdUuid(raw) {
   return ENTITY_ID_UUID_RE.test(raw.trim());
 }
@@ -5544,6 +5557,32 @@ var init_daily_metrics_range = __esm({
   }
 });
 
+// src/utils/snapshot/async-lock.ts
+async function withAsyncLock(key, fn) {
+  const prev = chains.get(key) ?? Promise.resolve();
+  let release;
+  const gate = new Promise((resolve21) => {
+    release = resolve21;
+  });
+  chains.set(
+    key,
+    prev.catch(() => void 0).then(() => gate)
+  );
+  await prev.catch(() => void 0);
+  try {
+    return await fn();
+  } finally {
+    release();
+  }
+}
+var chains;
+var init_async_lock = __esm({
+  "src/utils/snapshot/async-lock.ts"() {
+    "use strict";
+    chains = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/commands/google-analysis/wrap-snapshot-envelope.ts
 function coerceToRowArray(value) {
   if (Array.isArray(value)) return value;
@@ -5766,26 +5805,29 @@ async function writeGoogleAnalysisSnapshot(params) {
   const outlineBody = formatOutlineFileBody(fileName, normalizedWrapped, outlineExtra);
   await fs7.writeFile(path11.join(absDir, outlineFileName), `${outlineBody}
 `, "utf8");
-  const existing = await readManifestIfExists(absDir, accountSlug || void 0);
   const newArtifact = {
     section: params.section,
     file: relativeFile,
     writtenAt,
     ...params.endpointHint !== void 0 ? { endpointHint: params.endpointHint } : {}
   };
-  const merged = mergeGoogleAnalysisManifest(existing, {
-    accountId: params.accountId,
-    dateRange: params.dateRange,
-    cliVersion: params.cliVersion,
-    newArtifact
-  });
   const manifestFile = googleAnalysisManifestFile(accountSlug || void 0);
-  await fs7.writeFile(
-    path11.join(absDir, manifestFile),
-    `${JSON.stringify(stringifyIdsDeep(merged), null, 2)}
+  const manifestPath = path11.join(absDir, manifestFile);
+  await withAsyncLock(manifestPath, async () => {
+    const existing = await readManifestIfExists(absDir, accountSlug || void 0);
+    const merged = mergeGoogleAnalysisManifest(existing, {
+      accountId: params.accountId,
+      dateRange: params.dateRange,
+      cliVersion: params.cliVersion,
+      newArtifact
+    });
+    await fs7.writeFile(
+      manifestPath,
+      `${JSON.stringify(stringifyIdsDeep(merged), null, 2)}
 `,
-    "utf8"
-  );
+      "utf8"
+    );
+  });
   return {
     kind: "siluzan-tso-google-analysis-snapshot",
     schemaVersion: SCHEMA_VERSION2,
@@ -5803,6 +5845,7 @@ var init_google_analysis = __esm({
     "use strict";
     init_cli_json();
     init_wrap_snapshot_envelope();
+    init_async_lock();
     init_dir();
     LEGACY_MANIFEST_FILE = "manifest.json";
     CLI_PACKAGE = "siluzan-tso-cli";
@@ -102288,6 +102331,56 @@ async function loadSectionFile(snapshotDir, file) {
     return null;
   }
 }
+function dateTagFromRange(dateRange) {
+  if (!dateRange || dateRange.mode !== "range") return void 0;
+  return `${dateRange.start.replace(/-/g, "")}-${dateRange.end.replace(/-/g, "")}`;
+}
+function dateTagFromMeta(meta) {
+  const start = typeof meta?.startDate === "string" ? meta.startDate : "";
+  const end = typeof meta?.endDate === "string" ? meta.endDate : "";
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(start) || !/^\d{4}-\d{2}-\d{2}$/.test(end)) return void 0;
+  return `${start.replace(/-/g, "")}-${end.replace(/-/g, "")}`;
+}
+function pickSectionSnapshotFile(files, section, accountId, preferredDateTag) {
+  const escapedSection = section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapedId = accountId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${escapedSection}-${escapedId}(?:_(\\d{8}-\\d{8}))?\\.json$`);
+  const matches = files.filter((f) => re.test(f));
+  if (matches.length === 0) return null;
+  if (preferredDateTag) {
+    const preferred = matches.find((f) => f.endsWith(`_${preferredDateTag}.json`));
+    if (preferred) return preferred;
+  }
+  return [...matches].sort().at(-1) ?? null;
+}
+async function recoverMissingReportSections(sectionMap, absDir, accountId, preferredDateTag) {
+  if (!accountId) return;
+  let entries;
+  try {
+    entries = await fs20.readdir(absDir);
+  } catch {
+    return;
+  }
+  for (const section of REPORT_MERGE_SECTIONS) {
+    if (sectionMap.has(section)) continue;
+    const file = pickSectionSnapshotFile(entries, section, accountId, preferredDateTag);
+    if (!file) continue;
+    const data = await loadSectionFile(absDir, file);
+    if (data) sectionMap.set(section, data);
+  }
+}
+function periodMetricsFromRow(row) {
+  if (!row) return null;
+  return {
+    cost: num2(row.spend),
+    impressions: num2(row.impressions),
+    clicks: num2(row.clicks),
+    conversions: num2(row.conversions),
+    ctr: num2(row.ctr),
+    averageCpc: num2(row.averageCpc),
+    costPerConversion: num2(row.costPerConversion)
+  };
+}
 function items(envelope) {
   if (!envelope || !Array.isArray(envelope.items)) return [];
   return envelope.items.filter((row) => asRecord11(row) !== null);
@@ -102342,16 +102435,18 @@ async function mergeGoogleAnalysisSnapshotIntoReport(payload, snapshotDir) {
   if (!manifest) {
     throw new Error(`\u672A\u5728 ${absDir} \u627E\u5230 manifest*.json\uFF0C\u8BF7\u5148\u6267\u884C google-analysis --json-out`);
   }
+  const accountId = manifest.googleAnalysis?.accountId ?? metaAccountId;
+  const dateRange = manifest.googleAnalysis?.dateRange;
+  const preferredDateTag = dateTagFromRange(dateRange) ?? dateTagFromMeta(asRecord11(payload.meta) ?? void 0);
   const sectionMap = /* @__PURE__ */ new Map();
   for (const art of manifest.artifacts ?? []) {
     const data = await loadSectionFile(absDir, art.file);
     if (data) sectionMap.set(art.section, data);
   }
+  await recoverMissingReportSections(sectionMap, absDir, accountId, preferredDateTag);
   const overviewRecord = record(sectionMap.get("overview"));
   const currentPeriod = asRecord11(overviewRecord?.currentPeriod);
   const previousPeriod = asRecord11(overviewRecord?.previousPeriod);
-  const accountId = manifest.googleAnalysis?.accountId ?? metaAccountId;
-  const dateRange = manifest.googleAnalysis?.dateRange;
   const meta = { ...payload.meta ?? {} };
   if (!meta.accountId && accountId) meta.accountId = accountId;
   if (!meta.currency) {
@@ -102363,16 +102458,9 @@ async function mergeGoogleAnalysisSnapshotIntoReport(payload, snapshotDir) {
   if (!meta.generatedAt) meta.generatedAt = (/* @__PURE__ */ new Date()).toISOString();
   const campaignRows2 = items(sectionMap.get("campaigns"));
   const campaignKpis = sumCampaignRowsToPeriodKpis(campaignRows2);
+  const dimensionSummaryRecord = record(sectionMap.get("dimension-summary"));
   const kpis = { ...payload.kpis ?? {} };
-  const currentKpiSource = campaignKpis ?? (currentPeriod ? {
-    cost: num2(currentPeriod.spend),
-    impressions: num2(currentPeriod.impressions),
-    clicks: num2(currentPeriod.clicks),
-    conversions: num2(currentPeriod.conversions),
-    ctr: num2(currentPeriod.ctr),
-    averageCpc: num2(currentPeriod.averageCpc),
-    costPerConversion: num2(currentPeriod.costPerConversion)
-  } : null);
+  const currentKpiSource = campaignKpis ?? periodMetricsFromRow(currentPeriod) ?? periodMetricsFromRow(dimensionSummaryRecord);
   if (currentKpiSource) {
     if (currentKpiSource.cost != null) kpis.cost = currentKpiSource.cost;
     if (currentKpiSource.impressions != null) kpis.impressions = currentKpiSource.impressions;
@@ -102411,22 +102499,21 @@ async function mergeGoogleAnalysisSnapshotIntoReport(payload, snapshotDir) {
     }
   }
   const tables = { ...payload.tables ?? {} };
-  {
-    const summary = record(sectionMap.get("dimension-summary"));
-    if (summary) {
-      tables.dimensionSummary = {
-        cost: num2(summary.spend),
-        impressions: num2(summary.impressions),
-        clicks: num2(summary.clicks),
-        conversions: num2(summary.conversions),
-        ctr: num2(summary.ctr),
-        averageCpc: num2(summary.averageCpc),
-        costPerConversion: num2(summary.costPerConversion),
-        searchImpressionShare: num2(summary.searchImpressionShare),
-        searchBudgetLostImpressionShare: num2(summary.searchBudgetLostImpressionShare),
-        searchRankLostImpressionShare: num2(summary.searchRankLostImpressionShare)
-      };
-    }
+  if (dimensionSummaryRecord) {
+    tables.dimensionSummary = {
+      cost: num2(dimensionSummaryRecord.spend),
+      impressions: num2(dimensionSummaryRecord.impressions),
+      clicks: num2(dimensionSummaryRecord.clicks),
+      conversions: num2(dimensionSummaryRecord.conversions),
+      ctr: num2(dimensionSummaryRecord.ctr),
+      averageCpc: num2(dimensionSummaryRecord.averageCpc),
+      costPerConversion: num2(dimensionSummaryRecord.costPerConversion),
+      searchImpressionShare: num2(dimensionSummaryRecord.searchImpressionShare),
+      searchBudgetLostImpressionShare: num2(
+        dimensionSummaryRecord.searchBudgetLostImpressionShare
+      ),
+      searchRankLostImpressionShare: num2(dimensionSummaryRecord.searchRankLostImpressionShare)
+    };
   }
   if (campaignRows2.length > 0) {
     tables.campaigns = campaignRows2.map((r) => ({
@@ -102464,10 +102551,20 @@ async function mergeGoogleAnalysisSnapshotIntoReport(payload, snapshotDir) {
     tables
   };
 }
+var REPORT_MERGE_SECTIONS;
 var init_merge_snapshot = __esm({
   "src/commands/google-analysis/merge-snapshot.ts"() {
     "use strict";
     init_google_analysis();
+    REPORT_MERGE_SECTIONS = [
+      "overview",
+      "daily-metrics",
+      "dimension-summary",
+      "campaigns",
+      "devices",
+      "geographic",
+      "keywords"
+    ];
   }
 });
 
@@ -102511,6 +102608,19 @@ function validateGooglePeriodReportContent(data) {
       "\u22651 \u6BB5\u6267\u884C\u6458\u8981\uFF0C\u6982\u8FF0\u672C\u671F\u6D88\u8017/\u8F6C\u5316/CTR/CPA \u8D70\u52BF"
     );
   }
+  const kpis = asRecord12(data.kpis);
+  const hasCoreKpi = ["cost", "impressions", "clicks"].some(
+    (key) => Number.isFinite(Number(kpis?.[key]))
+  );
+  if (!hasCoreKpi) {
+    pushMissing(
+      missing,
+      "kpis-core-metrics",
+      "\u6267\u884C\u6458\u8981 KPI",
+      "kpis.cost / kpis.impressions / kpis.clicks",
+      "\u81F3\u5C11\u4E00\u9879\u987B\u4E3A\u6709\u6548\u6570\u5B57\uFF1B\u8BF7\u52A0 --snapshot-dir \u4ECE google-analysis \u5FEB\u7167\u5408\u5E76\uFF08\u52FF\u624B\u586B HTML\uFF09"
+    );
+  }
   const sectionAnalysisCounts = {};
   const sectionSuggestionCounts = {};
   for (const key of SECTION_KEYS) {
@@ -102571,7 +102681,7 @@ function formatGooglePeriodReportErrors(result) {
     ...lines,
     "",
     "\u8BF7\u8865\u5168 narrative.sections.<dimension>.{analysis,suggestions} \u4E0E narrative.recommendations \u540E\u91CD\u65B0\u6267\u884C render\u3002",
-    "\u6570\u503C\u7C7B\u5B57\u6BB5\uFF08kpis/charts/tables\uFF09\u53EF\u7701\u7565\uFF0C\u52A0 --snapshot-dir \u7531 CLI \u4ECE google-analysis \u5FEB\u7167\u81EA\u52A8\u5408\u5E76\uFF1BAgent \u53EA\u9700\u64B0\u5199\u53D9\u4E8B\u6587\u5B57\uFF0C\u7981\u6B62\u624B\u5199 HTML\u3002"
+    "kpis/charts/tables \u987B\u7531 --snapshot-dir \u4ECE google-analysis \u5FEB\u7167\u81EA\u52A8\u5408\u5E76\uFF08Agent \u53EA\u5199 narrative\uFF09\uFF1B\u5408\u5E76\u540E kpis \u4ECD\u4E3A\u7A7A\u65F6\u68C0\u67E5\u5FEB\u7167\u76EE\u5F55 manifest \u662F\u5426\u542B overview/campaigns/dimension-summary\u3002\u7981\u6B62\u624B\u5199 HTML\u3002"
   ].join("\n");
 }
 var SECTION_KEYS, SECTION_LABELS;
@@ -107168,6 +107278,20 @@ init_list_fetch();
 
 // src/commands/ad/_shared.ts
 init_auth();
+init_media_customer_id();
+function resolveAdAccountId(account, label = "-a, --account") {
+  try {
+    return requireNumericMediaCustomerId(account, label);
+  } catch (e) {
+    console.error(`
+\u274C ${e instanceof Error ? e.message : String(e)}
+`);
+    process.exit(1);
+  }
+}
+function withResolvedAdAccount(opts) {
+  return { ...opts, account: resolveAdAccountId(opts.account) };
+}
 async function findItemInList(listUrl, config, id, verbose) {
   const res = await apiFetch2(listUrl, config, {}, verbose);
   const item = (res.data ?? []).find((x) => x["id"] === id);
@@ -108342,6 +108466,7 @@ init_cli_table();
 init_cli_json_snapshot();
 
 // src/utils/snapshot/report-analysis.ts
+init_async_lock();
 init_google_analysis();
 init_cli_json();
 import * as fs8 from "fs/promises";
@@ -108415,25 +108540,24 @@ async function writeReportAnalysisSnapshot(params) {
 `,
     "utf8"
   );
-  const existing = await readReportManifestIfExists(absDir, accountSlug || void 0);
   const newArtifact = {
     section: params.section,
     file: fileName,
     writtenAt
   };
-  const merged = mergeReportAnalysisManifest(existing, {
-    accountId: params.accountId,
-    dateRange: params.dateRange,
-    cliVersion: params.cliVersion,
-    newArtifact
-  });
   const manifestFile = reportManifestFile(accountSlug || void 0);
-  await fs8.writeFile(
-    path12.join(absDir, manifestFile),
-    `${JSON.stringify(merged, null, 2)}
-`,
-    "utf8"
-  );
+  const manifestPath = path12.join(absDir, manifestFile);
+  await withAsyncLock(manifestPath, async () => {
+    const existing = await readReportManifestIfExists(absDir, accountSlug || void 0);
+    const merged = mergeReportAnalysisManifest(existing, {
+      accountId: params.accountId,
+      dateRange: params.dateRange,
+      cliVersion: params.cliVersion,
+      newArtifact
+    });
+    await fs8.writeFile(manifestPath, `${JSON.stringify(merged, null, 2)}
+`, "utf8");
+  });
   return {
     kind: "siluzan-tso-report-analysis-snapshot",
     schemaVersion: SCHEMA_VERSION3,
@@ -111297,6 +111421,9 @@ init_cli_json_snapshot();
 init_strip_legacy_google_fields();
 init_cli_table();
 
+// src/commands/ad/campaign-create-validate.ts
+init_media_customer_id();
+
 // src/commands/ad/campaign-length-violations.ts
 function pushLengthViolation(violations, item) {
   violations.push({ ...item, excess: item.actual - item.limit });
@@ -111694,6 +111821,7 @@ function keywordRowToYuan(item) {
   return { ...rest, maxCPCYuan: toDisplayMoney(rawMaxCpc) };
 }
 async function runAdKeywords(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -111797,6 +111925,7 @@ ${label}\uFF08\u8D26\u6237\uFF1A${opts.account}\uFF0C\u7B2C 1 \u9875\uFF0C\u672C
   console.log();
 }
 async function runAdKeywordCreate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   let keywords;
@@ -111849,6 +111978,7 @@ async function runAdKeywordCreate(opts) {
 `);
 }
 async function runAdNegativeKeywordCreate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   let keywords;
@@ -111888,6 +112018,7 @@ async function runAdNegativeKeywordCreate(opts) {
 `);
 }
 async function runAdKeywordDelete(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = await ensureDataPermission(loadConfig(opts.token));
   const googleApiUrl = requireGoogleApi(config);
   const body = [{ adGroupId: opts.adgroupId, id: opts.id }];
@@ -111905,6 +112036,7 @@ async function runAdKeywordDelete(opts) {
 `);
 }
 async function runAdKeywordEdit(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = await ensureDataPermission(loadConfig(opts.token));
   const googleApiUrl = requireGoogleApi(config);
   const hasChange = opts.text !== void 0 || opts.matchType !== void 0 || opts.maxCpc !== void 0 || opts.finalUrl !== void 0 || opts.status !== void 0;
@@ -111970,6 +112102,7 @@ async function runAdKeywordEdit(opts) {
 `);
 }
 async function runAdKeywordStatus(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = await ensureDataPermission(loadConfig(opts.token));
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -112005,6 +112138,7 @@ async function runAdKeywordStatus(opts) {
 `);
 }
 async function runAdNegativeKeywordEdit(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const dateParams = new URLSearchParams();
@@ -112046,6 +112180,7 @@ async function runAdNegativeKeywordEdit(opts) {
 `);
 }
 async function runAdNegativeKeywordDelete(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const dateParams = new URLSearchParams();
@@ -112888,9 +113023,13 @@ function validateCampaignCreateConfigCore(cfg) {
       "customerName \u4E3A\u7A7A\uFF1A\u63D0\u4EA4 campaign-create \u65F6\u5C06\u6309 account \u4ECE list-accounts \u81EA\u52A8\u586B\u5145 mediaCustomerName"
     );
   }
-  const accountNum = Number(cfg.account);
-  if (!Number.isFinite(accountNum) || accountNum <= 0) {
-    pushErr2(errors, "account \u5FC5\u987B\u662F\u53EF\u89E3\u6790\u4E3A\u6B63\u6570\u7684\u5A92\u4F53\u8D26\u6237 ID\uFF08\u63D0\u4EA4\u65F6 customerId \u4E3A number\uFF09");
+  const normalizedAccount = normalizeNumericMediaCustomerId(String(cfg.account ?? "").trim());
+  const accountNum = normalizedAccount ? Number(normalizedAccount) : NaN;
+  if (!normalizedAccount || !Number.isFinite(accountNum) || accountNum <= 0) {
+    pushErr2(
+      errors,
+      "account \u5FC5\u987B\u662F\u53EF\u89E3\u6790\u4E3A\u6B63\u6570\u7684\u5A92\u4F53\u8D26\u6237 ID\uFF08\u53EF\u542B\u8FDE\u5B57\u7B26\uFF1B\u63D0\u4EA4\u65F6 customerId \u4E3A number\uFF09"
+    );
   }
   if (!cfg.campaign || typeof cfg.campaign !== "object" || Array.isArray(cfg.campaign)) {
     pushErr2(errors, "campaign \u5BF9\u8C61\u4E0D\u80FD\u4E3A\u7A7A\uFF08\u540E\u7AEF\uFF1Acampaign is null\uFF09");
@@ -113256,6 +113395,7 @@ function parseCampaignTimeMs(v) {
   return Number.isFinite(t) ? t : null;
 }
 async function runAdCampaigns(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -113338,6 +113478,7 @@ async function runAdCampaigns(opts) {
   console.log();
 }
 async function runAdCampaignStatus(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const detailUrl = `${googleApiUrl}/campaignmanagement/campaign/${opts.account}/${opts.id}`;
@@ -113372,6 +113513,7 @@ async function runAdCampaignStatus(opts) {
 `);
 }
 async function runAdCampaignDelete(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const detailUrl = `${googleApiUrl}/campaignmanagement/campaign/${opts.account}/${opts.id}`;
@@ -113409,6 +113551,7 @@ async function runAdCampaignDelete(opts) {
 }
 async function runAdCampaignCreate(opts) {
   const cfg = loadCampaignCreateConfig(opts.configFile);
+  cfg.account = resolveAdAccountId(cfg.account, "account");
   const { errors, warnings } = runCampaignCreateValidation(cfg);
   if (warnings.length > 0) {
     console.warn("\n\u26A0\uFE0F  \u6295\u653E\u914D\u7F6E\u8B66\u544A\uFF08\u4E0D\u963B\u65AD\u63D0\u4EA4\uFF0C\u4F46\u5EFA\u8BAE\u4FEE\u6B63\uFF09\uFF1A");
@@ -113615,6 +113758,7 @@ function validateCampaignEditBidding(opts) {
   }
 }
 async function runAdCampaignEdit(opts) {
+  opts = withResolvedAdAccount(opts);
   validateCampaignEditBidding(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
@@ -113684,6 +113828,7 @@ init_cli_json_snapshot();
 init_strip_legacy_google_fields();
 init_cli_table();
 async function runAdGroups(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -113775,6 +113920,7 @@ function adGroupRowToYuan(item) {
   };
 }
 async function runAdGroupCreate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const body = {
@@ -113826,6 +113972,7 @@ async function runAdGroupCreate(opts) {
   }
 }
 async function runAdGroupStatus(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const listUrl = adgroupListUrl(googleApiUrl, opts.account, opts.startDate, opts.endDate);
@@ -113853,6 +114000,7 @@ async function runAdGroupStatus(opts) {
 `);
 }
 async function runAdGroupDelete(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const listUrl = adgroupListUrl(googleApiUrl, opts.account, opts.startDate, opts.endDate);
@@ -113879,6 +114027,7 @@ async function runAdGroupDelete(opts) {
 `);
 }
 async function runAdGroupRename(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const listUrl = adgroupListUrl(googleApiUrl, opts.account, opts.startDate, opts.endDate);
@@ -113906,6 +114055,7 @@ async function runAdGroupRename(opts) {
 `);
 }
 async function runAdGroupEdit(opts) {
+  opts = withResolvedAdAccount(opts);
   const hasName = opts.name !== void 0 && opts.name.trim() !== "";
   const hasMax = opts.maxCPCAmount !== void 0;
   const hasTcpa = opts.targetCpaAmount !== void 0;
@@ -114028,6 +114178,7 @@ function formatRsaCliValidationError(errors) {
 
 // src/commands/ad/ad-creative.ts
 async function runAdList(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -114104,6 +114255,7 @@ async function runAdList(opts) {
   console.log();
 }
 async function runAdCreate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const rsaErrors = validateRsaCliCopy({
@@ -114170,6 +114322,7 @@ async function runAdCreate(opts) {
   }
 }
 async function runAdStatus(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -114200,6 +114353,7 @@ async function runAdStatus(opts) {
 `);
 }
 async function runAdDelete(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -114229,6 +114383,7 @@ async function runAdDelete(opts) {
 `);
 }
 async function runAdEdit(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = await ensureDataPermission(loadConfig(opts.token));
   const googleApiUrl = requireGoogleApi(config);
   const hasTextOrUrl = opts.headlines || opts.descriptions || opts.finalUrl !== void 0 || opts.path1 !== void 0 || opts.path2 !== void 0;
@@ -114532,6 +114687,7 @@ function buildBusinessMessageBodyForCampaign(accountId, campaignId, bm) {
 
 // src/commands/ad/extension.ts
 async function runAdExtensionList(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const url = `${googleApiUrl}/extensionmanagement/v2/list/${opts.account}`;
@@ -114608,6 +114764,7 @@ async function runAdExtensionList(opts) {
   console.log();
 }
 async function runAdExtensionCreate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const body = {
@@ -114685,6 +114842,7 @@ async function runAdExtensionCreate(opts) {
   }
 }
 async function runAdExtensionDelete(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const listUrl = `${googleApiUrl}/extensionmanagement/v2/list/${opts.account}`;
@@ -114786,6 +114944,7 @@ async function runAdExtensionSnippetHeaders(opts) {
   console.log();
 }
 async function runAdExtensionLeadFormCreate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   let cfg;
@@ -114844,6 +115003,7 @@ async function runAdExtensionLeadFormCreate(opts) {
   );
 }
 async function runAdExtensionWhatsappCreate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   if (!opts.configFile) {
@@ -114906,6 +115066,7 @@ function detectExtensionUpdateKind(raw) {
   process.exit(1);
 }
 async function runAdExtensionUpdate(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   let raw;
@@ -114980,6 +115141,7 @@ init_cli_json_snapshot();
 init_strip_legacy_google_fields();
 init_cli_table();
 async function runAdSearchTerms(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const params = new URLSearchParams();
@@ -115108,6 +115270,7 @@ function resolveCriterionId(rows, opts) {
   return String(match.id);
 }
 async function runAdDeviceBidList(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const level = opts.level ?? "campaign";
@@ -115204,6 +115367,7 @@ async function runAdDeviceBidList(opts) {
   console.log();
 }
 async function runAdDeviceBidSet(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const level = opts.level ?? "campaign";
@@ -115334,6 +115498,7 @@ function pickGeoResolveCandidate(query, items2) {
   return items2[0] ?? null;
 }
 async function runAdGeoSearch(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   let items2;
@@ -115406,6 +115571,7 @@ function parseGeoResolveQueries(opts) {
   return unique;
 }
 async function runAdGeoResolve(opts) {
+  opts = withResolvedAdAccount(opts);
   let queries;
   try {
     queries = parseGeoResolveQueries(opts);
@@ -115517,6 +115683,7 @@ async function runAdGeoResolve(opts) {
   }
 }
 async function runAdGeoList(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   let url;
@@ -115580,6 +115747,7 @@ async function runAdGeoList(opts) {
   console.log();
 }
 async function runAdGeoAdd(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const body = {
@@ -115606,6 +115774,7 @@ async function runAdGeoAdd(opts) {
 `);
 }
 async function runAdGeoRemove(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   const body = { campaignId: opts.campaignId, id: opts.locationId };
@@ -115646,6 +115815,7 @@ function resolveGeoCriterionId(rows, opts) {
   return String(match["id"]);
 }
 async function runAdGeoSetBid(opts) {
+  opts = withResolvedAdAccount(opts);
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
   if (opts.bidModifier < 0) {
@@ -116502,11 +116672,12 @@ async function runCampaignBatchDiff(opts) {
 `);
     process.exit(1);
   }
-  const accountId = pickString2(opts.account, cfg.account);
-  if (!accountId) {
+  const rawAccountId = pickString2(opts.account, cfg.account);
+  if (!rawAccountId) {
     console.error("\n\u274C \u7F3A\u5C11\u8D26\u6237 ID\uFF1A\u8BF7\u5728 JSON \u4E2D\u586B\u5199 account \u6216\u4F7F\u7528 -a\n");
     process.exit(1);
   }
+  const accountId = resolveAdAccountId(rawAccountId, "account / -a");
   cfg.account = accountId;
   const config = loadConfig(opts.token);
   let campaignId = pickString2(opts.campaignId);
@@ -118527,14 +118698,7 @@ async function emitPmaxResult(opts, section, commandLabel, payload, idSuffix) {
   });
 }
 function requireAccountId(account, label = "-a, --account") {
-  const id = account?.toString().trim();
-  if (!id) {
-    console.error(`
-\u274C \u8BF7\u6307\u5B9A\u5A92\u4F53\u8D26\u6237 ID\uFF08${label}\uFF09
-`);
-    process.exit(1);
-  }
-  return id;
+  return resolveAdAccountId(account, label);
 }
 
 // src/commands/ad/pmax-video-upload.ts
@@ -118897,7 +119061,8 @@ async function runAdPmaxCreate(opts) {
   }
   const config = await ensureDataPermission(loadConfig(opts.token));
   const googleApiUrl = requireGoogleApi(config);
-  const accountId = cfg.account.toString().trim();
+  const accountId = resolveAdAccountId(cfg.account.toString(), "account");
+  cfg.account = accountId;
   let imageSlots;
   try {
     imageSlots = await resolvePmaxImageSlots(
@@ -122706,6 +122871,7 @@ async function runAccountMe(opts) {
 init_dist();
 init_auth();
 init_cli_json_snapshot();
+init_media_customer_id();
 
 // src/commands/account-manage/google-mcc.ts
 init_auth();
@@ -122881,18 +123047,14 @@ function hintGoogleOAuth(kind) {
   return "\u6267\u884C siluzan-tso account auth -m Google \u5B8C\u6210 OAuth \u7ED1\u5B9A\u3002";
 }
 function assertGoogleMediaCustomerId(raw) {
-  const id = raw.trim();
-  if (!id) {
-    console.error("\n\u274C --account \u4E0D\u80FD\u4E3A\u7A7A\u3002\n");
-    process.exit(1);
-  }
-  if (!/^\d+$/.test(id)) {
-    console.error(
-      "\n\u274C --account \u987B\u4E3A Google mediaCustomerId\uFF08\u7EAF\u6570\u5B57\uFF0C\u4E0E list-accounts -m Google \u4E00\u81F4\uFF09\u3002\n"
-    );
+  try {
+    return requireNumericMediaCustomerId(raw, "--account");
+  } catch (e) {
+    console.error(`
+\u274C ${e instanceof Error ? e.message : String(e)}
+`);
     process.exit(1);
   }
-  return id;
 }
 function parseCustomerAccessPermissionBody(text) {
   const trimmed = text.trim();

package/dist/skill/SKILL.md

@@ -38,7 +38,9 @@ siluzan-tso -h
 
 ## 即时规范
 
-- `entityId`（UUID）≠ `mediaCustomerId`（`list-accounts` 的 `ma.mediaCustomerId`：Google/TikTok/Bing 多为数字；**Yandex=`porg-…`**；Meta 常带 `act_`）。`stats`/`balance`/`accounts-digest` 的 `-a` **只传 mediaCustomerId**；空结果或 verbose 打出 403 时**先核验 ID**，禁止把 UUID/`entityId` 传给 `-a`，也**禁止**据此直接 `reauth`。
+- `entityId`（UUID）≠ `mediaCustomerId`（`list-accounts` 的 `ma.mediaCustomerId`：Google/TikTok/Bing 多为数字；**Yandex=`porg-…`**；Meta 常带 `act_`）。`stats`/`balance`/`accounts-digest`/`ad *` 的 `-a` **只传 mediaCustomerId**；空结果或 verbose 打出 403 时**先核验 ID**，禁止把 UUID/`entityId` 传给 `-a`，也**禁止**据此直接 `reauth`。
+- **Google CID 特殊性**：UI 常写 `123-456-7890`（带连字符），平台 `mediaCustomerId` 为纯数字 `1234567890`。CLI 会自动去连字符；**勿**把带横杠 403 误判为 OAuth 失效。优先用 `list-accounts` 的纯数字 ID。
+- **禁止臆测授权过期**：见 403/`HTTP 403`/拉数失败/「可能 OAuth 失效」时，**禁止**口头推断授权过期或直接 `reauth`。须先核验 ID（及 Google 连字符），再跑 `account check-access -a <mediaCustomerId>`（套餐已激活前提下），以返回的 `accessible` / `reauth_required` / `no_permission` 为准；细则见 `accounts-permissions.md`。
 - `list-accounts` 无余额/消耗；列全部用 `--page-size 999`。
 - 多户余额用 `balance-scan`（P2），多户消耗用 `accounts-digest`（P3）；禁止外层 for-loop 逐户拉数。
 - `stats` 的 `spend` = **区间合计**，不是日消耗。

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.43-beta.1",
-  "publishedAt": 1785983688138
+  "version": "1.1.43-beta.3",
+  "publishedAt": 1785999491310
 }

package/dist/skill/assets/google-period-report.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "siluzan-tso/google-period-report.schema.json",
   "title": "GooglePeriodReport",
-  "description": "Google Ads 周期分析报告 JSON（对齐 google-period-report.md 8 默认维度；供 google-analysis render 注入 HTML）。Agent 只需撰写 narrative 字段，kpis/charts/tables 可省略由 --snapshot-dir 从 google-analysis 落盘快照自动合并。",
+  "description": "Google Ads 周期分析报告 JSON（对齐 google-period-report.md 8 默认维度；供 google-analysis render 注入 HTML）。Agent 只需撰写 narrative；kpis/charts/tables 由 --snapshot-dir 从 google-analysis 快照合并。render 校验要求合并后 kpis.cost/impressions/clicks 至少一项为有效数字，否则拒绝出 HTML（避免执行摘要卡片全「—」）。",
   "type": "object",
   "required": ["meta", "narrative"],
   "properties": {
@@ -21,7 +21,7 @@
     },
     "kpis": {
       "type": "object",
-      "description": "账户级 KPI（执行摘要 KPI 网格）；可省略，由 --snapshot-dir 从 overview 合并",
+      "description": "账户级 KPI（执行摘要 KPI 网格）；Agent 可省略，但 render 时须经 --snapshot-dir 合并出 cost/impressions/clicks",
       "properties": {
         "cost": { "type": "number" },
         "impressions": { "type": "number" },

package/dist/skill/references/accounts/accounts-permissions.md

@@ -35,7 +35,9 @@ siluzan-tso account me --check-phone 15130150466 --json-out ./snap-me
 
 校验当前丝路赞凭据是否对指定 **Google** 广告账户有访问权限。应在拉数/诊断前调用，避免误用他户 ID。
 
-**前提（查授权是否过期时）**：须先确认该户 **套餐已激活**（`list-accounts` 的 `ma.scopeActivatedSources` 有未过期条目，或 Google 表格「套餐激活」= ✅ 已激活）。在已激活前提下，可用本命令检查授权是否可用：
+> **硬约束**：**禁止**凭 403、空结果或经验臆测「授权/OAuth 过期」。要对用户下「授权不可用 / 需重授权」结论前，**必须**先跑本命令（并满足下方套餐已激活前提），以 CLI 返回的 `status` 为准；**禁止**跳过本命令直接 `reauth` 或口头推断。
+
+**前提（查授权是否过期时）**：须先确认该户 **套餐已激活**（`list-accounts` 的 `ma.scopeActivatedSources` 有未过期条目，或 Google 表格「套餐激活」= ✅ 已激活）。在已激活前提下，**必须**用本命令检查授权是否可用：
 
 | 结果 | 含义（套餐已激活时） |
 | ---- | -------------------- |

package/dist/skill/references/accounts/accounts.md

@@ -19,6 +19,8 @@
 - `list-accounts` **不含**余额/消耗；列全部账户用 `--page-size 999`，禁止默认 20 再翻页。
 - `entityId`（UUID，分享/delink/账单/`reauth`）≠ `mediaCustomerId`（`balance`/`stats`/`accounts-digest`/`ad` 的 `-a`）。**Yandex 的 mediaCustomerId 形如 `porg-…`，不是 UUID。**
 - MetaAd OAuth 户的 `mediaCustomerId` **须带 `act_` 前缀**。
-- `stats`/`balance` 空结果 + verbose `HTTP 403`：先确认 `-a` 是否为 `ma.mediaCustomerId`；**禁止**把 `entityId` / tokenId 当 `-a`，也**禁止**未确认 `invalidOAuthToken=true` 就 `reauth`。
+- **Google CID**：广告后台展示常为 `XXX-XXX-XXXX`（连字符），`list-accounts` / 网关要的是**纯数字**（无横杠）。`stats`/`balance`/`ad *`/`google-analysis` 的 `-a` 可带连字符（CLI 会去掉）；若仍见 `HTTP 403：123-456-7890` 这类**回显带横杠 ID**，优先改成纯数字重试，**不要**直接当 OAuth 失效去 `reauth`。
+- **禁止臆测授权过期**：403 / 拉数失败时**禁止**口头说「可能授权过期」。须 ID 核验后，对 Google 在套餐已激活前提下执行 `account check-access -a <mediaCustomerId>`，以返回 `status` 为准（见 [`accounts-permissions.md`](accounts-permissions.md)）；非 Google 看 `list-accounts` 的 `invalidOAuthToken`。
+- `stats`/`balance` 空结果 + verbose `HTTP 403`：先确认 `-a` 是否为 `ma.mediaCustomerId`（且 Google 已去连字符）；**禁止**把 `entityId` / tokenId 当 `-a`；未跑 `account check-access`（或未见 `invalidOAuthToken=true`）**禁止** `reauth`。
 - 多账户余额预警用 `balance-scan`（P2），多账户消耗汇总用 `accounts-digest`（P3）；**禁止**外层 for-loop 逐户 `balance`/`stats`。
 - `stats` 默认 `spend` = **区间合计**，不是日消耗；日均看 `balance-scan.dailySpend` 或合计÷天数。

package/dist/skill/references/core/agent-conventions.md

@@ -126,7 +126,8 @@
 
 - **账户状态 ≠ 系列状态**：`stats` / `balance` / `list-accounts` 的 `status` 只表示账户是否可用；系列状态必须来自 `ad campaigns`。
 - **数据时效性**：涉及「今天/当天/今日消耗」「实时消耗排行」前，必读 `references/analytics/account-analytics.md` 顶部「数据时效性」表。TikTok / Yandex / BingV2 / Kwai 是 `accountsoverview` 同步昨天数据，**不能查今天**。
-- **先查账户再操作**（拉数 / 改账户 / 报告 / **创建广告**）：`list-accounts -m [mediaType] -k [mediaCustomerId]`；用户给出的 `mediaCustomerId` 必须 `-k` 核验，无结果则告知用户并停止，**禁止**翻页 grep 自行换 ID（会导致报告错户）；拉数、脚本、报告文件名全链路用同一 ID（以 stdout `accountId` 为准）。**Google 额外建议**：`list-accounts` 命中后，若 `scopeActivatedSources` 显示套餐**已激活**，拉数前可用 `account check-access -a <mediaCustomerId>` 检查授权是否仍可用（`reauth_required` / `no_permission`）；**未激活套餐时勿用 check-access 判断授权过期**。`no_permission`（403）也可能表示账户不在当前丝路赞账号下。详见 `accounts-permissions.md`。
+- **先查账户再操作**（拉数 / 改账户 / 报告 / **创建广告**）：`list-accounts -m [mediaType] -k [mediaCustomerId]`；用户给出的 `mediaCustomerId` 必须 `-k` 核验，无结果则告知用户并停止，**禁止**翻页 grep 自行换 ID（会导致报告错户）；拉数、脚本、报告文件名全链路用同一 ID（以 stdout `accountId` 为准）。
+- **禁止臆测授权过期（硬约束）**：任何 403、空结果、「可能授权/OAuth 过期」话术，**禁止**凭感觉下结论或直接 `reauth`。Google：在 `list-accounts` 确认套餐**已激活**后，**必须**执行 `account check-access -a <mediaCustomerId>`，仅当结果为 `reauth_required`（或列表 `invalidOAuthToken=true` 与之交叉确认）才谈重授权；`no_permission` 也可能是账户不在当前丝路赞账号下。**未激活套餐时勿用 check-access 判断授权过期**。非 Google 媒体以 `list-accounts` 的 `invalidOAuthToken` 为准，同样禁止臆测。详见 `accounts-permissions.md`。
 - **一律走 CLI，禁止自拼网关请求**：查余额 / 拉数 / 写操作只用 `siluzan-tso …`。**禁止**用 curl、自写脚本或改请求头直连 TSO/Google 网关「另辟蹊径」取数；`balance` 等无数据时按 CLI/`list-accounts` 字段向用户说明（如套餐未激活、授权失效），**禁止**尝试任何绕过平台门禁的取数方式。
 - **W3 仅出方案例外（覆盖上条）**：用户只要「投放方案 / 规划 / 表格 / 先别创建·开户·投钱」，或未给账户且未要求创建/发布时——**禁止**把「请先提供 Google 广告账户」当作第一步；按 `google-ads-campaign-plan.md` §「仅出方案 vs 创建」落盘 JSON 后 **写代码**投影完整审查稿（默认 MD；用户指定则 Excel 等；`account`=`[PENDING_ACCOUNT]`），跳过 `list-accounts` / `geo resolve` / validate / create。**禁止**只交概览表。用户确认要创建后再要账户并续跑创建流水线。
 - **W3 审查稿（搜索与 PMax）**：JSON 落盘后、创建前，必须 **写代码**读取 JSON，按 `google-ads-launch-plan-template.md`（搜索）或 `google-ads-pmax-launch-plan-template.md`（PMax）生成完整审查文件交给用户；须含全部关键词/RSA 或全部 PMax 文案与附加资产。**禁止**用「方案总结」条数勾选代替。用户要求其他格式时改脚本输出，数据仍只从 JSON 来。
@@ -276,7 +277,7 @@
 
 - **400**：参数错误，查看对应 reference 或 `-h`
 - **401 / OAuth 失效**：仅当 `list-accounts` 的 `invalidOAuthToken=true`（或表格「授权状态」为失效）且用户确认后——Siluzan Agent **优先**用平台重新授权工具（如 `present_reauth`）；备选 `account reauth -m <媒体> --id <entityId> --i-confirm --commit "…"`（内置 delink→OAuth，见 W9 / `accounts-permissions.md`）。走 CLI 时**必须把 stdout 中的完整授权 URL 原样贴给用户**，禁止只说「链接已生成」，也**禁止**自行改写/补全该 URL。解绑后若列表已无该户，恢复用平台授权工具或 `account auth -m <媒体>`。**丝路赞登录凭据失效** → `send-login-code` + `login --phone --code`，见 `references/core/setup.md`
-- **403（拉数空结果）**：`stats`/`balance`/`accounts-digest` 在 `--verbose` 下打出异常被吞的 `HTTP 403` 且无数据时：① **优先核验 `-a` 是否为 `ma.mediaCustomerId`**（勿传 `entityId`/UUID；Yandex 形如 `porg-…`）；② Google 再看套餐是否激活（`scopeActivatedSources`），未激活则说明需先激活，**禁止**非 CLI 绕过取数；③ **禁止**在 `invalidOAuthToken=false` 时把 403 当成 OAuth 过期并自行 `reauth`。
+- **403（拉数空结果 / ad 网关）**：① **优先核验 `-a` 是否为 `ma.mediaCustomerId`**（勿传 `entityId`/UUID；Google 注意连字符 CID；Yandex 形如 `porg-…`）；② Google 看套餐是否激活（`scopeActivatedSources`），未激活则说明需先激活，**禁止**非 CLI 绕过取数；③ **禁止臆测授权过期**：套餐已激活时**必须**跑 `account check-access -a <mediaCustomerId>`，以 `status` 为准后再决定是否 `reauth`；**禁止**仅凭 403 文案对用户说「授权过期」。
 - **500**：服务可能正在部署/升级，建议反馈 Siluzan 相关人员
 
 ---

package/dist/skill/references/google-ads/google-ads-read.md

@@ -26,12 +26,14 @@
 
 | 需要的 ID           | 获取命令                                                                |
 | ------------------- | ----------------------------------------------------------------------- |
-| `accountId`（`-a`） | `siluzan-tso list-accounts --json-out ./snap` → `mediaCustomerId`       |
+| `accountId`（`-a`） | `siluzan-tso list-accounts -m Google --json-out ./snap` → `mediaCustomerId`（**纯数字**；UI 的 `123-456-7890` 可原样传入，CLI 去连字符） |
 | 广告系列 `id`       | `siluzan-tso ad campaigns -a <accountId> --json-out ./snap` → `id`      |
 | 广告组 `id`、`name` | `siluzan-tso ad groups -a <accountId> --json-out ./snap` → `id`、`name` |
 | 广告 `id`           | `siluzan-tso ad list -a <accountId> --json-out ./snap` → `id`           |
 | 关键词 `id`         | `siluzan-tso ad keywords -a <accountId> --json-out ./snap` → `id`       |
 
+> **Google CID**：带连字符进网关曾导致 `HTTP 403：123-456-7890`；现 CLI 已归一化。仍失败时用纯数字重试；**禁止臆测授权过期**，须 `account check-access -a <mediaCustomerId>`（详见 [google-ads.md](google-ads.md) Gotchas / `accounts-permissions.md`）。
+
 ---
 
 ## ad campaigns — 广告系列管理

package/dist/skill/references/google-ads/google-ads-write.md

@@ -32,7 +32,7 @@
 
 | 需要的 ID           | 获取命令                                                                |
 | ------------------- | ----------------------------------------------------------------------- |
-| `accountId`（`-a`） | `siluzan-tso list-accounts --json-out ./snap` → `mediaCustomerId`       |
+| `accountId`（`-a`） / JSON `account` | `list-accounts -m Google` → `mediaCustomerId`（纯数字；UI 带连字符 CID 可传入，CLI 去横杠，见 [google-ads.md](google-ads.md) Gotchas） |
 | 广告系列 `id`       | `siluzan-tso ad campaigns -a <accountId> --json-out ./snap` → `id`      |
 | 广告组 `id`、`name` | `siluzan-tso ad groups -a <accountId> --json-out ./snap` → `id`、`name` |
 | 广告 `id`           | `siluzan-tso ad list -a <accountId> --json-out ./snap` → `id`           |

package/dist/skill/references/google-ads/google-ads.md

@@ -15,6 +15,10 @@
 
 ## Gotchas
 
+- **Google 客户 ID（CID）带连字符**：UI / 用户口述常为 `123-456-7890`，平台 `mediaCustomerId` 与 Google 网关路径需要 `1234567890`。`ad campaigns` / `ad groups` / `ad list` 等 `-a` 与 JSON 顶层 `account` **可带连字符**（CLI 自动去掉）。若错误为 `HTTP 403：123-456-7890`（回显带横杠），先换纯数字重试，**禁止**据此直接判断 OAuth 过期或 `reauth`。
+- **禁止臆测授权过期**：`ad *` / 拉数出现 403 或失败时，**禁止**对用户说「授权可能过期」。须核验 ID 后，在套餐已激活前提下执行 `account check-access -a <mediaCustomerId>`，仅当 `reauth_required`（或与 `invalidOAuthToken=true` 交叉确认）才走重授权。见 [`accounts-permissions.md`](../accounts/accounts-permissions.md)。
+- `-a` 必须是 `list-accounts -m Google` 的 `ma.mediaCustomerId`，**禁止**传 `entityId`（UUID）。
+
 ## 金额单位（全局重要）
 
 > **所有 CLI 金额参数均按「主币种金额」传入**（如 `1.5` = ¥1.50 / $1.50）；CLI 写入网关前对「分」字段 ×100（含 `ad keyword-edit --max-cpc` → `maxCPC`）。

package/dist/skill/references/report-templates/google-period-report.md

@@ -15,7 +15,7 @@
 | ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **1. 拉数**      | Agent 调 CLI | `google-analysis -a <id> --start <s> --end <e> --json-out ./snap-google --sections <见下方默认维度对应 CLI>`                                                               |
 | **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），完成筛选、聚合、排序与洞察                                                                              |
-| **3. 写 JSON**   | Agent        | 按 `assets/google-period-report.schema.json` 撰写 `google-period-report.json`：仅 `meta` + `narrative`（8 维度叙事）为必填，`kpis`/`charts`/`tables` 可省略由 CLI 自动合并 |
+| **3. 写 JSON**   | Agent        | 按 `assets/google-period-report.schema.json` 撰写 `google-period-report.json`：只写 `meta` + `narrative`（8 维度叙事）；`kpis`/`charts`/`tables` 留给步骤 4 的 `--snapshot-dir` 合并（合并后缺 KPI 会拒绝出 HTML） |
 | **4. 渲染 HTML** | CLI          | `google-analysis render` — **校验 narrative 8 维度必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML                                                           |
 
 ```bash
@@ -33,7 +33,7 @@ siluzan-tso google-analysis render \
 `google-period-report.json` 顶层结构：
 
 - `meta`：`accountId`（必填）/ `accountName` / `currency` / `startDate` / `endDate`；可省略由 `--snapshot-dir` 从 `overview` + manifest 自动合并。
-- `kpis`：账户级 KPI（消耗/展示/点击/转化/CTR/CPC/CPA，含可选 `previousPeriod` 环比）；可省略。本期 KPI 由 CLI 优先对 `campaigns` 全系列累加并重算比率（规避 overview/stats 相对 Google API 延迟）；无 campaigns 快照时回退 `overview.currentPeriod`。环比仍来自 `overview.previousPeriod`。
+- `kpis`：账户级 KPI（消耗/展示/点击/转化/CTR/CPC/CPA，含可选 `previousPeriod` 环比）；Agent 可省略，但 **render 合并后** `cost`/`impressions`/`clicks` 至少一项须为有效数字，否则拒绝出 HTML（避免执行摘要卡片全「—」）。本期 KPI 由 CLI 优先对 `campaigns` 全系列累加并重算比率；无 campaigns 时回退 `overview.currentPeriod`，再回退 `dimension-summary`。环比仍来自 `overview.previousPeriod`。
 - `charts.dailyTrend`：每日趋势（`dates`/`cost`/`conversions`/`cpa`）；可省略由 `daily-metrics` 自动合并。
 - `tables.{dimensionSummary,campaigns,devices,geographic,keywords}`：对应 §3～§7 表格数据；可省略由同名 `google-analysis` section 自动合并。
 - `narrative`（**Agent 必填，唯一由 Agent 撰写的内容**）：
@@ -53,7 +53,7 @@ siluzan-tso google-analysis render \
 模板源码：`report-templates/google-period-report.html`（结构与样式，ECharts 渲染逻辑已内联）。
 
 `render` 会向输出目录写入 HTML，并注入 `window.__GOOGLE_PERIOD_REPORT__`。  
-传 `--snapshot-dir` 时 CLI 自动从快照合并 KPI、每日趋势图表、周期汇总/系列/设备/地域/关键词表格：**数值一律以 CLI 快照覆盖**（`meta` 仅补空）。本期 KPI 优先 `campaigns` 累加；Agent 只写 `narrative`，勿自填 `kpis`/`tables`。
+传 `--snapshot-dir` 时 CLI 自动从快照合并 KPI、每日趋势图表、周期汇总/系列/设备/地域/关键词表格：**数值一律以 CLI 快照覆盖**（`meta` 仅补空）。本期 KPI 优先 `campaigns` 累加。若 manifest 缺条目但磁盘上仍有对应 `*.json`，CLI 会按文件名自愈补齐。Agent 只写 `narrative`，勿自填 `kpis`/`tables`。
 
 ---
 

package/dist/skill/report-templates/google-period-report.md

@@ -15,7 +15,7 @@
 | ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **1. 拉数**      | Agent 调 CLI | `google-analysis -a <id> --start <s> --end <e> --json-out ./snap-google --sections <见下方默认维度对应 CLI>`                                                               |
 | **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），完成筛选、聚合、排序与洞察                                                                              |
-| **3. 写 JSON**   | Agent        | 按 `assets/google-period-report.schema.json` 撰写 `google-period-report.json`：仅 `meta` + `narrative`（8 维度叙事）为必填，`kpis`/`charts`/`tables` 可省略由 CLI 自动合并 |
+| **3. 写 JSON**   | Agent        | 按 `assets/google-period-report.schema.json` 撰写 `google-period-report.json`：只写 `meta` + `narrative`（8 维度叙事）；`kpis`/`charts`/`tables` 留给步骤 4 的 `--snapshot-dir` 合并（合并后缺 KPI 会拒绝出 HTML） |
 | **4. 渲染 HTML** | CLI          | `google-analysis render` — **校验 narrative 8 维度必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML                                                           |
 
 ```bash
@@ -33,7 +33,7 @@ siluzan-tso google-analysis render \
 `google-period-report.json` 顶层结构：
 
 - `meta`：`accountId`（必填）/ `accountName` / `currency` / `startDate` / `endDate`；可省略由 `--snapshot-dir` 从 `overview` + manifest 自动合并。
-- `kpis`：账户级 KPI（消耗/展示/点击/转化/CTR/CPC/CPA，含可选 `previousPeriod` 环比）；可省略。本期 KPI 由 CLI 优先对 `campaigns` 全系列累加并重算比率（规避 overview/stats 相对 Google API 延迟）；无 campaigns 快照时回退 `overview.currentPeriod`。环比仍来自 `overview.previousPeriod`。
+- `kpis`：账户级 KPI（消耗/展示/点击/转化/CTR/CPC/CPA，含可选 `previousPeriod` 环比）；Agent 可省略，但 **render 合并后** `cost`/`impressions`/`clicks` 至少一项须为有效数字，否则拒绝出 HTML（避免执行摘要卡片全「—」）。本期 KPI 由 CLI 优先对 `campaigns` 全系列累加并重算比率；无 campaigns 时回退 `overview.currentPeriod`，再回退 `dimension-summary`。环比仍来自 `overview.previousPeriod`。
 - `charts.dailyTrend`：每日趋势（`dates`/`cost`/`conversions`/`cpa`）；可省略由 `daily-metrics` 自动合并。
 - `tables.{dimensionSummary,campaigns,devices,geographic,keywords}`：对应 §3～§7 表格数据；可省略由同名 `google-analysis` section 自动合并。
 - `narrative`（**Agent 必填，唯一由 Agent 撰写的内容**）：
@@ -53,7 +53,7 @@ siluzan-tso google-analysis render \
 模板源码：`report-templates/google-period-report.html`（结构与样式，ECharts 渲染逻辑已内联）。
 
 `render` 会向输出目录写入 HTML，并注入 `window.__GOOGLE_PERIOD_REPORT__`。  
-传 `--snapshot-dir` 时 CLI 自动从快照合并 KPI、每日趋势图表、周期汇总/系列/设备/地域/关键词表格：**数值一律以 CLI 快照覆盖**（`meta` 仅补空）。本期 KPI 优先 `campaigns` 累加；Agent 只写 `narrative`，勿自填 `kpis`/`tables`。
+传 `--snapshot-dir` 时 CLI 自动从快照合并 KPI、每日趋势图表、周期汇总/系列/设备/地域/关键词表格：**数值一律以 CLI 快照覆盖**（`meta` 仅补空）。本期 KPI 优先 `campaigns` 累加。若 manifest 缺条目但磁盘上仍有对应 `*.json`，CLI 会按文件名自愈补齐。Agent 只写 `narrative`，勿自填 `kpis`/`tables`。
 
 ---
 

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