siluzan-tso-cli 1.1.18 → 1.1.19-beta.2

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 (98) hide show
  1. package/README.md +8 -7
  2. package/assets/siluzan-ads/references/hosted-automation-user-catalog.md +17 -19
  3. package/dist/index.js +1112 -874
  4. package/dist/skill/SKILL.md +66 -38
  5. package/dist/skill/_meta.json +2 -2
  6. package/dist/skill/references/account-analytics.md +95 -88
  7. package/dist/skill/references/accounts.md +10 -9
  8. package/dist/skill/references/finance.md +5 -5
  9. package/dist/skill/references/google-ads-rules/google-ads-account-audit.md +1 -0
  10. package/dist/skill/references/google-ads-rules/google-ads-keyword-optimization.md +1 -1
  11. package/dist/skill/references/google-ads-rules/google-ads-landing-page-discovery-via-webfetch.md +72 -0
  12. package/dist/skill/references/google-ads-rules/google-ads-launch-plan-template.md +25 -16
  13. package/dist/skill/references/google-ads.md +236 -1025
  14. package/dist/skill/references/google-analysis-batch.md +53 -46
  15. package/dist/skill/references/hosted-automation-monitoring-json.md +10 -10
  16. package/dist/skill/references/hosted-automation-optimize-ab-winner.md +3 -3
  17. package/dist/skill/references/hosted-automation-optimize-index.md +5 -5
  18. package/dist/skill/references/hosted-automation-optimize-scale.md +2 -2
  19. package/dist/skill/references/hosted-automation-optimize-weak-downbid.md +5 -5
  20. package/dist/skill/references/hosted-automation-scenarios.md +5 -5
  21. package/dist/skill/references/hosted-automation-self-control.md +24 -23
  22. package/dist/skill/references/hosted-automation-user-catalog.md +17 -19
  23. package/dist/skill/references/keyword-planner-workflows.md +104 -0
  24. package/dist/skill/references/open-account-google-ui.md +0 -1
  25. package/dist/skill/references/reporting.md +2 -2
  26. package/dist/skill/references/setup.md +21 -22
  27. package/dist/skill/references/tips.md +2 -1
  28. package/dist/skill/references/tso-home.md +1 -1
  29. package/dist/skill/references/workflows.md +10 -4
  30. package/dist/skill/references/write-audit-restore.md +39 -6
  31. package/dist/skill/report-templates/README.md +1 -0
  32. package/dist/skill/report-templates/REPORT-WORKFLOW.md +4 -0
  33. package/dist/skill/report-templates/google-period-report.md +16 -16
  34. package/dist/skill/report-templates/okki-weekly-google-client.md +105 -0
  35. package/dist/skill/scripts/install.ps1 +2 -2
  36. package/dist/skill/scripts/install.sh +2 -2
  37. package/eval/cases/accounts-entityid-vs-mediaccustomerid.scenario.json +2 -14
  38. package/eval/cases/accounts-mcc-bind-inquiry.scenario.json +1 -3
  39. package/eval/cases/accounts-single-balance-not-bulk.scenario.json +3 -14
  40. package/eval/cases/budget-display-not-raw-micros.scenario.json +1 -8
  41. package/eval/cases/clue-meta-leads-json.scenario.json +2 -14
  42. package/eval/cases/clue-tiktok-leads-json.scenario.json +2 -11
  43. package/eval/cases/destructive-account-delink-needs-confirm.scenario.json +3 -9
  44. package/eval/cases/destructive-forewarning-delete-needs-confirm.scenario.json +3 -9
  45. package/eval/cases/destructive-invoice-apply-needs-confirm.scenario.json +3 -9
  46. package/eval/cases/finance-invoice-info-list.scenario.json +3 -11
  47. package/eval/cases/forewarning-list-google.scenario.json +3 -14
  48. package/eval/cases/google-ads-no-structural-without-confirm.scenario.json +2 -6
  49. package/eval/cases/google-analysis-keywords-route.scenario.json +2 -14
  50. package/eval/cases/human-p1-multiturn.scenario.json +1 -5
  51. package/eval/cases/meta-single-balance-not-bulk.scenario.json +3 -17
  52. package/eval/cases/open-account-bing-noninteractive.scenario.json +1 -4
  53. package/eval/cases/open-account-google-noninteractive.scenario.json +1 -3
  54. package/eval/cases/open-account-tiktok-license-file.scenario.json +1 -3
  55. package/eval/cases/optimize-list-by-account.scenario.json +3 -11
  56. package/eval/cases/p1-single-account-profile.scenario.json +1 -11
  57. package/eval/cases/p2-balance-scan-bulk.scenario.json +2 -9
  58. package/eval/cases/p3-accounts-digest.scenario.json +1 -5
  59. package/eval/cases/p4-period-report-window.scenario.json +1 -8
  60. package/eval/cases/report-list-google.scenario.json +2 -11
  61. package/eval/cases/report-push-list-google.scenario.json +2 -11
  62. package/eval/cases/reporting-vs-account-analytics-routing.scenario.json +1 -4
  63. package/eval/cases/setup-login-or-env.scenario.json +1 -3
  64. package/eval/cases/setup-siluzan-data-permission-env.scenario.json +1 -3
  65. package/eval/cases/skill-optimize-vs-google-ads-distinction.scenario.json +1 -4
  66. package/eval/cases/tiktok-bc-bind-inquiry.scenario.json +2 -6
  67. package/eval/cases/time-range-user-delegates-default.scenario.json +1 -8
  68. package/eval/cases/tips-json-filtering.scenario.json +1 -3
  69. package/eval/cases/tips-large-json-pagination.scenario.json +1 -3
  70. package/eval/cases/uj-ad-outdoor-campgear-search-plan.scenario.json +1 -3
  71. package/eval/cases/uj-analytics-30d-pdf-campaign-device-geo.scenario.json +6 -18
  72. package/eval/cases/uj-analytics-compare-google-tiktok-last-month-roi.scenario.json +1 -8
  73. package/eval/cases/uj-analytics-google-weekly-trends-campaigns-keywords.scenario.json +2 -11
  74. package/eval/cases/uj-analytics-report-push-weekly-email.scenario.json +1 -3
  75. package/eval/cases/uj-finance-invoice-records-this-month.scenario.json +2 -11
  76. package/eval/cases/uj-life-newbie-siluzan-google-end-to-end.scenario.json +1 -4
  77. package/eval/cases/uj-ops-google-accounts-list-normal.scenario.json +2 -14
  78. package/eval/cases/uj-ops-google-yesterday-spend-conversions.scenario.json +2 -14
  79. package/eval/cases/uj-ops-open-google-b2c-usd-shenzhen.scenario.json +1 -4
  80. package/eval/cases/uj-ops-pause-worst-adgroup-confirm.scenario.json +2 -6
  81. package/eval/cases/uj-ops-tiktok-leads-last-week.scenario.json +3 -17
  82. package/eval/cases/uj-patrol-cpc-spike-adgroups-over-15.scenario.json +2 -9
  83. package/eval/cases/uj-patrol-forewarning-create-daily-cap-3000.scenario.json +1 -3
  84. package/eval/cases/uj-patrol-forewarning-trigger-records.scenario.json +3 -17
  85. package/eval/cases/uj-patrol-google-balances-low.scenario.json +2 -11
  86. package/eval/cases/uj-roi-optimize-records-then-execute-cautiously.scenario.json +3 -14
  87. package/eval/cases/uj-roi-search-terms-add-negative-keywords.scenario.json +2 -14
  88. package/eval/stub-fixtures/balance-meta.json +3 -1
  89. package/eval/stub-fixtures/clue-meta.json +6 -1
  90. package/eval/stub-fixtures/clue-tiktok.json +3 -1
  91. package/eval/stub-fixtures/forewarning-create-ok.json +5 -1
  92. package/eval/stub-fixtures/forewarning-records.json +3 -1
  93. package/eval/stub-fixtures/google-analysis.json +81 -21
  94. package/eval/stub-fixtures/invoice-billable.json +3 -1
  95. package/eval/stub-fixtures/invoice-list.json +14 -2
  96. package/eval/stub-fixtures/report-push-list.json +3 -1
  97. package/package.json +2 -2
  98. package/scripts/postinstall.mjs +1 -2
