---
slug: "amz-ads-keyword-architect"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/Derek95king/amz-ads-keyword-architect@main/SKILL.md"
repo: "https://github.com/Derek95king/amz-ads-keyword-architect"
source_file: "SKILL.md"
branch: "main"
---
---
name: amz-ads-keyword-architect
description: 当用户需要做亚马逊关键词拓词、词库搭建/清洗/扩展/拆解/分级打标，或基于竞品 ASIN / 竞品词 / ABA / 选品指南针 / 评论 VOC 产出广告 campaign 架构（投放主题簇、ad group 分层、匹配方式、预算、攻守测分级），或进一步做 VOC 词库/收录排名追踪等关键词资产化交付时使用。覆盖「找词 → 拆解 → 需求三层分析(SIF) → 相关性×需求×竞争×趋势分级 → 属性 7 类分类 → 聚类成主题簇 → 广告架构落地 → VOC库/收录追踪 → Excel/飞书双通道交付」全链路。默认 SIF 分析 + Sorftime 找词/评论，自包含分类与评分，标品≤15/非标品≤30 ad group 主题簇，交付支持本地 Excel 与飞书在线表格双通道（按系统能力检测 + 用户偏好选择，默认 Excel），数值类指标只取数不编造。
---

# 亚马逊广告架构拓词 Skill

> 全链路覆盖「找词 → 广告架构 → 下游资产化 → 双通道交付」：在广告 campaign 架构之上，进一步纳入下游模块（VOC库 / 收录排名追踪），落到同一份工作簿的新增 Sheet。交付支持**双通道**——本地 Excel（默认）或飞书在线表格（可选，按系统能力检测 + 偏好选择），同一份数据两通道复用。受三道 CHECKPOINT / 反模式黑名单 / 簇上限 / 反虚构铁律统一约束。

## 核心理念

关键词资产的最终目的是**服务于广告架构产出**：从「词」到「ad group 主题簇」到「campaign 分层」，每一步都要有量化依据和可落地的执行动作。本 skill 覆盖「找词 → 拆解 → 需求/竞争分析 → 分类分级 → 聚类 → 广告架构 → 下游资产化 → 双通道交付（Excel/飞书）」全链路，自包含（不依赖其他 skill）。

### 绝对禁令

**不得虚构搜索量、SFR、ACOS、CTR、CVR、排名、市场份额等任何数值型指标。** 数值类指标只能通过工具（SIF / Sorftime / ABA 导出）取数；数据缺失时一律标「待数据验证」，仅做语义判断，不以经验值填充关键指标列。

## 标准执行流程

```
Step 0  锚点 + 类目门 + ASIN 回显
        └ 本品 spec + 必含/必排属性 + 竞品同类校验
          （本品 Listing/规格默认用 Sorftime ProductRequest 自抓，不需用户手填）
        └ 未指定类目 → 弹类目门提示 → 等确认
        └ 抓数据前回显竞品 ASIN 原文让用户确认（防串错）
        ↓
Step 1  多源采集
        └ ABA / 竞品反查 / 选品指南针 / 评论 VOC
        └ 按源打标签 + 置信度，以 ABA 为锚
        ↓
Step 2  归一化 + n-gram 拆解
        └ lemmatize、停用词过滤、单复数合并、保留错拼
        └ n-gram 词根拆解（bi/tri-gram → 词根）
        ↓
Step 3  需求量化（词频 ≠ 相关性）
        └ TF-IDF + SIF 需求三层：history / root_trend / demand
        └ 机会维度 ≠ 相关性维度，不得混用
        ↓
Step 4  双维打分  ← 🔴 CHECKPOINT 1（见下）
        └ 相关性（SIF top3 份额优先）× 需求 × 意图明确度
        └ 竞争维度：SIF competition 三维 + CPC + top3 click/conversion share
        ↓
Step 5  属性 7 类分类
        └ 优先级链：品牌 > 否词 > 人群 > 场景痛点 > 属性 > 核心大词 > 长尾
        └ 只取一个最高优先级；属性词备注删除核心产品词后的连续片段
        └ 详见 references/03-classification.md
        ↓
Step 6  聚类成投放主题簇
        └ 标品 ≤15 / 非标品 ≤30 ad group 主题簇
        └ 叠 coverage_ratio 验证覆盖率
        └ 详见 references/04-clustering.md
        ↓
Step 7  广告架构分级
        └ 四维：相关性/意图 × 搜索量 × 竞争/CPC × 趋势
        └ → campaign / ad group / 匹配方式 / 预算占比 / 攻守测
        └ 竞品 ad group 反查（SIF ads_get_ad_group_keyword_breakdown）为实证锚点
        └ 详见 references/05-ad-architecture.md
        ↓
Step 8  输出工作簿 + 否词池（双通道）  ← 🔴 CHECKPOINT 2（见下）
        └ 否词池贯穿 Step 0–7，交付前必须非空
        └ 恒定 Sheet(7)：拓词总表 / P0-P1优先词 / Listing埋词建议 / PPC投放建议 / 否词候选 / 来源汇总 / 执行说明
        └ 条件 Sheet：主题簇(传 --clusters-csv) / 广告架构(传 --architecture-csv) / ASIN画像(传 --asin-summary)
        ↓
Step 9  下游资产化（同一份工作簿，双通道交付 Excel/飞书）
        └ VOC词库：口语词 → 标准搜索表达映射，证据片段待填原文（≤20 词，不编造）
        └ 收录排名追踪：P0/P1/P2 词的待检测台账，指标列=待检测/待数据验证
```

