siluzan-tso-cli 1.1.13 → 1.1.14-beta.10

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

@@ -32,6 +32,7 @@
 > - 若当前会话中尚未阅读上述任一文件，AI 必须先主动阅读，再继续下一步流程，而不是直接生成广告计划或文案。
 > - 在首次阅读后，AI 需用自己的话向用户**简要复述**上述文档中与本次任务强相关的 3～5 条关键合规/策略要点，并询问用户是否有本地特殊限制需要补充。
 > - 后续生成的关键词、文案、出价与结构，必须**显式遵守这些规则**；一旦与规则冲突，应以规则优先，并向用户说明原因（例如：某些词因合规或商标问题被自动剔除）。
+> - **方案阶段措辞**：输出结构/投放方案时，用「方案草案 / 结构蓝图 / 待你确认后再执行」等表述；**避免**「可立即执行 / 拿到参数就立刻跑命令」等暗示可跳过用户确认的说法。回复开头宜有一行**已读规则文档清单**（本 `google-ads.md` + 上表 `references/google-ads-rules/` 中实际打开的文件名）。
 
 ### 第二步：向用户补齐关键信息
 
@@ -124,7 +125,7 @@ siluzan-tso ad campaigns -a 6326027735 --start 2026-03-01 --end 2026-03-31
 siluzan-tso ad campaigns -a 6326027735 --json
 ```
 
-输出字段：名称、状态（`statusV2`）、类型（`channelTypeV2`）、预算、点击数、展示数。
+输出字段：名称、状态、类型、预算、点击数、展示数（具体字段名以 `--json` 为准；另有 CLI 派生的 `statusDisplay`、`budgetDisplay` 等便于阅读）。
 
 ---
 
@@ -199,36 +200,38 @@ siluzan-tso ad adgroup-create \
   --campaign-id <campaignId> \
   --campaign-name <campaignName> \
   --name <adGroupName> \
-  --max-cpc <金额（微单位）>
+  --max-cpc <主币种金额>
 ```
 
-| 选项                     | 说明                                               | 必填 |
-| ------------------------ | -------------------------------------------------- | ---- |
-| `-a, --account <id>`     | Google mediaCustomerId                             | ✅   |
-| `--campaign-id <id>`     | 所属广告系列 ID（来自 `campaigns --json`）         | ✅   |
-| `--campaign-name <name>` | 所属广告系列名称                                   | ✅   |
-| `--name <name>`          | 广告组名称                                         | ✅   |
-| `--max-cpc <amount>`     | 最高 CPC 出价（最小货币单位，如 `100000` = 1 USD） | ✅   |
-| `--status <status>`      | `ENABLED \| PAUSED`（默认 `ENABLED`）              |      |
+> **金额单位**：`--max-cpc` 为 **主币种金额**（如 `1.5` 表示 ¥1.50），CLI 内部 `Math.round(value × 100)` 写入「分」字段，与前端表单 `arithmetic.times(maxCPCAmount, 100)`、`ad adgroup-edit` 完全一致。**禁止** 按 Google micros（×1,000,000）填写。
+
+| 选项                     | 说明                                                       | 必填 |
+| ------------------------ | ---------------------------------------------------------- | ---- |
+| `-a, --account <id>`     | Google mediaCustomerId                                     | ✅   |
+| `--campaign-id <id>`     | 所属广告系列 ID（来自 `campaigns --json`）                 | ✅   |
+| `--campaign-name <name>` | 所属广告系列名称                                           | ✅   |
+| `--name <name>`          | 广告组名称                                                 | ✅   |
+| `--max-cpc <amount>`     | 最高 CPC 出价，主币种金额（如 `1.5` = ¥1.50；CLI 内部 ×100）| ✅   |
+| `--status <status>`      | `ENABLED \| PAUSED`（默认 `ENABLED`）                      |      |
 
 **示例：**
 
 ```bash
-# 在广告系列下创建广告组，最高 CPC 1 USD
+# 在广告系列下创建广告组，最高 CPC ¥1
 siluzan-tso ad adgroup-create \
   -a 6326027735 \
   --campaign-id campaign_001 \
   --campaign-name "品牌推广_春季" \
   --name "核心词_跑步鞋" \
-  --max-cpc 100000
+  --max-cpc 1
 
-# 创建时设为暂停状态
+# 创建时设为暂停状态，最高 CPC ¥1.5
 siluzan-tso ad adgroup-create \
   -a 6326027735 \
   --campaign-id campaign_001 \
   --campaign-name "品牌推广_春季" \
   --name "竞品词" \
-  --max-cpc 150000 \
+  --max-cpc 1.5 \
   --status PAUSED
 ```
 