package/dist/skill/references/google-analysis-batch.md CHANGED
@@ -10,11 +10,11 @@
10
10
 
11
11
  ## 子命令
12
12
 
13
- | 子命令 | 用途 |
14
- |--------|------|
15
- | `run` | 首次执行：自动拉账户清单 + 双层并发 + 落盘 |
13
+ | 子命令 | 用途 |
14
+ | -------- | ----------------------------------------------- |
15
+ | `run` | 首次执行：自动拉账户清单 + 双层并发 + 落盘 |
16
16
  | `resume` | 续跑：仅重做 pending / failed_retryable 的 task |
17
- | `status` | 只读查询进度与失败样例（不发起 HTTP） |
17
+ | `status` | 只读查询进度与失败样例（不发起 HTTP） |
18
18
 
19
19
  ---
20
20
 
@@ -63,23 +63,23 @@ siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId
63
63
 
64
64
  ## 参数
65
65
 
66
- | 参数 | 说明 | 默认值 |
67
- |------|------|--------|
68
- | `--json-out <dir>` | 必填，产物根目录 | — |
69
- | `--run-id <id>` | 自定义 runId | 自动 `run-YYYYMMDD-HHmmss-<rand4>` |
70
- | `-a, --accounts <ids>` | 显式 ID 列表；传入则跳过清单拉取与 `--min-spend` | 省略时自动拉全量 Google 账号 |
71
- | `--start` / `--end` | 统计区间（YYYY-MM-DD） | 近 7 天截至昨天 |
72
- | `--sections <list>` | 维度（逗号分隔），合法值见 `references/account-analytics.md` | `campaigns,geographic,keywords` |
73
- | `--account-concurrency <n>` | 账户级并发（1~16） | 4 |
74
- | `--section-concurrency <n>` | 单账户内维度并发（1~16） | 6 |
75
- | `--keyword-limit <n>` | keywords / search-terms 条数上限 | google-analysis 默认 |
76
- | `--min-spend <n>` | 区间消耗 ≤ 此值跳过（与 `-a` 同传无效） | 0 |
77
- | `--deadline <dur>` | 整任务硬截止（如 `30m` / `2h`），到期标记 paused | 不设 |
78
- | `--task-timeout-ms <n>` | 单 task 硬超时 | 60000 |
79
- | `--max-attempts <n>` | 可重试错误最大尝试次数 | 3 |
80
- | `--refresh-dp` | 执行前强制刷新 Datapermission | false |
81
- | `--no-verbose-progress` | 关闭 stderr 进度条（CI 推荐） | false |
82
- | `-t, --token` | 临时覆盖 Token | `~/.siluzan/config.json` |
66
+ | 参数 | 说明 | 默认值 |
67
+ | --------------------------- | ------------------------------------------------------------ | ---------------------------------- |
68
+ | `--json-out <dir>` | 必填，产物根目录 | — |
69
+ | `--run-id <id>` | 自定义 runId | 自动 `run-YYYYMMDD-HHmmss-<rand4>` |
70
+ | `-a, --accounts <ids>` | 显式 ID 列表；传入则跳过清单拉取与 `--min-spend` | 省略时自动拉全量 Google 账号 |
71
+ | `--start` / `--end` | 统计区间（YYYY-MM-DD） | 近 7 天截至昨天 |
72
+ | `--sections <list>` | 维度（逗号分隔），合法值见 `references/account-analytics.md` | `campaigns,geographic,keywords` |
73
+ | `--account-concurrency <n>` | 账户级并发（1~16） | 4 |
74
+ | `--section-concurrency <n>` | 单账户内维度并发（1~16） | 6 |
75
+ | `--keyword-limit <n>` | keywords / search-terms 条数上限 | google-analysis 默认 |
76
+ | `--min-spend <n>` | 区间消耗 ≤ 此值跳过（与 `-a` 同传无效） | 0 |
77
+ | `--deadline <dur>` | 整任务硬截止（如 `30m` / `2h`），到期标记 paused | 不设 |
78
+ | `--task-timeout-ms <n>` | 单 task 硬超时 | 60000 |
79
+ | `--max-attempts <n>` | 可重试错误最大尝试次数 | 3 |
80
+ | `--refresh-dp` | 执行前强制刷新 Datapermission | false |
81
+ | `--no-verbose-progress` | 关闭 stderr 进度条（CI 推荐） | false |
82
+ | `-t, --token` | 临时覆盖 Token | `~/.siluzan/config.json` |
83
83
 
84
84
  ---
