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

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

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

package/dist/skill/scripts/install.ps1

@@ -9,11 +9,11 @@ $ErrorActionPreference = 'Stop'
 # -- Package info (injected at build time) ------------------------------------
 $PKG_NAME    = 'siluzan-tso-cli'
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-$PKG_VERSION = '1.1.52'
+$PKG_VERSION = '1.1.53-beta.2'
 $CLI_BIN     = 'siluzan-tso'
 $SKILL_LABEL = 'Siluzan TSO'
-$INSTALL_CMD = 'npm install -g siluzan-tso-cli'
-$WEB_BASE    = 'https://www.siluzan.com'
+$INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'
+$WEB_BASE    = 'https://www-ci.siluzan.com'
 
 # -- Constants ----------------------------------------------------------------
 $NODE_MAJOR_MIN    = 18

package/dist/skill/scripts/install.sh

@@ -9,11 +9,11 @@ set -euo pipefail
 # -- Package info (injected at build time) ------------------------------------
 readonly PKG_NAME="siluzan-tso-cli"
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-readonly PKG_VERSION="1.1.52"
+readonly PKG_VERSION="1.1.53-beta.2"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
-readonly INSTALL_CMD="npm install -g siluzan-tso-cli"
-readonly WEB_BASE="https://www.siluzan.com"
+readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"
+readonly WEB_BASE="https://www-ci.siluzan.com"
 
 # -- Constants ----------------------------------------------------------------
 readonly NODE_MAJOR_MIN=18

package/eval/cases/ir-p10-dazu-client-not-p4.scenario.json

@@ -0,0 +1,27 @@
+{
+  "id": "ir-p10-dazu-client-not-p4",
+  "description": "大族模板 Q3 汇总 & Q4 规划客户版 — P10",
+  "turns": [
+    "按大族模板给 Google 账户 {{EVAL_ACCOUNT_READ}} 生成一份 Google Ads Q3 汇总 & Q4 规划客户版报告，按 SKILL 做。"
+  ],
+  "judgeExpectation": "路径：大族模板 / 客户版 / Q3 汇总 & Q4 规划 → P10 google-quarterly，不是 P4 周期表，不是 P9。\n输出：collect → 写 narrative → render；不做行业数据。",
+  "skillMapping": "references/core/intent-routing.md · P10 vs P4",
+  "judgeReferencePaths": [
+    "references/core/intent-routing.md",
+    "references/core/playbooks.md",
+    "report-templates/google-quarterly-report.md"
+  ],
+  "commandMustInclude": [
+    [
+      "google-quarterly"
+    ]
+  ],
+  "commandMustNotInclude": [
+    [
+      "google-ads-diagnosis"
+    ],
+    [
+      "market-analysis"
+    ]
+  ]
+}

package/eval/cases/ir-p10-monthly-plan-not-p4.scenario.json

@@ -0,0 +1,27 @@
+{
+  "id": "ir-p10-monthly-plan-not-p4",
+  "description": "谷歌广告月度报告+下月规划 — P10，不是 P4",
+  "turns": [
+    "帮我给 Google 账户 {{EVAL_ACCOUNT_READ}} 出一份谷歌广告月度报告，含效率、区域询盘、国家明细和 下月规划。按 SKILL 做。"
+  ],
+  "judgeExpectation": "路径：月度报告且含效率/区域询盘/国家明细/下月规划 → P10 google-quarterly，不是「只要花费转化」的 P4。\n输出：collect 区间用该月或上一完整月；再写 narrative → render。",
+  "skillMapping": "references/core/intent-routing.md · P10 vs P4",
+  "judgeReferencePaths": [
+    "references/core/intent-routing.md",
+    "references/core/playbooks.md",
+    "report-templates/google-quarterly-report.md"
+  ],
+  "commandMustInclude": [
+    [
+      "google-quarterly"
+    ]
+  ],
+  "commandMustNotInclude": [
+    [
+      "google-ads-diagnosis"
+    ],
+    [
+      "market-analysis"
+    ]
+  ]
+}

package/eval/cases/ir-p10-quarterly-client-report.scenario.json

@@ -0,0 +1,27 @@
+{
+  "id": "ir-p10-quarterly-client-report",
+  "description": "谷歌广告季度客户报告 — P10",
+  "turns": [
+    "帮我给 Google 账户 {{EVAL_ACCOUNT_READ}} 做一份谷歌广告季度客户报告，按 SKILL 做。"
+  ],
+  "judgeExpectation": "路径：季度客户报告 / 季度汇报 / 投放季报 → P10 google-quarterly。\n输出：collect → narrative → render HTML。",
+  "skillMapping": "references/core/intent-routing.md · P10",
+  "judgeReferencePaths": [
+    "references/core/intent-routing.md",
+    "references/core/playbooks.md",
+    "report-templates/google-quarterly-report.md"
+  ],
+  "commandMustInclude": [
+    [
+      "google-quarterly"
+    ]
+  ],
+  "commandMustNotInclude": [
+    [
+      "google-ads-diagnosis"
+    ],
+    [
+      "market-analysis"
+    ]
+  ]
+}

