siluzan-tso-cli 1.1.14-beta.2 → 1.1.14-beta.4

package/README.md

@@ -19,8 +19,6 @@
 | 项目            | 说明                                                            |
 | --------------- | --------------------------------------------------------------- |
 | API Key / Token | 存储在 `~/.siluzan/config.json`，用于所有 API 调用鉴权          |
-| TSO API         | `tso-api.siluzan.com`（生产）/ `tso-api-ci.siluzan.com`（测试） |
-| Google API 网关 | `googleapi.mysiluzan.com` / `googleapi-ci.mysiluzan.com`        |
 | 前端页面        | `www.siluzan.com`（充值、激活等浏览器操作）                     |
 | 错误追踪        | `o605862.ingest.us.sentry.io`（匿名崩溃日志）                   |
 | 版本检查        | `registry.npmjs.org`                                            |
@@ -53,7 +51,7 @@ siluzan-tso init -d /path/to/skills  # 写入自定义目录
 siluzan-tso init --force             # 强制覆盖已存在文件
 ```
 
-> **注意**：当前为测试版（1.1.14-beta.2），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+> **注意**：当前为测试版（1.1.14-beta.4），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/assets/siluzan-ads/references/hosted-automation-user-catalog.md

@@ -0,0 +1,38 @@
+# 自动化场景用户向目录
+
+这是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/index.js

@@ -5184,6 +5184,12 @@ var SECTIONS = [
     dateMode: "range",
     path: (id) => `/reporting/media-account/${id}/CampaignSectionData`
   },
+  {
+    name: "campaign-hour",
+    description: "\u7CFB\u5217\u6309\u5C0F\u65F6 campaign-hour\uFF08Query\uFF1AstartDate\u3001endDate\uFF09",
+    dateMode: "range",
+    path: (id) => `/reporting/media-account/${id}/campaign-hour`
+  },
   {
     name: "ads",
     description: "\u5E7F\u544A\u7EA7\u5217\u8868 admanagement/v2/list",
@@ -5319,6 +5325,55 @@ async function fetchJson(config, pathWithQuery, verbose) {
   const url = `${config.googleApiUrl}${pathWithQuery}`;
   return apiFetch2(url, config, {}, verbose);
 }
+function assertNever(x, ctx) {
+  throw new Error(`${ctx}\uFF1A\u672A\u5904\u7406\u7684\u5206\u652F ${String(x)}`);
+}
+async function fetchGoogleAnalysisSectionJson(config, fullPath, verbose, name) {
+  switch (name) {
+    case "overview":
+      return fetchJson(config, fullPath, verbose);
+    case "keywords":
+      return fetchJson(config, fullPath, verbose);
+    case "search-terms":
+      return fetchJson(config, fullPath, verbose);
+    case "campaigns":
+      return fetchJson(config, fullPath, verbose);
+    case "campaign-hour":
+      return fetchJson(config, fullPath, verbose);
+    case "ads":
+      return fetchJson(config, fullPath, verbose);
+    case "extensions":
+      return fetchJson(config, fullPath, verbose);
+    case "devices":
+      return fetchJson(config, fullPath, verbose);
+    case "geographic":
+      return fetchJson(config, fullPath, verbose);
+    case "audience":
+      return fetchJson(config, fullPath, verbose);
+    case "asset-images":
+      return fetchJson(config, fullPath, verbose);
+    case "videos":
+      return fetchJson(config, fullPath, verbose);
+    case "resource-counts":
+      return fetchJson(config, fullPath, verbose);
+    case "conversion-actions":
+      return fetchJson(config, fullPath, verbose);
+    case "daily-metrics":
+      return fetchJson(config, fullPath, verbose);
+    case "gold-account":
+      return fetchJson(config, fullPath, verbose);
+    case "ads-index":
+      return fetchJson(config, fullPath, verbose);
+    case "final-urls":
+      return fetchJson(config, fullPath, verbose);
+    case "dimension-summary":
+      return fetchJson(config, fullPath, verbose);
+    case "campaign-types":
+      return fetchJson(config, fullPath, verbose);
+    default:
+      return assertNever(name, "google-analysis");
+  }
+}
 function summarizeHuman(section, data) {
   if (data === null || data === void 0) return "\u65E0\u6570\u636E";
   if (Array.isArray(data)) return `\u6570\u7EC4\uFF0C\u5171 ${data.length} \u6761`;
@@ -5389,7 +5444,12 @@ async function runOneSection(def, opts) {
       );
       return;
     }
-    const data = await fetchJson(config, fullPath, !!opts.verbose);
+    const data = await fetchGoogleAnalysisSectionJson(
+      config,
+      fullPath,
+      !!opts.verbose,
+      def.name
+    );
     if (opts.json) {
       console.log(JSON.stringify(stripLegacyGoogleFieldsIfV2Present(data), null, 2));
       return;
@@ -8044,6 +8104,53 @@ async function runAdGroupRename(opts) {
 \u2705 \u5E7F\u544A\u7EC4 ${opts.id} \u5DF2\u6539\u540D\u4E3A\u300C${opts.name}\u300D
 `);
 }