@@ -255,6 +258,43 @@ siluzan-tso ad adgroup-status -a 6326027735 --id adgroup_001 --status Enabled
 
 ---
 
+### 广告组编辑（名称 / 最高 CPC / 组级目标 CPA）
+
+先用 **`ad groups … --json`** 查看当前的 **`maxCPCAmountDisplay`**、**`targetCpaAmountDisplay`**（主币种金额）等，再用本命令只改传入的字段。
+
+```bash
+siluzan-tso ad adgroup-edit \
+  -a <accountId> \
+  --id <adGroupId> \
+  [--name <新名称>] \
+  [--max-cpc <主币种金额>] \
+  [--target-cpa <主币种金额>] \
+  [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>]
+```
+
+> **金额单位（必读）**：所有金额参数均按 **主币种金额** 传入（如 `1.5` 表示 ¥1.50）；CLI 内部 `Math.round(value × 100)` 写入后端「分」字段，与 `ad campaign-edit`、前端表单完全一致。**禁止** 按 Google micros（×1,000,000）填写。
+
+| 选项 | 说明 |
+|------|------|
+| `--max-cpc` | 最高 CPC，主币种金额（与 `ad groups --json` 中 **`maxCPCAmountDisplay`** 对齐）。 |
+| `--target-cpa` | 组级目标 CPA，主币种金额（与 `ad groups --json` 中 **`targetCpaAmountDisplay`** 对齐）。写入 **> 0** 才会更新。 |
+| `--name` | 新名称（可选）。 |
+
+**示例：**
+
+```bash
+# 先取 JSON，读取 maxCPCAmountDisplay / targetCpaAmountDisplay（主币种金额）算新值后再写回
+siluzan-tso ad groups -a 6326027735 --json
+
+# 把最高 CPC 调整到 ¥2
+siluzan-tso ad adgroup-edit -a 6326027735 --id 195548094874 --max-cpc 2
+
+# 设置目标 CPA = ¥50，并改名
+siluzan-tso ad adgroup-edit -a 6326027735 --id 195548094874 --target-cpa 50 --name "核心词_降价后"
+```
+
+---
+
 ### 广告组删除
 
 ```bash
@@ -277,11 +317,12 @@ siluzan-tso ad adgroup-delete -a 6326027735 --id adgroup_001
 siluzan-tso ad list -a <accountId> [选项]
 ```
 
-| 选项                     | 说明                           |
-| ------------------------ | ------------------------------ |
-| `-a, --account <id>`     | Google mediaCustomerId（必填） |
-| `--start / --end <date>` | 统计日期范围                   |
-| `--json`                 | 输出原始 JSON                  |
+| 选项                     | 说明                                                                 |
+| ------------------------ | -------------------------------------------------------------------- |
+| `-a, --account <id>`     | Google mediaCustomerId（必填）                                       |
+| `--start / --end <date>` | 统计日期范围                                                         |
+| `--include-deleted`      | 包含已删除的广告（默认不传；传则网关加 `readDeleted=true`，审计/排障用） |
+| `--json`                 | 输出原始 JSON                                                        |
 
 **示例：**
 
@@ -293,6 +334,28 @@ siluzan-tso ad list -a 6326027735
 siluzan-tso ad list -a 6326027735 --json
 ```
 
+### 拒审与政策（`ad list --json`）
+
+使用 **`siluzan-tso ad list -a <accountId> [--start/--end] --json`**（或 **`siluzan-tso google-analysis ads … --json`**，与 `references/account-analytics.md` 中 `ads` 子命令一致）巡检素材审核状态。
+
+**在 JSON 中可重点查看的键名（以当次 stdout 为准，多为 camelCase）：**
+
+- **`policyApprovalStatusV2`**（及可能出现的 **`policyApprovalStatus`**）：审核总状态。常见数值含义（若为数字）：**`2`** 表示不通过（拒审）、**`3`** 表示受限通过；若为字符串则按字面量解析。
+- **`approvalStatusDetails`**：政策相关说明的**摘要串**，多条证据之间常用 **`;`** 分隔。**不提供**与控制台一一对应的「政策主题」结构化数组；需要更细粒度编码时须另辟数据源或与维护方确认。
+- **`statusV2`**：广告启用状态；排除已移除条目时用 **`Removed`** 等值过滤（以实际枚举为准）。
+
+**同源拉数**：`ad list` 与 **`google-analysis ads`** 在默认参数下列表数据一致；任选其一做拒审巡检即可，仍以 **当次 `--json`** 为准。若使用 **`ad list --include-deleted`**，会多传 `readDeleted=true`，与未带该参数的 **`google-analysis ads`** 口径可能不一致。
+
+### 转化与价值（`ad list --json`，需网关已返回对应字段）
+
+在已部署的 Google 网关上，创意列表 JSON 中除 **`spend`**、**`conversions`**、**`impressions`**、**`ctr`** 等外，还可关注（键名以当次输出为准）：
+
+- **`allConversions`**
+- **`conversionsValue`**
+- **`conversionsValuePerImpression`**（可能由后端计算属性序列化；若无则用 **`conversionsValue / impressions`** 在聚合后自行计算）
+
+带 **`--start` / `--end`** 时，底层按日分段，**同一创意 `id` 可能多行**；做窗口汇总或 A/B 比较前须在宿主 **按 `id` 聚合** 后再算比率。宿主编排下的 **自动优化 SOP** 见 **`references/hosted-automation-optimize-index.md`**。
+
 ---
 
 ### 创建广告（自适应搜索广告 RSA）
@@ -562,11 +625,11 @@ siluzan-tso ad batch get --id <recordId>
 siluzan-tso ad batch update --id <recordId> [选项]
 ```
 
