siluzan-tso-cli 1.1.45-beta.2 → 1.1.45-beta.4

package/README.md

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

package/dist/index.js

@@ -4503,17 +4503,57 @@ var init_currency_display = __esm({
   }
 });
 
+// src/commands/google-analysis/daily-metrics-range.ts
+function pad2(n) {
+  return String(n).padStart(2, "0");
+}
+function formatChinaOffsetDateTime(d) {
+  const sh = new Date(d.getTime() + CHINA_OFFSET_MS);
+  return `${sh.getUTCFullYear()}-${pad2(sh.getUTCMonth() + 1)}-${pad2(sh.getUTCDate())}T${pad2(sh.getUTCHours())}:${pad2(sh.getUTCMinutes())}:${pad2(sh.getUTCSeconds())}+08:00`;
+}
+function defaultChinaDateRange(now = /* @__PURE__ */ new Date()) {
+  const chinaNow = new Date(now.getTime() + CHINA_OFFSET_MS);
+  chinaNow.setUTCDate(chinaNow.getUTCDate() - 1);
+  const endY = chinaNow.getUTCFullYear();
+  const endM = chinaNow.getUTCMonth();
+  const endD = chinaNow.getUTCDate();
+  const startChina = new Date(Date.UTC(endY, endM, endD - 6));
+  const endChina = new Date(Date.UTC(endY, endM, endD));
+  const fmt = (utcCal) => `${utcCal.getUTCFullYear()}-${pad2(utcCal.getUTCMonth() + 1)}-${pad2(utcCal.getUTCDate())}`;
+  return { startDate: fmt(startChina), endDate: fmt(endChina) };
+}
+function resolveDailyMetricsQueryTimes(startDate, endDate, now = /* @__PURE__ */ new Date()) {
+  const startInstant = `${startDate}T00:00:00+08:00`;
+  const endOfDay = /* @__PURE__ */ new Date(`${endDate}T23:59:59+08:00`);
+  const endInstant = endOfDay.getTime() > now.getTime() ? formatChinaOffsetDateTime(now) : formatChinaOffsetDateTime(endOfDay);
+  return { startInstant, endInstant };
+}
+function resolveChinaQueryTimes(startDate, endDate, _now = /* @__PURE__ */ new Date()) {
+  return { startInstant: startDate, endInstant: endDate };
+}
+var CHINA_OFFSET_MS;
+var init_daily_metrics_range = __esm({
+  "src/commands/google-analysis/daily-metrics-range.ts"() {
+    "use strict";
+    CHINA_OFFSET_MS = 8 * 36e5;
+  }
+});
+
 // src/utils/balance.ts
