siluzan-tso-cli 1.1.36 → 1.1.37-beta.2

package/dist/skill/report-templates/bing-period-report.md

@@ -2,9 +2,75 @@
 
 > 统计区间：`{startDate}` ~ `{endDate}`（**不可包含今天或昨天**，见下文）  
 > 账户：`{mediaCustomerId}`（`{mediaCustomerName}`）  
-> **默认交付**：**HTML**（Agent 脚本读落盘 JSON 生成；禁止仅 Markdown 摘要或纯 JSON 充当终稿）。用户指定 Excel 时 Agent 脚本写 xlsx，**无** CLI `render` 子命令。
+> **默认交付物**：一份可打开的、带 ECharts 图表的 **HTML 文件**（`bing-period-report.html`）。  
+> 用户**未指定格式**时一律走下方 **标准四步流程**；**禁止** Agent 手写/拼接 HTML（语法错误会导致报告无法显示）。  
+> **用户明确要求 Excel / xlsx** 时：拉数步骤不变，改为 Agent 脚本写 `.xlsx`；**不要**调用 `bing-analysis render`；禁止假设存在内置 excel 子命令。
+
+数据块（Bing 实际支持的 9 类业务维度 + 总览）：总览、设备、地域、受众（年龄/性别）、系列、广告组、广告、关键词、搜索字词。
+
+| CLI `--sections` | 落盘形状（生产实测） | 报告 `tables.*` / KPI |
+| --- | --- | --- |
+| `overview` | 对象：`currentPeriod` / `previousPeriod` / `balance` / `averageDailyCost` … | → `meta` + `kpis`（环比、余额、日均） |
+| `device` | `{ devices: Row[] }` | → `tables.devices[]` |
+| `geographic` | `{ countries: Row[] }` | → `tables.geographic[]` |
+| `audience-merged`（或 `age-audience`/`gender-audience`） | `{ data: { ageAudience.audience[], genderAudience.audience[] } }` | → `tables.audienceAge[]` / `audienceGender[]` |
+| `campaigns` | **根节点数组** | → `tables.campaigns[]`；**本期 KPI 优先由此累加** |
+| `ad-groups` | **根节点数组** | → `tables.adGroups[]`（含 `qualityScore`） |
+| `ads` | **根节点数组** | → `tables.ads[]` |
+| `keywords` | **根节点数组**（默认 limit=100） | → `tables.keywords[]` |
+| `search-terms` | **根节点数组**（默认 limit=100） | → `tables.searchTerms[]` |
+
+> Bing **没有** Google 的 `daily-metrics` / `dimension-summary`；报告模板也不渲染这两章。
 
