siluzan-tso-cli 1.1.29-beta.2 → 1.1.29-beta.21

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 (169) hide show
  1. package/README.md +1 -1
  2. package/dist/index.js +3174 -867
  3. package/dist/skill/AGENTS.md +30 -31
  4. package/dist/skill/SKILL.md +16 -33
  5. package/dist/skill/_meta.json +2 -2
  6. package/dist/skill/assets/campaign-create-keyword-test.fixed.json +10 -33
  7. package/dist/skill/assets/campaign-create-template.json +2 -0
  8. package/dist/skill/assets/campaign-create-template.md +114 -99
  9. package/dist/skill/assets/market-analysis-rules.md +55 -55
  10. package/dist/skill/assets/meta-period-report-rules.md +61 -60
  11. package/dist/skill/assets/pmax-asset-group-template.json +12 -4
  12. package/dist/skill/assets/pmax-asset-group-template.md +25 -0
  13. package/dist/skill/assets/pmax-brand-assets-template.json +25 -0
  14. package/dist/skill/assets/pmax-brand-assets-template.md +22 -0
  15. package/dist/skill/assets/pmax-brand-guidelines-enable-template.json +24 -0
  16. package/dist/skill/assets/pmax-brand-guidelines-enable-template.md +22 -0
  17. package/dist/skill/assets/pmax-create-template.json +41 -2
  18. package/dist/skill/assets/pmax-create-template.md +84 -51
  19. package/dist/skill/assets/pmax-lead-form-template.json +36 -0
  20. package/dist/skill/assets/pmax-lead-form-template.md +70 -0
  21. package/dist/skill/assets/pmax-signals-template.json +2 -6
  22. package/dist/skill/assets/pmax-whatsapp-template.json +26 -0
  23. package/dist/skill/assets/pmax-whatsapp-template.md +45 -0
  24. package/dist/skill/assets/website-diagnosis-rules.md +67 -67
  25. package/dist/skill/references/README.md +78 -65
  26. package/dist/skill/references/accounts/accounts.md +99 -105
  27. package/dist/skill/references/accounts/finance.md +23 -79
  28. package/dist/skill/references/accounts/open-account-by-media.md +84 -81
  29. package/dist/skill/references/accounts/open-account-google-ui.md +24 -24
  30. package/dist/skill/references/analytics/account-analytics.md +94 -103
  31. package/dist/skill/references/analytics/facebook-analysis-guide.md +61 -61
  32. package/dist/skill/references/analytics/google-analysis-batch.md +2 -2
  33. package/dist/skill/references/analytics/keyword-planner-workflows.md +22 -23
  34. package/dist/skill/references/analytics/market-analysis-guide.md +31 -25
  35. package/dist/skill/references/analytics/rag.md +20 -20
  36. package/dist/skill/references/analytics/reporting.md +4 -4
  37. package/dist/skill/references/analytics/website-diagnosis-guide.md +24 -24
  38. package/dist/skill/references/core/agent-conventions.md +136 -106
  39. package/dist/skill/references/core/cli-enums.md +47 -53
  40. package/dist/skill/references/core/playbooks.md +42 -41
  41. package/dist/skill/references/core/subagent-orchestration.md +40 -40
  42. package/dist/skill/references/core/tips.md +18 -61
  43. package/dist/skill/references/core/workflows.md +36 -29
  44. package/dist/skill/references/google-ads/google-ads-campaign-plan.md +25 -24
  45. package/dist/skill/references/google-ads/google-ads.md +81 -57
  46. package/dist/skill/references/google-ads/pmax-api.md +138 -34
  47. package/dist/skill/references/google-ads/rules/README.md +15 -15
  48. package/dist/skill/references/google-ads/rules/google-ads-account-audit.md +22 -22
  49. package/dist/skill/references/google-ads/rules/google-ads-compliance.md +27 -27
  50. package/dist/skill/references/google-ads/rules/google-ads-keyword-strategy.md +15 -15
  51. package/dist/skill/references/google-ads/rules/google-ads-keyword-taxonomy.md +32 -22
  52. package/dist/skill/references/google-ads/rules/google-ads-launch-plan-template.md +32 -30
  53. package/dist/skill/references/google-ads/rules/google-ads-pmax-guide.md +3 -1
  54. package/dist/skill/references/misc/tso-home.md +8 -8
  55. package/dist/skill/references/operations/clue.md +1 -1
  56. package/dist/skill/references/operations/forewarning.md +1 -1
  57. package/dist/skill/references/operations/hosted-automation-optimize-index.md +2 -2
  58. package/dist/skill/references/operations/hosted-automation-scenarios.md +5 -5
  59. package/dist/skill/references/operations/hosted-automation-self-control.md +15 -15
  60. package/dist/skill/references/operations/hosted-automation-user-catalog.md +13 -13
  61. package/dist/skill/references/operations/optimize.md +8 -8
  62. package/dist/skill/references/report-templates/README.md +45 -0
  63. package/dist/skill/references/report-templates/REPORT-WORKFLOW.md +114 -0
  64. package/dist/skill/references/report-templates/bing-period-report.md +65 -0
  65. package/dist/skill/references/report-templates/google-account-diagnosis-report.md +83 -0
  66. package/dist/skill/references/report-templates/google-ads-diagnosis.md +378 -0
  67. package/dist/skill/references/report-templates/google-inquiry-analysis.md +543 -0
  68. package/dist/skill/references/report-templates/google-period-report-excel.md +126 -0
  69. package/dist/skill/references/report-templates/google-period-report.md +60 -0
  70. package/dist/skill/references/report-templates/market-analysis-report.md +40 -0
  71. package/dist/skill/references/report-templates/meta-account-diagnosis-report.md +74 -0
  72. package/dist/skill/references/report-templates/meta-period-report-excel.md +230 -0
  73. package/dist/skill/references/report-templates/meta-period-report.md +219 -0
  74. package/dist/skill/references/report-templates/okki-weekly-google-client.md +217 -0
  75. package/dist/skill/references/report-templates/tiktok-period-report.md +56 -0
  76. package/dist/skill/references/report-templates/website-diagnosis-report.md +79 -0
  77. package/dist/skill/report-templates/README.md +16 -14
  78. package/dist/skill/report-templates/REPORT-WORKFLOW.md +13 -13
  79. package/dist/skill/report-templates/google-account-diagnosis-report.md +1 -1
  80. package/dist/skill/report-templates/google-ads-diagnosis.md +21 -21
  81. package/dist/skill/report-templates/google-inquiry-analysis.md +44 -44
  82. package/dist/skill/report-templates/google-period-report-excel.md +24 -24
  83. package/dist/skill/report-templates/google-period-report.md +23 -23
  84. package/dist/skill/report-templates/market-analysis-report.md +1 -1
  85. package/dist/skill/report-templates/meta-period-report-excel.md +72 -64
  86. package/dist/skill/report-templates/meta-period-report.html +706 -428
  87. package/dist/skill/report-templates/meta-period-report.md +61 -60
  88. package/dist/skill/report-templates/okki-weekly-google-client.md +26 -26
  89. package/dist/skill/report-templates/report-template-academic.html +1 -1
  90. package/dist/skill/report-templates/report-template-dark.html +1 -1
  91. package/dist/skill/report-templates/report-template-formal.html +1 -1
  92. package/dist/skill/report-templates/report-template-mobile.html +1 -1
  93. package/dist/skill/report-templates/report-template-onepager.html +1 -1
  94. package/dist/skill/report-templates/report-template-print.html +1 -1
  95. package/dist/skill/report-templates/report-template.html +1 -1
  96. package/dist/skill/report-templates/website-diagnosis-report.html +1731 -1653
  97. package/dist/skill/report-templates/website-diagnosis-report.md +21 -23
  98. package/dist/skill/scripts/install.ps1 +1 -1
  99. package/dist/skill/scripts/install.sh +1 -1
  100. package/dist/skill/snippets/handoff-p7-inquiry.md +5 -5
  101. package/eval/cases/accounts-entityid-vs-mediaccustomerid.scenario.json +2 -14
  102. package/eval/cases/accounts-mcc-bind-inquiry.scenario.json +1 -3
  103. package/eval/cases/accounts-single-balance-not-bulk.scenario.json +3 -14
  104. package/eval/cases/budget-display-not-raw-micros.scenario.json +1 -8
  105. package/eval/cases/clue-meta-leads-json.scenario.json +2 -14
  106. package/eval/cases/clue-tiktok-leads-json.scenario.json +2 -11
  107. package/eval/cases/destructive-account-delink-needs-confirm.scenario.json +3 -9
  108. package/eval/cases/destructive-forewarning-delete-needs-confirm.scenario.json +3 -9
  109. package/eval/cases/destructive-invoice-apply-needs-confirm.scenario.json +3 -9
  110. package/eval/cases/facebook-analysis-google-section-aliases.scenario.json +2 -11
  111. package/eval/cases/facebook-analysis-not-google-keywords.scenario.json +3 -10
  112. package/eval/cases/facebook-analysis-period-default.scenario.json +2 -14
  113. package/eval/cases/finance-invoice-info-list.scenario.json +3 -11
  114. package/eval/cases/forewarning-list-google.scenario.json +3 -14
  115. package/eval/cases/google-ads-no-structural-without-confirm.scenario.json +2 -6
  116. package/eval/cases/google-analysis-keywords-route.scenario.json +2 -14
  117. package/eval/cases/human-p1-multiturn.scenario.json +1 -5
  118. package/eval/cases/meta-single-balance-not-bulk.scenario.json +3 -17
  119. package/eval/cases/no-legacy-json-flag.scenario.json +2 -6
  120. package/eval/cases/open-account-google-noninteractive.scenario.json +1 -3
  121. package/eval/cases/open-account-tiktok-license-file.scenario.json +1 -3
  122. package/eval/cases/optimize-list-by-account.scenario.json +3 -11
  123. package/eval/cases/p1-single-account-profile.scenario.json +1 -11
  124. package/eval/cases/p2-balance-scan-bulk.scenario.json +2 -9
  125. package/eval/cases/p3-accounts-digest.scenario.json +1 -5
  126. package/eval/cases/p4-fb-meta-period-report.scenario.json +2 -12
  127. package/eval/cases/p4-period-report-window.scenario.json +1 -8
  128. package/eval/cases/pmax-asset-group-create-with-bg.scenario.json +15 -0
  129. package/eval/cases/pmax-brand-edit-routing.scenario.json +12 -0
  130. package/eval/cases/pmax-edit-not-campaign-edit.scenario.json +15 -0
  131. package/eval/cases/pmax-enable-brand-guidelines.scenario.json +15 -0
  132. package/eval/cases/pmax-no-assets-update-brand-fields.scenario.json +12 -0
  133. package/eval/cases/rag-before-keyword-expand.scenario.json +1 -11
  134. package/eval/cases/rag-list-then-query.scenario.json +2 -14
  135. package/eval/cases/report-list-google.scenario.json +2 -11
  136. package/eval/cases/report-push-list-google.scenario.json +2 -11
  137. package/eval/cases/setup-login-or-env.scenario.json +1 -3
  138. package/eval/cases/setup-siluzan-data-permission-env.scenario.json +1 -3
  139. package/eval/cases/tiktok-bc-bind-inquiry.scenario.json +2 -6
  140. package/eval/cases/time-range-user-delegates-default.scenario.json +1 -8
  141. package/eval/cases/tips-json-out-filtering.scenario.json +1 -3
  142. package/eval/cases/tips-large-json-pagination.scenario.json +1 -3
  143. package/eval/cases/uj-ad-campaign-validate-before-create-stub.scenario.json +2 -11
  144. package/eval/cases/uj-ad-outdoor-campgear-search-plan.scenario.json +1 -3
  145. package/eval/cases/uj-analytics-30d-pdf-campaign-device-geo.scenario.json +6 -18
  146. package/eval/cases/uj-analytics-compare-google-tiktok-last-month-roi.scenario.json +1 -8
  147. package/eval/cases/uj-analytics-google-weekly-trends-campaigns-keywords.scenario.json +2 -11
  148. package/eval/cases/uj-analytics-report-push-weekly-email.scenario.json +1 -3
  149. package/eval/cases/uj-finance-invoice-records-this-month.scenario.json +2 -11
  150. package/eval/cases/uj-life-newbie-siluzan-google-end-to-end.scenario.json +1 -4
  151. package/eval/cases/uj-ops-google-accounts-list-normal.scenario.json +2 -17
  152. package/eval/cases/uj-ops-google-yesterday-spend-conversions.scenario.json +2 -14
  153. package/eval/cases/uj-ops-pause-worst-adgroup-confirm.scenario.json +2 -6
  154. package/eval/cases/uj-ops-tiktok-leads-last-week.scenario.json +3 -17
  155. package/eval/cases/uj-patrol-cpc-spike-adgroups-over-15.scenario.json +1 -5
  156. package/eval/cases/uj-patrol-forewarning-create-daily-cap-3000.scenario.json +1 -3
  157. package/eval/cases/uj-patrol-forewarning-trigger-records.scenario.json +3 -17
  158. package/eval/cases/uj-patrol-google-balances-low.scenario.json +2 -11
  159. package/eval/cases/uj-roi-optimize-records-then-execute-cautiously.scenario.json +3 -14
  160. package/eval/cases/uj-roi-search-terms-add-negative-keywords.scenario.json +2 -14
  161. package/eval/stub-fixtures/facebook-analysis.json +24 -4
  162. package/eval/stub-fixtures/meta-overview.json +4 -1
  163. package/eval/stub-fixtures/pmax-asset-group-create-ok.json +12 -0
  164. package/eval/stub-fixtures/pmax-brand-assets-edit-ok.json +11 -0
  165. package/eval/stub-fixtures/pmax-brand-guidelines-enable-ok.json +11 -0
  166. package/eval/stub-fixtures/pmax-edit-ok.json +11 -0
  167. package/eval/stub-fixtures/pmax-get-bg-on.json +20 -0
  168. package/package.json +1 -1
  169. package/dist/skill/references/core/deliverable-preflight.md +0 -109
