siluzan-tso-cli 1.1.37-beta.6 → 1.1.37-beta.8

package/README.md

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

package/dist/index.js

@@ -112422,16 +112422,26 @@ async function runAdCampaignCreate(opts) {
 `);
     process.exit(1);
   }
+  const taskId = data?.["id"] ?? data?.["data"];
+  const agentWorkflow = {
+    status: "Creating",
+    terminal: false,
+    shouldRunBatchDiff: false,
+    shouldPollBatchGet: true,
+    batchId: taskId != null ? String(taskId) : null,
+    configFile: opts.configFile,
+    nextCommand: taskId != null ? `siluzan-tso ad batch get --id ${String(taskId)} --config-file ${opts.configFile} --json-out ./snap-campaign` : null,
+    agentHint: "\u4EFB\u52A1\u5DF2\u63D0\u4EA4\uFF1A\u6BCF 5s \u8F6E\u8BE2 nextCommand\uFF08ad batch get\uFF0C\u987B\u5E26\u540C\u4E00 --config-file \u4E0E --json-out\uFF09\uFF1B\u8BFB\u843D\u76D8 agentWorkflow\uFF1ACreating \u7EE7\u7EED\u8F6E\u8BE2\uFF1BSuccessfully/HasFailed \u6267\u884C nextCommand \u7684 batch diff\uFF08\u542B\u6295\u653E\u56FD\u5BB6\uFF09\uFF1BFailed \u53EA\u770B reason/errors\u3002"
+  };
   if (await emitCliJsonOrSnapshot(opts, {
     section: `ad-campaign-create-async-${cfg.account}`,
     commandLabel: "ad campaign-create",
     commandHint: cfg.account,
-    payload: data,
+    payload: { ...data, agentWorkflow },
     idSuffix: cfg.account
   })) {
     return;
   }
-  const taskId = data?.["id"] ?? data?.["data"];
   const campaign = cfg.campaign;
   const adGroups = campaign["AdGroupsForBatchJob"] ?? [];
   let kwCount = 0;
@@ -114605,6 +114615,7 @@ function buildExtensionRemediateCommandLine(opts) {
     parts.push(levelFlag);
     if (campaignFlag) parts.push(campaignFlag);
     parts.push(`--json-out ${jsonOut}`);
+    parts.push(`--commit ${shellArg("batch-diff remediate extension")}`);
     return parts.join(" ");
   }
   if (type === "CALLOUT") {
@@ -114619,6 +114630,7 @@ function buildExtensionRemediateCommandLine(opts) {
     ];
     if (campaignFlag) parts.push(campaignFlag);
     parts.push(`--json-out ${jsonOut}`);
+    parts.push(`--commit ${shellArg("batch-diff remediate extension")}`);
     return parts.join(" ");
   }
   if (type === "CALL") {
@@ -114635,6 +114647,7 @@ function buildExtensionRemediateCommandLine(opts) {
     ];
     if (campaignFlag) parts.push(campaignFlag);
     parts.push(`--json-out ${jsonOut}`);
+    parts.push(`--commit ${shellArg("batch-diff remediate extension")}`);
     return parts.join(" ");
   }
   if (type === "STRUCTURED_SNIPPET") {
@@ -114654,6 +114667,7 @@ function buildExtensionRemediateCommandLine(opts) {
     ];
     if (campaignFlag) parts.push(campaignFlag);
     parts.push(`--json-out ${jsonOut}`);
+    parts.push(`--commit ${shellArg("batch-diff remediate extension")}`);
     return parts.join(" ");
   }
   return null;
@@ -114666,6 +114680,7 @@ function asRecord3(v) {
 function pickString2(...vals) {
   for (const v of vals) {
     if (typeof v === "string" && v.trim()) return v.trim();
+    if (typeof v === "number" && Number.isFinite(v)) return String(v);
   }
   return "";
 }
@@ -114711,6 +114726,28 @@ function liveAdHasHeadline(ad, headline) {
   if (!h) return false;
   return collectRsaHeadlines(ad).includes(h);
 }
+function liveLocationId(item) {
+  return pickString2(
+    item["id"],
+    item["Id"],
+    item["countryCriteriaId"],
+    item["locationId"],
+    item["criterionId"],
+    item["geoTargetConstantId"]
+  );
+}
+function buildGeoRemediateCommandLine(opts) {
+  return [
+    "siluzan-tso",
+    "ad",
+    "geo",
+    "add",
+    `-a ${opts.accountId}`,
+    `--campaign-id ${opts.campaignId}`,
+    `--location-id ${opts.locationId}`,
+    `--commit "batch-diff remediate geo"`
+  ].join(" ");
+}
 function formatExtensionPlanned(ext) {
   if (!ext) return "\u2014";
   const type = pickString2(ext["typeV2"], ext["AssetFieldType"], ext["type"]);
@@ -114925,11 +114962,48 @@ function compareCampaignCreateToLive(cfg, campaignId, live, meta) {
       });
     }
   }
+  const plannedLocs = campaign["targetedLocations"];
+  const locationNames = Array.isArray(cfg.locations) ? cfg.locations.map((x) => typeof x === "string" ? x.trim() : String(x ?? "")) : [];
+  const liveLocRows = (live.targetedLocations ?? []).filter(
+    (loc) => belongsToCampaign(loc, campaignId, campaignName)
+  );
+  const liveLocIds = new Set(
+    liveLocRows.map((loc) => liveLocationId(loc)).filter((id) => id.length > 0)
+  );
+  let plannedLocCount = 0;
+  if (Array.isArray(plannedLocs)) {
+    plannedLocCount = plannedLocs.length;
+    for (let li = 0; li < plannedLocs.length; li++) {
+      const loc = asRecord3(plannedLocs[li]);
+      if (!loc) continue;
+      const id = pickString2(loc["id"], loc["Id"]);
+      if (!id) continue;
+      if (liveLocIds.has(id)) continue;
+      const displayName = locationNames[li] || pickString2(loc["locationName"], loc["name"], loc["countryOrRegion"]) || "";
+      const remediateCommand = accountId && campaignId ? buildGeoRemediateCommandLine({ accountId, campaignId, locationId: id }) : void 0;
+      missing.push({
+        layer: "location",
+        path: `campaign.targetedLocations[${li}]`,
+        plannedContent: `locationId: ${id}${displayName ? `  |  \u540D\u79F0: ${displayName}` : ""}`,
+        liveNote: `\u7CFB\u5217\u5DF2\u5B9A\u5411 ${liveLocIds.size}/${plannedLocCount} \u4E2A\u5730\u57DF`,
+        summary: `\u6295\u653E\u56FD\u5BB6/\u5730\u57DF\u672A\u751F\u6548\uFF1A${displayName || id}\uFF08id=${id}\uFF09`,
+        remediateCommand
+      });
+    }
+  }
   const plannedKeywords = listPlannedKeywords(campaign);
   const liveKwCount = live.keywords.filter(
     (k) => belongsToCampaign(k, campaignId, campaignName)
   ).length;
   const liveAdCount = live.ads.filter((a) => belongsToCampaign(a, campaignId, campaignName)).length;
+  const ok = missing.length === 0;
+  const remediateCount = missing.filter((m) => m.remediateCommand).length;
+  let agentHint;
+  if (!ok) {
+    agentHint = `\u53D1\u73B0 ${missing.length} \u9879\u4E0E\u8BA1\u5212\u4E0D\u4E00\u81F4` + (remediateCount > 0 ? `\uFF1B\u5176\u4E2D ${remediateCount} \u6761\u542B remediateCommand\uFF0CAgent \u5E94\u76F4\u63A5\u6267\u884C\u8865\u5EFA\uFF08\u52FF\u4EC5\u8BE2\u95EE\u7528\u6237\uFF09` : "\uFF1B\u6309 layer \u7528 ad adgroup-create / keyword-create / ad-create / keyword-negative-create / ad geo add / ad extension * \u8865\u5EFA") + "\uFF1B\u8865\u5EFA\u540E\u518D\u6B21 ad batch diff\u3002";
+  } else {
+    agentHint = "\u4E0E JSON \u8BA1\u5212\u4E00\u81F4\uFF08\u542B\u6295\u653E\u5730\u57DF\uFF09\uFF1B\u53EF\u5411\u7528\u6237\u786E\u8BA4\u521B\u5EFA\u5B8C\u6210\u3002";
+  }
   return {
     accountId,
     campaignId,
@@ -114937,6 +115011,8 @@ function compareCampaignCreateToLive(cfg, campaignId, live, meta) {
     configFile: meta?.configFile ?? "",
     batchId: meta?.batchId,
     batchStatus: meta?.batchStatus,
+    ok,
+    agentHint,
     live,
     missing,
     counts: {
@@ -114955,7 +115031,9 @@ function compareCampaignCreateToLive(cfg, campaignId, live, meta) {
         (k) => belongsToCampaign(k, campaignId, campaignName)
       ).length,
       plannedExtensions: plannedExt,
-      liveExtensions: liveExt
+      liveExtensions: liveExt,
+      plannedLocations: plannedLocCount,
+      liveLocations: liveLocIds.size
     }
   };
 }
@@ -114973,7 +115051,7 @@ async function fetchLiveSnapshotForCampaign(config, accountId, campaignId, campa
   params.set("startDate", toGoogleDate(void 0, -30));
   params.set("endDate", toGoogleDate(void 0, 0));
   const qs = params.toString();
-  const [campaigns, adGroups, keywords, negativeKeywords, ads, extensions] = await Promise.all([
+  const [campaigns, adGroups, keywords, negativeKeywords, ads, extensions, targetedLocations] = await Promise.all([
     fetchList(
       config,
       `${googleApiUrl}/campaignmanagement/v2/list/${accountId}?${qs}`,
@@ -115003,6 +115081,11 @@ async function fetchLiveSnapshotForCampaign(config, accountId, campaignId, campa
       config,
       `${googleApiUrl}/extensionmanagement/v2/list/${accountId}`,
       verbose
+    ),
+    fetchList(
+      config,
+      `${googleApiUrl}/campaignmanagement/v2/targetedlocations/${accountId}?${qs}`,
+      verbose
     )
   ]);
   const campaignFound = campaigns.some(
@@ -115017,12 +115100,78 @@ async function fetchLiveSnapshotForCampaign(config, accountId, campaignId, campa
       (k) => belongsToCampaign(k, campaignId, campaignName)
     ),
     ads: ads.filter((a) => belongsToCampaign(a, campaignId, campaignName)),
-    extensions: extensions.filter((e) => belongsToCampaign(e, campaignId, campaignName))
+    extensions: extensions.filter((e) => belongsToCampaign(e, campaignId, campaignName)),
+    targetedLocations: targetedLocations.filter(
+      (loc) => belongsToCampaign(loc, campaignId, campaignName)
+    )
   };
 }
 function resolveCampaignIdFromBatch(record2) {
   const campaign = asRecord3(record2["campaign"]);
-  return pickString2(campaign?.["Id"], campaign?.["id"], record2["campaignId"]);
+  const direct = pickString2(
+    campaign?.["Id"],
+    campaign?.["id"],
+    record2["campaignId"],
+    record2["CampaignId"]
+  );
+  if (direct) return direct;
+  const groups = campaign?.["AdGroupsForBatchJob"];
+  if (Array.isArray(groups)) {
+    for (const g of groups) {
+      const gr = asRecord3(g);
+      const cid = pickString2(gr?.["CampaignId"], gr?.["campaignId"]);
+      if (cid) return cid;
+    }
+  }
+  return "";
+}
+function resolveCampaignNameFromBatch(record2) {
+  const campaign = asRecord3(record2["campaign"]);
+  return pickString2(
+    record2["campaignName"],
+    record2["CampaignName"],
+    campaign?.["Name"],
+    campaign?.["name"]
+  );
+}
+function buildBatchGetAgentWorkflow(opts) {
+  const status = pickString2(opts.record["status"]);
+  const campaignId = resolveCampaignIdFromBatch(opts.record) || null;
+  const campaignName = resolveCampaignNameFromBatch(opts.record) || null;
+  const runDiff = shouldRunBatchDiff(status);
+  let nextCommand = null;
+  let agentHint;
+  if (status === "Creating") {
+    agentHint = "\u4EFB\u52A1\u4ECD\u5728 Creating\uFF1A\u6BCF 5s \u8F6E\u8BE2 ad batch get\uFF08\u987B\u5E26\u540C\u4E00 --config-file\uFF09\uFF0C\u52FF\u6267\u884C batch diff\u3002";
+    nextCommand = opts.configFile ? `siluzan-tso ad batch get --id ${opts.batchId} --config-file ${shellArgPath(opts.configFile)} --json-out ./snap-campaign` : `siluzan-tso ad batch get --id ${opts.batchId} --config-file <campaign.json> --json-out ./snap-campaign`;
+  } else if (status === "Failed") {
+    agentHint = "\u5168\u90E8 Failed\uFF1A\u8BFB reason/errors\uFF0C\u6539 JSON \u540E\u91CD\u63D0 campaign-create\uFF1B\u4E0D\u8981\u8DD1 batch diff\u3002";
+    nextCommand = null;
+  } else if (runDiff) {
+    if (!opts.configFile) {
+      agentHint = "\u5DF2\u53EF\u6BD4\u5BF9\uFF0C\u4F46\u7F3A\u5C11 --config-file\uFF1A\u8BF7\u7528\u63D0\u4EA4\u65F6\u7684 campaign.json \u6267\u884C ad batch diff\uFF08\u5FC5\u505A\uFF09\u3002";
+      nextCommand = `siluzan-tso ad batch diff --batch-id ${opts.batchId} --config-file <campaign.json>${campaignId ? ` --campaign-id ${campaignId}` : ""} --json-out ./snap-campaign`;
+    } else {
+      nextCommand = buildBatchDiffCommandLine({
+        batchId: opts.batchId,
+        configFile: opts.configFile,
+        campaignId: campaignId ?? void 0
+      });
+      agentHint = `\u5FC5\u505A\u4E0B\u4E00\u6B65\uFF1A\u6267\u884C nextCommand\uFF08ad batch diff\uFF09\uFF0C\u6838\u5BF9\u7EC4/\u8BCD/RSA/\u5426\u8BCD/\u9644\u52A0\u4FE1\u606F/\u6295\u653E\u56FD\u5BB6\uFF1B\u6709 remediateCommand \u5219\u76F4\u63A5\u8865\u5EFA\u3002`;
+    }
+  } else {
+    agentHint = `\u5F53\u524D status=${status || "\u2014"}\uFF0C\u6309 google-ads.md \xA7 batch \u5904\u7406\u3002`;
+  }
+  return {
+    status: status || null,
+    terminal: isBatchTerminalStatus(status),
+    shouldRunBatchDiff: runDiff,
+    campaignId,
+    campaignName,
+    configFile: opts.configFile ?? null,
+    nextCommand,
+    agentHint
+  };
 }
 function shellArgPath(p) {
   return /[\s"]/.test(p) ? `"${p.replace(/"/g, '\\"')}"` : p;