详见 [references/01-flow.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/01-flow.md)。

## 🔴 CHECKPOINT 0 · Step 0 🛑 STOP

**抓取任何数据之前必须完成以下校验，缺一项不进 Step 1：**

```
if 用户未指定具体类目:
    提示：「当前为通用默认阈值（SFR/搜索量/CPC 均为经验值）。正式分析前建议先定义类目并校准阈值。
           是否：(a) 继续用通用默认值  (b) 我先给你类目，按类目切分阈值」
    等待确认

抓数据前回显竞品 ASIN 串原文让用户确认（防串错）。
```

还需满足：
- 竞品 ASIN 3–5 个；不足 3 个先要求补足
- **ASIN 必须是真实串**（`B0` + 8 位真实字符）。若出现 `B08XYZ1234` / `B07ABC5678` 这类明显占位/示例串 → 🛑 停下要求用户给真实 ASIN，**不得拿占位串去取数**
- 本品锚点（spec / 必含属性 / 必排属性）已齐——**优先用 Sorftime `ProductRequest` 自抓本品 Listing（标题/五点/Property 规格/变体）填充，而非要求用户手填**；只有 A+ 图片内文案需手动补
- 竞品类目或形态不一致 → 先提示确认，不混拓
- **交付通道**：用户已点名 Excel/飞书则照办；未点名则默认 Excel，**不在此阶段阻塞**（最终交付前按 `references/09-feishu-delivery.md` 的决策树检测 + 选择即可）。仅当用户明确要飞书但未给已有表时，到交付环节再问「新建表还是写入已有表（给表格链接或标识）」

## 🔴 CHECKPOINT 1 · Step 4 双维打分前 🛑 STOP

抽样 10–20 行，核查**相关性是否被词频或搜索量代理**——词频高 ≠ 相关性高；SFR 低 ≠ 本品强相关。属性分类备注列不得为空。不过则回 Step 3 修正后再打分。详见 [references/07-quality-check.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/07-quality-check.md)。

## 🔴 CHECKPOINT 2 · Step 8 交付前 🛑 STOP

逐项核查五个必要条件：否词池非空、广告分级四维（相关性/需求/竞争/趋势）均已填写、数值列无编造（缺失列必须留空并标「待数据验证」）、Excel 含全部必备 Sheet、**下游 2 Sheet（VOC库/收录追踪）的指标列保持「待检测/待数据验证」而非被编造填充**。任一不过先回对应 Step 修正，不带瑕疵交付。详见 [references/07-quality-check.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/07-quality-check.md)。

## 工具编排 + 数据源双选项

**分工铁律**：Sorftime = 找词 + 评论正文 + 实时抓取；SIF = ABA 需求/竞争/竞品广告架构反查。两者互补，不可互换。

**数据源双选项**：
- 选项 A：用户已提供 ABA / 选品指南针导出文件 → 直接读取，作为 Step 1 锚源
- 选项 B：用户未提供 → 用 SIF `market_get_keyword_history` / `market_get_keyword_demand` + Sorftime `ASINRequestKeywordv2` 补数

