siluzan-tso-cli 1.1.45-beta.3 → 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.3），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+> **注意**：当前为测试版（1.1.45-beta.4），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/index.js

@@ -134342,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) {
@@ -134627,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) ?? {};
@@ -134697,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,
@@ -134704,7 +134773,8 @@ function validateYandexPeriodReportContent(data) {
       executiveSummaryCount: executiveSummary.length,
       recommendationCount: recommendations.length,
       sectionAnalysisCounts,
-      sectionSuggestionCounts
+      sectionSuggestionCounts,
+      rowInsightCoverage
     }
   };
 }
@@ -134715,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.3",
-  "publishedAt": 1786677354676
+  "version": "1.1.45-beta.4",
+  "publishedAt": 1786689638774
 }

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 天           | 缩短区间或排除该维                                   |
 

package/dist/skill/report-templates/yandex-period-report.html

@@ -272,6 +272,39 @@
     return n === undefined ? "—" : n.toFixed(2);
   }
 
+  /** 接口未回 CTR/CPC/转化率时，用展示/点击/消耗/转化补算（与 merge-snapshot 口径一致）。 */
+  function derivedCtr(r) {
+    const existing = toNum(r && r.ctr);
+    if (existing !== undefined) return existing;
+    const impressions = toNum(r && r.impressions);
+    const clicks = toNum(r && r.clicks);
+    return impressions > 0 && clicks !== undefined ? clicks / impressions : undefined;
+  }
+
+  function derivedCpc(r) {
+    const existing = toNum(r && r.averageCpc);
+    if (existing !== undefined) return existing;
+    const spend = toNum(r && r.spend);
+    const clicks = toNum(r && r.clicks);
+    return clicks > 0 && spend !== undefined ? spend / clicks : undefined;
+  }
+
+  function derivedCr(r) {
+    const existing = toNum(r && r.conversionRate);
+    if (existing !== undefined) return existing;
+    const clicks = toNum(r && r.clicks);
+    const conversions = toNum(r && r.conversions);
+    return clicks > 0 && conversions !== undefined ? conversions / clicks : undefined;
+  }
+
+  function derivedCpa(r) {
+    const existing = toNum(r && r.costPerConversion);
+    if (existing !== undefined) return existing;
+    const spend = toNum(r && r.spend);
+    const conversions = toNum(r && r.conversions);
+    return conversions > 0 && spend !== undefined ? spend / conversions : undefined;
+  }
+
   function asArr(v) {
     return Array.isArray(v) ? v : [];
   }
@@ -343,39 +376,61 @@
       .slice(0, n);
   }
 
