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

package/dist/skill/references/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 分析一致、不得矛盾**；可呼应对外客户话术（若用户需要）。
 
 ---
 

package/dist/skill/references/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`**。

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

@@ -1,9 +1,9 @@
 # Meta（Facebook）账户 — 诊断报告（模板纲要）
 
-> 统计区间：`{startDate}` ~ `{endDate}`  
+> 统计区间：`{startDate}` ~ `{endDate}`
 > 账户：`{mediaCustomerId}`（`{mediaCustomerName}`）
 
-在 **Facebook Ads 现有 7 个 Section** 内，尽量对齐 `google-account-diagnosis-report.md` 的章节结构；无接口的章节保留标题并写 `[ 本媒体接口未提供：{Google 维度名} ]`。
+在 **Facebook Ads 现有 7 个 Section** 内，尽量对齐 `google-account-diagnosis-report.md` 的章节结构；无接口的章节（健康度/系列类型/转化趋势/质量得分）在 JSON 中标注 `notAvailable: true` + `notAvailableReason`。
 
 拉数：**一次** `facebook-analysis`（建议全 7 维或默认 6 维 + 按需 `material`）。
 
@@ -11,64 +11,192 @@
 siluzan-tso facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb-diagnosis
 ```
 
+**默认交付：HTML（`facebook-analysis diagnosis-render` 注入 Agent JSON 生成；禁止手写/拼接 HTML）**。用户指定 Excel 时 Agent 脚本写 xlsx。
+
+---
+
+## 标准四步流程（默认 · 交付 HTML）
+
+| 步骤             | 执行者       | 动作                                                                                                                                                                         |
+| ---------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. 拉数**      | Agent 调 CLI | `facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb-diagnosis`（全 7 维或默认 6 维 + 按需 `material`）                                                     |
+| **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），做洞察与叙事；表格数字可由 `--snapshot-dir` 按 guide 根字段自动映射                                            |
+| **3. 写 JSON**   | Agent        | 撰写 `meta-account-diagnosis-report.json`：仅 `meta.accountId` + `narrative` 为必填；`kpis`/`tables` 可省略，由 `--snapshot-dir` 自动合并                                        |
+| **4. 渲染 HTML** | CLI          | `facebook-analysis diagnosis-render` — **校验 narrative 11 个分析小节必含字段**（4 个媒体未覆盖小节可标 `notAvailable`），缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML |
+
+> `--snapshot-dir` 自动补全 `meta` / `kpis`（仅 overview；**禁止**用 ad-sets/creative 行 results 加总对比 overview）与 `tables.*`（按 `facebook-analysis-guide.md`：`adGroups`/`networks`/`countries`/`audiences`/`creatives`/`materials`）。Agent 已填字段不覆盖。
+
+### JSON 契约（`meta-account-diagnosis-report.json`）
+
+```jsonc
+{
+  "meta": {
+    "accountId": "string（必填）",
+    "accountName": "string",
+    "currency": "string，如 USD/CNY",
+    "startDate": "YYYY-MM-DD",
+    "endDate": "YYYY-MM-DD",
+    "generatedAt": "ISO8601（可省略，render 自动写入）",
+  },
+  "kpis": {
+    "spend": "number",
+    "impressions": "number",
+    "clicks": "number",
+    "results": "number",
+    "ctr": "number（0~1 小数）",
+    "cpc": "number",
+    "costPerResult": "number",
+    "reach": "number",
+    "frequency": "number",
+    "previousPeriod": "同结构可选，用于环比",
+  },
+  "tables": {
+    "platform": "[{ publisherPlatform, platformPosition, spend, results, costPerResult }]",
+    "country": "[{ countryOrRegion, spend, results, costPerResult }]",
+    "audience": "[{ age, gender, spend, results, costPerResult }]",
+    "creative": "[{ creativeName, spend, impressions, clicks, ctr, results, costPerResult }]",
+    "material": "[{ materialName, spend, impressions, results }]（DC 专用，标准账户常为空）",
+  },
+  "narrative": {
+    "executiveSummary": ["string，≥1 段"],
+    "sections": {
+      "accountProfile": { "analysis": ["string，≥1 条"], "suggestions": ["string，≥1 条"] },
+      "coreMetrics": { "analysis": ["…"], "suggestions": ["…"] },
+      "accountStructure": { "analysis": ["…"], "suggestions": ["…"] },
+      "healthGrade": {
+        "notAvailable": true,
+        "notAvailableReason": "gold-account",
+        "_comment": "或改为 { analysis, suggestions } 若有派生数据",
+      },
+      "campaignTypes": { "notAvailable": true, "notAvailableReason": "campaign-types" },
+      "keyComparisons": { "analysis": ["…"], "suggestions": ["…"] },
+      "conversionTrend": { "notAvailable": true, "notAvailableReason": "daily-metrics" },
+      "platformGeoAudience": { "analysis": ["…"], "suggestions": ["…"] },
+      "creative": { "analysis": ["…"], "suggestions": ["…"] },
+      "material": { "analysis": ["…"], "suggestions": ["…"] },
+      "qualityScore": { "notAvailable": true, "notAvailableReason": "ads-index" },
+    },
+    "recommendations": ["string 或 { title, content }，≥3 条"],
+    "excludedChecks": [
+      "string，≥1 条，列出已排除的 Google-only 检查项（如 gold-account/daily-metrics/ads-index）",
+    ],
+  },
+}
+```
+
+> `healthGrade` / `campaignTypes` / `conversionTrend` / `qualityScore` 四节：Meta 无对应 API 时须写 `{ notAvailable: true, notAvailableReason: "<Google 维度名>" }`；若有派生数据（如用 `creativeType` 分布替代系列类型），则正常写 `{ analysis, suggestions }`，二者满足其一即可通过校验。
+
 ---
 
 ## 1. 账户画像
 