package/eval/cases/ir-p10-quarterly-not-p4.scenario.json

@@ -0,0 +1,27 @@
+{
+  "id": "ir-p10-quarterly-not-p4",
+  "description": "季度经营报告+下期规划 — P10，不是 P4 周期表",
+  "turns": [
+    "Google 账户 {{EVAL_ACCOUNT_READ}} 出一份 Q2 季度经营报告，要汇总和 Q3 规划，按 SKILL 做。"
+  ],
+  "judgeExpectation": "路径：用户要季度经营报告 / Q 汇总 & 下季规划 → P10 google-quarterly，不是 google-ads-diagnosis，也不是普通 google-analysis 周期 HTML。\n输出：说明 collect → 写 narrative → render；默认花费 +30%～+50%。",
+  "skillMapping": "references/core/intent-routing.md · P10 vs P4",
+  "judgeReferencePaths": [
+    "references/core/intent-routing.md",
+    "references/core/playbooks.md",
+    "report-templates/google-quarterly-report.md"
+  ],
+  "commandMustInclude": [
+    [
+      "google-quarterly"
+    ]
+  ],
+  "commandMustNotInclude": [
+    [
+      "google-ads-diagnosis"
+    ],
+    [
+      "market-analysis"
+    ]
+  ]
+}

package/eval/cases/ir-p4-period-not-diagnosis.scenario.json

@@ -4,7 +4,7 @@
   "turns": [
     "Google 账户 {{EVAL_ACCOUNT_READ}} 出一份 5 月份的月度投放报告，汇总花费和转化就行。"
   ],
-  "judgeExpectation": "路径：用户要「月度/周期报告」且给账户 ID、未强调健康诊断 → P4（google-analysis 等拉数），不是 google-ads-diagnosis。\n输出：说明周期报告与账户诊断区别；列出将用的拉数步骤。",
+  "judgeExpectation": "路径：用户只要某月花费/转化数据汇总、没有规划/客户版/大族结构 → P4（google-analysis 等拉数），不是 google-ads-diagnosis，也不是 google-quarterly。\n输出：说明周期报告与账户诊断区别；列出将用的拉数步骤。",
   "skillMapping": "references/core/intent-routing.md · P4 vs P1",
   "judgeReferencePaths": [
     "references/core/intent-routing.md",
@@ -21,6 +21,9 @@
   "commandMustNotInclude": [
     [
       "google-ads-diagnosis"
+    ],
+    [
+      "google-quarterly"
     ]
   ]
 }

package/eval/cases/p10-quarterly-report.scenario.json

@@ -0,0 +1,28 @@
+{
+  "id": "p10-quarterly-report",
+  "description": "P10: 季度经营报告 — google-quarterly collect",
+  "turns": [
+    "请给 Google 账户 {{EVAL_ACCOUNT_READ}} 出一份 2026-04-01 至 2026-06-30 的季度经营报告，要 Q2 汇总和 Q3 规划。\n按 SKILL P10 用 siluzan-tso google-quarterly collect，加 --json-out。"
+  ],
+  "judgeExpectation": "路径：季度经营复盘 + 下期规划应走 google-quarterly collect（可带 --json-out），不是 google-ads-diagnosis，也不是普通 google-analysis render。\n输出：应说明 collect → 写 narrative → render HTML；规划默认花费 +30%～+50%。",
+  "skillMapping": "Playbook P10 · Google 季度经营报告",
+  "commandMustInclude": [
+    [
+      "google-quarterly"
+    ],
+    [
+      "collect"
+    ],
+    [
+      "--json-out"
+    ]
+  ],
+  "commandMustNotInclude": [
+    [
+      "google-ads-diagnosis"
+    ],
+    [
+      "market-analysis"
+    ]
+  ]
+}

package/eval/cases/p3-cpa-scan-max-cpa.scenario.json

@@ -4,7 +4,7 @@
   "turns": [
     "请筛 Google 媒体下 2026-04-01 至 2026-04-15 CPA 高于 500 的账户。\n用 siluzan-tso accounts-digest，加 --max-cpa 500 与 --json-out ./snap-cpa；不要逐账户 stats。"
   ],
-  "judgeExpectation": "路径：多账户 CPA 筛查应使用 accounts-digest，并带 --max-cpa（或等价过滤）与 --json-out；可用 --start/--end 或 --start-date/--end-date。\n输出：交付高 CPA / 零转化命中表或「无命中」；禁止只落盘不说明。",
+  "judgeExpectation": "路径：多账户 CPA 筛查应使用 accounts-digest，并带 --max-cpa（或等价过滤）与 --json-out；可用 --start/--end 或 --start-date/--end-date。\n输出：交付高 CPA 命中表（零转化仅当消耗已超阈值）或「无命中」/全部正常句；优先贴 agentBrief.userDelivery；禁止只落盘不说明。",
   "skillMapping": "Playbook P3 · §零·D 转化成本巡检",
   "commandMustInclude": [
     [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.1.52",
+  "version": "1.1.53-beta.2",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",