package/dist/skill/references/analytics/account-analytics.md CHANGED
@@ -34,22 +34,13 @@
34
34
  > 「使用 okki 周报模板」固定话术 → **P6**，不按 `google-period-report.md` 默认 8 维追问。
35
35
  > 用户要 **Google 周期 Excel**（非 OKKI/询盘）→ **P4** + 全文 Read `report-templates/google-period-report-excel.md`（先 outline 后写 xlsx 脚本）。
36
36
 
37
- 通用纪律（详见 `core/tips.md` 与 `core/deliverable-preflight.md`）：
38
-
39
- - **拉数**：`google-analysis … --json-out <dir>`（Google）或 `report <media>-*` 命令落盘；目录内生成 `<section>-<accountId>.json` + `manifest-<accountId>.json`（Meta/TikTok/Bing 为 `report-manifest-<accountId>.json`）。
40
- - **消费**：先 Read `<section>-<accountId>.outline.txt` 了解字段 → **仅用脚本** `require`/`readFileSync` 读业务 JSON → 由脚本计算并写出最终产物；**禁止**用 Read 打开业务 `*.json`、**禁止**对话里心算/手填、**禁止**把应从 JSON 读取的业务数据写成源码字面量。
41
- - **stdout** 仅一行摘要（`absoluteSnapshotDir`/`writtenFiles`/`manifestFile`），完整数据从落盘文件读。
42
- - **报告首行**标注 `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`，交付后帮用户打开文件。
37
+ 拉数落盘：`google-analysis … --json-out <dir>`（Google）或 `report <media>-*` 命令；目录内生成 `<section>-<accountId>.json` + `manifest-<accountId>.json`（Meta/TikTok/Bing 为 `report-manifest-<accountId>.json`）。读盘协议、交付自检与报告首行标注统一见 `core/agent-conventions.md` §三、§七。
43
38
 
44
39
  ---
45
40
 
46
41
  ## 报告硬约束
47
42
 
