npm - siluzan-tso-cli - Versions diffs - 1.1.19-beta.2 → 1.1.19-beta.3 - Mend

siluzan-tso-cli 1.1.19-beta.2 → 1.1.19-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +1 -1
package/dist/skill/SKILL.md +3 -3
package/dist/skill/_meta.json +2 -2
package/dist/skill/report-templates/README.md +1 -1
package/dist/skill/report-templates/REPORT-WORKFLOW.md +1 -1
package/dist/skill/report-templates/okki-weekly-google-client.md +114 -20
package/package.json +1 -1

package/README.md CHANGED Viewed

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

package/dist/skill/SKILL.md CHANGED Viewed

@@ -5,7 +5,7 @@ description: >-
   写 Google 搜索方案/计划/待确认结构表时先读 references/google-ads.md。
   关键字规划师/拓词/竞品网址拓词/词包清洗/否词/建户关键词编排：先读 references/keyword-planner-workflows.md。
   ①竞品URL+种子拓词→JSON筛排TopN ②多种子长尾 ③月搜阈值与词根/意图洗词 ④google-analysis keywords 叠分批 keyword 市场指标 ⑤search-terms 与拓词对照否词线索 ⑥CPC/竞争度/搜索量筛高意图 ⑦否词表+ad keyword-negative-create ⑧Campaign→AdGroup→匹配表+ad 落地 ⑨keyword --json-out 供脚本复用。无 Forecast、无 Planner 官方按月 12 个月趋势接口。
-  运营「OKKI 周报」固定话术（如「使用okki周报模板生成…」）→ `report-templates/okki-weekly-google-client.md`，仅用现有 `stats`/`balance`/`google-analysis`，不新增拉数命令。
+  运营「OKKI 周报」固定话术（如「使用okki周报模板生成…」）→ `report-templates/okki-weekly-google-client.md`：拉数仅用现有 `stats`/`balance`/`google-analysis`（不新增拉数子命令）；**多 Sheet Excel 由 Agent 落盘后写脚本生成**，CLI **不**提供内置「写 Excel」子命令。
 license: MIT
 metadata:
   requires: nodejs,siluzan-tso-cli
@@ -56,7 +56,7 @@ Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令
 | `references/finance.md`                        | 转账、开票、发票抬头、充值网页引导                                                                                                                                                                                                                                                                                                       |
 | `references/write-audit-restore.md`            | 本机写审计、`--commit`、补偿写 `audit restore-plan` / `restore-apply`                                                                                                                                                                                                                                                                    |
 | `report-templates/report-template.html`        | 默认 HTML 报告样式参考                                                                                                                                                                                                                                                                                                                   |
-| `report-templates/okki-weekly-google-client.md` | **OKKI 周报**：固定客户话术 + 精简维度（`google-analysis` + `stats` + `balance`），见 Playbook P6                                                                                                                                                                                                                                        |
+| `report-templates/okki-weekly-google-client.md` | **OKKI 周报**：固定话术 + 精简维度 CLI 拉数；**Excel 由 Agent 脚本写**（见 P6），无 CLI 内置写表命令                                                                                                                                                                                                                                        |
 ---
@@ -220,7 +220,7 @@ siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --jso
 1. **不要**按 `google-period-report.md` 展开默认 8 维并追问追加；改读 **`report-templates/okki-weekly-google-client.md`** 全文并按其结构交付。
 2. 确认 `mediaCustomerId` 与 `--start` / `--end`（未给齐则按上文「时间范围强制反问」）。
 3. 同一 `--json-out` 目录执行模板中的命令组合：`list-accounts`（可选但推荐）、`stats`、`balance`、`google-analysis --sections overview,campaigns,keywords,search-terms,devices,geographic`。
-4. **先 outline 后脚本**：读各 `*.outline.txt`，编写并执行代码从 JSON 填「客户话术」块；复盘与优化建议可附于后；可选按该模板「可选交付」节写多 Sheet Excel。
+4. **先 outline 后脚本**：读各 `*.outline.txt`，再编写并执行代码从 JSON 计算并写出：① 客户话术（Markdown/纯文本均可）；② 若需 **Excel**：**必须**产出多 Sheet `.xlsx`（版式与 Sheet 名见模板「必选交付」节），**只能**由 Agent 在当前环境执行脚本生成，**禁止**假设存在 `siluzan-tso … excel` 类 CLI 子命令。WorkBuddy 等编排器须在流程中显式包含「写 `.xlsx` 脚本并执行」一步，否则易缺产物。
 5. 遵守 SKILL 硬规范：金额 `*Display`、禁止手填业务数、禁止编造 ID。
 ### P5 · 多账户多维度报告

