siluzan-tso-cli 1.1.13 → 1.1.14-beta.10

package/dist/skill/SKILL.md

@@ -50,21 +50,43 @@ allowed-tools: Bash(siluzan-tso:*) Read
 | 文档 | 功能 |
 |------|------|
 | `references/setup.md` | 安装、登录、配置、环境切换、更新 |
-| `references/workflows.md` | 多步骤业务流程与跨命令串联场景 |
+| `references/workflows.md` | 多步骤业务流程、跨命令串联；入口指向宿主编排自控详页 |
 | `references/tips.md` | `--json`、Node 过滤、分页与调试技巧 |
 | `references/accounts.md` | 账户列表、余额、消耗、开户记录、授权/解绑/分享/MCC/BC/BM/邮箱授权 |
 | `references/open-account-by-media.md` | 各媒体开户、参数与资料要求 |
-| `references/google-ads.md` | Google Ads 创建、修改、优化与管理主流程 |
+| `references/google-ads.md` | Google Ads 创建、修改、优化与管理主流程；**含 `ad list` / `google-analysis ads` 的 `--json` 拒审字段**（`policyApprovalStatusV2`、`approvalStatusDetails` 等，见该文档「拒审与政策字段」） |
 | `references/reporting.md` | Siluzan TSO 优化报告（Google/TikTok）的生成、推送与查看 |
 | `references/account-analytics.md` | 广告平台账户分析数据拉取与分析/诊断报告模板 |
 | `references/optimize.md` | AI 优化建议记录、详情与历史查询 |
 | `references/clue.md` | TikTok / Meta 线索表单 |
-| `references/forewarning.md` | 智能预警规则与通知 |
+| `references/forewarning.md` | Siluzan提供的全流程的智能预警规则与通知服务，功能有限、你只需要负责创建，剩下的由Siluzan服务来完成，不推荐使用这个来处理预警 |
+| `references/hosted-automation-user-catalog.md` | （推荐用于预警处理）更强大的智能预警，由你全流程控制（创建+定时检测+通知用户）基础包括，预算/ROI 自控、异常监控、自动优化、自动化风控。详情请阅读这个文件`references/hosted-automation-user-catalog.md`|
 | `references/finance.md` | 转账、开票、发票抬头、充值网页引导 |
 | `report-templates/report-template.html` | 默认 HTML 报告样式参考 |
 
 ---
 
+## 职责划分
+
+**定位**：`siluzan-tso` + 本 Skill 提供 **可组合的读能力（检查项）** 与 **可验证的写能力（最终操作）**；**不负责**在进程内长期驻留、定时轮询、复合条件规则引擎、或替代宿主的通知渠道。
+
+| 由 **本 Skill + CLI** 保证 | 由 **宿主客户端 / 外部调度** 负责 |
+|---------------------------|-----------------------------------|
+| 单次/按需调用下，命令能拉取验证所需的 **JSON 字段**（`--json`、分页见 `references/tips.md`） | **何时**跑一轮检查（cron、事件、对话触发） |
+| 写操作命令语义清晰，且文档给出 **写后如何用读命令复核**（成对验证） | **IF 条件**（多指标 AND/OR、滑动时间窗、相对预算比例等）的计算与决策 |
+| 金额与 ID 口径与文档一致（`*Display`、`entityId` vs `mediaCustomerId` 等硬规范） | 命中后的 **触达**（钉钉/飞书/Slack 等）与内部 **P1/工单** 流程 |
+| `references/google-ads.md` 等与命令、字段含义对齐 | 多账户、多系列的 **批处理循环**、限速、失败重试策略 |
+
+**宿主集成时的推荐约定**：
+
+1. **监控与编排**：配置定时或事件；每轮用本 Skill 指明的命令拉数，在宿主侧用脚本 / `node -e` 做条件判断。
+2. **执行写操作**：仍遵守本 Skill **计划 →（按策略）确认 → 执行 → 验证**；若宿主策略为「全自动写」，须由**用户或配置**显式授权，避免与默认安全规范冲突。
+3. **验证**：每次写入后，用文档中的 **读命令对同一 `id` 再拉一次**（例如 `ad campaign-status` 后 `ad campaigns --json` 看 `statusV2`；`adgroup-edit` 后 `ad groups --json` 看 `maxCPCAmount` / `targetCpaAmount`）。
+4. **`forewarning`**：仍是丝路赞侧 **微信通知** 的可选通道；宿主已有独立通知 skill 时，**不必**重复依赖 `forewarning` 完成「告警」——二者可并行或只选其一。
+
+更具体的 **检查项 ↔ 命令** 见 **`references/hosted-automation-self-control.md`**（三类自控）；异常监控 **`--json` 键名** 见 **`references/hosted-automation-monitoring-json.md`**；**自动优化（降价/扩量/A/B）** 见 **`references/hosted-automation-optimize-index.md`**（分文件 SOP）；主题入口 **`references/hosted-automation-scenarios.md`**。总览见 **`references/workflows.md`**「宿主编排下的投放自控」。
+
+
 ## Skill要如何使用
 
 ### 报告的生成
@@ -75,6 +97,8 @@ allowed-tools: Bash(siluzan-tso:*) Read
   - 这种报告你无法用它来做数据分析除非用户明确要求（Siluzan平台的优化报告）
 - （推荐，默认生成这种报告）由你主动拉取数据，并按照skill给出的格式，输出给用户：详情请查看（`references/account-analytics.md`）
 
