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

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

@@ -0,0 +1,126 @@
+# Google 账户周期报告 — Excel 交付规格
+
+> **适用场景**：用户明确要求 **Google 账户 + 统计区间 + Excel/xlsx**，且**未**使用 OKKI / 询盘固定话术。  
+> **工作流**：**P4**（与 `google-period-report.md` 共用拉数维度；交付形态不同）。  
+> **禁止**：加载宿主「xlsx / Excel」第三方 Skill 代替本流程；**无** CLI 内置写表子命令，须 Agent 脚本（`exceljs` / `xlsx` / `openpyxl`）读落盘 JSON 写 `.xlsx`。
+
+---
+
+## 执行门禁（**全部满足后才允许写脚本**）
+
+以下任一项未完成 → **禁止** `google-analysis` 之后的写 Excel 步骤：
+
+| #   | 门禁                  | 命令 / 动作                                                                                                                     |
+| --- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Read 当次必读         | `core/agent-conventions.md`、`analytics/account-analytics.md`、`google-period-report.md`（本文）                                |
+| 2   | **账户 ID 核验**      | `siluzan-tso list-accounts -m Google -k <用户给的 mediaCustomerId> --json-out ./snap-p4`                                        |
+| 3   | 确认 `currencyCode`   | 来自步骤 2 落盘 JSON 的 `items[].ma.currencyCode`（或表格列「币种」）                                                           |
+| 4   | **拉数**              | `google-analysis -a <已核验的 mediaCustomerId> --start … --end … --sections … --json-out <dir>`                                 |
+| 5   | **先 outline 后脚本** | 对本次 `--sections` 涉及的**每一个**维度，Read 同目录 `<section>-<accountId>_*.outline.txt`（或 stdout 摘要里的 `outlineFile`） |
+| 6   | 写脚本                | 字段名**只**来自 outline 最后一行 TS 类型；业务 JSON **仅**在脚本内 `readFileSync` / `require`                                  |
+| 7   | 交付前审阅            | 按 `core/agent-conventions.md` §七 自检；xlsx 无法 Read 时须贴自检表 + 脚本 stdout 摘要                                         |
+
+---
+
+## 账户 ID 纪律（来自真实踩坑）
+
+用户给出的 `mediaCustomerId`（如 `2702960720`）**必须**与后续全流程一致：
+
+- **必须**：`list-accounts -m Google -k <该 ID>` 单户查询；404 / 空列表 → 告知用户 ID 不存在，**停止**，不得换号继续。
+- **禁止**：`list-accounts` 翻页 + `grep` 猜账户；禁止把列表里「看起来像」的另一账户（如 `9322098303`）当作用户要的 ID。
+- **禁止**：目录名用用户 ID、但 `google-analysis -a` 或脚本里读文件用另一个 ID。
+- **禁止**：`entityId` 与 `mediaCustomerId` 混用（见 `agent-conventions.md`）。
+
+核验通过后，在报告首行/封面写：`统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`，且账户 ID 与 `list-accounts` 输出一致。
+
+---
+
+## 用户指定 Sheet → CLI section 映射
+
+用户已列出 Sheet 名时，**以用户清单为准**拉数（不必等追问）；未列出的 P4 默认维度（系列/设备/优化建议等）**不强行追加**，除非用户要求。
+
+| 用户 Sheet（常见表述） | `google-analysis` section      | 读法（schemaVersion 3）    |
+| ---------------------- | ------------------------------ | -------------------------- |
+| 账户概览 / 执行摘要    | `overview`                     | `record`（汇总维度）       |
+| 每日报告 / 每日趋势    | `daily-metrics`                | `items[]`                  |
+| 关键字 / 关键词报告    | `keywords`                     | `items[]`                  |
+| 搜索字词 / 搜索词报告  | `search-terms`                 | `items[]`                  |
+| 国家 / 地域 / 地区报告 | `geographic`                   | `items[]`                  |
+| 广告系列（若用户要）   | `campaigns`                    | `items[]`                  |
+| 设备（若用户要）       | `devices` 或 `campaign-device` | `items[]`；OKKI 口径用后者 |
+
+**一次拉齐示例**（用户要 5 Sheet：概览+每日+关键词+搜索词+国家）：
+
+```bash
+mkdir -p ./snap-p4
+siluzan-tso list-accounts -m Google -k <id> --json-out ./snap-p4
+
+siluzan-tso google-analysis -a <id> --start <S> --end <E> --json-out ./snap-p4 \
+  --sections overview,daily-metrics,keywords,search-terms,geographic
+```
+
+落盘文件名以 stdout 摘要 `results[].file` 为准（常含 `_<start>-<end>` 后缀），**禁止**硬编码 `overview.json`。
+
+---
+
+## outline → 脚本：禁止猜的字段名
+
+以下「直觉名」在 **schemaVersion 3** 落盘中**不存在**或易错——须以当次 `*.outline.txt` 为准：
+
+| 维度              | ❌ 禁止猜                                            | ✅ outline 真实字段                                                                                        |
+| ----------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `keywords`        | `keywordText`、`status`、`matchType`（单独作展示列） | `keyword`、`userStatus`、`keywordMatchTypeZh`（或 `keywordMatchType`）                                     |
+| `search-terms`    | `query`                                              | `searchTermText`；匹配类型用 `matchTypeZh`；状态用 `queryTargetingStatusZh`                                |
+| `geographic`      | `geoName`、`countryCriterionIdName`                  | `countryOrRegion`、`countryNameZh`、`countryCode`                                                          |
+| 全维度 CTR/转化率 | 已是 0~100 的百分数                                  | `ctr` / `conversionRate` 为 **0~1 小数**；Excel 写入原值 + 单元格 `0.00%`，或文案 `(v*100).toFixed(2)+'%'` |
+
+**数据访问统一规则**（outline 头部注释已写明）：
+
+- `record !== null` → 读 `record`（如 `overview`）
+- 否则 → 读 `items[]`
+
+---
+
+## 禁止的数据探查方式
+
+写 Excel 脚本**之前**，不得用以下方式「预览」业务 JSON（与 `agent-conventions.md`、`tips.md` 一致）：
+
+- `cat …json | python -m json.tool | head`
+- 宿主 **Read** 打开 `keywords-*.json`、`overview-*.json` 等落盘业务文件
+- 把 JSON 片段贴进对话当字段依据
+
+**允许**：Read `*.outline.txt`；脚本 `console.log` 打印行数 / 首行抽样 / 汇总 totals（stdout 给 Agent 核对）。
+
+---
+
+## Excel 版式（无运营固定样表时的最小约定）
+
+用户未指定表头时，可按业务语义建 Sheet，但须满足：
+
+1. **Sheet 名**与用户要求一致（如 `账户概览`、`每日报告`、`关键字报告`、`搜索字词报告`、`国家报告`）。
+2. **首行或 R2** 含统计区间 + 币种（与 `list-accounts` 一致）。
+3. **列表 Sheet**：R1 为表头；列名与 outline 字段含义对应，不造 outline 中不存在的列。
+4. **数值**：金额 2 位小数；`ctr`/`conversionRate` 按上文 0~1 口径；禁止对 JSON 比率再 ÷100。
+5. 某维度拉数失败：该 Sheet 写 `[ 数据不可用：<原因> ]`，禁止留空或编造。
+
+有 OKKI 固定话术时改走 **P6**（`okki-weekly-google-client.md`），**不**用本文。
+
+---
+
+## 交付前自检（P4 Excel 专用）
+
+对照 `core/agent-conventions.md` §七 表 A/B/C，并额外确认：
+
+- [ ] `google-analysis` 的 `accountId`（stdout 摘要）= 用户要求的 `mediaCustomerId`
+- [ ] 每个 Sheet 列均能在对应 `*.outline.txt` 中找到字段源
+- [ ] 脚本 stdout 打印的 `itemCount` 与 Excel 数据行数一致（±合计行）
+- [ ] 未使用第三方 xlsx Skill 替代本 Skill 拉数与字段口径
+
+---
+
+## 相关文档
+
+- `google-period-report.md` — 默认维度与可选追加
+- `okki-weekly-google-client.md` — OKKI 固定 5 Sheet（P6）
+- `references/core/tips.md` — 摘要 → outline → 脚本
+- `references/core/playbooks.md` — P4 步骤卡片

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

