siluzan-tso-cli 1.1.57 → 1.1.58-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.
- package/README.md +2 -1
- package/dist/index.js +363 -227
- package/dist/skill/SKILL.md +2 -1
- package/dist/skill/_meta.json +2 -2
- package/dist/skill/references/accounts/accounts-list.md +1 -1
- package/dist/skill/references/accounts/accounts-permissions.md +2 -2
- package/dist/skill/references/accounts/finance.md +1 -1
- package/dist/skill/references/accounts/open-account-by-media.md +1 -1
- package/dist/skill/references/accounts/open-account-google-ui.md +1 -1
- package/dist/skill/references/analytics/rag.md +1 -1
- package/dist/skill/references/analytics/reporting.md +5 -5
- package/dist/skill/references/core/agent-conventions.md +2 -1
- package/dist/skill/references/core/setup.md +5 -5
- package/dist/skill/references/google-ads/google-ads-read.md +8 -8
- package/dist/skill/references/google-ads/google-ads-write.md +48 -36
- package/dist/skill/references/google-ads/google-ads.md +2 -1
- package/dist/skill/references/misc/tso-home.md +2 -2
- package/dist/skill/scripts/install.ps1 +3 -3
- package/dist/skill/scripts/install.sh +3 -3
- package/package.json +1 -1
package/dist/skill/SKILL.md
CHANGED
|
@@ -44,7 +44,8 @@ siluzan-tso -h
|
|
|
44
44
|
- **Google 广告命令名**：列表是 `ad campaigns`（不是 `ad-campaigns` / `campaign list`）；`balance`/`stats` 须带 `-m Google`；单国地域用 `ad geo search … --json-out`（或 `geo resolve`）。
|
|
45
45
|
- **广告搭建媒体边界**：仅 **Google**（`ad`，Search + PMax）与 **Meta**（`meta-ad`，Instant Form 线索）。TikTok / BingV2 / Yandex **不能**创建或改广告结构；用户要搭建时须说明不支持，可改做账户分析（P4）或开户（W2）。**禁止**用 `ad` 冒充 Meta，**禁止**用 `meta-ad` 冒充 Google。
|
|
46
46
|
- **Google 广告类型边界**：CLI/Skill **仅支持** Google **搜索广告（Search）** 与 **Performance Max（PMax）** 的方案、创建与精细管理；**不支持展示广告（Display）**（含自适应展示广告 RDA、独立 Display 系列）。用户要做展示广告时须明确告知不支持，可改推 Search / PMax；**禁止**用 `campaign-create` / `ad-create` 伪装创建 Display。
|
|
47
|
-
- **删系列 / 测试系列须先问（硬性）**：「尽快创建 /
|
|
47
|
+
- **删系列 / 测试系列须先问（硬性）**：「尽快创建 / 按方案搭建」不含删除授权。创建失败（政策违规、名称占用、半成品系列）时**禁止**自行建测试系列逐地域排查、**禁止**自行 `ad campaign-delete`（含 Agent 自建系列）；先报告原因与选项，用户同意后才带 `--i-confirm --commit`。也**禁止**为让创建通过而整类删减方案内容（否词/排除地域/投放国家）：按 `batch get` 的 `failedOperations[]` 只改报错项。见 `google-ads-write.md`「创建失败时禁止的做法」。
|
|
48
|
+
- **本轮试出来的半成品广告直接删（硬性）**：同一轮 `ad ad-create` 为排查拒审留下的短标题或残缺 RSA，正式广告通过后用 `ad ad-delete` 删掉，不要只 `ad-status Paused`。对用户报的条数以随后的 `ad list` 为准。系列和用户原有广告仍须先问。
|
|
48
49
|
- **创建完成后交付（硬性）**：`ad batch diff` 的 stdout 含 `BEGIN_USER_DELIVERY_MARKDOWN`…`END_USER_DELIVERY_MARKDOWN`——**立刻**把中间全文原样发给用户（可先于补建）；禁止只摘要、禁止只说「创建成功/详情已交付/未发现缺失」、禁止等全部补建结束再交付。
|
|
49
50
|
- **报告 render 成功即交付（硬性）**：`google-quarterly render`、`google-analysis render`、`google-ads-diagnosis render`、`website-diagnosis render`、`market-analysis render`，以及 Bing / TikTok / Yandex / Meta 的 `render`，stdout 给出 HTML 路径后**立刻**把该文件交给用户。P10 与各媒体周期报告封面的「季度 / 月度」已按日期写好（其余仍是「周期」或「账户」）。**禁止**再打开、grep 或修改这份 HTML，**禁止**为此再 render。用户没要 PDF 就不要 `html_to_pdf`；要了也只转一次，**禁止**再用 pdftotext、PyMuPDF、截图或视觉模型读 PDF/页面。细则见 `agent-conventions.md` §七。
|
|
50
51
|
- `list-accounts` 无余额/消耗；列全部用 `--page-size 999`。查单户必须 `-k`；`itemCount < total` 时**禁止**判定账户未绑定。
|
package/dist/skill/_meta.json
CHANGED
|
@@ -170,7 +170,7 @@ siluzan-tso account-history --start 2026-03-01 --end 2026-03-31 --json-out ./sna
|
|
|
170
170
|
| 状态 | 含义 | 下一步操作 |
|
|
171
171
|
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
172
172
|
| `Pending` | 审核中 | 等待，可反复运行此命令轮询；审核周期因媒体而异 |
|
|
173
|
-
| `Approved` | 审核通过 | 运行 `list-accounts -m <媒体>` 确认账户已出现；引导用户充值激活（`config show` 取 `webUrl`，按 `finance.md` 打开对应媒体充值页；例如 Google 为 `https://www.siluzan.com/v3/foreign_trade/tso/recharge/pay?mediaType=Google`；Yandex 当前没有对应充值界面） |
|
|
173
|
+
| `Approved` | 审核通过 | 运行 `list-accounts -m <媒体>` 确认账户已出现；引导用户充值激活（`config show` 取 `webUrl`，按 `finance.md` 打开对应媒体充值页；例如 Google 为 `https://www-ci.siluzan.com/v3/foreign_trade/tso/recharge/pay?mediaType=Google`；Yandex 当前没有对应充值界面） |
|
|
174
174
|
| `Rejected` | 被拒 | 查看 `--json-out` 落盘中的 `reason` 字段了解拒绝原因；修改资料后重新提交；若原因不明，引导用户联系丝路赞客服 |
|
|
175
175
|
|
|
176
176
|
---
|
|
@@ -490,7 +490,7 @@ siluzan-tso account email-deauth -c <mediaCustomerId> --invitation-id <id> --res
|
|
|
490
490
|
|
|
491
491
|
| 功能 | 媒体 | 网页路径 |
|
|
492
492
|
| --------------------------------------- | ------ | ------------------------------------------------- |
|
|
493
|
-
| **账户激活**（邀请他人激活 / 充值激活） | Google | `https://www.siluzan.com/v3/foreign_trade/tso/manageAccounts` |
|
|
493
|
+
| **账户激活**（邀请他人激活 / 充值激活） | Google | `https://www-ci.siluzan.com/v3/foreign_trade/tso/manageAccounts` |
|
|
494
494
|
|
|
495
495
|
**Agent 建议话术**：
|
|
496
496
|
|
|
@@ -499,5 +499,5 @@ siluzan-tso account email-deauth -c <mediaCustomerId> --invitation-id <id> --res
|
|
|
499
499
|
siluzan-tso config show # 查看 webUrl 字段
|
|
500
500
|
|
|
501
501
|
# 账户激活（Google）→ 引导至账户管理页
|
|
502
|
-
# https://www.siluzan.com/v3/foreign_trade/tso/manageAccounts
|
|
502
|
+
# https://www-ci.siluzan.com/v3/foreign_trade/tso/manageAccounts
|
|
503
503
|
```
|
|
@@ -126,7 +126,7 @@ siluzan-tso config show
|
|
|
126
126
|
|
|
127
127
|
### 充值页链接（按媒体 × 类型）
|
|
128
128
|
|
|
129
|
-
链接模式：`https://www.siluzan.com/v3/foreign_trade/tso/recharge/<page>?mediaType=<mediaType>`；丝路赞钱包：`https://www.siluzan.com/v3/foreign_trade/tso/recharge/siluzanWallet`（无媒体参数）。
|
|
129
|
+
链接模式：`https://www-ci.siluzan.com/v3/foreign_trade/tso/recharge/<page>?mediaType=<mediaType>`；丝路赞钱包：`https://www-ci.siluzan.com/v3/foreign_trade/tso/recharge/siluzanWallet`（无媒体参数）。
|
|
130
130
|
|
|
131
131
|
| 充值类型 | `<page>` | 支持媒体（`mediaType` 参数） |
|
|
132
132
|
| ------------------------- | --------------------- | ------------------------------------------- |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 各媒体开户
|
|
2
2
|
|
|
3
|
-
> 网页链接：`https://www.siluzan.com/v3/foreign_trade/tso/accountOpeningHistory?tso=%2Fv3umijs%2Ftso%2FaccountOpeningHistory`
|
|
3
|
+
> 网页链接：`https://www-ci.siluzan.com/v3/foreign_trade/tso/accountOpeningHistory?tso=%2Fv3umijs%2Ftso%2FaccountOpeningHistory`
|
|
4
4
|
> 多命令串联见 `references/core/workflows.md` § 流程一。
|
|
5
5
|
|
|
6
6
|
## Contents
|
|
@@ -65,7 +65,7 @@ siluzan-tso open-account google-wizard
|
|
|
65
65
|
|
|
66
66
|
```bash
|
|
67
67
|
siluzan-tso account-history -m Google
|
|
68
|
-
# 审核通过后：config show → https://www.siluzan.com/v3/foreign_trade/tso/recharge/pay?mediaType=Google
|
|
68
|
+
# 审核通过后：config show → https://www-ci.siluzan.com/v3/foreign_trade/tso/recharge/pay?mediaType=Google
|
|
69
69
|
```
|
|
70
70
|
|
|
71
71
|
---
|
|
@@ -190,9 +190,9 @@ siluzan-tso report push receive-emails -m Google [--json-out ./snap]
|
|
|
190
190
|
|
|
191
191
|
| 媒体 | 报告类型 | URL 模板 |
|
|
192
192
|
| ------ | ---------------- | ----------------------------------------------------------- |
|
|
193
|
-
| Google | 日报（Daily） | `https://www.siluzan.com/media-report/publish/{entityId}?culture=zh-CN` |
|
|
194
|
-
| Google | 小时报（Hourly） | `https://www.siluzan.com/media-report/hour/{entityId}?culture=zh-CN` |
|
|
195
|
-
| TikTok | 日报 | `https://www.siluzan.com/media-report/publish/{entityId}?culture=zh-CN` |
|
|
193
|
+
| Google | 日报（Daily） | `https://www-ci.siluzan.com/media-report/publish/{entityId}?culture=zh-CN` |
|
|
194
|
+
| Google | 小时报（Hourly） | `https://www-ci.siluzan.com/media-report/hour/{entityId}?culture=zh-CN` |
|
|
195
|
+
| TikTok | 日报 | `https://www-ci.siluzan.com/media-report/publish/{entityId}?culture=zh-CN` |
|
|
196
196
|
|
|
197
197
|
`entityId` 来自 `siluzan-tso report list --json-out ./snap` 中每条记录的 `entityId` 字段。
|
|
198
198
|
|
|
@@ -205,8 +205,8 @@ siluzan-tso report list -m Google --json-out ./snap
|
|
|
205
205
|
|
|
206
206
|
# 第二步：查看 webUrl
|
|
207
207
|
siluzan-tso config show
|
|
208
|
-
# webUrl: https://www.siluzan.com
|
|
208
|
+
# webUrl: https://www-ci.siluzan.com
|
|
209
209
|
|
|
210
210
|
# 第三步：拼接链接（Google 日报）
|
|
211
|
-
# https://www.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
|
|
211
|
+
# https://www-ci.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
|
|
212
212
|
```
|
|
@@ -145,7 +145,8 @@
|
|
|
145
145
|
- **破坏性操作必须确认 + `--commit`**：账户解绑/关闭/取消分享、BC/MCC 解绑、删除预警/报告/广告/关键词、发票申请、广告发布等。
|
|
146
146
|
- **CLI 硬门控**：`account delink` / `unshare` / `reauth` / `mcc-unbind` / `bc-unbind`、`ad campaign-delete`、`ad pmax-edit --status Removed` **缺少 `--i-confirm` 会直接失败**（不会发网关）。`--commit` 只是审计说明，**不能替代**用户确认。
|
|
147
147
|
- **Agent**：先说明风险与将执行的命令 → **等待用户明确同意** → 才附加 `--i-confirm --commit "…"` 执行。用户说「别问我 / 直接做」也**不得**跳过确认；**禁止**未获同意就自行加 `--i-confirm`。
|
|
148
|
-
- **授权范围不外推**：「尽快创建 / 按方案搭建」只授权创建，**不**授权删除系列、建测试系列或在账户里做实验。创建失败时禁止为排查或清理而自行 `campaign-create` 测试系列 / `campaign-delete`（含 Agent
|
|
148
|
+
- **授权范围不外推**：「尽快创建 / 按方案搭建」只授权创建，**不**授权删除系列、建测试系列或在账户里做实验。创建失败时禁止为排查或清理而自行 `campaign-create` 测试系列 / `campaign-delete`（含 Agent 自建、半成品系列、占名系列）；停下报告原因与选项，等用户选。细则见 `google-ads-write.md`「创建失败时禁止的做法」。
|
|
149
|
+
- **例外——本轮试探广告**：同一轮自己用 `ad ad-create` 试出来的短标题或残缺 RSA，正式广告通过后直接 `ad ad-delete` 删掉，不要改成暂停留在组里。汇报条数前再跑一次 `ad list`，按列表实数写。这不包含删系列、删用户原有广告。
|
|
149
150
|
- **写操作结束后必须向用户交付成败报告**（修改 / 创建 / 删除 / 绑定 / 分享 / 开户提交 / 预警变更等凡改变远端状态的命令）：
|
|
150
151
|
- 用**业务语言**说明：结论（全成功 / 部分失败 / 全失败）→ **成功了哪些**（对象名或 ID）→ **失败了哪些**（对象 + 原因，来自当次 CLI stderr / `reason` / `errors` / 读命令复核）→ 如需用户动作再给 1 句下一步。
|
|
151
152
|
- 批量或可部分失败时（多账户 MCC/BC、关户、批量关键词等）：**逐项**列清，禁止只说「已处理」。
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
## 安装 CLI
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
|
-
npm install -g siluzan-tso-cli
|
|
13
|
+
npm install -g siluzan-tso-cli@beta
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
---
|
|
@@ -64,7 +64,7 @@ siluzan-tso config set --api-key <Key> # 或 config 直接写入
|
|
|
64
64
|
siluzan-tso config set --token <Token> # 备用：设置 JWT Token
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
API Key 获取入口：`https://www.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
|
|
67
|
+
API Key 获取入口：`https://www-ci.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
|
|
68
68
|
|
|
69
69
|
```bash
|
|
70
70
|
# 第 1 步：让用户报出手机号后，立刻发码（命令立即返回，不会等待输入）
|
|
@@ -127,9 +127,9 @@ siluzan-tso config show
|
|
|
127
127
|
|
|
128
128
|
```
|
|
129
129
|
构建环境 : production
|
|
130
|
-
apiBaseUrl : https://tso-api.siluzan.com
|
|
131
|
-
googleApiUrl : https://googleapi.mysiluzan.com
|
|
132
|
-
webUrl : https://www.siluzan.com
|
|
130
|
+
apiBaseUrl : https://tso-api-ci.siluzan.com
|
|
131
|
+
googleApiUrl : https://googleapi-ci.mysiluzan.com
|
|
132
|
+
webUrl : https://www-ci.siluzan.com
|
|
133
133
|
apiKey : abcd****1234
|
|
134
134
|
```
|
|
135
135
|
|
|
@@ -111,7 +111,7 @@ siluzan-tso ad adgroup-status -a <accountId> --id <adGroupId> --status <Enabled|
|
|
|
111
111
|
|
|
112
112
|
### 编辑
|
|
113
113
|
|
|
114
|
-
先用 `ad groups --json-out ./snap`
|
|
114
|
+
先用 `ad groups --json-out ./snap` 查看当前值。编辑和启停走字段级 PATCH，只写本次传入的字段，不必把列表里的整行再送回去。
|
|
115
115
|
|
|
116
116
|
```bash
|
|
117
117
|
siluzan-tso ad adgroup-edit \
|
|
@@ -120,7 +120,7 @@ siluzan-tso ad adgroup-edit \
|
|
|
120
120
|
[--start/--end <YYYY-MM-DD>]
|
|
121
121
|
```
|
|
122
122
|
|
|
123
|
-
`--max-cpc` / `--target-cpa` 与 `ad groups --json-out ./snap` 中 `maxCPCAmountYuan` / `targetCpaAmountYuan` 对齐（**元**，CLI
|
|
123
|
+
`--max-cpc` / `--target-cpa` 与 `ad groups --json-out ./snap` 中 `maxCPCAmountYuan` / `targetCpaAmountYuan` 对齐（**元**，CLI 出口已统一）。列表里的 `0` 多半是未设置。`--target-cpa 0` 会照写，Google 常回 `Too low`，这个 PATCH 也不能把组级目标 CPA 清回未设置。
|
|
124
124
|
|
|
125
125
|
### 删除
|
|
126
126
|
|
|
@@ -295,12 +295,12 @@ siluzan-tso ad geo remove -a <accountId> --campaign-id <id> --location-id <id>
|
|
|
295
295
|
|
|
296
296
|
每行 `status`（search 为 `pickStatus`）的取值和处理方式：
|
|
297
297
|
|
|
298
|
-
| status | 含义
|
|
299
|
-
| -------------- |
|
|
300
|
-
| `ok` | 唯一精确命中，已写入 `targetedLocations`
|
|
301
|
-
| `needs_review` | 有候选，但没有精确同名（如只搜到城市/省份）
|
|
302
|
-
| `unserved` | Google Ads 不支持投放的地区（伊朗、古巴、朝鲜、克里米亚等）
|
|
303
|
-
| `not_found` | 网关无候选
|
|
298
|
+
| status | 含义 | 处理 |
|
|
299
|
+
| -------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
300
|
+
| `ok` | 唯一精确命中，已写入 `targetedLocations` | 直接用 |
|
|
301
|
+
| `needs_review` | 有候选，但没有精确同名（如只搜到城市/省份） | 看 `topCandidates`（前 5 个），**问用户**选哪个或换英文写法；禁止自行挑第一个 |
|
|
302
|
+
| `unserved` | Google Ads 不支持投放的地区（伊朗、古巴、朝鲜、克里米亚等） | 从方案中去掉，并告诉用户原因；不要找替代 id |
|
|
303
|
+
| `not_found` | 网关无候选 | 换英文官方名再试，仍无则问用户 |
|
|
304
304
|
|
|
305
305
|
落盘汇总里的 `unserved[]`、`needsReview[]`、`failed[]` 必须在创建前逐项向用户说明。`failed` 不包含 `unserved`。
|
|
306
306
|
|
|
@@ -81,21 +81,21 @@
|
|
|
81
81
|
|
|
82
82
|
### 已上线 PMax 管理（CLI）
|
|
83
83
|
|
|
84
|
-
| 能力 | 命令
|
|
85
|
-
| ---------------- |
|
|
86
|
-
| 详情 | `ad pmax-get -a <id> --campaign-id <cid>`（读 `_brandGuidelinesActive`）
|
|
87
|
-
| 改活动 | `ad pmax-edit`（`--patch-file` 或 `--status` / `--budget` + `--budget-id`；改 `Removed` 须用户同意 + `--i-confirm`）
|
|
88
|
-
| 改 Campaign 品牌 | `ad pmax-brand-assets-edit`（BG 已开启）
|
|
89
|
-
| 启用 BG | `ad pmax-brand-guidelines-enable --config-file …`（存量活动）
|
|
90
|
-
| 新资产组 | `ad pmax-asset-group-create --config-file …`（BG 下自动省略品牌）
|
|
91
|
-
| 改资产组 | `ad pmax-asset-group-edit`
|
|
92
|
-
| 删资产组 | `ad pmax-asset-group-edit --status REMOVED`（软删；网关无 DELETE 端点）
|
|
93
|
-
| 改资产 | `ad pmax-assets-update --config-file …`
|
|
94
|
-
| YouTube 追加 | `ad pmax-youtube-link`（单条 `--youtube` / `--video-path`）；批量见 `ad pmax-assets-update`
|
|
95
|
-
| 信号 | `ad pmax-signals-get` / `ad pmax-signals-set`；受众下拉 `ad pmax-audiences`
|
|
96
|
-
| 附加资产 | `ad extension pmax-types`；`callout` / `snippet` / `lead-form` / `whatsapp`（见 `pmax-api.md` § 附加资产）
|
|
97
|
-
| 图片库 | `ad pmax-image-upload`
|
|
98
|
-
| 报表 | `ad pmax-report-asset-groups` / `ad pmax-report-geo`
|
|
84
|
+
| 能力 | 命令 |
|
|
85
|
+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
86
|
+
| 详情 | `ad pmax-get -a <id> --campaign-id <cid>`（读 `_brandGuidelinesActive`） |
|
|
87
|
+
| 改活动 | `ad pmax-edit`（`--patch-file` 或 `--status` / `--budget` + `--budget-id`；改 `Removed` 须用户同意 + `--i-confirm`） |
|
|
88
|
+
| 改 Campaign 品牌 | `ad pmax-brand-assets-edit`（BG 已开启） |
|
|
89
|
+
| 启用 BG | `ad pmax-brand-guidelines-enable --config-file …`（存量活动） |
|
|
90
|
+
| 新资产组 | `ad pmax-asset-group-create --config-file …`（BG 下自动省略品牌） |
|
|
91
|
+
| 改资产组 | `ad pmax-asset-group-edit` |
|
|
92
|
+
| 删资产组 | `ad pmax-asset-group-edit --status REMOVED`（软删；网关无 DELETE 端点） |
|
|
93
|
+
| 改资产 | `ad pmax-assets-update --config-file …` |
|
|
94
|
+
| YouTube 追加 | `ad pmax-youtube-link`（单条 `--youtube` / `--video-path`）；批量见 `ad pmax-assets-update` |
|
|
95
|
+
| 信号 | `ad pmax-signals-get` / `ad pmax-signals-set`；受众下拉 `ad pmax-audiences` |
|
|
96
|
+
| 附加资产 | `ad extension pmax-types`；`callout` / `snippet` / `lead-form` / `whatsapp`（见 `pmax-api.md` § 附加资产） |
|
|
97
|
+
| 图片库 | `ad pmax-image-upload` |
|
|
98
|
+
| 报表 | `ad pmax-report-asset-groups` / `ad pmax-report-geo` |
|
|
99
99
|
| 删活动 | 用户同意后 `ad campaign-delete -a <id> --id <campaignId> --i-confirm --commit "…"`（与 Search 共用；勿用 `ad campaign-edit`） |
|
|
100
100
|
|
|
101
101
|
模板与 HTTP 对照：`references/google-ads/pmax-api.md`。
|
|
@@ -260,7 +260,11 @@ siluzan-tso ad campaign-edit -a <accountId> --id <campaignId> \
|
|
|
260
260
|
|
|
261
261
|
相对运算：先 `ad campaigns --json-out ./snap` 读 `budget`（已为主币种元）、`biddingStrategyTypeV2`，再传入。
|
|
262
262
|
|
|
263
|
-
`campaign-edit`
|
|
263
|
+
`campaign-edit` 的名称、预算、出价，以及 `campaign-status`，走字段级 PATCH（`writeScope=search-field-patch`）。请求只带本次传入的字段，没传的字段保持原样。金额仍是主币种元，CLI ×100 写入网关「分」。`budgetShared=true` 时本命令直接拒绝 `--budget`，不会改共享预算。PMax 不要用本命令。
|
|
264
|
+
|
|
265
|
+
写完会再 GET：`verification=verified` 才表示对上了本次字段；没改预算但回读预算变了则是 `partial`；读不到是 `unknown`（再查 `ad campaigns`，不要当成没改成，也不要立刻重发）。请求失败时会再 GET 一次预算：金额相对提交前变了是 `partial`（退出码 0），读不到或无法对比是 `unknown`（退出码 0），都不要立刻重发；金额没变才是失败（退出码 1）。
|
|
266
|
+
|
|
267
|
+
`--search-network` / `--content-network` 不在字段级 PATCH 里。只在传入这两项时，CLI 会在 PATCH 之后再 GET 一次并整包 PUT 投放网络。不要用它们顺手改其它字段。
|
|
264
268
|
|
|
265
269
|
> PMax / 部分智能系列类型 Google 可能拒绝切换出价策略；以 API 返回错误为准。已上线 PMax 用 `ad pmax-edit`，不要用本命令。
|
|
266
270
|
|
|
@@ -298,20 +302,28 @@ siluzan-tso ad ad-create \
|
|
|
298
302
|
|
|
299
303
|
创建后暂停：`ad ad-status -a <accountId> --id <adId> --status Paused --commit "创建后暂停"`。若列表找不到新广告，给 `ad-status` / `ad list` 加宽 `--start`/`--end`。
|
|
300
304
|
|
|
305
|
+
**拒审试探留下的半成品**：同一轮里为定位哪句文案被拒而 `ad ad-create` 出来的短标题或残缺 RSA，正式那条通过后立刻删掉：
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
siluzan-tso ad ad-delete -a <accountId> --id <adId>
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
不要改成 `ad-status Paused` 留在组里。删完再 `ad list`，对用户报的条数用这次列表，不要按「每组 1 条」心算。只删本轮自己建的试探广告；删系列、删用户原有广告仍先问。
|
|
312
|
+
|
|
301
313
|
文案合规见 `rules/google-ads-compliance-copy.md`。
|
|
302
314
|
|
|
303
315
|
---
|
|
304
316
|
|
|
305
317
|
## ad ad-edit — 广告创意编辑
|
|
306
318
|
|
|
307
|
-
|
|
319
|
+
字段级 PATCH，只写本次传入的字段。标题、描述、最终网址、路径只适用于响应式搜索广告；只改 `--status` 时其它广告类型也可以。`--path1` / `--path2` 传空字符串会清空该段路径。
|
|
308
320
|
|
|
309
|
-
`ad list --json-out ./snap`
|
|
321
|
+
`ad list --json-out ./snap` 用来读当前文案，不必把未改字段再传回去：
|
|
310
322
|
|
|
311
|
-
- `headlinePart1~3` + `AddtionalHeadlines` → `--headlines`（≥3
|
|
312
|
-
- `adDescription`/`adDescription2` + `AddtionalAdDescriptions` → `--descriptions`（≥2
|
|
323
|
+
- `headlinePart1~3` + `AddtionalHeadlines` → `--headlines`（≥3条，整表替换）
|
|
324
|
+
- `adDescription`/`adDescription2` + `AddtionalAdDescriptions` → `--descriptions`（≥2条，整表替换）
|
|
313
325
|
- `finalUrl` → `--final-url`；`path1`/`path2` → `--path1`/`--path2`
|
|
314
|
-
- `statusV2` → `--status
|
|
326
|
+
- `statusV2` → `--status`
|
|
315
327
|
|
|
316
328
|
```bash
|
|
317
329
|
siluzan-tso ad ad-edit \
|
|
@@ -338,7 +350,7 @@ siluzan-tso ad keyword-delete -a <accountId> --id <keywordId> --adgroup-id <adGr
|
|
|
338
350
|
|
|
339
351
|
## ad keyword-edit — 搜索关键词编辑
|
|
340
352
|
|
|
341
|
-
|
|
353
|
+
只改 `--final-url` / `--max-cpc` / `--status` 时走字段级 PATCH，原地更新，`id` 与历史数据保留。`--final-url` 传空会清空关键词网址，回到广告自己的网址。改 `--text` / `--match-type`（Google 侧词面与匹配类型不可变）仍走批量 PUT，会新建并删除旧词，`id` 变化时 CLI 会提示。改 `--final-url` / `--max-cpc` / `--status` 后 CLI 会重新拉列表回读实际值，只有回读一致才输出 ✅；未生效或回读失败则报错退出。此时**禁止**自行改用 `keyword-delete` + `keyword-create`，也禁止直调网关删除重建（会丢失 id 与历史数据），哪怕只改一条也不行。应停下来告知用户「平台未生效、需反馈平台」，可另给 Google Ads Editor 导入清单作为替代方案。
|
|
342
354
|
|
|
343
355
|
```bash
|
|
344
356
|
siluzan-tso ad keyword-edit \
|
|
@@ -347,13 +359,13 @@ siluzan-tso ad keyword-edit \
|
|
|
347
359
|
[--max-cpc <n>] [--final-url <url>] [--status Enabled|Paused]
|
|
348
360
|
```
|
|
349
361
|
|
|
350
|
-
传 `--match-type` 时 CLI 自动规范 `keywordText` 括号/引号格式。至少传一项。`--max-cpc` 为主币种元（CLI ×100 写入 `
|
|
362
|
+
传 `--match-type` 时 CLI 自动规范 `keywordText` 括号/引号格式。至少传一项。`--max-cpc` 为主币种元（CLI ×100 写入 `maxCpc`「分」字段，与 `adgroup-edit --max-cpc` 同口径）。`ad keywords --json-out ./snap` 出价见 `maxCPCYuan`。列表里的 `0` 多半是未设置；`--max-cpc 0` 会照写，Google 常回 `Too low`，不能用来清空关键词出价。`--status` 写入 `userStatus`（关键词级开关，非系列的 `status`）。
|
|
351
363
|
|
|
352
364
|
---
|
|
353
365
|
|
|
354
366
|
## ad keyword-status — 搜索关键词状态切换
|
|
355
367
|
|
|
356
|
-
|
|
368
|
+
仅改关键词状态，字段级 PATCH `userStatus`。与 `ad adgroup-status` 用法对称。
|
|
357
369
|
|
|
358
370
|
```bash
|
|
359
371
|
siluzan-tso ad keyword-status -a <accountId> --id <keywordId> --status <Enabled|Paused>
|
|
@@ -454,22 +466,22 @@ siluzan-tso ad extension delete -a <accountId> --id <extensionId>
|
|
|
454
466
|
|
|
455
467
|
**`--bid-modifier` 口径（系列级直接透传 Google 倍率）**
|
|
456
468
|
|
|
457
|
-
| 倍率 | 含义
|
|
458
|
-
| ----- |
|
|
459
|
-
| `1.0` | 不调整
|
|
460
|
-
| `0.8` | 降低 20%
|
|
461
|
-
| `1.2` | 提高 20%
|
|
469
|
+
| 倍率 | 含义 |
|
|
470
|
+
| ----- | ----------------------------------------------------------------------------------------------------------- |
|
|
471
|
+
| `1.0` | 不调整 |
|
|
472
|
+
| `0.8` | 降低 20% |
|
|
473
|
+
| `1.2` | 提高 20% |
|
|
462
474
|
| `0` | **写入**时排除该设备（-100%）。**列表**里网关常把「未设置」也填成 `0`，此时 Google 后台显示 `—`，不是 -100% |
|
|
463
475
|
|
|
464
476
|
**展示口径（与 Google Ads 后台「出价调整」列一致）**：`list` / `google-analysis --sections campaign-device` 已输出 `bidModifierDisplay`。写表格必须用这个字段，禁止把倍率当正百分比（不要把 `0.6` 写成 `40%`）。
|
|
465
477
|
|
|
466
|
-
| `bidModifier`
|
|
467
|
-
|
|
|
468
|
-
| `0`（未设置）
|
|
469
|
-
| `0`（明确排除） | `true`
|
|
470
|
-
| `1.0`
|
|
471
|
-
| `0.6`
|
|
472
|
-
| `1.1`
|
|
478
|
+
| `bidModifier` | `bidModifierSpecified` | `bidModifierDisplay` |
|
|
479
|
+
| --------------- | ---------------------- | -------------------- |
|
|
480
|
+
| `0`（未设置） | 空 / `false` | `—` |
|
|
481
|
+
| `0`（明确排除） | `true` | `-100%` |
|
|
482
|
+
| `1.0` | — | `0%` |
|
|
483
|
+
| `0.6` | — | `-40%` |
|
|
484
|
+
| `1.1` | — | `+10%` |
|
|
473
485
|
|
|
474
486
|
**系列级列表的限制**：系列级接口只返回 `bid_modifier`，不带 `bidModifierSpecified`，所以「未设置」和「已排除（-100%）」都显示为 `0`。CLI 对这类行输出 `bidModifierDisplay = "— 或 -100%（网关不区分…）"` 和 `unsetOrExcluded: true`。遇到时不要断言是哪一种：对用户说明需要到 Google Ads 后台确认。要在建系列时就确定排除某设备，在 `campaign-create` JSON 的 `targetedPlatforms` 里写 `{ "id": 30002, "bidModifier": -100 }`（见 `campaign-create-template.md`）。
|
|
475
487
|
|
|
@@ -30,13 +30,14 @@ Meta / Facebook 线索广告走 **`meta-ad`（W13）**，**禁止**用本命令
|
|
|
30
30
|
## Gotchas
|
|
31
31
|
|
|
32
32
|
- **广告类型**：仅 Search + PMax；**不支持 Display**（见上文「支持的广告类型」）。
|
|
33
|
+
- **Search 改字段**：`campaign-status`、`campaign-edit` 的名称/预算/出价、`adgroup-status` / `adgroup-rename` / `adgroup-edit`、`keyword-status`、`keyword-edit` 的状态/出价/网址、`ad-status` / `ad-edit` 都是字段级 PATCH，只写本次参数。词面和匹配类型仍是批量 PUT。`--search-network` / `--content-network` 仍是整包 PUT。PMax 用 `pmax-edit`，不要用 `campaign-edit`。
|
|
33
34
|
- **命令名**：系列列表是 `ad campaigns`（别名 `campaign-list`），**禁止** `ad-campaigns` / `campaign list`。`balance`/`stats` 须 `-m Google`。
|
|
34
35
|
- **Google 客户 ID（CID）带连字符**：UI / 用户口述常为 `123-456-7890`，平台 `mediaCustomerId` 与 Google 网关路径需要 `1234567890`。`ad campaigns` / `ad groups` / `ad list` 等 `-a` 与 JSON 顶层 `account` **可带连字符**（CLI 自动去掉）。若错误为 `HTTP 403：123-456-7890`（回显带横杠），先换纯数字重试，**禁止**据此直接判断 OAuth 过期或 `reauth`。
|
|
35
36
|
- **禁止臆测授权过期**：`ad *` / geo / 拉数出现 403/500 时，**禁止**对用户说「授权可能过期」。须核验 ID 后执行 `account check-access -a <mediaCustomerId>`，仅当 `reauth_required`（或与 `invalidOAuthToken=true` 交叉确认）才走重授权；无激活字段时禁止谈套餐。见 [`accounts-permissions.md`](../accounts/accounts-permissions.md)。
|
|
36
37
|
- **预算投放**：`BudgetBudgetDeliveryMethodV2` 默认用 `STANDARD`；`ACCELERATED` 多数账户会被 Google 拒（validate 警告）。
|
|
37
38
|
- **STRUCTURED_SNIPPET**：`StructuredSnippetHeaderValue.Key` 须为合法英文标头（`ad extension snippet-headers`）；`Features` 等非法值 validate 会拦（建议 `Amenities`）。
|
|
38
39
|
- **batch get**：读 `agentWorkflow`——无 `campaignId` 的 Failed/HasFailed **禁止**跑 `batch diff`，按 `agentHint` 改 JSON 重提。
|
|
39
|
-
-
|
|
40
|
+
- **创建失败不删系列、不试系列**：政策违规、名称占用、半成品系列残留时，**禁止**自行建测试系列逐地域排查或 `campaign-delete`；先报告并等用户选（见 [`google-ads-write.md`](google-ads-write.md)「创建失败时禁止的做法」）。删系列须用户同意 + `--i-confirm`。本轮 `ad ad-create` 试出来的残缺 RSA 用 `ad ad-delete` 清掉，不要只暂停。
|
|
40
41
|
- **失败只改报错项**：`batch get` 带 `--config-file` 时 `agentWorkflow.failedOperations[]` 把 `mutate_operations[N]` 映射到 JSON 路径；只改这些项，**禁止**整类清空否词/排除地域/投放国家后重提（见 [`rules/google-ads-plan-source-fidelity.md`](rules/google-ads-plan-source-fidelity.md)「创建失败后」）。
|
|
41
42
|
- **batch diff 交付**：把 stdout 中 `BEGIN_USER_DELIVERY_MARKDOWN`…`END`（或 `reportMarkdownFile`）**全文以 Markdown 发给用户**（先于补建）；**禁止**只说「未发现缺失 / 详情已交付」。
|
|
42
43
|
- `-a` 必须是 `list-accounts -m Google` 的 `ma.mediaCustomerId`，**禁止**传 `entityId`（UUID）。
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
siluzan-tso config show # 取 webUrl
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
首页地址：`https://www.siluzan.com/v3/foreign_trade/tso/home`
|
|
9
|
+
首页地址：`https://www-ci.siluzan.com/v3/foreign_trade/tso/home`
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
@@ -25,7 +25,7 @@ siluzan-tso config show # 取 webUrl
|
|
|
25
25
|
|
|
26
26
|
## 推荐话术
|
|
27
27
|
|
|
28
|
-
1. **「和首页一样的总览」** → 打开 `https://www.siluzan.com/v3/foreign_trade/tso/home`。
|
|
28
|
+
1. **「和首页一样的总览」** → 打开 `https://www-ci.siluzan.com/v3/foreign_trade/tso/home`。
|
|
29
29
|
2. **「某个 Google 账户昨天花了多少」** → `list-accounts -m Google` + `stats -m Google -a <id>`。
|
|
30
30
|
3. **「有待充值账户」** → 说明聚合数据在首页；CLI 可 `list-accounts` + `balance` 逐户排查，或引导充值页。
|
|
31
31
|
|
|
@@ -9,11 +9,11 @@ $ErrorActionPreference = 'Stop'
|
|
|
9
9
|
# -- Package info (injected at build time) ------------------------------------
|
|
10
10
|
$PKG_NAME = 'siluzan-tso-cli'
|
|
11
11
|
# PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
|
|
12
|
-
$PKG_VERSION = '1.1.
|
|
12
|
+
$PKG_VERSION = '1.1.58-beta.2'
|
|
13
13
|
$CLI_BIN = 'siluzan-tso'
|
|
14
14
|
$SKILL_LABEL = 'Siluzan TSO'
|
|
15
|
-
$INSTALL_CMD = 'npm install -g siluzan-tso-cli'
|
|
16
|
-
$WEB_BASE = 'https://www.siluzan.com'
|
|
15
|
+
$INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'
|
|
16
|
+
$WEB_BASE = 'https://www-ci.siluzan.com'
|
|
17
17
|
|
|
18
18
|
# -- Constants ----------------------------------------------------------------
|
|
19
19
|
$NODE_MAJOR_MIN = 18
|
|
@@ -9,11 +9,11 @@ set -euo pipefail
|
|
|
9
9
|
# -- Package info (injected at build time) ------------------------------------
|
|
10
10
|
readonly PKG_NAME="siluzan-tso-cli"
|
|
11
11
|
# PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
|
|
12
|
-
readonly PKG_VERSION="1.1.
|
|
12
|
+
readonly PKG_VERSION="1.1.58-beta.2"
|
|
13
13
|
readonly CLI_BIN="siluzan-tso"
|
|
14
14
|
readonly SKILL_LABEL="Siluzan TSO"
|
|
15
|
-
readonly INSTALL_CMD="npm install -g siluzan-tso-cli"
|
|
16
|
-
readonly WEB_BASE="https://www.siluzan.com"
|
|
15
|
+
readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"
|
|
16
|
+
readonly WEB_BASE="https://www-ci.siluzan.com"
|
|
17
17
|
|
|
18
18
|
# -- Constants ----------------------------------------------------------------
|
|
19
19
|
readonly NODE_MAJOR_MIN=18
|