+**写报告前必读（账户 vs 系列）**：`stats` / `balance` / `list-accounts` 里的账户 `status` 只表示**广告账户**是否可用，**不能**当作**广告系列**是否启用；系列是否投放须用 `ad campaigns`（及 CLI 派生的 `statusDisplay` 等）。详见 `references/account-analytics.md`「账户状态 ≠ 广告系列状态」。
+
 ### 广告账户相关
 
 - 广告账户开户请阅读： `references/open-account-by-media.md`
@@ -87,7 +111,7 @@ allowed-tools: Bash(siluzan-tso:*) Read
 - Google广告优化记录功能(`references/optimize.md`)，这个也跟优化报告类似，你调用接口，Siluzan平台按照一定的优化逻辑自动执行，你只能查询到结果，不能控制优化流程 注意不要与`google-ads.md`中的优化流程混淆两个是互相独立的功能，`references/google-ads.md`中的优化功能更为强大，在实际的优化过程中，也推荐使用`references/google-ads.md`中提供的内容
 - TikTok / Meta 线索表单请阅读：`references/clue.md`
 - Siluzan平台提供的预警功能请阅读：`references/forewarning.md`
-  - 预警由Siluzan平台发送，当前仅支持微信推送，如果需要自定义的通知触达端，需要安装对应插件或skill+创建定时任务来完成
+  - 预警由 Siluzan 平台发送，当前仅支持微信推送。若监控与通知由 **OpenClaw / WorkBuddy 等宿主**承担，可将 `forewarning` 仅作补充或不用；自定义触达仍可用宿主插件 / skill + 定时任务（见上文职责划分）。
 - 转账、开票、发票抬头、充值网页引导请阅读：`references/finance.md`
 -
 
@@ -121,9 +145,12 @@ allowed-tools: Bash(siluzan-tso:*) Read
 
 ### 硬规范
 
+- **出报告时账户状态 ≠ 广告系列状态**：`stats` / `balance` / `list-accounts` 中的 `status`（如 Enabled）只表示**广告账户**关联/可用，**绝不能**据此填写或推断**各广告系列**是否「启用/在投」。已暂停或移除的系列若被写成启用，属于严重错误。系列是否启用**必须**来自 `ad campaigns`（或系列维报表中的系列状态）。详见 `references/account-analytics.md`「账户状态 ≠ 广告系列状态」。
 - **不确定时读文档**：遇到不熟悉的命令，先读对应 references 文件或使用-h查看命令帮助，不要猜参数。
 - **先查账户再操作**：对具体账户做操作前，先通过 `list-accounts -m [mediaType] -k [mediaCustomerId]` 确认。特别是不确定是Google/Bing/TikTok这些媒体平台中的哪一个的时候
-- **使用 --json 处理数据**：需对返回数据做计算或筛选时，加 `--json`，再用 `node -e` 过滤提取（见 `references/tips.md`）。
+- **使用 --json 处理数据**：需对返回数据做计算或筛选时，加 `--json`，再用 `node -e` 过滤提取（见 `references/tips.md`）。若用户**已有一份 JSON**（文件或剪贴板），只问如何筛选时：优先给「stdin / 读本地文件 + `node -e`」的通用写法，不必默认再跑一遍业务命令。
+- **CLI 输出忠实**：向用户引用 JSON 时，账户 ID、金额等须与**本次命令 stdout 一致**，不得换成别的示例 ID。禁止编造「stub/示例环境/登录异常」等**未在 CLI 输出或 stderr 中出现**的解释；`data` 为空时只说明「当前返回无记录」并附上原始 JSON。
+- **用户明确要求原始 JSON**：须在回复中给出 CLI 返回的 JSON（或完整代码块），不得以长篇推测替代交付。
 - **不要猜测账户 ID**：`entityId` ≠ `mediaCustomerId`，两者均来自 `list-accounts`。
 - **媒体类型区分大小写**：`Google`、`TikTok`、`MetaAd`、`BingV2`、`Kwai`。
 - **命令透明性**：以简洁的方式向用户说明即将执行的操作意图（如「正在查询您的 Google 账户列表」「正在为账户 xxx 创建预警规则」），让用户了解操作进度。用户主动要求查看执行细节时，应如实提供完整命令。
@@ -139,17 +166,30 @@ allowed-tools: Bash(siluzan-tso:*) Read
    > （A）最近完整自然周（周一到周日）
    > （B）本月 1 号到昨天
    > （C）自定义起止日（请告诉我 `YYYY-MM-DD` 起止）
-2. 用户给出范围后，**在报告首行显式标注"统计区间：YYYY-MM-DD ~ YYYY-MM-DD（时区：用户本地/UTC）"**，与调用参数保持完全一致。
+2. 用户给出范围后，**在报告首行显式标注** `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`（与 `references/account-analytics.md` 一致），与调用参数保持完全一致。
 3. **只有在用户明确说"按你默认来 / 你决定"**时，才使用下方默认值白名单。
 
