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

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

@@ -6,7 +6,7 @@
 
 ## 金额单位（全局重要）
 
-> **所有 CLI 金额参数均按「主币种金额」传入**（如 `1.5` = ¥1.50 / $1.50），CLI 内部 `Math.round(value × 100)` 写入后端「分」字段。
+> **所有 CLI 金额参数均按「主币种金额」传入**（如 `1.5` = ¥1.50 / $1.50）
 > **唯一例外**：`ad keyword-edit --max-cpc` 单位为「主币种元」（直接透传，不做 ×100 转换）。
 > **禁止** 按 Google micros（×1,000,000）填写任何金额参数。
 
@@ -24,76 +24,22 @@
 
 ---
 
-## 新建广告系列的流程
+## 新建广告系列（方案 + 创建）
 
-> **强制流程（AI 必须严格遵守）**
-> 1）完整阅读所有规则文档 → 2）向用户补齐关键信息 → 3）在规则约束下设计广告计划 → 4）按模板输出方案并获得用户「明确确认」 → 5）**仅在已确认的前提下**执行任何结构性改动。
-
-### 第一步：规则文档阅读（不得跳过）
-
-操作开始前，**AI 必须先阅读完下面所有文档**，严禁只读 `google-ads-launch-plan-template.md` 就直接出方案。
-
-| 文档地址                                                     | 文档内容                                                                      |
-| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `references/google-ads-rules/google-ads-compliance.md`       | 关键词 & 文案审核规则、编辑规范、禁止内容、商标规则                           |
-| `references/google-ads-rules/sensitive-industries.md`        | 酒精/赌博/金融/加密/医疗等 15 个敏感行业规则                                  |
-| `references/google-ads-rules/google-ads-keyword-strategy.md` | 匹配类型策略、分组结构、否定词技巧、出价意图分层                              |
-| `references/google-ads-rules/google-ads-keyword-optimization.md` | 基于数据的迭代优化闭环                                                    |
-| `references/google-ads-rules/google-ads-creative-optimization.md` | RSA 主题法、Ad Strength、A/B 测试、附加信息优化                        |
-| `references/google-ads-rules/google-ads-campaign-optimization.md` | 系列类型选择、出价策略、转化追踪、预算优化                            |
-| `references/google-ads-rules/google-ads-launch-plan-template.md` | **投放计划确认模板**（用户确认后再执行）                              |
-| `references/google-ads-rules/google-ads-account-audit.md`    | 账户诊断三层审计框架                                                          |
-| `references/google-ads-rules/google-ads-conversion-architecture.md` | 转化信号架构（L1-L5）、Enhanced Conversions、Consent Mode             |
-| `references/google-ads-rules/google-ads-audience-strategy.md` | 受众类型、再营销分层、Customer Match                                         |
-| `references/google-ads-rules/google-ads-pmax-guide.md`       | PMax 与 Demand Gen 深度运营                                                    |
-
-**搜索广告方案 — 落地页 URL 推断**：用户只提供官网首页时，参阅 `references/google-ads-rules/google-ads-landing-page-discovery-via-webfetch.md`（**不向用户复述工具名**）。
-
-> **AI Agent 要求：**
-> - 未读完全部文档前，不得生成广告计划或文案。
-> - 首次阅读后，向用户简要复述 3～5 条与本次任务强相关的合规/策略要点。
-> - 生成的关键词、文案、出价与结构必须显式遵守规则；与规则冲突时以规则优先。
-> - **方案阶段措辞**：用「方案草案 / 待你确认后再执行」等表述，避免暗示可跳过用户确认。回复开头列出已读规则文档清单。
-
-### 第二步：向用户补齐关键信息
-
-AI 应最少确认以下信息：
-- **业务与转化目标**：行业、主营产品/服务、转化动作（表单/电话/下单等）。
-- **目标地区与语言**：投放国家/地区、语言组合。
-- **预算与节奏**：日预算区间、活动档期、试错周期。
-- **历史投放情况**：是否有历史数据、必须保留/禁止的词或文案。
-- **合规与品牌限制**：敏感行业、品牌词/法律风控要求等。
-
-### 第三步：根据规则与信息生成计划并确认
-
-按 `references/google-ads-rules/google-ads-launch-plan-template.md` 生成计划，与用户沟通确认。方案中必须：
-- 引用并遵守规则文档关键条款，标注来源。
-- 解释核心决定依据（匹配结构、排除词、出价策略）。
-- 列出风险点与替代方案。
-
-**只有用户明确表示「同意/确认按此方案执行」后**，才能执行操作。
-
-> 即使用户要求跳过方案直接创建，也必须先输出完整 Markdown 投放方案并列出已参考的规则文档。
-
-- 创建失败处理：
-  - 部分失败：获取失败子项，用对应命令重新创建
-  - 完全失败：直接重新创建
+> **流程与校验**：`references/google-ads-campaign-plan.md`。本文件只写 **命令参数**（`campaign-validate` / `campaign-create` / `batch` 见下文各节）。
 
 ---
 
 ## 广告的编辑
 