-function fmt(d) {
-  return d.toISOString().slice(0, 10);
+function pad22(n) {
+  return String(n).padStart(2, "0");
 }
-function dateRangeLastNDays(n) {
+function dateRangeLastNDays(n, now = /* @__PURE__ */ new Date()) {
   const days = Math.max(1, Math.floor(Number(n) || 1));
-  const end = /* @__PURE__ */ new Date();
-  end.setDate(end.getDate() - 1);
-  const start = new Date(end);
-  start.setDate(start.getDate() - (days - 1));
-  return { startDate: fmt(start), endDate: fmt(end) };
+  const chinaNow = new Date(now.getTime() + CHINA_OFFSET_MS2);
+  chinaNow.setUTCDate(chinaNow.getUTCDate() - 1);
+  const endY = chinaNow.getUTCFullYear();
+  const endM = chinaNow.getUTCMonth();
+  const endD = chinaNow.getUTCDate();
+  const startChina = new Date(Date.UTC(endY, endM, endD - (days - 1)));
+  const endChina = new Date(Date.UTC(endY, endM, endD));
+  const fmtChina = (utcCal) => `${utcCal.getUTCFullYear()}-${pad22(utcCal.getUTCMonth() + 1)}-${pad22(utcCal.getUTCDate())}`;
+  return { startDate: fmtChina(startChina), endDate: fmtChina(endChina) };
 }
 function defaultDateRange() {
   return dateRangeLastNDays(7);
@@ -4709,9 +4749,10 @@ async function fetchOverviewMap(route, accountIds, config, startDate, endDate, v
   const end = endDate ?? range.endDate;
   try {
     if (route === "Google") {
+      const { startInstant, endInstant } = resolveDailyMetricsQueryTimes(start, end);
       const params = new URLSearchParams({
-        startDate: start,
-        endDate: end,
+        startDate: startInstant,
+        endDate: endInstant,
         mediaCustomerIds: accountIds.join("|")
       });
       const url = `${config.apiBaseUrl}/report/media-account/google/account-spend-overview?${params}`;
@@ -4797,10 +4838,11 @@ async function fetchOverviewMap(route, accountIds, config, startDate, endDate, v
   }
   return result;
 }
-var BALANCE_SUPPORTED_MEDIA;
+var BALANCE_SUPPORTED_MEDIA, CHINA_OFFSET_MS2;
 var init_balance = __esm({
   "src/utils/balance.ts"() {
     "use strict";
+    init_daily_metrics_range();
     init_auth();
     BALANCE_SUPPORTED_MEDIA = [
       "Google",
@@ -4810,6 +4852,7 @@ var init_balance = __esm({
       "Kwai",
       "MetaAd"
     ];
+    CHINA_OFFSET_MS2 = 8 * 36e5;
   }
 });
 
@@ -5525,42 +5568,6 @@ var init_accounts_digest2 = __esm({
   }
 });
 
-// src/commands/google-analysis/daily-metrics-range.ts
-function pad2(n) {
-  return String(n).padStart(2, "0");
-}
-function formatChinaOffsetDateTime(d) {
-  const sh = new Date(d.getTime() + CHINA_OFFSET_MS);
-  return `${sh.getUTCFullYear()}-${pad2(sh.getUTCMonth() + 1)}-${pad2(sh.getUTCDate())}T${pad2(sh.getUTCHours())}:${pad2(sh.getUTCMinutes())}:${pad2(sh.getUTCSeconds())}+08:00`;
-}
-function defaultChinaDateRange(now = /* @__PURE__ */ new Date()) {
-  const chinaNow = new Date(now.getTime() + CHINA_OFFSET_MS);
-  chinaNow.setUTCDate(chinaNow.getUTCDate() - 1);
-  const endY = chinaNow.getUTCFullYear();
-  const endM = chinaNow.getUTCMonth();
-  const endD = chinaNow.getUTCDate();
-  const startChina = new Date(Date.UTC(endY, endM, endD - 6));
-  const endChina = new Date(Date.UTC(endY, endM, endD));
-  const fmt2 = (utcCal) => `${utcCal.getUTCFullYear()}-${pad2(utcCal.getUTCMonth() + 1)}-${pad2(utcCal.getUTCDate())}`;
-  return { startDate: fmt2(startChina), endDate: fmt2(endChina) };
-}
-function resolveDailyMetricsQueryTimes(startDate, endDate, now = /* @__PURE__ */ new Date()) {
-  const startInstant = `${startDate}T00:00:00+08:00`;
-  const endOfDay = /* @__PURE__ */ new Date(`${endDate}T23:59:59+08:00`);
-  const endInstant = endOfDay.getTime() > now.getTime() ? formatChinaOffsetDateTime(now) : formatChinaOffsetDateTime(endOfDay);
-  return { startInstant, endInstant };
-}
-function resolveChinaQueryTimes(startDate, endDate, _now = /* @__PURE__ */ new Date()) {
-  return { startInstant: startDate, endInstant: endDate };
-}
-var CHINA_OFFSET_MS;
-var init_daily_metrics_range = __esm({
-  "src/commands/google-analysis/daily-metrics-range.ts"() {
-    "use strict";
-    CHINA_OFFSET_MS = 8 * 36e5;
-  }
-});
-
 // src/utils/snapshot/async-lock.ts
 async function withAsyncLock(key, fn) {
   const prev = chains.get(key) ?? Promise.resolve();
@@ -108630,8 +108637,8 @@ function resolveFacebookDateRange(start, end) {
     endD.setDate(endD.getDate() - 1);
     const startD = new Date(endD);
     startD.setDate(startD.getDate() - 6);
-    const fmt2 = (d) => d.toISOString().slice(0, 10);
-    return { startDate: fmt2(startD), endDate: fmt2(endD) };
+    const fmt = (d) => d.toISOString().slice(0, 10);
+    return { startDate: fmt(startD), endDate: fmt(endD) };
   }
   console.error("\n\u274C --start \u4E0E --end \u987B\u540C\u65F6\u4F20\u5165\uFF0C\u6216\u540C\u65F6\u7701\u7565\u4EE5\u4F7F\u7528\u9ED8\u8BA4\u8FD1 7 \u5929\uFF08\u622A\u81F3\u6628\u5929\uFF09\u3002\n");
   process.exit(1);
@@ -108729,8 +108736,8 @@ function resolveMetaOverviewDateRange(start, end) {
     endD.setDate(endD.getDate() - 1);
     const startD = new Date(endD);
     startD.setDate(startD.getDate() - 6);
-    const fmt2 = (d) => d.toISOString().slice(0, 10);
-    return { startDate: fmt2(startD), endDate: fmt2(endD) };
+    const fmt = (d) => d.toISOString().slice(0, 10);
+    return { startDate: fmt(startD), endDate: fmt(endD) };
   }
   console.error("\n\u274C --start \u4E0E --end \u987B\u540C\u65F6\u4F20\u5165\uFF0C\u6216\u540C\u65F6\u7701\u7565\u4EE5\u4F7F\u7528\u9ED8\u8BA4\u8FD1 7 \u5929\uFF08\u622A\u81F3\u6628\u5929\uFF09\u3002\n");
   process.exit(1);
@@ -133252,8 +133259,8 @@ function resolveDateRange2(start, end) {
     endD.setDate(endD.getDate() - 1);
     const startD = new Date(endD);
     startD.setDate(startD.getDate() - 6);
-    const fmt2 = (d) => d.toISOString().slice(0, 10);
-    return { startDate: fmt2(startD), endDate: fmt2(endD) };
+    const fmt = (d) => d.toISOString().slice(0, 10);
+    return { startDate: fmt(startD), endDate: fmt(endD) };
   }
   console.error("\n\u274C --start \u4E0E --end \u987B\u540C\u65F6\u4F20\u5165\uFF0C\u6216\u540C\u65F6\u7701\u7565\u4EE5\u4F7F\u7528\u9ED8\u8BA4\u8FD1 7 \u5929\uFF08\u622A\u81F3\u6628\u5929\uFF09\u3002\n");
   process.exit(1);
@@ -134320,6 +134327,7 @@ function asRecord26(value) {
   return null;
 }
 function num10(value) {
+  if (value === null || value === void 0 || value === "") return void 0;
   const n = Number(value);
   return Number.isFinite(n) ? n : void 0;
 }
@@ -134334,15 +134342,19 @@ function asItems(payload) {
   return items2.filter((r) => asRecord26(r) !== null);
 }
 function pickMetrics2(row, extras = []) {
+  const spend = num10(row.spend) ?? 0;
+  const impressions = num10(row.impressions) ?? 0;
+  const clicks = num10(row.clicks) ?? 0;
+  const conversions = num10(row.conversions) ?? 0;
   const out = {
-    spend: num10(row.spend) ?? 0,
-    impressions: num10(row.impressions) ?? 0,
-    clicks: num10(row.clicks) ?? 0,
-    ctr: num10(row.ctr),
-    averageCpc: num10(row.averageCpc),
-    conversions: num10(row.conversions) ?? 0,
-    conversionRate: num10(row.conversionRate),
-    costPerConversion: num10(row.costPerConversion),
+    spend,
+    impressions,
+    clicks,
+    conversions,
+    ctr: num10(row.ctr) ?? (impressions > 0 ? clicks / impressions : void 0),
+    averageCpc: num10(row.averageCpc) ?? (clicks > 0 ? round25(spend / clicks) : void 0),
+    conversionRate: num10(row.conversionRate) ?? (clicks > 0 ? conversions / clicks : void 0),
+    costPerConversion: num10(row.costPerConversion) ?? (conversions > 0 ? round25(spend / conversions) : void 0),
     roi: num10(row.roi)
   };
   for (const f of extras) {
@@ -134619,6 +134631,39 @@ function asRecord27(value) {
 function pushMissing6(missing, id, chapter, dimension, hint) {
   missing.push({ id, chapter, dimension, hint });
 }
+function normKey(value) {
+  return String(value ?? "").trim().toLowerCase();
+}
+function insightMatchRecord(item) {
+  const rec = asRecord27(item);
+  if (!rec) return {};
+  return asRecord27(rec.match) ?? rec;
+}
+function findRowInsight(list, primaryField, primaryValue, row) {
+  const target = normKey(primaryValue);
+  if (!target) return null;
+  const candidates = list.filter((it) => normKey(insightMatchRecord(it)[primaryField]) === target);
+  if (candidates.length <= 1) return asRecord27(candidates[0]);
+  const campaign = normKey(row.campaignName);
+  const narrowed = candidates.find(
+    (it) => normKey(insightMatchRecord(it).campaignName) === campaign
+  );
+  return asRecord27(narrowed ?? candidates[0]);
+}
+function topRowsBySpend(rows, limit) {
+  return rows.map((r) => asRecord27(r)).filter((r) => r != null).sort((a, b) => (Number(b.spend) || 0) - (Number(a.spend) || 0)).slice(0, limit);
+}
+var ROW_INSIGHT_SPECS = [
+  {
+    tableKey: "keywords",
+    insightKey: "keywords",
+    matchField: "keyword",
+    requiredField: "translation",
+    limit: 40,
+    chapter: "\u2463\u5173\u952E\u8BCD",
+    label: "\u4E2D\u6587\u7FFB\u8BD1"
+  }
+];
 function validateYandexPeriodReportContent(data) {
   const missing = [];
   const meta = asRecord27(data.meta) ?? {};
@@ -134689,6 +134734,38 @@ function validateYandexPeriodReportContent(data) {
       "\u81F3\u5C11\u4E00\u9879\u6709\u6548\u6570\u5B57\uFF08\u8BF7\u4F20 --snapshot-dir \u7531 CLI \u4ECE overview \u5408\u5E76\uFF09"
     );
   }
+  const tables = asRecord27(data.tables) ?? {};
+  const rowInsights = asRecord27(narrative.rowInsights) ?? {};
+  const rowInsightCoverage = {};
+  for (const spec of ROW_INSIGHT_SPECS) {
+    const shown = topRowsBySpend(asArray7(tables[spec.tableKey]), spec.limit).filter(
+      (row) => textLen7(row[spec.matchField])
+    );
+    const insights = asArray7(rowInsights[spec.insightKey]);
+    let covered = 0;
+    const uncovered = [];
+    for (const row of shown) {
+      const insight = findRowInsight(insights, spec.matchField, row[spec.matchField], row);
+      if (insight && textLen7(insight[spec.requiredField]) > 0) {
+        covered += 1;
+      } else {
+        uncovered.push(String(row[spec.matchField]));
+      }
+    }
+    rowInsightCoverage[spec.insightKey] = { shown: shown.length, covered };
+    if (shown.length === 0) continue;
+    if (covered < shown.length) {
+      const sample = uncovered.slice(0, 3).join("\u3001");
+      const more = uncovered.length > 3 ? ` \u7B49 ${uncovered.length} \u884C` : "";
+      pushMissing6(
+        missing,
+        `row-insights-${spec.insightKey}`,
+        spec.chapter,
+        `narrative.rowInsights.${spec.insightKey}.${spec.requiredField}`,
+        `HTML \u5C06\u5C55\u793A ${shown.length} \u884C\uFF0C\u6BCF\u884C\u987B\u6709${spec.label}\uFF08\u5F53\u524D ${covered}/${shown.length}\uFF09\u3002\u672A\u8986\u76D6\u793A\u4F8B\uFF1A${sample}${more}`
+      );
+    }
+  }
   return {
     ok: missing.length === 0,
     missing,
@@ -134696,7 +134773,8 @@ function validateYandexPeriodReportContent(data) {
       executiveSummaryCount: executiveSummary.length,
       recommendationCount: recommendations.length,
       sectionAnalysisCounts,
-      sectionSuggestionCounts
+      sectionSuggestionCounts,
+      rowInsightCoverage
     }
   };
 }
@@ -134707,7 +134785,7 @@ function formatYandexPeriodReportErrors(result) {
     `\u62A5\u544A JSON \u7F3A\u5C11 ${result.missing.length} \u9879\u5FC5\u542B\u5185\u5BB9\uFF08\u5BF9\u9F50 yandex-period-report.md\uFF09\uFF1A`,
     ...lines,
     "",
-    "\u8BF7\u8865\u5168 narrative.sections.<dimension>.{analysis,suggestions} \u4E0E narrative.recommendations \u540E\u91CD\u65B0\u6267\u884C render\u3002",
+    "\u8BF7\u8865\u5168 narrative.sections.<dimension>.{analysis,suggestions}\u3001narrative.recommendations\uFF0C\u4EE5\u53CA\u8868\u683C\u884C\u5BF9\u5E94\u7684 narrative.rowInsights\uFF08\u5173\u952E\u8BCD translation\uFF09\u540E\u91CD\u65B0\u6267\u884C render\u3002",
     "\u6570\u503C\u7C7B\u5B57\u6BB5\uFF08kpis/tables\uFF09\u987B\u7531 --snapshot-dir \u4ECE\u843D\u76D8 JSON \u5408\u5E76\uFF1BAgent \u53EA\u64B0\u5199\u53D9\u4E8B\uFF0C\u7981\u6B62\u624B\u5199 HTML\u3002"
   ].join("\n");
 }

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.45-beta.2",
-  "publishedAt": 1786612533558
+  "version": "1.1.45-beta.4",
+  "publishedAt": 1786689638774
 }

package/dist/skill/references/accounts/accounts-balance-stats.md

@@ -24,7 +24,7 @@ siluzan-tso balance-scan -m <媒体类型> [选项]
 | `-m, --media <type>`                  | 必填：`Google \| TikTok \| Yandex \| MetaAd \| BingV2 \| Kwai`                       | —            |
 | `-a, --accounts <ids>`                | 指定 `mediaCustomerId`（逗号分隔）；**跳过清单翻页**，对这些 ID 拉数后全部输出 | —            |
 | `--threshold-days <n>`                | 剩余续航天数阈值                                                                     | `7`          |
-| `--spend-days <n>`                    | 日均消耗回看自然日数（截至昨天不含今天；日均 = 窗口合计 / N）                        | `7`          |
+| `--spend-days <n>`                    | 日均消耗回看自然日数（截至昨天不含今天，**北京时间**；日均 = 窗口合计 / N）          | `7`          |
 | `--min-balance <n>`                   | 绝对余额阈值（与 threshold 取并集）                                                  | —            |
 | `--min-daily-spend <n>`               | 日均消耗低于此值视为僵尸账户，不做续航估算                                           | `0.01`       |
 | `--target-days <n>`                   | 建议充值目标续航天数                                                                 | `30`         |
@@ -47,7 +47,7 @@ siluzan-tso balance-scan -m BingV2 -a id1,id2,id3 --json-out ./snap-p2-subset
 siluzan-tso balance-scan -m MetaAd --json-out ./snap-p2-meta
 ```
 
-**读盘要点**：先看 `meta.dataIssue`（非空则失败）。`data.items` = **全部已检查账户**（OAuth 失效户不在 items，见 `meta.skippedInvalidOAuth`）；`meta.hitCount` = 触阈值条数。预警筛 `hitReason !== "none"`；`hitReason="none"` 表示已检查但未触阈值。按 `remainingDays` 升序交付。用 **`dailySpend`** 做日均（口径见 `meta.spendDays` / `meta.spendWindow`），勿把 `stats` 区间合计 `spend` 当「每天消耗」。与 `balance` / `accounts-digest` 分工见 `references/core/agent-conventions.md` §八。
+**读盘要点**：先看 `meta.dataIssue`（非空则失败）。`data.items` = **全部已检查账户**（OAuth 失效户不在 items，见 `meta.skippedInvalidOAuth`）；`meta.hitCount` = 触阈值条数。预警筛 `hitReason !== "none"`；`hitReason="none"` 表示已检查但未触阈值。按 `remainingDays` 升序交付。用 **`dailySpend`** 做日均（口径见 `meta.spendDays` / `meta.spendWindow`），勿把 `stats` 区间合计 `spend` 当「每天消耗」。Google 消耗走 `account-spend-overview`，`startDate`/`endDate` 带东八区墙钟（`…T00:00:00+08:00` / `…T23:59:59+08:00`），与 `stats` 同口径。与 `balance` / `accounts-digest` 分工见 `references/core/agent-conventions.md` §八。
 
 ---
 

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

@@ -27,7 +27,7 @@
 | `google-analysis --sections overview`（Google 网关 `OverviewSectionData`）                                                                                                            | **实时**；请求起止为 **YYYY-MM-DD**（不附加时区）                                                                                                      | ✅ 可查当天                       | 当天/今日消耗、当天高消耗账号排行                |
 | `google-analysis --sections campaign-types`（`types-summary`）                                                                                                                        | **实时**                                                                                                                                               | ✅ 可查当天                       | 当天系列类型分布                                 |
 | `google-analysis` 其他 range 维度（`campaigns` / `keywords` / `devices` / `geographic` / `daily-metrics` / …）                                                                        | 实时（受 Google Ads API 同步延迟影响）；**一律 YYYY-MM-DD**（不附加时区；与 `stats` 的 UTC+8 不同）                                                    | 可查当天，但当天可能尚未结算      | 周期分析、报告                                   |
-| `stats -m Google` / `balance-scan -m Google` / `accounts-digest -m Google` / `list-accounts -m Google` 合并消耗（TSO `account-spend-overview`，2026-05 起）                           | **后端自动分流**：窗口完全在历史 → `database`；含今天 → `googleCombined`。**`stats` 请求起止按 UTC+8 墙钟**（`…T00:00:00+08:00` ~ `…T23:59:59+08:00`） | ✅ 可查当天（含今天时切实时聚合） | 历史回溯、巡检、周报 KPI、余额续航估算           |
+| `stats -m Google` / `balance-scan -m Google` / `accounts-digest -m Google` / `list-accounts -m Google` 合并消耗（TSO `account-spend-overview`，2026-05 起）                           | **后端自动分流**：窗口完全在历史 → `database`；含今天 → `googleCombined`。**凡走本接口的请求起止一律东八区墙钟**（`…T00:00:00+08:00` ~ `…T23:59:59+08:00`） | ✅ 可查当天（含今天时切实时聚合） | 历史回溯、巡检、周报 KPI、余额续航估算           |
 | `stats` / `balance-scan` / `accounts-digest` / `list-accounts` 的 **TikTok / Yandex / BingV2 / Kwai / MetaAd** 合并消耗（TSO `accountsoverview`；MetaAd OAuth 户走 `FacebookAds` 段） | **每日同步昨天**                                                                                                                                       | ❌ 查今天会全为 0                 | 历史回溯、巡检、余额续航估算（口径为"截至昨天"） |
 | `balance`（`GetMediaAccountInfo`）                                                                                                                                                    | 实时                                                                                                                                                   | —                                 | 仅当前余额，不反映消耗                           |
 

package/dist/skill/references/operations/hosted-automation-monitoring-json.md

@@ -22,7 +22,7 @@ siluzan-tso balance-scan -m Google [--threshold-days <n>] [--min-balance <n>] [-
 | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 账户                                                       | `data.items[].mediaCustomerId`、`data.items[].name`、`data.items[].advertiserName`                                                                           |
 | 余额（主币种金额，与平台余额接口一致）                     | **`data.items[].balance`**（由 `remainingAccountBudget` 计算而来）                                                                                           |
-| 近 7 日估算日均消耗                                        | **`data.items[].dailySpend`** = 近 7 日总消耗 / 7（窗口为 **[T-7, T-1]**，即截至昨天的 7 个自然日，**不含当天**，避免拉到当天未结算数据）                    |
+| 近 7 日估算日均消耗                                        | **`data.items[].dailySpend`** = 近 7 日总消耗 / 7（窗口为 **[T-7, T-1]**，北京时间截至昨天的 7 个自然日，**不含当天**；Google 请求带 `+08:00`）              |
 | 按余额÷日均估算的续航天数                                  | **`data.items[].remainingDays`** = `balance / dailySpend`（消耗过低 < `minDailySpend` 时为 `null`）                                                          |
 | 建议充值额（按 `meta.thresholds.targetDaysForTopup` 目标） | **`data.items[].recommendedTopup`**                                                                                                                          |
 | 命中原因（阈值逻辑）                                       | **`data.items[].hitReason`**：`low-days` \| `low-balance` \| `both` \| `none`（已检查但未触阈值）。`data.items` 含全部已检查账户；预警筛 `hitReason !== "none"`。`meta.hitCount` 为触阈值条数 |

package/dist/skill/references/report-templates/yandex-period-report-excel.md

@@ -89,7 +89,7 @@ siluzan-tso yandex-analysis -a <porg-xxx> --start <S> --end <E> --json-out ./sna
 | ❌ 禁止                              | ✅ 正确                                              |
 | ------------------------------------ | ---------------------------------------------------- |
 | 把 `ctr` 当已是百分数再 ÷100         | 落盘为 0~1；Excel 用百分比格式或 `*100` 后加 `%`     |
-| 编造学习期 / 翻译字段                | API 无则叙事说明「数据不可用」                       |
+| 编造学习期、搜索词分类等无接口硬事实 | 无字段且算不出则不写该列；关键词翻译走 rowInsights   |
 | `campaignId` 写成数字                | `String(id)` + 文本格式                              |
 | search-terms 拉超过 180 天           | 缩短区间或排除该维                                   |
 

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

@@ -60,6 +60,43 @@ siluzan-tso yandex-analysis render \
   - `executiveSummary[]`：≥1 段执行摘要
   - `sections.{overview,search,campaigns,keywords,searchTerms,geo,devices,daily}`：每个维度各 `{analysis[]（≥1，含数字依据）, suggestions[]（≥1）}`
   - `recommendations[]`：≥3 条跨维度优化建议（可用 `{priority,text,anchor}`，anchor 对齐样例锚点如 `#keyword` / `#query`）
+  - `rowInsights`：有关键词表格行时，**HTML 将展示的 Top N 行必须有中文翻译**；`render` 缺项会拒绝出 HTML。问题/建议可空。见下方「逐行洞察」
+
+#### 逐行洞察 `narrative.rowInsights`
+
+开发样例的部分表格列（关键词"中文翻译"、各维度"问题/建议"）不是原始接口字段，而是 **Agent 基于已拉取数据做的翻译/判断**：
+
+- **必填（`render` 校验）**：`tables.keywords` 有行时，须为 HTML 将展示的每一行（按消耗降序，最多 40 行）提供匹配的 `rowInsights`，且有非空 `translation`。缺一项即拒绝生成 HTML。
+- **可空**：各维 `issue` / `suggestion`（空表示该行无问题，模板显示「—」）。
+- 搜索词「分类」Yandex 不提供，也无法由现有指标算出，报告不展示该列。
+
+示例：
+
+```jsonc
+"narrative": {
+  "rowInsights": {
+    // 按 keyword 原文匹配（如同词跨系列，可加 campaignName 消歧）
+    "keywords": [
+      { "match": { "keyword": "металлопрокатное оборудование" }, "translation": "金属轧制设备", "issue": "", "suggestion": "可加大预算" }
+    ],
+    // 按 searchQuery 原文匹配
+    "searchTerms": [
+      { "match": { "searchQuery": "прокатный стан своими руками" }, "issue": "DIY 意图消耗", "suggestion": "添加否定短语 своими руками" }
+    ],
+    // 按 campaignName 匹配
+    "campaigns": [
+      { "match": { "campaignName": "Search - 自动定向" }, "issue": "自动定向 CTR 弱", "suggestion": "评估降价或暂停" }
+    ],
+    // 按 locationName（城市名）匹配
+    "geo": [{ "match": { "locationName": "Moscow" }, "issue": "", "suggestion": "" }],
+    // 按 device 匹配
+    "devices": [{ "match": { "device": "tablet" }, "issue": "样本不足", "suggestion": "暂不调整设备系数" }]
+  }
+}
+```
+
+- `translation` 是 Agent **对已知原文的翻译**，允许生成；不得编造原始接口没有、也无法由现有指标算出的硬事实。Campaign「学习期」、搜索词「分类」无数据源，报告不展示这两列。
+- 每条洞察按原文匹配一行；HTML 将展示的关键词行若缺中文翻译，`render` 会拒绝出 HTML。
 
 ### 快照合并范围（`--snapshot-dir`）
 
@@ -93,7 +130,7 @@ siluzan-tso yandex-analysis -a <porg-xxx> --start <S> --end <E> --json-out ./sna
 
 - 写脚本前先读各 `yandex-*-<id>.outline.txt`（或 stdout 摘要里的 outline），再脚本读 `.json`。
 - `search` / `campaigns` / `keywords` / `geo` / `devices` 在 Direct 侧过滤 `AdNetworkType=SEARCH`。
-- **无**学习期 / 关键词翻译等专用接口——相关洞察仅能基于现有字段与叙事，勿编造后端字段。
+- Campaign「学习期」、搜索词「分类」无接口字段、也无法由现有指标算出，报告不展示这两列。关键词中文翻译可由 Agent 通过 `narrative.rowInsights` 提供（见上方「逐行洞察」）。
 
 ---
 

package/dist/skill/report-templates/yandex-period-report-excel.md

@@ -89,7 +89,7 @@ siluzan-tso yandex-analysis -a <porg-xxx> --start <S> --end <E> --json-out ./sna
 | ❌ 禁止                              | ✅ 正确                                              |
 | ------------------------------------ | ---------------------------------------------------- |
 | 把 `ctr` 当已是百分数再 ÷100         | 落盘为 0~1；Excel 用百分比格式或 `*100` 后加 `%`     |
-| 编造学习期 / 翻译字段                | API 无则叙事说明「数据不可用」                       |
+| 编造学习期、搜索词分类等无接口硬事实 | 无字段且算不出则不写该列；关键词翻译走 rowInsights   |
 | `campaignId` 写成数字                | `String(id)` + 文本格式                              |
 | search-terms 拉超过 180 天           | 缩短区间或排除该维                                   |