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

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

@@ -0,0 +1,121 @@
+# Yandex Direct — 账户分析报告（模板纲要）
+
+> 统计区间：`{startDate}` ~ `{endDate}`（**不能晚于今天**；省略默认近 7 天含今天）  
+> 账户：`{mediaCustomerId}`（如 `porg-xxx`，与 `list-accounts -m Yandex` 一致）  
+> **默认交付物**：一份可打开的 **HTML 文件**（`yandex-period-report.html`，样式对齐开发样例）。  
+> 用户**未指定格式**时一律走下方 **标准四步流程**；**禁止** Agent 手写/拼接 HTML。  
+> **用户明确要求 Excel / xlsx** 时：拉数步骤不变，改为 Agent 脚本写 `.xlsx`；**不要**调用 `yandex-analysis render`；禁止假设存在内置 excel 子命令。见 `yandex-period-report-excel.md`。
+
+数据块（YandexAPI `/yandex-analysis` 8 维 + 本地周聚合）：总览、按日、Search 网络、系列、关键词、搜索词、地域、设备；周报由 `daily` 本地聚合（后端无独立 weekly）。
+
+| CLI `--sections` | 落盘形状（CI 实测）                                      | 报告 `tables.*` / KPI                                      |
+| ---------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
+| `overview`       | 对象：`account` / `currency` / `balance` / `totals` …    | → `meta` + `kpis`（余额、日均、续航天数）                  |
+| `daily`          | `{ account, startDate, endDate, items: DayRow[] }`       | → `tables.daily[]`；并聚合 → `tables.weekly[]`             |
+| `search`         | `{ …, items: SearchRow[] }`                              | → `tables.search[]`                                        |
+| `campaigns`      | `{ …, items: CampaignRow[] }`（默认 limit=100）          | → `tables.campaigns[]`                                     |
+| `keywords`       | `{ …, items: KeywordRow[] }`                             | → `tables.keywords[]`                                      |
+| `search-terms`   | `{ …, items: SearchTermRow[] }`（**仅近 180 天**）       | → `tables.searchTerms[]`                                   |
+| `geo`            | `{ …, items: GeoRow[] }`                                 | → `tables.geo[]`                                           |
+| `devices`        | `{ …, items: DeviceRow[] }`                              | → `tables.devices[]`                                       |
+
+> 金额已为账户币种小数；`ctr` / `conversionRate` 为 **0~1 小数**。写叙事前先读各维 `*.outline.txt`。
+
+---
+
+## 标准四步流程（默认 · 交付 HTML）
+
+| 步骤             | 执行者       | 动作                                                                                                                                     |
+| ---------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. 拉数**      | Agent 调 CLI | `yandex-analysis -a <porg-xxx> --start <s> --end <e> --json-out ./snap-yandex`（全 8 维或 `--sections` 指定子集）                        |
+| **2. 分析**      | Agent        | 用 **node/python 脚本**读落盘 JSON（勿用 Read 打开业务 `*.json`），对照 outline 完成聚合与洞察                                           |
+| **3. 写 JSON**   | Agent        | 撰写 `yandex-period-report.json`：仅 `meta.accountId` + `narrative`（8 个分析章节）为必填；`kpis`/`tables` 可省略由 `--snapshot-dir` 合并 |
+| **4. 渲染 HTML** | CLI          | `yandex-analysis render` — **校验 narrative 8 个分析章节必含字段**，缺项报错不生成 HTML；**禁止** Agent 手写/拼接 HTML                   |
+
+```bash
+# 步骤 1
+siluzan-tso yandex-analysis -a <porg-xxx> --start <s> --end <e> --json-out ./snap-yandex
+
+# 步骤 4（步骤 2～3 完成后）
+siluzan-tso yandex-analysis render \
+  --data ./yandex-period-report.json \
+  --snapshot-dir ./snap-yandex \
+  --out ./yandex-period-report.html
+```
+
+### `yandex-period-report.json` 顶层结构
+
+- `meta`：`accountId`（必填）/ `accountName` / `currency` / `region` / `startDate` / `endDate` / `platform`；可省略由 `--snapshot-dir` 从 overview 补空。
+- `kpis`：`spend` / `impressions` / `clicks` / `conversions` / `ctr` / `averageCpc` / `costPerConversion` / `conversionRate` / `roi` / `balance` / `avgDailySpend` / `activeDays` / `runwayDays` / `balanceAsOf`；可省略。
+- `tables`（可省略，由 `--snapshot-dir` 映射）：
+  - `daily[]`：`{date, spend, impressions, clicks, ctr, averageCpc, conversions, …}`
+  - `weekly[]`：`{weekLabel, startDate, endDate, days, spend, impressions, clicks, ctr, averageCpc, conversions, costPerConversion}`（CLI 由 daily 聚合）
+  - `search[]`：`{network, spend, …}`
+  - `campaigns[]`：`{campaignId, campaignName, status, state, campaignType, budget, strategy, …metrics}`
+  - `keywords[]`：`{keyword, campaignName, criteriaType, network, …metrics}`
+  - `searchTerms[]`：`{searchQuery, matchedKeyword, campaignName, …metrics}`
+  - `geo[]`：`{locationName, targetingLocationName, network, …metrics}`
+  - `devices[]`：`{device, network, …metrics}`
+- `narrative`（**Agent 必填**）：
+  - `executiveSummary[]`：≥1 段执行摘要
+  - `sections.{overview,search,campaigns,keywords,searchTerms,geo,devices,daily}`：每个维度各 `{analysis[]（≥1，含数字依据）, suggestions[]（≥1）}`
+  - `recommendations[]`：≥3 条跨维度优化建议（可用 `{priority,text,anchor}`，anchor 对齐样例锚点如 `#keyword` / `#query`）
+
+### 快照合并范围（`--snapshot-dir`）
+
+`render` 传 `--snapshot-dir` 时，CLI 自动补全：
+
+1. `meta`（仅补空字段）
+2. **`kpis` / `tables.*` 一律以 CLI 快照覆盖**（有对应 section 时）
+3. `tables.weekly` 由 `daily.items` 本地 ISO 周聚合
+
+Agent 只需撰写 `narrative`；**禁止手写 HTML**，也**禁止**自填 `kpis`/`tables` 数值。
+
+---
+
+## 日期规则（必读）
+
+- `--start` / `--end` 须**同传或同省略**；**不能晚于今天**；省略=近 7 天（含今天）。
+- **search-terms** 仅支持近 **180 天**；超窗网关/CLI 拒绝——拉长区间时对该维用 `--exclude search-terms` 或缩短区间。
+- 用户说「X 月 / 月报」且该月已结束：`--start` 当月 1 日、`--end` 当月最后一天。
+
+---
+
+## 拉数（一次目录）
+
+```bash
+mkdir -p ./snap-yandex
+
+siluzan-tso list-accounts -m Yandex -k <porg-xxx> --json-out ./snap-yandex
+
+siluzan-tso yandex-analysis -a <porg-xxx> --start <S> --end <E> --json-out ./snap-yandex
+```
+
+- 写脚本前先读各 `yandex-*-<id>.outline.txt`（或 stdout 摘要里的 outline），再脚本读 `.json`。
+- `search` / `campaigns` / `keywords` / `geo` / `devices` 在 Direct 侧过滤 `AdNetworkType=SEARCH`。
+- **无**学习期 / 关键词翻译等专用接口——相关洞察仅能基于现有字段与叙事，勿编造后端字段。
+
+---
+
+## HTML 章节与锚点（对齐开发样例）
+
+| 锚点        | 章节           | 数据 / 叙事来源                                      |
+| ----------- | -------------- | ---------------------------------------------------- |
+| `#overview` | 账户总览       | `kpis` + `tables.weekly` + 每日折叠 + `sections.overview` |
+| `#next`     | 后续优化动作   | `narrative.recommendations`                          |
+| `#search`   | Search 网络    | `tables.search` + `sections.search`                  |
+| `#campaign` | Campaign       | `tables.campaigns` + `sections.campaigns`            |
+| `#keyword`  | 关键词         | `tables.keywords` + `sections.keywords`              |
+| `#query`    | 搜索词         | `tables.searchTerms` + `sections.searchTerms`        |
+| `#geo`      | 地域           | `tables.geo` + `sections.geo`                        |
+| `#device`   | 设备           | `tables.devices` + `sections.devices`                |
+| `#daily`    | 日报表         | `tables.daily` + `sections.daily`                    |
+| `#weekly`   | 周报表         | `tables.weekly`（同 daily 叙事）                     |
+
+---
+
+## 相关文档
+
+- `yandex-period-report-excel.md` — 用户要 xlsx 时
+- `references/analytics/account-analytics.md` — `yandex-analysis` 命令与日期
+- `references/core/agent-conventions.md` — 落盘读盘与交付自检