@@ -0,0 +1,60 @@
+# Google 账户分析报告
+
+> 统计区间：`{startDate}` ~ `{endDate}`  
+> 账户：`{mediaCustomerId}`
+
+> **用户明确要求 Excel / xlsx**（且非 OKKI / 询盘话术）时：在拉数步骤不变的前提下，**另 Read 全文** `report-templates/google-period-report-excel.md`，并**先读齐**各维度 `*.outline.txt` 再写脚本；禁止加载宿主第三方 xlsx Skill。
+
+---
+
+## 默认报告维度
+
+生成报告时，**默认包含**以下 8 个维度：
+
+| #   | 维度                                                                         | CLI                                                                                           |
+| --- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| 1   | 执行摘要（消耗/展示/点击/转化/CTR/CPC/CPA 本期概览）                         | `google-analysis --sections overview`                                                         |
+| 2   | 每日投放趋势（按日消耗/点击/转化曲线；金额/CPA **2 位小数**，转化/点击整数） | `google-analysis --sections daily-metrics`                                                    |
+| 3   | 月度汇总（全周期汇总数据）                                                   | `google-analysis --sections dimension-summary`                                                |
+| 4   | 广告系列表现（预算/出价策略/各系列消耗与效果）                               | `google-analysis --sections campaigns`                                                        |
+| 5   | 设备分布（PC/移动/平板 消耗/点击/转化）                                      | `google-analysis --sections devices`                                                          |
+| 6   | 地域分布（国家/地区 消耗占比）                                               | `google-analysis --sections geographic`                                                       |
+| 7   | 关键词表现（词/消耗/CTR/CPC 排行）                                           | `google-analysis --sections keywords`（这个命令获取的关键词数据会来自多个系列，不能合并去重） |
+| 8   | 优化建议（根据以上数据给出可执行改进建议）                                   | 不额外拉数，基于已有数据撰写                                                                  |
+
+**在执行任何数据拉取之前**，先向用户展示以下可选维度，询问是否需要追加：
+
+---
+
+## 平台支持的全部可选维度
+
+| 维度          | CLI                                             | 备注                                                              |
+| ------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
+| 系列按小时    | `google-analysis --sections campaign-hour`      | 行在 `items[]`，含 `date`/`hour`/消耗与效果                       |
+| 受众分布      | `google-analysis --sections audience`           | 可分 `SystemDefined` / `UserDefined`                              |
+| 搜索词报告    | `google-analysis --sections search-terms`       | 高消耗搜索词；`queryTargetingStatusZh` 列（已添加/已排除/都没有） |
+| 广告创意表现  | `google-analysis --sections ads`                | 广告标题/类型/到达网址                                            |
+| 附加信息      | `google-analysis --sections extensions`         | 附加链接/电话/宣传信息等状态                                      |
+| 图片/视频素材 | `google-analysis --sections materials`          | 图片 + 视频合并视图                                               |
+| 账户落地页    | `google-analysis --sections final-urls`         | 主投放域名/落地页（不传日期）                                     |
+| 黄金账户评分  | `google-analysis --sections gold-account`       | 健康度评分与各项达标状态                                          |
+| 广告质量指标  | `google-analysis --sections ads-index`          | 质量得分汇总                                                      |
+| 转化动作配置  | `google-analysis --sections conversion-actions` | 已配置的转化目标列表                                              |
+| 账户结构统计  | `google-analysis --sections resource-counts`    | 系列/组/广告/词数量                                               |
+| 广告系列类型  | `google-analysis --sections campaign-types`     | 系列类型分布（不传日期）                                          |
+
+---
+
+## 拉数顺序（默认 7 个维度）
+
+**首选：用 `google-analysis --sections` 一次拉齐**（单进程复用 keep-alive，比逐个 spawn 快 3-7×；详见 `references/analytics/account-analytics.md` 的 `all` 子命令说明）：
+
+```bash
+mkdir -p ./snap-google
+siluzan-tso google-analysis -a <id> --start <s> --end <e> --json-out ./snap-google \
+  --sections overview,daily-metrics,dimension-summary,campaigns,devices,geographic,keywords
+```
+
+如果用户**追加**了维度（按上文「可选追加」表），把它们加入 `--sections` 即可；要全 21 维则省略 `--sections`。
+
+> 仅在调试单个维度或需要传 `all` 暂未透传的特殊参数时，才回落到逐条 `siluzan-tso google-analysis <子命令> -a <id> …` 调用。

