siluzan-tso-cli 1.1.19-beta.7 → 1.1.19-beta.9

package/README.md

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

package/dist/index.js

@@ -4526,6 +4526,16 @@ import * as path11 from "path";
 function googleAnalysisManifestFile(accountId) {
   return `${applyIdSuffix("manifest", accountId)}.json`;
 }
+function buildOutlineHints(section) {
+  const hints = [];
+  if (RATE_BEARING_SECTIONS.has(section)) {
+    hints.push(...GOOGLE_ANALYSIS_RATE_NORMALIZED_OUTLINE_HINTS);
+  }
+  if (section === "campaigns") {
+    hints.push(...GOOGLE_ANALYSIS_CAMPAIGNS_OUTLINE_BUDGET_HINTS);
+  }
+  return hints.length > 0 ? hints : void 0;
+}
 function sectionToFilename(section, accountId) {
   if (!/^[a-z0-9-]+$/.test(section)) {
     throw new Error(`\u975E\u6CD5\u5B50\u547D\u4EE4\u540D\uFF0C\u65E0\u6CD5\u751F\u6210\u6587\u4EF6\u540D\uFF1A${section}`);
@@ -4585,7 +4595,7 @@ async function writeGoogleAnalysisSnapshot(params) {
   await fs7.writeFile(path11.join(absDir, fileName), `${body}
 `, "utf8");
   const outlineFileName = snapshotOutlineFileName(fileName);
-  const outlineExtra = params.section === "campaigns" ? GOOGLE_ANALYSIS_CAMPAIGNS_OUTLINE_BUDGET_HINTS : void 0;
+  const outlineExtra = buildOutlineHints(params.section);
   const outlineBody = formatOutlineFileBody(fileName, params.payload, outlineExtra);
   await fs7.writeFile(path11.join(absDir, outlineFileName), `${outlineBody}
 `, "utf8");
@@ -4620,7 +4630,7 @@ async function writeGoogleAnalysisSnapshot(params) {
     agentHint: OUTLINE_AGENT_HINT
   };
 }
-var LEGACY_MANIFEST_FILE, CLI_PACKAGE2, SCHEMA_VERSION2, DEFAULT_FIELD_GUIDE2, GOOGLE_ANALYSIS_CAMPAIGNS_OUTLINE_BUDGET_HINTS;
+var LEGACY_MANIFEST_FILE, CLI_PACKAGE2, SCHEMA_VERSION2, DEFAULT_FIELD_GUIDE2, GOOGLE_ANALYSIS_CAMPAIGNS_OUTLINE_BUDGET_HINTS, RATE_BEARING_SECTIONS, GOOGLE_ANALYSIS_RATE_NORMALIZED_OUTLINE_HINTS;
 var init_google_analysis = __esm({
   "src/utils/snapshot/google-analysis.ts"() {
     "use strict";
@@ -4628,7 +4638,7 @@ var init_google_analysis = __esm({
     init_dir();
     LEGACY_MANIFEST_FILE = "manifest.json";
     CLI_PACKAGE2 = "siluzan-tso-cli";
-    SCHEMA_VERSION2 = 1;
+    SCHEMA_VERSION2 = 2;
     DEFAULT_FIELD_GUIDE2 = {
       markdownRefs: ["references/account-analytics.md"],
       tsTypesModule: "tso-cli/src/types/google-analysis-api.ts"
@@ -4637,6 +4647,29 @@ var init_google_analysis = __esm({
       "// \u91D1\u989D\uFF1A`campaigns[].budgetAmount`\uFF1D\u7F51\u5173\u300C\u5206\u300D\uFF08\u4E3B\u5E01\u79CD\xD7100 \u7684\u6574\u6570\uFF09\uFF0C**\u5143\uFF1D\xF7100**\uFF1B**\u7981\u6B62**\u6309\u5FAE\u5143 **\xF71_000_000**\uFF08\u4F1A\u7EA6\u5C0F\u4E00\u4E07\u500D\uFF09\u3002",
       "// \u540C\u6587\u4EF6 `spend`\u3001`averageCpc`\u3001`costPerConversion` \u7B49\u5DF2\u4E3A\u300C\u5143\u300D\u5C0F\u6570\u3002\u8BE6 `references/account-analytics.md`\u300CCampaignSectionData\u300D\u3002"
     ];
+    RATE_BEARING_SECTIONS = /* @__PURE__ */ new Set([
+      "overview",
+      "keywords",
+      "search-terms",
+      "campaigns",
+      "ads",
+      "extensions",
+      "devices",
+      "geographic",
+      "campaign-geo",
+      "campaign-device",
+      "audience",
+      "asset-images",
+      "videos",
+      "materials",
+      "daily-metrics",
+      "dimension-summary",
+      "ads-index"
+    ]);
+    GOOGLE_ANALYSIS_RATE_NORMALIZED_OUTLINE_HINTS = [
+      "// \u6982\u7387\u5B57\u6BB5\uFF1A`ctr` / `conversionRate` \u81EA manifest schemaVersion 2\uFF082026-05\uFF09\u8D77\u5DF2\u7531 CLI \u7EDF\u4E00\u5F52\u4E00\u4E3A **0~1 \u5C0F\u6570**\uFF08\u5982 `0.0964` = 9.64%\uFF09\u3002",
+      "// \u5199 Excel 0~1 \u5C0F\u6570\u5217\uFF1A\u76F4\u63A5\u5199\u5165\uFF1B\u5199\u300Cx%\u300D\u6587\u6848\uFF1A`(v * 100).toFixed(2) + '%'`\uFF1B**\u7981\u6B62**\u518D \xF7100\u3002`interactionRate` \u4ECD\u662F\u5B57\u7B26\u4E32 0~1 \u5C0F\u6570\uFF0C`parseFloat` \u540E\u4F7F\u7528\u3002"
+    ];
   }
 });
 
@@ -4833,6 +4866,50 @@ var init_sections = __esm({
   }
 });
 
+// src/commands/google-analysis/normalize-rates.ts
+function divIfFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v / 100 : v;
+}
+function divideRatesInPlace(value, seen) {
+  if (value === null || typeof value !== "object") return;
+  if (seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) divideRatesInPlace(item, seen);
+    return;
+  }
+  const obj = value;
+  for (const k of Object.keys(obj)) {
+    if (RATE_FIELD_NAMES.has(k)) {
+      obj[k] = divIfFiniteNumber(obj[k]);
+    } else {
+      divideRatesInPlace(obj[k], seen);
+    }
+  }
+}
+function normalizeRateScales(payload, section) {
+  if (!PERCENT_SCALE_SECTIONS.has(section)) return payload;
+  divideRatesInPlace(payload, /* @__PURE__ */ new WeakSet());
+  return payload;
+}
+var PERCENT_SCALE_SECTIONS, RATE_FIELD_NAMES;
+var init_normalize_rates = __esm({
+  "src/commands/google-analysis/normalize-rates.ts"() {
+    "use strict";
+    PERCENT_SCALE_SECTIONS = /* @__PURE__ */ new Set([
+      "overview",
+      "keywords",
+      "search-terms",
+      "campaigns",
+      "ads",
+      "extensions",
+      "devices",
+      "ads-index"
+    ]);
+    RATE_FIELD_NAMES = /* @__PURE__ */ new Set(["ctr", "conversionRate"]);
+  }
+});
+
 // src/commands/google-analysis/fetch.ts
 function defaultDateRange3() {
   const end = /* @__PURE__ */ new Date();
@@ -4968,7 +5045,7 @@ async function fetchSectionPayload(def, opts, config, id) {
       fetchJson(config, videoPath, !!opts.verbose)
     ]);
     const merged = { images, videos };
-    return stripLegacyGoogleFieldsIfV2Present(merged);
+    return normalizeRateScales(stripLegacyGoogleFieldsIfV2Present(merged), "materials");
   }
   if (def.name === "daily-metrics") {
     const { startDate, endDate } = resolveDateRange2(opts.start, opts.end);
@@ -4980,7 +5057,7 @@ async function fetchSectionPayload(def, opts, config, id) {
     const url = `${config.apiBaseUrl}/report/media-account/google/account-daily-reports?${params.toString()}`;
     const raw = await apiFetch2(url, config, {}, !!opts.verbose);
     const rows = rowsFromAccountDailyReportsEnvelope(raw, id);
-    return stripLegacyGoogleFieldsIfV2Present(rows);
+    return normalizeRateScales(stripLegacyGoogleFieldsIfV2Present(rows), "daily-metrics");
   }
   const sectionPath = def.path(id);
   const query = buildSearchParams(def, opts.start, opts.end, extras);
@@ -4990,7 +5067,7 @@ async function fetchSectionPayload(def, opts, config, id) {
     !!opts.verbose,
     def.name
   );
-  return stripLegacyGoogleFieldsIfV2Present(data);
+  return normalizeRateScales(stripLegacyGoogleFieldsIfV2Present(data), def.name);
 }
 function endpointHintForSection(def) {
   if (def.name === "materials") return "CampaignAssetView+Videos";
@@ -5030,6 +5107,7 @@ var init_fetch = __esm({
     init_auth();
     init_strip_legacy_google_fields();
     init_sections();
+    init_normalize_rates();
   }
 });
 
@@ -6664,6 +6742,7 @@ var init_google_analysis2 = __esm({
     "use strict";
     init_sections();
     init_fetch();
+    init_normalize_rates();
     init_register_cli();
   }
 });

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.19-beta.7",
-  "publishedAt": 1778637043636
+  "version": "1.1.19-beta.9",
+  "publishedAt": 1778658380497
 }

