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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +1 -1
  2. package/assets/siluzan-ads/references/hosted-automation-user-catalog.md +38 -0
  3. package/dist/skill/SKILL.md +15 -29
  4. package/dist/skill/_meta.json +2 -2
  5. package/dist/skill/references/hosted-automation-scenarios.md +1 -0
  6. package/dist/skill/references/hosted-automation-user-catalog.md +38 -0
  7. package/package.json +3 -2
  8. package/scripts/postinstall.mjs +27 -2
package/README.md CHANGED
@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills # 写入自定义目录
51
51
  siluzan-tso init --force # 强制覆盖已存在文件
52
52
  ```
53
53
 
54
- > **注意**：当前为测试版（1.1.14-beta.3），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
54
+ > **注意**：当前为测试版（1.1.14-beta.4），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
55
55
 
56
56
  | 助手 | 建议 `--ai` |
57
57
  | ----------------------- | ------------------------------------ |
package/assets/siluzan-ads/references/hosted-automation-user-catalog.md ADDED
@@ -0,0 +1,38 @@
1
+ # 自动化场景用户向目录
2
+
3
+ 这是skill的一些结合Agent客户端可完成的自动化功能，你可以给用户介绍下面的这些内容
4
+
5
+ ## 预算 & ROI 控制引擎
6
+
7
+ 三条均为 **Google 宿主编排 + siluzan-tso** 路径；IF/定时/通知在宿主，命令与 JSON 以详规为准。
8
+
9
+ | 提醒名称 | 系统在后台默默帮你做什么？(自动动作) | 文档（references） |
10
+ | ------------------- | ------------------------------------- | ------------------ |
11
+ | 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`） |
12
+ | 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)（窗口粒度不足时的报表拉数） |
13
+ | 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 官方名） |
14
+
15
+ **总索引**：[`hosted-automation-scenarios.md`](hosted-automation-scenarios.md) · **自控全文**：[`hosted-automation-self-control.md`](hosted-automation-self-control.md) · **金额硬规范**（展示用 `*Display` 等）：[`SKILL.md`](../SKILL.md)「金额与货币单位硬约束」。
16
+
17
+ ## 异常监控与报警系统
18
+
19
+ 编排（定时、HTTP 探活、通知）在宿主；**读哪些 JSON 字段、用什么命令** 以 **[`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md)** 为准（键名以当次 `--json` 为准，勿套用 Google Ads API 官方字段名解析本 CLI 输出）。
20
+
21
+ | 功能名称 | 监控层级 / 说明 | CLI 检查入口（`--json`） |
22
+ | ----------------- | --------------- | ------------------------ |
23
+ | 1. 账户被封禁 | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 [`accounts.md`](accounts.md) |
24
+ | 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis final-urls`**；或 **`ad list`** / **`google-analysis ads`** 取落地页字段后由宿主 HTTP 校验 |
25
+ | 3. 广告素材拒审 | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **[`google-ads.md`](google-ads.md)**） |
26
+ | 4. 花费异动监控 | 系列或账户维度花费相对历史异常波动。 | **`google-analysis campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
27
+ | 5. 余额枯竭预警 | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
28
+
29
+ ## 自动优化
30
+
31
+ 编排与阈值在宿主；**命令、JSON 键名、聚合与写后复核** 见 **[`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md)**（及链出的三份 SOP）。
32
+
33
+ | 功能名称 | 说明 | SOP |
34
+ | ----------------------- | ---- | ----- |
35
+ | 1. 表现差广告降价/关停 | 组/创意：CTR、CPA、转化等触达后 **下调 `targetCpa` 或 `Paused`**。 | [`hosted-automation-optimize-weak-downbid.md`](hosted-automation-optimize-weak-downbid.md) |
36
+ | 2. 高转化广告提价扩量 | 系列/组：ROAS 代理、预算丢失份额等触达后 **提预算 / 上调目标 CPA**。 | [`hosted-automation-optimize-scale.md`](hosted-automation-optimize-scale.md) |
37
+ | 3. A/B 测试自动决出胜者 | 同组多创意：聚合后比 **CVPI / all conv** 等，**停输家**。 | [`hosted-automation-optimize-ab-winner.md`](hosted-automation-optimize-ab-winner.md) |
38
+ | 4. 异动根因自动排查建议 | 诊断报告与归因：用 `account-analytics`、报告模板等，见 [`account-analytics.md`](account-analytics.md) 与 `report-templates/`。 | （未单独拆 SOP，沿用分析文档） |
package/dist/skill/SKILL.md CHANGED
@@ -52,6 +52,7 @@ allowed-tools: Bash(siluzan-tso:*) Read
52
52
  | `references/setup.md` | 安装、登录、配置、环境切换、更新 |