package/dist/skill/scripts/install.ps1

@@ -9,11 +9,11 @@ $ErrorActionPreference = 'Stop'
 # -- Package info (injected at build time) ------------------------------------
 $PKG_NAME    = 'siluzan-tso-cli'
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-$PKG_VERSION = '1.1.44'
+$PKG_VERSION = '1.1.45-beta.2'
 $CLI_BIN     = 'siluzan-tso'
 $SKILL_LABEL = 'Siluzan TSO'
-$INSTALL_CMD = 'npm install -g siluzan-tso-cli'
-$WEB_BASE    = 'https://www.siluzan.com'
+$INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'
+$WEB_BASE    = 'https://www-ci.siluzan.com'
 
 # -- Constants ----------------------------------------------------------------
 $NODE_MAJOR_MIN    = 18

package/dist/skill/scripts/install.sh

@@ -9,11 +9,11 @@ set -euo pipefail
 # -- Package info (injected at build time) ------------------------------------
 readonly PKG_NAME="siluzan-tso-cli"
 # PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
-readonly PKG_VERSION="1.1.44"
+readonly PKG_VERSION="1.1.45-beta.2"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
-readonly INSTALL_CMD="npm install -g siluzan-tso-cli"
-readonly WEB_BASE="https://www.siluzan.com"
+readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"
+readonly WEB_BASE="https://www-ci.siluzan.com"
 
 # -- Constants ----------------------------------------------------------------
 readonly NODE_MAJOR_MIN=18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.1.44",
+  "version": "1.1.45-beta.2",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",
@@ -63,12 +63,14 @@
     "networkEndpoints": [
       "tso-api.siluzan.com",
       "googleapi.mysiluzan.com",
+      "yandexapi.mysiluzan.com",
       "www.siluzan.com",
       "o605862.ingest.us.sentry.io",
       "registry.npmjs.org"
     ],
     "optionalEnvVars": [
       "SILUZAN_GOOGLE_API",
+      "SILUZAN_YANDEX_API",
       "SILUZAN_API_KEY"
     ]
   },