siluzan-tso-cli 1.1.21-beta.4 → 1.1.21-beta.6

package/README.md

@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills  # 写入自定义目录
 siluzan-tso init --force             # 强制覆盖已存在文件
 ```
 
-> **注意**：当前为测试版（1.1.21-beta.4），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+> **注意**：当前为测试版（1.1.21-beta.6），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: siluzan-tso
 description: >-
-  Siluzan TSO 广告 skill（siluzan-tso-cli）：Google/Bing/Yandex/TikTok/Kwai 账户开户与管理、Google Ads CRUD、数据分析、优化报告、智能预警、TikTok/Meta 线索、发票财务，并提供 RAG 知识库查询，google广告关键词推荐；当你发现你的上下文被压缩过后，你需要根据用户的需求，重新阅读本skill相关的文件，保证skill功能正常。
+  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
@@ -76,13 +76,55 @@ Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令
 
 ---
 
+## 文档加载纪律（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 | `assets/pmax-create-template.md` + `references/pmax-api.md` |
+| 拓词 / 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. 读对应 references → 用 `-h` 确认命令 → 向用户输出操作计划
+1. **按「文档加载纪律」Read 当次任务 references**（新任务/换话题必做，勿复用上一轮）→ 用 `-h` 确认命令 → 向用户输出操作计划
 2. 涉及写入/修改/删除的操作必须与用户确认
 3. 按计划执行，说明每步意图
 4. 用成对的读命令复核写入结果；异步任务每 5s 轮询直到完成
@@ -186,8 +228,12 @@ Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令
 
 ## 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`
@@ -196,6 +242,8 @@ Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令
 
 ### P2 · 多账户余额扫描
 
+**必读**：`references/accounts.md`（`balance-scan`）、`references/currency.md`。
+
 **全量巡检**：
 
 ```bash
@@ -215,6 +263,8 @@ siluzan-tso balance-scan -m Google -a id1,id2,id3 --json-out ./snap-p2-subset
 
 ### 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
 ```
@@ -226,6 +276,8 @@ siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --jso
 
 ### 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 关键词/系列/地区分布、优化建议。