-| 选项                     | 说明                                          |
-| ------------------------ | --------------------------------------------- |
-| `--budget <amount>`      | 新预算（最小货币单位，如 `8500` = 85 元 CNY） |
-| `--url <url>`            | 新推广链接                                    |
-| `--campaign-name <name>` | 新广告系列名称                                |
+| 选项                     | 说明                                                                |
+| ------------------------ | ------------------------------------------------------------------- |
+| `--budget <amount>`      | 新日预算，主币种金额（如 `85` 表示 ¥85；CLI 内部自动 ×100 写入「分」） |
+| `--url <url>`            | 新推广链接                                                          |
+| `--campaign-name <name>` | 新广告系列名称                                                      |
 
 ### publish — 发布草稿
 
@@ -621,7 +684,7 @@ siluzan-tso keyword -k "running shoes" --json
 
 > - 默认行为：不加 `--draft` 时，CLI 直接走「立即发布」路径（`DraftStatus: Published`）。
 > - 草稿行为：加上 `--draft` 时，仅创建草稿记录（`DraftStatus: Draft`），需后续用 `ad batch publish` 才真正提交给 Google。  
->   广告组、关键词、广告创意的直接创建走另一套 Google 网关 API，均有对应的 `adgroup-create`、`keyword-create`、`ad-create` 等命令。  
+>   广告组、关键词、广告创意的分步创建请使用 `adgroup-create`、`keyword-create`、`ad-create` 等命令。  
 >   任务异步处理，任务 ID 可通过 `ad batch get --id <id>` 跟进进度。
 
 ---
@@ -758,33 +821,42 @@ siluzan-tso ad campaign-edit \
   -a <accountId> \
   --id <campaignId> \
   [--name <新名称>] \
-  [--budget <预算（最小货币单位）>] \
+  [--budget <主币种金额>] \
   [--bidding <出价策略>] \
-  [--bid-ceiling <出价上限>] \
+  [--bid-ceiling <主币种金额>] \
+  [--target-cpa <主币种金额>] \
   [--search-network true|false] \
   [--content-network true|false]
 ```
 
+> **金额单位（必读）**：所有金额参数均按 **主币种金额**（如 `100` 表示 ¥100，支持小数 `10.5`）传入；CLI 内部 `Math.round(value × 100)` 写入后端「分」字段，与前端表单、`ad campaign-create`、`ad batch update` 完全一致。**禁止** 按 Google micros（×1,000,000）口径填写，会被后端按「分」解读，导致金额放大 10000 倍。
+
 | 选项                | 说明                                                                      |
 | ------------------- | ------------------------------------------------------------------------- |
 | `--name`            | 新广告系列名称                                                            |
-| `--budget`          | 新预算，最小货币单位（如 100000 = 1 USD）                                 |
+| `--budget`          | 新日预算，主币种金额（如 `100` = ¥100；`10.5` = ¥10.50）                  |
 | `--bidding`         | 出价策略：`TARGET_SPEND` \| `TARGET_CPA` \| `TARGET_ROAS` \| `MANUAL_CPC` |
-| `--bid-ceiling`     | `TARGET_SPEND` 出价上限（最小货币单位，0 = 不限）                         |
-| `--target-cpa`      | `TARGET_CPA` 目标 CPA                                                     |
+| `--bid-ceiling`     | `TARGET_SPEND` 出价上限，主币种金额（`0` = 不限）                         |
+| `--target-cpa`      | `TARGET_CPA` 目标 CPA，主币种金额                                         |
 | `--search-network`  | 投放 Google 搜索：`true` \| `false`                                       |
 | `--content-network` | 投放展示网络：`true` \| `false`                                           |
 
 **示例：**
 
 ```bash
