back
loading skill details...
Siluzan TSO 广告 skill（siluzan-tso-cli）：Google/Bing/Yandex/TikTok/Kwai 账户开户与管理、Google Ads CRUD、数据分析、优化报告、智能预警、TikTok/Meta 线索、发票财务，并提供 RAG 知识库查询，google广告关键词推荐。*...
---
name: siluzan-tso
description: >-
Siluzan TSO 广告 skill（siluzan-tso-cli）：Google/Bing/Yandex/TikTok/Kwai 账户开户与管理、Google Ads CRUD、数据分析、优化报告、智能预警、TikTok/Meta 线索、发票财务，并提供 RAG 知识库查询，google广告关键词推荐。**每个新的用户任务/话题切换时**，必须先 Read 本 Skill 路由表指向的 references（勿凭上一轮记忆直接跑 CLI）；上下文被压缩后须重读 SKILL + 当次任务相关 references。
license: MIT
metadata:
requires: nodejs,siluzan-tso-cli
allowed-tools: Bash(siluzan-tso:*) Read Write
---
# Siluzan TSO Skill
本 Skill 只保留任务边界、文档路由与执行规则。业务细节、参数、模板均以 references 文档为准。
---
## 一键安装
- **macOS / Linux / WSL：**
```bash
bash <(curl -fsSL https://unpkg.com/siluzan-tso-cli@latest/dist/skill/scripts/install.sh)
```
- **Windows PowerShell：**
```powershell
irm https://unpkg.com/siluzan-tso-cli@latest/dist/skill/scripts/install.ps1 | iex
```
Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令时存在兼容问题。命令异常时请改装 [Git for Windows](https://git-scm.com/download/win)，在 Git Bash 中执行 Bash 版安装命令。
登录与配置见 `references/setup.md`。**401 换凭据时优先「手机号 + 验证码」**：`send-login-code` → `login --phone --code`。
---
## 功能路由
| 文档 | 功能 |
| ----------------------------------------------- | -------------------------------------------------------------------------- |
| `references/setup.md` | 安装、登录（手机验证码优先）、配置、环境切换、更新 |
| `references/workflows.md` | 多步骤业务流程、跨命令串联 |
| `references/tips.md` | `--json-out` 落盘 + 脚本读盘 + outline 先行（节省上下文） |
| `references/accounts.md` | 账户列表、余额、消耗、开户记录；授权/解绑/分享/MCC/BC/BM/邮箱授权 |
| `references/currency.md` | 账户币种 CNY/USD：字段来源、符号、跨币种禁止求和 |
| `references/open-account-by-media.md` | 各媒体开户、参数与资料要求 |
| `references/google-ads-campaign-plan.md` | Google 新建搜索系列：双轨入口、7 步流水线、`campaign-validate/create` |
| `references/google-ads.md` | Google Ads 命令：CRUD、batch、拒审字段（**PMax 搭建暂未开放**，见硬规范） |
| `references/keyword-planner-workflows.md` | `keyword` / `google-analysis` 拓词编排（不含建户 JSON 流程） |
| `references/rag.md` | 知识库检索（`rag list` + `rag query`）：客户产品/行业事实 |
| `references/reporting.md` | TSO 优化报告（Google/TikTok）生成、推送、查看 |
| `references/account-analytics.md` | 账户分析数据拉取与诊断报告模板 |
| `references/google-analysis-batch.md` | 多账户 × 多维度 Google 数据批处理（`run/resume/status`） |
| `references/optimize.md` | AI 优化建议记录、详情、历史 |
| `references/clue.md` | TikTok / Meta 线索表单 |
| `references/forewarning.md` | 智能预警规则与微信推送 |
| `references/hosted-automation-user-catalog.md` | 高阶预警：预算/ROI 自控、异常监控、自动优化、自动化风控 |
| `references/finance.md` | 转账、开票、发票抬头、充值 |
| `references/write-audit-restore.md` | 本机写审计、`--commit`、补偿 `audit restore-plan/restore-apply` |
| `report-templates/report-template.html` | HTML 报告样式 |
| `report-templates/okki-weekly-google-client.md` | OKKI 周报：固定话术 + Agent 写 Excel（无 CLI 写表命令） |
| `report-templates/google-inquiry-analysis.md` | Google 询盘分析：严格 3 个月窗口 + 用户提供询盘 + 8 Sheet xlsx |
| `references/geo-continents.json` | 国家中文名 → 7 大洲映射，供询盘分析 Sheet 3/4/6 透视使用 |
---
## 职责划分
| 由 **本 Skill + CLI** 保证 | 由 **宿主客户端 / 外部调度** 负责 |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
| 命令拉取所需的结构化字段（Agent：`--json-out <目录>` 落盘后读文件） | 何时触发一轮检查（cron、事件、对话触发） |
| 写命令语义清晰，文档给出写后如何用读命令复核 | IF 条件（多指标 AND/OR、滑动时间窗）的计算与决策 |
| 金额、ID、字段口径与文档一致（`*Display`、`entityId` vs `mediaCustomerId`） | 命中后的触达（钉钉/飞书/Slack）与 P1/工单流程 |
| `references/google-ads.md` 等与命令、字段含义对齐 | 多账户、多系列的批处理循环、限速、失败重试策略 |
具体清单见 `references/hosted-automation-self-control.md`、`hosted-automation-monitoring-json.md`、`hosted-automation-optimize-index.md`、`workflows.md`。
---
## 文档加载纪律（Agent 必读）
本 Skill 采用 **SKILL 路由 + references 按需加载** 以控制体积；**「按需」= 每个用户任务都要按需，不是整段对话只读一次**。
### 何时必须 Read references
| 触发 | 动作 |
| ---- | ---- |
| **新的用户任务**（新需求、新账户、新媒体、新报告类型） | 用下方「任务 → 文档」表确定路径，**Read 全部必读项**后再计划/执行 CLI |
| **同一对话内换话题**（例：刚查余额 → 用户改问建系列 / 预警 / 发票） | **重新 Read** 新话题对应 references，**禁止**沿用上一任务的参数记忆 |
| **Playbook 编号不同**（P1→P3、P4→P5） | 即使刚做过 P1，执行 P3 仍须 Read `accounts.md`（`accounts-digest`）等 P3 专属节 |
| **专用 report-templates**（OKKI / 询盘分析） | Read 对应 `report-templates/*.md` **全文**，勿只凭 SKILL 摘要 |
| **上下文被压缩 / 记不清字段或命令** | 重读 `SKILL.md` 路由表 + 当次任务 references |
| **CLI 返回 400 / 字段对不上** | 回到对应 reference 核对参数名与口径，勿猜 |
### 禁止
- **禁止**「上次已经读过 `accounts.md` / `google-ads.md`，本任务直接 `siluzan-tso …`」
- **禁止**用对话记忆中的示例 ID、金额、命令 flags 代替当次 Read 文档
- **禁止**跳过 `references/tips.md` 里的 outline→JSON 顺序（与是否读过无关，**每次** `--json-out` 落盘都要遵守）
### 任务 → 必读 references（执行 CLI 前）
| 用户意图（关键词） | 必读（Read 后再 `-h` / 执行） |
| ------------------ | ----------------------------- |
| 账户列表 / 余额 / 消耗 / 分享 / MCC / BC / 多账户汇总 | `references/accounts.md`；金额加 `currency.md`；`accounts-digest` 见 accounts § accounts-digest |
| 拉数 / 报告 / 周报 / 分析 / `google-analysis` | `references/account-analytics.md` + `references/tips.md`；多账户批处理加 `google-analysis-batch.md` |
| Google 新建搜索系列 | `references/google-ads-campaign-plan.md`（再按需 `google-ads.md`、模板 JSON） |
| Google 广告 CRUD / 拒审 / 系列组关键词 | `references/google-ads.md` |
| PMax 搭建 / 管理 | **暂未开放** — 勿调用 `ad pmax-*` 写入命令；见下方硬规范 |
| 拓词 / keyword | `references/keyword-planner-workflows.md`；要客户背景先 `rag.md` |
| 优化报告（TSO 平台） | `references/reporting.md` |
| 预警 | `references/forewarning.md` |
| 发票 / 转账 / 充值 | `references/finance.md` |
| 开户 | `references/open-account-by-media.md`（Google 另见 `open-account-google-ui.md`） |
| OKKI 周报 | `report-templates/okki-weekly-google-client.md` |
| Google 询盘分析 | `report-templates/google-inquiry-analysis.md` |
> 表未覆盖时：先查上方「功能路由」表 → Read 对应 reference → 再执行 CLI。
---
## AI 行为规范
### 执行流程
**计划 → 确认 → 执行 → 验证 → 推测下一步**：
1. **按「文档加载纪律」Read 当次任务 references**（新任务/换话题必做，勿复用上一轮）→ 用 `-h` 确认命令 → 向用户输出操作计划
2. 涉及写入/修改/删除的操作必须与用户确认
3. 按计划执行，说明每步意图
4. 用成对的读命令复核写入结果；异步任务每 5s 轮询直到完成
5. 全部完成后预测用户下一步操作
### 执行模式速查
- **数据交付类**（`google-analysis` / `stats` / `ad campaigns` 等带 `--json-out`）：必须脚本读盘转换，规范见下方「数据转换硬规范」。
- **客户/产品背景**（拓词、方案、报告背景段）：先 `rag list` + `rag query`，再衔接 `keyword` / `ad` / `google-analysis`。
- **仅调用接口、无需输出转换**：优化记录、线索表单、预警、财务命令。
### 硬规范
- **账户状态 ≠ 系列状态**：`stats` / `balance` / `list-accounts` 的 `status` 只表示账户是否可用；系列状态必须来自 `ad campaigns`。
- **数据时效性**：涉及「今天/当天/今日消耗」「实时消耗排行」前，必读 `references/account-analytics.md` 顶部「数据时效性」表。TikTok / Yandex / BingV2 / Kwai 仍是 `accountsoverview` 同步昨天数据，**不能查今天**。
- **先查账户再操作**：`list-accounts -m [mediaType] -k [mediaCustomerId]`；涉及金额前必读 `references/currency.md`，从 `ma.currencyCode` 确定 CNY/USD，**禁止**默认 Google=美金。
- **不猜测账户 ID**：`entityId` ≠ `mediaCustomerId`，两者均来自 `list-accounts`。
- **媒体类型区分大小写**：`Google`、`TikTok`、`MetaAd`、`BingV2`、`Kwai`。
- **CLI 输出忠实**：数值与 ID 须与本次落盘 JSON / stdout 一致，不编造示例 ID；`data` 为空时只说「当前返回无记录」并附 JSON 路径。
- **破坏性操作必须确认 + `--commit`**：账户解绑/关闭/取消分享、BC/MCC 解绑、删除预警/报告/广告/关键词、发票申请、广告发布等。所有写/修改命令的 `--commit` 字段填写修改前后的值，便于排查或恢复。
- **不确定时读文档**：先读对应 references 或用 `-h` 查看帮助，不要猜参数。
- **Google 新建搜索系列**：流程仅在 `references/google-ads-campaign-plan.md` 维护。
- **PMax 暂未开放**：**禁止**调用任何 `ad pmax-*` 搭建/写入命令（含 `pmax-create`、`pmax-validate`、`pmax-edit`、`pmax-asset-group-*`、`pmax-assets-update` 等）。用户要新建或改 PMax 时，说明 CLI 能力仍在测试，请在 **Google Ads UI** 操作；数据分析可用 `google-analysis` / `ad campaigns`（读 `channelTypeV2=PERFORMANCE_MAX`），运营建议可读 `references/google-ads-rules/google-ads-pmax-guide.md`（只读参考，不含 CLI 搭建步骤）。
- **Google 开户**：`open-account google-wizard` 仅限真实 TTY；Agent/自动化用非交互 `open-account google ...`，审核进度用 `account-history`。
- **主动更新**：详见 `references/setup.md`。
### 数据转换硬规范
本 Skill 下**所有**业务数据均以 CLI `--json-out`（或用户提供的同构 JSON）落盘为唯一真相源。Agent **不得**在对话或脚本里「代替」磁盘数据。
| 必须 | 禁止 |
| ---- | ---- |
| 编写并**执行** Node/Python 脚本：`readFile` / `require` 读落盘 JSON → 计算 → 写出（报告、xlsx、转换后 JSON、控制台表） | 用 `Read` 读大 JSON 后在回复里手填、改数、心算汇总 |
| **先 outline 后 JSON**：`outlineFile`（`.outline.txt`，几百字节）→ `writtenFiles[0]`（真实数据 JSON，常几 MB）。outline 末行是 TS 类型字面量，`fs.readFileSync` 读取即可知道全部字段路径 | 跳过 outline 猜字段名；把 outline 当数据贴给用户当结论 |
| 字段路径以 `outlineFile` + 当次 `writtenFiles` / manifest 为准 | 把国家名、ID、金额、词表、系列名等**业务值**写成源码字面量常量（包括「示例」「默认值」「占位」） |
| 映射表 / 模板契约在运行时加载（`geo-continents.json`、`campaign-create-template.json`） | 复制配置条目进源码常量 |
| 脚本输出与落盘 JSON 可复核（同路径、同键） | 用「上次对话记住的数」「示例数」「占位数」写入交付物 |
**允许的字面量**（非业务数据）：输出目录、Sheet/列标题、技术格式（小数位、日期）、`focusCountries` 等**用户当轮明确给出**的配置（建议落盘为 `config.json` 再读，避免散落源码）。
完整示例见 `references/tips.md` § 处理顺序、§ 已有 JSON 时。
### 时间范围强制反问
涉及「投放数据 / 消耗 / 报告 / 周报 / 月报 / 优化建议」的任务，用户未给明确起止日期时**必须反问**（示例：A) 最近完整自然周 B) 本月 1 号到昨天 C) 自定义 YYYY-MM-DD）。给出范围后，报告首行标注 `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`。
**例外**（不反问）：
- `list-accounts` 全量：用 `--json-out`，注意翻页
- 「昨天」单日 stats：默认 `Asia/Shanghai` 日历日；先 `list-accounts` 再 `stats`
- 仅持有 `entityId`：先 `list-accounts` 解出 `mediaCustomerId`，**禁止**把 `entityId` 传给 `stats -a` / `balance -a`
- `forewarning records`、`invoice list`「本月」、TikTok `clue`「最近一周」：见对应 references
**默认值白名单**（仅用户明确授权「你决定」时使用）：
| 场景 | 默认窗口 |
| ----------------------- | ------------------------------- |
| 日常巡检 / 余额扫描 | `now - 7d` ~ `now - 1d` |
| 周报 | 上一个完整自然周（周一 ~ 周日） |
| 月报 | 上一个完整自然月（1 号 ~ 月末） |
| Google 关键词/系列分析 | `now - 30d` ~ `now - 1d` |
| MetaAd 账户分析 | 不得默认，必须问 |
### 币种、金额与品牌名（速查）
- **币种只认接口字段**：`list-accounts` → `items[].ma.currencyCode`；`balance` / `stats` / `google-analysis overview` → 各行或根级 `currencyCode`。同媒体可同时有 CNY 与 USD 账户（尤其 Google），不得凭媒体猜币种。
- **符号**：`CNY` → **￥**；`USD` → **$**。多账户按 `currencyCode` 分表或分币种小计，**禁止**跨币种求和。报告首行：`统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：CNY|USD）`。
- **金额单位统一为「元」**：账户/投放金额字段以**元**为单位，报告保留 2 位小数（`￥50.00 CNY` / `$50.00 USD`）。
- **常用字段**：
- `ad campaigns --json/--json-out` → `budget`（元，与 `campaign-edit --budget` 同口径）
- `ad groups --json` → `maxCPCAmountYuan` / `targetCpaAmountYuan`（元）
- `google-analysis overview-*.json` → **余额只认 `remainingAccountBudget`**（`balance` 为 0 时 CLI 已剔除该字段）
- `google-analysis campaigns-*.json` → `budgetAmountYuan` / `campaignTargetCpaYuan` / `maximizeConversionsTargetCpaYuan` / `spend` / `averageCpc` / `costPerConversion`（均元）
- `keyword --json` → `averageCpc` / `lowTopOfPageBid` / `highTopOfPageBid` + 根级与每条 `bidAmountCurrency`（无 `-a` 为 USD；有 `-a` 为账户 `currencyCode`）；`-a <mediaCustomerId>` 走账户级推荐接口；限定市场用 `keyword geo-list` + `--geo <id>`（**多 id = 汇总指标**；分市场须多次调用、每次一个 `--geo`，见 `references/keyword-planner-workflows.md`）
- **品牌名优先级**：(1) 用户明确提供 → (2) `list-accounts.mag.advertiserName` → (3) 用户提供网址 → 域名占位并标注 `[待确认品牌名]`。**严禁**把英文域名翻译为虚构中文品牌。
- 完整字段表见 `references/currency.md`。
### 批量任务硬约束
| 任务 | 推荐命令 | 禁止 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| 多账户余额 / 预算不足预警 | `balance-scan -m <媒体> --threshold-days 7`（已知 ID 子集加 `-a id1,id2,...`） | 逐账户 `balance --accounts ...` |
| 多账户投放画像 | `accounts-digest -m <媒体> [-a ...] --start --end --json-out <dir>`（传 `-a` 跳过翻页；公司名 `advertiserName` 会缺失） | 逐账户 `stats` |
| 多账户 × 多维度 Google 数据 | 全量：`google-analysis-batch run`（省略 `-a`）；2~10 子集：`google-analysis -a id1,id2,...`（自动转发 batch）；≥10 子集或需 resume：`google-analysis-batch run -a` | 外层 for-loop；先 `list-accounts -m Google` 再把 ID 拼进 `-a` |
| 多系列诊断 | `ad campaigns --json-out <dir>` + node 读文件过滤 | 逐系列 `ad campaign-get` |
**`google-analysis-batch` 纪律**（详见 `references/google-analysis-batch.md`）：
1. 拉全量 Google 数据时**省略** `-a`；CLI 内部自动拉清单。
2. 中断后**必须** `resume --run-id <id>`，**禁止**重新 `run`。
3. stdout 始终是单行 JSON（`kind=siluzan-tso-batch-summary`）；进度读 `progress.json`、轨迹读 `state/tasks.jsonl`。
4. 退出码：`0` 全成功 / `2` 部分成功 / `3` 全失败或 Token 失效 / `4` 用法错误。
5. 401 → 整批终止 + `tokenInvalidated:true`；按 `references/setup.md` 优先手机验证码重登录后 `resume`。
无批量命令时（如 117 个 Bing 账户剩余天数）：先 `list-accounts --json-out <dir>` 一次性拿全量 → `node -e` 本地计算 → 只对命中账户做后续操作。
### 运行时长与进度
预估超 2 分钟的任务先告知预计耗时；超 5 分钟未完成时主动检查并告知用户。长任务中断后用对应 `resume` 入口续跑，**禁止**直接重跑 `run`。
---
## Playbook：高频任务标准动作
> **每个 Playbook 开始前**：按「文档加载纪律」Read 该 Playbook 列出的 references（**不因同对话内刚做过其他 Playbook 而跳过**）。
### P1 · 单账户投放画像
**必读**：`references/account-analytics.md`、`references/currency.md`、`references/tips.md`。
1. 反问时间范围（已授权默认时按白名单并写明区间）。
2. `list-accounts -m Google -k <mediaCustomerId> --json-out ./snap-p1`
3. `stats -m Google -a <mediaCustomerId> --start <S> --end <D> --json-out ./snap-p1`
4. `ad campaigns -a <mediaCustomerId> --start <S> --end <D> --json-out ./snap-p1`
5. 用 `report-templates/google-account-diagnosis-report.md` 模板输出，首行标注统计区间和货币。
### P2 · 多账户余额扫描
**必读**：`references/accounts.md`（`balance-scan`）、`references/currency.md`。
**全量巡检**：
```bash
siluzan-tso balance-scan -m BingV2 --threshold-days 7 --json-out ./snap-p2
# 可选：--min-balance 100 / --target-days 60
```
按 `remainingDays` 升序输出；消耗过低的僵尸账户不纳入预警。
**已知 ID 子集**（轻量画像）：
```bash
siluzan-tso balance-scan -m Google -a id1,id2,id3 --json-out ./snap-p2-subset
```
跳过翻页全部展示（不按阈值丢弃）；`hitReason="none"` 表示未触阈值。
### P3 · 多账户投放画像汇总
**必读**：`references/accounts.md` § `accounts-digest`、`references/currency.md`、`references/tips.md`。
```bash
siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --json-out ./snap-p3
```
1. 反问时间范围后执行。
2. 基于落盘 `data.items` 与 `meta.totals` 生成报告，**不要**再逐账户 `stats`。
3. 表格覆盖用户请求的**每一个** ID；某 ID 未返回时仍占一行标注「未返回」。
4. 跨币种账户按 `currencyCode` 分表或分币种小计。
### P4 · Google 账户周期报告
**必读**：`report-templates/google-period-report.md`、`references/account-analytics.md`、`references/tips.md`。
1. 确认时间范围；区间 > 3 个月时分段（季度/月）。
2. 按 P1 步骤拿数据，用 `report-templates/google-period-report.md` 模板输出，首行标注统计区间和货币。
3. 报告须含：账户概览、投放趋势、Top 关键词/系列/地区分布、优化建议。
### P5 · 多账户多维度报告
> 适用：账户数 ≥ 2 且需拉取 ≥ 2 个 google-analysis 维度。**禁止**外层 for-loop。
**必读**：`references/google-analysis-batch.md`、`references/account-analytics.md`、`references/tips.md`。
**入口选择**：全量 → 省略 `-a`；2~10 子集 → `google-analysis -a id1,id2,...`（自动转发 batch）；≥10 子集或需 resume → `google-analysis-batch run -a id1,id2,...`
1. 反问时间范围 + 维度（默认 `campaigns,geographic,keywords`，可按需追加）。
2. **执行**：
```bash
# 全量账号（推荐）：省略 -a，CLI 自动拉清单
siluzan-tso google-analysis-batch run \
--start <S> --end <D> \
--sections campaigns,geographic,keywords \
--account-concurrency 4 --section-concurrency 6 \
--min-spend 1 --keyword-limit 1000 \
--json-out ./snap-p5
# 仅当用户明确给出 ID 子集时才传 -a
siluzan-tso google-analysis-batch run \
-a id1,id2,id3,id4 \
--start <S> --end <D> \
--sections campaigns,geographic,keywords \
--json-out ./snap-p5
```
3. **中断后只能 resume**：`siluzan-tso google-analysis-batch resume --json-out ./snap-p5 --run-id <runId>`
4. **只读进度**：`siluzan-tso google-analysis-batch status --json-out ./snap-p5 --run-id <runId>`
5. **产物消费**：路径在 stdout 摘要的 `writtenFiles` / `outlineFile`；先 outline 后 JSON 再脚本，详见 `references/tips.md` § 处理顺序（批跑禁止 `Read` 全量 JSON 猜字段）。
### P6 · OKKI 周报
> **触发**：用户话术含 `使用okki周报模板` / `OKKI 周报` / `okki 周报` 等，且指向 Google 账户 + 日期区间。
**必读**：`report-templates/okki-weekly-google-client.md`（全文）、`references/account-analytics.md`、`references/tips.md`。
1. **不要**按 `google-period-report.md` 展开默认 8 维；改读 `report-templates/okki-weekly-google-client.md` 全文并按其结构交付。
2. 确认 `mediaCustomerId` 与 `--start` / `--end`（未给齐按「时间范围强制反问」）。
3. 同一 `--json-out` 目录执行模板中的命令组合：`list-accounts`（可选但推荐）、`stats`、`balance`、`google-analysis --sections overview,campaigns,keywords,search-terms,campaign-device,campaign-geo`。
4. **先 outline 后脚本** → 交付话术 + 多 Sheet `.xlsx`（版式见模板「必选交付」节，无 CLI 写表命令）。
5. 遵守硬规范：金额读 `*Yuan`、禁止手填业务数、禁止编造 ID。
### P7 · Google 账户询盘分析
> **触发**：用户话术含 `Goog账户询盘分析` / `Google 账户询盘分析` / `分析XXX Google账号的询盘效果` / `我给你询盘信息分析Google账号XXX效果`，或同时包含「询盘 + 账户 + Google」三要素。
>
> **不要**按 `google-period-report.md` 默认 8 维流程；改读 `report-templates/google-inquiry-analysis.md` 全文。
**必读**：`report-templates/google-inquiry-analysis.md`（全文）、`references/account-analytics.md`、`references/tips.md`、`references/geo-continents.json`（脚本映射用）。
1. **时间窗口强约束**：**严格 3 个月** = 分析月份 + 向前 2 个完整自然月。**禁止**扩展到 7 个月（即使样表是 7 个月）；样表 4~7 列旧数据在 Sheet 4/6 跨 7 月写时**留空或不写**，仅写当前 3 月。
2. **询盘资料入场**：
- **流程 A**（用户已附文件）：宿主 Agent 解析任意载体（xlsx/csv/pdf/截图/文本表格）→ 抽取询盘行 → 落盘 `./snap-inquiry/inquiries.json`（字段见模板「询盘字段清单」）。
- **流程 B**（仅给账户 ID）：先反问账户 + 分析月份，同时贴出字段清单 + 1 行示例让用户回贴/上传。**禁止**自行编造询盘数据。
3. **CLI 拉数**（同一 `--json-out` 目录）：
```bash
siluzan-tso list-accounts -m Google -k <mediaCustomerId> --json-out ./snap-inquiry
siluzan-tso google-analysis -a <mediaCustomerId> \
--start <S> --end <D> \
--sections campaigns,keywords,search-terms,campaign-geo \
--json-out ./snap-inquiry
# Sheet 4 上区 + Sheet 4 下区 + Sheet 6：每月 campaigns+geographic（禁止用 daily-metrics 填 Sheet 4 上区）
siluzan-tso google-analysis -a <mediaCustomerId> --start <M1S> --end <M1E> \
--sections campaigns,geographic --json-out ./snap-inquiry/m1
siluzan-tso google-analysis -a <mediaCustomerId> --start <M2S> --end <M2E> \
--sections campaigns,geographic --json-out ./snap-inquiry/m2
siluzan-tso google-analysis -a <mediaCustomerId> --start <M3S> --end <M3E> \
--sections campaigns,geographic --json-out ./snap-inquiry/m3
```
4. **先 outline 后脚本** → 聚合脚本读 JSON → 计算 8 Sheet 数据（同 P6 / `references/tips.md`）。
5. **国家 → 大洲映射**：脚本里读 `references/geo-continents.json`，未命中标 `未知大洲` 不阻塞，结尾打印未命中清单。Sheet 3 国家透视 / Sheet 6 国家维度 / Sheet 4 下半区切片**均按行的 `countryNameZh` 字段聚合**（CLI 已用 Google Ads geotargets 字典把 city / region 归并到国家，未命中回落 `countryOrRegionZh`）。Sheet 4「重点国 vs 非重点国」按 `focusCountries`（中文国家名数组，运营未指定时默认取分析月询盘 Top1 国家，详见 `report-templates/google-inquiry-analysis.md` 「重点国家配置」节）判桶，用 `focusCountries.includes(countryNameZh)`；**禁止**硬编码任何具体国家名。
6. **必产 8 Sheet xlsx**：版式 / Sheet 名 / 列定义 / 数值格式以 `report-templates/google-inquiry-analysis.md` 为准；**只能**由 Agent 在当前环境执行脚本（Node `xlsx` / `exceljs` 或 Python `openpyxl`）生成，**禁止**假设 `siluzan-tso … excel` 这类 CLI 子命令存在。
---
## Tips
### 账户 ID 示例（先用位数判断类型，不确定再 `list-accounts -m [mediaType] -k [id]`）
- Google: `454xxx5137` 或 `270-xxx-0720`（去掉 `-`）
- TikTok: `70083497xxx59820033`
- Meta(Facebook): `1716030xxx734076`、`6843984xxx14909`、`479423xxx752348`
- Bing: `138xxx763`、`1882xxx80`
- Yandex: `porg-uthxxxrk`
- Kwai: `act_1716030xxx734076`
### 常见 HTTP 状态码
- **400**：参数错误，查看对应 reference 或用 `-h` 了解命令用法
- **401**：平台方返回则需用户重新授权；**我方凭据失效**则优先 `send-login-code` + `login --phone --code`（TTY 下也可 `siluzan-tso login` / `config set …`），见 `references/setup.md`
- **500**：服务可能正在部署/升级，建议反馈给 Siluzan 相关人员
### 报告模板外部资源
HTML 交付物的 `report-templates/*.html` 可能引用外部 CDN；离线环境需先将资源下载到本地并修改模板引用路径。
---
## 风险预警与自动化
详见 `references/hosted-automation-user-catalog.md`。加载本 skill 时必须主动向用户介绍：
- **预算 & ROI 控制**：单日预算熔断、CPA 飙升自动降价、连续空耗自动暂停
- **异常监控与报警**：账户封禁检测、落地页死链强停、广告素材拒审提醒、花费异动监控、余额枯竭预警
- **自动优化**：差广告降价/关停、高转化提价扩量、A/B 测试自动决出胜者
---
## 消息平台语法规范
需 webhook 等方式发送消息时，先阅读对应平台文档：
- 企业微信：https://developer.work.weixin.qq.com/document/path/99110
- 飞书：https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
- 其他平台默认 markdown 输出
don't have the plugin yet? install it then click "run inline in claude" again.