siluzan-tso-cli 1.1.21 → 1.1.22-beta.3

package/dist/skill/SKILL.md

@@ -1,16 +1,27 @@
 ---
 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。
+  Operates Siluzan TSO ad accounts via siluzan-tso-cli: Google/Bing/Yandex/TikTok/Kwai/Meta
+  account management, Google Ads CRUD and PMax, analytics, optimization reports, forewarning,
+  leads, invoicing, and RAG knowledge lookup. Use when the user mentions ad accounts, balance,
+  spend, campaigns, keywords, open account, MCC/BC binding, or TSO reporting. On each new user
+  task or topic switch, re-read routed references per references/core/agent-conventions.md — do not reuse prior
+  task memory.
 license: MIT
+compatibility: Requires Node.js 18+, siluzan-tso-cli installed, authenticated via send-login-code + login or config set
 metadata:
   requires: nodejs,siluzan-tso-cli
 allowed-tools: Bash(siluzan-tso:*) Read Write
 ---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — edit .tmpl or snippets/, then: node scripts/gen-skill-docs.mjs -->
 
 # Siluzan TSO Skill
 
-本 Skill 只保留任务边界、文档路由与执行规则。业务细节、参数、模板均以 references 文档为准。
+本 Skill 只保留**任务边界、文档路由与执行入口**。业务细节、参数、Playbook 步骤均以 `references/` 域目录为准。域索引见 `AGENTS.md`。
+
+<!-- 注入到 SKILL.md.tmpl 的 {{AGENT_PREAMBLE}}；构建时由 gen-skill-docs.mjs 合并 -->
+
+> **Agent 纪律（每个新任务必读）**：Read `references/core/agent-conventions.md`，再按 `SKILL.md` 任务表 Read 域文档。禁止跨话题复用参数记忆；数据类任务一律 `--json-out` + 脚本读盘（见 `references/core/tips.md`）。
 
 ---
 
@@ -25,376 +36,79 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
   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 版安装命令。
