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

package/dist/skill/references/google-ads-rules/google-ads-launch-plan-template.md

@@ -2,59 +2,62 @@
 
 > 所属 skill：`siluzan-tso`。
 >
-> 用途：AI 根据用户需求生成投放计划 → 以本模板格式呈现给用户确认 → 用户确认后由助手在后台完成账户内创建。**勿向用户展示命令行或 `siluzan-tso` 等工具细节**（具体命令见文末「助手执行计划」）。
-> 触发场景：用户要求「帮我投广告」「创建广告系列」「制定投放方案」等。
+> 用途：从已确认的 `campaign-create` JSON **投影**用户可见的 Markdown 表格（勿与 JSON 矛盾）。流程与门禁见 `references/google-ads-campaign-plan.md`。
+> 触发：用户要投放方案/确认稿；**先完成 JSON + validate，再填本模板正文**。
+>
+> 字段契约：`assets/campaign-create-template.json` + `campaign-create-template.md`  
+> 关键词数量建议：`google-ads-keyword-taxonomy.md`（Agent 参考，CLI 不强制）
 
 ---
 
-## 使用流程
-
-```
-1. 收集信息：向用户了解产品/服务、目标、预算、地域、网站等
-2. 生成计划：按下方模板格式输出完整方案
-3. 用户确认：用户逐项审阅，提出修改
-4. 执行创建：用户确认后，助手在后台按计划完成创建；**不向用户复述或展示任何命令行**
-```
-
-**关键原则**：
+## 交付顺序（固定）
 
-- 用户可见正文只写业务字段（预算、地域、文案等），不出现命令行、可执行脚本或工具名称
-- 助手侧须保证每个业务字段可落实为实际创建步骤（映射关系见文末「助手执行计划」）；**搜索网络仅限 Google 搜索、关闭搜索合作伙伴与展示网络**为必选策略
-- 关键词和广告文案必须通过合规检查（参考 `references/google-ads-rules/google-ads-compliance.md` 第十一章）
-- 敏感行业须额外标注合规要求（参考 `sensitive-industries.md`）
+1. **JSON 代码块**（唯一数据源）
+2. **下方模板正文**（从 JSON 填充）
+3. **待确认**（改需求只改 JSON）
 
-### 各模块推荐数量一览
+### 创意与否定词数量（关键词见 taxonomy）
 
-以下与 `references/google-ads-rules/google-ads-compliance.md` 第七章、`references/google-ads-rules/google-ads-keyword-strategy.md`、`references/google-ads-rules/google-ads-creative-optimization.md` 第一章与第五章对齐；**正文结构以本节下「模板正文」中 Google Ads 搜索详细执行方案为准**。生成计划时按推荐条数填满表格，勿仅用少量示例占位。
+| 模块 | 推荐 | 说明 |
+|------|------|------|
+| RSA Headlines | 12–15 | 固定📌 见 §3.5 |
+| RSA Descriptions | 4 | |
+| Sitelink | 6–8 | |
+| Callout | 6–8 | 12–15 字符 |
+| Structured Snippet | 1–2 组，每组 ≥4 values | |
+| 账户级否定词包 | 5 类 | §3.4 表 |
+| 系列级补充否定 | 5–10 | |
 
-| 模块                             | 最少  | 推荐                                     | 上限 / 说明                                                    |
-| -------------------------------- | ----- | ---------------------------------------- | -------------------------------------------------------------- |
-| 每广告组正向关键词               | 20 条 | **20–30 条**                             | >30 条宜拆广告组；**组内意图须高度一致**以利质量得分           |
-| 账户级否定词包分类               | 3 类  | **5 类**（见模板「账户级否定关键词表」） | 每类下列多条广泛/词组否定词；列表须应用到**所有**系列          |
-| 系列级补充否定词                 | 3 条  | **5–10 条**                              | 系列专属；与账户列表互补                                       |
-| RSA Headlines                    | 12 条 | **12–15 条**                             | 最多 15 条；**关键位置按模板用「固定📌」标注**                 |
-| RSA Descriptions                 | 4 条  | **4 条**                                 | 最多 4 条                                                      |
-| Sitelink                         | 6 条  | **6–8 条**                               | 创意文档亦给出更高账户级上限，计划内以本表为准                 |
-| Callout                          | 6 条  | **6–8 条**                               | 每条宜 12–15 字符（效果参考创意文档）                          |
-| Structured Snippet               | 1 组  | **1–2 组**                               | 每组 **≥4 个值**（`values`）                                   |
-| 附加电话（CALL）                 | 0     | **有合规客服号则 1 条**                  | 无电话则可不填                                                 |
-| 潜在客户表单（Lead Form）        | 0     | **线索类 B2B 可 1 套**                   | 在 Google Ads 后台配置；CLI 当前无对应命令时由助手说明后台步骤 |
-| 合规提示下的限制条目（Tier 2/3） | —     | **每条实质限制 2–4 条**                  | 过少易漏项，过多影响可读性                                     |
+**落地页**：优先 PDP，否则 PLP；仅首页时见 `google-ads-landing-page-discovery-via-webfetch.md`。
 