-创建后的修改不能通过 `campaign-create` 覆盖，需用对应命令。任何编辑前都要读取 `references/google-ads-rules/google-ads-launch-plan-template.md` 确认输出格式。
-
-### 广告修改
-- 基于 `references/google-ads-rules/*.md` 评估修改内容
-- 读取 launch-plan-template 对应章节，按格式输出给用户确认
-- 使用 `ad -h` 查询可用命令，执行后用获取命令校验
+已上线系列勿用 `campaign-create` 覆盖；改方案/重建见 **`google-ads-campaign-plan.md`** § 已上线后的修改；分步 CRUD 用下文 `ad *-edit` 等，写后读命令复核。
 
 ### 广告新增
+
 参考修改流程，将修改命令替换为新增命令。
 
 ### 广告优化
+
 参考修改流程，增加新旧对照表格。
 
 ---
@@ -101,65 +47,121 @@ AI 应最少确认以下信息：
 ## ad campaigns — 广告系列管理
 
 ### 查询列表
+
 ```bash
 siluzan-tso ad campaigns -a <accountId> [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>] [--json]
 ```
+
 `--json` 下 `budget` 为日预算（主币种「元」，CLI 已 ÷100），另有 `statusDisplay`（状态文案）。
 
 ### 启停
+
 ```bash
 siluzan-tso ad campaign-status -a <accountId> --id <campaignId> --status <Enabled|Paused>
 ```
 
 ### 删除
+
 ```bash
 siluzan-tso ad campaign-delete -a <accountId> --id <campaignId>
 ```
+
 > 删除不可逆，建议先 `campaigns` 确认名称。
 
 ---
 
+## 批量创建工作流（adgroup + keyword + ad + extension）
+
+适用：从 Excel/JSON 任务清单一次性创建多个广告组及其内容。`adgroup-create` / `keyword-create` / `ad-create` / `extension <type>` 均已支持 **`--json`**，网关响应里直接含 `id`，**无需**再 `ad groups --json` 反查。
+
+**推荐节奏**（每广告组）：
+
+```bash
+# 1. 创建广告组 → 拿 adgroupId
+out=$(siluzan-tso ad adgroup-create -a <accountId> \
+  --campaign-id <campaignId> --campaign-name <campaignName> \
+  --name "<adgroupName>" --max-cpc 2.0 --status ENABLED --json)
+adgroupId=$(echo "$out" | jq -r '.id')
+
+# 2. 添加关键词（已是单组批量，传逗号分隔关键词）
+siluzan-tso ad keyword-create -a <accountId> \
+  --adgroup-id "$adgroupId" --adgroup-name "<adgroupName>" \
+  --campaign-id <campaignId> --campaign-name <campaignName> \
+  --keywords "kw1,\"kw2\",[kw3]" --final-url "https://..." --json
+
+# 3. 添加 RSA 广告
+siluzan-tso ad ad-create -a <accountId> \
+  --adgroup-id "$adgroupId" --adgroup-name "<adgroupName>" \
+  --final-url "https://..." \
+  --headlines "标题1,标题2,标题3,..." \
+  --descriptions "描述1,描述2,..." \
+  [--path1 <path1>] [--path2 <path2>] --json
+
+# 4. 系列层 Sitelinks（每条 1 次调用，逐条循环）
+for sitelink in "${SITELINKS[@]}"; do
+  siluzan-tso ad extension sitelink -a <accountId> \
+    --level Campaign --campaign-id <campaignId> \
+    --text "..." --url "..." [--line2/--line3 ...] --json
+done
+```
+
+**幂等性（Agent 侧）**：CLI 当前无 `--idempotent` 参数，请脚本侧先用 `ad groups --json` / `ad keywords --json` / `ad list --json` / `ad extension list --json` 取已有实体清单，按 `name + adgroupId` 等键过滤待创建项；HTTP 400 多半是重复创建，建议捕获并跳过。
+
+**字符上限**（Agent 侧校验）：标题 ≤30、描述 ≤90、CALLOUT ≤25、Sitelink Text ≤25。CJK 字符按 2 计（Google 规范），`google-ads-rules/google-ads-compliance.md` 有详细规则。
+
+---
+
 ## ad groups — 广告组管理
 
 ### 查询列表