-# 修改名称和预算
+# 修改名称和预算（日预算 ¥5000）
 siluzan-tso ad campaign-edit -a 6326027735 --id 23509626948 \
-  --name "搜索-春季促销-2026" --budget 500000
+  --name "搜索-春季促销-2026" --budget 5000
+
+# 在原预算基础上 +10 元（典型相对运算流程）：
+# 1) 先 GET 系列详情，读出 budgetDisplay（主币种）
+# 2) 计算新值（主币种）= budgetDisplay + 10
+# 3) 把新值（主币种）作为 --budget 传入；CLI 内部自动 ×100
+siluzan-tso ad campaign-edit -a 6326027735 --id 23509626948 --budget 10.01
 
 # 切换出价策略为 TARGET_CPA，目标 CPA 2 USD
 siluzan-tso ad campaign-edit -a 6326027735 --id 23509626948 \
-  --bidding TARGET_CPA --target-cpa 200000
+  --bidding TARGET_CPA --target-cpa 2
 ```
 
 ---
@@ -808,18 +880,18 @@ siluzan-tso ad adgroup-rename -a 6326027735 --id 195548094874 --name "核心词_
 
 ## ad ad-edit — 广告创意编辑（自适应搜索广告 RSA）
 
-与网页端一致：先按日期范围从 **`GET {googleApi}/admanagement/v2/list/{account}`** 拉取该广告完整对象，再 **`PUT {googleApi}/admanagement/campaign/{account}/{adId}`** 提交合并后的 JSON。成功时响应体与请求体字段结构一致（含 `id`、`activeuseridg`、`typeV2`、`statusV2` 等）。
+与网页端一致：先用 **`siluzan-tso ad list -a <accountId> [--start/--end] --json`** 取得该广告的完整 JSON，再用本命令只修改传入的选项；未改动的字段由 **`siluzan-tso`** 按列表原值带回。
 
-CLI 会在请求前自动设置 **Datapermission**（与浏览器 `datapermission` 头同源逻辑），避免网关侧权限相关错误。
+CLI 会自动附带数据权限相关请求头，减少权限类错误。
 
-### 网关 JSON 与 CLI 参数对应（常用字段）
+### `ad list --json` 常见键名与 CLI 选项（常用）
 
-| 网关字段                                            | 说明                                    | CLI                                         |
+| 列表 JSON 键名                                      | 说明                                    | CLI                                         |
 | --------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
 | `id`                                                | 广告 ID                                 | `--id`                                      |
 | `activeuseridg`                                     | 账户 mediaCustomerId                    | `-a` / `--account`                          |
 | `headlinePart1` / `headlinePart2` / `headlinePart3` | 前 3 条标题                             | `--headlines` 前 3 项                       |
-| `AddtionalHeadlines`                                | 第 4～15 条标题（网关拼写为 Addtional） | `--headlines` 第 4 项起                     |
+| `AddtionalHeadlines`                                | 第 4～15 条标题（历史拼写 Addtional）     | `--headlines` 第 4 项起                     |
 | `adDescription` / `adDescription2`                  | 前 2 条描述                             | `--descriptions` 前 2 项                    |
 | `AddtionalAdDescriptions`                           | 第 3～4 条描述                          | `--descriptions` 第 3 项起                  |
 | `finalUrl`                                          | 落地页                                  | `--final-url`                               |
@@ -842,30 +914,6 @@ siluzan-tso ad ad-edit \
   [--status Enabled|Paused]
 ```
 
