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

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

@@ -4,16 +4,17 @@
 
 ---
 
-| 轨 | 条件 | 动作 |
-|----|------|------|
+| 轨           | 条件                                     | 动作                                                                     |
+| ------------ | ---------------------------------------- | ------------------------------------------------------------------------ |
 | **直读直写** | 用户已给账户/预算/组/词/RSA 等结构化数据 | 通过代码转换为 campaign-create直接可用的 JSON → validate → 确认 → create |
-| **方案先行** | 无完整结构，或要求「先出方案」 | 读本文件 + 必读规则 → 生成 JSON → validate → Markdown → 确认 → create |
+| **方案先行** | 无完整结构，或要求「先出方案」           | 读本文件 + 必读规则 → 生成 JSON → validate → Markdown → 确认 → create    |
 
 **硬约束**
 
 - 可执行真相只有 **JSON**（`assets/campaign-create-template.json` 同构）；Markdown 只读投影。
+- **Agent Read 顺序（建系列前必做）**：① `assets/campaign-create-template.json`（复制/改写的结构真相源）→ ② `assets/campaign-create-template.md`（字段说明与踩坑）。**禁止**只读 `.md` 凭印象拼 JSON。
 - 改需求 **只改 JSON**，再 `campaign-validate`，再刷新 Markdown。
-- **PMax 系列创建**走独立流水线（勿用本文件 JSON 模板）：`assets/pmax-create-template.md` + `ad pmax-validate` / `ad pmax-create`；运营诊断见 `google-ads/rules/google-ads-pmax-guide.md`。
+- **PMax 系列创建**走独立流水线（勿用本文件 JSON 模板）：**先 Read `assets/pmax-create-template.json`** + `assets/pmax-create-template.md` + `ad pmax-validate` / `ad pmax-create`；**Lead Gen/B2B 方案默认含 `campaignExtensions.leadForm`**（方案 Markdown 须单列表单）；运营诊断见 `google-ads/rules/google-ads-pmax-guide.md`。
 - 搜索网络：仅 Google 搜索（`TargetSearchNetwork`/`TargetContentNetwork`/`TargetPartnerSearchNetwork` 均为 false）。
 
 ---
@@ -24,8 +25,8 @@
 |----|------|-----------|
 | 1 | `list-accounts` 锁定 `account` / `customerName` / 币种 | `references/accounts/currency.md` |
 | 2 | 可选 `rag query`；`keyword` / `keyword geo-list` 拓词 | `references/analytics/keyword-planner-workflows.md` |
-| 3 | 按分层规则写入 `KeywordsForBatchJob`（Exact/Phrase/Broad） | `google-ads/rules/google-ads-keyword-taxonomy.md`（参考，非 CLI 强制） |
-| 4 | 填 `campaign`（预算/出价/地域/否词≥20/RSA/附加信息） | `assets/campaign-create-template.md` |
+| 3 | 按分层规则写入 `KeywordsForBatchJob`（Exact/Phrase/Broad）；**否词单独写** `NegativeKeywordsForBatchJob`（勿与正向词混放） | `google-ads/rules/google-ads-keyword-taxonomy.md`（参考，非 CLI 强制） |
+| 4 | 复制 `campaign-create-template.json` 并填 `campaign`（预算/出价/地域/否词≥20/RSA/附加信息） | **`assets/campaign-create-template.json`** + `assets/campaign-create-template.md` |
 | 5 | **`ad campaign-validate --config-file <json>`**（失败只改 JSON；超长见下文「超长人工确认」） | 下文「校验」 |
 | 6 | 输出：**JSON 代码块** → **Markdown**（`google-ads-launch-plan-template.md` 正文）→ 待确认 | — |
 | 7 | 用户确认后 **`ad campaign-create`** | `google-ads/google-ads.md`|
@@ -43,28 +44,28 @@
 
 ### 必读（出方案前）
 
-| 文档 | 用途 |
-|------|------|
-| `google-ads/rules/google-ads-keyword-taxonomy.md` | 核心/长尾与匹配块**建议**（Agent 参考，CLI 不强制） |
-| `google-ads/rules/google-ads-compliance.md` | 词与文案合规 |
-| `google-ads/rules/sensitive-industries.md` | 敏感行业（若相关） |
-| `google-ads/rules/google-ads-launch-plan-template.md` | 用户可见 Markdown 结构与 RSA/否词表 |
+| 文档                                                   | 用途                                                            |
+| ------------------------------------------------------ | --------------------------------------------------------------- |
+| `google-ads/rules/google-ads-keyword-taxonomy.md`      | 核心/长尾与匹配块**建议**（Agent 参考，CLI 不强制）             |
+| `google-ads/rules/google-ads-compliance.md`            | 词与文案合规                                                    |
+| `google-ads/rules/sensitive-industries.md`             | 敏感行业（若相关）                                              |
+| `google-ads/rules/google-ads-launch-plan-template.md`  | 用户可见 Markdown 结构与 RSA/否词表                             |
 | `google-ads/rules/google-ads-creative-optimization.md` | RSA 创意主题；`campaign-validate` 强制 **15** 标题 + **4** 描述 |
