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

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

@@ -0,0 +1,99 @@
+# SOP：高转化广告 — 提预算 / 上调目标 CPA 扩量（Campaign / Ad Group）
+
+> **索引**：[`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md)
+
+---
+
+## 业务目标（宿主配置化）
+
+在约定窗口内：系列（或策略允许的组）**转化价值相对花费**高、且存在**预算丢失展示份额**等「有量接不住」信号时，**小幅提高日预算**与/或 **上调目标 CPA**，并配合 **P1** 类通知。比例、冷却时间（避免频繁改预算触发学习期波动）由宿主配置。
+
+---
+
+## 检查项（宿主每轮）
+
+### 1. 系列报表（ROAS 代理、搜索丢失份额）
+
+```bash
+siluzan-tso google-analysis campaigns -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+根对象常见 **`campaigns[]`**，单行关注（键名以当次 stdout 为准）：
+
+- **`conversionsValuePerCost`**（与 Google「转化价值/费用」语义一致，作 ROAS 代理）
+- **`searchBudgetLostImpressionShare`**、**`searchRankLostImpressionShare`**、**`searchImpressionShare`**
+- **`spend`**、**`impressions`**、**`conversions`**、**`campaignId`**、**`campaignName`**
+
+> **说明**：**不要**仅用 `ad campaigns --json` 替代本步：系列列表接口未必带齐上述份额与 `conversionsValuePerCost`；扩量判据以 **`google-analysis campaigns`** 为主。
+
+### 2. 日预算与系列状态（写前读当前值）
+
+```bash
+siluzan-tso ad campaigns -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+关注 **`budget`** / **`budgetDisplay`**、**`statusV2`**、**`id`**（系列 ID），与 `SKILL.md` 金额硬规范一致后再算「+20%」等新预算。
+
+### 3. 消耗节奏（可选）
+
+```bash
+siluzan-tso google-analysis campaign-hour -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+根为**数组**：**`campaignId`**、**`date`**、**`hour`**、**`spend`**。宿主可做「近若干小时花费 vs 预期」的辅助条件。
+
+### 4. 条件示例（仅示意）
+
+- 连续 **N** 日 **`conversionsValuePerCost`** 高于宿主配置的「目标 × 倍数」。  
+- 且 **`searchBudgetLostImpressionShare`** 高于配置阈值（注意接口多为 **0–1 小数**，比较时与配置统一）。  
+- 可选：`campaign-hour` 上近端 **`spend`** 增速超过配置。
+
+---
+
+## 最终操作
+
+> **金额单位（关键）**：`ad campaign-edit` / `ad adgroup-edit` 所有金额参数均为 **主币种金额**（如 `100` 表示 ¥100，支持小数 `10.5`）；CLI 内部自动 `Math.round(value × 100)` 写入「分」字段。详见 `references/google-ads.md`「ad campaign-edit」金额单位说明。
+>
+> **必须先用 `*Display` 字段取主币种当前值，加减后再传回**；不要把 `budget` / `targetCpaAmount` / `maxCPCAmount` 这些"分"字段当作主币种传给 CLI。
+
+**提高系列日预算**（在原值基础上 +10 元的写法）：
+
+```bash
+# 1) GET 取主币种当前值
+CUR=$(siluzan-tso ad campaigns -a <mediaCustomerId> --json | node -e '...筛选 budgetDisplay')
+# 2) 主币种 + 10
+NEW=$(node -e "console.log((${CUR} + 10).toFixed(2))")
+# 3) 主币种金额传回
+siluzan-tso ad campaign-edit -a <mediaCustomerId> --id <campaignId> --budget ${NEW}
+```
+
+**上调系列目标 CPA**（若策略为 tCPA 等）：
+
+```bash
+siluzan-tso ad campaign-edit -a <mediaCustomerId> --id <campaignId> --target-cpa <主币种金额>
+```
+
+若策略在**组级**调目标 CPA：
+
+```bash
+siluzan-tso ad adgroup-edit -a <mediaCustomerId> --id <adGroupId> --target-cpa <主币种金额>
+```
+
+写前务必先 **`ad campaigns --json` / `ad groups --json`** 取当前值，**读取 `*Display` 字段**（主币种）后按配置比例计算，再以主币种金额传回。
+
+---
+
+## 写后复核
+
+```bash
+siluzan-tso ad campaigns -a <mediaCustomerId> --start <…> --end <…> --json
+siluzan-tso google-analysis campaigns -a <mediaCustomerId> --start <…> --end <…> --json
+```
+
+确认 **`budget`/`budgetDisplay`**、**`targetCpa_BidingAmount`**（或组上 **`targetCpaAmount`**）与 **`statusV2`** 符合预期。
+
+---
+
+## 通知（宿主）
+
+命中扩量时走 **P1**（或等价）通道；建议含 `mediaCustomerId`、**`campaignId`**（或组 `id`）、新旧预算/目标 CPA 摘要及判据引用（如 `conversionsValuePerCost`、`searchBudgetLostImpressionShare`）。

package/dist/skill/references/hosted-automation-optimize-weak-downbid.md

@@ -0,0 +1,94 @@
+# SOP：表现差广告 — 降价 / 关停（Ad Group / Ad）
+
+> **索引**：[`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md)  
+> **层级**：广告组与创意均可；组级用 **`ad groups`**，创意级用 **`ad list`**（或 **`google-analysis ads`**，同源）。
+
+---
+
+## 业务目标（宿主配置化）
+
+在约定统计窗口内：若素材/组 **引流弱**（如 CTR 显著低于同池基准）或 **转化效率差**（如实际 CPA 显著高于目标且转化次数不足），则 **下调目标 CPA** 或 **暂停**；连续多轮仍无改善时可升级为关停。具体系数、窗口天数、P2 通知文案由宿主配置。
+
+---
+
+## 检查项（宿主每轮）
+
+### 1. 拉数命令
+
+**广告组**（含目标 CPA、花费、转化等）：
+
+```bash
+siluzan-tso ad groups -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+**创意**（含拒审、价值与 all conv 等）：
+
+```bash
+siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+（与上条等价数据源：`siluzan-tso google-analysis ads -a … --start … --end … --json`。）
+
+### 2. 聚合与常用键名
+
+- 响应为 `items[]`（外层结构见 `wrapListJson` 约定，以当次输出为准）。  
+- **须按 `id` 聚合**（见索引「按日多行」）：对 `impressions`、`clicks`、`spend`、`conversions`、**`allConversions`**、**`conversionsValue`** 等同名字段做**求和**；比率在聚合后计算，例如  
+  - **实际 CPA**（主币种）：`spend / conversions`（`conversions == 0` 时不做 CPA 规则判断）。  
+  - **CTR**：聚合后 `clicks / impressions` 或与行上 **`ctr`** 口径对齐前，先确认组列表与创意列表 **`ctr` 是否均为 0–1 或均为百分比**，避免跨命令混比。
+
+创意行上（在已部署网关、且 `skipReport` 为 false 时）常见扩展字段：
+
+- **`allConversions`**
+- **`conversionsValue`**
+- **`conversionsValuePerImpression`**（可能由后端计算属性序列化；若无则宿主用 `conversionsValue / impressions` 自行计算，与索引说明一致。）
+
+组行上常见：
+
+- **`targetCpaAmount`**（及 `maxCPCAmount` / `maxCPCAmountDisplay` 等，写入口径见 `google-ads.md`）
+- **`spend`**、**`conversions`**、**`impressions`**、**`ctr`**
+
+### 3. 条件示例（仅示意，以宿主配置为准）
+
+- **数据置信**：聚合后 **`impressions`**（或 **`clicks`**）高于配置下限再参与判定。  
+- **弱引流**：聚合后 CTR 低于「同池基准 × 配置比例」（基准由宿主对同类型/同系列池计算）。  
+- **弱转化**：**`spend / conversions`**（或 **`costPerConversion`** 与目标同口径比较）高于 **目标 CPA × 配置倍数**，且 **`conversions`** 低于配置上限。
+
+目标 CPA：组级从 **`targetCpaAmount`** 与 `google-ads.md` 货币单位说明读取；创意级通常需用 **`adGroupId`** 关联到对应组行再取目标。
+
+---
+
+## 最终操作
+
+**下调组目标 CPA**（数值单位与 `ad groups --json` 一致，见 `google-ads.md`「广告组编辑」）：
+
+```bash
+siluzan-tso ad adgroup-edit -a <mediaCustomerId> --id <adGroupId> --target-cpa <新值>
+```
+
+**暂停组或创意**：
+
+```bash
+siluzan-tso ad adgroup-status -a <mediaCustomerId> --id <adGroupId> --status Paused
+# 或
+siluzan-tso ad ad-status -a <mediaCustomerId> --id <adId> --status Paused
+```
+
+（`ad-status` 若需 `--start`/`--end` 见 `google-ads.md`。）
+
+---
+
+## 写后复核
+
+```bash
+siluzan-tso ad groups -a <mediaCustomerId> --start <当日或下一窗> --end <…> --json
+# 或
+siluzan-tso ad list -a <mediaCustomerId> --start <…> --end <…> --json
+```
+
+确认 **`statusV2`**、**`targetCpaAmount`**（或创意侧父级状态）与预期一致。
+
+---
+
+## 通知（宿主）
+
+命中降价/关停时走组织规定的 **P2**（或等价）通道；正文建议含 `mediaCustomerId`、对象类型、**`id`**、当次关键指标与阈值摘要。

package/dist/skill/references/hosted-automation-scenarios.md

@@ -0,0 +1,23 @@
+# 宿主编排（Google）：文档索引
+
+> **编排责任**：定时、多条件 IF、滑动时间窗、通知（含 P1 /「空耗熔断」文案）由 **OpenClaw / WorkBuddy / Cron** 等宿主实现。  
+> **CLI 责任**：单次调用下给出检查与写操作所需命令；**不**内置常驻调度或通知渠道。
+
+本主题拆成下面两份子文档，按需打开（本文件只做**入口与导航**）。
+
+| 文档 | 内容 |
+|------|------|
+| [`hosted-automation-self-control.md`](hosted-automation-self-control.md) | **三类投放自控**：单日预算熔断、CPA 飙升降价、连续空耗暂停；通用约定与常用 JSON 字段表；宿主编排实现清单；与 `forewarning` 的关系 |
+| [`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md) | **异常监控巡检**：`balance-scan` / `balance` / `google-analysis overview` / `campaign-hour` / `final-urls`、拒审相关等 **`--json` 键名与命令** |
+| [`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md) | **自动优化（宿主编排）**：差素材降价/关停、高转化扩量、A/B 停输家 — 分文件 SOP（含 `ad list` 按日聚合、`google-analysis campaigns` 等） |
+| [`hosted-automation-user-catalog.md`](hosted-automation-user-catalog.md) | **用户向一览**：预算/ROI 自控、异常监控、自动优化表格（可节选给用户；与上表互补） |
+
+**必读交叉引用**（子文档内会再写一遍）：
+
+- 金额与展示：`SKILL.md`「金额与货币单位硬约束」；`*Display` 与写入口径见 `references/google-ads.md`
+- `--json` 与 Node 过滤：`references/tips.md`
+- 写命令语法：`references/google-ads.md`
+- 账户/维度分析、时间窗：`references/account-analytics.md`
+- 余额类命令详解：`references/accounts.md`
+
+**前置**：已 `siluzan-tso login`，并已用 `list-accounts -m Google -k <mediaCustomerId> --json` 确认账户与 `mediaCustomerId`。

package/dist/skill/references/hosted-automation-self-control.md

@@ -0,0 +1,216 @@
+# 宿主编排：三类 Google 投放自控（详细步骤）
+
+> **主题索引**：[`hosted-automation-scenarios.md`](hosted-automation-scenarios.md)  
+> **编排责任**：定时、多条件 IF、滑动时间窗、通知（含 P1 /「空耗熔断」文案）由 **OpenClaw / WorkBuddy / Cron** 等宿主实现。  
+> **本页责任**：说明如何用 `siluzan-tso` **拉检查项**、**执行最终写操作**、**写后复核**。
+
+**必读交叉引用**：
+
+- 金额与展示：`SKILL.md`「金额与货币单位硬约束」；命令层 `budget` / `maxCPCAmount` 等与 `*Display` 关系见 `references/google-ads.md`、`ad campaigns` / `ad groups` 的 `--json` 说明。
+- `--json` 与 Node 过滤：`references/tips.md`
+- 写命令语法：`references/google-ads.md`（系列编辑、广告组编辑、启停等）
+- 账户/维度分析、时间窗：`references/account-analytics.md`
+- **异常监控**（余额、小时花费、落地页、拒审等 **`--json` 键名**）：[`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md)
+
+**前置**：已 `siluzan-tso login`，并已用 `list-accounts -m Google -k <mediaCustomerId> --json` 确认账户与 `mediaCustomerId`。
+
+---
+
+## 通用约定
+
+### 统计日与「今日」
+
+「今日累计」口径须与宿主配置一致。默认建议 **账户业务日 `Asia/Shanghai`** 的日历日；若宿主使用 UTC 或其他时区，须在配置中固定并在以下命令的 `--start` / `--end` 中显式换算为 **`YYYY-MM-DD`**，**不要**在文档未约定时自行假设。
+
+### 检查项常用 JSON 字段（以当次 `siluzan-tso … --json` 为准）
+
+| 检查意图 | 可关注的 JSON 字段（键名以实际 stdout 为准） |
+|----------|---------------------------------------------|
+| 周期内费用 | 系列/组/创意列表中的 **`spend`**；报表类子命令中带费用的指标字段 |
+| 日预算与费用比 | **`ad campaigns --json`**：`**budget**` / **`budgetDisplay`** 与 **`spend`**；比较时须**统一货币与单位**（见 `SKILL.md` 金额硬规范） |
+| 转化次数 | **`conversions`**（或报表里等价字段名） |
+| 实际 CPA | 宿主侧 **`spend / conversions`**（`conversions` 为 0 时不做 CPA 判断） |
+| 目标 CPA（系列 / 组） | 系列列表 JSON 中的 **`targetCpa_BidingAmount`** 等；组列表 **`ad groups --json`** 中的 **`targetCpaAmount`**（写入口径见 `google-ads.md`「广告组编辑」） |
+
+若某条检查所需字段在**当前** `--json` 中不存在，**禁止猜测**：先换用 `references/account-analytics.md` 中其它子命令拉数，或与维护方确认是否需扩展 `siluzan-tso`；宿主侧不得编造字段。
+
+---
+
+## 场景 1：单日预算熔断（Campaign）
+
+**业务目标**：当周期内费用相对日预算达到设定比例（如 **≥ 110%**，建议 **110%–120%** 缓冲 API 延迟）时，**将系列状态置为 Paused**；恢复由人工加预算后在网页或 CLI 再启用。
+
+### 检查项（宿主每轮执行）
+
+1. 解析 `mediaCustomerId`（见上文前置）。
+2. 拉系列列表（**统计日 = 当日**，起止同为该日或业务日定义）：
+
+```bash
+siluzan-tso ad campaigns -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json
+```
+
+3. 对 `items[]` 中每条系列（`id` 为系列 ID）：
+   - 读取 **`spend`**（或文档约定的费用字段）与 **`budgetDisplay`** / **`budget`**（二选一与 `spend` **统一口径**，见 `SKILL.md` 硬规范）。
+   - 计算阈值：`threshold = budget_in_same_unit * (coefficient / 100)`，系数 `coefficient` 建议 **110–120**（配置项）。
+   - **IF** `spend >= threshold` **且**宿主策略允许对该系列熔断（如排除白名单），则进入写操作。
+
+### 最终操作
+
+```bash
+siluzan-tso ad campaign-status -a <mediaCustomerId> --id <campaignId> --status Paused
+```
+
+### 写后复核
+
+```bash
+siluzan-tso ad campaigns -a <mediaCustomerId> --start <当日> --end <当日> --json
+```
+
+确认该 `id` 的 **`statusV2`**（或等价状态字段）为 **`Paused`**。
+
+### 恢复
+
+```bash
+siluzan-tso ad campaign-status -a <mediaCustomerId> --id <campaignId> --status Enabled
+```
+
+### CLI 能力摘要
+
+| 状态 | 说明 |
+|------|------|
+| 有 | 读：`ad campaigns --json`；写：`ad campaign-status`；复核：再次 `ad campaigns --json`。 |
+
+---
+
+## 场景 2：CPA 飙升自动降价（Campaign / Ad Group）
+
+**业务目标**：在过去 **X 小时**（或等价滑动窗口，由宿主定义）内 **`conversions ≥ 3`** 且 **实际 CPA > 目标 CPA × 飙升阈值**（如 **1.3**）时降价：
+
+- 系列为 **tCPA**：下调 **target_cpa** 约 **10%–15%**（具体比例配置在宿主）。
+- **eCPC**：下调 **cpc_bid_ceiling** 约 **15%**（系列侧多为 `ad campaign-edit --bid-ceiling` 等，见 `google-ads.md`；组侧手动上限可用 **`ad adgroup-edit --max-cpc`**，策略以实际账户为准）。
+
+### 检查项（宿主每轮执行）
+
+1. **时间窗**：由宿主将「过去 X 小时」映射为 **`--start` / `--end`**（或按小时粒度拆多次拉取再聚合，以 `account-analytics.md` 与接口能力为准）。
+2. **拉数**（至少覆盖费用、转化；字段以实际 JSON 为准）：
+   - 系列维度：`ad campaigns … --json`
+   - 组维度：`ad groups … --json`
+   - 若列表不足以算「过去 X 小时」，使用 **`account-analytics`** 或报表子命令中可下到系列/组且带时间粒度的接口（见 `account-analytics.md`）。
+3. 对候选对象：
+   - `conversions`（窗口内）**≥ 3**
+   - `actual_cpa = spend / conversions`（`conversions > 0`）
+   - 读取 **目标 CPA**（系列：`targetCpa_BidingAmount` 或 JSON 中实际键；组：`targetCpaAmount`）；与 **`actual_cpa`** 同单位后再比。
+   - **IF** `actual_cpa > target_cpa * spike_threshold`（如 `1.3`），则进入写操作。
+
+### 最终操作
+
+**系列（tCPA / 出价上限等）**：
+
+```bash
+# 所有金额参数均为「主币种金额」（如 50 表示 ¥50）；CLI 内部自动 ×100 写入「分」字段
+siluzan-tso ad campaign-edit -a <mediaCustomerId> --id <campaignId> --target-cpa <新值（主币种）>
+# 或 eCPC / 最大化点击上限等：
+# siluzan-tso ad campaign-edit ... --bid-ceiling <主币种金额> --bidding TARGET_SPEND
+```
+
+参数与单位见 **`references/google-ads.md`**「ad campaign-edit」金额单位说明。
+
+**广告组**：
+
+```bash
+siluzan-tso ad adgroup-edit -a <mediaCustomerId> --id <adGroupId> --target-cpa <主币种金额>
+# 或
+siluzan-tso ad adgroup-edit -a <mediaCustomerId> --id <adGroupId> --max-cpc <主币种金额>
+```
+
+见 **`references/google-ads.md`**「广告组编辑」。
+
+写前**必须**先 **`ad groups --json` / `ad campaigns --json`** 取当前值，**读取 `*Display` 字段**（主币种金额，如 `targetCpaAmountDisplay`、`maxCPCAmountDisplay`、`budgetDisplay`），在宿主内按主币种算新值（如下调 12%：`newDisplay = round((oldDisplay * 0.88) * 100) / 100`），再以主币种金额作为 `--target-cpa` / `--max-cpc` / `--budget` 传回。
+**严禁** 把 `targetCpaAmount` / `maxCPCAmount` / `budget` 这些「分」字段直接当作主币种金额传给 CLI——会被再 ×100 一次，金额放大 100 倍。
+
+### 写后复核
+
+再次 **`ad campaigns --json`** 或 **`ad groups --json`**：
+- 优先比对 **`*Display` 字段**（主币种）与预期主币种金额一致；
+- 整数字段 `targetCpa_BidingAmount` / `targetCpaAmount` / `maxCPCAmount` / `budget` 应等于 `主币种 × 100` 后的整数。
+
+### CLI 能力摘要
+
+| 状态 | 说明 |
+|------|------|
+| 已完成 | 系列：`campaign-edit`；组：`adgroup-edit`；检查项依赖宿主时间窗 + 多字段；若某策略字段未在 JSON 出现，须按上文「缺字段勿猜」处理。 |
+
+---
+
+## 场景 3：连续空耗自动暂停（Ad Group / Ad）
+
+**业务目标**：**今日**（或约定日）累计 **`cost`（费用）≥ 目标 CPA × N`** 且 **`conversions = 0`** 时，**暂停**广告组或广告；**P1 告警 + 文案「空耗熔断」** 由宿主通知 skill 发送（本 CLI 不发送 P1）。
+
+### 检查项（宿主每轮执行）
+
+1. 确定「今日」`--start` / `--end`（同场景 1 时区约定）。
+2. **广告组**：
+
+```bash
+siluzan-tso ad groups -a <mediaCustomerId> --start <当日> --end <当日> --json
+```
+
+对 `items[]`：读取 **`spend`**（费用）、**`conversions`**；目标 CPA 来自 **`targetCpaAmount`** 与 **`toDisplayMoney` 逆运算** 或宿主配置的「目标 CPA（主币种）」；计算 `limit = target_cpa_main_currency * N`（**N** 为配置）。
+
+   - **IF** `conversions === 0` **且** `spend >= limit`（注意 **`spend` 与 limit 单位一致**），则对该 `id` 执行组暂停。
+
+3. **广告（创意）**级：若策略在创意维熔断：
+
+```bash
+siluzan-tso ad list -a <mediaCustomerId> --start <当日> --end <当日> --json
+```
+
+同样判断费用与转化；命中则 **`ad ad-status`**。
+
+### 最终操作
+
+```bash
+siluzan-tso ad adgroup-status -a <mediaCustomerId> --id <adGroupId> --status Paused
+# 或
+siluzan-tso ad ad-status -a <mediaCustomerId> --id <adId> --status Paused
+```
+
+（`ad-status` 若需 `--start`/`--end` 见 `google-ads.md`。）
+
+### 通知（宿主）
+
+调用组织规定的 **P1** 通道（钉钉/飞书/Slack 等），标题或正文须含 **「空耗熔断」** 及 `mediaCustomerId`、对象类型、对象 `id`、当次 `spend` / 阈值。
+
+### 写后复核
+
+```bash
+siluzan-tso ad groups -a <mediaCustomerId> --start <当日> --end <当日> --json
+# 或 ad list …
+```
+
+确认对应 **`statusV2`** 为 **`Paused`**。
+
+### CLI 能力摘要
+
+| 状态 | 说明 |
+|------|------|
+| 有 | 读：`ad groups` / `ad list`；写：`adgroup-status` / `ad-status`；通知：宿主；复核：再次 list。 |
+
+---
+
+## 宿主编排实现清单（摘要）
+
+| 步骤 | 说明 |
+|------|------|
+| 1 | 配置：账户列表、系数、N、X 小时、白名单、是否自动写、通知 |
+| 2 | 每轮：`list-accounts` 或固定 `mediaCustomerId` → 拉 `--json` |
+| 3 | 宿主内算 IF（本页公式） |
+| 4 | 命中则调用写命令（可批量，注意 API 限速） |
+| 5 | 每写一条即复核读；失败重试与告警由宿主处理 |
+| 6 | 审计日志建议写在宿主侧（CLI 不内置） |
+
+---
+
+## 与 `forewarning` 的关系
+
+`siluzan-tso forewarning` 为丝路赞侧 **单条件、固定阈值、微信通知**，**不能**单独表达「预算 × 系数」「多条件 AND」等。上述三场景以 **宿主拉数 + 写命令** 为主路径；`forewarning` 仅作可选补充通知。

package/dist/skill/references/hosted-automation-user-catalog.md

@@ -0,0 +1,40 @@
+# 自动化场景
+
+这是skill的一些结合Agent客户端可完成的自动化功能，你可以给用户介绍下面的这些内容
+
+## 预算 & ROI 控制引擎
+
+三条均为 **Google 宿主编排 + siluzan-tso** 路径；IF/定时/通知在宿主，命令与 JSON 以详规为准。
+
+| 提醒名称            | 系统在后台默默帮你做什么？(自动动作) | 文档（references） |
+| ------------------- | ------------------------------------- | ------------------ |
+| 1. 单日预算熔断     | 当日系列 **花费**相对**日预算**达到设定比例（如 ≥110%，可配 110%–120% 抗延迟）时，**暂停 Campaign**；恢复需人工加预算后再启用。 | [场景 1 · 单日预算熔断](hosted-automation-self-control.md) · [`google-ads.md`](google-ads.md)（`ad campaigns`、`ad campaign-status`、预算口径） · [`tips.md`](tips.md)（`--json`） |
+| 2. CPA 飙升自动降价 | 滑动时间窗内 **转化数**达置信阈值且 **实际 CPA** 高于 **目标 CPA×飙升比例** 时，在 **Campaign / Ad Group** 上**下调** tCPA 或 eCPC 等**出价上限**（具体策略依账户）。 | [场景 2 · CPA 飙升自动降价](hosted-automation-self-control.md) · [`hosted-automation-optimize-weak-downbid.md`](hosted-automation-optimize-weak-downbid.md)（组/创意侧降价关停，可与宿主组合） · [`google-ads.md`](google-ads.md)（`campaign-edit`、`adgroup-edit`） · [`account-analytics.md`](account-analytics.md)（窗口粒度不足时的报表拉数） |
+| 3. 连续空耗自动暂停 | **当日**累计 **花费 ≥ 目标 CPA×N** 且 **转化为 0** 时，**暂停**广告组或创意；宿主发 **P1** 且文案含 **「空耗熔断」**。 | [场景 3 · 连续空耗自动暂停](hosted-automation-self-control.md) · [`google-ads.md`](google-ads.md)（`ad groups`、`ad list`、`adgroup-status`、`ad-status`） · [`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md)（JSON 键名勿套用 Google Ads API 官方名） |
+
+**总索引**：[`hosted-automation-scenarios.md`](hosted-automation-scenarios.md) · **自控全文**：[`hosted-automation-self-control.md`](hosted-automation-self-control.md) · **金额硬规范**（展示用 `*Display` 等）：[`SKILL.md`](../SKILL.md)「金额与货币单位硬约束」。
+
+## 异常监控与报警系统
+
+编排（定时、HTTP 探活、通知）在宿主；**读哪些 JSON 字段、用什么命令** 以 **[`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md)** 为准（键名以当次 `--json` 为准，勿套用 Google Ads API 官方字段名解析本 CLI 输出）。
+
+| 功能名称          | 监控层级 / 说明 | CLI 检查入口（`--json`） |
+| ----------------- | --------------- | ------------------------ |
+| 1. 账户被封禁     | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 [`accounts.md`](accounts.md) |
+| 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis final-urls`**；或 **`ad list`** / **`google-analysis ads`** 取落地页字段后由宿主 HTTP 校验 |
+| 3. 广告素材拒审   | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **[`google-ads.md`](google-ads.md)**） |
+| 4. 花费异动监控   | 系列或账户维度花费相对历史异常波动。 | **`google-analysis campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
+| 5. 余额枯竭预警   | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
+
+## 自动优化
+
+编排与阈值在宿主；**命令、JSON 键名、聚合与写后复核** 见 **[`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md)**（及链出的三份 SOP）。
+
+| 功能名称                | 说明 | SOP |
+| ----------------------- | ---- | ----- |
+| 1. 表现差广告降价/关停  | 组/创意：CTR、CPA、转化等触达后 **下调 `targetCpa` 或 `Paused`**。 | [`hosted-automation-optimize-weak-downbid.md`](hosted-automation-optimize-weak-downbid.md) |
+| 2. 高转化广告提价扩量   | 系列/组：ROAS 代理、预算丢失份额等触达后 **提预算 / 上调目标 CPA**。 | [`hosted-automation-optimize-scale.md`](hosted-automation-optimize-scale.md) |
+| 3. A/B 测试自动决出胜者 | 同组多创意：聚合后比 **CVPI / all conv** 等，**停输家**。 | [`hosted-automation-optimize-ab-winner.md`](hosted-automation-optimize-ab-winner.md) |
+| 4. 异动根因自动排查建议 | 诊断报告与归因：用 `account-analytics`、报告模板等，见 [`account-analytics.md`](account-analytics.md) 与 `report-templates/`。 | （未单独拆 SOP，沿用分析文档） |
+
+