-**与 curl 等价的网页请求形态（示意，勿把真实 Token 写入文档或仓库）：**
-
-```http
-PUT {googleApi}/admanagement/campaign/{activeuseridg}/{id}
-Content-Type: application/json
-
-{
-  "id": "<adId>",
-  "activeuseridg": "<account>",
-  "headlinePart1": "...",
-  "headlinePart2": "...",
-  "headlinePart3": "...",
-  "adDescription": "...",
-  "adDescription2": "...",
-  "adGroupId": "...",
-  "adGroup": "...",
-  "finalUrl": "https://...",
-  "path1": "...",
-  "path2": "...",
-  "typeV2": "RESPONSIVE_SEARCH_AD",
-  "statusV2": "Paused"
-}
-```
-
 **示例：**
 
 ```bash
@@ -885,7 +933,7 @@ siluzan-tso ad ad-edit -a 6326027735 --id 802428202775 --status Paused
 
 ## ad keyword-delete — 搜索关键词删除
 
-与网页一致：**`DELETE {googleApi}/keywordmanagement/Keyword/{account}/batch`**，请求体为 **JSON 数组**，每项至少包含 **`adGroupId`**、**`id`**（关键词资源 id）。成功时 HTTP 2xx 下 **响应体常为空**，属正常现象；CLI 只要未报错即表示删除请求已送达网关。请求前会自动设置 **Datapermission**；DELETE 使用带 **Content-Length** 的原始请求，避免部分网关对带 body 的 DELETE 解析异常。
+先用 **`siluzan-tso ad keywords -a <accountId> … --json`** 取得关键词 **`id`** 与 **`adGroupId`**，再执行删除。成功时 CLI 正常结束；可用 **`ad keywords --json`** 再次核对列表。
 
 ```bash
 siluzan-tso ad keyword-delete \
@@ -894,16 +942,7 @@ siluzan-tso ad keyword-delete \
   --adgroup-id <adGroupId>
 ```
 
-> `--id` 与 `--adgroup-id` 来自 `ad keywords --json` 的 `id`、`adGroupId`（与网关字段名一致）。
-
-**与 curl 等价的请求形态（示意）：**
-
-```http
-DELETE {googleApi}/keywordmanagement/Keyword/{account}/batch
-Content-Type: application/json
-
-[{"adGroupId":"193360670606","id":"2474194779750"}]
-```
+> `--id` 与 `--adgroup-id` 来自 **`ad keywords --json`** 中的 **`id`**、**`adGroupId`**。
 
 **示例：**
 
@@ -919,21 +958,25 @@ siluzan-tso ad keyword-delete -a 6326027735 --id 2464982882313 --adgroup-id 1955
 
 ## ad keyword-edit — 搜索关键词编辑
 
-与网页一致：**先**按日期范围从 **`GET {googleApi}/keywordmanagement/v2/list/{account}`** 取该关键词完整对象，**再** **`PUT {googleApi}/keywordmanagement/Keyword/{account}/batch`**，请求体为 **JSON 数组**（通常一条），元素为合并后的关键词对象。CLI 会自动设置 **Datapermission**。
+与网页一致：**先** **`siluzan-tso ad keywords … --json`** 取该关键词完整对象，**再**用本命令提交修改；未改字段随列表结果保留。
 
-### 网关字段与 CLI 对应（常用）
+> **⚠️ 金额单位（与系列 / 组的金额字段不同！）**：关键词的 `maxCPC` 字段单位是 **「主币种元」**（直接是元，不是「分」），CLI 直接透传 **不做 ×100 转换**。这与 `ad campaign-edit --budget` / `ad adgroup-edit --max-cpc` 等"用户传元、CLI 内部 ×100"的命令**口径相反**。
+>
+> 验证依据：前端 `KeywordList.vue:266` 用 `filterSpend(maxCPC)` 直接展示原值，对应 `useFormatter.js:86` 的 `filterSpend` 内部不 ÷100（对比 `filterBudget` 显式 ÷100）。
+
+### `ad keywords --json` 常见键名与 CLI 选项（常用）
 
-| 网关字段                      | 说明                                      | CLI                          |
+| 列表 JSON 键名                | 说明                                      | CLI                          |
 | ----------------------------- | ----------------------------------------- | ---------------------------- |
 | `id`                          | 关键词资源 id                             | `--id`                       |
 | `keywordText`                 | 关键词文案（数组，一般一项）              | `--text` → `["..."]`         |
 | `matchTypeV2`                 | 匹配类型（网页用 Broad / Phrase / Exact） | `--match-type`               |
 | `matchType`                   | 另一套枚举（如 EXACT），列表里可能仍存在  | 一般随 list 结果保留，勿手改 |
-| `maxCPC`                      | 最高每次点击费用                          | `--max-cpc`                  |
+| `maxCPC`                      | 最高每次点击费用，**主币种金额**（直接是元，不要 ×100） | `--max-cpc`                  |
 | `finalURL`                    | 关键词级最终到达网址                      | `--final-url`                |
 | `adGroupId` / `campaignId` 等 | 层级与统计字段                            | 从列表保留                   |
 
-**注意：** 成功响应也是数组；**`id` 可能与请求不一致**（网关可能返回新资源 id）。CLI 若检测到变化会打印提示，后续请用 **返回体中的新 `id`** 再查列表或再编辑。
+**注意：** 成功响应也可能是数组；**`id` 可能与请求不一致**。CLI 若检测到变化会打印提示，后续请用 **返回体中的新 `id`** 再查列表或再编辑。
 
 **约束：** `--text`、`--match-type`、`--max-cpc`、`--final-url` 至少传一项。
 
@@ -947,27 +990,6 @@ siluzan-tso ad keyword-edit \
   [--final-url <url>]
 ```
 
