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

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

@@ -0,0 +1,219 @@
+# Meta（Facebook）账户 — 周期分析报告
+
+> 统计区间：`{startDate}` ~ `{endDate}`  
+> 账户：`{mediaCustomerId}`（`{mediaCustomerName}`）
+
+> **默认交付物**：一份可打开的、带 ECharts 图表的 **HTML 文件**（如 `meta-period-report.html`）。  
+> 用户**未指定格式**时一律走下方 **标准四步流程**；**禁止**仅 Markdown 摘要或纯 JSON 充当终稿。  
+> 用户**明确要求 Excel / xlsx** 时，改走 `report-templates/meta-period-report-excel.md` 分支（见文末「Excel 分支」）。
+
+字段口径见 `references/analytics/facebook-analysis-guide.md`。  
+**内容丰富度（必读）**：`assets/meta-period-report-rules.md`（对齐 P8 网站诊断：全量建议 + 字数下限 + 7 维清单）。  
+Agent JSON Schema：`assets/meta-period-report.schema.json`。
+
+---
+
+## 标准四步流程（默认 · 交付 HTML）
+
+| 步骤             | 执行者       | 动作                                                                                                    |
+| ---------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| **1. 拉数**      | Agent 调 CLI | `facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb`                                  |
+| **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），完成筛选、聚合、排序与洞察           |
+| **3. 写 JSON**   | Agent        | 按本纲要撰写 `meta-period-report.json`（`meta` / `narrative` / 可选 HTML 扩展字段）                     |
+| **4. 渲染 HTML** | CLI          | `facebook-analysis render` — **校验 JSON 必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML |
+
+```bash
+# 步骤 1
+siluzan-tso facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb \
+  --sections overview,ad-sets,platform,country,audience
+
+# 步骤 4（步骤 2～3 完成后）
+siluzan-tso facebook-analysis render \
+  --data ./meta-period-report.json \
+  --snapshot-dir ./snap-fb \
+  --out ./meta-period-report.html
+```
+
+`--snapshot-dir` 与步骤 1 的 `--json-out` 同目录；CLI 自动合并 KPI、平台/国家/受众图表与表格（Agent JSON 已有字段不覆盖）。
+
+---
+
+## Excel 分支（仅当用户指定 Excel / xlsx）
+
+用户说「要 Excel」「导出 xlsx」「按业务 Excel 模板」等时：
+
+1. 步骤 1～3 **与 HTML 流程相同**（拉数 → 分析 → 写 `meta-period-report.json`）。
+2. **步骤 4 改为**：Agent 执行 **node/python 脚本**（如 `openpyxl` / `exceljs`）读取快照 JSON + `meta-period-report.json`，按 `meta-period-report-excel.md` 写出 `.xlsx`。
+3. **不要**调用 `facebook-analysis render`（除非用户同时要 HTML + Excel）。
+4. **禁止**假设存在 `siluzan-tso … excel` 子命令。
+
+版式与 5 Sheet 结构见 **`report-templates/meta-period-report-excel.md`**。
+
+---
+
+## 与原业务（TSO / Skill）对齐
+
+| 环节              | 实现                                  |
+| ----------------- | ------------------------------------- |
+| CLI 拉数          | 步骤 1                                |
+| Agent 分析 + 撰写 | 步骤 2～3 → `meta-period-report.json` |
+| **HTML 终稿**     | 步骤 4 → `facebook-analysis render`   |
+| **Excel 终稿**    | 仅用户指定时 → Agent 脚本写 xlsx      |
+
+模板源码：
+
+- `report-templates/meta-period-report.html` — 结构与样式（对齐深度分析月报）
+- `report-templates/meta-period-report.runtime.js` — 可选外链运行时（逻辑已内联于 HTML；ECharts 渲染 + 章节 DOM 拼装）
+
+`render` 会向输出目录写入 HTML + `meta-period-report.runtime.js`，并注入 `window.__META_PERIOD_REPORT__`。  
+传 `--snapshot-dir` 时 CLI 自动从快照合并 KPI、平台/国家/受众图表数据、广告组与受众表格（Agent JSON 中已有字段不覆盖）。
+
+---
+
+## Excel 五 Sheet 与 CLI 维度（默认周期报告）
+
+| #   | Excel Sheet    | 报告章节                                   | CLI `--sections`               | 后端 Section        |
+| --- | -------------- | ------------------------------------------ | ------------------------------ | ------------------- |
+| 1   | **总数据**     | 账户 KPI + 叙事（整体/区域/国家/优化建议） | `overview`                     | OverviewSectionData |
+| 2   | **广告组数据** | 区域组对比表（leads-欧洲/拉美/亚洲）       | `ad-sets`（别名 `campaigns`）  | AdSetSectionData    |
+| 3   | **平台数据**   | Facebook vs Instagram                      | `platform`（别名 `devices`）   | PlatformSectionData |
+| 4   | **国家数据**   | 国家/地区排行                              | `country`（别名 `geographic`） | CountrySectionData  |
+| 5   | **受众数据**   | 年龄 × 性别矩阵                            | `audience`                     | AudienceSectionData |
+
+**Excel 默认不含、按需追加：**
+
+| 章节       | CLI                            | 何时追加               |
+| ---------- | ------------------------------ | ---------------------- |
+| 广告创意   | `creative`（别名 `ads`）       | 用户要创意表或 DC 素材 |
+| 原生素材   | `material`（别名 `materials`） | Dynamic Creative 账户  |
+| _按日趋势_ | —                              | 接口无                 |
+| _关键词_   | —                              | 不适用                 |
+
+与 Google 8 章对照见 `facebook-analysis-guide.md`。
+
+**可选追加（执行拉数前可询问用户）：**
+
+| 维度        | CLI                            | 何时追加                                 |
+| ----------- | ------------------------------ | ---------------------------------------- |
+| DC 原生素材 | `material`（别名 `materials`） | 用户要素材 Tab 或账户为 Dynamic Creative |
+
+---
+
+## 拉数（默认 5 个数据维 = Excel 五 Sheet，一次批拉）
+
+```bash
+mkdir -p ./snap-fb
+siluzan-tso facebook-analysis -a <mediaCustomerId> --start <s> --end <e> --json-out ./snap-fb \
+  --sections overview,ad-sets,platform,country,audience
+```
+
+- 含创意：加 `creative`；全 7 数据维（含 `material`）：省略 `--sections`。
+- 国家 Top 10：同上命令加 `--limit 10`。
+- 账户 ID：数字或 `act_<数字>`；读 `report-manifest-<id>.json` 与各 `<section>-<id>.json`。
+- **勿**用 `report meta-overview` 代替本流程（仅 legacy 单维总览）。
+
+---
+
+## 各章撰写要求（对齐 Excel 总数据 Sheet）
+
+### 1. 整体表现（`narrative.overall`）
+
+- 数据源：`overview-<id>.json` → `currentPeriod`（可选对比 `previousPeriod` 写环比）。
+- **1 段话**必含：花费、**结果**（`results`）、CPL（`costPerResult`）、覆盖、展示、频次。
+- 元信息注明：`resultType`、`attributionSetting`（写入 `meta`）。
+- **勿写** overview 顶层 `totalCost`/`balance`/`optimizationScore`。
+
+### 2. 区域报告（`narrative.regional[]`）
+
+- 数据源：`ad-sets-<id>.json` → `adGroups[]`。
+- **每个广告组 1 段**（如 leads-欧洲 / leads-拉美 / leads-亚洲）：CPL、线索数、覆盖、频次、效率判断。
+- 表格列对齐 Excel：系列名、组名、覆盖、展示、频次、归因、成效类型、成效、花费、单次成效费用。
+
+### 3. 国家报告（`narrative.country`）
+
+- 数据源：`country-<id>.json` → `countries[]`。
+- **1 段话**：最低/最高 CPL 国家、中间梯队；表格按花费或 CPL 排序展示。
+
+### 4. 优化建议（`narrative.recommendations[]` + `supplementaryRecommendations` + `priorityPlan`）
+
+**固定 4 条标题**（`narrative.recommendations[]`，每条 content **≥150 字**，须引用当次 CPL/国家/组名）：
+
+| 标题         | 内容要点                                           |
+| ------------ | -------------------------------------------------- |
+| 简化表单问题 | 结合高频次高 CPL 市场；字段缩减至 3 项；写预期影响 |
+| 区域调整     | 各广告组语言/市场策略（土/葡/德等）；加减仓名单    |
+| 预算重构     | 具体比例（如 4:3:3）、测试周期、CPL 阈值优胜劣汰   |
+| 素材建议     | 分平台/分市场；素材套数、IG 短视频、FB 形态        |
+
+**另须** `supplementaryRecommendations` **7 维**（预算、平台、地域、受众、创意、频次、接口限制）与 `priorityPlan`（高/中/低各 ≥2 条）。细则见 **`assets/meta-period-report-rules.md`**。
+
+### 5. 平台数据（Sheet3 表 + 可选 `sections.platform.insight`）
+
+- 数据源：`platform-<id>.json` → 按 `publisherPlatform` 汇总（Excel 仅平台列）。
+- 版位细拆（`platformPosition`）为 HTML 扩展，Excel 不要求。
+
+### 6. 受众数据（Sheet5 表）
+
+- 数据源：`audiences[]`；`age`、`gender`。
+- 含 `unknown` 性别或零成效行时标注「样本不足」。
+
+### 可选：广告创意 / 原生素材
+
+- 仅当用户追加拉取 `creative` / `material`。
+- **勿**加总各行 `results` 与 overview 对比。
+
+### HTML 深度分析扩展（**默认交付必填**，Excel 不含）
+
+用户未指定 Excel 时，除 `narrative` 外 **必须** 填写（字数见 `meta-period-report-rules.md` §四）：
+
+- `executiveSummary[]`：**3～5 段**「为什么」解读（每段 ≥80 字）
+- `healthDiagnosis`：三阶段 + **4 张四问卡片** + **≥6 行**红绿灯表（③ 该加还是该减；可省略 `scorecard`，render 时由 `--snapshot-dir` 自动补全）
+- `sections.platform/country/adSets.insight`：各 **≥200 字**
+- `sections.audience`：`goldenProfile` ≥3 条 + `antiProfile` ≥2 条
+- `sections.landingPage.rows`：≥3 行
+- `abTests`：≥3 个实验；`actionChecklist`：today/thisWeek/thisMonth 非空
+
+---
+
+## 口径速记
+
+| 展示           | 字段                                |
+| -------------- | ----------------------------------- |
+| Meta「结果」   | `results`                           |
+| 单次成效费用   | `costPerResult`                     |
+| 业务转化 / CPA | `conversions` / `costPerConversion` |
+| CTR            | `ctr` × 100 → %                     |
+
+---
+
+## Agent JSON 结构（`meta-period-report.json`）
+
+完整 Schema：`assets/meta-period-report.schema.json`。Excel 必含字段：
+
+| 字段                               | 必填           | 说明                                                            |
+| ---------------------------------- | -------------- | --------------------------------------------------------------- |
+| `meta`                             | 推荐           | 账户名、周期、`resultType`、`attributionSetting`、`generatedAt` |
+| `kpis`                             | 可省略         | 账户 KPI 行；由 `--snapshot-dir` 从 `overview` 合并             |
+| **`narrative.overall`**            | **Excel 必含** | 整体表现 1 段                                                   |
+| **`narrative.regional[]`**         | **Excel 必含** | `{ adGroupName, text }` 区域报告                                |
+| **`narrative.country`**            | **Excel 必含** | 国家对比 1 段                                                   |
+| **`narrative.recommendations[]`**  | **必含**       | 固定 4 条，每条 ≥150 字                                         |
+| **`supplementaryRecommendations`** | **必含**       | 7 维数据驱动建议                                                |
+| **`priorityPlan`**                 | **推荐**       | 高/中/低各 ≥2 条；HTML 强烈建议填写                             |
+| `tables` / `charts`                | 可省略         | Sheet2～5；由快照自动汇总                                       |
+| `executiveSummary`                 | **HTML 必填**  | 3～5 段深度摘要                                                 |
+| `healthDiagnosis`                  | **HTML 必填**  | 四问 + 红绿灯表（`scorecard` 可由 CLI 从快照自动补全）          |
+| `sections.*.insight`               | **HTML 必填**  | 各维度 ≥200 字                                                  |
+| `abTests` / `actionChecklist`      | **HTML 必填**  | ≥3 实验 + 三列行动清单                                          |
+
+---
+
+## 相关文档
+
+| 文档                                                | 用途                                                |
+| --------------------------------------------------- | --------------------------------------------------- |
+| **`report-templates/meta-period-report-excel.md`**  | **Excel 五 Sheet 规格（业务模板基准）**             |
+| `assets/meta-period-report.schema.json`             | Agent JSON Schema                                   |
+| `references/analytics/facebook-analysis-guide.md`   | 字段、Google 对照、建议清单                         |
+| `report-templates/meta-account-diagnosis-report.md` | 深度诊断（在可用 Section 内尽量对齐 Google 诊断章） |
+| `report-templates/REPORT-WORKFLOW.md`               | 通用六步流程                                        |

