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
@@ -4,90 +4,17 @@
4
4
 
5
5
  ---
6
6
 
7
- ## 新建广告系列的流程
8
-
9
- > **强制流程总览(AI 必须严格遵守)**
10
- > 1)先完整阅读所有规则文档 → 2)向用户补齐关键信息提问 → 3)在规则约束下设计广告计划 → 4)按模板输出方案并获得用户「明确确认」 → 5)**仅在已确认的前提下**执行任何结构性改动。
11
-
12
- ### 第一步:规则文档阅读(不得跳过)
13
-
14
- 操作开始前,**AI 必须先阅读完下面所有文档**,并在心智模型中内化规则后,才能进入任何「方案规划 / 广告创建 / 调整」步骤,严禁只读 `google-ads-launch-plan-template.md` 就直接出方案。
15
-
16
- | 文档地址 | 文档内容 |
17
- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
- | `references/google-ads-rules/google-ads-compliance.md` | **Google 广告合规指南**:关键词 & 文案审核通过规则、编辑规范、禁止内容、虚假承诺处理、商标规则、多语言规则 |
19
- | `references/google-ads-rules/sensitive-industries.md` | **敏感行业合规细则**:酒精 / 赌博 / 金融 / 加密 / 医疗 / 法律等 15 个行业的关键词生成规则与地区限制 |
20
- | `references/google-ads-rules/google-ads-keyword-strategy.md` | **关键词策略与优化技巧**:匹配类型策略、分组结构、否定词技巧、出价意图分层、搜索词挖掘、竞品策略、PMax/AI Max 协同、信号污染防治 |
21
- | `references/google-ads-rules/google-ads-keyword-optimization.md` | **关键词持续优化指南**:基于投放数据的迭代优化闭环——指标解读、决策框架(暂停/提价/降价/加否定)、优化节奏、转化归因、预算再分配、衰减检测、竞争响应、CRM 反馈 |
22
- | `references/google-ads-rules/google-ads-creative-optimization.md` | **广告创意与素材优化**:RSA 六类主题法、Ad Strength 评分、文案 A/B 测试、创意疲劳管理、附加信息(Sitelink/Callout/Snippet/Image)优化、DKI/倒计时/IF 函数、落地页 CRO、PMax 创意策略、多语言管理 |
23
- | `references/google-ads-rules/google-ads-campaign-optimization.md` | **广告系列结构与投放优化**:系列类型选择决策树、电商/线索/本地/SaaS 架构模板、出价策略校准与启动协议、地域/设备优化、转化追踪(Enhanced Conversions/离线导入/价值规则)、预算优化、网络设置、实验设计、账户健康诊断 |
24
- | `references/google-ads-rules/google-ads-launch-plan-template.md` | **投放计划确认模板**:AI 生成完整投放方案的 Markdown 模板——信息收集清单、计划格式规范、字段与 CLI 参数映射、合规检查、执行命令预览;用于「用户确认后再执行」的工作流 |
25
- | `references/google-ads-rules/google-ads-account-audit.md` | **账户诊断与审计指南**:三层审计框架(账户→系列→组/词)、5 分钟快速健康检查、结构/转化/出价/关键词/创意/地域/设备/落地页/预算审计、竞争态势分析、20 条常见问题诊断速查表、审计报告模板 |
26
- | `references/google-ads-rules/google-ads-conversion-architecture.md` | **转化信号架构设计**:信号质量层级(L1-L5)、转化动作设计框架、多阶段漏斗价值设计、Enhanced Conversions 实施、离线转化导入策略、Consent Mode v2、利润导向出价(Profit-Based Bidding)、信号质量诊断与迁移路径、7 个行业推荐配置 |
27
- | `references/google-ads-rules/google-ads-audience-strategy.md` | **受众策略与分析**:受众类型全览、业务类型×漏斗阶段策略矩阵、观察 vs 定向模式决策、再营销四层分级(hot/warm/cool/cold)、RLSA 三大策略、Customer Match、受众数据分析框架、受众排除策略、2025-2026 隐私趋势 |
28
- | `references/google-ads-rules/google-ads-pmax-guide.md` | **PMax 与 Demand Gen 深度运营**:PMax 运营原理、Search 蚕食诊断(20% 品牌花费阈值)、Asset Group 策略、渠道级分析(2025 新功能)、搜索词/否定词/品牌排除管理、受众信号优化、Demand Gen 战术、AI Max for Search 协同、AI Overview 广告策略、常见问题诊断 |
29
-
30
- > **AI Agent 具体要求:**
31
- >
32
- > - 若当前会话中尚未阅读上述任一文件,AI 必须先主动阅读,再继续下一步流程,而不是直接生成广告计划或文案。
33
- > - 在首次阅读后,AI 需用自己的话向用户**简要复述**上述文档中与本次任务强相关的 3~5 条关键合规/策略要点,并询问用户是否有本地特殊限制需要补充。
34
- > - 后续生成的关键词、文案、出价与结构,必须**显式遵守这些规则**;一旦与规则冲突,应以规则优先,并向用户说明原因(例如:某些词因合规或商标问题被自动剔除)。
35
- > - **方案阶段措辞**:输出结构/投放方案时,用「方案草案 / 结构蓝图 / 待你确认后再执行」等表述;**避免**「可立即执行 / 拿到参数就立刻跑命令」等暗示可跳过用户确认的说法。回复开头宜有一行**已读规则文档清单**(本 `google-ads.md` + 上表 `references/google-ads-rules/` 中实际打开的文件名)。
36
-
37
- ### 第二步:向用户补齐关键信息
38
-
39
- 在进入计划设计前,AI 应最少询问并确认以下关键信息(可按需追加):
40
-
41
- - **业务与转化目标**:行业、主营产品/服务、主要转化动作(表单提交 / 电话咨询 / 在线下单 等)。
42
- - **目标地区与语言**:主要投放国家/地区、语言组合、多语言站点情况。
43
- - **预算与节奏**:日预算区间、是否有阶段性活动(如大促 / 节日档期)、允许的试错周期。
44
- - **历史投放情况**:是否已有历史账户/系列/关键词表现数据,是否有必须保留/禁止使用的词或文案。
45
- - **合规与品牌限制**:是否涉及敏感行业、是否有品牌词 / 合作方词 / 法律风控要求等。
46
-
47
- ### 第三步:根据规则与信息生成计划并确认
7
+ ## 金额单位(全局重要)
48
8
 
49
- 最终需要按照 `references/google-ads-rules/google-ads-launch-plan-template.md`
50
- 生成对应的计划,与用户沟通确认。**在该方案中,AI 必须:**
9
+ > **所有 CLI 金额参数均按「主币种金额」传入**(如 `1.5` = ¥1.50 / $1.50),CLI 内部 `Math.round(value × 100)` 写入后端「分」字段。
10
+ > **唯一例外**:`ad keyword-edit --max-cpc` 单位为「主币种元」(直接透传,不做 ×100 转换)。
11
+ > **禁止** 按 Google micros(×1,000,000)填写任何金额参数。
51
12
 
52
- - **引用并遵守**前述规则文档中的关键条款(尤其是合规与敏感行业部分),必要时在方案对应章节标注「来源规则」。
53
- - **解释核心决定的依据**,例如为何采用某类匹配结构、为何排除某类词、为何推荐某种出价策略。
54
- - **明确列出风险点与替代方案**,帮助用户在确认前做出知情决策。
55
-
56
- **只有在用户通过自然语言明确表示「同意 / 确认按此方案执行」之后**,AI 才能真正开始下面的操作;在用户未确认前,不得对账户做任何结构性改动(系列 / 广告组 / 关键词 / 创意)。
57
-
58
- > **AI Agent 额外要求**:即使用户强烈要求「不用看方案、直接创建」,也必须先按上述模板输出一次完整 Markdown 投放方案,并在对话中列出**已参考的规则文档列表**(`google-ads.md` 与 `references/google-ads-rules/` 目录下的文件),让用户有机会发现问题后再执行,防止误投和配置错误。
59
-
60
- - 如果创建失败
61
- - 部分失败:可以获取广告系列中哪些子项创建失败,然后通过对应子项的命令来重新创建
62
- - 完全失败:可以直接重新创建
63
-
64
- ## 广告的编辑
65
-
66
- 一个广告系列在创建后,发现完全失败,系列中的广告组、关键词、否定词、附加信息、地理位置、广告语、搜索字词就不能通过campaign-create来重新创建覆盖了,需要通过对应的命令来
67
- 无论是任何形式的编辑,都要读取`references/google-ads-rules/google-ads-launch-plan-template.md`来看下对应子项的输出格式,按照模板的格式输出
68
-
69
- ### 广告修改
70
-
71
- - 对用户提出的修改内容进行评估与拓展评估标准基于(references/googles-ads-rules/\*.md)中的对应的文件来确认
72
- - 确认修改方案按照
73
- - 读取`references/google-ads-rules/google-ads-launch-plan-template.md` 中关于计划模板的描述,节选用户需要修改的部分来按格式输出给用户确认
74
- - 使用对应命令来进行修改
75
- - 使用ad -h 来查询有哪些修改命令
76
- - 使用对应的获取命令进行校验
77
-
78
- ### 广告新增
79
-
80
- 参考修改的流程,将修改的命令改为新增
81
-
82
- ### 广告优化
83
-
84
- 参考修改的流程,优化的部分需要有新旧对照的表格,其他与修改流程一致
85
-
86
- ## 下面是相关命令的示例,参考就行
13
+ ---
87
14
 
88
- **ID 来源说明:**
15
+ ## ID 来源速查
89
16
 
90
- | 需要的 ID | 从哪里获取 |
17
+ | 需要的 ID | 获取命令 |
91
18
  | ------------------- | ------------------------------------------------------------ |
92
19
  | `accountId`(`-a`) | `siluzan-tso list-accounts --json` → `mediaCustomerId` |
93
20
  | 广告系列 `id` | `siluzan-tso ad campaigns -a <accountId> --json` → `id` |
@@ -97,720 +24,298 @@
97
24
 
98
25
  ---
99
26
 
100
- ## ad campaigns — 广告系列管理
101
-
102
- ### 查询广告系列列表
103
-
104
- ```bash
105
- siluzan-tso ad campaigns -a <accountId> [选项]
106
- ```
107
-
108
- | 选项 | 说明 |
109
- | ---------------------- | ------------------------------ |
110
- | `-a, --account <id>` | Google mediaCustomerId(必填) |
111
- | `--start <YYYY-MM-DD>` | 统计开始日期 |
112
- | `--end <YYYY-MM-DD>` | 统计结束日期 |
113
- | `--json` | 输出原始 JSON |
27
+ ## 新建广告系列的流程
114
28
 