-数据块：总览、设备、地域、受众（年龄/性别）、系列、广告组、广告、关键词、搜索字词。
+---
+
+## 标准四步流程（默认 · 交付 HTML）
+
+| 步骤             | 执行者       | 动作                                                                                                                                                      |
+| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. 拉数**      | Agent 调 CLI | `bing-analysis -a <id> --start <s> --end <e> --json-out ./snap-bing`（见下方「日期规则」，全 11 维或 `--sections` 指定子集）                              |
+| **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），把网关原始字段映射为下方 `tables.*` 契约，完成聚合与洞察                               |
+| **3. 写 JSON**   | Agent        | 撰写 `bing-period-report.json`：仅 `meta.accountId` + `narrative`（9 个分析小节）为必填；`kpis`/`tables` 可省略由 `--snapshot-dir` 自动合并 |
+| **4. 渲染 HTML** | CLI          | `bing-analysis render` — **校验 narrative 9 个分析小节必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML                                      |
+
+```bash
+# 步骤 1
+siluzan-tso bing-analysis -a <id> --start <s> --end <e> --json-out ./snap-bing
+
+# 步骤 4（步骤 2～3 完成后）
+siluzan-tso bing-analysis render \
+  --data ./bing-period-report.json \
+  --snapshot-dir ./snap-bing \
+  --out ./bing-period-report.html
+```
+
+### `bing-period-report.json` 顶层结构
+
+- `meta`：`accountId`（必填）/ `accountName` / `currency` / `startDate` / `endDate`；可省略由 `--snapshot-dir` 从 `overview` 快照自动合并。
+- `kpis`：账户级 KPI —— `spend`/`impressions`/`clicks`/`conversions`/`ctr`/`averageCpc`/`costPerConversion`/`averageDailyCost`/`balance`/`remainingAccountBudget`，含可选 `previousPeriod` 环比对象；可省略。**本期 KPI 优先对 `campaigns` 全系列累加并重算比率**；无 campaigns 时回退 `overview.currentPeriod`。余额/日均仍来自 overview。
+- `tables`（可省略，由 `--snapshot-dir` 按上表形状自动映射）：
+  - `devices[]`：`{deviceType, spend, impressions, clicks, ctr, averageCpc, conversions, costPerConversion}`
+  - `geographic[]`：`{countryOrRegion, spend, impressions, clicks, ctr, averageCpc, conversions, costPerConversion}`
+  - `audienceAge[]`：`{ageRange, spend, impressions, clicks, ctr, averageCpc, conversions}`
+  - `audienceGender[]`：`{gender, spend, impressions, clicks, ctr, averageCpc, conversions}`
+  - `campaigns[]`：`{campaignName, campaignStatus, campaignStatusDisplay, spend, impressions, clicks, ctr, conversions, costPerConversion}`
+  - `adGroups[]`：`{adGroupName, campaignName, qualityScore, spend, clicks, ctr, conversions, costPerConversion}`
+  - `ads[]`：`{adTitle, adGroupName, adType, spend, clicks, ctr, conversions}`
+  - `keywords[]`：`{keyword, matchType, qualityScore, spend, ctr, averageCpc, conversions, costPerConversion}`
+  - `searchTerms[]`：`{searchQuery, keyword, deliveredMatchType, spend, ctr, conversions, costPerConversion}`
+- `narrative`（**Agent 必填，唯一由 Agent 撰写的叙事内容**）：
+  - `executiveSummary[]`：≥1 段执行摘要
+  - `sections.{overview,devices,geographic,audience,campaigns,adGroups,ads,keywords,searchTerms}`：每个维度各 `{analysis[]（≥1 条，含数字依据）, suggestions[]（≥1 条）}`
+  - `recommendations[]`：≥3 条跨维度优化建议汇总
+
+### 快照合并范围（`--snapshot-dir`）
+
+`render` 传 `--snapshot-dir` 时，CLI 自动补全：
+
+1. `meta` / `kpis`（含余额、日均、环比；本期 KPI 优先 campaigns 累加）
+2. `tables.*`（按上表落盘形状映射；Agent 已填字段不覆盖）
+
+Agent 只需撰写 `narrative`；**禁止手写 HTML**。`ctr` / `conversionRate` 落盘已为 0~1 小数。
 
 ---
 
@@ -18,11 +84,11 @@
 
 用户指定某一月份（如「6月份报告」「6月 Bing 月报」）且该月**已结束**时：
 
-| 项 | 规则 |
-| --- | --- |
-| `--start` | 当月 **1 日**（如 `2026-06-01`） |
-| `--end` | 当月**最后一天**（如 6 月 → `2026-06-30`，**禁止**写成 `06-29`） |
-| 报告首行 | `统计区间：YYYY-MM-01 ~ YYYY-MM-<末>` |
+| 项        | 规则                                                             |
+| --------- | ---------------------------------------------------------------- |
+| `--start` | 当月 **1 日**（如 `2026-06-01`）                                 |
+| `--end`   | 当月**最后一天**（如 6 月 → `2026-06-30`，**禁止**写成 `06-29`） |
+| 报告首行  | `统计区间：YYYY-MM-01 ~ YYYY-MM-<末>`                            |
 
 示例（7 月 8 日要 6 月报告）：
 
@@ -103,9 +169,9 @@ CLI 落盘时会：overview 余额为 0 → 调 `GetMediaAccountInfo` → 写回
 
 Bing 网关常不返回 `averageDailyCost`、`activeDays`（或为 0）。CLI 落盘前会：① 缺 `totalCost` 时用 `currentPeriod.spend`；② 缺 `activeDays` 时用 `--start`~`--end` 含首尾日历天数；③ `averageDailyCost = totalCost / activeDays`（保留 2 位小数）。
 