+### 时间范围反问的例外（不要机械套用到下列任务）
+
+- **`list-accounts` 全量**：用户要「所有 Google 账户」且 JSON 时，看返回里的 `total` / `page` / `pageSize`；若 `itemCount < total`，须翻页（增大 `--page-size` 或循环 `--page`）或说明**当前仅为第 N 页**，不得把单页当成全量结论。
+- **「昨天」单日 stats**：用户已给出 Google `mediaCustomerId` 且只说「昨天」时：默认按 **`Asia/Shanghai` 日历日**换算昨日起止；**先** `list-accounts -m Google -k <id> --quick --json` **再** `stats -m Google -a <id> --start … --end … --json`，不要为时区再打断一轮（除非用户明确要求 UTC/其他时区）。
+- **仅持有 `entityId`**：**禁止**把 `entityId` 传给 `stats -a` / `balance -a`。应先 `list-accounts`（必要时 `--json` + 本地筛选或 `-k` 缩小范围）解析出 `mediaCustomerId` 后再调 `stats`。
+- **`forewarning records`**：见 `references/forewarning.md`，不要求先做投放类日期反问。
+- **`invoice list` /「本月」**：见 `references/finance.md`，可用当月 1 日~昨天直接查。
+- **TikTok `clue`「最近一周」**：见 `references/clue.md`，可直接 `--json` 查询，不要先做 A/B/C 日期口径反问。
+
+### 仅输出 JSON 的交付
+
+用户明确要求「**只输出**一个 JSON / 除 JSON 外不要文字」时：回复中**仅含一个** JSON 代码块，内容与本次 CLI **stdout 完全一致**（分页、失败体均如此）；失败时 CLI 已保证 `--json` 下 stdout 仍为 JSON 对象。
+
 ### 默认值白名单（仅在用户明确授权"你决定"时才能使用）
 
 | 场景                    | 允许的默认窗口                                        |
 | ----------------------- | ----------------------------------------------------- |
-| 日常投放巡检 / 余额扫描 | `now - 7d` ~ `now`（本地时间）                        |
+| 日常投放巡检 / 余额扫描 | `now - 7d` ~ `now - 1d`（本地时间）                        |
 | 周报                    | 上一个完整自然周（周一 00:00 ~ 周日 23:59）           |
 | 月报                    | 上一个完整自然月（1 号 ~ 月末）                       |
-| Google 关键词/系列分析  | `now - 30d` ~ `now`（与 TSO Google 接口最小窗口对齐） |
+| Google 关键词/系列分析  | `now - 30d` ~ `now - 1d`（与 TSO Google 接口最小窗口对齐） |
 | MetaAd 账户分析         | 不得默认，必须问（Meta 接口对窗口敏感）               |
 
 ### 金额与货币单位硬约束
@@ -166,6 +206,7 @@ allowed-tools: Bash(siluzan-tso:*) Read
   2. `list-accounts` 返回的 `mag.advertiserName`
   3. 用户提供的网址 → 明确告诉用户"使用域名作为占位"（例如 `hy-steelpipe.com`）并在交付物里标注 `[待确认品牌名]`
 - **严禁**"hy-steelpipe.com"这样的英文域名被输出成类似"海悦钢管"这种虚构中文品牌。
+- 正文里写出品牌名时，应能回溯到上述来源（可写「来自 list-accounts 的 `mag.advertiserName`：…」）；**禁止**写看似真实但未在上述来源或 CLI 输出中出现的名称（包括常见 Demo 风格占位名）。
 
 ### 批量任务硬约束（≥ 5 个账户或系列）
 
@@ -206,6 +247,8 @@ allowed-tools: Bash(siluzan-tso:*) Read
   - 发票申请（`invoice apply`）— 涉及财务
   - 广告发布（`ad batch publish` / `ad campaign-create`）— 涉及预算消耗
 - **只读操作可自主执行**：查询类命令（`list-accounts`、`balance`、`stats`、`report list`、`config show` 等）可直接执行，无需额外确认
+- **Google 广告结构性改动（否定词/系列/关键词等）**：须遵守 `references/google-ads.md` 开篇流程——先阅读规则文档、再列计划与将参考的文档清单；**仅在用户明确确认方案后**才可执行写命令。用户未确认前，不得使用「拿到参数就立刻执行」等措辞暗示可跳过确认。
+- **Google 开户（CLI 指引）**：`open-account google-wizard` 仅适用于真实 TTY；**Agent/自动化环境一律用非交互** `open-account google ...`，审核进度用 `account-history`（详见 `references/workflows.md` 流程一）。向用户写步骤时，把上述禁令放在指引**最前**，再给可复制命令。
 
 ---
 
@@ -217,15 +260,16 @@ allowed-tools: Bash(siluzan-tso:*) Read
 
 > 触发关键词：某账户数据 / 投放情况 / 整理账户 / 看下某个账户的表现
 
-1. **反问时间范围**（参见"时间范围强制反问"）。
+1. **反问时间范围**（参见"时间范围强制反问"；用户已授权「按默认」时用默认值白名单并写明区间）。
 2. `list-accounts -m Google -k <mediaCustomerId> --quick --json`
    - 一次拿齐：账户基础信息、创建日期、当前状态、公司名（`mag.advertiserName` 作为品牌名）
-3. `stats --media Google --accounts <id> --start-date <S> --end-date <D> --json`
-   - 拿该区间消耗、点击、转化等；**直接读响应中的主币种数值**，不要再 ×100。
-4. `ad campaigns --account <id> --start-date <S> --end-date <D> --json`
+3. `siluzan-tso stats -m Google -a <mediaCustomerId> --start <S> --end <D> --json`（`--start-date` / `--end-date` 与 `--start` / `--end` 等价）
+   - 拿该区间消耗、点击、转化等；**直接读响应中的主币种数值**，不要再 ×100。若返回 `{"ok":false,"error":...}`，须原样展示并**不得**用系列数据编造账户级 stats。
+4. `siluzan-tso ad campaigns -a <mediaCustomerId> --start <S> --end <D> --json`
    - 拿广告系列类型（Search / PMax / Display 等）、日预算（**用 `budgetDisplay`**）、优化得分相关字段。
 5. `stats` 结合 `accountsoverview` 字段派生"开始投放时间 / 有效投放天数 / 地区消耗分布"（如接口暂未直出，在 node 里聚合）。
 6. 用 `report-templates/google-account-diagnosis-report.md` 模板输出，**首行标注统计区间和货币**。