+
 ```bash
 siluzan-tso ad groups -a <accountId> [--start/--end <date>] [--json]
 ```
 
 ### 创建
+
 ```bash
 siluzan-tso ad adgroup-create \
   -a <accountId> \
   --campaign-id <campaignId> --campaign-name <campaignName> \
   --name <adGroupName> --max-cpc <主币种金额> \
-  [--status ENABLED|PAUSED]
+  [--status ENABLED|PAUSED] [--json | --json-out <path>]
 ```
 
-| 选项 | 说明 | 必填 |
-| --- | --- | --- |
-| `-a, --account <id>` | Google mediaCustomerId | ✅ |
-| `--campaign-id <id>` | 所属广告系列 ID | ✅ |
-| `--campaign-name <name>` | 所属广告系列名称 | ✅ |
-| `--name <name>` | 广告组名称 | ✅ |
-| `--max-cpc <amount>` | 最高 CPC（主币种金额） | ✅ |
-| `--status` | `ENABLED`（默认）/ `PAUSED` | |
+| 选项                     | 说明                                                               | 必填 |
+| ------------------------ | ------------------------------------------------------------------ | ---- |
+| `-a, --account <id>`     | Google mediaCustomerId                                             | ✅   |
+| `--campaign-id <id>`     | 所属广告系列 ID                                                    | ✅   |
+| `--campaign-name <name>` | 所属广告系列名称                                                   | ✅   |
+| `--name <name>`          | 广告组名称                                                         | ✅   |
+| `--max-cpc <amount>`     | 最高 CPC（主币种金额）                                             | ✅   |
+| `--status`               | `ENABLED`（默认）/ `PAUSED`                                        |      |
+| `--json` / `--json-out`  | 输出网关返回的完整 adgroup 对象（含 `id` / `maxCPCAmountYuan` 等） |      |
+
+**返回字段（--json）**：网关同步返回完整 adgroup，含 **`id`**（adgroupId）、`name`、`campaignId`、`statusV2`、`maxCPCAmountYuan`（元，CLI 已 ÷100）、`typeV2: "SEARCH_STANDARD"` 等 75+ 字段。批量创建脚本应直接读 `id`，**不需要**再次 `ad groups --json` 反查。
 
 ### 启停
+
 ```bash
 siluzan-tso ad adgroup-status -a <accountId> --id <adGroupId> --status <Enabled|Paused>
 ```
 
 ### 编辑
+
 先用 `ad groups --json` 查看当前值，再只改传入字段。
+
 ```bash
 siluzan-tso ad adgroup-edit \
   -a <accountId> --id <adGroupId> \
   [--name <新名称>] [--max-cpc <主币种金额>] [--target-cpa <主币种金额>] \
   [--start/--end <YYYY-MM-DD>]
 ```
-`--max-cpc` / `--target-cpa` 与 `ad groups --json` 中 `maxCPCAmountDisplay` / `targetCpaAmountDisplay` 对齐。
+
+`--max-cpc` / `--target-cpa` 与 `ad groups --json` 中 `maxCPCAmountYuan` / `targetCpaAmountYuan` 对齐（**元**，CLI 出口已统一）。
 
 ### 删除
+
 ```bash
 siluzan-tso ad adgroup-delete -a <accountId> --id <adGroupId>
 ```
@@ -169,15 +171,19 @@ siluzan-tso ad adgroup-delete -a <accountId> --id <adGroupId>
 ## ad list — 广告创意管理
 
 ### 查询列表
+
 ```bash
 siluzan-tso ad list -a <accountId> [--start/--end <date>] [--include-deleted] [--json]
 ```
+
 `--include-deleted` 用于审计/排障，会多传 `readDeleted=true`。
 
 ### 拒审巡检（`--json`）
+
 关注 `policyApprovalStatusV2`（`2`=不通过、`3`=受限）、`approvalStatusDetails`（`;` 分隔摘要）、`statusV2`（过滤 `Removed`）。同源也可用 `google-analysis --sections ads --json-out <dir>`。
 
 ### 创建（RSA）