53
53
  | `references/workflows.md` | 多步骤业务流程、跨命令串联；入口指向宿主编排自控详页 |
54
54
  | `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` |
55
+ | `references/hosted-automation-user-catalog.md` | **用户向**：预算/ROI 自控、异常监控、自动优化一览表（可节选给用户；详规见索引与各子文档） |
55
56
  | `references/tips.md` | `--json`、Node 过滤、分页与调试技巧 |
56
57
  | `references/accounts.md` | 账户列表、余额、消耗、开户记录、授权/解绑/分享/MCC/BC/BM/邮箱授权 |
57
58
  | `references/open-account-by-media.md` | 各媒体开户、参数与资料要求 |
@@ -372,37 +373,22 @@ HTML 报告模板（`report-templates/*.html`）引用了以下外部 CDN 资源
372
373
 
373
374
  ---
374
375
 
375
- ## 下面是一部分比较实用的自动化场景，当你回答完用户问题后，可以把下面的内容输出给用户，方便用户使用
376
+ ## 风险预警，预算&ROI 控制引擎，异常监控与报警系统，自动优化
376
377
 
377
- 您可以选择以下的预警或提醒，输入需想要执行的内容核实规则即可配置。
378
+ 当加载这个skill时，必须主动跟用户介绍你还可以通过这个skill完成以下功能
378
379
 
379
- ### 预算 & ROI 控制引擎
380
+ 1. 单日预算熔断 每日消耗达到设定值，自动暂停计划，杜绝 Google 超额扣费。
381
+ 2. CPA 飙升自动降价 光点不转化（如花费超过3倍目标成本），自动关停该条烂广告。
382
+ 3. 连续空耗自动暂停 大盘流量变贵、获客成本飙高时，系统自动下调出价避险。
380
383
 
381
- | 提醒名称 | 系统在后台默默帮你做什么？(自动动作) |
382
- | ------------------- | --------------------------------------------------------- |
383
- | 1. 单日预算熔断 | 每日消耗达到设定值，自动暂停计划，杜绝 Google 超额扣费。 |
384
- | 2. CPA 飙升自动降价 | 光点不转化（如花费超过3倍目标成本），自动关停该条烂广告。 |
385
- | 3. 连续空耗自动暂停 | 大盘流量变贵、获客成本飙高时，系统自动下调出价避险。 |
384
+ 1. 账户被封禁
385
+ 2. 落地页死链强停 网站宕机或链接填错，紧急自动暂停关联广告，防止把钱扔水里。
386
+ 3. 广告素材拒审 发现被 Google 封号或快没钱了，立刻发送企微/钉钉高优强提醒。
387
+ 4. 花费异动监控 花费突然暴涨或断崖式下跌，系统即时报警提示人工盯盘。
388
+ 5. 余额枯竭预警 广告被 Google 拦截，系统自动帮你打包违规原因并定时推送。
386
389
 
387
- ### 异常监控与报警系统
390
+ 1. 表现差广告降价/关停 发现转化极好的“好苗子”，以安全幅度自动涨预算/提价去抢量。
391
+ 2. 高转化广告 提价扩量" 连续几天表现垫底的垃圾素材，系统扮演无情杀手自动关停。
392
+ 3. A/B测试 自动决出胜者" 科学赛马，根据真实转化价值自动关停输家，把流量全给赢家。
388
393
 
