siluzan-tso-cli 1.1.36-beta.1 → 1.1.36-beta.2

package/README.md

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

package/dist/index.js

@@ -106735,7 +106735,7 @@ async function writeReportAnalysisSnapshot(params) {
   );
   await fs8.writeFile(
     path12.join(absDir, outlineFileName),
-    `${formatOutlineFileBody(fileName, params.payload)}
+    `${formatOutlineFileBody(fileName, params.payload, params.outlineExtraHints)}
 `,
     "utf8"
   );
@@ -127807,6 +127807,55 @@ function syncOverviewBalanceFields(record) {
   return out;
 }
 
+// src/commands/bing-analysis/normalize-bing-rates.ts
+var RATE_FIELD_NAMES2 = /* @__PURE__ */ new Set(["ctr", "conversionRate"]);
+var BING_RATE_BEARING_SECTIONS = /* @__PURE__ */ new Set([
+  "overview",
+  "device",
+  "geographic",
+  "age-audience",
+  "gender-audience",
+  "audience-merged",
+  "campaigns",
+  "ad-groups",
+  "ads",
+  "keywords",
+  "search-terms"
+]);
+function divIfFiniteNumber2(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v / 100 : v;
+}
+function divideRatesInPlace2(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) divideRatesInPlace2(item, seen);
+    return;
+  }
+  const obj = value;
+  for (const k of Object.keys(obj)) {
+    if (RATE_FIELD_NAMES2.has(k)) {
+      obj[k] = divIfFiniteNumber2(obj[k]);
+    } else {
+      divideRatesInPlace2(obj[k], seen);
+    }
+  }
+}
+function normalizeBingRateScales(payload, section) {
+  if (!BING_RATE_BEARING_SECTIONS.has(section)) return payload;
+  divideRatesInPlace2(payload, /* @__PURE__ */ new WeakSet());
+  return payload;
+}
+var BING_RATE_NORMALIZED_OUTLINE_HINTS = [
+  "// \u6982\u7387\u5B57\u6BB5\uFF1A`ctr` / `conversionRate` \u5DF2\u7531 bing-analysis CLI \u4ECE\u7F51\u5173\u767E\u5206\u6570\u523B\u5EA6\u5F52\u4E00\u4E3A **0~1 \u5C0F\u6570**\uFF08\u5982 `0.0074` = 0.74%\uFF09\u3002",
+  "// \u5199\u300Cx%\u300D\u6587\u6848\uFF1A`(v * 100).toFixed(2) + '%'`\uFF1B**\u7981\u6B62**\u518D \xF7100\uFF0C\u4E5F**\u7981\u6B62**\u628A JSON \u6570\u503C\u5F53\u300C\u5DF2\u662F\u767E\u5206\u6570\u300D\u76F4\u63A5\u52A0 `%`\uFF08\u4F1A \xD7100 \u9519\u8BEF\uFF0C\u5982 0.74% \u663E\u793A\u6210 74%\uFF09\u3002"
+];
+function buildBingOutlineHints(section) {
+  if (!BING_RATE_BEARING_SECTIONS.has(section)) return void 0;
+  return BING_RATE_NORMALIZED_OUTLINE_HINTS;
+}
+
 // src/commands/bing-analysis/fetch.ts
 var BING_KEYWORD_LIMIT_DEFAULT = 100;
 function stripLocalDate(d) {
@@ -127919,7 +127968,10 @@ async function fetchBingOverviewPayload(config, id, startDate, endDate, verbose)
     endDate,
     verbose
   );
-  return syncOverviewBalanceFields(withPrevious);
+  return normalizeBingSectionPayload(
+    syncOverviewBalanceFields(withPrevious),
+    "overview"
+  );
 }
 async function enrichBingOverviewPreviousPeriod(config, accountId, record, startDate, endDate, verbose) {
   if (!isBingPeriodBlockEmpty(record.previousPeriod)) {
@@ -127963,13 +128015,16 @@ async function fetchBingAudienceMergedPayload(config, id, startDate, endDate, ve
     fetchBingJson(config, ageUrl, verbose),
     fetchBingJson(config, genderUrl, verbose)
   ]);
-  return {
-    mergedParts: ["AgeAudienceData", "GenderAudienceData"],
-    startDate,
-    endDate,
-    account: id,
-    data: { ageAudience: ageData, genderAudience: genderData }
-  };
+  return normalizeBingSectionPayload(
+    {
+      mergedParts: ["AgeAudienceData", "GenderAudienceData"],
+      startDate,
+      endDate,
+      account: id,
+      data: { ageAudience: ageData, genderAudience: genderData }
+    },
+    "audience-merged"
+  );
 }
 async function fetchBingSectionPayload(def, opts, config, id) {
   const { startDate, endDate } = resolveBingDateRange(opts.start, opts.end);
@@ -127986,7 +128041,12 @@ async function fetchBingSectionPayload(def, opts, config, id) {
     params.set("orderByCost", "true");
   }
   const url = reportingUrl(config, id, def.segment, params.toString());
-  return fetchBingJson(config, url, verbose);
+  const raw = await fetchBingJson(config, url, verbose);
+  return normalizeBingRateScales(raw, def.name);
+}
+function normalizeBingSectionPayload(payload, section) {
+  if (payload === null || typeof payload !== "object") return payload;
+  return normalizeBingRateScales(payload, section);
 }
 function endpointHintForBingSection(def) {
   return `GET \u2026/BingV2/{id}/${def.segment}`;
@@ -128045,7 +128105,8 @@ async function runAllBingSections(opts) {
         accountId: id,
         dateRange: { start: startDate, end: endDate },
         payload,
-        cliVersion
+        cliVersion,
+        outlineExtraHints: buildBingOutlineHints(def.name)
       });
       return {
         section: def.name,

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.36-beta.1",
-  "publishedAt": 1783409684521
+  "version": "1.1.36-beta.2",
+  "publishedAt": 1783560342359
 }

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

@@ -319,7 +319,7 @@ siluzan-tso tiktok-analysis -a 1234567890 --start 2026-03-01 --end 2026-03-31 \
 
 ## Bing（BingV2）账户分析
 
-> **日期限制**：Bing 报表不能包含今天或昨天。省略时 CLI 默认截至前天的近 7 天。
+> **日期限制**：Bing 报表不能包含今天或昨天。省略时 CLI 默认截至前天的近 7 天。用户要**已结束的完整自然月**（如「6月份」）→ `--start` 当月 1 日、`--end` 当月最后一天（6 月 = `06-30`，**禁止**减 1 天），见 `report-templates/bing-period-report.md` §日期规则。
 
 与 `google-analysis` / `facebook-analysis` 同架构：`bing-analysis -a … --json-out …`（省略子命令名默认执行 `run`，批量拉取全部维度或 `--sections` 指定子集）。
 
@@ -343,6 +343,18 @@ siluzan-tso bing-analysis -a <mediaCustomerId> --start 2026-03-01 --end 2026-03-
 
 报告模板：`report-templates/bing-period-report.md`（**每个 section 须写「分析」**；**余额**：`overview` section 落盘 JSON 常自动校正 0 快照，读 `balance`/`remainingAccountBudget` 或 `balance` 命令；**环比**：网关 `previousPeriod` 常空，CLI 二次拉上一周期回填）。
 
+### 点击率 / 转化率口径（必读）
+
+Bing 的 `ctr` / `conversionRate` 为 0~1 小数**（`0.007434` = 0.74%），与 Google `schemaVersion ≥ 2` 一致。
+
+| 场景 | 正确写法 | 错误写法 |
+| ---- | -------- | -------- |
+| 报告 HTML 展示 | `(ctr * 100).toFixed(2) + '%'` | `ctr.toFixed(2) + '%'`（会显示 74% 而非 0.74%） |
+| Excel 0~1 列 | 直接写 JSON 数值 | 再 ÷100 |
+| 脚本校验 | `clicks / impressions` 与 `ctr` 应一致（允许四舍五入） | 心算或凭印象 |
+
+各 `overview-*.outline.txt` 等文件头部含 `//` 硬提示，Agent **须先读 outline** 再写报告。
+
 ---
 
 ## 报告模板

package/dist/skill/references/core/agent-conventions.md

@@ -149,6 +149,11 @@
 | Google 关键词/系列分析 | `now - 30d` ~ `now - 1d`        |
 | MetaAd 账户分析        | 不得默认，必须问                |
 
+**完整自然月口径**（用户说「X 月 / X月份 / 月报」且该月已结束，或上表「月报」默认）：
+
+- `--start` = 当月 1 日，`--end` = 当月最后一天（6 月 → `06-01` ~ `06-30`，**禁止** `06-29`）。
+- **Bing** `bing-analysis`：「不能含今天/昨天」仅当区间碰到**执行日**的今天/昨天时才需把结束日压到前天；**已结束的历史自然月必须用该月最后一天**，细则见 `report-templates/bing-period-report.md` §日期规则。交付前核对 `overview` 的 `activeDays` = 该月日历天数。
+
 ---
 
 ## 六、币种与金额

package/dist/skill/references/report-templates/bing-period-report.md

@@ -12,7 +12,25 @@
 
 - Bing 接口**无法**拉取过新的数据；时间范围内**任意一天**若为**今天**或**昨天**，请求会失败。
 - **CLI**：`--start` / `--end` 须**同传或同省略**；省略时默认**截至前天**的近 7 天（与 `bing-analysis` 实现一致）。
-- 自选区间时请确保结束日 ≤ **前天**。
+- **自选区间且靠近当前日期**时，结束日须 ≤ **前天**（仅当区间会碰到今天/昨天才需要压到前天；**不是**把历史自然月最后一天减 1 天）。
+
+### 用户说「X 月 / X月份 / 月报」（已结束的完整自然月）
+
+用户指定某一月份（如「6月份报告」「6月 Bing 月报」）且该月**已结束**时：
+
+| 项 | 规则 |
+| --- | --- |
+| `--start` | 当月 **1 日**（如 `2026-06-01`） |
+| `--end` | 当月**最后一天**（如 6 月 → `2026-06-30`，**禁止**写成 `06-29`） |
+| 报告首行 | `统计区间：YYYY-MM-01 ~ YYYY-MM-<末>` |
+
+示例（7 月 8 日要 6 月报告）：
+
+```bash
+siluzan-tso bing-analysis -a <id> --start 2026-06-01 --end 2026-06-30 --json-out ./snap-bing
+```
+
+**禁止**因「Bing 不能含今天/昨天」而对**已结束的历史自然月**把 `--end` 减 1 天——该限制只针对区间内的日历日是否等于**执行当天的今天或昨天**；6 月 30 日在 7 月 8 日拉数完全合法。拉数后核对 `overview` 落盘里的 `activeDays` 应等于该月日历天数（6 月 = 30）。
 
 ---
 
@@ -35,7 +53,7 @@ siluzan-tso bing-analysis -a <mediaCustomerId> --start <S> --end <E> \
 
 - 写脚本前先读各 `bing-*-<id>.outline.txt`，再读 `.json`（见 `references/core/agent-conventions.md` §三）。
 - TopN、排序、汇总均在脚本内完成，禁止心算。
-- 金额字段已为**元**；`ctr` / `conversionRate` 等为 **0~1 小数**，展示百分比用 `(v * 100).toFixed(2) + '%'`。
+- 金额字段已为**元**；`ctr` / `conversionRate` 等：**`bing-analysis` 落盘前已从网关百分数刻度归一为 0~1 小数**（如 `0.0074` = 0.74%），展示百分比用 `(v * 100).toFixed(2) + '%'`；**禁止**把 JSON 数值当「已是百分数」直接加 `%`（会重复 ×100，如 0.74% 显示成 74%）。
 
 ---
 

package/dist/skill/report-templates/bing-period-report.md

@@ -12,7 +12,25 @@
 
 - Bing 接口**无法**拉取过新的数据；时间范围内**任意一天**若为**今天**或**昨天**，请求会失败。
 - **CLI**：`--start` / `--end` 须**同传或同省略**；省略时默认**截至前天**的近 7 天（与 `bing-analysis` 实现一致）。
-- 自选区间时请确保结束日 ≤ **前天**。
+- **自选区间且靠近当前日期**时，结束日须 ≤ **前天**（仅当区间会碰到今天/昨天才需要压到前天；**不是**把历史自然月最后一天减 1 天）。
+
+### 用户说「X 月 / X月份 / 月报」（已结束的完整自然月）
+
+用户指定某一月份（如「6月份报告」「6月 Bing 月报」）且该月**已结束**时：
+
+| 项 | 规则 |
+| --- | --- |
+| `--start` | 当月 **1 日**（如 `2026-06-01`） |
+| `--end` | 当月**最后一天**（如 6 月 → `2026-06-30`，**禁止**写成 `06-29`） |
+| 报告首行 | `统计区间：YYYY-MM-01 ~ YYYY-MM-<末>` |
+
+示例（7 月 8 日要 6 月报告）：
+
+```bash
+siluzan-tso bing-analysis -a <id> --start 2026-06-01 --end 2026-06-30 --json-out ./snap-bing
+```
+
+**禁止**因「Bing 不能含今天/昨天」而对**已结束的历史自然月**把 `--end` 减 1 天——该限制只针对区间内的日历日是否等于**执行当天的今天或昨天**；6 月 30 日在 7 月 8 日拉数完全合法。拉数后核对 `overview` 落盘里的 `activeDays` 应等于该月日历天数（6 月 = 30）。
 
 ---
 
@@ -35,7 +53,7 @@ siluzan-tso bing-analysis -a <mediaCustomerId> --start <S> --end <E> \
 
 - 写脚本前先读各 `bing-*-<id>.outline.txt`，再读 `.json`（见 `references/core/agent-conventions.md` §三）。
 - TopN、排序、汇总均在脚本内完成，禁止心算。
-- 金额字段已为**元**；`ctr` / `conversionRate` 等为 **0~1 小数**，展示百分比用 `(v * 100).toFixed(2) + '%'`。
+- 金额字段已为**元**；`ctr` / `conversionRate` 等：**`bing-analysis` 落盘前已从网关百分数刻度归一为 0~1 小数**（如 `0.0074` = 0.74%），展示百分比用 `(v * 100).toFixed(2) + '%'`；**禁止**把 JSON 数值当「已是百分数」直接加 `%`（会重复 ×100，如 0.74% 显示成 74%）。
 
 ---
 

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.36-beta.1'
+$PKG_VERSION = '1.1.36-beta.2'
 $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.36-beta.1"
+readonly PKG_VERSION="1.1.36-beta.2"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
 readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"

package/package.json

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