siluzan-tso-cli 1.1.19-beta.6 → 1.1.19-beta.8

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 (4) hide show
  1. package/README.md +1 -1
  2. package/dist/skill/_meta.json +2 -2
  3. package/dist/skill/report-templates/okki-weekly-google-client.md +18 -9
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills # 写入自定义目录
51
51
  siluzan-tso init --force # 强制覆盖已存在文件
52
52
  ```
53
53
 
54
- > **注意**：当前为测试版（1.1.19-beta.6），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
54
+ > **注意**：当前为测试版（1.1.19-beta.8），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
55
55
 
56
56
  | 助手 | 建议 `--ai` |
57
57
  | ----------------------- | ------------------------------------ |
package/dist/skill/_meta.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "slug": "siluzan-tso",
3
- "version": "1.1.19-beta.6",
4
- "publishedAt": 1778579128140
3
+ "version": "1.1.19-beta.8",
4
+ "publishedAt": 1778652640240
5
5
  }
package/dist/skill/report-templates/okki-weekly-google-client.md CHANGED
@@ -57,7 +57,16 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
57
57
 
58
58
  ## xlsx 版式规范
59
59
 
60
- 以下按 **工作簿 → Sheet 名（须完全一致）→ 版式** 约定，便于 WorkBuddy / 人工用样表对照验收。**不**再单独建名为「广告系列」的 Sheet（系列表在 **`账户报告`** 内）,所有数据保留小数点后两位
60
+ 以下按 **工作簿 → Sheet 名（须完全一致）→ 版式** 约定，便于 WorkBuddy / 人工用样表对照验收。**不**再单独建名为「广告系列」的 Sheet（系列表在 **`账户报告`** 内）。**金额等展示列**：脚本与运营约定保留小数位数（常见两位），须与样表一致。
61
+
62
+ ### 脚本写表：点击率 / 转化率 / 互动率（易错，必读）
63
+
64
+ 网关落盘 JSON 中，**`ctr`、`conversionRate` 在绝大多数行上已是 0～1 的小数**（例如 `0.0753` 表示约 7.53% 点击率，`0.0365` 表示约 3.65% 转化率），**不是**「百分数刻度」里的 `7.53` / `3.65`。
65
+
66
+ - **写入 Excel**（本模板要求点击率、转化率、互动率列为 **0～1 小数**）：对上述字段应 **直接使用 JSON 数值**（或 `Number(...)`），**禁止**再 **`÷100`**，否则会变成 `0.0007` 量级，经四舍五入后常显示为 **0**。
67
+ - **客户话术 / 正文里写「x%」**：应使用 **`ctr * 100`、`conversionRate * 100`**（或等价格式化）后再加 `%`，**禁止**把已是 0～1 的 `ctr` 当「百分数」再除 100。
68
+ - **`interactionRate`**：网关可能为 **字符串**（如 `"0.0753…"`），须 **`parseFloat` / `Number`** 后再写入；若与 `interactions/impressions` 不一致，以 outline 为准或允许用 `interactions / impressions` 重算。
69
+ - **`interactions === 0`（或 null）** 时：**平均费用**（`spend / interactions`）与 **互动率** 列填 **`—`**，禁止除零。
61
70
 
62
71
  ### 工作簿级
63
72
 
@@ -71,7 +80,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
71
80
 
72
81
  ### 各 Sheet 共同版式
73
82
 
74
- - **第 1 行（A1）**：该 Sheet 的**报告标题**（见下表「R1 标题」）。建议合并单元格横跨数据区（样表约 A1:K1 / A1:N1）。
83
+ - **第 1 行（A1）**：该 Sheet 的**报告标题**（见下表「R1 标题」）。建议合并单元格横跨该 Sheet **R3 表头所含全部列**（列数随 Sheet 而定）。
75
84
  - **第 2 行（A2）**：统计区间，**中文可读**：`YYYY年M月D日 - YYYY年M月D日`（由 `--start` / `--end` 转换，与样表一致）。
76
85
  - **第 3 行**：**表头**（列名、顺序须与下表一致）。
77
86
  - **第 4 行起**：数据行；列宽与自动筛选、首行冻结为可选（样表含 `autoFilter`、部分 Sheet 对数据区设默认**按费用/转化相关列降序**排序，Agent 可复现或省略，**不得**因此改数）。
@@ -90,8 +99,8 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
90
99
  | R1 标题 | `广告系列报告`（与样表一致；若运营统一改名，可改文案但须保持 Sheet 名仍为 `账户报告`） |
91
100
  | R2 | 统计区间（中文日期，见上） |
92
101
  | R3 表头（A→K，共 11 列） | `广告系列` \| `预算` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
93
- | R4… | 每行一条广告系列：来自 `campaigns-*.json` 的 `campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks`、`ctr`（或 `clicks/impressions`）、`averageCpc`、**所有转化**与 **转化**字段以 JSON 及 outline 为准映射（若网关仅提供 `conversions`，缺列填 `0` 或留空并在脚注说明） |
94
- | 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；其余列按列语义对上方数据行做**求和或可加和指标**；**点击率 / 转化率**须用合计展示、点击、转化等**重算**，禁止对各行比率取算术平均 |
102
+ | R4… | 每行一条广告系列：来自 `campaigns-*.json` 的 `campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks`、**`ctr`（直接作 0～1 写入「点击率」，禁止 ÷100）**、`averageCpc`、**`allConversions ` →「所有转化次数」**、**`conversions` →「转化次数」**、`costPerConversion`、**`conversionRate`（直接作 0～1 写入「转化率」，禁止 ÷100）**；若缺 `allConversions ` 仅 `conversions`，「所有转化次数」可与「转化次数」同值或填 `0` / `—` 并在脚注说明（以 outline 为准） |
103
+ | 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；**展示 / 点击 / 所有转化次数 / 转化次数 / 费用**等做列求和；**点击率** = 合计点击÷合计展示；**转化率** = 合计转化÷合计点击（**禁止**用合计转化÷合计展示冒充）；**每次转化费用** = 合计费用÷合计转化（转化为 0 时填 `—`）；禁止对各行比率取算术平均 |
95
104
 
96
105
  表下**留白若干行**后写 **「数据复盘」**（与样表一致）：
97
106
 
@@ -134,8 +143,8 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
134
143
  | --- | --- |
135
144
  | R1 标题 | `设备报告` |
136
145
  | R2 | 统计区间 |
137
- | R3 表头（A→M，共 13 列） | `设备` \| `级别` \| `广告系列` \| `出价调整` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
138
- | R4… | **`campaign-device-*.json`**（根字段仍为 `devices[]`）：`deviceType` → 设备；`campaignName` / `adGroupName` 等映射「广告系列」「广告组」列；**出价调整** 若 JSON 无字段则留空或「—」级别列统一填 广告系列 |
146
+ | R3 表头（A→M，共 13 列） | `设备` \| `级别` \| `广告系列` \| `出价调整` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
147
+ | R4… | **`campaign-device-*.json`**（`devices[]`）：`deviceType` → 设备；`campaignName` / `adGroupName` →「广告系列」等；**`allConversions `（或 outline 中的等价字段）→「所有转化次数」**；`conversions` →「转化次数」；**`ctr` / `conversionRate` 作 0～1 写入，禁止 ÷100**；**出价调整** 无字段则「—」；**级别**列按运营约定（如填 `广告系列` 或 `账户`，全文一致） |
139
148
 
140
149
  ---
141
150
 
@@ -145,8 +154,8 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
145
154
  | --- | --- |
146
155
  | R1 标题 | `地理位置报告` |
147
156
  | R2 | 统计区间 |
148
- | R3 表头（A→L，共 12 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `转化次数` \| `每次转化费用` \| `转化率` |
149
- | R4… | **`campaign-geo-*.json`**（根字段仍为 `countries[]`）：`countryOrRegion` → 地理位置；`campaignName` 映射「广告系列」列；**互动次数** → `interactions`；**互动率** → `interactionRate`；**平均费用**列 **必须**按 **`spend / interactions`** 写入（`spend` 已为元、与 JSON 一致；与「每次互动费用」口径一致）。若 `interactions` 为 `0` / `null` / `undefined`，**平均费用**格填 **`—`**，禁止除零或手填臆造。其余列按 outline 映射。 |
157
+ | R3 表头（A→M，共 13 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
158
+ | R4… | **`campaign-geo-*.json`**（`countries[]`）：`countryOrRegion` → 地理位置；`campaignName` →「广告系列」；**`allConversions `（或等价）→「所有转化次数」**；`conversions` →「转化次数」；**互动次数** → `interactions`；**互动率** → `interactionRate`（字符串须解析）或 `interactions/impressions`（`interactions` 为 0 时互动率填 **`—`**）；**平均费用** **必须**为 **`spend / interactions`**，`interactions` 为 0 / null / undefined 时填 **`—`**；**`ctr` / `conversionRate` 作 0～1 写入，禁止 ÷100**；其余列按 outline 映射。 |
150
159
 
151
160
  ---
152
161
 
@@ -177,7 +186,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
177
186
  8. 账户余额：<金额+币种>（截至查询时点）
178
187
  ```
179
188
 
180
- **第 3 条**：若 CLI 返回的是**账户整体 CTR**，话术写「整体点击率」而非「搜索点击率」，避免与搜索广告狭义口径冲突；若数据中可区分搜索广告 CTR，再写「搜索点击率」。
189
+ **第 3 条**：若 CLI 返回的是**账户整体 CTR**，话术写「整体点击率」而非「搜索点击率」，避免与搜索广告狭义口径冲突；若数据中可区分搜索广告 CTR，再写「搜索点击率」。**百分比数字**：若 `stats` / `overview` 中 CTR 为 **0～1 小数**，话术里写「x%」前须 **×100**（与上文「脚本写表：点击率 / 转化率」一致），**禁止**再 ÷100。
181
190
 
182
191
  **第 1 条「平均每天」**：`区间总消耗 / 区间日历天数`（含起止日），在脚本中计算，禁止手填。
183
192
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "siluzan-tso-cli",
3
- "version": "1.1.19-beta.6",
3
+ "version": "1.1.19-beta.8",
4
4
  "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
5
5
  "keywords": [
6
6
  "ad-account",