389
- 编排（定时、HTTP 探活、通知）在宿主；**读哪些 JSON 字段、用什么命令** 以 **`references/hosted-automation-monitoring-json.md`** 为准（键名以当次 `--json` 为准，勿套用 Google Ads API 官方字段名解析本 CLI 输出）。
390
-
391
- | 功能名称 | 监控层级 / 说明 | CLI 检查入口（`--json`） |
392
- | ----------------- | --------------- | ------------------------ |
393
- | 1. 账户被封禁 | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 `references/accounts.md` |
394
- | 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis final-urls`**；或 **`ad list`** / **`google-analysis ads`** 取落地页字段后由宿主 HTTP 校验 |
395
- | 3. 广告素材拒审 | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **`references/google-ads.md`**） |
396
- | 4. 花费异动监控 | 系列或账户维度花费相对历史异常波动。 | **`google-analysis campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
397
- | 5. 余额枯竭预警 | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
398
-
399
- ### 自动优化
400
-
401
- 编排与阈值在宿主；**命令、JSON 键名、聚合与写后复核** 见 **`references/hosted-automation-optimize-index.md`**（及链出的三份 SOP）。
402
-
403
- | 功能名称 | 说明 | SOP |
404
- | ----------------------- | ---- | ----- |
405
- | 1. 表现差广告降价/关停 | 组/创意：CTR、CPA、转化等触达后 **下调 `targetCpa` 或 `Paused`**。 | [`hosted-automation-optimize-weak-downbid.md`](references/hosted-automation-optimize-weak-downbid.md) |
406
- | 2. 高转化广告提价扩量 | 系列/组：ROAS 代理、预算丢失份额等触达后 **提预算 / 上调目标 CPA**。 | [`hosted-automation-optimize-scale.md`](references/hosted-automation-optimize-scale.md) |
407
- | 3. A/B 测试自动决出胜者 | 同组多创意：聚合后比 **CVPI / all conv** 等，**停输家**。 | [`hosted-automation-optimize-ab-winner.md`](references/hosted-automation-optimize-ab-winner.md) |
408
- | 4. 异动根因自动排查建议 | 诊断报告与归因：用 `account-analytics`、报告模板等，见 `references/account-analytics.md` 与 `report-templates/`。 | （未单独拆 SOP，沿用分析文档） |
394
+ 详情可见`references/hosted-automation-user-catalog.md`
package/dist/skill/_meta.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "slug": "siluzan-tso",
3
- "version": "1.1.14-beta.3",
4
- "publishedAt": 1776995703860
3
+ "version": "1.1.14-beta.4",
4
+ "publishedAt": 1777026053968
5
5
  }
package/dist/skill/references/hosted-automation-scenarios.md CHANGED
@@ -10,6 +10,7 @@
10
10
  | [`hosted-automation-self-control.md`](hosted-automation-self-control.md) | **三类投放自控**：单日预算熔断、CPA 飙升降价、连续空耗暂停；通用约定与常用 JSON 字段表；宿主编排实现清单；与 `forewarning` 的关系 |
11
11
  | [`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md) | **异常监控巡检**：`balance-scan` / `balance` / `google-analysis overview` / `campaign-hour` / `final-urls`、拒审相关等 **`--json` 键名与命令** |
12
12
  | [`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md) | **自动优化（宿主编排）**：差素材降价/关停、高转化扩量、A/B 停输家 — 分文件 SOP（含 `ad list` 按日聚合、`google-analysis campaigns` 等） |
13
+ | [`hosted-automation-user-catalog.md`](hosted-automation-user-catalog.md) | **用户向一览**：预算/ROI 自控、异常监控、自动优化表格（可节选给用户；与上表互补） |
13
14
 
14
15
  **必读交叉引用**（子文档内会再写一遍）：
15
16
 
