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

package/dist/skill/references/google-analysis-batch.md

@@ -63,24 +63,24 @@ siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId
 
 ## 参数
 
-| 参数                        | 说明                                                         | 默认值                             |
-| --------------------------- | ------------------------------------------------------------ | ---------------------------------- |
-| `--json-out <dir>`          | 必填，产物根目录                                             | —                                  |
-| `--run-id <id>`             | 自定义 runId                                                 | 自动 `run-YYYYMMDD-HHmmss-<rand4>` |
-| `-a, --accounts <ids>`      | 显式 ID 列表；传入则跳过清单拉取与 `--min-spend`             | 省略时自动拉全量 Google 账号       |
-| `--start` / `--end`         | 统计区间（YYYY-MM-DD）                                       | 近 7 天截至昨天                    |
-| `--sections <list>`         | 维度（逗号分隔），合法值见 `references/account-analytics.md` | `campaigns,geographic,keywords`    |
-| `--account-concurrency <n>` | 账户级并发（1~16）                                           | 4                                  |
-| `--section-concurrency <n>` | 单账户内维度并发（1~16）                                     | 6                                  |
-| `--keyword-limit <n>`       | keywords / search-terms 条数上限                             | google-analysis 默认               |
+| 参数                                 | 说明                                                                                                           | 默认值                             |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `--json-out <dir>`                   | 必填，产物根目录                                                                                               | —                                  |
+| `--run-id <id>`                      | 自定义 runId                                                                                                   | 自动 `run-YYYYMMDD-HHmmss-<rand4>` |
+| `-a, --accounts <ids>`               | 显式 ID 列表；传入则跳过清单拉取与 `--min-spend`                                                               | 省略时自动拉全量 Google 账号       |
+| `--start` / `--end`                  | 统计区间（YYYY-MM-DD）                                                                                         | 近 7 天截至昨天                    |
+| `--sections <list>`                  | 维度（逗号分隔），合法值见 `references/account-analytics.md`                                                   | `campaigns,geographic,keywords`    |
+| `--account-concurrency <n>`          | 账户级并发（1~16）                                                                                             | 4                                  |
+| `--section-concurrency <n>`          | 单账户内维度并发（1~16）                                                                                       | 6                                  |
+| `--keyword-limit <n>`                | keywords / search-terms 条数上限                                                                               | google-analysis 默认               |
 | `--campaign-geo-cost-greater <n>` 等 | 仅 **`campaign-geo`**：与网关 `GetCampaignsGeoReport` 可选 query 一致；写入 `run-manifest.json`，`resume` 沿用 | 不设                               |
-| `--min-spend <n>`           | 区间消耗 ≤ 此值跳过（与 `-a` 同传无效）                      | 0                                  |
-| `--deadline <dur>`          | 整任务硬截止（如 `30m` / `2h`），到期标记 paused             | 不设                               |
-| `--task-timeout-ms <n>`     | 单 task 硬超时                                               | 60000                              |
-| `--max-attempts <n>`        | 可重试错误最大尝试次数                                       | 3                                  |
-| `--refresh-dp`              | 执行前强制刷新 Datapermission                                | false                              |
-| `--no-verbose-progress`     | 关闭 stderr 进度条（CI 推荐）                                | false                              |
-| `-t, --token`               | 临时覆盖 Token                                               | `~/.siluzan/config.json`           |
+| `--min-spend <n>`                    | 区间消耗 ≤ 此值跳过（与 `-a` 同传无效）                                                                        | 0                                  |
+| `--deadline <dur>`                   | 整任务硬截止（如 `30m` / `2h`），到期标记 paused                                                               | 不设                               |
+| `--task-timeout-ms <n>`              | 单 task 硬超时                                                                                                 | 60000                              |
+| `--max-attempts <n>`                 | 可重试错误最大尝试次数                                                                                         | 3                                  |
+| `--refresh-dp`                       | 执行前强制刷新 Datapermission                                                                                  | false                              |
+| `--no-verbose-progress`              | 关闭 stderr 进度条（CI 推荐）                                                                                  | false                              |
+| `-t, --token`                        | 临时覆盖 Token                                                                                                 | `~/.siluzan/config.json`           |
 
 ---
 
