siluzan-tso-cli 1.1.19-beta.10 → 1.1.19-beta.11
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.11），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
|
|
55
55
|
|
|
56
56
|
| 助手 | 建议 `--ai` |
|
|
57
57
|
| ----------------------- | ------------------------------------ |
|
package/dist/skill/_meta.json
CHANGED
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
> `使用okki周报模板生成<账户名或ID>，<YYYY-MM-DD>--<YYYY-MM-DD>的投放报告`
|
|
5
5
|
> 同义：`OKKI 周报`、`okki 周报模板`、`运营 OKKI 周报`。
|
|
6
6
|
> **媒体**：当前模板仅规范 **Google**（`mediaCustomerId`）。其他媒体用各自 `*-period-report.md`。
|
|
7
|
-
> **Excel 版式基准**：与运营样表《**数据复盘分析**》类 xlsx 对齐（如 `2025.12数据复盘分析.xlsx
|
|
7
|
+
> **Excel 版式基准**：与运营样表《**数据复盘分析**》类 xlsx 对齐（如 `2025.12数据复盘分析.xlsx`）；工作簿 5 个 Sheet、顺序与表头以下文规范为准。
|
|
8
8
|
|
|
9
|
-
识别到上述意图时：**不要**再走 `google-period-report.md` 的「默认 8 维 + 追问追加」流程；按本文**固定维度 +
|
|
9
|
+
识别到上述意图时：**不要**再走 `google-period-report.md` 的「默认 8 维 + 追问追加」流程；按本文**固定维度 + 固定客户话术**交付（数据全部来自 CLI 落盘 JSON，见 `references/account-analytics.md`）。
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
@@ -14,22 +14,22 @@
|
|
|
14
14
|
|
|
15
15
|
1. **账户**：`mediaCustomerId` 来自 `list-accounts -m Google -k <id>`，禁止猜 ID。
|
|
16
16
|
2. **统计区间**：`--start` / `--end`（用户未给齐时按 SKILL 反问；授权默认时可用「上一完整自然周」白名单并写明）。
|
|
17
|
-
3.
|
|
18
|
-
4.
|
|
17
|
+
3. **询盘口径**：默认使用区间内 `conversions`（转化次数，来自 `stats` 或 `overview`）。若运营定义为某类转化，须在首段脚注说明（必要时补拉 `google-analysis --sections conversion-actions` 仅作说明）。
|
|
18
|
+
4. **日期写法**：`2026.4.1`、`2026/4/1` 等先规范为 `YYYY-MM-DD`（如 `2026-04-01`）再传 `--start` / `--end`。
|
|
19
19
|
|
|
20
20
|
---
|
|
21
21
|
|
|
22
|
-
##
|
|
22
|
+
## 架构约定 · Excel 由谁生成
|
|
23
23
|
|
|
24
|
-
- **`siluzan-tso` 不提供**「一键生成 OKKI Excel
|
|
25
|
-
-
|
|
26
|
-
-
|
|
24
|
+
- **`siluzan-tso` 不提供**「一键生成 OKKI Excel」的子命令，**也不要**在 CLI 里新增。
|
|
25
|
+
- 需交付 Excel 时：由 **Agent（含 WorkBuddy 编排）** 在下列 CLI **`--json-out` 落盘后**，自行编写 **Node.js / Python** 脚本（如 `exceljs`、`xlsx`、`openpyxl`）读取 JSON → 写 `.xlsx`。
|
|
26
|
+
- **数值一律来自落盘 JSON，禁止在脚本里写死业务数字。**
|
|
27
27
|
|
|
28
28
|
---
|
|
29
29
|
|
|
30
|
-
##
|
|
30
|
+
## 拉数（一次目录）
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
同一目录落盘（示例 `./snap-okki`）：
|
|
33
33
|
|
|
34
34
|
```bash
|
|
35
35
|
mkdir -p ./snap-okki
|
|
@@ -46,54 +46,53 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
46
46
|
|
|
47
47
|
**说明**：
|
|
48
48
|
|
|
49
|
-
- `stats
|
|
50
|
-
- `balance
|
|
51
|
-
-
|
|
52
|
-
- 可选：`campaign-geo`
|
|
53
|
-
- TopN
|
|
54
|
-
-
|
|
49
|
+
- `stats`：区间消耗 / 曝光 / 点击 / 转化 / CTR / CPC，与账户级周报摘要对齐；金额用 `*Display` 或文档规定的展示字段。
|
|
50
|
+
- `balance`：**当前**余额（非历史快照），话术写「截至查询时点」。
|
|
51
|
+
- 「设备」「国家」两 Sheet **必须**用 **`campaign-device` / `campaign-geo`**（按系列/组拆行），**不要**用账户级 `devices` / `geographic`。落盘文件名为 `campaign-device-<id>.json`、`campaign-geo-<id>.json`。跨系列汇总在脚本中做。
|
|
52
|
+
- 可选：`campaign-geo` 支持 `--cost-greater` / `--click-greater` / `--conversions-greater`（见 `references/account-analytics.md`）。
|
|
53
|
+
- TopN、排序、汇总均在脚本内对 JSON 完成，禁止心算。
|
|
54
|
+
- 写脚本前先读各 `<section>-<id>.outline.txt` 再读 `.json`。
|
|
55
55
|
|
|
56
56
|
---
|
|
57
57
|
|
|
58
58
|
## xlsx 版式规范
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
一些状态的枚举如果是英语需要使用对应中文的字段或转成中文。
|
|
60
|
+
工作簿 → Sheet 名（须完全一致）→ 版式。**不**单独建「广告系列」Sheet（系列表在 `账户报告` 内）。状态枚举若为英文须转中文。
|
|
62
61
|
|
|
63
|
-
###
|
|
62
|
+
### 数值格式（强约束）
|
|
64
63
|
|
|
65
|
-
|
|
64
|
+
- **所有数值列一律保留 2 位小数**：金额、CPC、每次转化费用、预算、点击率、转化率、互动率等。
|
|
65
|
+
- 客户话术 / 文案中的 `x%`：`(v * 100).toFixed(2) + "%"`。
|
|
66
66
|
|
|
67
|
-
|
|
68
|
-
| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
69
|
-
| **写入 Excel 0~1 小数列**（点击率/转化率/互动率） | 直接写入 JSON 数值（**禁止**再 ÷100） |
|
|
70
|
-
| **写客户话术 / 文案的 `x%`** | `(v * 100).toFixed(2) + "%"`（**禁止**直接打印数值得到 "0.09%"） |
|
|
71
|
-
| **`interactionRate`（字符串）** | `parseFloat(row.interactionRate)` 后按数值字段使用（同样 0~1 小数） |
|
|
72
|
-
| **`interactions === 0` / `null`** | **平均费用**（`spend / interactions`）与 **互动率** 列填 **`—`**，禁止除零 |
|
|
67
|
+
### 点击率 / 转化率 / 互动率
|
|
73
68
|
|
|
74
|
-
>
|
|
69
|
+
> **2026-05 起 CLI 已统一归一**（manifest `schemaVersion: 2`）：所有 `<section>-*.json` 中的 `ctr` / `conversionRate` 一律为 **0~1 小数**（如 `0.10` = 10.00%）。详见 `references/account-analytics.md`「指标字段对照」。
|
|
70
|
+
|
|
71
|
+
| 场景 | 处理 |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| 写入 Excel **0~1 小数列**（点击率/转化率/互动率） | 直接写入 JSON 数值（**禁止**再 ÷100） |
|
|
74
|
+
| 写客户话术 / 文案的 `x%` | `(v * 100).toFixed(2) + "%"` |
|
|
75
|
+
| `interactionRate`（字符串） | `parseFloat(row.interactionRate)` 后按数值字段使用（同样 0~1 小数） |
|
|
76
|
+
| `interactions === 0` / `null` | **平均费用**（`spend / interactions`）与 **互动率** 列填 **`—`**，禁止除零 |
|
|
75
77
|
|
|
76
78
|
### 工作簿级
|
|
77
79
|
|
|
78
|
-
| 顺序 | Sheet 名 |
|
|
79
|
-
| ---: |
|
|
80
|
-
| 1 | `账户报告` | `campaigns` + 复盘文案（stats/overview
|
|
80
|
+
| 顺序 | Sheet 名 | 数据来源 |
|
|
81
|
+
| ---: | --- | --- |
|
|
82
|
+
| 1 | `账户报告` | `campaigns` + 复盘文案（stats/overview 汇总后 Agent 撰写） |
|
|
81
83
|
| 2 | `关键词` | `keywords` |
|
|
82
84
|
| 3 | `搜索词` | `search-terms` |
|
|
83
|
-
| 4 | `设备` | **`campaign-device
|
|
84
|
-
| 5 | `国家` | **`campaign-geo
|
|
85
|
+
| 4 | `设备` | **`campaign-device-*.json`**（按系列/组拆行） |
|
|
86
|
+
| 5 | `国家` | **`campaign-geo-*.json`**（按系列/地域拆行） |
|
|
85
87
|
|
|
86
88
|
### 各 Sheet 共同版式
|
|
87
89
|
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
- **点击率、转化率、互动率**等列：样表为 **0～1 小数**（例如 7.95% 存 `0.0795`）；若写百分比数字列须与运营约定二选一，**禁止**同一文件混用。
|
|
96
|
-
- **费用、CPC、每次转化费用、预算**等：与 `references/account-analytics.md` 一致；`campaigns` 中 **`budgetAmount` 为分**，展示为「元」须 **÷100**；同条 `spend`、`averageCpc` 等已为**元**。
|
|
90
|
+
- **R1（A1）**：报告标题（见各 Sheet 表）；建议合并单元格横跨该 Sheet R3 表头全部列。
|
|
91
|
+
- **R2（A2）**：统计区间，中文可读：`YYYY年M月D日 - YYYY年M月D日`。
|
|
92
|
+
- **R3**：表头（列名、顺序须与下表一致）。
|
|
93
|
+
- **R4 起**：数据行；列宽、自动筛选、首行冻结、降序排序为可选，**不得**因此改数。
|
|
94
|
+
- **百分比列**：样表为 0~1 小数（如 7.95% 存 `0.08`）；与运营约定二选一，**禁止**同一文件混用。
|
|
95
|
+
- **金额**：与 `references/account-analytics.md` 一致；`campaigns.budgetAmount` 为分，展示「元」须 ÷100；`spend`、`averageCpc` 等已为元。
|
|
97
96
|
|
|
98
97
|
---
|
|
99
98
|
|
|
@@ -101,22 +100,23 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
101
100
|
|
|
102
101
|
| 行 | 内容 |
|
|
103
102
|
| --- | --- |
|
|
104
|
-
| R1
|
|
105
|
-
| R2 |
|
|
106
|
-
| R3
|
|
107
|
-
| R4… |
|
|
108
|
-
| 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；**展示 / 点击 / 所有转化次数 / 转化次数 /
|
|
103
|
+
| R1 | `广告系列报告`（如运营改名，可改文案但 Sheet 名仍为 `账户报告`） |
|
|
104
|
+
| R2 | 统计区间 |
|
|
105
|
+
| R3（A→K，11 列） | `广告系列` \| `预算` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
106
|
+
| R4… | 来自 `campaigns-*.json`：`campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks`、`ctr`（已归一直接写入「点击率」）、`averageCpc`、`allConversions`→「所有转化次数」、`conversions`→「转化次数」、`costPerConversion`、`conversionRate`（已归一直接写入「转化率」）；缺 `allConversions` 时与「转化次数」同值或填 `0` / `—`，并在脚注说明 |
|
|
107
|
+
| 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；**展示 / 点击 / 所有转化次数 / 转化次数 / 费用** 做列求和；**点击率** = 合计点击 ÷ 合计展示；**转化率** = 合计转化 ÷ 合计点击（**禁止**用合计转化 ÷ 合计展示）；**每次转化费用** = 合计费用 ÷ 合计转化（转化为 0 时填 `—`）；禁止对各行比率取算术平均 |
|
|
109
108
|
|
|
110
|
-
表下**留白若干行**后写
|
|
109
|
+
表下**留白若干行**后写 **「数据复盘」**：
|
|
111
110
|
|
|
112
111
|
- 首行标题：`{结束日所在月份}月份数据复盘：`（例：`12月份数据复盘：`）。
|
|
113
|
-
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
112
|
+
- 5 条结构化要点：
|
|
113
|
+
1. **账户层级**：整体消耗、展示、点击、点击率与 3% 基准对比、询盘/转化数、平均询盘成本（数据来自 stats/overview 与上表合计）。
|
|
114
|
+
2. **关键词层级**：高转化词、高消耗低转化词、出价/竞争力建议。
|
|
115
|
+
3. **搜索字词层级**：标红/高意向词、否词与加词建议。
|
|
116
|
+
4. **设备层级**（基于 `campaign-device`）：各设备在系列上的消耗/转化分布；可点出高消耗系列×设备组合。
|
|
117
|
+
5. **国家层级**（基于 `campaign-geo`）：各国家/地区在系列上的消耗/转化；高消耗低转化地域与降权/调价建议。
|
|
118
|
+
|
|
119
|
+
文案由 Agent 据 JSON 撰写，**不得编造**表中不存在的数字。
|
|
120
120
|
|
|
121
121
|
---
|
|
122
122
|
|
|
@@ -124,10 +124,10 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
124
124
|
|
|
125
125
|
| 行 | 内容 |
|
|
126
126
|
| --- | --- |
|
|
127
|
-
| R1
|
|
128
|
-
| R2 |
|
|
129
|
-
| R3
|
|
130
|
-
| R4… | `keywords-*.json
|
|
127
|
+
| R1 | `搜索关键字报告` |
|
|
128
|
+
| R2 | 统计区间 |
|
|
129
|
+
| R3（A→L，12 列） | `关键字` \| `匹配类型` \| `广告系列` \| `广告组` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
130
|
+
| R4… | `keywords-*.json`：`keywordMatchType`→匹配类型；`campaignName` / `adGroupName` 等按 outline；`ctr` / `conversionRate` 已归一，直接写入 |
|
|
131
131
|
|
|
132
132
|
---
|
|
133
133
|
|
|
@@ -135,10 +135,10 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
135
135
|
|
|
136
136
|
| 行 | 内容 |
|
|
137
137
|
| --- | --- |
|
|
138
|
-
| R1
|
|
138
|
+
| R1 | `搜索字词报告` |
|
|
139
139
|
| R2 | 统计区间 |
|
|
140
|
-
| R3
|
|
141
|
-
| R4… | `search-terms-*.json
|
|
140
|
+
| R3（A→N，14 列） | `搜索字词` \| `匹配类型` \| `已添加/已排除` \| `广告系列` \| `广告组` \| `关键字` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
141
|
+
| R4… | `search-terms-*.json`：`已添加/已排除` 若 JSON 无此枚举则留空或填「—」，禁止臆造；`ctr` / `conversionRate` 已归一，直接写入 |
|
|
142
142
|
|
|
143
143
|
---
|
|
144
144
|
|
|
@@ -146,10 +146,10 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
146
146
|
|
|
147
147
|
| 行 | 内容 |
|
|
148
148
|
| --- | --- |
|
|
149
|
-
| R1
|
|
149
|
+
| R1 | `设备报告` |
|
|
150
150
|
| R2 | 统计区间 |
|
|
151
|
-
| R3
|
|
152
|
-
| R4… |
|
|
151
|
+
| R3（A→M，13 列） | `设备` \| `级别` \| `广告系列` \| `出价调整` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
152
|
+
| R4… | `campaign-device-*.json`（`devices[]`）：`deviceType`→设备；`campaignName` / `adGroupName`→「广告系列」等；`allConversions`→「所有转化次数」；`conversions`→「转化次数」；`ctr` / `conversionRate` 直接写入；**出价调整** 无字段则「—」；**级别**列按运营约定（如填 `广告系列` 或 `账户`，全文一致） |
|
|
153
153
|
|
|
154
154
|
---
|
|
155
155
|
|
|
@@ -157,24 +157,16 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
157
157
|
|
|
158
158
|
| 行 | 内容 |
|
|
159
159
|
| --- | --- |
|
|
160
|
-
| R1
|
|
160
|
+
| R1 | `地理位置报告` |
|
|
161
161
|
| R2 | 统计区间 |
|
|
162
|
-
| R3
|
|
163
|
-
| R4… |
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
|
-
## Excel 交付（谁来做）
|
|
168
|
-
|
|
169
|
-
若用户或运营要求交付 **xlsx**：须满足上文**最终 xlsx 版式规范**；实现仍遵守本文开头「架构约定」——**仅**由 Agent 写脚本生成，**无** CLI 内置写表命令。
|
|
162
|
+
| R3（A→M，13 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
|
|
163
|
+
| R4… | `campaign-geo-*.json`（`countries[]`）：`countryOrRegion`→地理位置；`campaignName`→「广告系列」；`allConversions`→「所有转化次数」；`conversions`→「转化次数」；**互动次数**→`interactions`；**互动率**→`interactionRate`（字符串须解析）或 `interactions/impressions`，`interactions` 为 0 时填 `—`；**平均费用 必须** = `spend / interactions`，`interactions` 为 0 / null / undefined 时填 `—`；`ctr` / `conversionRate` 直接写入；其余列按 outline 映射 |
|
|
170
164
|
|
|
171
165
|
---
|
|
172
166
|
|
|
173
167
|
## 对外客户话术（固定结构，填数来自 JSON）
|
|
174
168
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
`统计区间：<S> ~ <E>（货币：<币种>）`
|
|
169
|
+
首行：`统计区间：<S> ~ <E>（货币：<币种>）`
|
|
178
170
|
|
|
179
171
|
正文模板：
|
|
180
172
|
|
|
@@ -191,29 +183,25 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
|
|
|
191
183
|
8. 账户余额：<金额+币种>（截至查询时点）
|
|
192
184
|
```
|
|
193
185
|
|
|
194
|
-
**第
|
|
195
|
-
|
|
196
|
-
|
|
186
|
+
- **第 1 条「平均每天」**：`区间总消耗 / 区间日历天数`（含起止日），脚本计算，禁止手填。
|
|
187
|
+
- **第 3 条**：CLI 返回的若是账户整体 CTR，写「整体点击率」而非「搜索点击率」；可区分时再写「搜索点击率」。`overview-*.json`（`schemaVersion: 2`）的 `ctr` 已是 0~1 小数（如 `0.10`），话术 `x%` 用 `(ctr * 100).toFixed(2) + "%"`，**禁止**直接打印数值得到 "0.10%"。
|
|
188
|
+
- **所有金额、百分比** 一律 **2 位小数**。
|
|
197
189
|
|
|
198
190
|
---
|
|
199
191
|
|
|
200
|
-
## 复盘小结 +
|
|
192
|
+
## 复盘小结 + 优化建议（对内 / 邮件末段）
|
|
201
193
|
|
|
202
|
-
基于同一批 JSON
|
|
194
|
+
基于同一批 JSON（`campaigns`、`keywords`、`search-terms`、`campaign-device`、`campaign-geo`、`overview`）：
|
|
203
195
|
|
|
204
|
-
- **复盘**：3
|
|
205
|
-
- **优化建议**：3
|
|
196
|
+
- **复盘**：3~6 条 bullet：消耗集中度、高消耗系列/词、地域与设备差异、CTR/CPC 相对水平。
|
|
197
|
+
- **优化建议**：3~5 条可执行项（预算、否词、落地页、系列状态等），**不额外拉数**；缺数据则标 `[数据不可用：原因]`。
|
|
206
198
|
|
|
207
199
|
---
|
|
208
200
|
|
|
209
201
|
## 与 `google-period-report.md` 的差异
|
|
210
202
|
|
|
211
|
-
| 项 |
|
|
212
|
-
|
|
|
213
|
-
| 默认维度 | 8 维 +
|
|
214
|
-
| 输出形态 | 长文分析报告 | **固定话术** + 短复盘 + **多 Sheet Excel（Agent
|
|
203
|
+
| 项 | `google-period-report.md` | 本文 OKKI 周报 |
|
|
204
|
+
| --- | --- | --- |
|
|
205
|
+
| 默认维度 | 8 维 + 主动追问追加 | **固定** `overview,campaigns,keywords,search-terms,campaign-device,campaign-geo` + `stats` + `balance` |
|
|
206
|
+
| 输出形态 | 长文分析报告 | **固定话术** + 短复盘 + **多 Sheet Excel（Agent 脚本写）** |
|
|
215
207
|
| 典型用户 | 内部分析 | **发客户**的同步简报 |
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|