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

package/README.md

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

package/dist/index.js

@@ -112493,6 +112493,120 @@ async function runAdEdit(opts) {
 init_auth();
 init_cli_json_snapshot();
 init_strip_legacy_google_fields();
+
+// src/commands/ad/extension-lead-form.ts
+import { readFileSync as readFileSync5 } from "fs";
+var VALID_LEAD_FORM_INPUT_TYPES = [
+  "FULL_NAME",
+  "FIRST_NAME",
+  "LAST_NAME",
+  "EMAIL",
+  "PHONE_NUMBER",
+  "COMPANY_NAME",
+  "WORK_EMAIL",
+  "WORK_PHONE",
+  "JOB_TITLE",
+  "CITY",
+  "REGION",
+  "COUNTRY",
+  "POSTAL_CODE",
+  "STREET_ADDRESS"
+];
+function loadLeadFormExtensionConfig(configFile) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync5(configFile, "utf8"));
+  } catch {
+    console.error(`
+\u274C \u8BFB\u53D6\u914D\u7F6E\u6587\u4EF6\u5931\u8D25\uFF08${configFile}\uFF09
+`);
+    process.exit(1);
+  }
+  const cfg = stripMetaKeys(raw);
+  const result = validateLeadFormExtensionConfig(cfg);
+  if (!result.ok) {
+    console.error("\n\u274C Lead Form \u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A\n");
+    for (const e of result.errors) console.error(`  - ${e}`);
+    console.error();
+    process.exit(1);
+  }
+  return cfg;
+}
+function validateLeadFormPayload(lf, prefix = "leadForm") {
+  const errors = [];
+  if (!lf || typeof lf !== "object") {
+    errors.push(`${prefix} \u5BF9\u8C61\u4E0D\u80FD\u4E3A\u7A7A`);
+    return errors;
+  }
+  if (!lf.businessName?.trim()) errors.push(`${prefix}.businessName \u4E0D\u80FD\u4E3A\u7A7A`);
+  if (!lf.headline?.trim()) errors.push(`${prefix}.headline \u4E0D\u80FD\u4E3A\u7A7A`);
+  if (!lf.description?.trim()) errors.push(`${prefix}.description \u4E0D\u80FD\u4E3A\u7A7A`);
+  if (!lf.privacyPolicyUrl?.trim()) errors.push(`${prefix}.privacyPolicyUrl \u4E0D\u80FD\u4E3A\u7A7A`);
+  if (!lf.finalUrl?.trim()) errors.push(`${prefix}.finalUrl \u4E0D\u80FD\u4E3A\u7A7A`);
+  if (!Array.isArray(lf.fields) || lf.fields.length === 0) {
+    errors.push(`${prefix}.fields \u81F3\u5C11 1 \u9879`);
+  } else {
+    for (let i = 0; i < lf.fields.length; i++) {
+      const f = lf.fields[i];
+      const t = f?.inputType?.trim();
+      if (!t) {
+        errors.push(`${prefix}.fields[${i}].inputType \u4E0D\u80FD\u4E3A\u7A7A`);
+        continue;
+      }
+      if (!VALID_LEAD_FORM_INPUT_TYPES.includes(t)) {
+        errors.push(
+          `${prefix}.fields[${i}].inputType \u65E0\u6548\uFF1A${t}\uFF1B\u652F\u6301 ${VALID_LEAD_FORM_INPUT_TYPES.join(", ")}`
+        );
+      }
+    }
+  }
+  return errors;
+}
+function validateLeadFormExtensionConfig(cfg) {
+  const errors = [];
+  if (!cfg.account?.trim()) errors.push("account\uFF08\u5A92\u4F53\u5BA2\u6237 ID\uFF09\u4E0D\u80FD\u4E3A\u7A7A");
+  if (!cfg.campaignId?.trim()) errors.push("campaignId\uFF08PMax \u6D3B\u52A8 ID\uFF09\u4E0D\u80FD\u4E3A\u7A7A");
+  errors.push(...validateLeadFormPayload(cfg.leadForm, "leadForm"));
+  return { ok: errors.length === 0, errors };
+}
+function buildLeadFormExtensionBody(cfg, extensionId) {
+  const lf = cfg.leadForm;
+  const body = {
+    activeuseridg: cfg.account,
+    campaignId: cfg.campaignId,
+    level: "Campaign",
+    typeV2: "LEAD_FORM",
+    assetFieldType: "LEAD_FORM",
+    leadForm: {
+      businessName: lf.businessName.trim(),
+      headline: lf.headline.trim(),
+      description: lf.description.trim(),
+      privacyPolicyUrl: lf.privacyPolicyUrl.trim(),
+      finalUrl: lf.finalUrl.trim(),
+      callToActionType: lf.callToActionType?.trim() || "LEARN_MORE",
+      callToActionDescription: lf.callToActionDescription?.trim() || "Contact us",
+      fields: lf.fields.map((f) => ({
+        inputType: f.inputType.trim(),
+        ...f.singleChoiceAnswers?.length ? { singleChoiceAnswers: f.singleChoiceAnswers } : {}
+      })),
+      ...lf.postSubmitHeadline?.trim() ? { postSubmitHeadline: lf.postSubmitHeadline.trim() } : {},
+      ...lf.postSubmitDescription?.trim() ? { postSubmitDescription: lf.postSubmitDescription.trim() } : {},
+      ...lf.postSubmitCallToActionType?.trim() ? { postSubmitCallToActionType: lf.postSubmitCallToActionType.trim() } : {},
+      ...lf.customDisclosure?.trim() ? { customDisclosure: lf.customDisclosure.trim() } : {},
+      ...lf.webhook ? {
+        webhook: {
+          ...lf.webhook.advertiserWebhookUrl?.trim() ? { advertiserWebhookUrl: lf.webhook.advertiserWebhookUrl.trim() } : {},
+          ...lf.webhook.googleSecret?.trim() ? { googleSecret: lf.webhook.googleSecret.trim() } : {},
+          payloadSchemaVersion: lf.webhook.payloadSchemaVersion ?? 3
+        }
+      } : {}
+    }
+  };
+  if (extensionId) body["id"] = extensionId;
+  return body;
+}
+
+// src/commands/ad/extension.ts
 async function runAdExtensionList(opts) {
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
@@ -112513,6 +112627,10 @@ async function runAdExtensionList(opts) {
       (i) => String(i["typeV2"] ?? i["assetFieldType"] ?? "").toUpperCase() === filterType
     );
   }
+  if (opts.campaignId) {
+    const cid = opts.campaignId.trim();
+    items = items.filter((i) => String(i["campaignId"] ?? "") === cid);
+  }
   const n = items.length;
   const extPayload = stripLegacyGoogleFieldsIfV2Present(
     wrapListJson({ page: 1, pageSize: Math.max(n, 1), total: n, items })
@@ -112550,8 +112668,12 @@ async function runAdExtensionList(opts) {
     } else if (type === "STRUCTURED_SNIPPET") {
       const ssn = item["structuredSnippetHeaderValue"];
       if (ssn) detail = `${ssn["key"]}: ${ssn["value"]?.join(", ")}`;
+    } else if (type === "LEAD_FORM") {
+      const lf = item["leadForm"];
+      if (lf) detail = `\u300C${lf["headline"] ?? ""}\u300D business=${lf["businessName"] ?? ""}`;
     }
-    console.log(`  [${type}] id:${id}  level:${level}  ${detail}`);
+    const camp = item["campaignId"] ? `  campaign:${item["campaignId"]}` : "";
+    console.log(`  [${type}] id:${id}  level:${level}${camp}  ${detail}`);
   }
   console.log();
 }
