siluzan-tso-cli 1.1.29-beta.2 → 1.1.29-beta.21

package/dist/skill/references/report-templates/google-inquiry-analysis.md

@@ -0,0 +1,543 @@
+# Google 账户询盘分析（运营固定触发模板）
+
+> **触发话术**（等价即可，命中即走本模板）
+>
+> - `Goog账户询盘分析` / `Google 账户询盘分析`
+> - `分析XXX Google账号的询盘效果`
+> - `我给你询盘信息分析Google账号XXX效果`（附询盘资料 + 账户 ID）
+> - 含「询盘 + 账户 + Google」三要素的近义表述
+
+命中以上触发词时：**不要**按 `google-period-report.md` 的「8 维 + 追问」流程；按本文**固定字段 + 固定话术 + 固定时间窗**交付（数据全部来自 CLI 落盘 JSON，见 `references/analytics/account-analytics.md`）。
+
+---
+
+## 用户两种入场流程
+
+### 流程 A：用户直接带询盘资料
+
+`我给你询盘信息分析Google账号<id>效果` + 附件（**任意载体**：xlsx / csv / pdf / 截图 / 纯文本表格 / 飞书表格粘贴均可）。
+
+由**宿主 Agent**（Claude / Cursor / WorkBuddy 等）负责解析附件 → 抽取询盘行 → 落盘为 `./snap-inquiry/inquiries.json`。本 Skill 不约束载体格式，只规定字段清单（见下）。
+
+### 流程 B：用户没给资料
+
+用户说 `分析<id>Google账号的询盘效果`（仅给账户）。**Agent 须做**：
+
+1. 反问账户与分析月份（见下方「须先确认」）。
+2. 同时贴出**询盘字段清单 + 1 行示例**，让用户用任意方式补齐再回传：
+
+   ```
+   请把近 3 个月（{S} ~ {E}）的询盘记录回贴或上传（Excel / CSV / 截图 / 文本表格均可），字段如下：
+   月份 | 序号(可空) | 国家(中文) | 时间(YYYY-MM-DD 或 Excel 序列) | 产品 | 客户来源 | IP(可空)
+   示例：4月份 | 1 | 印度 | 2026-04-12 | 滴灌带 | WhatsApp(www.extruder.cn)
+   ```
+
+3. 拿到资料后由宿主 Agent 解析、落盘 `inquiries.json`，再进入「拉数与写 Excel」节。
+
+---
+
+## 须先确认
+
+1. **账户**：`mediaCustomerId` 来自 `list-accounts -m Google -k <id>`，**禁止猜 ID**。
+2. **分析月份**：默认**上一个完整自然月**（例：今天 5/13 → 默认 4 月）。用户未明确时**反问**（A) 上月 B) 本月 1 号到昨天 C) 自定义 YYYY-MM）。
+3. **时间窗口（硬约束）**：**严格 3 个月** = 分析月份 + 向前 2 个完整自然月。例：分析月 = 2026-04 → `--start 2026-02-01 --end 2026-04-30`。**所有月度表只展示 3 行**（不延伸到 7 个月）。
+4. **询盘字段最小集**：`月份 / 国家(中文) / 时间 / 产品 / 客户来源`；可选 `序号 / IP`。
+5. **日期规范化**：`2026.4.1` / `2026/4/1` 等先规范成 `YYYY-MM-DD` 再传 CLI。
+
+---
+
+## 架构约定 · Excel 由谁生成
+
+- **`siluzan-tso` 不提供**「一键生成询盘分析 Excel」CLI 子命令，**也不要**新增。
+- 需交付 Excel 时：由 **Agent**（宿主或 WorkBuddy 编排）在 CLI `--json-out` 落盘后，自行编写 **Node.js / Python** 脚本（`exceljs` / `xlsx` / `openpyxl`）读 JSON → 写 `.xlsx`。
+- **数值一律来自落盘 JSON 或 `inquiries.json`，禁止在脚本里写死业务数字。**
+
+---
+
+## Subagent 编排（可选）
+
+主 Agent 先 Read `references/core/subagent-orchestration.md` § P7：
+
+- **主 snap + 按月拉数**：可并行 3× Task（`snippets/handoff-p7-inquiry.md` 变体 m1/m2/m3），或主会话顺序执行。
+- **8 Sheet xlsx**：主 Agent 或单 Task 收尾；子会话禁止扩展 7 个月窗口、禁止编造询盘数据。
+- handoff 与 `returnSchema` 见 orchestration 文档。
+
+---
+
+## 拉数（同一目录落盘）
+
+`./snap-inquiry` 为示例目录。设 `S` = 起始月 1 号、`E` = 分析月最后一天。
+
+```bash
+mkdir -p ./snap-inquiry
+
+# 1) 账户清单（核 mediaCustomerId 与 advertiserName / currencyCode）
+siluzan-tso list-accounts -m Google -k <mediaCustomerId> --json-out ./snap-inquiry
+
+# 2) 区间维度（Sheet 5/7/8；系列为整段 S~E 汇总）
+siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-out ./snap-inquiry \
+  --sections campaigns,keywords,search-terms,campaign-geo
+
+# 3) 按月循环（Sheet 4 上区 + Sheet 4 下区 + Sheet 6）
+for month in <S月, S+1月, E月>:
+  mkdir -p ./snap-inquiry/<YYYY-MM>
+  siluzan-tso google-analysis -a <mediaCustomerId> \
+    --start <月1号> --end <月末> --json-out ./snap-inquiry/<YYYY-MM> \
+    --sections campaigns,geographic
+```
+
+**说明**：
+
+- **禁止**用 `daily-metrics` 填 Sheet 4 上区：该维度走 TSO 主平台 `account-daily-reports`，与 Google 前台 / Web 分析（`CampaignSectionData`）**不同数据源**，产品已确认存在不可接受偏差。
+- **Sheet 4 上区（账户月汇总）**：读 `./<YYYY-MM>/campaigns-*.json`，对 `items[]`（`schemaVersion 3` 行统一在 `items`）**全系列求和**得到当月账户级点击/展示/费用/转化，再算 CTR/CPC/CPA/CVR（公式见下文 Sheet 4）；与 Google「广告系列」页同区间加总口径一致。
+- `./snap-inquiry/campaigns-<accountId>_<S>-<E>.json`（步骤 2，整段 S~E）：仅用于 **Sheet 5** 系列明细；**不得**用它按月拆行填 Sheet 4。
+- `geographic`：账户级国家聚合；Sheet 6 与 Sheet 4 **下区**（重点国切片）按月目录读取。
+- `keywords` / `search-terms`：Sheet 7 / 8；默认拉取**全部有消耗**行（`keywords` 网关 `costGreater=0`，`limit=0` 不封顶）；需 TOP N 时加 `--limit <n>`。
+- `campaign-geo`：含 `campaignName`，用于 Sheet 6「暂停的系列」列辅助派生（若运营不需要可留空）；也用于 Sheet 3 国家级消耗 join。
+- `geographic`：账户级国家聚合；Sheet 6 月度循环主源；Sheet 4 下半区「重点国家 vs 非重点国」按月切片（重点国默认取分析月询盘 Top1 国家，可由运营覆盖，详见下文 Sheet 4 节）。
+- **地理字段自动补齐**（由 `translate-fields.ts` 在 `campaign-geo` / `geographic` 行上自动补，未命中字典则不补，详见 `references/analytics/account-analytics.md`「中文化字段」）：
+  - `countryOrRegionZh`：与 `countryOrRegion` **同粒度**的中文翻译（`Mumbai → 孟买` / `India → 印度` / `Davao Region → 达沃地区`）
+  - `countryCode`：归并到的 ISO alpha-2 国家代码（`Mumbai → "IN"` / `Davao Region → "PH"` / `India → "IN"`），数据源 Google Ads 官方 geotargets CSV（约 9.5 万条目）
+  - `countryNameZh`：归并后的**国家级中文名**（`Mumbai → "印度"` / `Davao Region → "菲律宾"`）。**Sheet 3 国家透视、Sheet 6 国家维度均应按 `countryNameZh` 聚合**，自动把城市/地区行归并到所属国家，不再出现"未知大洲"。
+
+**写脚本前先读 `<section>-<id>.outline.txt`**（几百字节 TS 类型字面量），别直接 `Read` 几 MB 的 JSON。
+
+### 落盘防覆盖（必读）
+
+CLI 业务 JSON 默认名为 `<section>-<accountId>.json`。**带 `--start`/`--end` 的 range 维度**会自动追加区间后缀，例如：
+
+`campaigns-3206866200_20260401-20260430.json`
+
+因此：
+
+| 做法                                       | 结果                                                                               |
+| ------------------------------------------ | ---------------------------------------------------------------------------------- |
+| 三个月都 `--json-out ./snap-inquiry`       | **旧版会覆盖**；新版 CLI 同目录可共存 3 个 `campaigns-*_YYYYMM01-YYYYMM31.json`    |
+| 每月 `--json-out ./snap-inquiry/<YYYY-MM>` | 每月目录内仍是 `campaigns-<id>_<月首>-<月末>.json`，**推荐**（脚本按目录读最直观） |
+| 步骤 2 整段 + 步骤 3 某月共用一个目录      | 文件名不同（整段 S~E vs 单月），**不会**互相覆盖                                   |
+
+**脚本读数**（二选一，禁止写死无日期后缀的旧文件名）：
+
+```text
+# 推荐：按月子目录
+./snap-inquiry/<YYYY-MM>/campaigns-<accountId>_<月1号>-<月末>.json
+
+# 或：同目录 glob（manifest.artifacts 会列出每个区间文件）
+./snap-inquiry/campaigns-<accountId>_*.json
+```
+
+Sheet 5 整段系列明细读：`./snap-inquiry/campaigns-<accountId>_<S>-<E>.json`（S、E 为 3 个月起止，无连字符）。
+
+---
+
+## 询盘字段规范（宿主 Agent 解析输出）
+
+宿主 Agent 解析任意载体后，**统一落盘** `./snap-inquiry/inquiries.json`：
+
+```json
+[
+  {
+    "month": "4月份",
+    "seq": 1,
+    "country": "印度",
+    "time": "2026-04-12",
+    "product": "滴灌带",
+    "source": "WhatsApp(www.extruder.cn)",
+    "ip": null
+  }
+]
+```
+
+- `month`：保留运营原文（`1月份` / `4月份` …）。
+- `country`：**中文名**，与 `countryOrRegionZh` 字典对齐（脚本会自动 lookup 大洲）。Agent 解析时遇到英文/缩写应先翻译为中文，未知国家保留原文并在脚本里标 `未知大洲`。
+- `time`：`YYYY-MM-DD`；Excel 日期序列号也接受，由解析方转换。
+- `product`：自由文本（`滴灌带` / `打包带` / `片材` / `滴头` / `模具` / `贴条` / `涂布水带` …），脚本以此作 Sheet 3 产品维度透视分桶 key。
+- `source`：自由文本（`WhatsApp` / `tawk.to` / `info邮箱` / `网站留言` / `微信(xxxx)` / `阿里巴巴` / `made-in-china` / `Youtube` / `TikTok` …），脚本以此作 Sheet 3 客户来源透视分桶 key。
+- `ip`：可空。
+
+---
+
+## 国家 → 大洲映射
+
+- **数据源**：`references/analytics/geo-continents.json`
+- **默认 7 桶**：`亚洲` / `中东` / `欧洲` / `北美` / `南美` / `非洲` / `大洋洲`。
+- **运营常用 5 桶合并**（与样表 Sheet 3 一致）：`<重点国>` / `中东` / `非洲` / `欧美` / `亚洲(除重点国)`。**由脚本在写表前做二次合并**，伪代码：
+
+  ```javascript
+  // focusCountries 由运营每次会议前确认（见下方「重点国家配置」节）；
+  // 单国时桶名 = 国家名（如 "印度"）；多国时桶名 = 列表拼接（如 "印度+印度尼西亚"）。
+  function bucketForSheet3(country, continents, focusCountries) {
+    if (focusCountries.includes(country)) return focusCountries.join("+");
+    const c = continents[country];
+    if (c === "欧洲" || c === "北美" || c === "南美") return "欧美";
+    return c || "未知";
+  }
+  ```
+
+- **未命中**：标 `未知大洲`（不阻塞、不报错）。脚本在末尾打印未命中国家清单，让运营回补字典。
+- **若同一国家在询盘里出现中英文两种写法**：脚本归一化（先按 `geo-en2zh.json` 翻译英文 → 中文，再查 continents）。
+
+---
+
+## xlsx 版式规范
+
+工作簿 8 个 Sheet，**顺序与名称须完全一致**（按运营样表《2026 年 4 月月报-TO 询盘分析模板》）。表头、合并单元格、数值格式严格执行；列宽 / 排序为可选，但**不得**因此改数。
+
+### 数值格式（强约束）
+
+- **金额、CPL / CPA / CPC / 平均费用**：保留 **2 位小数**，写明货币代码（如 `¥123.45 CNY`）。
+- **点击率 / 转化率 / 互动率**（`ctr` / `conversionRate` / `interactionRate`）：CLI 已归一为 **0~1 小数**（schemaVersion ≥ 2），写入 Excel 时**直接写 0~1**（与运营样表对齐，Excel 单元格用百分比格式自动渲染）。话术 `x%` 用 `(v * 100).toFixed(2) + "%"`。
+- **空值**：`interactions === 0` 时「平均费用」「互动率」填 `—`，**禁止**除零。
+
+### 分析输出区位置（**全局硬约束**）
+
+每个 Sheet 的分析输出区（`数据质量提示` / `Agent 数据洞察` / `优化建议` / Sheet 1 议题区与会后补写区）一律遵守：
+
+1. **位置**：放在该 Sheet **全部数据区最末行**下方留空 1 行接续，**从 A 列起**；禁止落在数据行之间。
+2. **最末行计算**：脚本需先算 `lastDataRow = MAX(各数据区的最末行号)`，再从 `lastDataRow + 2` 开始写分析输出区。
+   - Sheet 3 含**左右两区**（左明细 A-F / 右 4 个透视 H-K）：`lastDataRow = MAX(左区最末行, 右区第 4 个透视最末行)`。
+   - Sheet 4 含**上下两区**（汇总 + 重点国切片）：`lastDataRow = 下区最末行`。
+   - Sheet 5 含**上区主表 + 下区优化建议**：优化建议本身就是分析输出区，位置规则与其它 Sheet 一致。
+   - 其余 Sheet（2 / 6 / 7 / 8）单数据区：`lastDataRow = 主表最末行`。
+3. **跨列宽度**：分析输出区表格横跨 A 列至该 Sheet 主表的**最右占用列**（如 Sheet 3 横跨 A-K、Sheet 4 横跨 A-L），便于运营在最末位置一眼读完。
+4. **禁止**为对齐美观而**人工指定固定行号**（如"R30 起写洞察"）：行号必须由脚本动态算，否则数据条数变化时会插入数据中间。
+
+### Sheet 顺序
+
+| 顺序 | Sheet 名                      | 主源                                                                                            |
+| ---: | ----------------------------- | ----------------------------------------------------------------------------------------------- |
+|    1 | `会议讨论议题`                | Agent 从 Sheet 2~8 提炼议题（不拉数）；**含「会后补写区」由运营会后手填决策**                   |
+|    2 | `询盘明细---<S月>-<E月>月份`  | `inquiries.json`                                                                                |
+|    3 | `询盘分析-最近3个月`          | `inquiries.json` + `campaign-geo-*.json`                                                        |
+|    4 | `账号分析-最近3个月`          | `./<YYYY-MM>/campaigns-*.json`（上区，系列加总）+ `./<YYYY-MM>/geographic-*.json`（下区）× 3 月 |
+|    5 | `广告系列消费明细`            | `./snap-inquiry/campaigns-<accountId>_<S>-<E>.json`（整段 3 月）                                |
+|    6 | `国家消费明细<S月>-<E月>月份` | `./<YYYY-MM>/geographic-*.json` × 3 + `inquiries.json` 左 join                                  |
+|    7 | `关键词`                      | `keywords-*.json`                                                                               |
+|    8 | `搜索字词`                    | `search-terms-*.json`                                                                           |
+
+---
+
+### Sheet 1 `会议讨论议题`
+
+> **语义**：Agent 产出的是**会议前数据分析**，**不可能**知道会上讨论了什么 / 决策了什么。本 Sheet 由 Agent 把其他 7 个 Sheet 的**数据异常与机会**提炼成**待讨论议题**，会后由运营手工把决策结论补到「会后补写区」。
+>
+> **口吻硬约束**：议题区**只用**「建议讨论…」「是否…」「Top X 是…，是否…」等开放语气，**禁止**出现「已暂停」「已新增」「决定切换」这类决策口吻；禁止编造未在数据中出现的国家/产品/渠道。
+
+| 行      | 内容                                                                                                                                                                                             |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| R1      | 一句话数据要点（Agent 基于本期 Sheet 2~8 的核心发现概括，例：`本期 3 个月共 {N} 条询盘，{E月} CPL ¥{x}（环比 {±%}），消耗 Top3 国家：{A/B/C}，询盘 Top3 国家：{X/Y/Z}。`）                       |
+| R2      | `议题分类` \| `数据要点（引用具体数字）` \| `候选讨论选项` \| `数据来源`                                                                                                                         |
+| R3+     | 议题列表（**Agent 基于其他 7 个 Sheet 数据撰写，每条都要带具体数字**），4 大类，每类视数据出 1~3 条：                                                                                            |
+|         | ① **国家投放议题**：列出 (a) 消耗 Top + 询盘 Top (b) 高消耗 0 询盘国家 (c) 有询盘但消耗 ≈ 0 的国家；候选选项写「建议讨论：暂停 / 持平 / 加大」三选；数据来源标 `Sheet 3 / Sheet 6`               |
+|         | ② **产品策略议题**：基于 Sheet 3 产品透视 + Sheet 5 系列；指出 CPL 显著高/低的产品系列；候选选项写「建议讨论：调匹配类型 / 切 Pmax / 暂停」；数据来源标 `Sheet 3 / Sheet 5`                      |
+|         | ③ **渠道与数据采集议题**：基于 Sheet 3 客户来源透视，列出占比 Top1/Top2 渠道；若多渠道字面无法区分（如 `AI Search` / `Info邮箱`），议题写「建议讨论：是否加追踪参数」；数据来源标 `Sheet 3`      |
+|         | ④ **预算与节奏议题**：基于 Sheet 4 上区月趋势（CPL / CVR / 消耗环比）+ Sheet 5 系列消耗占比，列出预算保持/上调/下调 3 个候选方向，每个方向给出对应的「触发数据」；数据来源标 `Sheet 4 / Sheet 5` |
+| 空 1 行 | —                                                                                                                                                                                                |
+| 标题    | `会后补写区  ·  由运营会议结束后手填`                                                                                                                                                            |
+| 表头    | `#` \| `决策内容` \| `负责人` \| `截止日期` \| `所属议题(R3+ 行号)`                                                                                                                              |
+| R…      | **留 5~8 空行，Agent 不填**；运营开完会按议题手工补写                                                                                                                                            |
+
+**禁造数硬规范**：
+
+- 议题区每条结论必须能在其他 Sheet 里找到具体数据来源行（标注 Sheet 号），否则不写。
+- **禁止**写「玻利维亚消耗高已暂停」这类肯定句；只能写「玻利维亚消耗 ¥XXX、0 询盘，建议讨论是否暂停」。
+- 「会后补写区」**保持空白**，等运营手填；Agent **不**预填决策。
+
+---
+
+### Sheet 2 `询盘明细---<S月>-<E月>月份`
+
+| 行        | 内容                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------- |
+| R1（A→G） | `月份` \| `序号` \| `国家` \| `时间` \| `产品` \| `客户来源` \| `IP`                        |
+| R2…       | 来自 `inquiries.json` 逐行；`seq` 缺失时用 1..N 递增；`time` 写 `YYYY-MM-DD`；`ip` 缺失留空 |
+
+按 `month` + `seq` 升序。**不**对询盘做去重 / 校验。
+
+**`数据质量提示`**（**位置**：主表最末数据行下方空 1 行接续，**A 列起**；Agent 基于本表数据自动生成，**禁止**编造；纯观察、不带建议口吻）：
+
+| #   | 观察                               | 数据依据                                                                                    |
+| --- | ---------------------------------- | ------------------------------------------------------------------------------------------- |
+| 1   | 询盘总量与月分布                   | 3 个月共 `{N}` 条；分月：S月 `{n1}` / 中月 `{n2}` / E月 `{n3}`                              |
+| 2   | 字段缺失率（IP / 产品 / 客户来源） | `IP` 缺失 `{x}%`、`产品` 缺失 `{y}%`、`客户来源` 缺失 `{z}%`（任一字段缺失率 > 30% 时高亮） |
+| 3   | 重复 IP（同 IP 出现 ≥ 2 条询盘）   | `{m}` 条，涉及 `{k}` 个 IP（列出 Top3）                                                     |
+| 4   | 国家集中度                         | Top1 国家 `{country}` 占 `{p1}%`、Top3 合计 `{p3}%`（> 60% 时高亮"高度集中"）               |
+| 5   | 询盘时间分布异常                   | 若存在单日 ≥ 5 条询盘的"尖峰日"，列日期与条数；否则填 `—`                                   |
+
+**口径硬约束**：所有 `{...}` 占位符**必须**替换为本期真实数字；某项若数据不足则填 `—`，**禁止**写"约""大概"等模糊词。
+
+---
+
+### Sheet 3 `询盘分析-最近3个月`
+
+左右两区。**左区**：明细子集（仅本期 3 个月的询盘 + IP 列）；**右区**：4 个透视表。
+
+**左区**（A→F）：与 Sheet 2 同表头，但仅 `time` 落在 `[S, E]` 区间内的行。
+
+**右区**（H 起）4 个透视：
+
+1. **国家 × 询盘 & 消耗**（H→K）  
+   表头：`国家(分析月份询盘国家)` \| `询盘个数` \| `所属大洲` \| `消耗`  
+   `询盘个数` = `inquiries.json` 按国家 count；  
+   `所属大洲` = 按上文「运营常用 5 桶合并」规则；  
+   `消耗` = `campaign-geo-*.json` 按 **`countryNameZh`** 聚合的 `spend`（同一国家的所有 city / region 行也归并；未命中归并字典时回落 `countryOrRegionZh`）；  
+   末行 `总计`。
+
+2. **客户来源 × 询盘数**（H→I，国家透视下方留空 1 行后接续）  
+   表头：`客户来源` \| `询盘个数`；按 `source` 字段 count；末行 `总计`。
+
+3. **产品 × 询盘 & 消耗 & CPL**（H→K，再留空 1 行后接续）  
+   表头：`产品` \| `询盘个数` \| `消耗` \| `CPL`；  
+   `消耗`：产品维度的消耗在 `campaigns-*.json` 中需运营自配「产品 → 系列前缀映射」（见下方「可选：产品 → 系列前缀映射」节）。如未配置，**留空** + 脚注：`[ 数据不可用：未配置产品→系列映射 ]`，**禁止**编造分摊；  
+   `CPL` = `消耗 / 询盘个数`，询盘个数为 0 时填 `—`。
+
+**`Agent 数据洞察`**（**位置**：**左区明细最末行**与**右区 4 个透视最末行**两者中**行号更大者**下方留空 1 行接续，**A 列起**（横跨 A-K，绝不允许出现在两区数据行之间）；Agent 基于本 Sheet 数据自动生成，**禁止**编造；每条**必带**具体数字）：
+
+> **写表脚本必做**：先算 `lastRow = max(左区最末数据行号, 右区最末透视行号)`，再从 `lastRow + 2` 开始写洞察标题与表格。**禁止**直接接在右区透视下方（会落在左区明细中间）。
+
+| #   | 洞察类别                                                       | 内容（每条引用本 Sheet 具体数字）                                                            |
+| --- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| 1   | **高消耗 0 询盘国家**（透视 1 交叉）                           | 列出消耗 > `{阈值}` 但询盘 = 0 的国家清单（按消耗降序，最多 5 个）；阈值取本期国家消耗中位数 |
+| 2   | **0 消耗有询盘国家**（透视 1 交叉，可能是自然流量/远端品牌词） | 列出消耗 ≈ 0（< `¥10`）但询盘 ≥ 1 的国家（按询盘降序，最多 5 个）                            |
+| 3   | **客户来源集中度**（透视 2）                                   | Top1 渠道占 `{p1}%`、Top3 合计 `{p3}%`；> 70% 高亮"渠道高度集中，风险敞口大"                 |
+| 4   | **长尾渠道**（透视 2）                                         | 占比 < 5% 的渠道数量与合计占比；用于会议讨论"是否归并/精简"                                  |
+| 5   | **产品 CPL 偏差**（透视 3，仅当产品→系列映射已配置）           | 列出 CPL > 整体均值 × 1.5 的产品（拖累），CPL < 整体均值 × 0.5 的产品（明星）                |
+| 6   | **大洲映射缺漏**                                               | 透视 1 中"所属大洲 = 未知大洲"的国家清单（提示运营回流 `analytics/geo-continents.json`）     |
+
+**条数**：上表 6 条为**完整模板**；若某条数据为空（如未配置产品映射、无大洲缺漏），可省略该行，但其余必出。
+
+---
+
+### Sheet 4 `账号分析-最近3个月`
+
+上下两区。
+
+#### 上区口径：系列维度加总（对齐 Google）
+
+| 项       | 约定                                                                                                                                |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| 数据源   | `./snap-inquiry/<YYYY-MM>/campaigns-<accountId>_<月1号>-<月末>.json`（每月单独拉 `campaigns`；见「落盘防覆盖」）                    |
+| 聚合范围 | 该月内 **全部** `items[]` 行（`schemaVersion 3` 行统一在 `items`；含已暂停但在区间内有消耗的系列；**禁止**只取 Top N 或手工筛系列） |
+| 数据口径 | `google-analysis campaigns` 与账户月表一致；账户月表 = 各系列在当月起止日内指标之和                                                 |
+| 禁止     | `daily-metrics` / `stats` / `overview` 填上区投放列（询盘列仍来自 `inquiries.json`）                                                |
+
+**脚本聚合（每月一份 `campaigns-*.json`）**：
+
+```text
+rows = payload.items ?? []
+spend        = Σ rows[].spend
+clicks       = Σ rows[].clicks
+impressions  = Σ rows[].impressions
+conversions  = Σ rows[].conversions
+点击率       = impressions > 0 ? clicks / impressions : —
+平均每次点击费用 = clicks > 0 ? spend / clicks : —
+每次转化费用   = conversions > 0 ? spend / conversions : —
+转化率       = clicks > 0 ? conversions / clicks : —   # 与样表一致：转化÷点击，非÷展示
+询盘个数     = inquiries.json 该月 count
+CPL          = 询盘个数 > 0 ? spend / 询盘个数 : —
+```
+
+`时间` 列写 `YYYY-MM` 或 `YYYY年M月`（与样表一致即可）。金额列用 `list-accounts` 的 `currencyCode`。
+
+**可选校验（不写入 Excel，仅日志）**：同月再拉 `overview`，对比 `record.currentPeriod.spend`（汇总维度在 `record`）与系列 `spend` 之和；偏差 >1% 时在 Agent 交付说明中脚注差异，**仍以系列加总为准**。
+
+**上区**（B→L，跳过 A 列保持与运营样表一致）3 行月汇总：
+
+| R      | 内容                                                                                                                                                                                             |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| R1     | （A 列空）`汇总`                                                                                                                                                                                 |
+| R2     | `时间` \| `点击次数` \| `展示次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` \| `询盘个数` \| `CPL`                                                |
+| R3..R5 | 倒序写 3 个月（**E 月在上**，S 月在下）：脚本读 `./<YYYY-MM>/campaigns-*.json` 按上表对 `items[]` 全量求和；`询盘个数` = `inquiries.json` 按月 count；`CPL` = `费用 / 询盘个数`（询盘 0 填 `—`） |
+
+**下区**（B→G）3 月 × **重点国家 / 非重点国** 切片（共 6 行）：
+
+> **重点国家口径**（`focusCountries`）：见下方「重点国家配置」节，**禁止**在模板里写死任何国家名。
+
+| R       | 内容                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R7      | `时间` \| `国家` \| `消费` \| `线索数` \| `成本` \| `备注`                                                                                                                                                                                                                                                                                                                                                                                     |
+| R8..R13 | 每月一对（`<focusLabel>` / `非<focusLabel>`，其中 `focusLabel` = `focusCountries.join("+")`）：脚本读 `./<YYYY-MM>/geographic-*.json`，**按 `countryNameZh` 字段判桶**（CLI 已自动归并 city → country；未命中时回落 `countryOrRegionZh`）：`focusCountries.includes(countryNameZh)`；`消费` = 该桶 `spend` 求和；`线索数` = `inquiries.json` 同月同桶（按 `country` 字段匹配 `focusCountries`） count；`成本` = `消费 / 线索数`，线索 0 填 `—` |
+
+**`Agent 数据洞察`**（**位置**：下区（重点国切片）最末行下方留空 1 行接续，**A 列起**；Agent 基于本 Sheet 上 + 下区数据自动生成，**禁止**编造；每条**必带**具体数字）：
+
+| #   | 洞察类别                               | 内容（每条引用本 Sheet 具体数字）                                                                                |
+| --- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --- | ---------------------------------------------------------------------- |
+| 1   | **CPL 月环比**（上区）                 | E月 CPL `¥{x_E}` vs 中月 `¥{x_M}` vs S月 `¥{x_S}`；E月环比 `{±%}`；幅度 \|`> 30%`\| 高亮"显著波动"               |
+| 2   | **CTR / CVR 月环比**（上区）           | CTR：`{ctr_E}` / `{ctr_M}` / `{ctr_S}`（趋势 ↑↓→）；CVR：`{cvr_E}` / `{cvr_M}` / `{cvr_S}`（趋势 ↑↓→）           |
+| 3   | **消耗与询盘相关性**（上区）           | 列出 3 个月 `费用` 与 `询盘个数` 的同向 / 反向关系（如"消耗 ↓ 但询盘 ↑"提示效率提升）                            |
+| 4   | **重点国 vs 非重点国成本差额**（下区） | E月：重点国 CPL `¥{a}` vs 非重点国 `¥{b}`，差额 `{                                                               | a-b | }`；若重点国 CPL < 非重点国 CPL × 0.5 高亮"重点国成本显著低于其他市场" |
+| 5   | **重点国线索贡献占比**（下区）         | E月重点国线索 `{n}` 条，占总量 `{p}%`；3 个月平均占比 `{avg_p}%`；< 20% 提示"重点国线索贡献低，考虑扩展其他市场" |
+| 6   | **重点国趋势**（下区，3 月对比）       | 重点国线索数 / 消耗 / CPL 三个月趋势（如"重点国 CPL 连续 3 月下降"或"消耗稳定线索下降"）                         |
+
+**条数**：6 条为完整模板；若 `focusCountries = []`（本期无询盘），仅出第 1~3 条上区洞察，下区 3 条标 `[ 本期无重点国，省略下区洞察 ]`。
+
+---
+
+### Sheet 5 `广告系列消费明细`
+
+**上区**：
+
+| R                | 内容                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `广告系列表现明细  ·  账户 <mediaCustomerId(带连字符)>  ·  <数据开始月>-<数据结束月>`                                                                                                                                                                                                                                                                                                                                  |
+| R2（A→M，13 列） | `系列名称` \| `系列ID` \| `策略` \| `开始日期` \| `消耗 (¥)` \| `展示` \| `点击` \| `CTR` \| `平均CPC` \| `转化` \| `CPA (¥)` \| `转化率` \| `消耗占比`                                                                                                                                                                                                                                                                |
+| R3…              | 读 `campaigns-*.json` 的 `items[]`：`campaignName` / `campaignId` / `biddingStrategyTypeV2`（中文化：`MAXIMIZE_CONVERSIONS` → `Max转化`、`TARGET_SPEND` → `目标支出`、`MANUAL_CPC` → `手动CPC` 等；未命中保留原文）/ `startDate` / `spend` / `impressions` / `clicks` / `ctr` / `averageCpc` / `conversions` / `costPerConversion` / `conversionRate` / **`消耗占比` = `spend` / `sum(spend)`**（脚本算，写 0~1 小数） |
+| 末行             | `合计`：A 列写 `合计`；金额、展示、点击、转化 求和；CTR/CVR/CPA 按合计反推（**禁止**对各行比率求平均）                                                                                                                                                                                                                                                                                                                 |
+
+**下区**：
+
+| R           | 内容                                                                                                                                                                               |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 空 1 行     | —                                                                                                                                                                                  |
+| 标题        | `优化建议  ·  账户 <id>  ·  <分析月份>`                                                                                                                                            |
+| 表头（A→H） | `#` \| `问题/机会类别` \| `现状描述` \| `影响分析` \| `具体优化建议` \| `(留空)` \| `(留空)` \| `优先级`                                                                           |
+| 数据        | Agent 基于本期 Sheet 4/5/6/7/8 撰写 5~8 条建议；每条引用具体数字（如 `CPA ¥287，远高于均值 ¥111`）；`优先级` 取 `高` / `中` / `低`；**禁止**在建议里包含模板占位符或硬编码示例数字 |
+
+---
+
+### Sheet 6 `国家消费明细<S月>-<E月>月份`
+
+| R                | 内容                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1（A→N，14 列） | `月份(Excel 序列号)` \| `国家/地区（匹配）` \| `点击次数` \| `展示次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` \| `询盘个数` \| `(留空)` \| `(留空)` \| `暂停的系列`                                                                                                                                      |
+| R2…              | 笛卡尔积：`3 个月 × N 个国家`；脚本循环读 `./<YYYY-MM>/geographic-*.json`，每行**按 `countryNameZh` 聚合**（自动把 `Mumbai / Karachi / London` 等 city / region 行归并到所属国家；未命中归并字典回落 `countryOrRegionZh`）+ 该月该国家的指标；`询盘个数` = `inquiries.json` 同月同国家 count（左 join，缺失为 0）；`暂停的系列` 留空给运营手填（不要编造） |
+
+排序：按月份升序（与运营样表"45931 / 45962 / 45992 / 46023"顺序一致——分别对应 2025-10 ~ 2026-01 起算的 Excel 日期序列号）；同月内按 `点击次数` 降序。
+
+> **月份列用 Excel 日期序列号**还是 `YYYY-MM` 字符串？运营样表用日期序列号（如 `45931`、`46023`）；本模板**任选其一**，但**全表统一**；若用字符串则 R1 表头改为 `月份(YYYY-MM)`。
+
+**`Agent 数据洞察`**（**位置**：笛卡尔积主表最末数据行下方留空 1 行接续，**A 列起**；Agent 基于本 Sheet 数据自动生成，**禁止**编造）：
+
+| #   | 洞察类别                                            | 内容（每条引用本 Sheet 具体数字）                                                |
+| --- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
+| 1   | **国家月趋势 · 连续下降**                           | 列出 `费用` 连续 3 个月下降的国家（S → 中 → E 单调递减），按 E月消耗降序前 5     |
+| 2   | **国家月趋势 · 连续上升**                           | 列出 `费用` 连续 3 个月上升的国家（S → 中 → E 单调递增），按 E月消耗降序前 5     |
+| 3   | **新进入国家**（E 月有消耗，S 月消耗 = 0）          | 列国家、E 月消耗、E 月询盘；提示"本期新铺量国家"                                 |
+| 4   | **退出国家**（S 月有消耗，E 月消耗 = 0）            | 列国家、S 月消耗、3 月累计询盘；提示"本期已停投国家，可与暂停系列对照"           |
+| 5   | **高消耗 0 询盘国家**（与 Sheet 3 透视 1 交叉验证） | 列 3 月累计 `费用` Top10 中 3 月累计 `询盘个数` = 0 的国家                       |
+| 6   | **CPA 异常国家**                                    | 列 3 月平均 `每次转化费用` > 整体平均 × 2 的国家（且转化数 ≥ 3，排除小样本噪声） |
+
+**条数**：6 条为完整模板；某类无数据时该行填 `[ 无 ]`，**禁止**省略（保持出表完整）。
+
+---
+
+### Sheet 7 `关键词`
+
+| R                | 内容                                                                                                                                                                                                                                |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `关键词表现  ·  账户 <id>  ·  <分析月份>`                                                                                                                                                                                           |
+| R2（A→J，10 列） | `关键词` \| `匹配方式` \| `系列` \| `消耗 (¥)` \| `展示` \| `点击` \| `CTR` \| `平均CPC` \| `转化` \| `CPA (¥)`                                                                                                                     |
+| R3…              | 读 `keywords-*.json` 的 `items[]`：`keyword` / `keywordMatchTypeZh`（中文匹配方式：`Broad` / `Phrase` / `Exact`）/ `campaignName` / `spend` / `impressions` / `clicks` / `ctr` / `averageCpc` / `conversions` / `costPerConversion` |
+
+按 `转化` 降序、`消耗` 降序双排序。
+
+**`Agent 数据洞察`**（**位置**：关键词主表最末数据行下方留空 1 行接续，**A 列起**；Agent 基于本 Sheet 数据自动生成，**禁止**编造）：
+
+| #   | 洞察类别                                | 内容（每条引用本 Sheet 具体数字）                                                                                                                              |
+| --- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **匹配方式占比**                        | `Broad`：`{n_b}` 个、占消耗 `{p_b}%`；`Phrase`：`{n_p}` 个、占消耗 `{p_p}%`；`Exact`：`{n_e}` 个、占消耗 `{p_e}%`；Broad 消耗占比 > 70% 高亮"过度依赖广泛匹配" |
+| 2   | **高消耗 0 转化关键词**（精准止损候选） | 列 `消耗` Top20 中 `转化` = 0 的关键词，按消耗降序前 5；每条标 `关键词` + `匹配方式` + `消耗`                                                                  |
+| 3   | **CPA 异常关键词**（拖累候选）          | 列 `CPA` > 整体平均 × 2 且 `转化` ≥ 2 的关键词，前 5；每条标 `关键词` + `CPA` + `转化数`                                                                       |
+| 4   | **明星关键词**（性价比候选）            | 列 `CPA` < 整体平均 × 0.5 且 `转化` ≥ 3 的关键词，前 5；每条标 `关键词` + `CPA` + `转化数`                                                                     |
+| 5   | **单关键词消耗集中度**                  | Top3 关键词合计消耗占比 `{p3}%`；> 50% 高亮"消耗高度集中于少数关键词，风险敞口大"                                                                              |
+| 6   | **跨系列关键词重复**                    | 同一 `关键词` + `匹配方式` 出现在 ≥ 2 个 `系列` 中的条目数；提示"内部互抢候选"                                                                                 |
+
+**条数**：6 条为完整模板；某类无数据时该行填 `[ 无 ]`。
+
+---
+
+### Sheet 8 `搜索字词`
+
+| R                | 内容                                                                                                                                                                                                                                                                                    |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `搜索字词--TOP100`                                                                                                                                                                                                                                                                      |
+| R2               | `<S> - <E>`（如 `2026年4月1日 - 2026年4月30日` 等中文区间）                                                                                                                                                                                                                             |
+| R3（A→Q，17 列） | `搜索字词` \| `搜索字词匹配类型` \| `已添加/已排除` \| `广告系列` \| `广告组` \| `搜索广告关键字` \| `点击次数` \| `展示次数` \| `点击率` \| `货币代码` \| `平均每次点击费用` \| `费用` \| `绝对页首展示次数百分比` \| `页首展示次数百分比` \| `转化次数` \| `每次转化费用` \| `转化率` |
+| R4…              | 读 `search-terms-*.json`（`data[]`）：`searchTermText` / `matchTypeZh` / **`queryTargetingStatusZh`**（已添加/已排除/都没有；网关字段 `queryTargetingStatus`）/ `campaignName` / `adGroupName` / `keywordText` / 数值字段；`货币代码` 来自 `list-accounts` 同账户 `currencyCode`        |
+
+按 `费用` 降序前 100。
+
+> **关于"绝对页首展示次数百分比 / 页首展示次数百分比"**：当前 `SearchTermListRow` 类型只显式声明了通用指标，但 `[key: string]: unknown` 兜底使原始字段照常落盘。脚本应读 JSON 原始字段名（实际跑一次确认网关返回字段名，如 `absoluteTopImpressionPercentage` / `topImpressionPercentage`），命中即写、未返回则填 `—`。
+
+**`Agent 数据洞察`**（**位置**：搜索字词主表最末数据行下方留空 1 行接续，**A 列起**；Agent 基于本 Sheet 数据自动生成，**禁止**编造）：
+
+| #   | 洞察类别                                                            | 内容（每条引用本 Sheet 具体数字）                                                                                                                              |
+| --- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **未添加但高转化搜索词**（候选加为关键词）                          | `queryTargetingStatusZh` = "都没有" 且 `转化次数` ≥ `{阈值}`，按转化降序前 10；阈值取本期搜索词转化中位数                                                      |
+| 2   | **已添加但 0 转化高消耗搜索词**（候选加为否定关键词）               | `queryTargetingStatusZh` = "已添加" 且 `转化次数` = 0 且 `费用` > `¥{阈值}`，按消耗降序前 10；阈值取本期搜索词消耗 P75                                         |
+| 3   | **无关搜索词**（意图偏离候选）                                      | 基于 `搜索字词` 文本扫描，标出与广告组 / 关键字 主题明显不符的词（如"工厂"系列出现"价格便宜""免费""教程"等），前 5；**仅展示**，**不**自动判定，由运营会上拍板 |
+| 4   | **匹配方式分布**                                                    | `Broad`：`{n_b}` 个、占消耗 `{p_b}%`；`Phrase`：`{n_p}` 个、占消耗 `{p_p}%`；`Exact`：`{n_e}` 个、占消耗 `{p_e}%`                                              |
+| 5   | **页首展示低 / 高消耗搜索词**（仅当 `页首展示次数百分比` 字段可用） | 列 `费用` Top20 中 `页首展示次数百分比` < 50% 的搜索词，前 5；提示"花了钱但很少展示到页首，出价/质量得分待优化"                                                |
+
+**条数**：5 条为完整模板；若网关未返回页首展示字段（第 5 条），整行填 `[ 字段不可用 ]`；其余无数据填 `[ 无 ]`。
+
+---
+
+## 重点国家配置（Sheet 3 大洲桶 + Sheet 4 下半区切片共用）
+
+`focusCountries` 是一个**中文国家名数组**，决定：
+
+1. Sheet 3 国家透视「所属大洲」列的特殊桶名（如 `印度` / `印度+印度尼西亚` / `美国` …）；
+2. Sheet 4 下半区按月二分的「重点国 / 非重点国」分桶。
+
+**取值规则**（按优先级）：
+
+1. **运营在会议前显式指定**（最高优先级），例如：
+
+   ```json
+   { "focusCountries": ["印度"] }
+   ```
+
+   或多国（与样表 Sheet 3「印度+印尼」桶呼应）：
+
+   ```json
+   { "focusCountries": ["印度", "印度尼西亚"] }
+   ```
+
+2. **默认值（运营未指定时）**：取**分析月（最后一个月 E 月）`inquiries.json` 询盘数 Top1 国家**。脚本在控制台打印一行：`[focusCountry auto-pick] {E月}询盘 Top1 = {国家}（{count} 条），如需调整请回填运营配置`。
+3. **空数组兜底**：若分析月询盘 0 条，`focusCountries = []`；Sheet 3 跳过「重点国」单桶（直接走默认 5 桶里的对应大洲），Sheet 4 下半区**整段省略**并在 Sheet 标题留脚注 `[ 本期无询盘，省略国家切片 ]`。
+
+**禁止**：在脚本里硬编码 `"印度"`、`"India"` 等具体国家名作为业务逻辑（仅 `geo-en2zh.json` / `analytics/geo-continents.json` 这种字典数据除外）。
+
+---
+
+## 可选：产品 → 系列前缀映射
+
+样表里产品（`滴灌带` / `打包带` / `预制孔水带`）与系列名前缀对应（`A-滴灌带-…` / `B-打包带-…` / `C-预制孔水带设备`）。若运营给出映射，脚本可补 Sheet 3 第 3 个透视的「消耗」「CPL」列；否则**留空 + 脚注**。
+
+映射示例（由运营每次会议前确认，不写死在模板）：
+
+```json
+{
+  "滴灌带": ["A-滴灌带-"],
+  "打包带": ["B-打包带-"],
+  "预制孔水带": ["C-预制孔水带"]
+}
+```
+
+脚本逻辑：`产品消耗 = sum(campaigns[campaignName 以前缀 startsWith].spend)`。
+
+---
+
+## 与其他报告模板的差异
+
+| 项                       | `google-period-report.md` | `okki-weekly-google-client.md` | **本文（询盘分析）**                           |
+| ------------------------ | ------------------------- | ------------------------------ | ---------------------------------------------- |
+| 时间窗                   | 用户给定                  | 用户给定（通常 1 周）          | **严格 3 个自然月**                            |
+| 默认维度                 | 8 维 + 追问               | 6 维固定                       | **7 维固定（多 `geographic` 月度循环 3 次）**  |
+| 是否需要询盘原始数据     | 否                        | 否                             | **是**（用户上传 / 反问索要）                  |
+| 输出形态                 | 长文报告                  | 客户话术 + 多 Sheet xlsx       | **8 Sheet xlsx（不含客户话术）**               |
+| Excel 由谁写             | Agent 脚本（可选）        | Agent 脚本                     | **Agent 脚本（必需）**                         |
+| 大洲映射                 | 不涉及                    | 不涉及                         | **`references/analytics/geo-continents.json`** |
+| 重点国家 vs 非重点国切片 | 否                        | 否                             | **是**（Sheet 4 下半区，重点国可配置）         |
+
+---
+
+## 验收口径
+
+- 用户说出 3 条触发话术之一 → AI 切到本模板（**不**走 `google-period-report.md`）。
+- AI 反问：账户 + 分析月份 + 询盘资料（若用户未给）。
+- AI 跑 1 次区间多维度 + 3 次月度 `geographic` 循环；产物全部落 `./snap-inquiry`。
+- AI 产出 8 Sheet `.xlsx`，**每个数字可追溯到 `./snap-inquiry/**/\*.json`或`inquiries.json` 的具体字段\*\*。
+- 未命中大洲映射的国家：标 `未知大洲`，**不阻塞**、**不编造**；末尾打印未命中清单。
+- 产品 → 系列映射未给：Sheet 3 产品透视的「消耗 / CPL」列填空 + 脚注，**不分摊、不编造**。