115
- **示例:**
29
+ > **强制流程(AI 必须严格遵守)**
30
+ > 1)完整阅读所有规则文档 → 2)向用户补齐关键信息 → 3)在规则约束下设计广告计划 → 4)按模板输出方案并获得用户「明确确认」 → 5)**仅在已确认的前提下**执行任何结构性改动。
116
31
 
117
- ```bash
118
- # 查询账户下所有广告系列
119
- siluzan-tso ad campaigns -a 6326027735
120
-
121
- # 查询本月数据
122
- siluzan-tso ad campaigns -a 6326027735 --start 2026-03-01 --end 2026-03-31
32
+ ### 第一步:规则文档阅读(不得跳过)
123
33
 
124
- # JSON 输出,获取广告系列 id 供后续操作
125
- siluzan-tso ad campaigns -a 6326027735 --json
126
- ```
34
+ 操作开始前,**AI 必须先阅读完下面所有文档**,严禁只读 `google-ads-launch-plan-template.md` 就直接出方案。
35
+
36
+ | 文档地址 | 文档内容 |
37
+ | ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
38
+ | `references/google-ads-rules/google-ads-compliance.md` | 关键词 & 文案审核规则、编辑规范、禁止内容、商标规则 |
39
+ | `references/google-ads-rules/sensitive-industries.md` | 酒精/赌博/金融/加密/医疗等 15 个敏感行业规则 |
40
+ | `references/google-ads-rules/google-ads-keyword-strategy.md` | 匹配类型策略、分组结构、否定词技巧、出价意图分层 |
41
+ | `references/google-ads-rules/google-ads-keyword-optimization.md` | 基于数据的迭代优化闭环 |
42
+ | `references/google-ads-rules/google-ads-creative-optimization.md` | RSA 主题法、Ad Strength、A/B 测试、附加信息优化 |
43
+ | `references/google-ads-rules/google-ads-campaign-optimization.md` | 系列类型选择、出价策略、转化追踪、预算优化 |
44
+ | `references/google-ads-rules/google-ads-launch-plan-template.md` | **投放计划确认模板**(用户确认后再执行) |
45
+ | `references/google-ads-rules/google-ads-account-audit.md` | 账户诊断三层审计框架 |
46
+ | `references/google-ads-rules/google-ads-conversion-architecture.md` | 转化信号架构(L1-L5)、Enhanced Conversions、Consent Mode |
47
+ | `references/google-ads-rules/google-ads-audience-strategy.md` | 受众类型、再营销分层、Customer Match |
48
+ | `references/google-ads-rules/google-ads-pmax-guide.md` | PMax 与 Demand Gen 深度运营 |
49
+
50
+ **搜索广告方案 — 落地页 URL 推断**:用户只提供官网首页时,参阅 `references/google-ads-rules/google-ads-landing-page-discovery-via-webfetch.md`(**不向用户复述工具名**)。
51
+
52
+ > **AI Agent 要求:**
53
+ > - 未读完全部文档前,不得生成广告计划或文案。
54
+ > - 首次阅读后,向用户简要复述 3~5 条与本次任务强相关的合规/策略要点。
55
+ > - 生成的关键词、文案、出价与结构必须显式遵守规则;与规则冲突时以规则优先。
56
+ > - **方案阶段措辞**:用「方案草案 / 待你确认后再执行」等表述,避免暗示可跳过用户确认。回复开头列出已读规则文档清单。
127
57
 
128
- 输出字段:名称、状态、类型、预算、点击数、展示数(具体字段名以 `--json` 为准)。**`--json` / `--json-out` 下 `budget` 为日预算,已由 CLI 统一为主币种「元」**(网关列表接口的「分」在 CLI 内 ÷100),与 `ad campaign-edit --budget` 等写参同口径;另有 CLI 派生的 **`statusDisplay`**(状态文案)等便于阅读。
58
+ ### 第二步:向用户补齐关键信息
129
59
 
130
- ---
60
+ AI 应最少确认以下信息:
61
+ - **业务与转化目标**:行业、主营产品/服务、转化动作(表单/电话/下单等)。
62
+ - **目标地区与语言**:投放国家/地区、语言组合。
63
+ - **预算与节奏**:日预算区间、活动档期、试错周期。
64
+ - **历史投放情况**:是否有历史数据、必须保留/禁止的词或文案。
65
+ - **合规与品牌限制**:敏感行业、品牌词/法律风控要求等。
131
66
 
132
- ### 广告系列启停
67
+ ### 第三步:根据规则与信息生成计划并确认
133
68
 
134
- ```bash
135
- siluzan-tso ad campaign-status \
136
- -a <accountId> \
137
- --id <campaignId> \
138
- --status <Enabled|Paused>
139
- ```
69
+ 按 `references/google-ads-rules/google-ads-launch-plan-template.md` 生成计划,与用户沟通确认。方案中必须:
70
+ - 引用并遵守规则文档关键条款,标注来源。
71
+ - 解释核心决定依据(匹配结构、排除词、出价策略)。
72
+ - 列出风险点与替代方案。
140
73
 
141
- **示例:**
74
+ **只有用户明确表示「同意/确认按此方案执行」后**,才能执行操作。
142
75
 
143
- ```bash
144
- # 暂停广告系列
145
- siluzan-tso ad campaign-status -a 6326027735 --id campaign_001 --status Paused
76
+ > 即使用户要求跳过方案直接创建,也必须先输出完整 Markdown 投放方案并列出已参考的规则文档。
146
77
 
147
- # 恢复广告系列
148
- siluzan-tso ad campaign-status -a 6326027735 --id campaign_001 --status Enabled
149
- ```
78
+ - 创建失败处理:
79
+ - 部分失败:获取失败子项,用对应命令重新创建
80
+ - 完全失败:直接重新创建
150
81
 
151
82
  ---
152
83
 
153
- ### 广告系列删除
84
+ ## 广告的编辑
154
85
 
155
- ```bash
156
- siluzan-tso ad campaign-delete -a <accountId> --id <campaignId>
157
- ```
86
+ 创建后的修改不能通过 `campaign-create` 覆盖,需用对应命令。任何编辑前都要读取 `references/google-ads-rules/google-ads-launch-plan-template.md` 确认输出格式。
158
87
 
159
- **示例:**
88
+ ### 广告修改
89
+ - 基于 `references/google-ads-rules/*.md` 评估修改内容
90
+ - 读取 launch-plan-template 对应章节,按格式输出给用户确认
91
+ - 使用 `ad -h` 查询可用命令,执行后用获取命令校验
160
92
 
161
- ```bash
162
- siluzan-tso ad campaign-delete -a 6326027735 --id campaign_001
163
- ```
93
+ ### 广告新增
94
+ 参考修改流程,将修改命令替换为新增命令。
164
95
 
165
- > ⚠️ 删除操作不可逆,建议先用 `campaigns` 命令确认目标广告系列名称再删除。
96
+ ### 广告优化
97
+ 参考修改流程,增加新旧对照表格。
166
98
 
167
99
  ---
168
100
 
169
- ## ad groups广告组管理
170
-
171
- ### 查询广告组列表
101
+ ## ad campaigns广告系列管理
172
102
 
103
+ ### 查询列表
173
104
  ```bash
174
- siluzan-tso ad groups -a <accountId> [选项]
105
+ siluzan-tso ad campaigns -a <accountId> [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>] [--json]
175
106
  ```
107
+ `--json` 下 `budget` 为日预算(主币种「元」,CLI 已 ÷100),另有 `statusDisplay`(状态文案)。
176
108
 
177
- | 选项 | 说明 |
178
- | ------------------------ | ------------------------------ |
179
- | `-a, --account <id>` | Google mediaCustomerId(必填) |
180
- | `--start / --end <date>` | 统计日期范围 |
181
- | `--json` | 输出原始 JSON |
182
-
183
- **示例:**
184
-
109
+ ### 启停
185
110
  ```bash
186
- # 查询所有广告组
187
- siluzan-tso ad groups -a 6326027735
188
-
189
- # JSON 输出,获取 id 和 name
190
- siluzan-tso ad groups -a 6326027735 --json
111
+ siluzan-tso ad campaign-status -a <accountId> --id <campaignId> --status <Enabled|Paused>
191
112
  ```
192
113
 
193
- ---
194
-
195
- ### 创建广告组
196
-
114
+ ### 删除
197
115
  ```bash
198
- siluzan-tso ad adgroup-create \
199
- -a <accountId> \
200
- --campaign-id <campaignId> \
201
- --campaign-name <campaignName> \
202
- --name <adGroupName> \
203
- --max-cpc <主币种金额>
116
+ siluzan-tso ad campaign-delete -a <accountId> --id <campaignId>
204
117
  ```
118
+ > 删除不可逆,建议先 `campaigns` 确认名称。
205
119
 
206
- > **金额单位**:`--max-cpc` 为 **主币种金额**(如 `1.5` 表示 ¥1.50),CLI 内部 `Math.round(value × 100)` 写入「分」字段,与前端表单 `arithmetic.times(maxCPCAmount, 100)`、`ad adgroup-edit` 完全一致。**禁止** 按 Google micros(×1,000,000)填写。
207
-
208
- | 选项 | 说明 | 必填 |
209
- | ------------------------ | ---------------------------------------------------------- | ---- |
210
- | `-a, --account <id>` | Google mediaCustomerId | ✅ |
211
- | `--campaign-id <id>` | 所属广告系列 ID(来自 `campaigns --json`) | ✅ |
212
- | `--campaign-name <name>` | 所属广告系列名称 | ✅ |
213
- | `--name <name>` | 广告组名称 | ✅ |
214
- | `--max-cpc <amount>` | 最高 CPC 出价,主币种金额(如 `1.5` = ¥1.50;CLI 内部 ×100)| ✅ |
215
- | `--status <status>` | `ENABLED \| PAUSED`(默认 `ENABLED`) | |
120
+ ---
216
121
 
217
- **示例:**
122
+ ## ad groups — 广告组管理
218
123
 