-**数据呈现**：区间消耗、展示、点击、转化、CTR、CPC、CPA、日均消耗、**实时余额**（`balance`）、优化分；**有效** `previousPeriod` 时展示环比。
+**数据呈现**：区间消耗、展示、点击、转化、CTR、CPC、CPA、日均消耗、**实时余额**（`balance`）、优化分；**有效** `previousPeriod` 时展示环比。写入 JSON `kpis`（可由 `--snapshot-dir` 自动合并）。
 
-**分析（必写）**：
+**分析（必写）** → 写入 `narrative.sections.overview.{analysis,suggestions}`：
 
 - **总结**：本期 vs 上期消耗/点击/转化/CTR/CPC/CPA 变化（**仅当 previousPeriod 有数据**）；展示份额（`searchImpressionShare`）及预算/排名丢失份额；余额与日均消耗可支撑天数（用 **`balance` / `remainingAccountBudget`**，非 overview 快照 0）。
 - **建议**：账户级预算或投放节奏（引用具体百分比或金额）；若展示份额丢失高 → 预算或出价方向；1～3 条。
@@ -116,9 +182,9 @@ Bing 网关常不返回 `averageDailyCost`、`activeDays`（或为 0）。CLI
 
 - **CLI**：`bing-analysis --sections device` → `DeviceSectionData`（行在 `devices[]`）
 
-**数据呈现**：各 `deviceType` 的展示、点击、消耗、CTR、CPC、转化、CPA；建议附消耗占比。
+**数据呈现**：各 `deviceType` 的展示、点击、消耗、CTR、CPC、转化、CPA；建议附消耗占比。写入 JSON `tables.devices[]`。
 
-**分析（必写）**：
+**分析（必写）** → 写入 `narrative.sections.devices.{analysis,suggestions}`：
 
 - **总结**：主消耗设备、各设备 CPA/CPC 差异、高消耗低转化设备。
 - **建议**：设备出价调整或预算向高转化设备倾斜（写设备名 + 表中数字），1～3 条。
@@ -129,9 +195,9 @@ Bing 网关常不返回 `averageDailyCost`、`activeDays`（或为 0）。CLI
 
 - **CLI**：`bing-analysis --sections geographic` → `GeographicSectionData`（常见 `countries[]`，**以 outline 为准**）
 
-**数据呈现**：Top 国家/地区（建议 Top 10）消耗、点击、转化、CTR、CPC、CPA。
+**数据呈现**：Top 国家/地区（建议 Top 10）消耗、点击、转化、CTR、CPC、CPA。写入 JSON `tables.geographic[]`。
 
-**分析（必写）**：
+**分析（必写）** → 写入 `narrative.sections.geographic.{analysis,suggestions}`：
 
 - **总结**：地域消耗集中度、高转化 vs 高消耗低转化国家/地区。
 - **建议**：地域加价/降价/排除或单独系列（写 `countryOrRegion` + 数据），1～3 条。
@@ -142,9 +208,9 @@ Bing 网关常不返回 `averageDailyCost`、`activeDays`（或为 0）。CLI
 
 - **CLI**：推荐 `bing-analysis --sections audience-merged`（年龄+性别合并 JSON）；或分别 `--sections age-audience` / `--sections gender-audience`
 
-**数据呈现**：年龄段、性别的展示、点击、消耗、CTR、CPC（按 `data.ageAudience.audience` / `data.genderAudience.audience`）。
+**数据呈现**：年龄段、性别的展示、点击、消耗、CTR、CPC（按 `data.ageAudience.audience` / `data.genderAudience.audience`）。写入 JSON `tables.audienceAge[]` / `tables.audienceGender[]`。
 
-**分析（必写）**：
+**分析（必写）** → 写入 `narrative.sections.audience.{analysis,suggestions}`：
 
 - **总结**：主力年龄段/性别、转化或 CPA 更优的受众段、无效花费受众。
 - **建议**：受众出价\_modifier 或排除（引用 `audience` 字段 + 指标），1～3 条。
@@ -159,13 +225,13 @@ Bing 网关常不返回 `averageDailyCost`、`activeDays`（或为 0）。CLI
 | 广告组 | `bing-analysis --sections ad-groups` | `ad-groups-*.json`           |
 | 广告   | `bing-analysis --sections ads`       | `ads-*.json`                 |
 
