siluzan-tso-cli 1.1.29-beta.11 → 1.1.29-beta.12

package/README.md

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

package/dist/index.js

@@ -114935,6 +114935,17 @@ function runPmaxCreateValidation(cfg) {
       );
     }
   }
+  if (cfg.brandGuidelinesEnabled === false) {
+    pushWarn3(
+      warnings,
+      "brandGuidelinesEnabled=false\uFF1A\u54C1\u724C\u5C06\u6302\u5728 AssetGroup \u7EA7\uFF08\u65E7\u8DEF\u5F84\uFF09\uFF1Bv21+ \u9ED8\u8BA4 true\uFF08Campaign \u7EA7 BG\uFF09"
+    );
+  } else if (cfg.brandGuidelinesEnabled !== true) {
+    pushWarn3(
+      warnings,
+      "\u672A\u4F20 brandGuidelinesEnabled\uFF1A\u7F51\u5173\u9ED8\u8BA4 true\uFF1B\u521B\u5EFA\u540E\u9996\u4E2A AG \u7684 assets[] \u4E0D\u542B Logo/\u5546\u5BB6\u540D\uFF08\u89C1 brandAssets[]\uFF09"
+    );
+  }
   return { errors, warnings, lengthViolations };
 }
 
@@ -115126,6 +115137,12 @@ function pmaxCampaignUrl(googleApiUrl, accountId, campaignId) {
   const path27 = `${base}/accounts/${accountId}/campaign/pmax`;
   return campaignId ? `${path27}/${campaignId}` : path27;
 }