124
+ ### 查询列表
219
125
  ```bash
220
- # 在广告系列下创建广告组,最高 CPC ¥1
221
- siluzan-tso ad adgroup-create \
222
- -a 6326027735 \
223
- --campaign-id campaign_001 \
224
- --campaign-name "品牌推广_春季" \
225
- --name "核心词_跑步鞋" \
226
- --max-cpc 1
227
-
228
- # 创建时设为暂停状态,最高 CPC ¥1.5
229
- siluzan-tso ad adgroup-create \
230
- -a 6326027735 \
231
- --campaign-id campaign_001 \
232
- --campaign-name "品牌推广_春季" \
233
- --name "竞品词" \
234
- --max-cpc 1.5 \
235
- --status PAUSED
126
+ siluzan-tso ad groups -a <accountId> [--start/--end <date>] [--json]
236
127
  ```
237
128
 
238
- ---
239
-
240
- ### 广告组启停
241
-
129
+ ### 创建
242
130
  ```bash
243
- siluzan-tso ad adgroup-status \
131
+ siluzan-tso ad adgroup-create \
244
132
  -a <accountId> \
245
- --id <adGroupId> \
246
- --status <Enabled|Paused>
133
+ --campaign-id <campaignId> --campaign-name <campaignName> \
134
+ --name <adGroupName> --max-cpc <主币种金额> \
135
+ [--status ENABLED|PAUSED]
247
136
  ```
248
137
 
249
- **示例:**
138
+ | 选项 | 说明 | 必填 |
139
+ | --- | --- | --- |
140
+ | `-a, --account <id>` | Google mediaCustomerId | ✅ |
141
+ | `--campaign-id <id>` | 所属广告系列 ID | ✅ |
142
+ | `--campaign-name <name>` | 所属广告系列名称 | ✅ |
143
+ | `--name <name>` | 广告组名称 | ✅ |
144
+ | `--max-cpc <amount>` | 最高 CPC(主币种金额) | ✅ |
145
+ | `--status` | `ENABLED`(默认)/ `PAUSED` | |
250
146
 
147
+ ### 启停
251
148
  ```bash
252
- # 暂停广告组
253
- siluzan-tso ad adgroup-status -a 6326027735 --id adgroup_001 --status Paused
254
-
255
- # 恢复广告组
256
- siluzan-tso ad adgroup-status -a 6326027735 --id adgroup_001 --status Enabled
149
+ siluzan-tso ad adgroup-status -a <accountId> --id <adGroupId> --status <Enabled|Paused>
257
150
  ```
258
151
 
259
- ---
260
-
261
- ### 广告组编辑(名称 / 最高 CPC / 组级目标 CPA)
262
-
263
- 先用 **`ad groups … --json`** 查看当前的 **`maxCPCAmountDisplay`**、**`targetCpaAmountDisplay`**(主币种金额)等,再用本命令只改传入的字段。
264
-
152
+ ### 编辑
153
+ 先用 `ad groups --json` 查看当前值,再只改传入字段。
265
154
  ```bash
266
155
  siluzan-tso ad adgroup-edit \
267
- -a <accountId> \
268
- --id <adGroupId> \
269
- [--name <新名称>] \
270
- [--max-cpc <主币种金额>] \
271
- [--target-cpa <主币种金额>] \
272
- [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>]
273
- ```
274
-
275
- > **金额单位(必读)**:所有金额参数均按 **主币种金额** 传入(如 `1.5` 表示 ¥1.50);CLI 内部 `Math.round(value × 100)` 写入后端「分」字段,与 `ad campaign-edit`、前端表单完全一致。**禁止** 按 Google micros(×1,000,000)填写。
276
-
277
- | 选项 | 说明 |
278
- |------|------|
279
- | `--max-cpc` | 最高 CPC,主币种金额(与 `ad groups --json` 中 **`maxCPCAmountDisplay`** 对齐)。 |
280
- | `--target-cpa` | 组级目标 CPA,主币种金额(与 `ad groups --json` 中 **`targetCpaAmountDisplay`** 对齐)。写入 **> 0** 才会更新。 |
281
- | `--name` | 新名称(可选)。 |
282
-
283
- **示例:**
284
-
285
- ```bash
286
- # 先取 JSON,读取 maxCPCAmountDisplay / targetCpaAmountDisplay(主币种金额)算新值后再写回
287
- siluzan-tso ad groups -a 6326027735 --json
288
-
289
- # 把最高 CPC 调整到 ¥2
290
- siluzan-tso ad adgroup-edit -a 6326027735 --id 195548094874 --max-cpc 2
291
-
292
- # 设置目标 CPA = ¥50,并改名
293
- siluzan-tso ad adgroup-edit -a 6326027735 --id 195548094874 --target-cpa 50 --name "核心词_降价后"
156
+ -a <accountId> --id <adGroupId> \
157
+ [--name <新名称>] [--max-cpc <主币种金额>] [--target-cpa <主币种金额>] \
158
+ [--start/--end <YYYY-MM-DD>]
294
159
  ```
160
+ `--max-cpc` / `--target-cpa` 与 `ad groups --json` 中 `maxCPCAmountDisplay` / `targetCpaAmountDisplay` 对齐。
295
161
 
296
- ---
297
-
298
- ### 广告组删除
299
-
162
+ ### 删除
300
163
  ```bash
301
164
  siluzan-tso ad adgroup-delete -a <accountId> --id <adGroupId>
302
165
  ```
303
166
 
304
- **示例:**
305
-
306
- ```bash
307
- siluzan-tso ad adgroup-delete -a 6326027735 --id adgroup_001
308
- ```
309
-
310
167
  ---
311
168
 
312
169
  ## ad list — 广告创意管理
313
170
 
314
- ### 查询广告列表
315
-
171
+ ### 查询列表
316
172
  ```bash
317
- siluzan-tso ad list -a <accountId> [选项]
173
+ siluzan-tso ad list -a <accountId> [--start/--end <date>] [--include-deleted] [--json]
318
174
  ```
175
+ `--include-deleted` 用于审计/排障,会多传 `readDeleted=true`。
319
176
 
320
- | 选项 | 说明 |
321
- | ------------------------ | -------------------------------------------------------------------- |
322
- | `-a, --account <id>` | Google mediaCustomerId(必填) |
323
- | `--start / --end <date>` | 统计日期范围 |
324
- | `--include-deleted` | 包含已删除的广告(默认不传;传则网关加 `readDeleted=true`,审计/排障用) |
325
- | `--json` | 输出原始 JSON |
326
-
327
- **示例:**
328
-
329
- ```bash
330
- # 查询所有广告
331
- siluzan-tso ad list -a 6326027735
332
-
333
- # JSON 输出,获取广告 id
334
- siluzan-tso ad list -a 6326027735 --json
335
- ```
336
-
337
- ### 拒审与政策(`ad list --json`)
338
-
339
- 使用 **`siluzan-tso ad list -a <accountId> [--start/--end] --json`**,或按 `references/account-analytics.md` 口径 **`siluzan-tso google-analysis --sections ads … --json-out <dir>`** 落盘后读 **`ads.json`**,巡检素材审核状态。
340
-
341
- **在 JSON 中可重点查看的键名(以当次 stdout 为准,多为 camelCase):**
342
-
343
- - **`policyApprovalStatusV2`**(及可能出现的 **`policyApprovalStatus`**):审核总状态。常见数值含义(若为数字):**`2`** 表示不通过(拒审)、**`3`** 表示受限通过;若为字符串则按字面量解析。
344
- - **`approvalStatusDetails`**:政策相关说明的**摘要串**,多条证据之间常用 **`;`** 分隔。**不提供**与控制台一一对应的「政策主题」结构化数组;需要更细粒度编码时须另辟数据源或与维护方确认。
345
- - **`statusV2`**:广告启用状态;排除已移除条目时用 **`Removed`** 等值过滤(以实际枚举为准)。
346
-
347
- **同源拉数**:`ad list` 与 **`google-analysis --sections ads`** 在默认参数下列表数据一致;任选其一做拒审巡检即可,字段以 **当次 `ad list` 的 stdout JSON** 或 **`google-analysis --sections ads` 落盘 `ads.json`** 为准。若使用 **`ad list --include-deleted`**,会多传 `readDeleted=true`,与未带该参数的 **`google-analysis --sections ads`** 口径可能不一致。
348
-
349
- ### 转化与价值(`ad list --json`,需网关已返回对应字段)
350
-
351
- 在已部署的 Google 网关上,创意列表 JSON 中除 **`spend`**、**`conversions`**、**`impressions`**、**`ctr`** 等外,还可关注(键名以当次输出为准):
352
-
353
- - **`allConversions`**
354
- - **`conversionsValue`**
355
- - **`conversionsValuePerImpression`**(可能由后端计算属性序列化;若无则用 **`conversionsValue / impressions`** 在聚合后自行计算)
356
-
357
- 带 **`--start` / `--end`** 时,底层按日分段,**同一创意 `id` 可能多行**;做窗口汇总或 A/B 比较前须在宿主 **按 `id` 聚合** 后再算比率。宿主编排下的 **自动优化 SOP** 见 **`references/hosted-automation-optimize-index.md`**。
358
-
359
- ---
360
-
361
- ### 创建广告(自适应搜索广告 RSA)
177
+ ### 拒审巡检(`--json`)
178
+ 关注 `policyApprovalStatusV2`(`2`=不通过、`3`=受限)、`approvalStatusDetails`(`;` 分隔摘要)、`statusV2`(过滤 `Removed`)。同源也可用 `google-analysis --sections ads --json-out <dir>`。
362
179
 