站点默认 US，支持 US / CA / EU5（UK/DE/FR/IT/ES）。Sorftime domain 映射：US=1, UK=2, DE=3, FR=4, CA=7, IT=8, ES=9。

**失败兜底（if-then 三段式）**：

| 触发条件 | 一线修复 | 仍失败兜底 |
|---|---|---|
| SIF 某工具报错/无响应 | 重试一次；换等价工具（如 demand↔history） | 切 Sorftime 等价能力；仍不通 → 让用户手工粘原始数据，标该指标「待数据验证」 |
| Sorftime 调用失败/浏览器桥未连 | 确认 Chrome + Kimi WebBridge 已连后重试 | 改用 SIF 反查词替代；VOC 缺失则跳过并在交付说明标注 |
| 完全无外部数据（用户也不提供） | 转「语义版」：65 分语义评分 | 全程标「未补外部数据，待数据验证」，**绝不编造数值** |
| 竞品 ASIN < 3 / 含占位串 | 回 CHECKPOINT 0 要求补足/换真实串 | 用户坚持 → 仅语义拓词且开头声明范围不足 |
| VOC 源为空（无 Review/VOC 词且无 `--voc-csv`） | 提示用户补 Review 采集（Sorftime `ProductReviewsQuery`）；脚本仍出 VOC词库 表头脚手架 | 在执行说明标注「VOC 缺口」，跳过 VOC 映射，不影响其余 Sheet |
| `--voc-csv` 读取失败 / 列异常 | 回退到自动种词脚手架（证据片段留待填） | 标注「VOC 源异常」，提示用户核对 CSV 列后重跑 |
| `--asin` 未提供 | 收录排名追踪表 ASIN 列填「待填」继续生成 | 交付时提醒用户回填 ASIN，不阻塞其余流程 |
| 用户要飞书但 `lark-cli` 不可用（缺命令/`user.available=false`/无 `sheets:spreadsheet:create` scope）| 退回本地 Excel 交付，一句话说明「飞书未接入，需要可后续导入」| 标「飞书未接入」，不阻塞 |
| `lark-cli` 报 `needs_refresh` | 视为正常态，直接调用自动刷新；**不当失败处理** | — |
| 飞书 create/append 写入失败 | 重试一次；macOS Keychain 被沙盒拦截 → 沙盒外重试同条命令，**不改业务逻辑** | 保留本地 `.xlsx` + `.sheets.json` + 可重试命令，说明失败点，标「飞书待重试」，**不为交付成功而编数值** |

飞书通道完整失败表 + 降级见 [references/09-feishu-delivery.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/09-feishu-delivery.md)；工具取数失败见 [references/06-tools-data.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/06-tools-data.md)。

## 输出（双通道交付）

**先定通道，再生成**。交付前按 `references/09-feishu-delivery.md` 的决策树走：①用户点名 Excel/飞书 → 照办；②未点名 → 默认 **Excel**；③用户要飞书 → `lark-cli auth status` 检测能力可用后再选「新建表/写入已有表」，不可用则退回 Excel 并说明。两条通道**共用同一份脚本产物**，不另起炉灶。

**通道一 · 本地 Excel（默认）**：使用 `scripts/build_kw_architecture.py` 生成 `.xlsx`。

**通道二 · 飞书在线表格（可选）**：
- 路径甲（推荐）：脚本产物 `.xlsx` → 调 `lark-drive` skill 导入为飞书在线表格，一次带入全部 Sheet。
- 路径乙（需在飞书原生追加）：脚本加 `--emit-sheets-json` 导出每 Sheet 的 `{name, headers, rows, values}` → 调 `lark-sheets` skill 用 `+create`/`+create-sheet`/`+append` 逐页签构建。
- 细则、降级见 `references/09-feishu-delivery.md`。

支持的核心 CSV 入参：
- `--clusters-csv`（列：主题簇, 主属性维度, 相关性, 需求, 词数）
- `--architecture-csv`（列：campaign, ad_group, 匹配方式, 预算占比, 攻守测）