-### 搜索广告方案生成（Google · 搜索广告）
-
-**适用**：媒体为 **Google**、广告类型为 **搜索广告**、场景为 **搜索广告投放方案 / 计划生成**（含 AI 填表与向用户确认前的草案）。除上表与模板正文外，须满足下表；**落地页 URL 仅靠域名无法对齐时**，助手侧可按 `references/google-ads-rules/google-ads-landing-page-discovery-via-webfetch.md` 用 **webfetch** 分析公开页面结构以推断 **PDP / PLP**（对用户说明只用业务语言，不暴露工具名）。
+---
 
-| 需求         | 优化方案                                                                                                                                                                                                                                                                                                                                                                  | 原因                                                                                        |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| 广告的落地页 | **优先推荐**产品**详情页（PDP）**；若无独立 PDP 或需承接多 SKU，可推荐**产品列表/分类页（PLP）**。不做「必须用 PDP」的硬性一刀切，但须在计划正文（尤其 3.2 默认落地页、3.3 各广告组、RSA 最终到达网址）中**写明每个 URL 的角色**（PDP / PLP）及与产品线、关键词意图的对应关系。仅首页/公司介绍页不足以作为高意图组主落地页时，须尝试按上文独立文档流程补全 PDP/PLP 候选。 | 搜索流量购买意图强；**详情页**内容与广告/关键词一致度高，通常更利于**质量得分**与**转化**。 |
-| 广告关键词   | 在核心词、词组与完全匹配之外，**显式增加长尾词**：含**型号、规格、材质、场景、用途、地域、行业细分、问题型**等修饰；建议每组正向词中 **长尾意图词占比约 30–50%**（可与泛词分属不同广告组以保持组内意图一致）。数量仍须满足上表「每广告组 20–30 条推荐」区间，**避免**仅用少量头部词占位。                                                                                 | 方案生成阶段易出现**词量少、偏泛词**；长尾可覆盖细分意图、改善匹配质量并便于否定词迭代。    |
+## Markdown ↔ JSON 映射（生成 JSON 时对照）
+
+| 计划正文（Markdown）   | `campaign-create` JSON 字段（**PascalCase 直通后端**）                                                 |
+| ---------------------- | ----------------------------------------------------------------------------------------------------- |
+| 账户 ID / 客户名       | `account`、`customerName`（外层）                                                                      |
+| 系列名称               | `name`（外层展示用） / `campaign.Name`（内层）                                                         |
+| 日预算                 | `campaign.Budget`（**元**，CLI 内部 ×100 转分）                                                        |
+| 出价策略 / 上限 / tCPA | `campaign.BiddingStrategyTypeV2`、`campaign.TargetSpend_BidCeilingAmount`、`campaign.TargetCpa_BidingAmount`、`campaign.TargetRoas` |
+| 投放地域               | `campaign.targetedLocations: [{ id: "<geoId>" }]`（先 `ad geo search` 取 id）、外层 `locations`（展示名，可选） |
+| 语言                   | `campaign.targetedLanguages: [{ id: 1000 }]`（英语 1000 / 中文 1017）                                  |
+| 起止日期               | `campaign.StartTime`、`campaign.EndTime`（YYYY-MM-DD）                                                |
+| 落地页                 | 外层 `url`；广告组级 `KeywordsForBatchJob[].FinalURL`、创意级 `AdsForBatchJob[].Finalurl`              |
+| 关键词                 | `campaign.AdGroupsForBatchJob[].KeywordsForBatchJob`（`MatchTypeV2` + `KeywordText`）                  |
+| 否定词                 | `campaign.NegativeKeywordsForBatchJob: [{ KeywordText: [...], MatchTypeV2: "BROAD", FinalURL: "" }]`  |
+| 附加信息               | `campaign.ExtensionsForBatchJob`                                                                       |
+| 广告组                 | `campaign.AdGroupsForBatchJob[]`：`Name`、`MaxCPCAmount`、`KeywordsForBatchJob`、`AdsForBatchJob`       |
+| 仅保存草稿             | `draft: true` → 确认后 `ad batch publish`                                                              |
+| 立即创建               | `draft: false`（默认）                                                                                 |
+
+关键词匹配（在 `KeywordsForBatchJob` 块中以 `MatchTypeV2` 区分；同一块同匹配类型）：`词`→广泛、`"词"`→词组、`[词]`→完全。
 
 ---
 