package/dist/skill/references/open-account-google-ui.md

@@ -1,9 +1,3 @@
-# Google 开户：网页交互与 CLI 对照（/openAnAccount）
-
-> 路由：`{webUrl}/v3/foreign_trade/tso/openAnAccount?mediaType=Google&...`  
-> 前端组件：`openAnAccount.vue` + 顶部流程条 `GGOPASteps.vue`
-
----
 
 ## 一、页面顶部「五步」是什么？
 

package/dist/skill/references/reporting.md

@@ -27,6 +27,8 @@ siluzan-tso report list -m <媒体> [选项]
 | `--start / --end <date>` | 日期范围（YYYY-MM-DD）               |
 | `--json`                 | 输出原始 JSON                        |
 
+**仅 JSON 交付**：若用户明确要求「只输出一个 JSON / 不要解释」，回复中**只放一个** JSON 代码块（与本次 CLI stdout 一致），前后不加说明文字；分页结果以 JSON 内 `page` / `pageSize` / `total` / `itemCount` 为准，需全量时再翻页执行。
+
 **示例：**
 
 ```bash
@@ -212,8 +214,8 @@ siluzan-tso report list -m Google --json
 
 # 第二步：查看 webUrl
 siluzan-tso config show
-# webUrl: https://www.siluzan.com
+# webUrl: https://www-ci.siluzan.com
 
 # 第三步：拼接链接（Google 日报）
-# https://www.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
+# https://www-ci.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
 ```