package/dist/skill/references/report-templates/okki-weekly-google-client.md

@@ -0,0 +1,217 @@
+# OKKI 周报 · Google 客户同步（运营模板）
+
+> **触发话术（等价即可）**  
+> `使用okki周报模板生成<账户名或ID>，<YYYY-MM-DD>--<YYYY-MM-DD>的投放报告`  
+> 同义：`OKKI 周报`、`okki 周报模板`、`运营 OKKI 周报`。  
+> **媒体**：当前模板仅规范 **Google**（`mediaCustomerId`）。其他媒体用各自 `*-period-report.md`。  
+> **Excel 版式基准**：与运营样表《**数据复盘分析**》类 xlsx 对齐（如 `2025.12数据复盘分析.xlsx`）；工作簿 5 个 Sheet、顺序与表头以下文规范为准。
+
+识别到上述意图时：**不要**再走 `google-period-report.md` 的「默认 8 维 + 追问追加」流程；按本文**固定维度 + 固定客户话术**交付（数据全部来自 CLI 落盘 JSON，见 `references/analytics/account-analytics.md`）。
+
+---
+
+## 须先确认
+
+1. **账户**：`mediaCustomerId` 来自 `list-accounts -m Google -k <id>`，禁止猜 ID。
+2. **统计区间**：`--start` / `--end`（用户未给齐时按 SKILL 反问；授权默认时可用「上一完整自然周」白名单并写明）。
+3. **询盘口径**：默认使用区间内 `conversions`（转化次数，来自 `stats` 或 `overview`）。若运营定义为某类转化，须在首段脚注说明（必要时补拉 `google-analysis --sections conversion-actions` 仅作说明）。
+4. **日期写法**：`2026.4.1`、`2026/4/1` 等先规范为 `YYYY-MM-DD`（如 `2026-04-01`）再传 `--start` / `--end`。
+
+---
+
+## 架构约定 · Excel 由谁生成
+
+- **`siluzan-tso` 不提供**「一键生成 OKKI Excel」的子命令，**也不要**在 CLI 里新增。
+- 需交付 Excel 时：由 **Agent（含 WorkBuddy 编排）** 在下列 CLI **`--json-out` 落盘后**，自行编写 **Node.js / Python** 脚本（如 `exceljs`、`xlsx`、`openpyxl`）读取 JSON → 写 `.xlsx`。
+- **数值一律来自落盘 JSON，禁止在脚本里写死业务数字。**
+
+---
+
+## 拉数（一次目录）
+
+同一目录落盘（示例 `./snap-okki`）：
+
+```bash
+mkdir -p ./snap-okki
+
+siluzan-tso list-accounts -m Google -k <mediaCustomerId> --json-out ./snap-okki
+
+siluzan-tso stats -m Google -a <mediaCustomerId> --start <S> --end <E> --json-out ./snap-okki
+
+siluzan-tso balance -m Google -a <mediaCustomerId> --json-out ./snap-okki
+
+siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-out ./snap-okki \
+  --sections overview,campaigns,keywords,search-terms,campaign-device,campaign-geo-matched
+```
+
+**说明**：
+
+- `stats`：区间消耗 / 曝光 / 点击 / 转化 / CTR / CPC，与账户级周报摘要对齐；金额用 `*Display` 或文档规定的展示字段。
+- `balance`：**当前**余额（非历史快照），话术写「截至查询时点」。
+- 「设备」「国家」两 Sheet **必须**用 **`campaign-device` / `campaign-geo-matched`**（按系列/组拆行），**不要**用账户级 `devices` / `geographic`，也**不要**用 `campaign-geo`（定向地理位置，与 OKKI「地理位置报告」口径不一致）。落盘文件名为 `campaign-device-<id>.json`、`campaign-geo-matched-<id>.json`。跨系列汇总在脚本中做。
+- 可选：`campaign-geo-matched` 支持 `--cost-greater` / `--click-greater` / `--conversions-greater`（见 `references/analytics/account-analytics.md`）。
+- TopN、排序、汇总均在脚本内对 JSON 完成，禁止心算。
+- 写脚本前先读各 `<section>-<id>.outline.txt` 再读 `.json`。
+
+---
+
+## xlsx 版式规范
+
+工作簿 → Sheet 名（须完全一致）→ 版式。**不**单独建「广告系列」Sheet（系列表在 `账户报告` 内）。状态枚举若为英文须转中文。
+
+### 数值格式（强约束）
+
+- **所有数值列一律保留 2 位小数**：金额、CPC、每次转化费用、预算、点击率、转化率、互动率等。
+- 客户话术 / 文案中的 `x%`：`(v * 100).toFixed(2) + "%"`。
+
+### 点击率 / 转化率 / 互动率
+
+> **2026-05 起 CLI 已统一归一**（manifest `schemaVersion ≥ 2`）：所有 `<section>-*.json` 中的 `ctr` / `conversionRate` 一律为 **0~1 小数**（如 `0.10` = 10.00%）。`schemaVersion 3` 起行数据统一在 `items[]`、汇总在 `record`。详见 `references/analytics/account-analytics.md`「指标字段对照」「落盘 JSON 统一信封」。
+
+| 场景                                              | 处理                                                                       |
+| ------------------------------------------------- | -------------------------------------------------------------------------- |
+| 写入 Excel **0~1 小数列**（点击率/转化率/互动率） | 直接写入 JSON 数值（**禁止**再 ÷100）                                      |
+| 写客户话术 / 文案的 `x%`                          | `(v * 100).toFixed(2) + "%"`                                               |
+| `interactionRate`（字符串）                       | `parseFloat(row.interactionRate)` 后按数值字段使用（同样 0~1 小数）        |
+| `interactions === 0` / `null`                     | **平均费用**（`spend / interactions`）与 **互动率** 列填 **`—`**，禁止除零 |
+
+### 工作簿级
+
+| 顺序 | Sheet 名   | 数据来源                                                                             |
+| ---: | ---------- | ------------------------------------------------------------------------------------ |
+|    1 | `账户报告` | `campaigns` + 复盘文案（stats/overview 汇总后 Agent 撰写）                           |
+|    2 | `关键词`   | `keywords`                                                                           |
+|    3 | `搜索词`   | `search-terms`                                                                       |
+|    4 | `设备`     | **`campaign-device-*.json`**（按系列/组拆行）                                        |
+|    5 | `国家`     | **`campaign-geo-matched-*.json`**（相符地理位置 Matched locations，按系列/地域拆行） |
+
+### 各 Sheet 共同版式
+
+- **R1（A1）**：报告标题（见各 Sheet 表）；建议合并单元格横跨该 Sheet R3 表头全部列。
+- **R2（A2）**：统计区间，中文可读：`YYYY年M月D日 - YYYY年M月D日`。
+- **R3**：表头（列名、顺序须与下表一致）。
+- **R4 起**：数据行；列宽、自动筛选、首行冻结、降序排序为可选，**不得**因此改数。
+- **百分比列**：样表为 0~1 小数（如 7.95% 存 `0.08`）；与运营约定二选一，**禁止**同一文件混用。
+- **金额**：与 `references/analytics/account-analytics.md` 一致；`campaigns.budgetAmountYuan`、`spend`、`averageCpc`、`costPerConversion` 均为元，可直接写入。
+
+---
+
+### Sheet `账户报告`
+
+| 行               | 内容                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `广告系列报告`（如运营改名，可改文案但 Sheet 名仍为 `账户报告`）                                                                                                                                                                                                                                                                                                                                                |
+| R2               | 统计区间                                                                                                                                                                                                                                                                                                                                                                                                        |
+| R3（A→K，11 列） | `广告系列` \| `预算` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率`                                                                                                                                                                                                                                                      |
+| R4…              | 来自 `campaigns-*.json` 的 `items[]`（`schemaVersion 3` 行统一在 `items`）：`campaignName`、`budgetAmountYuan`（元）、`spend`、`impressions`、`clicks`、`ctr`（已归一直接写入「点击率」）、`averageCpc`、`allConversions`→「所有转化次数」、`conversions`→「转化次数」、`costPerConversion`、`conversionRate`（已归一直接写入「转化率」）；缺 `allConversions` 时与「转化次数」同值或填 `0` / `—`，并在脚注说明 |
+| 末行「合计」     | **广告系列**列填 `总计`；**预算**列填 `--`；**展示 / 点击 / 所有转化次数 / 转化次数 / 费用** 做列求和；**点击率** = 合计点击 ÷ 合计展示；**转化率** = 合计转化 ÷ 合计点击（**禁止**用合计转化 ÷ 合计展示）；**每次转化费用** = 合计费用 ÷ 合计转化（转化为 0 时填 `—`）；禁止对各行比率取算术平均                                                                                                               |
+
+表下**留白若干行**后写 **「数据复盘」**：
+
+- 首行标题：`{结束日所在月份}月份数据复盘：`（例：`12月份数据复盘：`）。
+- 5 条结构化要点：
+  1. **账户层级**：整体消耗、展示、点击、点击率与 3% 基准对比、询盘/转化数、平均询盘成本（数据来自 stats/overview 与上表合计）。
+     总结：
+     建议：
+  2. **关键词层级**：高转化词、高消耗低转化词、出价/竞争力建议。
+     总结：
+     建议：
+  3. **搜索字词层级**：标红/高意向词、否词与加词建议。
+     总结：
+     建议：
+  4. **设备层级**（基于 `campaign-device`）：各设备在系列上的消耗/转化分布；可点出高消耗系列×设备组合。
+     总结：
+     建议：
+  5. **国家层级**（基于 `campaign-geo-matched`）：各国家/地区在系列上的消耗/转化；高消耗低转化地域与降权/调价建议。
+     总结：
+     建议：
+
+文案由 Agent 据 JSON 撰写，**不得编造**表中不存在的数字。
+
+---
+
+### Sheet `关键词`
+
+| 行               | 内容                                                                                                                                                                 |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `搜索关键字报告`                                                                                                                                                     |
+| R2               | 统计区间                                                                                                                                                             |
+| R3（A→L，12 列） | `关键字` \| `匹配类型` \| `广告系列` \| `广告组` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
+| R4…              | `keywords-*.json`：`keywordMatchType`→匹配类型；`campaignName` / `adGroupName` 等按 outline；`ctr` / `conversionRate` 已归一，直接写入                               |
+
+---
+
+### Sheet `搜索词`
+
+| 行               | 内容                                                                                                                                                                                                        |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `搜索字词报告`                                                                                                                                                                                              |
+| R2               | 统计区间                                                                                                                                                                                                    |
+| R3（A→N，14 列） | `搜索字词` \| `匹配类型` \| `已添加/已排除` \| `广告系列` \| `广告组` \| `关键字` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率`       |
+| R4…              | `search-terms-*.json`：`queryTargetingStatusZh`（`Added`→已添加、`Excluded`→已排除、`None`→都没有）；无该字段时读 `queryTargetingStatus` 按上表映射，仍无则「—」；`ctr` / `conversionRate` 已归一，直接写入 |
+
+---
+
+### Sheet `设备`
+
+| 行               | 内容                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `设备报告`                                                                                                                                                                                                                                                                                                                                                            |
+| R2               | 统计区间                                                                                                                                                                                                                                                                                                                                                              |
+| R3（A→M，13 列） | `设备` \| `级别` \| `广告系列` \| `出价调整` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率`                                                                                                                                                                                    |
+| R4…              | `campaign-device-*.json`（`devices[]`）：`deviceType`→设备；`campaignName` / `adGroupName`→「广告系列」等；`allConversions`→「所有转化次数」；`conversions`→「转化次数」；`ctr` / `conversionRate` 直接写入；**出价调整**：bidModifier （0.5 表示 > 降低50%， 1.1表示提高10%，在表格中分别为-50%，+10%）；**级别**列按运营约定（如填 `广告系列` 或 `账户`，全文一致） |
+
+---
+
+### Sheet `国家`
+
+| 行               | 内容                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R1               | `地理位置报告`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| R2               | 统计区间                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| R3（A→M，13 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率`                                                                                                                                                                                                                                                                                                                      |
+| R4…              | `campaign-geo-matched-*.json` 的 `items[]`（`schemaVersion 3` 行统一在 `items`）：`countryOrRegion`→地理位置；`campaignName`→「广告系列」；`allConversions`→「所有转化次数」；`conversions`→「转化次数」；**互动次数**→`interactions`；**互动率**→`interactionRate`（字符串须解析）或 `interactions/impressions`，`interactions` 为 0 时填 `—`；**平均费用 必须** = `spend / interactions`，`interactions` 为 0 / null / undefined 时填 `—`；`ctr` / `conversionRate` 直接写入；其余列按 outline 映射 |
+
+---
+
+## 对外客户话术（固定结构，填数来自 JSON）
+
+首行：`统计区间：<S> ~ <E>（货币：<币种>）`
+
+正文模板：
+
+```
+您好，同步一下谷歌<S>--<E>的投放数据：
+
+1. 消耗：共消耗<金额+币种>，平均每天消耗<金额+币种>
+2. 展示点击：带来<曝光>次曝光，<点击>个点击；
+3. 搜索点击率 <CTR%>，<高于/低于/处于>正常水平（3%以上为正常）
+4. CPC：<金额+币种>
+5. 核心消费关键词：<列 Top5~10，词 + 消耗，可一句概括>
+6. 核心消费地区：<列 Top5~10 国家/地区 + 消耗占比或消耗，可一句概括>
+7. 询盘：<N>个<若口径为 conversions 则括号注明「转化次数」>
+8. 账户余额：<金额+币种>（截至查询时点）
+```
+
+- **第 1 条「平均每天」**：`区间总消耗 / 区间日历天数`（含起止日），脚本计算，禁止手填。
+- **第 3 条**：CLI 返回的若是账户整体 CTR，写「整体点击率」而非「搜索点击率」；可区分时再写「搜索点击率」。`overview-*.json`（汇总维度，`schemaVersion 3` 起整块在 `record`）的 `record.ctr` 已是 0~1 小数（如 `0.10`），话术 `x%` 用 `(ctr * 100).toFixed(2) + "%"`，**禁止**直接打印数值得到 "0.10%"。
+- **所有金额、百分比** 一律 **2 位小数**。
+
+---
+
+## 复盘小结 + 优化建议（对内 / 邮件末段）
+
+基于同一批 JSON（`campaigns`、`keywords`、`search-terms`、`campaign-device`、`campaign-geo-matched`、`overview`）：
+
+- **复盘**：3~6 条 bullet：消耗集中度、高消耗系列/词、地域与设备差异、CTR/CPC 相对水平。
+- **优化建议**：3~5 条可执行项（预算、否词、落地页、系列状态等），**不额外拉数**；缺数据则标 `[数据不可用：原因]`。
+
+---
+
+## 与 `google-period-report.md` 的差异
+
+| 项       | `google-period-report.md` | 本文 OKKI 周报                                                                                                 |
+| -------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| 默认维度 | 8 维 + 主动追问追加       | **固定** `overview,campaigns,keywords,search-terms,campaign-device,campaign-geo-matched` + `stats` + `balance` |
+| 输出形态 | 长文分析报告              | **固定话术** + 短复盘 + **多 Sheet Excel（Agent 脚本写）**                                                     |
+| 典型用户 | 内部分析                  | **发客户**的同步简报                                                                                           |

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