@@ -234,6 +286,8 @@ siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --jso
 
 > 适用：账户数 ≥ 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`，可按需追加）。
@@ -264,6 +318,8 @@ siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --jso
 
 > **触发**：用户话术含 `使用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`。
@@ -276,6 +332,8 @@ siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --jso
 >
 > **不要**按 `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`（字段见模板「询盘字段清单」）。

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.21-beta.4",
-  "publishedAt": 1779697477475
+  "version": "1.1.21-beta.6",
+  "publishedAt": 1779702256218
 }

package/dist/skill/references/accounts.md

@@ -124,7 +124,65 @@ siluzan-tso balance -m Google -a 6326027735 --json
 
 **单户余额与续航**：`balance` 只反映当前余额；判断「还能跑几天 / 是否够花」需结合 `stats`（或业务侧日均消耗）等数据。向用户展示 JSON 时，`mediaCustomerId` 须与本次 `-a` 查询的 ID 及命令输出一致。
 
-**少量账户的画像/续航估算**：直接用 `balance-scan -m <媒体> -a id1,id2`（子集模式）一条命令拿齐余额 + 近 7 日消耗 + 续航天数 + 充值建议，比 `balance` + `stats` 拼接更省事；或者用 `accounts-digest -m <媒体> -a id1,id2` 拿齐消耗 + CTR/CPC/CPA 派生指标 + 余额。两者都会跳过清单翻页，直接对指定 ID 拉数据。
+**少量账户续航预警**：用 `balance-scan`（见 `SKILL.md` Playbook P2）；**多账户投放画像汇总**（消耗/点击/转化/余额 + CTR/CPC/CPA）：用下文 **`accounts-digest`**，Skill 编排一律 **`--json-out`**。
+
+---
+
+## accounts-digest — 多账户投放画像汇总
+
+一条命令替代 AI 对每个账户循环 `list-accounts -k` + `stats`。**多账户汇总表、对比消耗、跨账户巡检** 应优先本命令，禁止外层 for-loop 逐户 `stats`。
+
+> **数据时效性**：与 `stats` / `balance-scan` 相同（Google `account-spend-overview` 分流；TikTok/Yandex/BingV2/Kwai 为截至昨天的 `accountsoverview`）。完整表见 `references/account-analytics.md` 顶部。
+
+```bash
+siluzan-tso accounts-digest -m <媒体类型> [选项]
+```
+
+| 选项 | 说明 | 默认 |
+| ---- | ---- | ---- |
+| `-m, --media <type>` | 媒体类型（必填）：`Google \| TikTok \| Yandex \| BingV2 \| Kwai`（**MetaAd 无消耗汇总接口**） | — |
+| `-a, --accounts <ids>` | 指定 `mediaCustomerId`，逗号分隔；**留空**则翻页拉该媒体全部账户 | — |
+| `--start <YYYY-MM-DD>` | 统计开始日期（SKILL 要求 AI 先与用户确认区间） | 近 7 天 |
+| `--end <YYYY-MM-DD>` | 统计结束日期 | 昨天 |
+| `--min-spend <n>` | 过滤：区间内消耗 ≤ 此值的账户不返回 | `0` |
+| `--page-size <n>` | 全量扫描时清单分页大小（上限 500） | `200` |
+| `--max-pages <n>` | 全量扫描时最多页数（上限 200） | `20` |
+| `--json` | stdout 输出完整 JSON（与 `--json-out` 互斥） | — |
+| `--json-out <path>` | **Agent 推荐**：落盘目录或 `*.json` 文件；stdout 一行摘要（含 `outlineFile`、`writtenFiles`、`manifestFile`） | — |
+
+**`--json-out` 落盘（Agent 必读）**：
+
+- 目录模式典型文件：`accounts-digest-<媒体小写>.json`（如 `accounts-digest-google.json`）、同 stem 的 `accounts-digest-google.outline.txt`、`cli-manifest-<媒体小写>.json`。
+- 处理顺序见 `references/tips.md`：先 stdout 摘要 → 再 `outlineFile` → 再 `require(writtenFiles[0])` 读真实数据；**禁止**在对话里手填 `data.items` 中的业务数。
+- 响应结构：`{ ok, data: { items: [...] }, meta: { media, window, scanned, returned, source, totals, currencyNote, generatedAt } }`。
+- `meta.source`：`list` = 全量翻清单后拉数；`subset` = 传了 `-a`，跳过清单翻页（**`advertiserName` 会缺失**，公司名列显示 `-`）。
+
+**与 `stats` / `balance-scan` 的分工**：
+
+| 场景 | 推荐 |
+| ---- | ---- |
+| 多账户消耗/点击/转化/CTR/CPC/CPA 汇总表 | `accounts-digest` + `--json-out` |
+| 余额续航不足 N 天、充值预警 | `balance-scan` + `--json-out` |
+| 单账户、必须逐户精确字段 | `stats` / `balance`（仍须 `-a` 单户或少量 ID） |
+
+**示例：**
+
+```bash
+# 指定账户子集（跳过清单翻页，Playbook P3）
+siluzan-tso accounts-digest -m Google -a 6326027735,4256317784 \
+  --start 2026-04-01 --end 2026-04-15 \
+  --json-out ./snap-p3
+
+# 扫描某媒体全部账户（内部翻页，勿先 list-accounts 再拼 -a）
+siluzan-tso accounts-digest -m BingV2 --start 2026-05-01 --end 2026-05-24 \
+  --json-out ./snap-digest-bing
+
+# 过滤低消耗账户
+siluzan-tso accounts-digest -m Google -a id1,id2 --min-spend 10 \
+  --start 2026-04-01 --end 2026-04-15 --json-out ./snap-p3
+```
+
+**`data.items[]` 主要字段**：`mediaCustomerId`、`name`、`advertiserName`、`currencyCode`、`balance`、`spend`、`impressions`、`clicks`、`conversions`、`ctr`（%）、`cpc`、`cpa`。跨币种汇总见 `references/currency.md`（**禁止**对 `meta.totals` 跨币种直接当最终结论）。
 
 ---
 

package/dist/skill/references/tips.md

@@ -1,5 +1,7 @@
 # CLI 使用技巧：`--json-out` 落盘 + Node.js 精准查询
 
+> **文档重读（与落盘无关，但同样硬）**：**每个新的用户任务**或**同对话内换话题**时，须按 `SKILL.md`「文档加载纪律」**重新 Read** 当次任务对应的 `references/*.md` / `report-templates/*.md`，再执行 CLI。**禁止**因上一轮已读过某 reference 而跳过（参数、批量命令、Playbook 编号会随任务变化）。
+
 > **AI 助手（本 Skill）**：凡需结构化数据，一律使用 **`--json-out <路径>`**（**目录** 或 **`*.json` 具体文件**）将 JSON 写入磁盘（并更新 **`cli-manifest[-<查询id>].json`**，与 `google-analysis` 的 **`manifest-<accountId>.json`**、`report …` 的 **`report-manifest[-<accountId>].json`** 并存于各自目录），再用 **脚本读文件**（`fs.readFileSync` / `require`）做筛选与聚合；**不要**依赖对话里粘贴的 stdout 整包 JSON。命令成功时 **stdout 仅一行摘要 JSON**（体积小），其中 **`outlineFile`** 指向与当次 `*.json` **同 stem** 的 **`*.outline.txt`**（纯文本单行，接近 **TypeScript 类型字面量**：`{ a: number; b: string }`、`(T | U)[]` 等；数组由**前 8 项**去重推断并集；环 / 同对象再出现为 `any`）。完整数据仍以落盘 `*.json` 为准，类型扫一眼读 outline 文件即可。
 >
 > **文件命名规则（重要）**：当一条命令具备明确的"查询 id"（mediaCustomerId / entityId / ruleId / auditId 等）时，目录模式落盘的 `*.json`、`*.outline.txt` 与对应 manifest **都会带上 `-<查询id>` 后缀**：
@@ -139,6 +141,30 @@ list
 "
 ```
 
+### 3b. 多账户投放画像（`accounts-digest`）
+
+多账户汇总消耗/点击/转化时**优先** `accounts-digest`，不要对每个账户循环 `stats`（见 `SKILL.md` Playbook P3、`references/accounts.md` § accounts-digest）。
+
+```bash
+siluzan-tso accounts-digest -m Google -a id1,id2,id3 \
+  --start 2026-04-01 --end 2026-04-15 \
+  --json-out ./snap-p3
+node -e "
+const path = require('path');
+const snap = './snap-p3';
+const d = require(path.join(snap, 'accounts-digest-google.json'));
+const rows = d.data?.items || [];
+const meta = d.meta || {};
+console.log('区间:', meta.window?.startDate, '~', meta.window?.endDate);
+console.log('返回', rows.length, '户，扫描', meta.scanned);
+rows.slice(0, 10).forEach((r) =>
+  console.log(' ', r.mediaCustomerId, r.spend, r.currencyCode, 'CTR%', r.ctr),
+);
+"
+```
+
+文件名以 stdout 摘要的 `writtenFiles[0]` / `manifestFile` 为准；读字段前先 `fs.readFileSync` 同 stem 的 `*.outline.txt`（见上文「处理顺序」）。
+
 ### 4. 从广告系列列表提取 ID
 
 ```bash

package/dist/skill/scripts/install.ps1

@@ -9,7 +9,7 @@ $ErrorActionPreference = 'Stop'
 # -- Package info (injected at build time) ------------------------------------
 $PKG_NAME    = 'siluzan-tso-cli'
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-$PKG_VERSION = '1.1.21-beta.4'
+$PKG_VERSION = '1.1.21-beta.6'
 $CLI_BIN     = 'siluzan-tso'
 $SKILL_LABEL = 'Siluzan TSO'
 $INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'

package/dist/skill/scripts/install.sh

@@ -9,7 +9,7 @@ set -euo pipefail
 # -- Package info (injected at build time) ------------------------------------
 readonly PKG_NAME="siluzan-tso-cli"
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-readonly PKG_VERSION="1.1.21-beta.4"
+readonly PKG_VERSION="1.1.21-beta.6"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
 readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"

package/eval/cases/p3-accounts-digest.scenario.json

@@ -2,9 +2,9 @@
   "id": "p3-accounts-digest",
   "description": "P3: 多账户汇总 — accounts-digest",
   "turns": [
-    "请对 Google 媒体下账户 {{EVAL_ACCOUNT_READ}},{{EVAL_ACCOUNT_READ_2}} 做 2026-04-01 至 2026-04-15 的消耗汇总表。\n根据 SKILL 应用 accounts-digest，加 --json；不要对每个账户单独 stats。"
+    "请对 Google 媒体下账户 {{EVAL_ACCOUNT_READ}},{{EVAL_ACCOUNT_READ_2}} 做 2026-04-01 至 2026-04-15 的消耗汇总表。\n根据 SKILL 应用 accounts-digest，加 --json-out ./snap-p3；不要对每个账户单独 stats。"
   ],
-  "judgeExpectation": "路径：多账户汇总消耗应优先 accounts-digest，而非对每个账户重复 stats。\n输出：应有汇总表或对比说明；不要求 ROAS/消耗数值与真实数据一致。",
+  "judgeExpectation": "路径：多账户汇总消耗应优先 accounts-digest（带 --json-out 落盘），而非对每个账户重复 stats。\n输出：应有汇总表或对比说明；结构化数据应来自落盘 JSON（可先 outline 再读文件），不要求 ROAS/消耗数值与真实数据一致。",
   "skillMapping": "Playbook P3 · accounts-digest",
   "commandMustInclude": [
     [

package/package.json

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