-| `assets/campaign-create-template.md` | JSON 字段契约 |
+| **`assets/campaign-create-template.json`** + `assets/campaign-create-template.md` | JSON 结构（先 Read `.json`）+ 字段说明 |
 
 ### 按需（触及时再读）
 
-| 文档 | 何时 |
-|------|------|
-| `google-ads/rules/google-ads-keyword-strategy.md` | 分组/匹配/否定词策略争议 |
-| `google-ads/rules/google-ads-campaign-optimization.md` | 出价策略、预算、学习期 |
-| `google-ads/rules/google-ads-landing-page-discovery-via-webfetch.md` | 仅首页、需推断 PDP/PLP |
-| `google-ads/rules/google-ads-conversion-architecture.md` | 转化/EC/归因说明 |
-| `google-ads/rules/google-ads-keyword-optimization.md` | 上线后优化，非首建 |
-| `google-ads/rules/google-ads-account-audit.md` | 账户诊断，非首建 |
-| `google-ads/rules/google-ads-audience-strategy.md` | 受众/RLSA |
-| `google-ads/rules/google-ads-pmax-guide.md` | PMax 运营/诊断；**创建**见 `assets/pmax-create-template.md` |
-| `references/google-ads/pmax-api.md` | PMax 网关路径与 Search API 边界 |
+| 文档                                                                 | 何时                                                        |
+| -------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `google-ads/rules/google-ads-keyword-strategy.md`                    | 分组/匹配/否定词策略争议                                    |
+| `google-ads/rules/google-ads-campaign-optimization.md`               | 出价策略、预算、学习期                                      |
+| `google-ads/rules/google-ads-landing-page-discovery-via-webfetch.md` | 仅首页、需推断 PDP/PLP                                      |
+| `google-ads/rules/google-ads-conversion-architecture.md`             | 转化/EC/归因说明                                            |
+| `google-ads/rules/google-ads-keyword-optimization.md`                | 上线后优化，非首建                                          |
+| `google-ads/rules/google-ads-account-audit.md`                       | 账户诊断，非首建                                            |
+| `google-ads/rules/google-ads-audience-strategy.md`                   | 受众/RLSA                                                   |
+| `google-ads/rules/google-ads-pmax-guide.md`                          | PMax 运营/诊断；**创建**见 `assets/pmax-create-template.md` |
+| `references/google-ads/pmax-api.md`                                  | PMax 网关路径与 Search API 边界                             |
 
 复述给用户：**3–5 条**与本次任务相关的合规/策略要点即可，无需罗列全部文件名。
 

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

@@ -13,8 +13,8 @@
 
 ## ID 来源速查
 
-| 需要的 ID           | 获取命令                                                     |
-| ------------------- | ------------------------------------------------------------ |
+| 需要的 ID           | 获取命令                                                                |
+| ------------------- | ----------------------------------------------------------------------- |
 | `accountId`（`-a`） | `siluzan-tso list-accounts --json-out ./snap` → `mediaCustomerId`       |
 | 广告系列 `id`       | `siluzan-tso ad campaigns -a <accountId> --json-out ./snap` → `id`      |
 | 广告组 `id`、`name` | `siluzan-tso ad groups -a <accountId> --json-out ./snap` → `id`、`name` |
@@ -33,14 +33,14 @@
 
 > **与 Search 隔离**：勿用 `campaign-create` 或 `campaign-create-template.json`。网关摘录见 `references/google-ads/pmax-api.md`。
 
