siluzan-tso-cli 1.1.21 → 1.1.22-beta.10

package/dist/skill/references/{google-ads.md → google-ads/google-ads.md}

@@ -15,36 +15,32 @@
 
 | 需要的 ID           | 获取命令                                                     |
 | ------------------- | ------------------------------------------------------------ |
-| `accountId`（`-a`） | `siluzan-tso list-accounts --json` → `mediaCustomerId`       |
-| 广告系列 `id`       | `siluzan-tso ad campaigns -a <accountId> --json` → `id`      |
-| 广告组 `id`、`name` | `siluzan-tso ad groups -a <accountId> --json` → `id`、`name` |
-| 广告 `id`           | `siluzan-tso ad list -a <accountId> --json` → `id`           |
-| 关键词 `id`         | `siluzan-tso ad keywords -a <accountId> --json` → `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` |
+| 广告 `id`           | `siluzan-tso ad list -a <accountId> --json-out ./snap` → `id`           |
+| 关键词 `id`         | `siluzan-tso ad keywords -a <accountId> --json-out ./snap` → `id`       |
 
 ---
 
 ## 新建广告系列（方案 + 创建）
 
-> **Search 流程与校验**：`references/google-ads-campaign-plan.md`。本文件只写 **命令参数**（`campaign-validate` / `campaign-create` / `batch` 见下文各节）。
+> **Search 流程与校验**：`references/google-ads/google-ads-campaign-plan.md`。本文件只写 **命令参数**（`campaign-validate` / `campaign-create` / `batch` 见下文各节）。
 
 ---
 
 ## 新建 Performance Max（PMax）
 
-> **⛔ 暂未开放（生产）**：PMax CLI 搭建/写入能力仍在测试，**禁止** Agent 或用户通过 `ad pmax-create` / `pmax-validate` / `pmax-edit` 等命令操作。请在 **Google Ads UI** 新建与管理 PMax。本地联调可设环境变量 `SILUZAN_PMAX_SETUP=1` 后使用 CLI（开发专用）。
->
-> 下列命令文档保留供后续上线参考，**当前勿执行**。
-
-> **与 Search 隔离**：勿用 `campaign-create` 或 `campaign-create-template.json`。网关摘录见 `references/pmax-api.md`。
+> **与 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]`（含图片尺寸/比例/大小校验） |
+| 校验 | `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` → `channelTypeV2` 为 `PERFORMANCE_MAX` |
+| 复核 | `siluzan-tso ad campaigns -a <accountId> --json-out ./snap` → `channelTypeV2` 为 `PERFORMANCE_MAX` |
 
 **网关**：`POST {googleApiUrl}/accounts/{accountId}/campaign/pmax`（`PmaxCampaignManagementController`）。**同步**返回 `campaignId`、`assetGroupId`、`budgetId`；无 `ad batch get/diff`。
 
@@ -70,13 +66,13 @@
 | 报表 | `ad pmax-report-asset-groups` / `ad pmax-report-geo` |
 | 删活动 | `ad campaign-delete -a <id> --id <campaignId>`（与 Search 共用；勿用 `ad campaign-edit`） |
 
-模板与 HTTP 对照：`references/pmax-api.md`。
+模板与 HTTP 对照：`references/google-ads/pmax-api.md`。
 
 ---
 
 ## 广告的编辑
 
-已上线系列勿用 `campaign-create` 覆盖；改方案/重建见 **`google-ads-campaign-plan.md`** § 已上线后的修改；分步 CRUD 用下文 `ad *-edit` 等，写后读命令复核。
+已上线系列勿用 `campaign-create` 覆盖；改方案/重建见 **`google-ads/google-ads-campaign-plan.md`** § 已上线后的修改；分步 CRUD 用下文 `ad *-edit` 等，写后读命令复核。
 
 ### 广告新增
 
@@ -93,10 +89,10 @@
 ### 查询列表
 
 ```bash
-siluzan-tso ad campaigns -a <accountId> [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>] [--json]
+siluzan-tso ad campaigns -a <accountId> [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>] [--json-out ./snap]
 ```
 
-`--json` 下 `budget` 为日预算（主币种「元」，CLI 已 ÷100），另有 `statusDisplay`（状态文案）。
+落盘 JSON 中 `budget` 为日预算（主币种「元」，CLI 已 ÷100），另有 `statusDisplay`（状态文案）。
 
 ### 启停
 
@@ -116,7 +112,7 @@ siluzan-tso ad campaign-delete -a <accountId> --id <campaignId>
 
 ## 批量创建工作流（adgroup + keyword + ad + extension）
 
-适用：从 Excel/JSON 任务清单一次性创建多个广告组及其内容。`adgroup-create` / `keyword-create` / `ad-create` / `extension <type>` 均已支持 **`--json`**，网关响应里直接含 `id`，**无需**再 `ad groups --json` 反查。
+适用：从 Excel/JSON 任务清单一次性创建多个广告组及其内容。`adgroup-create` / `keyword-create` / `ad-create` / `extension <type>` 写命令均支持 **`--json-out`**，落盘响应里直接含 `id`，**无需**再 `ad groups --json-out ./snap` 反查。
 
 **推荐节奏**（每广告组）：
 
@@ -124,14 +120,14 @@ siluzan-tso ad campaign-delete -a <accountId> --id <campaignId>
 # 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)
+  --name "<adgroupName>" --max-cpc 2.0 --status ENABLED --json-out ./snap)
 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
+  --keywords "kw1,\"kw2\",[kw3]" --final-url "https://..." --json-out ./snap
 
 # 3. 添加 RSA 广告
 siluzan-tso ad ad-create -a <accountId> \
@@ -139,19 +135,19 @@ siluzan-tso ad ad-create -a <accountId> \
   --final-url "https://..." \
   --headlines "标题1,标题2,标题3,..." \
   --descriptions "描述1,描述2,..." \
-  [--path1 <path1>] [--path2 <path2>] --json
+  [--path1 <path1>] [--path2 <path2>] --json-out ./snap
 
 # 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
+    --text "..." --url "..." [--line2/--line3 ...] --json-out ./snap
 done
 ```
 