+7. 用户要求「先拉 JSON 再文字总结」时：回复中须包含实际 `--json` 输出（完整或明确声明截断），再写总结；**禁止**用未出现在这些 JSON / `list-accounts` 中的字段写品牌名或接口状态。
 
 ### P2 · 多账户余额扫描 / 预算预警（典型指令："117 个 Bing 账户不足 7 天的挑出来"）
 
@@ -276,8 +320,9 @@ siluzan-tso accounts-digest -m Google \
 
 1. **反问时间范围**（P 级硬约束），拿到用户回复后再执行 `accounts-digest`。
 2. 如命令已返回 `--json`，直接基于其中 `data.items` 与 `meta.totals` 生成报告；**不要**再逐账户 `stats`。
-3. 跨币种账户：按 `item.currencyCode` 分表或在 meta.currencyNote 提示的前提下分币种小计。
-4. 金额字段严格按"金额与货币单位硬约束"处理。
+3. **多账户 `-a id1,id2,...` 时**：表格须覆盖用户请求的**每一个** ID；若某 ID 在 `data.items` 中未出现，仍占一行并标注「未返回/无数据」，并说明与 `meta.totals` 的关系；**禁止**只展示子集却声称已完成多账户汇总。
+4. 跨币种账户：按 `item.currencyCode` 分表或在 meta.currencyNote 提示的前提下分币种小计。
+5. 金额字段严格按"金额与货币单位硬约束"处理。
 
 ### P4 · Google 账户周期报告（典型指令："生成 2026.1.1-2026.4.15 的报告"）
 
@@ -286,6 +331,7 @@ siluzan-tso accounts-digest -m Google \
 3. 使用 `report-templates/google-period-report.md` 模板输出。
 4. 首行必须有：`统计区间：2026-01-01 ~ 2026-04-15` + `货币：XXX`。
 5. 报告必须包含：账户概览、投放趋势、Top 关键词/系列 / 地区分布 / 优化建议；不得编造未拉取到的指标（例如没拉取到的关键词就写"未提供"而不是估算）。
+6. 品牌名遵守上文「品牌名 / 公司名来源硬约束」；描述系列启停时只引用 `ad campaigns`（或系列维报表）中的系列级状态字段，勿与账户 `status` 混用。
 
 ---
 
@@ -326,33 +372,28 @@ HTML 报告模板（`report-templates/*.html`）引用了以下外部 CDN 资源
 
 ---
 
-## 下面是一部分比较实用的自动化场景，当你回答完用户问题后，可以把下面的内容输出给用户，方便用户使用
+## 风险预警，预算&ROI 控制引擎，异常监控与报警系统，自动优化，自动化风控详情可见`references/hosted-automation-user-catalog.md`
+
+当加载这个skill时，必须主动跟用户介绍你还可以通过这个skill完成以下功能
 
-您可以选择以下的预警或提醒，输入需想要执行的内容核实规则即可配置。
+1. 单日预算熔断	每日消耗达到设定值，自动暂停计划，杜绝 Google 超额扣费。
+2. CPA 飙升自动降价	光点不转化（如花费超过3倍目标成本），自动关停该条烂广告。
+3. 连续空耗自动暂停	大盘流量变贵、获客成本飙高时，系统自动下调出价避险。
 
-### 预算 & ROI 控制引擎
+1. 账户被封禁	
+2. 落地页死链强停	网站宕机或链接填错，紧急自动暂停关联广告，防止把钱扔水里。
+3. 广告素材拒审	发现被 Google 封号或快没钱了，立刻发送企微/钉钉高优强提醒。
+4. 花费异动监控	花费突然暴涨或断崖式下跌，系统即时报警提示人工盯盘。
+5. 余额枯竭预警	广告被 Google 拦截，系统自动帮你打包违规原因并定时推送。
 
-| 提醒名称            | 系统在后台默默帮你做什么？(自动动作)                      |
-| ------------------- | --------------------------------------------------------- |
-| 1. 单日预算熔断     | 每日消耗达到设定值，自动暂停计划，杜绝 Google 超额扣费。  |
-| 2. CPA 飙升自动降价 | 光点不转化（如花费超过3倍目标成本），自动关停该条烂广告。 |
-| 3. 连续空耗自动暂停 | 大盘流量变贵、获客成本飙高时，系统自动下调出价避险。      |
+1. 表现差广告降价/关停	发现转化极好的“好苗子”，以安全幅度自动涨预算/提价去抢量。
+2. 高转化广告 提价扩量"	连续几天表现垫底的垃圾素材，系统扮演无情杀手自动关停。
+3. A/B测试 自动决出胜者"	科学赛马，根据真实转化价值自动关停输家，把流量全给赢家。
 
-### 异常监控与报警系统
 