+async function runAdGroupEdit(opts) {
+  const hasName = opts.name !== void 0 && opts.name.trim() !== "";
+  const hasMax = opts.maxCPCAmount !== void 0;
+  const hasTcpa = opts.targetCpaAmount !== void 0;
+  if (!hasName && !hasMax && !hasTcpa) {
+    console.error(
+      "\n\u274C \u8BF7\u81F3\u5C11\u6307\u5B9A\u4E00\u9879\u4FEE\u6539\uFF1A--name / --max-cpc / --target-cpa\n"
+    );
+    process.exit(1);
+  }
+  if (hasMax && (!Number.isFinite(opts.maxCPCAmount) || opts.maxCPCAmount < 0)) {
+    console.error("\n\u274C --max-cpc \u987B\u4E3A\u975E\u8D1F\u6570\u5B57\n");
+    process.exit(1);
+  }
+  if (hasTcpa && (!Number.isFinite(opts.targetCpaAmount) || opts.targetCpaAmount < 0)) {
+    console.error("\n\u274C --target-cpa \u987B\u4E3A\u975E\u8D1F\u6570\u5B57\n");
+    process.exit(1);
+  }
+  const config = loadConfig(opts.token);
+  const googleApiUrl = requireGoogleApi(config);
+  const listUrl = adgroupListUrl(googleApiUrl, opts.account, opts.startDate, opts.endDate);
+  let adgroup;
+  try {
+    adgroup = await findItemInList(listUrl, config, opts.id, opts.verbose);
+  } catch (err) {
+    console.error(`
+\u274C \u67E5\u8BE2\u5E7F\u544A\u7EC4\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  const body = { ...adgroup };
+  if (hasName) body["name"] = opts.name.trim();
+  if (hasMax) body["maxCPCAmount"] = Math.round(opts.maxCPCAmount);
+  if (hasTcpa) body["targetCpaAmount"] = Math.round(opts.targetCpaAmount);
+  const putUrl = `${googleApiUrl}/adgroupnmanagement/adgroup/${opts.account}/${opts.id}`;
+  try {
+    await apiFetch2(putUrl, config, { method: "PUT", body: JSON.stringify(body) }, opts.verbose);
+  } catch (err) {
+    console.error(`
+\u274C \u7F16\u8F91\u5E7F\u544A\u7EC4\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  console.log(`
+\u2705 \u5E7F\u544A\u7EC4 ${opts.id} \u5DF2\u66F4\u65B0
+`);
+}
 async function runAdEdit(opts) {
   const config = await ensureDataPermission(loadConfig(opts.token));
   const googleApiUrl = requireGoogleApi(config);
@@ -13310,6 +13417,29 @@ adCmd.command("adgroup-rename").description("\u4FEE\u6539\u5E7F\u544A\u7EC4\u540
     });
   }
 );