-**幂等性（Agent 侧）**：CLI 当前无 `--idempotent` 参数，请脚本侧先用 `ad groups --json` / `ad keywords --json` / `ad list --json` / `ad extension list --json` 取已有实体清单，按 `name + adgroupId` 等键过滤待创建项；HTTP 400 多半是重复创建，建议捕获并跳过。
+**幂等性（Agent 侧）**：CLI 当前无 `--idempotent` 参数，请脚本侧先用 `ad groups --json-out ./snap` / `ad keywords --json-out ./snap` / `ad list --json-out ./snap` / `ad extension list --json-out ./snap` 取已有实体清单，按 `name + adgroupId` 等键过滤待创建项；HTTP 400 多半是重复创建，建议捕获并跳过。
 
-**字符上限**（Agent 侧校验）：标题 ≤30、描述 ≤90、CALLOUT ≤25、Sitelink Text ≤25。CJK 字符按 2 计（Google 规范），`google-ads-rules/google-ads-compliance.md` 有详细规则。
+**字符上限**（Agent 侧校验）：标题 ≤30、描述 ≤90、CALLOUT ≤25、Sitelink Text ≤25。CJK 字符按 2 计（Google 规范），`google-ads/rules/google-ads-compliance.md` 有详细规则。
 
 ---
 
@@ -160,7 +156,7 @@ done
 ### 查询列表
 
 ```bash
-siluzan-tso ad groups -a <accountId> [--start/--end <date>] [--json]
+siluzan-tso ad groups -a <accountId> [--start/--end <date>] [--json-out ./snap]
 ```
 
 ### 创建
@@ -170,7 +166,7 @@ siluzan-tso ad adgroup-create \
   -a <accountId> \
   --campaign-id <campaignId> --campaign-name <campaignName> \
   --name <adGroupName> --max-cpc <主币种金额> \
-  [--status ENABLED|PAUSED] [--json | --json-out <path>]
+  [--status ENABLED|PAUSED] [--json-out <path>]
 ```
 
 | 选项                     | 说明                                                               | 必填 |
@@ -181,9 +177,9 @@ siluzan-tso ad adgroup-create \
 | `--name <name>`          | 广告组名称                                                         | ✅   |
 | `--max-cpc <amount>`     | 最高 CPC（主币种金额）                                             | ✅   |
 | `--status`               | `ENABLED`（默认）/ `PAUSED`                                        |      |
-| `--json` / `--json-out`  | 输出网关返回的完整 adgroup 对象（含 `id` / `maxCPCAmountYuan` 等） |      |
+| `--json-out`  | 输出网关返回的完整 adgroup 对象（含 `id` / `maxCPCAmountYuan` 等） |      |
 
-**返回字段（--json）**：网关同步返回完整 adgroup，含 **`id`**（adgroupId）、`name`、`campaignId`、`statusV2`、`maxCPCAmountYuan`（元，CLI 已 ÷100）、`typeV2: "SEARCH_STANDARD"` 等 75+ 字段。批量创建脚本应直接读 `id`，**不需要**再次 `ad groups --json` 反查。
+**返回字段（--json-out）**：网关同步返回完整 adgroup，含 **`id`**（adgroupId）、`name`、`campaignId`、`statusV2`、`maxCPCAmountYuan`（元，CLI 已 ÷100）、`typeV2: "SEARCH_STANDARD"` 等 75+ 字段。批量创建脚本应直接读 `id`，**不需要**再次 `ad groups --json-out ./snap` 反查。
 
 ### 启停
 
@@ -193,7 +189,7 @@ siluzan-tso ad adgroup-status -a <accountId> --id <adGroupId> --status <Enabled|
 
 ### 编辑
 
-先用 `ad groups --json` 查看当前值，再只改传入字段。
+先用 `ad groups --json-out ./snap` 查看当前值，再只改传入字段。
 
 ```bash
 siluzan-tso ad adgroup-edit \