-| 功能名称          | 监控层级 / 说明                                             |
-| ----------------- | ----------------------------------------------------------- |
-| 1. 账户被封禁     |                                                             |
-| 2. 落地页死链强停 | 网站宕机或链接填错，紧急自动暂停关联广告，防止把钱扔水里。  |
-| 3. 广告素材拒审   | 发现被 Google 封号或快没钱了，立刻发送企微/钉钉高优强提醒。 |
-| 4. 花费异动监控   | 花费突然暴涨或断崖式下跌，系统即时报警提示人工盯盘。        |
-| 5. 余额枯竭预警   | 广告被 Google 拦截，系统自动帮你打包违规原因并定时推送。    |
+## 这里有一些对应平台的输出格式文档当你需要使用webhook或其他方式发送消息时可以先阅读下面的文档获取平台的语法规范再生成：
 
-### 自动优化
+企业微信文档：https://developer.work.weixin.qq.com/document/path/99110
+飞书文档：https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot#f62e72d5
 
-| 功能名称                | 监控层级                                                                   |
-| ----------------------- | -------------------------------------------------------------------------- |
-| 1. 表现差广告降价/关停  | 发现转化极好的「好苗子」，以安全幅度自动涨预算/提价去抢量。                |
-| 2. 高转化广告提价扩量   | 连续几天表现垫底的垃圾素材，系统扮演无情杀手自动关停。                     |
-| 3. A/B测试自动决出胜者  | 科学赛马，根据真实转化价值自动关停输家，把流量全给赢家。                   |
-| 4. 异动根因自动排查建议 | 老板问为什么成本翻倍？系统一键生成诊断报告（揪出外部竞对或内部操作失误）。 |
+其他平台，可以默认使用markdown输出

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.13",
-  "publishedAt": 1776762370285
+  "version": "1.1.14-beta.10",
+  "publishedAt": 1777371470961
 }

package/dist/skill/references/account-analytics.md

@@ -16,12 +16,29 @@
 5. 输出 HTML 时：**默认**以 `report-templates/report-template.html` 为样式基准（适用于一切总结性、报告性、汇总性成稿）；若场景更适合作正式件、深色、单页等，再从 `report-templates/report-template*.html` 中选或询问用户，并对照 `report-templates/README.md`
 6. 注意最终交付的是用html生成的PDF
 7. 使用浏览器或能够打开html/pdf的插件帮用户打开报告
-8. **报告首行**必须标注：`统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`，与实际调用 `--start` / `--end` 一致。
+8. **报告首行**必须标注：`统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`，与实际调用 `--start` / `--end` 一致。**禁止**用「上周 / 本月 / 近 7 天」等口语替代首行日期；若用户口语指区间，先在首行写换算后的起止日。
 
 用于按账户维度拉取 Google Ads 报表、结构类数据。
 
 ## 报告中的硬约束（必须遵守）
 
+### 账户状态 ≠ 广告系列状态（出报告最高优先级）
+
+**常见错误**：Agent 看到 `stats`、`balance` 或账户列表里 `status: Enabled`（或「账户正常」），就在报告中把**广告系列**写成「启用」「在投」。这会导致**已暂停、已结束排期或已从投放层面移除**的系列被误标为启用。
+
+| 含义 | 数据来源（示例） | `status` / 状态字段表示什么 |
+|------|------------------|-----------------------------|
+| **广告账户**是否在媒体侧关联可用、能否拉数 | `stats`、`balance`、`list-accounts` | 账户级启用/可用，**不描述单个系列是否在投** |
+| **广告系列**是否暂停、是否在排期内可投放 | **`ad campaigns`**（含 `statusDisplay` 等）、系列维报表 | 系列级启停；**唯一**用于写「某系列启用/暂停」 |
+
+**写报告时的硬性规则**：
+
+1. **禁止**用 `stats` / `balance` / `list-accounts` 返回的账户 `status` 推断或概括**广告系列**是否启用；不得在报告正文写「根据账户状态，各系列均为启用」这类表述（除非已逐条用 `ad campaigns` 核对）。
+2. **凡是**描述「某广告系列是否投放 / 启用 / 暂停 / 移除」，**必须**基于 `siluzan-tso ad campaigns -a <mediaCustomerId> --json`（或 `google-analysis` 中带系列粒度、含系列状态的数据）。账户总览里的消耗/点击可以与系列表并列，但**系列状态列不得来自账户接口**。
+3. 若报告中有「账户概况」与「广告系列明细」两块：前者可用账户级接口；后者**系列状态列只能**来自系列级接口（如 `statusDisplay`），与账户 `status` **不得混为一谈**。
+
+**一句话**：账户「能用 / Enabled」≠ 系列「在投」；系列是否启用只看系列级数据（首推 `ad campaigns`）。
+
 ### 品牌名 / 公司名来源
 
 生成带品牌名、方案、邮件、广告文案的报告时，**严禁自行生成品牌名（包括中文译名、拼音、意译）**。品牌名必须来自以下来源之一，按优先级：
@@ -65,10 +82,54 @@
 
 ---
 
