siluzan-tso-cli 1.1.20-beta.18 → 1.1.20-beta.19

package/README.md

@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills  # 写入自定义目录
 siluzan-tso init --force             # 强制覆盖已存在文件
 ```
 
-> **注意**：当前为测试版（1.1.20-beta.18），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+> **注意**：当前为测试版（1.1.20-beta.19），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/index.js

@@ -114185,7 +114185,7 @@ Google Ads \u56FD\u5BB6/\u5730\u533A\u5E38\u91CF\uFF08\u5171 ${n} \u6761\uFF09
     ]
   );
   console.log(
-    '\n\u62D3\u8BCD\u65F6\u6307\u5B9A\u5730\u533A\uFF1Asiluzan-tso keyword -k "\u79CD\u5B50" --geo <id>[,<id>...]\n  \u4F8B\uFF1A\u7F8E\u56FD=2840\uFF0C\u4E2D\u56FD=2826\n'
+    '\n\u62D3\u8BCD\u65F6\u6307\u5B9A\u5730\u533A\uFF1Asiluzan-tso keyword -k "\u79CD\u5B50" --geo <id>\n  \u4F8B\uFF1A\u7F8E\u56FD=2840\uFF0C\u4E2D\u56FD=2826\n  \u591A\u4E2A --geo \u4E3A\u6C47\u603B\u6570\u636E\uFF1B\u5206\u5E02\u573A\u5BF9\u6BD4\u8BF7\u591A\u6B21\u8C03\u7528\u3001\u6BCF\u6B21\u53EA\u4F20\u4E00\u4E2A id\n'
   );
 }
 async function runKeywordSuggest(opts) {
@@ -114377,7 +114377,7 @@ function register21(program2) {
   attachBaseCliOptions(keywordCmd);
   keywordCmd.requiredOption("-k, --keyword <words>", "\u641C\u7D22\u8BCD\uFF0C\u591A\u4E2A\u9017\u53F7\u5206\u9694").option(
     "--geo <ids>",
-    "geoTargetConstant ID\uFF0C\u9017\u53F7\u5206\u9694\uFF08\u5148 keyword geo-list \u67E5 id\uFF1B\u4F8B 2840=\u7F8E\u56FD,2826=\u4E2D\u56FD\uFF09"
+    "geoTargetConstant ID\uFF08\u5148 keyword geo-list\uFF1B\u4F8B 2840=\u7F8E\u56FD\uFF09\u3002\u591A\u4E2A ID \u4E3A\u6C47\u603B\u6307\u6807\uFF1B\u5206\u5E02\u573A\u987B\u591A\u6B21\u8C03\u7528\u3001\u6BCF\u6B21\u53EA\u4F20\u4E00\u4E2A"
   ).option("--url <url>", "\u516C\u53F8/\u4EA7\u54C1\u7F51\u5740\uFF08\u586B\u5199\u540E\u89E6\u53D1\u7F51\u5740\u62D3\u8BCD\uFF1B\u4E0E --google-only \u4E92\u65A5\uFF09").option("--google-only", "\u4EC5 Google Keyword Planner\uFF0C\u4E0D\u53E0\u52A0\u7F51\u5740\u62D3\u8BCD").option("--include <words>", "\u7ED3\u679C\u5FC5\u987B\u5305\u542B\u7684\u8BCD\uFF0C\u9017\u53F7\u6216\u7A7A\u683C\u5206\u9694").option("--exclude <words>", "\u7ED3\u679C\u4E0D\u5305\u542B\u7684\u8BCD\uFF0C\u9017\u53F7\u6216\u7A7A\u683C\u5206\u9694").action(async (opts) => {
     await runKeywordSuggest({
       token: opts.token,

package/dist/skill/SKILL.md

@@ -152,7 +152,7 @@ Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令
   - `ad campaigns --json/--json-out` → `budget`（元，与 `campaign-edit --budget` 同口径）
   - `ad groups --json` → `maxCPCAmountYuan` / `targetCpaAmountYuan`（元）
   - `google-analysis campaigns-*.json` → `budgetAmountYuan` / `campaignTargetCpaYuan` / `maximizeConversionsTargetCpaYuan` / `spend` / `averageCpc` / `costPerConversion`（均元）
-  - `keyword --json` → 美元 `averageCpcUSD` / `lowTopOfPageBidUSD` / `highTopOfPageBidUSD`；人民币同名 CNY 字段；根级 `usdToCnyExchangeRate`、`bidAmountCurrency:"USD"`；限定市场用 `keyword geo-list` + `--geo 2840,2826`
+  - `keyword --json` → 美元 `averageCpcUSD` / `lowTopOfPageBidUSD` / `highTopOfPageBidUSD`；人民币同名 CNY 字段；根级 `usdToCnyExchangeRate`、`bidAmountCurrency:"USD"`；限定市场用 `keyword geo-list` + `--geo <id>`（**多 id 一次调用 = 汇总指标**；分市场对比须多次调用、每次只传一个 `--geo`，见 `references/keyword-planner-workflows.md`）
 - **品牌名优先级**：(1) 用户明确提供 → (2) `list-accounts.mag.advertiserName` → (3) 用户提供网址 → 域名占位并标注 `[待确认品牌名]`。**严禁**把英文域名翻译为虚构中文品牌。
 - 完整字段表见 `references/currency.md`。
 

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.20-beta.18",
-  "publishedAt": 1779330011717
+  "version": "1.1.20-beta.19",
+  "publishedAt": 1779333530583
 }

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

@@ -2,7 +2,13 @@
   "_meta": {
     "schema": "campaign-create/v2",
     "doc": "campaign-create-template.md",
-    "note": "以 _ 开头的键仅作说明，CLI 提交前会剥离；字段名一律 PascalCase，直接对齐后端 CampaignCreationRecord + Campaign 契约"
+    "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",
@@ -16,11 +22,9 @@
 
   "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,
@@ -28,20 +32,16 @@
     "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": [],
@@ -72,6 +72,16 @@
         "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"
+        }
       }
     ],
 
@@ -107,10 +117,11 @@
 
         "AdsForBatchJob": [
           {
-            "AdTitle": null,
+            "_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",

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

@@ -6,7 +6,7 @@
 
 **`ad campaign-create` 提交前**，CLI 在 JSON 原文之外额外处理（不影响 validate 读到的「元」口径）：
 
-1. 剥除以 `_` 开头的注解键（如 `_meta`、`_comment_budget`）；
+1. 剥除以 `_` 开头的注解键（如 `_meta`、`_comment_budget`、`_comment_finalurl`）；
 2. 外层 body：`account` → 数字 `customerId`；补全 `KeywordRecommendationsV2`（按广告组名，`Value` 可为 `[]`）；`googleDataRecordId` 缺省为 `""`（与 Web 智投一致）；
 3. `campaign` 金额字段「元」→「分」（×100）；
 4. `ExtensionsForBatchJob` 中 SITELINK 的 `Properties` 规范化（见下文「SITELINK」）。
@@ -15,12 +15,78 @@ JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-templa
 
 ---
 
+## 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 --json-out ./snap-campaign
+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）
@@ -111,6 +177,8 @@ JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-templa
 
 | 字段 | 类型 | 说明 |
 | ---- | ---- | ---- |
+| `typeV2` | string | 必填 `SITELINK` |
+| `AssetFieldType` | string | **必填** `SITELINK`（与 `typeV2` 一致；缺省会导致部分账户 BatchJob 失败） |
 | `level` / `Level` | string | 系列级填 `Campaign` |
 | `Properties` | object | 键值均为字符串；见下表 |
 | `Properties.Text` | string | 链接文字（必填）。可写 `LinkText`，提交前会映射为 `Text` |
@@ -147,7 +215,9 @@ JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-templa
 | 字段                          | 类型     | 必填 | 说明                                          |
 | ----------------------------- | -------- | :--: | --------------------------------------------- |
 | `TypeV2`                      | string   |      | RSA 填 `RESPONSIVE_SEARCH_AD`                  |
-| `DestinationUrl` / `Finalurl` | string   |  ✅  | 落地页                                        |
+| `DestinationUrl`              | string   |  ✅  | 展示/编辑用落地页 URL                         |
+| `Finalurl`                    | string   |  ✅  | **后端 BatchJob 必填**；与 `DestinationUrl` 填**相同** URL。勿只写前者——validate 可能仍通过，create 会失败 |
+| `AdTitle`                     | null \| string |  | 可选；无标题时写 `null`（与 Web 智投一致）   |
 | `Path1` / `Path2`             | string   |      | 显示路径，**≤ 15 字符**（CJK 按 2 计）        |
 | `headlinePart1/2/3`           | string   |  ✅  | 前 3 条标题；**每条 ≤ 30 字符**（CJK 按 2 计） |
 | `AddtionalHeadlines`          | string[] |      | 第 4–15 条标题（合计 ≤ 15）                   |
@@ -165,4 +235,4 @@ JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-templa
 | Google Ads BatchJob                                                                         | RSA 字段数与字符上限；关键词词面非空；SITELINK `Line2`/`Line3` ≤25 字且不可 null；系列名不可与在投/暂停系列重名 |
 | CLI 实务                                                                                    | `Budget > 0`、地理/语言至少 1 项、日期格式与先后、出价策略与配套字段                                |
 
-`ad campaign-validate` 通过不保证 BatchJob 成功。异步结果用 `ad batch get` 轮询；`HasFailed` / 部分失败时用 `ad batch diff` 对照 JSON 补缺，系列级失败时改 JSON 重提，勿在半成品上反复整包创建。写操作须 `--commit`，见 `references/google-ads.md` § ad campaign-create。
+`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/google-ads.md