-## 模板正文
+## 模板正文（Markdown 投影，须与 JSON 一致）
 
-AI 生成计划时，按以下格式输出。`{{占位符}}` 由 AI 根据用户需求填充。
+AI 生成计划时，**先写好 JSON，再按以下格式输出说明**。`{{占位符}}` 由 JSON 字段填充，不得手写与 JSON 矛盾的数值。
 
 ---
 
@@ -137,14 +140,14 @@ AI 生成计划时，按以下格式输出。`{{占位符}}` 由 AI 根据用户
 
 ### 3.3 广告组（Ad Group）与关键词矩阵
 
-**原则**：每一个广告组内的关键词**意图必须高度一致**，广告文案与落地页与意图对齐，**质量得分（Quality Score）**才容易拉高。匹配符号：`[完全]`、`"词组"`、广泛无括号。**搜索广告方案生成**时须在每组中补足**长尾词**（参见文首「搜索广告方案生成」专项表），与头词、词组、完全匹配分层搭配，避免整组仅为短泛词。
+**原则**：每一个广告组内的关键词**意图必须高度一致**；匹配符号：`[完全]`、`"词组"`、广泛无括号。Markdown 表列建议含 **词面 | 分层(tier) | 类型(class) | MatchTypeV2 | FinalURL**（分层列可来自方案笔记，写入 JSON 的仅为 `KeywordsForBatchJob`）。数量建议见 `google-ads-keyword-taxonomy.md`。
 
 #### 系列 1：{{系列名称}}
 
-| 广告组名称    | 核心关键词（带匹配符号）                                      | 对应搜索意图   | 建议基准出价 (CPC) |
-| ------------- | ------------------------------------------------------------- | -------------- | ------------------ |
+| 广告组名称    | 核心关键词（带匹配符号）                                                              | 对应搜索意图   | 建议基准出价 (CPC) |
+| ------------- | ------------------------------------------------------------------------------------- | -------------- | ------------------ |
 | {{AG 1 名称}} | {{`"词1"` / `[词2]` / 广泛词 …，补足 20–30 条时在组下列全表（须含长尾，见文首专项）}} | {{意图一句话}} | {{币种区间或定额}} |
-| {{AG 2 名称}} | {{…}}                                                         | {{…}}          | {{…}}              |
+| {{AG 2 名称}} | {{…}}                                                                                 | {{…}}          | {{…}}              |
 
 （每个广告组下可再拆「关键词」子表：| 关键词 | 匹配类型 | 格式 |，列满推荐条数，勿停留在 3 条示例。）
 
@@ -247,11 +250,11 @@ Display URL：`{{domain}}/{{path1}}/{{path2}}`（Path1/Path2 各 ≤ 15 字符
 
 ### 3.7 优化师日常操作 S.O.P（执行规范）
 
-| 频次                     | 必做事项                                                                                                                                                                   |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **每日（建议前 14 天）** | 查**搜索词报告**：发现 C 端/教程/无关意图，**立即**将具体词或整句以合适匹配类型加入**账户否定列表**或系列否定；这是控制流量质量的关键                                      |
+| 频次                     | 必做事项 |
+| ------------------------ | ------------------------------- |
+| **每日（建议前 14 天）** | 查**搜索词报告**：发现 C 端/教程/无关意图，**立即**将具体词或整句以合适匹配类型加入**账户否定列表**或系列否定；这是控制流量质量的关键|
 | **每周**                 | **砍烂词**：某关键词花费 > {{如：$15}} 且无有效转化（或无线索/WhatsApp 等约定动作），**暂停**；**调出价**：有效 B2B/目标动作词可提价 **10%–15%**，争取**绝对页首展示份额** |
-| **每月**                 | 核对 CRM/销售数据，算真实 ROI；对「垃圾线索」来源词**降价或暂停**；评估是否满足切换 **tCPA / 智能出价** 的数据门槛                                                         |
+| **每月**                 | 核对 CRM/销售数据，算真实 ROI；对「垃圾线索」来源词**降价或暂停**；评估是否满足切换 **tCPA / 智能出价** 的数据门槛|
 
 **阶段总览**（与 `references/google-ads-rules/google-ads-campaign-optimization.md` 可对照，不替代上表日常动作）：
 
