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

package/README.md

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

package/dist/index.js

@@ -116848,7 +116848,7 @@ function register20(program2) {
   );
   addPmaxJsonOptions(
     adCmd.command("pmax-youtube-link").description(
-      "\u4E3A\u8D44\u4EA7\u7EC4\u94FE\u63A5\u6216\u66FF\u6362 YouTube \u89C6\u9891\uFF08POST .../youtube\uFF1B\u4F1A\u5148\u79FB\u9664\u5DF2\u6709 YOUTUBE_VIDEO \u518D\u6302\u65B0\u7247\uFF09\n  --youtube\uFF1A\u5DF2\u6709 URL/ID\uFF1B--video-path\uFF1A\u672C\u5730\u6587\u4EF6\u7ECF PyAPI \u4E0A\u4F20\u540E\u94FE\u63A5"
+      "\u4E3A\u8D44\u4EA7\u7EC4\u8FFD\u52A0\u5355\u6761 YouTube \u89C6\u9891\uFF08POST .../youtube\uFF1B\u9ED8\u8BA4\u4E0D\u66FF\u6362\u5DF2\u6709\u89C6\u9891\uFF0C\u6BCF\u8D44\u4EA7\u7EC4 \u226415 \u6761\uFF09\n  --youtube\uFF1A\u5DF2\u6709 URL/ID\uFF1B--video-path\uFF1A\u672C\u5730\u6587\u4EF6\u7ECF PyAPI \u4E0A\u4F20\u540E\u94FE\u63A5\uFF1B\u6279\u91CF\u8FFD\u52A0\u7528 pmax-assets-update"
     ).requiredOption("-a, --account <id>", "Google \u5A92\u4F53\u5BA2\u6237 ID").requiredOption("--asset-group-id <id>", "\u8D44\u4EA7\u7EC4 ID").option("--campaign-id <id>", "\u6240\u5C5E\u6D3B\u52A8 ID\uFF08\u5EFA\u8BAE\u4F20\uFF09").option("--youtube <urlOrId>", "YouTube URL \u6216 11 \u4F4D\u89C6\u9891 ID\uFF08\u4E0E --video-path \u4E8C\u9009\u4E00\uFF09").option("--video-path <path>", "\u672C\u5730\u89C6\u9891\u8DEF\u5F84\uFF08PyAPI \u4E0A\u4F20\uFF1B\u4E0E --youtube \u4E8C\u9009\u4E00\uFF09").option("--video-title <title>", "PyAPI \u4E0A\u4F20\u6807\u9898\uFF08\u9ED8\u8BA4\u6587\u4EF6\u540D\uFF09").option("--video-description <text>", "PyAPI \u4E0A\u4F20\u63CF\u8FF0").option("--asset-name <name>", "\u8D44\u4EA7\u663E\u793A\u540D").option("--body-file <path>", "\u5B8C\u6574 JSON body\uFF08\u542B youtubeUrlOrId\uFF1B\u8986\u76D6 --youtube/--video-path\uFF09").option("-t, --token <token>", "Auth Token")
   ).action(
     async (opts) => {
@@ -122389,7 +122389,7 @@ var FACEBOOK_SECTIONS = [
   },
   {
     name: "platform",
-    description: "\u6295\u653E\u5E73\u53F0 PlatformSectionData\uFF08facebook / instagram \u7B49\uFF09",
+    description: "\u6295\u653E\u5E73\u53F0\xD7\u7248\u4F4D PlatformSectionData\uFF08publisherPlatform + platformPosition\uFF1Bnetwork \u517C\u5BB9\u65E7\u7248\uFF09",
     segment: "PlatformSectionData"
   },
   {

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.27-beta.2",
-  "publishedAt": 1780643679737
+  "version": "1.1.27-beta.3",
+  "publishedAt": 1780645792583
 }

package/dist/skill/assets/pmax-assets-update-template.json

@@ -1,14 +1,45 @@
 {
-  "_comment": "PUT .../asset-group/{assetGroupId}/assets；campaignId 必填",
+  "_comment": "PUT .../asset-group/{assetGroupId}/assets；campaignId 必填。YOUTUBE_VIDEO 默认追加（≤15/资产组）；替换全部视频时设 replaceFieldTypes: [\"YOUTUBE_VIDEO\"]",
   "account": "6326027735",
   "campaignId": "12345678901",
   "assetGroupId": "98765432101",
   "assetsToLink": [
     {
-      "fieldType": 2,
+      "fieldType": "HEADLINE",
       "text": "Extra headline from CLI"
     }
   ],
   "assetGroupAssetResourceNamesToRemove": [],
-  "replaceFieldTypes": []
+  "replaceFieldTypes": [],
+  "_examples": {
+    "appendYoutubeVideos": {
+      "assetsToLink": [
+        {
+          "fieldType": "YOUTUBE_VIDEO",
+          "youtubeVideoId": "dQw4w9WgXcQ",
+          "assetName": "Promo1"
+        },
+        {
+          "fieldType": "YOUTUBE_VIDEO",
+          "youtubeVideoId": "https://youtu.be/jNQXAC9IVRw",
+          "assetName": "Promo2"
+        }
+      ]
+    },
+    "replaceAllYoutubeVideos": {
+      "replaceFieldTypes": ["YOUTUBE_VIDEO"],
+      "assetsToLink": [
+        {
+          "fieldType": "YOUTUBE_VIDEO",
+          "youtubeVideoId": "9bZkp7q19f0",
+          "assetName": "NewPromo"
+        }
+      ]
+    },
+    "unlinkYoutube": {
+      "assetGroupAssetResourceNamesToRemove": [
+        "customers/6326027735/assetGroupAssets/98765432101~7~12345"
+      ]
+    }
+  }
 }

package/dist/skill/assets/pmax-create-template.md

@@ -62,7 +62,7 @@ siluzan-tso ad campaigns -a <accountId> --json-out ./snap
 | `biddingStrategyTypeV2` | string | | 默认 `MAXIMIZE_CONVERSIONS` |
 | `targetCpa_BidingAmount` | number | | `TARGET_CPA` 或带目标 CPA 的 `MAXIMIZE_CONVERSIONS` 时必填（**元**） |
 | `targetRoas` | number | | `TARGET_ROAS` 时必填（如 `2.5` = 250%） |
-| `videoPath` | string | | YOUTUBE_VIDEO（可选）：本地视频 ≥10s；与 `youtubeUrlOrId` 二选一，创建时最多 1 条 |
+| `videoPath` | string | | YOUTUBE_VIDEO（可选）：本地视频 ≥10s；与 `youtubeUrlOrId` 二选一，创建时最多 1 条；更多视频创建后用 `pmax-youtube-link` / `pmax-assets-update` 追加 |
 | `videoTitle` | string | | PyAPI 上传标题（默认文件名） |
 | `videoDescription` | string | | PyAPI 上传描述（可选） |
 | `youtubeUrlOrId` | string | | 已有 YouTube URL 或 11 位 ID；`pmax-create` 后自动链接 |

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

@@ -280,6 +280,7 @@ siluzan-tso facebook-analysis -a <mediaCustomerId> --start YYYY-MM-DD --end YYYY
 | `-a, --account` | 数字 `mediaCustomerId` 或 `act_<数字>` |
 | `--json-out` | 必填；`report-manifest-<id>.json` + `<section>-<id>.json` |
 | `--sections` / `--exclude` | `overview` `ad-sets` `platform` `country` `audience` `creative` `material`；**别名**：`campaigns`→`ad-sets`，`geographic`→`country`，`devices`→`platform`，`ads`→`creative`，`materials`→`material` |
+| `platform` 响应字段 | `networks[]` 含 `publisherPlatform`（投放平台）+ `platformPosition`（版位）；`network` 与 `platformPosition` 同值，详见 `facebook-analysis-guide.md` |
 | `--limit` | 仅 `country`：按 spend 降序前 N 条 |
 | `--start` / `--end` | 同传或同省略；省略=近 7 天截至昨天 |
 | `--concurrency` | 默认 5，上限 16 |

package/dist/skill/references/analytics/facebook-analysis-guide.md

@@ -12,7 +12,7 @@
 | 每日趋势 `daily-metrics` | ❌ 无接口 | — | 报告中注明「Meta 报告无按日 Section」 |
 | 月度汇总 `dimension-summary` | ⚠️ 用 `overview` 单周期汇总代替 | `overview` | 仅 currentPeriod 即全区间汇总 |
 | 系列 `campaigns` | ⚠️ 广告组 + 行上 `campaignName` | `ad-sets` | 无独立 Campaign Section；可按 `campaignName` 聚合撰写 |
-| 设备 `devices` | ⚠️ 投放平台 | `platform` | `facebook` / `instagram` / `audience_network` 等 |
+| 设备 `devices` | ⚠️ 投放平台 × 版位 | `platform` | `publisherPlatform`（facebook / instagram 等）+ `platformPosition`（feed / facebook_reels 等） |
 | 地域 `geographic` | ✅ 国家 | `country` | 可选 `--limit N` |
 | 关键词 `keywords` | ❌ 无 | — | 非搜索广告；章节写「不适用」 |
 | 受众 `audience` | ⚠️ 年龄×性别 | `audience` | 无兴趣/自定义受众列表 |
@@ -59,13 +59,33 @@
 
 ---
 
+## PlatformSectionData 字段（平台 / 版位）
+
+后端按 Meta `publisher_platform,platform_position` breakdown 拆分（2026-06 起）。`networks[]` 每行：
+
+| 字段 | 含义 | 示例 |
+| ---- | ---- | ---- |
+| `publisherPlatform` | 投放平台（Meta `publisher_platform`） | `facebook`、`instagram`、`audience_network` |
+| `platformPosition` | 版位（Meta `platform_position`） | `feed`、`facebook_reels`、`instagram_stories`、`instream_video` |
+| `network` | 兼容旧前端，**等于 `platformPosition`** | 勿单独当作「平台」列使用 |
+
+**撰写表格建议列**：投放平台 | 版位 | 展示 | 花费 | 结果 | 单次成效费用。
+
+**汇总规则**：
+
+- 按**平台**占比：对 `publisherPlatform` 聚合 `spend` / `results`。
+- 按**版位**占比：对 `platformPosition` 聚合（跨平台合并同名版位时须注明）。
+- 精细诊断：保留 `publisherPlatform` + `platformPosition` 组合行（如 `instagram` + `feed` vs `facebook` + `feed`）。
+
+---
+
 ## 各 Section 文件与章节要点
 
 | section | 落盘文件 | 根字段 | 报告章节要点 |
 | ------- | -------- | ------ | ------------ |
 | `overview` | `overview-<id>.json` | `currentPeriod`, `previousPeriod` | 环比表：消耗、展示、点击、CTR、CPC、转化、CPA、结果、单次成效、reach、frequency；注明 `resultType` / `attributionSetting` |
 | `ad-sets` | `ad-sets-<id>.json` | `adGroups[]` | Top 组 by spend；`spendPercentage`；按 `campaignName` 归并；高消耗低结果组 |
-| `platform` | `platform-<id>.json` | `networks[]` | 各版位 spend 占比与 `costPerResult`；预算倾斜建议 |
+| `platform` | `platform-<id>.json` | `networks[]` | **两列维度**：`publisherPlatform`（投放平台）+ `platformPosition`（版位）；`network` 与 `platformPosition` 同值（兼容旧版）。同版位名可能跨平台出现（如 facebook/instagram 均有 `feed`），**禁止**仅用 `network` 当平台汇总 |
 | `country` | `country-<id>.json` | `countries[]` | Top 国家；`countryOrRegion` 为展示名 |
 | `audience` | `audience-<id>.json` | `audiences[]` | 年龄×性别矩阵；高/低效人群段 |
 | `creative` | `creative-<id>.json` | `creatives[]` | 按 `creativeType` 汇总；Top 创意表（adName、title、spend、results、costPerResult） |
@@ -93,7 +113,7 @@ siluzan-tso facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb
 结合已拉维度，至少覆盖：
 
 1. **预算**：高 `spendPercentage` 但 `costPerResult` 差的 Ad Set → 降预算/暂停。
-2. **版位**：某 `network` CPA 明显差 → 减投或单独系列。
+2. **平台/版位**：按 `publisherPlatform` + `platformPosition` 定位高消耗低 `costPerResult` 组合（勿只读 `network`）；可分别按平台或版位汇总后给减投建议。
 3. **地域**：高消耗国家转化差 → 收窄/geo 排除。
 4. **受众**：低效 age×gender → 收窄定向。
 5. **创意**：关停高消耗低 `results` 的 ad；复制 winner 的 `creativeType`/文案结构。

package/dist/skill/references/google-ads/google-ads.md

@@ -48,7 +48,7 @@
 
 **图片**：配置 `imagePaths`（相对 JSON 文件目录）或 `marketingImageBase64` / `squareMarketingImageBase64` / `logoImageBase64`。`pmax-validate` 会自动校验图片尺寸（最小值 / 推荐值 / 宽高比 ±2% / 文件大小 ≤5120 KB）。如需将任意图片转为合规素材，用 `ad pmax-image-convert`（`marketing` / `square` / `logo` 三种格式，sharp 处理，居中裁切）。
 
-**视频**：`videoPath`（本地文件，经 `{googleApiUrl}/pyapi` 上传并轮询 `video_id` 后自动链接）与 `youtubeUrlOrId` **二选一**；或创建后 `ad pmax-youtube-link`。
+**视频**：`videoPath`（本地文件，经 `{googleApiUrl}/pyapi` 上传并轮询 `video_id` 后自动链接）与 `youtubeUrlOrId` **二选一**（创建时最多 1 条）；创建后追加更多视频用 `ad pmax-youtube-link`（单条）或 `ad pmax-assets-update`（批量，每资产组 ≤15 条）。
 
 **禁止**：对已创建的 PMax 系列使用 `ad campaign-edit`（旧 PUT 会 **400**）。
 
@@ -62,7 +62,7 @@
 | 改资产组 | `ad pmax-asset-group-edit` |
 | 删资产组 | `ad pmax-asset-group-edit --status REMOVED`（软删；网关无 DELETE 端点） |
 | 改资产 | `ad pmax-assets-update --config-file …` |
-| YouTube 链接/替换 | `ad pmax-youtube-link`（`--youtube` 或 `--video-path`） |
+| YouTube 追加 | `ad pmax-youtube-link`（单条 `--youtube` / `--video-path`）；批量见 `ad pmax-assets-update` |
 | 信号 | `ad pmax-signals-get` / `ad pmax-signals-set`；受众下拉 `ad pmax-audiences` |
 | 图片库 | `ad pmax-image-upload` |
 | 报表 | `ad pmax-report-asset-groups` / `ad pmax-report-geo` |

package/dist/skill/references/google-ads/pmax-api.md

@@ -23,7 +23,7 @@
 | `ad pmax-asset-group-create` | 新建资产组 |
 | `ad pmax-asset-group-edit` | 编辑资产组 |
 | `ad pmax-assets-update` | 更新资产 |
-| `ad pmax-youtube-link` | 关联/替换 YouTube（会移除资产组内已有视频再挂新片） |
+| `ad pmax-youtube-link` | **追加**单条 YouTube 视频（不替换已有视频） |
 | `ad pmax-signals-get` / `ad pmax-signals-set` | 读/写信号（**全量** PUT） |
 | `ad pmax-audiences` | 受众列表 |
 | `ad pmax-image-upload` | 单张图片上传 |
@@ -38,13 +38,50 @@
 2. `ad pmax-validate` → 用户确认 → `ad pmax-create`：CLI **自动上传**三张图并写入 `*ImageAssetId`（Body 不含 Base64）。
 3. 可选预上传：`ad pmax-image-upload -a <id> --image-path ./x.png`，将返回 `id` 写入 JSON。
 
-### 视频
+### 视频（YouTube）
+
+**语义（与后端 `pmax-frontend-api.md` §5.3 / §5.4 一致）**：`YOUTUBE_VIDEO` 默认 **追加**，每个资产组最多 **15** 条；不可重复链接同一 `videoId`。仅当 `pmax-assets-update` 显式传 `replaceFieldTypes: ["YOUTUBE_VIDEO"]` 时才会先删后增（替换全部视频）。
+
+| 场景 | 命令 / 接口 |
+|------|-------------|
+| 创建时挂 1 条 | `pmax-create` JSON：`videoPath` 或 `youtubeUrlOrId`（二选一，单次最多 1 条） |
+| 追加 1 条 | `ad pmax-youtube-link` → `POST .../asset-group/{id}/youtube` |
+| 批量追加多条 | `ad pmax-assets-update` → `PUT .../assets`，`assetsToLink` 中多条 `YOUTUBE_VIDEO` |
+| 取消链接 | `ad pmax-assets-update`，`assetGroupAssetResourceNamesToRemove`（取自 `pmax-get` 的 `assets[].assetResourceName`） |
+| 替换全部视频 | `ad pmax-assets-update`，`replaceFieldTypes: ["YOUTUBE_VIDEO"]` + 新的 `assetsToLink` |
+
+**创建时自动链接**
 
 - **`videoPath`**：本地 `.mp4` 等；`pmax-create` 经 **GoogleAdsPyAPI** `POST {googleApiUrl}/pyapi/video/upload` 上传，轮询 `GET .../upload/status` 得 `video_id`，再 `POST .../asset-group/{id}/youtube` 链接（与 `youtubeUrlOrId` 二选一）。
 - **`youtubeUrlOrId`**：已有 YouTube URL 或 11 位 ID；创建成功后自动链接。
-- **已创建系列换视频**：`ad pmax-youtube-link`（同一接口；后端先删旧 `YOUTUBE_VIDEO` 再链接新片）：
-  - `--youtube "<url或ID>"` 或 `--video-path ./new.mp4`（可选 `--video-title`）
-  - 示例：`siluzan-tso ad pmax-youtube-link -a <id> --asset-group-id <agId> --campaign-id <cid> --video-path ./promo-v2.mp4`
+
+**已创建系列追加视频**（`ad pmax-youtube-link`）：
+
+```bash
+# 已有 YouTube URL / ID
+siluzan-tso ad pmax-youtube-link -a <id> --asset-group-id <agId> --campaign-id <cid> \
+  --youtube "https://www.youtube.com/watch?v=xxxxx"
+
+# 本地视频（PyAPI 上传后追加）
+siluzan-tso ad pmax-youtube-link -a <id> --asset-group-id <agId> --campaign-id <cid> \
+  --video-path ./promo-v2.mp4 --video-title "宣传视频 2"
+```
+
+**批量追加**（`ad pmax-assets-update --config-file ./pmax-videos.json`）：
+
+```json
+{
+  "account": "6326027735",
+  "campaignId": "12345678901",
+  "assetGroupId": "98765432101",
+  "assetsToLink": [
+    { "fieldType": "YOUTUBE_VIDEO", "youtubeVideoId": "dQw4w9WgXcQ", "assetName": "Promo1" },
+    { "fieldType": "YOUTUBE_VIDEO", "youtubeVideoId": "https://youtu.be/jNQXAC9IVRw", "assetName": "Promo2" }
+  ]
+}
+```
+
+`youtubeVideoId` 接受 11 位 ID 或完整 URL。模板见 `assets/pmax-assets-update-template.json`。
 
 ---
 

package/dist/skill/report-templates/meta-account-diagnosis-report.md

@@ -47,6 +47,7 @@ siluzan-tso facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb
 ## 8. 平台、地域、受众
 
 - **CLI**：`platform`、`country`、`audience`
+- `platform` → `networks[]`：用 **`publisherPlatform`**（投放平台）+ **`platformPosition`**（版位）；`network` 仅等于 `platformPosition`（兼容旧版，勿当平台列）。
 - 全表或 Top 表；与 Google `devices` / `geographic` / `audience` 对应说明。
 
 ## 9. 创意（替代搜索词+搜索广告）

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

@@ -13,7 +13,7 @@
 | --- | --- | --- | --- | --- |
 | 1 | 执行摘要 | overview | `overview` | OverviewSectionData |
 | 2 | 投放结构（广告组 / 系列归并） | campaigns | `ad-sets`（别名 `campaigns`） | AdSetSectionData |
-| 3 | 投放平台分布 | devices（版位） | `platform`（别名 `devices`） | PlatformSectionData |
+| 3 | 投放平台 × 版位分布 | devices（版位） | `platform`（别名 `devices`） | PlatformSectionData |
 | 4 | 国家/地区分布 | geographic | `country`（别名 `geographic`） | CountrySectionData |
 | 5 | 受众（年龄×性别） | audience（子集） | `audience` | AudienceSectionData |
 | 6 | 广告创意表现 | ads + materials（子集） | `creative`（别名 `ads`） | CreativeSectionData |
@@ -60,10 +60,13 @@ siluzan-tso facebook-analysis -a <mediaCustomerId> --start <s> --end <e> --json-
 - Top 5～10 广告组表；可按 `campaignName` 小计 spend 占比。
 - 指出：高消耗 + 高 `costPerResult` 或低 `results` 的组。
 
-### 3. 投放平台
+### 3. 投放平台 × 版位
 
-- 数据源：`networks[]`；`network` + 效果指标。
-- 各平台花费占比；最佳/最差 `costPerResult` 平台。
+- 数据源：`networks[]`。
+- **必用字段**：`publisherPlatform`（投放平台，如 facebook / instagram）+ `platformPosition`（版位，如 feed / facebook_reels）。`network` 与 `platformPosition` 同值，仅兼容旧版，**勿**单独当「平台」列。
+- 表格建议列：投放平台 | 版位 | 花费 | 花费占比 | 结果 | 单次成效费用。
+- 先给 **按 `publisherPlatform` 汇总** 的花费占比；再列 Top 版位组合（含跨平台同名版位，如 instagram/feed 与 facebook/feed 须分行）。
+- 指出：高花费 + 高 `costPerResult` 的平台或版位组合。
 
 ### 4. 国家/地区
 

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