@@ -102,7 +102,7 @@ siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId
     └── tasks.lock               # 运行时锁
 ```
 
-**产物消费（Agent 强制顺序）**：先读 `*.outline.txt` 了解字段类型 → 再写聚合脚本 → 由脚本读 `<section>-<accountId>.json`。与单账户 `google-analysis` 完全同口径（含 **`campaigns`：`budgetAmount`＝分、÷100 为元，禁止 ÷1e6**——outline 内嵌提示与单账户一致）。
+**产物消费（Agent 强制顺序）**：先读 `*.outline.txt` 了解字段类型 → 再写聚合脚本 → 由脚本读 `<section>-<accountId>.json`。与单账户 `google-analysis` 完全同口径（含 **`campaigns`：`budgetAmountYuan` / `campaignTargetCpaYuan` / `maximizeConversionsTargetCpaYuan` 均为元**——outline 内嵌提示与单账户一致）。
 
 **为什么先读 outline 而不是直接 `Read` JSON**：
 

package/dist/skill/references/hosted-automation-optimize-weak-downbid.md

@@ -44,7 +44,7 @@ siluzan-tso ad list -a <mediaCustomerId> --start <YYYY-MM-DD> --end <YYYY-MM-DD>
 
 组行上常见：
 
-- **`targetCpaAmount`**（及 `maxCPCAmount` / `maxCPCAmountDisplay` 等，写入口径见 `google-ads.md`）
+- **`targetCpaAmountYuan`** / **`maxCPCAmountYuan`**（元，CLI 出口已统一；写入口径见 `google-ads.md`）
 - **`spend`**、**`conversions`**、**`impressions`**、**`ctr`**
 
 ### 3. 条件示例（仅示意，以宿主配置为准）

package/dist/skill/references/hosted-automation-self-control.md

@@ -125,8 +125,8 @@ siluzan-tso ad adgroup-edit -a <mediaCustomerId> --id <adGroupId> --max-cpc <主
 
 见 **`references/google-ads.md`**「广告组编辑」。
 
-写前**必须**先 **`ad groups --json` / `ad campaigns --json`** 取当前值，**读取主币种金额**：组侧优先 `*Display`（如 `targetCpaAmountDisplay`、`maxCPCAmountDisplay`）；系列列表侧 **`ad campaigns` 的 `budget` 已为元**（与写参 `--budget` 一致），在宿主内按主币种算新值（如下调 12%：`newDisplay = round((oldDisplay * 0.88) * 100) / 100`），再以主币种金额作为 `--target-cpa` / `--max-cpc` / `--budget` 传回。
-**严禁** 把 `targetCpaAmount` / `maxCPCAmount` / `budget` 这些「分」字段直接当作主币种金额传给 CLI——会被再 ×100 一次，金额放大 100 倍。
+写前**必须**先 **`ad groups --json` / `ad campaigns --json`** 取当前值，**读取主币种金额**：组侧读 `maxCPCAmountYuan` / `targetCpaAmountYuan`（元）；系列列表侧 `ad campaigns` 的 `budget` 也是元（与写参 `--budget` 一致）；`google-analysis campaigns-*.json` 的 `budgetAmountYuan` 同。在宿主内按主币种算新值（如下调 12%：`newYuan = round(oldYuan * 0.88 * 100) / 100`），再以主币种金额作为 `--target-cpa` / `--max-cpc` / `--budget` 传回。
+**严禁** 自己再做 `÷100` / `÷1_000_000` 换算——`*Yuan` 字段已经是元，再换算就是错的。
 
 ### 写后复核
 

package/dist/skill/references/keyword-planner-workflows.md

@@ -1,8 +1,48 @@
 # 关键词规划师工作流
 
-> 拓词、竞品网址拓词、词包清洗、否词、建户关键词结构：**先 Read 本文件**，再按需打开 `references/google-ads.md`（命令参数）与 `references/google-ads-rules/google-ads-keyword-strategy.md`（匹配与分组原则）。
+> **拓词命令**读本文；**建户 JSON + validate + create** 读 `references/google-ads-campaign-plan.md`。关键词数量规则：`google-ads-rules/google-ads-keyword-taxonomy.md`。
 >
-> **数据口径**：`siluzan-tso keyword` 走网关 `keywordidea/google`（市场侧关键字创意/体量与竞价参考；后端使用共享 MCC + 缓存全局 OAuth Token，**无需用户绑账户**），可选 `--url` 叠加站内网址拓词服务；与账户内 **`google-analysis` 投放表现**不是同一套数据，文档与回复中须区分「市场参考」与「账户实际花费/转化」。
+> **数据口径**：`siluzan-tso keyword` 默认走 `keywordidea/google`（共享 MCC，出价 **USD**）；传 **`-a <mediaCustomerId>`** 时走 `keywordrecommendation/recommend/{id}/google`，出价币种为 `list-accounts` 的 **`currencyCode`**（如 CNY）。可选 `--url` 叠加 **网址拓词**（`websitereco`）。与 **`google-analysis` 投放表现**不是同一套数据。
+
+
+---
+
+## 路径选择（拓词前先定分支）
+
+关键词列表可能来自 **三类来源**，交付前须在说明中标注来源，勿混为一谈：
+
+| 来源                | 典型做法                                                                          | 是否含 `montlySearch` / CPC 等 Google 指标             |
+| ------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| **A. 宿主联网搜索** | 助手用 WebSearch / 公开网页归纳行业词、竞品词、长尾变体，再写入词包               | ❌ 无，须再调 `keyword` 补指标或单独标注「无市场数据」 |
+| **B. Google API**   | `siluzan-tso keyword -k "种子,..."`（无 `-a`：`keywordidea/google`/USD；有 `-a`：账户接口/账户币；可选 `--geo`） | ✅ 有                                                  |
+| **C. 网址拓词**     | `keyword` 带 `--url`（`websitereco` 轮询，与 Web `/tool/keyword` 填网址分支一致） | 通常仅词面，**无**完整 Planner 指标                    |
+
+### 分支 A — 混合拓词
+
+**适用**：用户要「全面拓词」「行业/竞品词一起出」，且**未**要求只要 Google 数据。
+
+1. （可选）宿主 **联网搜索** 或 `rag query` 归纳 **2–8 个英文种子词**（RAG 见 §0，联网搜索勿与 Google 指标混写在同一列）。
+2. `siluzan-tso keyword -k "种子1,种子2,..." [--url "<落地页或竞品站>"] --json-out ./snap-kw`
+3. 对落盘 `items`：以 **`keyword` 返回行为准**（有 `montlySearch` / `averageCpc` 等，币种见 `bidAmountCurrency`）；联网搜索得到的词若无对应行，可并入词包但须标注 **「无 Google 市场数据」**，或丢弃。
+
+### 分支 B — 仅 Google 市场数据（默认）
+
+**适用**：用户明确「只要 Google 关键词规划师 / Keyword Planner 数据」「不要联网搜索」「不要网络拓词」；或只需带搜索量、CPC、竞争度的官方建议列表。
+
+**禁止**：
+
+- 为补词而做 **WebSearch / webfetch 联网归纳**（落地页 PDP 推断等 **投放方案** 流程除外，且不得把联网词当作 Planner 结果）。
+- CLI 使用 **`--url`**（会叠加网址拓词，非纯 Google API）。
+
+**执行**：
+
+1. 种子词仅来自：**用户已给出的词**、账户内 `google-analysis` 抽词、或（可选）**RAG 知识库**片段——**不要**再联网搜索补种子。
+2. ```bash
+   siluzan-tso keyword -k "种子1,种子2,..." --google-only --json-out ./snap-kw
+   ```
+   （`--google-only` 即使误传 `--url` 也会忽略网址拓词；与 Web 端只填搜索词、不填公司网址一致。）
+3. 词包说明首行标注：**数据来源：Google Keyword Planner（`keywordidea/google`）**；表格只列落盘 JSON 中有 `montlySearch` 等字段的词。
+4. 若 `source` 为 `"Cgy"` 的条目仍存在，须在说明中单独标注，勿称为 Google Planner 原生建议。
 
 ---
 
@@ -10,41 +50,100 @@
 
 洗词、分组、否词表、匹配策略等多依赖对 **`--json-out` 落盘 JSON** 的解析或 Agent 归纳；逐步命令见「场景编排」。
 
-| # | 场景 | 编排 |
-| - | ---- | ---- |
-| 1 | 竞品网址 + 种子拓词：至少一个 `-k` + `--url`，落盘后去重/排序/截 Top N | §1 |
-| 2 | 多种子长尾：`-k "种子1,种子2,..."` | §2 |
-| 3 | 按规则洗词：月搜索量阈值、排除词根、排除类意图等 | §2（JSON） |
-| 4 | 账户关键词表现 + 市场侧指标：`google-analysis` keywords → 抽词 → 分批 `keyword` | §3 |
-| 5 | 搜索词 + 拓词：浪费流量 / 否词线索 | §4 |
-| 6 | 高商业意图粗筛：CPC、竞争度、搜索量 | §5 |
-| 7 | 否词或否词根落地：`ad keyword-negative-create` 等 | §4 + `google-ads.md` |
-| 8 | Campaign → AdGroup → 关键词与匹配：`ad campaign-create` / `ad keyword-create` 等 | §6 |
-| 9 | 拓词结果导出：`keyword … --json-out`，供脚本消费 | §7 |
+| #   | 场景                                                                             | 编排                 |
+| --- | -------------------------------------------------------------------------------- | -------------------- |
+| —   | **仅 Google Planner 数据**（不联网搜索、不用 `--url`）                           | 上文「分支 B」       |
+| 0   | **先 RAG 再拓词**：客户产品/行业背景 → 种子词与 `--url`                          | §0                   |
+| 1   | 竞品网址 + 种子拓词：至少一个 `-k` + `--url`，落盘后去重/排序/截 Top N           | §1                   |
+| 2   | 多种子长尾：`-k "种子1,种子2,..."`                                               | §2                   |
+| 3   | 按规则洗词：月搜索量阈值、排除词根、排除类意图等                                 | §2（JSON）           |
+| 4   | 账户关键词表现 + 市场侧指标：`google-analysis` keywords → 抽词 → 分批 `keyword`  | §3                   |
+| 5   | 搜索词 + 拓词：浪费流量 / 否词线索                                               | §4                   |
+| 6   | 高商业意图粗筛：CPC、竞争度、搜索量                                              | §5                   |
+| 7   | 否词或否词根落地：`ad keyword-negative-create` 等                                | §4 + `google-ads.md` |
+| 8   | Campaign → AdGroup → JSON：`ad campaign-validate` → `ad campaign-create` | §6                   |
+| 9   | 拓词结果导出：`keyword … --json-out`，供脚本消费                                 | §7                   |
+
+---
+
+## 指定拓词市场地区（geoTargetConstant）
+
+Google Keyword Planner 的搜索量/CPC 与**目标国家/地区**相关。CLI 与 Web 网关一致：
+
+1. **查国家 ID**：
+   ```bash
+   siluzan-tso keyword geo-list --json-out ./snap-geo
+   # 或按代码过滤：--country-code US,CN
+   ```
+2. **带地区拓词**（单次只传 **一个** ID 时，指标对应该市场）：
+   ```bash
+   siluzan-tso keyword -k "pipe" --geo 2840 --json-out ./snap-kw-us
+   ```
+
+常见 ID（与 `ad campaign-create --location-ids` 同源）：美国 `2840`，中国 `2826`。
+
+### ⚠️ 多地区 `--geo`：返回汇总数据，无法按地区拆分
+
+`--geo` 可传多个 ID（逗号分隔，如 `--geo 2840,2826`），网关会把它们一并传给 `keywordidea/google?geoTargetConstantIds=...`。此时 Google Keyword Planner 返回的 `montlySearch`、CPC、竞争度等是**跨所传地区的汇总/合并口径**，**不是**「每个国家各一行」或 JSON 里带 `geoTargetConstantId` 分字段。
+
+| 需求 | 做法 |
+| ---- | ---- |
+| 只要「美国+中国合在一起」的市场参考 | 一次调用：`--geo 2840,2826` |
+| 要对比美国 vs 中国各自搜索量/CPC | **多次调用**，每次 `--geo` **只传一个** ID，分别 `--json-out` 到不同目录（如 `./snap-kw-us`、`./snap-kw-cn`） |
+
+**禁止**把 `--geo 2840,2826` 的单次落盘结果当成「美国一套、中国一套」两张表；报告里若写多市场对比，须注明数据来源为分次 `keyword` 调用。
+
+```bash
+# 正确：分市场各查一次
+siluzan-tso keyword -k "pipe" --geo 2840 --json-out ./snap-kw-us
+siluzan-tso keyword -k "pipe" --geo 2826 --json-out ./snap-kw-cn
+
+# 易误解：单次多 geo 只有汇总指标，无法在 items[] 内按国家拆开
+siluzan-tso keyword -k "pipe" --geo 2840,2826 --json-out ./snap-kw-merged
+```
 
 ---
 
 ## 无接口能力（勿过度承诺）
 
-| 能力 | CLI 现状 |
-| ---- | -------- |
-| 种子词 / 多种子、可选竞品站 URL、本地 `--include` / `--exclude`、搜索量与 CPC、竞争度 | ✅ `keyword` |
-| 账户内关键词/搜索词表现 + 再对重点词拉市场侧指标 | ✅ 多命令编排（见下） |
-| 词包数值过滤、意图分类、语义 AdGroup、否词清单、匹配策略表 | ✅ **由 AI 消费 `--json-out` 落盘结果后产出**；无单独算法命令 |
-| Google Ads 内「过去 12 个月按月」搜索量趋势曲线 | ❌ **无接口**，勿用本 CLI 假装产出 |
-| Keyword Planner **Forecast**（官方点击/展示/成本预估） | ❌ **无接口**；若用户要官方 Forecast，引导至 Google Ads 界面或接受「仅粗算说明」并标注非 Forecast |
+| 能力                                                                                  | CLI 现状                                                                                          |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 种子词 / 多种子、可选竞品站 URL、本地 `--include` / `--exclude`、搜索量与 CPC、竞争度 | ✅ `keyword`                                                                                      |
+| 按国家/地区限定 Keyword Planner 市场指标                                                | ✅ `keyword geo-list` + `keyword --geo`                                                           |
+| 账户内关键词/搜索词表现 + 再对重点词拉市场侧指标                                      | ✅ 多命令编排（见下）                                                                             |
+| 词包数值过滤、意图分类、语义 AdGroup、否词清单、匹配策略表                            | ✅ **由 AI 消费 `--json-out` 落盘结果后产出**；无单独算法命令                                     |
+| Google Ads 内「过去 12 个月按月」搜索量趋势曲线                                       | ❌ **无接口**，勿用本 CLI 假装产出                                                                |
+| Keyword Planner **Forecast**（官方点击/展示/成本预估）                                | ❌ **无接口**；若用户要官方 Forecast，引导至 Google Ads 界面或接受「仅粗算说明」并标注非 Forecast |
 
 ---
 
 ## 通用执行规范
 
 - **一律**对可复用中间结果使用 `--json-out <目录>`（或等价快照参数），再读 `cli-manifest*.json` / 各 section 的 `*.outline.txt` 了解字段；详见 **`references/tips.md`**。
-- **写账户**（加词、加否词、改系列）须遵守 **`references/google-ads.md`** 开篇流程：先方案与用户确认，再执行写命令；写后用成对读命令复核。
+- **写账户**（新建系列/加词/加否词）：新建系列走 **`references/google-ads-campaign-plan.md`**（含 `campaign-validate`）；其余写操作先与用户确认，写后用成对读命令复核（命令见 `google-ads.md`）。
 
 ---
 
 ## 场景编排
 
+### 0）先知识库、再市场侧拓词（推荐）
+
+当用户给出**客户/品牌**或需要**产品型号、英文类目、应用场景**才能写出靠谱种子词时，**先**走 `references/rag.md`，**再**调用 `keyword`（市场侧指标与账户内表现仍须区分，见文首「数据口径」）。
+
+1. 选定客户知识库：  
+   `siluzan-tso rag list --rag-only --json`
+2. 检索产品/行业背景（锁定 `--folder-id`，长正文优先 `--partition wiki`）：  
+   `siluzan-tso rag query -q "产品型号 英文类目 应用场景 认证" --folder-id <id> --partition wiki --top-k 12 --json`
+3. 从 RAG 片段归纳 **2–8 个种子词**（含官网/画册中的英文写法），再拓词：  
+   `siluzan-tso keyword -k "种子1,种子2,..." [--url "<落地页>"] --json-out ./snap-kw`
+4. 报告/词包说明中标注：**卖点与术语来自知识库片段**；搜索量/CPC/竞争度来自 `keyword`（市场参考）。
+
+```bash
+siluzan-tso rag list --rag-only --json
+siluzan-tso rag query -q "结构胶 型号 SG 建筑幕墙" --folder-id <id> --partition wiki --top-k 12 --json
+siluzan-tso keyword -k "structural adhesive,SG-200,curtain wall bonding" --url "https://example.com/products" --json-out ./snap-kw
+```
+
 ### 1）竞品网址 + 种子拓词
 
 1. 选定至少 **1 个种子词** `-k`（品类、品牌或竞品站上的核心产品词均可）；**不可**仅传 URL。
@@ -62,6 +161,8 @@
 
 ### 3）旧账户关键词 + 叠市场侧 CPC/热度
 
+可选前置：若账户所属客户有知识库，先 `rag query` 核对产品表述，避免对账户内高花费词做错误英文拓词。
+
 1. 拉账户表现：  
    `siluzan-tso google-analysis -a <mediaCustomerId> --sections keywords --start <S> --end <E> --json-out ./snap-ga`
 2. 从落盘 JSON 抽取关键词文案（字段路径以该次 **`keywords-*.outline.txt`** 为准）。
@@ -78,13 +179,11 @@
 ### 5）高商业意图粗筛（出价 + 竞争度 + 搜索量）
 
 1. `siluzan-tso keyword -k "..." --json-out ./snap-kw`
-2. 对落盘 `items` 按 `averageCpc`（JSON 内常为微单位；表格 stdout 已换算展示）、`competition` / `competitionV2`、`montlySearch` 综合排序截断；此外 `lowTopOfPageBidMicros` / `highTopOfPageBidMicros`（页首出价 20/80 分位，**微单位**）可用于评估合理出价区间。
+2. 对落盘 `items` 按 `averageCpc`（CLI 出口已 ÷1,000,000，货币见 **`bidAmountCurrency`**）、`competition` / `competitionV2`、`montlySearch` 综合排序截断；此外 `lowTopOfPageBid` / `highTopOfPageBid`（页首出价 20/80 分位，与 `bidAmountCurrency` 一致）可用于评估合理出价区间。
 
-### 6）Campaign → AdGroup → 关键词 映射表 + 匹配建议
+### 6）词包 → campaign-create JSON
 
-1. 输入为 `keyword`（或合并账户词）的 JSON。
-2. 结构设计与匹配类型：**遵循** `references/google-ads-rules/google-ads-keyword-strategy.md`；由 AI 输出树形或表格。
-3. 执行：`ad campaign-create` / `adgroup-create` / `ad keyword-create` 等（**`references/google-ads.md`**，`keywordText` 与 `--match-type` 格式以前者为准）。
+拓词落盘结果 + `google-ads-keyword-taxonomy.md` 分层建议 → 填 JSON（`KeywordsForBatchJob`、`campaign-validate`、`campaign-create`）见 **`references/google-ads-campaign-plan.md`** § 标准流水线 **步 3–7**。
 
 ### 7）拓词结果标准化导出
 
@@ -98,9 +197,14 @@
 ## 单命令速查
 
 ```bash