48
- 以下约束与 SKILL.md 一致，此处强调报告场景的具体应用：
49
-
50
- ### 账户状态 ≠ 广告系列状态
51
-
52
- `stats`/`balance`/`list-accounts` 的账户 `status` 只表示账户可用，**不能**推断系列是否在投。系列是否启用**必须**来自 `ad campaigns`（含 `statusDisplay` 等）或 `google-analysis --sections campaigns` 落盘的系列数据。报告中「系列状态列」不得来自账户接口。
43
+ 报告中「系列状态列」不得来自账户接口（账户状态 ≠ 系列状态，见 `core/agent-conventions.md` §四）：系列是否启用**必须**来自 `ad campaigns`（含 `statusDisplay`）或 `google-analysis --sections campaigns` 落盘的系列数据。
53
44
 
54
45
  ### 金额单位
55
46
 
@@ -57,11 +48,11 @@ CLI 出口的所有 JSON / 表格金额已统一为**元**，关键字段：
57
48
 
58
49
  | 命令 / Section | 元字段 |
59
50
  | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
60
- | `ad campaigns --json-out ./snap` | `budget`（元，与 `--budget` 写参同口径） |
61
- | `ad groups --json-out ./snap` | `maxCPCAmountYuan`、`targetCpaAmountYuan` |
51
+ | `ad campaigns --json-out ./snap` | `budget`（元，与 `--budget` 写参同口径） |
52
+ | `ad groups --json-out ./snap` | `maxCPCAmountYuan`、`targetCpaAmountYuan` |
62
53
  | `google-analysis campaigns` 落盘 `campaigns-*.json` | `budgetAmountYuan`、`campaignTargetCpaYuan`、`maximizeConversionsTargetCpaYuan`；同行 `spend` / `averageCpc` / `costPerConversion` 也是元 |
63
- | `keyword suggest --json-out ./snap` | `averageCpc`、`lowTopOfPageBid`、`highTopOfPageBid`；根级与每条 `bidAmountCurrency`（有 `-a` 为账户币；无 `-a` 为 USD） |
64
- | `balance` 等账户余额接口 | 余额字段为`remainingAccountBudget`（元） |
54
+ | `keyword suggest --json-out ./snap` | `averageCpc`、`lowTopOfPageBid`、`highTopOfPageBid`；根级与每条 `bidAmountCurrency`（有 `-a` 为账户币；无 `-a` 为 USD） |
55
+ | `balance` 等账户余额接口 | 余额字段为`remainingAccountBudget`（元） |
65
56
 
66
57
  旧字段 `budgetAmount`（分）、`maxCPCAmountDisplay`、`*Micros`（微元）**已不再落盘**，下游脚本无需做单位换算。金额保留 2 位小数，带货币代码（如 `￥50.00 CNY`、`$50.00 USD`），`currencyCode` 从响应读取，跨币种账户分表；细则见 `references/accounts/currency.md`。
67
58
 
@@ -92,70 +83,70 @@ siluzan-tso google-analysis -a <id> --exclude materials,gold-account --json-out
92
83
 
93
84
  ### 选项
94
85
 
95
- | 选项 | 说明 |
96
- | --------------------------- | ------------------------------------------------------------------------------------ |
97
- | `-a, --account <id>` | Google `mediaCustomerId`（必填） |
98
- | `--json-out <dir>` | 必填；每维一个 `<section>-<accountId>.json` + `manifest-<accountId>.json` |
99
- | `--sections <list>` | 仅执行指定维度（逗号分隔）；省略=全部 25 个 |
100
- | `--exclude <list>` | 排除指定维度；与 `--sections` 可叠加 |
101
- | `--start` / `--end` | 统计区间（YYYY-MM-DD）；省略=近 7 天截至昨天；`final-urls`/`campaign-types` 自动忽略 |
102
- | `--concurrency <n>` | 并发数，默认 5，上限 16 |
103
- | `--limit <n>` | 透传给 `keywords`/`search-terms`（默认 **0**=不封顶；`orderByCost=true`） |
104
- | `--level <lvl>` | 透传给 `extensions`（Account/Campaign/Ad Group） |
105
- | `--audience-type <type>` | 透传给 `audience`（SystemDefined/UserDefined） |
106
- | `--no-order-by-cost` | 透传给 `keywords`/`search-terms` |
86
+ | 选项 | 说明 |
87
+ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
88
+ | `-a, --account <id>` | Google `mediaCustomerId`（必填） |
89
+ | `--json-out <dir>` | 必填；每维一个 `<section>-<accountId>.json` + `manifest-<accountId>.json` |
90
+ | `--sections <list>` | 仅执行指定维度（逗号分隔）；省略=全部 25 个 |
91
+ | `--exclude <list>` | 排除指定维度；与 `--sections` 可叠加 |
92
+ | `--start` / `--end` | 统计区间（YYYY-MM-DD）；省略=近 7 天截至昨天；`final-urls`/`campaign-types` 自动忽略 |
93
+ | `--concurrency <n>` | 并发数，默认 5，上限 16 |
94
+ | `--limit <n>` | 透传给 `keywords`/`search-terms`（默认 **0**=不封顶；`orderByCost=true`） |
95
+ | `--level <lvl>` | 透传给 `extensions`（Account/Campaign/Ad Group） |
96
+ | `--audience-type <type>` | 透传给 `audience`（SystemDefined/UserDefined） |
97
+ | `--no-order-by-cost` | 透传给 `keywords`/`search-terms` |
107
98
  | `--cost-greater <n>` | 仅 **`geo-matched` / `campaign-geo` / `campaign-geo-matched`**：网关 `costGreater`（整数，单位以后端为准） |
108
99
  | `--click-greater <n>` | 仅 **`geo-matched` / `campaign-geo` / `campaign-geo-matched`**：网关 `clickGreater` |
109
- | `--conversions-greater <n>` | 仅 **`geo-matched` / `campaign-geo` / `campaign-geo-matched`**：网关 `conversionsGreater` |
110
- | `--verbose` | 打印详细错误 |
100
+ | `--conversions-greater <n>` | 仅 **`geo-matched` / `campaign-geo` / `campaign-geo-matched`**：网关 `conversionsGreater` |
101
+ | `--verbose` | 打印详细错误 |
111
102
 
112
103
  ### 维度列表（25 个）
113
104
 