@@ -112658,6 +112780,168 @@ async function runAdExtensionDelete(opts) {
 \u2705 \u9644\u52A0\u4FE1\u606F ${opts.id} \u5DF2\u5220\u9664
 `);
 }
+async function runAdExtensionPmaxTypes(opts) {
+  const config = loadConfig(opts.token);
+  const googleApiUrl = requireGoogleApi(config);
+  const url = `${googleApiUrl}/extensionmanagement/pmaxSupportedTypeList`;
+  let data;
+  try {
+    data = await apiFetch2(url, config, {}, opts.verbose);
+  } catch (err) {
+    console.error(`
+\u274C \u67E5\u8BE2 PMax \u9644\u52A0\u8D44\u4EA7\u7C7B\u578B\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  if (await emitCliJsonOrSnapshot(opts, {
+    section: "ad-extension-pmax-types",
+    commandLabel: "ad extension pmax-types",
+    payload: data
+  })) {
+    return;
+  }
+  const obj = data ?? {};
+  const types = obj["supportedTypes"] ?? [];
+  console.log("\nPMax \u652F\u6301\u7684\u9644\u52A0\u8D44\u4EA7\u7C7B\u578B\uFF1A\n");
+  for (const t of types) {
+    console.log(`  - ${t["name"] ?? t["typeV2"]} (id=${t["id"]})`);
+  }
+  const levels = obj["supportedLevels"]?.join(", ") ?? "";
+  const lfLevels = obj["leadFormSupportedLevels"]?.join(", ") ?? "";
+  console.log(`
+  \u652F\u6301\u5C42\u7EA7\uFF1A${levels}`);
+  console.log(`  Lead Form \u5C42\u7EA7\uFF1A${lfLevels}`);
+  console.log("  \u4E0D\u652F\u6301\uFF1AAd Group\uFF08PMax \u4F1A 400\uFF09");
+  console.log("  WhatsApp\uFF1A\u540E\u7AEF\u5C1A\u672A\u5F00\u653E\uFF08\u540E\u7EED\u9636\u6BB5\uFF09\n");
+}
+async function runAdExtensionSnippetHeaders(opts) {
+  const config = loadConfig(opts.token);
+  const googleApiUrl = requireGoogleApi(config);
+  const url = `${googleApiUrl}/extensionmanagement/structuredSnippetHeaders`;
+  let data;
+  try {
+    data = await apiFetch2(url, config, {}, opts.verbose);
+  } catch (err) {
+    console.error(
+      `
+\u274C \u67E5\u8BE2\u7ED3\u6784\u5316\u6458\u8981\u6807\u5934\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`
+    );
+    process.exit(1);
+  }
+  if (await emitCliJsonOrSnapshot(opts, {
+    section: "ad-extension-snippet-headers",
+    commandLabel: "ad extension snippet-headers",
+    payload: data
+  })) {
+    return;
+  }
+  const rows = data ?? [];
+  console.log("\n\u7ED3\u6784\u5316\u6458\u8981\u6807\u5934\uFF08\u6309\u8BED\u8A00\uFF09\uFF1A\n");
+  for (const row of rows) {
+    if (Array.isArray(row)) {
+      console.log(`  ${row[0]}: ${row[1].join(", ")}`);
+    } else if (row && typeof row === "object") {
+      const lang = row.Key ?? "Unknown";
+      const vals = row.Value ?? [];
+      console.log(`  ${lang}: ${vals.join(", ")}`);
+    }
+  }
+  console.log();
+}
+async function runAdExtensionLeadFormCreate(opts) {
+  const config = loadConfig(opts.token);
+  const googleApiUrl = requireGoogleApi(config);
+  let cfg;
+  if (opts.configFile) {
+    cfg = loadLeadFormExtensionConfig(opts.configFile);
+    if (opts.account && opts.account !== cfg.account) {
+      console.error("\n\u274C --account \u4E0E\u914D\u7F6E\u6587\u4EF6 account \u4E0D\u4E00\u81F4\n");
+      process.exit(1);
+    }
+    if (opts.campaignId && opts.campaignId !== cfg.campaignId) {
+      console.error("\n\u274C --campaign-id \u4E0E\u914D\u7F6E\u6587\u4EF6 campaignId \u4E0D\u4E00\u81F4\n");
+      process.exit(1);
+    }
+  } else {
+    console.error(
+      "\n\u274C Lead Form \u987B\u4F7F\u7528 --config-file\uFF08\u6A21\u677F\u89C1 assets/pmax-lead-form-template.json\uFF09\n"
+    );
+    process.exit(1);
+  }
+  const body = buildLeadFormExtensionBody(cfg);
+  const url = `${googleApiUrl}/extensionmanagement/extension/${cfg.account}`;
+  let response;
+  try {
+    response = await apiFetch2(
+      url,
+      config,
+      { method: "POST", body: JSON.stringify(body) },
+      opts.verbose
+    );
+  } catch (err) {
+    console.error(`
+\u274C \u521B\u5EFA Lead Form \u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  if (await emitCliJsonOrSnapshot(opts, {
+    section: `ad-extension-lead-form-${cfg.account}`,
+    commandLabel: "ad extension lead-form",
+    commandHint: `${cfg.account}:${cfg.campaignId}`,
+    payload: response,
+    idSuffix: cfg.campaignId
+  })) {
+    return;
+  }
+  const resObj = response ?? {};
+  const extId = resObj["id"];
+  console.log(
+    `
+\u2705 PMax Lead Form \u5DF2\u521B\u5EFA\uFF08campaignId: ${cfg.campaignId}${extId ? `\uFF0Cid: ${extId}` : ""}\uFF09
+`
+  );
+  console.log(
+    "\u63D0\u793A\uFF1A\u521B\u5EFA\u6210\u529F\u540E\u540E\u7AEF\u4F1A\u81EA\u52A8\u5C1D\u8BD5\u5F00\u542F SUBMIT_LEAD_FORM + GOOGLE_HOSTED \u8F6C\u5316\u76EE\u6807\uFF08biddable=true\uFF09\u3002\n"
+  );
+}
+async function runAdExtensionUpdate(opts) {
+  const config = loadConfig(opts.token);
+  const googleApiUrl = requireGoogleApi(config);
+  const cfg = loadLeadFormExtensionConfig(opts.configFile);
+  if (opts.account !== cfg.account) {
+    console.error("\n\u274C --account \u4E0E\u914D\u7F6E\u6587\u4EF6 account \u4E0D\u4E00\u81F4\n");
+    process.exit(1);
+  }
+  const body = buildLeadFormExtensionBody(cfg, opts.id);
+  const url = `${googleApiUrl}/extensionmanagement/extension/${opts.account}/${opts.id}`;
+  let response;
+  try {
+    response = await apiFetch2(
+      url,
+      config,
+      { method: "PUT", body: JSON.stringify(body) },
+      opts.verbose
+    );
+  } catch (err) {
+    console.error(`
+\u274C \u66F4\u65B0\u9644\u52A0\u4FE1\u606F\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  if (await emitCliJsonOrSnapshot(opts, {
+    section: `ad-extension-update-${opts.account}`,
+    commandLabel: "ad extension update",
+    commandHint: `${opts.account}:${opts.id}`,
+    payload: response,
+    idSuffix: opts.id
+  })) {
+    return;
+  }
+  console.log(`
+\u2705 \u9644\u52A0\u4FE1\u606F ${opts.id} \u5DF2\u66F4\u65B0
+`);
+}
 
 // src/commands/ad/search-terms.ts
 init_auth();
@@ -114606,7 +114890,7 @@ async function runPmaxImageValidation(configFile, cfg) {
 // src/commands/ad/pmax-image-resolve.ts
 init_auth();
 import { basename as basename4, dirname as dirname8, isAbsolute as isAbsolute3, resolve as resolve7 } from "path";
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 
 // src/commands/ad/pmax-urls.ts
 function pmaxChannelTypesUrl(googleApiUrl) {
@@ -114763,7 +115047,7 @@ async function uploadPmaxImageFileBase64(config, googleApiUrl, accountId, absIma
 async function uploadPmaxImageFile(config, googleApiUrl, accountId, absImagePath, name2, verbose) {
   const fileName = basename4(absImagePath);
   const assetName = (name2 ?? fileName).trim() || fileName;
-  const fileBuffer = readFileSync5(absImagePath);
+  const fileBuffer = readFileSync6(absImagePath);
   if (fileBuffer.length <= MAX_BASE64_UPLOAD_BYTES) {
     return uploadPmaxImageFileBase64(
       config,
@@ -114849,7 +115133,7 @@ function assertPmaxImageSlotsResolved(slots) {
 }
 
 // src/commands/ad/pmax-load.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 function loadPmaxCreateConfig(configFile) {
   const cfg = tryLoadPmaxCreateConfig(configFile);
   if (!cfg) {
@@ -114920,7 +115204,7 @@ function detectDeprecatedPmaxVideoKeys(raw) {
 function tryLoadPmaxCreateConfig(configFile) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync6(configFile, "utf8"));
+    raw = JSON.parse(readFileSync7(configFile, "utf8"));
   } catch {
     return null;
   }
@@ -114928,7 +115212,7 @@ function tryLoadPmaxCreateConfig(configFile) {
 }
 function loadPmaxCreateConfigRaw(configFile) {
   try {
-    const raw = JSON.parse(readFileSync6(configFile, "utf8"));
+    const raw = JSON.parse(readFileSync7(configFile, "utf8"));
     return stripMetaKeys(raw);
   } catch {
     return null;
@@ -114976,19 +115260,19 @@ function buildPmaxCreateUrl(googleApiUrl, accountId) {
 }
 
 // src/commands/ad/pmax-video-upload.ts
-import { existsSync as existsSync3, readFileSync as readFileSync8 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync9 } from "fs";
 import { basename as basename5, dirname as dirname10, isAbsolute as isAbsolute5, resolve as resolve9 } from "path";
 
 // src/commands/ad/pmax-shared.ts
 init_auth();
 init_cli_json_snapshot();
-import { readFileSync as readFileSync7 } from "fs";
+import { readFileSync as readFileSync8 } from "fs";
 import { dirname as dirname9, isAbsolute as isAbsolute4, resolve as resolve8 } from "path";
 var PMAX_MONEY_KEYS = /* @__PURE__ */ new Set(["budget", "targetCpa_BidingAmount"]);
 function loadPmaxJsonFile(configFile) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync7(configFile, "utf8"));
+    raw = JSON.parse(readFileSync8(configFile, "utf8"));
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     console.error(`
@@ -115175,7 +115459,7 @@ function runPmaxVideoValidation(configFile, cfg) {
     return { errors, warnings };
   }
   try {
-    const buf = readFileSync8(abs);
+    const buf = readFileSync9(abs);
     if (buf.length === 0) errors.push(`videoPath \u4E3A\u7A7A\u6587\u4EF6\uFF1A${abs}`);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
@@ -115238,7 +115522,7 @@ async function uploadPmaxLocalVideo(opts) {
   const fileName = basename5(opts.absVideoPath);
   const title = (opts.title ?? fileName).trim() || fileName;
   const description = (opts.description ?? "Uploaded via siluzan-tso PMax video upload").trim() || "Uploaded via siluzan-tso";
-  const fileBuffer = readFileSync8(opts.absVideoPath);
+  const fileBuffer = readFileSync9(opts.absVideoPath);
   const form = new FormData();
   form.append("media_account_id", opts.accountId.replace(/-/g, ""));
   form.append("title", title);
@@ -115294,7 +115578,7 @@ function validatePmaxVideoPathQuick(absPath) {
     return `\u89C6\u9891\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${absPath}`;
   }
   try {
-    if (readFileSync8(absPath).length === 0) return `\u89C6\u9891\u6587\u4EF6\u4E3A\u7A7A\uFF1A${absPath}`;
+    if (readFileSync9(absPath).length === 0) return `\u89C6\u9891\u6587\u4EF6\u4E3A\u7A7A\uFF1A${absPath}`;
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     return `\u65E0\u6CD5\u8BFB\u53D6\u89C6\u9891\u6587\u4EF6\uFF08${absPath}\uFF09\uFF1A${msg}`;
@@ -115358,6 +115642,197 @@ async function linkPmaxVideoAfterCreate(opts) {
   }
 }
 
+// src/commands/ad/pmax-campaign-extensions.ts
+init_auth();
+function validatePmaxCampaignExtensions(ext) {
+  const errors = [];
+  const warnings = [];
+  if (!ext) return { errors, warnings };
+  const callouts = ext.callouts ?? [];
+  for (let i = 0; i < callouts.length; i++) {
+    const text = callouts[i]?.trim();
+    if (!text) {
+      errors.push(`campaignExtensions.callouts[${i}] \u4E0D\u80FD\u4E3A\u7A7A`);
+      continue;
+    }
+    if (text.length > CALLOUT_TEXT_MAX_LEN) {
+      errors.push(
+        `campaignExtensions.callouts[${i}] \u8D85\u8FC7 ${CALLOUT_TEXT_MAX_LEN} \u5B57\u7B26\uFF08\u5F53\u524D ${text.length}\uFF09\uFF1A"${text}"`
+      );
+    }
+  }
+  const snippets = ext.structuredSnippets ?? [];
+  for (let i = 0; i < snippets.length; i++) {
+    const s = snippets[i];
+    const prefix = `campaignExtensions.structuredSnippets[${i}]`;
+    if (!s?.header?.trim()) {
+      errors.push(`${prefix}.header \u4E0D\u80FD\u4E3A\u7A7A`);
+    }
+    const values = (s?.values ?? []).map((v) => v?.trim()).filter(Boolean);
+    if (values.length < 3) {
+      errors.push(`${prefix}.values \u81F3\u5C11 3 \u4E2A\u975E\u7A7A\u503C\uFF08\u5F53\u524D ${values.length}\uFF09`);
+    }
+  }
+  if (ext.leadForm) {
+    const lfErrors = validateLeadFormPayload(ext.leadForm, "campaignExtensions.leadForm");
+    errors.push(...lfErrors);
+  }
+  if (callouts.length === 0 && snippets.length === 0 && !ext.leadForm) {
+    warnings.push(
+      "campaignExtensions \u5DF2\u58F0\u660E\u4F46 callouts / structuredSnippets / leadForm \u5747\u4E3A\u7A7A\uFF0C\u521B\u5EFA\u65F6\u5C06\u8DF3\u8FC7\u9644\u52A0\u8D44\u4EA7"
+    );
+  }
+  return { errors, warnings };
+}
+function hasExtensionsToAttach(ext) {
+  if (!ext) return false;
+  const hasCallouts = (ext.callouts ?? []).some((t) => t?.trim());
+  const hasSnippets = (ext.structuredSnippets ?? []).some(
+    (s) => s?.header?.trim() && (s.values ?? []).some((v) => v?.trim())
+  );
+  return hasCallouts || hasSnippets || Boolean(ext.leadForm);
+}
+async function postExtension(config, googleApiUrl, accountId, body, verbose) {
+  const url = `${googleApiUrl}/extensionmanagement/extension/${accountId}`;
+  try {
+    const data = await apiFetch2(
+      url,
+      config,
+      { method: "POST", body: JSON.stringify(body) },
+      verbose
+    );
+    return { ok: true, data };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function buildCalloutBody(accountId, campaignId, text) {
+  return {
+    activeuseridg: accountId,
+    campaignId,
+    level: "Campaign",
+    typeV2: "CALLOUT",
+    assetFieldType: "CALLOUT",
+    properties: { Text: text.trim() }
+  };
+}
+function buildSnippetBody(accountId, campaignId, header, values) {
+  return {
+    activeuseridg: accountId,
+    campaignId,
+    level: "Campaign",
+    typeV2: "STRUCTURED_SNIPPET",
+    assetFieldType: "STRUCTURED_SNIPPET",
+    structuredSnippetHeaderValue: {
+      key: header.trim(),
+      value: values.map((v) => v.trim()).filter(Boolean)
+    }
+  };
+}
+function buildLeadFormBodyForCampaign(accountId, campaignId, leadForm) {
+  return buildLeadFormExtensionBody({ account: accountId, campaignId, leadForm });
+}
+async function attachPmaxCampaignExtensions(opts) {
+  const ext = opts.extensions;
+  if (!hasExtensionsToAttach(ext)) {
+    return {
+      callouts: [],
+      structuredSnippets: [],
+      allOk: true,
+      skippedReason: "\u672A\u914D\u7F6E campaignExtensions \u6216\u5185\u5BB9\u4E3A\u7A7A"
+    };
+  }
+  const result = {
+    callouts: [],
+    structuredSnippets: [],
+    allOk: true
+  };
+  for (const raw of ext.callouts ?? []) {
+    const text = raw?.trim();
+    if (!text) continue;
+    if (opts.logProgress) console.log(`
+   \u6302\u8F7D\u5BA3\u4F20\u4FE1\u606F\uFF1A${text}`);
+    const posted = await postExtension(
+      opts.config,
+      opts.googleApiUrl,
+      opts.accountId,
+      buildCalloutBody(opts.accountId, opts.campaignId, text),
+      opts.verbose
+    );
+    if (posted.ok) {
+      result.callouts.push({
+        ok: true,
+        id: String(posted.data["id"] ?? ""),
+        label: text
+      });
+    } else {
+      result.allOk = false;
+      result.callouts.push({ ok: false, error: posted.error, label: text });
+    }
+  }
+  for (const s of ext.structuredSnippets ?? []) {
+    const header = s?.header?.trim();
+    const values = (s?.values ?? []).map((v) => v?.trim()).filter(Boolean);
+    if (!header || values.length < 3) continue;
+    const label = `${header}: ${values.join(", ")}`;
+    if (opts.logProgress) console.log(`
+   \u6302\u8F7D\u7ED3\u6784\u5316\u6458\u8981\uFF1A${label}`);
+    const posted = await postExtension(
+      opts.config,
+      opts.googleApiUrl,
+      opts.accountId,
+      buildSnippetBody(opts.accountId, opts.campaignId, header, values),
+      opts.verbose
+    );
+    if (posted.ok) {
+      result.structuredSnippets.push({
+        ok: true,
+        id: String(posted.data["id"] ?? ""),
+        label
+      });
+    } else {
+      result.allOk = false;
+      result.structuredSnippets.push({ ok: false, error: posted.error, label });
+    }
+  }
+  if (ext.leadForm) {
+    const headline = ext.leadForm.headline?.trim() || "Lead Form";
+    if (opts.logProgress) console.log(`
+   \u6302\u8F7D\u6F5C\u5728\u5BA2\u6237\u8868\u5355\uFF1A${headline}`);
+    const posted = await postExtension(
+      opts.config,
+      opts.googleApiUrl,
+      opts.accountId,
+      buildLeadFormBodyForCampaign(opts.accountId, opts.campaignId, ext.leadForm),
+      opts.verbose
+    );
+    if (posted.ok) {
+      result.leadForm = {
+        ok: true,
+        id: String(posted.data["id"] ?? ""),
+        label: headline
+      };
+    } else {
+      result.allOk = false;
+      result.leadForm = { ok: false, error: posted.error, label: headline };
+    }
+  }
+  return result;
+}
+function formatPmaxExtensionsAttachErrors(result) {
+  const msgs = [];
+  for (const c of result.callouts) {
+    if (!c.ok) msgs.push(`\u5BA3\u4F20\u4FE1\u606F\u300C${c.label}\u300D\u5931\u8D25\uFF1A${c.error}`);
+  }
+  for (const s of result.structuredSnippets) {
+    if (!s.ok) msgs.push(`\u7ED3\u6784\u5316\u6458\u8981\u300C${s.label}\u300D\u5931\u8D25\uFF1A${s.error}`);
+  }
+  if (result.leadForm && !result.leadForm.ok) {
+    msgs.push(`\u6F5C\u5728\u5BA2\u6237\u8868\u5355\u300C${result.leadForm.label}\u300D\u5931\u8D25\uFF1A${result.leadForm.error}`);
+  }
+  return msgs;
+}
+
 // src/commands/ad/pmax-create.ts
 function printVideoLinkRecoveryHint(accountId, assetGroupId, campaignId, youtubeTarget) {
   const cid = campaignId != null ? ` --campaign-id ${campaignId}` : "";
@@ -115384,8 +115859,11 @@ async function runAdPmaxCreate(opts) {
     opts.configFile,
     cfg
   );
-  const errors = [...deprecatedVideoKeys, ...cfgErrors, ...imgErrors, ...videoErrors];
-  const warnings = [...cfgWarnings, ...imgWarnings, ...videoWarnings];
+  const { errors: extErrors, warnings: extWarnings } = validatePmaxCampaignExtensions(
+    cfg.campaignExtensions
+  );
+  const errors = [...deprecatedVideoKeys, ...cfgErrors, ...imgErrors, ...videoErrors, ...extErrors];
+  const warnings = [...cfgWarnings, ...imgWarnings, ...videoWarnings, ...extWarnings];
   if (warnings.length > 0) {
     console.warn("\n\u26A0\uFE0F  PMax \u914D\u7F6E\u8B66\u544A\uFF08\u4E0D\u963B\u65AD\u63D0\u4EA4\uFF09\uFF1A");
     for (const w of warnings) console.warn(`   \u2022 ${w}`);
@@ -115457,6 +115935,21 @@ async function runAdPmaxCreate(opts) {
     verbose: opts.verbose,
     logProgress: !opts.jsonOut
   });
+  let extensionsResult;
+  if (campaignId != null && cfg.campaignExtensions) {
+    if (!opts.jsonOut) {
+      console.log("\n   \u6302\u8F7D Campaign \u9644\u52A0\u8D44\u4EA7\u2026");
+    }
+    extensionsResult = await attachPmaxCampaignExtensions({
+      config,
+      googleApiUrl,
+      accountId,
+      campaignId: String(campaignId),
+      extensions: cfg.campaignExtensions,
+      verbose: opts.verbose,
+      logProgress: !opts.jsonOut
+    });
+  }
   const payload = {
     ...data,
     videoLink: {
@@ -115466,7 +115959,8 @@ async function runAdPmaxCreate(opts) {
       uploadError: videoResult.uploadError,
       linkError: videoResult.linkError,
       skippedReason: videoResult.skippedReason
-    }
+    },
+    campaignExtensions: extensionsResult ?? { allOk: true, skippedReason: "\u672A\u914D\u7F6E campaignExtensions" }
   };
   if (videoResult.uploadError) {
     console.error(`
@@ -115490,6 +115984,20 @@ async function runAdPmaxCreate(opts) {
 \u26A0\uFE0F  \u6D3B\u52A8\u5DF2\u521B\u5EFA\uFF0C\u4F46\u89C6\u9891\u672A\u94FE\u63A5\uFF1A${videoResult.skippedReason}
 `);
   }
+  if (extensionsResult && !extensionsResult.allOk) {
+    console.error("\n\u26A0\uFE0F  \u6D3B\u52A8\u5DF2\u521B\u5EFA\uFF0C\u4F46\u90E8\u5206\u9644\u52A0\u8D44\u4EA7\u6302\u8F7D\u5931\u8D25\uFF1A");
+    for (const msg of formatPmaxExtensionsAttachErrors(extensionsResult)) {
+      console.error(`   \u2022 ${msg}`);
+    }
+    console.error(
+      `   \u53EF\u624B\u52A8\u8865\u6302\uFF1Asiluzan-tso ad extension callout|snippet|lead-form -a ${accountId} --campaign-id ${campaignId} \u2026
+`
+    );
+  } else if (extensionsResult?.allOk && extensionsResult.callouts.length + extensionsResult.structuredSnippets.length + (extensionsResult.leadForm ? 1 : 0) > 0) {
+    if (!opts.jsonOut) {
+      console.log("\n\u2705 Campaign \u9644\u52A0\u8D44\u4EA7\u5DF2\u6302\u8F7D");
+    }
+  }
   if (await emitCliJsonOrSnapshot(opts, {
     section: `ad-pmax-create-${accountId}`,
     commandLabel: "ad pmax-create",
@@ -115542,8 +116050,11 @@ async function runAdPmaxValidate(opts) {
     opts.configFile,
     cfg
   );
-  const errors = [...deprecatedVideoKeys, ...cfgErrors, ...imgErrors, ...videoErrors];
-  const warnings = [...cfgWarnings, ...imgWarnings, ...videoWarnings];
+  const { errors: extErrors, warnings: extWarnings } = validatePmaxCampaignExtensions(
+    cfg.campaignExtensions
+  );
+  const errors = [...deprecatedVideoKeys, ...cfgErrors, ...imgErrors, ...videoErrors, ...extErrors];
+  const warnings = [...cfgWarnings, ...imgWarnings, ...videoWarnings, ...extWarnings];
   const lengthViolations = cfgLengthViolations;
   if (opts.writeNormalized) {
     const toWrite = stripMetaKeysForExport(cfg);
@@ -116384,7 +116895,7 @@ async function runAdCampaignValidate(opts) {
 }
 
 // src/commands/ad/pmax-image-convert.ts
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5, readFileSync as readFileSync9, existsSync as existsSync4 } from "fs";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5, readFileSync as readFileSync10, existsSync as existsSync4 } from "fs";
 import { resolve as resolve10, dirname as dirname11, basename as basename7, extname } from "path";
 var SPECS = [
   { kind: "marketing", width: 1200, height: 628, fit: "cover", suffix: "_marketing" },
@@ -116475,7 +116986,7 @@ async function runAdPmaxImageConvert(opts) {
   if (opts.updateConfig) {
     const configPath = resolve10(opts.updateConfig);
     try {
-      const raw = JSON.parse(readFileSync9(configPath, "utf8"));
+      const raw = JSON.parse(readFileSync10(configPath, "utf8"));
       const imgPaths = raw["imagePaths"] ?? {};
       if (outputPaths.marketing) imgPaths["marketing"] = outputPaths.marketing;
       if (outputPaths.square) imgPaths["square"] = outputPaths.square;
@@ -117292,8 +117803,39 @@ function register20(program2) {
       });
     }
   );
-  const extensionCmd = adCmd.command("extension").description("\u9644\u52A0\u4FE1\u606F\u7BA1\u7406\uFF08\u9644\u52A0\u94FE\u63A5/\u7535\u8BDD/\u5BA3\u4F20\u4FE1\u606F/\u7ED3\u6784\u5316\u6458\u8981\uFF09");
-  extensionCmd.command("list").description("\u67E5\u8BE2\u9644\u52A0\u4FE1\u606F\u5217\u8868").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").option("--type <type>", "\u6309\u7C7B\u578B\u7B5B\u9009\uFF1ASITELINK | CALL | CALLOUT | STRUCTURED_SNIPPET").option("-t, --token <token>", "Auth Token").option(
+  const extensionCmd = adCmd.command("extension").description(
+    "\u9644\u52A0\u4FE1\u606F\u7BA1\u7406\uFF08\u9644\u52A0\u94FE\u63A5/\u7535\u8BDD/\u5BA3\u4F20\u4FE1\u606F/\u7ED3\u6784\u5316\u6458\u8981/\u6F5C\u5728\u5BA2\u6237\u8868\u5355\uFF1BPMax \u89C1 pmax-types\uFF09"
+  );
+  extensionCmd.command("pmax-types").description("\u67E5\u8BE2 PMax \u652F\u6301\u7684\u9644\u52A0\u8D44\u4EA7\u7C7B\u578B\u4E0E\u5C42\u7EA7\uFF08\u542B LEAD_FORM\uFF09").option("-t, --token <token>", "Auth Token").option(
+    "--json-out <path>",
+    "\u843D\u76D8\uFF08\u76EE\u5F55\u6216 *.json \u6587\u4EF6\u8DEF\u5F84\uFF09\u5E76\u66F4\u65B0 cli-manifest[-<\u67E5\u8BE2id>].json",
+    void 0
+  ).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+    async (opts) => {
+      await runAdExtensionPmaxTypes({
+        token: opts.token,
+        jsonOut: opts.jsonOut,
+        verbose: opts.verbose
+      });
+    }
+  );
+  extensionCmd.command("snippet-headers").description("\u67E5\u8BE2\u7ED3\u6784\u5316\u6458\u8981\u53EF\u9009\u6807\u5934\uFF08\u6309\u8BED\u8A00\u5206\u7EC4\uFF09").option("-t, --token <token>", "Auth Token").option(
+    "--json-out <path>",
+    "\u843D\u76D8\uFF08\u76EE\u5F55\u6216 *.json \u6587\u4EF6\u8DEF\u5F84\uFF09\u5E76\u66F4\u65B0 cli-manifest[-<\u67E5\u8BE2id>].json",
+    void 0
+  ).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+    async (opts) => {
+      await runAdExtensionSnippetHeaders({
+        token: opts.token,
+        jsonOut: opts.jsonOut,
+        verbose: opts.verbose
+      });
+    }
+  );
+  extensionCmd.command("list").description("\u67E5\u8BE2\u9644\u52A0\u4FE1\u606F\u5217\u8868").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").option(
+    "--type <type>",
+    "\u6309\u7C7B\u578B\u7B5B\u9009\uFF1ASITELINK | CALL | CALLOUT | STRUCTURED_SNIPPET | LEAD_FORM"
+  ).option("--campaign-id <id>", "\u6309\u5E7F\u544A\u7CFB\u5217 ID \u7B5B\u9009\uFF08PMax Campaign \u7EA7\u6269\u5C55\uFF09").option("-t, --token <token>", "Auth Token").option(
     "--json-out <path>",
     "\u843D\u76D8\uFF08\u76EE\u5F55\u6216 *.json \u6587\u4EF6\u8DEF\u5F84\uFF09\u5E76\u66F4\u65B0 cli-manifest[-<\u67E5\u8BE2id>].json\uFF1B\u76EE\u5F55\u6A21\u5F0F\u6587\u4EF6\u540D\u4E3A `<section>[-<\u67E5\u8BE2id>].json`\uFF1Bstdout \u4E00\u884C\u6458\u8981 JSON\uFF0C\u542B outlineFile\uFF08TS \u5F0F\u7C7B\u578B\u5728 `*.outline.txt`\uFF09",
     void 0
@@ -117303,6 +117845,41 @@ function register20(program2) {
         token: opts.token,
         account: opts.account,
         type: opts.type,
+        campaignId: opts.campaignId,
+        jsonOut: opts.jsonOut,
+        verbose: opts.verbose
+      });
+    }
+  );
+  extensionCmd.command("lead-form").description(
+    "\u4E3A PMax \u6D3B\u52A8\u6DFB\u52A0\u6F5C\u5728\u5BA2\u6237\u8868\u5355\uFF08LEAD_FORM\uFF1B\u4EC5 Campaign \u7EA7\uFF1B\u987B --config-file\uFF09\n  \u6A21\u677F\uFF1Aassets/pmax-lead-form-template.json"
+  ).requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--config-file <path>", "Lead Form JSON \u914D\u7F6E\uFF08\u89C1 pmax-lead-form-template.json\uFF09").option("--campaign-id <id>", "\u8986\u76D6\u914D\u7F6E\u6587\u4EF6\u4E2D\u7684 campaignId").option("-t, --token <token>", "Auth Token").option(
+    "--json-out <path>",
+    "\u843D\u76D8\uFF08\u76EE\u5F55\u6216 *.json \u6587\u4EF6\u8DEF\u5F84\uFF09\u5E76\u66F4\u65B0 cli-manifest[-<\u67E5\u8BE2id>].json",
+    void 0
+  ).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+    async (opts) => {
+      await runAdExtensionLeadFormCreate({
+        token: opts.token,
+        account: opts.account,
+        campaignId: opts.campaignId,
+        configFile: opts.configFile,
+        jsonOut: opts.jsonOut,
+        verbose: opts.verbose
+      });
+    }
+  );
+  extensionCmd.command("update").description("\u66F4\u65B0\u9644\u52A0\u4FE1\u606F\uFF08\u5F53\u524D\u652F\u6301 LEAD_FORM\uFF1BPUT \u5168\u91CF\u66FF\u6362 leadForm \u5BF9\u8C61\uFF09").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--id <extensionId>", "\u9644\u52A0\u4FE1\u606F ID\uFF08\u5148 ad extension list \u67E5\u8BE2\uFF09").requiredOption("--config-file <path>", "Lead Form JSON \u914D\u7F6E").option("-t, --token <token>", "Auth Token").option(
+    "--json-out <path>",
+    "\u843D\u76D8\uFF08\u76EE\u5F55\u6216 *.json \u6587\u4EF6\u8DEF\u5F84\uFF09\u5E76\u66F4\u65B0 cli-manifest[-<\u67E5\u8BE2id>].json",
+    void 0
+  ).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+    async (opts) => {
+      await runAdExtensionUpdate({
+        token: opts.token,
+        account: opts.account,
+        id: opts.id,
+        configFile: opts.configFile,
         jsonOut: opts.jsonOut,
         verbose: opts.verbose
       });

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.29-beta.1",
-  "publishedAt": 1781057100770
+  "version": "1.1.29-beta.3",
+  "publishedAt": 1781073977455
 }

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

@@ -8,7 +8,9 @@
       "budget / targetCpa_BidingAmount 填主币种「元」，CLI 提交前 ×100 转 API 整型",
       "三张图：只填 imagePaths（pmax-create 会自动上传为 assetId）；勿把 Base64 写入 JSON",
       "本地视频：填 videoPath（或别名 video）；创建后 CLI 自动 PyAPI 上传并链接，与 --json-out 无关",
-      "提交前：ad pmax-validate → 用户确认 → ad pmax-create"
+      "提交前：ad pmax-validate → 用户确认 → ad pmax-create",
+      "campaignExtensions 可选：创建成功后 CLI 自动挂 callout/snippet/leadForm（非 pmax POST body）",
+      "不需要附加资产时删除整个 campaignExtensions 块"
     ]
   },
 
@@ -38,5 +40,27 @@
   "targetedLanguages": [{ "id": 1000 }],
   "biddingStrategyTypeV2": "MAXIMIZE_CONVERSIONS",
   "targetCpa_BidingAmount": 0,
-  "targetRoas": 0
+  "targetRoas": 0,
+
+  "campaignExtensions": {
+    "callouts": ["Free shipping", "24/7 support"],
+    "structuredSnippets": [
+      {
+        "header": "Services",
+        "values": ["Design", "Install", "Support"]
+      }
+    ],
+    "leadForm": {
+      "businessName": "Example Brand Co",
+      "headline": "Get a free quote",
+      "description": "Tell us about your project.",
+      "privacyPolicyUrl": "https://www.example.com/privacy",
+      "finalUrl": "https://www.example.com",
+      "fields": [
+        { "inputType": "FULL_NAME" },
+        { "inputType": "EMAIL" },
+        { "inputType": "PHONE_NUMBER" }
+      ]
+    }
+  }
 }

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

@@ -17,6 +17,7 @@
 | 金额 | JSON 填**主币种「元」**；CLI 提交前 `budget`、`targetCpa_BidingAmount` ×100 |
 | 图片 | **只填 `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`） |
 | 列表复核 | `ad campaigns -a <id> --json-out ./snap`，`channelTypeV2` 应为 `PERFORMANCE_MAX` |
 
@@ -67,9 +68,24 @@ siluzan-tso ad campaigns -a <accountId> --json-out ./snap
 | `videoDescription` | string | | PyAPI 上传描述（可选） |
 | `youtubeUrlOrId` | string | | 已有 YouTube URL 或 11 位 ID；`pmax-create` 后自动链接 |
 | `youtubeAssetName` | string | | 链接 YouTube 时的资产显示名 |
+| `campaignExtensions` | object | | 创建成功后自动挂载的 Campaign 级扩展（见下表） |
 
 \* 三张图各须有一种来源（路径或 Base64）。
 
+### `campaignExtensions`（可选，CLI 编排）
+
+**不**随 `POST .../campaign/pmax` 提交；活动创建成功后 CLI 自动调用 `extensionmanagement`。
+
+| 子字段 | 类型 | 说明 |
+|--------|------|------|
+| `callouts` | string[] | 宣传信息（CALLOUT），每条 ≤25 字符，各创建 1 个扩展 |
+| `structuredSnippets` | object[] | `{ header, values }`；`values` 至少 3 项 |
+| `leadForm` | object | 潜在客户表单；字段同 `pmax-lead-form-template.json` 的 `leadForm` |
+
+标头可选值：`ad extension snippet-headers`。WhatsApp 尚未支持。
+
+若挂载失败，活动仍已创建；`--json-out` 的 `campaignExtensions` 段含各条 `ok` / `error`，可手动 `ad extension *` 补挂。
+
 ### 出价策略（PMax 支持子集）
 
 | 值 | 说明 |

package/dist/skill/assets/pmax-lead-form-template.json

@@ -0,0 +1,35 @@
+{
+  "_meta": {
+    "schema": "pmax-lead-form/v1",
+    "doc": "pmax-lead-form-template.md",
+    "note": "以 _ 开头的键仅作说明，CLI 提交前会剥离",
+    "agentPitfalls": [
+      "LEAD_FORM 仅支持 Campaign 级，须挂到已存在的 PMax 活动 campaignId",
+      "勿在 pmax-create 流程内创建；先 pmax-create 再 ad extension lead-form",
+      "每个 PMax 活动通常仅允许 1 个 Lead Form；创建前用 ad extension list --type LEAD_FORM --campaign-id 检查",
+      "账户须在 Google Ads UI 接受 Lead Form ToS",
+      "WhatsApp 私信扩展后端尚未开放"
+    ]
+  },
+  "account": "REPLACE_mediaCustomerId",
+  "campaignId": "REPLACE_pmaxCampaignId",
+  "leadForm": {
+    "businessName": "Example Brand Co",
+    "headline": "Get a free quote",
+    "description": "Tell us about your project and we will contact you.",
+    "privacyPolicyUrl": "https://www.example.com/privacy",
+    "finalUrl": "https://www.example.com",
+    "callToActionType": "LEARN_MORE",
+    "callToActionDescription": "Contact us",
+    "fields": [
+      { "inputType": "FULL_NAME" },
+      { "inputType": "EMAIL" },
+      { "inputType": "PHONE_NUMBER" }
+    ],
+    "webhook": {
+      "advertiserWebhookUrl": "https://your-crm.example.com/webhook",
+      "googleSecret": "your-google-secret",
+      "payloadSchemaVersion": 3
+    }
+  }
+}

package/dist/skill/assets/pmax-lead-form-template.md

@@ -0,0 +1,63 @@
+# `ad extension lead-form` JSON 配置说明
+
+为**已创建的 PMax 活动**挂载潜在客户表单（`LEAD_FORM`）。不走 `pmax-create` 主流程。
+
+模板 JSON：同目录 [`pmax-lead-form-template.json`](pmax-lead-form-template.json)。
+
+---
+
+## 推荐命令顺序
+
+```bash
+# 1. 确认 PMax 活动 ID
+siluzan-tso ad campaigns -a <accountId> --json-out ./snap
+
+# 2. 查看 PMax 支持的扩展类型
+siluzan-tso ad extension pmax-types --json-out ./snap
+
+# 3. 检查活动上是否已有 Lead Form
+siluzan-tso ad extension list -a <accountId> --type LEAD_FORM --campaign-id <campaignId> --json-out ./snap
+
+# 4. 创建
+siluzan-tso ad extension lead-form -a <accountId> --config-file ./lead-form.json --json-out ./snap
+
+# 5. 更新（须带完整 leadForm 对象）
+siluzan-tso ad extension update -a <accountId> --id <extensionId> --config-file ./lead-form.json
+```
+
+---
+
+## 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `account` | string | ✅ | Google 媒体客户 ID |
+| `campaignId` | string | ✅ | PMax 活动 ID（`channelTypeV2=PERFORMANCE_MAX`） |
+| `leadForm.businessName` | string | ✅ | 商家名称 |
+| `leadForm.headline` | string | ✅ | 表单标题 |
+| `leadForm.description` | string | ✅ | 表单描述 |
+| `leadForm.privacyPolicyUrl` | string | ✅ | 隐私政策 URL |
+| `leadForm.finalUrl` | string | ✅ | 落地页 URL |
+| `leadForm.callToActionType` | string | | 默认 `LEARN_MORE` |
+| `leadForm.callToActionDescription` | string | | 默认 `Contact us` |
+| `leadForm.fields` | object[] | ✅ | 至少 1 项；`inputType` 如 `FULL_NAME`、`EMAIL`、`PHONE_NUMBER` |
+| `leadForm.webhook` | object | | 写入 Google 的 Webhook（非平台接收端） |
+
+---
+
+## PMax 附加资产对照
+
+| 中文 | 类型 | CLI 命令 |
+|------|------|----------|
+| 宣传信息 | `CALLOUT` | `ad extension callout` |
+| 结构化摘要 | `STRUCTURED_SNIPPET` | `ad extension snippet` |
+| 潜在客户表单 | `LEAD_FORM` | `ad extension lead-form` |
+| 附加链接 | `SITELINK` | `ad extension sitelink` |
+| 附加电话 | `CALL` | `ad extension call` |
+| 私信 WhatsApp | — | **后端尚未开放** |
+
+**层级**：PMax 仅 `Account` / `Campaign`；`Ad Group` 会 **400**。
+
+**副作用**：创建 Lead Form 后，后端会自动尝试将 `SUBMIT_LEAD_FORM` + `GOOGLE_HOSTED` 转化目标设为 `biddable=true`。
+
+详见 `references/google-ads/pmax-api.md` § 附加资产。

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

@@ -20,26 +20,18 @@
 | **上下文被压缩 / 记不清字段或命令** | 重读 `SKILL.md` 路由表 + 当次任务 references |
 | **CLI 返回 400 / 字段对不上** | 回到对应 reference 核对参数名与口径，勿猜 |
 
-### 禁止
+### 应当遵循（及原因）
+
+| 应当怎么做 | 原因 |
+| -------- | ---- |
+| **每个新任务先 Read 当次必读 references，再执行 CLI** — 即使用户刚查过余额、对话里刚读过 `accounts/accounts.md` 或 `google-ads/google-ads.md`，换话题（建系列、预警、报告等）仍按 `SKILL.md` 路由表 **重新 Read** 对应文档后再 `siluzan-tso …` | 不同任务的命令、参数口径、Playbook 编号各不相同；对话会被压缩，「读过」≠ 当前上下文仍含正确字段名与 flags |
+| **所有 ID、金额、命令 flags 以当次 Read 文档 + 当次 CLI 输出为准** — 计划与执行前对照 reference 确认 `-a`/`-m`/日期等参数；数值只来自本次 stdout 或脚本读盘结果 | Skill 文档与 CLI 会迭代，对话记忆里的示例 ID、占位金额易串户、串币种或触发 400 |
+| **数据转换严格按 outline → 脚本读 JSON 顺序** — Read `references/core/tips.md` § 处理顺序；解析 stdout 得 `outlineFile` → Read outline → 编写并执行脚本读 `writtenFiles` | outline 是字段类型的唯一轻量索引；跳步会导致列名猜错（如 `keywordText` vs `keyword`）或把 MB 级 JSON 误读进对话 |
+| **大 JSON 只经脚本读盘，对话里只 Read 小文件** — Read 仅 `references/`、`*.outline.txt`、stdout 一行摘要；业务 `*.json`（`campaigns-*.json`、`list-accounts-*.json` 等）由 Node/Python `readFileSync` / `JSON.parse` 处理 | `--json-out` 落盘常为 MB 级，Read 整文件会撑爆上下文且无法可靠汇总；脚本可精确取所需字段并与落盘 JSON 复核 |
+| **报告 / Excel 走本 Skill 拉数 + outline + 脚本全流程** — 按 Playbook 与 `report-templates/*.md` 拉数、落盘、脚本转换后交付；不另加载宿主 xlsx / Excel 第三方 Skill 代劳 | 第三方 Skill 不知 TSO 字段口径、账户核验与 `deliverable-preflight`；易跳过 `-k` 核验或编造未落盘数据 |
+| **用户给出的 `mediaCustomerId` 必须 `-k` 核验，全链路同一 ID** — `list-accounts -m <媒体> -k <用户ID>`；无结果则告知用户并停止；拉数、脚本、报告文件名均用该 ID（以 stdout `accountId` 为准） | 列表第一页可能不含目标户；自行换 ID 会导致报告错户，属严重交付事故 |
+| 交付前自检产物，是否有为空的部分，是否有数据明显异常的部分，是否有字段使用错误的部分 | 如果不自检的话，出来的产物很可能无法使用 |
 
-- **禁止**「上次已经读过 `accounts/accounts.md` / `google-ads/google-ads.md`，本任务直接 `siluzan-tso …`」
-- **禁止**用对话记忆中的示例 ID、金额、命令 flags 代替当次 Read 文档
-- **禁止**跳过 `references/core/tips.md` 里的 outline→脚本读 JSON 顺序
-- **禁止**用 Read / `cat` / `type` / `head` 打开 `--json-out` 落盘的**业务数据** `*.json`（`campaigns-*.json`、`list-accounts-*.json` 等）；只允许 Read 体积小的 `*.outline.txt` 与 `references/` 文档
-- **禁止**在 siluzan-tso 报告任务中加载宿主「xlsx / Excel」第三方 Skill 代替本 Skill 的拉数 + outline + 脚本流程
-- **禁止**用户给出 `mediaCustomerId` 后不用 `-k` 核验、翻页 `grep` 列表并**换成另一个账户 ID** 继续拉数/写报告
-
-### 报告类常见违规（对照修复）
-
-| 违规现象 | 正确做法 |
-| -------- | -------- |
-| 未读 `*.outline.txt` 就写 Excel，列名用 `keywordText` / `query` / `geoName` | 先 Read 各 section 的 outline；字段以最后一行 TS 类型为准（如 `keyword`、`searchTermText`、`countryOrRegion`） |
-| `cat keywords-*.json \| python -m json.tool \| head` 探结构 | 只 Read `keywords-*.outline.txt`；业务 JSON 仅在脚本内读取 |
-| `list-accounts` 第一页未见 ID，改用列表里「另一个」账户 | `list-accounts -m Google -k <用户ID>`；无结果则告知用户，停止 |
-| 用户要 `2702960720`，拉数/脚本却用 `9322098303` | 全流程同一 `mediaCustomerId`；文件名以 stdout `accountId` 为准 |
-| 交付 xlsx 前未对照 `deliverable-preflight.md` | 交付前自检表 A/B/C；xlsx 附脚本 stdout 行数/汇总摘要 |
-
----
 
 ## 执行流程
 

package/dist/skill/references/core/cli-enums.md

@@ -68,6 +68,8 @@
 | 命令 | 选项 | 合法值 |
 | ---- | ---- | ------ |
 | ad extension sitelink, callout, snippet, … | --level | Account \| Campaign \| AdGroup |
+| ad extension list | --type | SITELINK \| CALL \| CALLOUT \| STRUCTURED_SNIPPET \| LEAD_FORM |
+| ad extension lead-form / update | --config-file | JSON（见 `assets/pmax-lead-form-template.json`） |
 
 
 ### 搜索系列 `BiddingStrategyTypeV2`

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

@@ -64,6 +64,7 @@
 | 改资产 | `ad pmax-assets-update --config-file …` |
 | YouTube 追加 | `ad pmax-youtube-link`（单条 `--youtube` / `--video-path`）；批量见 `ad pmax-assets-update` |
 | 信号 | `ad pmax-signals-get` / `ad pmax-signals-set`；受众下拉 `ad pmax-audiences` |
+| 附加资产 | `ad extension pmax-types`；`callout` / `snippet` / `lead-form`（见 `pmax-api.md` § 附加资产） |
 | 图片库 | `ad pmax-image-upload` |
 | 报表 | `ad pmax-report-asset-groups` / `ad pmax-report-geo` |
 | 删活动 | `ad campaign-delete -a <id> --id <campaignId>`（与 Search 共用；勿用 `ad campaign-edit`） |
@@ -512,11 +513,19 @@ siluzan-tso ad keyword-negative-edit \
 
 ## ad extension — 附加信息管理
 
-修改方式为**先删后建**（无 PUT 接口）。所有 `extension <type>` 子命令均支持 `--json-out`，输出网关返回的扩展对象（含 `id`），批量脚本可据此回填。
+Callout / Snippet / Sitelink / Call 等类型修改可**先删后建**；**Lead Form** 支持 `ad extension update`（PUT 全量替换 `leadForm`）。所有 `extension <type>` 子命令均支持 `--json-out`，输出网关返回的扩展对象（含 `id`），批量脚本可据此回填。
 
 ```bash
+# PMax 支持的类型与层级（含 LEAD_FORM）
+siluzan-tso ad extension pmax-types [--json-out ./snap]
+
+# 结构化摘要标头（按语言）
+siluzan-tso ad extension snippet-headers [--json-out ./snap]
+
 # 查询
-siluzan-tso ad extension list -a <accountId> [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET] [--json-out ./snap]
+siluzan-tso ad extension list -a <accountId> \
+  [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET|LEAD_FORM] \
+  [--campaign-id <campaignId>] [--json-out ./snap]
 
 # 附加链接
 siluzan-tso ad extension sitelink -a <accountId> --text "文字" --url "https://..." \
@@ -532,11 +541,21 @@ siluzan-tso ad extension callout -a <accountId> --text "免费送货上门" [--l
 # 附加结构化摘要
 siluzan-tso ad extension snippet -a <accountId> --header "Brands" --values "A,B,C" [--level Account] [--json-out ./snap]
 
+# PMax 潜在客户表单（仅 Campaign 级；模板 assets/pmax-lead-form-template.json）
+siluzan-tso ad extension lead-form -a <accountId> --config-file ./lead-form.json [--json-out ./snap]
+
+# 更新 Lead Form
+siluzan-tso ad extension update -a <accountId> --id <extensionId> --config-file ./lead-form.json
+
 # 删除
 siluzan-tso ad extension delete -a <accountId> --id <extensionId>
 ```
 
-`--header` 常用值：`Brands`/`Services`/`Amenities`/`Types`/`Styles`/`Courses`/`Models` 等。
+**PMax 约束**：仅 `Account` / `Campaign` 层级；`Ad Group` 会 400。`LEAD_FORM` 仅挂 Campaign。WhatsApp 私信扩展后端尚未开放。
+
+`--header` 常用值：`Brands`/`Services`/`Amenities`/`Types`/`Styles`/`Courses`/`Models` 等（完整列表：`ad extension snippet-headers`）。
+
+**网关**：`ExtensionManagementController.cs` — `pmaxSupportedTypeList`、`structuredSnippetHeaders`、`extension/{accountId}` POST/PUT/DELETE。
 
 ---
 

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

@@ -29,8 +29,62 @@
 | `ad pmax-image-upload` | 单张图片上传 |
 | `ad pmax-report-asset-groups` / `ad pmax-report-geo` | 报表 |
 | `ad campaigns` | 列表（筛 `PERFORMANCE_MAX`） |
+| `ad extension pmax-types` | PMax 支持的附加资产类型与层级 |
+| `ad extension callout` / `snippet` / `lead-form` | 宣传信息 / 结构化摘要 / 潜在客户表单 |
+| `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`。
+模板：`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`。
+
+### 附加资产（Callout / Snippet / Lead Form）
+
+网关 `POST .../campaign/pmax` **不**接受扩展字段；CLI 通过 **`campaignExtensions`** 在 `pmax-create` 成功后**自动编排** `extensionmanagement`（与手动 `ad extension *` 等价）。
+
+**方式 A（推荐，一条命令）**：在 `pmax-create` JSON 中填 `campaignExtensions`：
+
+```json
+{
+  "campaignExtensions": {
+    "callouts": ["Free shipping"],
+    "structuredSnippets": [{ "header": "Services", "values": ["A", "B", "C"] }],
+    "leadForm": { "businessName": "...", "headline": "...", "description": "...", "privacyPolicyUrl": "...", "finalUrl": "...", "fields": [{ "inputType": "EMAIL" }] }
+  }
+}
+```
+
+`pmax-validate` 会一并校验；`pmax-create` 成功后在同一次调用内挂载（`--json-out` 含 `campaignExtensions` 结果）。
+
+**方式 B（分步）**：活动创建后手动走 `extensionmanagement`（PMax 限制 Account/Campaign 层级）。
+
+| 中文 | 类型 | 命令 |
+|------|------|------|
+| 宣传信息 | `CALLOUT` | `ad extension callout -a <id> --text "..." --level Campaign --campaign-id <cid>` |
+| 结构化摘要 | `STRUCTURED_SNIPPET` | `ad extension snippet -a <id> --header Brands --values "A,B,C" --level Campaign --campaign-id <cid>` |
+| 潜在客户表单 | `LEAD_FORM` | `ad extension lead-form -a <id> --config-file ./lead-form.json` |
+| 附加链接 / 电话 | `SITELINK` / `CALL` | `ad extension sitelink` / `call`（同上 `--level Campaign`） |
+| 私信 WhatsApp | — | **后端尚未开放**（后续阶段） |
+
+```bash
+# 查 PMax 支持类型
+siluzan-tso ad extension pmax-types --json-out ./snap
+
+# 结构化摘要标头下拉
+siluzan-tso ad extension snippet-headers --json-out ./snap
+
+# Lead Form（模板见 assets/pmax-lead-form-template.md）
+siluzan-tso ad extension lead-form -a <accountId> --config-file ./lead-form.json --json-out ./snap
+
+# 复核 / 更新 / 删除
+siluzan-tso ad extension list -a <accountId> --type LEAD_FORM --campaign-id <cid> --json-out ./snap
+siluzan-tso ad extension update -a <accountId> --id <extId> --config-file ./lead-form.json
+siluzan-tso ad extension delete -a <accountId> --id <extId>
+```
+
+**约束**：
+- PMax **不支持** `level: Ad Group`（会 400）
+- `LEAD_FORM` **仅** `Campaign` 级；每活动通常 1 个
+- 创建 Lead Form 后后端自动尝试开启 `SUBMIT_LEAD_FORM` + `GOOGLE_HOSTED` 转化目标
+
+**网关**：`GET /extensionmanagement/pmaxSupportedTypeList`；`POST|PUT|DELETE /extensionmanagement/extension/{accountId}[/{id}]`（Sammamish `ExtensionManagementController.cs`）。
 
 ### 图片（推荐流程）
 

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

package/dist/skill/scripts/install.sh

@@ -9,7 +9,7 @@ set -euo pipefail
 # -- Package info (injected at build time) ------------------------------------
 readonly PKG_NAME="siluzan-tso-cli"
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-readonly PKG_VERSION="1.1.29-beta.1"
+readonly PKG_VERSION="1.1.29-beta.3"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
 readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"

package/package.json

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