-| 步骤 | 命令 |
-|------|------|
-| 模板 | 复制 `assets/pmax-create-template.json`，字段见 `assets/pmax-create-template.md` |
-| **素材转换** | `siluzan-tso ad pmax-image-convert --input ./banner.jpg --output-dir ./assets --prefix <name> [--update-config ./pmax.json]` |
-| 地理 ID | `siluzan-tso ad geo search -a <accountId> -q "<地区名>"` |
-| 校验 | `siluzan-tso ad pmax-validate --config-file ./pmax.json [--json-out ./snap-pmax]`（图片规格 + 文案超长 `lengthViolations`；超长勿自动截断，见 `google-ads/google-ads-campaign-plan.md` § 超长人工确认） |
-| 创建 | `siluzan-tso ad pmax-create --config-file ./pmax.json [--json-out ./snap-pmax]` |
-| 复核 | `siluzan-tso ad campaigns -a <accountId> --json-out ./snap` → `channelTypeV2` 为 `PERFORMANCE_MAX` |
+| 步骤         | 命令                                                                                                                                                                                                    |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 模板         | 复制 `assets/pmax-create-template.json`，字段见 `assets/pmax-create-template.md`                                                                                                                        |
+| **素材转换** | `siluzan-tso ad pmax-image-convert --input ./banner.jpg --output-dir ./assets --prefix <name> [--update-config ./pmax.json]`                                                                            |
+| 地理 ID      | `siluzan-tso ad geo search -a <accountId> -q "<地区名>"`                                                                                                                                                |
+| 校验         | `siluzan-tso ad pmax-validate --config-file ./pmax.json [--json-out ./snap-pmax]`（图片规格 + 文案超长 `lengthViolations`；超长勿自动截断，见 `google-ads/google-ads-campaign-plan.md` § 超长人工确认） |
+| 创建         | `siluzan-tso ad pmax-create --config-file ./pmax.json [--json-out ./snap-pmax]`                                                                                                                         |
+| 复核         | `siluzan-tso ad campaigns -a <accountId> --json-out ./snap` → `channelTypeV2` 为 `PERFORMANCE_MAX`                                                                                                      |
 
 **PMax**：`ad pmax-create` **同步**返回 `campaignId`、`assetGroupId`、`budgetId`；无 `ad batch get/diff`。详见 `pmax-api.md`。
 
@@ -54,19 +54,22 @@
 
 ### 已上线 PMax 管理（CLI）
 
-| 能力 | 命令 |
-|------|------|
-| 详情 | `ad pmax-get -a <id> --campaign-id <cid>` |
-| 改活动 | `ad pmax-edit`（`--patch-file` 或 `--status` / `--budget` + `--budget-id`） |
-| 新资产组 | `ad pmax-asset-group-create --config-file …` |
-| 改资产组 | `ad pmax-asset-group-edit` |
-| 删资产组 | `ad pmax-asset-group-edit --status REMOVED`（软删；网关无 DELETE 端点） |
-| 改资产 | `ad pmax-assets-update --config-file …` |
-| YouTube 追加 | `ad pmax-youtube-link`（单条 `--youtube` / `--video-path`）；批量见 `ad pmax-assets-update` |
-| 信号 | `ad pmax-signals-get` / `ad pmax-signals-set`；受众下拉 `ad pmax-audiences` |
-| 图片库 | `ad pmax-image-upload` |
-| 报表 | `ad pmax-report-asset-groups` / `ad pmax-report-geo` |
-| 删活动 | `ad campaign-delete -a <id> --id <campaignId>`（与 Search 共用；勿用 `ad campaign-edit`） |
+| 能力             | 命令                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------- |
+| 详情             | `ad pmax-get -a <id> --campaign-id <cid>`（读 `_brandGuidelinesActive`）                                   |
+| 改活动           | `ad pmax-edit`（`--patch-file` 或 `--status` / `--budget` + `--budget-id`）                                |
+| 改 Campaign 品牌 | `ad pmax-brand-assets-edit`（BG 已开启）                                                                   |
+| 启用 BG          | `ad pmax-brand-guidelines-enable --config-file …`（存量活动）                                              |
+| 新资产组         | `ad pmax-asset-group-create --config-file …`（BG 下自动省略品牌）                                          |
+| 改资产组         | `ad pmax-asset-group-edit`                                                                                 |
+| 删资产组         | `ad pmax-asset-group-edit --status REMOVED`（软删；网关无 DELETE 端点）                                    |
+| 改资产           | `ad pmax-assets-update --config-file …`                                                                    |
+| YouTube 追加     | `ad pmax-youtube-link`（单条 `--youtube` / `--video-path`）；批量见 `ad pmax-assets-update`                |
+| 信号             | `ad pmax-signals-get` / `ad pmax-signals-set`；受众下拉 `ad pmax-audiences`                                |
+| 附加资产         | `ad extension pmax-types`；`callout` / `snippet` / `lead-form` / `whatsapp`（见 `pmax-api.md` § 附加资产） |
+| 图片库           | `ad pmax-image-upload`                                                                                     |
+| 报表             | `ad pmax-report-asset-groups` / `ad pmax-report-geo`                                                       |
+| 删活动           | `ad campaign-delete -a <id> --id <campaignId>`（与 Search 共用；勿用 `ad campaign-edit`）                  |
 
 模板与 HTTP 对照：`references/google-ads/pmax-api.md`。
 
@@ -179,7 +182,7 @@ siluzan-tso ad adgroup-create \
 | `--name <name>`          | 广告组名称                                                         | ✅   |
 | `--max-cpc <amount>`     | 最高 CPC（主币种金额）                                             | ✅   |
 | `--status`               | `ENABLED`（默认）/ `PAUSED`                                        |      |
