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

package/README.md

@@ -19,8 +19,6 @@
 | 项目            | 说明                                                            |
 | --------------- | --------------------------------------------------------------- |
 | API Key / Token | 存储在 `~/.siluzan/config.json`，用于所有 API 调用鉴权          |
-| TSO API         | `tso-api.siluzan.com`（生产）/ `tso-api-ci.siluzan.com`（测试） |
-| Google API 网关 | `googleapi.mysiluzan.com` / `googleapi-ci.mysiluzan.com`        |
 | 前端页面        | `www.siluzan.com`（充值、激活等浏览器操作）                     |
 | 错误追踪        | `o605862.ingest.us.sentry.io`（匿名崩溃日志）                   |
 | 版本检查        | `registry.npmjs.org`                                            |
@@ -53,7 +51,7 @@ siluzan-tso init -d /path/to/skills  # 写入自定义目录
 siluzan-tso init --force             # 强制覆盖已存在文件
 ```
 
-> **注意**：当前为测试版（1.1.14-beta.1），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+> **注意**：当前为测试版（1.1.14-beta.3），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/index.js

@@ -3676,18 +3676,25 @@ var VALID_MEDIA_TYPES2 = ["Google", "TikTok", "Yandex", "MetaAd", "BingV2", "Kwa
 async function runBalance(opts) {
   const config = loadConfig(opts.token);
   if (!VALID_MEDIA_TYPES2.includes(opts.media)) {
-    console.error(
-      `
-\u274C \u4E0D\u652F\u6301\u7684\u5A92\u4F53\u7C7B\u578B\uFF1A${opts.media}
-   \u53EF\u9009\u503C\uFF1A${VALID_MEDIA_TYPES2.join(" | ")}
-`
-    );
+    const msg = `\u4E0D\u652F\u6301\u7684\u5A92\u4F53\u7C7B\u578B\uFF1A${opts.media}\uFF08\u53EF\u9009\uFF1A${VALID_MEDIA_TYPES2.join(" | ")}\uFF09`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+      process.exit(1);
+    }
+    console.error(`
+\u274C ${msg}
+`);
     process.exit(1);
   }
   const media = opts.media;
   if (!BALANCE_SUPPORTED_MEDIA.includes(media)) {
+    const msg = `${media} \u6682\u4E0D\u652F\u6301\u4F59\u989D\u67E5\u8BE2`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+      process.exit(1);
+    }
     console.error(`
-\u26A0\uFE0F  ${media} \u6682\u4E0D\u652F\u6301\u4F59\u989D\u67E5\u8BE2
+\u26A0\uFE0F  ${msg}
 `);
     process.exit(1);
   }
@@ -3707,8 +3714,13 @@ async function runBalance(opts) {
       opts.verbose
     );
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+      process.exit(1);
+    }
     console.error(`
-\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${message}
 `);
     process.exit(1);
   }
@@ -3948,18 +3960,54 @@ async function runBalanceScan(opts) {
     const CHUNK = 100;
     const chunks = [];
     for (let i = 0; i < validIds.length; i += CHUNK) chunks.push(validIds.slice(i, i + CHUNK));
+    process.stderr.write(
+      `\u23F3 [balance-scan] \u6709\u6548\u8D26\u6237 ${validIds.length} \u4E2A\uFF0C\u5206 ${chunks.length} \u6279\uFF1B\u4F59\u989D\u4E0E\u8FD1 7 \u65E5\u6D88\u8017\u5E76\u884C\u8BF7\u6C42\uFF08\u5355\u8BF7\u6C42\u6700\u957F\u7EA6 10 \u5206\u949F\uFF09\u3002
+`
+    );
+    const logBalanceChunk = (idx, ids, m) => {
+      process.stderr.write(
+        `   \u2713 [\u4F59\u989D] \u7B2C ${idx + 1}/${chunks.length} \u6279\u5B8C\u6210\uFF08${ids.length} \u6237 \u2192 ${m.size} \u6761\uFF09
+`
+      );
+    };
+    const logOverviewChunk = (idx, ids, m) => {
+      process.stderr.write(
+        `   \u2713 [\u8FD17\u65E5\u6D88\u8017] \u7B2C ${idx + 1}/${chunks.length} \u6279\u5B8C\u6210\uFF08${ids.length} \u6237 \u2192 ${m.size} \u6761\uFF09
+`
+      );
+    };
     const [bMaps, oMaps] = await Promise.all([
       Promise.all(
-        chunks.map(
-          (ids) => fetchBalanceMap(media, ids, config, void 0, void 0, opts.verbose)
-        )
+        chunks.map((ids, chunkIdx) => {
+          process.stderr.write(
+            `   \u2192 [\u4F59\u989D] \u7B2C ${chunkIdx + 1}/${chunks.length} \u6279\u8BF7\u6C42\u4E2D\uFF08${ids.length} \u6237\uFF09\u2026
+`
+          );
+          return fetchBalanceMap(media, ids, config, void 0, void 0, opts.verbose).then(
+            (m) => {
+              logBalanceChunk(chunkIdx, ids, m);
+              return m;
+            }
+          );
+        })
       ),
       Promise.all(
-        chunks.map(
-          (ids) => fetchOverviewMap(media, ids, config, void 0, void 0, opts.verbose)
-        )
+        chunks.map((ids, chunkIdx) => {
+          process.stderr.write(
+            `   \u2192 [\u8FD17\u65E5\u6D88\u8017] \u7B2C ${chunkIdx + 1}/${chunks.length} \u6279\u8BF7\u6C42\u4E2D\uFF08${ids.length} \u6237\uFF09\u2026
+`
+          );
+          return fetchOverviewMap(media, ids, config, void 0, void 0, opts.verbose).then(
+            (m) => {
+              logOverviewChunk(chunkIdx, ids, m);
+              return m;
+            }
+          );
+        })
       )
     ]);
+    process.stderr.write(`\u23F3 [balance-scan] \u4F59\u989D\u4E0E\u6D88\u8017\u5DF2\u9F50\uFF0C\u6B63\u5728\u6309\u9608\u503C\u7B5B\u9009\u2026
+`);
     for (const m of bMaps) for (const [k, v] of m) balanceMap.set(k, v);
     for (const m of oMaps) for (const [k, v] of m) overviewMap.set(k, v);
   }
@@ -4382,8 +4430,13 @@ async function runStats(opts) {
   try {
     raw = await apiFetch2(url, config, {}, opts.verbose);
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+      process.exit(1);
+    }
     console.error(`