package/dist/skill/references/hosted-automation-user-catalog.md ADDED
@@ -0,0 +1,38 @@
1
+ # 自动化场景用户向目录
2
+
3
+ 这是skill的一些结合Agent客户端可完成的自动化功能，你可以给用户介绍下面的这些内容
4
+
5
+ ## 预算 & ROI 控制引擎
6
+
7
+ 三条均为 **Google 宿主编排 + siluzan-tso** 路径；IF/定时/通知在宿主，命令与 JSON 以详规为准。
8
+
9
+ | 提醒名称 | 系统在后台默默帮你做什么？(自动动作) | 文档（references） |
10
+ | ------------------- | ------------------------------------- | ------------------ |
11
+ | 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`） |
12
+ | 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)（窗口粒度不足时的报表拉数） |
13
+ | 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 官方名） |
14
+
15
+ **总索引**：[`hosted-automation-scenarios.md`](hosted-automation-scenarios.md) · **自控全文**：[`hosted-automation-self-control.md`](hosted-automation-self-control.md) · **金额硬规范**（展示用 `*Display` 等）：[`SKILL.md`](../SKILL.md)「金额与货币单位硬约束」。
16
+
17
+ ## 异常监控与报警系统
18
+
19
+ 编排（定时、HTTP 探活、通知）在宿主；**读哪些 JSON 字段、用什么命令** 以 **[`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md)** 为准（键名以当次 `--json` 为准，勿套用 Google Ads API 官方字段名解析本 CLI 输出）。
20
+
21
+ | 功能名称 | 监控层级 / 说明 | CLI 检查入口（`--json`） |
22
+ | ----------------- | --------------- | ------------------------ |
23
+ | 1. 账户被封禁 | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 [`accounts.md`](accounts.md) |
24
+ | 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis final-urls`**；或 **`ad list`** / **`google-analysis ads`** 取落地页字段后由宿主 HTTP 校验 |
25
+ | 3. 广告素材拒审 | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **[`google-ads.md`](google-ads.md)**） |
26
+ | 4. 花费异动监控 | 系列或账户维度花费相对历史异常波动。 | **`google-analysis campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
27
+ | 5. 余额枯竭预警 | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
28
+
29
+ ## 自动优化
30
+
31
+ 编排与阈值在宿主；**命令、JSON 键名、聚合与写后复核** 见 **[`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md)**（及链出的三份 SOP）。
32
+
33
+ | 功能名称 | 说明 | SOP |
34
+ | ----------------------- | ---- | ----- |
35
+ | 1. 表现差广告降价/关停 | 组/创意：CTR、CPA、转化等触达后 **下调 `targetCpa` 或 `Paused`**。 | [`hosted-automation-optimize-weak-downbid.md`](hosted-automation-optimize-weak-downbid.md) |
36
+ | 2. 高转化广告提价扩量 | 系列/组：ROAS 代理、预算丢失份额等触达后 **提预算 / 上调目标 CPA**。 | [`hosted-automation-optimize-scale.md`](hosted-automation-optimize-scale.md) |
37
+ | 3. A/B 测试自动决出胜者 | 同组多创意：聚合后比 **CVPI / all conv** 等，**停输家**。 | [`hosted-automation-optimize-ab-winner.md`](hosted-automation-optimize-ab-winner.md) |
38
+ | 4. 异动根因自动排查建议 | 诊断报告与归因：用 `account-analytics`、报告模板等，见 [`account-analytics.md`](account-analytics.md) 与 `report-templates/`。 | （未单独拆 SOP，沿用分析文档） |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "siluzan-tso-cli",
3
- "version": "1.1.14-beta.3",
3
+ "version": "1.1.14-beta.4",
4
4
  "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
5
5
  "keywords": [
6
6
  "ad-account",
@@ -21,7 +21,8 @@
21
21
  "eval/cases",
22
22
  "eval/stub-fixtures",
23
23
  "README.md",
24
- "scripts/postinstall.mjs"
24
+ "scripts/postinstall.mjs",
25
+ "assets/siluzan-ads/references/hosted-automation-user-catalog.md"
25
26
  ],
26
27
  "type": "module",
27
28
  "publishConfig": {
package/scripts/postinstall.mjs CHANGED
@@ -1,7 +1,32 @@
1
1
  /**
2
2
  * 安装本包后提示：升级 CLI 后请同步 Skill（见 siluzan-tso update）。
3
3
  * monorepo / 本地 link 时每次 install 也会执行，属预期。
4
+ *
5
+ * 自动化场景说明从 `assets/.../hosted-automation-user-catalog.md` 读取，避免在脚本内嵌含反引号的模板字符串导致语法错误。
4
6
  */
5
- console.log(
6
- "[siluzan-tso]: 安装成功，请执行 siluzan-tso init -d /path/to/skills 复制项目中最新的skill文件来更新你的skill",
7
+ import fs from "node:fs";
8
+ import path from "node:path";
9
+ import { fileURLToPath } from "node:url";
10
+
11
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
12
+ const catalogPath = path.join(
13
+ __dirname,
14
+ "..",
15
+ "assets",
16
+ "siluzan-ads",
17
+ "references",
18
+ "hosted-automation-user-catalog.md",
7
19
  );
20
+
21
+ const header =
22
+ "[siluzan-tso]: 安装成功，请执行 siluzan-tso init -d /path/to/skills 复制项目中最新的 skill 文件来更新你的 skill";
23
+
24
+ let body = "";
25
+ try {
26
+ body = "\n\n" + fs.readFileSync(catalogPath, "utf8").trimEnd();
27
+ } catch {
28
+ body =
29
+ "\n\n";
30
+ }
31
+
32
+ console.log(header + body);