114
- | 维度 | 说明 |
115
- | ------------------------ | --------------------------------------------------------------------------------------------------- |
116
- | `overview` | 总览（实时，可查当天；当天高消耗账号排行首选） |
117
- | `keywords` | 关键词；默认 `costGreater=0`（仅有消耗）、`limit=0`（不封顶）、`orderByCost=true`；可用 `--limit` 限制 Top N |
118
- | `search-terms` | 搜索词；默认 `limit=0`（不封顶）、`orderByCost=true`；落盘前过滤 `spend>0`；含 `queryTargetingStatus` / `queryTargetingStatusZh`（已添加/已排除/都没有）；可用 `--limit` 限制 Top N |
119
- | `campaigns` | 广告系列 |
120
- | `campaign-hour` | 系列按小时（行在 `items[]`） |
121
- | `ads` | 广告；与 `ad list` 同源 |
122
- | `extensions` | 附加信息；可选 `--level` |
123
- | `devices` | 设备分布（账户级 `DeviceSectionData`） |
124
- | `geographic` | 地域分布（账户级 `GeographicSectionData`，网关侧常按国家聚合） |
125
- | `geo-matched` | 相符地理位置（Matched locations，`user_location_view`）账户级按国家/地区汇总 |
126
- | `campaign-geo` | 广告系列维度地理（可选 `--cost-greater` / `--click-greater` / `--conversions-greater` 与网关一致） |
127
- | `campaign-geo-matched` | 相符地理位置（Matched locations）系列级明细（可选同上阈值参数） |
128
- | `campaign-device` | 广告系列维度设备（行可含系列/组） |
129
- | `audience` | 受众；可选 `--audience-type` |
130
- | `asset-images` | 图片素材 |
131
- | `videos` | 视频 |
132
- | `materials` | 图片+视频拍平进 `items[]`，每行带 `assetType: 'image' \| 'video'` |
133
- | `resource-counts` | 结构统计 |
134
- | `conversion-actions` | 转化动作 |
135
- | `daily-metrics` | 按日指标（主平台 `GET …/report/media-account/google/account-daily-reports`，`--json-out` 落盘为按日数组）。**广告诊断报告**中：金额/CPA **保留 2 位小数**，转化/点击/展示为整数；须配趋势**分析**段落（见 `google-ads-diagnosis.md`） |
136
- | `gold-account` | 黄金账户 |
137
- | `ads-index` | 质量指标 |
138
- | `final-urls` | 最终到达网址（不传 `--start`/`--end`） |
139
- | `dimension-summary` | 账户汇总 |
140
- | `campaign-types` | 系列类型（实时，可查当天；不传 `--start`/`--end`） |
105
+ | 维度 | 说明 |
106
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
107
+ | `overview` | 总览（实时，可查当天；当天高消耗账号排行首选） |
108
+ | `keywords` | 关键词；默认 `costGreater=0`（仅有消耗）、`limit=0`（不封顶）、`orderByCost=true`；可用 `--limit` 限制 Top N |
109
+ | `search-terms` | 搜索词；默认 `limit=0`（不封顶）、`orderByCost=true`；落盘前过滤 `spend>0`；含 `queryTargetingStatus` / `queryTargetingStatusZh`（已添加/已排除/都没有）；可用 `--limit` 限制 Top N |
110
+ | `campaigns` | 广告系列 |
111
+ | `campaign-hour` | 系列按小时（行在 `items[]`） |
112
+ | `ads` | 广告；与 `ad list` 同源 |
113
+ | `extensions` | 附加信息；可选 `--level` |
114
+ | `devices` | 设备分布（账户级 `DeviceSectionData`） |
115
+ | `geographic` | 地域分布（账户级 `GeographicSectionData`，网关侧常按国家聚合） |
116
+ | `geo-matched` | 相符地理位置（Matched locations，`user_location_view`）账户级按国家/地区汇总 |
117
+ | `campaign-geo` | 广告系列维度地理（可选 `--cost-greater` / `--click-greater` / `--conversions-greater` 与网关一致） |
118
+ | `campaign-geo-matched` | 相符地理位置（Matched locations）系列级明细（可选同上阈值参数） |
119
+ | `campaign-device` | 广告系列维度设备（行可含系列/组） |
120
+ | `audience` | 受众；可选 `--audience-type` |
121
+ | `asset-images` | 图片素材 |
122
+ | `videos` | 视频 |
123
+ | `materials` | 图片+视频拍平进 `items[]`，每行带 `assetType: 'image' \| 'video'` |
124
+ | `resource-counts` | 结构统计 |
125
+ | `conversion-actions` | 转化动作 |
126
+ | `daily-metrics` | 按日指标（主平台 `GET …/report/media-account/google/account-daily-reports`，`--json-out` 落盘为按日数组）。**广告诊断报告**中：金额/CPA **保留 2 位小数**，转化/点击/展示为整数；须配趋势**分析**段落（见 `google-ads-diagnosis.md`） |
127
+ | `gold-account` | 黄金账户 |
128
+ | `ads-index` | 质量指标 |
129
+ | `final-urls` | 最终到达网址（不传 `--start`/`--end`） |
130
+ | `dimension-summary` | 账户汇总 |
131
+ | `campaign-types` | 系列类型（实时，可查当天；不传 `--start`/`--end`） |
141
132
 
142
133
  ### 落盘 JSON
143
134
 
144
- | 字段 | 含义 |
145
- | ---- | ---- |
146
- | `schemaVersion` | 文件内固定 `3` |
147
- | `section` | 维度名（与文件名 stem 一致；仅标识，读数据用不到） |
148
- | `itemCount` | `items.length` |
149
- | `items` | **所有列表维度的行数据**统一入口（含 `materials`）；汇总维度为 `[]` |
150
- | `record` | **汇总维度**的整块对象；列表维度为 `null` |
151
- | `meta` | 仅 `search-terms` / `ads`：网关 `code`/`message`（与数据无关，可忽略） |
135
+ | 字段 | 含义 |
136
+ | --------------- | ---------------------------------------------------------------------- |
137
+ | `schemaVersion` | 文件内固定 `3` |
138
+ | `section` | 维度名（与文件名 stem 一致；仅标识，读数据用不到） |
139
+ | `itemCount` | `items.length` |
140
+ | `items` | **所有列表维度的行数据**统一入口（含 `materials`）；汇总维度为 `[]` |
141
+ | `record` | **汇总维度**的整块对象；列表维度为 `null` |
142
+ | `meta` | 仅 `search-terms` / `ads`：网关 `code`/`message`（与数据无关，可忽略） |
152
143
 
153
144
  **唯一判别规则**：`record` 非 `null` → 读 `record`（汇总维度）；否则 → 读 `items[]`（列表维度）。
154
145
 
155
- | 桶 | 维度 | 读法 |
156
- | -- | ---- | ---- |
146
+ | 桶 | 维度 | 读法 |
147
+ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
157
148
  | **列表** | `keywords`、`search-terms`、`campaigns`、`campaign-hour`、`ads`、`extensions`、`devices`、`geographic`、`geo-matched`、`campaign-geo`、`campaign-geo-matched`、`campaign-device`、`audience`、`asset-images`、`videos`、`materials`、`daily-metrics`、`conversion-actions` | `d.items[]` |
158
- | **汇总** | `overview`、`resource-counts`、`dimension-summary`、`gold-account`、`ads-index`、`final-urls`、`campaign-types` | `d.record` |
149
+ | **汇总** | `overview`、`resource-counts`、`dimension-summary`、`gold-account`、`ads-index`、`final-urls`、`campaign-types` | `d.record` |
159
150
 
160
151
  脚本示例（Node）—— 所有维度同一套读法：
161
152
 
@@ -212,19 +203,19 @@ const data = d.record ?? d.items; // record 非空=汇总维度；否则=列表
212
203
 
213
204
  `campaigns[]` 每系列可带 `competitiveMetrics`，**值为 0~1 小数**（如 `0.0999` ≈ 9.99%）。常见字段：
214
205
 
215
- | 字段 | 含义 |
216
- |------|------|
217
- | `searchImpressionShare` | 搜索展示份额 |
218
- | `searchTopImpressionShare` | 搜索页首展示份额 |
219
- | `searchAbsoluteTopImpressionShare` | 搜索绝对页首展示份额 |
220
- | `searchBudgetLostImpressionShare` | 因预算丢失的搜索展示份额 |
221
- | `searchRankLostImpressionShare` | 因排名丢失的搜索展示份额 |
222
- | `searchBudgetLostTopImpressionShare` / `searchRankLostTopImpressionShare` | 页首维度预算/排名丢失 |
223
- | `searchBudgetLostAbsoluteTopImpressionShare` / `searchRankLostAbsoluteTopImpressionShare` | 绝对页首维度预算/排名丢失 |
224
- | `searchExactMatchImpressionShare` | 完全匹配展示份额 |
225
- | `contentImpressionShare` / `contentBudgetLostImpressionShare` / `contentRankLostImpressionShare` | 展示网络份额与丢失 |
226
- | `searchClickShare` | 搜索点击份额 |
227
- | `relativeCtr` | 相对点击率 |
206
+ | 字段 | 含义 |
207
+ | ------------------------------------------------------------------------------------------------ | ------------------------- |
208
+ | `searchImpressionShare` | 搜索展示份额 |
209
+ | `searchTopImpressionShare` | 搜索页首展示份额 |
210
+ | `searchAbsoluteTopImpressionShare` | 搜索绝对页首展示份额 |
211
+ | `searchBudgetLostImpressionShare` | 因预算丢失的搜索展示份额 |
212
+ | `searchRankLostImpressionShare` | 因排名丢失的搜索展示份额 |
213
+ | `searchBudgetLostTopImpressionShare` / `searchRankLostTopImpressionShare` | 页首维度预算/排名丢失 |
214
+ | `searchBudgetLostAbsoluteTopImpressionShare` / `searchRankLostAbsoluteTopImpressionShare` | 绝对页首维度预算/排名丢失 |
215
+ | `searchExactMatchImpressionShare` | 完全匹配展示份额 |
216
+ | `contentImpressionShare` / `contentBudgetLostImpressionShare` / `contentRankLostImpressionShare` | 展示网络份额与丢失 |
217
+ | `searchClickShare` | 搜索点击份额 |
218
+ | `relativeCtr` | 相对点击率 |
228
219
 