-siluzan-tso keyword -k "<必填，逗号分隔多词>" [--url <url>] [--include <words>] [--exclude <words>] [--json] [--json-out <dir>] [--verbose]
+siluzan-tso keyword -k "<必填，逗号分隔多词>" [-a <mediaCustomerId>] [--geo <id[,id...]>] [--url <url>] [--google-only] [--include <words>] [--exclude <words>] [--json] [--json-out <dir>] [--verbose]
+siluzan-tso keyword geo-list [--country-code <codes>] [--name-contains <text>] [--json] [--json-out <dir>]
 ```
 
-**返回字段**（与后端 `Samm.Core.Service.KeywordRecommendation` 对齐）：`keyword` / `montlySearch` / `averageCpc`（微单位）/ `competition`（0~1 数值）/ `competitionV2`（`Low/Medium/High/Unknown`）/ `keywordPlanCompetitionLevel`（1~4 整数）/ `lowTopOfPageBidMicros` / `highTopOfPageBidMicros`（页首出价 P20/P80，微单位）/ `source`（`"Google"` 或 `"Cgy"`）。后端已按 `keywordPlanCompetitionLevel` 降序排序。
+`-a`：走 `keywordrecommendation/recommend/{id}/google`；先 `list-accounts -m Google -k <id>` 确认账户与 **`currencyCode`**；出价金额字段为 `averageCpc` / `lowTopOfPageBid` / `highTopOfPageBid`（**账户币种「元」**，非汇率换算）。
+
+`--google-only`：只调 Google 推荐主接口（有 `-a` 为账户接口，无 `-a` 为 `keywordidea/google`），不叠加 `--url` 的网址拓词；**分支 B（仅 Google）必加**。
+
+**返回字段**（与后端 `Samm.Core.Service.KeywordRecommendation` 对齐）：根级与每条 **`bidAmountCurrency`**（无账户=`USD`；有账户=`list-accounts` 的 `currencyCode`）；`averageCpc` / `lowTopOfPageBid` / `highTopOfPageBid`（微元 ÷1,000,000，**与 `bidAmountCurrency` 一致**）。无账户 USD 时可选 `usdToCnyExchangeRate` 与 `averageCpcCNY` 等**参考**字段（非 Google 账户币种口径）。另有 `keyword` / `montlySearch` / `competition` / `competitionV2` / `source` 等。
 
 与只读账户关键词列表、否词 CRUD 的对照仍归 **`references/google-ads.md`** 中 `ad keywords` / `ad keyword-*` 各节。

package/dist/skill/references/rag.md

@@ -0,0 +1,104 @@
+# rag：知识库检索（TSO 广告投放辅助）
+
+知识库管理页面在 https://www-ci.siluzan.com/knowledge-base/
+
+为 **广告投放、账户分析、拓词、诊断报告** 等 TSO 业务提供**企业已入库**的产品、行业、客户背景事实依据。
+
+**何时用**：回答或生成内容依赖「客户产品参数、卖点、行业术语、公司背景」且不应凭模型记忆编造时，先 `rag list` 锁定客户库，再 `rag query` 取片段，再结合 `keyword` / `ad` / `google-analysis` 等命令执行。
+
+**何时不用**：纯数据拉取（消耗、余额、系列状态）→ 走 `stats` / `google-analysis`；社媒口播/三库写稿 → 用 `siluzan-cso rag`（见 CSO skill）。
+
+---
+
+## 命令速览
+
+```bash
+# 1. 列出已建索引的知识库（按客户/品牌选 folder）
+siluzan-tso rag list --rag-only --json
+
+# 2. 检索产品/行业资料（建议锁定 --folder-id）
+siluzan-tso rag query -q "产品核心卖点 应用场景 目标客群" --folder-id <id> --partition wiki --top-k 12
+siluzan-tso rag query -q "行业术语 英文类目" --folder-id <id> --top-k 10
+```
+
+---
+
+## 参数说明
+
+| 选项          | 默认      | 说明                                                            |
+| ------------- | --------- | --------------------------------------------------------------- |
+| `-q, --query` | 必填      | 检索词。含空白时按词分检、去重合并（`--json` 含 `subQueries`）  |
+| `--folder-id` | 全库      | 文件夹 ID，逗号分隔；**已识别客户/品牌时强烈建议锁定**          |
+| `--tags`      | 不过滤    | 不传 = 全库无标签限制                                           |
+| `--partition` | `default` | 仅 `wiki` 或 `default`；长正文优先 `wiki`，缺细节再补 `default` |
+| `--top-k`     | 7         | 每分检 3–30 条；多词合并上限 `min(30, topK×词数)`               |
+| `--json`      | false     | 机器可读输出（含 `score` 0–1，越大越相关）                      |
+
+`belongToId` 默认从 `GET /query/account/me` 的 `companyId` 解析；`csoBaseUrl` 从 TSO API 自动推导（`tso-api` → `cso`），可用 `SILUZAN_CSO_BASE` 覆盖。
+
+---
+
+## TSO 业务场景路由
+
+| 用户意图                       | 建议检索词（示例）                        | 后续 TSO 命令                                                     |
+| ------------------------------ | ----------------------------------------- | ----------------------------------------------------------------- |
+| Google 搜索广告方案 / 批量草稿 | 产品卖点、应用行业、目标国家、竞品差异    | `google-ads-campaign-plan.md` + `keyword` / `campaign-create`；草稿发布见 `google-ads.md` § ad batch |
+| 关键字拓词补语境               | 产品型号、英文类目、行业术语、应用场景    | `keyword suggest -k "..."`；编排见 `keyword-planner-workflows.md` |
+| 账户诊断 / 周期报告「背景」段  | 公司简介、主营产品、目标市场、认证资质    | `google-analysis` + `report-templates/` 对应模板                  |
+| 询盘分析报告                   | 产品线、出口市场、客户画像、大洲业务侧重  | `report-templates/google-inquiry-analysis.md`                     |
+| 开户行业/资质核对              | 营业执照经营范围、行业描述、品牌全称      | `open-account-by-media.md` 对应媒体开户流                         |
+| 优化建议解释                   | 产品毛利结构、旺季、转化路径（表单/电话） | `optimize` 记录 + 人工解读；数据仍来自 `google-analysis`          |
+
+检索结果**只作事实参考**：广告标题/描述须符合 `google-ads-rules/google-ads-compliance.md`；数值指标仍以 CLI 拉数为准。
+
+---
+
+## AI 检索策略（TSO 版）
+
+### 1. 先锁客户库
+
+- 运行 `rag list --rag-only --json`，按知识库**名称**匹配用户说的公司/品牌。
+- 多客户代运营：每个客户单独 `--folder-id`，**禁止**混库检索后张冠李戴。
+
+### 2. 改写为「检索型」问句
+
+去掉「帮我」「分析一下」等任务句，保留 **实体 + 属性**：
+
+- 差：「这个客户 Google 广告怎么投」
+- 好：`产品系列 出口 认证 CE FDA` 或 `注塑机 型号 吨位 应用`
+
+### 3. 空格分检（多角度）
+
+```bash
+siluzan-tso rag query -q "产品 卖点 差异化" --folder-id <id> --partition wiki --top-k 12
+siluzan-tso rag query -q "目标市场 国家 行业" --folder-id <id> --partition wiki --top-k 10
+```
+
+### 4. 与拉数命令配合
+
+典型编排：
+
+```
+rag list --rag-only --json
+  → rag query（产品/行业背景）
+  → list-accounts -k <id>
+  → keyword suggest / google-analysis / ad campaigns
+  → 报告模板输出（背景段引用 RAG，数据段引用 JSON）
+```
+
+### 5. 结果使用纪律
+
+- `score` 越大越相关；明显跑题片段丢弃。
+- 不得把 RAG 片段里的过期价格/政策当作当前投放依据；金额与消耗以 `stats` / `google-analysis` 为准。
+- 片段不足以支撑结论时如实说明缺口，**不要编造**。
+
+---
+
+## 与 CSO rag 的区别
+
+| 维度      | siluzan-tso `rag`                         | siluzan-cso `rag`                             |
+| --------- | ----------------------------------------- | --------------------------------------------- |
+| 主要用途  | 广告投放、分析、拓词、报告背景            | 社媒文案、三库素材、口播写稿                  |
+| 默认 tags | 不过滤（按 folder 锁客户）                | 常配合三库 tags（见 CSO `references/rag.md`） |
+| 后续命令  | `ad` / `keyword` / `google-analysis`      | `publish` / 写稿工作流                        |
+| API       | 相同 `cutapi/v1/material/queryknowledges` | 相同                                          |

package/dist/skill/references/reporting.md

@@ -4,7 +4,7 @@
 >
 > 本文档仅覆盖 **TSO steward 优化报告**：列表、生成、删除、邮件推送与网页查看。  
 > **账户分析拉数**（`google-analysis`、`report tiktok-*`、`report bing-*`、`report meta-overview`）与**周期/诊断报告纲要**见 `references/account-analytics.md`。  
-> **异步批量 / 智投记录**（`ad batch`）见 `references/aigc.md`。  
+> **异步批量创建记录**（`ad batch`）见 `references/google-ads.md` § ad batch。  
 > **AI 广告优化**（`optimize`）见 `references/optimize.md`。  
 > **广告线索**（`clue`）见 `references/clue.md`。
 

package/dist/skill/references/tips.md

@@ -14,6 +14,12 @@
 
 ---
 
+## 币种（**Agent 必读**）
+
+涉及余额、消耗、预算、报告、Excel 前：**先 Read `references/currency.md`**，从 `list-accounts` / `balance` / `stats` / `google-analysis` 的 **`currencyCode`** 确定 CNY 或 USD，再选 **￥** 或 **$**。**禁止**默认 Google=美金、禁止跨币种求和。
+
+---
+
 ## 处理顺序（**Agent 必读**）：先 outline → 再 JSON → 再脚本聚合
 
 每条 `--json-out` 命令成功后，**必须**按以下顺序处理，不要跳步、不要把 outline 当数据：
@@ -23,7 +29,7 @@
    - 第 1 行（注释）：`// outline of \`<xxx>.json\` — schema-only, NOT the data.` —— **明确告诉你它是"数据结构描述文件"**，不要把它当业务数据使用。
    - 第 2 行（注释）：中文用法说明。
    - 第 3 行（注释）：类型推断口径（数组取前 8 项去重并集；环或重复对象记为 any）。