package/dist/skill/report-templates/okki-weekly-google-client.md

@@ -59,14 +59,18 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 
 以下按 **工作簿 → Sheet 名（须完全一致）→ 版式** 约定，便于 WorkBuddy / 人工用样表对照验收。**不**再单独建名为「广告系列」的 Sheet（系列表在 **`账户报告`** 内）。**金额等展示列**：脚本与运营约定保留小数位数（常见两位），须与样表一致。
 
-### 脚本写表：点击率 / 转化率 / 互动率（易错，必读）
+### 脚本写表：点击率 / 转化率 / 互动率
 
-网关落盘 JSON 中，**`ctr`、`conversionRate` 在绝大多数行上已是 0～1 的小数**（例如 `0.0753` 表示约 7.53% 点击率，`0.0365` 表示约 3.65% 转化率），**不是**「百分数刻度」里的 `7.53` / `3.65`。
+> **2026-05 起 CLI 已统一归一**（manifest `schemaVersion: 2`）：所有 `<section>-*.json` 中的 `ctr` / `conversionRate` 一律为 **0~1 小数**（如 `0.0964` = 9.64%）。无需再按维度做 ÷100 分支；下表与脚本片段仅作快速参考。详见 `references/account-analytics.md`「指标字段对照」。
 
-- **写入 Excel**（本模板要求点击率、转化率、互动率列为 **0～1 小数**）：对上述字段应 **直接使用 JSON 数值**（或 `Number(...)`），**禁止**再 **`÷100`**，否则会变成 `0.0007` 量级，经四舍五入后常显示为 **0**。  
-- **客户话术 / 正文里写「x%」**：应使用 **`ctr * 100`、`conversionRate * 100`**（或等价格式化）后再加 `%`，**禁止**把已是 0～1 的 `ctr` 当「百分数」再除 100。  
-- **`interactionRate`**：网关可能为 **字符串**（如 `"0.0753…"`），须 **`parseFloat` / `Number`** 后再写入；若与 `interactions/impressions` 不一致，以 outline 为准或允许用 `interactions / impressions` 重算。  
-- **`interactions === 0`（或 null）** 时：**平均费用**（`spend / interactions`）与 **互动率** 列填 **`—`**，禁止除零。
+| 场景                                                | 处理                                                                                       |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **写入 Excel 0~1 小数列**（点击率/转化率/互动率）   | 直接写入 JSON 数值（**禁止**再 ÷100）                                                      |
+| **写客户话术 / 文案的 `x%`**                        | `(v * 100).toFixed(2) + "%"`（**禁止**直接打印数值得到 "0.09%"）                           |
+| **`interactionRate`（字符串）**                     | `parseFloat(row.interactionRate)` 后按数值字段使用（同样 0~1 小数）                        |
+| **`interactions === 0` / `null`**                   | **平均费用**（`spend / interactions`）与 **互动率** 列填 **`—`**，禁止除零                 |
+
+> **历史快照兼容（`schemaVersion: 1` 旧目录）**：2026-04 及更早落盘 JSON **未归一**——`overview` / `campaigns` / `keywords` / `search-terms` / `ads` / `extensions` / `devices`（账户级）/ `ads-index` 这 8 个维度仍是百分数刻度（如 `ctr: 9.636` = 9.636%），写入前须 ÷100；其余维度原样为 0~1 小数。先看 `manifest-<id>.json` 顶部 `schemaVersion` 判别，**不要**用「值 > 1 才 ÷100」启发式（搜索词旧行 `ctr: 100` 会被误判）。
 
 ### 工作簿级
 