-- 账户名：`overview` → `accountName`；`list-accounts -m MetaAd -k <id>` 补 BM/状态（若有）。
-- **无** Google 式落地页 Section → 写 `[ 本媒体接口未提供：final-urls ]`。
+**数据呈现**：账户名：`overview` → `accountName`；`list-accounts -m MetaAd -k <id>` 补 BM/状态（若有）。写入 JSON `meta.accountName`。
+
+- **无** Google 式落地页 Section → 写 `[ 本媒体接口未提供：final-urls ]`
+
+**分析（必写）** → 写入 `narrative.sections.accountProfile.{analysis,suggestions}`：
+
+- **总结**：账户基本信息、投放状态。
+- **建议**：账户结构或设置层面的优化，1～3 条。
 
 ## 2. 核心指标快照
 
+**数据呈现**：本期 vs 上期：消耗、展示、点击、CTR、CPC、转化、CPA、results、costPerResult、reach、frequency。写入 JSON `kpis`（可由 `--snapshot-dir` 自动合并）。
+
 - **CLI**：`overview`
-- 本期 vs 上期：消耗、展示、点击、CTR、CPC、转化、CPA、results、costPerResult、reach、frequency。
+
+**分析（必写）** → 写入 `narrative.sections.coreMetrics.{analysis,suggestions}`：
+
+- **总结**：本期 vs 上期消耗/结果/CPL 变化（仅当 previousPeriod 有数据）；覆盖与频次水平。
+- **建议**：账户级预算或投放节奏（引用具体数字），1～3 条。
 
 ## 3. 账户结构
 
+**数据呈现**：
+
 - **无** `resource-counts` / `conversion-actions` → 用 `ad-sets` + `creative` 行数简述：「共 N 个广告组、M 条在投创意（有 spend/impressions）」。
 - 按 `campaignName` 去重估算系列数（说明为派生，非 API 直出）。
 
+**分析（必写）** → 写入 `narrative.sections.accountStructure.{analysis,suggestions}`：
+
+- **总结**：账户结构规模、集中度。
+- **建议**：结构精简或扩展方向，1～3 条。
+
 ## 4. 健康度 / 黄金账户
 
-- `[ 本媒体接口未提供：gold-account ]`
+- `[ 本媒体接口未提供：gold-account ]` → 写入 `narrative.sections.healthGrade = { notAvailable: true, notAvailableReason: "gold-account" }`
 
 ## 5. 系列类型分布
 
-- `[ 本媒体接口未提供：campaign-types ]`；可用 `creative` 的 `creativeType` 分布作补充。
+- `[ 本媒体接口未提供：campaign-types ]`；可用 `creative` 的 `creativeType` 分布作补充 → 写入 `narrative.sections.campaignTypes`（`notAvailable` 或补充 `analysis/suggestions`）
 
 ## 6. 重点维度对比（本期 vs 上期）
 
-- 总览已含环比；另可对 `ad-sets` / `country` / `platform` 做「本期排行」快照（无上期分维数据时不做分维环比）。
+**数据呈现**：总览已含环比；另可对 `ad-sets` / `country` / `platform` 做「本期排行」快照（无上期分维数据时不做分维环比）。
+
+**分析（必写）** → 写入 `narrative.sections.keyComparisons.{analysis,suggestions}`：
+
+- **总结**：Top 广告组/国家/平台及其效率差异。
+- **建议**：预算或出价调整方向（引用具体 `name` + 数据），1～3 条。
 
 ## 7. 转化成本趋势
 