85
85
 
@@ -112,10 +112,14 @@ siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId
112
112
  读 outline 的最小写法（脚本里也只读最后一行）：
113
113
 
114
114
  ```js
115
- const fs = require('node:fs');
115
+ const fs = require("node:fs");
116
116
  // outlineFile 来自 manifest-<accountId>.json 的 sections[].outlineFile
117
- const outline = fs.readFileSync(outlineFile, 'utf8');
118
- const tsType = outline.trimEnd().split('\n').filter(l => !l.startsWith('//')).pop();
117
+ const outline = fs.readFileSync(outlineFile, "utf8");
118
+ const tsType = outline
119
+ .trimEnd()
120
+ .split("\n")
121
+ .filter((l) => !l.startsWith("//"))
122
+ .pop();
119
123
  // tsType 形如：{ items: { id: number; spend: number; ... }[]; meta: { ... } }
120
124
  ```
121
125
 
@@ -138,9 +142,12 @@ const tsType = outline.trimEnd().split('\n').filter(l => !l.startsWith('//')).po
138
142
  "tokenInvalidated": false,
139
143
  "elapsedMs": 423000,
140
144
  "stats": {
141
- "totalTasks": 468, "success": 462,
142
- "failedPermanent": 4, "failedRetryable": 2,
143
- "skipped": 0, "throttleEvents": 1
145
+ "totalTasks": 468,
146
+ "success": 462,
147
+ "failedPermanent": 4,
148
+ "failedRetryable": 2,
149
+ "skipped": 0,
150
+ "throttleEvents": 1
144
151
  }
145
152
  }