@@ -115038,6 +115187,9 @@ function buildBatchDiffCommandLine(opts) {
   }
   return parts.join(" ");
 }
+function isBatchTerminalStatus(status) {
+  return status === "Successfully" || status === "Failed" || status === "HasFailed";
+}
 function shouldRunBatchDiff(status) {
   return status === "Successfully" || status === "HasFailed";
 }
@@ -115067,17 +115219,23 @@ function printBatchDiffFollowUpHint(opts) {
     campaignId: opts.campaignId
   });
   if (opts.status === "Successfully") {
-    console.log("  \u6838\u5BF9\u8BA1\u5212\u4E0E\u8D26\u6237\u662F\u5426\u4E00\u81F4\uFF08\u65E0\u7F3A\u5931\u5E94\u663E\u793A \u2705\uFF09\u3002\n");
+    console.log(
+      "  \u6838\u5BF9\u8BA1\u5212\u4E0E\u8D26\u6237\u662F\u5426\u4E00\u81F4\uFF08\u542B\u6295\u653E\u56FD\u5BB6/\u5730\u57DF\uFF1B\u65E0\u7F3A\u5931\u5E94\u663E\u793A \u2705\uFF0C--json-out \u65F6\u8BFB ok=true\uFF09\u3002\n"
+    );
   } else {
     console.log(
-      "  \u5217\u51FA\u7F3A\u5931\u9879\u540E\u81EA\u52A8\u8865\u5EFA\uFF08\u9644\u52A0\u4FE1\u606F\u7528 ad extension *\uFF1B\u7EC4/\u8BCD/RSA \u7528\u5BF9\u5E94 create \u547D\u4EE4\uFF09\u3002\n"
+      "  \u5217\u51FA\u7F3A\u5931\u9879\u540E\u81EA\u52A8\u8865\u5EFA\uFF08\u5730\u57DF\u7528 ad geo add\uFF1B\u9644\u52A0\u4FE1\u606F\u7528 ad extension *\uFF1B\u7EC4/\u8BCD/RSA \u7528\u5BF9\u5E94 create\uFF09\u3002\n"
     );
   }
   console.log(`  ${cmd}
 `);