229
220
  无竞争数据时 `competitiveMetrics` 为 `null`（或缺省）。`competitiveMetrics` 中均为 **0~1 小数**。写 Excel「x%」列：`(v * 100).toFixed(2) + '%'`。
230
221
 
@@ -252,15 +243,15 @@ siluzan-tso facebook-analysis -a <mediaCustomerId> --start YYYY-MM-DD --end YYYY
252
243
  --sections overview,ad-sets,platform,country,audience,creative
253
244
  ```
254
245
 
255
- | 选项 | 说明 |
256
- | --- | --- |
257
- | `-a, --account` | 数字 `mediaCustomerId` 或 `act_<数字>` |
258
- | `--json-out` | 必填；`report-manifest-<id>.json` + `<section>-<id>.json` |
246
+ | 选项 | 说明 |
247
+ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
248
+ | `-a, --account` | 数字 `mediaCustomerId` 或 `act_<数字>` |
249
+ | `--json-out` | 必填；`report-manifest-<id>.json` + `<section>-<id>.json` |
259
250
  | `--sections` / `--exclude` | `overview` `ad-sets` `platform` `country` `audience` `creative` `material`；**别名**：`campaigns`→`ad-sets`，`geographic`→`country`，`devices`→`platform`，`ads`→`creative`，`materials`→`material` |
260
- | `platform` 响应字段 | `networks[]` 含 `publisherPlatform`（投放平台）+ `platformPosition`（版位）；`network` 与 `platformPosition` 同值，详见 `facebook-analysis-guide.md` |
261
- | `--limit` | 仅 `country`：按 spend 降序前 N 条 |
262
- | `--start` / `--end` | 同传或同省略；省略=近 7 天截至昨天 |
263
- | `--concurrency` | 默认 5，上限 16 |
251
+ | `platform` 响应字段 | `networks[]` 含 `publisherPlatform`（投放平台）+ `platformPosition`（版位）；`network` 与 `platformPosition` 同值，详见 `facebook-analysis-guide.md` |
252
+ | `--limit` | 仅 `country`：按 spend 降序前 N 条 |
253
+ | `--start` / `--end` | 同传或同省略；省略=近 7 天截至昨天 |
254
+ | `--concurrency` | 默认 5，上限 16 |
264
255
 
265
256
  ```bash
266
257
  # 全 7 维（含 material）
@@ -272,11 +263,11 @@ siluzan-tso facebook-analysis -a <id> --sections country --limit 10 --json-out .
272
263
 
273
264
  ### 报告模板与交付流程
274
265
 
275
- | 场景 | 模板 | 默认终稿 |
276
- | --- | --- | --- |
277
- | 周期 / 月报 / 周报 | `report-templates/meta-period-report.md` | **HTML**（四步：拉数 → 分析 → `meta-period-report.json` → `facebook-analysis render`） |
278
- | 用户指定 Excel | `report-templates/meta-period-report-excel.md` | Agent 脚本写 `.xlsx`（步骤 1～3 同上；**不**默认 `render`） |
279
- | 深度诊断 | `report-templates/meta-account-diagnosis-report.md` | 按该模板（通常 HTML） |
266
+ | 场景 | 模板 | 默认终稿 |
267
+ | ------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------- |
268
+ | 周期 / 月报 / 周报 | `report-templates/meta-period-report.md` | **HTML**（四步：拉数 → 分析 → `meta-period-report.json` → `facebook-analysis render`） |
269
+ | 用户指定 Excel | `report-templates/meta-period-report-excel.md` | Agent 脚本写 `.xlsx`（步骤 1～3 同上；**不**默认 `render`） |
270
+ | 深度诊断 | `report-templates/meta-account-diagnosis-report.md` | 按该模板（通常 HTML） |
280
271
 
281
272
  遗留总览：`siluzan-tso report meta-overview -a <id> [--start … --end …] --json-out <dir>`。
282
273
 
@@ -344,15 +335,15 @@ siluzan-tso report bing-audience-merged -a <mediaCustomerId> --json-out ./snap-b
344
335
 
345
336
  报告产物可以是 HTML、Excel、PDF、PPT、Markdown 等，数据口径须与快照 JSON 一致。章节与数据块参考 `report-templates/`：
346
337
 
347
- | 模板 | 用途 |
348
- | ------------------------------------ | --------------------------- |
349
- | `google-period-report.md` | Google 周期汇总报告章节 |
350
- | `google-account-diagnosis-report.md` | Google 诊断报告纲要 |
351
- | `google-ads-diagnosis.md` | Google Ads 诊断报告完整骨架 |
352
- | `meta-period-report.md` | Meta（Facebook）周期报告 |
353
- | `tiktok-period-report.md` | TikTok 周期报告 |
354
- | `bing-period-report.md` | Bing 周期报告 |
355
- | `website-diagnosis-report.md` | 网站/落地页诊断（`website-diagnosis`，见 P8）；**默认交付 HTML**（`website-diagnosis render`，禁止仅 Markdown） |
356
- | `README.md` | 索引与规则 |
338
+ | 模板 | 用途 |
339
+ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
340
+ | `google-period-report.md` | Google 周期汇总报告章节 |
341
+ | `google-account-diagnosis-report.md` | Google 诊断报告纲要 |
342
+ | `google-ads-diagnosis.md` | Google Ads 诊断报告完整骨架 |
343
+ | `meta-period-report.md` | Meta（Facebook）周期报告 |
344
+ | `tiktok-period-report.md` | TikTok 周期报告 |
345
+ | `bing-period-report.md` | Bing 周期报告 |
346
+ | `website-diagnosis-report.md` | 网站/落地页诊断（`website-diagnosis`，见 P8）；**默认交付 HTML**（`website-diagnosis render`，禁止仅 Markdown） |
347
+ | `README.md` | 索引与规则 |
357
348
 
358
349
  `.html` 文件（`report-template.html`、`report-template-academic.html` 等）为 HTML 路线的样式参考。选其他格式时仍以各 `*.md` 纲要为章节清单。
package/dist/skill/references/analytics/facebook-analysis-guide.md CHANGED
@@ -8,12 +8,12 @@
8
8
 
9
9
  用户要 **Facebook / Meta 分析报告**且**未指定交付格式**时，按以下四步执行：
10
10
 
11
- | 步骤 | 说明 |
12
- | ---- | ---- |
13
- | **1. 拉数** | `facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb`（默认 `--sections overview,ad-sets,platform,country,audience`） |
14
- | **2. 分析** | Agent 用脚本读 `report-manifest-<id>.json` 与各 `<section>-<id>.json`，完成聚合与洞察（禁止 Read 业务 JSON、禁止对话里手填数） |
15
- | **3. 写 JSON** | 产出 `meta-period-report.json`（`narrative` 必填；HTML 扩展字段按需） |
16
- | **4. 渲染** | `facebook-analysis render --data ./meta-period-report.json --snapshot-dir ./snap-fb --out ./meta-period-report.html` |
11
+ | 步骤 | 说明 |
12
+ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
13
+ | **1. 拉数** | `facebook-analysis -a <id> --start <s> --end <e> --json-out ./snap-fb`（默认 `--sections overview,ad-sets,platform,country,audience`） |
14
+ | **2. 分析** | Agent 用脚本读 `report-manifest-<id>.json` 与各 `<section>-<id>.json`，完成聚合与洞察（禁止 Read 业务 JSON、禁止对话里手填数） |
15
+ | **3. 写 JSON** | 产出 `meta-period-report.json`（`narrative` 必填；HTML 扩展字段按需） |
16
+ | **4. 渲染** | `facebook-analysis render --data ./meta-period-report.json --snapshot-dir ./snap-fb --out ./meta-period-report.html` |
17
17
 