@@ -99,7 +103,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 | R1 标题 | `广告系列报告`（与样表一致；若运营统一改名，可改文案但须保持 Sheet 名仍为 `账户报告`） |
 | R2 | 统计区间（中文日期，见上） |
 | R3 表头（A→K，共 11 列） | `广告系列` \| `预算` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
-| R4… | 每行一条广告系列：来自 `campaigns-*.json` 的 `campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks`、**`ctr`（直接作 0～1 写入「点击率」，禁止 ÷100）**、`averageCpc`、**`allConv` →「所有转化次数」**、**`conversions` →「转化次数」**、`costPerConversion`、**`conversionRate`（直接作 0～1 写入「转化率」，禁止 ÷100）**；若缺 `allConv` 仅 `conversions`，「所有转化次数」可与「转化次数」同值或填 `0` / `—` 并在脚注说明（以 outline 为准） |
+| R4… | 每行一条广告系列：来自 `campaigns-*.json` 的 `campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks`、**`ctr` 直接写入「点击率」（已归一为 0~1 小数）**、`averageCpc`、**`allConversions ` →「所有转化次数」**、**`conversions` →「转化次数」**、`costPerConversion`、**`conversionRate` 直接写入「转化率」（已归一为 0~1 小数）**；若缺 `allConversions ` 仅 `conversions`，「所有转化次数」可与「转化次数」同值或填 `0` / `—` 并在脚注说明（以 outline 为准） |
 | 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；**展示 / 点击 / 所有转化次数 / 转化次数 / 费用**等做列求和；**点击率** = 合计点击÷合计展示；**转化率** = 合计转化÷合计点击（**禁止**用合计转化÷合计展示冒充）；**每次转化费用** = 合计费用÷合计转化（转化为 0 时填 `—`）；禁止对各行比率取算术平均 |
 
 表下**留白若干行**后写 **「数据复盘」**（与样表一致）：