+adCmd.command("adgroup-edit").description("\u7F16\u8F91\u5E7F\u544A\u7EC4\uFF08\u540D\u79F0\u3001\u6700\u9AD8 CPC\u3001\u7EC4\u7EA7\u76EE\u6807 CPA\uFF1B\u81F3\u5C11\u4F20\u4E00\u9879\uFF1B\u4E0E\u7F51\u5173 PUT \u4E00\u81F4\uFF09").requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--id <adgroupId>", "\u5E7F\u544A\u7EC4 ID").option("--name <name>", "\u65B0\u540D\u79F0").option(
+  "--max-cpc <n>",
+  "\u6700\u9AD8 CPC\uFF0C\u4E0E ad groups --json \u7684 maxCPCAmount \u540C\u53E3\u5F84\uFF08\u4E3B\u5E01\u79CD\u91D1\u989D\xD7100\uFF0C\u89C1 references/google-ads.md\uFF09",
+  parseFloat
+).option(
+  "--target-cpa <n>",
+  "\u7EC4\u7EA7\u76EE\u6807 CPA\uFF0C\u4E0E ad groups --json \u7684 targetCpaAmount \u540C\u53E3\u5F84\uFF08\xD7100 \u5206\u5355\u4F4D\uFF09",
+  parseFloat
+).option("--start <date>", "\u5217\u8868\u67E5\u8BE2\u8D77\u59CB\u65E5\u671F YYYY-MM-DD").option("--end <date>", "\u5217\u8868\u67E5\u8BE2\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option("-t, --token <token>", "Auth Token").option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
+  async (opts) => {
+    await runAdGroupEdit({
+      token: opts.token,
+      account: opts.account,
+      id: opts.id,
+      name: opts.name,
+      maxCPCAmount: opts.maxCpc,
+      targetCpaAmount: opts.targetCpa,
+      startDate: opts.start,
+      endDate: opts.end,
+      verbose: opts.verbose
+    });
+  }
+);
 adCmd.command("ad-edit").description(
   "\u7F16\u8F91\u81EA\u9002\u5E94\u641C\u7D22\u5E7F\u544A\uFF08RESPONSIVE_SEARCH_AD\uFF09\uFF1A\u6807\u9898/\u63CF\u8FF0/\u843D\u5730\u9875/\u8DEF\u5F84/\u72B6\u6001\uFF1B\u4E0E\u7F51\u9875 PUT admanagement/campaign \u884C\u4E3A\u4E00\u81F4"
 ).requiredOption("-a, --account <id>", "Google \u8D26\u6237 mediaCustomerId").requiredOption("--id <adId>", "\u5E7F\u544A ID").option(

package/dist/skill/SKILL.md

@@ -50,11 +50,13 @@ allowed-tools: Bash(siluzan-tso:*) Read
 | 文档 | 功能 |
 |------|------|
 | `references/setup.md` | 安装、登录、配置、环境切换、更新 |
-| `references/workflows.md` | 多步骤业务流程与跨命令串联场景 |
+| `references/workflows.md` | 多步骤业务流程、跨命令串联；入口指向宿主编排自控详页 |
+| `references/hosted-automation-scenarios.md` | **宿主编排（Google）索引**；自控见 `references/hosted-automation-self-control.md`；监控见 `references/hosted-automation-monitoring-json.md`；**自动优化 SOP** 见 `references/hosted-automation-optimize-index.md` |
+| `references/hosted-automation-user-catalog.md` | **用户向**：预算/ROI 自控、异常监控、自动优化一览表（可节选给用户；详规见索引与各子文档） |
 | `references/tips.md` | `--json`、Node 过滤、分页与调试技巧 |
 | `references/accounts.md` | 账户列表、余额、消耗、开户记录、授权/解绑/分享/MCC/BC/BM/邮箱授权 |
 | `references/open-account-by-media.md` | 各媒体开户、参数与资料要求 |
-| `references/google-ads.md` | Google Ads 创建、修改、优化与管理主流程 |
+| `references/google-ads.md` | Google Ads 创建、修改、优化与管理主流程；**含 `ad list` / `google-analysis ads` 的 `--json` 拒审字段**（`policyApprovalStatusV2`、`approvalStatusDetails` 等，见该文档「拒审与政策字段」） |
 | `references/reporting.md` | Siluzan TSO 优化报告（Google/TikTok）的生成、推送与查看 |
 | `references/account-analytics.md` | 广告平台账户分析数据拉取与分析/诊断报告模板 |
 | `references/optimize.md` | AI 优化建议记录、详情与历史查询 |
@@ -65,6 +67,27 @@ allowed-tools: Bash(siluzan-tso:*) Read
 
 ---
 
+## 职责划分
+
+**定位**：`siluzan-tso` + 本 Skill 提供 **可组合的读能力（检查项）** 与 **可验证的写能力（最终操作）**；**不负责**在进程内长期驻留、定时轮询、复合条件规则引擎、或替代宿主的通知渠道。
+
+| 由 **本 Skill + CLI** 保证 | 由 **宿主客户端 / 外部调度** 负责 |
+|---------------------------|-----------------------------------|
+| 单次/按需调用下，命令能拉取验证所需的 **JSON 字段**（`--json`、分页见 `references/tips.md`） | **何时**跑一轮检查（cron、事件、对话触发） |
+| 写操作命令语义清晰，且文档给出 **写后如何用读命令复核**（成对验证） | **IF 条件**（多指标 AND/OR、滑动时间窗、相对预算比例等）的计算与决策 |
+| 金额与 ID 口径与文档一致（`*Display`、`entityId` vs `mediaCustomerId` 等硬规范） | 命中后的 **触达**（钉钉/飞书/Slack 等）与内部 **P1/工单** 流程 |
+| `references/google-ads.md` 等与命令、字段含义对齐 | 多账户、多系列的 **批处理循环**、限速、失败重试策略 |
+
+**宿主集成时的推荐约定**：
+
+1. **监控与编排**：配置定时或事件；每轮用本 Skill 指明的命令拉数，在宿主侧用脚本 / `node -e` 做条件判断。
+2. **执行写操作**：仍遵守本 Skill **计划 →（按策略）确认 → 执行 → 验证**；若宿主策略为「全自动写」，须由**用户或配置**显式授权，避免与默认安全规范冲突。
+3. **验证**：每次写入后，用文档中的 **读命令对同一 `id` 再拉一次**（例如 `ad campaign-status` 后 `ad campaigns --json` 看 `statusV2`；`adgroup-edit` 后 `ad groups --json` 看 `maxCPCAmount` / `targetCpaAmount`）。
+4. **`forewarning`**：仍是丝路赞侧 **微信通知** 的可选通道；宿主已有独立通知 skill 时，**不必**重复依赖 `forewarning` 完成「告警」——二者可并行或只选其一。
+
+更具体的 **检查项 ↔ 命令** 见 **`references/hosted-automation-self-control.md`**（三类自控）；异常监控 **`--json` 键名** 见 **`references/hosted-automation-monitoring-json.md`**；**自动优化（降价/扩量/A/B）** 见 **`references/hosted-automation-optimize-index.md`**（分文件 SOP）；主题入口 **`references/hosted-automation-scenarios.md`**。总览见 **`references/workflows.md`**「宿主编排下的投放自控」。
+
+
 ## Skill要如何使用
 
 ### 报告的生成
@@ -89,7 +112,7 @@ allowed-tools: Bash(siluzan-tso:*) Read
 - Google广告优化记录功能(`references/optimize.md`)，这个也跟优化报告类似，你调用接口，Siluzan平台按照一定的优化逻辑自动执行，你只能查询到结果，不能控制优化流程 注意不要与`google-ads.md`中的优化流程混淆两个是互相独立的功能，`references/google-ads.md`中的优化功能更为强大，在实际的优化过程中，也推荐使用`references/google-ads.md`中提供的内容
 - TikTok / Meta 线索表单请阅读：`references/clue.md`
 - Siluzan平台提供的预警功能请阅读：`references/forewarning.md`
-  - 预警由Siluzan平台发送，当前仅支持微信推送，如果需要自定义的通知触达端，需要安装对应插件或skill+创建定时任务来完成
+  - 预警由 Siluzan 平台发送，当前仅支持微信推送。若监控与通知由 **OpenClaw / WorkBuddy 等宿主**承担，可将 `forewarning` 仅作补充或不用；自定义触达仍可用宿主插件 / skill + 定时任务（见上文职责划分）。
 - 转账、开票、发票抬头、充值网页引导请阅读：`references/finance.md`
 -
 
@@ -350,33 +373,22 @@ HTML 报告模板（`report-templates/*.html`）引用了以下外部 CDN 资源
 
 ---
 
-## 下面是一部分比较实用的自动化场景，当你回答完用户问题后，可以把下面的内容输出给用户，方便用户使用
-
-您可以选择以下的预警或提醒，输入需想要执行的内容核实规则即可配置。
-
-### 预算 & ROI 控制引擎
+## 风险预警，预算&ROI 控制引擎，异常监控与报警系统，自动优化
 
-| 提醒名称            | 系统在后台默默帮你做什么？(自动动作)                      |
-| ------------------- | --------------------------------------------------------- |
-| 1. 单日预算熔断     | 每日消耗达到设定值，自动暂停计划，杜绝 Google 超额扣费。  |
-| 2. CPA 飙升自动降价 | 光点不转化（如花费超过3倍目标成本），自动关停该条烂广告。 |
-| 3. 连续空耗自动暂停 | 大盘流量变贵、获客成本飙高时，系统自动下调出价避险。      |
+当加载这个skill时，必须主动跟用户介绍你还可以通过这个skill完成以下功能
 
-### 异常监控与报警系统
+1. 单日预算熔断	每日消耗达到设定值，自动暂停计划，杜绝 Google 超额扣费。
+2. CPA 飙升自动降价	光点不转化（如花费超过3倍目标成本），自动关停该条烂广告。
+3. 连续空耗自动暂停	大盘流量变贵、获客成本飙高时，系统自动下调出价避险。
 
-| 功能名称          | 监控层级 / 说明                                             |
-| ----------------- | ----------------------------------------------------------- |
-| 1. 账户被封禁     |                                                             |
-| 2. 落地页死链强停 | 网站宕机或链接填错，紧急自动暂停关联广告，防止把钱扔水里。  |
-| 3. 广告素材拒审   | 发现被 Google 封号或快没钱了，立刻发送企微/钉钉高优强提醒。 |
-| 4. 花费异动监控   | 花费突然暴涨或断崖式下跌，系统即时报警提示人工盯盘。        |
-| 5. 余额枯竭预警   | 广告被 Google 拦截，系统自动帮你打包违规原因并定时推送。    |
+1. 账户被封禁	
+2. 落地页死链强停	网站宕机或链接填错，紧急自动暂停关联广告，防止把钱扔水里。
+3. 广告素材拒审	发现被 Google 封号或快没钱了，立刻发送企微/钉钉高优强提醒。
+4. 花费异动监控	花费突然暴涨或断崖式下跌，系统即时报警提示人工盯盘。
+5. 余额枯竭预警	广告被 Google 拦截，系统自动帮你打包违规原因并定时推送。
 
-### 自动优化
+1. 表现差广告降价/关停	发现转化极好的“好苗子”，以安全幅度自动涨预算/提价去抢量。
+2. 高转化广告 提价扩量"	连续几天表现垫底的垃圾素材，系统扮演无情杀手自动关停。
+3. A/B测试 自动决出胜者"	科学赛马，根据真实转化价值自动关停输家，把流量全给赢家。
 
-| 功能名称                | 监控层级                                                                   |
-| ----------------------- | -------------------------------------------------------------------------- |
-| 1. 表现差广告降价/关停  | 发现转化极好的「好苗子」，以安全幅度自动涨预算/提价去抢量。                |
-| 2. 高转化广告提价扩量   | 连续几天表现垫底的垃圾素材，系统扮演无情杀手自动关停。                     |
-| 3. A/B测试自动决出胜者  | 科学赛马，根据真实转化价值自动关停输家，把流量全给赢家。                   |
-| 4. 异动根因自动排查建议 | 老板问为什么成本翻倍？系统一键生成诊断报告（揪出外部竞对或内部操作失误）。 |
+详情可见`references/hosted-automation-user-catalog.md`

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.14-beta.2",
-  "publishedAt": 1776838977656
+  "version": "1.1.14-beta.4",
+  "publishedAt": 1777026053968
 }