@@ -202,7 +198,7 @@ siluzan-tso ad adgroup-edit \
   [--start/--end <YYYY-MM-DD>]
 ```
 
-`--max-cpc` / `--target-cpa` 与 `ad groups --json` 中 `maxCPCAmountYuan` / `targetCpaAmountYuan` 对齐（**元**，CLI 出口已统一）。
+`--max-cpc` / `--target-cpa` 与 `ad groups --json-out ./snap` 中 `maxCPCAmountYuan` / `targetCpaAmountYuan` 对齐（**元**，CLI 出口已统一）。
 
 ### 删除
 
@@ -217,12 +213,12 @@ siluzan-tso ad adgroup-delete -a <accountId> --id <adGroupId>
 ### 查询列表
 
 ```bash
-siluzan-tso ad list -a <accountId> [--start/--end <date>] [--include-deleted] [--json]
+siluzan-tso ad list -a <accountId> [--start/--end <date>] [--include-deleted] [--json-out ./snap]
 ```
 
 `--include-deleted` 用于审计/排障，会多传 `readDeleted=true`。
 
-### 拒审巡检（`--json`）
+### 拒审巡检（`--json-out`）
 
 关注 `policyApprovalStatusV2`（`2`=不通过、`3`=受限）、`approvalStatusDetails`（`;` 分隔摘要）、`statusV2`（过滤 `Removed`）。同源也可用 `google-analysis --sections ads --json-out <dir>`。
 
@@ -236,10 +232,10 @@ siluzan-tso ad ad-create \
   --headlines "标题1,标题2,标题3" \
   --descriptions "描述1,描述2" \
   [--path1 <≤15字符>] [--path2 <≤15字符>] \
-  [--json | --json-out <path>]
+  [--json-out <path>]
 ```
 
-`--headlines` 至少 3 条（≤30字符），`--descriptions` 至少 2 条（≤90字符）。**`--json`** 返回网关响应（含 `id` 等字段），便于批量脚本拿到 adId 后续编辑/启停。
+`--headlines` 至少 3 条（≤30字符），`--descriptions` 至少 2 条（≤90字符）。**`--json-out`** 落盘返回网关响应（含 `id` 等字段），便于批量脚本拿到 adId 后续编辑/启停。
 
 ### 启停 / 删除
 
@@ -255,7 +251,7 @@ siluzan-tso ad ad-delete -a <accountId> --id <adId>
 ### 查询
 
 ```bash
-siluzan-tso ad keywords -a <accountId> [--negative] [--start/--end <date>] [--json]
+siluzan-tso ad keywords -a <accountId> [--negative] [--start/--end <date>] [--json-out ./snap]
 ```
 
 ### 添加关键词
@@ -266,10 +262,10 @@ siluzan-tso ad keyword-create \
   --adgroup-id <adGroupId> --adgroup-name <adGroupName> \
   --campaign-id <campaignId> --campaign-name <campaignName> \
   --keywords "词1,词2,词3" [--final-url <url>] \
-  [--json | --json-out <path>]
+  [--json-out <path>]
 ```
 
-`--json` 输出 `{ request: { adgroupId, count }, response: ... }`，批量脚本可直接据此核对成功量。
+`--json-out` 落盘 `{ request: { adgroupId, count }, response: ... }`，批量脚本可直接据此核对成功量。
 
 ### 否定关键词
 
@@ -281,7 +277,7 @@ siluzan-tso ad keyword-negative-create \
   --keywords "词1,词2" \
   [--adgroup-id <id> --adgroup-name <name>]
 
-# 删除（先用 ad keywords --negative --json 获取 id）
+# 删除（先用 ad keywords --negative --json-out ./snap 获取 id）
 siluzan-tso ad keyword-negative-delete -a <accountId> --id <negativeKeywordId>
 ```
 
@@ -292,7 +288,7 @@ siluzan-tso ad keyword-negative-delete -a <accountId> --id <negativeKeywordId>
 对应页面 `/advertising/AICreationList`。
 
 ```bash
-siluzan-tso ad batch list [--state Creating|Successfully|Failed|HasFailed|Unpublished] [--customer-id <id>] [--start/--end <date>] [--json]
+siluzan-tso ad batch list [--state Creating|Successfully|Failed|HasFailed|Unpublished] [--customer-id <id>] [--start/--end <date>] [--json-out ./snap]
 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>
@@ -304,24 +300,24 @@ siluzan-tso ad batch publish --id <recordId>
 
 ## keyword — 关键字推荐
 
-多场景编排（竞品 URL + 种子、账户词叠市场指标、否词与建户表等）见 **`references/keyword-planner-workflows.md`**。
+多场景编排（竞品 URL + 种子、账户词叠市场指标、否词与建户表等）见 **`references/analytics/keyword-planner-workflows.md`**。
 
 ```bash