146
153
  ```
@@ -151,23 +158,23 @@ const tsType = outline.trimEnd().split('\n').filter(l => !l.startsWith('//')).po
151
158
 
152
159
  ## 退出码
153
160
 
154
- | 码 | 含义 | 后续动作 |
155
- |----|------|---------|
156
- | `0` | 全部成功，state=`succeeded` | 继续后续 |
157
- | `2` | 部分成功（`partial`）或超时（`paused`） | 看 `errors/` 或消费已有产物 |
161
+ | 码 | 含义 | 后续动作 |
162
+ | --- | ------------------------------------------ | --------------------------------------------- |
163
+ | `0` | 全部成功，state=`succeeded` | 继续后续 |
164
+ | `2` | 部分成功（`partial`）或超时（`paused`） | 看 `errors/` 或消费已有产物 |
158
165
  | `3` | 全失败 / Token 失效 / 致命错误（`failed`） | `tokenInvalidated:true` → `siluzan-tso login` |
159
- | `4` | 参数错误（命令未执行） | 修正参数重试 |
166
+ | `4` | 参数错误（命令未执行） | 修正参数重试 |
160
167
 
161
168
  ---
162
169
 
163
170
  ## 错误分类与重试
164
171
 
165
- | 分类 | 触发条件 | 处理 |
166
- |------|---------|------|
167
- | `abort` | HTTP 401 | **立即终止整批**，`tokenInvalidated:true`，可 resume |
168
- | `failed_permanent` | HTTP 400 / 403 / 404 | 不重试，记入 `errors/` |
169
- | `failed_retryable` | HTTP 408 / 429 / 5xx / 超时 / 网络错误 | 指数退避 `1s × 2^attempt + jitter`（cap 30s），最多 `--max-attempts` 次 |
170
- | `skipped` | `invalidOAuthToken=true` 或被 `--min-spend` 过滤 | 不发起 HTTP |
172
+ | 分类 | 触发条件 | 处理 |
173
+ | ------------------ | ------------------------------------------------ | ----------------------------------------------------------------------- |
174
+ | `abort` | HTTP 401 | **立即终止整批**，`tokenInvalidated:true`，可 resume |
175
+ | `failed_permanent` | HTTP 400 / 403 / 404 | 不重试，记入 `errors/` |
176
+ | `failed_retryable` | HTTP 408 / 429 / 5xx / 超时 / 网络错误 | 指数退避 `1s × 2^attempt + jitter`（cap 30s），最多 `--max-attempts` 次 |
177
+ | `skipped` | `invalidOAuthToken=true` 或被 `--min-spend` 过滤 | 不发起 HTTP |
171
178
 
172
179
  **自适应降级**：滚动 20 task 内错误率 ≥ 30% → 账户并发与维度并发同时减半；冷却 60s。`progress.throttleEvents` 记录次数。
173
180
 
@@ -177,14 +184,14 @@ const tsType = outline.trimEnd().split('\n').filter(l => !l.startsWith('//')).po
177
184
 
178
185
  `google-analysis` 会根据 `-a` 的 ID 数量自动选路，底层共享同一引擎：
179
186
 
180
- | | `google-analysis -a <单ID>` | `google-analysis -a id1,id2,id3` | `google-analysis-batch run` |
181
- |--------|------|------|------|
182
- | 账户数 | 1 | 2~10 | 任意（含 0→自动拉全量） |
183
- | 调度 | 单账户多维度 | 双层并发 | 双层并发 |
184
- | 失败处理 | 抛错 | 自动分类 + 退避 + 401 终止 | 同左 |
185
- | 中断恢复 | 不支持 | `resume` | `resume` |
186
- | stdout | snapshot-batch | `siluzan-tso-batch-summary`（含 `forwardedFrom`） | `siluzan-tso-batch-summary` |
187
- | 产物 | `<dir>/<section>-<id>.json` | `<dir>/<runId>/results/<accountId>/<section>-<id>.json` | 同左 |
187
+ | | `google-analysis -a <单ID>` | `google-analysis -a id1,id2,id3` | `google-analysis-batch run` |
188
+ | -------- | --------------------------- | ------------------------------------------------------- | --------------------------- |
189
+ | 账户数 | 1 | 2~10 | 任意（含 0→自动拉全量） |
190
+ | 调度 | 单账户多维度 | 双层并发 | 双层并发 |
191
+ | 失败处理 | 抛错 | 自动分类 + 退避 + 401 终止 | 同左 |
192
+ | 中断恢复 | 不支持 | `resume` | `resume` |
193
+ | stdout | snapshot-batch | `siluzan-tso-batch-summary`（含 `forwardedFrom`） | `siluzan-tso-batch-summary` |
194
+ | 产物 | `<dir>/<section>-<id>.json` | `<dir>/<runId>/results/<accountId>/<section>-<id>.json` | 同左 |
188
195
 
189
196
  单 section JSON 结构完全一致，仅目录组织不同。
190
197
 
package/dist/skill/references/hosted-automation-monitoring-json.md CHANGED
@@ -18,16 +18,16 @@ siluzan-tso balance-scan -m Google [--threshold-days <n>] [--min-balance <n>] [-
18
18
 
19
19
  `--json` 时根结构为 **`{ ok, data: { items }, meta }`**（以实际输出为准）。宿主常用字段：
20
20
 
21
- | 用途 | JSON 路径 / 字段名 |
22
- |------|---------------------|
23
- | 账户 | `data.items[].mediaCustomerId`、`data.items[].name`、`data.items[].advertiserName` |
24
- | 余额（主币种金额，与平台余额接口一致） | **`data.items[].balance`**（由 `remainingAccountBudget` 计算而来） |
25
- | 近 7 日估算日均消耗 | **`data.items[].dailySpend`** = 近 7 日总消耗 / 7（窗口为 **[T-7, T-1]**，即截至昨天的 7 个自然日，**不含当天**，避免拉到当天未结算数据） |
26
- | 按余额÷日均估算的续航天数 | **`data.items[].remainingDays`** = `balance / dailySpend`（消耗过低 < `minDailySpend` 时为 `null`） |
27
- | 建议充值额（按 `meta.thresholds.targetDaysForTopup` 目标） | **`data.items[].recommendedTopup`** |
28
- | 命中原因（阈值逻辑） | **`data.items[].hitReason`**：`low-days` \| `low-balance` \| `both` |
29
- | 币种 / 状态 / OAuth | `data.items[].currencyCode`、`data.items[].status`、`data.items[].invalidOAuthToken` |
30
- | 本轮扫描元数据 | **`meta`**：`scannedAccounts`、`validAccounts`、`hitCount`、`thresholds`（含 `days`、`minBalance`、`minDailySpend`、`targetDaysForTopup`）、`generatedAt` 等 |
21
+ | 用途 | JSON 路径 / 字段名 |
22
+ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
23
+ | 账户 | `data.items[].mediaCustomerId`、`data.items[].name`、`data.items[].advertiserName` |
24
+ | 余额（主币种金额，与平台余额接口一致） | **`data.items[].balance`**（由 `remainingAccountBudget` 计算而来） |
25
+ | 近 7 日估算日均消耗 | **`data.items[].dailySpend`** = 近 7 日总消耗 / 7（窗口为 **[T-7, T-1]**，即截至昨天的 7 个自然日，**不含当天**，避免拉到当天未结算数据） |
26
+ | 按余额÷日均估算的续航天数 | **`data.items[].remainingDays`** = `balance / dailySpend`（消耗过低 < `minDailySpend` 时为 `null`） |
27
+ | 建议充值额（按 `meta.thresholds.targetDaysForTopup` 目标） | **`data.items[].recommendedTopup`** |
28
+ | 命中原因（阈值逻辑） | **`data.items[].hitReason`**：`low-days` \| `low-balance` \| `both` |
29
+ | 币种 / 状态 / OAuth | `data.items[].currencyCode`、`data.items[].status`、`data.items[].invalidOAuthToken` |
30
+ | 本轮扫描元数据 | **`meta`**：`scannedAccounts`、`validAccounts`、`hitCount`、`thresholds`（含 `days`、`minBalance`、`minDailySpend`、`targetDaysForTopup`）、`generatedAt` 等 |
31
31
 
32
32
  **单账户** — 命令：
33
33
 
package/dist/skill/references/hosted-automation-optimize-ab-winner.md CHANGED
@@ -22,8 +22,8 @@ siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD>
22
22
 
23
23
  ### 2. 按组筛选、按创意聚合
24
24
 
25
- - 对同一 **`adGroupId`** 下的行，先按创意 **`id`** 聚合（见索引「按日多行」）：对 **`impressions`**、**`clicks`**、**`spend`**、**`conversions`**、**`allConversions`**、**`conversionsValue`** **求和**。
26
- - **每次展现价值（聚合后）**：宿主计算
25
+ - 对同一 **`adGroupId`** 下的行，先按创意 **`id`** 聚合（见索引「按日多行」）：对 **`impressions`**、**`clicks`**、**`spend`**、**`conversions`**、**`allConversions`**、**`conversionsValue`** **求和**。
26
+ - **每次展现价值（聚合后）**：宿主计算
27
27
 
28
28
  `cvpi = (Σ conversionsValue) / (Σ impressions)`，当分母为 0 时跳过该创意判定。
29
29
 
@@ -31,7 +31,7 @@ siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD>
31
31
 
32
32
  ### 3. 参与判定的最小样本（示例）
33
33
 
34
- - 聚合后 **`impressions`**（或 **`clicks`**）低于配置下限的创意**不参与**胜负判定。
34
+ - 聚合后 **`impressions`**（或 **`clicks`**）低于配置下限的创意**不参与**胜负判定。
35
35
  - 同组内「活跃且达样本」的创意 **≥ 2** 条时才进入 A/B 决策。
36
36
 
37
37
  ### 4. 统计显著性
package/dist/skill/references/hosted-automation-optimize-index.md CHANGED
@@ -3,11 +3,11 @@
3
3
  > **编排责任**：定时、阈值、多轮状态（如「连续 3 日未改善」）、统计检验、通知（P1/P2）由 **宿主** 实现。
4
4
  > **本组文档**：说明如何用 `siluzan-tso` **拉检查项**、**执行写操作**、**写后复核**；每条 SOP 独立成文，避免单文件过长。
5
5
 
6
- | 文档 | 场景 |
7
- |------|------|
8
- | [`hosted-automation-optimize-weak-downbid.md`](hosted-automation-optimize-weak-downbid.md) | 表现差：组/创意 **降价或暂停** |
9
- | [`hosted-automation-optimize-scale.md`](hosted-automation-optimize-scale.md) | 高转化：**提预算 / 上调目标 CPA** 扩量 |
10
- | [`hosted-automation-optimize-ab-winner.md`](hosted-automation-optimize-ab-winner.md) | 同组多创意：**A/B 决胜负、停输家** |
6
+ | 文档 | 场景 |
7
+ | ------------------------------------------------------------------------------------------ | -------------------------------------- |
8
+ | [`hosted-automation-optimize-weak-downbid.md`](hosted-automation-optimize-weak-downbid.md) | 表现差：组/创意 **降价或暂停** |
9
+ | [`hosted-automation-optimize-scale.md`](hosted-automation-optimize-scale.md) | 高转化：**提预算 / 上调目标 CPA** 扩量 |
10
+ | [`hosted-automation-optimize-ab-winner.md`](hosted-automation-optimize-ab-winner.md) | 同组多创意：**A/B 决胜负、停输家** |
11
11
 
12
12
  **必读交叉引用**：`SKILL.md`（金额与 `*Display` 硬规范）、`references/google-ads.md`（`ad campaign-edit` / `ad adgroup-edit` / `ad-status`）、`references/account-analytics.md`（日期与 **`google-analysis --json-out`**）、`references/tips.md`（通用 **`--json-out`** 落盘 + 读文件技巧）、[`hosted-automation-self-control.md`](hosted-automation-self-control.md)（统计日与时区约定）。
13
13
 
package/dist/skill/references/hosted-automation-optimize-scale.md CHANGED
@@ -44,8 +44,8 @@ mkdir -p ./snap-scale && siluzan-tso google-analysis -a <mediaCustomerId> --sect
44
44
 
45
45
  ### 4. 条件示例（仅示意）
46
46
 
47
- - 连续 **N** 日 **`conversionsValuePerCost`** 高于宿主配置的「目标 × 倍数」。
48
- - 且 **`searchBudgetLostImpressionShare`** 高于配置阈值（注意接口多为 **0–1 小数**，比较时与配置统一）。
47
+ - 连续 **N** 日 **`conversionsValuePerCost`** 高于宿主配置的「目标 × 倍数」。
48
+ - 且 **`searchBudgetLostImpressionShare`** 高于配置阈值（注意接口多为 **0–1 小数**，比较时与配置统一）。
49
49
  - 可选：`campaign-hour` 上近端 **`spend`** 增速超过配置。
50
50
 
51
51
  ---
package/dist/skill/references/hosted-automation-optimize-weak-downbid.md CHANGED
@@ -31,9 +31,9 @@ siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD>
31
31
 
32
32
  ### 2. 聚合与常用键名
33
33
 
34
- - 响应为 `items[]`（外层结构见 `wrapListJson` 约定，以当次输出为准）。
35
- - **须按 `id` 聚合**（见索引「按日多行」）：对 `impressions`、`clicks`、`spend`、`conversions`、**`allConversions`**、**`conversionsValue`** 等同名字段做**求和**；比率在聚合后计算，例如
36
- - **实际 CPA**（主币种）：`spend / conversions`（`conversions == 0` 时不做 CPA 规则判断）。
34
+ - 响应为 `items[]`（外层结构见 `wrapListJson` 约定，以当次输出为准）。
35
+ - **须按 `id` 聚合**（见索引「按日多行」）：对 `impressions`、`clicks`、`spend`、`conversions`、**`allConversions`**、**`conversionsValue`** 等同名字段做**求和**；比率在聚合后计算，例如
36
+ - **实际 CPA**（主币种）：`spend / conversions`（`conversions == 0` 时不做 CPA 规则判断）。
37
37
  - **CTR**：聚合后 `clicks / impressions` 或与行上 **`ctr`** 口径对齐前，先确认组列表与创意列表 **`ctr` 是否均为 0–1 或均为百分比**，避免跨命令混比。
38
38
 
39
39
  创意行上（在已部署网关、且 `skipReport` 为 false 时）常见扩展字段：
@@ -49,8 +49,8 @@ siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD>
49
49
 
50
50
  ### 3. 条件示例（仅示意，以宿主配置为准）
51
51
 
52
- - **数据置信**：聚合后 **`impressions`**（或 **`clicks`**）高于配置下限再参与判定。
53
- - **弱引流**：聚合后 CTR 低于「同池基准 × 配置比例」（基准由宿主对同类型/同系列池计算）。
52
+ - **数据置信**：聚合后 **`impressions`**（或 **`clicks`**）高于配置下限再参与判定。
53
+ - **弱引流**：聚合后 CTR 低于「同池基准 × 配置比例」（基准由宿主对同类型/同系列池计算）。
54
54
  - **弱转化**：**`spend / conversions`**（或 **`costPerConversion`** 与目标同口径比较）高于 **目标 CPA × 配置倍数**，且 **`conversions`** 低于配置上限。
55
55
 
56
56
  目标 CPA：组级从 **`targetCpaAmount`** 与 `google-ads.md` 货币单位说明读取；创意级通常需用 **`adGroupId`** 关联到对应组行再取目标。
package/dist/skill/references/hosted-automation-scenarios.md CHANGED
@@ -5,12 +5,12 @@
5
5
 
6
6
  本主题拆成下面两份子文档，按需打开（本文件只做**入口与导航**）。
7
7
 
8
- | 文档 | 内容 |
9
- |------|------|
10
- | [`hosted-automation-self-control.md`](hosted-automation-self-control.md) | **三类投放自控**：单日预算熔断、CPA 飙升降价、连续空耗暂停；通用约定与常用 JSON 字段表；宿主编排实现清单；与 `forewarning` 的关系 |
8
+ | 文档 | 内容 |
9
+ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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` 等 **`--json` stdout**；**`google-analysis --sections overview` / `campaign-hour` / `final-urls`** 与账户分析口径一致时用 **`--json-out <dir>`** 读落盘 `*.json`；拒审相关键名与命令见该文档 |
12
- | [`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md) | **自动优化（宿主编排）**：差素材降价/关停、高转化扩量、A/B 停输家 — 分文件 SOP（含 `ad list` 按日聚合、`google-analysis --sections campaigns` 等） |
13
- | [`hosted-automation-user-catalog.md`](hosted-automation-user-catalog.md) | **用户向一览**：预算/ROI 自控、异常监控、自动优化表格（可节选给用户；与上表互补） |
12
+ | [`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md) | **自动优化（宿主编排）**：差素材降价/关停、高转化扩量、A/B 停输家 — 分文件 SOP（含 `ad list` 按日聚合、`google-analysis --sections campaigns` 等） |
13
+ | [`hosted-automation-user-catalog.md`](hosted-automation-user-catalog.md) | **用户向一览**：预算/ROI 自控、异常监控、自动优化表格（可节选给用户；与上表互补） |
14
14
 
