siluzan-tso-cli 1.1.15-beta.4 → 1.1.15-beta.6

package/README.md

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

package/assets/siluzan-ads/references/hosted-automation-user-catalog.md

@@ -21,10 +21,10 @@
 | 功能名称          | 监控层级 / 说明 | CLI 检查入口（`--json`） |
 | ----------------- | --------------- | ------------------------ |
 | 1. 账户被封禁     | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 [`accounts.md`](accounts.md) |
-| 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis final-urls`**；或 **`ad list`** / **`google-analysis ads`** 取落地页字段后由宿主 HTTP 校验 |
-| 3. 广告素材拒审   | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **[`google-ads.md`](google-ads.md)**） |
-| 4. 花费异动监控   | 系列或账户维度花费相对历史异常波动。 | **`google-analysis campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
-| 5. 余额枯竭预警   | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
+| 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis --sections final-urls`**；或 **`ad list`** / **`google-analysis --sections ads`** 取落地页字段后由宿主 HTTP 校验 |
+| 3. 广告素材拒审   | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis --sections ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **[`google-ads.md`](google-ads.md)**） |
+| 4. 花费异动监控   | 系列或账户维度花费相对历史异常波动。 | **`google-analysis --sections campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
+| 5. 余额枯竭预警   | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis --sections overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
 
 ## 自动优化
 

package/dist/index.js