180
+ ### 创建(RSA)
363
181
  ```bash
364
182
  siluzan-tso ad ad-create \
365
183
  -a <accountId> \
366
- --adgroup-id <adGroupId> \
367
- --adgroup-name <adGroupName> \
184
+ --adgroup-id <adGroupId> --adgroup-name <adGroupName> \
368
185
  --final-url <url> \
369
186
  --headlines "标题1,标题2,标题3" \
370
- --descriptions "描述1,描述2"
371
- ```
372
-
373
- | 选项 | 说明 | 必填 |
374
- | ------------------------ | ------------------------------------------------ | ---- |
375
- | `-a, --account <id>` | Google mediaCustomerId | ✅ |
376
- | `--adgroup-id <id>` | 广告组 ID(来自 `groups --json`) | ✅ |
377
- | `--adgroup-name <name>` | 广告组名称 | ✅ |
378
- | `--final-url <url>` | 最终落地页 URL | ✅ |
379
- | `--headlines <titles>` | 标题列表,逗号分隔(**至少 3 个**,每个≤30字符) | ✅ |
380
- | `--descriptions <descs>` | 描述列表,逗号分隔(**至少 2 个**,每个≤90字符) | ✅ |
381
- | `--path1 <text>` | 显示路径第1段(≤15字符) | |
382
- | `--path2 <text>` | 显示路径第2段(≤15字符) | |
383
-
384
- **示例:**
385
-
386
- ```bash
387
- # 创建基础 RSA 广告
388
- siluzan-tso ad ad-create \
389
- -a 6326027735 \
390
- --adgroup-id adgroup_001 \
391
- --adgroup-name "核心词_跑步鞋" \
392
- --final-url "https://www.brand-a.com/running-shoes" \
393
- --headlines "专业跑步鞋,轻量透气跑鞋,跑步必备神器" \
394
- --descriptions "全球百万跑者信赖,专业设计助你突破极限。,免费配送,30天无理由退换。"
395
-
396
- # 带显示路径
397
- siluzan-tso ad ad-create \
398
- -a 6326027735 \
399
- --adgroup-id adgroup_001 \
400
- --adgroup-name "核心词_跑步鞋" \
401
- --final-url "https://www.brand-a.com/running-shoes" \
402
- --headlines "跑步鞋专场,品牌直销价,限时特惠" \
403
- --descriptions "正品保证,7天无理由退换。,百款跑鞋,一站购齐。" \
404
- --path1 "跑步鞋" \
405
- --path2 "特惠"
406
- ```
407
-
408
- ---
409
-
410
- ### 广告创意启停
411
-
412
- ```bash
413
- siluzan-tso ad ad-status \
414
- -a <accountId> \
415
- --id <adId> \
416
- --status <Enabled|Paused>
187
+ --descriptions "描述1,描述2" \
188
+ [--path1 <≤15字符>] [--path2 <≤15字符>]
417
189
  ```
190
+ `--headlines` 至少 3 条(≤30字符),`--descriptions` 至少 2 条(≤90字符)。
418
191
 
419
- **示例:**
420
-
421
- ```bash
422
- siluzan-tso ad ad-status -a 6326027735 --id ad_001 --status Paused
423
- siluzan-tso ad ad-status -a 6326027735 --id ad_001 --status Enabled
424
- ```
425
-
426
- ---
427
-
428
- ### 广告创意删除
429
-
192
+ ### 启停 / 删除
430
193
  ```bash
194
+ siluzan-tso ad ad-status -a <accountId> --id <adId> --status <Enabled|Paused>
431
195
  siluzan-tso ad ad-delete -a <accountId> --id <adId>
432
196
  ```
433
197
 
434
- **示例:**
435
-
436
- ```bash
437
- siluzan-tso ad ad-delete -a 6326027735 --id ad_001
438
- ```
439
-
440
198
  ---
441
199
 
442
200
  ## ad keywords — 关键词管理
443
201
 
444
- ### 查询关键词列表
445
-
202
+ ### 查询
446
203
  ```bash
447
- siluzan-tso ad keywords -a <accountId> [选项]
204
+ siluzan-tso ad keywords -a <accountId> [--negative] [--start/--end <date>] [--json]
448
205
  ```
449
206
 
450
- | 选项 | 说明 |
451
- | ------------------------ | ---------------------------------- |
452
- | `-a, --account <id>` | Google mediaCustomerId(必填) |
453
- | `--negative` | 查询否定关键词(默认查普通关键词) |
454
- | `--start / --end <date>` | 统计日期范围 |
455
- | `--json` | 输出原始 JSON |
456
-
457
- **示例:**
458
-
459
- ```bash
460
- # 查询普通关键词
461
- siluzan-tso ad keywords -a 6326027735
462
-
463
- # 查询否定关键词
464
- siluzan-tso ad keywords -a 6326027735 --negative
465
-
466
- # JSON 输出,获取关键词 id
467
- siluzan-tso ad keywords -a 6326027735 --json
468
- ```
469
-
470
- ---
471
-
472
207
  ### 添加关键词
473
-
474
208
  ```bash
475
209
  siluzan-tso ad keyword-create \
476
210
  -a <accountId> \
477
- --adgroup-id <adGroupId> \
478
- --adgroup-name <adGroupName> \
479
- --campaign-id <campaignId> \
480
- --campaign-name <campaignName> \
481
- --keywords "词1,词2,词3"
211
+ --adgroup-id <adGroupId> --adgroup-name <adGroupName> \
212
+ --campaign-id <campaignId> --campaign-name <campaignName> \
213
+ --keywords "词1,词2,词3" [--final-url <url>]
482
214
  ```
483
215
 
484
- | 选项 | 说明 | 必填 |
485
- | ------------------------ | ------------------------ | ---- |
486
- | `-a, --account <id>` | Google mediaCustomerId | ✅ |
487
- | `--adgroup-id <id>` | 广告组 ID | ✅ |
488
- | `--adgroup-name <name>` | 广告组名称 | ✅ |
489
- | `--campaign-id <id>` | 广告系列 ID | ✅ |
490
- | `--campaign-name <name>` | 广告系列名称 | ✅ |
491
- | `--keywords <words>` | 关键词列表,逗号分隔 | ✅ |
492
- | `--final-url <url>` | 关键词独立落地页(可选) | |
493
-
494
- **示例:**
495
-
496
- ```bash
497
- # 添加 3 个关键词到广告组
498
- siluzan-tso ad keyword-create \
499
- -a 6326027735 \
500
- --adgroup-id adgroup_001 \
501
- --adgroup-name "核心词_跑步鞋" \
502
- --campaign-id campaign_001 \
503
- --campaign-name "品牌推广_春季" \
504
- --keywords "跑步鞋,running shoes,专业跑鞋"
505
-
506
- # 带独立落地页
507
- siluzan-tso ad keyword-create \
508
- -a 6326027735 \
509
- --adgroup-id adgroup_001 \
510
- --adgroup-name "核心词_跑步鞋" \
511
- --campaign-id campaign_001 \
512
- --campaign-name "品牌推广_春季" \
513
- --keywords "马拉松跑鞋" \
514
- --final-url "https://www.brand-a.com/marathon-shoes"
515
- ```
516
-
517
- ---
518
-
519
- ### 添加否定关键词
520
-
521
- 可在广告系列层级或广告组层级添加否定关键词。
522
-
216
+ ### 否定关键词
523
217
  ```bash
218
+ # 添加(默认系列层级;传 --adgroup-id 则为组层级)
524
219
  siluzan-tso ad keyword-negative-create \
525
220
  -a <accountId> \
526
- --campaign-id <campaignId> \
527
- --campaign-name <campaignName> \
528
- --keywords "词1,词2"
529
- ```
530
-
531
- | 选项 | 说明 |
532
- | ----------------------- | ------------------------------------------------------- |
533
- | `--adgroup-id <id>` | 广告组 ID(传入则在广告组层级添加,否则在广告系列层级) |
534
- | `--adgroup-name <name>` | 广告组名称(与 `--adgroup-id` 配套使用) |
535
-
536
- **示例:**
221
+ --campaign-id <campaignId> --campaign-name <campaignName> \
222
+ --keywords "词1,词2" \
223
+ [--adgroup-id <id> --adgroup-name <name>]
537
224
 
538
- ```bash
539
- # 在广告系列层级添加否定关键词(屏蔽)
540
- siluzan-tso ad keyword-negative-create \
541
- -a 6326027735 \
542
- --campaign-id campaign_001 \
543
- --campaign-name "品牌推广_春季" \
544
- --keywords "免费,破解,二手"
545
-
546
- # 在广告组层级添加否定关键词
547
- siluzan-tso ad keyword-negative-create \
548
- -a 6326027735 \
549
- --campaign-id campaign_001 \
550
- --campaign-name "品牌推广_春季" \
551
- --adgroup-id adgroup_001 \
552
- --adgroup-name "核心词_跑步鞋" \
553
- --keywords "拖鞋,凉鞋"
554
- ```
555
-
556
- ---
557
-
558
- ### 删除否定关键词
559
-
560
- ```bash
561
- siluzan-tso ad keyword-negative-delete \
562
- -a <accountId> \
563
- --id <negativeKeywordId>
564
- ```
565
-
566
- | 选项 | 说明 |
567
- | ------------------------ | ---------------------------------------------- |
568
- | `--start / --end <date>` | 查询日期范围(用于定位关键词,默认最近 30 天) |
569
-
570
- **示例:**
571
-
572
- ```bash
573
- # 先查询获取否定关键词 id
574
- siluzan-tso ad keywords -a 6326027735 --negative --json
575
-
576
- # 然后删除
577
- siluzan-tso ad keyword-negative-delete -a 6326027735 --id negkw_abc123
225
+ # 删除(先用 ad keywords --negative --json 获取 id)
226
+ siluzan-tso ad keyword-negative-delete -a <accountId> --id <negativeKeywordId>
578
227
  ```
579
228
 
580
229
  ---
581
230
 
582
231
  ## ad batch — 异步批量创建记录
583
232
 
584
- 对应页面:`/advertising/AICreationList`。与 `ad campaign-create` 等同源异步创建链路,用于管理异步批量创建任务与草稿。
585
-
586
- ### list — 查询列表
587
-
588
- ```bash
589
- siluzan-tso ad batch list [选项]
590
- ```
591
-
592
- | 选项 | 说明 |
593
- | ------------------------ | ---------------------------------------------------------------------- |
594
- | `-s, --state <state>` | 状态:`Creating \| Successfully \| Failed \| HasFailed \| Unpublished` |
595
- | `--customer-id <id>` | Google mediaCustomerId |
596
- | `--customer-name <name>` | 客户名称关键字 |
597
- | `-k, --keyword <text>` | 关键字 |
598
- | `--start / --end <date>` | 创建日期范围 |
599
- | `-p, --page <n>` | 页码(默认 1) |
600
- | `--page-size <n>` | 每页数量(默认 20) |
601
- | `--json` | 输出原始 JSON |
602
-
603
- **示例:**
604
-
605
- ```bash
606
- siluzan-tso ad batch list
607
- siluzan-tso ad batch list --customer-id 6326027735
608
- siluzan-tso ad batch list --state Failed --json
609
- siluzan-tso ad batch list --state Unpublished --start 2026-03-01
610
- ```
611
-
612
- ### get — 获取记录 / 草稿详情
233
+ 对应页面 `/advertising/AICreationList`。
613
234
 
