siluzan-tso-cli 1.1.45 → 1.1.46-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.
Files changed (27) hide show
  1. package/README.md +2 -1
  2. package/dist/index.js +480 -106
  3. package/dist/skill/_meta.json +2 -2
  4. package/dist/skill/references/accounts/accounts-balance-stats.md +10 -10
  5. package/dist/skill/references/accounts/accounts-list.md +1 -1
  6. package/dist/skill/references/accounts/accounts-permissions.md +2 -2
  7. package/dist/skill/references/accounts/finance.md +1 -1
  8. package/dist/skill/references/accounts/open-account-by-media.md +1 -1
  9. package/dist/skill/references/accounts/open-account-google-ui.md +1 -1
  10. package/dist/skill/references/analytics/account-analytics.md +74 -13
  11. package/dist/skill/references/analytics/rag.md +1 -1
  12. package/dist/skill/references/analytics/reporting.md +5 -5
  13. package/dist/skill/references/core/setup.md +5 -5
  14. package/dist/skill/references/google-ads/rules/google-ads-keyword-strategy.md +8 -8
  15. package/dist/skill/references/misc/tso-home.md +2 -2
  16. package/dist/skill/references/operations/hosted-automation-monitoring-json.md +9 -9
  17. package/dist/skill/references/operations/hosted-automation-scenarios.md +2 -0
  18. package/dist/skill/references/report-templates/REPORT-WORKFLOW.md +3 -3
  19. package/dist/skill/references/report-templates/yandex-period-report-excel.md +45 -45
  20. package/dist/skill/references/report-templates/yandex-period-report.md +26 -27
  21. package/dist/skill/report-templates/REPORT-WORKFLOW.md +3 -3
  22. package/dist/skill/report-templates/yandex-period-report-excel.md +45 -45
  23. package/dist/skill/report-templates/yandex-period-report.html +1377 -1164
  24. package/dist/skill/report-templates/yandex-period-report.md +26 -27
  25. package/dist/skill/scripts/install.ps1 +3 -3
  26. package/dist/skill/scripts/install.sh +3 -3
  27. package/package.json +1 -1
package/dist/skill/references/report-templates/yandex-period-report.md CHANGED
@@ -8,16 +8,16 @@
8
8
 
9
9
  数据块（YandexAPI `/yandex-analysis` 8 维 + 本地周聚合）：总览、按日、Search 网络、系列、关键词、搜索词、地域、设备；周报由 CLI 写入 `daily.weekly`（后端无独立 weekly）。**禁止**自行按 `date` 聚周。
10
10
 
11
- | CLI `--sections` | 落盘形状（CI 实测） | 报告 `tables.*` / KPI |
12
- | ---------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
13
- | `overview` | 对象：`account` / `currency` / `balance` / `totals` … | → `meta` + `kpis`（余额、日均、续航天数） |
11
+ | CLI `--sections` | 落盘形状（CI 实测） | 报告 `tables.*` / KPI |
12
+ | ---------------- | --------------------------------------------------------------------- | ------------------------------------------------ |
13
+ | `overview` | 对象：`account` / `currency` / `balance` / `totals` … | → `meta` + `kpis`（余额、日均、续航天数） |
14
14
  | `daily` | `{ account, startDate, endDate, items: DayRow[], weekly: WeekRow[] }` | → `tables.daily[]` + `tables.weekly[]`（勿重算） |
15
- | `search` | `{ …, items: SearchRow[] }` | → `tables.search[]` |
16
- | `campaigns` | `{ …, items: CampaignRow[] }`（默认 limit=100） | → `tables.campaigns[]` |
17
- | `keywords` | `{ …, items: KeywordRow[] }` | → `tables.keywords[]` |
18
- | `search-terms` | `{ …, items: SearchTermRow[] }`（**仅近 180 天**） | → `tables.searchTerms[]` |
19
- | `geo` | `{ …, items: GeoRow[] }` | → `tables.geo[]` |
20
- | `devices` | `{ …, items: DeviceRow[] }` | → `tables.devices[]` |
15
+ | `search` | `{ …, items: SearchRow[] }` | → `tables.search[]` |
16
+ | `campaigns` | `{ …, items: CampaignRow[] }`（默认 limit=100） | → `tables.campaigns[]` |
17
+ | `keywords` | `{ …, items: KeywordRow[] }` | → `tables.keywords[]` |
18
+ | `search-terms` | `{ …, items: SearchTermRow[] }`（**仅近 180 天**） | → `tables.searchTerms[]` |
19
+ | `geo` | `{ …, items: GeoRow[] }` | → `tables.geo[]` |
20
+ | `devices` | `{ …, items: DeviceRow[] }` | → `tables.devices[]` |
21
21
 
22
22
  > 金额已为账户币种小数；`ctr` / `conversionRate` 为 **0~1 小数**。写叙事前先读各维 `*.outline.txt`。
23
23
 
@@ -25,12 +25,12 @@
25
25
 
26
26
  ## 标准四步流程（默认 · 交付 HTML）