+
 ```bash
 siluzan-tso ad ad-create \
   -a <accountId> \
@@ -185,11 +191,14 @@ siluzan-tso ad ad-create \
   --final-url <url> \
   --headlines "标题1,标题2,标题3" \
   --descriptions "描述1,描述2" \
-  [--path1 <≤15字符>] [--path2 <≤15字符>]
+  [--path1 <≤15字符>] [--path2 <≤15字符>] \
+  [--json | --json-out <path>]
 ```
-`--headlines` 至少 3 条（≤30字符），`--descriptions` 至少 2 条（≤90字符）。
+
+`--headlines` 至少 3 条（≤30字符），`--descriptions` 至少 2 条（≤90字符）。**`--json`** 返回网关响应（含 `id` 等字段），便于批量脚本拿到 adId 后续编辑/启停。
 
 ### 启停 / 删除
+
 ```bash
 siluzan-tso ad ad-status -a <accountId> --id <adId> --status <Enabled|Paused>
 siluzan-tso ad ad-delete -a <accountId> --id <adId>
@@ -200,20 +209,26 @@ siluzan-tso ad ad-delete -a <accountId> --id <adId>
 ## ad keywords — 关键词管理
 
 ### 查询
+
 ```bash
 siluzan-tso ad keywords -a <accountId> [--negative] [--start/--end <date>] [--json]
 ```
 
 ### 添加关键词
+
 ```bash
 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,词3" [--final-url <url>] \
+  [--json | --json-out <path>]
 ```
 
+`--json` 输出 `{ request: { adgroupId, count }, response: ... }`，批量脚本可直接据此核对成功量。
+
 ### 否定关键词
+
 ```bash
 # 添加（默认系列层级；传 --adgroup-id 则为组层级）
 siluzan-tso ad keyword-negative-create \
@@ -238,6 +253,7 @@ siluzan-tso ad batch get --id <recordId>
 siluzan-tso ad batch update --id <recordId> [--budget <主币种>] [--url <url>] [--campaign-name <name>]
 siluzan-tso ad batch publish --id <recordId>
 ```
+
 `update` / `publish` 仅 `draftStatus === "Draft"` 可操作。
 
 ---
@@ -247,88 +263,129 @@ siluzan-tso ad batch publish --id <recordId>
 多场景编排（竞品 URL + 种子、账户词叠市场指标、否词与建户表等）见 **`references/keyword-planner-workflows.md`**。
 
 ```bash