package/dist/skill/references/report-templates/market-analysis-report.md

@@ -0,0 +1,40 @@
+# 战略市场分析报告（交付模板）
+
+> **最终交付物**：可打开的 `market-analysis-report.html`。  
+> **质量门禁**：`render` 按 **TSO getMarketReport 原始业务维度** 校验 HTML，缺项失败（非文件大小）。
+
+---
+
+## 数据流
+
+```
+collect → Agent 按维度清单调研撰写 → market-report.json → render → HTML
+```
+
+---
+
+## Agent 必读
+
+- `assets/market-analysis-rules.md` — **原始业务维度清单**（校验依据）
+- `collect` 中的 `customerInfo`、`websitePreview`
+
+---
+
+## 交付前自检（对照维度清单）
+
+### 六大章 + 附录
+
+- [ ] **一、市场与趋势**：TAM/SAM/SOM、价值链、国家拆解、PESTEL、3–5 年预测
+- [ ] **二、行业洞察**：≥4 痛点、合规模块、BPMN 流程对比 + 量化
+- [ ] **三、受众场景**：受众分层表、场景价值 + 图表
+- [ ] **四、竞争定位**：≥3 竞品、≥10 行对比表、四类空白、定位陈述
+- [ ] **五、增长品牌**：GTM 三阶段、品牌传播、营销战术
+- [ ] **六、实施风险**：里程碑表、预算、风险矩阵
+- [ ] **附录**：来源清单、调研方法、术语表（ROI/CAGR/GTM/BPMN）
+
+### 呈现
+
+- [ ] ECharts 图表（`homeCDN/echarts.js`）+ Source 脚注
+- [ ] 已 `render` 成功（无「缺少 N 项必含内容」）
+
+**不通过** → 针对 CLI 列出的缺失维度补研扩写，勿交付简版。