27
27
 
28
- | 步骤 | 执行者 | 动作 |
29
- | ---------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
30
- | **1. 拉数** | Agent 调 CLI | `yandex-analysis -a <porg-xxx> --start <s> --end <e> --json-out ./snap-yandex`（全 8 维或 `--sections` 指定子集） |
31
- | **2. 分析** | Agent | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`）。周趋势读 `daily-*.json` 的 `weekly[]`，**禁止**自己按 `date` 聚周。 |
28
+ | 步骤 | 执行者 | 动作 |
29
+ | ---------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | **1. 拉数** | Agent 调 CLI | `yandex-analysis -a <porg-xxx> --start <s> --end <e> --json-out ./snap-yandex`（全 8 维或 `--sections` 指定子集） |
31
+ | **2. 分析** | Agent | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`）。周趋势读 `daily-*.json` 的 `weekly[]`，**禁止**自己按 `date` 聚周。 |
32
32
  | **3. 写 JSON** | Agent | 撰写 `yandex-period-report.json`：仅 `meta.accountId` + `narrative`（8 个分析章节）为必填；`kpis`/`tables` 可省略由 `--snapshot-dir` 合并 |
33
- | **4. 渲染 HTML** | CLI | `yandex-analysis render` — **校验 narrative 8 个分析章节必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML |
33
+ | **4. 渲染 HTML** | CLI | `yandex-analysis render` — **校验 narrative 8 个分析章节必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML |
34
34
 
35
35
  ```bash
36
36
  # 步骤 1
@@ -57,7 +57,6 @@ siluzan-tso yandex-analysis render \
57
57
  - `geo[]`：`{locationName, targetingLocationName, network, …metrics}`
58
58
  - `devices[]`：`{device, network, …metrics}`
59
59
  - `narrative`（**Agent 必填**）：
60
- - `executiveSummary[]`：≥1 段执行摘要
61
60
  - `sections.{overview,search,campaigns,keywords,searchTerms,geo,devices,daily}`：每个维度各 `{analysis[]（≥1，含数字依据）, suggestions[]（≥1）}`
62
61
  - `recommendations[]`：≥3 条跨维度优化建议（可用 `{priority,text,anchor}`，anchor 对齐样例锚点如 `#keyword` / `#query`）
63
62
  - `rowInsights`：有关键词表格行时，**HTML 将展示的 Top N 行必须有中文翻译**；`render` 缺项会拒绝出 HTML。见下方「逐行洞察」。Campaign / 关键词 / 搜索词 / 地域 / 设备列表**不展示**「问题」「建议」列，行级判断写入各维 `sections.*.analysis/suggestions` 即可。
@@ -132,18 +131,18 @@ siluzan-tso yandex-analysis -a <porg-xxx> --start <S> --end <E> --json-out ./sna
132
131
 
133
132
  ## HTML 章节与锚点（对齐开发样例）
134
133
 
135
- | 锚点 | 章节 | 数据 / 叙事来源 |
136
- | ----------- | -------------- | ---------------------------------------------------- |
137
- | `#overview` | 账户总览 | `kpis` + `tables.weekly` + 每日折叠 + `sections.overview` |
138
- | `#next` | 后续优化动作 | `narrative.recommendations` |
139
- | `#search` | Search 网络 | `tables.search` + `sections.search` |
140
- | `#campaign` | Campaign | `tables.campaigns` + `sections.campaigns` |
141
- | `#keyword` | 关键词 | `tables.keywords` + `sections.keywords` |
142
- | `#query` | 搜索词 | `tables.searchTerms` + `sections.searchTerms` |
143
- | `#geo` | 地域 | `tables.geo` + `sections.geo` |
144
- | `#device` | 设备 | `tables.devices` + `sections.devices` |
145
- | `#daily` | 日报表 | `tables.daily` + `sections.daily` |
146
- | `#weekly` | 周报表 | `tables.weekly`（同 daily 叙事） |
134
+ | 锚点 | 章节 | 数据 / 叙事来源 |
135
+ | ----------- | ------------ | --------------------------------------------------------- |
136
+ | `#overview` | 账户总览 | `kpis` + `tables.weekly` + 每日折叠 + `sections.overview` |
137
+ | `#next` | 后续优化动作 | `narrative.recommendations` |
138
+ | `#search` | Search 网络 | `tables.search` + `sections.search` |
139
+ | `#campaign` | Campaign | `tables.campaigns` + `sections.campaigns` |
140
+ | `#keyword` | 关键词 | `tables.keywords` + `sections.keywords` |
141
+ | `#query` | 搜索词 | `tables.searchTerms` + `sections.searchTerms` |
142
+ | `#geo` | 地域 | `tables.geo` + `sections.geo` |
143
+ | `#device` | 设备 | `tables.devices` + `sections.devices` |
144
+ | `#daily` | 日报表 | `tables.daily` + `sections.daily` |
145
+ | `#weekly` | 周报表 | `tables.weekly`（同 daily 叙事） |
147
146
 
148
147
  ---
149
148
 