-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]
+siluzan-tso keyword -k <搜索词> [--geo <geoTargetConstantIds>] [--url <url>] [--google-only] [--include <words>] [--exclude <words>] [--json-out <dir>]
+siluzan-tso keyword geo-list [--country-code <US,CN,...>] [--name-contains <text>] [--json-out ./snap]
 ```
 
-`--geo` 传多个 ID（如 `2840,2826`）时，返回的搜索量/CPC/竞争度为**跨所传地区的汇总数据**，响应中**无**按地区拆分的字段。若要分别查看各市场指标，须**多次调用**且每次 `--geo` **只传一个** ID（详见 **`references/keyword-planner-workflows.md`**「多地区 `--geo`」）。
+`--geo` 传多个 ID（如 `2840,2826`）时，返回的搜索量/CPC/竞争度为**跨所传地区的汇总数据**，响应中**无**按地区拆分的字段。若要分别查看各市场指标，须**多次调用**且每次 `--geo` **只传一个** ID（详见 **`references/analytics/keyword-planner-workflows.md`**「多地区 `--geo`」）。
 
-`--url` 触发网址拓词（`websitereco`）并合并进结果；与 `--google-only` 互斥（仅 Google Keyword Planner 时用后者）。`--include`/`--exclude` 为本地过滤。仅 Google、不联网搜索的 Agent 编排见 **`references/keyword-planner-workflows.md`**「分支 B」。
+`--url` 触发网址拓词（`websitereco`）并合并进结果；与 `--google-only` 互斥（仅 Google Keyword Planner 时用后者）。`--include`/`--exclude` 为本地过滤。仅 Google、不联网搜索的 Agent 编排见 **`references/analytics/keyword-planner-workflows.md`**「分支 B」。
 
 ---
 
 ## ad campaign-validate — 投放 JSON 校验
 
-不提交 API；创建系列前**建议**跑。命令、选项、与 create 共用校验逻辑见 **`references/google-ads-campaign-plan.md`** § 校验与创建（后端/Google 硬约束，不含关键词分层占比）。
+不提交 API；创建系列前**建议**跑。命令、选项、与 create 共用校验逻辑见 **`references/google-ads/google-ads-campaign-plan.md`** § 校验与创建（后端/Google 硬约束，不含关键词分层占比）。
 
-**超长内容**：加 **`--json-out <dir>`**（推荐，与 create/batch 共用目录）或 `--json` 时响应含 `lengthViolations`（完整 `text` + JSON `path`）。Agent **勿自动截断**；须列出全部超长项与改写方案，用户确认后再改 JSON 并重跑 validate（流程见 `google-ads-campaign-plan.md` § 超长人工确认）。
+**超长内容**：加 **`--json-out <dir>`**（推荐，与 create/batch 共用目录）或 `--json-out` 时响应含 `lengthViolations`（完整 `text` + JSON `path`）。Agent **勿自动截断**；须列出全部超长项与改写方案，用户确认后再改 JSON 并重跑 validate（流程见 `google-ads/google-ads-campaign-plan.md` § 超长人工确认）。
 
 ---
 
@@ -349,7 +345,7 @@ 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；省略时按系列名自动匹配）
+# 可选：--campaign-id <id>（ad campaigns -a <accountId> --json-out ./snap；省略时按系列名自动匹配）
 
 # Failed：系列未创建，无需 diff；根据 get 的 reason/errors 改 JSON 后重提
 # siluzan-tso ad campaign-create --config-file ./campaign.json
@@ -370,14 +366,14 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json
    `ad campaign-delete -a <accountId> --id <campaignId>` → 按 `reason`/`errors` 修正 **campaign.json** → 重新 `ad campaign-create`。**不要**在脏系列上反复补建。
 
 2. **仅少数组/资产失败**（系列与大部分组已有 `Id`）：  
-   - 缺组：`ad adgroup-create`（`--json` 取 `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 batch diff` 比对维度：**系列是否存在 → 各 `AdGroupsForBatchJob[].Name` → 组内关键词（匹配类型+词面）→ RSA 首条标题 → 系列否定词 → 附加信息条数。默认按层级树状输出每条缺失的 **JSON 路径 + 计划内容 + 账户实况**；`--json` 可落盘完整结构。
+**`ad batch diff` 比对维度：**系列是否存在 → 各 `AdGroupsForBatchJob[].Name` → 组内关键词（匹配类型+词面）→ RSA 首条标题 → 系列否定词 → 附加信息条数。默认按层级树状输出每条缺失的 **JSON 路径 + 计划内容 + 账户实况**；`--json-out` 可落盘完整结构。
 
-**`ad batch get` 输出：**摘要表 + 后端原始 `reason` + 完整 `errors`（或 `--json` 整条记录）。
+**`ad batch get` 输出：**摘要表 + 后端原始 `reason` + 完整 `errors`（或 `--json-out` 整条记录）。
 
 **CLI 在提交前只做三件事：**
 
@@ -399,7 +395,7 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json
 
 ```bash
 # 支持的策略枚举
-siluzan-tso ad campaign-bidding-strategies [--json]
+siluzan-tso ad campaign-bidding-strategies [--json-out ./snap]
 
 siluzan-tso ad campaign-edit \
   -a <accountId> --id <campaignId> \