@@ -122,7 +126,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 | R1 标题 | `搜索关键字报告` |
 | R2 | 统计区间（同 `账户报告`） |
 | R3 表头（A→L，共 12 列） | `关键字` \| `匹配类型` \| `广告系列` \| `广告组` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
-| R4… | `keywords-*.json` 行映射；`keywordMatchType` → 匹配类型；`campaignName` / `adGroupName` 等按 outline |
+| R4… | `keywords-*.json` 行映射；`keywordMatchType` → 匹配类型；`campaignName` / `adGroupName` 等按 outline；**`ctr` / `conversionRate` 直接写入「点击率」「转化率」（CLI 已统一归一为 0~1 小数）** |
 
 ---
 
@@ -133,7 +137,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 | R1 标题 | `搜索字词报告` |
 | R2 | 统计区间 |
 | R3 表头（A→N，共 14 列） | `搜索字词` \| `匹配类型` \| `已添加/已排除` \| `广告系列` \| `广告组` \| `关键字` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
-| R4… | `search-terms-*.json`；`已添加/已排除` 若 JSON 无此枚举则留空或填「—」，禁止臆造状态 |
+| R4… | `search-terms-*.json`；`已添加/已排除` 若 JSON 无此枚举则留空或填「—」，禁止臆造状态；**`ctr` / `conversionRate` 直接写入「点击率」「转化率」（CLI 已统一归一为 0~1 小数）** |
 
 ---
 