-  function metricCells(r, currency) {
-    return (
-      '<td class="num">' +
-      money(r.spend, currency) +
-      '</td><td class="num">' +
-      int(r.impressions) +
-      '</td><td class="num">' +
-      int(r.clicks) +
-      '</td><td class="num">' +
-      pct(r.ctr) +
-      '</td><td class="num">' +
-      money(r.averageCpc, currency) +
-      '</td><td class="num">' +
-      num2(r.conversions) +
-      '</td><td class="num">' +
-      pct(r.conversionRate) +
-      '</td><td class="num">' +
-      money(r.costPerConversion, currency) +
-      "</td>"
-    );
+  function normKey(v) {
+    return String(v ?? "").trim().toLowerCase();
   }
 
-  /** 对齐开发样例关键词/搜索词/地域/设备表格的列集合（含 cr% 转化率）。 */
-  const METRIC_HEADERS = [
-    { label: "消耗", num: true },
-    { label: "展示", num: true },
-    { label: "点击", num: true },
-    { label: "CTR", num: true },
-    { label: "CPC", num: true },
-    { label: "转化", num: true },
-    { label: "转化率", num: true },
-    { label: "CPA", num: true },
-  ];
+  /**
+   * 从 Agent 可选提供的 `narrative.rowInsights.<dim>[]` 里按主字段（如关键词原文/搜索词原文）
+   * 找匹配行的洞察（翻译/分类/问题/建议）。找不到返回 null——渲染层一律显示「—」，不编造内容。
+   * 每条洞察支持 `{match:{...}, ...}` 或扁平写法 `{keyword, campaignName, ...}`。
+   */
+  function findInsight(list, primaryField, primaryValue, row) {
+    const target = normKey(primaryValue);
+    if (!target) return null;
+    const candidates = asArr(list).filter(function (it) {
+      const m = (it && it.match) || it || {};
+      return normKey(m[primaryField]) === target;
+    });
+    if (candidates.length <= 1) return candidates[0] || null;
+    const cn = normKey(row && row.campaignName);
+    const narrowed = candidates.find(function (it) {
+      const m = (it && it.match) || it || {};
+      return normKey(m.campaignName) === cn;
+    });
+    return narrowed || candidates[0];
+  }
+
+  function rowInsightsOf(data, key) {
+    return asArr(((data.narrative || {}).rowInsights || {})[key]);
+  }
+
+  /**
+   * 「样本」徽标——纯阈值判断（基于点击量），不依赖大模型/不编造：
+   * 点击 <30 视为极小样本，效率类结论不可用；<100 转化类结论慎出；否则样本充足。
+   */
+  function sampleBadge(clicks) {
+    const c = toNum(clicks) || 0;
+    if (c < 30) {
+      return '<span class="badge b-danger">点击 ' + int(c) + "，样本极小，效率类结论不可用</span>";
+    }
+    if (c < 100) {
+      return '<span class="badge b-warn">点击 ' + int(c) + "，转化类结论慎出</span>";
+    }
+    return '<span class="badge b-ok">点击 ' + int(c) + "，样本充足</span>";
+  }
+
+  /** Campaign 状态徽标——只用真实 status/state 字段做颜色归类。 */
+  function campaignStatusBadge(r) {
+    const raw = r.status || r.state || "";
+    if (!raw) return '<span class="badge b-gray">—</span>';
+    const low = String(raw).toLowerCase();
+    let cls = "b-gray";
+    if (/(active|running|accept|enable)/.test(low)) cls = "b-ok";
+    else if (/(reject|declin|error)/.test(low)) cls = "b-danger";
+    else if (/(moderat|review|pending)/.test(low)) cls = "b-warn";
+    return '<span class="badge ' + cls + '">' + escapeHtml(String(raw)) + "</span>";
+  }
 
   function renderHero(data) {
     const meta = data.meta || {};
@@ -687,6 +742,10 @@
     );
   }
 