@@ -3538,6 +3538,10 @@ async function writeGoogleAnalysisSnapshot(params) {
   const writtenAt = (/* @__PURE__ */ new Date()).toISOString();
   const body = JSON.stringify(params.payload, null, 2);
   await fs4.writeFile(path6.join(absDir, fileName), `${body}
+`, "utf8");
+  const outlineFileName = snapshotOutlineFileName(fileName);
+  const outlineBody = formatOutlineFileBody(fileName, params.payload);
+  await fs4.writeFile(path6.join(absDir, outlineFileName), `${outlineBody}
 `, "utf8");
   const existing = await readManifestIfExists(absDir, accountSlug || void 0);
   const newArtifact = {
@@ -3564,8 +3568,10 @@ async function writeGoogleAnalysisSnapshot(params) {
     schemaVersion: SCHEMA_VERSION,
     absoluteSnapshotDir: absDir,
     manifestFile,
-    writtenFiles: [fileName],
-    section: params.section
+    writtenFiles: [fileName, outlineFileName],
+    section: params.section,
+    outlineFile: outlineFileName,
+    agentHint: OUTLINE_AGENT_HINT
   };
 }
 
@@ -3573,6 +3579,7 @@ async function writeGoogleAnalysisSnapshot(params) {
 var CLI_SNAPSHOT_MANIFEST_FILE = "cli-manifest.json";
 var CLI_PACKAGE2 = "siluzan-tso-cli";
 var SCHEMA_VERSION2 = 1;
+var OUTLINE_AGENT_HINT = "\u5904\u7406\u987A\u5E8F\uFF1A\u5148\u8BFB outlineFile\uFF08schema \u63CF\u8FF0\uFF0C\u975E\u6570\u636E\uFF09\u4E86\u89E3\u5B57\u6BB5\u7C7B\u578B\uFF0C\u518D\u7528\u811A\u672C\u8BFB writtenFiles[0]\uFF08\u771F\u5B9E JSON \u6570\u636E\uFF09\u505A\u7B5B\u9009/\u805A\u5408\uFF1B\u4E0D\u8981\u628A outline \u5F53\u6210\u6570\u636E\uFF0C\u4E5F\u4E0D\u8981\u628A JSON \u5F53\u6210 schema\u3002";
 var DEFAULT_FIELD_GUIDE2 = {
   markdownRefs: ["references/tips.md", "references/accounts.md"]
 };
@@ -3706,9 +3713,18 @@ function snapshotOutlineFileName(jsonBasename) {
   }
   return `${jsonBasename.slice(0, -".json".length)}.outline.txt`;
 }
+function formatOutlineFileBody(jsonBasename, payload) {
+  const typeText = describePayloadTsLike(payload);
+  const lines = [
+    `// outline of \`${jsonBasename}\` \u2014 schema-only, NOT the data.`,
+    `// \u7528\u6CD5\uFF1A\u5904\u7406\u540C\u76EE\u5F55 \`${jsonBasename}\` \u7684\u6570\u636E\u524D\uFF0C\u5148\u8BFB\u672C\u6587\u4EF6\u4E86\u89E3\u5B57\u6BB5\u7C7B\u578B\uFF0C\u518D\u7528\u811A\u672C\uFF08fs.readFileSync / require\uFF09\u8BFB\u53D6\u8BE5 JSON \u505A\u7B5B\u9009\u4E0E\u805A\u5408\u3002`,
+    `// \u7C7B\u578B\u7531 JSON \u63A8\u65AD\uFF1A\u6570\u7EC4\u53D6\u524D 8 \u9879\u53BB\u91CD\u5E76\u96C6\uFF1B\u73AF\u6216\u91CD\u590D\u5BF9\u8C61\u5F15\u7528\u8BB0\u4E3A any\u3002`,
+    typeText
+  ];
+  return lines.join("\n");
+}
 async function writeCliJsonSnapshot(params) {
   const trimmed = params.snapshotDir.trim();
-  const outlineText = describePayloadTsLike(params.payload);
   const idSlug = slugifyIdSuffix(params.idSuffix);
   const manifestFile = cliManifestFileName(idSlug || void 0);
   let absDir;
@@ -3744,7 +3760,8 @@ async function writeCliJsonSnapshot(params) {
   if (outlineFileName.toLowerCase() === manifestFile.toLowerCase()) {
     throw new Error(`\u975E\u6CD5\u8F93\u51FA\uFF1A${outlineFileName} \u4E0E\u6E05\u5355\u6587\u4EF6\u540D\u51B2\u7A81`);
   }
-  await fs5.writeFile(path7.join(absDir, outlineFileName), `${outlineText}
+  const outlineBody = formatOutlineFileBody(fileName, params.payload);
+  await fs5.writeFile(path7.join(absDir, outlineFileName), `${outlineBody}
 `, "utf8");
   const existing = await readCliManifestIfExists(absDir, idSlug || void 0);
   const newArtifact = {
@@ -3770,7 +3787,8 @@ async function writeCliJsonSnapshot(params) {
     manifestFile,
     writtenFiles: [fileName, outlineFileName],
     section,
-    outlineFile: outlineFileName
+    outlineFile: outlineFileName,
+    agentHint: OUTLINE_AGENT_HINT
   };
 }
 async function emitCliJsonOrSnapshot(opts, params) {
@@ -6429,7 +6447,7 @@ async function writeReportAnalysisSnapshot(params) {
   );
   await fs8.writeFile(
     path11.join(absDir, outlineFileName),
-    `${describePayloadTsLike(params.payload)}
+    `${formatOutlineFileBody(fileName, params.payload)}
 `,
     "utf8"
   );
@@ -6459,7 +6477,8 @@ async function writeReportAnalysisSnapshot(params) {
     manifestFile,
     writtenFiles: [fileName, outlineFileName],
     section: params.section,
-    outlineFile: outlineFileName
+    outlineFile: outlineFileName,
+    agentHint: OUTLINE_AGENT_HINT
   };
 }
 
@@ -7305,22 +7324,6 @@ function manifestDateRange(def, start, end) {
   const { startDate, endDate } = resolveDateRange(start, end);
   return { mode: "range", start: startDate, end: endDate };
 }
-function summarizeHuman(section, data) {
-  if (data === null || data === void 0) return "\u65E0\u6570\u636E";
-  if (Array.isArray(data)) return `\u6570\u7EC4\uFF0C\u5171 ${data.length} \u6761`;
-  if (typeof data === "object") {
-    const o = data;
-    if (Array.isArray(o.keywords)) return `keywords\uFF1A${o.keywords.length} \u6761`;
-    if (Array.isArray(o.campaigns)) return `campaigns\uFF1A${o.campaigns.length} \u6761`;
-    if (Array.isArray(o.devices)) return `devices\uFF1A${o.devices.length} \u6761`;
-    if (Array.isArray(o.countries)) return `countries\uFF1A${o.countries.length} \u6761`;
-    if (Array.isArray(o.audience)) return `audience\uFF1A${o.audience.length} \u6761`;
-    if (Array.isArray(o.data)) return `data\uFF1A${o.data.length} \u6761`;
-    const keys = Object.keys(o);
-    return `\u5BF9\u8C61\uFF0C\u9876\u5C42\u5B57\u6BB5\uFF1A${keys.slice(0, 8).join(", ")}${keys.length > 8 ? "\u2026" : ""}`;
-  }
-  return String(data);
-}
 async function fetchSectionPayload(def, opts, config, id) {
   const extras = {};
   if (def.keywordOptions) {
@@ -7363,63 +7366,6 @@ function endpointHintForSection(def) {
   if (def.name === "materials") return "CampaignAssetView+Videos";
   return endpointHintFrom(def);
 }
-async function runOneSection(def, opts) {
-  const config = loadConfig(opts.token);
-  const id = opts.account.trim();
-  if (!/^\d+$/.test(id)) {
-    console.error("\n\u274C --account \u987B\u4E3A\u6570\u5B57 mediaCustomerId\u3002\n");
-    process.exit(1);
-  }
-  if (opts.json && opts.jsonOut) {
-    console.error(
-      "\n\u274C --json \u4E0E --json-out \u4E0D\u80FD\u540C\u65F6\u4F7F\u7528\u3002\n"
-    );
-    process.exit(1);
-  }
-  try {
-    const payload = await fetchSectionPayload(def, opts, config, id);
-    if (opts.json) {
-      console.log(JSON.stringify(payload, null, 2));
-      return;
-    }
-    if (opts.jsonOut) {
-      const summary = await writeGoogleAnalysisSnapshot({
-        snapshotDir: opts.jsonOut,
-        section: def.name,
-        accountId: id,
-        dateRange: manifestDateRange(def, opts.start, opts.end),
-        payload,
-        cliVersion: getCurrentVersion2(),
-        endpointHint: endpointHintForSection(def)
-      });
-      console.log(JSON.stringify(summary));
-      return;
-    }
-    if (def.name === "materials") {
-      const m = payload;
-      const iLen = Array.isArray(m.images) ? m.images.length : 0;
-      const vLen = Array.isArray(m.videos) ? m.videos.length : 0;
-      console.log(
-        `
-\u2705 google-analysis materials \u8D26\u6237 ${id}
-   \u56FE\u7247\u7D20\u6750\uFF1A${iLen} \u6761\uFF0C\u89C6\u9891\u7D20\u6750\uFF1A${vLen} \u6761\uFF08\u5B8C\u6574\u6570\u636E\u8BF7\u52A0 --json-out <\u76EE\u5F55>\uFF09
-`
-      );
-      return;
-    }
-    console.log(
-      `
-\u2705 google-analysis ${def.name} \u8D26\u6237 ${id}
-   ${summarizeHuman(def.name, payload)}
-`
-    );
-  } catch (err) {
-    console.error(`
-\u274C \u8BF7\u6C42\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
-`);
-    process.exit(1);
-  }
-}
 function resolveSectionList(sections, exclude) {
   const allNames = SECTIONS.map((s) => s.name);
   const splitClean = (s) => (s ?? "").split(",").map((x) => x.trim()).filter(Boolean);
@@ -7523,13 +7469,15 @@ async function runAllSections(opts) {
   if (failed > 0) process.exit(2);
 }
 function registerGoogleAnalysisCommands(program2) {
-  const root = program2.command("google-analysis").description("Google \u8D26\u6237\u5206\u6790\u7F51\u5173\uFF08googleApiUrl\uFF09\uFF1A\u6309\u7EF4\u5EA6\u62C9\u53D6\u62A5\u8868/\u7ED3\u6784\u6570\u636E");
-  root.command("all").description(
-    "\u5355\u8FDB\u7A0B\u6279\u91CF\u62C9\u53D6\u6240\u6709\u7EF4\u5EA6\uFF08\u9ED8\u8BA4 21 \u4E2A\uFF09\uFF1A\u590D\u7528\u8FDB\u7A0B + keep-alive\uFF0C\u6BD4\u9010\u4E2A\u8C03\u7528\u5FEB 3-7x"
-  ).requiredOption("-a, --account <id>", "Google mediaCustomerId").requiredOption(
+  program2.command("google-analysis").description(
+    "Google \u8D26\u6237\u5206\u6790\uFF08googleApiUrl\uFF09\uFF1A\u5355\u8FDB\u7A0B\u6279\u91CF\u62C9\u53D6\u4E00\u4E2A\u6216\u591A\u4E2A\u7EF4\u5EA6\uFF0C\u81EA\u52A8\u590D\u7528 keep-alive \u8FDE\u63A5"
+  ).argument("[legacy-section]", "\uFF08\u5DF2\u5E9F\u5F03\uFF09\u5386\u53F2\u7684\u5355\u7EF4\u5EA6\u5B50\u547D\u4EE4\u540D\uFF0C\u8BF7\u6539\u7528 --sections <name>").requiredOption("-a, --account <id>", "Google mediaCustomerId").requiredOption(
     "--json-out <dir>",
-    "\u7ED3\u679C\u843D\u76D8\u76EE\u5F55\uFF1B\u6BCF\u4E2A\u7EF4\u5EA6\u4E00\u4E2A <section>-<accountId>.json\uFF0C\u4E0E manifest-<accountId>.json \u540C\u7EA7"
-  ).option("-t, --token <token>", "Auth Token").option("--start <date>", "\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08range \u7C7B\u7EF4\u5EA6\u751F\u6548\uFF1B\u9ED8\u8BA4\u8FD1 7 \u5929\u622A\u81F3\u6628\u5929\uFF09").option("--end <date>", "\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option(
+    "\u7ED3\u679C\u843D\u76D8\u76EE\u5F55\uFF1B\u6BCF\u7EF4\u5EA6\u4E00\u4E2A <section>-<accountId>.json\uFF0C\u4E0E manifest-<accountId>.json \u540C\u7EA7"
+  ).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(
     "--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 21 \u4E2A"
   ).option(
@@ -7537,35 +7485,48 @@ function registerGoogleAnalysisCommands(program2) {
     "\u6392\u9664\u6307\u5B9A\u7EF4\u5EA6\uFF08\u9017\u53F7\u5206\u9694\uFF09\uFF0C\u5982 materials,gold-account\uFF1B\u4E0E --sections \u53EF\u53E0\u52A0"
   ).option(
     "--concurrency <n>",
-    "\u5E76\u53D1\u6570\uFF0C\u9ED8\u8BA4 5\uFF1B\u4E0A\u9650 16\uFF08\u4E0E http-raw maxSockets \u5BF9\u9F50\uFF09",
+    "\u5E76\u53D1\u6570\uFF0C\u9ED8\u8BA4 5\uFF1B\u4E0A\u9650 16\uFF08\u4E0E http-raw maxSockets \u5BF9\u9F50\uFF09\uFF1B\u8D26\u6237\u5927\u6216\u7F51\u7EDC\u6162\u65F6\u8C03\u5C0F",
     (v) => parseInt(v, 10)
-  ).option("--limit <n>", "keywords/search-terms \u7684\u6761\u6570\u4E0A\u9650", (v) => parseInt(v, 10)).option("--no-order-by-cost", "keywords/search-terms \u4E0D\u6309\u6D88\u8017\u6392\u5E8F", false).option("--level <level>", "extensions \u7684 level \u8FC7\u6EE4").option("--audience-type <type>", "audience \u7684 audienceTypeFilter").option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(async (opts) => {
-    await runAllSections(opts);
-  });
-  for (const def of SECTIONS) {
-    const cmd = root.command(def.name).description(def.description).requiredOption("-a, --account <id>", "Google mediaCustomerId").option("-t, --token <token>", "Auth Token").option("--json", "\u8F93\u51FA\u5B8C\u6574 JSON", false).option(
-      "--json-out <dir>",
-      "\u5C06 JSON \u5199\u5165\u76EE\u5F55\uFF08\u6587\u4EF6\u540D\u5E26 accountId \u540E\u7F00\uFF09\u5E76\u66F4\u65B0 manifest-<accountId>.json\uFF08\u4E0E --json \u4E92\u65A5\uFF09\uFF1Bstdout \u4EC5\u4E00\u884C\u6458\u8981 JSON"
-    ).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false);
-    if (def.dateMode === "range") {
-      cmd.option("--start <date>", "\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08\u4E0E --end \u540C\u4F20\uFF0C\u6216\u5747\u7701\u7565\u7528\u9ED8\u8BA4\u8FD1 7 \u5929\uFF09").option("--end <date>", "\u7ED3\u675F\u65E5\u671F YYYY-MM-DD");
-    }
-    if (def.keywordOptions) {
-      cmd.option("--limit <n>", "\u6761\u6570\u4E0A\u9650\uFF08\u9ED8\u8BA4 100\uFF09", (v) => parseInt(v, 10)).option("--no-order-by-cost", "\u4E0D\u6309\u6D88\u8017\u6392\u5E8F", false);
-    }
-    if (def.extensionLevelOption) {
-      cmd.option(
-        "--level <level>",
-        "\u6309\u5C42\u7EA7\u7B5B\u9009\uFF1AAccount | Campaign | Ad Group\uFF08\u4F20\u5165\u5219\u4F5C\u4E3A\u67E5\u8BE2\u53C2\u6570\uFF09"
+  ).option("--limit <n>", "\u900F\u4F20\u7ED9 keywords / search-terms \u7EF4\u5EA6\u7684\u6761\u6570\u4E0A\u9650", (v) => parseInt(v, 10)).option("--no-order-by-cost", "\u900F\u4F20\uFF1Akeywords / search-terms \u4E0D\u6309\u6D88\u8017\u6392\u5E8F", false).option(
+    "--level <level>",
+    "\u900F\u4F20\u7ED9 extensions \u7EF4\u5EA6\u7684 level \u8FC7\u6EE4\uFF1AAccount | Campaign | Ad Group"
+  ).option(
+    "--audience-type <type>",
+    "\u900F\u4F20\u7ED9 audience \u7EF4\u5EA6\u7684 audienceTypeFilter\uFF1ASystemDefined | UserDefined"
+  ).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).addHelpText(
+    "after",
+    [
+      "",
+      "\u53EF\u7528\u7EF4\u5EA6\uFF0821 \u4E2A\uFF0C\u4E0E --sections / --exclude \u53D6\u503C\u4E00\u81F4\uFF09\uFF1A",
+      ...SECTIONS.map((s) => `  ${s.name.padEnd(20)} ${s.description}`),
+      "",
+      "\u793A\u4F8B\uFF1A",
+      "  # \u62C9\u5168\u90E8 21 \u4E2A\u7EF4\u5EA6",
+      "  siluzan-tso google-analysis -a <mediaCustomerId> --json-out ./snap",
+      "",
+      "  # \u4EC5\u62C9\u5355\u4E2A\u7EF4\u5EA6\uFF08\u66FF\u4EE3\u5386\u53F2\u7684 google-analysis overview ...\uFF09",
+      "  siluzan-tso google-analysis -a <mediaCustomerId> --sections overview --json-out ./snap",
+      "",
+      "  # \u4EC5\u62C9\u62A5\u544A\u9700\u8981\u7684\u5B50\u96C6",
+      "  siluzan-tso google-analysis -a <mediaCustomerId> --start 2026-04-01 --end 2026-04-30 \\",
+      "    --sections overview,daily-metrics,campaigns,devices,geographic,keywords --json-out ./snap"
+    ].join("\n")
+  ).action(async (legacySection, opts) => {
+    if (legacySection) {
+      const sectionNames = SECTIONS.map((s) => s.name);
+      const isKnown = sectionNames.includes(legacySection);
+      const fixHint = isKnown ? `   siluzan-tso google-analysis -a ${opts.account ?? "<id>"} --sections ${legacySection} --json-out <dir>` : `   \u672A\u77E5\u7EF4\u5EA6\u540D"${legacySection}"\u3002\u53EF\u9009\u7EF4\u5EA6\uFF1A${sectionNames.join(", ")}`;
+      console.error(
+        `
+\u274C google-analysis \u5DF2\u4E0D\u518D\u652F\u6301\u5355\u7EF4\u5EA6\u5B50\u547D\u4EE4\uFF08\u66FE\u7ECF\u7684 \`google-analysis ${legacySection} ...\` \u7528\u6CD5\u5DF2\u5220\u9664\uFF09\u3002
+   \u73B0\u5728\u6240\u6709\u7EF4\u5EA6\u90FD\u901A\u8FC7 --sections \u9009\u53D6\uFF0C\u5355\u7EF4\u5EA6\u7B49\u4EF7\u5199\u6CD5\uFF1A
+${fixHint}
+`
       );
+      process.exit(1);
     }
-    if (def.audienceFilterOption) {
-      cmd.option("--audience-type <type>", "audienceTypeFilter\uFF1ASystemDefined | UserDefined");
-    }
-    cmd.action(async (opts) => {
-      await runOneSection(def, opts);
-    });
-  }
+    await runAllSections(opts);
+  });
 }
 
 // src/commands/report-tiktok-analysis.ts