package/dist/skill/references/account-analytics.md

@@ -82,6 +82,48 @@
 
 ---
 
+### CampaignSectionData（`campaigns[]`）
+
+**路由**：`GET …/reporting/media-account/{mediaCustomerId}/CampaignSectionData?startDate=&endDate=`（以及 TikTok 等媒体在路径中插入媒体段，如 `…/TikTok/{id}/CampaignSectionData?…`）。
+
+**CLI**：Google 为 `siluzan-tso google-analysis campaigns`；TikTok 为 `siluzan-tso report tiktok-campaigns`（另带 `take`，默认 100）。
+
+`campaigns` 数组每一行在既有指标外，另包含：
+
+| 字段 | 说明 |
+| --- | --- |
+| `conversionsValue` | 转化价值 |
+| `conversionsValuePerCost` | 转化价值相对消耗；接口按 **`conversionsValue / spend`** 计算，当 **`spend ≤ 0`** 时为 **`0`** |
+| `campaignTargetCpaMicros` | 系列目标 CPA（微货币单位） |
+| `maximizeConversionsTargetCpaMicros` | 「尽可能提高转化次数」下的目标 CPA（微货币单位） |
+| `manualCpcEnhancedCpcEnabled` | 人工 CPC 是否启用增强 CPC |
+| `percentCpcEnhancedCpcEnabled` | 百分比 CPC 是否启用增强 CPC |
+
+展示微货币字段时须按账户 `currencyCode` 换算为金额，**不要**把 micros 直接当元展示。
+
+---
+
+### campaign-hour（系列按小时）
+
+**路由**：`GET {googleApiUrl}/reporting/media-account/{mediaCustomerId}/campaign-hour?startDate=&endDate=`（与 `google-analysis` 其它带区间接口相同，**`--start` / `--end` 须同传或同省略**）。
+
+**CLI**：`siluzan-tso google-analysis campaign-hour -a <mediaCustomerId> [--start YYYY-MM-DD --end YYYY-MM-DD] --json`
+
+响应体为 **JSON 数组**（非 `{ campaigns: … }` 包装）。元素常见字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `campaignId` | 广告系列 ID |
+| `campaignName` | 广告系列名称 |
+| `date` | 日期 |
+| `hour` | 小时 |
+| `spend` | 消耗 |
+| `impressions` | 展示 |
+| `clicks` | 点击 |
+| `conversions` | 转化 |
+
+---
+
 ### google-analysis
 
 使用已配置的 `googleApiUrl` 与 Token，无需手写 curl。