+  /**
+   * 通用维度表格：`opts.headers` / `opts.rowCells(r, currency, data)` 由调用方给出
+   * 完整列定义与单元格 HTML，逐维对齐开发样例的列顺序（而不是共用一套固定指标列）。
+   */
   function dimSection(opts) {
     const data = opts.data;
     const currency = currencyOf(data);
@@ -698,22 +757,10 @@
     if (rows.length) {
       const rowHtml = rows
         .map(function (r) {
-          const name = opts.nameOf(r);
-          return (
-            "<tr><td>" +
-            escapeHtml(name) +
-            "</td>" +
-            (opts.extraCells ? opts.extraCells(r, currency) : "") +
-            metricCells(r, currency) +
-            "</tr>"
-          );
+          return "<tr>" + opts.rowCells(r, currency, data) + "</tr>";
         })
         .join("");
-      const headers = [{ label: opts.nameLabel }].concat(
-        opts.extraHeaders || [],
-        METRIC_HEADERS
-      );
-      body = tableHtml(headers, rowHtml);
+      body = tableHtml(opts.headers, rowHtml);
     } else {
       body = '<div class="empty-note">' + EMPTY_NOTE + "</div>";
     }
@@ -732,6 +779,11 @@
       sectionHead(opts.title, desc) +
       '<div class="panel">' +
       body +
+      (opts.footnote
+        ? '<div class="empty-note" style="text-align:left;padding:0 16px 14px;">' +
+          escapeHtml(opts.footnote) +
+          "</div>"
+        : "") +
       analysisBlock(sec) +
       "</div>" +
       "</div></section>"
@@ -852,9 +904,42 @@
         tableKey: "search",
         title: "广告类型 · Search",
         desc: "搜索网络（Search）投放汇总",
-        nameLabel: "网络",
-        nameOf: function (r) {
-          return r.network || "SEARCH";
+        headers: [
+          { label: "Network" },
+          { label: "Spend", num: true },
+          { label: "Impressions", num: true },
+          { label: "Clicks", num: true },
+          { label: "CPC", num: true },
+          { label: "Conversions", num: true },
+          { label: "CPA", num: true },
+          { label: "ROI", num: true },
+          { label: "CTR", num: true },
+          { label: "样本" },
+        ],
+        rowCells: function (r, currency) {
+          return (
+            "<td>" +
+            escapeHtml(r.network || "Search") +
+            '</td><td class="num">' +
+            money(r.spend, currency) +
+            '</td><td class="num">' +
+            int(r.impressions) +
+            '</td><td class="num">' +
+            int(r.clicks) +
+            '</td><td class="num">' +
+            money(r.averageCpc, currency) +
+            '</td><td class="num">' +
+            num2(r.conversions) +
+            '</td><td class="num">' +
+            money(r.costPerConversion, currency) +
+            '</td><td class="num">' +
+            pct(r.roi) +
+            '</td><td class="num">' +
+            pct(r.ctr) +
+            "</td><td>" +
+            sampleBadge(r.clicks) +
+            "</td>"
+          );
         },
       })
     );
@@ -866,17 +951,55 @@
         tableKey: "campaigns",
         title: "Campaign",
         desc: "按消耗排序的系列明细",