-siluzan-tso keyword -k <搜索词> [--url <url>] [--include <words>] [--exclude <words>] [--json] [--json-out <dir>]
+siluzan-tso keyword -k <搜索词> [--geo <geoTargetConstantIds>] [--url <url>] [--google-only] [--include <words>] [--exclude <words>] [--json] [--json-out <dir>]
+siluzan-tso keyword geo-list [--country-code <US,CN,...>] [--name-contains <text>] [--json]
 ```
-`--url` 触发网址拓词 + 轮询流程；`--include`/`--exclude` 为本地过滤。
+
+`--geo` 传多个 ID（如 `2840,2826`）时，返回的搜索量/CPC/竞争度为**跨所传地区的汇总数据**，响应中**无**按地区拆分的字段。若要分别查看各市场指标，须**多次调用**且每次 `--geo` **只传一个** ID（详见 **`references/keyword-planner-workflows.md`**「多地区 `--geo`」）。
+
+`--url` 触发网址拓词（`websitereco`）并合并进结果；与 `--google-only` 互斥（仅 Google Keyword Planner 时用后者）。`--include`/`--exclude` 为本地过滤。仅 Google、不联网搜索的 Agent 编排见 **`references/keyword-planner-workflows.md`**「分支 B」。
+
+---
+
+## ad campaign-validate — 投放 JSON 校验
+
+不提交 API；创建系列前**建议**跑。命令、选项、与 create 共用校验逻辑见 **`references/google-ads-campaign-plan.md`** § 校验与创建（后端/Google 硬约束，不含关键词分层占比）。
 
 ---
 
-## ad campaign-create — 广告系列新增
-
-支持两种模式：
-- 默认：直接发布（`DraftStatus: Published`）
-- `--draft`：仅保存草稿，需后续 `ad batch publish`
-
-广告组/关键词/创意的分步创建用 `adgroup-create`、`keyword-create`、`ad-create`。
-
-### --config-file（推荐）
-
-复杂参数时优先使用 JSON 配置文件：避免 shell 转义问题，`headlines` 元素内允许含逗号。
-
-**步骤：** 1) Write 工具写 JSON → 2) `siluzan-tso ad campaign-create --config-file /path/to/config.json` → 3) `ad batch get --id <taskId>` 查进度
-
-完整 Schema 见 `assets/campaign-create-template.json`。
-
-**核心字段：**
-
-| 字段 | 必填 | 类型 | 说明 |
-| --- | --- | --- | --- |
-| `account` | ✅ | string | Google mediaCustomerId |
-| `customerName` | ✅ | string | 账户名称 |
-| `name` | ✅ | string | 广告系列名称 |
-| `budget` | ✅ | number | 日预算，主币种金额 |
-| `bidding` | ✅ | string | `TARGET_SPEND` / `MANUAL_CPC` / `TARGET_CPA` / `TARGET_ROAS` |
-| `locationIds` | ✅ | string[] | 地理位置 ID（`ad geo search` 获取） |
-| `adgroupName` | ✅ | string | 第一个广告组名称 |
-| `maxCpc` | ✅ | number | 最高 CPC，主币种金额 |
-| `bidCeiling` | ✅ | number | TARGET_SPEND 出价上限 |
-| `targetCpa` | ✅ | number | TARGET_CPA 目标 CPA |
-| `targetRoas` | ✅ | number | TARGET_ROAS（如 2.5） |
-| `languageIds` | ✅ | string[] | 默认 `["1000"]`=英语，中文=`"1017"` |
-| `startDate`/`endDate` | ✅ | string | YYYY-MM-DD |
-| `url` | ✅ | string | 落地页 |
-| `status` | ✅ | string | `Enabled` / `Paused` |
-| `matchType` | ✅ | string | `BROAD` / `PHRASE` / `EXACT` |
-| `keywords` | ✅ | string[] | 第一个广告组关键词 |
-| `headlines` | ✅ | string[] | ≥3 条，≤30 字符，元素内允许逗号 |
-| `descriptions` | ✅ | string[] | ≥2 条，≤90 字符 |
-| `finalUrl` | ✅ | string | 广告落地页 |
-| `path1`/`path2` | ✅ | string | ≤15 字符 |
-| `productWords` | ✅ | string[] | 推广产品词 |
-| `negativeKeywords` | ✅ | string[] | 否定关键词 |
-| `extensions` | | array | 附加功能（CALL/SITELINK/STRUCTURED_SNIPPET） |
-| `extraAdGroups` | | array | 额外广告组 |
-| `draft` | | boolean | `true`=仅保存草稿 |
-
-### 命令行传参（简单场景）
+## ad campaign-create — 广告系列创建
+
+**仅支持 JSON 配置文件**（`--config-file`）。JSON 字段名 **直接对齐后端契约**（外层 `CampaignCreationRecord`、内层 `campaign` 对应 `Samm.Domain.AdsAcctMgmt.Campaign`，**全部 PascalCase**）。CLI 不做字段重命名、camelCase 转换或结构展开。
+
+- 默认：`draft: false` → 立即发布（`DraftStatus: Published`）
+- `draft: true` → 仅保存草稿，需 `ad batch publish`
+
+**步骤：**
+
+- 模板：`assets/siluzan-ads/assets/campaign-create-template.json`（PascalCase 直通）
+- 说明：`assets/siluzan-ads/assets/campaign-create-template.md`（逐字段含必填条件）
 
 ```bash