package/dist/skill/references/report-templates/meta-account-diagnosis-report.md

@@ -0,0 +1,74 @@
+# Meta（Facebook）账户 — 诊断报告（模板纲要）
+
+> 统计区间：`{startDate}` ~ `{endDate}`  
+> 账户：`{mediaCustomerId}`（`{mediaCustomerName}`）
+
+在 **Facebook Ads 现有 7 个 Section** 内，尽量对齐 `google-account-diagnosis-report.md` 的章节结构；无接口的章节保留标题并写 `[ 本媒体接口未提供：{Google 维度名} ]`。
+
+拉数：**一次** `facebook-analysis`（建议全 7 维或默认 6 维 + 按需 `material`）。
+
+```bash
+siluzan-tso facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb-diagnosis
+```
+
+---
+
+## 1. 账户画像
+
+- 账户名：`overview` → `accountName`；`list-accounts -m MetaAd -k <id>` 补 BM/状态（若有）。
+- **无** Google 式落地页 Section → 写 `[ 本媒体接口未提供：final-urls ]`。
+
+## 2. 核心指标快照
+
+- **CLI**：`overview`
+- 本期 vs 上期：消耗、展示、点击、CTR、CPC、转化、CPA、results、costPerResult、reach、frequency。
+
+## 3. 账户结构
+
+- **无** `resource-counts` / `conversion-actions` → 用 `ad-sets` + `creative` 行数简述：「共 N 个广告组、M 条在投创意（有 spend/impressions）」。
+- 按 `campaignName` 去重估算系列数（说明为派生，非 API 直出）。
+
+## 4. 健康度 / 黄金账户
+
+- `[ 本媒体接口未提供：gold-account ]`
+
+## 5. 系列类型分布
+
+- `[ 本媒体接口未提供：campaign-types ]`；可用 `creative` 的 `creativeType` 分布作补充。
+
+## 6. 重点维度对比（本期 vs 上期）
+
+- 总览已含环比；另可对 `ad-sets` / `country` / `platform` 做「本期排行」快照（无上期分维数据时不做分维环比）。
+
+## 7. 转化成本趋势
+
+- `[ 本媒体接口未提供：daily-metrics ]`；勿用猜测曲线。
+
+## 8. 平台、地域、受众
+
+- **CLI**：`platform`、`country`、`audience`
+- `platform` → `networks[]`：用 **`publisherPlatform`**（投放平台）+ **`platformPosition`**（版位）；`network` 仅等于 `platformPosition`（兼容旧版，勿当平台列）。
+- 全表或 Top 表；与 Google `devices` / `geographic` / `audience` 对应说明。
+
+## 9. 创意（替代搜索词+搜索广告）
+
+- **CLI**：`creative`
+- Top 创意、低效创意；**无** `search-terms` → `[ 不适用：搜索词 ]`
+
+## 10. 素材
+
+- **CLI**：`material`（DC）；否则指向 `creative`。
+- **无** Google `extensions` → `[ 本媒体接口未提供：extensions ]`
+
+## 11. 质量得分
+
+- `[ 本媒体接口未提供：ads-index ]`
+
+## 12. 总结与行动项
+
+- 优先：高消耗低效 Ad Set、版位、国家、人群、创意。
+- 列出已排除的 Google-only 检查项，避免读者以为漏查。
+
+---
+
+字段细则：`references/analytics/facebook-analysis-guide.md`。