@@ -0,0 +1,56 @@
+# TikTok 广告主账户 — 周期分析报告（模板纲要）
+
+> 统计区间：`{startDate}` ~ `{endDate}`  
+> 账户：`{mediaCustomerId}`（`{mediaCustomerName}`）
+
+数据块：总览、系列/组/广告、视频素材、受众（含性别/年龄/兴趣合并）、地域与设备（**以 `--json-out` 实际字段为准**）。
+
+---
+
+## 1. 执行摘要（总览）
+
+- 账户级消耗、展示、点击、转化、CTR、CPC 等（接口返回结构因版本可能略有差异）
+- **CLI**：`siluzan-tso report tiktok-overview -a <mediaCustomerId> [--start YYYY-MM-DD --end YYYY-MM-DD] --json-out <dir>`
+
+## 2. 广告结构（系列 / 广告组 / 广告）
+
+- 系列：`report tiktok-campaigns` → `CampaignSectionData`（Query：`startDate`、`endDate`、`take`，默认 `take=100`）
+- 广告组：`report tiktok-ad-groups` → `AdGroupReport`
+- 广告：`report tiktok-ads` → `AdReport`
+
+## 3. 素材与创意（视频）
+
+- **CLI**：`siluzan-tso report tiktok-videos -a <id> [--start … --end …] [--take N] --json-out <dir>`
+
+## 4. 受众分析
+
+- 单维度：`report tiktok-audience -a <id> -d <dimension> [--take N] --json-out <dir>`  
+  可选 `dimension`：`gender` | `age` | `interest_category` | `country_code` | `platform` | `language`
+- 三块合并：`report tiktok-audience-merged`（**固定输出合并 JSON**，含 `gender` / `age` / `interest_category`）
+
+## 5. 地域 / 兴趣辅助数据
+
+- 地区代码枚举：`report tiktok-areacode`（解析地域报表、对照名称）
+- 兴趣类目树：`report tiktok-interest-list -a <id>`（需配置 **`tiktokApiUrl`**）
+
+## 6. 附录
+
+- 日期规则：`--start` / `--end` **同传或同省略**；省略时默认**近 7 天（截至昨天）**，与 `report meta-overview`、`google-analysis` 一致。
+- 鉴权：与 TSO 其他接口相同（`config show` 中 `tsoApiBaseUrl` / Token）。
+- 与 steward「优化报告」区别：见 `meta-period-report.md` 末节说明；`report list/create` 为成品报告流，本模板对应**实时分析 JSON**。
+
+---
+
+### CLI 速查表
+
+| 数据块                 | 子命令                          |
+| ---------------------- | ------------------------------- |
+| 总览                   | `report tiktok-overview`        |
+| 系列                   | `report tiktok-campaigns`       |
+| 广告组                 | `report tiktok-ad-groups`       |
+| 广告                   | `report tiktok-ads`             |
+| 视频素材               | `report tiktok-videos`          |
+| 受众（单维）           | `report tiktok-audience -d …`   |
+| 受众（性别+年龄+兴趣） | `report tiktok-audience-merged` |
+| 地区码                 | `report tiktok-areacode`        |
+| 兴趣列表               | `report tiktok-interest-list`   |