package/dist/skill/references/setup.md

@@ -10,7 +10,7 @@
 ## 安装 CLI
 
 ```bash
-npm install -g siluzan-tso-cli
+npm install -g siluzan-tso-cli@beta
 ```
 
 ---
@@ -47,7 +47,7 @@ siluzan-tso config set --api-key <Key>     # 或通过 config set 直接写入
 siluzan-tso config set --token <Token>     # 备用：设置 JWT Token
 ```
 
-API Key 获取入口：`https://www.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
+API Key 获取入口：`https://www-ci.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
 
 ### 通过环境变量传入凭据（CI/CD 推荐）
 
@@ -82,9 +82,9 @@ siluzan-tso config show
 
 ```
   构建环境     : production
-  apiBaseUrl   : https://tso-api.siluzan.com
-  googleApiUrl : https://googleapi.mysiluzan.com
-  webUrl       : https://www.siluzan.com
+  apiBaseUrl   : https://tso-api-ci.siluzan.com
+  googleApiUrl : https://googleapi-ci.mysiluzan.com
+  webUrl       : https://www-ci.siluzan.com
   apiKey       : abcd****1234
 ```
 

package/dist/skill/references/tips.md

@@ -5,6 +5,12 @@
 
 ---
 
+## 已有 JSON 时（不必先重跑 CLI）
+
+用户已保存输出或只问「怎么从一大坨 JSON 里筛字段」时：直接用 **stdin / 本地文件** 喂给 `node -e` 即可，不必为示例再执行 `list-accounts` 等业务命令（字段路径以实际响应为准，常见为 `data.items` 或顶层数组）。
+
+---
+
 ## 基础模式：`--json` + `node -e` 管道
 
 ### 过滤特定字段

package/dist/skill/references/tso-home.md

@@ -6,7 +6,7 @@
 
 用 `siluzan-tso config show` 读取 **`webUrl`**，再拼接路径：
 
-首页地址：`https://www.siluzan.com/v3/foreign_trade/tso/home`
+首页地址：`https://www-ci.siluzan.com/v3/foreign_trade/tso/home`
 
 > 若用户已登录 TSO，也可从左侧菜单进入「首页」。
 