@@ -102,7 +144,7 @@ siluzan-tso google-analysis <子命令> -a <mediaCustomerId> [选项]
 | `-t, --token`       | 鉴权 Token（可选，默认读配置）                            |
 | `--verbose`         | 打印详细错误                                              |
 
-**子命令与网关路径对应**
+**子命令与拉数路径**
 
 | 子命令               | 说明                                                                                    |
 | -------------------- | --------------------------------------------------------------------------------------- |
@@ -110,6 +152,7 @@ siluzan-tso google-analysis <子命令> -a <mediaCustomerId> [选项]
 | `keywords`           | 关键词 `KeywordSectionData`；可选 `--limit`、`--no-order-by-cost`                       |
 | `search-terms`       | 搜索词 `searchtermmanagement/v2/list`；同上                                             |
 | `campaigns`          | 系列 `CampaignSectionData`                                                              |
+| `campaign-hour`      | 系列按小时 `campaign-hour`（`?startDate=&endDate=`；**根为 JSON 数组**）                 |
 | `ads`                | 广告 `admanagement/v2/list`                                                             |
 | `extensions`         | 附加信息 `extensionmanagement/v2/list`；可选 `--level`（Account / Campaign / Ad Group） |
 | `devices`            | 设备 `DeviceSectionData`                                                                |