@@ -144,7 +148,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 | R1 标题 | `设备报告` |
 | R2 | 统计区间 |
 | R3 表头（A→M，共 13 列） | `设备` \| `级别` \| `广告系列` \| `出价调整` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
-| R4… | **`campaign-device-*.json`**（`devices[]`）：`deviceType` → 设备；`campaignName` / `adGroupName` →「广告系列」等；**`allConv`（或 outline 中的等价字段）→「所有转化次数」**；`conversions` →「转化次数」；**`ctr` / `conversionRate` 作 0～1 写入，禁止 ÷100**；**出价调整** 无字段则「—」；**级别**列按运营约定（如填 `广告系列` 或 `账户`，全文一致） |
+| R4… | **`campaign-device-*.json`**（`devices[]`）：`deviceType` → 设备；`campaignName` / `adGroupName` →「广告系列」等；**`allConversions `（或 outline 中的等价字段）→「所有转化次数」**；`conversions` →「转化次数」；**`ctr` / `conversionRate` 直接写入（已归一为 0~1 小数）**；**出价调整** 无字段则「—」；**级别**列按运营约定（如填 `广告系列` 或 `账户`，全文一致） |
 
 ---
 
@@ -155,7 +159,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 | R1 标题 | `地理位置报告` |
 | R2 | 统计区间 |
 | R3 表头（A→M，共 13 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
-| R4… | **`campaign-geo-*.json`**（`countries[]`）：`countryOrRegion` → 地理位置；`campaignName` →「广告系列」；**`allConv`（或等价）→「所有转化次数」**；`conversions` →「转化次数」；**互动次数** → `interactions`；**互动率** → `interactionRate`（字符串须解析）或 `interactions/impressions`（`interactions` 为 0 时互动率填 **`—`**）；**平均费用** **必须**为 **`spend / interactions`**，`interactions` 为 0 / null / undefined 时填 **`—`**；**`ctr` / `conversionRate` 作 0～1 写入，禁止 ÷100**；其余列按 outline 映射。 |
+| R4… | **`campaign-geo-*.json`**（`countries[]`）：`countryOrRegion` → 地理位置；`campaignName` →「广告系列」；**`allConversions `（或等价）→「所有转化次数」**；`conversions` →「转化次数」；**互动次数** → `interactions`；**互动率** → `interactionRate`（字符串须解析）或 `interactions/impressions`（`interactions` 为 0 时互动率填 **`—`**）；**平均费用** **必须**为 **`spend / interactions`**，`interactions` 为 0 / null / undefined 时填 **`—`**；**`ctr` / `conversionRate` 直接写入（已归一为 0~1 小数）**；其余列按 outline 映射。 |
 
 ---
 
@@ -186,7 +190,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 8. 账户余额：<金额+币种>（截至查询时点）
 ```
 
-**第 3 条**：若 CLI 返回的是**账户整体 CTR**，话术写「整体点击率」而非「搜索点击率」，避免与搜索广告狭义口径冲突；若数据中可区分搜索广告 CTR，再写「搜索点击率」。**百分比数字**：若 `stats` / `overview` 中 CTR 为 **0～1 小数**，话术里写「x%」前须 **×100**（与上文「脚本写表：点击率 / 转化率」一致），**禁止**再 ÷100。
+**第 3 条**：若 CLI 返回的是**账户整体 CTR**，话术写「整体点击率」而非「搜索点击率」，避免与搜索广告狭义口径冲突；若数据中可区分搜索广告 CTR，再写「搜索点击率」。**百分比数字**：`overview-*.json`（`schemaVersion: 2` 起）的 `ctr` 已是 **0~1 小数**（如 `0.1026`），话术 `x%` 用 `(ctr * 100).toFixed(2) + "%"`，**禁止**直接打印数值得到 "0.1%"。
 
 **第 1 条「平均每天」**：`区间总消耗 / 区间日历天数`（含起止日），在脚本中计算，禁止手填。
 

package/package.json

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