@@ -429,7 +425,7 @@ siluzan-tso ad campaign-edit -a <accountId> --id <campaignId> \
   --bidding TARGET_CPA --target-cpa 80
 ```
 
-相对运算：先 `ad campaigns --json` 读 `budget`（已为主币种元）、`biddingStrategyTypeV2`，再传入。
+相对运算：先 `ad campaigns --json-out ./snap` 读 `budget`（已为主币种元）、`biddingStrategyTypeV2`，再传入。
 
 > PMax / 部分智能系列类型 Google 可能拒绝切换出价策略；以 API 返回错误为准。
 
@@ -445,9 +441,9 @@ siluzan-tso ad adgroup-rename -a <accountId> --id <adGroupId> --name <新名称>
 
 ## ad ad-edit — 广告创意编辑
 
-先用 `ad list --json` 取得完整 JSON，再只修改传入字段，未改字段从列表原值带回。
+先用 `ad list --json-out ./snap` 取得完整 JSON，再只修改传入字段，未改字段从列表原值带回。
 
-`ad list --json` 关键字段映射：
+`ad list --json-out ./snap` 关键字段映射：
 
 - `headlinePart1~3` + `AddtionalHeadlines` → `--headlines`（≥3条）
 - `adDescription`/`adDescription2` + `AddtionalAdDescriptions` → `--descriptions`（≥2条）
@@ -470,7 +466,7 @@ siluzan-tso ad ad-edit \
 
 ```bash
 # 先查询获取 id 和 adGroupId
-siluzan-tso ad keywords -a <accountId> --json
+siluzan-tso ad keywords -a <accountId> --json-out ./snap
 # 再删除
 siluzan-tso ad keyword-delete -a <accountId> --id <keywordId> --adgroup-id <adGroupId>
 ```
@@ -479,7 +475,7 @@ siluzan-tso ad keyword-delete -a <accountId> --id <keywordId> --adgroup-id <adGr
 
 ## ad keyword-edit — 搜索关键词编辑
 
-先用 `ad keywords --json` 取完整对象，再提交修改。`id` 可能与请求不一致，CLI 检测到变化会提示。
+先用 `ad keywords --json-out ./snap` 取完整对象，再提交修改。`id` 可能与请求不一致，CLI 检测到变化会提示。
 
 ```bash
 siluzan-tso ad keyword-edit \
@@ -488,7 +484,7 @@ siluzan-tso ad keyword-edit \
   [--max-cpc <n>] [--final-url <url>] [--status Enabled|Paused]
 ```
 
-传 `--match-type` 时 CLI 自动规范 `keywordText` 括号/引号格式。至少传一项。`--max-cpc` 为主币种元（CLI ×100 写入 `maxCPC`「分」字段，与 `adgroup-edit --max-cpc` 同口径）。`ad keywords --json` 出价见 `maxCPCYuan`。`--status` 写入 `userStatusV2`（与 Web 关键词开关一致，非系列的 `statusV2`）。
+传 `--match-type` 时 CLI 自动规范 `keywordText` 括号/引号格式。至少传一项。`--max-cpc` 为主币种元（CLI ×100 写入 `maxCPC`「分」字段，与 `adgroup-edit --max-cpc` 同口径）。`ad keywords --json-out ./snap` 出价见 `maxCPCYuan`。`--status` 写入 `userStatusV2`（与 Web 关键词开关一致，非系列的 `statusV2`）。
 
 ---
 
@@ -516,25 +512,25 @@ siluzan-tso ad keyword-negative-edit \
 
 ## ad extension — 附加信息管理
 
-修改方式为**先删后建**（无 PUT 接口）。所有 `extension <type>` 子命令均支持 `--json` / `--json-out`，输出网关返回的扩展对象（含 `id`），批量脚本可据此回填。
+修改方式为**先删后建**（无 PUT 接口）。所有 `extension <type>` 子命令均支持 `--json-out`，输出网关返回的扩展对象（含 `id`），批量脚本可据此回填。
 
 ```bash
 # 查询
-siluzan-tso ad extension list -a <accountId> [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET] [--json]
+siluzan-tso ad extension list -a <accountId> [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET] [--json-out ./snap]
 
 # 附加链接
 siluzan-tso ad extension sitelink -a <accountId> --text "文字" --url "https://..." \
-  [--line2/--line3 <text>] [--level Account|Campaign|AdGroup] [--campaign-id <id>] [--json]
+  [--line2/--line3 <text>] [--level Account|Campaign|AdGroup] [--campaign-id <id>] [--json-out ./snap]
 
 # 附加电话
 siluzan-tso ad extension call -a <accountId> --country-code "+86" --phone "4008001234" \
-  [--level Account|Campaign|AdGroup] [--json]
+  [--level Account|Campaign|AdGroup] [--json-out ./snap]
 
 # 附加宣传信息（≤25字符）
-siluzan-tso ad extension callout -a <accountId> --text "免费送货上门" [--level Account] [--json]
+siluzan-tso ad extension callout -a <accountId> --text "免费送货上门" [--level Account] [--json-out ./snap]
 
 # 附加结构化摘要
-siluzan-tso ad extension snippet -a <accountId> --header "Brands" --values "A,B,C" [--level Account] [--json]
+siluzan-tso ad extension snippet -a <accountId> --header "Brands" --values "A,B,C" [--level Account] [--json-out ./snap]
 
 # 删除
 siluzan-tso ad extension delete -a <accountId> --id <extensionId>