614
235
  ```bash
236
+ siluzan-tso ad batch list [--state Creating|Successfully|Failed|HasFailed|Unpublished] [--customer-id <id>] [--start/--end <date>] [--json]
615
237
  siluzan-tso ad batch get --id <recordId>
616
- ```
617
-
618
- 输出完整 JSON(含广告系列、预算、关键词、定向位置等),通常配合 `--json` 使用,供 AI 或脚本进一步分析。
619
-
620
- ### update — 更新草稿字段
621
-
622
- 只有 `draftStatus === "Draft"` 的记录可更新。
623
-
624
- ```bash
625
- siluzan-tso ad batch update --id <recordId> [选项]
626
- ```
627
-
628
- | 选项 | 说明 |
629
- | ------------------------ | ------------------------------------------------------------------- |
630
- | `--budget <amount>` | 新日预算,主币种金额(如 `85` 表示 ¥85;CLI 内部自动 ×100 写入「分」) |
631
- | `--url <url>` | 新推广链接 |
632
- | `--campaign-name <name>` | 新广告系列名称 |
633
-
634
- ### publish — 发布草稿
635
-
636
- 只有 `draftStatus === "Draft"` 的记录可发布。发布后状态变为 `Creating`,Google 后台异步执行创建。
637
-
638
- ```bash
238
+ siluzan-tso ad batch update --id <recordId> [--budget <主币种>] [--url <url>] [--campaign-name <name>]
639
239
  siluzan-tso ad batch publish --id <recordId>
640
240
  ```
241
+ `update` / `publish` 仅 `draftStatus === "Draft"` 可操作。
641
242
 
642
243
  ---
643
244
 
644
245
  ## keyword — 关键字推荐
645
246
 
646
- 根据种子词或网址,从 Google Keyword Planner 获取相关关键词建议。
647
-
648
- ```bash
649
- siluzan-tso keyword -k <搜索词> [选项]
650
- ```
651
-
652
- | 选项 | 说明 |
653
- | ----------------------- | -------------------------------------------------- |
654
- | `-k, --keyword <words>` | 种子词,多个逗号分隔(必填) |
655
- | `--url <url>` | 公司/产品网址(填写后触发「网址拓词 + 轮询」流程) |
656
- | `--include <words>` | 结果必须包含的词(逗号或空格分隔,本地过滤) |
657
- | `--exclude <words>` | 结果不包含的词(本地过滤) |
658
- | `--json` | 输出原始 JSON |
659
-
660
- **示例:**
247
+ 多场景编排(竞品 URL + 种子、账户词叠市场指标、否词与建户表等)见 **`references/keyword-planner-workflows.md`**。
661
248
 
662
249
  ```bash
663
- # 基础关键词推荐
664
- siluzan-tso keyword -k "running shoes"
665
-
666
- # 多种子词推荐
667
- siluzan-tso keyword -k "running shoes,sports shoes,marathon"
668
-
669
- # 网址拓词(爬取网址内容后推荐相关词)
670
- siluzan-tso keyword -k "跑步鞋" --url "https://www.brand-a.com"
671
-
672
- # 过滤:只保留含 "shoes" 的词,且排除 "cheap" 和 "kids"
673
- siluzan-tso keyword -k "running shoes" --include "shoes" --exclude "cheap,kids"
674
-
675
- # JSON 输出(含搜索量、竞争度、建议出价等)
676
- siluzan-tso keyword -k "running shoes" --json
250
+ siluzan-tso keyword -k <搜索词> [--url <url>] [--include <words>] [--exclude <words>] [--json] [--json-out <dir>]
677
251
  ```
252
+ `--url` 触发网址拓词 + 轮询流程;`--include`/`--exclude` 为本地过滤。
678
253
 
679
254
  ---
680
255
 
681
256
  ## ad campaign-create — 广告系列新增
682
257
 
