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

package/dist/skill/references/workflows.md

@@ -18,9 +18,13 @@
 
 ---
 
-## 关键词规划师（拓词 / 词包 / 建户结构编排）
+## 关键词规划师（拓词 / 词包）
 
-**`references/keyword-planner-workflows.md`**：`google-analysis`、`keyword`、`ad keyword-*` 串联步骤；Forecast / 12 个月趋势在 CLI 侧无接口；`--json-out` 消费约定。单命令参数见 `references/google-ads.md`「keyword」节。
+**`references/keyword-planner-workflows.md`**：`keyword` / `google-analysis` 拓词编排；**不含**建户 JSON（见下节）。
+
+## Google 搜索系列方案 + 创建（Agent）
+
+**`references/google-ads-campaign-plan.md`**：双轨入口、7 步流水线、`campaign-validate` 门禁、`campaign-create` + batch。字段契约见 `assets/campaign-create-template.md`；命令参数见 `references/google-ads.md`。
 
 ---
 
@@ -202,7 +206,7 @@ siluzan-tso account-history -m Google
 
 ## 流程二：AI 智投创建 → 审核 → 发布
 
-对应页面：`/advertising/AICreation`（创建向导）、`/advertising/AICreationList`（记录列表）。`ad smart` 与 `ad batch` 详解见 **`references/aigc.md`**。
+对应页面：`/advertising/AICreation`（创建向导）、`/advertising/AICreationList`（记录列表）。`ad batch` 命令见 **`references/google-ads.md`** § ad batch。
 
 ### 业务背景
 
@@ -276,38 +280,25 @@ Failed / HasFailed（部分或全部失败）
 用户要创建 Google 广告
 ├─ 有已保存的 AI 智投草稿（网页向导填写的）？
 │    └─ 是 → 流程二（ad batch update/publish）
-├─ 需要 AI 辅助规划关键词/预算/地区分配？
-│    └─ 是 → 流程十三（ad smart prepare → ad campaign-create 一体化）
-└─ 已知所有参数，直接创建？
-     └─ 是 → 本流程（ad campaign-create，内部走 AI 创建 API）
+├─ 需先出投放方案（口述/官网/拓词）？
+│    └─ 是 → references/google-ads-campaign-plan.md → campaign-validate → campaign-create
+└─ 已有完整 JSON 或结构化计划？
+     └─ 是 → 本流程（campaign-validate → campaign-create）
 ```
 
 ### 场景 A：一体化创建（系列 + 关键词 + 广告，推荐）
 
-一条命令完成全部内容，等同于网页向导发布行为。
+**方案阶段**：按 **`references/google-ads-campaign-plan.md`**（JSON → `campaign-validate` → Markdown → 用户确认 → create）。下文为命令串联速查。
 
 ```bash
-# 前置：获取地理位置 ID
+# 前置：地域 ID 写入 JSON（campaign.targetedLocations[].id）
 siluzan-tso ad geo search -a <mediaCustomerId> -q "United States"
-# 记录 id（如美国 = 2840）
 
-# 一体化创建（含关键词和广告创意）
-siluzan-tso ad campaign-create \
-  -a <mediaCustomerId> \
-  --customer-name "<mediaAccountName>" \
-  --name "品牌推广_US_搜索" \
-  --budget 100 \
-  --bidding TARGET_SPEND \
-  --location-ids 2840 \
-  --adgroup-name "核心词_跑步鞋" \
-  --max-cpc 5 \
-  --url "https://www.brand-a.com/running-shoes" \
-  --keywords "running shoes,sport shoes,trail running" \
-  --headlines "专业跑步鞋,轻量透气设计,品牌直销价" \
-  --descriptions "全球百万跑者信赖，专业助力每一步。,免费配送，30天无理由退换。" \
-  --final-url "https://www.brand-a.com/running-shoes" \
-  --path1 "跑步鞋" \
-  --path2 "特惠"
+# 方案门禁（必跑，失败只改 JSON）
+siluzan-tso ad campaign-validate --config-file ./campaign.json
+
+# 用户确认后创建（字段说明见 campaign-create-template.md）
+siluzan-tso ad campaign-create --config-file ./campaign.json
 
 # 记录返回的任务 ID，轮询创建状态（Creating → Successfully）
 siluzan-tso ad batch get --id <taskId>