-- `[ 本媒体接口未提供：daily-metrics ]`；勿用猜测曲线。
+- `[ 本媒体接口未提供：daily-metrics ]`；勿用猜测曲线 → 写入 `narrative.sections.conversionTrend = { notAvailable: true, notAvailableReason: "daily-metrics" }`
 
 ## 8. 平台、地域、受众
 
+**数据呈现**：
+
 - **CLI**：`platform`、`country`、`audience`
-- `platform` → `networks[]`：用 **`publisherPlatform`**（投放平台）+ **`platformPosition`**（版位）；`network` 仅等于 `platformPosition`（兼容旧版，勿当平台列）。
-- 全表或 Top 表；与 Google `devices` / `geographic` / `audience` 对应说明。
+- `platform` → `networks[]`：用 **`publisherPlatform`**（投放平台）+ **`platformPosition`**（版位）；`network` 仅等于 `platformPosition`（兼容旧版，勿当平台列）。写入 JSON `tables.platform[]` / `tables.country[]` / `tables.audience[]`。
+
+**分析（必写）** → 写入 `narrative.sections.platformGeoAudience.{analysis,suggestions}`：
+
+- **总结**：主力平台/国家/受众段及其效率差异；与 Google `devices` / `geographic` / `audience` 对应说明。
+- **建议**：版位/地域/受众定向调整（引用具体值 + 数据），1～3 条。
 
 ## 9. 创意（替代搜索词+搜索广告）
 
+**数据呈现**：Top 创意、低效创意；**无** `search-terms` → `[ 不适用：搜索词 ]`。写入 JSON `tables.creative[]`。
+
 - **CLI**：`creative`
-- Top 创意、低效创意；**无** `search-terms` → `[ 不适用：搜索词 ]`
+
+**分析（必写）** → 写入 `narrative.sections.creative.{analysis,suggestions}`：
+
+- **总结**：Top 消耗创意、CTR/转化表现分化。
+- **建议**：暂停低效创意或复制高效创意方向，1～3 条。
 
 ## 10. 素材
 
-- **CLI**：`material`（DC）；否则指向 `creative`。
+**数据呈现**：写入 JSON `tables.material[]`（DC 专用，标准账户常为空）。
+
+- **CLI**：`material`（DC）；否则指向 `creative`
 - **无** Google `extensions` → `[ 本媒体接口未提供：extensions ]`
 
+**分析（必写）** → 写入 `narrative.sections.material.{analysis,suggestions}`：
+
+- **总结**：素材表现（若为空，说明账户非 DC，改用 §9 创意结论）。
+- **建议**：素材迭代方向，1～3 条。
+
 ## 11. 质量得分
 
-- `[ 本媒体接口未提供：ads-index ]`
+- `[ 本媒体接口未提供：ads-index ]` → 写入 `narrative.sections.qualityScore = { notAvailable: true, notAvailableReason: "ads-index" }`
 
 ## 12. 总结与行动项
 
-- 优先：高消耗低效 Ad Set、版位、国家、人群、创意。
-- 列出已排除的 Google-only 检查项，避免读者以为漏查。
+- 优先：高消耗低效 Ad Set、版位、国家、人群、创意。写入 JSON `narrative.recommendations[]`（≥3 条）。
+- 列出已排除的 Google-only 检查项，避免读者以为漏查。写入 JSON `narrative.excludedChecks[]`（≥1 条，如 `gold-account`、`campaign-types`、`daily-metrics`、`ads-index`）。
 
 ---
 
 字段细则：`references/analytics/facebook-analysis-guide.md`。
+
+### 渲染 HTML
+
+```bash
+siluzan-tso facebook-analysis diagnosis-render --data ./meta-account-diagnosis-report.json --snapshot-dir ./snap-fb-diagnosis --out ./meta-account-diagnosis-report.html
+```
+
+- `--data`：Agent 撰写的诊断报告 JSON（必填）
+- `--snapshot-dir`：可选，`facebook-analysis --json-out` 目录，自动补全 `meta` / `kpis` / `tables.*`
+- `--out`：输出 HTML 路径（默认同 `--data` 目录）

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

@@ -1,38 +1,133 @@
 # TikTok 广告主账户 — 周期分析报告（模板纲要）
 
-> 统计区间：`{startDate}` ~ `{endDate}`  
+> 统计区间：`{startDate}` ~ `{endDate}`
 > 账户：`{mediaCustomerId}`（`{mediaCustomerName}`）
 