18
18
  **禁止**：跳过步骤 3/4 直接交付 Markdown；禁止 Agent 手写 HTML。
19
19
 
@@ -25,19 +25,19 @@
25
25
 
26
26
  ## 与 Google 周期报告的能力对照
27
27
 
28
- | Google 默认/常见维度 | Facebook 对应 | CLI | 说明 |
29
- | -------------------- | ------------- | --- | ---- |
30
- | 执行摘要 `overview` | ✅ 本期/上期环比 | `overview` | 上一周期由后端自动算，勿再拉第二次 |
31
- | 每日趋势 `daily-metrics` | ❌ 无接口 | — | 报告中注明「Meta 报告无按日 Section」 |
32
- | 月度汇总 `dimension-summary` | ⚠️ 用 `overview` 单周期汇总代替 | `overview` | 仅 currentPeriod 即全区间汇总 |
33
- | 系列 `campaigns` | ⚠️ 广告组 + 行上 `campaignName` | `ad-sets` | 无独立 Campaign Section；可按 `campaignName` 聚合撰写 |
34
- | 设备 `devices` | ⚠️ 投放平台 × 版位 | `platform` | `publisherPlatform`（facebook / instagram 等）+ `platformPosition`（feed / facebook_reels 等） |
35
- | 地域 `geographic` | ✅ 国家 | `country` | 可选 `--limit N` |
36
- | 关键词 `keywords` | ❌ 无 | — | 非搜索广告；章节写「不适用」 |
37
- | 受众 `audience` | ⚠️ 年龄×性别 | `audience` | 无兴趣/自定义受众列表 |
38
- | 广告创意 `ads` | ✅ 创意+文案+缩略图 | `creative` | 一行 = ad + creative |
39
- | 图片/视频素材 `materials` | ⚠️ DC 素材 | `material` | 标准账户为空，用 `creative` |
40
- | 搜索词 / 附加信息 / 落地页 / 黄金账户 / 质量分 / 转化动作列表 / 系列类型 / 按小时 | ❌ 无 | — | 诊断模板中标注「Facebook 无此数据」 |
28
+ | Google 默认/常见维度 | Facebook 对应 | CLI | 说明 |
29
+ | --------------------------------------------------------------------------------- | ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------- |
30
+ | 执行摘要 `overview` | ✅ 本期/上期环比 | `overview` | 上一周期由后端自动算，勿再拉第二次 |
31
+ | 每日趋势 `daily-metrics` | ❌ 无接口 | — | 报告中注明「Meta 报告无按日 Section」 |
32
+ | 月度汇总 `dimension-summary` | ⚠️ 用 `overview` 单周期汇总代替 | `overview` | 仅 currentPeriod 即全区间汇总 |
33
+ | 系列 `campaigns` | ⚠️ 广告组 + 行上 `campaignName` | `ad-sets` | 无独立 Campaign Section；可按 `campaignName` 聚合撰写 |
34
+ | 设备 `devices` | ⚠️ 投放平台 × 版位 | `platform` | `publisherPlatform`（facebook / instagram 等）+ `platformPosition`（feed / facebook_reels 等） |
35
+ | 地域 `geographic` | ✅ 国家 | `country` | 可选 `--limit N` |
36
+ | 关键词 `keywords` | ❌ 无 | — | 非搜索广告；章节写「不适用」 |
37
+ | 受众 `audience` | ⚠️ 年龄×性别 | `audience` | 无兴趣/自定义受众列表 |
38
+ | 广告创意 `ads` | ✅ 创意+文案+缩略图 | `creative` | 一行 = ad + creative |
39
+ | 图片/视频素材 `materials` | ⚠️ DC 素材 | `material` | 标准账户为空，用 `creative` |
40
+ | 搜索词 / 附加信息 / 落地页 / 黄金账户 / 质量分 / 转化动作列表 / 系列类型 / 按小时 | ❌ 无 | — | 诊断模板中标注「Facebook 无此数据」 |
41
41
 
42
42
  **`--sections` 别名**（与 Google 习惯兼容）：`campaigns`→`ad-sets`，`geographic`→`country`，`devices`→`platform`，`ads`→`creative`，`materials`→`material`。
43
43
 
@@ -47,27 +47,27 @@
47
47
 
48
48
  ### 基础
49
49
 
50
- | 字段 | 撰写展示 |
51
- | ---- | -------- |
52
- | `impressions` | 展示（整数） |
53
- | `clicks` | 点击 |
54
- | `spend` | 花费（账户币种，**非** micros） |
55
- | `ctr` | 点击率：**小数**，展示时 ×100 加 `%`（0.05 → 5%） |
56
- | `averageCpc` | 平均 CPC |
57
- | `conversions` | 业务转化次数（lead/purchase/messaging 等汇总） |
58
- | `costPerConversion` | CPA |
59
- | `conversionRate` | CVR（小数，×100 为 %） |
50
+ | 字段 | 撰写展示 |
51
+ | ------------------- | ------------------------------------------------- |
52
+ | `impressions` | 展示（整数） |
53
+ | `clicks` | 点击 |
54
+ | `spend` | 花费（账户币种，**非** micros） |
55
+ | `ctr` | 点击率：**小数**，展示时 ×100 加 `%`（0.05 → 5%） |
56
+ | `averageCpc` | 平均 CPC |
57
+ | `conversions` | 业务转化次数（lead/purchase/messaging 等汇总） |
58
+ | `costPerConversion` | CPA |
59
+ | `conversionRate` | CVR（小数，×100 为 %） |
60
60
 
61
61
  ### Facebook 扩展
62
62
 
63
- | 字段 | 撰写展示 |
64
- | ---- | -------- |
65
- | `reach` | 覆盖人数 |
66
- | `frequency` | 频次；>3 可提示创意疲劳 |
67
- | `resultType` | 结果类型（如 `lead`） |
68
- | `attributionSetting` | 归因（如 `7d_click`） |
69
- | `results` | 对齐 Meta「结果」列 |
70
- | `costPerResult` | 单次成效费用 |
63
+ | 字段 | 撰写展示 |
64
+ | -------------------- | ----------------------- |
65
+ | `reach` | 覆盖人数 |
66
+ | `frequency` | 频次；>3 可提示创意疲劳 |
67
+ | `resultType` | 结果类型（如 `lead`） |
68
+ | `attributionSetting` | 归因（如 `7d_click`） |
69
+ | `results` | 对齐 Meta「结果」列 |
70
+ | `costPerResult` | 单次成效费用 |
71
71
 
72
72
  ### 口径（必读）
73
73
 
@@ -82,11 +82,11 @@
82
82
 
83
83
  后端按 Meta `publisher_platform,platform_position` breakdown 拆分（2026-06 起）。`networks[]` 每行：
84
84
 
85
- | 字段 | 含义 | 示例 |
86
- | ---- | ---- | ---- |
87
- | `publisherPlatform` | 投放平台（Meta `publisher_platform`） | `facebook`、`instagram`、`audience_network` |
88
- | `platformPosition` | 版位（Meta `platform_position`） | `feed`、`facebook_reels`、`instagram_stories`、`instream_video` |
89
- | `network` | 兼容旧前端，**等于 `platformPosition`** | 勿单独当作「平台」列使用 |
85
+ | 字段 | 含义 | 示例 |
86
+ | ------------------- | --------------------------------------- | --------------------------------------------------------------- |
87
+ | `publisherPlatform` | 投放平台（Meta `publisher_platform`） | `facebook`、`instagram`、`audience_network` |
88
+ | `platformPosition` | 版位（Meta `platform_position`） | `feed`、`facebook_reels`、`instagram_stories`、`instream_video` |
89
+ | `network` | 兼容旧前端，**等于 `platformPosition`** | 勿单独当作「平台」列使用 |
90
90
 
91
91
  **撰写表格建议列**：投放平台 | 版位 | 展示 | 花费 | 结果 | 单次成效费用。