@@ -549,7 +545,7 @@ siluzan-tso ad extension delete -a <accountId> --id <extensionId>
 只读报告。屏蔽搜索词：先查到词，再用 `keyword-negative-create` 加否词。
 
 ```bash
-siluzan-tso ad search-terms -a <accountId> [--start/--end YYYY-MM-DD] [--json]
+siluzan-tso ad search-terms -a <accountId> [--start/--end YYYY-MM-DD] [--json-out ./snap]
 ```
 
 ---
@@ -615,12 +611,12 @@ siluzan-tso ad geo remove -a <accountId> --campaign-id <id> --location-id <id>
 
 ```bash
 # 系列级：账户下全部设备出价（可按系列过滤）
-siluzan-tso ad device-bid list -a <accountId> [--campaign-id <id>] [--json]
+siluzan-tso ad device-bid list -a <accountId> [--campaign-id <id>] [--json-out ./snap]
 
 # 广告组级
-siluzan-tso ad device-bid list -a <accountId> --level adgroup --campaign-id <id> --ad-group-id <id> [--json]
+siluzan-tso ad device-bid list -a <accountId> --level adgroup --campaign-id <id> --ad-group-id <id> [--json-out ./snap]
 
-# 修改系列设备出价（id 来自 list --json，或用 --device-type 自动匹配）
+# 修改系列设备出价（id 来自 list --json-out ./snap，或用 --device-type 自动匹配）
 siluzan-tso ad device-bid set -a <accountId> --campaign-id <id> --device-type Mobile --bid-modifier 0.8
 
 # 修改广告组设备出价

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

@@ -1,7 +1,5 @@
 # Performance Max 网关 API（CLI 对照）
 
-> **⛔ 暂未开放（生产）**：PMax CLI 搭建/写入仍在测试。Skill 路由已屏蔽；CLI 默认拒绝 `pmax-create` 等写入命令。请在 Google Ads UI 操作，或本地设 `SILUZAN_PMAX_SETUP=1` 联调。
->
 > 完整契约：Sammamish `src/GoogleAPI/docs/pmax-frontend-api.md`
 
 ---

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

@@ -0,0 +1,21 @@
+# Google Ads 优化与合规规则
+
+> 本目录为 **策略/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` | 敏感行业限制 |
+
+宿主编排下的自动优化分文件 SOP：`references/operations/hosted-automation-optimize-index.md`。

package/dist/skill/references/{google-ads-rules → google-ads/rules}/google-ads-account-audit.md

@@ -78,8 +78,8 @@ siluzan-tso google-analysis -a <CID> --sections ads-index
 ### 执行命令
 
 ```bash
-siluzan-tso ad campaigns -a <CID> --json
-siluzan-tso ad groups -a <CID> --json
+siluzan-tso ad campaigns -a <CID> --json-out ./snap
+siluzan-tso ad groups -a <CID> --json-out ./snap
 siluzan-tso google-analysis -a <CID> --sections campaigns
 ```
 
@@ -155,7 +155,7 @@ siluzan-tso google-analysis -a <CID> --sections overview
 ### 执行命令
 
 ```bash
-siluzan-tso ad campaigns -a <CID> --json
+siluzan-tso ad campaigns -a <CID> --json-out ./snap
 siluzan-tso google-analysis -a <CID> --sections campaigns
 siluzan-tso google-analysis -a <CID> --sections daily-metrics
 ```
@@ -192,7 +192,7 @@ siluzan-tso google-analysis -a <CID> --sections daily-metrics
 ```bash
 siluzan-tso google-analysis -a <CID> --sections keywords
 siluzan-tso google-analysis -a <CID> --sections search-terms
-siluzan-tso ad keywords -a <CID> --json
+siluzan-tso ad keywords -a <CID> --json-out ./snap
 siluzan-tso ad search-terms -a <CID>
 ```
 
@@ -243,7 +243,7 @@ siluzan-tso ad search-terms -a <CID>
 siluzan-tso google-analysis -a <CID> --sections ads
 siluzan-tso google-analysis -a <CID> --sections ads-index
 siluzan-tso google-analysis -a <CID> --sections extensions
-siluzan-tso ad list -a <CID> --json
+siluzan-tso ad list -a <CID> --json-out ./snap
 siluzan-tso ad extension list -a <CID>
 ```
 
@@ -260,7 +260,7 @@ siluzan-tso ad extension list -a <CID>
 
 ### 7.2 RSA 素材覆盖检查
 
-从 `ad list --json` 检查每个 RSA 的素材数量：
+从 `ad list --json-out ./snap` 检查每个 RSA 的素材数量：
 
 | 素材类型         | 最低要求 | 推荐数量   | 不足时影响                   |
 | ---------------- | -------- | ---------- | ---------------------------- |
@@ -383,7 +383,7 @@ siluzan-tso google-analysis -a <CID> --sections devices
 ```bash
 siluzan-tso google-analysis -a <CID> --sections campaigns
 siluzan-tso google-analysis -a <CID> --sections daily-metrics