-**与 curl 等价的请求形态（示意，勿写入真实 Token）：**
-
-```http
-PUT {googleApi}/keywordmanagement/Keyword/{account}/batch
-Content-Type: application/json
-
-[
-  {
-    "id": "<keywordId>",
-    "keywordText": ["广告工具1"],
-    "matchType": "EXACT",
-    "matchTypeV2": "Broad",
-    "maxCPC": 0,
-    "finalURL": "https://example.com",
-    "adGroupId": "...",
-    "campaignId": "...",
-    "...": "其余字段来自 list 接口"
-  }
-]
-```
-
 **示例：**
 
 ```bash
@@ -1179,13 +1201,13 @@ siluzan-tso list-accounts -m Google --json -k [mediaCustomerId]
 siluzan-tso ad campaigns -a 6326027735 --json
 # 假设 campaignId = campaign_001，campaignName = "品牌推广_春季"
 
-# 第四步：创建广告组（最高 CPC 1 USD = 100000 微单位）
+# 第四步：创建广告组（最高 CPC ¥1，主币种金额；CLI 内部 ×100 写入「分」）
 siluzan-tso ad adgroup-create \
   -a 6326027735 \
   --campaign-id campaign_001 \
   --campaign-name "品牌推广_春季" \
   --name "核心词_跑步鞋" \
-  --max-cpc 100000
+  --max-cpc 1
 
 # 第五步：查询新建广告组 id
 siluzan-tso ad groups -a 6326027735 --json

package/dist/skill/references/hosted-automation-monitoring-json.md

@@ -0,0 +1,94 @@
+# 异常监控巡检：`siluzan-tso` CLI `--json` 键名与命令
+
+> **主题索引**：[`hosted-automation-scenarios.md`](hosted-automation-scenarios.md)  
+> **编排责任**：定时、HTTP 探活、通知等在宿主。本页只列 **读数命令与常见 JSON 键名**。  
+> **统计日 / 时区**：与自控场景相同，见 [`hosted-automation-self-control.md`](hosted-automation-self-control.md)「统计日与今日」。
+
+宿主做定时巡检时，**只以 `siluzan-tso … --json` 当次 stdout 的键名为准**。Google Ads API 文档里的资源名（如 `billing_setup`、`account_budget`、`amount_served_micros`）**与本 CLI 输出不是同一套命名**，不要当作本仓库 JSON 的键去解析。若某键缺失，**禁止猜测**：以实际输出为准，或换用 `references/account-analytics.md` 中的其它子命令。
+
+---
+
+## 1. 余额枯竭 / 续航不足（多账户批扫）
+
+**批扫（推荐）** — 命令：
+
+```bash
+siluzan-tso balance-scan -m Google [--threshold-days <n>] [--min-balance <n>] [--json]
+```
+
+`--json` 时根结构为 **`{ ok, data: { items }, meta }`**（以实际输出为准）。宿主常用字段：
+
+| 用途 | JSON 路径 / 字段名 |
+|------|---------------------|
+| 账户 | `data.items[].mediaCustomerId`、`data.items[].name`、`data.items[].advertiserName` |
+| 余额（主币种金额，与平台余额接口一致） | **`data.items[].balance`**（由 `remainingAccountBudget` 计算而来） |
+| 近 7 日估算日均消耗 | **`data.items[].dailySpend`** = 近 7 日总消耗 / 7（窗口为 **[T-7, T-1]**，即截至昨天的 7 个自然日，**不含当天**，避免拉到当天未结算数据） |
+| 按余额÷日均估算的续航天数 | **`data.items[].remainingDays`** = `balance / dailySpend`（消耗过低 < `minDailySpend` 时为 `null`） |
+| 建议充值额（按 `meta.thresholds.targetDaysForTopup` 目标） | **`data.items[].recommendedTopup`** |
+| 命中原因（阈值逻辑） | **`data.items[].hitReason`**：`low-days` \| `low-balance` \| `both` |
+| 币种 / 状态 / OAuth | `data.items[].currencyCode`、`data.items[].status`、`data.items[].invalidOAuthToken` |
+| 本轮扫描元数据 | **`meta`**：`scannedAccounts`、`validAccounts`、`hitCount`、`thresholds`（含 `days`、`minBalance`、`minDailySpend`、`targetDaysForTopup`）、`generatedAt` 等 |
+
+**单账户** — 命令：
+
+```bash
+siluzan-tso balance -m Google --accounts <mediaCustomerId> --json
+```
+
+`items[]` 每行：**`mediaCustomerId`**、**`remainingAccountBudget`**、**`status`**、**`currencyCode`**、**`name`**（与 `references/accounts.md` 中 `balance` 说明一致）。
+
+**账户总览（区间内的费用与日均，可与续航逻辑组合）** — 命令：
+
+```bash
+siluzan-tso google-analysis overview -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+根对象常见字段：**`remainingAccountBudget`**、**`averageDailyCost`**、**`totalCost`**、**`activeDays`**、**`currencyCode`**、**`accountId`**；**`currentPeriod`** / **`previousPeriod`** 为对象块，内含 **`spend`**、`impressions`、`clicks`、`conversions` 等与 `references/account-analytics.md` 总览口径一致的指标（块内还可能出现 **`currencyCode`**）。
+
+---
+
+## 2. 花费异动（按系列 × 日历小时）
+
+命令：
+
+```bash
+siluzan-tso google-analysis campaign-hour -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+**根 JSON 为数组**（不是 `items` 包装）。每元素常见字段：
+
+**`campaignId`**、**`campaignName`**、**`date`**、**`hour`**、**`spend`**、`impressions`、`clicks`、`conversions`。
+
+宿主侧可做：同一 `campaignId` 在相邻小时或相邻日的 **`spend`** 对比、滑动均值、超阈值告警等（阈值与统计时区由宿主配置，见 [`hosted-automation-self-control.md`](hosted-automation-self-control.md)「统计日与今日」）。
+
+---
+
+## 3. 落地页 URL 收集（HTTP 探活由宿主完成）
+
+**仅拉 URL 列表（无日期参数）**：
+
+```bash
+siluzan-tso google-analysis final-urls -a <mediaCustomerId> --json
+```
+
+根为 **对象**：**键名**为网关返回的资源标识（以当次 JSON 为准），**值为字符串数组**（每个元素是一条最终到达网址）。CLI **不**代发 HTTP 请求判断 4xx/5xx；死链判定须在宿主对 URL 执行 HEAD/GET（注意频率与 robots/合规）。
+
+**按创意行拉数**（可与拒审、启停共用一轮数据）：
+
+```bash
+siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+`items[]` 为网关原样字段集合；落地页相关键名以当次输出为准（类型说明里常见 **`finalurl`**；亦可用 **`google-analysis ads`** 列表，结构见 `references/google-ads.md` / `account-analytics.md`）。命中后暂停创意用 **`ad ad-status`**（见 `references/google-ads.md`），写后复核再次 `ad list --json` 看 **`statusV2`**。
+
+---
+
+## 4. 广告素材拒审
+
+不依赖 `PolicyTopic` 等 API 资源名；直接读 CLI 拒审字段：**`policyApprovalStatusV2`**、**`approvalStatusDetails`**、**`statusV2`** 等。逐步说明见 **`references/google-ads.md`**「拒审与政策」；**`ad list`** 与 **`google-analysis ads`** 列表同源，任选其一做巡检。
+
+---
+
+## 5. 账户「封禁」与 Google 客户状态（暂不展开）
+
+Google 客户级 **`SUSPENDED` / `CANCELED`** 与 **`list-accounts --json`** 中 **`status`** 的逐项对应关系**不在本页维护**；宿主若需该判定，请以内部运维约定或后续专门文档为准。