15
15
  **必读交叉引用**（子文档内会再写一遍）：
16
16
 
package/dist/skill/references/hosted-automation-self-control.md CHANGED
@@ -24,12 +24,12 @@
24
24
 
25
25
  ### 检查项常用 JSON 字段（以当次 `siluzan-tso … --json` 为准）
26
26
 
27
- | 检查意图 | 可关注的 JSON 字段（键名以实际 stdout 为准） |
28
- |----------|---------------------------------------------|
29
- | 周期内费用 | 系列/组/创意列表中的 **`spend`**；报表类子命令中带费用的指标字段 |
30
- | 日预算与费用比 | **`ad campaigns --json`**：`**budget`**（CLI 已为元）与 **`spend`**；比较时须**统一货币与单位**（见 `SKILL.md` 金额硬规范） |
31
- | 转化次数 | **`conversions`**（或报表里等价字段名） |
32
- | 实际 CPA | 宿主侧 **`spend / conversions`**（`conversions` 为 0 时不做 CPA 判断） |
27
+ | 检查意图 | 可关注的 JSON 字段（键名以实际 stdout 为准） |
28
+ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
+ | 周期内费用 | 系列/组/创意列表中的 **`spend`**；报表类子命令中带费用的指标字段 |
30
+ | 日预算与费用比 | **`ad campaigns --json`**：`**budget`**（CLI 已为元）与 **`spend`**；比较时须**统一货币与单位\*\*（见 `SKILL.md` 金额硬规范） |
31
+ | 转化次数 | **`conversions`**（或报表里等价字段名） |
32
+ | 实际 CPA | 宿主侧 **`spend / conversions`**（`conversions` 为 0 时不做 CPA 判断） |
33
33
  | 目标 CPA（系列 / 组） | 系列列表 JSON 中的 **`targetCpa_BidingAmount`** 等；组列表 **`ad groups --json`** 中的 **`targetCpaAmount`**（写入口径见 `google-ads.md`「广告组编辑」） |