package/dist/skill/references/report-templates/website-diagnosis-report.md

@@ -0,0 +1,79 @@
+# 网站诊断报告
+
+> **最终交付物：一份可打开的、带图表的 HTML 文件**（如 `website-diagnosis-report.html`），不是仅 Markdown 摘要。须含：综合得分环、模块雷达图、风险/模块条形图、Lighthouse 对比图（有数据时）。  
+> 数据：`website-diagnosis collect` 落盘 JSON + Agent 按 `assets/website-diagnosis-rules.md` 生成的诊断 JSON
+
+---
+
+**siluzan-tso Skill / 纯 CLI 场景**：**Agent 只负责产出诊断 JSON**；终稿 HTML **必须**由 CLI 的 `render` 命令读取该 JSON 生成。**严禁** Agent 现场手写、拼接、或直接输出 HTML 作为交付物。
+
+必须严格按以下三步顺序执行，**不得跳过任何一步**：
+
+1. **采集原料**（拿到 Lighthouse + 首页 HTML，落盘 JSON）：
+
+```bash
+siluzan-tso website-diagnosis collect --url <网站URL> --json-out ./out
+```
+
+2. **生成诊断 JSON**：Agent 依据上一步原料 + `assets/website-diagnosis-rules.md` 规则，产出 **诊断结果 JSON**（落盘为 `./out/diagnosis.json`，结构见下文「数据字段速查」）。**此步只能输出 JSON，不能输出 HTML。**
+
+3. **用 JSON 调用 render 生成 HTML**（唯一允许产出 HTML 的方式）：
+
+```bash
+siluzan-tso website-diagnosis render --data ./out/diagnosis.json [--collect ./out/collect.json] --out ./website-diagnosis-report.html
+```
+
+> 口诀：**没有诊断 JSON，就不能 render；不经过 render，就没有 HTML 交付物。**
+
+模板源码：
+
+- `report-templates/website-diagnosis-report.html` — 结构与样式
+  `render` 会向输出目录写入 HTML + runtime.js，并注入 `window.__WEBSITE_DIAGNOSIS__`。
+
+---
+
+## HTML 章节清单（须全部出现）
+
+| 区块 ID / 组件   | 内容                                                                   |
+| ---------------- | ---------------------------------------------------------------------- |
+| `ReportHeader`   | 标题「网站诊断报告」、URL、`analyzedAt`、综合得分与等级色              |
+| `HealthOverview` | 总分、行业对比文案、`ratingId` 说明、**ECharts 雷达图** + 得分环       |
+| `RiskMap`        | `coreIssuesIds` 列表 + **模块得分横向条形图**（对齐前端 RiskMap）      |
+| `ModuleDetail`   | 6 模块 × 子项：得分、status、issue、suggestion（表格或卡片）           |
+| `PriorityPlan`   | 高/中/低优先级改进计划（来自核心问题 + 低分子项）                      |
+| `LoadingSpeed`   | **Lighthouse 柱状对比图** + desktop/mobile 指标表；缺失时 callout 说明 |
+| `LongtermValue`  | 投放建议、长期优化价值（与 s1–s5 评级一致）                            |
+
+生成前可对 JSON 做与前端相同的聚合逻辑：各模块 `score` = 子项得分之和
+
+---
+
+## 样式与文件约定
+
+- 单文件 HTML，`lang` 与用户语言一致（默认 `zh-CN`）。
+- ECharts 统一引用：`https://staticpn.siluzan.com/assets/slz/homeCDN/echarts.js`（与 `report-template.html` 相同）。
+- 落盘建议与 `--json-out` 同目录：`website-diagnosis-report.html`。
+- **唯一生成方式**：先产出诊断 JSON，再 `siluzan-tso website-diagnosis render --data <diagnosis.json> [--collect <collect.json>]`（详见顶部「强制流程」）。
+- **禁止**只交付 Markdown 或纯 JSON 当作最终报告（JSON 仅为 render 的输入/中间产物）。
+- **禁止**绕过 render 直接手写或拼接 HTML。
+
+---
+
+## 数据字段速查
+
+| 字段                              | HTML 中的用法                                      |
+| --------------------------------- | -------------------------------------------------- |
+| `url`                             | 报告头、页脚                                       |
+| `analyzedAt`                      | 诊断时间                                           |
+| `ratingId`                        | 等级徽章（s1–s5 → 优秀…不建议投放）                |
+| `score`                           | 总分（可由 modules 汇总）                          |
+| `coreIssuesIds`                   | RiskMap / 优先改进                                 |
+| `modules[].id`                    | m1–m6 分节标题                                     |
+| `modules[].items[]`               | 子项行：诊断项名、得分/满分、issue、suggestion     |
+| `lighthouse` / `lighthouseResult` | LoadingSpeed 节（collect payload 为 `lighthouse`） |
+
+---
+
+## 可选附录（非必须单独成章）
+
+- 与 Google 账户衔接：引导 `google-analysis` / 广告诊断页（勿混淆两种「诊断」）。

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

