siluzan-tso-cli 1.1.19-beta.5 → 1.1.19-beta.7
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
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.
|
|
54
|
+
> **注意**：当前为测试版（1.1.19-beta.7），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
|
|
55
55
|
|
|
56
56
|
| 助手 | 建议 `--ai` |
|
|
57
57
|
| ----------------------- | ------------------------------------ |
|
package/dist/skill/SKILL.md
CHANGED
|
@@ -219,7 +219,7 @@ siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --jso
|
|
|
219
219
|
|
|
220
220
|
1. **不要**按 `google-period-report.md` 展开默认 8 维并追问追加；改读 **`report-templates/okki-weekly-google-client.md`** 全文并按其结构交付。
|
|
221
221
|
2. 确认 `mediaCustomerId` 与 `--start` / `--end`（未给齐则按上文「时间范围强制反问」）。
|
|
222
|
-
3. 同一 `--json-out` 目录执行模板中的命令组合：`list-accounts`（可选但推荐）、`stats`、`balance`、`google-analysis --sections overview,campaigns,keywords,search-terms,
|
|
222
|
+
3. 同一 `--json-out` 目录执行模板中的命令组合：`list-accounts`（可选但推荐）、`stats`、`balance`、`google-analysis --sections overview,campaigns,keywords,search-terms,campaign-device,campaign-geo`。
|
|
223
223
|
4. **先 outline 后脚本**：读各 `*.outline.txt`，再编写并执行代码从 JSON 计算并写出：① 客户话术（Markdown/纯文本均可）；② 若需 **Excel**：**必须**产出多 Sheet `.xlsx`（版式与 Sheet 名见模板「必选交付」节），**只能**由 Agent 在当前环境执行脚本生成，**禁止**假设存在 `siluzan-tso … excel` 类 CLI 子命令。WorkBuddy 等编排器须在流程中显式包含「写 `.xlsx` 脚本并执行」一步，否则易缺产物。
|
|
224
224
|
5. 遵守 SKILL 硬规范：金额 `*Display`、禁止手填业务数、禁止编造 ID。
|
|
225
225
|
|
package/dist/skill/_meta.json
CHANGED
|
@@ -41,31 +41,32 @@ siluzan-tso stats -m Google -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
41
41
|
siluzan-tso balance -m Google -a <mediaCustomerId> --json-out ./snap-okki
|
|
42
42
|
|
|
43
43
|
siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-out ./snap-okki \
|
|
44
|
-
--sections overview,campaigns,keywords,search-terms,
|
|
44
|
+
--sections overview,campaigns,keywords,search-terms,campaign-device,campaign-geo
|
|
45
45
|
```
|
|
46
46
|
|
|
47
47
|
**说明**：
|
|
48
48
|
|
|
49
49
|
- `stats`：区间消耗、曝光、点击、转化、CTR、CPC 等与**账户级周报摘要**对齐；金额用 `*Display` 或文档规定的展示字段。
|
|
50
50
|
- `balance`：**当前**账户余额（非历史快照）；话术里写清「截至查询时点」。
|
|
51
|
-
- `google-analysis`：系列 / 词 /
|
|
52
|
-
-
|
|
51
|
+
- `google-analysis`：系列 / 词 / 搜索词；**设备与国家两 Sheet 的数据源**须用 **`campaign-device` / `campaign-geo`**（网关 `…/campaigns/reports/device` 与 `…/campaigns/reports/geo`，**按广告系列（及常见广告组）拆行**），**不要**再用账户级 `devices` / `geographic`。JSON 根结构仍为 `devices[]` / `countries[]`，落盘文件名分别为 `campaign-device-<id>.json`、`campaign-geo-<id>.json`。若运营需对「国家」「设备」做跨系列汇总，在脚本中聚合，**禁止**改回账户级维度冒充系列口径。
|
|
52
|
+
- 可选：`campaign-geo` 支持网关阈值过滤，与 CLI 一致时追加 `--cost-greater` / `--click-greater` / `--conversions-greater`（见 `references/account-analytics.md`）。
|
|
53
|
+
- TopN、排序、跨系列汇总均在脚本内对 JSON 完成，禁止心算。
|
|
53
54
|
- **写脚本前**先读各 `<section>-<id>.outline.txt`（及 stats/balance 的 outline，若有），再读对应 `.json`。
|
|
54
55
|
|
|
55
|
-
|
|
56
|
+
---
|
|
56
57
|
|
|
57
|
-
|
|
58
|
-
| --- | --- |
|
|
59
|
-
| **广告系列** | JSON 无 `campaignName`（或等价字段）时，**统一填** `所有广告系列` |
|
|
60
|
-
| **级别** | **统一填** `账户` |
|
|
61
|
-
| **出价调整** | **统一填** `-`（半角减号；勿与空单元格混用，除非运营另行约定） |
|
|
62
|
-
| **广告组**（仅「设备」Sheet R3 含该列） | 账户级 JSON 无广告组字段时，**统一填** `—`（全角长横，**勿**用 `-`，以免与「出价调整」列混淆） |
|
|
58
|
+
## xlsx 版式规范
|
|
63
59
|
|
|
64
|
-
|
|
60
|
+
以下按 **工作簿 → Sheet 名（须完全一致）→ 版式** 约定，便于 WorkBuddy / 人工用样表对照验收。**不**再单独建名为「广告系列」的 Sheet（系列表在 **`账户报告`** 内）。**金额等展示列**：脚本与运营约定保留小数位数（常见两位），须与样表一致。
|
|
61
|
+
|
|
62
|
+
### 脚本写表：点击率 / 转化率 / 互动率（易错，必读）
|
|
65
63
|
|
|
66
|
-
|
|
64
|
+
网关落盘 JSON 中，**`ctr`、`conversionRate` 在绝大多数行上已是 0～1 的小数**（例如 `0.0753` 表示约 7.53% 点击率，`0.0365` 表示约 3.65% 转化率），**不是**「百分数刻度」里的 `7.53` / `3.65`。
|
|
67
65
|
|
|
68
|
-
|
|
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`）与 **互动率** 列填 **`—`**，禁止除零。
|
|
69
70
|
|
|
70
71
|
### 工作簿级
|
|
71
72
|
|
|
@@ -74,12 +75,12 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
74
75
|
| 1 | `账户报告` | `campaigns` + 复盘文案（stats/overview 汇总后由 Agent 撰写） |
|
|
75
76
|
| 2 | `关键词` | `keywords` |
|
|
76
77
|
| 3 | `搜索词` | `search-terms` |
|
|
77
|
-
| 4 | `设备` | **`
|
|
78
|
-
| 5 | `国家` | **`
|
|
78
|
+
| 4 | `设备` | **`campaign-device`**（`campaign-device-*.json`；按系列/组拆行，非账户级 `devices`） |
|
|
79
|
+
| 5 | `国家` | **`campaign-geo`**（`campaign-geo-*.json`；按系列/地域拆行，非账户级 `geographic`） |
|
|
79
80
|
|
|
80
81
|
### 各 Sheet 共同版式
|
|
81
82
|
|
|
82
|
-
- **第 1 行（A1）**：该 Sheet 的**报告标题**（见下表「R1
|
|
83
|
+
- **第 1 行（A1）**：该 Sheet 的**报告标题**（见下表「R1 标题」）。建议合并单元格横跨该 Sheet **R3 表头所含全部列**（列数随 Sheet 而定）。
|
|
83
84
|
- **第 2 行（A2）**：统计区间，**中文可读**：`YYYY年M月D日 - YYYY年M月D日`（由 `--start` / `--end` 转换，与样表一致）。
|
|
84
85
|
- **第 3 行**：**表头**（列名、顺序须与下表一致）。
|
|
85
86
|
- **第 4 行起**：数据行；列宽与自动筛选、首行冻结为可选（样表含 `autoFilter`、部分 Sheet 对数据区设默认**按费用/转化相关列降序**排序，Agent 可复现或省略，**不得**因此改数）。
|
|
@@ -98,8 +99,8 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
98
99
|
| R1 标题 | `广告系列报告`（与样表一致；若运营统一改名，可改文案但须保持 Sheet 名仍为 `账户报告`） |
|
|
99
100
|
| R2 | 统计区间（中文日期，见上） |
|
|
100
101
|
| R3 表头（A→K，共 11 列） | `广告系列` \| `预算` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
101
|
-
| R4… | 每行一条广告系列：来自 `campaigns-*.json` 的 `campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks
|
|
102
|
-
| 末行「合计」 | **广告系列**列填 `总计`；**预算**列填
|
|
102
|
+
| R4… | 每行一条广告系列：来自 `campaigns-*.json` 的 `campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks`、**`ctr`（直接作 0～1 写入「点击率」，禁止 ÷100）**、`averageCpc`、**`allConv` →「所有转化次数」**、**`conversions` →「转化次数」**、`costPerConversion`、**`conversionRate`（直接作 0～1 写入「转化率」，禁止 ÷100）**；若缺 `allConv` 仅 `conversions`，「所有转化次数」可与「转化次数」同值或填 `0` / `—` 并在脚注说明（以 outline 为准） |
|
|
103
|
+
| 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；**展示 / 点击 / 所有转化次数 / 转化次数 / 费用**等做列求和；**点击率** = 合计点击÷合计展示；**转化率** = 合计转化÷合计点击（**禁止**用合计转化÷合计展示冒充）；**每次转化费用** = 合计费用÷合计转化（转化为 0 时填 `—`）；禁止对各行比率取算术平均 |
|
|
103
104
|
|
|
104
105
|
表下**留白若干行**后写 **「数据复盘」**（与样表一致）：
|
|
105
106
|
|
|
@@ -108,8 +109,8 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
108
109
|
**1. 账户层级**（整体消耗、展示、点击、点击率与 3% 基准对比、询盘/转化数、平均询盘成本等，数来自 stats/overview 与上表合计）；
|
|
109
110
|
**2. 关键词层级**（高转化词、高消耗低转化词及出价/竞争力建议）；
|
|
110
111
|
**3. 搜索字词层级**（标红/高意向词、否词与加词建议）；
|
|
111
|
-
**4.
|
|
112
|
-
**5.
|
|
112
|
+
**4. 设备层级**（基于 **`campaign-device`**：各设备在系列上的消耗/转化分布；复盘可汇总或点出高消耗系列×设备组合）；
|
|
113
|
+
**5. 国家层级**（基于 **`campaign-geo`**：各国家/地区在系列上的消耗/转化；高消耗/低转化地域与降权/调价建议）。
|
|
113
114
|
文案由 Agent 据 JSON 撰写，**不得编造**表中不存在的数字。
|
|
114
115
|
|
|
115
116
|
---
|
|
@@ -142,8 +143,8 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
142
143
|
| --- | --- |
|
|
143
144
|
| R1 标题 | `设备报告` |
|
|
144
145
|
| R2 | 统计区间 |
|
|
145
|
-
| R3 表头（A→M，共 13 列） | `设备` \| `级别` \|
|
|
146
|
-
| R4… | **`
|
|
146
|
+
| R3 表头（A→M，共 13 列） | `设备` \| `级别` \| `广告系列` \| `出价调整` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
147
|
+
| R4… | **`campaign-device-*.json`**（`devices[]`）：`deviceType` → 设备；`campaignName` / `adGroupName` →「广告系列」等；**`allConv`（或 outline 中的等价字段）→「所有转化次数」**；`conversions` →「转化次数」；**`ctr` / `conversionRate` 作 0～1 写入，禁止 ÷100**；**出价调整** 无字段则「—」；**级别**列按运营约定（如填 `广告系列` 或 `账户`，全文一致） |
|
|
147
148
|
|
|
148
149
|
---
|
|
149
150
|
|
|
@@ -153,8 +154,8 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
153
154
|
| --- | --- |
|
|
154
155
|
| R1 标题 | `地理位置报告` |
|
|
155
156
|
| R2 | 统计区间 |
|
|
156
|
-
| R3 表头（A→
|
|
157
|
-
| R4… | **`
|
|
157
|
+
| R3 表头（A→M，共 13 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
158
|
+
| R4… | **`campaign-geo-*.json`**（`countries[]`）：`countryOrRegion` → 地理位置；`campaignName` →「广告系列」；**`allConv`（或等价）→「所有转化次数」**；`conversions` →「转化次数」；**互动次数** → `interactions`；**互动率** → `interactionRate`（字符串须解析）或 `interactions/impressions`（`interactions` 为 0 时互动率填 **`—`**）；**平均费用** **必须**为 **`spend / interactions`**，`interactions` 为 0 / null / undefined 时填 **`—`**；**`ctr` / `conversionRate` 作 0～1 写入，禁止 ÷100**；其余列按 outline 映射。 |
|
|
158
159
|
|
|
159
160
|
---
|
|
160
161
|
|
|
@@ -185,7 +186,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
185
186
|
8. 账户余额：<金额+币种>（截至查询时点）
|
|
186
187
|
```
|
|
187
188
|
|
|
188
|
-
**第 3 条**：若 CLI 返回的是**账户整体 CTR**，话术写「整体点击率」而非「搜索点击率」，避免与搜索广告狭义口径冲突；若数据中可区分搜索广告 CTR
|
|
189
|
+
**第 3 条**：若 CLI 返回的是**账户整体 CTR**，话术写「整体点击率」而非「搜索点击率」，避免与搜索广告狭义口径冲突；若数据中可区分搜索广告 CTR，再写「搜索点击率」。**百分比数字**：若 `stats` / `overview` 中 CTR 为 **0～1 小数**，话术里写「x%」前须 **×100**（与上文「脚本写表：点击率 / 转化率」一致），**禁止**再 ÷100。
|
|
189
190
|
|
|
190
191
|
**第 1 条「平均每天」**：`区间总消耗 / 区间日历天数`（含起止日），在脚本中计算，禁止手填。
|
|
191
192
|
|
|
@@ -193,7 +194,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
193
194
|
|
|
194
195
|
## 复盘小结 + 优化建议（对内或可附在客户邮件末段）
|
|
195
196
|
|
|
196
|
-
基于同一批 JSON（尤其 `campaigns`、`keywords`、`search-terms
|
|
197
|
+
基于同一批 JSON（尤其 `campaigns`、`keywords`、`search-terms`、**`campaign-device`**、**`campaign-geo`**、`overview`）：
|
|
197
198
|
|
|
198
199
|
- **复盘**：3～6 条 bullet：消耗集中度、高消耗系列/词、地域与设备差异、CTR/CPC 相对水平。
|
|
199
200
|
- **优化建议**：3～5 条可执行项（预算、否词、落地页、系列状态等），**不额外拉数**；缺数据则标 `[数据不可用：原因]`。
|
|
@@ -204,7 +205,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
204
205
|
|
|
205
206
|
| 项 | 周期报告 `google-period-report.md` | 本文 OKKI 周报 |
|
|
206
207
|
| -- | ---------------------------------- | ---------------- |
|
|
207
|
-
| 默认维度 | 8 维 + 主动追问可选追加 | **固定** `overview,campaigns,keywords,search-terms,
|
|
208
|
+
| 默认维度 | 8 维 + 主动追问可选追加 | **固定** `overview,campaigns,keywords,search-terms,campaign-device,campaign-geo` + `stats` + `balance` |
|
|
208
209
|
| 输出形态 | 长文分析报告 | **固定话术** + 短复盘 + **多 Sheet Excel（Agent 脚本写，非 CLI）** |
|
|
209
210
|
| 典型用户 | 内部分析 | **发客户**的同步简报 |
|
|
210
211
|
|