-**数据呈现**：各表按消耗降序；系列含 `campaignStatus`；广告组可含质量分相关字段（以 outline 为准）。
+**数据呈现**：各表按消耗降序；系列含 `campaignStatus`；广告组可含质量分相关字段（以 outline 为准）。写入 JSON `tables.campaigns[]` / `tables.adGroups[]` / `tables.ads[]`。
 
 **分析（必写，三个子块各写一段，不可合并为一句带过）**：
 
-1. **系列分析 — 总结**：Top 系列及费用占比、暂停/活跃系列效果差异、合计 CTR/CPC/CPA。**建议**：预算增减、暂停或放量具体 `campaignName`，1～3 条。
-2. **广告组分析 — 总结**：高消耗广告组、质量分或 CPA 异常组。**建议**：出价、暂停或结构优化（写 `adGroupName` + 数据），1～3 条。
-3. **广告分析 — 总结**：Top 消耗创意、CTR/转化表现分化。**建议**：暂停低效广告、复制高效创意方向，1～3 条。
+1. **系列分析 — 总结**：Top 系列及费用占比、暂停/活跃系列效果差异、合计 CTR/CPC/CPA。**建议**：预算增减、暂停或放量具体 `campaignName`，1～3 条。→ 写入 `narrative.sections.campaigns.{analysis,suggestions}`
+2. **广告组分析 — 总结**：高消耗广告组、质量分或 CPA 异常组。**建议**：出价、暂停或结构优化（写 `adGroupName` + 数据），1～3 条。→ 写入 `narrative.sections.adGroups.{analysis,suggestions}`
+3. **广告分析 — 总结**：Top 消耗创意、CTR/转化表现分化。**建议**：暂停低效广告、复制高效创意方向，1～3 条。→ 写入 `narrative.sections.ads.{analysis,suggestions}`
 
 ---
 
@@ -176,18 +242,18 @@ Bing 网关常不返回 `averageDailyCost`、`activeDays`（或为 0）。CLI
 | 关键词   | `bing-analysis --sections keywords`     | 默认 `limit=100`、`orderByCost=true` |
 | 搜索字词 | `bing-analysis --sections search-terms` | 同上                                 |
 
-**数据呈现**：Top 关键词/搜索词表（消耗、CTR、CPC、转化、CPA、质量分/匹配类型等，以 outline 为准）。
+**数据呈现**：Top 关键词/搜索词表（消耗、CTR、CPC、转化、CPA、质量分/匹配类型等，以 outline 为准）。写入 JSON `tables.keywords[]` / `tables.searchTerms[]`。
 
 **分析（必写，两块各写一段）**：
 
-1. **关键词 — 总结**：高转化词、高消耗低转化或零转化词、匹配类型分布。**建议**：暂停/降价/提价/改匹配（写 `keyword` + 数据），1～3 条。
-2. **搜索字词 — 总结**：高意向词、应加为关键词的词、应否定的无关词（对比触发 `keyword`）。**建议**：加词、否词（写 `searchQuery` + 数据），1～3 条。
+1. **关键词 — 总结**：高转化词、高消耗低转化或零转化词、匹配类型分布。**建议**：暂停/降价/提价/改匹配（写 `keyword` + 数据），1～3 条。→ 写入 `narrative.sections.keywords.{analysis,suggestions}`
+2. **搜索字词 — 总结**：高意向词、应加为关键词的词、应否定的无关词（对比触发 `keyword`）。**建议**：加词、否词（写 `searchQuery` + 数据），1～3 条。→ 写入 `narrative.sections.searchTerms.{analysis,suggestions}`
 
 ---
 
 ## 7. 报告收尾（全账户）
 
-在以上各 section 分析之后，可增加 **「优化建议汇总」**（3～5 条），跨 section 归纳优先级，**须与前面各 section 分析一致、不得矛盾**；可呼应对外客户话术（若用户需要）。
+在以上各 section 分析之后，须撰写 **「优化建议汇总」**（3～5 条，写入 JSON `narrative.recommendations[]`），跨 section 归纳优先级，**须与前面各 section 分析一致、不得矛盾**；可呼应对外客户话术（若用户需要）。
 
 ---