package/dist/skill/_meta.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.19-beta.2",
-  "publishedAt": 1778567157660
+  "version": "1.1.19-beta.3",
+  "publishedAt": 1778568598630
 }

package/dist/skill/report-templates/README.md CHANGED Viewed

@@ -21,7 +21,7 @@
 | `meta-period-report.md`              | Meta（Facebook）账户周期报告                      |
 | `tiktok-period-report.md`            | TikTok 广告主周期报告                             |
 | `bing-period-report.md`              | Bing（BingV2）分析报告                            |
-| `okki-weekly-google-client.md`       | **OKKI 周报**：Google 发客户固定话术 + 精简维度（见 SKILL P6） |
+| `okki-weekly-google-client.md`       | **OKKI 周报**：Google 发客户固定话术 + 精简维度 CLI；**Excel 仅 Agent 脚本**（无 CLI 写表子命令），见 SKILL P6 |
 ---

package/dist/skill/report-templates/REPORT-WORKFLOW.md CHANGED Viewed

@@ -74,7 +74,7 @@
 | 用户措辞                       | 映射                                                              |
 | ------------------------------ | ----------------------------------------------------------------- |
 | 月报、周报、投放总结、效果回顾 | 周期分析 → 对应媒体 `*-period-report.md`                          |
-| **使用 okki 周报模板 / OKKI 周报 / okki 周报**（Google + 区间） | **固定话术 + 精简表** → `okki-weekly-google-client.md`（见 SKILL **P6**），**不**再走 `google-period-report.md` 的默认 8 维追问 |
+| **使用 okki 周报模板 / OKKI 周报 / okki 周报**（Google + 区间） | **固定话术 + 精简表 +（按需）Excel** → `okki-weekly-google-client.md`（见 SKILL **P6**）；Excel **仅**由 Agent 脚本生成，**无** CLI 内置写表子命令 |
 | 健康检查、诊断、账户分析       | 诊断 → `google-account-diagnosis-report.md`（Google）或周期型降级 |
 | 对比、汇报、给客户看           | 以周期型为骨架，简化版本                                          |

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

@@ -3,7 +3,8 @@
 > **触发话术（等价即可）**
 > `使用okki周报模板生成<账户名或ID>，<YYYY-MM-DD>--<YYYY-MM-DD>的投放报告`
 > 同义：`OKKI 周报`、`okki 周报模板`、`运营 OKKI 周报`。
-> **媒体**：当前模板仅规范 **Google**（`mediaCustomerId`）。其他媒体用各自 `*-period-report.md`。
+> **媒体**：当前模板仅规范 **Google**（`mediaCustomerId`）。其他媒体用各自 `*-period-report.md`。
+> **Excel 版式基准**：与运营样表《**数据复盘分析**》类 xlsx 对齐（如 `2025.12数据复盘分析.xlsx`）：**工作簿 5 个 Sheet、顺序与表头**以本文「最终 xlsx 版式规范」为准；Agent 生成产物须可与之逐 Sheet 对照验收。
 识别到上述意图时：**不要**再走 `google-period-report.md` 的「默认 8 维 + 追问追加」流程；按本文**固定维度 + 固定客户话术**交付即可（数据仍全部来自 CLI 落盘 JSON，见 `references/account-analytics.md`）。
@@ -14,6 +15,15 @@
 1. **账户**：`mediaCustomerId` 来自 `list-accounts -m Google -k <id>`，禁止猜 ID。
 2. **统计区间**：`--start` / `--end`（用户未给齐时按 SKILL 反问；授权默认时可用「上一完整自然周」白名单并写明）。
 3. **询盘口径**：模板正文第 7 条默认使用 **区间内 `conversions`（转化次数）**（来自 `stats` 或 `overview` 汇总）。若运营将「询盘」定义为某一类转化，须在报告首段脚注说明数据来源（必要时补拉 `google-analysis --sections conversion-actions` 仅作说明，不替代统计口径 unless 用户确认）。
+4. **日期写法**：用户可能写 `2026.4.1`、`2026/4/1` 等，Agent 须先规范为 CLI 要求的 **`YYYY-MM-DD`**（如 `2026-04-01`）再传 `--start` / `--end`。
+---
+## 架构约定（Excel 谁来做）
+- **`siluzan-tso` 不提供**「一键生成 OKKI Excel」的内置子命令，也**不要**在 CLI 里新增此类能力。
+- **需要交付 Excel 时**：由 **Agent（含 WorkBuddy 编排）** 在下列 CLI **`--json-out` 落盘完成后**，自行编写并执行 **Node.js / Python** 脚本（可选用 `exceljs`、`xlsx`、`openpyxl` 等）读取目录内 JSON → 按本文「多 Sheet 版式」写出 `.xlsx`。
+- 脚本与依赖可在当前工作区临时添加（如 `package.json` + `npm install` 或 `pip install`），或由宿主环境预装；**数值一律来自落盘 JSON**，禁止在脚本源码里写死业务数字。
 ---