@@ -307,80 +310,11 @@ Display URL：`{{domain}}/{{path1}}/{{path2}}`（Path1/Path2 各 ≤ 15 字符
 
 ## 助手执行计划（内部，勿向用户展示或复述）
 
-用户确认方案后，助手在后台按下列顺序执行（参数须与计划正文中的业务字段一致）。**不要**把本节内容粘贴给用户或逐条朗读命令。
-
-**与产品方案对齐的硬规则**：
-
-- 创建/编辑系列时：**仅 Google 搜索网络**；**勿启用**搜索合作伙伴与展示网络（若 API/后台选项由平台暴露，须显式关闭）。
-- **账户级否定关键词列表**：若当前 CLI/API 仅支持系列级否定，则对每个系列执行否定词创建，或与用户说明需在后台一次性绑定列表；**计划正文仍以「账户列表 + 全系列应用」为准**。
-- **RSA 图钉（Headline/Description 固定位置）**、**Lead Form 附加信息**：若 CLI 无字段，在 Google Ads 界面按计划补全（不向用户展示命令）。
-
-```bash
-# 1. 查询地域 ID（如尚未确认）
-siluzan-tso ad geo search -a {{CID}} -q "{{地域名}}"
-
-# 2. 创建系列 1（一体化模式；网络选项须与计划 3.1 一致）
-siluzan-tso ad campaign-create \
-  -a {{CID}} \
-  --customer-name "{{账户名}}" \
-  --name "{{系列名}}" \
-  --budget {{日预算}} \
-  --bidding {{出价策略}} \
-  --location-ids {{geo_ids}} \
-  --lang-ids {{lang_ids}} \
-  --adgroup-name "{{广告组名}}" \
-  --max-cpc {{CPC金额}} \
-  --url "{{落地页URL}}" \
-  --keywords "{{关键词列表}}" \
-  --headlines "{{H1}},{{H2}},{{H3}},..." \
-  --descriptions "{{D1}},{{D2}}" \
-  --final-url "{{落地页URL}}" \
-  --path1 "{{path1}}" --path2 "{{path2}}"
-
-# 3. 查看创建进度
-siluzan-tso ad batch get --id <返回的taskId>
-
-# 4. 如有额外广告组，逐个创建
-siluzan-tso ad adgroup-create \
-  -a {{CID}} \
-  --campaign-id <上一步返回的系列ID> \
-  --campaign-name "{{系列名}}" \
-  --name "{{广告组名}}" \
-  --max-cpc {{CPC金额}}
-
-# 5. 为额外广告组添加关键词
-siluzan-tso ad keyword-create \
-  -a {{CID}} \
-  --adgroup-id <广告组ID> \
-  --keyword "{{关键词}}" \
-  --match-type {{EXACT/PHRASE/BROAD}}
-
-# 6. 为额外广告组创建广告
-siluzan-tso ad ad-create \
-  -a {{CID}} \
-  --adgroup-id <广告组ID> \
-  --final-url "{{URL}}" \
-  --headlines "{{headlines}}" \
-  --descriptions "{{descriptions}}" \
-  --path1 "{{path1}}" --path2 "{{path2}}"
-
-# 7. 添加否定关键词（系列级；账户级列表若后台统一管理，此处可逐系列同步同一批词）
-siluzan-tso ad keyword-negative-create \
-  -a {{CID}} \
-  --campaign-id <系列ID> \
-  --keyword "{{否定词}}" \
-  --match-type {{EXACT/PHRASE}}
-
-# 8. 部署附加信息（Lead Form 无 CLI 时跳过，改后台）
-siluzan-tso ad extension call -a {{CID}} --country-code "{{+XX}}" --phone "{{本地号码}}"
-# （无客服电话则跳过 call；邮箱用 sitelink：mailto: 或联系页 URL，勿写入 RSA）
-siluzan-tso ad extension sitelink -a {{CID}} --text "{{文本}}" --url "{{URL}}"
-siluzan-tso ad extension callout -a {{CID}} --text "{{文本}}"
-siluzan-tso ad extension snippet -a {{CID}} --header "{{Header}}" --values "{{值列表}}"
-
-# 9. 添加地域排除（如有）
-siluzan-tso ad geo add -a {{CID}} --campaign-id <ID> --location-id <排除地域ID> --exclude
-```
+用户确认后**仅使用确认版 JSON**；命令与 batch 轮询/diff 见 **`references/google-ads-campaign-plan.md`** § 校验与创建、`references/google-ads.md` § ad campaign-create。
+
+**硬规则**（须已在 JSON 中体现）：仅 Google 搜索网络（`TargetGoogleSearch: true`，其余三个 `Target*Network: false`）；金额 JSON 填**元**；RSA 图钉/Lead Form 等 CLI 无法表达的项在创建成功后说明需后台补全。
+
+**禁止**：废弃行内 `campaign-create -a …`；未更新 JSON 仅改 Markdown 即创建；用 Markdown 手填与 JSON 冲突的参数。
 
 ---
 