34
34
 
35
35
  若某条检查所需字段在**当前** `--json` 中不存在，**禁止猜测**：先换用 `references/account-analytics.md` 中其它子命令拉数，或与维护方确认是否需扩展 `siluzan-tso`；宿主侧不得编造字段。
@@ -76,9 +76,9 @@ siluzan-tso ad campaign-status -a <mediaCustomerId> --id <campaignId> --status E
76
76
 
77
77
  ### CLI 能力摘要
78
78
 
79
- | 状态 | 说明 |
80
- |------|------|
81
- | 有 | 读：`ad campaigns --json`；写：`ad campaign-status`；复核：再次 `ad campaigns --json`。 |
79
+ | 状态 | 说明 |
80
+ | ---- | --------------------------------------------------------------------------------------- |
81
+ | 有 | 读：`ad campaigns --json`；写：`ad campaign-status`；复核：再次 `ad campaigns --json`。 |
82
82
 
83
83
  ---
84
84
 
@@ -131,13 +131,14 @@ siluzan-tso ad adgroup-edit -a <mediaCustomerId> --id <adGroupId> --max-cpc <主
131
131
  ### 写后复核
132
132
 
133
133
  再次 **`ad campaigns --json`** 或 **`ad groups --json`**：
134
+
134
135
  - 优先比对 **`*Display` 字段**（主币种）与预期主币种金额一致；
135
136
  - 整数字段 `targetCpa_BidingAmount` / `targetCpaAmount` / `maxCPCAmount` / `budget` 应等于 `主币种 × 100` 后的整数。
136
137
 
137
138
  ### CLI 能力摘要
138
139
 
139
- | 状态 | 说明 |
140
- |------|------|
140
+ | 状态 | 说明 |
141
+ | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
141
142
  | 已完成 | 系列：`campaign-edit`；组：`adgroup-edit`；检查项依赖宿主时间窗 + 多字段；若某策略字段未在 JSON 出现，须按上文「缺字段勿猜」处理。 |
142
143
 
143
144
  ---
@@ -157,7 +158,7 @@ siluzan-tso ad groups -a <mediaCustomerId> --start <当日> --end <当日> --jso
157
158
 
158
159
  对 `items[]`：读取 **`spend`**（费用）、**`conversions`**；目标 CPA 来自 **`targetCpaAmount`** 与 **`toDisplayMoney` 逆运算** 或宿主配置的「目标 CPA（主币种）」；计算 `limit = target_cpa_main_currency * N`（**N** 为配置）。
159
160
 
160
- - **IF** `conversions === 0` **且** `spend >= limit`（注意 **`spend` 与 limit 单位一致**），则对该 `id` 执行组暂停。
161
+ - **IF** `conversions === 0` **且** `spend >= limit`（注意 **`spend` 与 limit 单位一致**），则对该 `id` 执行组暂停。
161
162
 
162
163
  3. **广告（创意）**级：若策略在创意维熔断：
163
164
 
@@ -192,22 +193,22 @@ siluzan-tso ad groups -a <mediaCustomerId> --start <当日> --end <当日> --jso
192
193
 
193
194
  ### CLI 能力摘要
194
195
 
195
- | 状态 | 说明 |
196
- |------|------|
197
- | 有 | 读：`ad groups` / `ad list`；写：`adgroup-status` / `ad-status`；通知：宿主；复核：再次 list。 |
196
+ | 状态 | 说明 |
197
+ | ---- | ---------------------------------------------------------------------------------------------- |
198
+ | 有 | 读：`ad groups` / `ad list`；写：`adgroup-status` / `ad-status`；通知：宿主；复核：再次 list。 |
198
199
 
199
200
  ---
200
201
 
201
202
  ## 宿主编排实现清单（摘要）
202
203
 
203
- | 步骤 | 说明 |
204
- |------|------|
205
- | 1 | 配置：账户列表、系数、N、X 小时、白名单、是否自动写、通知 |
206
- | 2 | 每轮：`list-accounts` 或固定 `mediaCustomerId` → 拉 `--json` |
207
- | 3 | 宿主内算 IF（本页公式） |
208
- | 4 | 命中则调用写命令（可批量，注意 API 限速） |
209
- | 5 | 每写一条即复核读；失败重试与告警由宿主处理 |
210
- | 6 | 审计日志建议写在宿主侧（CLI 不内置） |
204
+ | 步骤 | 说明 |
205
+ | ---- | ------------------------------------------------------------ |
206
+ | 1 | 配置：账户列表、系数、N、X 小时、白名单、是否自动写、通知 |
207
+ | 2 | 每轮：`list-accounts` 或固定 `mediaCustomerId` → 拉 `--json` |
208
+ | 3 | 宿主内算 IF（本页公式） |
209
+ | 4 | 命中则调用写命令（可批量，注意 API 限速） |
210
+ | 5 | 每写一条即复核读；失败重试与告警由宿主处理 |
211
+ | 6 | 审计日志建议写在宿主侧（CLI 不内置） |
211
212
 