package/dist/skill/report-templates/REPORT-WORKFLOW.md CHANGED
@@ -23,9 +23,9 @@
23
23
 
24
24
  根据媒体与用户意图，选择 `report-templates/` 下对应的 `*.md`：
25
25
 
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` |
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） | 同周期，注明能力受限 | 同周期 |
package/dist/skill/report-templates/yandex-period-report-excel.md CHANGED
@@ -9,15 +9,15 @@
9
9
 
10
10
  ## 执行门禁（**全部满足后才允许写脚本**）
11
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 摘要 |
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
21
 
22
22
  ---
23
23
 
@@ -31,17 +31,17 @@
31
31
 
32
32
  用户已列出 Sheet 名时以用户清单为准；未列出时可用下表默认 7 Sheet（周报由脚本从 daily 聚合，不必单独拉）：
33
33
 
34
- | Sheet（建议名） | `yandex-analysis` section | 读法 |
35
- | --------------- | ------------------------- | ---------------------------- |
36
- | 账户总览 | `overview` | 对象：`totals` / `balance` … |
37
- | 日报表 | `daily` | `items[]` |
34
+ | Sheet（建议名） | `yandex-analysis` section | 读法 |
35
+ | --------------- | ------------------------- | ------------------------------- |
36
+ | 账户总览 | `overview` | 对象：`totals` / `balance` … |
37
+ | 日报表 | `daily` | `items[]` |
38
38
  | 周报表 | `daily` 的 `weekly[]` | **读落盘 weekly，禁止自行聚周** |
39
- | Search 网络 | `search` | `items[]` |
40
- | 广告系列 | `campaigns` | `items[]` |
41
- | 关键词 | `keywords` | `items[]` |
42
- | 搜索词 | `search-terms` | `items[]`（区间 ≤180 天） |
43
- | 地域 | `geo` | `items[]` |
44
- | 设备 | `devices` | `items[]` |
39
+ | Search 网络 | `search` | `items[]` |
40
+ | 广告系列 | `campaigns` | `items[]` |
41
+ | 关键词 | `keywords` | `items[]` |
42
+ | 搜索词 | `search-terms` | `items[]`（区间 ≤180 天） |
43
+ | 地域 | `geo` | `items[]` |
44
+ | 设备 | `devices` | `items[]` |
45
45
 
46
46
  ```bash
47
47
  mkdir -p ./snap-yandex
@@ -56,43 +56,43 @@ siluzan-tso yandex-analysis -a <porg-xxx> --start <S> --end <E> --json-out ./sna
56
56
 
57
57
  ## 统一度量列（列表 Sheet）
58
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 |
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
69
 
70
70
  ### 维度列（按 Sheet）
71
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` |
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
81
  | 周报 | `daily.weekly[]` 的 `weekLabel`、`startDate`、`endDate`、`days`（CLI 已算） |
82
82
 
83
- **账户总览 Sheet**：KPI 区（余额、本期消耗、日均、点击、CTR、CPC、转化）+ **全部叙事**（执行摘要、各维总结/建议、≥3 条跨维优化建议）写在本 Sheet；列表 Sheet 仅数据表。
83
+ **账户总览 Sheet**：KPI 区（余额、本期消耗、日均、点击、CTR、CPC、转化）+ **全部叙事**（各维总结/建议、≥3 条跨维优化建议）写在本 Sheet；列表 Sheet 仅数据表。不写「一句话数据概况 / 执行摘要」。
84
84
 
85
85
  ---
86
86
 
87
87
  ## 禁止猜的字段 / 口径
88
88
 
89
- | ❌ 禁止 | ✅ 正确 |
90
- | ------------------------------------ | ---------------------------------------------------- |
91
- | 把 `ctr` 当已是百分数再 ÷100 | 落盘为 0~1；Excel 用百分比格式或 `*100` 后加 `%` |
92
- | 编造学习期、搜索词分类等无接口硬事实 | 无字段且算不出则不写该列；关键词翻译走 rowInsights |
89
+ | ❌ 禁止 | ✅ 正确 |
90
+ | ---------------------------------------------- | ------------------------------------------------------------------ |
91
+ | 把 `ctr` 当已是百分数再 ÷100 | 落盘为 0~1；Excel 用百分比格式或 `*100` 后加 `%` |
92
+ | 编造学习期、搜索词分类等无接口硬事实 | 无字段且算不出则不写该列；关键词翻译走 rowInsights |
93
93
  | 自行按 `daily.date` 聚周（易出 `NaN-NaN-NaN`） | 读 `daily.weekly[]`；`date` 已是 YYYY-MM-DD，禁止再拼 `T00:00:00Z` |
94
- | `campaignId` 写成数字 | `String(id)` + 文本格式 |
95
- | search-terms 拉超过 180 天 | 缩短区间或排除该维 |
94
+ | `campaignId` 写成数字 | `String(id)` + 文本格式 |
95
+ | search-terms 拉超过 180 天 | 缩短区间或排除该维 |
96
96
 
97
97
  ---
98
98