package/dist/skill/references/hosted-automation-optimize-ab-winner.md

@@ -0,0 +1,69 @@
+# SOP：同组多创意 A/B — 停输家、保赢家（Ad）
+
+> **索引**：[`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md)
+
+---
+
+## 业务目标（宿主配置化）
+
+在同一 **广告组** 内存在多条可比较的创意时，根据约定窗口内的 **转化价值效率**、**全部转化** 或宿主侧统计检验，将**明显劣势**的创意 **Paused**，保留优势创意继续投放。显著性水平、最小样本、冷却期由宿主配置。
+
+---
+
+## 检查项（宿主每轮）
+
+### 1. 拉创意列表
+
+```bash
+siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+（等价：`siluzan-tso google-analysis ads …`。）
+
+### 2. 按组筛选、按创意聚合
+
+- 对同一 **`adGroupId`** 下的行，先按创意 **`id`** 聚合（见索引「按日多行」）：对 **`impressions`**、**`clicks`**、**`spend`**、**`conversions`**、**`allConversions`**、**`conversionsValue`** **求和**。  
+- **每次展现价值（聚合后）**：宿主计算  
+
+  `cvpi = (Σ conversionsValue) / (Σ impressions)`，当分母为 0 时跳过该创意判定。
+
+若单行上已有后端提供的 **`conversionsValuePerImpression`**，在未聚合前**勿直接跨日相加**；应在聚合后用上式或按业务约定只对单日行比较。
+
+### 3. 参与判定的最小样本（示例）
+
+- 聚合后 **`impressions`**（或 **`clicks`**）低于配置下限的创意**不参与**胜负判定。  
+- 同组内「活跃且达样本」的创意 **≥ 2** 条时才进入 A/B 决策。
+
+### 4. 统计显著性
+
+**p 值、贝叶斯后验、序贯检验等**须由宿主实现；CLI **不提供**检验函数。可用聚合后的 **`conversions`/`clicks`** 或 **`conversionsValue`/`impressions`** 等输入自定义检验。
+
+---
+
+## 最终操作
+
+对判定为 **Loser** 的创意：
+
+```bash
+siluzan-tso ad ad-status -a <mediaCustomerId> --id <adId> --status Paused
+```
+
+（若需 `--start`/`--end` 见 `google-ads.md`。）
+
+**不在此 SOP 内**：Google Ads 界面「将流量倾斜给赢家」的算法开关；宿主仅能 **停输家** 或结合人工/网页调整轮换策略。
+
+---
+
+## 写后复核
+
+```bash
+siluzan-tso ad list -a <mediaCustomerId> --start <当日或下一窗> --end <…> --json
+```
+
+确认 Loser 的 **`statusV2`** 为 **`Paused`**；Winner 仍为 **`ENABLED`**（或宿主期望状态）。
+
+---
+
+## 通知（宿主）
+
+建议 **P2**：含 `mediaCustomerId`、**`adGroupId`**、输/赢 **`id`**、聚合指标摘要与判定规则版本号，便于审计。

package/dist/skill/references/hosted-automation-optimize-index.md

@@ -0,0 +1,32 @@
+# 宿主编排：自动优化（Google）— 文档索引
+
+> **编排责任**：定时、阈值、多轮状态（如「连续 3 日未改善」）、统计检验、通知（P1/P2）由 **宿主** 实现。  
+> **本组文档**：说明如何用 `siluzan-tso` **拉检查项**、**执行写操作**、**写后复核**；每条 SOP 独立成文，避免单文件过长。
+
+| 文档 | 场景 |
+|------|------|
+| [`hosted-automation-optimize-weak-downbid.md`](hosted-automation-optimize-weak-downbid.md) | 表现差：组/创意 **降价或暂停** |
+| [`hosted-automation-optimize-scale.md`](hosted-automation-optimize-scale.md) | 高转化：**提预算 / 上调目标 CPA** 扩量 |
+| [`hosted-automation-optimize-ab-winner.md`](hosted-automation-optimize-ab-winner.md) | 同组多创意：**A/B 决胜负、停输家** |
+
+**必读交叉引用**：`SKILL.md`（金额与 `*Display` 硬规范）、`references/google-ads.md`（`ad campaign-edit` / `ad adgroup-edit` / `ad-status`）、`references/account-analytics.md`（日期与 `google-analysis`）、`references/tips.md`（`--json`）、[`hosted-automation-self-control.md`](hosted-automation-self-control.md)（统计日与时区约定）。
+
+---
+
+## 通用约定（三条 SOP 共用）
+
+### 1. 统计区间
+
+`--start` / `--end` 为 **`YYYY-MM-DD`**，与宿主业务日一致；约定见 **`hosted-automation-self-control.md`**「统计日与今日」。
+
+### 2. `ad list` / `ad groups` 与「按日多行」
+
+`admanagement/v2/list`（`ad list`、`google-analysis ads`）在带日期区间时，底层 GAQL 含 **`segments.date`**，**同一创意 `id` 可出现多行（一日一行）**。做「过去 7 天总展现 / 总花费 / 总转化」时，宿主须对 **`items[]` 按广告 `id`（及需要时 `adGroupId`）聚合** 后再算比率或阈值，**禁止**把未聚合的多行直接当作多条独立创意误判。
+
+### 3. JSON 键名以当次 `--json` 为准
+
+下列键名为当前网关常见命名；若某键缺失，以实际 stdout 为准，勿猜测。
+
+### 4. 写操作与复核
+
+所有写入须遵守 **`references/google-ads.md`** 的确认与安全约定；写后**同区间或下一统计日**再拉一次读命令核对 `statusV2`、预算、`targetCpaAmount` 等。