@@ -328,16 +319,8 @@ siluzan-tso ad campaigns -a <mediaCustomerId> --json
 适合需要精细控制每个广告组、关键词、广告创意的场景。
 
 ```bash
-# 第一步：创建广告系列骨架（含空广告组，无关键词和广告）
-siluzan-tso ad campaign-create \
-  -a <mediaCustomerId> \
-  --customer-name "<mediaAccountName>" \
-  --name "品牌推广_US_搜索" \
-  --budget 100 \
-  --bidding TARGET_SPEND \
-  --location-ids 2840 \
-  --adgroup-name "核心词_跑步鞋" \
-  --max-cpc 5
+# 第一步：创建广告系列骨架（config 中省略 keywords/headlines 即可）
+siluzan-tso ad campaign-create --config-file ./campaign-skeleton.json
 
 # 第二步：等待创建完成
 siluzan-tso ad batch get --id <taskId>
@@ -806,134 +789,6 @@ siluzan-tso balance -m Google -a <mediaCustomerId>
 
 ---
 
-## 流程十三：Google AIGC 广告智投方案生成（全 CLI，无需打开浏览器）
-
-对应功能：`ad smart prepare`（数据收集）→ AI Agent 规划 → `ad` 系列命令落地
-
-### 业务背景
-
-AI Agent 全程辅助的 Google 广告方案生成：CLI 负责调用平台 AI 接口收集行业、关键词、地区预算等结构化数据，AI Agent 据此生成完整的广告方案（系列/组/关键词/广告语），再通过 `ad` 命令直接在 Google Ads 账户中落地创建。**全程无需打开浏览器。**
-
-### 完整业务流程
-
-```
-ad smart prepare → 收集行业/关键词/地区预算等规划数据
-AI Agent 分析    → 基于数据生成完整广告方案（系列结构/关键词/广告语）
-ad adgroup-create → 在现有广告系列下创建广告组
-ad keyword-create → 添加推荐关键词
-ad ad-create      → 创建广告创意（RSA）
-```
-
-### 步骤
-
-```bash
-# 第一步：确认 Google 账户（取 mediaCustomerId）
-siluzan-tso list-accounts -m Google --json
-
-# 第二步：收集 AIGC 方案规划数据
-# 命令会自动完成：链接验证 → 行业匹配 → 语言获取 → 关键词推荐 → 地区预算比例
-siluzan-tso ad smart prepare \
-  -a <mediaCustomerId> \
-  --url "https://www.brand-a.com" \
-  -w "running shoes,sport shoes" \
-  --secondary-words "marathon shoes,trail running" \
-  --budget 200
-
-# 第三步：AI Agent 分析 ad smart prepare 的输出，生成方案
-# AI Agent 依据以下数据规划：
-#   - 行业代码、推荐语言 → 广告系列定向设置
-#   - 地区预算比例 → 各地区广告系列预算分配
-#   - 关键词推荐列表 → 广告组关键词
-#   - 产品词 + 链接 → AI 自行生成标题和描述
-
-# 第四步：查看现有广告系列（方案需要挂载在某个系列下）
-siluzan-tso ad campaigns -a <mediaCustomerId> --json
-# 若返回为空，需先创建广告系列（异步，完成后用 ad batch get --id <taskId> 跟踪状态）：
-# siluzan-tso ad campaign-create -a <mediaCustomerId> --name "品牌A-搜索广告" --budget 100 --location-ids 2840
-
-# 第五步：按方案创建广告组（以第一个地区/产品词方向为例）
-siluzan-tso ad adgroup-create \
-  -a <mediaCustomerId> \
-  --campaign-id <campaignId> \
-  --campaign-name "<campaignName>" \
-  --name "核心词_running shoes" \
-  --max-cpc 100000
-
-# 第六步：查询新建广告组 ID
-siluzan-tso ad groups -a <mediaCustomerId> --json
-
-# 第七步：添加推荐关键词
-siluzan-tso ad keyword-create \
-  -a <mediaCustomerId> \
-  --campaign-id <campaignId> \
-  --campaign-name "<campaignName>" \
-  --adgroup-id <adgroupId> \
-  --adgroup-name "核心词_running shoes" \
-  --keywords "running shoes,sport shoes,marathon shoes"
-
-# 第八步：创建广告创意（RSA）
-siluzan-tso ad ad-create \
-  -a <mediaCustomerId> \
-  --adgroup-id <adgroupId> \
-  --adgroup-name "核心词_running shoes" \
-  --final-url "https://www.brand-a.com/running-shoes" \
-  --headlines "专业跑步鞋,轻量透气设计,品牌直销价" \
-  --descriptions "全球百万跑者信赖，专业助力每一步。,免费配送，30天无理由退换。" \
-  --path1 "跑步鞋" \
-  --path2 "特惠"
-
-# 第九步：验证广告已创建
-siluzan-tso ad list -a <mediaCustomerId>
-```
-
-### `ad smart prepare` 输出说明
-
-| 字段                               | 说明                     | AI Agent 使用方式          |
-| ---------------------------------- | ------------------------ | -------------------------- |
-| `industry.industryName`            | 匹配的行业               | 确认产品方向是否正确       |
-| `industry.language` / `languageId` | 推荐语言                 | 设置广告系列语言定向       |
-| `keywordIdeas`                     | 关键词列表（含月搜索量） | 筛选高搜索量词加入广告组   |
-| `budgetProportions`                | 地区预算比例             | 多地区方案中按比例分配预算 |
-| `account.currencyCode`             | 货币单位                 | 换算 `max-cpc` 的实际金额  |
-
-### JSON 输出格式（`--json`）
-
-```bash
-# 输出完整 JSON 供 AI Agent 程序化处理
-siluzan-tso ad smart prepare \
-  -a <mediaCustomerId> \
-  --url "https://www.brand-a.com" \
-  -w "running shoes" \
-  --json
-```
-
-```json
-{
-  "account": { "mediaCustomerId": "...", "currencyCode": "USD" },
-  "url": { "validated": true, "input": "https://..." },
-  "industry": { "industryCode": "...", "industryName": "...", "language": "English", "languageId": "1000" },
-  "languages": [...],
-  "keywordIdeas": [
-    { "keyword": "running shoes", "monthlySearch": 90500 },
-    { "keyword": "sport running shoes", "monthlySearch": 22200 }
-  ],
-  "budgetProportions": [
-    { "areaCode": "NA", "regionCodes": ["US", "CA"], "budgetProportion": 0.45 },
-    { "areaCode": "EU", "regionCodes": ["GB", "DE", "FR"], "budgetProportion": 0.30 }
-  ]
-}
-```
-
-**AI Agent 行为规范**：
-
-- 用户说「生成广告方案」「规划 Google 广告」时，**先运行 `ad smart prepare` 收集数据**，再基于数据规划方案
-- 关键词来自 `keywordIdeas`，根据月搜索量筛选，同时结合用户的产品词
-- 广告创意（标题/描述）由 AI Agent 自行生成，遵循 Google 广告规范（标题≤30字符，描述≤90字符）
-- 如有多个地区方向，按 `budgetProportions` 的比例分配日预算，为每个地区创建独立广告组
-- `ad campaign-create` / `ad smart create`（批量创建 API）的预算与 CPC 为**主币种展示金额**，与 Web 一致内部 `×100`；分步命令里 `ad adgroup-create`、`ad keyword-edit` 等金额单位以 `references/google-ads.md` 对应章节为准
-
----
-
 ## 流程十四：网站诊断与广告落地页评估
 
 对应页面：`/advertising/AICreation`（落地页质量评估入口）
@@ -950,18 +805,15 @@ siluzan-tso ad smart prepare \
 # 引导用户打开网站诊断页面（在 AICreation 流程中内嵌，或直接访问）
 siluzan-tso config show   # 取 webUrl
 
-# 诊断入口（在 AIGC 智投向导内）：
+# 诊断入口（网页 AICreation 向导内嵌）：
 # {webUrl}/v3/foreign_trade/tso/advertising/AICreation
 # → 输入推广链接时，系统会自动触发网站诊断
 ```
 