@@ -267,6 +267,8 @@ siluzan-tso keyword -k <搜索词> [--geo <geoTargetConstantIds>] [--url <url>]
 siluzan-tso keyword geo-list [--country-code <US,CN,...>] [--name-contains <text>] [--json]
 ```
 
+`--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」。
 
 ---

package/dist/skill/references/keyword-planner-workflows.md

@@ -75,12 +75,32 @@ Google Keyword Planner 的搜索量/CPC 与**目标国家/地区**相关。CLI
    siluzan-tso keyword geo-list --json-out ./snap-geo
    # 或按代码过滤：--country-code US,CN
    ```
-2. **带地区拓词**：
+2. **带地区拓词**（单次只传 **一个** ID 时，指标对应该市场）：
    ```bash
-   siluzan-tso keyword -k "pipe" --geo 2840,2826 --json-out ./snap-kw
+   siluzan-tso keyword -k "pipe" --geo 2840 --json-out ./snap-kw-us
    ```
 
-常见 ID（与 `ad campaign-create --location-ids` 同源）：美国 `2840`，中国 `2826`。多国家可逗号分隔。
+常见 ID（与 `ad campaign-create --location-ids` 同源）：美国 `2840`，中国 `2826`。
+
+### ⚠️ 多地区 `--geo`：返回汇总数据，无法按地区拆分
+
+`--geo` 可传多个 ID（逗号分隔，如 `--geo 2840,2826`），网关会把它们一并传给 `keywordidea/google?geoTargetConstantIds=...`。此时 Google Keyword Planner 返回的 `montlySearch`、CPC、竞争度等是**跨所传地区的汇总/合并口径**，**不是**「每个国家各一行」或 JSON 里带 `geoTargetConstantId` 分字段。
+
+| 需求 | 做法 |
+| ---- | ---- |
+| 只要「美国+中国合在一起」的市场参考 | 一次调用：`--geo 2840,2826` |
+| 要对比美国 vs 中国各自搜索量/CPC | **多次调用**，每次 `--geo` **只传一个** ID，分别 `--json-out` 到不同目录（如 `./snap-kw-us`、`./snap-kw-cn`） |
+
+**禁止**把 `--geo 2840,2826` 的单次落盘结果当成「美国一套、中国一套」两张表；报告里若写多市场对比，须注明数据来源为分次 `keyword` 调用。
+
+```bash
+# 正确：分市场各查一次
+siluzan-tso keyword -k "pipe" --geo 2840 --json-out ./snap-kw-us
+siluzan-tso keyword -k "pipe" --geo 2826 --json-out ./snap-kw-cn
+
+# 易误解：单次多 geo 只有汇总指标，无法在 items[] 内按国家拆开
+siluzan-tso keyword -k "pipe" --geo 2840,2826 --json-out ./snap-kw-merged
+```
 
 ---
 

package/dist/skill/scripts/install.ps1

@@ -9,7 +9,7 @@ $ErrorActionPreference = 'Stop'
 # -- Package info (injected at build time) ------------------------------------
 $PKG_NAME    = 'siluzan-tso-cli'
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-$PKG_VERSION = '1.1.20-beta.18'
+$PKG_VERSION = '1.1.20-beta.19'
 $CLI_BIN     = 'siluzan-tso'
 $SKILL_LABEL = 'Siluzan TSO'
 $INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'

package/dist/skill/scripts/install.sh

@@ -9,7 +9,7 @@ set -euo pipefail
 # -- Package info (injected at build time) ------------------------------------
 readonly PKG_NAME="siluzan-tso-cli"
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-readonly PKG_VERSION="1.1.20-beta.18"
+readonly PKG_VERSION="1.1.20-beta.19"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
 readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.1.20-beta.18",
+  "version": "1.1.20-beta.19",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",