@@ -127,15 +170,18 @@ siluzan-tso google-analysis <子命令> -a <mediaCustomerId> [选项]
 | `dimension-summary`  | 账户汇总 `reports/combined`                                                             |
 | `campaign-types`     | 系列类型（**不要**传 `--start`/`--end`）                                                |
 
+`ads` 与 **`ad list`** 同源；带日期区间时创意可能 **按日多行**，宿主编排（降价/扩量/A/B）见 **`references/hosted-automation-optimize-index.md`**。
+
 **示例**
 
 ```bash
 siluzan-tso google-analysis overview -a 6326027735 --start 2026-03-01 --end 2026-03-31 --json
 siluzan-tso google-analysis keywords -a 6326027735 --limit 50
+siluzan-tso google-analysis campaign-hour -a 6326027735 --start 2026-03-01 --end 2026-03-07 --json
 siluzan-tso google-analysis final-urls -a 6326027735 --json
 ```
 
-**CPC / 花费异常巡检（先查后停）**：用户要先定位异常再考虑暂停时，在确认统计区间后，优先用 `google-analysis` 拉**带花费/CPC 粒度**的数据（如 `campaigns`、`daily-metrics`、`keywords` 等，按 CLI `siluzan-tso google-analysis --help` 选择子命令），**不要**在未拉数前就把暂停阈值与写操作一并推进；暂停类命令须遵守 `references/google-ads.md` 的确认流程。
+**CPC / 花费异常巡检（先查后停）**：用户要先定位异常再考虑暂停时，在确认统计区间后，优先用 `google-analysis` 拉**带花费/CPC 粒度**的数据（如 `campaigns`、`campaign-hour`、`daily-metrics`、`keywords` 等，按 CLI `siluzan-tso google-analysis --help` 选择子命令），**不要**在未拉数前就把暂停阈值与写操作一并推进；暂停类命令须遵守 `references/google-ads.md` 的确认流程。
 
 ---
 