+  console.log(
+    "  Agent\uFF1A\u51E0\u4E4E\u603B\u662F\u5E26 --json-out\uFF1B\u8BF7\u8BFB\u843D\u76D8 JSON \u7684 agentWorkflow.nextCommand / ok / missing[].remediateCommand\u3002\n"
+  );
 }
 var LAYER_ORDER = [
   "campaign",
+  "location",
   "adgroup",
   "keyword",
   "ad",
@@ -115086,6 +115244,7 @@ var LAYER_ORDER = [
 ];
 var LAYER_TITLE = {
   campaign: "\u7CFB\u5217",
+  location: "\u6295\u653E\u56FD\u5BB6/\u5730\u57DF",
   adgroup: "\u5E7F\u544A\u7EC4",
   keyword: "\u5173\u952E\u8BCD",
   ad: "\u521B\u610F",
@@ -115131,11 +115290,13 @@ function formatBatchDiffGrouped(result) {
   console.log(`  \u914D\u7F6E\u6587\u4EF6\uFF1A${result.configFile}`);
   const c = result.counts;
   console.log(
-    `  \u5E7F\u544A\u7EC4 ${c.liveAdGroups}/${c.plannedAdGroups}  |  \u5173\u952E\u8BCD ${c.liveKeywords}/${c.plannedKeywords}  |  \u521B\u610F ${c.liveAds}/${c.plannedAds}  |  \u5426\u5B9A\u8BCD ${c.liveNegativeKeywords}/${c.plannedNegativeKeywords}  |  \u9644\u52A0\u4FE1\u606F ${c.liveExtensions}/${c.plannedExtensions}`
+    `  \u5E7F\u544A\u7EC4 ${c.liveAdGroups}/${c.plannedAdGroups}  |  \u5173\u952E\u8BCD ${c.liveKeywords}/${c.plannedKeywords}  |  \u521B\u610F ${c.liveAds}/${c.plannedAds}  |  \u5426\u5B9A\u8BCD ${c.liveNegativeKeywords}/${c.plannedNegativeKeywords}  |  \u9644\u52A0\u4FE1\u606F ${c.liveExtensions}/${c.plannedExtensions}  |  \u5730\u57DF ${c.liveLocations}/${c.plannedLocations}`
   );
   console.log();
   if (result.missing.length === 0) {
-    console.log("  \u2705 \u672A\u53D1\u73B0\u7F3A\u5931\u9879\uFF08\u4E0E JSON \u8BA1\u5212\u4E00\u81F4\uFF0C\u6216\u5DEE\u5F02\u672A\u7EB3\u5165\u6BD4\u5BF9\u7EF4\u5EA6\uFF09\u3002\n");
+    console.log("  \u2705 \u672A\u53D1\u73B0\u7F3A\u5931\u9879\uFF08\u4E0E JSON \u8BA1\u5212\u4E00\u81F4\uFF0C\u542B\u6295\u653E\u5730\u57DF\uFF09\u3002\n");
+    if (result.agentHint) console.log(`  ${result.agentHint}
+`);
     return;
   }
   console.log(`\u2500\u2500 \u7F3A\u5931\u660E\u7EC6\uFF08\u5171 ${result.missing.length} \u6761\uFF09\u2500\u2500`);
@@ -115163,7 +115324,7 @@ function formatBatchDiffGrouped(result) {
       printMissingGroupByAdGroup(configFile, layer, layerItems);
       continue;
     }
-    if (layer === "negative_keyword" || layer === "extension") {
+    if (layer === "location" || layer === "negative_keyword" || layer === "extension") {
       console.log(`
 [${LAYER_TITLE[layer]}] \u7CFB\u5217\u7EA7\uFF08${layerItems.length} \u6761\uFF09`);
       for (const m of layerItems) {
@@ -115174,8 +115335,17 @@ function formatBatchDiffGrouped(result) {
           "\n  \u{1F4A1} \u9644\u52A0\u4FE1\u606F BatchJob \u5E38\u5931\u8D25\uFF1AAgent \u5E94**\u76F4\u63A5\u6267\u884C**\u4E0A\u65B9\u300C\u8865\u5EFA\u300D\u547D\u4EE4\uFF08\u7528\u6237\u5DF2\u786E\u8BA4\u8FC7 JSON\uFF09\uFF0C\u52FF\u4EC5\u8BE2\u95EE\u662F\u5426\u8865\u5EFA\u3002"
         );
       }
+      if (layer === "location" && layerItems.some((m) => m.remediateCommand)) {
+        console.log(
+          "\n  \u{1F4A1} \u6295\u653E\u5730\u57DF\u7F3A\u5931\uFF1AAgent \u5E94**\u76F4\u63A5\u6267\u884C**\u4E0A\u65B9\u300C\u8865\u5EFA\u300D`ad geo add`\uFF08\u7528\u6237\u5DF2\u786E\u8BA4\u8FC7 JSON\uFF09\uFF0C\u52FF\u8DF3\u8FC7\u3002"
+        );
+      }
     }
   }
+  if (result.agentHint) {
+    console.log(`
+  \u{1F449} ${result.agentHint}`);
+  }
   console.log();
 }
 async function runCampaignBatchDiff(opts) {
@@ -115267,9 +115437,11 @@ async function runCampaignBatchDiff(opts) {
     payload: result,
     idSuffix: campaignId
   })) {
+    if (!result.ok) process.exit(2);
     return;
   }
   formatBatchDiffGrouped(result);
+  if (!result.ok) process.exit(2);
 }
 
 // src/commands/ad/ai-creation.ts