-**CLI 辅助验证**（与诊断配合使用）：
+**CLI 辅助**（诊断前后核对账户授权）：
 
 ```bash
-# 验证链接可访问性（接口：/query/media-account/GetSuitableLink）
-# → 此为内部辅助，Agent 在 AIGC 创建流程中会自动调用，无需手动执行
-
-# 如果链接验证失败，先确认账户 OAuth 正常
+# 如果链接或落地页异常，先确认账户 OAuth 正常
 siluzan-tso list-accounts -m Google --json
 # 检查 invalidOAuthToken 字段，若为 true 则先重新授权
 siluzan-tso account auth -m Google
@@ -971,7 +823,7 @@ siluzan-tso account auth -m Google
 
 | 诊断评级         | 建议操作                                             |
 | ---------------- | ---------------------------------------------------- |
-| 优秀（85分以上） | 可直接投放，继续完成 AIGC 方案生成                   |
+| 优秀（85分以上） | 可直接投放；CLI 方案轨见 `google-ads-campaign-plan.md` |
 | 良好（70-84分）  | 建议优化后投放，可先小预算测试                       |
 | 一般（60-69分）  | 重点改善转化代码和页面速度后再投                     |
 | 较差（60分以下） | 需先修复关键问题（参考诊断报告），否则广告效果会很差 |

package/dist/skill/report-templates/README.md

@@ -13,14 +13,14 @@
 
 ## 内容纲要文件
 
-| 文件                                 | 适用场景                                          |
-| ------------------------------------ | ------------------------------------------------- |
-| `google-period-report.md`            | Google 账户分析报告（周期/月度/诊断均用此模板）   |
-| `google-account-diagnosis-report.md` | Google 账户深度诊断（健康度/转化/结构等）         |
-| `google-ads-diagnosis.md`            | 与网页版《Google Ads 账户诊断报告》对齐的完整骨架 |
-| `meta-period-report.md`              | Meta（Facebook）账户周期报告                      |
-| `tiktok-period-report.md`            | TikTok 广告主周期报告                             |
-| `bing-period-report.md`              | Bing（BingV2）分析报告                            |
+| 文件                                 | 适用场景                                                                                                       |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `google-period-report.md`            | Google 账户分析报告（周期/月度/诊断均用此模板）                                                                |
+| `google-account-diagnosis-report.md` | Google 账户深度诊断（健康度/转化/结构等）                                                                      |
+| `google-ads-diagnosis.md`            | 与网页版《Google Ads 账户诊断报告》对齐的完整骨架                                                              |
+| `meta-period-report.md`              | Meta（Facebook）账户周期报告                                                                                   |
+| `tiktok-period-report.md`            | TikTok 广告主周期报告                                                                                          |
+| `bing-period-report.md`              | Bing（BingV2）分析报告                                                                                         |
 | `okki-weekly-google-client.md`       | **OKKI 周报**：Google 发客户固定话术 + 精简维度 CLI；**Excel 仅 Agent 脚本**（无 CLI 写表子命令），见 SKILL P6 |
 
 ---

package/dist/skill/report-templates/REPORT-WORKFLOW.md

@@ -21,12 +21,12 @@
 
 根据媒体与用户意图，选择 `report-templates/` 下对应的 `*.md`：
 
-| 意图                   | Google                               | Meta                    | TikTok                    | Bing                    |
-| ---------------------- | ------------------------------------ | ----------------------- | ------------------------- | ----------------------- |
-| 周期分析 / 月报 / 周报 | `google-period-report.md`            | `meta-period-report.md` | `tiktok-period-report.md` | `bing-period-report.md` |
-| OKKI 周报 / 固定话术发客户（Google） | `okki-weekly-google-client.md` | — | — | — |
-| **询盘分析** / 固定运营触发（Goog账户询盘分析 / 我给你询盘信息分析Google账号XXX效果） | `google-inquiry-analysis.md`（**严格 3 个月** + 用户上传询盘资料 + 8 Sheet xlsx；见 SKILL **P7**） | — | — | — |
-| 深度诊断 / 健康检查    | `google-account-diagnosis-report.md` | 同周期，注明能力受限    | 同周期                    | 同周期                  |
+| 意图                                                                                  | Google                                                                                             | Meta                    | TikTok                    | Bing                    |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------- | ----------------------- |
+| 周期分析 / 月报 / 周报                                                                | `google-period-report.md`                                                                          | `meta-period-report.md` | `tiktok-period-report.md` | `bing-period-report.md` |
+| OKKI 周报 / 固定话术发客户（Google）                                                  | `okki-weekly-google-client.md`                                                                     | —                       | —                         | —                       |
+| **询盘分析** / 固定运营触发（Goog账户询盘分析 / 我给你询盘信息分析Google账号XXX效果） | `google-inquiry-analysis.md`（**严格 3 个月** + 用户上传询盘资料 + 8 Sheet xlsx；见 SKILL **P7**） | —                       | —                         | —                       |
+| 深度诊断 / 健康检查                                                                   | `google-account-diagnosis-report.md`                                                               | 同周期，注明能力受限    | 同周期                    | 同周期                  |
 
 无精确匹配时，用最接近媒体的同类 `*.md`，并在报告开头注明。
 
@@ -72,12 +72,12 @@
 
 ## 未知报告名处理
 
-| 用户措辞                       | 映射                                                              |
-| ------------------------------ | ----------------------------------------------------------------- |
-| 月报、周报、投放总结、效果回顾 | 周期分析 → 对应媒体 `*-period-report.md`                          |
-| **使用 okki 周报模板 / OKKI 周报 / okki 周报**（Google + 区间） | **固定话术 + 精简表 +（按需）Excel** → `okki-weekly-google-client.md`（见 SKILL **P6**）；Excel **仅**由 Agent 脚本生成，**无** CLI 内置写表子命令 |
+| 用户措辞                                                                                                                                              | 映射                                                                                                                                                                                                 |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 月报、周报、投放总结、效果回顾                                                                                                                        | 周期分析 → 对应媒体 `*-period-report.md`                                                                                                                                                             |
+| **使用 okki 周报模板 / OKKI 周报 / okki 周报**（Google + 区间）                                                                                       | **固定话术 + 精简表 +（按需）Excel** → `okki-weekly-google-client.md`（见 SKILL **P6**）；Excel **仅**由 Agent 脚本生成，**无** CLI 内置写表子命令                                                   |
 | **Goog账户询盘分析 / Google 账户询盘分析 / 分析XXX Google账号的询盘效果 / 我给你询盘信息分析Google账号XXX效果**（或含「询盘 + 账户 + Google」三要素） | **询盘 + 账户合并分析 + 严格 3 个月 + 8 Sheet xlsx** → `google-inquiry-analysis.md`（见 SKILL **P7**）；询盘资料用户上传任意载体，宿主 Agent 解析落盘 `inquiries.json`，xlsx **仅**由 Agent 脚本生成 |
-| 健康检查、诊断、账户分析       | 诊断 → `google-account-diagnosis-report.md`（Google）或周期型降级 |
-| 对比、汇报、给客户看           | 以周期型为骨架，简化版本                                          |
+| 健康检查、诊断、账户分析                                                                                                                              | 诊断 → `google-account-diagnosis-report.md`（Google）或周期型降级                                                                                                                                    |
+| 对比、汇报、给客户看                                                                                                                                  | 以周期型为骨架，简化版本                                                                                                                                                                             |
 
 无法识别时，默认按**周期分析**处理，并在报告开头注明推断。