-siluzan-tso ad campaign-create \
-  -a <accountId> --customer-name <name> --name <name> \
-  --budget <主币种> --bidding <策略> --location-ids <ids> \
-  --adgroup-name <name> --max-cpc <主币种> \
-  [--keywords <kws>] [--headlines <titles>] [--descriptions <descs>] \
-  [--url/--final-url <url>] [--path1/--path2 <path>] \
-  [--negative-keywords <kws>] [--product-words <words>] \
-  [--extensions-json <json>] [--extra-adgroups-json <json>] \
-  [--lang-ids <ids>] [--bid-ceiling/--target-cpa/--target-roas <n>] \
-  [--start/--end <date>] [--status Enabled|Paused] [--draft] \
-  [--config-file <path>]
+# 1. 复制模板并填写
+#    - 外层：account / customerName / name / url / draft
+#    - 内层 campaign：Name / Budget / BiddingStrategyTypeV2 / targetedLocations 等（PascalCase）
+#    - 广告组在 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
+
+# 3. 成功或部分成功后必做比对
+siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json
+# 可选：--campaign-id <id>（ad campaigns -a <accountId> --json；省略时按系列名自动匹配）
+
+# Failed：系列未创建，无需 diff；根据 get 的 reason/errors 改 JSON 后重提
+# siluzan-tso ad campaign-create --config-file ./campaign.json
 ```
-> `--headlines` 中不能含逗号，含逗号请用 `--config-file`。
+
+### 失败处理（Agent 必遵）
+
+| `status` | 含义 | 做法 |
+| -------- | ---- | ---- |
+| `Creating` | 仍在执行 | 继续 `ad batch get`，勿重复 `campaign-create` |
+| `Successfully` | 全部成功 | **须** `ad batch diff` 核对计划与账户一致（无缺失应 ✅） |
+| `Failed` | 全部失败 | `ad batch get` 读 `reason`/`errors` → **只改 JSON** → 再 `ad campaign-create`（**不要** `batch diff`） |
+| `HasFailed` | 部分成功 | **须** `ad batch diff` 列出缺失 → 分步补建或删系列重提 |
+
+**`HasFailed` 分支：**
+
+1. **多数广告组未建成**（`AdGroupsForBatchJob` 中多数项无 `Id`，默认 ≥50%）：  
+   `ad campaign-delete -a <accountId> --id <campaignId>` → 按 `reason`/`errors` 修正 **campaign.json** → 重新 `ad campaign-create`。**不要**在脏系列上反复补建。
+
+2. **仅少数组/资产失败**（系列与大部分组已有 `Id`）：  
+   - 缺组：`ad adgroup-create`（`--json` 取 `id`）  
+   - 缺词：`ad keyword-create`（词面格式同 JSON `KeywordsForBatchJob`）  
+   - 缺 RSA：`ad ad-create`（`--headlines` / `--descriptions` 从 JSON `AdsForBatchJob` 抄）  
+   补建前可用 `ad groups` / `ad keywords` 核对账户现状。
+
+**`ad batch diff` 比对维度：**系列是否存在 → 各 `AdGroupsForBatchJob[].Name` → 组内关键词（匹配类型+词面）→ RSA 首条标题 → 系列否定词 → 附加信息条数。默认按层级树状输出每条缺失的 **JSON 路径 + 计划内容 + 账户实况**；`--json` 可落盘完整结构。
+
+**`ad batch get` 输出：**摘要表 + 后端原始 `reason` + 完整 `errors`（或 `--json` 整条记录）。
+
+**CLI 在提交前只做三件事：**
+
+1. 剥除 `_` 前缀注解键（如 `_meta`、`_comment_xxx`）；
+2. 缺失 `googleDataRecordId` 时生成 UUID；
+3. 把 `campaign` 子树内金额字段（`Budget`、`MaxCPCAmount`、`TargetSpend_BidCeilingAmount`、`TargetCpa_BidingAmount`、`MaxCpmAmount`、`MaxCPVAmount`、`TargetCpaAmount`、`MaxCPC`）从「元」深遍历 ×100 转为「分」。
+
+**字段校验：**提交前自动执行 `runCampaignCreateValidation`（与 `ad campaign-validate` 相同）：后端镜像硬约束 + 词面/RSA/搜索网络等；关键词分层与匹配占比见 `google-ads-keyword-taxonomy.md`（仅 Agent 参考，CLI 不校验）。
+
+**广告组：** 写在 `campaign.AdGroupsForBatchJob` 数组中（至少 1 项），字段名严格 PascalCase（`Name` / `MaxCPCAmount` / `KeywordsForBatchJob` / `AdsForBatchJob`）。详见 `campaign-create-template.md`。
+
+**关键词匹配：** 写在 `KeywordsForBatchJob` 块内；同一块同匹配类型，`MatchTypeV2` 与 `KeywordText` 词面格式必须对齐（`PHRASE` 用 `"词"`、`EXACT` 用 `[词]`、`BROAD` 直写）。
+
+广告组/关键词/创意的分步创建仍用 `adgroup-create`、`keyword-create`、`ad-create`。
 
 ---
 
 ## ad campaign-edit — 广告系列编辑
 
 ```bash
+# 支持的策略枚举
+siluzan-tso ad campaign-bidding-strategies [--json]
+
 siluzan-tso ad campaign-edit \
   -a <accountId> --id <campaignId> \
   [--name <新名称>] [--budget <主币种>] [--bidding <策略>] \