-siluzan-tso ad campaigns -a <CID> --json
+siluzan-tso ad campaigns -a <CID> --json-out ./snap
 ```
 
 ### 10.1 预算利用率分析
@@ -529,12 +529,12 @@ siluzan-tso google-analysis -a <CID> --sections dimension-summary
 | 4   | CTR 持续下降           | `ads` 查广告强度和创意内容            | 广告疲劳                | 更新广告素材，添加新标题/描述             |
 | 5   | CTR 持续下降           | `campaigns` 查 searchImpressionShare  | 广告位置下降            | 检查出价竞争力和 QS                       |
 | 6   | 展示量大幅下降         | `campaigns` 查 searchBudgetLostIS     | 预算耗尽                | 增加预算                                  |
-| 7   | 展示量大幅下降         | `keywords` 查关键词状态               | 关键词被暂停或否定      | `ad keywords --json` 检查状态             |
-| 8   | 展示量大幅下降         | `campaigns` 查系列状态                | 广告被拒或系列暂停      | `ad campaigns --json` 检查状态            |
+| 7   | 展示量大幅下降         | `keywords` 查关键词状态               | 关键词被暂停或否定      | `ad keywords --json-out ./snap` 检查状态             |
+| 8   | 展示量大幅下降         | `campaigns` 查系列状态                | 广告被拒或系列暂停      | `ad campaigns --json-out ./snap` 检查状态            |
 | 9   | 转化量下降但点击正常   | `final-urls` 查转化率                 | 落地页问题（改版/故障） | 检查落地页是否可访问且正常                |
 | 10  | 转化量下降但点击正常   | `conversion-actions` 查转化操作       | 转化追踪代码失效        | 检查 Google Tag 是否正常触发              |
 | 11  | 预算花不出去           | `keywords` 查展示量和出价             | 出价过低无竞争力        | 提高出价或切换出价策略                    |
-| 12  | 预算花不出去           | `ad keywords --json` 查关键词数量     | 关键词太少或搜索量低    | 扩展关键词列表                            |
+| 12  | 预算花不出去           | `ad keywords --json-out ./snap` 查关键词数量     | 关键词太少或搜索量低    | 扩展关键词列表                            |
 | 13  | QS 整体下降            | `keywords` 查 QS 分布                 | 落地页体验下降          | 检查落地页加载速度和内容相关性            |
 | 14  | QS 整体下降            | `ads` 查广告相关性                    | 广告与关键词不匹配      | 重写广告，确保包含核心关键词              |
 | 15  | 移动端效果差           | `devices` 查移动端 CPA                | 移动落地页体验差        | 优化移动端页面或降低移动出价              |
@@ -542,7 +542,7 @@ siluzan-tso google-analysis -a <CID> --sections dimension-summary
 | 17  | 搜索展示份额骤降       | `campaigns` 查 searchRankLostIS       | 竞争对手加大投放        | 提高 QS 和出价应对                        |
 | 18  | 转化波动大（时高时低） | `daily-metrics` 查每日趋势            | 转化延迟或追踪不稳定    | `conversion-actions` 确认追踪和归因窗口   |
 | 19  | 花费突然激增           | `search-terms` 查新搜索词             | 广泛匹配触发大量新词    | 添加否定关键词，收紧匹配类型              |
-| 20  | 广告审核被拒           | `ad list --json` 查广告状态           | 广告违规政策            | 修改广告内容后重新提交                    |
+| 20  | 广告审核被拒           | `ad list --json-out ./snap` 查广告状态           | 广告违规政策            | 修改广告内容后重新提交                    |
 
 ## 14. CLI 审计命令序列
 
@@ -578,17 +578,17 @@ siluzan-tso google-analysis -a <CID> --sections conversion-actions
 
 # ---- 第二阶段：系列与结构 ----
 siluzan-tso google-analysis -a <CID> --sections campaigns
-siluzan-tso ad campaigns -a <CID> --json
-siluzan-tso ad groups -a <CID> --json
+siluzan-tso ad campaigns -a <CID> --json-out ./snap
+siluzan-tso ad groups -a <CID> --json-out ./snap
 
 # ---- 第三阶段：关键词与搜索词 ----
 siluzan-tso google-analysis -a <CID> --sections keywords
 siluzan-tso google-analysis -a <CID> --sections search-terms
-siluzan-tso ad keywords -a <CID> --json
+siluzan-tso ad keywords -a <CID> --json-out ./snap
 
 # ---- 第四阶段：创意与扩展 ----
 siluzan-tso google-analysis -a <CID> --sections ads
-siluzan-tso ad list -a <CID> --json
+siluzan-tso ad list -a <CID> --json-out ./snap
 siluzan-tso google-analysis -a <CID> --sections extensions
 siluzan-tso ad extension list -a <CID>
 
@@ -613,10 +613,10 @@ siluzan-tso google-analysis -a <CID> --sections gold-account
 siluzan-tso google-analysis -a <CID> --sections conversion-actions
 
 # ---- 账户结构梳理 ----
-siluzan-tso ad campaigns -a <CID> --json
-siluzan-tso ad groups -a <CID> --json
-siluzan-tso ad keywords -a <CID> --json
-siluzan-tso ad list -a <CID> --json
+siluzan-tso ad campaigns -a <CID> --json-out ./snap
+siluzan-tso ad groups -a <CID> --json-out ./snap
+siluzan-tso ad keywords -a <CID> --json-out ./snap
+siluzan-tso ad list -a <CID> --json-out ./snap
 
 # ---- 效果基线建立 ----
 siluzan-tso google-analysis -a <CID> --sections campaigns

package/dist/skill/references/{google-ads-rules → google-ads/rules}/google-ads-campaign-optimization.md

@@ -495,7 +495,7 @@ siluzan-tso ad batch get --id <taskId>
 
 ```bash
 # 查看当前系列设置