@@ -115402,11 +115574,17 @@ async function runAiCreationGet(opts) {
 `);
     process.exit(1);
   }
+  const agentWorkflow = buildBatchGetAgentWorkflow({
+    batchId: opts.id,
+    record: data,
+    configFile: opts.configFile
+  });
+  const payload = { ...data, agentWorkflow };
   if (await emitCliJsonOrSnapshot(opts, {
     section: `ad-batch-get-${opts.id}`,
     commandLabel: "ad batch get",
     commandHint: opts.id,
-    payload: data,
+    payload,
     idSuffix: opts.id
   })) {
     return;
@@ -119087,10 +119265,13 @@ function register20(program2) {
     }
   );
   adBatchCmd.command("get").description(
-    "\u83B7\u53D6\u5355\u6761\u8BB0\u5F55/\u8349\u7A3F\u8BE6\u60C5\uFF08\u9ED8\u8BA4\uFF1A\u6458\u8981\u8868 + \u540E\u7AEF\u539F\u59CB reason/errors\uFF1B--json-out \u8F93\u51FA\u5B8C\u6574 JSON\uFF09\n  \u6210\u529F\u6216\u90E8\u5206\u6210\u529F\u540E\u987B\u6267\u884C ad batch diff\uFF08\u89C1 --config-file\uFF09\uFF1BFailed \u4EC5\u770B reason/errors \u540E\u91CD\u63D0\n\n  \u793A\u4F8B\uFF1A\n    siluzan-tso ad batch list\n    siluzan-tso ad batch get --id <taskId> --config-file ./campaign.json\n    siluzan-tso ad batch get --id <taskId> --json-out"
-  ).requiredOption("--id <id>", "\u8BB0\u5F55 ID\uFF08\u6765\u81EA ad batch list --json-out \u7684 results[].id\uFF09").option("--config-file <path>", "\u672C\u6B21 campaign-create JSON\uFF08\u7ED3\u675F\u540E\u6253\u5370 batch diff \u547D\u4EE4\uFF09").option(
+    "\u83B7\u53D6\u5355\u6761\u8BB0\u5F55/\u8349\u7A3F\u8BE6\u60C5\uFF08\u9ED8\u8BA4\uFF1A\u6458\u8981\u8868 + \u540E\u7AEF\u539F\u59CB reason/errors\uFF1B--json-out \u8F93\u51FA\u5B8C\u6574 JSON\uFF09\n  \u6210\u529F\u6216\u90E8\u5206\u6210\u529F\u540E\u987B\u6267\u884C ad batch diff\uFF08\u89C1 --config-file\uFF09\uFF1BFailed \u4EC5\u770B reason/errors \u540E\u91CD\u63D0\n  --json-out \u843D\u76D8\u542B agentWorkflow.nextCommand / agentHint\uFF08Agent \u5FC5\u8BFB\uFF0C\u52FF\u56E0\u65E9\u9000\u8DF3\u8FC7 diff\uFF09\n\n  \u793A\u4F8B\uFF1A\n    siluzan-tso ad batch list\n    siluzan-tso ad batch get --id <taskId> --config-file ./campaign.json --json-out ./snap-campaign\n"
+  ).requiredOption("--id <id>", "\u8BB0\u5F55 ID\uFF08\u6765\u81EA ad batch list --json-out \u7684 results[].id\uFF09").option(
+    "--config-file <path>",
+    "\u672C\u6B21 campaign-create JSON\uFF08\u5199\u5165 agentWorkflow.nextCommand\uFF1B\u4EBA\u8BFB\u6A21\u5F0F\u4E5F\u6253\u5370 batch diff\uFF09"
+  ).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",
+    "\u843D\u76D8\u5B8C\u6574\u8BB0\u5F55 + agentWorkflow\uFF1B\u76EE\u5F55\u6216 *.json\uFF1Bstdout \u4E00\u884C\u6458\u8981",
     void 0
   ).option("-t, --token <token>", "Auth Token").option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
     async (opts) => {
@@ -119104,7 +119285,7 @@ function register20(program2) {
     }
   );
   adBatchCmd.command("diff").description(
-    "\u6210\u529F\u6216\u90E8\u5206\u6210\u529F\uFF1A\u6309 campaign-create JSON \u4E0E\u8D26\u6237\u5B9E\u51B5\u9010\u5C42\u6BD4\u5BF9\n  Failed \u4E0D\u9002\u7528\uFF08\u7CFB\u5217\u672A\u521B\u5EFA\uFF09\uFF0C\u8BF7\u7528 ad batch get \u67E5\u770B reason/errors \u540E\u6539 JSON \u91CD\u63D0\n\n  \u793A\u4F8B\uFF1A\n    siluzan-tso ad batch diff --campaign-id <id> --config-file ./campaign.json\n    siluzan-tso ad batch diff --batch-id <taskId> --campaign-id <id> --config-file ./campaign.json"
+    "\u6210\u529F\u6216\u90E8\u5206\u6210\u529F\uFF1A\u6309 campaign-create JSON \u4E0E\u8D26\u6237\u5B9E\u51B5\u9010\u5C42\u6BD4\u5BF9\uFF08\u542B\u6295\u653E\u56FD\u5BB6/\u5730\u57DF\uFF09\n  \u6709\u7F3A\u5931\u65F6 exit 2\uFF1B--json-out \u8BFB ok / agentHint / missing[].remediateCommand\uFF08\u542B ad geo add\uFF09\n  Failed \u4E0D\u9002\u7528\uFF08\u7CFB\u5217\u672A\u521B\u5EFA\uFF09\uFF0C\u8BF7\u7528 ad batch get \u67E5\u770B reason/errors \u540E\u6539 JSON \u91CD\u63D0\n\n  \u793A\u4F8B\uFF1A\n    siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json --json-out ./snap-campaign\n    siluzan-tso ad batch diff --campaign-id <id> --config-file ./campaign.json"
   ).requiredOption("--config-file <path>", "\u63D0\u4EA4\u65F6\u4F7F\u7528\u7684 campaign-create JSON").option(
     "--campaign-id <id>",
     "Google \u5E7F\u544A\u7CFB\u5217 ID\uFF08\u53EF\u4ECE ad campaigns --json-out \u83B7\u53D6\uFF1B\u7701\u7565\u65F6\u6309\u7CFB\u5217\u540D\u5339\u914D\uFF09"

package/dist/skill/SKILL.md

@@ -82,7 +82,7 @@ siluzan-tso -h   # 查看帮助
 
 | 用户意图（关键词） | 工作流 | 必读文档 |
 | ------------------ | ------ | -------- |
-| 新建搜索系列 / 出投放方案 / **按 Excel·xlsx·表格投放方案创建广告** / **根据官网·网站·URL 生成 Google 搜索广告** / 搜索广告文案·关键词·**表格** / 写搜索广告计划 | **W3** | `references/google-ads/google-ads-campaign-plan.md` + **`assets/campaign-create-template.json`**（先 Read）+ `assets/campaign-create-template.md`；**有方案文件时必读** `references/google-ads/rules/google-ads-plan-source-fidelity.md`（Agent 写脚本 Excel→campaign JSON + **`ad geo resolve`**，禁止对话手填）；表格交付读 `references/google-ads/rules/google-ads-launch-plan-template.md`。**≠ P8 / ≠ P9 / ≠ W5** |
+| 新建搜索系列 / 出投放方案 / **按 Excel·xlsx·表格投放方案创建广告** / **根据官网·网站·URL 生成 Google 搜索广告** / 搜索广告文案·关键词·**表格** / 写搜索广告计划 | **W3** | `references/google-ads/google-ads-campaign-plan.md` + **`assets/campaign-create-template.json`**（先 Read）+ `assets/campaign-create-template.md`；**有方案文件时必读** `references/google-ads/rules/google-ads-plan-source-fidelity.md`（Agent 写脚本 Excel→campaign JSON + **`ad geo resolve`**；不合规须问「您自己改还是我帮您改」；代改则创建后出 from→to 报告）；表格交付读 `references/google-ads/rules/google-ads-launch-plan-template.md`。**≠ P8 / ≠ P9 / ≠ W5** |
 | 广告系列/组/广告/关键词 CRUD / 拒审 | W3 | `references/google-ads/google-ads.md` |
 | PMax 系列 | W3 | **`assets/pmax-create-template.json`**（先 Read）+ `assets/pmax-create-template.md` + `references/google-ads/pmax-api.md` |
 | AI 智投草稿 list/get/update/publish | W4 | `references/google-ads/google-ads.md`（§ ad batch） |

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.37-beta.6",
-  "publishedAt": 1784087019185
+  "version": "1.1.37-beta.8",
+  "publishedAt": 1784167934152
 }

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

@@ -40,6 +40,8 @@ JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-templa
 | 编造 `targetedLocations[].id` 或对 30 国逐条 `geo search` | **一次** `ad geo resolve --from-file … --json-out`；见 `google-ads-plan-source-fidelity.md` |
 | 对话里手写完整 campaign JSON | Agent **写转换脚本** Excel → `campaign.json`（落盘），再 validate |
 | 方案有 Exact/Phrase，JSON 却一律 `BROAD` | 转换脚本按方案列/词面写入 EXACT/PHRASE/BROAD 分块 |
+| validate 失败后未问用户就改词/消重标题/截断 | **询问**「您自己改还是我帮您改？」；见 `google-ads-plan-source-fidelity.md` § 用户方案不合规 |
+| 代改后只说「创建成功」不交代改了啥 | 创建完成后出报告：创建清单 + **从 xxx→xxx + 原因**（代改时维护变更账本） |
 
 **多词短语（与 `keyword-negative-create` 同类误判）**：`KeywordText` 是 **JSON 字符串数组**，**空格多词完全合法**（如 `"how to make"`、`"home cooking"`）。PHRASE 写 `"\"vegan recipe\""` 或裸词 + `MatchTypeV2: "PHRASE"`（validate 会补引号）。**禁止**因「多词」就省略否词或让用户去 Google Ads 后台手补——那是 Agent 误判，不是 `campaign-create` 限制。
 
@@ -93,7 +95,9 @@ siluzan-tso ad campaign-validate --config-file ./campaign.json
 # 用户确认方案后：
 siluzan-tso ad campaign-create --config-file ./campaign.json --commit '<campaign create description>'
 siluzan-tso ad batch get --id <taskId> --config-file ./campaign.json --json-out ./snap-campaign
+# 读落盘 agentWorkflow.nextCommand（Creating 继续轮询；成功/部分成功 → batch diff）
 siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json --json-out ./snap-campaign
+# 读 ok / missing（含 layer=location 投放国家）；有缺失 exit 2，执行 remediateCommand 后复 diff
 ```
 
 `Creating` 时每 5–10s 轮询 `batch get`，**勿**重复 `campaign-create`。

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

@@ -98,6 +98,8 @@
 
 **报告/Excel 全流程走本 Skill**：按工作流卡片与 `report-templates/*.md` 拉数、落盘、脚本转换；**禁止**加载宿主第三方 xlsx/Excel Skill 代劳（不知 TSO 字段口径与账户核验）。
 
+**写 Excel 时所有 ID 必须是文本（字符串），禁止数字类型**：含 `mediaCustomerId` / `entityId` / `accountId` / `campaignId` / `adGroupId` / `keywordId` / `criterionId` / geo `locationId` 及一切以 `Id`/`ID`/`id` 结尾的标识列。写入前一律 `String(id)`；`exceljs` 设 `numFmt: '@'`（文本），`openpyxl` 写字符串且勿让推断成 number。**禁止**写成 JSON number / Excel 数值单元格（会科学计数法或丢精度，如 `2.77E+09`）。金额、次数、比率等度量字段仍用数字类型。
+
 **中间结果一律落盘**：跨步骤数据不靠对话记忆；Windows 避免管道传 JSON，优先 `--json-out` + `node -e` 读文件。
 
 ---
@@ -122,7 +124,7 @@
   - 当前凭据未返回手机号且用户指定了手机号 → 视同未校验通过，引导重新用手机号登录。
 - **Google 新建搜索系列**：流程在 `references/google-ads/google-ads-campaign-plan.md`；填 JSON 前**必须先 Read** `assets/campaign-create-template.json`，再 Read `assets/campaign-create-template.md`。**禁止**只读 `.md` 手写 JSON。
 - **「根据官网生成 Google 搜索广告 / 表格格式」**：仍属新建搜索系列 → **W3 + 本文件上条**；用户要的「表格」是 `google-ads-launch-plan-template.md` 对 JSON 的投影，**不是**可跳过 JSON/`campaign-validate` 的独立交付物。**禁止**与 P8 网站诊断、P9 市场分析、W5 仅拓词混用。
-- **Excel/表格投放方案 → 创建广告**：必读 `references/google-ads/rules/google-ads-plan-source-fidelity.md`。Agent **写代码**直接转成 campaign-create JSON；地域用 **`ad geo resolve`**；**禁止**对话手填完整 JSON、**禁止**编造 geo id；有方案匹配类型时勿压成一律 BROAD。
+- **Excel/表格投放方案 → 创建广告**：必读 `references/google-ads/rules/google-ads-plan-source-fidelity.md`。Agent **写代码**直接转成 campaign-create JSON；地域用 **`ad geo resolve`**；**禁止**对话手填完整 JSON、**禁止**编造 geo id；有方案匹配类型时勿压成一律 BROAD。**方案不合规时必须询问**：「您自己改还是我帮您改？」——**禁止**未问就静默改用户方案内容后 create。用户选「我帮您改」时：代改同步落盘变更账本；**创建完成后必出报告**（创建了哪些 + 从 xxx→xxx + 原因）。
 - **「行业分析 / 行业分析报告 / 生成 XX 行业报告」**（例：「帮我生成一份电商行业的行业分析报告」）→ **P9 战略市场分析**。**必须**先 `siluzan-tso market-analysis collect … --json-out`，再 WebSearch 补数据、写 `market-report.json`，最后 `market-analysis render` 出 HTML。**禁止**不调用 CLI、仅在对话里用 WebSearch 写 Markdown 充当终稿。**不是** `google-analysis`、**不是** P8 网站诊断。
 - **开户首次响应**：对话内首次进入开户话题时，**必须先**按 `references/accounts/open-account-by-media.md` §「首次响应硬规范」输出**完整必填清单**（未指明媒体则列全平台六表），再收集资料；**禁止**未列清单就执行 `open-account` 或零散追问。
 - **Google 开户**：`open-account google-wizard` 仅限真实 TTY；Agent/自动化用非交互 `open-account google ...`，审核进度用 `account-history`。
@@ -175,7 +177,7 @@
 
 **A · 币种**：首行含 `统计区间：…（货币：CNY|USD）`；全文符号与 `currencyCode` 一致（CNY=￥、USD=$，未混用）；与当次 `list-accounts -k` 结果相同；多账户分币种分表、无跨币种「总计」行。
 
-**B · 结构完整**（对照当次 `report-templates/*.md`）：模板要求的每一章/Sheet 都存在；无整章空白（缺数据章节写 `[ 数据不可用：… ]`，禁止编造数字填坑）；优化建议独立成节、引用当次数字（Meta：4 条建议各 ≥150 字 + 7 维补充；Google 诊断：每模块除表格外有「分析」+「建议」）；Excel 的表头列须能在当次 `*.outline.txt` 找到对应字段、产物内账户 ID = 用户当轮给出的 `mediaCustomerId`。
+**B · 结构完整**（对照当次 `report-templates/*.md`）：模板要求的每一章/Sheet 都存在；无整章空白（缺数据章节写 `[ 数据不可用：… ]`，禁止编造数字填坑）；优化建议独立成节、引用当次数字（Meta：4 条建议各 ≥150 字 + 7 维补充；Google 诊断：每模块除表格外有「分析」+「建议」）；Excel 的表头列须能在当次 `*.outline.txt` 找到对应字段、产物内账户 ID = 用户当轮给出的 `mediaCustomerId`；**Excel 内全部 ID 列为文本**（见上文「写 Excel 时所有 ID 必须是文本」）。
 
 **C · 数字可信**（抽样，不读大 JSON）：总消耗/CPA 数量级与生成过程中脚本 stdout 打印的汇总一致（若无，补跑一次极小 `node -e` 只打印 totals）；账户 ID、区间与用户需求一致；无「示例账户」「占位 123456」等模板残留；表格行数符合预期（如 P3 每个 `-a` ID 占一行）。
 

package/dist/skill/references/core/user-communication-guide.md

@@ -40,7 +40,9 @@
 | ---- | ---- |
 | 查数、诊断、报告、列表 | **先拉数再汇报**；缺账户 ID 才问；缺时间范围按 `agent-conventions.md` §五 处理（能默认则默认并注明区间） |
 | 模糊意图（「帮我看一下」「最近怎么样」） | 选**最可能**的工作流先执行（有 Google 户 → 画像/总览）；结论后附「您是不是还想…」 |
-| **campaign-create 后 Sitelink 等附加信息 batch 失败** | **自动** `ad batch diff` → 执行 `ad extension *` 补建 → 汇报已补挂条数；**勿**反问「需要我现在补上吗？」（用户已确认过 JSON） |
+| **campaign-create 后 Sitelink / 投放国家 batch 漏建** | **自动**读 `batch get` 的 `agentWorkflow` → `ad batch diff` → 执行 `ad geo add` / `ad extension *` 补建 → 汇报已补挂条数；**勿**反问「需要我现在补上吗？」（用户已确认过 JSON） |
+| **用户提供的投放方案（Excel 等）有不合规** | 列出问题 → **二选一询问**：「您自己改方案，还是我帮您改？」→ 停等回复；**禁止**未问就静默改词/标题/删行后直接 create（见 `google-ads-plan-source-fidelity.md`） |
+| **用户选「我帮您改」且广告已创建完成** | **必出报告**：① 创建了哪些；② 修改了哪些（从 xxx → xxx + 原因）。代改时维护变更账本，创建后按账本汇报，勿凭记忆（见同文件 § 创建完成报告） |
 | 写入/删除/充值/开户提交 | **必须先确认**（`agent-conventions.md` §四）；话术用业务语言说明「将要做什么」 |
 | 对象不清且无法推断 | **只问一次**，给 2～3 个选项，不要问卷式连问 |
 

package/dist/skill/references/core/workflows.md

@@ -74,13 +74,13 @@
 - **步骤（Search · 方案文件 → 创建）**：
   1. Read `campaign-create-template.json`；Agent 写转换脚本读 Excel → 写出 `campaign.json`（匹配类型按方案分块）。
   2. `ad geo resolve -a <id> --from-file ./locations.json --json-out ./snap-geo`，把 id 写回 JSON。
-  3. `ad campaign-validate` → 确认摘要（国家↔id + Exact/Phrase/Broad 计数）→ `campaign-create` → `batch get` / `batch diff` / 自动补扩展。
+  3. `ad campaign-validate`；**有不合规 → 询问「您自己改还是我帮您改？」**（见 `google-ads-plan-source-fidelity.md`）→ 确认摘要 → `campaign-create` → `batch get` / `batch diff` / 自动补扩展；若 Agent 代改过 → **创建完成报告**（创建清单 + 从 xxx→xxx + 原因）。
 - **步骤（Search 一体化创建，无现成方案文件）**：
   1. 地域：多国 `ad geo resolve`；单国 `ad geo search -a <id> -q "United States"`（仍禁止编造）。
   2. 门禁：`ad campaign-validate --config-file ./campaign.json`（必跑）。
   3. 用户确认后创建：`ad campaign-create --config-file ./campaign.json`，记录返回 taskId。
-  4. 轮询：`ad batch get --id <taskId>` 直至非 Creating。
-  5. **必做** `ad batch diff`；缺失的附加信息（Sitelink 等）**自动**用 `ad extension *` 补建，勿反问用户（见 `google-ads-campaign-plan.md` § batch diff 后自动补建）。
+  4. 轮询：`ad batch get --id <taskId> --config-file … --json-out …` 直至非 Creating；**读落盘 `agentWorkflow.nextCommand`**（`--json-out` 时人读提示不会出现）。
+  5. **必做** `ad batch diff`（含投放国家）；`ok===false` / exit 2 时按 `missing[].remediateCommand` **自动** `ad geo add` / `ad extension *` 补建，勿反问用户（见 `google-ads-campaign-plan.md` § batch diff 后自动补建）。
   6. 复核：`ad campaigns` / `ad extension list` 确认系列与扩展齐全。
 - **精细管理与日常运营**：`ad adgroup-create` / `ad keyword-create` / `ad keyword-negative-create` / `ad ad-create`（拓词辅助见 **W5**）；调整用 `ad adgroup-status` / `ad campaign-status` / `ad ad-delete` / `ad keyword-negative-delete`。完整参数见 `references/google-ads/google-ads.md`。
 - **交付/确认**：关键词匹配格式 `running shoes`=广泛 / `"..."`=词组 / `[...]`=精确；结构性写操作（新建/暂停/删除）须用户确认；写后用成对读命令复核。

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

@@ -47,12 +47,15 @@
 | 3   | 无方案文件时：多国 **`ad geo resolve`**（或单国 `ad geo search`）写入 `locations` + `targetedLocations`                                                              | **禁止编造 id**                                                                   |
 | 4   | 无方案文件时：按分层写入 `KeywordsForBatchJob`（EXACT/PHRASE/BROAD）；否词进 `NegativeKeywordsForBatchJob`                                                             | 参考 `google-ads-keyword-taxonomy.md`；有方案源则走步骤 0                          |
 | 5   | 得到与模板同构的 `campaign-create` JSON                                                                                                                                | **`assets/campaign-create-template.json`**                                        |
-| 6   | **`ad campaign-validate --config-file <json>`**（失败改中间件/脚本再组装；超长见下文）                                                                                | 下文「校验」                                                                      |
+| 6   | **`ad campaign-validate --config-file <json>`**                                                                                                                      | 下文「校验」                                                                      |
+| 6b  | **方案来自用户且不合规**：列出问题 → **询问**「您自己改还是我帮您改？」→ 按选择处理后再 validate（**禁止**未问就静默改方案）                                         | **`rules/google-ads-plan-source-fidelity.md`** § 用户方案不合规                   |
+| 6c  | 用户选「我帮您改」：改 JSON 时**同步落盘变更账本**（from → to + reason）                                                                                              | 同上 § Agent 代改后：创建完成报告                                                  |
 | 7   | 给人看：**国家↔id** + **匹配类型条数** + 可选 Markdown 投影；**勿**贴整份 JSON 当主交付                                                                               | `google-ads-launch-plan-template.md`                                              |
 | 8   | 用户确认后 **`ad campaign-create`**                                                                                                                                  | `references/google-ads/google-ads.md`                                             |
 | 9   | 每隔5s 获取创建结果                                                                                                                                                  | `ad batch get --id <taskId> --config-file ./campaign.json`                        |
 | 10  | 成功或部分成功后 **`ad batch diff`** 对照 JSON 与账户实况                                                                                                              |                                                                                   |
 | 11  | **自动补建缺失项**（见下文「batch diff 后自动补建」）：附加信息（Sitelink/Callout 等）**直接**执行 `ad extension *`；组/词/RSA 用对应 create 命令。**勿**仅汇报失败并反问用户是否补建 | `references/google-ads/google-ads.md` § batch diff 后自动补建                     |
+| 12  | **若曾由 Agent 代改方案**：出「创建与修改报告」——创建了哪些 + 修改了哪些（从 xxx → xxx + 原因）                                                                   | **`rules/google-ads-plan-source-fidelity.md`** § 创建完成报告                     |
 
 多系列：每系列一个 JSON；可选 `campaign-manifest.json`（`role: brand|competitor|generic`）仅作文件组织参考。
 
@@ -110,8 +113,9 @@ validate 与 create **共用** `runCampaignCreateValidation`：词面规范化 +
 
 1. 使用 **`ad campaign-validate --config-file <json> --json-out <dir>`**（与 create/batch 同一落盘目录），读落盘文件中的 `lengthViolations`（每项含 `path`、`limit`、`actual`、**完整** `text`）。
 2. Agent 将 **全部** 超长条目整理成表（路径、原文、上限、超出量），并为每条给出 **1–2 个改写方案**（保留卖点、符合字符计数；CJK 按 2 计见 `google-ads-compliance.md` §3.2.1）。
-3. **用户确认**选用方案后，Agent **只改 JSON 对应字段**，再执行 `campaign-validate`；通过后再 `campaign-create`。
-4. **禁止**：未确认前 `slice`/省略号截断、仅改 `--write-normalized` 而不经用户确认。
+3. **方案来自用户时**：先按 `google-ads-plan-source-fidelity.md` 询问「您自己改还是我帮您改？」；选「我帮您改」并确认改写方案后，再改 JSON。
+4. **用户确认**选用方案后，Agent **只改 JSON 对应字段**，再执行 `campaign-validate`；通过后再 `campaign-create`。
+5. **禁止**：未确认前 `slice`/省略号截断、仅改 `--write-normalized` 而不经用户确认。
 
 人读模式失败时 CLI 会额外打印「📏 超长内容清单」；`--json-out` 时见 `lengthViolations` + `agentHint`。
 
@@ -119,18 +123,20 @@ validate 与 create **共用** `runCampaignCreateValidation`：词面规范化 +
 
 ## batch diff 后自动补建（Agent 必遵）
 
-`campaign-create` BatchJob **常漏附加信息**（尤其 Sitelink）；系列/组/关键词/RSA 已创建成功时，**不要**停在「需要我现在补上吗？」——用户确认 JSON 时已包含这些内容，Agent **应自动补建**。
+`campaign-create` BatchJob **常漏附加信息**（Sitelink）与 **投放国家**；系列/组/关键词/RSA 已创建成功时，**不要**停在「需要我现在补上吗？」——用户确认 JSON 时已包含这些内容，Agent **应自动补建**。
 
 | 步骤 | 动作 |
 | ---- | ---- |
-| 1 | `ad batch get` 直至 `Successfully` 或 `HasFailed`（Creating 时每 5s 轮询） |
-| 2 | `ad batch diff --batch-id <taskId> --config-file ./campaign.json [--campaign-id <id>]` |
-| 3 | 读缺失明细（或 `--json-out` 落盘中的 `missing[]`）；每条 `extension` 层若有 `remediateCommand`，**直接执行** |
-| 4 | 无 `remediateCommand` 时，按 JSON 路径与 `google-ads.md` § 批量创建工作流 映射为 `ad extension sitelink` / `callout` / `call` / `snippet` |
-| 5 | 缺组/词/RSA/否词：用 `ad adgroup-create` / `keyword-create` / `ad-create` / `keyword-negative-create` 补建（补建前 `ad extension list` 等核对，避免重复） |
-| 6 | 全部补建后再 `ad batch diff` 或 `ad extension list --campaign-id <id>` 复核；汇总告诉用户「已自动补上 N 条 Sitelink」 |
+| 1 | `ad batch get --id <taskId> --config-file ./campaign.json --json-out ./snap-campaign` 直至终端态（Creating 时每 5s 轮询；**读落盘 `agentWorkflow.nextCommand`**，勿只看人读提示） |
+| 2 | `Successfully` / `HasFailed`：执行 `agentWorkflow.nextCommand`（即 `ad batch diff … --json-out`）；**Failed** 勿 diff |
+| 3 | 读落盘 `ok` / `missing[]`；`layer=location` → 执行 `ad geo add`；`layer=extension` → 执行 `remediateCommand` |
+| 4 | 无 `remediateCommand` 时，按 JSON 路径映射 `ad extension *` / `adgroup-create` / `keyword-create` / `ad-create` / `keyword-negative-create` |
+| 5 | 有缺失时 CLI **exit 2**；补建后再 `ad batch diff`，直到 `ok===true`（含 `counts.liveLocations === plannedLocations`） |
+| 6 | 汇总告诉用户「已自动补上 N 个投放国家 / M 条 Sitelink」 |
 | 7 | 仅当补建命令也失败时，才向用户说明原因并给改写方案 |
 
+**Agent 易漏点**：`--json-out` 时人读「下一步」不会打印——**必须以落盘 `agentWorkflow` 为准**；`campaign-create` 落盘同样带 `agentWorkflow.nextCommand`（首轮 `batch get`）。
+
 **Sitelink 单条示例**（字段来自 `ExtensionsForBatchJob[i].Properties`）：
 
 ```bash

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

@@ -357,12 +357,13 @@ siluzan-tso keyword geo-list [--country-code <US,CN,...>] [--name-contains <text
 #    - 广告组在 campaign.AdGroupsForBatchJob 数组中
 siluzan-tso ad campaign-create --config-file ./campaign.json
 
-# 2. 查异步任务（Creating 时每 5–10s 轮询，直至非 Creating）
-siluzan-tso ad batch get --id <taskId> --config-file ./campaign.json
+# 2. 查异步任务（Creating 时每 5–10s 轮询，直至非 Creating；Agent 几乎总带 --json-out）
+siluzan-tso ad batch get --id <taskId> --config-file ./campaign.json --json-out ./snap-campaign
+# 读落盘 agentWorkflow：Creating → 继续 nextCommand；Successfully/HasFailed → 执行 nextCommand（batch diff）
 
-# 3. 成功或部分成功后必做比对
-siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json
-# 可选：--campaign-id <id>（ad campaigns -a <accountId> --json-out ./snap；省略时按系列名自动匹配）
+# 3. 成功或部分成功后必做比对（含投放国家；有缺失 exit 2）
+siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json --json-out ./snap-campaign
+# 读 ok / missing[].remediateCommand（地域 → ad geo add；扩展 → ad extension *）
 
 # Failed：系列未创建，无需 diff；根据 get 的 reason/errors 改 JSON 后重提
 # siluzan-tso ad campaign-create --config-file ./campaign.json
@@ -372,10 +373,10 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json
 
 | `status`       | 含义     | 做法                                                                                                   |
 | -------------- | -------- | ------------------------------------------------------------------------------------------------------ |
-| `Creating`     | 仍在执行 | 继续 `ad batch get`，勿重复 `campaign-create`                                                          |
-| `Successfully` | 全部成功 | **须** `ad batch diff` 核对计划与账户一致（无缺失应 ✅）                                               |
+| `Creating`     | 仍在执行 | 继续 `ad batch get`（带同一 `--config-file` + `--json-out`），读 `agentWorkflow`，勿重复 `campaign-create` |
+| `Successfully` | 全部成功 | **须** `ad batch diff`（含投放国家）；`--json-out` 时 `ok===true` 才算齐                                 |
 | `Failed`       | 全部失败 | `ad batch get` 读 `reason`/`errors` → **只改 JSON** → 再 `ad campaign-create`（**不要** `batch diff`） |
-| `HasFailed`    | 部分成功 | **须** `ad batch diff` 列出缺失 → 分步补建或删系列重提                                                 |
+| `HasFailed`    | 部分成功 | **须** `ad batch diff` 列出缺失 → 分步补建或删系列重提（`ok===false` / exit 2）                          |
 
 **`HasFailed` 分支：**
 
@@ -386,24 +387,25 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json
    - 缺组：`ad adgroup-create`（`--json-out` 取 `id`）
    - 缺词：`ad keyword-create`（词面格式同 JSON `KeywordsForBatchJob`）
    - 缺 RSA：`ad ad-create`（`--headlines` / `--descriptions` 从 JSON `AdsForBatchJob` 抄）
+   - **缺投放国家/地域**：**自动**执行 `ad geo add -a <account> --campaign-id <id> --location-id <geoId>`（`layer=location` 的 `remediateCommand`）
    - **缺附加信息（常见）**：**自动**执行 `ad extension sitelink` / `callout` / `call` / `snippet`（见下节）；`batch diff` 输出含 `补建:` 行或 `--json-out` 的 `missing[].remediateCommand`  
-     补建前可用 `ad groups` / `ad keywords` / `ad extension list` 核对账户现状。
+     补建前可用 `ad groups` / `ad keywords` / `ad geo list --mode targeted` / `ad extension list` 核对账户现状。
 
-### batch diff 后自动补建附加信息（Agent 必遵）
+### batch diff 后自动补建（Agent 必遵）
 
-BatchJob 中 `ExtensionsForBatchJob`（尤其 **Sitelink**）失败率较高，但系列/组/词/RSA 往往已成功。用户确认创建时已认可 JSON 内全部附加信息 → Agent **须直接补建**，**禁止**仅汇报「Sitelink 未创建，需要我现在补上吗？」。
+BatchJob 常漏 **附加信息**（Sitelink）与 **投放地域**；系列/组/词/RSA 往往已成功。用户确认创建时已认可 JSON → Agent **须直接补建**，**禁止**仅汇报「未创建，需要我现在补上吗？」。
 
-1. 跑 `ad batch diff`；对 `layer=extension` 的缺失项执行输出中的 **`补建:`** 命令（或读落盘 `missing[].remediateCommand`）。
-2. 字段映射：`Properties.Text` + `DestinationUrl` → `ad extension sitelink`；`CALLOUT` → `callout`；`CALL` → `call`；`STRUCTURED_SNIPPET` → `snippet`（`StructuredSnippetHeaderValue`）。
-3. 系列级统一 `--level Campaign --campaign-id <id>`；每条 `--json-out ./snap`。
-4. 补建完成后 `ad extension list -a <accountId> --campaign-id <id> --type SITELINK` 复核条数。
-5. 向用户汇报：「系列已创建；Sitelink 等 X 条已通过单独命令补挂完成」（附系列 ID 与条数即可）。
+1. `ad campaign-create` / `ad batch get` 的 `--json-out` 落盘含 **`agentWorkflow`**：读 `nextCommand` / `shouldRunBatchDiff` / `agentHint`（人读提示在 `--json-out` 早退时不可见）。
+2. 跑 `ad batch diff`；对 `missing[]` 中带 `remediateCommand` 的项**直接执行**（`location` → `ad geo add`；`extension` → `ad extension *`）。
+3. 扩展字段映射：`Properties.Text` + `DestinationUrl` → `ad extension sitelink`；`CALLOUT` → `callout`；`CALL` → `call`；`STRUCTURED_SNIPPET` → `snippet`。
+4. 有缺失时 CLI **exit 2**；补建后再跑一次 `ad batch diff`，直到 `ok===true`。
+5. 向用户汇报已补挂条数（地域 + Sitelink 等）。
 
 完整流水线见 `references/google-ads/google-ads-campaign-plan.md` § batch diff 后自动补建。
 
-**`ad batch diff` 比对维度：**系列是否存在 → 各 `AdGroupsForBatchJob[].Name` → 组内关键词（匹配类型+词面）→ RSA 首条标题 → 系列否定词 → 附加信息条数。默认按层级树状输出每条缺失的 **JSON 路径 + 计划内容 + 账户实况**；`--json-out` 可落盘完整结构。
+**`ad batch diff` 比对维度：**系列是否存在 → **`targetedLocations`（投放国家/地域 id）** → 各 `AdGroupsForBatchJob[].Name` → 组内关键词（匹配类型+词面）→ RSA 首条标题 → 系列否定词 → 附加信息条数。`--json-out` 含 `ok` / `agentHint` / `counts.plannedLocations|liveLocations`。
 
-**`ad batch get` 输出：**摘要表 + 后端原始 `reason` + 完整 `errors`（或 `--json-out` 整条记录）。
+**`ad batch get` 输出：**摘要表 + `reason`/`errors`；`--json-out` 另含 **`agentWorkflow`**（`nextCommand` 指向 batch diff 或继续轮询）。
 
 **CLI 在提交前只做三件事：**
 

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

@@ -9,7 +9,7 @@
 | `google-ads-keyword-strategy.md`                    | 关键词策略规划                                         |
 | `google-ads-keyword-optimization.md`                | 关键词出价/否定/扩词优化                               |
 | `google-ads-keyword-taxonomy.md`                    | 词类分层与命名                                         |
-| `google-ads-plan-source-fidelity.md`                | **Excel/表格方案 → JSON**：Agent 写脚本直转 + `ad geo resolve`（有方案文件时必读） |
+| `google-ads-plan-source-fidelity.md`                | **Excel/表格方案 → JSON**：Agent 写脚本直转 + `ad geo resolve`；不合规须问「自己改 / 帮您改」（有方案文件时必读） |
 | `google-ads-creative-optimization.md`               | 创意/文案优化                                          |
 | `google-ads-audience-strategy.md`                   | 受众策略                                               |
 | `google-ads-pmax-guide.md`                          | PMax 运营指南（配合 `assets/pmax-create-template.md`） |

package/dist/skill/references/google-ads/rules/google-ads-plan-source-fidelity.md

@@ -19,17 +19,87 @@
    campaign.json  （campaign-create 契约）
         │
         ▼
- ad campaign-validate → 确认摘要 → ad campaign-create
+ ad campaign-validate
+        │
+        ├─ 有不合规 → 【必问】用户自己改，还是 Agent 代改？（见下文）
+        │
+        └─ 通过 → 确认摘要 → ad campaign-create
 ```
 
 | 步 | 谁做 | 动作 |
 | -- | ---- | ---- |
-| 1 | Agent + 脚本 | 读全 Sheet，按语义抽出预算/组/词+匹配类型/RSA/否词/国家等，写出 `campaign.json` |
+| 1 | Agent + 脚本 | 读全 Sheet，按语义抽出预算/组/词+匹配类型/RSA/否词/国家等，写出 `campaign.json`（**先忠实落盘，勿静默改用户方案**） |
 | 2 | CLI | 国家列表 → `ad geo resolve -a <id> --from-file … --json-out …`，把返回的 `locations` / `targetedLocations` 写入 JSON（**禁止**编造 id） |
 | 3 | CLI | `ad campaign-validate --config-file ./campaign.json` |
+| 3b | Agent → 用户 | **若有不合规**：列出问题清单 → **询问**「您自己改方案/文件，还是我帮您改？」→ 按用户选择处理后再 validate（见下节） |
 | 4 | Agent → 用户 | 摘要确认：国家↔id、Exact/Phrase/Broad 条数（可抽样几条），**勿**贴整份 JSON |
 | 5 | CLI | 用户确认后 `ad campaign-create` → `batch get` / `batch diff` |
 
+---
+
+## 用户方案不合规时：必须二选一询问（Agent 必遵）
+
+**适用**：计划来源是用户提供的（Excel / 表格 / 粘贴方案 / 用户自写的 JSON），且出现下列任一情况：
+
+| 类型 | 示例 |
+| ---- | ---- |
+| `campaign-validate` error / warning | 词面非法字符、嵌套引号、RSA 跨组标题重复、超长、匹配类型与符号不一致、locations 数量不一致等 |
+| 政策 / 合规明显风险 | 违禁宣称、落地页与文案严重不符等（见 `google-ads-compliance.md`） |
+| 转换时发现方案自相矛盾 | 同组同词多匹配类型冲突、必填块缺失等 |
+
+**禁止**：未询问就替用户改方案内容（改词面、改标题消重、截断、删词、改匹配类型等）然后直接 create。  
+**禁止**：只丢一句「校验失败」就停住，不给选项。
+
+**必做话术结构**（业务语言，勿贴整段 CLI）：
+
+1. 说明：方案里有 **N 处**不合规（可表格：位置 / 原文要点 / 原因）。
+2. **明确二选一**（一次问清）：
+   - **A. 您自己改**：改 Excel/原文后发我，或告诉我改哪几处；我再重新转换/校验。
+   - **B. 我帮您改**：您同意后，我按建议改 `campaign.json`，再 validate → 请您确认 → create；**创建完成后必须出「创建与修改报告」**（见下节）。
+3. **停等用户回复**；选 B 时再动手改；选 A 时不要擅自改 JSON。
+4. **选 B 时立刻落盘变更账本**（见下节「变更账本」）：每改一处就记一行「原值 → 新值 + 原因」，勿等创建完再凭记忆补写。
+
+**例外（仍可静默做，不算「改方案」，也不进修改报告主表）**：`ad geo resolve` 取地域 id、剥 `_` 注解键、提交前金额元→分——这些是契约/网关要求，不是改用户业务内容。
+
+**与「创建后自动补建」的区别**：用户已确认过 JSON 并 `campaign-create` 之后，BatchJob 漏掉的 Sitelink/地域用 `batch diff` **自动补建**（见 `google-ads-campaign-plan.md`）；那是执行层补洞，不是改用户方案。不合规询问发生在 **create 之前**。补建条数可写在报告「创建结果」里，但**不要**混进「相对原方案的修改」表。
+
+---
+
+## Agent 代改后：创建完成报告（必出）
+
+**何时必出**：用户选择「我帮您改」且最终完成了 `campaign-create`（含 batch get / batch diff / 必要补建）之后。  
+**何时不必出完整修改表**：用户全程自己改方案、Agent 未改业务内容——只需常规创建结果摘要。
+
+### 变更账本（代改过程中维护）
+
+落盘建议：`./snap-campaign/plan-edits.json`（或同目录 Markdown）。每条至少：
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `path` | JSON 路径或业务位置（如组名 + 关键词 / RSA 标题序号） |
+| `from` | 用户原方案中的值（改前） |
+| `to` | 实际写入并创建的值（改后） |
+| `reason` | 修改原因（对应哪条 validate/合规规则，一句话） |
+
+**禁止**：创建结束后凭印象写「改了一些标题」；必须以账本为准。
+
+### 面向用户的报告结构（业务语言）
+
+创建与核对结束后，用一份短报告回复用户，至少含三块：
+
+1. **创建了哪些**  
+   账户 ID/名称、系列名与 `campaignId`、广告组数、关键词数（可附 Exact/Phrase/Broad）、否词数、投放国家数、RSA/附加信息条数；batch 状态；若有自动补建（Sitelink/地域等）写明补了几条。
+
+2. **修改了哪些（相对您的原方案）**  
+   表格逐条：**位置 | 从（原值） | 改成（新值） | 原因**。  
+   - `from` / `to` 写清原文，勿只写「已优化」。  
+   - 无修改则写「相对您的原方案无业务内容修改」（仅 geo id 解析等不写进此表）。
+
+3. **未改动的说明（可选一句）**  
+   如：匹配类型/国家列表按您的方案保留。
+
+**禁止**：只说「已创建成功」而不交代代改明细；**禁止**把创建结果与修改混成一团让用户自己猜改了啥。
+
 可选脚手架（非必须）：`assets/plan-extract.example.json` + `assets/scripts/assemble-campaign-from-plan.mjs`——若 Agent 更习惯先抽中间件再组装，可以用；**不强制**。
 
 ---

package/dist/skill/references/report-templates/REPORT-WORKFLOW.md

@@ -50,6 +50,11 @@
 2. Read 本次每个 section 的 **`*.outline.txt`**（见 `google-period-report-excel.md` §执行门禁）。
 3. **禁止** `cat|json.tool|head` 或 Read 业务 `*.json` 探字段；**禁止**加载宿主第三方 xlsx Skill。
 
+### 写 xlsx 硬规则（全报告类型共用）
+
+- **所有 ID 列必须写成字符串（文本）**，禁止 Excel 数字类型：`mediaCustomerId` / `campaignId` / `adGroupId` / `keywordId` / geo id 等一律 `String(...)`；`exceljs` 用 `numFmt: '@'`，`openpyxl` 写 str。详见 `references/core/agent-conventions.md`。
+- 金额、次数、比率等度量字段仍用数字类型。
+
 ### 步骤 4：拉取数据
 
 - **`google-analysis` / `facebook-analysis` / `tiktok-analysis` / `bing-analysis` / `report …` 账户分析子命令**：统一 **`--json-out <目录>`** 落盘，再由脚本读 **`manifest-<accountId>.json` / `report-manifest-<accountId>.json`**（清单文件名见 stdout 摘要的 `manifestFile`）与各 **`<section>-<accountId>.json`**（见 `references/analytics/account-analytics.md`）。

package/dist/skill/references/report-templates/google-inquiry-analysis.md

@@ -187,6 +187,7 @@ Sheet 5 整段系列明细读：`./snap-inquiry/campaigns-<accountId>_<S>-<E>.js
 
 - **金额、CPL / CPA / CPC / 平均费用**：保留 **2 位小数**，写明货币代码（如 `¥123.45 CNY`）。
 - **点击率 / 转化率 / 互动率**（`ctr` / `conversionRate` / `interactionRate`）：CLI 已归一为 **0~1 小数**（schemaVersion ≥ 2），写入 Excel 时**直接写 0~1**（与运营样表对齐，Excel 单元格用百分比格式自动渲染）。话术 `x%` 用 `(v * 100).toFixed(2) + "%"`。
+- **所有 ID**：账户 / 系列 / 组 / 关键词 / 地域等 id **一律字符串（文本单元格）**，`String(id)` + `numFmt: '@'`（或 openpyxl 写 str）；**禁止**数字类型（防科学计数法）。见 `agent-conventions.md`。
 - **空值**：`interactions === 0` 时「平均费用」「互动率」填 `—`，**禁止**除零。
 
 ### 分析输出区位置（**全局硬约束**）

package/dist/skill/references/report-templates/google-period-report-excel.md

@@ -101,7 +101,8 @@ siluzan-tso google-analysis -a <id> --start <S> --end <E> --json-out ./snap-p4 \
 2. **首行或 R2** 含统计区间 + 币种（与 `list-accounts` 一致）。
 3. **列表 Sheet**：R1 为表头；列名与 outline 字段含义对应，不造 outline 中不存在的列。
 4. **数值**：金额 2 位小数；`ctr`/`conversionRate` 按上文 0~1 口径；禁止对 JSON 比率再 ÷100。
-5. 某维度拉数失败：该 Sheet 写 `[ 数据不可用：<原因> ]`，禁止留空或编造。
+5. **所有 ID 列写字符串（文本）**：账户/系列/组/关键词/地域等 id 用 `String(id)` + 文本格式（`exceljs` `numFmt: '@'`）；**禁止**写成数字（防科学计数法/丢精度）。见 `agent-conventions.md`。
+6. 某维度拉数失败：该 Sheet 写 `[ 数据不可用：<原因> ]`，禁止留空或编造。
 
 有 OKKI 固定话术时改走 **P6**（`okki-weekly-google-client.md`），**不**用本文。
 
@@ -114,6 +115,7 @@ siluzan-tso google-analysis -a <id> --start <S> --end <E> --json-out ./snap-p4 \
 - [ ] `google-analysis` 的 `accountId`（stdout 摘要）= 用户要求的 `mediaCustomerId`
 - [ ] 每个 Sheet 列均能在对应 `*.outline.txt` 中找到字段源
 - [ ] 脚本 stdout 打印的 `itemCount` 与 Excel 数据行数一致（±合计行）
+- [ ] 全部 ID 列为文本（非数字类型 / 无科学计数法）
 - [ ] 未使用第三方 xlsx Skill 替代本 Skill 拉数与字段口径
 
 ---

package/dist/skill/references/report-templates/meta-period-report-excel.md

@@ -5,6 +5,8 @@
 
 > 对照业务交付物：`无锡顺晟Facebook4月报告.xlsx`（5 个 Sheet）。  
 > Excel 流程：CLI 拉数 → Agent 分析并写 `meta-period-report.json` → **Agent 脚本**按本规格写 `.xlsx`（**无** CLI 内置 excel 子命令）。
+>
+> **ID 列硬规则**：账户 / 系列 / 广告组 / 广告等 id **一律写成字符串（文本）**，禁止 Excel 数字类型；见 `references/core/agent-conventions.md`。
 
 ---
 

package/dist/skill/references/report-templates/okki-weekly-google-client.md

@@ -24,6 +24,7 @@
 - **`siluzan-tso` 不提供**「一键生成 OKKI Excel」的子命令，**也不要**在 CLI 里新增。
 - 需交付 Excel 时：由 **Agent（含 WorkBuddy 编排）** 在下列 CLI **`--json-out` 落盘后**，自行编写 **Node.js / Python** 脚本（如 `exceljs`、`xlsx`、`openpyxl`）读取 JSON → 写 `.xlsx`。
 - **数值一律来自落盘 JSON，禁止在脚本里写死业务数字。**
+- **所有 ID 列写字符串（文本）**，禁止 Excel 数字类型（防科学计数法）；见 `references/core/agent-conventions.md`。
 
 ---
 

package/dist/skill/report-templates/REPORT-WORKFLOW.md

@@ -50,6 +50,11 @@
 2. Read 本次每个 section 的 **`*.outline.txt`**（见 `google-period-report-excel.md` §执行门禁）。
 3. **禁止** `cat|json.tool|head` 或 Read 业务 `*.json` 探字段；**禁止**加载宿主第三方 xlsx Skill。
 
+### 写 xlsx 硬规则（全报告类型共用）
+
+- **所有 ID 列必须写成字符串（文本）**，禁止 Excel 数字类型：`mediaCustomerId` / `campaignId` / `adGroupId` / `keywordId` / geo id 等一律 `String(...)`；`exceljs` 用 `numFmt: '@'`，`openpyxl` 写 str。详见 `references/core/agent-conventions.md`。
+- 金额、次数、比率等度量字段仍用数字类型。
+
 ### 步骤 4：拉取数据
 
 - **`google-analysis` / `facebook-analysis` / `tiktok-analysis` / `bing-analysis` / `report …` 账户分析子命令**：统一 **`--json-out <目录>`** 落盘，再由脚本读 **`manifest-<accountId>.json` / `report-manifest-<accountId>.json`**（清单文件名见 stdout 摘要的 `manifestFile`）与各 **`<section>-<accountId>.json`**（见 `references/analytics/account-analytics.md`）。

package/dist/skill/report-templates/google-inquiry-analysis.md

@@ -187,6 +187,7 @@ Sheet 5 整段系列明细读：`./snap-inquiry/campaigns-<accountId>_<S>-<E>.js
 
 - **金额、CPL / CPA / CPC / 平均费用**：保留 **2 位小数**，写明货币代码（如 `¥123.45 CNY`）。
 - **点击率 / 转化率 / 互动率**（`ctr` / `conversionRate` / `interactionRate`）：CLI 已归一为 **0~1 小数**（schemaVersion ≥ 2），写入 Excel 时**直接写 0~1**（与运营样表对齐，Excel 单元格用百分比格式自动渲染）。话术 `x%` 用 `(v * 100).toFixed(2) + "%"`。
+- **所有 ID**：账户 / 系列 / 组 / 关键词 / 地域等 id **一律字符串（文本单元格）**，`String(id)` + `numFmt: '@'`（或 openpyxl 写 str）；**禁止**数字类型（防科学计数法）。见 `agent-conventions.md`。
 - **空值**：`interactions === 0` 时「平均费用」「互动率」填 `—`，**禁止**除零。
 
 ### 分析输出区位置（**全局硬约束**）

package/dist/skill/report-templates/google-period-report-excel.md

@@ -101,7 +101,8 @@ siluzan-tso google-analysis -a <id> --start <S> --end <E> --json-out ./snap-p4 \
 2. **首行或 R2** 含统计区间 + 币种（与 `list-accounts` 一致）。
 3. **列表 Sheet**：R1 为表头；列名与 outline 字段含义对应，不造 outline 中不存在的列。
 4. **数值**：金额 2 位小数；`ctr`/`conversionRate` 按上文 0~1 口径；禁止对 JSON 比率再 ÷100。
-5. 某维度拉数失败：该 Sheet 写 `[ 数据不可用：<原因> ]`，禁止留空或编造。
+5. **所有 ID 列写字符串（文本）**：账户/系列/组/关键词/地域等 id 用 `String(id)` + 文本格式（`exceljs` `numFmt: '@'`）；**禁止**写成数字（防科学计数法/丢精度）。见 `agent-conventions.md`。
+6. 某维度拉数失败：该 Sheet 写 `[ 数据不可用：<原因> ]`，禁止留空或编造。
 
 有 OKKI 固定话术时改走 **P6**（`okki-weekly-google-client.md`），**不**用本文。
 
@@ -114,6 +115,7 @@ siluzan-tso google-analysis -a <id> --start <S> --end <E> --json-out ./snap-p4 \
 - [ ] `google-analysis` 的 `accountId`（stdout 摘要）= 用户要求的 `mediaCustomerId`
 - [ ] 每个 Sheet 列均能在对应 `*.outline.txt` 中找到字段源
 - [ ] 脚本 stdout 打印的 `itemCount` 与 Excel 数据行数一致（±合计行）
+- [ ] 全部 ID 列为文本（非数字类型 / 无科学计数法）
 - [ ] 未使用第三方 xlsx Skill 替代本 Skill 拉数与字段口径
 
 ---

package/dist/skill/report-templates/meta-period-report-excel.md

@@ -5,6 +5,8 @@
 
 > 对照业务交付物：`无锡顺晟Facebook4月报告.xlsx`（5 个 Sheet）。  
 > Excel 流程：CLI 拉数 → Agent 分析并写 `meta-period-report.json` → **Agent 脚本**按本规格写 `.xlsx`（**无** CLI 内置 excel 子命令）。
+>
+> **ID 列硬规则**：账户 / 系列 / 广告组 / 广告等 id **一律写成字符串（文本）**，禁止 Excel 数字类型；见 `references/core/agent-conventions.md`。
 
 ---
 

package/dist/skill/report-templates/okki-weekly-google-client.md

@@ -24,6 +24,7 @@
 - **`siluzan-tso` 不提供**「一键生成 OKKI Excel」的子命令，**也不要**在 CLI 里新增。
 - 需交付 Excel 时：由 **Agent（含 WorkBuddy 编排）** 在下列 CLI **`--json-out` 落盘后**，自行编写 **Node.js / Python** 脚本（如 `exceljs`、`xlsx`、`openpyxl`）读取 JSON → 写 `.xlsx`。
 - **数值一律来自落盘 JSON，禁止在脚本里写死业务数字。**
+- **所有 ID 列写字符串（文本）**，禁止 Excel 数字类型（防科学计数法）；见 `references/core/agent-conventions.md`。
 
 ---
 

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.37-beta.6'
+$PKG_VERSION = '1.1.37-beta.8'
 $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.37-beta.6"
+readonly PKG_VERSION="1.1.37-beta.8"
 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.37-beta.6",
+  "version": "1.1.37-beta.8",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",