siluzan-tso-cli 1.1.24 → 1.1.25-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 +535 -140
- package/dist/skill/SKILL.md +4 -1
- package/dist/skill/_meta.json +2 -2
- package/dist/skill/assets/pmax-create-template.md +8 -8
- package/dist/skill/references/accounts/accounts.md +23 -17
- package/dist/skill/references/accounts/currency.md +1 -1
- package/dist/skill/references/accounts/finance.md +4 -4
- package/dist/skill/references/accounts/open-account-by-media.md +150 -14
- package/dist/skill/references/accounts/open-account-google-ui.md +2 -2
- package/dist/skill/references/analytics/account-analytics.md +35 -21
- package/dist/skill/references/analytics/rag.md +1 -1
- package/dist/skill/references/analytics/reporting.md +2 -2
- package/dist/skill/references/analytics/website-diagnosis-guide.md +9 -2
- package/dist/skill/references/core/agent-conventions.md +2 -0
- package/dist/skill/references/core/playbooks.md +3 -2
- package/dist/skill/references/core/setup.md +5 -5
- package/dist/skill/references/core/skill-authoring.md +1 -1
- package/dist/skill/references/core/workflows.md +15 -13
- package/dist/skill/references/operations/hosted-automation-monitoring-json.md +1 -1
- package/dist/skill/references/operations/hosted-automation-optimize-scale.md +2 -2
- package/dist/skill/references/operations/hosted-automation-self-control.md +1 -1
- package/dist/skill/report-templates/README.md +1 -1
- package/dist/skill/report-templates/REPORT-WORKFLOW.md +5 -0
- package/dist/skill/report-templates/google-account-diagnosis-report.md +7 -0
- package/dist/skill/report-templates/google-ads-diagnosis.md +51 -2
- package/dist/skill/report-templates/google-inquiry-analysis.md +8 -8
- package/dist/skill/report-templates/google-period-report.md +2 -2
- package/dist/skill/report-templates/okki-weekly-google-client.md +4 -4
- package/dist/skill/report-templates/report-template.html +1 -0
- package/dist/skill/report-templates/website-diagnosis-report.html +450 -36
- package/dist/skill/report-templates/website-diagnosis-report.md +6 -5
- package/dist/skill/scripts/install.ps1 +3 -3
- package/dist/skill/scripts/install.sh +3 -3
- package/package.json +1 -1
|
@@ -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 步：让用户报出手机号后，立刻发码（命令立即返回，不会等待输入）
|
|
@@ -129,9 +129,9 @@ siluzan-tso config show
|
|
|
129
129
|
|
|
130
130
|
```
|
|
131
131
|
构建环境 : production
|
|
132
|
-
apiBaseUrl : https://tso-api.siluzan.com
|
|
133
|
-
googleApiUrl : https://googleapi.mysiluzan.com
|
|
134
|
-
webUrl : https://www.siluzan.com
|
|
132
|
+
apiBaseUrl : https://tso-api-ci.siluzan.com
|
|
133
|
+
googleApiUrl : https://googleapi-ci.mysiluzan.com
|
|
134
|
+
webUrl : https://www-ci.siluzan.com
|
|
135
135
|
apiKey : abcd****1234
|
|
136
136
|
```
|
|
137
137
|
|
|
@@ -53,7 +53,7 @@ siluzan-tso/ # 安装后目录名
|
|
|
53
53
|
|
|
54
54
|
- 从 SKILL.md **只链接一层**（`references/foo.md`），避免 A→B→C 链式引用。
|
|
55
55
|
- 路径用正斜杠，不用 Windows 反斜杠。
|
|
56
|
-
- 占位符 `https://www.siluzan.com`、`https://tso-api.siluzan.com`、`npm install -g siluzan-tso-cli` 由构建脚本替换，文档中禁止硬编码环境 URL。
|
|
56
|
+
- 占位符 `https://www-ci.siluzan.com`、`https://tso-api-ci.siluzan.com`、`npm install -g siluzan-tso-cli@beta` 由构建脚本替换，文档中禁止硬编码环境 URL。
|
|
57
57
|
|
|
58
58
|
---
|
|
59
59
|
|
|
@@ -30,9 +30,9 @@
|
|
|
30
30
|
|
|
31
31
|
## 流程一：新账户开通（Google / TikTok / Yandex / Bing / Kwai）
|
|
32
32
|
|
|
33
|
-
**主文档**：`references/accounts/open-account-by-media.md
|
|
33
|
+
**主文档**：`references/accounts/open-account-by-media.md`。Google 开户字段见 `accounts/open-account-google-ui.md`。
|
|
34
34
|
|
|
35
|
-
> **AI Agent 注意**：`open-account google-wizard` 需要真实 TTY，Agent
|
|
35
|
+
> **AI Agent 注意**：`open-account google-wizard` 需要真实 TTY，Agent 环境无法使用，始终用非交互命令。用户**第一次**提出开户时，必须先输出 `open-account-by-media.md` 中的完整必填清单，再收集资料或提交。
|
|
36
36
|
|
|
37
37
|
以下保留完整示例供 workflows 内联阅读；维护时以 `accounts/open-account-by-media.md` 为准。
|
|
38
38
|
|
|
@@ -78,9 +78,9 @@ siluzan-tso list-accounts -m Google
|
|
|
78
78
|
|
|
79
79
|
### TikTok 开户
|
|
80
80
|
|
|
81
|
-
|
|
81
|
+
**必填清单**：见 `open-account-by-media.md` § TikTok（含法人银联四项；币种 CLI 固定 USD）。
|
|
82
82
|
|
|
83
|
-
> **执照 OCR 提示**：网页上传执照图片后系统会自动 OCR
|
|
83
|
+
> **执照 OCR 提示**：网页上传执照图片后系统会自动 OCR。CLI 不做 OCR，需用户手动提供 `--company` 和 `--license-no`。
|
|
84
84
|
|
|
85
85
|
```bash
|
|
86
86
|
# 前置：查询注册地合法代码（如不确定）
|
|
@@ -96,13 +96,16 @@ siluzan-tso open-account tiktok-timezones --keyword Shanghai
|
|
|
96
96
|
siluzan-tso open-account tiktok \
|
|
97
97
|
--company "Brand A Inc." \
|
|
98
98
|
--account-name "品牌A TikTok账户" \
|
|
99
|
-
--currency USD \
|
|
100
99
|
--timezone "Asia/Shanghai" \
|
|
101
100
|
--industry-id <tiktok-industries 输出的叶子节点 ID> \
|
|
102
101
|
--registered-area CN \
|
|
103
102
|
--promotion-link "https://www.brand-a.com" \
|
|
104
103
|
--license-no "91440300XXXXXXXXXX" \
|
|
105
|
-
--license-file "/path/to/license.jpg"
|
|
104
|
+
--license-file "/path/to/license.jpg" \
|
|
105
|
+
--representative-name "张三" \
|
|
106
|
+
--representative-id "440300XXXXXXXXXXXXXXXXX" \
|
|
107
|
+
--unionpay-account "6222XXXXXXXXXXXX" \
|
|
108
|
+
--representative-phone "13800138000"
|
|
106
109
|
|
|
107
110
|
# 轮询审核进度
|
|
108
111
|
siluzan-tso account-history -m TikTok
|
|
@@ -112,18 +115,14 @@ siluzan-tso account-history -m TikTok
|
|
|
112
115
|
|
|
113
116
|
### Yandex 开户
|
|
114
117
|
|
|
115
|
-
|
|
118
|
+
**必填清单**：公司名、邮箱、税号（TIN）——见 `open-account-by-media.md` § Yandex。
|
|
116
119
|
|
|
117
120
|
```bash
|
|
118
121
|
# 提交开户（CLI 自动按公司名创建/关联广告主组，无需 magKey）
|
|
119
122
|
siluzan-tso open-account yandex \
|
|
120
123
|
--company "Brand A Inc." \
|
|
121
|
-
--login "brandainc_yandex" \
|
|
122
|
-
--first-name "San" \
|
|
123
|
-
--last-name "Zhang" \
|
|
124
124
|
--email "contact@brand-a.com" \
|
|
125
|
-
--tin "XXXXXXXXXX"
|
|
126
|
-
--phone "+86XXXXXXXXXXX"
|
|
125
|
+
--tin "XXXXXXXXXX"
|
|
127
126
|
|
|
128
127
|
# 轮询审核进度
|
|
129
128
|
siluzan-tso account-history -m Yandex
|
|
@@ -133,7 +132,7 @@ siluzan-tso account-history -m Yandex
|
|
|
133
132
|
|
|
134
133
|
### BingV2 开户
|
|
135
134
|
|
|
136
|
-
|
|
135
|
+
**必填清单**：见 `open-account-by-media.md` § BingV2（含 `--pattern`、`--name-remark-list`、`--postcode`）。
|
|
137
136
|
|
|
138
137
|
```bash
|
|
139
138
|
# 前置：查询行业名称（将输出的 name 值传给 --trade-id）
|
|
@@ -141,11 +140,14 @@ siluzan-tso open-account bing-industries --keyword "科技"
|
|
|
141
140
|
|
|
142
141
|
# 提交开户（CLI 自动按公司名创建/关联广告主组，无需 magKey）
|
|
143
142
|
siluzan-tso open-account bing \
|
|
143
|
+
--pattern Direct \
|
|
144
144
|
--advertiser-name "深圳XX科技有限公司" \
|
|
145
145
|
--name-short "XX科技" \
|
|
146
|
+
--name-remark-list "XX科技-推广户" \
|
|
146
147
|
--province "广东省" \
|
|
147
148
|
--city "深圳市" \
|
|
148
149
|
--address "南山区科技园XX路XX号XX大厦" \
|
|
150
|
+
--postcode "518000" \
|
|
149
151
|
--promotion-link "https://www.brand-a.com" \
|
|
150
152
|
--trade-id "IT/消费电子-其他" \
|
|
151
153
|
--license-file "/path/to/license.jpg"
|
|
@@ -71,7 +71,7 @@ mkdir -p ./snap-monitor && siluzan-tso google-analysis -a <mediaCustomerId> --se
|
|
|
71
71
|
mkdir -p ./snap-monitor && siluzan-tso google-analysis -a <mediaCustomerId> --sections final-urls --json-out ./snap-monitor
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
读 **`./snap-monitor/final-urls.json
|
|
74
|
+
读 **`./snap-monitor/final-urls.json`**。`final-urls` 为**汇总维度**，整块对象在 **`record`**（`schemaVersion 3` 起；`items` 为 `[]`）：`record` 的**键名**为网关返回的资源标识（以当次 JSON 为准），**值为字符串数组**（每个元素是一条最终到达网址）。CLI **不**代发 HTTP 请求判断 4xx/5xx；死链判定须在宿主对 URL 执行 HEAD/GET（注意频率与 robots/合规）。
|
|
75
75
|
|
|
76
76
|
**按创意行拉数**（可与拒审、启停共用一轮数据）：
|
|
77
77
|
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
mkdir -p ./snap-scale && siluzan-tso google-analysis -a <mediaCustomerId> --sections campaigns --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json-out ./snap-scale
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
读 **`./snap-scale/campaigns-<accountId>.json`**（具体路径见 stdout 摘要的 `writtenFiles[0]` 或 `manifest-<accountId>.json` 的 `artifacts
|
|
21
|
+
读 **`./snap-scale/campaigns-<accountId>.json`**（具体路径见 stdout 摘要的 `writtenFiles[0]` 或 `manifest-<accountId>.json` 的 `artifacts`）。系列行在 **`items[]`**（`schemaVersion 3` 统一信封），单行关注（键名以当次落盘 JSON 为准）：
|
|
22
22
|
|
|
23
23
|
- **`conversionsValuePerCost`**（与 Google「转化价值/费用」语义一致，作 ROAS 代理）
|
|
24
24
|
- **`searchBudgetLostImpressionShare`**、**`searchRankLostImpressionShare`**、**`searchImpressionShare`**
|
|
@@ -40,7 +40,7 @@ siluzan-tso ad campaigns -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-M
|
|
|
40
40
|
mkdir -p ./snap-scale && siluzan-tso google-analysis -a <mediaCustomerId> --sections campaign-hour --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json-out ./snap-scale
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
读 **`./snap-scale/campaign-hour.json
|
|
43
|
+
读 **`./snap-scale/campaign-hour.json`**。行在 **`items[]`**：**`campaignId`**、**`date`**、**`hour`**、**`spend`**。宿主可做「近若干小时花费 vs 预期」的辅助条件。
|
|
44
44
|
|
|
45
45
|
### 4. 条件示例（仅示意）
|
|
46
46
|
|
|
@@ -125,7 +125,7 @@ siluzan-tso ad adgroup-edit -a <mediaCustomerId> --id <adGroupId> --max-cpc <主
|
|
|
125
125
|
|
|
126
126
|
见 **`references/google-ads/google-ads.md`**「广告组编辑」。
|
|
127
127
|
|
|
128
|
-
写前**必须**先 **`ad groups --json-out ./snap` / `ad campaigns --json-out ./snap`** 取当前值，**读取主币种金额**：组侧读 `maxCPCAmountYuan` / `targetCpaAmountYuan`（元）；系列列表侧 `ad campaigns` 的 `budget` 也是元（与写参 `--budget` 一致）；`google-analysis campaigns-*.json` 的 `budgetAmountYuan` 同。在宿主内按主币种算新值（如下调 12%：`newYuan = round(oldYuan * 0.88 * 100) / 100`），再以主币种金额作为 `--target-cpa` / `--max-cpc` / `--budget` 传回。
|
|
128
|
+
写前**必须**先 **`ad groups --json-out ./snap` / `ad campaigns --json-out ./snap`** 取当前值，**读取主币种金额**：组侧读 `maxCPCAmountYuan` / `targetCpaAmountYuan`（元）；系列列表侧 `ad campaigns` 的 `budget` 也是元（与写参 `--budget` 一致）；`google-analysis campaigns-*.json` 的 `items[]` 行 `budgetAmountYuan` 同。在宿主内按主币种算新值（如下调 12%：`newYuan = round(oldYuan * 0.88 * 100) / 100`），再以主币种金额作为 `--target-cpa` / `--max-cpc` / `--budget` 传回。
|
|
129
129
|
**严禁** 自己再做 `÷100` / `÷1_000_000` 换算——`*Yuan` 字段已经是元，再换算就是错的。
|
|
130
130
|
|
|
131
131
|
### 写后复核
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
|
|
18
18
|
| `google-period-report.md` | Google 账户分析报告（周期/月度/诊断均用此模板） |
|
|
19
19
|
| `google-account-diagnosis-report.md` | Google 账户深度诊断（健康度/转化/结构等） |
|
|
20
|
-
| `google-ads-diagnosis.md` | Google
|
|
20
|
+
| `google-ads-diagnosis.md` | Google **广告诊断**完整纲要（HTML 区块、**每日趋势 2 位小数**、**每模块必填分析/建议**） |
|
|
21
21
|
| `meta-period-report.md` | Meta（Facebook）周期报告（`facebook-analysis`，对齐 Google 周期章节能 cover 部分） |
|
|
22
22
|
| `meta-account-diagnosis-report.md` | Meta（Facebook）诊断报告（在 7 Section 内对齐 Google 诊断结构） |
|
|
23
23
|
| `tiktok-period-report.md` | TikTok 广告主周期报告 |
|
|
@@ -58,6 +58,11 @@
|
|
|
58
58
|
- 最后写**优化建议**（基于已有数据，不额外拉数）。
|
|
59
59
|
- 可选：按 `report-template*.html` 选择 HTML 样式输出（未指定时默认 `report-template.html`）。
|
|
60
60
|
|
|
61
|
+
**Google 广告诊断报告**（`google-ads-diagnosis.md` / `google-account-diagnosis-report.md`）额外必遵：
|
|
62
|
+
|
|
63
|
+
1. **每日趋势**（`daily-metrics` / `conversionCost`）：金额、CPA **2 位小数**；转化/点击/展示为整数；图表轴与 tooltip 同规则。
|
|
64
|
+
2. **每个模块**在表/图后写 **分析**（≥2 条，有数据依据）+ **建议**（≥1 条）；禁止只贴表不写分析。详见 `google-ads-diagnosis.md` § 撰写硬约束。
|
|
65
|
+
|
|
61
66
|
---
|
|
62
67
|
|
|
63
68
|
### 步骤 6：末尾附数据来源（可选）
|
|
@@ -5,6 +5,13 @@
|
|
|
5
5
|
|
|
6
6
|
按章节组织结论与建议；各节所需数据与建议 CLI 如下（**`google-analysis` 子命令请使用 `--json-out <目录>`** 落盘，脚本读磁盘 JSON 再写入报告）。
|
|
7
7
|
|
|
8
|
+
**完整章节结构、HTML 区块 ID、分析/建议必填规则、每日趋势小数格式** → 必读同目录 **`google-ads-diagnosis.md` § 撰写硬约束**（产品验收）。
|
|
9
|
+
|
|
10
|
+
### 撰写要点（摘要）
|
|
11
|
+
|
|
12
|
+
1. **每日趋势**（§7 / `daily-metrics`）：金额、CPA **保留 2 位小数**；展示/点击/转化用整数；图表 tooltip 同规则。
|
|
13
|
+
2. **每一章**除表格外须有 **分析**（≥2 条）+ **建议**（≥1 条）；禁止只罗列数据。
|
|
14
|
+
|
|
8
15
|
---
|
|
9
16
|
|
|
10
17
|
## 1. 账户画像与落地页
|
|
@@ -1,7 +1,52 @@
|
|
|
1
1
|
# Google Ads 账户诊断报告
|
|
2
2
|
|
|
3
3
|
> 账户诊断报告纲要：配合 `google-analysis` CLI 拉数后填充。
|
|
4
|
-
> 占位符：`{reportDate}` `{companyName}` `{period}` 等。
|
|
4
|
+
> 占位符：`{reportDate}` `{companyName}` `{period}` 等。
|
|
5
|
+
> 与 `google-account-diagnosis-report.md`（章节与 CLI 对照）配合使用；**撰写与验收以本节「硬约束」为准**。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 撰写硬约束（产品验收 · 必遵）
|
|
10
|
+
|
|
11
|
+
### 1. 数值格式（含「每日趋势」）
|
|
12
|
+
|
|
13
|
+
| 类型 | 规则 | 示例 |
|
|
14
|
+
| ---- | ---- | ---- |
|
|
15
|
+
| 金额类（消耗、CPA、CPC、预算等） | **保留 2 位小数**，带货币 | `￥1,234.56 CNY` |
|
|
16
|
+
| 展示、点击、转化次数 | **整数**，不写长小数 | `1,280` 而非 `1280.000000` |
|
|
17
|
+
| 比率（CTR、CVR、环比%） | JSON 为 0~1 小数时，展示 `(v×100).toFixed(2)+'%'` | `0.0523` → `5.23%` |
|
|
18
|
+
| **每日趋势 / 转化成本曲线** | 数据源：`daily-metrics` 或 `conversionCost.items`（`date`、`cost`、`cpa`、`conversions` 等） | 见下 |
|
|
19
|
+
|
|
20
|
+
**每日趋势表与图（§3.5 转化成本 / 按日趋势）**：
|
|
21
|
+
|
|
22
|
+
- 表格中：`cost`、`cpa`、`averageCpc` 等金额 → **`Number(v).toFixed(2)`**（或千分位 + 2 位小数）。
|
|
23
|
+
- 表格中：`conversions`、`clicks`、`impressions` → **整数**。
|
|
24
|
+
- ECharts / Chart.js：Y 轴与 tooltip 对金额类 **最多 2 位小数**；禁止 `12.3456789` 类展示。
|
|
25
|
+
- 脚本示例（Node）：`const money = (n) => Number(n).toFixed(2);` `const int = (n) => Math.round(Number(n));`
|
|
26
|
+
|
|
27
|
+
### 2. 每个模块必须有「分析」（禁止只贴表）
|
|
28
|
+
|
|
29
|
+
除「页眉」「导航」外，**每一个业务模块**（对应 `section-*` 或下文章节 §02~§12）在数据表/图之后**必须**包含：
|
|
30
|
+
|
|
31
|
+
1. **分析**（`### 分析` 或 `insight-title analysis-title`）：≥2 条要点，写清**现象 + 依据字段**（如「CPA 由 85.2 升至 112.40，峰值出现在 3/15」），禁止空泛套话。
|
|
32
|
+
2. **建议**（`### 建议` / `### 优化建议`）：≥1 条可执行项，与上文分析对应。
|
|
33
|
+
|
|
34
|
+
| 模块 | 数据对象 | 分析字段（优先写入报告） |
|
|
35
|
+
| ---- | -------- | ------------------------ |
|
|
36
|
+
| §02 诊断概览 | `diagnosisOverview` | 优势/不足每条已有描述，可补充 1 句总评 |
|
|
37
|
+
| §03 核心指标 | `metrics` | `metrics.analysis`、`metrics.suggestions`；**无则 Agent 根据 JSON 撰写，禁止省略** |
|
|
38
|
+
| §03.5 系列/地域/词/按日 | `campaigns`、`geographic`、`keywords`、`conversionCost` | 各对象的 `analysis`、`suggestions`；**按日趋势**另须结合曲线写 2 条趋势分析 |
|
|
39
|
+
| §04 黄金账户 | `goldAccount` | 未达标项归纳 + 修复优先级 |
|
|
40
|
+
| §05 预算竞争力 | `budgetCompetitiveness` | 每项 IS/份额与标准对比后的结论 |
|
|
41
|
+
| §06 定向策略 | `fullGeographic`、`fullDevice`、`fullAudience`、`fullCustomAudience` | 各维 `analysis`、`suggestions`（无数据则写「本期无数据」+ 原因，**仍须有建议**） |
|
|
42
|
+
| §07 着陆页 | `landingPageAnalysis` | 未达标项与行动优先级 |
|
|
43
|
+
| §08 关键词/搜索词 | `fullKeywords`、`fullSearchTerms`、`broadKeywordsCount` | 各块 `analysis`、`suggestions` |
|
|
44
|
+
| §09 出价策略 | `biddingStrategy` | 有问题系列逐条说明 |
|
|
45
|
+
| §10 创意 | `adCreativeOptimization` | `analysis`、`suggestions` |
|
|
46
|
+
| §11 新产品 | `newFeatures` | 未启用功能的建议 |
|
|
47
|
+
| §12 总结 | `summary` | `keyIssues`、`optimizationRoadmap` |
|
|
48
|
+
|
|
49
|
+
> HTML 报告对齐 `GoogleAdsDiagnosisReport.html` 时：有 `*.analysis` / `*.suggestions` 数组的，**必须渲染**「分析」「建议」区块；禁止只渲染表格/图表。
|
|
5
50
|
|
|
6
51
|
---
|
|
7
52
|
|
|
@@ -132,7 +177,11 @@
|
|
|
132
177
|
|
|
133
178
|
#### 转化成本 / 按日趋势（若页面已渲染）
|
|
134
179
|
|
|
135
|
-
- **数据**：`conversionCost.items
|
|
180
|
+
- **数据**：`conversionCost.items` 或 `daily-metrics` 落盘数组（含 `date`、`cost`、`cpa`、`conversions`、`clicks` 等）。
|
|
181
|
+
- **表格**：日期 | 消耗（2 位小数）| 转化（整数）| CPA（2 位小数）— 见上文「每日趋势」格式。
|
|
182
|
+
- **图表**：折线/双轴图；tooltip 金额 **2 位小数**。
|
|
183
|
+
- **分析（必填）**：至少 2 条，例如「周内 CPA 波动区间」「转化高峰日 vs 消耗高峰日是否一致」。
|
|
184
|
+
- **建议（必填）**：至少 1 条（调价/预算/排查追踪等）。
|
|
136
185
|
|
|
137
186
|
---
|
|
138
187
|
|
|
@@ -89,7 +89,7 @@ for month in <S月, S+1月, E月>:
|
|
|
89
89
|
**说明**：
|
|
90
90
|
|
|
91
91
|
- **禁止**用 `daily-metrics` 填 Sheet 4 上区：该维度走 TSO 主平台 `account-daily-reports`，与 Google 前台 / Web 分析（`CampaignSectionData`）**不同数据源**，产品已确认存在不可接受偏差。
|
|
92
|
-
- **Sheet 4 上区（账户月汇总）**：读 `./<YYYY-MM>/campaigns-*.json`，对 `
|
|
92
|
+
- **Sheet 4 上区（账户月汇总）**：读 `./<YYYY-MM>/campaigns-*.json`，对 `items[]`（`schemaVersion 3` 行统一在 `items`）**全系列求和**得到当月账户级点击/展示/费用/转化，再算 CTR/CPC/CPA/CVR（公式见下文 Sheet 4）；与 Google「广告系列」页同区间加总口径一致。
|
|
93
93
|
- `./snap-inquiry/campaigns-<accountId>_<S>-<E>.json`（步骤 2，整段 S~E）：仅用于 **Sheet 5** 系列明细；**不得**用它按月拆行填 Sheet 4。
|
|
94
94
|
- `geographic`：账户级国家聚合；Sheet 6 与 Sheet 4 **下区**（重点国切片）按月目录读取。
|
|
95
95
|
- `keywords` / `search-terms`：Sheet 7 / 8；默认拉取**全部有消耗**行（`keywords` 网关 `costGreater=0`，`limit=0` 不封顶）；需 TOP N 时加 `--limit <n>`。
|
|
@@ -186,7 +186,7 @@ Sheet 5 整段系列明细读：`./snap-inquiry/campaigns-<accountId>_<S>-<E>.js
|
|
|
186
186
|
### 数值格式（强约束）
|
|
187
187
|
|
|
188
188
|
- **金额、CPL / CPA / CPC / 平均费用**：保留 **2 位小数**，写明货币代码（如 `¥123.45 CNY`）。
|
|
189
|
-
- **点击率 / 转化率 / 互动率**（`ctr` / `conversionRate` / `interactionRate`）：CLI 已归一为 **0~1 小数**（schemaVersion
|
|
189
|
+
- **点击率 / 转化率 / 互动率**（`ctr` / `conversionRate` / `interactionRate`）：CLI 已归一为 **0~1 小数**（schemaVersion ≥ 2），写入 Excel 时**直接写 0~1**（与运营样表对齐，Excel 单元格用百分比格式自动渲染）。话术 `x%` 用 `(v * 100).toFixed(2) + "%"`。
|
|
190
190
|
- **空值**：`interactions === 0` 时「平均费用」「互动率」填 `—`，**禁止**除零。
|
|
191
191
|
|
|
192
192
|
### 分析输出区位置（**全局硬约束**）
|
|
@@ -317,14 +317,14 @@ Sheet 5 整段系列明细读：`./snap-inquiry/campaigns-<accountId>_<S>-<E>.js
|
|
|
317
317
|
| 项 | 约定 |
|
|
318
318
|
| --- | --- |
|
|
319
319
|
| 数据源 | `./snap-inquiry/<YYYY-MM>/campaigns-<accountId>_<月1号>-<月末>.json`（每月单独拉 `campaigns`；见「落盘防覆盖」） |
|
|
320
|
-
| 聚合范围 | 该月内 **全部** `
|
|
320
|
+
| 聚合范围 | 该月内 **全部** `items[]` 行（`schemaVersion 3` 行统一在 `items`；含已暂停但在区间内有消耗的系列；**禁止**只取 Top N 或手工筛系列） |
|
|
321
321
|
| 数据口径 | `google-analysis campaigns` 与账户月表一致；账户月表 = 各系列在当月起止日内指标之和 |
|
|
322
322
|
| 禁止 | `daily-metrics` / `stats` / `overview` 填上区投放列（询盘列仍来自 `inquiries.json`） |
|
|
323
323
|
|
|
324
324
|
**脚本聚合（每月一份 `campaigns-*.json`）**：
|
|
325
325
|
|
|
326
326
|
```text
|
|
327
|
-
rows = payload.
|
|
327
|
+
rows = payload.items ?? []
|
|
328
328
|
spend = Σ rows[].spend
|
|
329
329
|
clicks = Σ rows[].clicks
|
|
330
330
|
impressions = Σ rows[].impressions
|
|
@@ -339,7 +339,7 @@ CPL = 询盘个数 > 0 ? spend / 询盘个数 : —
|
|
|
339
339
|
|
|
340
340
|
`时间` 列写 `YYYY-MM` 或 `YYYY年M月`（与样表一致即可）。金额列用 `list-accounts` 的 `currencyCode`。
|
|
341
341
|
|
|
342
|
-
**可选校验（不写入 Excel，仅日志）**：同月再拉 `overview`，对比 `currentPeriod.spend`
|
|
342
|
+
**可选校验（不写入 Excel，仅日志）**：同月再拉 `overview`，对比 `record.currentPeriod.spend`（汇总维度在 `record`）与系列 `spend` 之和；偏差 >1% 时在 Agent 交付说明中脚注差异，**仍以系列加总为准**。
|
|
343
343
|
|
|
344
344
|
**上区**（B→L，跳过 A 列保持与运营样表一致）3 行月汇总：
|
|
345
345
|
|
|
@@ -347,7 +347,7 @@ CPL = 询盘个数 > 0 ? spend / 询盘个数 : —
|
|
|
347
347
|
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
348
348
|
| R1 | （A 列空）`汇总` |
|
|
349
349
|
| R2 | `时间` \| `点击次数` \| `展示次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` \| `询盘个数` \| `CPL` |
|
|
350
|
-
| R3..R5 | 倒序写 3 个月（**E 月在上**，S 月在下）：脚本读 `./<YYYY-MM>/campaigns-*.json` 按上表对 `
|
|
350
|
+
| R3..R5 | 倒序写 3 个月（**E 月在上**，S 月在下）：脚本读 `./<YYYY-MM>/campaigns-*.json` 按上表对 `items[]` 全量求和；`询盘个数` = `inquiries.json` 按月 count；`CPL` = `费用 / 询盘个数`（询盘 0 填 `—`） |
|
|
351
351
|
|
|
352
352
|
**下区**（B→G）3 月 × **重点国家 / 非重点国** 切片（共 6 行）：
|
|
353
353
|
|
|
@@ -381,7 +381,7 @@ CPL = 询盘个数 > 0 ? spend / 询盘个数 : —
|
|
|
381
381
|
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
382
382
|
| R1 | `广告系列表现明细 · 账户 <mediaCustomerId(带连字符)> · <数据开始月>-<数据结束月>` |
|
|
383
383
|
| R2（A→M，13 列） | `系列名称` \| `系列ID` \| `策略` \| `开始日期` \| `消耗 (¥)` \| `展示` \| `点击` \| `CTR` \| `平均CPC` \| `转化` \| `CPA (¥)` \| `转化率` \| `消耗占比` |
|
|
384
|
-
| R3… | 读 `campaigns-*.json`：`campaignName` / `campaignId` / `biddingStrategyTypeV2`（中文化：`MAXIMIZE_CONVERSIONS` → `Max转化`、`TARGET_SPEND` → `目标支出`、`MANUAL_CPC` → `手动CPC` 等；未命中保留原文）/ `startDate` / `spend` / `impressions` / `clicks` / `ctr` / `averageCpc` / `conversions` / `costPerConversion` / `conversionRate` / **`消耗占比` = `spend` / `sum(spend)`**（脚本算，写 0~1 小数） |
|
|
384
|
+
| R3… | 读 `campaigns-*.json` 的 `items[]`：`campaignName` / `campaignId` / `biddingStrategyTypeV2`（中文化：`MAXIMIZE_CONVERSIONS` → `Max转化`、`TARGET_SPEND` → `目标支出`、`MANUAL_CPC` → `手动CPC` 等；未命中保留原文）/ `startDate` / `spend` / `impressions` / `clicks` / `ctr` / `averageCpc` / `conversions` / `costPerConversion` / `conversionRate` / **`消耗占比` = `spend` / `sum(spend)`**（脚本算，写 0~1 小数） |
|
|
385
385
|
| 末行 | `合计`：A 列写 `合计`；金额、展示、点击、转化 求和；CTR/CVR/CPA 按合计反推（**禁止**对各行比率求平均） |
|
|
386
386
|
|
|
387
387
|
**下区**：
|
|
@@ -427,7 +427,7 @@ CPL = 询盘个数 > 0 ? spend / 询盘个数 : —
|
|
|
427
427
|
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
428
428
|
| R1 | `关键词表现 · 账户 <id> · <分析月份>` |
|
|
429
429
|
| R2（A→J，10 列） | `关键词` \| `匹配方式` \| `系列` \| `消耗 (¥)` \| `展示` \| `点击` \| `CTR` \| `平均CPC` \| `转化` \| `CPA (¥)` |
|
|
430
|
-
| R3… | 读 `keywords-*.json
|
|
430
|
+
| R3… | 读 `keywords-*.json` 的 `items[]`：`keyword` / `keywordMatchTypeZh`（中文匹配方式：`Broad` / `Phrase` / `Exact`）/ `campaignName` / `spend` / `impressions` / `clicks` / `ctr` / `averageCpc` / `conversions` / `costPerConversion` |
|
|
431
431
|
|
|
432
432
|
按 `转化` 降序、`消耗` 降序双排序。
|
|
433
433
|
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
| # | 维度 | CLI |
|
|
13
13
|
| --- | ---------------------------------------------------- | ---------------------------------------------- |
|
|
14
14
|
| 1 | 执行摘要（消耗/展示/点击/转化/CTR/CPC/CPA 本期概览） | `google-analysis --sections overview` |
|
|
15
|
-
| 2 |
|
|
15
|
+
| 2 | 每日投放趋势（按日消耗/点击/转化曲线；金额/CPA **2 位小数**，转化/点击整数） | `google-analysis --sections daily-metrics` |
|
|
16
16
|
| 3 | 月度汇总（全周期汇总数据） | `google-analysis --sections dimension-summary` |
|
|
17
17
|
| 4 | 广告系列表现（预算/出价策略/各系列消耗与效果） | `google-analysis --sections campaigns` |
|
|
18
18
|
| 5 | 设备分布（PC/移动/平板 消耗/点击/转化） | `google-analysis --sections devices` |
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
|
|
29
29
|
| 维度 | CLI | 备注 |
|
|
30
30
|
| ------------- | ----------------------------------------------- | ------------------------------------------------------------ |
|
|
31
|
-
| 系列按小时 | `google-analysis --sections campaign-hour` | `
|
|
31
|
+
| 系列按小时 | `google-analysis --sections campaign-hour` | 行在 `items[]`，含 `date`/`hour`/消耗与效果 |
|
|
32
32
|
| 受众分布 | `google-analysis --sections audience` | 可分 `SystemDefined` / `UserDefined` |
|
|
33
33
|
| 搜索词报告 | `google-analysis --sections search-terms` | 高消耗搜索词；`queryTargetingStatusZh` 列（已添加/已排除/都没有） |
|
|
34
34
|
| 广告创意表现 | `google-analysis --sections ads` | 广告标题/类型/到达网址 |
|
|
@@ -79,7 +79,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
79
79
|
|
|
80
80
|
### 点击率 / 转化率 / 互动率
|
|
81
81
|
|
|
82
|
-
> **2026-05 起 CLI 已统一归一**（manifest `schemaVersion
|
|
82
|
+
> **2026-05 起 CLI 已统一归一**（manifest `schemaVersion ≥ 2`）：所有 `<section>-*.json` 中的 `ctr` / `conversionRate` 一律为 **0~1 小数**（如 `0.10` = 10.00%）。`schemaVersion 3` 起行数据统一在 `items[]`、汇总在 `record`。详见 `references/analytics/account-analytics.md`「指标字段对照」「落盘 JSON 统一信封」。
|
|
83
83
|
|
|
84
84
|
| 场景 | 处理 |
|
|
85
85
|
| ------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
@@ -116,7 +116,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
116
116
|
| R1 | `广告系列报告`（如运营改名，可改文案但 Sheet 名仍为 `账户报告`） |
|
|
117
117
|
| R2 | 统计区间 |
|
|
118
118
|
| R3（A→K，11 列） | `广告系列` \| `预算` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
119
|
-
| R4… | 来自 `campaigns-*.json
|
|
119
|
+
| R4… | 来自 `campaigns-*.json` 的 `items[]`（`schemaVersion 3` 行统一在 `items`）：`campaignName`、`budgetAmountYuan`（元）、`spend`、`impressions`、`clicks`、`ctr`（已归一直接写入「点击率」）、`averageCpc`、`allConversions`→「所有转化次数」、`conversions`→「转化次数」、`costPerConversion`、`conversionRate`（已归一直接写入「转化率」）；缺 `allConversions` 时与「转化次数」同值或填 `0` / `—`，并在脚注说明 |
|
|
120
120
|
| 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；**展示 / 点击 / 所有转化次数 / 转化次数 / 费用** 做列求和；**点击率** = 合计点击 ÷ 合计展示；**转化率** = 合计转化 ÷ 合计点击（**禁止**用合计转化 ÷ 合计展示）；**每次转化费用** = 合计费用 ÷ 合计转化（转化为 0 时填 `—`）；禁止对各行比率取算术平均 |
|
|
121
121
|
|
|
122
122
|
表下**留白若干行**后写 **「数据复盘」**：
|
|
@@ -183,7 +183,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
183
183
|
| R1 | `地理位置报告` |
|
|
184
184
|
| R2 | 统计区间 |
|
|
185
185
|
| R3（A→M，13 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
186
|
-
| R4… | `campaign-geo-matched-*.json
|
|
186
|
+
| R4… | `campaign-geo-matched-*.json` 的 `items[]`（`schemaVersion 3` 行统一在 `items`）：`countryOrRegion`→地理位置；`campaignName`→「广告系列」；`allConversions`→「所有转化次数」；`conversions`→「转化次数」；**互动次数**→`interactions`；**互动率**→`interactionRate`（字符串须解析）或 `interactions/impressions`，`interactions` 为 0 时填 `—`；**平均费用 必须** = `spend / interactions`，`interactions` 为 0 / null / undefined 时填 `—`；`ctr` / `conversionRate` 直接写入；其余列按 outline 映射 |
|
|
187
187
|
|
|
188
188
|
---
|
|
189
189
|
|
|
@@ -207,7 +207,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
207
207
|
```
|
|
208
208
|
|
|
209
209
|
- **第 1 条「平均每天」**：`区间总消耗 / 区间日历天数`（含起止日），脚本计算，禁止手填。
|
|
210
|
-
- **第 3 条**：CLI 返回的若是账户整体 CTR，写「整体点击率」而非「搜索点击率」；可区分时再写「搜索点击率」。`overview-*.json
|
|
210
|
+
- **第 3 条**：CLI 返回的若是账户整体 CTR，写「整体点击率」而非「搜索点击率」；可区分时再写「搜索点击率」。`overview-*.json`（汇总维度，`schemaVersion 3` 起整块在 `record`）的 `record.ctr` 已是 0~1 小数（如 `0.10`），话术 `x%` 用 `(ctr * 100).toFixed(2) + "%"`，**禁止**直接打印数值得到 "0.10%"。
|
|
211
211
|
- **所有金额、百分比** 一律 **2 位小数**。
|
|
212
212
|
|
|
213
213
|
---
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
与目录内 *.md 纲要的数据形态对应关系（按需组合，不必一页全用）：
|
|
14
14
|
- 执行摘要 / 总览（period 类 md §1） → 页眉 + KPI 指标卡网格 + 趋势折线/面积图
|
|
15
15
|
- 漏斗式 KPI（google-ads-diagnosis §3.1）→ 步骤条或纵向编号表 + 附注列
|
|
16
|
+
- 广告诊断每日趋势（google-ads-diagnosis 硬约束）→ 折线图 tooltip/表：金额与 CPA toFixed(2)，转化整数；每 section 后必有「分析」「建议」区块
|
|
16
17
|
- 结构计数（诊断 §3.2） → 紧凑 stat 宫格或 definition list
|
|
17
18
|
- 对比表（行业基准、系列环比） → 斑马纹表格 + 环比列用徽章上色
|
|
18
19
|
- 设备/地域/受众分布 → 条形图、饼图、堆叠柱（ECharts）
|