package/dist/skill/references/report-templates/meta-period-report-excel.md

@@ -0,0 +1,230 @@
+# Meta（Facebook）周期报告 — Excel 模板规格
+
+> **适用场景**：用户**明确要求 Excel / xlsx** 交付时读本文件。  
+> 用户未指定格式时，**默认交付 HTML**，走 `meta-period-report.md` 标准四步（拉数 → 分析 → 写 JSON → `facebook-analysis render`），**不要**默认走 Excel。
+
+> 对照业务交付物：`无锡顺晟Facebook4月报告.xlsx`（5 个 Sheet）。  
+> Excel 流程：CLI 拉数 → Agent 分析并写 `meta-period-report.json` → **Agent 脚本**按本规格写 `.xlsx`（**无** CLI 内置 excel 子命令）。
+
+---
+
+## Excel 工作簿结构（5 Sheet）
+
+| Sheet | 中文名         | CLI `--sections` | 落盘文件             | 报告中的角色                                        |
+| ----- | -------------- | ---------------- | -------------------- | --------------------------------------------------- |
+| 1     | **总数据**     | `overview`       | `overview-<id>.json` | 账户级 KPI + **全部叙事分析**（唯一写文案的 Sheet） |
+| 2     | **广告组数据** | `ad-sets`        | `ad-sets-<id>.json`  | 区域/广告组维度表（拉美、欧洲、亚洲等）             |
+| 3     | **平台数据**   | `platform`       | `platform-<id>.json` | Facebook vs Instagram 对比表                        |
+| 4     | **国家数据**   | `country`        | `country-<id>.json`  | 国家/地区排行表                                     |
+| 5     | **受众数据**   | `audience`       | `audience-<id>.json` | 年龄 × 性别矩阵表                                   |
+
+**Excel 模板不含**：创意 Sheet、`material`、按日趋势、关键词。若用户要创意章节，额外拉 `--sections creative`。
+
+---
+
+## 统一数据列（Sheet 2～5 及总数据 KPI 行）
+
+Excel 导出列与 API 字段对照（撰写/渲染时统一用 API camelCase，展示用中文列名）：
+
+| Excel 列名       | API 字段             | 说明                                      |
+| ---------------- | -------------------- | ----------------------------------------- |
+| 目标 / 成效类型  | `resultType`         | 如「Meta 潜在客户」                       |
+| 覆盖人数         | `reach`              | 整数                                      |
+| 展示次数         | `impressions`        | 整数                                      |
+| 频次             | `frequency`          | 小数；>2 可提示疲劳                       |
+| 归因设置         | `attributionSetting` | 如「点击后 7 天内或浏览后 1 天内」        |
+| 成效             | `results`            | Meta「结果」列，**勿与 conversions 混用** |
+| 已花费金额 (USD) | `spend`              | 美元，非 micros                           |
+| 单次成效费用     | `costPerResult`      | CPL                                       |
+
+### Sheet 2 额外列
+
+| Excel 列名   | API 字段       |
+| ------------ | -------------- |
+| 广告系列名称 | `campaignName` |
+| 广告组名称   | `adGroupName`  |
+
+### Sheet 3 维度列
+
+| Excel 列名 | API 字段            | 备注                                            |
+| ---------- | ------------------- | ----------------------------------------------- |
+| 平台       | `publisherPlatform` | 汇总时按平台聚合；版位细拆见 `platformPosition` |
+
+### Sheet 4 维度列
+
+| Excel 列名 | API 字段          |
+| ---------- | ----------------- |
+| 国家/地区  | `countryOrRegion` |
+
+### Sheet 5 维度列
+
+| Excel 列名 | API 字段 |
+| ---------- | -------- | ----------------------------- |
+| 年龄       | `age`    |
+| 性别       | `gender` | `male` / `female` / `unknown` |
+
+**受众表注意**：`gender=unknown` 或 `成效=0` 的行可保留在数据表，撰写时说明「样本不足勿扩量」。
+
+---
+
+## Sheet 1「总数据」— 叙事章节（Agent 必写）
+
+总数据 Sheet 除首行 KPI 外，按**固定标题块**顺序撰写（与 Excel 版式一致）：
+
+### 1. 整体表现
+
+- **1 段话**，覆盖：总花费、线索数（`results`）、平均 CPL、覆盖、展示、频次。
+- 示例结构：「{月}月总花费 {spend} 美元，获得 {results} 条线索，平均每条成本 {cpl} 美元。覆盖 {reach} 人，展示 {impressions} 次，频次 {frequency}。」
+
+### 2. 区域报告
+
+- 按 **广告组**（Sheet 2 各行）写 **3～5 句**，每段对应一个区域组（如 leads-欧洲、leads-拉美、leads-亚洲）。
+- 必提：单条 CPL、线索数、覆盖/频次特征、是否「曝光不足」或「频次高转化差」。
+- 数据依据：`ad-sets-<id>.json` → `adGroups[]`。
+
+### 3. 国家报告
+
+- **1 段话**对比 Top 国家：最低 CPL 国家、最高 CPL 国家、中间梯队。
+- 数据依据：`country-<id>.json` → `countries[]`（按 `costPerResult` 或 `spend` 排序）。
+
+### 4. 优化建议（固定 4 条 + 7 维补充）
+
+**每条 `content` ≥150 字**，须引用当次国家名/CPL/广告组名；严重项以「强烈建议：」开头。完整规则见 **`assets/meta-period-report-rules.md`**。
+
+| #   | 标题             | 撰写要点                                                   |
+| --- | ---------------- | ---------------------------------------------------------- |
+| 1   | **简化表单问题** | 点名高频次高 CPL 国家/组；字段缩减至 3 项；写预期 CPL 改善 |
+| 2   | **区域调整**     | 按广告组写语言/市场策略；写清加谁、减谁、暂停谁            |
+| 3   | **预算重构**     | 具体比例（如 4:3:3）、测试 7/14 天、CPL 阈值优胜劣汰       |
+| 4   | **素材建议**     | 分 IG/FB、分市场；素材套数、视频时长、高花费低结果创意处理 |
+
+**Excel 总数据 Sheet 另须**（可写在 4 条之后或单独小节）：
+
+- `supplementaryRecommendations` 7 维表（预算/平台/地域/受众/创意/频次/接口限制）
+- `priorityPlan` 高/中/低各 ≥2 条（推荐）
+
+---
+
+## 拉数命令（对齐 Excel 五 Sheet）
+
+```bash
+siluzan-tso facebook-analysis -a <mediaCustomerId> \
+  --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
+  --json-out ./snap-fb \
+  --sections overview,ad-sets,platform,country,audience
+```
+
+---
+
+## Agent JSON 映射（`meta-period-report.json`）
+
+与 Excel 模板 **一一对应** 的字段（HTML 深度分析扩展字段见 `meta-period-report.md` § HTML 扩展章节）。
+
+```jsonc
+{
+  "meta": {
+    "accountName": "无锡顺晟",
+    "periodLabel": "2026年4月",
+    "startDate": "2026-04-01",
+    "endDate": "2026-04-30",
+    "resultType": "Meta 潜在客户",
+    "attributionSetting": "点击后7天内或浏览后1天内",
+    "generatedAt": "2026/5/19 18:27:05",
+  },
+  // KPI 行：可省略，由 --snapshot-dir 从 overview 合并
+  "kpis": {
+    "spend": 473.01,
+    "results": 36,
+    "costPerResult": 13.14,
+    "reach": 45628,
+    "impressions": 72850,
+    "frequency": 1.6,
+  },
+  // 对应 Sheet1 叙事块
+  "narrative": {
+    "overall": "4月总花费473美元…",
+    "regional": [
+      { "adGroupName": "leads-欧洲", "text": "欧洲（土耳其）成本最低…" },
+      { "adGroupName": "leads-拉美", "text": "拉美成本最高…" },
+      { "adGroupName": "leads-亚洲", "text": "亚洲介于两者之间…" },
+    ],
+    "country": "土耳其单条9.45美元，远低于其他国家…",
+    "recommendations": [
+      { "title": "简化表单问题", "content": "强烈建议：…（≥150字，含国家/CPL数字）" },
+      { "title": "区域调整", "content": "推荐优化：…" },
+      { "title": "预算重构", "content": "…" },
+      { "title": "素材建议", "content": "…" },
+    ],
+  },
+  "supplementaryRecommendations": [
+    { "dimension": "预算与广告组", "issue": "…", "suggestion": "…" },
+  ],
+  "priorityPlan": { "high": ["…"], "medium": ["…"], "low": ["…"] },
+  // 对应 Sheet2～5 表格 + 图表：可省略，由 --snapshot-dir 自动合并
+  "tables": {
+    "adSets": [
+      /* 见 merge-snapshot */
+    ],
+    "platform": [
+      /* publisherPlatform 汇总行 */
+    ],
+    "countries": [
+      /* country 行 */
+    ],
+    "audiences": [
+      /* age×gender 行 */
+    ],
+  },
+  "charts": {
+    "platform": { "labels": ["instagram", "facebook"], "cpl": [], "spend": [] },
+    "country": { "labels": [], "cpl": [] },
+    "audience": { "labels": [], "cpl": [], "leads": [] },
+  },
+}
+```
+
+完整 JSON Schema：`assets/meta-period-report.schema.json`。
+
+---
+
+## HTML 渲染章节（Excel 必含 vs 深度分析扩展）
+
+| 报告章节            | Excel 必含                     | 深度 HTML 扩展（可选）                     |
+| ------------------- | ------------------------------ | ------------------------------------------ |
+| KPI 顶栏            | ✅                             | —                                          |
+| 整体表现 / 执行摘要 | ✅ `narrative.overall`         | `executiveSummary[]` 可多段深度解读        |
+| 区域报告            | ✅ `narrative.regional`        | 广告组疲劳表 + `sections.adSets.insight`   |
+| 国家报告            | ✅ `narrative.country`         | 国家 CPL 图表 + `sections.country.insight` |
+| 优化建议 4 条       | ✅ `narrative.recommendations` | A/B 实验、行动清单                         |
+| 平台对比表/图       | ✅ Sheet3                      | `sections.platform.insight`                |
+| 国家排行表/图       | ✅ Sheet4                      | —                                          |
+| 受众矩阵表/图       | ✅ Sheet5                      | Top/Bottom 10、黄金画像                    |
+| 账户健康诊断        | ❌                             | 三阶段 / 四问 / 红绿灯表                   |
+| 落地页表单分析      | ❌（合并在「简化表单」建议）   | `sections.landingPage`                     |
+
+**默认交付**：以 Excel 五 Sheet + 总数据叙事为准；用户明确要求「深度分析 / 总监视角」时再补 HTML 扩展章节。
+
+---
+
+## HTML 渲染（可选 · 非 Excel 默认路径）
+
+用户**同时要 HTML** 或**未要 Excel、走默认流程**时，在写完 `meta-period-report.json` 后执行：
+
+```bash
+siluzan-tso facebook-analysis render \
+  --data ./meta-period-report.json \
+  --snapshot-dir ./snap-fb \
+  --out ./meta-period-report.html
+```
+
+**仅交付 Excel** 时可跳过本节。
+
+---
+
+## 相关文档
+
+| 文档                                              | 用途                                |
+| ------------------------------------------------- | ----------------------------------- |
+| `meta-period-report.md`                           | 周期报告总纲 + HTML 扩展 + CLI 流程 |
+| `assets/meta-period-report.schema.json`           | Agent JSON 机器校验                 |
+| `references/analytics/facebook-analysis-guide.md` | API 字段口径                        |