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

package/README.md

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

package/dist/index.js

@@ -5066,6 +5066,20 @@ var init_normalize_money = __esm({
   }
 });
 
+// src/commands/google-analysis/normalize-overview.ts
+function normalizeOverviewPayload(payload) {
+  const obj = payload;
+  if (typeof obj.balance === "number" && obj.balance === 0) {
+    delete obj.balance;
+  }
+  return payload;
+}
+var init_normalize_overview = __esm({
+  "src/commands/google-analysis/normalize-overview.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/google-analysis/match-type-en2zh.json
 var match_type_en2zh_default;
 var init_match_type_en2zh = __esm({
@@ -100731,13 +100745,13 @@ async function fetchSectionPayload(def, opts, config, id) {
     !!opts.verbose,
     def.name
   );
-  return annotateZhFields(
-    normalizeMoneyScales(
-      normalizeRateScales(stripLegacyGoogleFieldsIfV2Present(data), def.name),
-      def.name
-    ),
-    def.name
-  );
+  let payload = stripLegacyGoogleFieldsIfV2Present(data);
+  payload = normalizeRateScales(payload, def.name);
+  payload = normalizeMoneyScales(payload, def.name);
+  if (def.name === "overview") {
+    payload = normalizeOverviewPayload(payload);
+  }
+  return annotateZhFields(payload, def.name);
 }
 function endpointHintForSection(def) {
   if (def.name === "materials") return "CampaignAssetView+Videos";
@@ -100779,6 +100793,7 @@ var init_fetch = __esm({
     init_sections();
     init_normalize_rates();
     init_normalize_money();
+    init_normalize_overview();
     init_translate_fields();
   }
 });

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广告关键词推荐，
+  Siluzan TSO 广告 skill（siluzan-tso-cli）：Google/Bing/Yandex/TikTok/Kwai 账户开户与管理、Google Ads CRUD、数据分析、优化报告、智能预警、TikTok/Meta 线索、发票财务，并提供 RAG 知识库查询，google广告关键词推荐；当你发现你的上下文被压缩过后，你需要根据用户的需求，重新阅读本skill相关的文件，保证skill功能正常。
 license: MIT
 metadata:
   requires: nodejs,siluzan-tso-cli
@@ -153,7 +153,7 @@ Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令
 - **常用字段**：
   - `ad campaigns --json/--json-out` → `budget`（元，与 `campaign-edit --budget` 同口径）
   - `ad groups --json` → `maxCPCAmountYuan` / `targetCpaAmountYuan`（元）
-  - `google-analysis overview-*.json` → **余额取 `remainingAccountBudget`，禁止取 `balance`**（`balance` 是 Google 原始字段，多数账户恒为 0）
+  - `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) 用户提供网址 → 域名占位并标注 `[待确认品牌名]`。**严禁**把英文域名翻译为虚构中文品牌。

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.21-beta.3",
-  "publishedAt": 1779689350731
+  "version": "1.1.21-beta.5",
+  "publishedAt": 1779700715977
 }

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

@@ -84,7 +84,7 @@ CLI 出口的所有 JSON / 表格金额已统一为**元**，关键字段：
 | `ad groups --json`                                  | `maxCPCAmountYuan`、`targetCpaAmountYuan`                                                                                                 |
 | `google-analysis campaigns` 落盘 `campaigns-*.json` | `budgetAmountYuan`、`campaignTargetCpaYuan`、`maximizeConversionsTargetCpaYuan`；同行 `spend` / `averageCpc` / `costPerConversion` 也是元 |
 | `keyword suggest --json`                            | `averageCpc`、`lowTopOfPageBid`、`highTopOfPageBid`；根级与每条 `bidAmountCurrency`（有 `-a` 为账户币；无 `-a` 为 USD） |
-| `balance` 等账户余额接口                            | `remainingAccountBudget`（元）；**注意：`google-analysis overview` 同时返回 `balance`（Google 原始字段，多数账户恒为 0）和 `remainingAccountBudget`（真实余额），余额取值必须用后者** |
+| `balance` 等账户余额接口                            | 余额字段为`remainingAccountBudget`（元） |
 
 旧字段 `budgetAmount`（分）、`maxCPCAmountDisplay`、`*Micros`（微元）**已不再落盘**，下游脚本无需做单位换算。金额保留 2 位小数，带货币代码（如 `￥50.00 CNY`、`$50.00 USD`），`currencyCode` 从响应读取，跨币种账户分表；细则见 `references/currency.md`。
 

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/hosted-automation-monitoring-json.md

@@ -43,7 +43,7 @@ siluzan-tso balance -m Google --accounts <mediaCustomerId> --json
 mkdir -p ./snap-monitor && siluzan-tso google-analysis -a <mediaCustomerId> --sections overview --start <YYYY-MM-DD> --end <YYYY-MM-DD> --json-out ./snap-monitor
 ```
 
-读 **`./snap-monitor/overview-<accountId>.json`**（具体路径见 stdout 摘要的 `writtenFiles[0]` 或 `manifest-<accountId>.json` 的 `artifacts`）。根对象常见字段：**`remainingAccountBudget`**、**`averageDailyCost`**、**`totalCost`**、**`activeDays`**、**`currencyCode`**、**`accountId`**；**`currentPeriod`** / **`previousPeriod`** 为对象块，内含 **`spend`**、`impressions`、`clicks`、`conversions` 等与 `references/account-analytics.md` 总览口径一致的指标（块内还可能出现 **`currencyCode`**）。
+读 **`./snap-monitor/overview-<accountId>.json`**（具体路径见 stdout 摘要的 `writtenFiles[0]` 或 `manifest-<accountId>.json` 的 `artifacts`）。根对象常见字段：**`remainingAccountBudget`**（余额）、**`averageDailyCost`**、**`totalCost`**、**`activeDays`**、**`currencyCode`**、**`accountId`**（无 **`balance`**，网关为 0 时 CLI 已剔除）；**`currentPeriod`** / **`previousPeriod`** 为对象块，内含 **`spend`**、`impressions`、`clicks`、`conversions` 等与 `references/account-analytics.md` 总览口径一致的指标（块内还可能出现 **`currencyCode`**）。
 
 ---
 

package/dist/skill/references/tips.md

@@ -139,6 +139,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.3'
+$PKG_VERSION = '1.1.21-beta.5'
 $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.3"
+readonly PKG_VERSION="1.1.21-beta.5"
 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.3",
+  "version": "1.1.21-beta.5",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",