下游资产化入参（全部并入同一份工作簿）：
- `--voc-csv`（可选，列自定义；不传则从 VOC/Review 类词自动种出脚手架，证据片段留待填）
- `--asin`（本品 ASIN，用于给「收录排名追踪」表种 ASIN 列）
- `--no-downstream`（开关：跳过 VOC库/收录追踪，退回纯广告架构行为，不出下游 Sheet）
- `--emit-sheets-json`（飞书通道才需要：把每个 Sheet 导出为 JSON manifest，喂给 `lark-sheets` 原生构建；Excel 通道不传）

示例命令行（`拓词总表.csv` 为必填 positional 入参 = 关键词总表 CSV）：
```bash
python3 scripts/build_kw_architecture.py 拓词总表.csv \
  --product-name "yoga mat" --core-terms "yoga mat" --asin B0XXXXXXXX \
  --clusters-csv clusters.csv \
  --architecture-csv architecture.csv \
  --voc-csv voc.csv \
  -o 广告架构拓词_B0XXXXXX.xlsx \
  --emit-sheets-json 广告架构拓词_B0XXXXXX.sheets.json   # 仅飞书通道
```

默认追加 2 个下游 Sheet：`VOC词库` / `收录排名追踪`。其指标列默认填「待检测/待数据验证」，由分析人结合工具取数回填，**禁止脚本或模型编造数值**。下游模块细则见 [references/08-downstream-application.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/08-downstream-application.md)。

不支持 Excel 时降级为 Markdown 表格 / 单文件 HTML 报告。数值缺失列留空并标「待数据验证」，绝不编造。飞书在线交付（导入 / 原生构建）见 [references/09-feishu-delivery.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/09-feishu-delivery.md)。

## 簇上限

- **标品** ≤ 15 个 ad group 主题簇
- **非标品** ≤ 30 个 ad group 主题簇

超出上限须合并语义最近的簇，并用 `coverage_ratio` 验证合并后覆盖率不下降。详见 [references/04-clustering.md](https://github.com/Derek95king/amz-ads-keyword-architect/blob/HEAD/references/04-clustering.md)。

## 🚫 反模式黑名单（红灯）

执行中命中任一条 = 立即停手改正：

1. **别把词频/搜索量当相关性** —— 高频多是泛大词；相关性走「反查 ASIN 同类占比」，词频只进需求维。
2. **别编造数值** —— 搜索量/SFR/CPC/ACOS/份额/排名缺数据时标「待数据验证」，绝不用经验值填关键指标列。
3. **别跳类目门** —— 未指定类目先弹 CHECKPOINT 0 提示，不直接用通用阈值开跑。
4. **别用未确认/占位 ASIN 取数** —— ASIN 串必先回显确认；`B08XYZ1234` 类占位串禁止入流程。
5. **别把 VOC 口语直接当投放词** —— 评论词先映射成标准搜索表达再入池（如「light output adjustable」≠ 搜索词，归卖点/A+）。
6. **别把否词流后置** —— 否词池贯穿 Step 0–7 持续沉淀，不到交付才补。
7. **别只按竞争度单维分广告架构** —— 必走「相关性×需求×竞争×趋势」四维，否则金词与垃圾词混档。
8. **别擅自往飞书写** —— 用户没点名通道时默认本地 Excel；要飞书须先 `lark-cli auth status` 检测可用 + 确认新建/写已有表，不可用就退回 Excel 并说明，**不为「交付成功」而在任一通道编造数值**。

## 何时读取详细 references

按当前任务需要，读取对应 reference 文件：

- 走流程、查步骤细节 → `references/01-flow.md`
- 定量化阈值、校准类目参数 → `references/02-metrics.md`
- 做属性 7 类分类、查备注规范 → `references/03-classification.md`
- 语义聚类成主题簇、控簇上限 → `references/04-clustering.md`
- 广告架构决策矩阵、campaign/ad group 分层规则 → `references/05-ad-architecture.md`
- SIF/Sorftime 取数与评分、站点 domain 映射 → `references/06-tools-data.md`
- 交付前三大 CHECKPOINT 自检清单 → `references/07-quality-check.md`
- 下游资产化（VOC库/收录追踪）的列定义与回填纪律 → `references/08-downstream-application.md`
- 交付通道决策（Excel ↔ 飞书检测/偏好）、飞书导入/原生构建两条路径 → `references/09-feishu-delivery.md`

**不要一次读全，按需读取**，节省上下文窗口。