@@ -43,6 +53,107 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 ---
+## 最终 xlsx 版式规范（与运营样表对齐）
+以下按 **工作簿 → Sheet 名（须完全一致）→ 版式** 约定，便于 WorkBuddy / 人工用样表对照验收。**不**再单独建名为「广告系列」的 Sheet（系列表在 **`账户报告`** 内）。
+### 工作簿级
+| 顺序 | Sheet 名 | 数据来源（CLI 落盘） |
+| ---: | ---------- | -------------------- |
+| 1 | `账户报告` | `campaigns` + 复盘文案（stats/overview 汇总后由 Agent 撰写） |
+| 2 | `关键词` | `keywords` |
+| 3 | `搜索词` | `search-terms` |
+| 4 | `设备` | `devices` |
+| 5 | `国家` | `geographic`（列「地理位置」为**国家/地区**中文名） |
+### 各 Sheet 共同版式
+- **第 1 行（A1）**：该 Sheet 的**报告标题**（见下表「R1 标题」）。建议合并单元格横跨数据区（样表约 A1:K1 / A1:N1）。
+- **第 2 行（A2）**：统计区间，**中文可读**：`YYYY年M月D日 - YYYY年M月D日`（由 `--start` / `--end` 转换，与样表一致）。
+- **第 3 行**：**表头**（列名、顺序须与下表一致）。
+- **第 4 行起**：数据行；列宽与自动筛选、首行冻结为可选（样表含 `autoFilter`、部分 Sheet 对数据区设默认**按费用/转化相关列降序**排序，Agent 可复现或省略，**不得**因此改数）。
+### 百分比与金额（与样表一致）
+- **点击率、转化率、互动率**等列：样表为 **0～1 小数**（例如 7.95% 存 `0.0795`）；若写百分比数字列须与运营约定二选一，**禁止**同一文件混用。
+- **费用、CPC、每次转化费用、预算**等：与 `references/account-analytics.md` 一致；`campaigns` 中 **`budgetAmount` 为分**，展示为「元」须 **÷100**；同条 `spend`、`averageCpc` 等已为**元**。
+---
+### Sheet `账户报告`
+| 行 | 内容 |
+| --- | --- |
+| R1 标题 | `广告系列报告`（与样表一致；若运营统一改名，可改文案但须保持 Sheet 名仍为 `账户报告`） |
+| R2 | 统计区间（中文日期，见上） |
+| R3 表头（A→K，共 11 列） | `广告系列` \| `预算` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `所有转化次数` \| `转化次数` \| `每次转化费用` \| `转化率` |
+| R4… | 每行一条广告系列：来自 `campaigns-*.json` 的 `campaignName`、`budgetAmount`（÷100 为元）、`spend`、`impressions`、`clicks`、`ctr`（或 `clicks/impressions`）、`averageCpc`、**所有转化**与 **转化**字段以 JSON 及 outline 为准映射（若网关仅提供 `conversions`，缺列填 `0` 或留空并在脚注说明） |
+| 末行「合计」 | **广告系列**列填 `总计`；**预算**列填 `--`；其余列按列语义对上方数据行做**求和或可加和指标**；**点击率 / 转化率**须用合计展示、点击、转化等**重算**，禁止对各行比率取算术平均 |
+表下**留白若干行**后写 **「数据复盘」**（与样表一致）：
+- 首行标题：`{结束日所在月份}月份数据复盘：`（例：`12月份数据复盘：`）。
+- 接续 **5 条结构化要点**（每条一行或自动换行，对应样表逻辑）：
+  **1. 账户层级**（整体消耗、展示、点击、点击率与 3% 基准对比、询盘/转化数、平均询盘成本等，数来自 stats/overview 与上表合计）；
+  **2. 关键词层级**（高转化词、高消耗低转化词及出价/竞争力建议）；
+  **3. 搜索字词层级**（标红/高意向词、否词与加词建议）；
+  **4. 设备层级**（消耗与转化在各设备的分布）；
+  **5. 国家层级**（高消耗/低转化国家与降权/调价建议）。
+  文案由 Agent 据 JSON 撰写，**不得编造**表中不存在的数字。
+---
+### Sheet `关键词`
+| 行 | 内容 |
+| --- | --- |
+| R1 标题 | `搜索关键字报告` |
+| R2 | 统计区间（同 `账户报告`） |
+| R3 表头（A→L，共 12 列） | `关键字` \| `匹配类型` \| `广告系列` \| `广告组` \| `费用` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
+| R4… | `keywords-*.json` 行映射；`keywordMatchType` → 匹配类型；`campaignName` / `adGroupName` 等按 outline |
+---
+### Sheet `搜索词`
+| 行 | 内容 |
+| --- | --- |
+| R1 标题 | `搜索字词报告` |
+| R2 | 统计区间 |
+| R3 表头（A→N，共 14 列） | `搜索字词` \| `匹配类型` \| `已添加/已排除` \| `广告系列` \| `广告组` \| `关键字` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
+| R4… | `search-terms-*.json`；`已添加/已排除` 若 JSON 无此枚举则留空或填「—」，禁止臆造状态 |
+---
+### Sheet `设备`
+| 行 | 内容 |
+| --- | --- |
+| R1 标题 | `设备报告` |
+| R2 | 统计区间 |
+| R3 表头（A→M，共 13 列） | `设备` \| `级别` \| `出价调整` \| `广告系列` \| `广告组` \| `展示次数` \| `点击次数` \| `点击率` \| `平均每次点击费用` \| `费用` \| `转化次数` \| `每次转化费用` \| `转化率` |
+| R4… | `devices-*.json`：`deviceType` → 设备；**级别 / 出价调整** 若 JSON 无字段则留空或「—」 |
+---
+### Sheet `国家`
+| 行 | 内容 |
+| --- | --- |
+| R1 标题 | `地理位置报告` |
+| R2 | 统计区间 |
+| R3 表头（A→L，共 12 列） | `地理位置` \| `广告系列` \| `展示次数` \| `互动次数` \| `互动率` \| `费用` \| `平均费用` \| `点击次数` \| `点击率` \| `转化次数` \| `每次转化费用` \| `转化率` |
+| R4… | `geographic-*.json`：`countryOrRegion` → 地理位置；**互动次数 / 互动率 / 平均费用** 按 outline 与网关字段映射，无则留空或从 `interactions` 等派生并注释 |
+---
+## Excel 交付（谁来做）
+若用户或运营要求交付 **xlsx**：须满足上文**最终 xlsx 版式规范**；实现仍遵守本文开头「架构约定」——**仅**由 Agent 写脚本生成，**无** CLI 内置写表命令。
+---
 ## 对外客户话术（固定结构，填数来自 JSON）
 首行建议：