@@ -9,24 +9,26 @@
 
 > 冲突时以 `*.md` 的内容要求为准，样式文件仅影响排版。
 
+**图表库（全部 HTML 模板统一）**：ECharts 5 — `https://staticpn.siluzan.com/assets/slz/homeCDN/echarts.js`；初始化用 `echarts.init(el).setOption(...)`。勿使用 Chart.js。
+
 ---
 
 ## 内容纲要文件
 
-| 文件                                 | 适用场景                                                                                                       |
-| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| `google-period-report.md`            | Google 账户分析报告（周期/月度/诊断均用此模板）                                                                |
-| `google-period-report-excel.md`      | **仅用户要 Excel 时**（P4 定制 Sheet）：先 `*.outline.txt` 后脚本写 xlsx；账户须 `-k` 核验，无 CLI excel 子命令 |
-| `google-account-diagnosis-report.md` | Google 账户深度诊断（健康度/转化/结构等）                                                                      |
-| `google-ads-diagnosis.md`            | Google **广告诊断**完整纲要（HTML 区块、**每日趋势 2 位小数**、**每模块必填分析/建议**）                      |
-| `meta-period-report.md` / `.html`    | **Meta（Facebook）周期报告（默认）**：四步流程 → `facebook-analysis render` 出 HTML，见 P4-FB |
-| `meta-period-report-excel.md`        | **仅用户要 Excel 时**：5 Sheet xlsx 版式；Agent 脚本写表，无 CLI excel 子命令 |
-| `meta-account-diagnosis-report.md`   | Meta（Facebook）诊断报告（在 7 Section 内对齐 Google 诊断结构）                                                |
-| `tiktok-period-report.md`            | TikTok 广告主周期报告                                                                                          |
-| `bing-period-report.md`              | Bing（BingV2）分析报告                                                                                         |
-| `okki-weekly-google-client.md`       | **OKKI 周报**：Google 发客户固定话术 + 精简维度 CLI；**Excel 仅 Agent 脚本**，见 `references/core/playbooks.md` P6 |
-| `google-inquiry-analysis.md`         | **Google 询盘分析**：严格 3 个月 + 用户询盘 + 8 Sheet xlsx，见 `references/core/playbooks.md` P7 |
-| `website-diagnosis-report.md` / `.html` | **网站诊断**：终稿为 **HTML**（对齐 TSO `WebsiteAnalysisReport/v3`）；配合 `website-diagnosis collect`，见 P8 |
+| 文件                                    | 适用场景                                                                                                           |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `google-period-report.md`               | Google 账户分析报告（周期/月度/诊断均用此模板）                                                                    |
+| `google-period-report-excel.md`         | **仅用户要 Excel 时**（P4 定制 Sheet）：先 `*.outline.txt` 后脚本写 xlsx；账户须 `-k` 核验，无 CLI excel 子命令    |
+| `google-account-diagnosis-report.md`    | Google 账户深度诊断（健康度/转化/结构等）                                                                          |
+| `google-ads-diagnosis.md`               | Google **广告诊断**完整纲要（HTML 区块、**每日趋势 2 位小数**、**每模块必填分析/建议**）                           |
+| `meta-period-report.md` / `.html`       | **Meta（Facebook）周期报告（默认）**：四步流程 → `facebook-analysis render` 出 HTML，见 P4-FB                      |
+| `meta-period-report-excel.md`           | **仅用户要 Excel 时**：5 Sheet xlsx 版式；Agent 脚本写表，无 CLI excel 子命令                                      |
+| `meta-account-diagnosis-report.md`      | Meta（Facebook）诊断报告（在 7 Section 内对齐 Google 诊断结构）                                                    |
+| `tiktok-period-report.md`               | TikTok 广告主周期报告                                                                                              |
+| `bing-period-report.md`                 | Bing（BingV2）分析报告                                                                                             |
+| `okki-weekly-google-client.md`          | **OKKI 周报**：Google 发客户固定话术 + 精简维度 CLI；**Excel 仅 Agent 脚本**，见 `references/core/playbooks.md` P6 |
+| `google-inquiry-analysis.md`            | **Google 询盘分析**：严格 3 个月 + 用户询盘 + 8 Sheet xlsx，见 `references/core/playbooks.md` P7                   |
+| `website-diagnosis-report.md` / `.html` | **网站诊断**：终稿为 **HTML**（对齐 TSO `WebsiteAnalysisReport/v3`）；配合 `website-diagnosis collect`，见 P8      |
 
 ---