package/dist/skill/references/accounts.md

@@ -66,7 +66,7 @@ siluzan-tso account-active-bills -m <媒体> --id <entityId> [--json]
 | `--id <entityId>`    | 必填：账户 `entityId`                                                                |
 | `--json`             | 输出接口原始 JSON                                                                    |
 
-**响应体常用字段（以后端为准）：**
+**响应体常用字段（以接口返回为准）：**
 
 | 字段                                              | 说明                                                                                              |
 | ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
@@ -517,7 +517,7 @@ siluzan-tso open-account kwai \
 >
 > 对应网页：`/foreign_trade/tso/manageAccounts` → 选中 TikTok 账户 → 关闭账户
 >
-> **实现说明（与网页 `manageAccounts` 一致）**：先请求 TikTok 网关 `CheckAdvDisable`（不满足条件如余额未清零会失败），再 `POST .../AdvertiserDisable`；Body 为各账户的 **entityId**。你只需传入 `list-accounts` 中的 **mediaCustomerId**，CLI 会解析 entityId；旧版误把 mediaCustomerId 当 Body 会导致 HTTP 成功但关户不生效。
+> **实现说明（与网页 `manageAccounts` 一致）**：先经 TikTok 侧 `CheckAdvDisable` 校验（不满足条件如余额未清零会失败），再 `POST .../AdvertiserDisable`；Body 为各账户的 **entityId**。你只需传入 `list-accounts` 中的 **mediaCustomerId**，CLI 会解析 entityId；旧版误把 mediaCustomerId 当 Body 会导致 HTTP 成功但关户不生效。
 
 ```bash
 siluzan-tso account close --accounts <mediaCustomerId>
@@ -692,7 +692,7 @@ siluzan-tso account email-auth-list -c <mediaCustomerId> [--agent-type <type>]
 | 选项                     | 说明                                                                       |
 | ------------------------ | -------------------------------------------------------------------------- |
 | `-c, --customer-id <id>` | Google 广告账户 `mediaCustomerId`（与网页查询参数 `customerId` 一致）      |
-| `--agent-type <type>`    | 可选；网关需要时再传（与 `list-accounts --json` 的 `ma.accountType` 一致） |
+| `--agent-type <type>`    | 可选；平台需要时再传（与 `list-accounts --json` 的 `ma.accountType` 一致） |
 | `--json`                 | 输出原始 JSON                                                              |
 
 ---