-| `--json-out`  | 输出网关返回的完整 adgroup 对象（含 `id` / `maxCPCAmountYuan` 等） |      |
+| `--json-out`             | 输出网关返回的完整 adgroup 对象（含 `id` / `maxCPCAmountYuan` 等） |      |
 
 **返回字段（--json-out）**：网关同步返回完整 adgroup，含 **`id`**（adgroupId）、`name`、`campaignId`、`statusV2`、`maxCPCAmountYuan`（元，CLI 已 ÷100）、`typeV2: "SEARCH_STANDARD"` 等 75+ 字段。批量创建脚本应直接读 `id`，**不需要**再次 `ad groups --json-out ./snap` 反查。
 
@@ -353,23 +356,23 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json
 
 ### 失败处理（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` 列出缺失 → 分步补建或删系列重提 |
+| `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-out` 取 `id`）  
-   - 缺词：`ad keyword-create`（词面格式同 JSON `KeywordsForBatchJob`）  
+2. **仅少数组/资产失败**（系列与大部分组已有 `Id`）：
+   - 缺组：`ad adgroup-create`（`--json-out` 取 `id`）
+   - 缺词：`ad keyword-create`（词面格式同 JSON `KeywordsForBatchJob`）
    - 缺 RSA：`ad ad-create`（`--headlines` / `--descriptions` 从 JSON `AdsForBatchJob` 抄）  
-   补建前可用 `ad groups` / `ad keywords` 核对账户现状。
+     补建前可用 `ad groups` / `ad keywords` 核对账户现状。
 
 **`ad batch diff` 比对维度：**系列是否存在 → 各 `AdGroupsForBatchJob[].Name` → 组内关键词（匹配类型+词面）→ RSA 首条标题 → 系列否定词 → 附加信息条数。默认按层级树状输出每条缺失的 **JSON 路径 + 计划内容 + 账户实况**；`--json-out` 可落盘完整结构。
 
@@ -405,13 +408,13 @@ siluzan-tso ad campaign-edit \
   [--search-network true|false] [--content-network true|false]
 ```
 
-| `--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，元） |
+| `--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，元）    |
 
 示例：
 
@@ -512,11 +515,19 @@ siluzan-tso ad keyword-negative-edit \
 
 ## ad extension — 附加信息管理
 
-修改方式为**先删后建**（无 PUT 接口）。所有 `extension <type>` 子命令均支持 `--json-out`，输出网关返回的扩展对象（含 `id`），批量脚本可据此回填。
+Callout / Snippet / Sitelink / Call 等类型修改可**先删后建**；**Lead Form / WhatsApp** 支持 `ad extension update`（PUT；WhatsApp 成功后 **id 会变**）。所有 `extension <type>` 子命令均支持 `--json-out`，输出网关返回的扩展对象（含 `id`），批量脚本可据此回填。
 
 ```bash
+# PMax 支持的类型与层级（含 LEAD_FORM）
+siluzan-tso ad extension pmax-types [--json-out ./snap]
+
+# 结构化摘要标头（按语言）
+siluzan-tso ad extension snippet-headers [--json-out ./snap]
+
 # 查询
-siluzan-tso ad extension list -a <accountId> [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET] [--json-out ./snap]
+siluzan-tso ad extension list -a <accountId> \
+  [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET|LEAD_FORM|BUSINESS_MESSAGE] \
+  [--campaign-id <campaignId>] [--json-out ./snap]
 
 # 附加链接
 siluzan-tso ad extension sitelink -a <accountId> --text "文字" --url "https://..." \