+Windows：部分 Agent 通过 PowerShell 代执行时可能失败，改在 [Git Bash](https://git-scm.com/download/win) 运行 Bash 版安装命令。
 
-登录与配置见 `references/setup.md`。**401 换凭据时优先「手机号 + 验证码」**：`send-login-code` → `login --phone --code`。
+登录与配置见 `references/core/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 透视使用                   |
+| 级别 | 示例 |
+| ---- | ---- |
+| **只读** | 账户列表、余额、消耗、报告、预警记录、Google Ads 查询 |
+| **写入**（需用户确认） | 创建/修改广告、开户申请、预警规则、报告推送 |
+| **破坏性**（确认 + `--commit`） | 账户解绑/关闭、MCC/BC 解绑、删除预警/报告/广告、发票申请 |
 
 ---
 
-## 职责划分
+## 域路由（lazy-load）
 
-| 由 **本 Skill + CLI** 保证                                                          | 由 **宿主客户端 / 外部调度** 负责                       |
-| ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| 命令拉取所需的结构化字段（Agent：`--json-out <目录>` 落盘后读文件）                 | 何时触发一轮检查（cron、事件、对话触发）                |
-| 写命令语义清晰，文档给出写后如何用读命令复核                                        | IF 条件（多指标 AND/OR、滑动时间窗）的计算与决策        |
-| 金额、ID、字段口径与文档一致（`*Display`、`entityId` vs `mediaCustomerId`）         | 命中后的触达（钉钉/飞书/Slack）与 P1/工单流程           |
-| `references/google-ads.md` 等与命令、字段含义对齐                                   | 多账户、多系列的批处理循环、限速、失败重试策略          |
+| 域 | 入口 | 典型任务 |
+| ---- | ---- | -------- |
+| `references/core/` | `agent-conventions.md` | 纪律、tips、playbooks、workflows |
+| `references/accounts/` | `accounts.md` | 列表、余额、MCC/BC、开户、发票 |
+| `references/google-ads/` | `google-ads.md` | CRUD、PMax、campaign-plan；`rules/` 优化 SOP |
+| `references/analytics/` | `account-analytics.md` | google-analysis、批处理、拓词、RAG |
+| `references/operations/` | `forewarning.md` | 预警、线索、optimize、宿主编排 |
 
-具体清单见 `references/hosted-automation-self-control.md`、`hosted-automation-monitoring-json.md`、`hosted-automation-optimize-index.md`、`workflows.md`。
+完整文件列表：`references/README.md` · Agent 目录：`AGENTS.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 前）
+## 任务 → 必读 references
 
 | 用户意图（关键词） | 必读（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 子命令存在。
+| 任意任务（首次） | `core/agent-conventions.md` |
+| 账户列表 / 余额 / 消耗 / 分享 / MCC / 多账户汇总 | `accounts/accounts.md`；金额加 `accounts/currency.md` |
+| 拉数 / 报告 / 周报 / `google-analysis` | `analytics/account-analytics.md` + `core/tips.md`；多账户加 `analytics/google-analysis-batch.md` |
+| Google 新建搜索系列 | `google-ads/google-ads-campaign-plan.md` |
+| Google 广告 CRUD / 拒审 | `google-ads/google-ads.md` |
+| PMax | `assets/pmax-create-template.md` + `google-ads/pmax-api.md` |
+| 拓词 / keyword | `analytics/keyword-planner-workflows.md`；背景先 `analytics/rag.md` |
+| 优化报告（TSO 平台） | `analytics/reporting.md` |
+| 预警 | `operations/forewarning.md` |
+| 发票 / 转账 / 充值 | `accounts/finance.md` |
+| 开户 | `accounts/open-account-by-media.md`（Google 加 `accounts/open-account-google-ui.md`） |
+| OKKI 周报 | `report-templates/okki-weekly-google-client.md` + `core/playbooks.md` P6 |
+| Google 询盘分析 | `report-templates/google-inquiry-analysis.md` + `core/playbooks.md` P7 |
+| 标准画像/扫描/周期报告 | `core/playbooks.md` 对应 P1–P5 |
+
+> 表未覆盖时：查 `references/README.md` → Read 对应 reference → 再执行 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`
+## Playbook 速查
 
-### 常见 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；离线环境需先将资源下载到本地并修改模板引用路径。
+P1–P7 见 `references/core/playbooks.md`。
 
 ---
 
-## 风险预警与自动化
+## 职责划分
 
-详见 `references/hosted-automation-user-catalog.md`。加载本 skill 时必须主动向用户介绍：
+| 由 **本 Skill + CLI** 保证 | 由 **宿主客户端 / 外部调度** 负责 |
+| -------------------------- | --------------------------------- |
+| 结构化字段拉取（`--json-out`） | 何时触发检查（cron、对话） |
+| 写命令语义与读命令复核文档 | IF 条件计算与决策 |
+| 金额、ID、字段口径一致 | 触达（钉钉/飞书）与工单 |
+| references 与命令对齐 | 批处理循环、限速、重试 |
 
-- **预算 & ROI 控制**：单日预算熔断、CPA 飙升自动降价、连续空耗自动暂停
-- **异常监控与报警**：账户封禁检测、落地页死链强停、广告素材拒审提醒、花费异动监控、余额枯竭预警
-- **自动优化**：差广告降价/关停、高转化提价扩量、A/B 测试自动决出胜者
+详见 `operations/hosted-automation-self-control.md`、`operations/hosted-automation-monitoring-json.md`、`operations/hosted-automation-optimize-index.md`。
 
 ---
 
-## 消息平台语法规范
-
-需 webhook 等方式发送消息时，先阅读对应平台文档：
+## 维护者
 
-- 企业微信：https://developer.work.weixin.qq.com/document/path/99110
-- 飞书：https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
-- 其他平台默认 markdown 输出
+- `references/core/skill-authoring.md` — 规范与检查清单
+- `docs/skill-guide.md` — 人类导读

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.21",
-  "publishedAt": 1779760187569
+  "version": "1.1.22-beta.3",
+  "publishedAt": 1779787502989
 }

package/dist/skill/assets/campaign-create-template.md

@@ -23,9 +23,9 @@ JSON 模板：同目录 [`campaign-create-template.json`](campaign-create-templa
 
 | 命令 | 支持 `--json-out`？ | 推荐用法 |
 | ---- | :-----------------: | -------- |
-| `ad campaign-validate` | **是** | **推荐** `--json-out ./snap-campaign`（落盘 `ad-campaign-validate-<account>.json`，含 `lengthViolations`）；与 `--json` 互斥。人读：`--config-file` 即可；词面规范化：`--write-normalized`。超长勿自动截断，见 `google-ads-campaign-plan.md` § 超长人工确认 |
+| `ad campaign-validate` | **是** | **推荐** `--json-out ./snap-campaign`（落盘 `ad-campaign-validate-<account>.json`，含 `lengthViolations`）；与 `--json` 互斥。人读：`--config-file` 即可；词面规范化：`--write-normalized`。超长勿自动截断，见 `google-ads/google-ads-campaign-plan.md` § 超长人工确认 |
 | `ad campaign-create` | **是** | 落盘任务响应：`--json-out ./snap-campaign`；与 `--json` 互斥 |
-| `ad batch get` / `ad batch diff` | **是** | 轮询与 diff 结果落盘，见 `references/tips.md` |
+| `ad batch get` / `ad batch diff` | **是** | 轮询与 diff 结果落盘，见 `references/core/tips.md` |
 
 **Agent**：校验与 create/batch 共用同一 `--json-out` 目录时，按 stdout 摘要里的 `outlineFile` → 再读对应 JSON（勿把 outline 当数据）。
 
@@ -76,7 +76,7 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json --js
 
 ## Agent 编排
 
-流程、双轨入口、`campaign-validate` 门禁与分层规则阅读：**`references/google-ads-campaign-plan.md`**（本文件仅字段契约，不重复流水线）。
+流程、双轨入口、`campaign-validate` 门禁与分层规则阅读：**`references/google-ads/google-ads-campaign-plan.md`**（本文件仅字段契约，不重复流水线）。
 
 一个 JSON 对应一个广告系列；多系列使用多个 JSON 文件（可选 `campaign-manifest.json`，见 campaign-plan）。
 
@@ -235,4 +235,4 @@ siluzan-tso ad batch diff --batch-id <taskId> --config-file ./campaign.json --js
 | Google Ads BatchJob                                                                         | RSA `Path1`/`Path2` 必填（缺/null → 后端 ArgumentNullException）；字段数与字符上限；关键词词面非空；SITELINK `Line2`/`Line3` ≤25 字且不可 null |
 | CLI 实务                                                                                    | `Budget > 0`、地理/语言至少 1 项、日期格式与先后、出价策略与配套字段                                |
 
-`ad campaign-validate` 通过不保证 BatchJob 成功（例如仅写 `DestinationUrl` 未写 `Finalurl` 时 validate 仍可能 ✅）。异步结果用 `ad batch get` 轮询；`HasFailed` / 部分失败时用 `ad batch diff` 对照 JSON 补缺，系列级失败时改 JSON 重提，勿在半成品上反复整包创建。写操作须 `--commit`，见 `references/google-ads.md` § ad campaign-create。
+`ad campaign-validate` 通过不保证 BatchJob 成功（例如仅写 `DestinationUrl` 未写 `Finalurl` 时 validate 仍可能 ✅）。异步结果用 `ad batch get` 轮询；`HasFailed` / 部分失败时用 `ad batch diff` 对照 JSON 补缺，系列级失败时改 JSON 重提，勿在半成品上反复整包创建。写操作须 `--commit`，见 `references/google-ads/google-ads.md` § ad campaign-create。

package/dist/skill/assets/pmax-create-template.md

@@ -13,9 +13,10 @@
 | 场景 | 正确做法 |
 |------|----------|
 | 创建 PMax | `pmax-validate` → 用户确认 → `pmax-create` |
+| 文案超长 | `pmax-validate --json-out` 读 `lengthViolations`（含完整 `text`）；**勿自动截断**，列改写方案给用户确认后再改 JSON 并重跑 validate（同 Search `campaign-validate`） |
 | 金额 | JSON 填**主币种「元」**；CLI 提交前 `budget`、`targetCpa_BidingAmount` ×100 |
 | 图片 | **只填 `imagePaths`** 指向本地 PNG/JPEG；`pmax-create` 会自动 multipart 上传并用 assetId 创建（勿把 Base64 提交进 Git） |
-| 改已上线 PMax | `ad pmax-get` / `pmax-edit` / `pmax-assets-update` 等（见 `references/pmax-api.md`） |
+| 改已上线 PMax | `ad pmax-get` / `pmax-edit` / `pmax-assets-update` 等（见 `references/google-ads/pmax-api.md`） |
 | 列表复核 | `ad campaigns -a <id> --json`，`channelTypeV2` 应为 `PERFORMANCE_MAX` |
 
 ---
@@ -89,6 +90,6 @@ siluzan-tso ad campaigns -a <accountId> --json
 ## 范围说明
 
 - **支持**：Lead Gen / 非 Shopping 的 Performance Max
-- **不含**：Shopping PMax、Listing groups；信号与其它编辑见 `ad pmax-signals-*` 等（`references/pmax-api.md`）
+- **不含**：Shopping PMax、Listing groups；信号与其它编辑见 `ad pmax-signals-*` 等（`references/google-ads/pmax-api.md`）
 
-网关完整契约见 Sammamish：`src/GoogleAPI/docs/pmax-frontend-api.md`；CLI 摘录见 `references/pmax-api.md`。
+网关完整契约见 Sammamish：`src/GoogleAPI/docs/pmax-frontend-api.md`；CLI 摘录见 `references/google-ads/pmax-api.md`。

package/dist/skill/docs/skill-guide.md

@@ -0,0 +1,44 @@
+# Siluzan TSO Skill — 人类导读
+
+Agent 运行时请用 `SKILL.md` + `AGENTS.md`；本文供维护者与产品经理深读。
+
+## 设计理念（对齐 gstack）
+
+1. **薄入口**：`SKILL.md` 仅路由，<150 行
+2. **域化 references**：`core/`、`accounts/`、`google-ads/`、`analytics/`、`operations/`
+3. **渐进披露**：Playbook、参数表、SOP 按需 Read，不塞进主文件
+4. **模板分离**：`assets/*.json` 契约 vs `report-templates/*.md` 内容纲要
+
+## 目录树
+
+```
+siluzan-ads/
+├── AGENTS.md              # Agent 域目录（类似 gstack AGENTS.md）
+├── SKILL.md               # 路由入口
+├── docs/skill-guide.md    # 本文件
+├── references/
+│   ├── core/              # 纪律、安装、playbooks
+│   ├── accounts/          # 账户、开户、财务
+│   ├── google-ads/        # CLI 命令 + rules/ SOP
+│   ├── analytics/         # 拉数、批处理、拓词
+│   └── operations/        # 预警、线索、自动化
+├── assets/                # JSON/MD 创建契约
+└── report-templates/      # 报告纲要 + HTML 样式
+```
+
+## 常见维护任务
+
+| 任务 | 改哪里 |
+| --- | --- |
+| 新 CLI 命令 | `src/commands/` + 对应 `references/<域>/` |
+| 新 Playbook | `references/core/playbooks.md` + `SKILL.md` 任务表 |
+| 环境 URL | `scripts/write-defaults.mjs` + `copy-skill-assets.mjs` |
+| 发布 Skill | `npm run build:prod` → `siluzan-tso init --force` |
+
+## 与 eval 的关系
+
+场景 JSON 中 `judgeReferencePaths` 须使用域路径，例如 `references/accounts/accounts.md`。改文档后运行：
+
+```bash
+pnpm --filter siluzan-tso-cli run eval:export-cases
+```