-        nameLabel: "系列",
-        nameOf: function (r) {
-          return r.campaignName || r.campaignId || "—";
-        },
-        extraHeaders: [{ label: "状态" }, { label: "类型" }],
-        extraCells: function (r) {
+        headers: [
+          { label: "Campaign" },
+          { label: "预算", num: true },
+          { label: "战略" },
+          { label: "目标CPA(API)", num: true },
+          { label: "Spend", num: true },
+          { label: "Impr", num: true },
+          { label: "Clicks", num: true },
+          { label: "CPC", num: true },
+          { label: "Conv", num: true },
+          { label: "CPA", num: true },
+          { label: "状态" },
+          { label: "问题" },
+          { label: "建议" },
+        ],
+        rowCells: function (r, currency, data) {
+          const insight = findInsight(
+            rowInsightsOf(data, "campaigns"),
+            "campaignName",
+            r.campaignName,
+            r
+          );
           return (
             "<td>" +
-            escapeHtml(r.status || r.state || "—") +
+            escapeHtml(r.campaignName || r.campaignId || "—") +
+            '</td><td class="num">' +
+            (r.budget != null ? money(r.budget, currency) : "—") +
+            "</td><td>" +
+            escapeHtml(r.strategy || "—") +
+            '</td><td class="num">' +
+            (r.targetCpa != null ? money(r.targetCpa, currency) : "—") +
+            '</td><td class="num">' +
+            money(r.spend, currency) +
+            '</td><td class="num">' +
+            int(r.impressions) +
+            '</td><td class="num">' +
+            int(r.clicks) +
+            '</td><td class="num">' +
+            money(r.averageCpc, currency) +
+            '</td><td class="num">' +
+            num2(r.conversions) +
+            '</td><td class="num">' +
+            money(r.costPerConversion, currency) +
+            "</td><td>" +
+            campaignStatusBadge(r) +
             "</td><td>" +
-            escapeHtml(r.campaignType || "—") +
+            escapeHtml((insight && insight.issue) || "—") +
+            "</td><td>" +
+            escapeHtml((insight && insight.suggestion) || "—") +
             "</td>"
           );
         },
@@ -891,17 +1014,55 @@
         tableKey: "keywords",
         title: "关键词",
         desc: "按消耗排序的关键词明细",
-        nameLabel: "关键词",
-        nameOf: function (r) {
-          return r.keyword || "—";
-        },
-        extraHeaders: [{ label: "系列" }, { label: "匹配" }],
-        extraCells: function (r) {
+        footnote:
+          "「中文翻译」「问题/建议」为 Agent 撰写报告时提供（narrative.rowInsights.keywords），未提供的行显示「—」，不做机械占位。",
+        headers: [
+          { label: "Campaign" },
+          { label: "Group" },
+          { label: "Keyword" },
+          { label: "中文翻译" },
+          { label: "Impr", num: true },
+          { label: "Clicks", num: true },
+          { label: "Spend", num: true },
+          { label: "Conv", num: true },
+          { label: "CR%", num: true },
+          { label: "CPA", num: true },
+          { label: "CTR", num: true },
+          { label: "CPC", num: true },
+          { label: "问题" },
+          { label: "建议" },
+        ],
+        rowCells: function (r, currency, data) {
+          const insight = findInsight(rowInsightsOf(data, "keywords"), "keyword", r.keyword, r);
           return (
             "<td>" +
             escapeHtml(r.campaignName || "—") +
             "</td><td>" +
-            escapeHtml(r.criteriaType || "—") +
+            escapeHtml(r.adGroupId != null ? String(r.adGroupId) : "—") +
+            "</td><td>" +
+            escapeHtml(r.keyword || "—") +
+            "</td><td>" +
+            escapeHtml((insight && insight.translation) || "—") +
+            '</td><td class="num">' +
+            int(r.impressions) +
+            '</td><td class="num">' +
+            int(r.clicks) +
+            '</td><td class="num">' +
+            money(r.spend, currency) +
+            '</td><td class="num">' +
+            num2(r.conversions) +
+            '</td><td class="num">' +
+            pct(derivedCr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpa(r), currency) +
+            '</td><td class="num">' +
+            pct(derivedCtr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpc(r), currency) +
+            "</td><td>" +
+            escapeHtml((insight && insight.issue) || "—") +
+            "</td><td>" +
+            escapeHtml((insight && insight.suggestion) || "—") +
             "</td>"
           );
         },
@@ -916,17 +1077,54 @@
         tableKey: "searchTerms",
         title: "搜索词",
         desc: "按消耗排序的搜索词明细（仅近 180 天数据）",
-        nameLabel: "搜索词",
-        nameOf: function (r) {
-          return r.searchQuery || "—";
-        },
-        extraHeaders: [{ label: "匹配关键词" }, { label: "系列" }],
-        extraCells: function (r) {
+        footnote:
+          "「问题/建议」为 Agent 撰写报告时提供（narrative.rowInsights.searchTerms），未提供的行显示「—」，不做机械占位。",
+        headers: [
+          { label: "Search Query" },
+          { label: "匹配关键词" },
+          { label: "Impr", num: true },
+          { label: "Clicks", num: true },
+          { label: "CTR", num: true },
+          { label: "CPC", num: true },
+          { label: "Spend", num: true },
+          { label: "Conv", num: true },
+          { label: "cr%", num: true },
+          { label: "CPA", num: true },
+          { label: "问题" },
+          { label: "建议" },
+        ],
+        rowCells: function (r, currency, data) {
+          const insight = findInsight(
+            rowInsightsOf(data, "searchTerms"),
+            "searchQuery",
+            r.searchQuery,
+            r
+          );
           return (
             "<td>" +
+            escapeHtml(r.searchQuery || "—") +
+            "</td><td>" +
             escapeHtml(r.matchedKeyword || "—") +
+            '</td><td class="num">' +
+            int(r.impressions) +
+            '</td><td class="num">' +
+            int(r.clicks) +
+            '</td><td class="num">' +
+            pct(derivedCtr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpc(r), currency) +
+            '</td><td class="num">' +
+            money(r.spend, currency) +
+            '</td><td class="num">' +
+            num2(r.conversions) +
+            '</td><td class="num">' +
+            pct(derivedCr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpa(r), currency) +
             "</td><td>" +
-            escapeHtml(r.campaignName || "—") +
+            escapeHtml((insight && insight.issue) || "—") +
+            "</td><td>" +
+            escapeHtml((insight && insight.suggestion) || "—") +
             "</td>"
           );
         },
@@ -941,14 +1139,55 @@
         tableKey: "geo",
         title: "地域",
         desc: "按消耗排序的地域明细",
-        nameLabel: "地域",
-        nameOf: function (r) {
-          return (
+        footnote: "「国家」取自账户投放地区（meta.region）；「City」为 Yandex 返回的地域名称。",
+        headers: [
+          { label: "国家" },
+          { label: "City" },
+          { label: "Spend", num: true },
+          { label: "Clicks", num: true },
+          { label: "Impr", num: true },
+          { label: "CTR", num: true },
+          { label: "CPC", num: true },
+          { label: "Conv", num: true },
+          { label: "cr%", num: true },
+          { label: "CPA", num: true },
+          { label: "问题" },
+          { label: "建议" },
+        ],
+        rowCells: function (r, currency, data) {
+          const cityName =
             r.locationName ||
             r.targetingLocationName ||
             r.location ||
             r.name ||
-            (r.locationId != null ? "地域 " + r.locationId : "—")
+            (r.locationId != null ? "地域 " + r.locationId : "—");
+          const insight = findInsight(rowInsightsOf(data, "geo"), "locationName", cityName, r);
+          return (
+            "<td>" +
+            escapeHtml((data.meta && data.meta.region) || "—") +
+            "</td><td>" +
+            escapeHtml(cityName) +
+            '</td><td class="num">' +
+            money(r.spend, currency) +
+            '</td><td class="num">' +
+            int(r.clicks) +
+            '</td><td class="num">' +
+            int(r.impressions) +
+            '</td><td class="num">' +
+            pct(derivedCtr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpc(r), currency) +
+            '</td><td class="num">' +
+            num2(r.conversions) +
+            '</td><td class="num">' +
+            pct(derivedCr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpa(r), currency) +
+            "</td><td>" +
+            escapeHtml((insight && insight.issue) || "—") +
+            "</td><td>" +
+            escapeHtml((insight && insight.suggestion) || "—") +
+            "</td>"
           );
         },
         limit: 30,
@@ -962,9 +1201,46 @@
         tableKey: "devices",
         title: "设备",
         desc: "按消耗排序的设备明细",
-        nameLabel: "设备",
-        nameOf: function (r) {
-          return r.device || "—";
+        headers: [
+          { label: "Device" },
+          { label: "Spend", num: true },
+          { label: "impr", num: true },
+          { label: "Clicks", num: true },
+          { label: "ctr", num: true },
+          { label: "CPC", num: true },
+          { label: "Conv", num: true },
+          { label: "cr%", num: true },
+          { label: "CPA", num: true },
+          { label: "问题" },
+          { label: "建议" },
+        ],
+        rowCells: function (r, currency, data) {
+          const insight = findInsight(rowInsightsOf(data, "devices"), "device", r.device, r);
+          return (
+            "<td>" +
+            escapeHtml(r.device || "—") +
+            '</td><td class="num">' +
+            money(r.spend, currency) +
+            '</td><td class="num">' +
+            int(r.impressions) +
+            '</td><td class="num">' +
+            int(r.clicks) +
+            '</td><td class="num">' +
+            pct(derivedCtr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpc(r), currency) +
+            '</td><td class="num">' +
+            num2(r.conversions) +
+            '</td><td class="num">' +
+            pct(derivedCr(r)) +
+            '</td><td class="num">' +
+            money(derivedCpa(r), currency) +
+            "</td><td>" +
+            escapeHtml((insight && insight.issue) || "—") +
+            "</td><td>" +
+            escapeHtml((insight && insight.suggestion) || "—") +
+            "</td>"
+          );
         },
         limit: 20,
       })

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