siluzan-tso-cli 1.0.0-beta.52 → 1.0.0-beta.53

package/README.md

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

package/dist/index.js

@@ -4557,6 +4557,7 @@ async function runInvoiceInfoDelete(opts) {
 
 // src/commands/ad.ts
 import { randomUUID } from "crypto";
+import { readFileSync as readFileSync6 } from "fs";
 async function findItemInList(listUrl, config, id, verbose) {
   const res = await apiFetch2(listUrl, config, {}, verbose);
   const item = (res.data ?? []).find((x) => x["id"] === id);
@@ -5200,8 +5201,59 @@ function buildAdsForBatchJob(opts) {
   return [ad];
 }
 async function runAdCampaignCreate(opts) {
-  const config = loadConfig(opts.token);
-  console.log(opts);
+  if (opts.configFile) {
+    let fileConfig;
+    try {
+      fileConfig = JSON.parse(readFileSync6(opts.configFile, "utf8"));
+    } catch (err) {
+      console.error(`
+\u274C \u8BFB\u53D6\u914D\u7F6E\u6587\u4EF6\u5931\u8D25\uFF08${opts.configFile}\uFF09\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+    const fromFile = {
+      account: fileConfig.account,
+      customerName: fileConfig.customerName,
+      name: fileConfig.name,
+      budget: fileConfig.budget,
+      // CampaignCreateConfig.bidding → AdCampaignCreateOptions.biddingStrategy
+      biddingStrategy: fileConfig.bidding,
+      bidCeiling: fileConfig.bidCeiling,
+      targetCpa: fileConfig.targetCpa,
+      targetRoas: fileConfig.targetRoas,
+      locationIds: fileConfig.locationIds,
+      languageIds: fileConfig.languageIds,
+      startDate: fileConfig.startDate,
+      endDate: fileConfig.endDate,
+      url: fileConfig.url,
+      status: fileConfig.status,
+      adgroupName: fileConfig.adgroupName,
+      maxCpc: fileConfig.maxCpc,
+      matchType: fileConfig.matchType,
+      keywords: fileConfig.keywords,
+      headlines: fileConfig.headlines,
+      descriptions: fileConfig.descriptions,
+      finalUrl: fileConfig.finalUrl,
+      path1: fileConfig.path1,
+      path2: fileConfig.path2,
+      productWords: fileConfig.productWords,
+      negativeKeywords: fileConfig.negativeKeywords,
+      // CampaignCreateConfig.extensions/extraAdGroups → extensionsJson/extraAdGroupsJson
+      extensionsJson: fileConfig.extensions,
+      extraAdGroupsJson: fileConfig.extraAdGroups,
+      draft: fileConfig.draft,
+      targetSearchNetwork: fileConfig.targetSearchNetwork,
+      targetContentNetwork: fileConfig.targetContentNetwork
+    };
+    opts = {
+      ...fromFile,
+      ...Object.fromEntries(
+        Object.entries(opts).filter(([, v]) => v !== void 0 && v !== "" && !(Array.isArray(v) && v.length === 0))
+      ),
+      configFile: void 0
+    };
+  }
+  const config = await ensureDataPermission(loadConfig(opts.token));
   if (!config.apiBaseUrl) {
     console.error("\n\u274C \u672A\u914D\u7F6E apiBaseUrl\uFF0C\u8BF7\u6267\u884C\uFF1Asiluzan-tso config set --api-base <URL>\n");
     process.exit(1);
@@ -5209,9 +5261,12 @@ async function runAdCampaignCreate(opts) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const defaultEnd = "2037-12-30";
   const budgetBatch = Math.round(opts.budget * 100);
-  const maxCpcBatch = String(Math.round(opts.maxCpc * 100));
+  const maxCpcBatch = Math.round(opts.maxCpc * 100);
   const campaign = {
+    // 预算共享（Web 默认 false = 独立预算）
+    BudgetShared: false,
     Budget: budgetBatch,
+    BudgetId: 0,
     Name: opts.name,
     StatusV2: opts.status ?? "Enabled",
     ChannelTypeV2: "SEARCH",
@@ -5222,22 +5277,51 @@ async function runAdCampaignCreate(opts) {
     ...opts.targetRoas ? { TargetRoas: opts.targetRoas } : {},
     TargetGoogleSearch: true,
     TargetSearchNetwork: opts.targetSearchNetwork ?? true,
+    // 地理位置定向类型（0 = DONT_CARE，与 Web 一致）
+    NegativeGeoTargetType: 0,
+    PositiveGeoTargetType: 0,
+    // DSA 动态搜索广告配置（搜索广告系列保持默认空值即可）
+    DSADomainName: "",
+    DSALanguageCode: "en",
     TargetContentNetwork: opts.targetContentNetwork ?? false,
     StartTime: opts.startDate ?? today,
     EndTime: opts.endDate ?? defaultEnd,
-    // 地理位置定向
+    // 否定关键词（传入则写入第一条记录；不传则空数组，后续可用 ad negative-keyword-create 追加）
+    NegativeKeywordsForBatchJob: opts.negativeKeywords && opts.negativeKeywords.length > 0 ? [{
+      KeywordText: opts.negativeKeywords,
+      MatchTypeV2: "BROAD",
+      FinalURL: ""
+    }] : [],
+    // 广告附加功能（CALL / STRUCTURED_SNIPPET / SITELINK 等，不传则空数组）
+    ExtensionsForBatchJob: opts.extensionsJson ?? [],
+    // 第一个广告组（关键词与广告：不传则为空，后续用 ad keyword-create / ad ad-create 补充）
+    AdGroupsForBatchJob: [
+      {
+        Name: opts.adgroupName,
+        StatusV2: "Enabled",
+        TypeV2: "SEARCH_STANDARD",
+        RotationModeV2: "Unspecified",
+        MaxCPCAmount: maxCpcBatch,
+        AdsForBatchJob: buildAdsForBatchJob(opts),
+        KeywordsForBatchJob: buildKeywordsForBatchJob(opts)
+      },
+      // 可通过 --extra-adgroups-json 追加更多广告组
+      ...opts.extraAdGroupsJson ?? []
+    ],
+    // 地理位置定向（id 保持字符串类型，与 Web API 一致）
     targetedLocations: opts.locationIds.map((id) => ({
+      id: String(id),
       bidModifier: 0,
-      bidModifierSpecified: false,
-      id: Number(id)
+      bidModifierSpecified: false
     })),
     excludedLocations: [],
     // 语言（默认英语 1000）
     targetedLanguages: (opts.languageIds ?? ["1000"]).map((id) => ({ id: Number(id) })),
-    // 设备（默认 PC + 移动）
+    // 设备：30000=全部，30001=移动，30002=平板（与 Web 默认三端投放一致）
     targetedPlatforms: [
-      { id: 3e4, bidModifier: 0 },
-      { id: 30001, bidModifier: 0 }
+      { id: 30001, bidModifier: 0 },
+      { id: 30002, bidModifier: 0 },
+      { id: 3e4, bidModifier: 0 }
     ],
     // 全周全天投放
     adSchedules: [2, 3, 4, 5, 6, 7, 8].map((day) => ({
@@ -5246,19 +5330,7 @@ async function runAdCampaignCreate(opts) {
       StartMinuteV2: 2,
       endHour: 24,
       EndMinuteV2: 2
-    })),
-    NegativeKeywordsForBatchJob: [],
-    ExtensionsForBatchJob: [],
-    // 第一个广告组（关键词与广告：不传则为空，后续用 ad keyword-create / ad ad-create 补充）
-    AdGroupsForBatchJob: [{
-      Name: opts.adgroupName,
-      StatusV2: "Enabled",
-      TypeV2: "SEARCH_STANDARD",
-      RotationModeV2: "Unspecified",
-      MaxCPCAmount: maxCpcBatch,
-      AdsForBatchJob: buildAdsForBatchJob(opts),
-      KeywordsForBatchJob: buildKeywordsForBatchJob(opts)
-    }]
+    }))
   };
   const adGroupsForBatchJob = campaign.AdGroupsForBatchJob;
   const keywordRecommendations = (adGroupsForBatchJob ?? []).filter((g) => typeof g.Name === "string" && g.Name.trim().length > 0).map((g) => ({
@@ -5270,9 +5342,10 @@ async function runAdCampaignCreate(opts) {
     customerName: opts.customerName,
     campaignName: opts.name,
     url: opts.url ?? "",
-    // 前端页面会传入覆盖范围与产品词，这里暂时缺少同等丰富的来源，先留空数组以通过后端字段校验
+    // locations 为地理位置名称的展示字符串列表（前端只读，后端不做校验，可留空）
     locations: [],
-    productWords: [],
+    // productWords 为产品核心词，用于 AI 生成关键词推荐，可通过 --product-words 传入
+    productWords: opts.productWords ?? [],
     // Web 端异步创建在走「立即发布」时会使用非空的 GoogleDataRecordId（UUID）且 DraftStatus 为 Published；
     // 这里保持一致，使用随机 UUID 作为唯一标识。是否直接发布由 draft 开关控制：
     // - draft=true  → DraftStatus = Draft（仅创建草稿，需后续 ad batch publish 发布）
@@ -9901,20 +9974,20 @@ adCmd.command("keyword-negative-delete").description("\u5220\u9664\u5426\u5B9A\u
 });
 adCmd.command("campaign-create").description(
   '\u65B0\u5EFA\u641C\u7D22\u5E7F\u544A\u7CFB\u5217\uFF08\u542B\u7B2C\u4E00\u4E2A\u5E7F\u544A\u7EC4\uFF0C\u5F02\u6B65\u63D0\u4EA4\uFF1B\u9ED8\u8BA4\u7ACB\u5373\u53D1\u5E03\uFF0C\u53EF\u52A0 --draft \u4EC5\u4FDD\u5B58\u4E3A\u8349\u7A3F\uFF09\n\n  \u524D\u7F6E\u6B65\u9AA4\uFF1A\n    1. siluzan-tso ad geo search -a <accountId> -q "United States"  # \u83B7\u53D6 locationId\n    2. \u586B\u5165 --location-ids\uFF0C\u521B\u5EFA\u5B8C\u6BD5\u540E\u7528 ad batch get --id <taskId> \u8DDF\u8FDB\u72B6\u6001'
-).requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--customer-name <name>", "\u8D26\u6237\u540D\u79F0\uFF08\u6765\u81EA list-accounts --json \u7684 mediaAccountName \u5B57\u6BB5\uFF09").requiredOption("--name <name>", "\u5E7F\u544A\u7CFB\u5217\u540D\u79F0").requiredOption(
+).option("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId\uFF08\u4F7F\u7528 --config-file \u65F6\u53EF\u7701\u7565\uFF0C\u4ECE\u6587\u4EF6\u8BFB\u53D6\uFF09").option("--customer-name <name>", "\u8D26\u6237\u540D\u79F0\uFF08\u6765\u81EA list-accounts --json \u7684 mediaAccountName \u5B57\u6BB5\uFF09").option("--name <name>", "\u5E7F\u544A\u7CFB\u5217\u540D\u79F0").option(
   "--budget <amount>",
-  "\u65E5\u9884\u7B97\uFF1A\u8D26\u6237\u4E3B\u5E01\u79CD\u91D1\u989D\uFF08\u5982 100 = \u6BCF\u5929 100 USD/CNY\uFF1B\u4E0E Web / ad smart create \u4E00\u81F4\uFF0C\u5185\u90E8 \xD7100 \u5199\u5165\u63A5\u53E3\uFF09",
+  "\u65E5\u9884\u7B97\uFF1A\u8D26\u6237\u4E3B\u5E01\u79CD\u91D1\u989D\uFF08\u5982 100 = \u6BCF\u5929 100 USD/CNY\uFF1B\u5185\u90E8 \xD7100 \u5199\u5165\u63A5\u53E3\uFF09",
   parseFloat
-).requiredOption(
+).option(
   "--bidding <strategy>",
   "\u51FA\u4EF7\u7B56\u7565\uFF1ATARGET_SPEND | MANUAL_CPC | TARGET_CPA | TARGET_ROAS"
-).requiredOption(
+).option(
   "--location-ids <ids>",
   "\u6295\u653E\u5730\u7406\u4F4D\u7F6E ID\uFF0C\u9017\u53F7\u5206\u9694\uFF08\u7528 ad geo search \u83B7\u53D6\uFF0C\u5982 2840=\u7F8E\u56FD\uFF09",
   (v) => v.split(",").map((s) => s.trim())
-).requiredOption("--adgroup-name <name>", "\u7B2C\u4E00\u4E2A\u5E7F\u544A\u7EC4\u540D\u79F0").requiredOption(
+).option("--adgroup-name <name>", "\u7B2C\u4E00\u4E2A\u5E7F\u544A\u7EC4\u540D\u79F0").option(
   "--max-cpc <amount>",
-  "\u7B2C\u4E00\u4E2A\u5E7F\u544A\u7EC4\u6700\u9AD8 CPC\uFF1A\u4E3B\u5E01\u79CD\u91D1\u989D\uFF08\u5982 1.5 = \u6BCF\u6B21\u70B9\u51FB 1.50\uFF1B\u4E0E Web / ad smart create \u4E00\u81F4\uFF0C\u5185\u90E8 \xD7100 \u5199\u5165 MaxCPCAmount\uFF09",
+  "\u7B2C\u4E00\u4E2A\u5E7F\u544A\u7EC4\u6700\u9AD8 CPC\uFF1A\u4E3B\u5E01\u79CD\u91D1\u989D\uFF08\u5982 1.5 = \u6BCF\u6B21\u70B9\u51FB 1.50\uFF1B\u5185\u90E8 \xD7100 \u5199\u5165 MaxCPCAmount\uFF09",
   parseFloat
 ).option(
   "--bid-ceiling <amount>",
@@ -9936,9 +10009,44 @@ adCmd.command("campaign-create").description(
   "--descriptions <descs>",
   "\u5E7F\u544A\u63CF\u8FF0\uFF0C\u9017\u53F7\u5206\u9694\uFF0C\u81F3\u5C11 2 \u6761\uFF0C\u6BCF\u6761 \u2264 90 \u5B57\u7B26",
   (v) => v.split(",").map((s) => s.trim())
-).option("--final-url <url>", "\u5E7F\u544A\u843D\u5730\u9875\uFF08\u5173\u952E\u8BCD\u548C\u5E7F\u544A\u5171\u7528\uFF1B\u4E0D\u4F20\u5219\u7EE7\u627F --url\uFF09").option("--path1 <path>", "\u5C55\u793A URL \u8DEF\u5F84 1\uFF08\u2264 15 \u5B57\u7B26\uFF0C\u53EF\u9009\uFF09").option("--path2 <path>", "\u5C55\u793A URL \u8DEF\u5F84 2\uFF08\u2264 15 \u5B57\u7B26\uFF0C\u53EF\u9009\uFF09").option("--draft", "\u4EC5\u4FDD\u5B58\u4E3A\u8349\u7A3F\uFF08DraftStatus=Draft\uFF0C\u9700\u8981\u540E\u7EED ad batch publish \u53D1\u5E03\uFF09", false).option("-t, --token <token>", "Auth Token").option("--json", "JSON \u683C\u5F0F\u8F93\u51FA\u539F\u59CB\u54CD\u5E94", false).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(async (opts) => {
+).option("--final-url <url>", "\u5E7F\u544A\u843D\u5730\u9875\uFF08\u5173\u952E\u8BCD\u548C\u5E7F\u544A\u5171\u7528\uFF1B\u4E0D\u4F20\u5219\u7EE7\u627F --url\uFF09").option("--path1 <path>", "\u5C55\u793A URL \u8DEF\u5F84 1\uFF08\u2264 15 \u5B57\u7B26\uFF0C\u53EF\u9009\uFF09").option("--path2 <path>", "\u5C55\u793A URL \u8DEF\u5F84 2\uFF08\u2264 15 \u5B57\u7B26\uFF0C\u53EF\u9009\uFF09").option(
+  "--product-words <words>",
+  "\u63A8\u5E7F\u4EA7\u54C1\u8BCD\uFF0C\u9017\u53F7\u5206\u9694\uFF08\u5199\u5165\u5916\u5C42 productWords\uFF0C\u7528\u4E8E AI \u5173\u952E\u8BCD\u63A8\u8350\uFF09",
+  (v) => v.split(",").map((s) => s.trim())
+).option(
+  "--negative-keywords <kws>",
+  "\u5426\u5B9A\u5173\u952E\u8BCD\uFF0C\u9017\u53F7\u5206\u9694\uFF08\u751F\u6210 NegativeKeywordsForBatchJob\uFF0C\u9ED8\u8BA4 BROAD \u5339\u914D\uFF09",
+  (v) => v.split(",").map((s) => s.trim())
+).option(
+  "--extensions-json <json>",
+  "\u5E7F\u544A\u9644\u52A0\u529F\u80FD JSON \u6570\u7EC4\u5B57\u7B26\u4E32\uFF08ExtensionsForBatchJob\uFF1B\u5305\u542B CALL/SITELINK/STRUCTURED_SNIPPET \u7B49\uFF09"
+).option(
+  "--extra-adgroups-json <json>",
+  "\u989D\u5916\u5E7F\u544A\u7EC4 JSON \u6570\u7EC4\u5B57\u7B26\u4E32\uFF08\u8FFD\u52A0\u5230 AdGroupsForBatchJob\uFF1B\u6BCF\u6761\u987B\u5305\u542B Name/MaxCPCAmount/AdsForBatchJob/KeywordsForBatchJob \u7B49\u5B57\u6BB5\uFF09"
+).option(
+  "--config-file <path>",
+  "JSON \u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84\uFF08\u63A8\u8350 AI \u4F7F\u7528\uFF09\uFF1A\u5C06\u6240\u6709\u53C2\u6570\u5199\u5165 JSON \u6587\u4EF6\u518D\u4F20\u6B64\u8DEF\u5F84\uFF0C\u652F\u6301 headlines \u6570\u7EC4\uFF08\u5141\u8BB8\u5143\u7D20\u5185\u542B\u9017\u53F7\uFF09\u3001extensions/extraAdGroups \u76F4\u63A5\u4F5C\u4E3A JSON \u6570\u7EC4\uFF0CCLI \u663E\u5F0F\u4F20\u5165\u7684\u53C2\u6570\u4F1A\u8986\u76D6\u6587\u4EF6\u4E2D\u7684\u540C\u540D\u5B57\u6BB5"
+).option("--draft", "\u4EC5\u4FDD\u5B58\u4E3A\u8349\u7A3F\uFF08DraftStatus=Draft\uFF0C\u9700\u8981\u540E\u7EED ad batch publish \u53D1\u5E03\uFF09", false).option("-t, --token <token>", "Auth Token").option("--json", "JSON \u683C\u5F0F\u8F93\u51FA\u539F\u59CB\u54CD\u5E94", false).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(async (opts) => {
+  if (!opts.configFile) {
+    const missing = [];
+    if (!opts.account) missing.push("-a/--account");
+    if (!opts.customerName) missing.push("--customer-name");
+    if (!opts.name) missing.push("--name");
+    if (opts.budget === void 0) missing.push("--budget");
+    if (!opts.bidding) missing.push("--bidding");
+    if (!opts.locationIds?.length) missing.push("--location-ids");
+    if (!opts.adgroupName) missing.push("--adgroup-name");
+    if (opts.maxCpc === void 0) missing.push("--max-cpc");
+    if (missing.length > 0) {
+      console.error(`
+\u274C \u7F3A\u5C11\u5FC5\u586B\u53C2\u6570\uFF1A${missing.join("\uFF0C")}
+   \u63D0\u793A\uFF1A\u53EF\u4F7F\u7528 --config-file <path> \u4ECE JSON \u6587\u4EF6\u8BFB\u53D6\u6240\u6709\u53C2\u6570
+`);
+      process.exit(1);
+    }
+  }
   const strategies = ["TARGET_SPEND", "MANUAL_CPC", "TARGET_CPA", "TARGET_ROAS"];
-  if (!strategies.includes(opts.bidding)) {
+  if (opts.bidding && !strategies.includes(opts.bidding)) {
     console.error(`
 \u274C --bidding \u53EA\u63A5\u53D7 ${strategies.join(" | ")}
 `);
@@ -9955,26 +10063,46 @@ adCmd.command("campaign-create").description(
 `);
     process.exit(1);
   }
+  let extensionsJson;
+  if (opts.extensionsJson) {
+    try {
+      extensionsJson = JSON.parse(opts.extensionsJson);
+    } catch {
+      console.error("\n\u274C --extensions-json \u683C\u5F0F\u9519\u8BEF\uFF0C\u8BF7\u4F20\u5165\u5408\u6CD5\u7684 JSON \u6570\u7EC4\u5B57\u7B26\u4E32\n");
+      process.exit(1);
+    }
+  }
+  let extraAdGroupsJson;
+  if (opts.extraAdgroupsJson) {
+    try {
+      extraAdGroupsJson = JSON.parse(opts.extraAdgroupsJson);
+    } catch {
+      console.error("\n\u274C --extra-adgroups-json \u683C\u5F0F\u9519\u8BEF\uFF0C\u8BF7\u4F20\u5165\u5408\u6CD5\u7684 JSON \u6570\u7EC4\u5B57\u7B26\u4E32\n");
+      process.exit(1);
+    }
+  }
   await runAdCampaignCreate({
+    configFile: opts.configFile,
     token: opts.token,
-    account: opts.account,
-    customerName: opts.customerName,
-    name: opts.name,
-    budget: opts.budget,
-    biddingStrategy: opts.bidding,
+    // 未使用 config-file 时，这些字段已通过上方校验确保非空；config-file 场景下函数内部会从文件补全
+    account: opts.account ?? "",
+    customerName: opts.customerName ?? "",
+    name: opts.name ?? "",
+    budget: opts.budget ?? 0,
+    biddingStrategy: opts.bidding ?? "",
     bidCeiling: opts.bidCeiling,
     targetCpa: opts.targetCpa,
     targetRoas: opts.targetRoas,
     targetSearchNetwork: opts.searchNetwork,
     targetContentNetwork: opts.contentNetwork,
-    locationIds: opts.locationIds,
+    locationIds: opts.locationIds ?? [],
     languageIds: opts.langIds,
     startDate: opts.start,
     endDate: opts.end,
     url: opts.url,
     status: opts.status ?? "Enabled",
-    adgroupName: opts.adgroupName,
-    maxCpc: opts.maxCpc,
+    adgroupName: opts.adgroupName ?? "",
+    maxCpc: opts.maxCpc ?? 0,
     keywords: opts.keywords,
     matchType: opts.matchType,
     headlines: opts.headlines,
@@ -9982,6 +10110,10 @@ adCmd.command("campaign-create").description(
     finalUrl: opts.finalUrl,
     path1: opts.path1,
     path2: opts.path2,
+    productWords: opts.productWords,
+    negativeKeywords: opts.negativeKeywords,
+    extensionsJson,
+    extraAdGroupsJson,
     draft: opts.draft,
     json: opts.json,
     verbose: opts.verbose

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.0.0-beta.52",
-  "publishedAt": 1775024116116
+  "version": "1.0.0-beta.53",
+  "publishedAt": 1775034415747
 }

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

@@ -9,7 +9,7 @@
 
 ### 第一步：规则文档阅读（不得跳过）
 
-操作开始前，**AI 必须先阅读完下面所有相关文档**，并在心智模型中内化规则后，才能进入任何「方案规划 / 广告创建 / 调整」步骤，严禁只读 `google-ads-launch-plan-template.md` 就直接出方案。
+操作开始前，**AI 必须先阅读完下面所有文档**，并在心智模型中内化规则后，才能进入任何「方案规划 / 广告创建 / 调整」步骤，严禁只读 `google-ads-launch-plan-template.md` 就直接出方案。
 
 | 文档地址 | 文档内容 |
 |----------|-----------|
@@ -591,7 +591,7 @@ siluzan-tso keyword -k "running shoes" --json
 
 ## ad campaign-create — 广告系列新增
 
-新建搜索广告系列（异步批量任务）。支持两种模式：
+新建搜索广告系列（异步批量任务）。支持两种创建模式：
 
 - **一体化模式**（推荐）：传入 `--keywords`、`--headlines`、`--descriptions`，一条命令完成系列 + 组 + 关键词 + 广告创意，与网页 AI 创建向导行为等价。
 - **骨架模式**：仅创建系列和空广告组，后续用 `ad keyword-create`、`ad ad-create` 补充内容。
@@ -603,41 +603,202 @@ siluzan-tso keyword -k "running shoes" --json
 > 广告组、关键词、广告创意的直接创建走另一套 Google 网关 API，均有对应的 `adgroup-create`、`keyword-create`、`ad-create` 等命令。  
 > 任务异步处理，任务 ID 可通过 `ad batch get --id <id>` 跟进进度。
 
-### 选项
+---
+
+### 🤖 AI 推荐用法：--config-file（JSON 配置文件）
+
+**当参数复杂（多广告组、含附加功能、标题中有逗号）时，AI 应优先使用此方式**：将所有参数写入一个 JSON 文件，再用 `--config-file` 传入路径。
+
+**优势：**
+- `headlines` 是真正的字符串数组，元素内**允许含逗号**（如 `"Global Reach, Local Impact"`）
+- `extensions` / `extraAdGroups` 直接写 JSON，不需要序列化为字符串
+- 参数复杂时无 shell 转义问题，AI 一次生成即可成功
+
+**AI 执行步骤：**
+1. 用 Write 工具将配置写入 JSON 文件（如 `/tmp/campaign.json`）
+2. 执行 `siluzan-tso ad campaign-create --config-file /tmp/campaign.json`
+3. 用返回的任务 ID 查询进度
+
+**JSON 配置文件完整 Schema：**
+
+```json
+{
+  "account": "6326027735",
+  "customerName": "账户显示名称（来自 list-accounts --json 的 mediaAccountName）",
+  "name": "搜索-品牌词-2026",
+  "budget": 100,
+  "bidding": "TARGET_SPEND",
+  "bidCeiling": 1.5,
+  "locationIds": ["2840", "2826", "2036"],
+  "languageIds": ["1000", "1017"],
+  "startDate": "2026-04-01",
+  "endDate": "2027-04-01",
+  "url": "https://www.example.com",
+  "status": "Enabled",
+  "adgroupName": "核心词_品牌词",
+  "maxCpc": 1.5,
+  "matchType": "BROAD",
+  "keywords": [
+    "brand keyword 1",
+    "brand keyword 2",
+    "brand keyword 3"
+  ],
+  "headlines": [
+    "Brand Name: Quality Products",
+    "Trusted For Over 20 Years",
+    "Global Reach, Local Impact",
+    "Contact Us Today",
+    "Request A Free Quote Now"
+  ],
+  "descriptions": [
+    "Top-quality products with certified standards. Contact us today!",
+    "Trusted by global partners. Request a free quote now!"
+  ],
+  "finalUrl": "https://www.example.com/products",
+  "path1": "products",
+  "path2": "2026",
+  "productWords": ["brand", "product"],
+  "negativeKeywords": [
+    "free", "cheap", "wikipedia", "pdf", "ebay", "amazon"
+  ],
+  "extensions": [
+    {
+      "level": "Campaign",
+      "typeV2": "CALL",
+      "AssetFieldType": "CALL",
+      "Properties": { "ContryCode": "CN", "PhoneNumber": "+86 400-XXX-XXXX" }
+    },
+    {
+      "level": "Campaign",
+      "typeV2": "SITELINK",
+      "AssetFieldType": "SITELINK",
+      "properties": {
+        "DestinationUrl": "https://www.example.com/about",
+        "Text": "About Us",
+        "Line2": "Learn about our story",
+        "Line3": "Explore our mission"
+      }
+    },
+    {
+      "level": "Campaign",
+      "typeV2": "STRUCTURED_SNIPPET",
+      "AssetFieldType": "STRUCTURED_SNIPPET",
+      "StructuredSnippetHeaderValue": {
+        "key": "Services",
+        "value": ["Quality Certified", "Global Shipping", "24/7 Support"]
+      }
+    }
+  ],
+  "extraAdGroups": [
+    {
+      "MaxCPCAmount": 150,
+      "Name": "通用词_行业词",
+      "StatusV2": "Enabled",
+      "TypeV2": "SEARCH_STANDARD",
+      "RotationModeV2": "Unspecified",
+      "KeywordsForBatchJob": [
+        {
+          "KeywordText": ["industry keyword 1", "industry keyword 2"],
+          "MatchTypeV2": "BROAD",
+          "Finalurl": "https://www.example.com"
+        }
+      ],
+      "AdsForBatchJob": [
+        {
+          "AdTitle": null,
+          "DestinationUrl": "https://www.example.com",
+          "Finalurl": "https://www.example.com",
+          "Path1": "", "Path2": "",
+          "TypeV2": "RESPONSIVE_SEARCH_AD",
+          "headlinePart1": "Industry Leading Products",
+          "headlinePart2": "Certified Quality Standards",
+          "headlinePart3": "Get A Free Quote Today",
+          "AddtionalHeadlines": [
+            "Trusted By Global Partners",
+            "20+ Years Of Experience",
+            "Contact Us Now"
+          ],
+          "adDescription": "Top-quality industry products with global shipping. Contact us today!",
+          "adDescription2": "Certified standards and reliable delivery. Request a quote now!"
+        }
+      ]
+    }
+  ],
+  "draft": false
+}
+```
+
+**字段说明：**
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `account` | ✅ | string | Google 账户 mediaCustomerId |
+| `customerName` | ✅ | string | 账户名称（`list-accounts --json` 的 `mediaAccountName`） |
+| `name` | ✅ | string | 广告系列名称 |
+| `budget` | ✅ | number | 日预算，**主币种展示金额**（100 = 每天 100 USD/CNY，内部 ×100） |
+| `bidding` | ✅ | string | 出价策略：`TARGET_SPEND` \| `MANUAL_CPC` \| `TARGET_CPA` \| `TARGET_ROAS` |
+| `locationIds` | ✅ | string[] | 地理位置 ID 数组（`ad geo search` 获取） |
+| `adgroupName` | ✅ | string | 第一个广告组名称 |
+| `maxCpc` | ✅ | number | 第一个广告组最高 CPC，主币种展示金额（1.5 = 1.50 USD，内部 ×100） |
+| `bidCeiling` | — | number | TARGET_SPEND 出价上限（主币种，内部 ×100） |
+| `targetCpa` | — | number | TARGET_CPA 目标 CPA（主币种，内部 ×100） |
+| `targetRoas` | — | number | TARGET_ROAS 目标 ROAS（如 2.5） |
+| `languageIds` | — | string[] | 语言 ID 数组（默认 `["1000"]` = 英语，中文 = `"1017"`） |
+| `startDate` / `endDate` | — | string | 日期 YYYY-MM-DD（默认：今天 / 2037-12-30） |
+| `url` | — | string | 落地页 URL |
+| `status` | — | string | `Enabled` \| `Paused`（默认 Enabled） |
+| `matchType` | — | string | 默认匹配类型：`BROAD` \| `PHRASE` \| `EXACT` |
+| `keywords` | — | string[] | 第一个广告组关键词 |
+| `headlines` | — | string[] | 标题数组，至少 3 条，推荐 15 条，每条 ≤ 30 字符，**元素内允许含逗号** |
+| `descriptions` | — | string[] | 描述数组，至少 2 条，推荐 4 条，每条 ≤ 90 字符 |
+| `finalUrl` | — | string | 广告落地页 |
+| `path1` / `path2` | — | string | 展示 URL 路径（各 ≤ 15 字符） |
+| `productWords` | — | string[] | 推广产品词（用于 AI 关键词推荐） |
+| `negativeKeywords` | — | string[] | 否定关键词数组（默认 BROAD 匹配） |
+| `extensions` | — | array | 广告附加功能（CALL / SITELINK / STRUCTURED_SNIPPET），见 Schema |
+| `extraAdGroups` | — | array | 额外广告组，追加到 AdGroupsForBatchJob，见 Schema |
+| `draft` | — | boolean | `true` = 仅保存草稿（需后续 `ad batch publish` 发布） |
+
+---
+
+### 命令行直接传参（简单场景适用）
+
+所有参数也可以直接通过 CLI 选项传入（复杂场景推荐用 `--config-file`）：
 
 | 选项 | 必填 | 说明 |
 |------|------|------|
-| `-a, --account <id>` | ✅ | Google 账户 mediaCustomerId |
-| `--customer-name <name>` | ✅ | 账户名称（来自 `list-accounts --json` 的 `mediaAccountName`） |
-| `--name <name>` | ✅ | 广告系列名称 |
-| `--budget <amount>` | ✅ | 日预算：**账户主币种展示金额**（如 `100` = 每天 100 USD/CNY；与 Web、`ad smart create` 一致，内部 `×100` 写入 `Budget`，**非** Google micros） |
-| `--bidding <strategy>` | ✅ | 出价策略：`TARGET_SPEND` \| `MANUAL_CPC` \| `TARGET_CPA` \| `TARGET_ROAS` |
-| `--location-ids <ids>` | ✅ | 地理位置 ID，逗号分隔（用 `ad geo search` 获取，2840=美国） |
-| `--adgroup-name <name>` | ✅ | 第一个广告组名称 |
-| `--max-cpc <amount>` | ✅ | 第一个广告组最高 CPC：**主币种展示金额**（如 `1.5` = 每次点击 1.50；内部 `×100` 写入批量体 `MaxCPCAmount` 字符串） |
-| `--keywords <kws>` | — | 关键词，逗号分隔；格式：词→BROAD，`*词*`→PHRASE，`[词]`→EXACT |
-| `--match-type <type>` | — | 无格式前缀关键词的默认匹配类型（默认 BROAD） |
-| `--headlines <titles>` | — | 广告标题，逗号分隔，至少 3 条 推荐15条，每条 ≤ 30 字符 |
-| `--descriptions <descs>` | — | 广告描述，逗号分隔，至少 2 条 推荐4条，每条 ≤ 90 字符 |
-| `--final-url <url>` | — | 广告落地页（关键词 / 广告共用；不传则继承 `--url`） |
-| `--path1 / --path2` | — | 展示 URL 路径（各 ≤ 15 字符） |
-| `--url <url>` | — | 推广落地页（附在外层 body） |
-| `--lang-ids <ids>` | — | 投放语言 ID，逗号分隔（默认 1000=英语；中文=1017） |
-| `--bid-ceiling <amount>` | — | TARGET_SPEND 出价上限：主币种金额（内部 `×100`；0=不限） |
-| `--target-cpa <amount>` | — | TARGET_CPA 目标 CPA：主币种金额（内部 `×100`） |
-| `--target-roas <n>` | — | TARGET_ROAS 目标 ROAS（如 2.5；最大 1000） |
-| `--start / --end` | — | 广告系列开始/结束日期（默认：今天 / 2037-12-30） |
-| `--status` | — | 初始状态：`Enabled` \| `Paused`（默认 Enabled） |
-| `--draft` | — | 仅保存为草稿（`DraftStatus=Draft`，需后续 `ad batch publish` 发布） |
-
-**典型用法**
+| `-a, --account <id>` | ✅* | Google 账户 mediaCustomerId（*使用 `--config-file` 时可从文件读取） |
+| `--customer-name <name>` | ✅* | 账户名称 |
+| `--name <name>` | ✅* | 广告系列名称 |
+| `--budget <amount>` | ✅* | 日预算（主币种展示金额） |
+| `--bidding <strategy>` | ✅* | 出价策略 |
+| `--location-ids <ids>` | ✅* | 地理位置 ID，逗号分隔 |
+| `--adgroup-name <name>` | ✅* | 第一个广告组名称 |
+| `--max-cpc <amount>` | ✅* | 最高 CPC（主币种展示金额） |
+| `--keywords <kws>` | — | 关键词，逗号分隔 |
+| `--headlines <titles>` | — | 广告标题，逗号分隔（⚠️ 标题内不能含逗号，含逗号请用 `--config-file`） |
+| `--descriptions <descs>` | — | 广告描述，逗号分隔 |
+| `--product-words <words>` | — | 产品词，逗号分隔 |
+| `--negative-keywords <kws>` | — | 否定关键词，逗号分隔 |
+| `--extensions-json <json>` | — | 附加功能 JSON 数组字符串 |
+| `--extra-adgroups-json <json>` | — | 额外广告组 JSON 数组字符串 |
+| `--lang-ids <ids>` | — | 语言 ID，逗号分隔（默认 1000=英语） |
+| `--bid-ceiling / --target-cpa / --target-roas` | — | 出价相关参数 |
+| `--start / --end` | — | 日期 YYYY-MM-DD |
+| `--url / --final-url` | — | 落地页 |
+| `--path1 / --path2` | — | 展示路径 |
+| `--status` | — | Enabled \| Paused |
+| `--draft` | — | 仅保存草稿 |
+| `--config-file <path>` | — | JSON 配置文件路径（AI 推荐） |
+
+**典型用法（简单场景）：**
 
 ```bash
 # 前置：搜索投放地区 ID
 siluzan-tso ad geo search -a 6326027735 -q "United States"
 # 取出 id 字段，如 2840
 
-# 一体化创建（系列 + 关键词 + 广告创意，推荐）
+# 一体化创建（CLI 直接传参，适合参数较少的场景）
 siluzan-tso ad campaign-create \
   -a 6326027735 \
   --customer-name "测试账户" \
@@ -648,17 +809,28 @@ siluzan-tso ad campaign-create \
   --adgroup-name "核心词_跑步鞋" \
   --max-cpc 5 \
   --url "https://www.brand-a.com/running-shoes" \
-  --keywords "running shoes,sport shoes,[trail running]" \
-  --headlines "专业跑步鞋,轻量透气设计,品牌直销价" \
-  --descriptions "全球百万跑者信赖，专业助力每一步。,免费配送，30天无理由退换。" \
+  --keywords "running shoes,sport shoes,trail running" \
+  --headlines "Brand Running Shoes,Lightweight Design,Direct Factory Price" \
+  --descriptions "Trusted by millions worldwide.,Free shipping and 30-day returns." \
   --final-url "https://www.brand-a.com/running-shoes" \
-  --path1 "跑步鞋" \
-  --path2 "特惠"
+  --path1 "running" \
+  --path2 "shoes"
 
-# 第四步：用返回的任务 ID 查看创建进度
+# 查看创建进度
 siluzan-tso ad batch get --id <taskId>
 ```
 
+**典型用法（AI 推荐，config-file 方式）：**
+
+```bash
+# 1. AI 先写好 JSON 配置文件（使用 Write 工具）
+# 2. 执行创建
+siluzan-tso ad campaign-create --config-file /tmp/campaign-config.json
+
+# 3. 查看进度
+siluzan-tso ad batch get --id <返回的taskId>
+```
+
 ---
 
 ## ad campaign-edit — 广告系列编辑

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.0.0-beta.52",
+  "version": "1.0.0-beta.53",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "type": "module",
   "bin": {