siluzan-tso-cli 1.1.20-beta.2 → 1.1.20-beta.21

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

@@ -1,99 +1,152 @@
 {
-  "account": "6326027735",
-  "customerName": "账户显示名称（来自 list-accounts --json 的 mediaAccountName）",
-  "name": "搜索-品牌词-2026",
-  "budget": 100,
-  "bidding": "TARGET_SPEND",
-  "bidCeiling": 1.5,
-  "locationIds": ["2840", "2826", "2036"],
-  "languageIds": ["1000", "1017"],
-  "startDate": "2026-04-01",
-  "endDate": "2027-04-01",
+  "_meta": {
+    "schema": "campaign-create/v2",
+    "doc": "campaign-create-template.md",
+    "note": "以 _ 开头的键仅作说明，CLI 提交前会剥离；字段名一律 PascalCase，直接对齐后端 CampaignCreationRecord + Campaign 契约",
+    "agentPitfalls": [
+      "campaign-validate 不支持 --json-out， --json ",
+      "RSA 须同时写 DestinationUrl 与 Finalurl（后端必填 Finalurl；仅有 DestinationUrl 时 validate 可能仍通过）",
+      "SITELINK 须写 AssetFieldType: SITELINK（与 typeV2 一致）",
+      "提交前：ad campaign-validate → 用户确认 → ad campaign-create（勿对 validate 加 --json-out）"
+    ]
+  },
+
+  "account": "REPLACE_mediaCustomerId",
+  "customerName": "REPLACE_mediaAccountName_from_list_accounts",
+  "name": "Search_Brand_US_2026",
   "url": "https://www.example.com",
-  "status": "Enabled",
-  "adgroupName": "核心词_品牌词",
-  "maxCpc": 1.5,
-  "matchType": "BROAD",
-  "keywords": ["brand keyword 1", "brand keyword 2", "brand keyword 3"],
-  "headlines": [
-    "Brand Name: Quality Products",
-    "Trusted For Over 20 Years",
-    "Global Reach, Local Impact",
-    "Contact Us Today",
-    "Request A Free Quote Now"
-  ],
-  "descriptions": [
-    "Top-quality products with certified standards. Contact us today!",
-    "Trusted by global partners. Request a free quote now!"
-  ],
-  "finalUrl": "https://www.example.com/products",
-  "path1": "products",
-  "path2": "2026",
+  "locations": ["United States"],
   "productWords": ["brand", "product"],
-  "negativeKeywords": ["free", "cheap", "wikipedia", "pdf", "ebay", "amazon"],
-  "extensions": [
-    {
-      "level": "Campaign",
-      "typeV2": "CALL",
-      "AssetFieldType": "CALL",
-      "Properties": { "ContryCode": "CN", "PhoneNumber": "+86 400-XXX-XXXX" }
-    },
-    {
-      "level": "Campaign",
-      "typeV2": "SITELINK",
-      "AssetFieldType": "SITELINK",
-      "properties": {
-        "DestinationUrl": "https://www.example.com/about",
-        "Text": "About Us",
-        "Line2": "Learn about our story",
-        "Line3": "Explore our mission"
+  "googleDataRecordId": null,
+  "draft": false,
+
+  "campaign": {
+    "_comment_budget": "金额字段（Budget / TargetSpend_BidCeilingAmount / TargetCpa_BidingAmount / 各 AdGroup.MaxCPCAmount）以主币种「元」填写，CLI 提交前自动 ×100 转「分」",
+    "Name": "Search_Brand_US_2026",
+    "StatusV2": "Enabled",
+    "ChannelTypeV2": "SEARCH",
+    "BiddingStrategyTypeV2": "TARGET_SPEND",
+    "Budget": 100,
+    "BudgetShared": false,
+    "BudgetId": 0,
+    "BudgetBudgetDeliveryMethodV2": "STANDARD",
+    "TargetSpend_BidCeilingAmount": 1.5,
+    "ManualCpc_EnhancedCpcEnabled": false,
+    "TargetGoogleSearch": true,
+    "TargetSearchNetwork": false,
+    "TargetContentNetwork": false,
+    "TargetPartnerSearchNetwork": false,
+    "PositiveGeoTargetType": 0,
+    "NegativeGeoTargetType": 0,
+    "DSADomainName": "",
+    "DSALanguageCode": "en",
+    "StartTime": "2026-04-01",
+    "EndTime": "2037-12-30",
+    "targetedLocations": [{ "id": "2840", "bidModifier": 0, "bidModifierSpecified": false }],
+    "excludedLocations": [],
+    "excludedIpAddresses": [],
+    "targetedLanguages": [{ "id": 1000 }],
+    "targetedPlatforms": [
+      { "id": 30001, "bidModifier": 0 },
+      { "id": 30002, "bidModifier": 0 },
+      { "id": 30000, "bidModifier": 0 }
+    ],
+
+    "adSchedules": [
+      { "DayOfWeekV2": 2, "startHour": 0, "StartMinuteV2": 2, "endHour": 24, "EndMinuteV2": 2 },
+      { "DayOfWeekV2": 3, "startHour": 0, "StartMinuteV2": 2, "endHour": 24, "EndMinuteV2": 2 },
+      { "DayOfWeekV2": 4, "startHour": 0, "StartMinuteV2": 2, "endHour": 24, "EndMinuteV2": 2 },
+      { "DayOfWeekV2": 5, "startHour": 0, "StartMinuteV2": 2, "endHour": 24, "EndMinuteV2": 2 },
+      { "DayOfWeekV2": 6, "startHour": 0, "StartMinuteV2": 2, "endHour": 24, "EndMinuteV2": 2 },
+      { "DayOfWeekV2": 7, "startHour": 0, "StartMinuteV2": 2, "endHour": 24, "EndMinuteV2": 2 },
+      { "DayOfWeekV2": 8, "startHour": 0, "StartMinuteV2": 2, "endHour": 24, "EndMinuteV2": 2 }
+    ],
+
+    "NegativeKeywordsForBatchJob": [
+      { "KeywordText": ["free", "cheap", "download"], "MatchTypeV2": "BROAD", "FinalURL": "" }
+    ],
+
+    "ExtensionsForBatchJob": [
+      {
+        "level": "Campaign",
+        "typeV2": "CALL",
+        "AssetFieldType": "CALL",
+        "Properties": { "ContryCode": "US", "PhoneNumber": "+1 800-555-0100" }
+      },
+      {
+        "typeV2": "SITELINK",
+        "Level": "Campaign",
+        "Properties": {
+          "Text": "About Us",
+          "Line2": "xxx",
+          "Line3": "xxxx",
+          "DestinationUrl": "https://www.example.com/about"
+        }
       }
-    },
-    {
-      "level": "Campaign",
-      "typeV2": "STRUCTURED_SNIPPET",
-      "AssetFieldType": "STRUCTURED_SNIPPET",
-      "StructuredSnippetHeaderValue": {
-        "key": "Services",
-        "value": ["Quality Certified", "Global Shipping", "24/7 Support"]
+    ],
+
+    "AdGroupsForBatchJob": [
+      {
+        "Name": "Core_Brand_Keywords",
+        "StatusV2": "Enabled",
+        "TypeV2": "SEARCH_STANDARD",
+        "RotationModeV2": "Unspecified",
+        "MaxCPCAmount": 1.5,
+
+        "KeywordsForBatchJob": [
+          {
+            "KeywordText": [
+              "brand name product",
+              "buy brand product online",
+              "brand official store"
+            ],
+            "MatchTypeV2": "BROAD",
+            "FinalURL": "https://www.example.com/products"
+          },
+          {
+            "KeywordText": ["\"brand name product\""],
+            "MatchTypeV2": "PHRASE",
+            "FinalURL": "https://www.example.com/products"
+          },
+          {
+            "KeywordText": ["[brand name product]"],
+            "MatchTypeV2": "EXACT",
+            "FinalURL": "https://www.example.com/products"
+          }
+        ],
+
+        "AdsForBatchJob": [
+          {
+            "_comment_finalurl": "Finalurl 与 DestinationUrl 填相同 URL；勿只写 DestinationUrl（BatchJob 会报 Finalurl 缺失）",
+            "TypeV2": "RESPONSIVE_SEARCH_AD",
+            "DestinationUrl": "https://www.example.com/products",
+            "Finalurl": "https://www.example.com/products",
+            "AdTitle": null,
+            "Path1": "products",
+            "Path2": "brand",
+            "headlinePart1": "Brand Name Official Store",
+            "headlinePart2": "Quality Products You Trust",
+            "headlinePart3": "Shop Direct From Brand",
+            "AddtionalHeadlines": [
+              "Fast Shipping Available",
+              "Certified Product Quality",
+              "Explore The Full Catalog",
+              "Trusted By Global Buyers",
+              "Request A Quote Today",
+              "Professional Grade Products",
+              "Browse Best Sellers Now",
+              "Reliable Supply Partner",
+              "Contact Us For Details"
+            ],
+            "adDescription": "Official products with certified quality. Contact us for pricing.",
+            "adDescription2": "Trusted by partners worldwide. Request a quote or browse the catalog.",
+            "AddtionalAdDescriptions": [
+              "Fast response from our sales team. See specs and certifications on our site.",
+              "Shop the full product line with reliable shipping and support options."
+            ]
+          }
+        ]
       }
-    }
-  ],
-  "extraAdGroups": [
-    {
-      "MaxCPCAmount": 150,
-      "Name": "通用词_行业词",
-      "StatusV2": "Enabled",
-      "TypeV2": "SEARCH_STANDARD",
-      "RotationModeV2": "Unspecified",
-      "KeywordsForBatchJob": [
-        {
-          "KeywordText": ["industry keyword 1", "industry keyword 2"],
-          "MatchTypeV2": "BROAD",
-          "Finalurl": "https://www.example.com"
-        }
-      ],
-      "AdsForBatchJob": [
-        {
-          "AdTitle": null,
-          "DestinationUrl": "https://www.example.com",
-          "Finalurl": "https://www.example.com",
-          "Path1": "",
-          "Path2": "",
-          "TypeV2": "RESPONSIVE_SEARCH_AD",
-          "headlinePart1": "Industry Leading Products",
-          "headlinePart2": "Certified Quality Standards",
-          "headlinePart3": "Get A Free Quote Today",
-          "AddtionalHeadlines": [
-            "Trusted By Global Partners",
-            "20+ Years Of Experience",
-            "Contact Us Now"
-          ],
-          "adDescription": "Top-quality industry products with global shipping. Contact us today!",
-          "adDescription2": "Certified standards and reliable delivery. Request a quote now!"
-        }
-      ]
-    }
-  ],
-  "draft": false
+    ]
+  }
 }

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

@@ -0,0 +1,238 @@
+# `ad campaign-create` JSON 配置说明
+
+`siluzan-tso ad campaign-create` **仅**接受 `--config-file` 指向的 JSON 文件
+
+**JSON 字段名保持 PascalCase**，与后端 `Campaign` / `CampaignCreationRecord` 契约一致；`ad campaign-validate` 阶段**不**改词面与结构。
+
+**`ad campaign-create` 提交前**，CLI 在 JSON 原文之外额外处理（不影响 validate 读到的「元」口径）：
+
+1. 剥除以 `_` 开头的注解键（如 `_meta`、`_comment_budget`、`_comment_finalurl`）；
+2. 外层 body：`account` → 数字 `customerId`；补全 `KeywordRecommendationsV2`（按广告组名，`Value` 可为 `[]`）；`googleDataRecordId` 缺省为 `""`（与 Web 智投一致）；
+3. `campaign` 金额字段「元」→「分」（×100）；
+4. `ExtensionsForBatchJob` 中 SITELINK 的 `Properties` 规范化（见下文「SITELINK」）。
+
+JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-template.json)。
+
+---
+
+## Agent 常见坑（实战）
+
+> 摘自真实创建流水：多次 `--json-out` 误用、validate 通过但 create 因 `Finalurl` 失败。提交前对照本表，避免重复踩坑。
+
+### CLI 参数（勿混用）
+
+| 命令 | 支持 `--json-out`？ | 推荐用法 |
+| ---- | :-----------------: | -------- |
+| `ad campaign-validate` | **否** | `siluzan-tso ad campaign-validate --config-file ./campaign.json` 或加 `--json`；规范化输出用 `--write-normalized ./campaign.normalized.json` |
+| `ad campaign-create` | **是**（较新版本） | 落盘任务响应：`--json-out ./snap-campaign`；与 `--json` 互斥。若报 `unknown option --json-out`，升级 `siluzan-tso` 或暂用 `--json` |
+| `ad batch get` / `ad batch diff` | **是** | 轮询与 diff 结果落盘，见 `references/tips.md` |
+
+**禁止**：对 `campaign-validate` 加 `--json-out`（会报参数不支持，浪费多轮重试）。
+
+### RSA 落地页：`Finalurl` 必填
+
+后端 BatchJob **要求**每条 `AdsForBatchJob[]` 带 **`Finalurl`**（小写 url）。仅写 `DestinationUrl` 时：
+
+- `ad campaign-validate` **可能仍显示通过**（校验用 `Finalurl ?? DestinationUrl` 只检查 URL 格式，不强制字段存在）；
+- `ad campaign-create` / BatchJob **会失败**（报 `Finalurl` 缺失类错误）。
+
+**正确写法**（两字段同值）：
+
+```json
+"DestinationUrl": "https://www.example.com/products",
+"Finalurl": "https://www.example.com/products",
+"AdTitle": null
+```
+
+生成 JSON 后可用脚本批量补全（勿手改几十条）：
+
+```python
+# 与实战 fix_campaign_v2.py 同逻辑：缺 Finalurl 则从 DestinationUrl 复制
+for ag in camp.get("AdGroupsForBatchJob", []):
+    for ad in ag.get("AdsForBatchJob", []):
+        if "Finalurl" not in ad:
+            ad["Finalurl"] = ad.get("DestinationUrl", "")
+        if "AdTitle" not in ad:
+            ad["AdTitle"] = None
+```
+
+### SITELINK 附加信息
+
+每条 `typeV2: "SITELINK"` 须同时有 **`AssetFieldType": "SITELINK"`**（模板已示例）。缺省时部分账户 BatchJob 会失败。
+
+### 推荐命令顺序（单系列）
+
+```bash
+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
+siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json --json-out ./snap-campaign
+```
+
+`Creating` 时每 5–10s 轮询 `batch get`，**勿**重复 `campaign-create`。
+
+---
+
+## Agent 编排
+
+流程、双轨入口、`campaign-validate` 门禁与分层规则阅读：**`references/google-ads-campaign-plan.md`**（本文件仅字段契约，不重复流水线）。
+
+一个 JSON 对应一个广告系列；多系列使用多个 JSON 文件（可选 `campaign-manifest.json`，见 campaign-plan）。
+
+**提交前自检（代码改 JSON，不手填 Markdown）：**
+
+1. 每条 RSA：`Finalurl` 与 `DestinationUrl` 同值；可选 `AdTitle: null`；
+2. 每条 SITELINK：`AssetFieldType` = `SITELINK`；
+3. `ad campaign-validate` 通过（**不加** `--json-out`）；
+4. 用户确认后再 `campaign-create`。
+
+---
+
+## 外层字段（CampaignCreationRecord）
+
+| 字段                   | 类型                | 必填 | 说明                                                                                                   |
+| ---------------------- | ------------------- | :--: | ------------------------------------------------------------------------------------------------------ |
+| `account`              | string              |  ✅  | 媒体账户 ID；提交时转为数字 `customerId`（勿依赖引号字符串）                                            |
+| `customerName`         | string              |  ✅  | 须与 `list-accounts` 的 `mediaAccountName` **完全一致**，否则 `customer name error`                    |
+| `name`                 | string              |      | 智投 `campaignName`；缺省取 `campaign.Name`；账户内不得与已有在投/暂停系列重名，否则 BatchJob 系列创建失败 |
+| `url`                  | string              |      | 智投展示用 URL；后端只读，用于回显                                                                     |
+| `locations`            | string[]            |      | 展示用地区名（后端只读，可空数组）                                                                     |
+| `productWords`         | string[]            |      | 智投/推荐用产品核心词                                                                                  |
+| `googleDataRecordId`   | string \| null      |      | 智投记录 ID；省略时提交 `""`（与 Web 智投一致）                                                        |
+| `draft`                | boolean             |      | `false`（默认）立即发布到 Google；`true` 仅保存草稿，需后续 `ad batch publish`                         |
+| `campaign`             | object              |  ✅  | 内层 Campaign 对象，见下表                                                                             |
+
+> 提交时 CLI 另附 `KeywordRecommendationsV2`：`[{ Key: <广告组 Name>, Value: [] }, …]`，与 Web `/advertising/AICreation` 结构一致；JSON 文件内无需手写。
+
+---
+
+## 内层字段（`campaign` 对象）
+
+> **金额单位**：JSON 中以「元」填写，CLI 提交前 ×100 转为「分」（与后端 `Budget`、`MaxCPCAmount` 等字段一致）。
+> 涉及字段：`Budget`、`TargetSpend_BidCeilingAmount`、`TargetCpa_BidingAmount`、`TargetCpaAmount`、`MaxCPCAmount`、`MaxCpmAmount`、`MaxCPVAmount`、`MaxCPC`。
+
+### 基础
+
+| 字段                            | 类型                  | 必填 | 说明                                                                  |
+| ------------------------------- | --------------------- | :--: | --------------------------------------------------------------------- |
+| `Name`                          | string                |  ✅  | 广告系列名；须与外层 `name` 一致；账户内唯一（在投/暂停不可重名）                                      |
+| `StatusV2`                      | "Enabled" \| "Paused" |      | 默认 `Enabled`                                                        |
+| `ChannelTypeV2`                 | string                |      | 搜索系列填 `SEARCH`                                                   |
+
+### 预算与出价
+
+| 字段                                  | 类型                                                  | 必填条件                       | 说明                                       |
+| ------------------------------------- | ----------------------------------------------------- | ------------------------------ | ------------------------------------------ |
+| `Budget`                              | number                                                | ✅ > 0                          | 日预算（元）                               |
+| `BudgetShared`                        | boolean                                               |                                | 共享预算时为 true                          |
+| `BudgetId`                            | number / string                                       |                                | 共享预算 id                                |
+| `BudgetBudgetDeliveryMethodV2`        | "STANDARD" \| "ACCELERATED" \| "UNSPECIFIED" \| "UNKNOWN" |                            | 默认 STANDARD                              |
+| `BiddingStrategyTypeV2`               | "TARGET_SPEND" \| "MANUAL_CPC" \| "TARGET_CPA" \| "TARGET_ROAS" \| "MAXIMIZE_CONVERSIONS" \| "MAXIMIZE_CONVERSION_VALUE" | ✅ | 出价策略 |
+| `TargetSpend_BidCeilingAmount`        | number                                                | TARGET_SPEND 时 ✅              | 每次点击费用上限（元）                     |
+| `TargetCpa_BidingAmount`              | number                                                | TARGET_CPA 时 ✅                | 目标 CPA（元）                             |
+| `TargetRoas`                          | number                                                | TARGET_ROAS 时 ✅               | 目标 ROAS（如 2.5 表示 250%）              |
+| `ManualCpc_EnhancedCpcEnabled`        | boolean                                               |                                | 是否增强 CPC                               |
+
+### 网络（后端硬约束）
+
+| 字段                            | 类型    | 说明                                                                                          |
+| ------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `TargetGoogleSearch`            | boolean | 默认 true；当 `TargetSearchNetwork=true` 时**必须** true                                       |
+| `TargetSearchNetwork`           | boolean | Google 搜索网络合作伙伴；产品默认建议 false                                                   |
+| `TargetContentNetwork`          | boolean | 展示网络；搜索专属方案建议 false                                                              |
+| `TargetPartnerSearchNetwork`    | boolean | **必须 false**（后端拒绝：cannot set TargetPartnerSearchNetwork）                              |
+
+### 地理 / 语言 / 平台
+
+| 字段                  | 类型                                          | 必填 | 说明                                                                |
+| --------------------- | --------------------------------------------- | :--: | ------------------------------------------------------------------- |
+| `targetedLocations`   | `{ id: string, bidModifier?: number }[]`      |  ✅  | 至少 1 个；先 `siluzan-tso ad geo search -a <acct> -q <地区名>`     |
+| `excludedLocations`   | 同上                                          |      | 排除地区                                                            |
+| `targetedLanguages`   | `{ id: number }[]`                            |  ✅  | 英语 1000，中文 1017                                                |
+| `targetedPlatforms`   | `{ id: number, bidModifier?: number }[]`      |      | 30001 桌面 / 30002 平板 / 30000 移动                                |
+| `excludedIpAddresses` | string[]                                      |      | 排除 IP                                                             |
+| `PositiveGeoTargetType` | number                                      |      |                                                                     |
+| `NegativeGeoTargetType` | number                                      |      |                                                                     |
+
+### 时间与 DSA
+
+| 字段              | 类型                | 说明                                                            |
+| ----------------- | ------------------- | --------------------------------------------------------------- |
+| `StartTime`       | YYYY-MM-DD          | 开始日期                                                        |
+| `EndTime`         | YYYY-MM-DD          | 结束日期（必须晚于 StartTime）                                  |
+| `adSchedules`     | object[]            | 投放时段，缺省可填全周全天（见模板）                            |
+| `DSADomainName`   | string              | 动态搜索广告域名                                                |
+| `DSALanguageCode` | string              | 默认 `en`                                                       |
+
+### 子结构
+
+| 字段                            | 类型     | 说明                                                                          |
+| ------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| `AdGroupsForBatchJob`           | object[] | **至少 1 组**；见下                                                           |
+| `NegativeKeywordsForBatchJob`   | object[] | 系列级否词；元素：`{ KeywordText: string[], MatchTypeV2: "BROAD", FinalURL: "" }` |
+| `ExtensionsForBatchJob`         | object[] | 附加信息；`Properties` 须 **string→string**（勿用数组值）。SITELINK 见下表 |
+
+#### SITELINK（`ExtensionsForBatchJob[i]`，`typeV2` / `AssetFieldType` = `SITELINK`）
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `typeV2` | string | 必填 `SITELINK` |
+| `AssetFieldType` | string | **必填** `SITELINK`（与 `typeV2` 一致；缺省会导致部分账户 BatchJob 失败） |
+| `level` / `Level` | string | 系列级填 `Campaign` |
+| `Properties` | object | 键值均为字符串；见下表 |
+| `Properties.Text` | string | 链接文字（必填）。可写 `LinkText`，提交前会映射为 `Text` |
+| `Properties.Line2` | string | 描述行 1，**≤ 25 字符**。可写 `Description1`，提交前映射为 `Line2` |
+| `Properties.Line3` | string | 描述行 2，**≤ 25 字符**；**不可省略或空字符串**（Google V20 不允许 null，空时 CLI 用 `Line2` 回填）。可写 `Description2` |
+| `Properties.DestinationUrl` | string | 落地页 URL（必填）。**勿**写 `FinalUrls` 数组——会导致 TSO 无法反序列化整包 body（`campaign creation record is null`） |
+
+---
+
+## 广告组（`AdGroupsForBatchJob[i]`）
+
+| 字段                  | 类型                  | 必填 | 说明                                                                            |
+| --------------------- | --------------------- | :--: | ------------------------------------------------------------------------------- |
+| `Name`                | string                |  ✅  | 组名；用于提交体 `KeywordRecommendationsV2[].Key`                             |
+| `StatusV2`            | "Enabled" \| "Paused" |      | 默认 Enabled                                                                    |
+| `TypeV2`              | string                |      | 搜索系列填 `SEARCH_STANDARD`                                                    |
+| `RotationModeV2`      | string                |      | 一般 `Unspecified`                                                              |
+| `MaxCPCAmount`        | number                |  ✅(MANUAL_CPC)  | 元；MANUAL_CPC 出价策略必须 > 0                                       |
+| `KeywordsForBatchJob` | object[]              |      | 见下                                                                            |
+| `AdsForBatchJob`      | object[]              |      | 见下                                                                            |
+
+### 关键词块（`KeywordsForBatchJob[j]`）
+
+每个块描述一组**同匹配类型**的关键词：
+
+| 字段          | 类型                              | 说明                                                                  |
+| ------------- | --------------------------------- | --------------------------------------------------------------------- |
+| `KeywordText` | string[]                          | 关键词词面数组；PHRASE 应写 `"keyword"`，EXACT 应写 `[keyword]`       |
+| `MatchTypeV2` | "BROAD" \| "PHRASE" \| "EXACT"    | 与词面格式对应                                                        |
+| `FinalURL`    | string                            | 关键词级落地页                                                        |
+
+### 创意块（`AdsForBatchJob[j]`，RSA）
+
+| 字段                          | 类型     | 必填 | 说明                                          |
+| ----------------------------- | -------- | :--: | --------------------------------------------- |
+| `TypeV2`                      | string   |      | RSA 填 `RESPONSIVE_SEARCH_AD`                  |
+| `DestinationUrl`              | string   |  ✅  | 展示/编辑用落地页 URL                         |
+| `Finalurl`                    | string   |  ✅  | **后端 BatchJob 必填**；与 `DestinationUrl` 填**相同** URL。勿只写前者——validate 可能仍通过，create 会失败 |
+| `AdTitle`                     | null \| string |  | 可选；无标题时写 `null`（与 Web 智投一致）   |
+| `Path1` / `Path2`             | string   |  ✅  | 显示路径（**必填**，缺/null 会导致后端 BatchJob `ArgumentNullException`）；**≤ 15 字符**（CJK 按 2 计）；小写 a-z、数字、连字符 |
+| `headlinePart1/2/3`           | string   |  ✅  | 前 3 条标题；**每条 ≤ 30 字符**（CJK 按 2 计） |
+| `AddtionalHeadlines`          | string[] |      | 第 4–15 条标题（合计 ≤ 15）                   |
+| `adDescription` / `adDescription2` | string |  ✅  | 前 2 条描述；**每条 ≤ 90 字符**            |
+| `AddtionalAdDescriptions`     | string[] |      | 第 3–4 条描述（合计 ≤ 4）                     |
+
+---
+
+## 校验规则（CLI 镜像后端）
+
+| 来源                                                                                       | 规则                                                                                                |
+| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `CampaignCommandController.CreateCampaignAsync`                                            | `customerName` 非空 / `campaign` 非空                                                              |
+| `CampaignCommandController` 行 94–106                                                      | `campaign.TargetPartnerSearchNetwork` 必须 false；`!TargetGoogleSearch && TargetSearchNetwork` 拒绝 |
+| Google Ads BatchJob                                                                         | RSA `Path1`/`Path2` 必填（缺/null → 后端 ArgumentNullException）；字段数与字符上限；关键词词面非空；SITELINK `Line2`/`Line3` ≤25 字且不可 null |
+| CLI 实务                                                                                    | `Budget > 0`、地理/语言至少 1 项、日期格式与先后、出价策略与配套字段                                |
+
+`ad campaign-validate` 通过不保证 BatchJob 成功（例如仅写 `DestinationUrl` 未写 `Finalurl` 时 validate 仍可能 ✅）。异步结果用 `ad batch get` 轮询；`HasFailed` / 部分失败时用 `ad batch diff` 对照 JSON 补缺，系列级失败时改 JSON 重提，勿在半成品上反复整包创建。写操作须 `--commit`，见 `references/google-ads.md` § ad campaign-create。

package/dist/skill/references/account-analytics.md

@@ -76,14 +76,21 @@
 
 ### 金额单位
 
-- **永远使用 `*Display` 字段**（如 `maxCPCAmountDisplay`），不得将 `maxCPCAmount` 等 ×100 分单位直接当金额展示。**例外**：`siluzan-tso ad campaigns` 列表的 **`--json`/`--json-out` 中 `budget` 已由 CLI 换为「元」**，可直接作用户可见日预算，勿再 ÷100。
-- **`google-analysis` 落盘 `campaigns-<id>.json`（`CampaignSectionData`）特例**：响应里常见只有 **`budgetAmount`（无 `budgetDisplay`）**。该字段与网关 **`Budget` 同为「分」整数**（主币种 ×100），换算为元须 **÷100**。**禁止**误用 Google Ads API 的**微元**去 **÷1_000_000**，否则日预算会约偏小 **一万倍**（例如 `15000` 应为 ¥150.00，误除微元会得到 ¥0.015）。同文件 **`spend`、`averageCpc`、`costPerConversion` 等已是「元」小数**，与 `budgetAmount` 单位不同，写 Excel/报告脚本时须分支处理。对应 `*.outline.txt` 内写有**同等硬提示**（`campaigns` 维度）。
-- 金额保留 2 位小数，带货币代码（如 `¥50.00 CNY`），`currencyCode` 从响应读取。跨币种账户分表。
-- CNY使用 ￥50，USD使用 $50 不要混用！！！
+CLI 出口的所有 JSON / 表格金额已统一为**元**，关键字段：
+
+| 命令 / Section                                      | 元字段                                                                                                                                    |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ad campaigns --json`                               | `budget`（元，与 `--budget` 写参同口径）                                                                                                  |
+| `ad groups --json`                                  | `maxCPCAmountYuan`、`targetCpaAmountYuan`                                                                                                 |
+| `google-analysis campaigns` 落盘 `campaigns-*.json` | `budgetAmountYuan`、`campaignTargetCpaYuan`、`maximizeConversionsTargetCpaYuan`；同行 `spend` / `averageCpc` / `costPerConversion` 也是元 |
+| `keyword suggest --json`                            | `averageCpc`、`lowTopOfPageBid`、`highTopOfPageBid`；`bidAmountCurrency`（有 `-a` 为账户币；无 `-a` 为 USD，可选 `averageCpcCNY` 参考） |
+| `balance` 等账户余额接口                            | `remainingAccountBudget`（元）                                                                                                            |
+
+旧字段 `budgetAmount`（分）、`maxCPCAmountDisplay`、`*Micros`（微元）**已不再落盘**，下游脚本无需做单位换算。金额保留 2 位小数，带货币代码（如 `￥50.00 CNY`、`$50.00 USD`），`currencyCode` 从响应读取，跨币种账户分表；细则见 `references/currency.md`。
 
 ### 预算建议
 
-基于当前实际预算（如 `ad campaigns --json` 的 **`budget`（元）** 或报表中的 `*Display`/分析字段）、历史日均消耗、用户给的预算上限给出建议。数据不足以判断时，在报告里写明「建议区间需用户确认」而非直接给高风险数字。
+基于当前实际预算（如 `ad campaigns --json` 的 `budget`（元）或 `google-analysis campaigns-*.json` 的 `budgetAmountYuan`（元））、历史日均消耗、用户给的预算上限给出建议。数据不足以判断时，在报告里写明「建议区间需用户确认」而非直接给高风险数字。
 
 ---
 
@@ -108,38 +115,38 @@ siluzan-tso google-analysis -a <id> --exclude materials,gold-account --json-out
 
 ### 选项
 
-| 选项                     | 说明                                                                                 |
-| ------------------------ | ------------------------------------------------------------------------------------ |
-| `-a, --account <id>`     | Google `mediaCustomerId`（必填）                                                     |
-| `--json-out <dir>`       | 必填；每维一个 `<section>-<accountId>.json` + `manifest-<accountId>.json`            |
-| `--sections <list>`      | 仅执行指定维度（逗号分隔）；省略=全部 23 个                                          |
-| `--exclude <list>`       | 排除指定维度；与 `--sections` 可叠加                                                 |
-| `--start` / `--end`      | 统计区间（YYYY-MM-DD）；省略=近 7 天截至昨天；`final-urls`/`campaign-types` 自动忽略 |
-| `--concurrency <n>`      | 并发数，默认 5，上限 16                                                              |
-| `--limit <n>`            | 透传给 `keywords`/`search-terms`（默认 **200**，`orderByCost=true`）                                 |
-| `--level <lvl>`          | 透传给 `extensions`（Account/Campaign/Ad Group）                                     |
-| `--audience-type <type>` | 透传给 `audience`（SystemDefined/UserDefined）                                       |
-| `--no-order-by-cost`     | 透传给 `keywords`/`search-terms`                                                     |
-| `--cost-greater <n>`     | 仅 **`campaign-geo`**：网关 `costGreater`（整数，单位以后端为准）                    |
-| `--click-greater <n>`    | 仅 **`campaign-geo`**：网关 `clickGreater`                                           |
-| `--conversions-greater <n>` | 仅 **`campaign-geo`**：网关 `conversionsGreater`                                    |
-| `--verbose`              | 打印详细错误                                                                         |
+| 选项                        | 说明                                                                                 |
+| --------------------------- | ------------------------------------------------------------------------------------ |
+| `-a, --account <id>`        | Google `mediaCustomerId`（必填）                                                     |
+| `--json-out <dir>`          | 必填；每维一个 `<section>-<accountId>.json` + `manifest-<accountId>.json`            |
+| `--sections <list>`         | 仅执行指定维度（逗号分隔）；省略=全部 23 个                                          |
+| `--exclude <list>`          | 排除指定维度；与 `--sections` 可叠加                                                 |
+| `--start` / `--end`         | 统计区间（YYYY-MM-DD）；省略=近 7 天截至昨天；`final-urls`/`campaign-types` 自动忽略 |
+| `--concurrency <n>`         | 并发数，默认 5，上限 16                                                              |
+| `--limit <n>`               | 透传给 `keywords`/`search-terms`（默认 **200**，`orderByCost=true`）                 |
+| `--level <lvl>`             | 透传给 `extensions`（Account/Campaign/Ad Group）                                     |
+| `--audience-type <type>`    | 透传给 `audience`（SystemDefined/UserDefined）                                       |
+| `--no-order-by-cost`        | 透传给 `keywords`/`search-terms`                                                     |
+| `--cost-greater <n>`        | 仅 **`campaign-geo`**：网关 `costGreater`（整数，单位以后端为准）                    |
+| `--click-greater <n>`       | 仅 **`campaign-geo`**：网关 `clickGreater`                                           |
+| `--conversions-greater <n>` | 仅 **`campaign-geo`**：网关 `conversionsGreater`                                     |
+| `--verbose`                 | 打印详细错误                                                                         |
 
 ### 维度列表（23 个）
 
 | 维度                 | 说明                                                                                                |
 | -------------------- | --------------------------------------------------------------------------------------------------- |
 | `overview`           | 总览（实时，可查当天；当天高消耗账号排行首选）                                                      |
-| `keywords`           | 关键词；默认 `limit=200`、`orderByCost=true`；可用 `--limit`、`--no-order-by-cost` 覆盖              |
-| `search-terms`       | 搜索词；默认 `limit=200`、`orderByCost=true`；可用 `--limit`、`--no-order-by-cost` 覆盖              |
+| `keywords`           | 关键词；默认 `limit=200`、`orderByCost=true`；可用 `--limit`、`--no-order-by-cost` 覆盖             |
+| `search-terms`       | 搜索词；默认 `limit=200`、`orderByCost=true`；可用 `--limit`、`--no-order-by-cost` 覆盖             |
 | `campaigns`          | 广告系列                                                                                            |
 | `campaign-hour`      | 系列按小时（根为 JSON 数组）                                                                        |
 | `ads`                | 广告；与 `ad list` 同源                                                                             |
 | `extensions`         | 附加信息；可选 `--level`                                                                            |
 | `devices`            | 设备分布（账户级 `DeviceSectionData`）                                                              |
-| `geographic`         | 地域分布（账户级 `GeographicSectionData`，网关侧常按国家聚合）                                    |
+| `geographic`         | 地域分布（账户级 `GeographicSectionData`，网关侧常按国家聚合）                                      |
 | `campaign-geo`       | 广告系列维度地理 （可选 `--cost-greater` / `--click-greater` / `--conversions-greater` 与网关一致） |
-| `campaign-device`    | 广告系列维度设备 （行可含系列/组）      |
+| `campaign-device`    | 广告系列维度设备 （行可含系列/组）                                                                  |
 | `audience`           | 受众；可选 `--audience-type`                                                                        |
 | `asset-images`       | 图片素材                                                                                            |
 | `videos`             | 视频                                                                                                |
@@ -191,19 +198,19 @@ siluzan-tso google-analysis -a <id> --exclude materials,gold-account --json-out
 
 CLI 在落盘前为以下维度自动补「中文译名字段」（**原英文字段保留**，便于排错；字典未命中时该字段缺省）：
 
-| 维度          | 源字段（英文）     | 新增字段（中文）       | 字典源                                                          |
-| ------------- | ------------------ | ---------------------- | --------------------------------------------------------------- |
-| `keywords`    | `keywordMatchType` | `keywordMatchTypeZh`   | `match-type-en2zh.json`（覆盖 `BROAD/PHRASE/EXACT` 大小写写法） |
-| `search-terms`| `matchType`        | `matchTypeZh`          | `match-type-en2zh.json`                                         |
-| `campaign-geo`| `countryOrRegion`  | `countryOrRegionZh`    | `geo-en2zh.json`（覆盖 105 个国家/地区）                        |
+| 维度           | 源字段（英文）     | 新增字段（中文）     | 字典源                                                          |
+| -------------- | ------------------ | -------------------- | --------------------------------------------------------------- |
+| `keywords`     | `keywordMatchType` | `keywordMatchTypeZh` | `match-type-en2zh.json`（覆盖 `BROAD/PHRASE/EXACT` 大小写写法） |
+| `search-terms` | `matchType`        | `matchTypeZh`        | `match-type-en2zh.json`                                         |
+| `campaign-geo` | `countryOrRegion`  | `countryOrRegionZh`  | `geo-en2zh.json`（覆盖 105 个国家/地区）                        |
 
 写 Excel / 报表脚本可直接读 `keywordMatchTypeZh` / `matchTypeZh` / `countryOrRegionZh` 输出中文，**不要**自己维护字典或在线翻译。判断覆盖率用 `if (row.xxxZh)` 即可。
 
 ### CampaignSectionData 关键字段
 
-`campaigns[]` 每行额外包含：`conversionsValue`、`conversionsValuePerCost`（`spend ≤ 0` 时为 0）、`campaignTargetCpaMicros`、`maximizeConversionsTargetCpaMicros`、`manualCpcEnhancedCpcEnabled`、`percentCpcEnhancedCpcEnabled`。micros 字段须按 `currencyCode` 换算，不要直接当元展示。
+`campaigns[]` 每行额外包含：`conversionsValue`、`conversionsValuePerCost`（`spend ≤ 0` 时为 0）、`campaignTargetCpaYuan`、`maximizeConversionsTargetCpaYuan`、`manualCpcEnhancedCpcEnabled`、`percentCpcEnhancedCpcEnabled`。所有金额字段（`*Yuan` 后缀）已统一为元，可直接展示，无需换算。
 
-**`budgetAmount`（再强调）**：**分**（÷100 → 元），**禁止 ÷1e6**；与 `tso-cli/src/commands/ad/_shared.ts` 中系列预算读写「分」口径一致。Python/Excel 脚本示例：`日预算元 = (row.get("budgetAmount") or 0) / 100`。
+日预算字段为 `budgetAmountYuan`（元），脚本可直接 `row.get("budgetAmountYuan")`；网关原始 `budgetAmount`（分）已不再落盘。
 
 ### campaign-hour 字段