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.