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

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

@@ -3,7 +3,57 @@
 > 统计区间：`{startDate}` ~ `{endDate}`  
 > 账户：`{mediaCustomerId}`
 
-> **用户明确要求 Excel / xlsx**（且非 OKKI / 询盘话术）时：在拉数步骤不变的前提下，**另 Read 全文** `report-templates/google-period-report-excel.md`，并**先读齐**各维度 `*.outline.txt` 再写脚本；禁止加载宿主第三方 xlsx Skill。
+> **默认交付物**：一份可打开的、带 ECharts 图表的 **HTML 文件**（`google-period-report.html`）。  
+> 用户**未指定格式**时一律走下方 **标准四步流程**；**禁止** Agent 手写/拼接 HTML（语法错误会导致报告无法显示）。  
+> **用户明确要求 Excel / xlsx**（且非 OKKI / 询盘话术）时：在拉数步骤不变的前提下，**另 Read 全文** `report-templates/google-period-report-excel.md`，并**先读齐**各维度 `*.outline.txt` 再写脚本；禁止加载宿主第三方 xlsx Skill；**不要**调用 `google-analysis render`。
+
+---
+
+## 标准四步流程（默认 · 交付 HTML）
+
+| 步骤             | 执行者       | 动作                                                                                                                                                                       |
+| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. 拉数**      | Agent 调 CLI | `google-analysis -a <id> --start <s> --end <e> --json-out ./snap-google --sections <见下方默认维度对应 CLI>`                                                               |
+| **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），完成筛选、聚合、排序与洞察                                                                              |
+| **3. 写 JSON**   | Agent        | 按 `assets/google-period-report.schema.json` 撰写 `google-period-report.json`：仅 `meta` + `narrative`（8 维度叙事）为必填，`kpis`/`charts`/`tables` 可省略由 CLI 自动合并 |
+| **4. 渲染 HTML** | CLI          | `google-analysis render` — **校验 narrative 8 维度必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML                                                           |
+
+```bash
+# 步骤 1
+siluzan-tso google-analysis -a <id> --start <s> --end <e> --json-out ./snap-google \
+  --sections overview,daily-metrics,dimension-summary,campaigns,devices,geographic,keywords
+
+# 步骤 4（步骤 2～3 完成后）
+siluzan-tso google-analysis render \
+  --data ./google-period-report.json \
+  --snapshot-dir ./snap-google \
+  --out ./google-period-report.html
+```
+
+`google-period-report.json` 顶层结构：
+
+- `meta`：`accountId`（必填）/ `accountName` / `currency` / `startDate` / `endDate`；可省略由 `--snapshot-dir` 从 `overview` + manifest 自动合并。
+- `kpis`：账户级 KPI（消耗/展示/点击/转化/CTR/CPC/CPA，含可选 `previousPeriod` 环比）；可省略。本期 KPI 由 CLI 优先对 `campaigns` 全系列累加并重算比率（规避 overview/stats 相对 Google API 延迟）；无 campaigns 快照时回退 `overview.currentPeriod`。环比仍来自 `overview.previousPeriod`。
+- `charts.dailyTrend`：每日趋势（`dates`/`cost`/`conversions`/`cpa`）；可省略由 `daily-metrics` 自动合并。
+- `tables.{dimensionSummary,campaigns,devices,geographic,keywords}`：对应 §3～§7 表格数据；可省略由同名 `google-analysis` section 自动合并。
+- `narrative`（**Agent 必填，唯一由 Agent 撰写的内容**）：
+  - `executiveSummary[]`：≥1 段执行摘要
+  - `sections.{overview,dailyTrend,dimensionSummary,campaigns,devices,geographic,keywords}`：每个维度各 `{analysis[]（≥2 条）, suggestions[]（≥1 条）}`，对应报告 §1～§7
+  - `recommendations[]`：≥3 条跨维度优化建议，对应报告 §8
+
+完整字段定义见 `assets/google-period-report.schema.json`。
+
+**Excel 分支**（用户明确要 xlsx 时）：
+
+1. 步骤 1～2 与 HTML 流程相同（拉数 → 分析）。
+2. 改为 Agent 执行 node/python 脚本按 `google-period-report-excel.md` 写出 `.xlsx`（先读齐 `*.outline.txt`）。
+3. **不要**调用 `google-analysis render`（除非用户同时要 HTML + Excel）。
+4. **禁止**假设存在 `siluzan-tso … excel` 子命令。
+
+模板源码：`report-templates/google-period-report.html`（结构与样式，ECharts 渲染逻辑已内联）。
+
+`render` 会向输出目录写入 HTML，并注入 `window.__GOOGLE_PERIOD_REPORT__`。  
+传 `--snapshot-dir` 时 CLI 自动从快照合并 KPI、每日趋势图表、周期汇总/系列/设备/地域/关键词表格（Agent JSON 中已有字段不覆盖）。本期 KPI 优先 `campaigns` 累加，勿用延迟的 `stats`/overview 手工填账户级消耗。
 
 ---
 
@@ -65,9 +115,9 @@ siluzan-tso google-analysis -a <id> --start <s> --end <e> --json-out ./snap-goog
 
 `campaigns-*.json` → `items[]` 每行含 CLI 注入的 **`campaignStatusDisplay`**（`投放中` / `已暂停` / `已移除`）。
 
-| 正确 | 错误 |
-| ---- | ---- |
-| 直接展示 `row.campaignStatusDisplay` | 读 `campaignStatus` 后自行 `MAP[s] \|\| '已移除'`（`Enabled` 未命中键时会全变「已移除」） |
-| 需要英文枚举时读 `campaignStatus` 或 `campaignStatusV2`，展示前 `.upper()` 再映射 | 用 `stats` / `list-accounts` 的账户 `status` 充当系列状态 |
+| 正确                                                                              | 错误                                                                                      |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| 直接展示 `row.campaignStatusDisplay`                                              | 读 `campaignStatus` 后自行 `MAP[s] \|\| '已移除'`（`Enabled` 未命中键时会全变「已移除」） |
+| 需要英文枚举时读 `campaignStatus` 或 `campaignStatusV2`，展示前 `.upper()` 再映射 | 用 `stats` / `list-accounts` 的账户 `status` 充当系列状态                                 |
 
 原始枚举为 PascalCase（`Enabled`），与 `ad campaigns` 的 `statusDisplay`（有效/未投放/已结束使用）口径不同；周期报告「状态」列统一用 **`campaignStatusDisplay`**。