-\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${message}
 `);
     process.exit(1);
   }
@@ -5131,6 +5184,12 @@ var SECTIONS = [
     dateMode: "range",
     path: (id) => `/reporting/media-account/${id}/CampaignSectionData`
   },
+  {
+    name: "campaign-hour",
+    description: "\u7CFB\u5217\u6309\u5C0F\u65F6 campaign-hour\uFF08Query\uFF1AstartDate\u3001endDate\uFF09",
+    dateMode: "range",
+    path: (id) => `/reporting/media-account/${id}/campaign-hour`
+  },
   {
     name: "ads",
     description: "\u5E7F\u544A\u7EA7\u5217\u8868 admanagement/v2/list",
@@ -5266,6 +5325,55 @@ async function fetchJson(config, pathWithQuery, verbose) {
   const url = `${config.googleApiUrl}${pathWithQuery}`;
   return apiFetch2(url, config, {}, verbose);
 }
+function assertNever(x, ctx) {
+  throw new Error(`${ctx}\uFF1A\u672A\u5904\u7406\u7684\u5206\u652F ${String(x)}`);
+}
+async function fetchGoogleAnalysisSectionJson(config, fullPath, verbose, name) {
+  switch (name) {
+    case "overview":
+      return fetchJson(config, fullPath, verbose);
+    case "keywords":
+      return fetchJson(config, fullPath, verbose);
+    case "search-terms":
+      return fetchJson(config, fullPath, verbose);
+    case "campaigns":
+      return fetchJson(config, fullPath, verbose);
+    case "campaign-hour":
+      return fetchJson(config, fullPath, verbose);
+    case "ads":
+      return fetchJson(config, fullPath, verbose);
+    case "extensions":
+      return fetchJson(config, fullPath, verbose);
+    case "devices":
+      return fetchJson(config, fullPath, verbose);
+    case "geographic":
+      return fetchJson(config, fullPath, verbose);
+    case "audience":
+      return fetchJson(config, fullPath, verbose);
+    case "asset-images":
+      return fetchJson(config, fullPath, verbose);
+    case "videos":
+      return fetchJson(config, fullPath, verbose);
+    case "resource-counts":
+      return fetchJson(config, fullPath, verbose);
+    case "conversion-actions":
+      return fetchJson(config, fullPath, verbose);
+    case "daily-metrics":
+      return fetchJson(config, fullPath, verbose);
+    case "gold-account":
+      return fetchJson(config, fullPath, verbose);
+    case "ads-index":
+      return fetchJson(config, fullPath, verbose);
+    case "final-urls":
+      return fetchJson(config, fullPath, verbose);
+    case "dimension-summary":
+      return fetchJson(config, fullPath, verbose);
+    case "campaign-types":
+      return fetchJson(config, fullPath, verbose);
+    default:
+      return assertNever(name, "google-analysis");
+  }
+}
 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`;
@@ -5336,7 +5444,12 @@ async function runOneSection(def, opts) {
       );
       return;
     }