-  [--bid-ceiling <主币种>] [--target-cpa <主币种>] \
+  [--bid-ceiling <主币种>] [--target-cpa <主币种>] [--target-roas <倍数>] \
+  [--manual-ecpc true|false] \
   [--search-network true|false] [--content-network true|false]
 ```
-相对运算：先 `ad campaigns --json` 读 `budget`（已为主币种元），计算新值后传入。
+
+| `--bidding` | 须配合 |
+|-------------|--------|
+| `TARGET_SPEND` | 可选 `--bid-ceiling`（0=不限） |
+| `MANUAL_CPC` | 可选 `--manual-ecpc` |
+| `TARGET_CPA` | **必填** `--target-cpa` |
+| `TARGET_ROAS` | **必填** `--target-roas`（2.5 = 250%） |
+| `MAXIMIZE_CONVERSIONS` | 可选 `--target-cpa`（目标 CPA，元） |
+
+示例：
+
+```bash
+# 改为「尽可能争取更多点击次数」并设 CPC 上限 ¥3.5
+siluzan-tso ad campaign-edit -a <accountId> --id <campaignId> \
+  --bidding TARGET_SPEND --bid-ceiling 3.5
+
+# 改为 tCPA = ¥80
+siluzan-tso ad campaign-edit -a <accountId> --id <campaignId> \
+  --bidding TARGET_CPA --target-cpa 80
+```
+
+相对运算：先 `ad campaigns --json` 读 `budget`（已为主币种元）、`biddingStrategyTypeV2`，再传入。
+
+> PMax / 部分智能系列类型 Google 可能拒绝切换出价策略；以 API 返回错误为准。
 
 ---
 
@@ -345,6 +402,7 @@ siluzan-tso ad adgroup-rename -a <accountId> --id <adGroupId> --name <新名称>
 先用 `ad list --json` 取得完整 JSON，再只修改传入字段，未改字段从列表原值带回。
 
 `ad list --json` 关键字段映射：
+
 - `headlinePart1~3` + `AddtionalHeadlines` → `--headlines`（≥3条）
 - `adDescription`/`adDescription2` + `AddtionalAdDescriptions` → `--descriptions`（≥2条）
 - `finalUrl` → `--final-url`；`path1`/`path2` → `--path1`/`--path2`
@@ -357,6 +415,7 @@ siluzan-tso ad ad-edit \
   [--final-url <url>] [--path1 <p1>] [--path2 <p2>] \
   [--status Enabled|Paused]
 ```
+
 至少指定一项。
 
 ---
@@ -380,9 +439,20 @@ siluzan-tso ad keyword-delete -a <accountId> --id <keywordId> --adgroup-id <adGr
 siluzan-tso ad keyword-edit \
   -a <accountId> --id <keywordId> \
   [--text <新关键词>] [--match-type Broad|Phrase|Exact] \
-  [--max-cpc <n>] [--final-url <url>]
+  [--max-cpc <n>] [--final-url <url>] [--status Enabled|Paused]
+```
+
+传 `--match-type` 时 CLI 自动规范 `keywordText` 括号/引号格式。至少传一项。`--max-cpc` 为「主币种元」（见文首金额单位说明）。`--status` 写入 `userStatusV2`（与 Web 关键词开关一致，非系列的 `statusV2`）。
+
+---
+
+## ad keyword-status — 搜索关键词状态切换
+
+仅改 `userStatusV2`，走与 `keyword-edit` 相同的批量 PUT。与 `ad adgroup-status` 用法对称。
+
+```bash
+siluzan-tso ad keyword-status -a <accountId> --id <keywordId> --status <Enabled|Paused>
 ```
-传 `--match-type` 时 CLI 自动规范 `keywordText` 括号/引号格式。至少传一项。`--max-cpc` 为「主币种元」（见文首金额单位说明）。
 
 ---
 
@@ -393,13 +463,14 @@ siluzan-tso ad keyword-negative-edit \
   -a <accountId> --id <negativeKeywordId> \
   [--text <新文本>] [--match-type Broad|Phrase|Exact]
 ```
+
 传 `--match-type` 时 CLI 自动同步改写外层括号/引号。
 
 ---
 
 ## ad extension — 附加信息管理
 