@@ -52,7 +163,7 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 正文模板：
 ```
-您好，同步一下谷歌<S>--<E>的投放报告投放数据：
+您好，同步一下谷歌<S>--<E>的投放数据：
 1. 消耗：共消耗<金额+币种>，平均每天消耗<金额+币种>
 2. 展示点击：带来<曝光>次曝光，<点击>个点击；
@@ -79,27 +190,10 @@ siluzan-tso google-analysis -a <mediaCustomerId> --start <S> --end <E> --json-ou
 ---
-## 可选交付：多 Sheet Excel（版式约定）
-无新 CLI 命令时，由 **脚本**（Node/Python + 所选 xlsx 库）从快照目录读 JSON 写出：
-| Sheet 名   | 内容 |
-| ---------- | ---- |
-| `账户报告` | 上文「客户话术」全文 + 「复盘小结」+「优化建议」+ **广告系列**数据表（与 `campaigns` JSON 一致列） |
-| `广告系列` | 可选：与上表相同仅表；若运营希望单 Sheet「账户报告」含表，则可省略本 Sheet |
-| `关键词`   | `keywords` 落盘表 |
-| `搜索词`   | `search-terms` 落盘表 |
-| `设备`     | `devices` 落盘表 |
-| `国家`     | `geographic` 落盘表（列名含国家/地区即可） |
-列名与单位与 JSON / `references/account-analytics.md` 金额规则一致（`campaigns` 的 `budgetAmount` 为分，须 ÷100 为元等）。
----
 ## 与 `google-period-report.md` 的差异
 | 项 | 周期报告 `google-period-report.md` | 本文 OKKI 周报 |
 | -- | ---------------------------------- | ---------------- |
 | 默认维度 | 8 维 + 主动追问可选追加 | **固定** `overview,campaigns,keywords,search-terms,devices,geographic` + `stats` + `balance` |
-| 输出形态 | 长文分析报告 | **固定话术** + 短复盘 + 可选 Excel |
+| 输出形态 | 长文分析报告 | **固定话术** + 短复盘 + **多 Sheet Excel（Agent 脚本写，非 CLI）** |
 | 典型用户 | 内部分析 | **发客户**的同步简报 |

package/package.json CHANGED Viewed

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