+### CampaignSectionData（`campaigns[]`）
+
+**路由**：`GET …/reporting/media-account/{mediaCustomerId}/CampaignSectionData?startDate=&endDate=`（以及 TikTok 等媒体在路径中插入媒体段，如 `…/TikTok/{id}/CampaignSectionData?…`）。
+
+**CLI**：Google 为 `siluzan-tso google-analysis campaigns`；TikTok 为 `siluzan-tso report tiktok-campaigns`（另带 `take`，默认 100）。
+
+`campaigns` 数组每一行在既有指标外，另包含：
+
+| 字段 | 说明 |
+| --- | --- |
+| `conversionsValue` | 转化价值 |
+| `conversionsValuePerCost` | 转化价值相对消耗；接口按 **`conversionsValue / spend`** 计算，当 **`spend ≤ 0`** 时为 **`0`** |
+| `campaignTargetCpaMicros` | 系列目标 CPA（微货币单位） |
+| `maximizeConversionsTargetCpaMicros` | 「尽可能提高转化次数」下的目标 CPA（微货币单位） |
+| `manualCpcEnhancedCpcEnabled` | 人工 CPC 是否启用增强 CPC |
+| `percentCpcEnhancedCpcEnabled` | 百分比 CPC 是否启用增强 CPC |
+
+展示微货币字段时须按账户 `currencyCode` 换算为金额，**不要**把 micros 直接当元展示。
+
+---
+
+### campaign-hour（系列按小时）
+
+**路由**：`GET {googleApiUrl}/reporting/media-account/{mediaCustomerId}/campaign-hour?startDate=&endDate=`（与 `google-analysis` 其它带区间接口相同，**`--start` / `--end` 须同传或同省略**）。
+
+**CLI**：`siluzan-tso google-analysis campaign-hour -a <mediaCustomerId> [--start YYYY-MM-DD --end YYYY-MM-DD] --json`
+
+响应体为 **JSON 数组**（非 `{ campaigns: … }` 包装）。元素常见字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `campaignId` | 广告系列 ID |
+| `campaignName` | 广告系列名称 |
+| `date` | 日期 |
+| `hour` | 小时 |
+| `spend` | 消耗 |
+| `impressions` | 展示 |
+| `clicks` | 点击 |
+| `conversions` | 转化 |
+
+---
+
 ### google-analysis
 
 使用已配置的 `googleApiUrl` 与 Token，无需手写 curl。
 
+> **路由（重要）**：用户要「关键词花费 / 点击 / 转化 / CPA」等**搜索关键词维度**表现时，须用 **`siluzan-tso google-analysis keywords -a <mediaCustomerId> [--start/--end] --json`**。不要用 `ad keywords` 代替（后者偏结构/出价与列表字段，与命题中的「账户内关键词报表」不是同一路径）。
+
 ```text
 siluzan-tso google-analysis <子命令> -a <mediaCustomerId> [选项]
 ```
@@ -83,7 +144,7 @@ siluzan-tso google-analysis <子命令> -a <mediaCustomerId> [选项]
 | `-t, --token`       | 鉴权 Token（可选，默认读配置）                            |
 | `--verbose`         | 打印详细错误                                              |
 
-**子命令与网关路径对应**
+**子命令与拉数路径**
 
 | 子命令               | 说明                                                                                    |
 | -------------------- | --------------------------------------------------------------------------------------- |
@@ -91,6 +152,7 @@ siluzan-tso google-analysis <子命令> -a <mediaCustomerId> [选项]
 | `keywords`           | 关键词 `KeywordSectionData`；可选 `--limit`、`--no-order-by-cost`                       |
 | `search-terms`       | 搜索词 `searchtermmanagement/v2/list`；同上                                             |
 | `campaigns`          | 系列 `CampaignSectionData`                                                              |
+| `campaign-hour`      | 系列按小时 `campaign-hour`（`?startDate=&endDate=`；**根为 JSON 数组**）                 |
 | `ads`                | 广告 `admanagement/v2/list`                                                             |
 | `extensions`         | 附加信息 `extensionmanagement/v2/list`；可选 `--level`（Account / Campaign / Ad Group） |
 | `devices`            | 设备 `DeviceSectionData`                                                                |
@@ -108,14 +170,19 @@ siluzan-tso google-analysis <子命令> -a <mediaCustomerId> [选项]
 | `dimension-summary`  | 账户汇总 `reports/combined`                                                             |
 | `campaign-types`     | 系列类型（**不要**传 `--start`/`--end`）                                                |
 
+`ads` 与 **`ad list`** 同源；带日期区间时创意可能 **按日多行**，宿主编排（降价/扩量/A/B）见 **`references/hosted-automation-optimize-index.md`**。
+
 **示例**
 
 ```bash
 siluzan-tso google-analysis overview -a 6326027735 --start 2026-03-01 --end 2026-03-31 --json
 siluzan-tso google-analysis keywords -a 6326027735 --limit 50
+siluzan-tso google-analysis campaign-hour -a 6326027735 --start 2026-03-01 --end 2026-03-07 --json
 siluzan-tso google-analysis final-urls -a 6326027735 --json
 ```
 
+**CPC / 花费异常巡检（先查后停）**：用户要先定位异常再考虑暂停时，在确认统计区间后，优先用 `google-analysis` 拉**带花费/CPC 粒度**的数据（如 `campaigns`、`campaign-hour`、`daily-metrics`、`keywords` 等，按 CLI `siluzan-tso google-analysis --help` 选择子命令），**不要**在未拉数前就把暂停阈值与写操作一并推进；暂停类命令须遵守 `references/google-ads.md` 的确认流程。
+
 ---
 
 ## Meta 账户分析总览（TSO）

package/dist/skill/references/accounts.md

@@ -66,7 +66,7 @@ siluzan-tso account-active-bills -m <媒体> --id <entityId> [--json]
 | `--id <entityId>`    | 必填：账户 `entityId`                                                                |
 | `--json`             | 输出接口原始 JSON                                                                    |
 