package/dist/skill/references/workflows.md

@@ -5,6 +5,19 @@
 
 ---
 
+## 宿主编排下的投放自控（检查项 → 写操作 → 复核）
+
+宿主编排相关文档（**入口** + 两份子页）：
+
+- **`references/hosted-automation-scenarios.md`** — 索引与导航  
+- **`references/hosted-automation-self-control.md`** — 三类场景（**单日预算熔断**、**CPA 飙升降价**、**连续空耗暂停**）的逐步命令、字段对照、系数与复核  
+- **`references/hosted-automation-monitoring-json.md`** — 异常监控（余额/`campaign-hour`/落地页/拒审等 **`--json` 键名与命令**）
+- **`references/hosted-automation-optimize-index.md`** — 自动优化（差素材降价/关停、高转化扩量、A/B 决胜负）**分文件 SOP**
+
+本文件其余章节仍为其他业务流程；实现上述自控、监控或自动优化时按需打开子页，并配合 `references/tips.md`（`--json`）、`references/google-ads.md`（写命令与拒审字段）、`references/account-analytics.md`（时间窗与报表）、`references/accounts.md`（`balance` / `balance-scan`）。
+
+---
+
 ## 流程一：新账户开通（Google / TikTok / Yandex / Bing / Kwai）
 
 对应页面：`/accountOpeningHistory`