-siluzan-tso ad campaigns -a <CID> --json
+siluzan-tso ad campaigns -a <CID> --json-out ./snap
 
 # 切换到 Target CPA（数据充足后）
 # --target-cpa 是「主币种金额」，CLI 内部自动 ×100 写入；50 = 50 USD（不是微单位 5000）

package/dist/skill/references/{google-ads-rules → google-ads/rules}/google-ads-keyword-optimization.md

@@ -500,7 +500,7 @@ siluzan-tso ad keyword-create --keywords "[高转化词1],[高转化词2]" ...
 
 ```bash
 # 1. 拉取 30 天全量数据
-siluzan-tso google-analysis -a <CID> --sections keywords --start <30天前> --end <昨天> --limit 200
+siluzan-tso google-analysis -a <CID> --sections keywords --start <30天前> --end <昨天>
 
 # 2. 拉取按日趋势（看 CPA 趋势）
 siluzan-tso google-analysis -a <CID> --sections daily-metrics --start <30天前> --end <昨天>

package/dist/skill/references/{google-ads-rules → google-ads/rules}/google-ads-keyword-strategy.md

@@ -446,7 +446,7 @@ Broad Match + 受众信号 = 伪装成广泛定向的精准投放。
 CLI 命令格式：
 
 ```
-siluzan-tso keyword -k "搜索词" [--url <URL>] [--include <包含词>] [--exclude <排除词>] [--json]
+siluzan-tso keyword -k "搜索词" [--url <URL>] [--include <包含词>] [--exclude <排除词>] [--json-out ./snap]
 ```
 
 | 参数        | 说明                                                                             |
@@ -455,7 +455,7 @@ siluzan-tso keyword -k "搜索词" [--url <URL>] [--include <包含词>] [--excl
 | `--url`     | 配合网站 URL 获取更相关的建议；Google 会分析页面内容，返回与该网站更匹配的关键词 |
 | `--include` | 结果必须包含的词（逗号分隔），用于缩小建议范围                                   |
 | `--exclude` | 排除包含这些词的建议（逗号分隔），过滤无关结果                                   |
-| `--json`    | 输出 JSON 格式，便于程序化处理或进一步分析                                       |
+| `--json-out`    | 输出 JSON 格式，便于程序化处理或进一步分析                                       |
 
 **组合用法建议**：先用 `-k` 拉大探索范围，拿到初步结果后，再用 `--include` / `--exclude` 精筛，逐步收窄到高相关关键词集合。
 
@@ -495,7 +495,7 @@ Step 3: 竞品参考
 Step 4: 整理为关键词列表
   → 按意图分层：BOFU（交易意图）/ MOFU（商业调研）/ TOFU（信息意图）
   → 分配匹配类型：高价值已验证词 → Exact；商业意图词 → Phrase；探索词 → Broad
-  → 导出 JSON（--json）供批量导入或进一步加工
+  → 导出 JSON（--json-out）供批量导入或进一步加工
 ```
 
 ### 16.5 与其他章节的协同

package/dist/skill/references/{google-ads-rules → google-ads/rules}/google-ads-keyword-taxonomy.md

@@ -1,7 +1,7 @@
 # Google 搜索广告关键词分层与数量规范（Agent 参考）
 
 > 所属 skill：`siluzan-tso`。本文为**方案撰写参考**，**不由** `ad campaign-validate` / `ad campaign-create` 强制执行。  
-> 建户 JSON 契约与 CLI 硬约束见 `assets/campaign-create-template.md`、`references/google-ads-campaign-plan.md`。
+> 建户 JSON 契约与 CLI 硬约束见 `assets/campaign-create-template.md`、`references/google-ads/google-ads-campaign-plan.md`。
 
 ---
 
@@ -54,7 +54,7 @@
 | 技术词 | api/sdk/integration | payment sdk integration |
 | 问题词 | how to + 问题 | how to reduce failed payments |
 
-拓词编排见 `references/keyword-planner-workflows.md`；Planner 出价见 `averageCpc` / `lowTopOfPageBid` / `highTopOfPageBid` 与根级、每条 `bidAmountCurrency`。
+拓词编排见 `references/analytics/keyword-planner-workflows.md`；Planner 出价见 `averageCpc` / `lowTopOfPageBid` / `highTopOfPageBid` 与根级、每条 `bidAmountCurrency`。
 
 ---