@@ -532,11 +543,24 @@ siluzan-tso ad extension callout -a <accountId> --text "免费送货上门" [--l
 # 附加结构化摘要
 siluzan-tso ad extension snippet -a <accountId> --header "Brands" --values "A,B,C" [--level Account] [--json-out ./snap]
 
+# PMax 潜在客户表单（仅 Campaign 级；模板 assets/pmax-lead-form-template.json）
+siluzan-tso ad extension lead-form -a <accountId> --config-file ./lead-form.json [--json-out ./snap]
+
+# PMax WhatsApp 私信（BUSINESS_MESSAGE；需 Google API 白名单；模板 assets/pmax-whatsapp-template.json）
+siluzan-tso ad extension whatsapp -a <accountId> --config-file ./whatsapp.json [--json-out ./snap]
+
+# 更新 Lead Form 或 WhatsApp（配置文件含 leadForm / businessMessage；WhatsApp PUT 后 id 会变）
+siluzan-tso ad extension update -a <accountId> --id <extensionId> --config-file ./lead-form.json
+
 # 删除
 siluzan-tso ad extension delete -a <accountId> --id <extensionId>
 ```
 
-`--header` 常用值：`Brands`/`Services`/`Amenities`/`Types`/`Styles`/`Courses`/`Models` 等。
+**PMax 约束**：仅 `Account` / `Campaign` 层级；`Ad Group` 会 400。`LEAD_FORM` 仅 Campaign。WhatsApp 每 Campaign 仅 1 个 ENABLED，须 Google API 白名单。
+
+`--header` 常用值：`Brands`/`Services`/`Amenities`/`Types`/`Styles`/`Courses`/`Models` 等（完整列表：`ad extension snippet-headers`）。
+
+**网关**：`ExtensionManagementController.cs` — `pmaxSupportedTypeList`、`structuredSnippetHeaders`、`extension/{accountId}` POST/PUT/DELETE。
 
 ---
 
@@ -573,9 +597,9 @@ siluzan-tso ad geo remove -a <accountId> --campaign-id <id> --location-id <id>
 
 **`--bid-modifier` 口径（`add` / `set-bid` 均为 Google 倍率）**
 
-| 倍率 | 含义 |
-|------|------|
-| `1.0` | 不调整 |
+| 倍率  | 含义     |
+| ----- | -------- |
+| `1.0` | 不调整   |
 | `1.2` | 提高 20% |
 | `0.8` | 降低 20% |
 
@@ -589,19 +613,19 @@ siluzan-tso ad geo remove -a <accountId> --campaign-id <id> --location-id <id>
 
 与 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[]` |
+| 级别             | 列表                                                                                    | 修改                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| **系列**（默认） | `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%） |
+| 倍率  | 含义                |
+| ----- | ------------------- |
+| `1.0` | 不调整              |
+| `0.8` | 降低 20%            |
+| `1.2` | 提高 20%            |
+| `0`   | 排除该设备（-100%） |
 
 广告组级会在 CLI 内将倍率转为后端百分比：`(倍率 - 1) × 100`。
 

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

@@ -2,10 +2,10 @@
 
 ## 金额单位
 
-| JSON / CLI | 提交到 API |
-|------------|------------|
-| `budget: 5.5`（元） | `550`（×100） |
-| `targetCpa_BidingAmount: 0.5`（元） | `50` |
+| JSON / CLI                          | 提交到 API    |
+| ----------------------------------- | ------------- |
+| `budget: 5.5`（元）                 | `550`（×100） |
+| `targetCpa_BidingAmount: 0.5`（元） | `50`          |
 
 报表 `spend` 为美元浮点，勿与管理 API 混用。
 
@@ -13,24 +13,99 @@
 
 ## CLI 命令
 
-| 命令 | 说明 |
-|------|------|
-| `ad pmax-validate` | 本地校验 |
-| `ad pmax-create` | 创建系列（同步返回 `campaignId` 等） |
-| `ad pmax-channel-types` | 渠道类型列表 |
-| `ad pmax-get` | 系列详情 |
-| `ad pmax-edit` | 编辑系列 |
-| `ad pmax-asset-group-create` | 新建资产组 |
-| `ad pmax-asset-group-edit` | 编辑资产组 |
-| `ad pmax-assets-update` | 更新资产 |
-| `ad pmax-youtube-link` | **追加**单条 YouTube 视频（不替换已有视频） |
-| `ad pmax-signals-get` / `ad pmax-signals-set` | 读/写信号（**全量** PUT） |
-| `ad pmax-audiences` | 受众列表 |
-| `ad pmax-image-upload` | 单张图片上传 |
-| `ad pmax-report-asset-groups` / `ad pmax-report-geo` | 报表 |
-| `ad campaigns` | 列表（筛 `PERFORMANCE_MAX`） |
-
-模板：`assets/pmax-create-template.json`、`pmax-asset-group-template.json`、`pmax-assets-update-template.json`、`pmax-signals-template.json`、`pmax-patch-campaign-template.json`。
+| 命令                                                          | 说明                                                                                          |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `ad pmax-validate`                                            | 本地校验                                                                                      |
+| `ad pmax-create`                                              | 创建系列（同步返回 `campaignId` 等）                                                          |
+| `ad pmax-channel-types`                                       | 渠道类型列表                                                                                  |
+| `ad pmax-get`                                                 | 系列详情（含 `brandAssets[]`；`--json-out` 附加 `_brandGuidelinesActive`、`_agentBrandHint`） |
+| `ad pmax-edit`                                                | 编辑系列（预算/出价/状态；**不可**改 `brandGuidelinesEnabled`）                               |
+| `ad pmax-brand-assets-edit`                                   | BG 已开启时改 Campaign 级品牌（商家名/Logo/样式）                                             |
+| `ad pmax-brand-guidelines-enable`                             | 存量活动启用 BG（不可关闭）                                                                   |
+| `ad pmax-asset-group-create`                                  | 新建资产组                                                                                    |
+| `ad pmax-asset-group-edit`                                    | 编辑资产组                                                                                    |
+| `ad pmax-assets-update`                                       | 更新资产                                                                                      |
+| `ad pmax-youtube-link`                                        | **追加**单条 YouTube 视频（不替换已有视频）                                                   |
+| `ad pmax-signals-get` / `ad pmax-signals-set`                 | 读/写信号（**全量** PUT）                                                                     |
+| `ad pmax-audiences`                                           | 受众列表                                                                                      |
+| `ad pmax-image-upload`                                        | 单张图片上传                                                                                  |
+| `ad pmax-report-asset-groups` / `ad pmax-report-geo`          | 报表                                                                                          |
+| `ad campaigns`                                                | 列表（筛 `PERFORMANCE_MAX`）                                                                  |
+| `ad extension pmax-types`                                     | PMax 支持的附加资产类型与层级                                                                 |
+| `ad extension callout` / `snippet` / `lead-form` / `whatsapp` | 宣传信息 / 结构化摘要 / 潜在客户表单 / WhatsApp                                               |
+| `ad extension list`                                           | 查询已挂载扩展（`--type` / `--campaign-id`）                                                  |
+
+模板：`assets/pmax-create-template.json`、`pmax-asset-group-template.json`、`pmax-assets-update-template.json`、`pmax-signals-template.json`、`pmax-patch-campaign-template.json`、`pmax-brand-assets-template.json`、`pmax-brand-guidelines-enable-template.json`、`pmax-lead-form-template.json`。
+
+### 附加资产（Callout / Snippet / Lead Form）
+
+网关 `POST .../campaign/pmax` **不**接受扩展字段；CLI 通过 **`campaignExtensions`** 在 `pmax-create` 成功后**自动编排** `extensionmanagement`（与手动 `ad extension *` 等价）。
+
+**方式 A（推荐，一条命令）**：在 `pmax-create` JSON 中填 `campaignExtensions`。**Lead Gen / B2B 询盘方案须含 `leadForm`**（勿只写 callouts/snippets；用户明确不要表单才省略）：
+
+```json
+{
+  "campaignExtensions": {
+    "callouts": ["Free shipping"],
+    "structuredSnippets": [{ "header": "Services", "values": ["A", "B", "C"] }],
+    "leadForm": {
+      "businessName": "...",
+      "headline": "...",
+      "description": "...",
+      "privacyPolicyUrl": "...",
+      "finalUrl": "...",
+      "fields": [{ "inputType": "EMAIL" }]
+    },
+    "businessMessage": {
+      "starterMessage": "Hi!",
+      "whatsapp": { "countryCode": "US", "phoneNumber": "2125550100" }
+    }
+  }
+}
+```
+
+`pmax-validate` 会一并校验；`pmax-create` 成功后在同一次调用内挂载（`--json-out` 含 `campaignExtensions` 结果）。
+
+**方式 B（分步）**：活动创建后手动走 `extensionmanagement`（PMax 限制 Account/Campaign 层级）。
+
+| 中文            | 类型                 | 命令                                                                                                 |
+| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
+| 宣传信息        | `CALLOUT`            | `ad extension callout -a <id> --text "..." --level Campaign --campaign-id <cid>`                     |
+| 结构化摘要      | `STRUCTURED_SNIPPET` | `ad extension snippet -a <id> --header Brands --values "A,B,C" --level Campaign --campaign-id <cid>` |
+| 潜在客户表单    | `LEAD_FORM`          | `ad extension lead-form -a <id> --config-file ./lead-form.json`                                      |
+| 附加链接 / 电话 | `SITELINK` / `CALL`  | `ad extension sitelink` / `call`（同上 `--level Campaign`）                                          |
+| 私信 WhatsApp   | `BUSINESS_MESSAGE`   | `ad extension whatsapp` 或 `campaignExtensions.businessMessage`                                      |
+
+```bash
+# 查 PMax 支持类型
+siluzan-tso ad extension pmax-types --json-out ./snap
+
+# 结构化摘要标头下拉
+siluzan-tso ad extension snippet-headers --json-out ./snap
+
+# Lead Form（模板见 assets/pmax-lead-form-template.md）
+siluzan-tso ad extension lead-form -a <accountId> --config-file ./lead-form.json --json-out ./snap
+
+# WhatsApp（模板见 assets/pmax-whatsapp-template.md；需 Google API 白名单）
+siluzan-tso ad extension whatsapp -a <accountId> --config-file ./whatsapp.json --json-out ./snap
+
+# 复核 / 更新 / 删除
+siluzan-tso ad extension list -a <accountId> --type LEAD_FORM --campaign-id <cid> --json-out ./snap
+siluzan-tso ad extension list -a <accountId> --type BUSINESS_MESSAGE --campaign-id <cid> --json-out ./snap
+siluzan-tso ad extension update -a <accountId> --id <extId> --config-file ./lead-form.json
+siluzan-tso ad extension update -a <accountId> --id <extId> --config-file ./whatsapp.json  # id 会变
+siluzan-tso ad extension delete -a <accountId> --id <extId>
+```
+
+**约束**：
+
+- PMax **不支持** `level: Ad Group`（会 400）
+- `LEAD_FORM` **仅** `Campaign` 级；每活动通常 1 个
+- `BUSINESS_MESSAGE`（WhatsApp）每 Campaign **仅 1 个** ENABLED；须 **Google API 白名单**
+- WhatsApp **PUT 后 asset id 会变**；后续操作须用响应中的新 `id`
+- 创建 Lead Form 后后端自动尝试开启 `SUBMIT_LEAD_FORM` + `GOOGLE_HOSTED` 转化目标
+
+**网关**：`GET /extensionmanagement/pmaxSupportedTypeList`；`POST|PUT|DELETE /extensionmanagement/extension/{accountId}[/{id}]`（Sammamish `ExtensionManagementController.cs`）。
 
 ### 图片（推荐流程）
 
@@ -42,13 +117,13 @@
 
 **语义（与后端 `pmax-frontend-api.md` §5.3 / §5.4 一致）**：`YOUTUBE_VIDEO` 默认 **追加**，每个资产组最多 **15** 条；不可重复链接同一 `videoId`。仅当 `pmax-assets-update` 显式传 `replaceFieldTypes: ["YOUTUBE_VIDEO"]` 时才会先删后增（替换全部视频）。
 
-| 场景 | 命令 / 接口 |
-|------|-------------|
-| 创建时挂 1 条 | `pmax-create` JSON：`videoPath` 或 `youtubeUrlOrId`（二选一，单次最多 1 条） |
-| 追加 1 条 | `ad pmax-youtube-link` → `POST .../asset-group/{id}/youtube` |
-| 批量追加多条 | `ad pmax-assets-update` → `PUT .../assets`，`assetsToLink` 中多条 `YOUTUBE_VIDEO` |
-| 取消链接 | `ad pmax-assets-update`，`assetGroupAssetResourceNamesToRemove`（取自 `pmax-get` 的 `assets[].assetResourceName`） |
-| 替换全部视频 | `ad pmax-assets-update`，`replaceFieldTypes: ["YOUTUBE_VIDEO"]` + 新的 `assetsToLink` |
+| 场景          | 命令 / 接口                                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------------------------------ |
+| 创建时挂 1 条 | `pmax-create` JSON：`videoPath` 或 `youtubeUrlOrId`（二选一，单次最多 1 条）                                       |
+| 追加 1 条     | `ad pmax-youtube-link` → `POST .../asset-group/{id}/youtube`                                                       |
+| 批量追加多条  | `ad pmax-assets-update` → `PUT .../assets`，`assetsToLink` 中多条 `YOUTUBE_VIDEO`                                  |
+| 取消链接      | `ad pmax-assets-update`，`assetGroupAssetResourceNamesToRemove`（取自 `pmax-get` 的 `assets[].assetResourceName`） |
+| 替换全部视频  | `ad pmax-assets-update`，`replaceFieldTypes: ["YOUTUBE_VIDEO"]` + 新的 `assetsToLink`                              |
 
 **创建时自动链接**
 
@@ -76,7 +151,11 @@ siluzan-tso ad pmax-youtube-link -a <id> --asset-group-id <agId> --campaign-id <
   "assetGroupId": "98765432101",
   "assetsToLink": [
     { "fieldType": "YOUTUBE_VIDEO", "youtubeVideoId": "dQw4w9WgXcQ", "assetName": "Promo1" },
-    { "fieldType": "YOUTUBE_VIDEO", "youtubeVideoId": "https://youtu.be/jNQXAC9IVRw", "assetName": "Promo2" }
+    {
+      "fieldType": "YOUTUBE_VIDEO",
+      "youtubeVideoId": "https://youtu.be/jNQXAC9IVRw",
+      "assetName": "Promo2"
+    }
   ]
 }
 ```
@@ -85,13 +164,38 @@ siluzan-tso ad pmax-youtube-link -a <id> --asset-group-id <agId> --campaign-id <
 
 ---
 
+## Brand Guidelines（品牌手册，Google v21+）
+
+Google v21+ 新建 PMax **默认开启** BG：`businessName` / Logo 挂在 **Campaign**（`brandAssets[]`），全活动共用；首个 AssetGroup 的 `assets[]` **不含** 品牌。
+
+### Agent 决策（必读）
+
+1. **任何编辑前先** `ad pmax-get --json-out` → 读 `_brandGuidelinesActive`（或 `_agentBrandHint`）
+2. BG 生效 → 改品牌用 `ad pmax-brand-assets-edit`；追加 AG **省略** 品牌字段
+3. BG 未生效 → 改品牌在 AssetGroup 上用 `ad pmax-assets-update`；或 `ad pmax-brand-guidelines-enable` 启用 BG
+
+| 场景               | 命令                                                                              |
+| ------------------ | --------------------------------------------------------------------------------- |
+| 创建（默认 BG 开） | `pmax-create` JSON 仍必填 `businessName`+Logo；可省略 `brandGuidelinesEnabled`    |
+| 创建（旧路径）     | JSON 加 `"brandGuidelinesEnabled": false`                                         |
+| 改 Campaign 级品牌 | `ad pmax-brand-assets-edit -a <id> --campaign-id <cid> --patch-file ./brand.json` |
+| 存量启用 BG        | `ad pmax-brand-guidelines-enable --config-file ./enable-bg.json`                  |
+| 追加资产组         | `pmax-asset-group-create`（CLI 自动判断，BG 下无需 Logo/商家名）                  |
+
+**禁止**：BG 生效时对 AssetGroup 执行 `pmax-assets-update` 链接 `BUSINESS_NAME`/`LOGO`/`LANDSCAPE_LOGO`（CLI 预检阻断，网关亦 400）。
+
+模板：`assets/pmax-brand-assets-template.md`、`pmax-brand-guidelines-enable-template.md`。
+
+---
+
 ## 编辑流程
 
-1. `ad pmax-get` 拉详情
+1. `ad pmax-get` 拉详情（读 `_brandGuidelinesActive`）
 2. 改系列 → `ad pmax-edit` 或 `--patch-file`
-3. 改资产组 → `ad pmax-asset-group-edit`
-4. 改资产 → `ad pmax-assets-update`（`campaignId` 必填）
-5. 改信号 → `ad pmax-signals-get` → `ad pmax-audiences` → `ad pmax-signals-set`（一次带齐两类数组）
+3. **改品牌** → BG 生效：`ad pmax-brand-assets-edit`；未生效：`ad pmax-assets-update` 或先 `pmax-brand-guidelines-enable`
+4. 改资产组 → `ad pmax-asset-group-edit`
+5. 改 AG 内素材 → `ad pmax-assets-update`（`campaignId` 必填；勿改品牌 fieldType 若 BG 生效）
+6. 改信号 → `ad pmax-signals-get` → `ad pmax-audiences` → `ad pmax-signals-set`（一次带齐两类数组）
 
 ---
 

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

@@ -2,20 +2,20 @@
 
 > 本目录为 **策略/SOP 文档**，非 CLI 参数表。命令与字段见 `references/google-ads/google-ads.md`；新建流程见 `google-ads/google-ads-campaign-plan.md`。
 
-| 文件 | 何时 Read |
-| ---- | --------- |
-| `google-ads-account-audit.md` | 账户健康度审计、结构诊断 |
-| `google-ads-campaign-optimization.md` | 系列层优化决策 |
-| `google-ads-keyword-strategy.md` | 关键词策略规划 |
-| `google-ads-keyword-optimization.md` | 关键词出价/否定/扩词优化 |
-| `google-ads-keyword-taxonomy.md` | 词类分层与命名 |
-| `google-ads-creative-optimization.md` | 创意/文案优化 |
-| `google-ads-audience-strategy.md` | 受众策略 |
-| `google-ads-pmax-guide.md` | PMax 运营指南（配合 `assets/pmax-create-template.md`） |
-| `google-ads-conversion-architecture.md` | 转化追踪架构 |
-| `google-ads-compliance.md` | 合规与政策 |
-| `google-ads-landing-page-discovery-via-webfetch.md` | 落地页发现（WebFetch） |
-| `google-ads-launch-plan-template.md` | 上线计划模板 |
-| `sensitive-industries.md` | 敏感行业限制 |
+| 文件                                                | 何时 Read                                              |
+| --------------------------------------------------- | ------------------------------------------------------ |
+| `google-ads-account-audit.md`                       | 账户健康度审计、结构诊断                               |
+| `google-ads-campaign-optimization.md`               | 系列层优化决策                                         |
+| `google-ads-keyword-strategy.md`                    | 关键词策略规划                                         |
+| `google-ads-keyword-optimization.md`                | 关键词出价/否定/扩词优化                               |
+| `google-ads-keyword-taxonomy.md`                    | 词类分层与命名                                         |
+| `google-ads-creative-optimization.md`               | 创意/文案优化                                          |
+| `google-ads-audience-strategy.md`                   | 受众策略                                               |
+| `google-ads-pmax-guide.md`                          | PMax 运营指南（配合 `assets/pmax-create-template.md`） |
+| `google-ads-conversion-architecture.md`             | 转化追踪架构                                           |
+| `google-ads-compliance.md`                          | 合规与政策                                             |
+| `google-ads-landing-page-discovery-via-webfetch.md` | 落地页发现（WebFetch）                                 |
+| `google-ads-launch-plan-template.md`                | 上线计划模板                                           |
+| `sensitive-industries.md`                           | 敏感行业限制                                           |
 
 宿主编排下的自动优化分文件 SOP：`references/operations/hosted-automation-optimize-index.md`。