-数据块：总览、系列/组/广告、视频素材、受众（含性别/年龄/兴趣合并）、地域与设备（**以 `--json-out` 实际字段为准**）。
+数据块：总览、系列/组/广告、视频素材、受众（含性别/年龄/兴趣合并）（**以 `--json-out` 实际字段为准**）。
+
+**默认交付：HTML（`tiktok-analysis render` 注入 Agent JSON 生成；禁止手写/拼接 HTML）**。用户指定 Excel 时 Agent 脚本写 xlsx。
+
+---
+
+## 标准四步流程（默认 · 交付 HTML）
+
+| 步骤             | 执行者       | 动作                                                                                                                                                                             |
+| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. 拉数**      | Agent 调 CLI | `tiktok-analysis -a <id> --start <s> --end <e> --json-out ./snap-tiktok`（见下方「日期规则」，全 12 维或 `--sections` 指定子集）                                                 |
+| **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），做洞察与叙事；表格数字可由 `--snapshot-dir` 按类型自动映射                                                      |
+| **3. 写 JSON**   | Agent        | 撰写 `tiktok-period-report.json`：仅 `meta.accountId` + `narrative` 为必填；`kpis`/`tables` 可省略，由 `--snapshot-dir` 按网关类型自动合并                                         |
+| **4. 渲染 HTML** | CLI          | `tiktok-analysis render` — **校验 narrative 6 个分析小节必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML                                                           |
+
+> `--snapshot-dir` 自动补全 `meta` / `kpis` / `tables.*`。网关形状见 `src/types/tiktok-analysis-api.ts`（对齐前端 `periodReport/tiktok.js`）：`campaigns` 为 `{ campaigns:[] }`；ad-groups/videos/audience 为 `{ data.list[].metrics }`（snake_case）；ads 为根数组。**本期 KPI 优先 campaigns 累加**。Agent 已填字段不覆盖。
+
+### JSON 契约（`tiktok-period-report.json`）
+
+```jsonc
+{
+  "meta": {
+    "accountId": "string（必填，TikTok mediaCustomerId）",
+    "accountName": "string",
+    "currency": "string，如 CNY/USD",
+    "startDate": "YYYY-MM-DD",
+    "endDate": "YYYY-MM-DD",
+    "generatedAt": "ISO8601（可省略，render 自动写入）",
+  },
+  "kpis": {
+    "spend": "number",
+    "impressions": "number",
+    "clicks": "number",
+    "conversions": "number",
+    "ctr": "number（0~1 小数）",
+    "averageCpc": "number",
+    "costPerConversion": "number",
+    "previousPeriod": "同结构可选，用于环比",
+  },
+  "tables": {
+    "campaigns": "[{ campaignName, status, spend, impressions, clicks, ctr, conversions, costPerConversion }]",
+    "adGroups": "[{ adGroupName, campaignName, spend, clicks, ctr, conversions, costPerConversion }]",
+    "ads": "[{ adName, adGroupName, spend, clicks, ctr, conversions }]",
+    "videos": "[{ videoName, spend, impressions, clicks, ctr, conversions, costPerConversion }]",
+    "audienceGender": "[{ gender, spend, impressions, clicks, ctr }]",
+    "audienceAge": "[{ ageRange, spend, impressions, clicks, ctr }]",
+    "audienceInterest": "[{ interestCategory, spend, impressions, clicks, ctr }]",
+  },
+  "narrative": {
+    "executiveSummary": ["string，≥1 段"],
+    "sections": {
+      "overview": { "analysis": ["string，≥1 条"], "suggestions": ["string，≥1 条"] },
+      "campaigns": { "analysis": ["…"], "suggestions": ["…"] },
+      "adGroups": { "analysis": ["…"], "suggestions": ["…"] },
+      "ads": { "analysis": ["…"], "suggestions": ["…"] },
+      "videos": { "analysis": ["…"], "suggestions": ["…"] },
+      "audience": { "analysis": ["…"], "suggestions": ["…"] },
+    },
+    "recommendations": ["string 或 { title, content }，≥3 条"],
+  },
+}
+```
 
 ---
 
 ## 1. 执行摘要（总览）
 
-- 账户级消耗、展示、点击、转化、CTR、CPC 等（接口返回结构因版本可能略有差异）
+**数据呈现**：账户级消耗、展示、点击、转化、CTR、CPC 等（接口返回结构因版本可能略有差异）。写入 JSON `kpis`（Agent 从 overview 快照映射填写）。
+
 - **CLI**：`siluzan-tso tiktok-analysis -a <mediaCustomerId> --sections overview [--start YYYY-MM-DD --end YYYY-MM-DD] --json-out <dir>`
 