-   - 其后**可能**还有若干行 `//` 字段提示（例如 `google-analysis` 的 **`campaigns-*.outline.txt`** 会插入 **`budgetAmount` 单位**说明）。
+   - 其后**可能**还有若干行 `//` 字段提示（例如 `google-analysis` 的 **`campaigns-*.outline.txt`** 会插入金额字段已统一为元的说明）。
    - **类型字面量**：**最后一个不以 `//` 开头的行**（单行 TS，如 `{ a: number; items: { ... }[] }`）—— 写筛选/聚合脚本时取这一行即可。
    - 提取写法：`outlineRaw.trimEnd().split('\n').filter(l => !l.startsWith('//')).pop()`（**不要**用 `lines[lines.length - 1]`：当最后一行是空行时会错）。
 3. **再 `require(writtenFiles[0])` / `fs.readFileSync` 读真实 JSON 数据**做筛选、聚合、计算。**禁止**：
@@ -34,11 +40,11 @@
 
 > 这个顺序对所有三类快照统一生效：通用业务命令（`cli-manifest[-<id>].json`）、`google-analysis`（`manifest-<accountId>.json`）、`report …` 分析（`report-manifest[-<accountId>].json`）。三种 summary 都带 `outlineFile`、`agentHint` 字段。
 
-### Google `campaigns-*.json` 预算单位（Agent 易错点）
+### Google `campaigns-*.json` 金额字段
 
