siluzan-tso-cli 1.1.44 → 1.1.45-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 +1001 -118
- package/dist/skill/SKILL.md +1 -0
- package/dist/skill/_meta.json +2 -2
- package/dist/skill/references/README.md +1 -0
- package/dist/skill/references/accounts/accounts-balance-stats.md +3 -3
- package/dist/skill/references/accounts/accounts-list.md +1 -1
- package/dist/skill/references/accounts/accounts-permissions.md +2 -2
- package/dist/skill/references/accounts/finance.md +1 -1
- package/dist/skill/references/accounts/open-account-by-media.md +1 -1
- package/dist/skill/references/accounts/open-account-google-ui.md +1 -1
- package/dist/skill/references/analytics/account-analytics.md +44 -1
- package/dist/skill/references/analytics/rag.md +1 -1
- package/dist/skill/references/analytics/reporting.md +5 -5
- package/dist/skill/references/core/playbooks.md +1 -1
- package/dist/skill/references/core/setup.md +5 -5
- package/dist/skill/references/misc/tso-home.md +2 -2
- package/dist/skill/references/operations/hosted-automation-monitoring-json.md +1 -1
- package/dist/skill/references/report-templates/README.md +2 -0
- package/dist/skill/references/report-templates/REPORT-WORKFLOW.md +6 -4
- package/dist/skill/references/report-templates/yandex-period-report-excel.md +123 -0
- package/dist/skill/references/report-templates/yandex-period-report.md +121 -0
- package/dist/skill/report-templates/README.md +2 -0
- package/dist/skill/report-templates/REPORT-WORKFLOW.md +6 -4
- package/dist/skill/report-templates/yandex-period-report-excel.md +123 -0
- package/dist/skill/report-templates/yandex-period-report.html +968 -0
- package/dist/skill/report-templates/yandex-period-report.md +121 -0
- package/dist/skill/scripts/install.ps1 +3 -3
- package/dist/skill/scripts/install.sh +3 -3
- package/package.json +3 -1
|
@@ -23,9 +23,9 @@
|
|
|
23
23
|
|
|
24
24
|
根据媒体与用户意图，选择 `report-templates/` 下对应的 `*.md`：
|
|
25
25
|
|
|
26
|
-
| 意图 | Google | Meta | TikTok | Bing |
|
|
27
|
-
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | ----------------------- |
|
|
28
|
-
| 周期分析 / 月报 / 周报 | `google-period-report.md` | `meta-period-report.md` | `tiktok-period-report.md` | `bing-period-report.md` |
|
|
26
|
+
| 意图 | Google | Meta | TikTok | Bing | Yandex |
|
|
27
|
+
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | ----------------------- | --------------------------- |
|
|
28
|
+
| 周期分析 / 月报 / 周报 | `google-period-report.md` | `meta-period-report.md` | `tiktok-period-report.md` | `bing-period-report.md` | `yandex-period-report.md` |
|
|
29
29
|
| OKKI 周报 / 固定话术发客户（Google） | `okki-weekly-google-client.md` | — | — | — |
|
|
30
30
|
| **询盘分析** / 固定运营触发（Goog账户询盘分析 / 我给你询盘信息分析Google账号XXX效果） | `google-inquiry-analysis.md`（**严格 3 个月** + 用户上传询盘资料 + 8 Sheet xlsx；见 SKILL **P7**） | — | — | — |
|
|
31
31
|
| 深度诊断 / 健康检查 | `google-account-diagnosis-report.md` | `meta-account-diagnosis-report.md`（`facebook-analysis diagnosis-render` 出 HTML） | 同周期，注明能力受限 | 同周期 |
|
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
|
|
60
60
|
### 步骤 4：拉取数据
|
|
61
61
|
|
|
62
|
-
- **`google-analysis` / `facebook-analysis` / `tiktok-analysis` / `bing-analysis` / `report …` 账户分析子命令**：统一 **`--json-out <目录>`** 落盘，再由脚本读 **`manifest-<accountId>.json` / `report-manifest-<accountId>.json`**（清单文件名见 stdout 摘要的 `manifestFile`）与各 **`<section>-<accountId>.json`**（见 `references/analytics/account-analytics.md`）。
|
|
62
|
+
- **`google-analysis` / `facebook-analysis` / `tiktok-analysis` / `bing-analysis` / `yandex-analysis` / `report …` 账户分析子命令**：统一 **`--json-out <目录>`** 落盘，再由脚本读 **`manifest-<accountId>.json` / `report-manifest-<accountId>.json`**（清单文件名见 stdout 摘要的 `manifestFile`）与各 **`<section>-<accountId>.json`**（见 `references/analytics/account-analytics.md`）。
|
|
63
63
|
- **`stats`、`ad campaigns` 等辅助命令**：按 `references/core/tips.md` 与各命令文档做结构化拉数。
|
|
64
64
|
- 仅执行与**本次报告维度**对应的命令（默认 + 用户追加）。
|
|
65
65
|
- 数据失败/缺失：在对应章节写 `[ 数据不可用：{原因} ]`，不写推测。
|
|
@@ -83,6 +83,7 @@
|
|
|
83
83
|
- **Google 周期报告**：产出 `google-period-report.json`（见 `google-period-report.md`，仅 `meta` + `narrative` 为必填）。
|
|
84
84
|
- **TikTok 周期报告**：产出 `tiktok-period-report.json`（见 `tiktok-period-report.md`，`meta` 可由 `--snapshot-dir` 自动合并）。
|
|
85
85
|
- **Bing 周期报告**：产出 `bing-period-report.json`（见 `bing-period-report.md`，`meta`/`kpis` 可由 `--snapshot-dir` 自动合并）。
|
|
86
|
+
- **Yandex 周期报告**：产出 `yandex-period-report.json`（见 `yandex-period-report.md`，`meta`/`kpis`/`tables` 可由 `--snapshot-dir` 自动合并）。
|
|
86
87
|
- **其余场景**（OKKI、询盘等未接入 render 的模板）：可直接组织 Markdown/HTML 正文。
|
|
87
88
|
|
|
88
89
|
### 步骤 5b：生成终稿（按媒体与格式）
|
|
@@ -94,6 +95,7 @@
|
|
|
94
95
|
| **Google 周期报告** | `google-analysis render` → **HTML**（必做） | **周期/定制 Sheet**：`google-period-report-excel.md`（P4，先 outline 后脚本）；**不**默认 `render` |
|
|
95
96
|
| **TikTok 周期报告** | `tiktok-analysis render` → **HTML**（必做） | Agent 脚本写 xlsx；**不**默认 `render` |
|
|
96
97
|
| **Bing 周期报告** | `bing-analysis render` → **HTML**（必做） | Agent 脚本写 xlsx；**不**默认 `render` |
|
|
98
|
+
| **Yandex 周期报告** | `yandex-analysis render` → **HTML**（必做） | Agent 脚本按 `yandex-period-report-excel.md` 写 xlsx；**不**默认 `render` |
|
|
97
99
|
| **Google 诊断/OKKI/询盘** | 按 `report-template*.html` 写 HTML（默认 `report-template.html`） | **诊断**：同左；**OKKI**：P6；**询盘**：P7 |
|
|
98
100
|
| **网站诊断** | `website-diagnosis render` → HTML | — |
|
|
99
101
|
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Yandex Direct 账户周期报告 — Excel 交付规格
|
|
2
|
+
|
|
3
|
+
> **适用场景**：用户明确要求 **Yandex 账户 + 统计区间 + Excel/xlsx**。
|
|
4
|
+
> **工作流**：**P4**（与 `yandex-period-report.md` 共用拉数维度；交付形态不同）。
|
|
5
|
+
> **禁止**：加载宿主「xlsx / Excel」第三方 Skill 代替本流程；**无** CLI 内置写表子命令，须 Agent 脚本（`exceljs` / `xlsx` / `openpyxl`）读落盘 JSON 写 `.xlsx`。
|
|
6
|
+
> 用户未指定格式时走 `yandex-period-report.md` → `yandex-analysis render` HTML，**不要**默认走本文。
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 执行门禁（**全部满足后才允许写脚本**）
|
|
11
|
+
|
|
12
|
+
| # | 门禁 | 命令 / 动作 |
|
|
13
|
+
| --- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
14
|
+
| 1 | Read 当次必读 | `agent-conventions.md`、`account-analytics.md`、`yandex-period-report.md`（本文） |
|
|
15
|
+
| 2 | **账户 ID 核验** | `siluzan-tso list-accounts -m Yandex -k <porg-xxx> --json-out ./snap-yandex` |
|
|
16
|
+
| 3 | 确认 `currency` | 来自 overview 落盘或 list-accounts（Yandex 常用 USD/RUB 等） |
|
|
17
|
+
| 4 | **拉数** | `yandex-analysis -a <已核验 id> --start … --end … --json-out <dir>`（全 8 维或用户指定 Sheet 对应维） |
|
|
18
|
+
| 5 | **先 outline 后脚本** | 对本次每个 section Read `*.outline.txt`；业务 JSON 仅在脚本内读取 |
|
|
19
|
+
| 6 | 写脚本 | 字段名只来自 outline；`ctr`/`conversionRate` 为 **0~1 小数** |
|
|
20
|
+
| 7 | 交付前审阅 | 按 `agent-conventions.md` §七；xlsx 无法 Read 时贴自检表 + 脚本 stdout 摘要 |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 账户 ID
|
|
25
|
+
|
|
26
|
+
`list-accounts -m Yandex -k <porg-xxx>` 核验；全流程用同一 Client-Login。报告首行：`统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`。
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 推荐 Sheet ↔ CLI section
|
|
31
|
+
|
|
32
|
+
用户已列出 Sheet 名时以用户清单为准；未列出时可用下表默认 7 Sheet（周报由脚本从 daily 聚合，不必单独拉）：
|
|
33
|
+
|
|
34
|
+
| Sheet（建议名） | `yandex-analysis` section | 读法 |
|
|
35
|
+
| --------------- | ------------------------- | ---------------------------- |
|
|
36
|
+
| 账户总览 | `overview` | 对象：`totals` / `balance` … |
|
|
37
|
+
| 日报表 | `daily` | `items[]` |
|
|
38
|
+
| 周报表 | （无） | 脚本按 ISO 周聚合 `daily` |
|
|
39
|
+
| Search 网络 | `search` | `items[]` |
|
|
40
|
+
| 广告系列 | `campaigns` | `items[]` |
|
|
41
|
+
| 关键词 | `keywords` | `items[]` |
|
|
42
|
+
| 搜索词 | `search-terms` | `items[]`（区间 ≤180 天） |
|
|
43
|
+
| 地域 | `geo` | `items[]` |
|
|
44
|
+
| 设备 | `devices` | `items[]` |
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
mkdir -p ./snap-yandex
|
|
48
|
+
siluzan-tso list-accounts -m Yandex -k <porg-xxx> --json-out ./snap-yandex
|
|
49
|
+
|
|
50
|
+
siluzan-tso yandex-analysis -a <porg-xxx> --start <S> --end <E> --json-out ./snap-yandex
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
落盘文件名以 stdout 摘要 `results[].file` 为准。
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 统一度量列（列表 Sheet）
|
|
58
|
+
|
|
59
|
+
| Excel 列名 | API 字段 | 说明 |
|
|
60
|
+
| ---------- | -------------------- | ----------------------------- |
|
|
61
|
+
| 消耗 | `spend` | 账户币种小数，2 位 |
|
|
62
|
+
| 展示 | `impressions` | 整数 |
|
|
63
|
+
| 点击 | `clicks` | 整数 |
|
|
64
|
+
| CTR | `ctr` | 0~1；单元格 `0.00%` 或文案 % |
|
|
65
|
+
| CPC | `averageCpc` | 小数 |
|
|
66
|
+
| 转化 | `conversions` | 小数/整数按 outline |
|
|
67
|
+
| 转化率 | `conversionRate` | 0~1 |
|
|
68
|
+
| CPA | `costPerConversion` | 可为 null |
|
|
69
|
+
|
|
70
|
+
### 维度列（按 Sheet）
|
|
71
|
+
|
|
72
|
+
| Sheet | 维度列（API） |
|
|
73
|
+
| -------- | ----------------------------------------------------------------------------- |
|
|
74
|
+
| Search | `network` |
|
|
75
|
+
| 广告系列 | `campaignId`（文本）、`campaignName`、`status`/`state`、`campaignType` |
|
|
76
|
+
| 关键词 | `keyword`、`campaignName`、`criteriaType`、`adGroupId`（文本） |
|
|
77
|
+
| 搜索词 | `searchQuery`、`matchedKeyword`、`campaignName` |
|
|
78
|
+
| 地域 | `locationName` / `targetingLocationName` |
|
|
79
|
+
| 设备 | `device` |
|
|
80
|
+
| 日报 | `date` |
|
|
81
|
+
| 周报 | `weekLabel`、`startDate`、`endDate`、`days`（脚本生成） |
|
|
82
|
+
|
|
83
|
+
**账户总览 Sheet**：KPI 区（余额、本期消耗、日均、点击、CTR、CPC、转化）+ **全部叙事**（执行摘要、各维总结/建议、≥3 条跨维优化建议）写在本 Sheet；列表 Sheet 仅数据表。
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## 禁止猜的字段 / 口径
|
|
88
|
+
|
|
89
|
+
| ❌ 禁止 | ✅ 正确 |
|
|
90
|
+
| ------------------------------------ | ---------------------------------------------------- |
|
|
91
|
+
| 把 `ctr` 当已是百分数再 ÷100 | 落盘为 0~1；Excel 用百分比格式或 `*100` 后加 `%` |
|
|
92
|
+
| 编造学习期 / 翻译字段 | API 无则叙事说明「数据不可用」 |
|
|
93
|
+
| `campaignId` 写成数字 | `String(id)` + 文本格式 |
|
|
94
|
+
| search-terms 拉超过 180 天 | 缩短区间或排除该维 |
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 禁止的数据探查方式
|
|
99
|
+
|
|
100
|
+
- `cat …json \| python -m json.tool \| head`
|
|
101
|
+
- 宿主 **Read** 打开业务 `*.json`
|
|
102
|
+
- 把 JSON 片段贴进对话当字段依据
|
|
103
|
+
|
|
104
|
+
**允许**：Read `*.outline.txt`；脚本 stdout 打印行数 / 汇总。
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 交付前自检
|
|
109
|
+
|
|
110
|
+
- [ ] `accountId` = 用户要求的 `porg-xxx`
|
|
111
|
+
- [ ] 每个 Sheet 列均能在对应 outline 找到源字段
|
|
112
|
+
- [ ] `itemCount` 与 Excel 数据行一致（±合计行）
|
|
113
|
+
- [ ] 全部 ID 列为文本
|
|
114
|
+
- [ ] 未调用 `yandex-analysis render`（Excel 路径）
|
|
115
|
+
- [ ] 未使用第三方 xlsx Skill 替代拉数口径
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 相关文档
|
|
120
|
+
|
|
121
|
+
- `yandex-period-report.md` — 默认 HTML 四步
|
|
122
|
+
- `references/analytics/account-analytics.md` — 命令与日期
|
|
123
|
+
- `references/core/tips.md` — 摘要 → outline → 脚本
|