212
213
  ---
213
214
 
package/dist/skill/references/hosted-automation-user-catalog.md CHANGED
@@ -6,11 +6,11 @@
6
6
 
7
7
  三条均为 **Google 宿主编排 + siluzan-tso** 路径；IF/定时/通知在宿主，命令与 JSON 以详规为准。
8
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`） |
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
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 官方名） |
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
14
 
15
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
16
 
@@ -18,23 +18,21 @@
18
18
 
19
19
  编排（定时、HTTP 探活、通知）在宿主；**读哪些 JSON 字段、用什么命令** 以 **[`hosted-automation-monitoring-json.md`](hosted-automation-monitoring-json.md)** 为准（键名以当次 `--json` 为准，勿套用 Google Ads API 官方字段名解析本 CLI 输出）。
20
20
 
21
- | 功能名称 | 监控层级 / 说明 | CLI 检查入口（`--json`） |
22
- | ----------------- | --------------- | ------------------------ |
23
- | 1. 账户被封禁 | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 [`accounts.md`](accounts.md) |
24
- | 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis --sections final-urls`**；或 **`ad list`** / **`google-analysis --sections ads`** 取落地页字段后由宿主 HTTP 校验 |
25
- | 3. 广告素材拒审 | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis --sections ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **[`google-ads.md`](google-ads.md)**） |
26
- | 4. 花费异动监控 | 系列或账户维度花费相对历史异常波动。 | **`google-analysis --sections campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
27
- | 5. 余额枯竭预警 | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis --sections overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
21
+ | 功能名称 | 监控层级 / 说明 | CLI 检查入口（`--json`） |
22
+ | ----------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
23
+ | 1. 账户被封禁 | 账户级；与 Google `CustomerStatus` 及 `list-accounts` 的字段映射**暂不写进本 skill**，由宿主约定。 | `list-accounts`、`balance` 等见 [`accounts.md`](accounts.md) |
24
+ | 2. 落地页死链强停 | URL 不可用或跳错页时暂停关联创意，避免无效消耗。 | **`google-analysis --sections final-urls`**；或 **`ad list`** / **`google-analysis --sections ads`** 取落地页字段后由宿主 HTTP 校验 |
25
+ | 3. 广告素材拒审 | 创意政策状态异常时告警或配合工单。 | **`ad list`** / **`google-analysis --sections ads`**：`policyApprovalStatusV2`、`approvalStatusDetails` 等（见 **[`google-ads.md`](google-ads.md)**） |
26
+ | 4. 花费异动监控 | 系列或账户维度花费相对历史异常波动。 | **`google-analysis --sections campaign-hour`**：按 `campaignId` + `date` + `hour` 看 **`spend`** |
27
+ | 5. 余额枯竭预警 | 余额过低或按日均推算续航不足。 | **`balance-scan`**（`balance`、`remainingDays`、`hitReason`、`meta`）或 **`balance`** / **`google-analysis --sections overview`**（`remainingAccountBudget`、`averageDailyCost` 等） |
28
28
 
29
29
  ## 自动优化
30
30
 
31
31
  编排与阈值在宿主；**命令、JSON 键名、聚合与写后复核** 见 **[`hosted-automation-optimize-index.md`](hosted-automation-optimize-index.md)**（及链出的三份 SOP）。
32
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，沿用分析文档） |
39
-
40
-
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/references/keyword-planner-workflows.md ADDED
@@ -0,0 +1,104 @@
1
+ # 关键词规划师工作流
2
+
3
+ > 拓词、竞品网址拓词、词包清洗、否词、建户关键词结构：**先 Read 本文件**，再按需打开 `references/google-ads.md`（命令参数）与 `references/google-ads-rules/google-ads-keyword-strategy.md`（匹配与分组原则）。
4
+ >
5
+ > **数据口径**：`siluzan-tso keyword` 走网关 `keywordidea/google`（关键字创意/体量与竞价参考），可选 `--url` 叠加站内网址拓词服务；与账户内 **`google-analysis` 投放表现**不是同一套数据，文档与回复中须区分「市场参考」与「账户实际花费/转化」。
6
+
7
+ ---
8
+
9
+ ## 九类场景索引
10
+
11
+ 洗词、分组、否词表、匹配策略等多依赖对 **`--json-out` 落盘 JSON** 的解析或 Agent 归纳；逐步命令见「场景编排」。
12
+
13
+ | # | 场景 | 编排 |
14
+ | - | ---- | ---- |
15
+ | 1 | 竞品网址 + 种子拓词：至少一个 `-k` + `--url`，落盘后去重/排序/截 Top N | §1 |
16
+ | 2 | 多种子长尾：`-k "种子1,种子2,..."` | §2 |
17
+ | 3 | 按规则洗词：月搜索量阈值、排除词根、排除类意图等 | §2（JSON） |
18
+ | 4 | 账户关键词表现 + 市场侧指标：`google-analysis` keywords → 抽词 → 分批 `keyword` | §3 |
19
+ | 5 | 搜索词 + 拓词：浪费流量 / 否词线索 | §4 |
20
+ | 6 | 高商业意图粗筛：CPC、竞争度、搜索量 | §5 |
21
+ | 7 | 否词或否词根落地：`ad keyword-negative-create` 等 | §4 + `google-ads.md` |
22
+ | 8 | Campaign → AdGroup → 关键词与匹配：`ad campaign-create` / `ad keyword-create` 等 | §6 |
23
+ | 9 | 拓词结果导出：`keyword … --json-out`，供脚本消费 | §7 |
24
+
25
+ ---
26
+
27
+ ## 无接口能力（勿过度承诺）
28
+
29
+ | 能力 | CLI 现状 |
30
+ | ---- | -------- |
31
+ | 种子词 / 多种子、可选竞品站 URL、本地 `--include` / `--exclude`、搜索量与 CPC、竞争度 | ✅ `keyword` |
32
+ | 账户内关键词/搜索词表现 + 再对重点词拉市场侧指标 | ✅ 多命令编排（见下） |
33
+ | 词包数值过滤、意图分类、语义 AdGroup、否词清单、匹配策略表 | ✅ **由 AI 消费 `--json-out` 落盘结果后产出**；无单独算法命令 |
34
+ | Google Ads 内「过去 12 个月按月」搜索量趋势曲线 | ❌ **无接口**，勿用本 CLI 假装产出 |
35
+ | Keyword Planner **Forecast**（官方点击/展示/成本预估） | ❌ **无接口**；若用户要官方 Forecast，引导至 Google Ads 界面或接受「仅粗算说明」并标注非 Forecast |
36
+
37
+ ---
38
+
39
+ ## 通用执行规范
40
+
41
+ - **一律**对可复用中间结果使用 `--json-out <目录>`（或等价快照参数），再读 `cli-manifest*.json` / 各 section 的 `*.outline.txt` 了解字段；详见 **`references/tips.md`**。
42
+ - **写账户**（加词、加否词、改系列）须遵守 **`references/google-ads.md`** 开篇流程：先方案与用户确认，再执行写命令；写后用成对读命令复核。
43
+
44
+ ---
45
+
46
+ ## 场景编排
47
+
48
+ ### 1）竞品网址 + 种子拓词
49
+
50
+ 1. 选定至少 **1 个种子词** `-k`（品类、品牌或竞品站上的核心产品词均可）；**不可**仅传 URL。
51
+ 2. ```bash
52
+ siluzan-tso keyword -k "<种子>" --url "<竞品或落地页 URL>" --json-out ./snap-kw
53
+ ```
54
+ 3. 合并去重、按搜索量/CPC/竞争度排序、截断 Top N、写「词包说明」：**由 AI 对落盘 JSON 处理**（CLI 不内置「相关度 Top 200」参数）。
55
+
56
+ ### 2）核心词长尾裂变 + 自定义过滤
57
+
58
+ 1. ```bash
59
+ siluzan-tso keyword -k "种子1,种子2,..." [--include "<须含片段>"] [--exclude "<排除片段>"] --json-out ./snap-kw
60
+ ```
61
+ 2. 月搜索量阈值、排除求职/零售等意图：**对 JSON 中 `montlySearch`（字段名与网关一致）等做程序或 AI 过滤**；`--exclude` 仅做子串级粗滤。
62
+
63
+ ### 3）旧账户关键词 + 叠市场侧 CPC/热度
64
+
65
+ 1. 拉账户表现：
66
+ `siluzan-tso google-analysis -a <mediaCustomerId> --sections keywords --start <S> --end <E> --json-out ./snap-ga`
67
+ 2. 从落盘 JSON 抽取关键词文案（字段路径以该次 **`keywords-*.outline.txt`** 为准）。
68
+ 3. 分批调用（避免单次 body 过大）：
69
+ `siluzan-tso keyword -k "词A,词B,..." --json-out ./snap-kw-batchN`
70
+ 4. 报告中**分栏说明**：左列为账户内指标（花费/转化等），右列为 `keyword` 返回的搜索量/CPC/竞争度（市场参考）。
71
+
72
+ ### 4）搜索词辅助（浪费流量 / 否词线索）
73
+
74
+ 1. `siluzan-tso google-analysis -a <id> --sections search-terms --start <S> --end <E> --json-out ./snap-st`
75
+ 2. 与 `keyword` 拓词结果对照，由 AI 列否词根或精确否词；落地执行：
76
+ `siluzan-tso ad keyword-negative-create …`（见 `references/google-ads.md`）。
77
+
78
+ ### 5）高商业意图粗筛（出价 + 竞争度 + 搜索量）
79
+
80
+ 1. `siluzan-tso keyword … --json-out ./snap-kw`
81
+ 2. 对落盘 `items` 按 `averageCpc`（JSON 内常为微单位；表格 stdout 已换算展示）、`competition` / `competitionV2`、`montlySearch` 综合排序截断；**勿承诺**「页首出价高位」等 CLI 未文档化字段，除非当次 outline 中明确存在。
82
+
83
+ ### 6）Campaign → AdGroup → 关键词 映射表 + 匹配建议
84
+
85
+ 1. 输入为 `keyword`（或合并账户词）的 JSON。
86
+ 2. 结构设计与匹配类型：**遵循** `references/google-ads-rules/google-ads-keyword-strategy.md`；由 AI 输出树形或表格。
87
+ 3. 执行：`ad campaign-create` / `adgroup-create` / `ad keyword-create` 等（**`references/google-ads.md`**，`keywordText` 与 `--match-type` 格式以前者为准）。
88
+
89
+ ### 7）拓词结果标准化导出
90
+
91
+ 1. ```bash
92
+ siluzan-tso keyword -k "..." [--url ...] [--include ...] [--exclude ...] --json-out ./snap-kw
93
+ ```
94
+ 2. 消费顺序：**先**读该目录下 `cli-manifest*.json` 与 **`*.outline.txt`（字段结构）**，**再**用脚本 `require()` 或聚合逻辑读真实数据 JSON；禁止跳过 outline 猜字段。总约定见 **`references/tips.md`**。
95
+
96
+ ---
97
+
98
+ ## 单命令速查
99
+
100
+ ```bash
101
+ siluzan-tso keyword -k "<必填，逗号分隔多词>" [--url <url>] [--include <words>] [--exclude <words>] [--json] [--json-out <dir>] [--verbose]
102
+ ```
103
+
104
+ 与只读账户关键词列表、否词 CRUD 的对照仍归 **`references/google-ads.md`** 中 `ad keywords` / `ad keyword-*` 各节。
package/dist/skill/references/open-account-google-ui.md CHANGED
@@ -1,4 +1,3 @@
1
-
2
1
  ## 一、页面顶部「五步」是什么？
3
2
 
4
3
  与**表单分步**不是同一套数字，但语义连贯：
package/dist/skill/references/reporting.md CHANGED
@@ -214,8 +214,8 @@ siluzan-tso report list -m Google --json
214
214
 
215
215
  # 第二步：查看 webUrl
216
216
  siluzan-tso config show
217
- # webUrl: https://www.siluzan.com
217
+ # webUrl: https://www-ci.siluzan.com
218
218
 
219
219
  # 第三步：拼接链接（Google 日报）
220
- # https://www.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
220
+ # https://www-ci.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
221
221
  ```