siluzan-tso-cli 1.1.52 → 1.1.53-beta.2

package/dist/skill/references/report-templates/google-quarterly-report.md

@@ -0,0 +1,100 @@
+# Google 季度经营报告
+
+> collect 只出事实；Agent 只写 `narrative`；`render` 注入 `google-quarterly-report.html`（大族版式 + ECharts）。
+> **禁止** Read HTML 模板。行业数据不做。专项广告无量则整章隐藏。
+>
+> **触发（命中即 P10，勿改 P4/P9）**：月度报告、月总结与规划、季度报告、Q3 汇总、Q4 规划、季度汇报、投放季报、客户版、大族模板、下月规划；或「效率 + 区域询盘 + 国家明细 + 规划」。用户说月度则 `--start/--end` 用该月（默认上一完整自然月）。
+
+## 询盘入场（硬规则）
+
+CLI **不读** xlsx / csv / 截图。流程固定三步：
+
+1. 用户给询盘载体（xlsx / csv / 截图 / 粘贴表，格式不限）。
+2. **Agent** 抽行、归一后落盘 `./snap-p10/inquiries.json`，再 `--inquiries` 传给 collect。
+3. collect → 只写 `narrative` → `render` 出 HTML。
+
+**禁止**把原始 `.xlsx` / `.csv` 传给 `--inquiries`（会 `JSON.parse` 失败）。没有载体：可 `--inquiry-conversion <转化动作名>`；再没有则询盘位留空并脚注。**禁止编造询盘行。**
+
+落盘 JSON：根为数组或 `{ "items": [...] }`。每行至少有国家 +（月份或日期）：
+
+| 用途 | 接受的键 | 归一 |
+| ---- | -------- | ---- |
+| 国家 | `国家` / `国家(中文)` / `country` / `countryZh` | 英文/缩写先译中文，与 geographic `countryNameZh` 对齐 |
+| 月份 | `月份` / `month` / `ym` | `2026-04` 或 `4月份`（有日期则用日期年） |
+| 日期 | `时间` / `date` / `time` | `YYYY-MM-DD`；Excel 序列号由 Agent 转好 |
+| 产品 | `产品` / `product` | 可选 |
+| 来源 | `客户来源` / `来源` / `source` | 可选 |
+
+样例（字段名任选上表别名）：
+
+```json
+[
+  { "月份": "4月份", "国家(中文)": "印度", "时间": "2026-04-12", "产品": "协作机器人", "客户来源": "WhatsApp" }
+]
+```
+
+e2e 对照：`src/commands/google-quarterly/test-fixtures/inquiries-q2-2026.xlsx`（给人看的样表）+ 同目录 `.json`（collect 真入口）。
+
+## CLI
+
+```bash
+siluzan-tso google-quarterly collect \
+  -a <mediaCustomerId> --start 2023-07-01 --end 2023-09-30 \
+  --json-out ./snap-p10 \
+  --account-name "客户名" \
+  --inquiries ./inquiries.json          # 可选；必须是上节 JSON，禁止传 xlsx
+  # --inquiry-conversion "表单提交"     # 无询盘载体时用转化动作名称兜底
+
+# Agent 撰写 ./snap-p10/google-quarterly.json（只含 narrative，勿改 kpis）
+
+siluzan-tso google-quarterly render \
+  --data ./snap-p10/google-quarterly.json \
+  --collect ./snap-p10/google-quarterly-collect.json \
+  --out ./snap-p10/google-quarterly-report.html
+```
+
+省略 `--start/--end` 时 collect 用上一完整自然季（上海日历）。
+
+可选：`--keyword-seeds "a,b"` 走 Keyword Planner（标注数据源，禁止写成行业指数）。**不做**频道订阅总数、订阅来源饼、视频类型（要 YouTube Analytics / 人工分类）。YouTube 广告能拿到的曝光 / TrueView / 完播 / CPV / 频道 ID /（若已关联）广告带来订阅，collect 会写入 `specialAds` + `videosSummary`，render 直接展示。
+
+Agent JSON Schema：`assets/google-quarterly-report.schema.json`。
+
+## Spike（网关）
+
+| 能力 | 官方 | Sammamish | CLI |
+| ---- | ---- | --------- | --- |
+| 消耗最高国一级行政区 | `geographic_view` + `geo_target_state` / `province` / `region` | `GET …/reports/geo/subdivisions`（可带 `countryCriterionId`） | collect 自动选本期花费最高国家；未发布或该国无分段则国家级回退 |
+| YouTube 广告层 | `video` 资源：title / channel_id / TrueView / 四分位完播 / CPV | 已有 `GetVideoReport` | 专项章 KPI + 视频表；无量则隐藏整章 |
+| 广告带来订阅 | Ads 转化动作名含 subscribe/订阅 | 已有 `conversion-actions` | 有则展示；**不是**频道粉数 |
+
+## 事实字段（collect，禁止改）
+
+| 字段 | 来源 |
+| ---- | ---- |
+| `kpis` / `monthly` | 系列加总；月度来自各月 `campaigns`，不是 daily-metrics |
+| `inquiries` | Agent 转好的 JSON（`--inquiries`）优先；否则 `--inquiry-conversion`；再否则空，页脚注明口径 |
+| `regions` / `countries` | 询盘按国家归并（印度/印尼单独成桶）+ 花费来自 geographic |
+| `usStates` / `meta.drillCountry` | 下钻对象=本期花费最高国家；Sammamish `GET …/reports/geo/subdivisions`（`geo_target_state` / `province` / `region`）；无分段则回退该国国家行，**不写死美国** |
+| `specialAds` / `videosSummary` | YouTube 视频名 + Ads 视频指标 → PMax 系列名 → 其他非搜索 → `none`（HTML 隐藏整章）。不做订阅总数 / 来源饼 / 视频类型 |
+| `planDefaults` | 花费 ×1.3～×1.5；**不**自动给 CPA/询盘目标 |
+
+频道订阅总数、订阅来源、视频类型本报告不拉。
+
+## Agent 只写 `narrative`
+
+```json
+{
+  "narrative": {
+    "executiveSummary": ["本期花费…", "询盘…"],
+    "sections": {
+      "efficiency": { "analysis": ["…"] },
+      "adType": { "analysis": ["…"] },
+      "region": { "analysis": ["…"] },
+      "summary": { "analysis": ["…"] }
+    },
+    "plan": { "analysis": ["下期花费目标取 collect.planDefaults.spendLow～spendHigh", "动作…"] }
+  }
+}
+```
+
+缺 `executiveSummary` / `sections.*.analysis` / `plan` 时 render 失败。

package/dist/skill/report-templates/README.md

@@ -22,6 +22,7 @@
 | 文件                                         | 适用场景                                                                                                                                                          |
 | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `google-period-report.md`                    | **Google 周期分析报告（默认）**：终稿=HTML，四步流程 → `google-analysis render` 出 HTML                                                                           |
+| `google-quarterly-report.md` / `.html`       | **Google 季度经营报告（P10）**：`google-quarterly collect`+`render`；花费默认 +30%～+50%；无行业章                                                                |
 | `google-period-report-excel.md`              | **仅用户要 Excel 时**（P4 定制 Sheet）：先 `*.outline.txt` 后脚本写 xlsx；账户须 `-k` 核验，无 CLI excel 子命令                                                   |
 | `stats-daily-excel.md`                       | **P4-DAILY**：账户级按日 Excel（`stats --by-day`）                                                                                                                |
 | `google-account-diagnosis-report.md`         | Google 账户深度诊断（健康度/转化/结构等）                                                                                                                         |