-**响应体常用字段（以后端为准）：**
+**响应体常用字段（以接口返回为准）：**
 
 | 字段                                              | 说明                                                                                              |
 | ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
@@ -108,7 +108,7 @@ siluzan-tso balance -m <媒体类型> -a <账户ID列表>
 | ---------------------- | ------------------------------------------------------------------------------------ |
 | `-m, --media <type>`   | 媒体类型（必填）                                                                     |
 | `-a, --accounts <ids>` | 账户 `mediaCustomerId`（数字 ID），多个用逗号分隔（必填）。**注意：不是 `entityId`** |
-| `--json`               | 输出原始 JSON                                                                        |
+| `--json`               | 输出原始 JSON；不支持或查询失败时 stdout 为 `{"ok":false,"error":"..."}`              |
 
 **示例：**
 
@@ -123,6 +123,8 @@ siluzan-tso balance -m TikTok -a 1234567890,9876543210
 siluzan-tso balance -m Google -a 6326027735 --json
 ```
 
+**单户余额与续航**：`balance` 只反映当前余额；判断「还能跑几天 / 是否够花」需结合 `stats`（或业务侧日均消耗）等数据。向用户展示 JSON 时，`mediaCustomerId` 须与本次 `-a` 查询的 ID 及命令输出一致。
+
 ---
 
 ## stats — 查询投放消耗数据
@@ -137,7 +139,8 @@ siluzan-tso stats -m <媒体类型> [选项]
 | `-a, --accounts <ids>` | 账户 `mediaCustomerId`（数字 ID），逗号分隔（**必填**，接口不支持查全部账户） | —      |
 | `--start <YYYY-MM-DD>` | 开始日期                                                                      | 7 天前 |
 | `--end <YYYY-MM-DD>`   | 结束日期                                                                      | 昨天   |
-| `--json`               | 输出原始 JSON                                                                 | —      |
+| `--start-date` / `--end-date` | 与 `--start` / `--end` 同义（CLI 别名，与 SKILL Playbook 一致）          | —      |
+| `--json`               | 输出原始 JSON；**失败时 stdout 仍为 JSON**（`{"ok":false,"error":"..."}`）     | —      |
 
 **示例：**
 
@@ -514,7 +517,7 @@ siluzan-tso open-account kwai \
 >
 > 对应网页：`/foreign_trade/tso/manageAccounts` → 选中 TikTok 账户 → 关闭账户
 >
-> **实现说明（与网页 `manageAccounts` 一致）**：先请求 TikTok 网关 `CheckAdvDisable`（不满足条件如余额未清零会失败），再 `POST .../AdvertiserDisable`；Body 为各账户的 **entityId**。你只需传入 `list-accounts` 中的 **mediaCustomerId**，CLI 会解析 entityId；旧版误把 mediaCustomerId 当 Body 会导致 HTTP 成功但关户不生效。
+> **实现说明（与网页 `manageAccounts` 一致）**：先经 TikTok 侧 `CheckAdvDisable` 校验（不满足条件如余额未清零会失败），再 `POST .../AdvertiserDisable`；Body 为各账户的 **entityId**。你只需传入 `list-accounts` 中的 **mediaCustomerId**，CLI 会解析 entityId；旧版误把 mediaCustomerId 当 Body 会导致 HTTP 成功但关户不生效。
 
 ```bash
 siluzan-tso account close --accounts <mediaCustomerId>
@@ -689,7 +692,7 @@ siluzan-tso account email-auth-list -c <mediaCustomerId> [--agent-type <type>]
 | 选项                     | 说明                                                                       |
 | ------------------------ | -------------------------------------------------------------------------- |
 | `-c, --customer-id <id>` | Google 广告账户 `mediaCustomerId`（与网页查询参数 `customerId` 一致）      |
-| `--agent-type <type>`    | 可选；网关需要时再传（与 `list-accounts --json` 的 `ma.accountType` 一致） |
+| `--agent-type <type>`    | 可选；平台需要时再传（与 `list-accounts --json` 的 `ma.accountType` 一致） |
 | `--json`                 | 输出原始 JSON                                                              |
 
 ---

package/dist/skill/references/clue.md

@@ -19,6 +19,11 @@ siluzan-tso clue -m <媒体> -a <账户ID> [选项]
 | `--end <date>`       | Meta 专用：结束日期（YYYY-MM-DD）                                 |
 | `--json`             | 输出原始 JSON                                                     |
 
+**AI 交付**：用户要求「原始 JSON / 自己筛」时，回复中须包含 **`--json` 命令打印的完整 JSON**（或等价完整代码块），并可按上表说明 `custom_fields` / `system_fields`（TikTok）或 `field_data`（Meta）。**禁止**用未出现在本次 CLI 输出中的账户 ID、媒体或「环境异常」类推测替代 JSON 交付。  
+若本次查询失败：CLI 在 `--json` 下会输出 **`{"ok":false,"error":"...","items":[]}`**（stdout），请**原样**贴出该 JSON，不要改成纯文字描述。
+
+**时间范围（TikTok）**：用户说「最近一周」且要拉线索、未给起止日时，**不要**再按投放报表类任务做 A/B/C 反问；直接按 CLI 默认窗口执行 `clue -m TikTok -a <advertiserId> --json`（需自定义区间时再用 Meta 同款 `--start/--end` 仅适用于 Meta，TikTok 以接口返回为准）。
+
 **TikTok 示例：**
 
 ```bash

package/dist/skill/references/finance.md

@@ -7,7 +7,7 @@
 
 ## invoice-info — 发票抬头管理
 
-对应页面：`https://www.siluzan.com/v3/foreign_trade/settings/invoiceInformation`
+对应页面：`https://www-ci.siluzan.com/v3/foreign_trade/settings/invoiceInformation`
 
 发票抬头是开票申请时使用的公司/企业信息模板，支持三种类型：
 