92
92
 
@@ -100,15 +100,15 @@
100
100
 
101
101
  ## 各 Section 文件与章节要点
102
102
 
103
- | section | 落盘文件 | 根字段 | 报告章节要点 |
104
- | ------- | -------- | ------ | ------------ |
105
- | `overview` | `overview-<id>.json` | `currentPeriod`, `previousPeriod` | 环比表：消耗、展示、点击、CTR、CPC、转化、CPA、结果、单次成效、reach、frequency；注明 `resultType` / `attributionSetting` |
106
- | `ad-sets` | `ad-sets-<id>.json` | `adGroups[]` | Top 组 by spend；`spendPercentage`；按 `campaignName` 归并；高消耗低结果组 |
107
- | `platform` | `platform-<id>.json` | `networks[]` | **两列维度**：`publisherPlatform`（投放平台）+ `platformPosition`（版位）；`network` 与 `platformPosition` 同值（兼容旧版）。同版位名可能跨平台出现（如 facebook/instagram 均有 `feed`），**禁止**仅用 `network` 当平台汇总 |
108
- | `country` | `country-<id>.json` | `countries[]` | Top 国家；`countryOrRegion` 为展示名 |
109
- | `audience` | `audience-<id>.json` | `audiences[]` | 年龄×性别矩阵；高/低效人群段 |
110
- | `creative` | `creative-<id>.json` | `creatives[]` | 按 `creativeType` 汇总；Top 创意表（adName、title、spend、results、costPerResult） |
111
- | `material` | `material-<id>.json` | `materials[]`, `dataSource`, `message` | 仅 `dataSource===meta_asset_breakdown` 且有条目时写章节；否则一句说明 |
103
+ | section | 落盘文件 | 根字段 | 报告章节要点 |
104
+ | ---------- | -------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
105
+ | `overview` | `overview-<id>.json` | `currentPeriod`, `previousPeriod` | 环比表：消耗、展示、点击、CTR、CPC、转化、CPA、结果、单次成效、reach、frequency；注明 `resultType` / `attributionSetting` |
106
+ | `ad-sets` | `ad-sets-<id>.json` | `adGroups[]` | Top 组 by spend；`spendPercentage`；按 `campaignName` 归并；高消耗低结果组 |
107
+ | `platform` | `platform-<id>.json` | `networks[]` | **两列维度**：`publisherPlatform`（投放平台）+ `platformPosition`（版位）；`network` 与 `platformPosition` 同值（兼容旧版）。同版位名可能跨平台出现（如 facebook/instagram 均有 `feed`），**禁止**仅用 `network` 当平台汇总 |
108
+ | `country` | `country-<id>.json` | `countries[]` | Top 国家；`countryOrRegion` 为展示名 |
109
+ | `audience` | `audience-<id>.json` | `audiences[]` | 年龄×性别矩阵；高/低效人群段 |
110
+ | `creative` | `creative-<id>.json` | `creatives[]` | 按 `creativeType` 汇总；Top 创意表（adName、title、spend、results、costPerResult） |
111
+ | `material` | `material-<id>.json` | `materials[]`, `dataSource`, `message` | 仅 `dataSource===meta_asset_breakdown` 且有条目时写章节；否则一句说明 |
112
112
 
113
113
  ---
114
114
 
@@ -153,11 +153,11 @@ siluzan-tso facebook-analysis render \
153
153
 
154
154
  ### 三层建议结构
155
155
 
156
- | 层级 | JSON 字段 | 要求 |
157
- | ---- | --------- | ---- |
158
- | 固定 4 条 | `narrative.recommendations[]` | 标题枚举 4 个；每条 content **≥150 字** |
159
- | 7 维补充 | `supplementaryRecommendations` | 预算/平台/地域/受众/创意/频次/接口限制 **各 1 条** |
160
- | 优先级 | `priorityPlan` | high/medium/low 各 **≥2 条** |
156
+ | 层级 | JSON 字段 | 要求 |
157
+ | --------- | ------------------------------ | -------------------------------------------------- |
158
+ | 固定 4 条 | `narrative.recommendations[]` | 标题枚举 4 个；每条 content **≥150 字** |
159
+ | 7 维补充 | `supplementaryRecommendations` | 预算/平台/地域/受众/创意/频次/接口限制 **各 1 条** |
160
+ | 优先级 | `priorityPlan` | high/medium/low 各 **≥2 条** |
161
161
 
162
162
  ### 7 维数据驱动要点
163
163
 
@@ -177,8 +177,8 @@ siluzan-tso facebook-analysis render \
177
177
 
178
178
  ## 辅助命令（非报告 Section）
179
179
 
180
- | 意图 | CLI |
181
- | ---- | --- |
182
- | 账户列表 | `list-accounts -m MetaAd -k <id> --json-out <dir>` |
183
- | 余额（若需） | `balance` / `stats`（口径与报告 spend 可能不同，须标注来源） |
184
- | 遗留仅总览 | `report meta-overview`（`MetaAd` 路径，不推荐替代 `facebook-analysis`） |
180
+ | 意图 | CLI |
181
+ | ------------ | ----------------------------------------------------------------------- |
182
+ | 账户列表 | `list-accounts -m MetaAd -k <id> --json-out <dir>` |
183
+ | 余额（若需） | `balance` / `stats`（口径与报告 spend 可能不同，须标注来源） |
184
+ | 遗留仅总览 | `report meta-overview`（`MetaAd` 路径，不推荐替代 `facebook-analysis`） |
package/dist/skill/references/analytics/google-analysis-batch.md CHANGED
@@ -69,7 +69,7 @@ siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId
69
69
  | `--run-id <id>` | 自定义 runId | 自动 `run-YYYYMMDD-HHmmss-<rand4>` |
70
70
  | `-a, --accounts <ids>` | 显式 ID 列表；传入则跳过清单拉取与 `--min-spend` | 省略时自动拉全量 Google 账号 |
71
71
  | `--start` / `--end` | 统计区间（YYYY-MM-DD） | 近 7 天截至昨天 |
72
- | `--sections <list>` | 维度（逗号分隔），合法值见 `references/analytics/account-analytics.md` | `campaigns,geographic,keywords` |
72
+ | `--sections <list>` | 维度（逗号分隔），合法值见 `references/analytics/account-analytics.md` | `campaigns,geographic,keywords` |
73
73
  | `--account-concurrency <n>` | 账户级并发（1~16） | 4 |
74
74
  | `--section-concurrency <n>` | 单账户内维度并发（1~16） | 6 |
75
75
  | `--keyword-limit <n>` | keywords / search-terms 条数上限 | google-analysis 默认 |
@@ -102,7 +102,7 @@ siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId
102
102
  └── tasks.lock # 运行时锁
