siluzan-tso-cli 1.1.37-beta.2 → 1.1.37-beta.4

package/README.md

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

package/dist/index.js

@@ -110511,6 +110511,7 @@ function validateCampaignExtensionsForBatchJob(campaign, errors, warnings, lengt
 
 // src/commands/ad/keyword.ts
 init_auth();
+import { readFileSync as readFileSync4 } from "fs";
 init_cli_json_snapshot();
 init_strip_legacy_google_fields();
 init_cli_table();
@@ -110539,6 +110540,68 @@ function formatKeywordTextForMatchType(rawCoreOrDisplay, matchType) {
     }
   }
 }
+function parseKeywordsCsv(raw) {
+  const out = [];
+  let cur = "";
+  let inDouble = false;
+  let inBracket = false;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === '"' && !inBracket) {
+      inDouble = !inDouble;
+      cur += ch;
+      continue;
+    }
+    if (ch === "[" && !inDouble && !inBracket) {
+      inBracket = true;
+      cur += ch;
+      continue;
+    }
+    if (ch === "]" && inBracket) {
+      inBracket = false;
+      cur += ch;
+      continue;
+    }
+    if (ch === "," && !inDouble && !inBracket) {
+      const t = cur.trim();
+      if (t) out.push(t);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  const last = cur.trim();
+  if (last) out.push(last);
+  return out;
+}
+function loadKeywordsFromFile(filePath) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync4(filePath, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `\u8BFB\u53D6\u5173\u952E\u8BCD\u6587\u4EF6\u5931\u8D25\uFF08${filePath}\uFF09\uFF1A${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new Error(`\u5173\u952E\u8BCD\u6587\u4EF6\u987B\u4E3A\u975E\u7A7A JSON \u5B57\u7B26\u4E32\u6570\u7EC4\uFF1A${filePath}`);
+  }
+  const list = raw.map((x) => typeof x === "string" ? x.trim() : "").filter((s) => s.length > 0);
+  if (list.length === 0) {
+    throw new Error(`\u5173\u952E\u8BCD\u6587\u4EF6\u65E0\u6709\u6548\u5B57\u7B26\u4E32\uFF1A${filePath}`);
+  }
+  return list;
+}
+function resolveKeywordTexts(opts) {
+  const fromCsv = opts.keywords?.length ? opts.keywords : [];
+  const fromFile = opts.keywordsFile ? loadKeywordsFromFile(opts.keywordsFile) : [];
+  const merged = [...fromCsv, ...fromFile];
+  if (merged.length === 0) {
+    throw new Error("\u8BF7\u4F20 --keywords \u548C/\u6216 --keywords-file\uFF08\u591A\u8BCD\u77ED\u8BED\u76F4\u63A5\u5199\u7A7A\u683C\u5373\u53EF\uFF0C\u5982 how to make\uFF09");
+  }
+  if (!opts.matchType) return merged;
+  return merged.map((k) => formatKeywordTextForMatchType(k, opts.matchType));
+}
 function firstKeywordTextFromRecord(k) {
   const kt = k["keywordText"];
   if (Array.isArray(kt) && kt.length > 0 && typeof kt[0] === "string") {
@@ -110661,8 +110724,21 @@ ${label}\uFF08\u8D26\u6237\uFF1A${opts.account}\uFF0C\u7B2C 1 \u9875\uFF0C\u672C
 async function runAdKeywordCreate(opts) {
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
+  let keywords;
+  try {
+    keywords = resolveKeywordTexts({
+      keywords: opts.keywords,
+      keywordsFile: opts.keywordsFile,
+      matchType: opts.matchType
+    });
+  } catch (err) {
+    console.error(`
+\u274C ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
   const body = {
-    KeywordText: opts.keywords,
+    KeywordText: keywords,
     FinalUrl: opts.finalUrl ?? "",
     AdGroup: opts.adgroupName,
     AdGroupId: opts.adgroupId,
@@ -110688,20 +110764,33 @@ async function runAdKeywordCreate(opts) {
     section: `ad-keyword-create-${opts.account}-${opts.adgroupId}`,
     commandLabel: "ad keyword-create",
     commandHint: `${opts.account}:${opts.adgroupId}`,
-    payload: { request: { adgroupId: opts.adgroupId, count: opts.keywords.length }, response },
+    payload: { request: { adgroupId: opts.adgroupId, count: keywords.length }, response },
     idSuffix: `${opts.account}-${opts.adgroupId}`
   })) {
     return;
   }
   console.log(`
-\u2705 \u5DF2\u6DFB\u52A0 ${opts.keywords.length} \u4E2A\u5173\u952E\u8BCD\u5230\u5E7F\u544A\u7EC4\u300C${opts.adgroupName}\u300D
+\u2705 \u5DF2\u6DFB\u52A0 ${keywords.length} \u4E2A\u5173\u952E\u8BCD\u5230\u5E7F\u544A\u7EC4\u300C${opts.adgroupName}\u300D
 `);
 }
 async function runAdNegativeKeywordCreate(opts) {
   const config = loadConfig(opts.token);
   const googleApiUrl = requireGoogleApi(config);
+  let keywords;
+  try {
+    keywords = resolveKeywordTexts({
+      keywords: opts.keywords,
+      keywordsFile: opts.keywordsFile,
+      matchType: opts.matchType
+    });
+  } catch (err) {
+    console.error(`
+\u274C ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
   const body = {
-    KeywordText: opts.keywords,
+    KeywordText: keywords,
     CampaignId: opts.campaignId,
     Campaign: opts.campaignName
   };
@@ -110720,7 +110809,7 @@ async function runAdNegativeKeywordCreate(opts) {
     process.exit(1);
   }
   console.log(`
-\u2705 \u5DF2\u5728${level}\u5C42\u7EA7\u6DFB\u52A0 ${opts.keywords.length} \u4E2A\u5426\u5B9A\u5173\u952E\u8BCD
+\u2705 \u5DF2\u5728${level}\u5C42\u7EA7\u6DFB\u52A0 ${keywords.length} \u4E2A\u5426\u5B9A\u5173\u952E\u8BCD
 `);
 }
 async function runAdKeywordDelete(opts) {
@@ -111957,7 +112046,7 @@ function runCampaignCreateValidation(cfg) {
 }
 
 // src/commands/ad/campaign-load.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 function stripMetaKeys(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripMetaKeys(item));
@@ -111988,7 +112077,7 @@ function loadCampaignCreateConfig(configFile) {
 function tryLoadCampaignCreateConfig(configFile) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync4(configFile, "utf8"));
+    raw = JSON.parse(readFileSync5(configFile, "utf8"));
   } catch {
     return null;
   }
@@ -113017,12 +113106,12 @@ async function runAdEdit(opts) {
 
 // src/commands/ad/extension.ts
 init_auth();
-import { readFileSync as readFileSync7 } from "fs";
+import { readFileSync as readFileSync8 } from "fs";
 init_cli_json_snapshot();
 init_strip_legacy_google_fields();
 
 // src/commands/ad/extension-lead-form.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 var VALID_LEAD_FORM_INPUT_TYPES = [
   "FULL_NAME",
   "FIRST_NAME",
@@ -113039,10 +113128,14 @@ var VALID_LEAD_FORM_INPUT_TYPES = [
   "POSTAL_CODE",
   "STREET_ADDRESS"
 ];
+var LEAD_FORM_HEADLINE_MAX_LEN = 30;
+var LEAD_FORM_DESCRIPTION_MAX_LEN = 200;
+var LEAD_FORM_BUSINESS_NAME_MAX_LEN = 25;
+var LEAD_FORM_CTA_DESCRIPTION_MAX_LEN = 30;
 function loadLeadFormExtensionConfig(configFile) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync5(configFile, "utf8"));
+    raw = JSON.parse(readFileSync6(configFile, "utf8"));
   } catch {
     console.error(`
 \u274C \u8BFB\u53D6\u914D\u7F6E\u6587\u4EF6\u5931\u8D25\uFF08${configFile}\uFF09
@@ -113066,10 +113159,30 @@ function validateLeadFormPayload(lf, prefix = "leadForm") {
     return errors;
   }
   if (!lf.businessName?.trim()) errors.push(`${prefix}.businessName \u4E0D\u80FD\u4E3A\u7A7A`);
+  else if (lf.businessName.trim().length > LEAD_FORM_BUSINESS_NAME_MAX_LEN) {
+    errors.push(
+      `${prefix}.businessName \u8D85\u957F\uFF08${lf.businessName.trim().length}/${LEAD_FORM_BUSINESS_NAME_MAX_LEN}\uFF09\uFF1A\u300C${lf.businessName.trim()}\u300D`
+    );
+  }
   if (!lf.headline?.trim()) errors.push(`${prefix}.headline \u4E0D\u80FD\u4E3A\u7A7A`);
+  else if (lf.headline.trim().length > LEAD_FORM_HEADLINE_MAX_LEN) {
+    errors.push(
+      `${prefix}.headline \u8D85\u957F\uFF08${lf.headline.trim().length}/${LEAD_FORM_HEADLINE_MAX_LEN}\uFF09\uFF1A\u300C${lf.headline.trim()}\u300D`
+    );
+  }
   if (!lf.description?.trim()) errors.push(`${prefix}.description \u4E0D\u80FD\u4E3A\u7A7A`);
+  else if (lf.description.trim().length > LEAD_FORM_DESCRIPTION_MAX_LEN) {
+    errors.push(
+      `${prefix}.description \u8D85\u957F\uFF08${lf.description.trim().length}/${LEAD_FORM_DESCRIPTION_MAX_LEN}\uFF09`
+    );
+  }
   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 (lf.callToActionDescription?.trim() && lf.callToActionDescription.trim().length > LEAD_FORM_CTA_DESCRIPTION_MAX_LEN) {
+    errors.push(
+      `${prefix}.callToActionDescription \u8D85\u957F\uFF08${lf.callToActionDescription.trim().length}/${LEAD_FORM_CTA_DESCRIPTION_MAX_LEN}\uFF09`
+    );
+  }
   if (!Array.isArray(lf.fields) || lf.fields.length === 0) {
     errors.push(`${prefix}.fields \u81F3\u5C11 1 \u9879`);
   } else {
@@ -113134,7 +113247,7 @@ function buildLeadFormExtensionBody(cfg, extensionId) {
 }
 
 // src/commands/ad/extension-whatsapp.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 var VALID_WHATSAPP_CTA_SELECTIONS = [
   "CONTACT_US",
   "LEARN_MORE",
@@ -113146,7 +113259,7 @@ var VALID_WHATSAPP_CTA_SELECTIONS = [
 function loadWhatsappExtensionConfig(configFile) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync6(configFile, "utf8"));
+    raw = JSON.parse(readFileSync7(configFile, "utf8"));
   } catch {
     console.error(`
 \u274C \u8BFB\u53D6\u914D\u7F6E\u6587\u4EF6\u5931\u8D25\uFF08${configFile}\uFF09
@@ -113608,7 +113721,7 @@ async function runAdExtensionUpdate(opts) {
   const googleApiUrl = requireGoogleApi(config);
   let raw;
   try {
-    raw = stripMetaKeys(JSON.parse(readFileSync7(opts.configFile, "utf8")));
+    raw = stripMetaKeys(JSON.parse(readFileSync8(opts.configFile, "utf8")));
   } catch {
     console.error(`
 \u274C \u8BFB\u53D6\u914D\u7F6E\u6587\u4EF6\u5931\u8D25\uFF08${opts.configFile}\uFF09
@@ -115802,7 +115915,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 readFileSync8 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 
 // src/commands/ad/pmax-urls.ts
 function pmaxChannelTypesUrl(googleApiUrl) {
@@ -115965,7 +116078,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 = readFileSync8(absImagePath);
+  const fileBuffer = readFileSync9(absImagePath);
   if (fileBuffer.length <= MAX_BASE64_UPLOAD_BYTES) {
     return uploadPmaxImageFileBase64(
       config,
@@ -116051,7 +116164,7 @@ function assertPmaxImageSlotsResolved(slots, requiredKinds = ["marketing", "squa
 }
 
 // src/commands/ad/pmax-load.ts
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 
 // src/commands/ad/pmax-campaign-extensions.ts
 init_auth();
@@ -116555,7 +116668,10 @@ function classifyExtensionAttachError(error) {
     return `${raw}\uFF08\u591A\u4E3A header \u4E0D\u5728\u5408\u6CD5\u679A\u4E3E\uFF1B\u8FD0\u884C ad extension snippet-headers \u6838\u5BF9\uFF09`;
   }
   if (/lead form|lead_form|LEAD_FORM/i.test(raw)) {
-    return `${raw}\uFF08\u68C0\u67E5 Google Ads UI \u662F\u5426\u5DF2\u63A5\u53D7 Lead Form ToS\u3001fields \u662F\u5426\u542B FULL_NAME/EMAIL/PHONE_NUMBER\uFF09`;
+    return `${raw}\uFF08\u68C0\u67E5\uFF1Aheadline\u226430\u3001description\u2264200\u3001businessName\u226425\uFF1Bfields \u52FF\u7528 MESSAGE\uFF1BGoogle Ads UI \u662F\u5426\u5DF2\u63A5\u53D7 Lead Form ToS\uFF09`;
+  }
+  if (/^HTTP 400\b/i.test(raw)) {
+    return `${raw}\uFF08\u6269\u5C55\u5B57\u6BB5\u8FDD\u89C4\u5E38\u89C1\uFF1Asnippet header \u975E\u679A\u4E3E\u3001Lead Form \u6587\u6848\u8D85\u957F\u3001URL \u65E0\u6548\uFF1B\u52A0 --verbose \u770B\u7F51\u5173\u539F\u6587\uFF09`;
   }
   return raw;
 }
@@ -116678,7 +116794,7 @@ function detectDeprecatedPmaxVideoKeys(raw) {
 function tryLoadPmaxCreateConfig(configFile) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync9(configFile, "utf8"));
+    raw = JSON.parse(readFileSync10(configFile, "utf8"));
   } catch {
     return null;
   }
@@ -116686,7 +116802,7 @@ function tryLoadPmaxCreateConfig(configFile) {
 }
 function loadPmaxCreateConfigRaw(configFile) {
   try {
-    const raw = JSON.parse(readFileSync9(configFile, "utf8"));
+    const raw = JSON.parse(readFileSync10(configFile, "utf8"));
     return stripMetaKeys(raw);
   } catch {
     return null;
@@ -116737,19 +116853,19 @@ function buildPmaxCreateUrl(googleApiUrl, accountId) {
 }
 
 // src/commands/ad/pmax-video-upload.ts
-import { existsSync as existsSync3, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync12 } 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 readFileSync10 } from "fs";
+import { readFileSync as readFileSync11 } 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(readFileSync10(configFile, "utf8"));
+    raw = JSON.parse(readFileSync11(configFile, "utf8"));
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     console.error(`
@@ -116949,7 +117065,7 @@ function runPmaxVideoValidation(configFile, cfg) {
     return { errors, warnings };
   }
   try {
-    const buf = readFileSync11(abs);
+    const buf = readFileSync12(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);
@@ -117012,7 +117128,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 = readFileSync11(opts.absVideoPath);
+  const fileBuffer = readFileSync12(opts.absVideoPath);
   const form = new FormData();
   form.append("media_account_id", opts.accountId.replace(/-/g, ""));
   form.append("title", title);
@@ -117070,7 +117186,7 @@ function validatePmaxVideoPathQuick(absPath) {
     return `\u89C6\u9891\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${absPath}`;
   }
   try {
-    if (readFileSync11(absPath).length === 0) return `\u89C6\u9891\u6587\u4EF6\u4E3A\u7A7A\uFF1A${absPath}`;
+    if (readFileSync12(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}`;
@@ -118473,7 +118589,7 @@ async function runAdCampaignValidate(opts) {
 }
 
 // src/commands/ad/pmax-image-convert.ts
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5, readFileSync as readFileSync12, existsSync as existsSync4 } from "fs";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5, readFileSync as readFileSync13, 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" },
@@ -118562,7 +118678,7 @@ async function runAdPmaxImageConvert(opts) {
   if (opts.updateConfig) {
     const configPath = resolve10(opts.updateConfig);
     try {
-      const raw = JSON.parse(readFileSync12(configPath, "utf8"));
+      const raw = JSON.parse(readFileSync13(configPath, "utf8"));
       const imgPaths = raw["imagePaths"] ?? {};
       if (outputPaths.marketing) imgPaths["marketing"] = outputPaths.marketing;
       if (outputPaths.square) imgPaths["square"] = outputPaths.square;
@@ -118718,6 +118834,17 @@ async function runAdPmaxBrandGuidelinesEnable(opts) {
 }
 
 // src/commands/ad/_register.ts
+function parseOptionalMatchType(raw) {
+  if (!raw?.trim()) return void 0;
+  const t = raw.trim().toLowerCase();
+  if (t === "broad") return "Broad";
+  if (t === "phrase") return "Phrase";
+  if (t === "exact") return "Exact";
+  console.error(`
+\u274C --match-type \u65E0\u6548\uFF1A${raw}\uFF1B\u5408\u6CD5\u503C Broad | Phrase | Exact
+`);
+  process.exit(1);
+}
 function register20(program2) {
   const adCmd = program2.command("ad").description(
     "Google \u5E7F\u544A\u7BA1\u7406\uFF08Google API \u5730\u5740\u4ECE TSO API \u81EA\u52A8\u63A8\u5BFC\uFF0C\u53EF\u901A\u8FC7 SILUZAN_GOOGLE_API \u73AF\u5883\u53D8\u91CF\u8986\u76D6\uFF09\n  \u542B\uFF1A\u7CFB\u5217/\u7EC4/\u521B\u610F/\u5173\u952E\u8BCD\u7B49\u5E38\u89C4\u5E7F\u544A\u6295\u653E\u4E0E\u7BA1\u7406\u80FD\u529B"
@@ -119002,10 +119129,16 @@ function register20(program2) {
       });
     }
   );
-  adCmd.command("keyword-create").description("\u5411\u5E7F\u544A\u7EC4\u6DFB\u52A0\u641C\u7D22\u5173\u952E\u8BCD").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--adgroup-id <id>", "\u76EE\u6807\u5E7F\u544A\u7EC4 ID").requiredOption("--adgroup-name <name>", "\u76EE\u6807\u5E7F\u544A\u7EC4\u540D\u79F0").requiredOption("--campaign-id <id>", "\u6240\u5C5E\u5E7F\u544A\u7CFB\u5217 ID").requiredOption("--campaign-name <name>", "\u6240\u5C5E\u5E7F\u544A\u7CFB\u5217\u540D\u79F0").requiredOption(
+  adCmd.command("keyword-create").description("\u5411\u5E7F\u544A\u7EC4\u6DFB\u52A0\u641C\u7D22\u5173\u952E\u8BCD\uFF08\u652F\u6301\u7A7A\u683C\u591A\u8BCD\uFF1B\u53EF\u7528 --keywords-file\uFF09").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--adgroup-id <id>", "\u76EE\u6807\u5E7F\u544A\u7EC4 ID").requiredOption("--adgroup-name <name>", "\u76EE\u6807\u5E7F\u544A\u7EC4\u540D\u79F0").requiredOption("--campaign-id <id>", "\u6240\u5C5E\u5E7F\u544A\u7CFB\u5217 ID").requiredOption("--campaign-name <name>", "\u6240\u5C5E\u5E7F\u544A\u7CFB\u5217\u540D\u79F0").option(
     "--keywords <kw1,kw2,...>",
-    "\u5173\u952E\u8BCD\u5217\u8868\uFF0C\u9017\u53F7\u5206\u9694",
-    (v) => v.split(",").map((s) => s.trim())
+    "\u5173\u952E\u8BCD\u5217\u8868\uFF0C\u9017\u53F7\u5206\u9694\uFF08\u7A7A\u683C\u591A\u8BCD\u5408\u6CD5\uFF0C\u5982 how to make\uFF09\uFF1B\u53EF\u4E0E --keywords-file \u5E76\u7528",
+    (v) => parseKeywordsCsv(v)
+  ).option(
+    "--keywords-file <path>",
+    'JSON \u5B57\u7B26\u4E32\u6570\u7EC4\u6587\u4EF6\uFF08\u63A8\u8350\u591A\u8BCD/\u5E26\u5F15\u53F7\u573A\u666F\uFF09\uFF0C\u5982 ["how to make","home cooking"]'
+  ).option(
+    "--match-type <Broad|Phrase|Exact>",
+    '\u7EDF\u4E00\u5339\u914D\u7C7B\u578B\uFF08\u5199\u5165\u65F6\u7528\u6587\u6848 "\u2026" / [\u2026] \u5305\u88C5\uFF1B\u7701\u7565\u5219\u6309\u8BCD\u9762\u539F\u6837\u63D0\u4EA4\uFF09'
   ).option("--final-url <url>", "\u5173\u952E\u8BCD\u6700\u7EC8\u5230\u8FBE\u7F51\u5740\uFF08\u53EF\u9009\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",
@@ -119020,16 +119153,26 @@ function register20(program2) {
         campaignId: opts.campaignId,
         campaignName: opts.campaignName,
         keywords: opts.keywords,
+        keywordsFile: opts.keywordsFile,
+        matchType: parseOptionalMatchType(opts.matchType),
         finalUrl: opts.finalUrl,
         jsonOut: opts.jsonOut,
         verbose: opts.verbose
       });
     }
   );
-  adCmd.command("keyword-negative-create").description("\u6DFB\u52A0\u5426\u5B9A\u5173\u952E\u8BCD\uFF08\u5E7F\u544A\u7CFB\u5217\u5C42\u7EA7\uFF1B\u4F20 --adgroup-id \u5219\u4E3A\u5E7F\u544A\u7EC4\u5C42\u7EA7\uFF09").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--campaign-id <id>", "\u5E7F\u544A\u7CFB\u5217 ID").requiredOption("--campaign-name <name>", "\u5E7F\u544A\u7CFB\u5217\u540D\u79F0").requiredOption(
+  adCmd.command("keyword-negative-create").description(
+    "\u6DFB\u52A0\u5426\u5B9A\u5173\u952E\u8BCD\uFF08\u7CFB\u5217/\u7EC4\u7EA7\uFF1B\u652F\u6301\u7A7A\u683C\u591A\u8BCD\u77ED\u8BED\uFF0C\u5982 how to make\uFF1B\u53EF\u7528 --keywords-file\uFF09"
+  ).requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--campaign-id <id>", "\u5E7F\u544A\u7CFB\u5217 ID").requiredOption("--campaign-name <name>", "\u5E7F\u544A\u7CFB\u5217\u540D\u79F0").option(
     "--keywords <kw1,kw2,...>",
-    "\u5426\u5B9A\u5173\u952E\u8BCD\u5217\u8868\uFF0C\u9017\u53F7\u5206\u9694",
-    (v) => v.split(",").map((s) => s.trim())
+    "\u5426\u5B9A\u8BCD\u5217\u8868\uFF0C\u9017\u53F7\u5206\u9694\uFF08\u7A7A\u683C\u591A\u8BCD\u5408\u6CD5\uFF09\uFF1B\u53EF\u4E0E --keywords-file \u5E76\u7528",
+    (v) => parseKeywordsCsv(v)
+  ).option(
+    "--keywords-file <path>",
+    'JSON \u5B57\u7B26\u4E32\u6570\u7EC4\u6587\u4EF6\uFF08\u63A8\u8350\u591A\u8BCD\u77ED\u8BED\uFF09\uFF0C\u5982 ["how to make","home cooking","second hand"]'
+  ).option(
+    "--match-type <Broad|Phrase|Exact>",
+    "\u7EDF\u4E00\u5339\u914D\u7C7B\u578B\uFF08Broad \u65E0\u5305\u88C5 / Phrase \u52A0\u53CC\u5F15\u53F7 / Exact \u52A0\u65B9\u62EC\u53F7\uFF09"
   ).option("--adgroup-id <id>", "\u5E7F\u544A\u7EC4 ID\uFF08\u6307\u5B9A\u540E\u4E3A\u5E7F\u544A\u7EC4\u5C42\u7EA7\u5426\u5B9A\uFF09").option("--adgroup-name <name>", "\u5E7F\u544A\u7EC4\u540D\u79F0").option("-t, --token <token>", "Auth Token").option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
     async (opts) => {
       await runAdNegativeKeywordCreate({
@@ -119040,6 +119183,8 @@ function register20(program2) {
         adgroupId: opts.adgroupId,
         adgroupName: opts.adgroupName,
         keywords: opts.keywords,
+        keywordsFile: opts.keywordsFile,
+        matchType: parseOptionalMatchType(opts.matchType),
         verbose: opts.verbose
       });
     }

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.37-beta.2",
-  "publishedAt": 1783912835109
+  "version": "1.1.37-beta.4",
+  "publishedAt": 1783934085806
 }

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

@@ -7,6 +7,7 @@
     "agentPitfalls": [
       "campaign-validate 推荐 --json-out ",
       "否词只写 campaign.NegativeKeywordsForBatchJob，禁止把 free/jobs/tutorial 等否词抄进 AdGroupsForBatchJob[].KeywordsForBatchJob",
+      "KeywordText 是 JSON 字符串数组，空格多词合法（如 how to make）；禁止因多词省略否词或让用户去后台手补",
       "RSA 须同时写 DestinationUrl 与 Finalurl（后端必填 Finalurl；仅有 DestinationUrl 时 validate 可能仍通过）",
       "SITELINK 须写 AssetFieldType: SITELINK（与 typeV2 一致）",
       "提交前：ad campaign-validate → 用户确认 → ad campaign-create（勿对 validate 加 --json-out）"
@@ -65,7 +66,24 @@
     ],
 
     "NegativeKeywordsForBatchJob": [
-      { "KeywordText": ["free", "cheap", "download"], "MatchTypeV2": "BROAD", "FinalURL": "" }
+      {
+        "KeywordText": [
+          "free",
+          "cheap",
+          "download",
+          "how to make",
+          "home cooking",
+          "second hand",
+          "near me"
+        ],
+        "MatchTypeV2": "BROAD",
+        "FinalURL": ""
+      },
+      {
+        "KeywordText": ["\"vegan recipe\"", "\"stock price\""],
+        "MatchTypeV2": "PHRASE",
+        "FinalURL": ""
+      }
     ],
 
     "ExtensionsForBatchJob": [

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

@@ -31,6 +31,8 @@ JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-templa
 **禁止**：把方案 Markdown「否定词表」里的 `free` / `jobs` / `tutorial` 等抄进 `KeywordsForBatchJob`——那会**主动购买**这些流量。  
 **正确**：否词只写 `NegativeKeywordsForBatchJob`；`ad campaign-validate` 会对误填给出 **warnings**（常见否词词根 / 与否词块重复）。
 
+**多词短语（与 `keyword-negative-create` 同类误判）**：`KeywordText` 是 **JSON 字符串数组**，**空格多词完全合法**（如 `"how to make"`、`"home cooking"`）。PHRASE 写 `"\"vegan recipe\""` 或裸词 + `MatchTypeV2: "PHRASE"`（validate 会补引号）。**禁止**因「多词」就省略否词或让用户去 Google Ads 后台手补——那是 Agent 误判，不是 `campaign-create` 限制。
+
 投放方案 Markdown 中 §3.3 关键词矩阵 → `KeywordsForBatchJob`；§3.3 系列级否定词 / §3.4 账户级否定词 → `NegativeKeywordsForBatchJob`（账户级列表仍须在 Google 后台单独应用）。
 
 ### CLI 参数（勿混用）
@@ -184,7 +186,7 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json --js
 | 字段                          | 类型     | 说明                                                                              |
 | ----------------------------- | -------- | --------------------------------------------------------------------------------- |
 | `AdGroupsForBatchJob`         | object[] | **至少 1 组**；见下                                                               |
-| `NegativeKeywordsForBatchJob` | object[] | 系列级否词；元素：`{ KeywordText: string[], MatchTypeV2: "BROAD", FinalURL: "" }` |
+| `NegativeKeywordsForBatchJob` | object[] | 系列级否词；元素：`{ KeywordText: string[], MatchTypeV2: "BROAD"\|"PHRASE"\|"EXACT", FinalURL: "" }`；**KeywordText 可含空格多词**（见模板示例） |
 | `ExtensionsForBatchJob`       | object[] | 附加信息；`Properties` 须 **string→string**（勿用数组值）。SITELINK 见下表        |
 
 #### SITELINK（`ExtensionsForBatchJob[i]`，`typeV2` / `AssetFieldType` = `SITELINK`）

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

@@ -40,14 +40,14 @@ siluzan-tso ad extension update -a <accountId> --id <extensionId> --config-file
 | ---------------------------------- | -------- | :--: | -------------------------------------------------------------- |
 | `account`                          | string   |  ✅  | Google 媒体客户 ID                                             |
 | `campaignId`                       | string   |  ✅  | PMax 活动 ID（`channelTypeV2=PERFORMANCE_MAX`）                |
-| `leadForm.businessName`            | string   |  ✅  | 商家名称                                                       |
-| `leadForm.headline`                | string   |  ✅  | 表单标题                                                       |
-| `leadForm.description`             | string   |  ✅  | 表单描述                                                       |
+| `leadForm.businessName`            | string   |  ✅  | 商家名称（≤25 字符）                                           |
+| `leadForm.headline`                | string   |  ✅  | 表单标题（**≤30 字符**，超长网关常直接 HTTP 400）              |
+| `leadForm.description`             | string   |  ✅  | 表单描述（≤200 字符）                                          |
 | `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.callToActionDescription` | string   |      | 默认 `Contact us`（≤30 字符）                                  |
+| `leadForm.fields`                  | object[] |  ✅  | 至少 1 项；`inputType` 如 `FULL_NAME`、`EMAIL`、`PHONE_NUMBER`（**无** `MESSAGE`） |
 | `leadForm.webhook`                 | object   |      | 写入 Google 的 Webhook（非平台接收端）                         |
 
 ---

package/dist/skill/references/accounts/accounts.md

@@ -203,7 +203,7 @@ siluzan-tso accounts-digest -m Google -a id1,id2 --min-spend 10 \
   --start 2026-04-01 --end 2026-04-15 --json-out ./snap-p3
 ```
 
-**`data.items[]` 主要字段**：`mediaCustomerId`、`name`、`advertiserName`、`currencyCode`、`balance`、`spend`、`impressions`、`clicks`、`conversions`、`ctr`（%）、`cpc`、`cpa`。跨币种汇总见 `references/accounts/currency.md`（**禁止**对 `meta.totals` 跨币种直接当最终结论）。
+**`data.items[]` 主要字段**：`mediaCustomerId`、`name`、`advertiserName`、`currencyCode`、`balance`、`spend`（**区间合计**，同 `stats`）、`impressions`、`clicks`、`conversions`、`ctr`（%）、`cpc`、`cpa`。跨币种汇总见 `references/accounts/currency.md`（**禁止**对 `meta.totals` 跨币种直接当最终结论）。
 
 ---
 
@@ -230,6 +230,8 @@ siluzan-tso stats -m <媒体类型> [选项]
 | `--start-date` / `--end-date` | 与 `--start` / `--end` 同义（CLI 别名，与 SKILL Playbook 一致）               | —      |
 | `--json-out`                  | 输出原始 JSON；**失败时 stdout 仍为 JSON**（`{"ok":false,"error":"..."}`）    | —      |
 
+**口径（易错）**：返回的 **`spend` = `--start`～`--end` 闭区间合计消耗**，默认近 7 天即约 **7 日之和**，**不是**「一天的消耗」。要日消耗须 `start=end`；要日均用 `spend/天数` 或 `balance-scan` 的 `dailySpend`。**禁止**把默认窗口的 `spend` 当成日消耗去比日预算或写「今天花了 X」。
+
 **示例：**
 
 ```bash

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

@@ -194,10 +194,13 @@
 
 | 任务                        | 推荐命令                                                                               | 禁止                             |
 | --------------------------- | -------------------------------------------------------------------------------------- | -------------------------------- |
-| 多账户余额 / 预算不足预警   | `balance-scan -m <媒体> --threshold-days 7`                                            | 逐账户 `balance --accounts ...`  |
-| 多账户投放画像              | `accounts-digest -m <媒体> [-a ...] --start --end --json-out`                          | 逐账户 `stats`                   |
+| 多账户余额 / 预算不足预警   | `balance-scan -m <媒体> --threshold-days 7`（用 **`dailySpend`** / `remainingDays`）   | 逐账户 `balance --accounts ...`；把 `stats` 多日 **`spend` 当「日消耗」** |
+| 多账户投放画像              | `accounts-digest -m <媒体> [-a ...] --start --end --json-out`（**`spend`=区间合计**）  | 逐账户 `stats`；把合计 `spend` 说成「每天花了」 |
 | 多账户 × 多维度 Google 数据 | 全量：`google-analysis-batch run`（省略 `-a`）；2~10：`google-analysis -a id1,id2,...` | 外层 for-loop；先 list 再拼 `-a` |
 | 多系列诊断                  | `ad campaigns --json-out` + node 读文件过滤                                            | 逐系列 `ad campaign-get`         |
+| 单日预算熔断 / 当日花费比日预算 | `ad campaigns --start <当日> --end <当日>`（**start=end**）后再比 `spend` 与 `budget` | 用默认近 7 天窗口的 `spend` 对比日预算 |
+
+**消耗口径（自动化必读）**：凡 `--start`/`--end` 读命令的 `spend` = **闭区间合计**，默认近 7 天 ≠ 一天。日均用 `balance-scan.dailySpend` 或 `合计÷天数`；详见 `references/operations/hosted-automation-self-control.md`「检查项常用 JSON 字段」。
 
 **`google-analysis-batch` 纪律**（详见 `references/analytics/google-analysis-batch.md`）：拉全量时省略 `-a`；中断后**必须** `resume --run-id <id>`，**禁止**重新 `run`；stdout 始终单行 JSON（`kind=siluzan-tso-batch-summary`）；退出码 `0` 全成功 / `2` 部分成功 / `3` 全失败或 Token 失效 / `4` 用法错误；401 → 整批终止，按 `references/core/setup.md` 重登录后 `resume`。
 

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

@@ -93,16 +93,17 @@ low.forEach((a) => console.log(' ', a.mediaCustomerId, a.name, '余额:', a.rema
 
 ### 3. 汇总消耗数据
 
-`stats` 的 `AccountOverviewItem` 使用 **`spend`**（非 `cost`）：
+`stats` 的 `AccountOverviewItem` 使用 **`spend`**（非 `cost`）。**`spend` = `--start`～`--end` 区间合计**（默认近 7 天 ≈ 7 日之和，**不是**「一天的消耗」）：
 
 ```bash
-siluzan-tso stats -m Google --days 7 --json-out ./snap-cli
+siluzan-tso stats -m Google -a <id> --start 2026-07-06 --end 2026-07-12 --json-out ./snap-cli
 node -e "
 const d = require('./snap-cli/stats-google.json');
 const list = d.items || [];
+// 「总消耗」= 区间合计；日均请 total/天数，或 balance-scan.dailySpend；勿说成每天花了 total
 const total = list.reduce((s, a) => s + Number(a.spend ?? 0), 0);
 const clicks = list.reduce((s, a) => s + Number(a.clicks ?? 0), 0);
-console.log('总消耗:', total.toFixed(2), '  总点击:', clicks);
+console.log('区间总消耗:', total.toFixed(2), '  总点击:', clicks);
 list
   .slice()
   .sort((a, b) => Number(b.spend) - Number(a.spend))

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

@@ -27,7 +27,8 @@
 2. **结论先行**：第一句给出可操作的判断（正常 / 有问题 / 原因是什么），不要让用户从表格里自己猜。
 3. **数据支撑**：引用**当次 CLI/脚本**的真实数字（消耗、CPA、余额、状态等）；禁止编造、禁止示例 ID。
 4. **行动建议**：1～3 条可执行项，点名对象（系列名、账户、关键词）并引用数据。
-5. **下一步**：一句预测或邀请（「要我帮您调整预算吗？」「还想看关键词明细吗？」）。
+5. **下一步**：一句预测或邀请（「要我帮您调整预算吗？」「还想看关键词明细吗？」）。  
+   **注意**：客户端会另行展示可点击的 suggestion chips（完整用户话术）。本文件与各任务 reference **只要求回复里出现一句邀请**，**不要**在 skill 各任务文档里维护「可点 chips 全文清单」——那份清单由产品侧 chips 规则维护，skill 更新不应与之逐条对齐。
 
 长任务（预计 >30s）：中间用**进度式**短句（「正在拉取系列数据…」「正在检查余额…」），不要长时间沉默后突然扔一大段表。
 
@@ -59,7 +60,8 @@
 | 帮我开个户 / 建广告 | W2 / W3 | 「没问题，我先告诉您需要准备哪些资料。」 |
 | 网站行不行 | P8 | 「我来给这个网站做个体检，看是否符合投放要求。」 |
 
-完整话术矩阵见产品文档第十章；Skill 内记住**结构**即可，勿背诵全文。
+完整话术矩阵见产品文档第十章；Skill 内记住**结构**即可，勿背诵全文。  
+可点击的「下一步」完整句子由客户端 suggestion chips 提供，**禁止**在本 skill 的 playbooks/workflows 里复制维护 chips 文案表（避免 skill 更新后与产品侧脱节）。
 
 ---
 
@@ -106,7 +108,8 @@
 | ---- | ---- |
 | `agent-conventions.md` | 怎么拉数、怎么读 outline、怎么自检、硬规范 |
 | `intent-routing.md` | 报告/分析消歧、选哪个 P/W |
-| `playbooks.md` / `workflows.md` | 步骤清单 |
-| **本文件** | **对用户怎么说** |
+| `playbooks.md` / `workflows.md` | 步骤清单（执行），不维护 chips 全文 |
+| **本文件** | **对用户怎么说**（结构 + 一句下一步邀请） |
+| 客户端 suggestion chips | **可点的下一步完整话术**（产品侧维护，与本 skill 解耦） |
 
 数值纪律不变：所有金额、状态、ID 仍只来自当次 CLI/`--json-out` 脚本；本文件只约束**表述方式**，不放宽数据真实性要求。

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

@@ -97,7 +97,9 @@
 siluzan-tso ad campaigns -a <accountId> [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>] [--json-out ./snap]
 ```
 
-落盘 JSON 中 `budget` 为日预算（主币种「元」，CLI 已 ÷100），另有 `statusDisplay`（状态文案）。
+落盘 JSON 中 **`budget` 为日预算**（主币种「元」，CLI 已 ÷100），另有 `statusDisplay`（状态文案）。
+带 `--start` / `--end` 时，同行的 **`spend` / `impressions` / `clicks` / `conversions` 为该闭区间合计**（**不是**日消耗）。
+与日预算比较「是否超预算」时，**必须** `start=end=统计日`；多日窗口须先 ÷ 天数或改用 `balance-scan.dailySpend` / `overview.averageDailyCost` 再谈「日均」。
 
 ### 启停
 
@@ -266,26 +268,38 @@ siluzan-tso ad keyword-create \
   -a <accountId> \
   --adgroup-id <adGroupId> --adgroup-name <adGroupName> \
   --campaign-id <campaignId> --campaign-name <campaignName> \
-  --keywords "词1,词2,词3" [--final-url <url>] \
+  --keywords "词1,词2,多词短语" [--final-url <url>] \
+  [--match-type Broad|Phrase|Exact] [--keywords-file ./kws.json] \
   [--json-out <path>]
 ```
 
-`--json-out` 落盘 `{ request: { adgroupId, count }, response: ... }`，批量脚本可直接据此核对成功量。
+`--keywords` **支持空格多词**（逗号才是分隔符）。`--json-out` 落盘 `{ request: { adgroupId, count }, response: ... }`，批量脚本可直接据此核对成功量。
 
 ### 否定关键词
 
+**支持空格多词短语**（如 `how to make`、`home cooking`）。匹配类型与 Web 一致：裸词=广泛，`"短语"`=词组，`[词]`=完全；也可用 `--match-type`。多词/带引号时推荐 `--keywords-file`，避免 shell 转义。
+
 ```bash
 # 添加（默认系列层级；传 --adgroup-id 则为组层级）
+# 多词短语直接写空格，逗号分隔多条——CLI 支持，无需改后台手工补
 siluzan-tso ad keyword-negative-create \
   -a <accountId> \
   --campaign-id <campaignId> --campaign-name <campaignName> \
-  --keywords "词1,词2" \
-  [--adgroup-id <id> --adgroup-name <name>]
+  --keywords "how to make,home cooking,second hand,near me"
+
+# 统一词组匹配 + JSON 文件（推荐）
+# negatives.json → ["how to make","home cooking","vegan recipe"]
+siluzan-tso ad keyword-negative-create \
+  -a <accountId> \
+  --campaign-id <campaignId> --campaign-name <campaignName> \
+  --keywords-file ./negatives.json --match-type Phrase
 
 # 删除（先用 ad keywords --negative --json-out ./snap 获取 id）
 siluzan-tso ad keyword-negative-delete -a <accountId> --id <negativeKeywordId>
 ```
 
+> **禁止**因「多词」就让用户去 Google Ads 后台手工补否词——那是 Agent 误判；用上面命令即可。
+
 ---
 
 ## ad batch — 异步批量创建记录
@@ -403,6 +417,8 @@ BatchJob 中 `ExtensionsForBatchJob`（尤其 **Sitelink**）失败率较高，
 
 **关键词匹配：** 写在 `KeywordsForBatchJob` 块内；同一块同匹配类型，`MatchTypeV2` 与 `KeywordText` 词面格式必须对齐（`PHRASE` 用 `"词"`、`EXACT` 用 `[词]`、`BROAD` 直写）。
 
+**多词短语：** `KeywordText` / 否词 `NegativeKeywordsForBatchJob[].KeywordText` 是 **JSON 字符串数组**，**空格多词合法**（如 `"how to make"`）。与 `keyword-negative-create` 不同，这里**没有**逗号 CLI 解析问题——**禁止**因「多词」省略否词或让用户去后台手补。
+
 广告组/关键词/创意的分步创建仍用 `adgroup-create`、`keyword-create`、`ad-create`。
 
 ---

package/dist/skill/references/google-ads/rules/google-ads-keyword-strategy.md

@@ -409,8 +409,8 @@ Broad Match + 受众信号 = 伪装成广泛定向的精准投放。
 | ------------ | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
 | 关键词调研   | `keyword -k "词" [--url]`                                    | 结果按意图分层后再添加                                                  |
 | 添加关键词   | `ad keyword-create --keywords "词1,词2"`                     | 格式：`词→BROAD`、`"词"→PHRASE`、`[词]→EXACT`                           |
-| 添加否定词   | `ad keyword-negative-create`                                 | 每周从 `ad search-terms` 挖掘                                           |
-| 创建广告系列 | `ad campaign-create --config-file`（先 `campaign-validate`） | 按本文第三章架构设计系列结构；匹配块见 `google-ads-keyword-taxonomy.md` |
+| 添加否定词   | `ad keyword-negative-create`                                 | **支持空格多词**（`how to make`）；多词用 `--keywords` 或 `--keywords-file`，**禁止**因多词改让用户后台手补 |
+| 创建广告系列 | `ad campaign-create --config-file`（先 `campaign-validate`） | `KeywordText` 为 JSON 数组，**空格多词合法**；否词写 `NegativeKeywordsForBatchJob`，勿因多词省略 |
 | 搜索词分析   | `ad search-terms`                                            | 每周导出，按第八章流程处理                                              |
 | 竞品监控     | `ad auction-insights`（如有）                                | 按第九章分析竞争态势                                                    |
 | 出价调整     | 广告系列级 Smart Bidding 设置                                | 新账户用 Manual/ECPC → 有数据后切 tCPA/tROAS                            |

package/dist/skill/references/operations/hosted-automation-self-control.md

@@ -26,11 +26,15 @@
 
 | 检查意图              | 可关注的 JSON 字段（键名以实际 stdout 为准）                                                                                                                                              |
 | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 周期内费用            | 系列/组/创意列表中的 **`spend`**；报表类子命令中带费用的指标字段                                                                                                                          |
-| 日预算与费用比        | **`ad campaigns --json-out ./snap`**：`**budget`**（CLI 已为元）与 **`spend`**；比较时须**统一货币与单位\*\*（见 `SKILL.md` 金额硬规范）                                                  |
-| 转化次数              | **`conversions`**（或报表里等价字段名）                                                                                                                                                   |
-| 实际 CPA              | 宿主侧 **`spend / conversions`**（`conversions` 为 0 时不做 CPA 判断）                                                                                                                    |
+| **区间合计费用**      | 系列/组/创意列表中的 **`spend`** = **`--start`～`--end` 整段合计**（**不是**「一天的消耗」；窗口 7 天则约为 7 日之和）                                                                    |
+| **日预算**            | **`ad campaigns --json-out ./snap`** 的 **`budget`**（CLI 已为元）= **每日预算上限**，与 `spend` **量纲不同**                                                                            |
+| 日预算与「当日」费用比 | **仅当** `--start` 与 `--end` 为**同一统计日**时，才可用 `spend` 对比 `budget`；**禁止**用多日 `spend` 去除以或对比日预算（会把周/月合计误当成「一天花了这么多」）                        |
+| 转化次数              | **`conversions`**（窗口内合计）                                                                                                                                                           |
+| 实际 CPA              | 宿主侧 **`spend / conversions`**（同窗口合计；`conversions` 为 0 时不做 CPA 判断）                                                                                                        |
 | 目标 CPA（系列 / 组） | 系列列表 JSON 中的 **`targetCpa_BidingAmount`** 等；组列表 **`ad groups --json-out ./snap`** 中的 **`targetCpaAmount`**（写入口径见 `references/google-ads/google-ads.md`「广告组编辑」） |
+| 日均消耗（续航用）    | 用 `balance-scan` 的 **`dailySpend`**（近 7 日合计/7），或自算 `spend / 活跃天数`；**禁止**把多日 `spend` 直接当「日消耗」                                                                |
+
+> **硬约束（自动化 / 预警必读）**：凡带 `--start` / `--end` 的读命令，返回的 `spend` / `impressions` / `clicks` / `conversions` 均为**该闭区间合计**。要「一天的消耗」必须 `start=end=该日`，或显式 `合计 ÷ 天数`；要「日均」用 `balance-scan.dailySpend` / `overview.averageDailyCost`。
 
 若某条检查所需字段在**当前**落盘 JSON 中不存在，**禁止猜测**：先换用 `references/analytics/account-analytics.md` 中其它子命令拉数，或与维护方确认是否需扩展 `siluzan-tso`；宿主侧不得编造字段。
 
@@ -38,21 +42,22 @@
 
 ## 场景 1：单日预算熔断（Campaign）
 
-**业务目标**：当周期内费用相对日预算达到设定比例（如 **≥ 110%**，建议 **110%–120%** 缓冲 API 延迟）时，**将系列状态置为 Paused**；恢复由人工加预算后在网页或 CLI 再启用。
+**业务目标**：当**当日**系列花费相对**日预算**达到设定比例（如 **≥ 110%**，建议 **110%–120%** 缓冲 API 延迟）时，**将系列状态置为 Paused**；恢复由人工加预算后在网页或 CLI 再启用。
 
 ### 检查项（宿主每轮执行）
 
 1. 解析 `mediaCustomerId`（见上文前置）。
-2. 拉系列列表（**统计日 = 当日**，起止同为该日或业务日定义）：
+2. 拉系列列表（**必须** `--start` = `--end` = **当日**统计日；**禁止**用默认近 7 天窗口做本场景）：
 
 ```bash
-siluzan-tso ad campaigns -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json-out ./snap
+siluzan-tso ad campaigns -a <mediaCustomerId> --start <当日YYYY-MM-DD> --end <当日YYYY-MM-DD> --json-out ./snap
 ```
 
 3. 对 `items[]` 中每条系列（`id` 为系列 ID）：
-   - 读取 **`spend`**（或文档约定的费用字段）与 **`budget`**（`ad campaigns` JSON 下**已为元**，与 `spend` 同量级口径，见 `SKILL.md` 硬规范）。
-   - 计算阈值：`threshold = budget_in_same_unit * (coefficient / 100)`，系数 `coefficient` 建议 **110–120**（配置项）。
+   - 读取 **`spend`**（= **仅当日**合计费用）与 **`budget`**（**日预算**，元）。
+   - 计算阈值：`threshold = budget * (coefficient / 100)`，系数 `coefficient` 建议 **110–120**（配置项）。
    - **IF** `spend >= threshold` **且**宿主策略允许对该系列熔断（如排除白名单），则进入写操作。
+   - **禁止**：`--start`≠`--end` 时仍用 `spend` 对比 `budget`（会把多日合计误判成单日超预算）。
 
 ### 最终操作
 

package/dist/skill/references/operations/hosted-automation-user-catalog.md

@@ -14,6 +14,8 @@
 
 **总索引**：[`references/operations/hosted-automation-scenarios.md`](references/operations/hosted-automation-scenarios.md) · **自控全文**：[`references/operations/hosted-automation-self-control.md`](references/operations/hosted-automation-self-control.md) · **金额硬规范**（展示用 `*Display` 等）：[`SKILL.md`](../SKILL.md)「金额与货币单位硬约束」。
 
+> **消耗 ≠ 日消耗**：`ad campaigns` / `stats` / `accounts-digest` 的 **`spend` 是 `--start`～`--end` 合计**。单日熔断必须 `start=end=当日`；续航日均用 **`balance-scan.dailySpend`**，禁止把默认近 7 天 `spend` 当成「一天的花费」去比日预算。
+
 ## 异常监控与报警系统
 
 编排（定时、HTTP 探活、通知）在宿主；**读哪些 JSON 字段、用什么命令** 以 **[`references/operations/hosted-automation-monitoring-json.md`](references/operations/hosted-automation-monitoring-json.md)** 为准（键名以当次 `--json-out` 落盘 JSON 为准，勿套用 Google Ads API 官方字段名解析本 CLI 输出）。

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