@@ -24,6 +24,8 @@ siluzan-tso invoice-info list -k "公司名关键字"         # 按公司名搜
 siluzan-tso invoice-info list --json                   # 原始 JSON（含 id 字段）
 ```
 
+查询结果若 `data` 为空数组或无可核对字段，表示当前账号下**尚无已保存抬头**：向用户展示**原始 JSON** 并如实说明即可，勿推测「测试桩」等未经 CLI 报错佐证的原因。
+
 ### 新增发票抬头
 
 **PI（形式发票，境外英文）：**
@@ -131,10 +133,10 @@ siluzan-tso config show
 **示例：**
 
 ```
-- 现金充值（单笔）：https://www.siluzan.com/recharge/pay
-- 现金充值（批量）：https://www.siluzan.com/recharge/pay_batch
-- 月结充值：        https://www.siluzan.com/recharge/accountBillingQuota
-- 丝路赞钱包：      https://www.siluzan.com/recharge/siluzanWallet
+- 现金充值（单笔）：https://www-ci.siluzan.com/recharge/pay
+- 现金充值（批量）：https://www-ci.siluzan.com/recharge/pay_batch
+- 月结充值：        https://www-ci.siluzan.com/recharge/accountBillingQuota
+- 丝路赞钱包：      https://www-ci.siluzan.com/recharge/siluzanWallet
 ```
 
 ---
@@ -208,6 +210,8 @@ siluzan-tso transfer create -m Google --out 1234567890 --in 9876543210 --amount
 siluzan-tso invoice list [选项]
 ```
 
+> **与投放报表类任务不同**：用户只说「本月开票记录」而未写起止日时，可用**当月 1 日 ~ 昨天**（`Asia/Shanghai` 日历）直接执行 `invoice list --start … --end … --json`，**不必**先做 SKILL「投放数据」类的时间范围 A/B/C 反问；若用户随后纠正区间再重查即可。
+
 | 选项                     | 说明                   |
 | ------------------------ | ---------------------- |
 | `-k, --keyword <text>`   | 发票号/关键字          |

package/dist/skill/references/forewarning.md

@@ -7,6 +7,7 @@
 ## 功能概述
 
 智能预警允许设置监控规则，当广告账户的消耗、余额、CTR 等指标满足指定条件时，自动通过**微信公众号**发送通知。
+这是siluzan 提供的全链路服务，除非用户提到需要使用这个否则默认不推荐使用这个智能预警
 
 ---
 
@@ -135,6 +136,8 @@ siluzan-tso forewarning list -m Google
 # JSON 格式（含完整配置）
 siluzan-tso forewarning list -m Google --json
 
+若用户要求「仅 JSON / 只输出一个 JSON 对象」，回复中只贴本次命令 stdout（含 `total` > `itemCount` 时的分页说明亦在 JSON 内，勿在 JSON 外再写中文解释）。
+
 # 按账户筛选
 siluzan-tso forewarning list -m Google --account <mediaCustomerId>
 
@@ -146,6 +149,8 @@ siluzan-tso forewarning list -m Google --keyword "消耗"
 
 ## 查询触发记录
 
+> **不属于「投放数据时间范围强制反问」**：用户要查「最近有没有触发记录」并要 JSON 时，**直接**执行 `forewarning records -m Google --json`（可加 `--rule-id` / `--status`）；不要先套用 SKILL 里针对消耗/报表的日期反问，也不要强行索要 Google `mediaCustomerId`（本命令不按媒体账户筛）。
+
 ```bash
 # 查询所有规则的触发记录
 siluzan-tso forewarning records -m Google
@@ -158,6 +163,8 @@ siluzan-tso forewarning records -m Google --status Success
 siluzan-tso forewarning records -m Google --status Failed
 ```
 
+**创建规则（AI）**：用户已给出阈值、频率、媒体并确认要创建时：① `list-accounts -m Google -k <mediaCustomerId> --json` 取账户 **`entityId`**（`forewarning create --accounts` 用）；② `forewarning notify-accounts` 取 **`--notify`** 的微信对象 `entityId`；③ 再执行 `forewarning create ...`。创建属写操作，须用户明确确认后再跑命令。
+
 ---
 
 ## 更新已有规则

package/dist/skill/references/google-ads-rules/google-ads-campaign-optimization.md

@@ -511,10 +511,11 @@ siluzan-tso ad batch get --id <taskId>
 siluzan-tso ad campaigns -a <CID> --json
 
 # 切换到 Target CPA（数据充足后）
+# --target-cpa 是「主币种金额」，CLI 内部自动 ×100 写入；50 = 50 USD（不是微单位 5000）
 siluzan-tso ad campaign-edit -a <CID> --id <系列ID> \
-  --bidding TARGET_CPA --target-cpa 5000  # 50 USD (微单位)
+  --bidding TARGET_CPA --target-cpa 50
 
-# 切换到 Target ROAS
+# 切换到 Target ROAS（ROAS 是比例，不是金额，无需 ×100）
 siluzan-tso ad campaign-edit -a <CID> --id <系列ID> \
   --bidding TARGET_ROAS --target-roas 3.0
 ```