-修改方式为**先删后建**（无 PUT 接口）。
+修改方式为**先删后建**（无 PUT 接口）。所有 `extension <type>` 子命令均支持 `--json` / `--json-out`，输出网关返回的扩展对象（含 `id`），批量脚本可据此回填。
 
 ```bash
 # 查询
@@ -407,21 +478,22 @@ siluzan-tso ad extension list -a <accountId> [--type SITELINK|CALL|CALLOUT|STRUC
 
 # 附加链接
 siluzan-tso ad extension sitelink -a <accountId> --text "文字" --url "https://..." \
-  [--line2/--line3 <text>] [--level Account|Campaign|AdGroup] [--campaign-id <id>]
+  [--line2/--line3 <text>] [--level Account|Campaign|AdGroup] [--campaign-id <id>] [--json]
 
 # 附加电话
 siluzan-tso ad extension call -a <accountId> --country-code "+86" --phone "4008001234" \
-  [--level Account|Campaign|AdGroup]
+  [--level Account|Campaign|AdGroup] [--json]
 
 # 附加宣传信息（≤25字符）
-siluzan-tso ad extension callout -a <accountId> --text "免费送货上门" [--level Account]
+siluzan-tso ad extension callout -a <accountId> --text "免费送货上门" [--level Account] [--json]
 
 # 附加结构化摘要
-siluzan-tso ad extension snippet -a <accountId> --header "Brands" --values "A,B,C" [--level Account]
+siluzan-tso ad extension snippet -a <accountId> --header "Brands" --values "A,B,C" [--level Account] [--json]
 
 # 删除
 siluzan-tso ad extension delete -a <accountId> --id <extensionId>
 ```
+
 `--header` 常用值：`Brands`/`Services`/`Amenities`/`Types`/`Styles`/`Courses`/`Models` 等。
 
 ---
@@ -451,3 +523,43 @@ siluzan-tso ad geo add -a <accountId> --campaign-id <id> --location-id <id> [--b
 # 删除
 siluzan-tso ad geo remove -a <accountId> --campaign-id <id> --location-id <id>
 ```
+
+---
+
+## ad device-bid — 设备出价调整
+
+与前端 `updateDeviceAndAddress`（`intelligent-optimization-v2.ts`）及 AI 优化「修改设备出价」同源。
+
+| 级别 | 列表 | 修改 |
+|------|------|------|
+| **系列**（默认） | `GET …/campaignmanagement/{id}/BidModifiers/Devices` | `PUT …/campaigns/{campaignId}/Criteria/{criterionId}/BidModifier/{bidModifier}` |
+| **广告组** | `GET …/adgroupnmanagement/bidmodifiers/{id}?campaignId&adgroupId&criteriaType=PLATFORM` | `PUT …/adgroupnmanagement/bidmodifiers/{id}?campaignId&adGroupId` + Body `Criterion[]` |
+
+**`--bid-modifier` 口径（系列级直接透传 Google 倍率）**
+
+| 倍率 | 含义 |
+|------|------|
+| `1.0` | 不调整 |
+| `0.8` | 降低 20% |
+| `1.2` | 提高 20% |
+| `0` | 排除该设备（-100%） |
+
+广告组级会在 CLI 内将倍率转为后端百分比：`(倍率 - 1) × 100`（与 `GoogleAdsAcctMgmtServiceProviderV2.MutateAdGroupBidModifier` 一致）。
+
+**Sammamish 落点**：`CampaignManagementController.GetDeviceBidModifier` / `ModifyCampaignCriteriaBidModifier`；`AdGroupManagementController.SetAdGroupCriterionBidModifier` → `GoogleAdsAcctMgmtServiceProviderV2`。
+
+```bash
+# 系列级：账户下全部设备出价（可按系列过滤）
+siluzan-tso ad device-bid list -a <accountId> [--campaign-id <id>] [--json]
+
+# 广告组级
+siluzan-tso ad device-bid list -a <accountId> --level adgroup --campaign-id <id> --ad-group-id <id> [--json]
+
+# 修改系列设备出价（id 来自 list --json，或用 --device-type 自动匹配）
+siluzan-tso ad device-bid set -a <accountId> --campaign-id <id> --device-type Mobile --bid-modifier 0.8
+
+# 修改广告组设备出价
+siluzan-tso ad device-bid set -a <accountId> --level adgroup --campaign-id <id> --ad-group-id <id> --device-type Desktop --bid-modifier 1.1
+```
+
+> 智能出价（tCPA/tROAS）可能覆盖设备出价调整；排除极差设备仍可用 `0`。