+function pmaxBrandAssetsUrl(googleApiUrl, accountId, campaignId) {
+  return `${pmaxCampaignUrl(googleApiUrl, accountId, campaignId)}/brand-assets`;
+}
+function pmaxBrandGuidelinesEnableUrl(googleApiUrl, accountId, campaignId) {
+  return `${pmaxCampaignUrl(googleApiUrl, accountId, campaignId)}/brand-guidelines/enable`;
+}
 function pmaxAssetGroupUrl(googleApiUrl, accountId, assetGroupId, suffix) {
   const base = googleApiUrl.replace(/\/$/, "");
   const path27 = `${base}/accounts/${accountId}/campaign/pmax/asset-group/${assetGroupId}`;
@@ -115321,7 +115338,7 @@ async function resolveOneSlot(configFile, cfg, kind, accountId, config, googleAp
   );
 }
 async function resolvePmaxImageSlots(configFile, cfg, accountId, config, googleApiUrl, opts) {
-  const kinds = ["marketing", "square", "logo"];
+  const kinds = opts?.requiredKinds ?? ["marketing", "square", "logo"];
   const willUpload = kinds.some((k) => {
     const meta = SLOT_META[k];
     if (String(cfg[meta.configAssetIdKey] ?? "").trim()) return false;
@@ -115345,8 +115362,8 @@ async function resolvePmaxImageSlots(configFile, cfg, accountId, config, googleA
   }
   return merged;
 }
-function assertPmaxImageSlotsResolved(slots) {
-  for (const kind of ["marketing", "square", "logo"]) {
+function assertPmaxImageSlotsResolved(slots, requiredKinds = ["marketing", "square", "logo"]) {
+  for (const kind of requiredKinds) {
     const meta = SLOT_META[kind];
     const id = slots[meta.assetIdKey];
     const b64 = slots[meta.base64Key];
@@ -115476,6 +115493,9 @@ function buildPmaxCreateApiBody(cfg, imageSlots) {
   if (roas != null && Number(roas) > 0) {
     body.targetRoas = Number(roas);
   }
+  if (cfg.brandGuidelinesEnabled !== void 0) {
+    body.brandGuidelinesEnabled = cfg.brandGuidelinesEnabled;
+  }
   return body;
 }
 function buildPmaxCreateUrl(googleApiUrl, accountId) {
@@ -115521,17 +115541,27 @@ function convertPmaxMoneyInObject(body) {
   }
   return out;
 }
-function buildPmaxAssetGroupApiBody(cfg, imageSlots) {
-  assertPmaxImageSlotsResolved(imageSlots);
-  return {
+function buildPmaxAssetGroupApiBody(cfg, imageSlots, opts) {
+  const requiredKinds = opts?.omitBrandAssets ? ["marketing", "square"] : ["marketing", "square", "logo"];
+  assertPmaxImageSlotsResolved(imageSlots, [...requiredKinds]);
+  const body = {
     name: cfg.name.trim(),
     finalUrls: cfg.finalUrls.map((u) => u.trim()).filter(Boolean),
     headlines: cfg.headlines.map((h) => h.trim()).filter(Boolean),
     longHeadlines: cfg.longHeadlines.map((h) => h.trim()).filter(Boolean),
-    descriptions: cfg.descriptions.map((d) => d.trim()).filter(Boolean),
-    businessName: cfg.businessName.trim(),
-    ...imageSlots
+    descriptions: cfg.descriptions.map((d) => d.trim()).filter(Boolean)
   };
+  if (!opts?.omitBrandAssets) {
+    body["businessName"] = cfg.businessName.trim();
+  }
+  for (const key of Object.keys(imageSlots)) {
+    if (opts?.omitBrandAssets && (key === "logoImageAssetId" || key === "logoImageBase64")) {
+      continue;
+    }
+    const val = imageSlots[key];
+    if (val != null && String(val).trim()) body[key] = val;
+  }
+  return body;
 }
 async function processAssetsUpdateBodyWithUpload(configFile, body, accountId, config, googleApiUrl, verbose) {
   const out = { ...body };
@@ -116213,6 +116243,8 @@ async function runAdPmaxCreate(opts) {
   }
   const payload = {
     ...data,
+    _brandGuidelinesEnabled: cfg.brandGuidelinesEnabled !== false,
+    _agentBrandHint: cfg.brandGuidelinesEnabled === false ? "\u54C1\u724C\u5728 AssetGroup \u7EA7\uFF1B\u6539\u54C1\u724C\u7528 pmax-assets-update" : "\u54C1\u724C\u5728 Campaign \u7EA7 brandAssets[]\uFF1B\u6539\u54C1\u724C\u7528 pmax-brand-assets-edit\uFF1B\u8FFD\u52A0 AG \u53EF\u7701\u7565 Logo/\u5546\u5BB6\u540D",
     videoLink: {
       ok: Boolean(videoResult.youtubeLink && !videoResult.uploadError && !videoResult.linkError),
       youtubeTarget: videoResult.youtubeTarget,
@@ -116365,6 +116397,179 @@ async function runAdPmaxValidate(opts) {
 
 // src/commands/ad/pmax-mgmt.ts
 import { basename as basename6, isAbsolute as isAbsolute6 } from "path";
+
+// src/commands/ad/pmax-brand-guidelines.ts
+var PMAX_CAMPAIGN_BRAND_FIELD_TYPES = /* @__PURE__ */ new Set([
+  "BUSINESS_NAME",
+  "LOGO",
+  "LANDSCAPE_LOGO"
+]);
+function isPmaxBrandGuidelinesActive(detail) {
+  if (detail["brandGuidelinesEnabled"] === true) return true;
+  const assets = detail["brandAssets"];
+  if (!Array.isArray(assets)) return false;
+  return assets.some((row) => {
+    if (!row || typeof row !== "object") return false;
+    const ft = String(row["fieldType"] ?? "").toUpperCase();
+    return PMAX_CAMPAIGN_BRAND_FIELD_TYPES.has(ft);
+  });
+}
+function brandEditAgentHint(bgActive) {
+  return bgActive ? "\u6539\u5546\u5BB6\u540D/Logo/\u6837\u5F0F\uFF1Aad pmax-brand-assets-edit\uFF08\u52FF\u5BF9 AssetGroup \u7528 pmax-assets-update \u6539 BUSINESS_NAME/LOGO\uFF09" : "\u6539\u54C1\u724C\uFF1Aad pmax-assets-update\uFF08AssetGroup \u7EA7\uFF09\uFF1B\u6216 ad pmax-brand-guidelines-enable \u542F\u7528 BG \u540E\u8D70 ad pmax-brand-assets-edit";
+}
+function enrichPmaxDetailForAgent(detail) {
+  const bgActive = isPmaxBrandGuidelinesActive(detail);
+  return {
+    ...detail,
+    _brandGuidelinesActive: bgActive,
+    _agentBrandHint: brandEditAgentHint(bgActive)
+  };
+}
+async function fetchPmaxCampaignDetail(config, googleApiUrl, accountId, campaignId, verbose) {
+  const url = pmaxCampaignUrl(googleApiUrl, accountId, campaignId);
+  const raw = await pmaxApiFetch(url, config, {}, verbose);
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    return raw;
+  }
+  return { data: raw };
+}
+function hasBrandImageSource(cfg, slot) {
+  if (slot === "logo") {
+    return Boolean(
+      cfg.logoImageAssetId?.trim() || cfg.logoImageBase64?.trim() || cfg.imagePaths?.logo?.trim()
+    );
+  }
+  return Boolean(
+    cfg.landscapeLogoImageAssetId?.trim() || cfg.landscapeLogoImageBase64?.trim() || cfg.imagePaths?.landscapeLogo?.trim()
+  );
+}
+function validateBrandAssetsPatchBody(cfg, opts) {
+  const errors = [];
+  const style = cfg.brandGuidelines;
+  const hasMain = Boolean(style?.mainColor?.trim());
+  const hasAccent = Boolean(style?.accentColor?.trim());
+  if (hasMain !== hasAccent) {
+    errors.push("brandGuidelines.mainColor \u4E0E accentColor \u987B\u6210\u5BF9\u4F20\u5165");
+  }
+  const hasAny = Boolean(cfg.businessName?.trim()) || hasBrandImageSource(cfg, "logo") || hasBrandImageSource(cfg, "landscapeLogo") || Boolean(style?.predefinedFontFamily?.trim()) || hasMain;
+  if (opts?.requireAtLeastOne !== false && !hasAny) {
+    errors.push(
+      "\u81F3\u5C11\u4F20\u4E00\u9879\uFF1AbusinessName\u3001logoImage*\u3001landscapeLogoImage* \u6216 brandGuidelines \u6837\u5F0F\u5B57\u6BB5"
+    );
+  }
+  return errors;
+}
+function validateEnableBrandGuidelinesBody(cfg) {
+  const errors = validateBrandAssetsPatchBody(cfg, {
+    requireAtLeastOne: cfg.autoPopulateBrandAssets !== true
+  });
+  if (cfg.autoPopulateBrandAssets !== true) {
+    if (!cfg.businessName?.trim()) {
+      errors.push("autoPopulateBrandAssets=false \u65F6 businessName \u5FC5\u586B");
+    }
+    if (!hasBrandImageSource(cfg, "logo")) {
+      errors.push("autoPopulateBrandAssets=false \u65F6 Logo\uFF08logoImage* / imagePaths.logo\uFF09\u5FC5\u586B");
+    }
+  }
+  return errors;
+}
+function detectAssetGroupBrandLinkBlocked(body, bgActive) {
+  if (!bgActive) return [];
+  const errors = [];
+  const links = body["assetsToLink"];
+  if (Array.isArray(links)) {
+    for (const item of links) {
+      if (!item || typeof item !== "object") continue;
+      const ft = String(item["fieldType"] ?? "").toUpperCase();
+      if (PMAX_CAMPAIGN_BRAND_FIELD_TYPES.has(ft)) {
+        errors.push(
+          `Brand Guidelines \u5DF2\u751F\u6548\uFF0C\u7981\u6B62\u5728 AssetGroup PUT ${ft}\uFF1B\u8BF7\u7528 ad pmax-brand-assets-edit`
+        );
+      }
+    }
+  }
+  const replace = body["replaceFieldTypes"];
+  if (Array.isArray(replace)) {
+    for (const ft of replace) {
+      const upper = String(ft ?? "").toUpperCase();
+      if (PMAX_CAMPAIGN_BRAND_FIELD_TYPES.has(upper)) {
+        errors.push(
+          `Brand Guidelines \u5DF2\u751F\u6548\uFF0CreplaceFieldTypes \u542B ${upper}\uFF1B\u8BF7\u7528 ad pmax-brand-assets-edit`
+        );
+      }
+    }
+  }
+  return errors;
+}
+async function buildBrandAssetsApiBody(configFile, cfg, accountId, config, googleApiUrl, verbose) {
+  const body = {};
+  if (cfg.businessName?.trim()) body["businessName"] = cfg.businessName.trim();
+  const logoCfg = {
+    logoImageAssetId: cfg.logoImageAssetId,
+    logoImageBase64: cfg.logoImageBase64,
+    imagePaths: cfg.imagePaths?.logo ? { logo: cfg.imagePaths.logo } : void 0
+  };
+  const needsLogo = cfg.logoImageAssetId?.trim() || cfg.logoImageBase64?.trim() || cfg.imagePaths?.logo?.trim();
+  if (needsLogo) {
+    const slots = await resolvePmaxImageSlots(
+      configFile,
+      logoCfg,
+      accountId,
+      config,
+      googleApiUrl,
+      { verbose, logUploads: false, requiredKinds: ["logo"] }
+    );
+    if (slots.logoImageAssetId) body["logoImageAssetId"] = slots.logoImageAssetId;
+    else if (slots.logoImageBase64) body["logoImageBase64"] = slots.logoImageBase64;
+  }
+  const needsLandscape = cfg.landscapeLogoImageAssetId?.trim() || cfg.landscapeLogoImageBase64?.trim() || cfg.imagePaths?.landscapeLogo?.trim();
+  if (needsLandscape) {
+    const landscapeCfg = {
+      logoImageAssetId: cfg.landscapeLogoImageAssetId,
+      logoImageBase64: cfg.landscapeLogoImageBase64,
+      imagePaths: cfg.imagePaths?.landscapeLogo ? { logo: cfg.imagePaths.landscapeLogo } : void 0
+    };
+    const slots = await resolvePmaxImageSlots(
+      configFile,
+      landscapeCfg,
+      accountId,
+      config,
+      googleApiUrl,
+      { verbose, logUploads: false, requiredKinds: ["logo"] }
+    );
+    if (slots.logoImageAssetId) body["landscapeLogoImageAssetId"] = slots.logoImageAssetId;
+    else if (slots.logoImageBase64) body["landscapeLogoImageBase64"] = slots.logoImageBase64;
+  }
+  if (cfg.brandGuidelines && typeof cfg.brandGuidelines === "object") {
+    const style = {};
+    const src = cfg.brandGuidelines;
+    if (src.mainColor?.trim()) style["mainColor"] = src.mainColor.trim();
+    if (src.accentColor?.trim()) style["accentColor"] = src.accentColor.trim();
+    if (src.predefinedFontFamily?.trim()) {
+      style["predefinedFontFamily"] = src.predefinedFontFamily.trim();
+    }
+    if (Object.keys(style).length > 0) body["brandGuidelines"] = style;
+  }
+  return body;
+}
+async function buildEnableBrandGuidelinesApiBody(configFile, cfg, accountId, config, googleApiUrl, verbose) {
+  const body = await buildBrandAssetsApiBody(
+    configFile,
+    cfg,
+    accountId,
+    config,
+    googleApiUrl,
+    verbose
+  );
+  if (cfg.autoPopulateBrandAssets === true) {
+    body["autoPopulateBrandAssets"] = true;
+  } else {
+    body["autoPopulateBrandAssets"] = false;
+  }
+  return body;
+}
+
+// src/commands/ad/pmax-mgmt.ts
 function buildReportQuery(opts) {
   const params = new URLSearchParams();
   params.set("startDate", toGoogleDate(opts.startDate, -30).replace(/\//g, "-"));
@@ -116425,18 +116630,30 @@ async function runAdPmaxChannelTypes(opts) {
 async function runAdPmaxGet(opts) {
   const accountId = requireAccountId(opts.account);
   await withGoogleApi(opts, async (config, googleApiUrl) => {
-    const url = pmaxCampaignUrl(googleApiUrl, accountId, opts.campaignId.trim());
     let data;
     try {
-      const raw = await pmaxApiFetch(url, config, {}, opts.verbose);
-      data = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : { data: raw };
+      data = await fetchPmaxCampaignDetail(
+        config,
+        googleApiUrl,
+        accountId,
+        opts.campaignId.trim(),
+        opts.verbose
+      );
     } catch (err) {
       console.error(`
 \u274C \u83B7\u53D6 PMax \u8BE6\u60C5\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
 `);
       process.exit(1);
     }
-    if (await emitPmaxResult(opts, `ad-pmax-get-${accountId}`, "ad pmax-get", data, opts.campaignId)) {
+    const enriched = enrichPmaxDetailForAgent(data);
+    const bgActive = enriched["_brandGuidelinesActive"] === true;
+    if (await emitPmaxResult(
+      opts,
+      `ad-pmax-get-${accountId}`,
+      "ad pmax-get",
+      enriched,
+      opts.campaignId
+    )) {
       return;
     }
     console.log(`
@@ -116444,9 +116661,13 @@ async function runAdPmaxGet(opts) {
     console.log(`   \u540D\u79F0\uFF1A${data["name"] ?? "\u2014"}`);
     console.log(`   \u72B6\u6001\uFF1A${data["statusV2"] ?? "\u2014"}`);
     console.log(`   \u9884\u7B97\uFF1A${data["budget"] ?? "\u2014"}\uFF08API \u5206\uFF0C\u5C55\u793A \xF7100\uFF09`);
+    console.log(
+      `   Brand Guidelines\uFF1A${bgActive ? "\u751F\u6548\uFF08\u54C1\u724C\u5728 Campaign \u7EA7 brandAssets[]\uFF09" : "\u672A\u751F\u6548\uFF08\u54C1\u724C\u5728 AssetGroup assets[]\uFF09"}`
+    );
     const groups = data["assetGroups"];
     const n = Array.isArray(groups) ? groups.length : 0;
     console.log(`   \u8D44\u4EA7\u7EC4\uFF1A${n} \u4E2A`);
+    console.log(`   ${brandEditAgentHint(bgActive)}`);
     console.log(`
    \u5B8C\u6574\u7ED3\u6784\u8BF7\u4F7F\u7528 --json-out
 `);
@@ -116521,6 +116742,7 @@ async function runAdPmaxAssetGroupCreate(opts) {
     console.error("\n\u274C JSON \u987B\u5305\u542B campaignId\n");
     process.exit(1);
   }
+  const forceLegacyBrand = cfg["includeBrandAssets"] === true || cfg["forceBrandAssets"] === true;
   const assetFields = {
     name: String(cfg["name"] ?? ""),
     finalUrls: cfg["finalUrls"] ?? [],
@@ -116537,6 +116759,45 @@ async function runAdPmaxAssetGroupCreate(opts) {
     logoImageBase64: cfg["logoImageBase64"]
   };
   await withGoogleApi(opts, async (config, googleApiUrl) => {
+    let omitBrandAssets = false;
+    const warnings = [];
+    if (!forceLegacyBrand) {
+      try {
+        const detail = await fetchPmaxCampaignDetail(
+          config,
+          googleApiUrl,
+          accountId,
+          campaignId,
+          opts.verbose
+        );
+        omitBrandAssets = isPmaxBrandGuidelinesActive(detail);
+        if (omitBrandAssets) {
+          const hasBrandInConfig = assetFields.businessName.trim() || assetFields.logoImageAssetId?.trim() || assetFields.logoImageBase64?.trim() || assetFields.imagePaths?.logo?.trim();
+          if (hasBrandInConfig) {
+            warnings.push(
+              "\u6D3B\u52A8 Brand Guidelines \u5DF2\u751F\u6548\uFF1AbusinessName/Logo \u5C06\u88AB\u5FFD\u7565\uFF08\u54C1\u724C\u5728 Campaign \u7EA7\uFF09\uFF1B\u53EF\u4ECE JSON \u5220\u9664\u4EE5\u51CF\u566A"
+            );
+          }
+        }
+      } catch (err) {
+        console.error(
+          `
+\u274C \u8BFB\u53D6\u6D3B\u52A8\u8BE6\u60C5\u5931\u8D25\uFF08\u65E0\u6CD5\u5224\u65AD Brand Guidelines\uFF09\uFF1A${err instanceof Error ? err.message : String(err)}
+`
+        );
+        process.exit(1);
+      }
+    }
+    if (!omitBrandAssets && !assetFields.businessName.trim()) {
+      console.error(
+        "\n\u274C Brand Guidelines \u672A\u751F\u6548\u65F6 businessName \u5FC5\u586B\uFF1B\u82E5\u6D3B\u52A8\u5DF2\u5F00 BG \u8BF7\u52FF\u4F20 includeBrandAssets\n"
+      );
+      process.exit(1);
+    }
+    if (warnings.length > 0 && !opts.jsonOut) {
+      console.warn("\n\u26A0\uFE0F  PMax \u8D44\u4EA7\u7EC4\u521B\u5EFA\u8B66\u544A\uFF1A");
+      for (const w of warnings) console.warn(`   \u2022 ${w}`);
+    }
     let imageSlots;
     try {
       imageSlots = await resolvePmaxImageSlots(
@@ -116545,7 +116806,11 @@ async function runAdPmaxAssetGroupCreate(opts) {
         accountId,
         config,
         googleApiUrl,
-        { verbose: opts.verbose, logUploads: !opts.jsonOut }
+        {
+          verbose: opts.verbose,
+          logUploads: !opts.jsonOut,
+          requiredKinds: omitBrandAssets ? ["marketing", "square"] : void 0
+        }
       );
     } catch (err) {
       console.error(
@@ -116557,7 +116822,7 @@ async function runAdPmaxAssetGroupCreate(opts) {
     }
     let body;
     try {
-      body = buildPmaxAssetGroupApiBody(assetFields, imageSlots);
+      body = buildPmaxAssetGroupApiBody(assetFields, imageSlots, { omitBrandAssets });
     } catch (err) {
       console.error(`
 \u274C \u6784\u5EFA\u8BF7\u6C42\u4F53\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
@@ -116586,7 +116851,11 @@ async function runAdPmaxAssetGroupCreate(opts) {
       { ...opts, account: accountId },
       `ad-pmax-asset-group-create-${accountId}`,
       "ad pmax-asset-group-create",
-      data,
+      {
+        ...data,
+        _brandGuidelinesActive: omitBrandAssets,
+        _warnings: warnings.length > 0 ? warnings : void 0
+      },
       String(data["id"] ?? campaignId)
     )) {
       return;
@@ -116662,6 +116931,25 @@ async function runAdPmaxAssetsUpdate(opts) {
     process.exit(1);
   }
   await withGoogleApi(opts, async (config, googleApiUrl) => {
+    const campaignId = String(cfg["campaignId"] ?? "").trim();
+    let bgActive = false;
+    try {
+      const detail = await fetchPmaxCampaignDetail(
+        config,
+        googleApiUrl,
+        accountId,
+        campaignId,
+        opts.verbose
+      );
+      bgActive = isPmaxBrandGuidelinesActive(detail);
+    } catch (err) {
+      console.error(
+        `
+\u274C \u8BFB\u53D6\u6D3B\u52A8\u8BE6\u60C5\u5931\u8D25\uFF08Brand Guidelines \u9884\u68C0\uFF09\uFF1A${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(1);
+    }
     let body;
     try {
       const { account: _a, ...rest } = cfg;
@@ -116679,6 +116967,13 @@ async function runAdPmaxAssetsUpdate(opts) {
 `);
       process.exit(1);
     }
+    const brandBlocked = detectAssetGroupBrandLinkBlocked(body, bgActive);
+    if (brandBlocked.length > 0) {
+      console.error("\n\u274C PMax \u8D44\u4EA7\u66F4\u65B0\u88AB Brand Guidelines \u89C4\u5219\u963B\u65AD\uFF1A");
+      for (const e of brandBlocked) console.error(`   \u2022 ${e}`);
+      console.error();
+      process.exit(1);
+    }
     const url = pmaxAssetGroupUrl(googleApiUrl, accountId, assetGroupId, "assets");
     try {
       await pmaxApiFetch(
@@ -117267,6 +117562,146 @@ async function runAdPmaxImageConvert(opts) {
   );
 }
 
+// src/commands/ad/pmax-brand-mgmt.ts
+function loadBrandConfig(path27, accountId, campaignId) {
+  const cfg = loadPmaxJsonFile(path27);
+  return {
+    ...cfg,
+    account: String(cfg["account"] ?? accountId).trim(),
+    campaignId: String(cfg["campaignId"] ?? campaignId).trim()
+  };
+}
+async function runAdPmaxBrandAssetsEdit(opts) {
+  const accountId = requireAccountId(opts.account);
+  const campaignId = opts.campaignId.trim();
+  if (!opts.patchFile?.trim()) {
+    console.error("\n\u274C \u8BF7\u6307\u5B9A --patch-file\uFF08\u6A21\u677F pmax-brand-assets-template.json\uFF09\n");
+    process.exit(1);
+  }
+  const cfg = loadBrandConfig(opts.patchFile, accountId, campaignId);
+  const errors = validateBrandAssetsPatchBody(cfg);
+  if (errors.length > 0) {
+    console.error("\n\u274C Brand Assets \u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A");
+    for (const e of errors) console.error(`   \u2022 ${e}`);
+    console.error();
+    process.exit(1);
+  }
+  await withGoogleApi(opts, async (config, googleApiUrl) => {
+    let body;
+    try {
+      body = await buildBrandAssetsApiBody(
+        opts.patchFile,
+        cfg,
+        accountId,
+        config,
+        googleApiUrl,
+        opts.verbose
+      );
+    } catch (err) {
+      console.error(
+        `
+\u274C \u6784\u5EFA brand-assets \u8BF7\u6C42\u4F53\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(1);
+    }
+    const url = pmaxBrandAssetsUrl(googleApiUrl, accountId, campaignId);
+    try {
+      await pmaxApiFetch(
+        url,
+        config,
+        { method: "PATCH", body: JSON.stringify(body) },
+        opts.verbose
+      );
+    } catch (err) {
+      console.error(
+        `
+\u274C \u66F4\u65B0 PMax Campaign \u54C1\u724C\u8D44\u4EA7\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(1);
+    }
+    if (await emitPmaxResult(
+      { ...opts, account: accountId },
+      `ad-pmax-brand-assets-edit-${accountId}`,
+      "ad pmax-brand-assets-edit",
+      { ok: true, campaignId, patch: body },
+      campaignId
+    )) {
+      return;
+    }
+    console.log(`
+\u2705 PMax \u6D3B\u52A8 ${campaignId} Campaign \u7EA7\u54C1\u724C\u8D44\u4EA7\u5DF2\u66F4\u65B0
+`);
+  });
+}
+async function runAdPmaxBrandGuidelinesEnable(opts) {
+  const cfgRaw = loadPmaxJsonFile(opts.configFile);
+  const accountId = requireAccountId(String(cfgRaw["account"] ?? opts.account ?? ""));
+  const campaignId = String(cfgRaw["campaignId"] ?? opts.campaignId ?? "").trim();
+  if (!campaignId) {
+    console.error("\n\u274C JSON \u987B\u5305\u542B campaignId\n");
+    process.exit(1);
+  }
+  const cfg = loadBrandConfig(opts.configFile, accountId, campaignId);
+  const errors = validateEnableBrandGuidelinesBody(cfg);
+  if (errors.length > 0) {
+    console.error("\n\u274C Enable Brand Guidelines \u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A");
+    for (const e of errors) console.error(`   \u2022 ${e}`);
+    console.error();
+    process.exit(1);
+  }
+  await withGoogleApi(opts, async (config, googleApiUrl) => {
+    let body;
+    try {
+      body = await buildEnableBrandGuidelinesApiBody(
+        opts.configFile,
+        cfg,
+        accountId,
+        config,
+        googleApiUrl,
+        opts.verbose
+      );
+    } catch (err) {
+      console.error(
+        `
+\u274C \u6784\u5EFA brand-guidelines/enable \u8BF7\u6C42\u4F53\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(1);
+    }
+    const url = pmaxBrandGuidelinesEnableUrl(googleApiUrl, accountId, campaignId);
+    try {
+      await pmaxApiFetch(
+        url,
+        config,
+        { method: "POST", body: JSON.stringify(body) },
+        opts.verbose
+      );
+    } catch (err) {
+      console.error(
+        `
+\u274C \u542F\u7528 Brand Guidelines \u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(1);
+    }
+    if (await emitPmaxResult(
+      { ...opts, account: accountId },
+      `ad-pmax-brand-guidelines-enable-${accountId}`,
+      "ad pmax-brand-guidelines-enable",
+      { ok: true, campaignId, body },
+      campaignId
+    )) {
+      return;
+    }
+    console.log(`
+\u2705 PMax \u6D3B\u52A8 ${campaignId} \u5DF2\u542F\u7528 Brand Guidelines\uFF08\u4E0D\u53EF\u5173\u95ED\uFF09
+`);
+    console.log("   \u540E\u7EED\u6539\u54C1\u724C\u8BF7\u7528\uFF1Aad pmax-brand-assets-edit\n");
+  });
+}
+
 // src/commands/ad/_register.ts
 function register20(program2) {
   const adCmd = program2.command("ad").description(
@@ -117714,9 +118149,27 @@ function register20(program2) {
       await runAdPmaxEdit(opts);
     }
   );
+  addPmaxJsonOptions(
+    adCmd.command("pmax-brand-assets-edit").description(
+      "\u66F4\u65B0 PMax Campaign \u7EA7\u54C1\u724C\u8D44\u4EA7/\u6837\u5F0F\uFF08PATCH .../brand-assets\uFF1BBG \u5DF2\u5F00\u542F\u65F6\u7528\u6B64\u547D\u4EE4\uFF0C\u52FF pmax-assets-update \u6539 BUSINESS_NAME/LOGO\uFF09\n  \u6A21\u677F pmax-brand-assets-template.json"
+    ).requiredOption("-a, --account <id>", "Google \u5A92\u4F53\u5BA2\u6237 ID").requiredOption("--campaign-id <id>", "\u6D3B\u52A8 ID").requiredOption("--patch-file <path>", "PATCH JSON\uFF08\u81F3\u5C11\u4F20\u4E00\u9879\u53D8\u66F4\u5B57\u6BB5\uFF09").option("-t, --token <token>", "Auth Token")
+  ).action(
+    async (opts) => {
+      await runAdPmaxBrandAssetsEdit(opts);
+    }
+  );
+  addPmaxJsonOptions(
+    adCmd.command("pmax-brand-guidelines-enable").description(
+      "\u5B58\u91CF PMax \u6D3B\u52A8\u542F\u7528 Brand Guidelines\uFF08POST .../brand-guidelines/enable\uFF1B\u542F\u7528\u540E\u4E0D\u53EF\u5173\u95ED\uFF09\n  \u6A21\u677F pmax-brand-guidelines-enable-template.json"
+    ).requiredOption("--config-file <path>", "JSON \u914D\u7F6E\u8DEF\u5F84").option("-a, --account <id>", "Google \u5A92\u4F53\u5BA2\u6237 ID\uFF08\u53EF\u5199\u5728 JSON account\uFF09").option("--campaign-id <id>", "\u6D3B\u52A8 ID\uFF08\u53EF\u5199\u5728 JSON campaignId\uFF09").option("-t, --token <token>", "Auth Token")
+  ).action(
+    async (opts) => {
+      await runAdPmaxBrandGuidelinesEnable(opts);
+    }
+  );
   addPmaxJsonOptions(
     adCmd.command("pmax-asset-group-create").description(
-      "\u5728\u540C\u4E00 PMax \u6D3B\u52A8\u4E0B\u65B0\u5EFA\u8D44\u4EA7\u7EC4\uFF08\u6A21\u677F pmax-asset-group-template.json\uFF09"
+      "\u5728\u540C\u4E00 PMax \u6D3B\u52A8\u4E0B\u65B0\u5EFA\u8D44\u4EA7\u7EC4\uFF08\u6A21\u677F pmax-asset-group-template.json\uFF1BBG \u751F\u6548\u65F6\u81EA\u52A8\u7701\u7565\u54C1\u724C\u5B57\u6BB5\uFF09"
     ).requiredOption("--config-file <path>", "JSON \u914D\u7F6E\u8DEF\u5F84").option("-t, --token <token>", "Auth Token")
   ).action(
     async (opts) => {
@@ -117732,7 +118185,7 @@ function register20(program2) {
   );
   addPmaxJsonOptions(
     adCmd.command("pmax-assets-update").description(
-      "\u6279\u91CF\u94FE\u63A5/\u53D6\u6D88\u94FE\u63A5/\u66FF\u6362\u8D44\u4EA7\uFF08PUT .../assets\uFF1B\u6A21\u677F pmax-assets-update-template.json\uFF09"
+      "\u6279\u91CF\u94FE\u63A5/\u53D6\u6D88\u94FE\u63A5/\u66FF\u6362\u8D44\u4EA7\uFF08PUT .../assets\uFF1BBG \u751F\u6548\u65F6\u52FF\u6539 BUSINESS_NAME/LOGO\uFF0C\u7528 pmax-brand-assets-edit\uFF09"
     ).requiredOption("--config-file <path>", "JSON \u914D\u7F6E\u8DEF\u5F84").option("-t, --token <token>", "Auth Token")
   ).action(
     async (opts) => {

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.29-beta.11",
-  "publishedAt": 1781252553270
+  "version": "1.1.29-beta.12",
+  "publishedAt": 1781511893004
 }

package/dist/skill/assets/pmax-asset-group-template.json

@@ -1,16 +1,24 @@
 {
-  "_comment": "追加 PMax 资产组：POST .../campaign/pmax/{campaignId}/asset-group",
+  "_meta": {
+    "schema": "pmax-asset-group/v2",
+    "doc": "pmax-asset-group-template.md",
+    "note": "POST .../campaign/pmax/{campaignId}/asset-group",
+    "agentPitfalls": [
+      "提交前 CLI 自动 GET 活动详情判断 Brand Guidelines",
+      "BG 生效（_brandGuidelinesActive=true）时 businessName/Logo 可省略，CLI 自动剔除",
+      "BG 未生效时 businessName + Logo 必填",
+      "勿在 BG 生效后对 AG 用 pmax-assets-update 改 BUSINESS_NAME/LOGO"
+    ]
+  },
   "account": "6326027735",
   "campaignId": "12345678901",
   "name": "AG-Second",
   "finalUrls": ["https://www.example.com/landing"],
-  "businessName": "Test Brand Co",
   "headlines": ["Headline one ok", "Headline two ok", "Headline three ok"],
   "longHeadlines": ["Long headline for performance max"],
   "descriptions": ["Description one ok", "Description two ok"],
   "imagePaths": {
     "marketing": "./images/marketing.jpg",
-    "square": "./images/square.jpg",
-    "logo": "./images/logo.png"
+    "square": "./images/square.jpg"
   }
 }

package/dist/skill/assets/pmax-asset-group-template.md

@@ -0,0 +1,25 @@
+# `ad pmax-asset-group-create` JSON
+
+在同一 PMax 活动下追加资产组。
+
+```bash
+siluzan-tso ad pmax-get -a <accountId> --campaign-id <cid> --json-out ./snap
+siluzan-tso ad pmax-asset-group-create --config-file ./ag.json --json-out ./snap
+```
+
+模板：[`pmax-asset-group-template.json`](pmax-asset-group-template.json)
+
+## Brand Guidelines 分支（Agent 必读）
+
+CLI **自动** GET 活动详情，无需手填开关：
+
+| `_brandGuidelinesActive`（来自 pmax-get） | JSON 要求 |
+|-------------------------------------------|-----------|
+| `true` | **省略** `businessName`、`logoImage*`、`imagePaths.logo`（仅横图+方图） |
+| `false` | **必填** `businessName` + Logo（三图齐全） |
+
+若 JSON 在 BG 生效时仍含品牌字段，CLI 会警告并忽略（不阻断）。
+
+## 字段
+
+与 `pmax-create` 资产组部分相同（`name`、`finalUrls`、标题/描述、营销图）。`campaignId` 必填。

package/dist/skill/assets/pmax-brand-assets-template.json

@@ -0,0 +1,25 @@
+{
+  "_meta": {
+    "schema": "pmax-brand-assets/v1",
+    "doc": "pmax-brand-assets-template.md",
+    "note": "PATCH .../campaign/pmax/{campaignId}/brand-assets；Brand Guidelines 已开启时使用",
+    "agentPitfalls": [
+      "须先 ad pmax-get 确认 _brandGuidelinesActive=true",
+      "BG 生效时勿用 pmax-assets-update 改 BUSINESS_NAME/LOGO（会 400）",
+      "至少传一项：businessName、logoImage*、landscapeLogoImage* 或 brandGuidelines",
+      "mainColor 与 accentColor 须成对",
+      "Logo 可填 imagePaths.logo，CLI 自动上传"
+    ]
+  },
+  "account": "REPLACE_mediaCustomerId",
+  "campaignId": "REPLACE_campaignId",
+  "businessName": "Renamed Brand Co",
+  "imagePaths": {
+    "logo": "./REPLACE_logo_1200x1200.png"
+  },
+  "brandGuidelines": {
+    "mainColor": "#112233",
+    "accentColor": "#445566",
+    "predefinedFontFamily": "Roboto"
+  }
+}

package/dist/skill/assets/pmax-brand-assets-template.md

@@ -0,0 +1,22 @@
+# `ad pmax-brand-assets-edit` PATCH JSON
+
+Brand Guidelines（BG）**已开启**时，改商家名 / Logo / 主色字体走 Campaign 级接口。
+
+```bash
+siluzan-tso ad pmax-get -a <accountId> --campaign-id <cid> --json-out ./snap
+# 确认 _brandGuidelinesActive === true 后：
+siluzan-tso ad pmax-brand-assets-edit -a <accountId> --campaign-id <cid> \
+  --patch-file ./brand-patch.json --json-out ./snap
+```
+
+模板：[`pmax-brand-assets-template.json`](pmax-brand-assets-template.json)
+
+| 字段 | 说明 |
+|------|------|
+| `businessName` | 商家名（≤25 字符） |
+| `logoImageAssetId` / `logoImageBase64` / `imagePaths.logo` | Logo 三选一 |
+| `landscapeLogoImageAssetId` / `landscapeLogoImageBase64` / `imagePaths.landscapeLogo` | 可选横版 Logo |
+| `brandGuidelines.mainColor` / `accentColor` | 须成对 |
+| `brandGuidelines.predefinedFontFamily` | 如 `Roboto` |
+
+**至少传一项**。改完后 `ad pmax-get` 刷新，品牌读 `brandAssets[]`。

package/dist/skill/assets/pmax-brand-guidelines-enable-template.json

@@ -0,0 +1,24 @@
+{
+  "_meta": {
+    "schema": "pmax-brand-guidelines-enable/v1",
+    "doc": "pmax-brand-guidelines-enable-template.md",
+    "note": "POST .../campaign/pmax/{campaignId}/brand-guidelines/enable；启用后不可关闭",
+    "agentPitfalls": [
+      "仅当 pmax-get 显示 _brandGuidelinesActive=false 时使用",
+      "autoPopulateBrandAssets=true 时可省略 businessName/Logo（Google 自动选）",
+      "Travel Goals PMax 不支持 BG",
+      "启用成功后改品牌走 ad pmax-brand-assets-edit"
+    ]
+  },
+  "account": "REPLACE_mediaCustomerId",
+  "campaignId": "REPLACE_campaignId",
+  "autoPopulateBrandAssets": false,
+  "businessName": "Example Brand Co",
+  "imagePaths": {
+    "logo": "./REPLACE_logo_1200x1200.png"
+  },
+  "brandGuidelines": {
+    "mainColor": "#112233",
+    "accentColor": "#445566"
+  }
+}

package/dist/skill/assets/pmax-brand-guidelines-enable-template.md

@@ -0,0 +1,22 @@
+# `ad pmax-brand-guidelines-enable` JSON
+
+存量 PMax 活动启用 Brand Guidelines（**不可关闭**）。
+
+```bash
+siluzan-tso ad pmax-get -a <accountId> --campaign-id <cid> --json-out ./snap
+# _brandGuidelinesActive === false 时：
+siluzan-tso ad pmax-brand-guidelines-enable --config-file ./enable-bg.json --json-out ./snap
+```
+
+模板：[`pmax-brand-guidelines-enable-template.json`](pmax-brand-guidelines-enable-template.json)
+
+| 字段 | 必填 | 说明 |
+|------|:----:|------|
+| `account` | ✅ | 媒体客户 ID |
+| `campaignId` | ✅ | 活动 ID |
+| `autoPopulateBrandAssets` | | 默认 `false`；`true` 时 Google 自动选品牌资产 |
+| `businessName` | 条件 | `autoPopulateBrandAssets=false` 时必填 |
+| Logo 相关 | 条件 | `autoPopulateBrandAssets=false` 时必填（同 brand-assets 模板） |
+| `brandGuidelines` | | 可选样式 |
+
+启用后：`pmax-asset-group-create` 可省略 `businessName`/Logo；改品牌用 `pmax-brand-assets-edit`。

package/dist/skill/assets/pmax-create-template.json

@@ -7,6 +7,8 @@
       "勿与 Search campaign-create-template.json 混用（PMax 走 POST .../campaign/pmax，非 batch-asyncs）",
       "budget / targetCpa_BidingAmount 填主币种「元」，CLI 提交前 ×100 转 API 整型",
       "三张图：只填 imagePaths（pmax-create 会自动上传为 assetId）；勿把 Base64 写入 JSON",
+      "brandGuidelinesEnabled 省略时网关默认 true（Google v21+）；品牌在 Campaign 级 brandAssets[]，首个 AG 不含 Logo/商家名",
+      "改已上线品牌：先 pmax-get 看 _brandGuidelinesActive；true 用 pmax-brand-assets-edit，false 用 pmax-assets-update 或 pmax-brand-guidelines-enable",
       "本地视频：填 videoPath（或别名 video）；创建后 CLI 自动 PyAPI 上传并链接，与 --json-out 无关",
       "提交前：ad pmax-validate → 用户确认 → ad pmax-create",
       "campaignExtensions 可选：创建成功后 CLI 自动挂 callout/snippet/leadForm（非 pmax POST body）",

package/dist/skill/assets/pmax-create-template.md

@@ -18,7 +18,7 @@
 | 图片 | **只填 `imagePaths`** 指向本地 PNG/JPEG；`pmax-create` 会自动 multipart 上传并用 assetId 创建（勿把 Base64 提交进 Git） |
 | 视频 | JSON 填 **`videoPath`**（别名 `video` 亦可）；`pmax-create` 成功后 **必定**经 PyAPI 上传并链接（含 `--json-out`）。已有 YouTube 用 `youtubeUrlOrId` |
 | 附加资产 | 可选填 **`campaignExtensions`** |
-| 改已上线 PMax | `ad pmax-get` / `pmax-edit` / `pmax-assets-update` 等（见 `references/google-ads/pmax-api.md`） |
+| 改已上线 PMax | 先 `ad pmax-get` 看 `_brandGuidelinesActive`；改品牌见 `pmax-api.md` § Brand Guidelines |
 | 列表复核 | `ad campaigns -a <id> --json-out ./snap`，`channelTypeV2` 应为 `PERFORMANCE_MAX` |
 
 ---
@@ -63,6 +63,7 @@ siluzan-tso ad campaigns -a <accountId> --json-out ./snap
 | `biddingStrategyTypeV2` | string | | 默认 `MAXIMIZE_CONVERSIONS` |
 | `targetCpa_BidingAmount` | number | | `TARGET_CPA` 或带目标 CPA 的 `MAXIMIZE_CONVERSIONS` 时必填（**元**） |
 | `targetRoas` | number | | `TARGET_ROAS` 时必填（如 `2.5` = 250%） |
+| `brandGuidelinesEnabled` | boolean | | 省略 = 网关默认 `true`（Campaign 级 BG）；`false` = 品牌在 AssetGroup（旧路径） |
 | `videoPath` | string | | YOUTUBE_VIDEO（可选）：本地视频 ≥10s；与 `youtubeUrlOrId` 二选一，创建时最多 1 条；更多视频创建后用 `pmax-youtube-link` / `pmax-assets-update` 追加 |
 | `videoTitle` | string | | PyAPI 上传标题（默认文件名） |
 | `videoDescription` | string | | PyAPI 上传描述（可选） |

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

@@ -56,9 +56,11 @@
 
 | 能力 | 命令 |
 |------|------|
-| 详情 | `ad pmax-get -a <id> --campaign-id <cid>` |
+| 详情 | `ad pmax-get -a <id> --campaign-id <cid>`（读 `_brandGuidelinesActive`） |
 | 改活动 | `ad pmax-edit`（`--patch-file` 或 `--status` / `--budget` + `--budget-id`） |
-| 新资产组 | `ad pmax-asset-group-create --config-file …` |
+| 改 Campaign 品牌 | `ad pmax-brand-assets-edit`（BG 已开启） |
+| 启用 BG | `ad pmax-brand-guidelines-enable --config-file …`（存量活动） |
+| 新资产组 | `ad pmax-asset-group-create --config-file …`（BG 下自动省略品牌） |
 | 改资产组 | `ad pmax-asset-group-edit` |
 | 删资产组 | `ad pmax-asset-group-edit --status REMOVED`（软删；网关无 DELETE 端点） |
 | 改资产 | `ad pmax-assets-update --config-file …` |

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

@@ -18,8 +18,10 @@
 | `ad pmax-validate` | 本地校验 |
 | `ad pmax-create` | 创建系列（同步返回 `campaignId` 等） |
 | `ad pmax-channel-types` | 渠道类型列表 |
-| `ad pmax-get` | 系列详情 |
-| `ad pmax-edit` | 编辑系列 |
+| `ad pmax-get` | 系列详情（含 `brandAssets[]`；`--json-out` 附加 `_brandGuidelinesActive`、`_agentBrandHint`） |
+| `ad pmax-edit` | 编辑系列（预算/出价/状态；**不可**改 `brandGuidelinesEnabled`） |
+| `ad pmax-brand-assets-edit` | BG 已开启时改 Campaign 级品牌（商家名/Logo/样式） |
+| `ad pmax-brand-guidelines-enable` | 存量活动启用 BG（不可关闭） |
 | `ad pmax-asset-group-create` | 新建资产组 |
 | `ad pmax-asset-group-edit` | 编辑资产组 |
 | `ad pmax-assets-update` | 更新资产 |
@@ -33,7 +35,7 @@
 | `ad extension callout` / `snippet` / `lead-form` / `whatsapp` | 宣传信息 / 结构化摘要 / 潜在客户表单 / WhatsApp |
 | `ad extension list` | 查询已挂载扩展（`--type` / `--campaign-id`） |
 
-模板：`assets/pmax-create-template.json`、`pmax-asset-group-template.json`、`pmax-assets-update-template.json`、`pmax-signals-template.json`、`pmax-patch-campaign-template.json`、`pmax-lead-form-template.json`。
+模板：`assets/pmax-create-template.json`、`pmax-asset-group-template.json`、`pmax-assets-update-template.json`、`pmax-signals-template.json`、`pmax-patch-campaign-template.json`、`pmax-brand-assets-template.json`、`pmax-brand-guidelines-enable-template.json`、`pmax-lead-form-template.json`。
 
 ### 附加资产（Callout / Snippet / Lead Form）
 
@@ -147,13 +149,38 @@ siluzan-tso ad pmax-youtube-link -a <id> --asset-group-id <agId> --campaign-id <
 
 ---
 
+## Brand Guidelines（品牌手册，Google v21+）
+
+Google v21+ 新建 PMax **默认开启** BG：`businessName` / Logo 挂在 **Campaign**（`brandAssets[]`），全活动共用；首个 AssetGroup 的 `assets[]` **不含** 品牌。
+
+### Agent 决策（必读）
+
+1. **任何编辑前先** `ad pmax-get --json-out` → 读 `_brandGuidelinesActive`（或 `_agentBrandHint`）
+2. BG 生效 → 改品牌用 `ad pmax-brand-assets-edit`；追加 AG **省略** 品牌字段
+3. BG 未生效 → 改品牌在 AssetGroup 上用 `ad pmax-assets-update`；或 `ad pmax-brand-guidelines-enable` 启用 BG
+
+| 场景 | 命令 |
+|------|------|
+| 创建（默认 BG 开） | `pmax-create` JSON 仍必填 `businessName`+Logo；可省略 `brandGuidelinesEnabled` |
+| 创建（旧路径） | JSON 加 `"brandGuidelinesEnabled": false` |
+| 改 Campaign 级品牌 | `ad pmax-brand-assets-edit -a <id> --campaign-id <cid> --patch-file ./brand.json` |
+| 存量启用 BG | `ad pmax-brand-guidelines-enable --config-file ./enable-bg.json` |
+| 追加资产组 | `pmax-asset-group-create`（CLI 自动判断，BG 下无需 Logo/商家名） |
+
+**禁止**：BG 生效时对 AssetGroup 执行 `pmax-assets-update` 链接 `BUSINESS_NAME`/`LOGO`/`LANDSCAPE_LOGO`（CLI 预检阻断，网关亦 400）。
+
+模板：`assets/pmax-brand-assets-template.md`、`pmax-brand-guidelines-enable-template.md`。
+
+---
+
 ## 编辑流程
 
-1. `ad pmax-get` 拉详情
+1. `ad pmax-get` 拉详情（读 `_brandGuidelinesActive`）
 2. 改系列 → `ad pmax-edit` 或 `--patch-file`
-3. 改资产组 → `ad pmax-asset-group-edit`
-4. 改资产 → `ad pmax-assets-update`（`campaignId` 必填）
-5. 改信号 → `ad pmax-signals-get` → `ad pmax-audiences` → `ad pmax-signals-set`（一次带齐两类数组）
+3. **改品牌** → BG 生效：`ad pmax-brand-assets-edit`；未生效：`ad pmax-assets-update` 或先 `pmax-brand-guidelines-enable`
+4. 改资产组 → `ad pmax-asset-group-edit`
+5. 改 AG 内素材 → `ad pmax-assets-update`（`campaignId` 必填；勿改品牌 fieldType 若 BG 生效）
+6. 改信号 → `ad pmax-signals-get` → `ad pmax-audiences` → `ad pmax-signals-set`（一次带齐两类数组）
 
 ---
 

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.29-beta.11'
+$PKG_VERSION = '1.1.29-beta.12'
 $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.29-beta.11"
+readonly PKG_VERSION="1.1.29-beta.12"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
 readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"

package/eval/cases/pmax-asset-group-create-with-bg.scenario.json

@@ -0,0 +1,26 @@
+{
+  "id": "pmax-asset-group-create-with-bg",
+  "description": "BG 生效下追加资产组：pmax-get 后 pmax-asset-group-create",
+  "turns": [
+    "账户 {{EVAL_ACCOUNT_READ}} 的 PMax 活动 23856329277 已有，请再建一个资产组 AG-Second（营销图+标题描述即可，品牌活动级已有）。\n用 siluzan-tso pmax-asset-group-create --config-file，执行前可先 pmax-get --json-out ./snap-pmax。"
+  ],
+  "judgeExpectation": "路径：在同一 PMax 活动下追加资产组应先 `pmax-get` 判断 BG；BG 生效时 `pmax-asset-group-create`（不必重复 businessName/Logo），**不得** `pmax-create` 或 Search `campaign-create` 新建活动。\n输出：说明 CLI 会自动省略品牌字段；stub 即可。",
+  "skillMapping": "references/google-ads/pmax-api.md §5.1；assets/pmax-asset-group-template.md",
+  "judgeReferencePaths": [
+    "references/google-ads/pmax-api.md",
+    "assets/pmax-asset-group-template.md"
+  ],
+  "commandMustInclude": [
+    [
+      "pmax-get"
+    ],
+    [
+      "pmax-asset-group-create"
+    ]
+  ],
+  "commandMustNotInclude": [
+    "pmax-create",
+    "campaign-create",
+    "ad campaign-create"
+  ]
+}

package/eval/cases/pmax-brand-edit-routing.scenario.json

@@ -0,0 +1,25 @@
+{
+  "id": "pmax-brand-edit-routing",
+  "description": "PMax 改商家名：先 pmax-get，BG 生效时用 pmax-brand-assets-edit",
+  "turns": [
+    "Google 账户 {{EVAL_ACCOUNT_READ}} 的 PMax 活动 campaignId=23856329277，只改商家名为「New Brand Co」，Logo 不动。\n按 SKILL 用 siluzan-tso 执行；需要结构化数据时加 --json-out ./snap-pmax。"
+  ],
+  "judgeExpectation": "路径：应先 `ad pmax-get`（带 --json-out）确认 `_brandGuidelinesActive` 或 brandAssets；BG 生效时改商家名/Logo 须 `ad pmax-brand-assets-edit --patch-file`，不得 `pmax-assets-update` 链接 BUSINESS_NAME/LOGO，不得 `ad campaign-edit`。\n输出：说明改的是 Campaign 级 brandAssets；stub 即可。",
+  "skillMapping": "references/google-ads/pmax-api.md § Brand Guidelines",
+  "judgeReferencePaths": [
+    "references/google-ads/pmax-api.md"
+  ],
+  "commandMustInclude": [
+    [
+      "pmax-get"
+    ],
+    [
+      "pmax-brand-assets-edit"
+    ]
+  ],
+  "commandMustNotInclude": [
+    "pmax-assets-update",
+    "campaign-edit",
+    "ad campaign-edit"
+  ]
+}

package/eval/cases/pmax-edit-not-campaign-edit.scenario.json

@@ -0,0 +1,25 @@
+{
+  "id": "pmax-edit-not-campaign-edit",
+  "description": "改 PMax 日预算须 pmax-edit（勿 campaign-edit）",
+  "turns": [
+    "把 Google 账户 {{EVAL_ACCOUNT_READ}} 的 PMax 活动 23856329277 日预算从 50 调到 80 元。\n按 SKILL 用 siluzan-tso 执行，--json-out ./snap-pmax。"
+  ],
+  "judgeExpectation": "路径：改 PMax 日预算应先 `pmax-get` 取 budgetId，再 `ad pmax-edit`（budget + budgetId 成对）；**不得** `ad campaign-edit`（会 400）。\n输出：说明 PMax 与 Search 系列 API 隔离；stub 即可。",
+  "skillMapping": "references/google-ads/pmax-api.md §4.3",
+  "judgeReferencePaths": [
+    "references/google-ads/pmax-api.md",
+    "references/google-ads/google-ads.md"
+  ],
+  "commandMustInclude": [
+    [
+      "pmax-get"
+    ],
+    [
+      "pmax-edit"
+    ]
+  ],
+  "commandMustNotInclude": [
+    "campaign-edit",
+    "ad campaign-edit"
+  ]
+}

package/eval/cases/pmax-enable-brand-guidelines.scenario.json

@@ -0,0 +1,25 @@
+{
+  "id": "pmax-enable-brand-guidelines",
+  "description": "存量 PMax 启用 Brand Guidelines",
+  "turns": [
+    "账户 {{EVAL_ACCOUNT_WRITE}} 的 PMax 活动 23856329277 是旧活动，还没开 Brand Guidelines，现在要启用并带上商家名和 Logo（config 已准备好）。\n请用 siluzan-tso 执行，--json-out ./snap-pmax。"
+  ],
+  "judgeExpectation": "路径：存量活动 `_brandGuidelinesActive=false` 时启用 BG 应 `pmax-get` 确认后 `ad pmax-brand-guidelines-enable --config-file`；启用后不可关闭；后续改品牌走 `pmax-brand-assets-edit`。\n输出：说明 enable 与 edit 分工；stub 即可。",
+  "skillMapping": "references/google-ads/pmax-api.md §4.3.1",
+  "judgeReferencePaths": [
+    "references/google-ads/pmax-api.md",
+    "assets/pmax-brand-guidelines-enable-template.md"
+  ],
+  "commandMustInclude": [
+    [
+      "pmax-get"
+    ],
+    [
+      "pmax-brand-guidelines-enable"
+    ]
+  ],
+  "commandMustNotInclude": [
+    "campaign-edit",
+    "ad campaign-edit"
+  ]
+}

package/eval/cases/pmax-no-assets-update-brand-fields.scenario.json

@@ -0,0 +1,23 @@
+{
+  "id": "pmax-no-assets-update-brand-fields",
+  "description": "BG 生效时禁止用 pmax-assets-update 改 BUSINESS_NAME/LOGO",
+  "turns": [
+    "PMax 活动 23856329277（账户 {{EVAL_ACCOUNT_READ}}）要换 Logo 图片，新 Logo 已准备好 patch JSON。\nBrand Guidelines 已开启。请用 siluzan-tso 正确命令执行，--json-out ./snap-pmax。"
+  ],
+  "judgeExpectation": "路径：用户要在 PMax 上换 Logo 时，若 BG 已生效，应 `pmax-get` 后走 `pmax-brand-assets-edit`，**不得** `pmax-assets-update` 对 AssetGroup PUT LOGO/BUSINESS_NAME（CLI 预检与网关均会 400）。\n输出：说明 Campaign 级品牌与 AssetGroup 素材分离；stub 即可。",
+  "skillMapping": "references/google-ads/pmax-api.md § Brand Guidelines",
+  "judgeReferencePaths": [
+    "references/google-ads/pmax-api.md"
+  ],
+  "commandMustInclude": [
+    [
+      "pmax-get"
+    ],
+    [
+      "pmax-brand-assets-edit"
+    ]
+  ],
+  "commandMustNotInclude": [
+    "pmax-assets-update"
+  ]
+}

package/eval/stub-fixtures/pmax-asset-group-create-ok.json

@@ -0,0 +1,12 @@
+{
+  "kind": "siluzan-tso-cli-json-snapshot",
+  "schemaVersion": 1,
+  "section": "ad-pmax-asset-group-create-stub",
+  "outlineFile": "ad-pmax-asset-group-create-stub.outline.txt",
+  "payloadPreview": {
+    "id": "98765432199",
+    "name": "AG-Second",
+    "_brandGuidelinesActive": true,
+    "_warnings": ["活动 Brand Guidelines 已生效：businessName/Logo 已被 CLI 忽略"]
+  }
+}

package/eval/stub-fixtures/pmax-brand-assets-edit-ok.json

@@ -0,0 +1,11 @@
+{
+  "kind": "siluzan-tso-cli-json-snapshot",
+  "schemaVersion": 1,
+  "section": "ad-pmax-brand-assets-edit-stub",
+  "outlineFile": "ad-pmax-brand-assets-edit-stub.outline.txt",
+  "payloadPreview": {
+    "ok": true,
+    "campaignId": "23856329277",
+    "patch": { "businessName": "New Brand Co" }
+  }
+}

package/eval/stub-fixtures/pmax-brand-guidelines-enable-ok.json

@@ -0,0 +1,11 @@
+{
+  "kind": "siluzan-tso-cli-json-snapshot",
+  "schemaVersion": 1,
+  "section": "ad-pmax-brand-guidelines-enable-stub",
+  "outlineFile": "ad-pmax-brand-guidelines-enable-stub.outline.txt",
+  "payloadPreview": {
+    "ok": true,
+    "campaignId": "23856329277",
+    "body": { "autoPopulateBrandAssets": false, "businessName": "Test Brand Co" }
+  }
+}

package/eval/stub-fixtures/pmax-edit-ok.json

@@ -0,0 +1,11 @@
+{
+  "kind": "siluzan-tso-cli-json-snapshot",
+  "schemaVersion": 1,
+  "section": "ad-pmax-edit-stub",
+  "outlineFile": "ad-pmax-edit-stub.outline.txt",
+  "payloadPreview": {
+    "ok": true,
+    "campaignId": "23856329277",
+    "patch": { "budgetId": "111222333", "budget": 8000 }
+  }
+}

package/eval/stub-fixtures/pmax-get-bg-on.json

@@ -0,0 +1,20 @@
+{
+  "kind": "siluzan-tso-cli-json-snapshot",
+  "schemaVersion": 1,
+  "section": "ad-pmax-get-stub",
+  "outlineFile": "ad-pmax-get-stub.outline.txt",
+  "agentHint": "payload 含 _brandGuidelinesActive；改品牌见 _agentBrandHint",
+  "payloadPreview": {
+    "id": "23856329277",
+    "name": "PMAX_Stub_BG_On",
+    "brandGuidelinesEnabled": true,
+    "brandAssets": [
+      { "fieldType": "BUSINESS_NAME", "text": "Old Brand Co", "linkStatus": "ENABLED" },
+      { "fieldType": "LOGO", "assetId": "365402561157", "linkStatus": "ENABLED" }
+    ],
+    "budgetId": "111222333",
+    "budget": 5000,
+    "_brandGuidelinesActive": true,
+    "_agentBrandHint": "改商家名/Logo/样式：ad pmax-brand-assets-edit（勿 pmax-assets-update 改 BUSINESS_NAME/LOGO）"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.1.29-beta.11",
+  "version": "1.1.29-beta.12",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",