103
103
  ```
104
104
 
105
- **产物消费（Agent 强制顺序）**：先读 `*.outline.txt` 了解字段类型 → 再写聚合脚本 → 由脚本读 `<section>-<accountId>.json`。与单账户 `google-analysis` 完全同口径（含 **`campaigns`：`budgetAmountYuan` / `campaignTargetCpaYuan` / `maximizeConversionsTargetCpaYuan` 均为元**——outline 内嵌提示与单账户一致）。
105
+ **产物消费（Agent 强制顺序）**：**每个维度各读一份** `*.outline.txt`（同维度多账户同结构，读其一即可；一批并行把所有维度 outline 读全）了解字段类型 → 再写聚合脚本 → 由脚本读 `<section>-<accountId>.json`。**outline 没逐维读全，禁止开写脚本**（字段名以 outline 为准，不凭模板/通用命名猜——详见 `references/core/agent-conventions.md` §三 outline 门禁）。与单账户 `google-analysis` 完全同口径（含 **`campaigns`：`budgetAmountYuan` / `campaignTargetCpaYuan` / `maximizeConversionsTargetCpaYuan` 均为元**——outline 内嵌提示与单账户一致）。
106
106
 
107
107
  **为什么先读 outline 而不是直接 `Read` JSON**：
108
108
 
package/dist/skill/references/analytics/keyword-planner-workflows.md CHANGED
@@ -4,18 +4,17 @@
4
4
  >
5
5
  > **数据口径**：`siluzan-tso keyword` 默认走 `keywordidea/google`（共享 MCC，出价 **USD**）；传 **`-a <mediaCustomerId>`** 时走 `keywordrecommendation/recommend/{id}/google`，出价币种为 `list-accounts` 的 **`currencyCode`**（如 CNY）。可选 `--url` 叠加 **网址拓词**（`websitereco`）。与 **`google-analysis` 投放表现**不是同一套数据。
6
6
 
7
-
8
7
  ---
9
8
 
10
9
  ## 路径选择（拓词前先定分支）
11
10
 
12
11
  关键词列表可能来自 **三类来源**，交付前须在说明中标注来源，勿混为一谈：
13
12
 
14
- | 来源 | 典型做法 | 是否含 `montlySearch` / CPC 等 Google 指标 |
15
- | ------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
16
- | **A. 宿主联网搜索** | 助手用 WebSearch / 公开网页归纳行业词、竞品词、长尾变体，再写入词包 | ❌ 无，须再调 `keyword` 补指标或单独标注「无市场数据」 |
13
+ | 来源 | 典型做法 | 是否含 `montlySearch` / CPC 等 Google 指标 |
14
+ | ------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
15
+ | **A. 宿主联网搜索** | 助手用 WebSearch / 公开网页归纳行业词、竞品词、长尾变体，再写入词包 | ❌ 无，须再调 `keyword` 补指标或单独标注「无市场数据」 |
17
16
  | **B. Google API** | `siluzan-tso keyword -k "种子,..."`（无 `-a`：`keywordidea/google`/USD；有 `-a`：账户接口/账户币；可选 `--geo`） | ✅ 有 |
18
- | **C. 网址拓词** | `keyword` 带 `--url`（`websitereco` 轮询） | 通常仅词面，**无**完整 Planner 指标 |
17
+ | **C. 网址拓词** | `keyword` 带 `--url`（`websitereco` 轮询） | 通常仅词面，**无**完整 Planner 指标 |
19
18
 
20
19
  ### 分支 A — 混合拓词
21
20
 
@@ -50,19 +49,19 @@
50
49
 
51
50
  洗词、分组、否词表、匹配策略等多依赖对 **`--json-out` 落盘 JSON** 的解析或 Agent 归纳；逐步命令见「场景编排」。
52
51
 
53
- | # | 场景 | 编排 |
54
- | --- | -------------------------------------------------------------------------------- | -------------------- |
55
- | — | **仅 Google Planner 数据**（不联网搜索、不用 `--url`） | 上文「分支 B」 |
56
- | 0 | **先 RAG 再拓词**：客户产品/行业背景 → 种子词与 `--url` | §0 |
57
- | 1 | 竞品网址 + 种子拓词：至少一个 `-k` + `--url`，落盘后去重/排序/截 Top N | §1 |
58
- | 2 | 多种子长尾：`-k "种子1,种子2,..."` | §2 |
59
- | 3 | 按规则洗词：月搜索量阈值、排除词根、排除类意图等 | §2（JSON） |
60
- | 4 | 账户关键词表现 + 市场侧指标：`google-analysis` keywords → 抽词 → 分批 `keyword` | §3 |
61
- | 5 | 搜索词 + 拓词：浪费流量 / 否词线索 | §4 |
62
- | 6 | 高商业意图粗筛：CPC、竞争度、搜索量 | §5 |
63
- | 7 | 否词或否词根落地：`ad keyword-negative-create` 等 | §4 + `google-ads/google-ads.md` |
64
- | 8 | Campaign → AdGroup → JSON：`ad campaign-validate` → `ad campaign-create` | §6 |
65
- | 9 | 拓词结果导出：`keyword … --json-out`，供脚本消费 | §7 |
52
+ | # | 场景 | 编排 |
53
+ | --- | ------------------------------------------------------------------------------- | ------------------------------- |
54
+ | — | **仅 Google Planner 数据**（不联网搜索、不用 `--url`） | 上文「分支 B」 |
55
+ | 0 | **先 RAG 再拓词**：客户产品/行业背景 → 种子词与 `--url` | §0 |
56
+ | 1 | 竞品网址 + 种子拓词：至少一个 `-k` + `--url`，落盘后去重/排序/截 Top N | §1 |
57
+ | 2 | 多种子长尾：`-k "种子1,种子2,..."` | §2 |
58
+ | 3 | 按规则洗词：月搜索量阈值、排除词根、排除类意图等 | §2（JSON） |
59
+ | 4 | 账户关键词表现 + 市场侧指标：`google-analysis` keywords → 抽词 → 分批 `keyword` | §3 |
60
+ | 5 | 搜索词 + 拓词：浪费流量 / 否词线索 | §4 |
61
+ | 6 | 高商业意图粗筛：CPC、竞争度、搜索量 | §5 |
62
+ | 7 | 否词或否词根落地：`ad keyword-negative-create` 等 | §4 + `google-ads/google-ads.md` |
63
+ | 8 | Campaign → AdGroup → JSON：`ad campaign-validate` → `ad campaign-create` | §6 |
64
+ | 9 | 拓词结果导出：`keyword … --json-out`，供脚本消费 | §7 |
66
65
 
67
66
  ---
68
67
 
@@ -86,10 +85,10 @@ Google Keyword Planner 的搜索量/CPC 与**目标国家/地区**相关。指
86
85
 
87
86
  `--geo` 可传多个 ID（逗号分隔，如 `--geo 2840,2826`），网关会把它们一并传给 `keywordidea/google?geoTargetConstantIds=...`。此时 Google Keyword Planner 返回的 `montlySearch`、CPC、竞争度等是**跨所传地区的汇总/合并口径**，**不是**「每个国家各一行」或 JSON 里带 `geoTargetConstantId` 分字段。
88
87
 
89
- | 需求 | 做法 |
90
- | ---- | ---- |
91
- | 只要「美国+中国合在一起」的市场参考 | 一次调用：`--geo 2840,2826` |
92
- | 要对比美国 vs 中国各自搜索量/CPC | **多次调用**，每次 `--geo` **只传一个** ID，分别 `--json-out` 到不同目录（如 `./snap-kw-us`、`./snap-kw-cn`） |
88
+ | 需求 | 做法 |
89
+ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
90
+ | 只要「美国+中国合在一起」的市场参考 | 一次调用：`--geo 2840,2826` |
91
+ | 要对比美国 vs 中国各自搜索量/CPC | **多次调用**，每次 `--geo` **只传一个** ID，分别 `--json-out` 到不同目录（如 `./snap-kw-us`、`./snap-kw-cn`） |
93
92
 
94
93
  **禁止**把 `--geo 2840,2826` 的单次落盘结果当成「美国一套、中国一套」两张表；报告里若写多市场对比，须注明数据来源为分次 `keyword` 调用。
95
94
 
@@ -109,7 +108,7 @@ siluzan-tso keyword -k "pipe" --geo 2840,2826 --json-out ./snap-kw-merged
109
108
  | 能力 | CLI 现状 |
110
109
  | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
111
110
  | 种子词 / 多种子、可选竞品站 URL、本地 `--include` / `--exclude`、搜索量与 CPC、竞争度 | ✅ `keyword` |
112
- | 按国家/地区限定 Keyword Planner 市场指标 | ✅ `keyword geo-list` + `keyword --geo` |
111
+ | 按国家/地区限定 Keyword Planner 市场指标 | ✅ `keyword geo-list` + `keyword --geo` |
113
112
  | 账户内关键词/搜索词表现 + 再对重点词拉市场侧指标 | ✅ 多命令编排（见下） |
114
113
  | 词包数值过滤、意图分类、语义 AdGroup、否词清单、匹配策略表 | ✅ **由 AI 消费 `--json-out` 落盘结果后产出**；无单独算法命令 |
115
114
  | Google Ads 内「过去 12 个月按月」搜索量趋势曲线 | ❌ **无接口**，勿用本 CLI 假装产出 |