683
- 新建搜索广告系列(异步批量任务)。支持两种创建模式:
684
-
685
- > - 默认行为:不加 `--draft` 时,CLI 直接走「立即发布」路径(`DraftStatus: Published`)。
686
- > - 草稿行为:加上 `--draft` 时,仅创建草稿记录(`DraftStatus: Draft`),需后续用 `ad batch publish` 才真正提交给 Google。
687
- > 广告组、关键词、广告创意的分步创建请使用 `adgroup-create`、`keyword-create`、`ad-create` 等命令。
688
- > 任务异步处理,任务 ID 可通过 `ad batch get --id <id>` 跟进进度。
689
-
690
- ---
691
-
692
- ### --config-file(JSON 配置文件) -强烈推荐使用这种方式
693
-
694
- **当参数复杂(多广告组、含附加功能、标题中有逗号)时,AI 应优先使用此方式**:将所有参数写入一个 JSON 文件,再用 `--config-file` 传入路径。
695
-
696
- **优势:**
697
-
698
- - `headlines` 是真正的字符串数组,元素内**允许含逗号**(如 `"Global Reach, Local Impact"`)
699
- - `extensions` / `extraAdGroups` 直接写 JSON,不需要序列化为字符串
700
- - 参数复杂时无 shell 转义问题,AI 一次生成即可成功
701
-
702
- **AI 执行步骤:**
703
-
704
- 1. Write 工具将配置写入 JSON 文件(如 `/tmp/campaign.json`)
705
- 2. 执行 `siluzan-tso ad campaign-create --config-file /tmp/campaign.json`
706
- 3. 用返回的任务 ID 查询进度
707
-
708
- **JSON 配置文件完整 Schema:**
709
-
710
- 请阅读:`assets/campaign-create-template.json`
711
-
712
- **JSON文件 字段说明:**
713
-
714
- | 字段 | 必填 | 类型 | 说明 |
715
- | ----------------------- | ---- | -------- | ------------------------------------------------------------------------- |
716
- | `account` | ✅ | string | Google 账户 mediaCustomerId |
717
- | `customerName` | ✅ | string | 账户名称(`list-accounts --json` 的 `mediaAccountName`) |
718
- | `name` | ✅ | string | 广告系列名称 |
719
- | `budget` | ✅ | number | 日预算,**主币种展示金额**(100 = 每天 100 USD/CNY,内部 ×100) |
720
- | `bidding` | ✅ | string | 出价策略:`TARGET_SPEND` \| `MANUAL_CPC` \| `TARGET_CPA` \| `TARGET_ROAS` |
721
- | `locationIds` | ✅ | string[] | 地理位置 ID 数组(`ad geo search` 获取) |
722
- | `adgroupName` | ✅ | string | 第一个广告组名称 |
723
- | `maxCpc` | ✅ | number | 第一个广告组最高 CPC,主币种展示金额(1.5 = 1.50 USD,内部 ×100) |
724
- | `bidCeiling` | | number | TARGET_SPEND 出价上限(主币种,内部 ×100 |
725
- | `targetCpa` | | number | TARGET_CPA 目标 CPA(主币种,内部 ×100) |
726
- | `targetRoas` | | number | TARGET_ROAS 目标 ROAS(如 2.5) |
727
- | `languageIds` | ✅ | string[] | 语言 ID 数组(默认 `["1000"]` = 英语,中文 = `"1017"`) |
728
- | `startDate` / `endDate` | ✅ | string | 日期 YYYY-MM-DD(默认:今天 / 2037-12-30) |
729
- | `url` | ✅ | string | 落地页 URL |
730
- | `status` | ✅ | string | `Enabled` \| `Paused`(默认 Enabled) |
731
- | `matchType` | ✅ | string | 默认匹配类型:`BROAD` \| `PHRASE` \| `EXACT` |
732
- | `keywords` | ✅ | string[] | 第一个广告组关键词 |
733
- | `headlines` | ✅ | string[] | 标题数组,至少 3 条,推荐 15 条,每条 ≤ 30 字符,**元素内允许含逗号** |
734
- | `descriptions` | ✅ | string[] | 描述数组,至少 2 条,推荐 4 条,每条 ≤ 90 字符 |
735
- | `finalUrl` | ✅ | string | 广告落地页 |
736
- | `path1` / `path2` | ✅ | string | 展示 URL 路径(各 ≤ 15 字符) |
737
- | `productWords` | ✅ | string[] | 推广产品词(用于 AI 关键词推荐) |
738
- | `negativeKeywords` | ✅ | string[] | 否定关键词数组(默认 BROAD 匹配) |
739
- | `extensions` | ✅ | array | 广告附加功能(CALL / SITELINK / STRUCTURED_SNIPPET),见 Schema |
740
- | `extraAdGroups` | ✅ | array | 额外广告组,追加到 AdGroupsForBatchJob,见 Schema |
741
- | `draft` | ✅ | boolean | `true` = 仅保存草稿(需后续 `ad batch publish` 发布) |
742
-
743
- ---
744
-
745
- ### 命令行直接传参(简单场景适用)
746
-
747
- 所有参数也可以直接通过 CLI 选项传入(复杂场景推荐用 `--config-file`):
748
-
749
- | 选项 | 必填 | 说明 |
750
- | ---------------------------------------------- | ---- | --------------------------------------------------------------------- |
751
- | `-a, --account <id>` | ✅\* | Google 账户 mediaCustomerId(\*使用 `--config-file` 时可从文件读取) |
752
- | `--customer-name <name>` | ✅\* | 账户名称 |
753
- | `--name <name>` | ✅\* | 广告系列名称 |
754
- | `--budget <amount>` | ✅\* | 日预算(主币种展示金额) |
755
- | `--bidding <strategy>` | ✅\* | 出价策略 |
756
- | `--location-ids <ids>` | ✅\* | 地理位置 ID,逗号分隔 |
757
- | `--adgroup-name <name>` | ✅\* | 第一个广告组名称 |
758
- | `--max-cpc <amount>` | ✅\* | 最高 CPC(主币种展示金额) |
759
- | `--keywords <kws>` | — | 关键词,逗号分隔 |
760
- | `--headlines <titles>` | — | 广告标题,逗号分隔(⚠️ 标题内不能含逗号,含逗号请用 `--config-file`) |
761
- | `--descriptions <descs>` | — | 广告描述,逗号分隔 |
762
- | `--product-words <words>` | — | 产品词,逗号分隔 |
763
- | `--negative-keywords <kws>` | — | 否定关键词,逗号分隔 |
764
- | `--extensions-json <json>` | — | 附加功能 JSON 数组字符串 |
765
- | `--extra-adgroups-json <json>` | — | 额外广告组 JSON 数组字符串 |
766
- | `--lang-ids <ids>` | — | 语言 ID,逗号分隔(默认 1000=英语) |
767
- | `--bid-ceiling / --target-cpa / --target-roas` | — | 出价相关参数 |
768
- | `--start / --end` | — | 日期 YYYY-MM-DD |
769
- | `--url / --final-url` | — | 落地页 |
770
- | `--path1 / --path2` | — | 展示路径 |
771
- | `--status` | — | Enabled \| Paused |
772
- | `--draft` | — | 仅保存草稿 |
773
- | `--config-file <path>` | — | JSON 配置文件路径(AI 推荐) |
774
-
775
- **典型用法(简单场景):**
258
+ 支持两种模式:
259
+ - 默认:直接发布(`DraftStatus: Published`)
260
+ - `--draft`:仅保存草稿,需后续 `ad batch publish`
261
+
262
+ 广告组/关键词/创意的分步创建用 `adgroup-create`、`keyword-create`、`ad-create`。
263
+
264
+ ### --config-file(推荐)
265
+
266
+ 复杂参数时优先使用 JSON 配置文件:避免 shell 转义问题,`headlines` 元素内允许含逗号。
267
+
268
+ **步骤:** 1) Write 工具写 JSON → 2) `siluzan-tso ad campaign-create --config-file /path/to/config.json` → 3) `ad batch get --id <taskId>` 查进度
269
+
270
+ 完整 Schema 见 `assets/campaign-create-template.json`。
271
+
272
+ **核心字段:**
273
+
274
+ | 字段 | 必填 | 类型 | 说明 |
275
+ | --- | --- | --- | --- |
276
+ | `account` | ✅ | string | Google mediaCustomerId |
277
+ | `customerName` | ✅ | string | 账户名称 |
278
+ | `name` | ✅ | string | 广告系列名称 |
279
+ | `budget` | | number | 日预算,主币种金额 |
280
+ | `bidding` | | string | `TARGET_SPEND` / `MANUAL_CPC` / `TARGET_CPA` / `TARGET_ROAS` |
281
+ | `locationIds` | ✅ | string[] | 地理位置 ID(`ad geo search` 获取) |
282
+ | `adgroupName` | ✅ | string | 第一个广告组名称 |
283
+ | `maxCpc` | ✅ | number | 最高 CPC,主币种金额 |
284
+ | `bidCeiling` | ✅ | number | TARGET_SPEND 出价上限 |
285
+ | `targetCpa` | ✅ | number | TARGET_CPA 目标 CPA |
286
+ | `targetRoas` | ✅ | number | TARGET_ROAS(如 2.5) |
287
+ | `languageIds` | ✅ | string[] | 默认 `["1000"]`=英语,中文=`"1017"` |
288
+ | `startDate`/`endDate` | ✅ | string | YYYY-MM-DD |
289
+ | `url` | | string | 落地页 |
290
+ | `status` | | string | `Enabled` / `Paused` |
291
+ | `matchType` | ✅ | string | `BROAD` / `PHRASE` / `EXACT` |
292
+ | `keywords` | ✅ | string[] | 第一个广告组关键词 |
293
+ | `headlines` | ✅ | string[] | ≥3 条,≤30 字符,元素内允许逗号 |
294
+ | `descriptions` | ✅ | string[] | ≥2 条,≤90 字符 |
295
+ | `finalUrl` | ✅ | string | 广告落地页 |
296
+ | `path1`/`path2` | ✅ | string | ≤15 字符 |
297
+ | `productWords` | ✅ | string[] | 推广产品词 |
298
+ | `negativeKeywords` | ✅ | string[] | 否定关键词 |
299
+ | `extensions` | | array | 附加功能(CALL/SITELINK/STRUCTURED_SNIPPET |
300
+ | `extraAdGroups` | | array | 额外广告组 |
301
+ | `draft` | | boolean | `true`=仅保存草稿 |
302
+
303
+ ### 命令行传参(简单场景)
776
304
 
777
305
  ```bash
778
- # 前置:搜索投放地区 ID
779
- siluzan-tso ad geo search -a 6326027735 -q "United States"
780
- # 取出 id 字段,如 2840
781
-
782
- # 一体化创建(CLI 直接传参,适合参数较少的场景)
783
306
  siluzan-tso ad campaign-create \
784
- -a 6326027735 \
785
- --customer-name "测试账户" \
786
- --name "搜索-跑步鞋-2026" \
787
- --budget 100 \
788
- --bidding TARGET_SPEND \
789
- --location-ids 2840 \
790
- --adgroup-name "核心词_跑步鞋" \
791
- --max-cpc 5 \
792
- --url "https://www.brand-a.com/running-shoes" \
793
- --keywords "running shoes,sport shoes,trail running" \
794
- --headlines "Brand Running Shoes,Lightweight Design,Direct Factory Price" \
795
- --descriptions "Trusted by millions worldwide.,Free shipping and 30-day returns." \
796
- --final-url "https://www.brand-a.com/running-shoes" \
797
- --path1 "running" \
798
- --path2 "shoes"
799
-
800
- # 查看创建进度
801
- siluzan-tso ad batch get --id <taskId>
802
- ```
803
-
804
- **典型用法(AI 推荐,config-file 方式):**
805
-
806
- ```bash
807
- # 1. AI 先写好 JSON 配置文件(使用 Write 工具)
808
- # 2. 执行创建
809
- siluzan-tso ad campaign-create --config-file /tmp/campaign-config.json
810
-
811
- # 3. 查看进度
812
- siluzan-tso ad batch get --id <返回的taskId>
307
+ -a <accountId> --customer-name <name> --name <name> \
308
+ --budget <主币种> --bidding <策略> --location-ids <ids> \
309
+ --adgroup-name <name> --max-cpc <主币种> \
310
+ [--keywords <kws>] [--headlines <titles>] [--descriptions <descs>] \
311
+ [--url/--final-url <url>] [--path1/--path2 <path>] \
312
+ [--negative-keywords <kws>] [--product-words <words>] \
313
+ [--extensions-json <json>] [--extra-adgroups-json <json>] \
314
+ [--lang-ids <ids>] [--bid-ceiling/--target-cpa/--target-roas <n>] \
315
+ [--start/--end <date>] [--status Enabled|Paused] [--draft] \
316
+ [--config-file <path>]
813
317
  ```
318
+ > `--headlines` 中不能含逗号,含逗号请用 `--config-file`。
814
319
 
815
320
  ---
816
321
 
@@ -818,425 +323,131 @@ siluzan-tso ad batch get --id <返回的taskId>
818
323
 
819
324
  ```bash
820
325
  siluzan-tso ad campaign-edit \
821
- -a <accountId> \
822
- --id <campaignId> \
823
- [--name <新名称>] \
824
- [--budget <主币种金额>] \
825
- [--bidding <出价策略>] \
826
- [--bid-ceiling <主币种金额>] \
827
- [--target-cpa <主币种金额>] \
828
- [--search-network true|false] \
829
- [--content-network true|false]
830
- ```
831
-
832
- > **金额单位(必读)**:所有金额参数均按 **主币种金额**(如 `100` 表示 ¥100,支持小数 `10.5`)传入;CLI 内部 `Math.round(value × 100)` 写入后端「分」字段,与前端表单、`ad campaign-create`、`ad batch update` 完全一致。**禁止** 按 Google micros(×1,000,000)口径填写,会被后端按「分」解读,导致金额放大 10000 倍。
833
-
834
- | 选项 | 说明 |
835
- | ------------------- | ------------------------------------------------------------------------- |
836
- | `--name` | 新广告系列名称 |
837
- | `--budget` | 新日预算,主币种金额(如 `100` = ¥100;`10.5` = ¥10.50) |
838
- | `--bidding` | 出价策略:`TARGET_SPEND` \| `TARGET_CPA` \| `TARGET_ROAS` \| `MANUAL_CPC` |
839
- | `--bid-ceiling` | `TARGET_SPEND` 出价上限,主币种金额(`0` = 不限) |
840
- | `--target-cpa` | `TARGET_CPA` 目标 CPA,主币种金额 |
841
- | `--search-network` | 投放 Google 搜索:`true` \| `false` |
842
- | `--content-network` | 投放展示网络:`true` \| `false` |
843
-
844
- **示例:**
845
-
846
- ```bash
847
- # 修改名称和预算(日预算 ¥5000)
848
- siluzan-tso ad campaign-edit -a 6326027735 --id 23509626948 \
849
- --name "搜索-春季促销-2026" --budget 5000
850
-
851
- # 在原预算基础上 +10 元(典型相对运算流程):
852
- # 1) 先 `ad campaigns --json` 读出该系列 `budget`(已为**主币种元**)
853
- # 2) 计算新值(主币种)= budget + 10
854
- # 3) 把新值(主币种)作为 --budget 传入;CLI 内部自动 ×100 写入网关「分」
855
- siluzan-tso ad campaign-edit -a 6326027735 --id 23509626948 --budget 10.01
856
-
857
- # 切换出价策略为 TARGET_CPA,目标 CPA 2 USD
858
- siluzan-tso ad campaign-edit -a 6326027735 --id 23509626948 \
859
- --bidding TARGET_CPA --target-cpa 2
326
+ -a <accountId> --id <campaignId> \
327
+ [--name <新名称>] [--budget <主币种>] [--bidding <策略>] \
328
+ [--bid-ceiling <主币种>] [--target-cpa <主币种>] \
329
+ [--search-network true|false] [--content-network true|false]
860
330
  ```
331
+ 相对运算:先 `ad campaigns --json` 读 `budget`(已为主币种元),计算新值后传入。
861
332
 
862
333
  ---
863
334
 
864
335
  ## ad adgroup-rename — 广告组改名
865
336
 
866
337
  ```bash
867
- siluzan-tso ad adgroup-rename \
868
- -a <accountId> \
869
- --id <adGroupId> \
870
- --name <新名称>
871
- ```
872
-
873
- **示例:**
874
-
875
- ```bash
876
- siluzan-tso ad adgroup-rename -a 6326027735 --id 195548094874 --name "核心词_跑步鞋_改"
338
+ siluzan-tso ad adgroup-rename -a <accountId> --id <adGroupId> --name <新名称>
877
339
  ```
878
340
 
879
341
  ---
880
342
 
881
- ## ad ad-edit — 广告创意编辑(自适应搜索广告 RSA)
882
-
883
- 与网页端一致:先用 **`siluzan-tso ad list -a <accountId> [--start/--end] --json`** 取得该广告的完整 JSON,再用本命令只修改传入的选项;未改动的字段由 **`siluzan-tso`** 按列表原值带回。
884
-
885
- CLI 会自动附带数据权限相关请求头,减少权限类错误。
886
-
887
- ### `ad list --json` 常见键名与 CLI 选项(常用)
343
+ ## ad ad-edit — 广告创意编辑
888
344
 
889
- | 列表 JSON 键名 | 说明 | CLI |
890
- | --------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
891
- | `id` | 广告 ID | `--id` |
892
- | `activeuseridg` | 账户 mediaCustomerId | `-a` / `--account` |
893
- | `headlinePart1` / `headlinePart2` / `headlinePart3` | 前 3 条标题 | `--headlines` 前 3 项 |
894
- | `AddtionalHeadlines` | 第 4~15 条标题(历史拼写 Addtional) | `--headlines` 第 4 项起 |
895
- | `adDescription` / `adDescription2` | 前 2 条描述 | `--descriptions` 前 2 项 |
896
- | `AddtionalAdDescriptions` | 第 3~4 条描述 | `--descriptions` 第 3 项起 |
897
- | `finalUrl` | 落地页 | `--final-url` |
898
- | `path1` / `path2` | 显示路径 | `--path1` / `--path2` |
899
- | `adGroupId` / `adGroup` | 广告组 | 从列表结果保留,勿手改 |
900
- | `typeV2` | 广告类型 | 从列表保留(RSA 为 `RESPONSIVE_SEARCH_AD`) |
901
- | `statusV2` | `Enabled` / `Paused` | `--status Enabled` 或 `--status Paused` |
345
+ 先用 `ad list --json` 取得完整 JSON,再只修改传入字段,未改字段从列表原值带回。
902
346
 
903
- **约束:** 至少指定一项:`--headlines` / `--descriptions` / `--final-url` / `--path1` / `--path2` / `--status`。若传 `--headlines` 须 ≥3 条;若传 `--descriptions` 须 ≥2 条。
347
+ `ad list --json` 关键字段映射:
348
+ - `headlinePart1~3` + `AddtionalHeadlines` → `--headlines`(≥3条)
349
+ - `adDescription`/`adDescription2` + `AddtionalAdDescriptions` → `--descriptions`(≥2条)
350
+ - `finalUrl` → `--final-url`;`path1`/`path2` → `--path1`/`--path2`
351
+ - `statusV2` → `--status`;`typeV2`(RSA=`RESPONSIVE_SEARCH_AD`)从列表保留勿手改
904
352
 
905
353
  ```bash
906
354
  siluzan-tso ad ad-edit \
907
- -a <accountId> \
908
- --id <adId> \
909
- [--headlines "标题1,标题2,标题3,..."] \
910
- [--descriptions "描述1,描述2,..."] \
911
- [--final-url <落地页>] \
912
- [--path1 <路径1>] \
913
- [--path2 <路径2>] \
355
+ -a <accountId> --id <adId> \
356
+ [--headlines "标题1,标题2,..."] [--descriptions "描述1,描述2,..."] \
357
+ [--final-url <url>] [--path1 <p1>] [--path2 <p2>] \
914
358
  [--status Enabled|Paused]
915
359
  ```
916
-
917
- **示例:**
918
-
919
- ```bash
920
- # 只更新标题
921
- siluzan-tso ad ad-edit -a 6326027735 --id 795205788626 \
922
- --headlines "专业跑步鞋,轻量透气设计,品牌直销价,全球热销款,运动首选品牌"
923
-
924
- # 更新落地页
925
- siluzan-tso ad ad-edit -a 6326027735 --id 795205788626 \
926
- --final-url "https://www.brand-a.com/shoes-2026"
927
-
928
- # 仅暂停广告(与网页改状态一致,其余字段从列表原样带回)
929
- siluzan-tso ad ad-edit -a 6326027735 --id 802428202775 --status Paused
930
- ```
360
+ 至少指定一项。
931
361
 
932
362
  ---
933
363
 
934
364
  ## ad keyword-delete — 搜索关键词删除
935
365
 
936
- 先用 **`siluzan-tso ad keywords -a <accountId> … --json`** 取得关键词 **`id`** 与 **`adGroupId`**,再执行删除。成功时 CLI 正常结束;可用 **`ad keywords --json`** 再次核对列表。
937
-
938
- ```bash
939
- siluzan-tso ad keyword-delete \
940
- -a <accountId> \
941
- --id <keywordId> \
942
- --adgroup-id <adGroupId>
943
- ```
944
-
945
- > `--id` 与 `--adgroup-id` 来自 **`ad keywords --json`** 中的 **`id`**、**`adGroupId`**。
946
-
947
- **示例:**
948
-
949
366
  ```bash
950
367
  # 先查询获取 id 和 adGroupId
951
- siluzan-tso ad keywords -a 6326027735 --json
952
-
953
- # 然后删除
954
- siluzan-tso ad keyword-delete -a 6326027735 --id 2464982882313 --adgroup-id 195548094874
368
+ siluzan-tso ad keywords -a <accountId> --json
369
+ # 再删除
370
+ siluzan-tso ad keyword-delete -a <accountId> --id <keywordId> --adgroup-id <adGroupId>
955
371
  ```
956
372
 
957
373
  ---
958
374
 
959
375
  ## ad keyword-edit — 搜索关键词编辑
960
376
 
961
- 与网页一致:**先** **`siluzan-tso ad keywords --json`** 取该关键词完整对象,**再**用本命令提交修改;未改字段随列表结果保留。
962
-
963
- > **⚠️ 金额单位(与系列 / 组的金额字段不同!)**:关键词的 `maxCPC` 字段单位是 **「主币种元」**(直接是元,不是「分」),CLI 直接透传 **不做 ×100 转换**。这与 `ad campaign-edit --budget` / `ad adgroup-edit --max-cpc` 等"用户传元、CLI 内部 ×100"的命令**口径相反**。
964
- >
965
- > 验证依据:前端 `KeywordList.vue:266` 用 `filterSpend(maxCPC)` 直接展示原值,对应 `useFormatter.js:86` 的 `filterSpend` 内部不 ÷100(对比 `filterBudget` 显式 ÷100)。
966
-
967
- ### `ad keywords --json` 常见键名与 CLI 选项(常用)
968
-
969
- | 列表 JSON 键名 | 说明 | CLI |
970
- | ----------------------------- | ----------------------------------------- | ---------------------------- |
971
- | `id` | 关键词资源 id | `--id` |
972
- | `keywordText` | 关键词文案(数组,一般一项) | `--text` → `["..."]` |
973
- | `matchTypeV2` | 匹配类型(网页用 Broad / Phrase / Exact) | `--match-type` |
974
- | `matchType` | 另一套枚举(如 EXACT),列表里可能仍存在 | 一般随 list 结果保留,勿手改 |
975
- | `maxCPC` | 最高每次点击费用,**主币种金额**(直接是元,不要 ×100) | `--max-cpc` |
976
- | `finalURL` | 关键词级最终到达网址 | `--final-url` |
977
- | `adGroupId` / `campaignId` 等 | 层级与统计字段 | 从列表保留 |
978
-
979
- **注意:** 成功响应也可能是数组;**`id` 可能与请求不一致**。CLI 若检测到变化会打印提示,后续请用 **返回体中的新 `id`** 再查列表或再编辑。
980
-
981
- **约束:** `--text`、`--match-type`、`--max-cpc`、`--final-url` 至少传一项。
982
-
983
- **匹配类型与文案:** Google 网关 V2 根据 `keywordText` 上的 `"` / `[` `]` 推断实际 MatchType(会覆盖仅传的 `matchTypeV2`)。因此只要传 `--match-type`,CLI **默认**把 `keywordText` 规范为词干 / `"词干"` / `[词干]` 并写入 `matchTypeV2`,无需额外开关;仅改匹配时可不传 `--text`(用列表里的当前文案去外层括号后再包一层)。
377
+ 先用 `ad keywords --json` 取完整对象,再提交修改。`id` 可能与请求不一致,CLI 检测到变化会提示。
984
378
 
985
379
  ```bash
986
380
  siluzan-tso ad keyword-edit \
987
- -a <accountId> \
988
- --id <keywordId> \
989
- [--text <新关键词>] \
990
- [--match-type <Broad|Phrase|Exact>] \
991
- [--max-cpc <n>] \
992
- [--final-url <url>]
993
- ```
994
-
995
- **示例:**
996
-
997
- ```bash
998
- # 改匹配类型为精确匹配
999
- siluzan-tso ad keyword-edit -a 6326027735 --id 310074153549 --match-type Exact
1000
-
1001
- # 同时改文本和匹配类型
1002
- siluzan-tso ad keyword-edit -a 6326027735 --id 310074153549 \
1003
- --text "professional running shoes" --match-type Phrase
1004
-
1005
- # 与网页一致:改落地页与出价(maxCPC 为 0 时含义以 Google/平台为准)
1006
- siluzan-tso ad keyword-edit -a 6326027735 --id 2081924039951 \
1007
- --final-url "https://www-ci.siluzan.com" --max-cpc 0
381
+ -a <accountId> --id <keywordId> \
382
+ [--text <新关键词>] [--match-type Broad|Phrase|Exact] \
383
+ [--max-cpc <n>] [--final-url <url>]
1008
384
  ```
385
+ 传 `--match-type` 时 CLI 自动规范 `keywordText` 括号/引号格式。至少传一项。`--max-cpc` 为「主币种元」(见文首金额单位说明)。
1009
386
 
1010
387
  ---
1011
388
 
1012
389
  ## ad keyword-negative-edit — 否词编辑
1013
390
 
1014
- 与搜索词相同:传 `--match-type` 时 CLI 会默认同步改写 `keywordText` 外层括号/引号。
1015
-
1016
391
  ```bash
1017
392
  siluzan-tso ad keyword-negative-edit \
1018
- -a <accountId> \
1019
- --id <negativeKeywordId> \
1020
- [--text <新文本>] \
1021
- [--match-type <Broad|Phrase|Exact>]
1022
- ```
1023
-
1024
- **示例:**
1025
-
1026
- ```bash
1027
- siluzan-tso ad keyword-negative-edit -a 6326027735 --id 349349835545 \
1028
- --text "cheap shoes" --match-type Phrase
393
+ -a <accountId> --id <negativeKeywordId> \
394
+ [--text <新文本>] [--match-type Broad|Phrase|Exact]
1029
395
  ```
396
+ 传 `--match-type` 时 CLI 自动同步改写外层括号/引号。
1030
397
 
1031
398
  ---
1032
399
 
1033
400
  ## ad extension — 附加信息管理
1034
401
 
1035
- 附加信息(Ad Extensions)支持四种类型,**修改方式为先删后建**(无 PUT 编辑接口)。
1036
-
1037
- ### 查询附加信息列表
402
+ 修改方式为**先删后建**(无 PUT 接口)。
1038
403
 
1039
404
  ```bash
1040
- siluzan-tso ad extension list -a <accountId> [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET]
1041
- ```
405
+ # 查询
406
+ siluzan-tso ad extension list -a <accountId> [--type SITELINK|CALL|CALLOUT|STRUCTURED_SNIPPET] [--json]
1042
407
 
1043
- ### 添加附加链接(SITELINK)
408
+ # 附加链接
409
+ siluzan-tso ad extension sitelink -a <accountId> --text "文字" --url "https://..." \
410
+ [--line2/--line3 <text>] [--level Account|Campaign|AdGroup] [--campaign-id <id>]
1044
411
 
1045
- ```bash
1046
- siluzan-tso ad extension sitelink \
1047
- -a <accountId> \
1048
- --text "产品中心" \
1049
- --url "https://www.example.com/products" \
1050
- [--line2 "查看全系列产品"] \
1051
- [--line3 "限时优惠进行中"] \
1052
- [--level Account|Campaign|AdGroup] \
1053
- [--campaign-id <id>]
1054
- ```
1055
-
1056
- ### 添加附加电话(CALL)
1057
-
1058
- ```bash
1059
- siluzan-tso ad extension call \
1060
- -a <accountId> \
1061
- --country-code "+86" \
1062
- --phone "4008001234" \
412
+ # 附加电话
413
+ siluzan-tso ad extension call -a <accountId> --country-code "+86" --phone "4008001234" \
1063
414
  [--level Account|Campaign|AdGroup]
1064
- ```
1065
415
 
1066
- ### 添加附加宣传信息(CALLOUT,≤25 字符)
416
+ # 附加宣传信息(≤25字符)
417
+ siluzan-tso ad extension callout -a <accountId> --text "免费送货上门" [--level Account]
1067
418
 
1068
- ```bash
1069
- siluzan-tso ad extension callout \
1070
- -a <accountId> \
1071
- --text "免费送货上门" \
1072
- [--level Account]
1073
- ```
419
+ # 附加结构化摘要
420
+ siluzan-tso ad extension snippet -a <accountId> --header "Brands" --values "A,B,C" [--level Account]
1074
421
 
1075
- ### 添加附加结构化摘要(STRUCTURED_SNIPPET)
1076
-
1077
- ```bash
1078
- siluzan-tso ad extension snippet \
1079
- -a <accountId> \
1080
- --header "Brands" \
1081
- --values "品牌A,品牌B,品牌C" \
1082
- [--level Account]
1083
- ```
1084
-
1085
- > `--header` 常用值:`Brands` | `Services` | `Amenities` | `Types` | `Styles` | `Courses` | `Featured hotels` | `Neighborhoods` | `Destinations` | `Degree programs` | `Insurance coverage` | `Models`
1086
-
1087
- ### 删除附加信息
1088
-
1089
- ```bash
1090
- # 先查 id
1091
- siluzan-tso ad extension list -a 6326027735 --json
1092
-
1093
- # 再删除
1094
- siluzan-tso ad extension delete -a 6326027735 --id <extensionId>
422
+ # 删除
423
+ siluzan-tso ad extension delete -a <accountId> --id <extensionId>
1095
424
  ```
425
+ `--header` 常用值:`Brands`/`Services`/`Amenities`/`Types`/`Styles`/`Courses`/`Models` 等。
1096
426
 
1097
427
  ---
1098
428
 
1099
429
  ## ad search-terms — 搜索字词报告
1100
430
 
1101
- > 搜索字词为**只读报告**,不支持直接删除。若需屏蔽某个搜索词,先查到对应词,再通过 `keyword-negative-create` 将其加为否词。
431
+ 只读报告。屏蔽搜索词:先查到词,再用 `keyword-negative-create` 加否词。
1102
432
 
1103
433
  ```bash
1104
- siluzan-tso ad search-terms -a <accountId> [--start YYYY-MM-DD] [--end YYYY-MM-DD]
1105
- ```
1106
-
1107
- **示例:**
1108
-
1109
- ```bash
1110
- # 查询近 30 天搜索字词
1111
- siluzan-tso ad search-terms -a 6326027735
1112
-
1113
- # 查询指定区间
1114
- siluzan-tso ad search-terms -a 6326027735 --start 2026-03-01 --end 2026-03-23
1115
-
1116
- # JSON 输出(可获取 campaignId/adGroupId 用于添加否词)
1117
- siluzan-tso ad search-terms -a 6326027735 --json
1118
- ```
1119
-
1120
- **搜索字词转否词示例(屏蔽无效流量):**
1121
-
1122
- ```bash
1123
- # 1. 查到不想投放的搜索字词,记录其 campaignId 和 adGroupId
1124
- siluzan-tso ad search-terms -a 6326027735 --json
1125
-
1126
- # 2. 在广告系列层级将其加为否词
1127
- siluzan-tso ad keyword-negative-create \
1128
- -a 6326027735 \
1129
- --campaign-id 23509626948 \
1130
- --campaign-name "搜索-ces-1769764388" \
1131
- --keywords "不想要的词1,不想要的词2"
434
+ siluzan-tso ad search-terms -a <accountId> [--start/--end YYYY-MM-DD] [--json]
1132
435
  ```
1133
436
 
1134
437
  ---
1135
438
 
1136
439
  ## ad geo — 地理位置定向管理
1137
440
 
1138
- ### 搜索地理位置(获取 locationId)
1139
-
1140
441
  ```bash
442
+ # 搜索 locationId
1141
443
  siluzan-tso ad geo search -a <accountId> -q <地名>
1142
- ```
1143
-
1144
- ```bash
1145
- # 搜索中国
1146
- siluzan-tso ad geo search -a 6326027735 -q "China"
1147
-
1148
- # 搜索北京
1149
- siluzan-tso ad geo search -a 6326027735 -q "Beijing"
1150
- ```
1151
-
1152
- ### 查询已定向地理位置
1153
-
1154
- ```bash
1155
- # 查已定位(普通定向)
1156
- siluzan-tso ad geo list -a 6326027735 --mode targeted
1157
444
 
1158
- # 查已排除(否定定向)
1159
- siluzan-tso ad geo list -a 6326027735 --mode excluded
445
+ # 查询已定向
446
+ siluzan-tso ad geo list -a <accountId> --mode targeted|excluded|report [--start/--end <date>]
1160
447
 
1161
- # 查消耗报告(哪些地区产生了展示/点击)
1162
- siluzan-tso ad geo list -a 6326027735 --mode report --start 2026-03-01 --end 2026-03-23
1163
- ```
1164
-
1165
- ### 添加地理位置定向
1166
-
1167
- ```bash
1168
- # 添加普通定向(先 search 获取 locationId)
1169
- siluzan-tso ad geo add \
1170
- -a 6326027735 \
1171
- --campaign-id 23509626948 \
1172
- --location-id 2156 \
1173
- [--bid-modifier 1.2]
1174
-
1175
- # 添加排除定向
1176
- siluzan-tso ad geo add \
1177
- -a 6326027735 \
1178
- --campaign-id 23509626948 \
1179
- --location-id 1006093 \
1180
- --exclude
1181
- ```
1182
-
1183
- ### 删除地理位置定向
1184
-
1185
- ```bash
1186
- # 普通定向和排除定向均通过 geo remove 删除
1187
- siluzan-tso ad geo remove \
1188
- -a 6326027735 \
1189
- --campaign-id 23509626948 \
1190
- --location-id 2156
1191
- ```
1192
-
1193
- ---
448
+ # 添加定向
449
+ siluzan-tso ad geo add -a <accountId> --campaign-id <id> --location-id <id> [--bid-modifier 1.2] [--exclude]
1194
450
 
1195
- ## 完整操作示例:从零搭建 Google 广告
1196
-
1197
- 以下是一个完整的从头建立 Google 广告的操作示例:
1198
-
1199
- ```bash
1200
- # 第二步:查询账户, 确认用户信息
1201
- siluzan-tso list-accounts -m Google --json -k [mediaCustomerId]
1202
- # 假设 accountId = 6326027735
1203
-
1204
- # 第三步:查看现有广告系列,确认 campaign_id
1205
- siluzan-tso ad campaigns -a 6326027735 --json
1206
- # 假设 campaignId = campaign_001,campaignName = "品牌推广_春季"
1207
-
1208
- # 第四步:创建广告组(最高 CPC ¥1,主币种金额;CLI 内部 ×100 写入「分」)
1209
- siluzan-tso ad adgroup-create \
1210
- -a 6326027735 \
1211
- --campaign-id campaign_001 \
1212
- --campaign-name "品牌推广_春季" \
1213
- --name "核心词_跑步鞋" \
1214
- --max-cpc 1
1215
-
1216
- # 第五步:查询新建广告组 id
1217
- siluzan-tso ad groups -a 6326027735 --json
1218
- # 假设 adGroupId = adgroup_new,adGroupName = "核心词_跑步鞋"
1219
-
1220
- # 第六步:添加关键词
1221
- siluzan-tso ad keyword-create \
1222
- -a 6326027735 \
1223
- --campaign-id campaign_001 \
1224
- --campaign-name "品牌推广_春季" \
1225
- --adgroup-id adgroup_new \
1226
- --adgroup-name "核心词_跑步鞋" \
1227
- --keywords "跑步鞋,专业跑鞋,running shoes"
1228
-
1229
- # 第七步:创建广告创意
1230
- siluzan-tso ad ad-create \
1231
- -a 6326027735 \
1232
- --adgroup-id adgroup_new \
1233
- --adgroup-name "核心词_跑步鞋" \
1234
- --final-url "https://www.brand-a.com/running-shoes" \
1235
- --headlines "专业跑步鞋,轻量透气设计,品牌直销价" \
1236
- --descriptions "全球百万跑者信赖,专业助力每一步。,免费配送,30天无理由退换。" \
1237
- --path1 "跑步鞋" \
1238
- --path2 "特惠"
1239
-
1240
- # 第八步:验证广告已创建
1241
- siluzan-tso ad list -a 6326027735
451
+ # 删除
452
+ siluzan-tso ad geo remove -a <accountId> --campaign-id <id> --location-id <id>
1242
453
  ```