@@ -911,7 +924,7 @@ siluzan-tso 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` 等走 Google 网关，金额单位以 `references/google-ads.md` 对应章节为准
+- `ad campaign-create` / `ad smart create`（批量创建 API）的预算与 CPC 为**主币种展示金额**，与 Web 一致内部 `×100`；分步命令里 `ad adgroup-create`、`ad keyword-edit` 等金额单位以 `references/google-ads.md` 对应章节为准
 
 ---
 

package/dist/skill/report-templates/google-account-diagnosis-report.md

@@ -73,4 +73,4 @@
 
 ### 并行拉取提示
 
-诊断场景可在同一统计区间内并行执行多条 `google-analysis`（注意网关限流）；合并后再套入本模板各章节。
+诊断场景可在同一统计区间内并行执行多条 `google-analysis`（注意接口限流）；合并后再套入本模板各章节。

package/dist/skill/report-templates/google-period-report.md

@@ -28,6 +28,7 @@
 
 | 维度          | CLI                                  | 备注                                 |
 | ------------- | ------------------------------------ | ------------------------------------ |
+| 系列按小时    | `google-analysis campaign-hour`      | `campaign-hour`；根为 JSON 数组，含 `date`/`hour`/消耗与效果 |
 | 受众分布      | `google-analysis audience`           | 可分 `SystemDefined` / `UserDefined` |
 | 搜索词报告    | `google-analysis search-terms`       | 高消耗搜索词与关键词匹配关系         |
 | 广告创意表现  | `google-analysis ads`                | 广告标题/类型/到达网址               |

package/dist/skill/scripts/install.ps1

@@ -10,8 +10,8 @@ $ErrorActionPreference = 'Stop'
 $PKG_NAME    = 'siluzan-tso-cli'
 $CLI_BIN     = 'siluzan-tso'
 $SKILL_LABEL = 'Siluzan TSO'
-$INSTALL_CMD = 'npm install -g siluzan-tso-cli'
-$WEB_BASE    = 'https://www.siluzan.com'
+$INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'
+$WEB_BASE    = 'https://www-ci.siluzan.com'
 
 # -- Constants ----------------------------------------------------------------
 $NODE_MAJOR_MIN = 18

package/dist/skill/scripts/install.sh

@@ -10,8 +10,8 @@ set -euo pipefail
 readonly PKG_NAME="siluzan-tso-cli"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
-readonly INSTALL_CMD="npm install -g siluzan-tso-cli"
-readonly WEB_BASE="https://www.siluzan.com"
+readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"
+readonly WEB_BASE="https://www-ci.siluzan.com"
 
 # -- Constants ----------------------------------------------------------------
 readonly NODE_MAJOR_MIN=18