+**分析（必写）** → 写入 `narrative.sections.overview.{analysis,suggestions}`：
+
+- **总结**：本期 vs 上期消耗/点击/转化/CTR/CPC/CPA 变化（若有 previousPeriod 数据）。
+- **建议**：账户级预算或投放节奏（引用具体百分比或金额），1～3 条。
+
 ## 2. 广告结构（系列 / 广告组 / 广告）
 
-- 系列：`--sections campaigns` → `CampaignSectionData`（Query：`startDate`、`endDate`、`take`，默认 `take=100`）
-- 广告组：`--sections ad-groups` → `AdGroupReport`
-- 广告：`--sections ads` → `AdReport`
+**数据呈现**：
+
+- 系列：`--sections campaigns` → `CampaignSectionData`（Query：`startDate`、`endDate`、`take`，默认 `take=100`）。写入 JSON `tables.campaigns[]`。
+- 广告组：`--sections ad-groups` → `AdGroupReport`。写入 JSON `tables.adGroups[]`。
+- 广告：`--sections ads` → `AdReport`。写入 JSON `tables.ads[]`。
+
+**分析（必写，三个子块各写一段，不可合并为一句带过）**：
+
+1. **系列分析 — 总结**：Top 系列及费用占比、暂停/活跃系列效果差异。**建议**：预算增减或暂停具体 `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}`
 
 ## 3. 素材与创意（视频）
 
+**数据呈现**：按消耗排序的视频素材表现（消耗、展示、点击、CTR、转化、CPA）。写入 JSON `tables.videos[]`。
+
 - **CLI**：`siluzan-tso tiktok-analysis -a <id> --sections videos [--start … --end …] [--take N] --json-out <dir>`
 
+**分析（必写）** → 写入 `narrative.sections.videos.{analysis,suggestions}`：
+
+- **总结**：高消耗低转化素材、Top 转化素材的共性（时长/形式/卖点）。
+- **建议**：暂停低效素材、复制高效创意方向，1～3 条。
+
 ## 4. 受众分析
 
+**数据呈现**：
+
 - 单维度：`--sections audience-<dimension>`，可选：`audience-gender` | `audience-age` | `audience-interest-category` | `audience-country-code` | `audience-platform` | `audience-language`
 - 三块合并：`--sections audience-merged`（**固定输出合并 JSON**，含 `gender` / `age` / `interest_category`；别名 `audience`）
 
+写入 JSON `tables.audienceGender[]` / `tables.audienceAge[]` / `tables.audienceInterest[]`。
+
+**分析（必写）** → 写入 `narrative.sections.audience.{analysis,suggestions}`：
+
+- **总结**：主力性别/年龄段/兴趣类目、转化或 CTR 更优的受众段。
+- **建议**：受众定向调整或素材投放方向（引用维度值 + 指标），1～3 条。
+
 ## 5. 地域 / 兴趣辅助数据
 
 - 地区代码枚举：`tiktok-analysis areacode`（解析地域报表、对照名称，非 `--sections` 批跑维度）
 - 兴趣类目树：`tiktok-analysis interest-list -a <id>`（需配置 **`tiktokApiUrl`**）
 
-## 6. 附录
+## 6. 报告收尾（全账户）
+
+在以上各 section 分析之后，须撰写 **「优化建议」**（3～5 条，写入 JSON `narrative.recommendations[]`），跨 section 归纳优先级，**须与前面各 section 分析一致、不得矛盾**。
+
+## 7. 附录
 
 - 日期规则：`--start` / `--end` **同传或同省略**；省略时默认**近 7 天（截至昨天）**，与 `report meta-overview`、`google-analysis` 一致。
 - 鉴权：与 TSO 其他接口相同（`config show` 中 `tsoApiBaseUrl` / Token）。
@@ -55,3 +150,13 @@
 | 受众（性别+年龄+兴趣） | `audience-merged`（别名 `audience`）                                                                                                    |
 | 地区码                 | 子命令 `tiktok-analysis areacode`（非 `--sections`）                                                                                    |
 | 兴趣列表               | 子命令 `tiktok-analysis interest-list -a <id>`（非 `--sections`）                                                                       |
+
+### 渲染 HTML
+
+```bash
+siluzan-tso tiktok-analysis render --data ./tiktok-period-report.json --snapshot-dir ./snap-tiktok --out ./tiktok-period-report.html
+```
+
+- `--data`：Agent 撰写的报告 JSON（必填）
+- `--snapshot-dir`：可选，`tiktok-analysis --json-out` 目录，自动补全 `meta` / `kpis` / `tables.*`
+- `--out`：输出 HTML 路径（默认同 `--data` 目录）