-- **`campaigns[].budgetAmount`**：**网关「分」**（主币种 ×100 的整数），**元 = ÷100**。
-- **禁止**按 Google Ads API **微元**用 **`/ 1_000_000`**（会把日预算缩小约 **10⁴** 倍）。
-- 同文件 **`spend` / `averageCpc` / `costPerConversion`**：已是 **元** 小数，与 `budgetAmount` 单位不同。
+- 日预算用 **`budgetAmountYuan`**（元，CLI 出口已 ÷100）；系列层目标 CPA 用 `campaignTargetCpaYuan` / `maximizeConversionsTargetCpaYuan`（元，已 ÷1,000,000）。
+- 同行 `spend` / `averageCpc` / `costPerConversion` 也是元，直接展示。
+- 网关原始字段 `budgetAmount`（分）、`*Micros`（微元）**已不再落盘**，无需做任何单位换算。
 - **`campaigns-*.outline.txt`** 在标准 3 行头注释之后会多 **2 行** 中文 `//` 提示；提取类型行请用 **`outlineRaw.trimEnd().split('\n').filter(l => !l.startsWith('//')).pop()`**（与上文步骤 2 一致），勿把提示行当 TS 类型。
 
 详见 `references/account-analytics.md`「金额单位」「CampaignSectionData」。
@@ -175,7 +181,7 @@ console.log(top.join(','));
 "
 ```
 
-### 7. 根据地区预算比例（需先有 AIGC / 分析 JSON 文件）
+### 7. 根据地区预算比例（分析 JSON 文件）
 
 若上游步骤已生成包含 `budgetProportions` 的快照 JSON（例如自建脚本或历史 `google-analysis` 落盘），直接读该文件：