-    const data = await fetchJson(config, fullPath, !!opts.verbose);
+    const data = await fetchGoogleAnalysisSectionJson(
+      config,
+      fullPath,
+      !!opts.verbose,
+      def.name
+    );
     if (opts.json) {
       console.log(JSON.stringify(stripLegacyGoogleFieldsIfV2Present(data), null, 2));
       return;
@@ -7991,6 +8104,53 @@ async function runAdGroupRename(opts) {
 \u2705 \u5E7F\u544A\u7EC4 ${opts.id} \u5DF2\u6539\u540D\u4E3A\u300C${opts.name}\u300D
 `);
 }
+async function runAdGroupEdit(opts) {
+  const hasName = opts.name !== void 0 && opts.name.trim() !== "";
+  const hasMax = opts.maxCPCAmount !== void 0;
+  const hasTcpa = opts.targetCpaAmount !== void 0;
+  if (!hasName && !hasMax && !hasTcpa) {
+    console.error(
+      "\n\u274C \u8BF7\u81F3\u5C11\u6307\u5B9A\u4E00\u9879\u4FEE\u6539\uFF1A--name / --max-cpc / --target-cpa\n"
+    );
+    process.exit(1);
+  }
+  if (hasMax && (!Number.isFinite(opts.maxCPCAmount) || opts.maxCPCAmount < 0)) {
+    console.error("\n\u274C --max-cpc \u987B\u4E3A\u975E\u8D1F\u6570\u5B57\n");
+    process.exit(1);
+  }
+  if (hasTcpa && (!Number.isFinite(opts.targetCpaAmount) || opts.targetCpaAmount < 0)) {
+    console.error("\n\u274C --target-cpa \u987B\u4E3A\u975E\u8D1F\u6570\u5B57\n");
+    process.exit(1);
+  }
+  const config = loadConfig(opts.token);
+  const googleApiUrl = requireGoogleApi(config);
+  const listUrl = adgroupListUrl(googleApiUrl, opts.account, opts.startDate, opts.endDate);
+  let adgroup;
+  try {
+    adgroup = await findItemInList(listUrl, config, opts.id, opts.verbose);
+  } catch (err) {
+    console.error(`
+\u274C \u67E5\u8BE2\u5E7F\u544A\u7EC4\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  const body = { ...adgroup };
+  if (hasName) body["name"] = opts.name.trim();
+  if (hasMax) body["maxCPCAmount"] = Math.round(opts.maxCPCAmount);
+  if (hasTcpa) body["targetCpaAmount"] = Math.round(opts.targetCpaAmount);
+  const putUrl = `${googleApiUrl}/adgroupnmanagement/adgroup/${opts.account}/${opts.id}`;
+  try {
+    await apiFetch2(putUrl, config, { method: "PUT", body: JSON.stringify(body) }, opts.verbose);
+  } catch (err) {
+    console.error(`
+\u274C \u7F16\u8F91\u5E7F\u544A\u7EC4\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  console.log(`
+\u2705 \u5E7F\u544A\u7EC4 ${opts.id} \u5DF2\u66F4\u65B0
+`);
+}
 async function runAdEdit(opts) {
   const config = await ensureDataPermission(loadConfig(opts.token));
   const googleApiUrl = requireGoogleApi(config);
@@ -9510,8 +9670,13 @@ async function fetchTikTokClues(opts, config) {
     );
     leads = Array.isArray(res) ? res : res.data ?? [];
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message, items: [] }, null, 2));
+      process.exit(1);
+    }
     console.error(`
-\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${message}
 `);
     process.exit(1);
   }
@@ -9558,8 +9723,13 @@ async function fetchMetaClues(opts, config) {
   try {
     raw = await apiFetch2(url, config, {}, opts.verbose);
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message, items: [] }, null, 2));
+      process.exit(1);
+    }
     console.error(`
-\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+\u274C \u67E5\u8BE2\u5931\u8D25\uFF1A${message}
 `);
     process.exit(1);
   }
@@ -12216,14 +12386,14 @@ program.command("accounts-digest").description(
 program.command("stats").description("\u67E5\u8BE2\u5E7F\u544A\u6D88\u8017\u3001\u70B9\u51FB\u3001\u8F6C\u5316\u7B49\u6295\u653E\u6570\u636E\uFF08\u9ED8\u8BA4\u8FD1 7 \u5929\uFF0C\u4E0D\u542B\u4ECA\u5929\uFF09").requiredOption(
   "-m, --media <type>",
   "\u5A92\u4F53\u7C7B\u578B\uFF1AGoogle | TikTok | Yandex | MetaAd | BingV2 | Kwai"
-).option("-a, --accounts <ids>", "\u8D26\u6237 ID\uFF0C\u591A\u4E2A\u7528\u9017\u53F7\u5206\u9694\uFF08\u7559\u7A7A\u5219\u67E5\u5168\u90E8\u8D26\u6237\uFF09").option("--start <date>", "\u5F00\u59CB\u65E5\u671F\uFF0C\u683C\u5F0F YYYY-MM-DD\uFF08\u9ED8\u8BA4 7 \u5929\u524D\uFF09").option("--end <date>", "\u7ED3\u675F\u65E5\u671F\uFF0C\u683C\u5F0F YYYY-MM-DD\uFF08\u9ED8\u8BA4\u6628\u5929\uFF09").option("-t, --token <token>", "Token\uFF08\u53EF\u9009\uFF1B\u4F18\u5148\u4E8E ~/.siluzan/config.json\uFF09").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA\u539F\u59CB\u54CD\u5E94", false).option("--verbose", "\u663E\u793A\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+).option("-a, --accounts <ids>", "\u8D26\u6237 ID\uFF0C\u591A\u4E2A\u7528\u9017\u53F7\u5206\u9694\uFF08\u7559\u7A7A\u5219\u67E5\u5168\u90E8\u8D26\u6237\uFF09").option("--start <date>", "\u5F00\u59CB\u65E5\u671F\uFF0C\u683C\u5F0F YYYY-MM-DD\uFF08\u9ED8\u8BA4 7 \u5929\u524D\uFF09").option("--end <date>", "\u7ED3\u675F\u65E5\u671F\uFF0C\u683C\u5F0F YYYY-MM-DD\uFF08\u9ED8\u8BA4\u6628\u5929\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("-t, --token <token>", "Token\uFF08\u53EF\u9009\uFF1B\u4F18\u5148\u4E8E ~/.siluzan/config.json\uFF09").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA\u539F\u59CB\u54CD\u5E94", false).option("--verbose", "\u663E\u793A\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
   async (opts) => {
     await runStats({
       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,
       json: opts.json,
       verbose: opts.verbose
     });
@@ -13247,6 +13417,29 @@ adCmd.command("adgroup-rename").description("\u4FEE\u6539\u5E7F\u544A\u7EC4\u540
     });
   }
 );
+adCmd.command("adgroup-edit").description("\u7F16\u8F91\u5E7F\u544A\u7EC4\uFF08\u540D\u79F0\u3001\u6700\u9AD8 CPC\u3001\u7EC4\u7EA7\u76EE\u6807 CPA\uFF1B\u81F3\u5C11\u4F20\u4E00\u9879\uFF1B\u4E0E\u7F51\u5173 PUT \u4E00\u81F4\uFF09").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--id <adgroupId>", "\u5E7F\u544A\u7EC4 ID").option("--name <name>", "\u65B0\u540D\u79F0").option(
+  "--max-cpc <n>",
+  "\u6700\u9AD8 CPC\uFF0C\u4E0E ad groups --json \u7684 maxCPCAmount \u540C\u53E3\u5F84\uFF08\u4E3B\u5E01\u79CD\u91D1\u989D\xD7100\uFF0C\u89C1 references/google-ads.md\uFF09",
+  parseFloat
+).option(
+  "--target-cpa <n>",
+  "\u7EC4\u7EA7\u76EE\u6807 CPA\uFF0C\u4E0E ad groups --json \u7684 targetCpaAmount \u540C\u53E3\u5F84\uFF08\xD7100 \u5206\u5355\u4F4D\uFF09",
+  parseFloat
+).option("--start <date>", "\u5217\u8868\u67E5\u8BE2\u8D77\u59CB\u65E5\u671F YYYY-MM-DD").option("--end <date>", "\u5217\u8868\u67E5\u8BE2\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option("-t, --token <token>", "Auth Token").option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+  async (opts) => {
+    await runAdGroupEdit({
+      token: opts.token,
+      account: opts.account,
+      id: opts.id,
+      name: opts.name,
+      maxCPCAmount: opts.maxCpc,
+      targetCpaAmount: opts.targetCpa,
+      startDate: opts.start,
+      endDate: opts.end,
+      verbose: opts.verbose
+    });
+  }
+);
 adCmd.command("ad-edit").description(
   "\u7F16\u8F91\u81EA\u9002\u5E94\u641C\u7D22\u5E7F\u544A\uFF08RESPONSIVE_SEARCH_AD\uFF09\uFF1A\u6807\u9898/\u63CF\u8FF0/\u843D\u5730\u9875/\u8DEF\u5F84/\u72B6\u6001\uFF1B\u4E0E\u7F51\u9875 PUT admanagement/campaign \u884C\u4E3A\u4E00\u81F4"
 ).requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--id <adId>", "\u5E7F\u544A ID").option(

package/dist/skill/SKILL.md

@@ -50,11 +50,12 @@ allowed-tools: Bash(siluzan-tso:*) Read
 | 文档 | 功能 |
 |------|------|
 | `references/setup.md` | 安装、登录、配置、环境切换、更新 |
-| `references/workflows.md` | 多步骤业务流程与跨命令串联场景 |
+| `references/workflows.md` | 多步骤业务流程、跨命令串联；入口指向宿主编排自控详页 |
+| `references/hosted-automation-scenarios.md` | **宿主编排（Google）索引**；自控见 `references/hosted-automation-self-control.md`；监控见 `references/hosted-automation-monitoring-json.md`；**自动优化 SOP** 见 `references/hosted-automation-optimize-index.md` |
 | `references/tips.md` | `--json`、Node 过滤、分页与调试技巧 |
 | `references/accounts.md` | 账户列表、余额、消耗、开户记录、授权/解绑/分享/MCC/BC/BM/邮箱授权 |
 | `references/open-account-by-media.md` | 各媒体开户、参数与资料要求 |
-| `references/google-ads.md` | Google Ads 创建、修改、优化与管理主流程 |
+| `references/google-ads.md` | Google Ads 创建、修改、优化与管理主流程；**含 `ad list` / `google-analysis ads` 的 `--json` 拒审字段**（`policyApprovalStatusV2`、`approvalStatusDetails` 等，见该文档「拒审与政策字段」） |
 | `references/reporting.md` | Siluzan TSO 优化报告（Google/TikTok）的生成、推送与查看 |
 | `references/account-analytics.md` | 广告平台账户分析数据拉取与分析/诊断报告模板 |
 | `references/optimize.md` | AI 优化建议记录、详情与历史查询 |
@@ -65,6 +66,27 @@ allowed-tools: Bash(siluzan-tso:*) Read
 
 ---
 
+## 职责划分
+
+**定位**：`siluzan-tso` + 本 Skill 提供 **可组合的读能力（检查项）** 与 **可验证的写能力（最终操作）**；**不负责**在进程内长期驻留、定时轮询、复合条件规则引擎、或替代宿主的通知渠道。
+
+| 由 **本 Skill + CLI** 保证 | 由 **宿主客户端 / 外部调度** 负责 |
+|---------------------------|-----------------------------------|
+| 单次/按需调用下，命令能拉取验证所需的 **JSON 字段**（`--json`、分页见 `references/tips.md`） | **何时**跑一轮检查（cron、事件、对话触发） |
+| 写操作命令语义清晰，且文档给出 **写后如何用读命令复核**（成对验证） | **IF 条件**（多指标 AND/OR、滑动时间窗、相对预算比例等）的计算与决策 |
+| 金额与 ID 口径与文档一致（`*Display`、`entityId` vs `mediaCustomerId` 等硬规范） | 命中后的 **触达**（钉钉/飞书/Slack 等）与内部 **P1/工单** 流程 |
+| `references/google-ads.md` 等与命令、字段含义对齐 | 多账户、多系列的 **批处理循环**、限速、失败重试策略 |
+
+**宿主集成时的推荐约定**：
+
+1. **监控与编排**：配置定时或事件；每轮用本 Skill 指明的命令拉数，在宿主侧用脚本 / `node -e` 做条件判断。
+2. **执行写操作**：仍遵守本 Skill **计划 →（按策略）确认 → 执行 → 验证**；若宿主策略为「全自动写」，须由**用户或配置**显式授权，避免与默认安全规范冲突。
+3. **验证**：每次写入后，用文档中的 **读命令对同一 `id` 再拉一次**（例如 `ad campaign-status` 后 `ad campaigns --json` 看 `statusV2`；`adgroup-edit` 后 `ad groups --json` 看 `maxCPCAmount` / `targetCpaAmount`）。
+4. **`forewarning`**：仍是丝路赞侧 **微信通知** 的可选通道；宿主已有独立通知 skill 时，**不必**重复依赖 `forewarning` 完成「告警」——二者可并行或只选其一。
+
+更具体的 **检查项 ↔ 命令** 见 **`references/hosted-automation-self-control.md`**（三类自控）；异常监控 **`--json` 键名** 见 **`references/hosted-automation-monitoring-json.md`**；**自动优化（降价/扩量/A/B）** 见 **`references/hosted-automation-optimize-index.md`**（分文件 SOP）；主题入口 **`references/hosted-automation-scenarios.md`**。总览见 **`references/workflows.md`**「宿主编排下的投放自控」。
+
+
 ## Skill要如何使用
 
 ### 报告的生成
@@ -89,7 +111,7 @@ allowed-tools: Bash(siluzan-tso:*) Read
 - Google广告优化记录功能(`references/optimize.md`)，这个也跟优化报告类似，你调用接口，Siluzan平台按照一定的优化逻辑自动执行，你只能查询到结果，不能控制优化流程 注意不要与`google-ads.md`中的优化流程混淆两个是互相独立的功能，`references/google-ads.md`中的优化功能更为强大，在实际的优化过程中，也推荐使用`references/google-ads.md`中提供的内容
 - TikTok / Meta 线索表单请阅读：`references/clue.md`
 - Siluzan平台提供的预警功能请阅读：`references/forewarning.md`
-  - 预警由Siluzan平台发送，当前仅支持微信推送，如果需要自定义的通知触达端，需要安装对应插件或skill+创建定时任务来完成
+  - 预警由 Siluzan 平台发送，当前仅支持微信推送。若监控与通知由 **OpenClaw / WorkBuddy 等宿主**承担，可将 `forewarning` 仅作补充或不用；自定义触达仍可用宿主插件 / skill + 定时任务（见上文职责划分）。
 - 转账、开票、发票抬头、充值网页引导请阅读：`references/finance.md`
 -
 
@@ -126,7 +148,9 @@ allowed-tools: Bash(siluzan-tso:*) Read
 - **出报告时账户状态 ≠ 广告系列状态**：`stats` / `balance` / `list-accounts` 中的 `status`（如 Enabled）只表示**广告账户**关联/可用，**绝不能**据此填写或推断**各广告系列**是否「启用/在投」。已暂停或移除的系列若被写成启用，属于严重错误。系列是否启用**必须**来自 `ad campaigns`（或系列维报表中的系列状态）。详见 `references/account-analytics.md`「账户状态 ≠ 广告系列状态」。
 - **不确定时读文档**：遇到不熟悉的命令，先读对应 references 文件或使用-h查看命令帮助，不要猜参数。
 - **先查账户再操作**：对具体账户做操作前，先通过 `list-accounts -m [mediaType] -k [mediaCustomerId]` 确认。特别是不确定是Google/Bing/TikTok这些媒体平台中的哪一个的时候
-- **使用 --json 处理数据**：需对返回数据做计算或筛选时，加 `--json`，再用 `node -e` 过滤提取（见 `references/tips.md`）。
+- **使用 --json 处理数据**：需对返回数据做计算或筛选时，加 `--json`，再用 `node -e` 过滤提取（见 `references/tips.md`）。若用户**已有一份 JSON**（文件或剪贴板），只问如何筛选时：优先给「stdin / 读本地文件 + `node -e`」的通用写法，不必默认再跑一遍业务命令。
+- **CLI 输出忠实**：向用户引用 JSON 时，账户 ID、金额等须与**本次命令 stdout 一致**，不得换成别的示例 ID。禁止编造「stub/示例环境/登录异常」等**未在 CLI 输出或 stderr 中出现**的解释；`data` 为空时只说明「当前返回无记录」并附上原始 JSON。
+- **用户明确要求原始 JSON**：须在回复中给出 CLI 返回的 JSON（或完整代码块），不得以长篇推测替代交付。
 - **不要猜测账户 ID**：`entityId` ≠ `mediaCustomerId`，两者均来自 `list-accounts`。
 - **媒体类型区分大小写**：`Google`、`TikTok`、`MetaAd`、`BingV2`、`Kwai`。
 - **命令透明性**：以简洁的方式向用户说明即将执行的操作意图（如「正在查询您的 Google 账户列表」「正在为账户 xxx 创建预警规则」），让用户了解操作进度。用户主动要求查看执行细节时，应如实提供完整命令。
@@ -142,9 +166,22 @@ allowed-tools: Bash(siluzan-tso:*) Read
    > （A）最近完整自然周（周一到周日）
    > （B）本月 1 号到昨天
    > （C）自定义起止日（请告诉我 `YYYY-MM-DD` 起止）
-2. 用户给出范围后，**在报告首行显式标注"统计区间：YYYY-MM-DD ~ YYYY-MM-DD（时区：用户本地/UTC）"**，与调用参数保持完全一致。
+2. 用户给出范围后，**在报告首行显式标注** `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`（与 `references/account-analytics.md` 一致），与调用参数保持完全一致。
 3. **只有在用户明确说"按你默认来 / 你决定"**时，才使用下方默认值白名单。
 
+### 时间范围反问的例外（不要机械套用到下列任务）
+
+- **`list-accounts` 全量**：用户要「所有 Google 账户」且 JSON 时，看返回里的 `total` / `page` / `pageSize`；若 `itemCount < total`，须翻页（增大 `--page-size` 或循环 `--page`）或说明**当前仅为第 N 页**，不得把单页当成全量结论。
+- **「昨天」单日 stats**：用户已给出 Google `mediaCustomerId` 且只说「昨天」时：默认按 **`Asia/Shanghai` 日历日**换算昨日起止；**先** `list-accounts -m Google -k <id> --quick --json` **再** `stats -m Google -a <id> --start … --end … --json`，不要为时区再打断一轮（除非用户明确要求 UTC/其他时区）。
+- **仅持有 `entityId`**：**禁止**把 `entityId` 传给 `stats -a` / `balance -a`。应先 `list-accounts`（必要时 `--json` + 本地筛选或 `-k` 缩小范围）解析出 `mediaCustomerId` 后再调 `stats`。
+- **`forewarning records`**：见 `references/forewarning.md`，不要求先做投放类日期反问。
+- **`invoice list` /「本月」**：见 `references/finance.md`，可用当月 1 日~昨天直接查。
+- **TikTok `clue`「最近一周」**：见 `references/clue.md`，可直接 `--json` 查询，不要先做 A/B/C 日期口径反问。
+
+### 仅输出 JSON 的交付
+
+用户明确要求「**只输出**一个 JSON / 除 JSON 外不要文字」时：回复中**仅含一个** JSON 代码块，内容与本次 CLI **stdout 完全一致**（分页、失败体均如此）；失败时 CLI 已保证 `--json` 下 stdout 仍为 JSON 对象。
+
 ### 默认值白名单（仅在用户明确授权"你决定"时才能使用）
 
 | 场景                    | 允许的默认窗口                                        |
@@ -169,6 +206,7 @@ allowed-tools: Bash(siluzan-tso:*) Read
   2. `list-accounts` 返回的 `mag.advertiserName`
   3. 用户提供的网址 → 明确告诉用户"使用域名作为占位"（例如 `hy-steelpipe.com`）并在交付物里标注 `[待确认品牌名]`
 - **严禁**"hy-steelpipe.com"这样的英文域名被输出成类似"海悦钢管"这种虚构中文品牌。
+- 正文里写出品牌名时，应能回溯到上述来源（可写「来自 list-accounts 的 `mag.advertiserName`：…」）；**禁止**写看似真实但未在上述来源或 CLI 输出中出现的名称（包括常见 Demo 风格占位名）。
 
 ### 批量任务硬约束（≥ 5 个账户或系列）
 
@@ -209,6 +247,8 @@ allowed-tools: Bash(siluzan-tso:*) Read
   - 发票申请（`invoice apply`）— 涉及财务
   - 广告发布（`ad batch publish` / `ad campaign-create`）— 涉及预算消耗
 - **只读操作可自主执行**：查询类命令（`list-accounts`、`balance`、`stats`、`report list`、`config show` 等）可直接执行，无需额外确认
+- **Google 广告结构性改动（否定词/系列/关键词等）**：须遵守 `references/google-ads.md` 开篇流程——先阅读规则文档、再列计划与将参考的文档清单；**仅在用户明确确认方案后**才可执行写命令。用户未确认前，不得使用「拿到参数就立刻执行」等措辞暗示可跳过确认。
+- **Google 开户（CLI 指引）**：`open-account google-wizard` 仅适用于真实 TTY；**Agent/自动化环境一律用非交互** `open-account google ...`，审核进度用 `account-history`（详见 `references/workflows.md` 流程一）。向用户写步骤时，把上述禁令放在指引**最前**，再给可复制命令。
 
 ---
 
@@ -220,15 +260,16 @@ allowed-tools: Bash(siluzan-tso:*) Read
 
 > 触发关键词：某账户数据 / 投放情况 / 整理账户 / 看下某个账户的表现
 
-1. **反问时间范围**（参见"时间范围强制反问"）。
+1. **反问时间范围**（参见"时间范围强制反问"；用户已授权「按默认」时用默认值白名单并写明区间）。
 2. `list-accounts -m Google -k <mediaCustomerId> --quick --json`
    - 一次拿齐：账户基础信息、创建日期、当前状态、公司名（`mag.advertiserName` 作为品牌名）
-3. `stats --media Google --accounts <id> --start-date <S> --end-date <D> --json`
-   - 拿该区间消耗、点击、转化等；**直接读响应中的主币种数值**，不要再 ×100。
-4. `ad campaigns --account <id> --start-date <S> --end-date <D> --json`
+3. `siluzan-tso stats -m Google -a <mediaCustomerId> --start <S> --end <D> --json`（`--start-date` / `--end-date` 与 `--start` / `--end` 等价）
+   - 拿该区间消耗、点击、转化等；**直接读响应中的主币种数值**，不要再 ×100。若返回 `{"ok":false,"error":...}`，须原样展示并**不得**用系列数据编造账户级 stats。
+4. `siluzan-tso ad campaigns -a <mediaCustomerId> --start <S> --end <D> --json`
    - 拿广告系列类型（Search / PMax / Display 等）、日预算（**用 `budgetDisplay`**）、优化得分相关字段。
 5. `stats` 结合 `accountsoverview` 字段派生"开始投放时间 / 有效投放天数 / 地区消耗分布"（如接口暂未直出，在 node 里聚合）。
 6. 用 `report-templates/google-account-diagnosis-report.md` 模板输出，**首行标注统计区间和货币**。
+7. 用户要求「先拉 JSON 再文字总结」时：回复中须包含实际 `--json` 输出（完整或明确声明截断），再写总结；**禁止**用未出现在这些 JSON / `list-accounts` 中的字段写品牌名或接口状态。
 
 ### P2 · 多账户余额扫描 / 预算预警（典型指令："117 个 Bing 账户不足 7 天的挑出来"）
 
@@ -279,8 +320,9 @@ siluzan-tso accounts-digest -m Google \
 
 1. **反问时间范围**（P 级硬约束），拿到用户回复后再执行 `accounts-digest`。
 2. 如命令已返回 `--json`，直接基于其中 `data.items` 与 `meta.totals` 生成报告；**不要**再逐账户 `stats`。
-3. 跨币种账户：按 `item.currencyCode` 分表或在 meta.currencyNote 提示的前提下分币种小计。
-4. 金额字段严格按"金额与货币单位硬约束"处理。
+3. **多账户 `-a id1,id2,...` 时**：表格须覆盖用户请求的**每一个** ID；若某 ID 在 `data.items` 中未出现，仍占一行并标注「未返回/无数据」，并说明与 `meta.totals` 的关系；**禁止**只展示子集却声称已完成多账户汇总。
+4. 跨币种账户：按 `item.currencyCode` 分表或在 meta.currencyNote 提示的前提下分币种小计。
+5. 金额字段严格按"金额与货币单位硬约束"处理。
 
 ### P4 · Google 账户周期报告（典型指令："生成 2026.1.1-2026.4.15 的报告"）
 
@@ -289,6 +331,7 @@ siluzan-tso accounts-digest -m Google \
 3. 使用 `report-templates/google-period-report.md` 模板输出。
 4. 首行必须有：`统计区间：2026-01-01 ~ 2026-04-15` + `货币：XXX`。
 5. 报告必须包含：账户概览、投放趋势、Top 关键词/系列 / 地区分布 / 优化建议；不得编造未拉取到的指标（例如没拉取到的关键词就写"未提供"而不是估算）。
+6. 品牌名遵守上文「品牌名 / 公司名来源硬约束」；描述系列启停时只引用 `ad campaigns`（或系列维报表）中的系列级状态字段，勿与账户 `status` 混用。
 
 ---
 
@@ -343,19 +386,23 @@ HTML 报告模板（`report-templates/*.html`）引用了以下外部 CDN 资源
 
 ### 异常监控与报警系统
 
-| 功能名称          | 监控层级 / 说明                                             |
-| ----------------- | ----------------------------------------------------------- |
-| 1. 账户被封禁     |                                                             |
-| 2. 落地页死链强停 | 网站宕机或链接填错，紧急自动暂停关联广告，防止把钱扔水里。  |
-| 3. 广告素材拒审   | 发现被 Google 封号或快没钱了，立刻发送企微/钉钉高优强提醒。 |
-| 4. 花费异动监控   | 花费突然暴涨或断崖式下跌，系统即时报警提示人工盯盘。        |
-| 5. 余额枯竭预警   | 广告被 Google 拦截，系统自动帮你打包违规原因并定时推送。    |
+编排（定时、HTTP 探活、通知）在宿主；**读哪些 JSON 字段、用什么命令** 以 **`references/hosted-automation-monitoring-json.md`** 为准（键名以当次 `--json` 为准，勿套用 Google Ads API 官方字段名解析本 CLI 输出）。
+
+| 功能名称          | 监控层级 / 说明 | CLI 检查入口（`--json`） |
+| ----------------- | --------------- | ------------------------ |
+| 1. 账户被封禁     | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 `references/accounts.md` |
+| 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis final-urls`**；或 **`ad list`** / **`google-analysis ads`** 取落地页字段后由宿主 HTTP 校验 |
+| 3. 广告素材拒审   | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **`references/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` 等） |
 
 ### 自动优化
 
-| 功能名称                | 监控层级                                                                   |
-| ----------------------- | -------------------------------------------------------------------------- |
-| 1. 表现差广告降价/关停  | 发现转化极好的「好苗子」，以安全幅度自动涨预算/提价去抢量。                |
-| 2. 高转化广告提价扩量   | 连续几天表现垫底的垃圾素材，系统扮演无情杀手自动关停。                     |
-| 3. A/B测试自动决出胜者  | 科学赛马，根据真实转化价值自动关停输家，把流量全给赢家。                   |
-| 4. 异动根因自动排查建议 | 老板问为什么成本翻倍？系统一键生成诊断报告（揪出外部竞对或内部操作失误）。 |
+编排与阈值在宿主；**命令、JSON 键名、聚合与写后复核** 见 **`references/hosted-automation-optimize-index.md`**（及链出的三份 SOP）。
+
+| 功能名称                | 说明 | SOP |
+| ----------------------- | ---- | ----- |
+| 1. 表现差广告降价/关停  | 组/创意：CTR、CPA、转化等触达后 **下调 `targetCpa` 或 `Paused`**。 | [`hosted-automation-optimize-weak-downbid.md`](references/hosted-automation-optimize-weak-downbid.md) |
+| 2. 高转化广告提价扩量   | 系列/组：ROAS 代理、预算丢失份额等触达后 **提预算 / 上调目标 CPA**。 | [`hosted-automation-optimize-scale.md`](references/hosted-automation-optimize-scale.md) |
+| 3. A/B 测试自动决出胜者 | 同组多创意：聚合后比 **CVPI / all conv** 等，**停输家**。 | [`hosted-automation-optimize-ab-winner.md`](references/hosted-automation-optimize-ab-winner.md) |
+| 4. 异动根因自动排查建议 | 诊断报告与归因：用 `account-analytics`、报告模板等，见 `references/account-analytics.md` 与 `report-templates/`。 | （未单独拆 SOP，沿用分析文档） |

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.14-beta.1",
-  "publishedAt": 1776765041399
+  "version": "1.1.14-beta.3",
+  "publishedAt": 1776995703860
 }