@@ -392,7 +326,7 @@ siluzan-tso ad geo add -a {{CID}} --campaign-id <ID> --location-id <排除地域
 
 在生成计划前，至少确认以下信息（缺失则向用户询问）：
 
-| 必须 | 信息                             | 用途                                                                                                                            |
+| 必须 | 信息                             | 用途                                                            zz                                                                |
 | ---- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | ✅   | 广告账户 ID                      | 关联投放账户（执行时由助手使用，勿向用户解释命令行）                                                                            |
 | ✅   | 推广的产品/服务                  | 决定关键词和文案方向                                                                                                            |
@@ -413,7 +347,7 @@ siluzan-tso ad geo add -a {{CID}} --campaign-id <ID> --location-id <排除地域
 | 系列命名           | 遵循 `[类型]_[目标]_[定向]_[地域]_[匹配]` 规范（参考 `google-ads-campaign-optimization.md` 2.1 节）；可与业务名并用（如「B2B 源头寻源」）                                                                                                          |
 | 出价策略（首月）   | **产品默认**：核心系列用 **Manual CPC**，且**关闭 eCPC**，写明建议 CPC 上限区间；测流/爆款系列可用 **Maximize Clicks + 最高 CPC**；与 `TARGET_SPEND` 等等价映射以实际 CLI/API 可选值为准时在助手侧转换，**用户可见正文始终用 Google Ads 界面用语** |
 | 出价策略（次月）   | **产品默认**：近 **30 天满 30 个**约定转化（如表单）后切换 **tCPA**；无足够数据则延续人工或 Max Clicks 并写明条件                                                                                                                                  |
-| 关键词（每广告组） | **组内意图高度一致**；**最少 5、推荐 10–20**（与文首一览表 20–30 条推荐对齐时以一览表为准）；`[完全]` / `"词组"` / 广泛分层（`google-ads-keyword-strategy.md`）；**搜索方案生成须含足量长尾词**（文首「搜索广告方案生成」专项）                    |
+| 关键词（每广告组） | 数量与匹配块建议见 **`google-ads-keyword-taxonomy.md`**；组内意图一致；符号 `[完全]` / `"词组"` / 广泛；策略争议见 `google-ads-keyword-strategy.md` |
 | 否定词             | **账户级 5 类词包**填满模板表；系列级补充 5–10 条；上线后搜索词**每日**迭代                                                                                                                                                                        |
 | RSA                | **12–15** 标题、**4** 描述；**至少 H1、H2 与 D1** 在表中标注【固定📌】及目标位置与理由；字符合规见第十一章字数≤30                                                                                                                                  |
 | 附加信息           | Sitelink **6–8**（可含 OEM/验厂/报价/目录/联系）；Callout **6–8**；Snippet **≥1 组、每组 ≥4 值**；**Lead Form** 线索业务建议填标题与必填字段                                                                                                       |
@@ -435,8 +369,4 @@ siluzan-tso ad geo add -a {{CID}} --campaign-id <ID> --location-id <排除地域
 
 ### 输出格式要求
 
-- 直接输出 Markdown 文本，不需要代码围栏包裹
-- 所有金额标注币种
-- 字符数必须实际计算并填入（CJK 字符按 2 计）
-- **用户可见正文中不得出现**：`siluzan-tso`、shell/bash 代码块、命令行参数（如 `--budget`）、或任何可复制的终端命令；执行细节仅保留在助手侧，对照「助手执行计划」与计划表格保持一致即可
-- 如系列较多（>3），助手侧可分系列执行；用户可见方案写全业务表格即可
+交付顺序与改稿规则见文首 **「交付顺序（固定）」** 与 **`references/google-ads-campaign-plan.md`**。补充：用户可见正文不得出现 CLI 命令（JSON 代码块除外）；多系列 = 多 JSON + 合并 Markdown（每节标明文件名）。