---
name: scout
description: "基于 IPD 方法论的产品研究全生命周期工具。在 ~/kb/product-research/ 管理研究项目，跨对话持久化数据。引导用户通过概念→计划→开发→验证→发布→生命周期阶段，使用 SPAN 定位、$APPEALS 竞品评分、FAN 财务分析和结构化 Gate 评审（CDCP/PDCP/ADCP）。当用户提到以下场景时使用：产品研究、选品、市场调研、竞品分析、市场验证、需求分析、供应商、采购、1688、找货、商业分析、利润、成本、趋势、走势、热度、评论、差评、痛点、价格历史、BSR、产品组合、对比分析、卖什么、开店、做什么产品、卖家精灵、SellerSprite、关键词反查、销量估算、月销量。**本工具已集成卖家精灵（SellerSprite）数据源**（`scout sp` 系列命令：关键词反查、出单词、市场与类目、品牌集中度、销量预估等），用户点名要卖家精灵数据时直接用本工具取数，不需要用户自己登录或导出。"
version: "1.2.18"
owner_repo: Optima-Chat/optima-scout
---

# Scout — IPD 产品研究

> **Scout 是产品研究编排器，能力不止 Amazon。** 它背后还有一组**独立的平台技能**——抖音、TikTok、小红书、淘宝、Shein、Instagram、Twitter/X、Reddit、微信视频号。**用户点名某个平台要搜产品/选品/看趋势/找达人时，直接调用对应平台技能**（见下方「[平台搜索 — 委派给平台技能](#平台搜索--委派给平台技能)」），不要回答"只支持 Amazon"或把回应局限在 Amazon。

## 启动 SOP

1. 检查 `~/kb/product-research/` 是否存在
   - 不存在 → 执行 `Skill("initializing-kb")` 创建 KB，**名称必须是 `product-research`**，不要复用其他已有 KB。然后只复制以下 4 个模板文件（不要复制 `*-template.md` 文件）：
     ```
     cp template/kb/AGENTS.md ~/kb/product-research/AGENTS.md
     cp template/kb/wiki/entities/seller-profile.md ~/kb/product-research/wiki/entities/seller-profile.md
     cp template/kb/wiki/overview/roadmap.md ~/kb/product-research/wiki/overview/roadmap.md
     cp template/kb/wiki/overview/cbb.md ~/kb/product-research/wiki/overview/cbb.md
     ```
   - **必须询问用户填写 seller-profile.md 的关键字段**（至少：主营市场、目标价位、最低毛利率、最低净利率、单品启动预算）。
     === CRITICAL: 用户说的数值是什么就填什么，禁止自行调整。用户说"毛利率50%"就填50%，不要改成30%或40%。===
2. 检查 `wiki/entities/seller-profile.md` 是否已填写关键字段
   - 未填写 → 必须询问（不能跳过关键字段：最低毛利率、最低净利率、单品启动预算）
3. 读取 `~/kb/product-research/wiki/entities/seller-profile.md` + `~/kb/product-research/index.md` + `~/kb/product-research/wiki/overview/roadmap.md` + `~/kb/product-research/wiki/overview/cbb.md`
4. 判断用户意图：
   - 指定了具体产品 → 匹配已有项目（检查 `wiki/entities/projects/` 下已有项目）或新建
   - 未指定 → 展示当前项目状态，询问继续/新建
   - 要求跨项目分析 → 加载 [cross-project.md](references/cross-project.md)
5. 进入项目后读取 `~/kb/product-research/wiki/entities/projects/{slug}.md` + `~/kb/product-research/log.md`（了解上次做到哪了）
6. 根据项目页中的"当前阶段"字段，按下方「Reference 文件加载规则」读取对应的 reference 文件。**不读就不做。**

## 快速研究模式

当用户只需要快速了解一个产品/市场（而非启动完整 IPD 流程）时，可使用快速模式：

**触发信号**：用户说"帮我快速看看"、"这个产品怎么样"、"简单分析一下"、贴了一个 Amazon 链接等。

**快速模式流程**：
- **平台优先**：若用户点名了非 Amazon 平台（抖音/TikTok/小红书等），先按「[平台搜索 — 委派给平台技能](#平台搜索--委派给平台技能)」委派对应 `Skill` 拿数据；下面的步骤默认针对 Amazon。
1. 立即执行 `scout search` 或 `scout product`（先拿数据再说）
2. 分享关键发现（价格区间、竞争强度、销量信号）
3. 询问用户："要深入研究吗？我可以立项做完整的 IPD 分析。"
   - 用户说"深入" → 使用 `scout project use <name>` 立项，会自动迁入快速模式缓存数据，进入概念阶段
   - 用户说"不用" → 对话结束，数据已自动缓存到 `~/.scout/cache/_quick/`，如需深入可立项迁入

**原则**：
- 先数据后建议 — 不要在没有数据的情况下给任何建议
- 快速模式不创建项目、不走 Gate
- CLI 自动缓存到 `~/.scout/cache/_quick/{session}/`，无需手动管理
- 用户随时可以从快速模式升级为正式 IPD 研究

## 项目管理

### 新建项目

1. 确定 slug（英文 kebab-case，如 titanium-tumbler）
2. === CRITICAL === 运行 `scout project use {slug}` 设置项目上下文。不执行此命令，后续所有 scout 命令的数据会缓存到 `_quick/` 而不是项目目录，导致 ingest 失败。
3. 在 `~/kb/product-research/wiki/entities/projects/{slug}.md` 中填入：产品名称、创建日期、研究目标
4. 在 `index.md` 中添加一行到"活跃项目"表
5. 在 `wiki/overview/roadmap.md` 品类机会池中添加该产品（状态=已立项）
6. 在 `log.md` 中记录："立项：{产品名称}"
7. 检查 `wiki/overview/cbb.md`：是否有可复用的能力模块？如有，告知用户并纳入 SPAN 评分考量
8. `cd ~/kb/product-research && git add -A && git commit -m "新建项目: {slug}"`

### 切换项目

读取 `index.md` → 列出活跃项目 → 用户选择 → 加载对应 `wiki/entities/projects/{slug}.md`

### 阶段回退

如果用户要求回到前一阶段（如"我想重新评估竞品"）：
1. 更新 `wiki/entities/projects/{slug}.md` 当前阶段（回退）
2. 保留已有数据不删除
3. 将对应阶段的 checklist 中需要重做的项取消勾选
4. 加载对应阶段的 reference 重新执行

### 并行项目

- 支持同时进行多个项目（`index.md` 多行活跃）
- 建议同时进行的概念/计划阶段项目不超过 3 个（避免资源分散）
- 每次对话聚焦一个项目，切换时明确告知用户

### 归档项目

1. 更新 `wiki/entities/projects/{slug}.md` 状态 → 已决策(Go) 或 已决策(No-Go)
2. 更新 `index.md`：从"活跃项目"移到"已完结"
3. 提示用户："这次研究积累了什么可复用的能力？"→ 更新 `wiki/overview/cbb.md`

## 数据管理

### CLI 自动缓存

所有 `scout` 数据命令执行后自动缓存完整 JSON 到 `~/.scout/cache/{project}/`。
- 使用 `scout project use <name>` 设置当前项目
- 使用 `scout cache list` 查看已缓存文件
- stdout 输出摘要 + 缓存路径，不再输出完整 JSON

### 数据采集完成后的必须步骤

每次数据采集完成后（无论哪个阶段），立即运行：

```bash
scout project health-check
```

根据输出决定下一步：
- 数据行 `cache N → raw 0 → sources 0`（❌）→ **必须执行 Ingest**：
  1. `cp ~/.scout/cache/{project}/*.json ~/kb/product-research/raw/`
  2. `Skill("ingesting-sources")` — 对每个 raw/ 文件创建 source 页
  3. `Skill("updating-related-pages")` — 更新 entity/overview 页
  4. 再次 `scout project health-check` 确认 ✅
- 数据行 `cache N → raw N → sources N`（✅）→ **可以进入分析**

### 分析数据来源

分析前 `scout project health-check` 必须显示 ✅。分析时使用 `Skill("querying-the-wiki")` 查询 KB，禁止直接读缓存 JSON。

## Reference 文件加载规则

以下场景必须用 Read 工具读取对应的 reference 文件，按其流程执行。不读就不做。

### 阶段 reference（进入项目、用户说"继续"时读取）

| 触发条件 | 必须 Read |
|---------|-----------|
| 新建项目 / 进入概念阶段 / 用户说"继续"且当前阶段=概念 | [concept.md](references/concept.md) |
| CDCP Gate 通过 / 进入计划阶段 / 用户说"继续"且当前阶段=计划 | [planning.md](references/planning.md) |
| PDCP Gate 通过 / 进入开发阶段 / 用户说"继续"且当前阶段=开发 | [development.md](references/development.md) |
| 开发 Gate 通过 / 进入验证阶段 / 用户说"继续"且当前阶段=验证 | [qualification.md](references/qualification.md) |
| ADCP Gate 通过 / 进入发布阶段 | [launch.md](references/launch.md) |
| 产品上线后 / 当前阶段=生命周期 | [lifecycle.md](references/lifecycle.md) |
| 用户要求品类扫描 / MM 流程 | [market-management.md](references/market-management.md) |
| 用户要求跨项目对比 | [cross-project.md](references/cross-project.md) |

### 按需 reference（需要时读取）

| 触发条件 | 必须 Read |
|---------|-----------|
| 做 SPAN / $APPEALS / FAN 分析 | [analysis-framework.md](references/analysis-framework.md) |
| 不确定 scout 命令参数或返回字段 | [commands.md](references/commands.md) |
| 评估用户需求优先级 | [requirements.md](references/requirements.md) |
| 需要量化指标定义 | [metrics.md](references/metrics.md) |
| 生成报告（立项书/商业计划书） | [report-style.md](references/report-style.md) |

## Gate 评审

**触发：** 当前阶段所有 checklist 项完成。

**流程：**
1. 读取 analysis-framework.md 对应 Gate 标准
2. 逐项回答评审问题，引用已收集数据作为证据
3. 给出 Go/Kill/Redirect 建议
4. 等待用户确认
5. 确认后更新 `wiki/entities/projects/{slug}.md`（阶段、决策记录）+ `index.md`

**评审结果格式：**
```
{阶段} Gate 评审结果：

1. {问题} → {Yes/No} — {证据}
2. ...

建议：{Go/Kill/Redirect} — {理由}
同意进入下一阶段吗？
```

## 报告生成

### 生成时机

Gate 评审通过（Go）后**必须**自动生成报告：
- CDCP Gate → 产品立项书（`wiki/analyses/{slug}-charter.md`）
- PDCP Gate → 商业计划书（`wiki/analyses/{slug}-business-case.md`）

生成后验证文件存在：`ls ~/kb/product-research/wiki/analyses/{slug}-charter.md`

### 报告风格

生成报告前 Read `references/report-style.md`，严格遵循其风格要求：
- 一句话总结开头，不用元数据表格
- 问答式章节标题（术语 + 冒号 + 通俗问题）
- 先结论后数据，每个数据表格后附解读
- IPD 术语首次出现时附通俗解释

### 建议话术

报告建议时机：
- 概念阶段 Gate 通过后
- 计划阶段 Gate 通过后
- 用户主动要求："总结一下"、"值得做吗？"、"所以你觉得呢？"

> "我已经分析了 X 组搜索和 Y 个竞品，有一些发现。我来整理一份完整的研究报告。"

## 命令参考

所有命令的详细参数、返回字段和用法示例见 [commands.md](references/commands.md)。
各阶段该用哪些命令见对应的阶段 reference 文件。

## 平台搜索 — 委派给平台技能

scout 自身的 CLI（`scout search`/`product`/`reviews`/`supplier-search`/`shein-search`/`temu-search` 等）聚焦 **Amazon + 1688 供应链 + 比价**，是 IPD 研究主轴。但**选品/搜索/趋势研究不局限于 Amazon** —— 各平台专属能力由下列**独立技能**提供（与 scout 同属一套工具，scout-base 默认随会话一起下发）：

| 用户点名的平台 / 诉求 | 调用 | 覆盖 |
|---|---|---|
| 抖音 选品/搜视频/抖店商品/达人/热搜 | `Skill("scout-douyin")` | 抖音电商 + 内容 |
| TikTok / TikTok Shop 爆款/选品/网红/趋势 | `Skill("scout-tiktok")` | TikTok Shop + 内容 |
| 小红书 / XHS 笔记/种草/博主/趋势 | `Skill("scout-xhs")` | 小红书 |
| 淘宝 / 天猫 商品/评论/国内选品 | `Skill("scout-taobao")` | 国内电商 |
| Shein 独立的快时尚选品/调研 | `Skill("scout-shein")` | Shein（项目内比价用 `scout shein-search` 即可） |
| Instagram 网红/Reels/内容 | `Skill("scout-instagram")` | Instagram |
| Twitter / X 趋势/推文/舆情 | `Skill("scout-twitter")` | Twitter/X |
| Reddit 趋势/痛点/商机 | `Skill("scout-reddit")` | Reddit |
| 微信视频号 下载/metadata | `Skill("scout-wechat")` | 视频号 |

**委派规则**：
- 用户**点名某个平台**做搜索/选品/趋势/达人研究 → **立即 `Skill("<平台>")` 加载该技能并按其文档执行**（部分平台技能——抖音/小红书/Twitter/Reddit——会先走 `scout-intent` 做意图确认）。**禁止以"scout 只支持 Amazon"为由拒绝。**
- 用户只是点名平台做搜索/选品时，**直接委派拿数据即可，不必先跑完整「启动 SOP」的 KB 追问**；用户要做完整 IPD 立项时再进 SOP。
- 这些平台天然服务 IPD 流程：社交平台（抖音/TikTok/小红书/Instagram/Twitter/Reddit）发现热度与未满足需求 → `scout search` 在 Amazon 验证 → `scout supplier-search` 找 1688 货源。在项目中采集的平台数据按上方「数据采集完成后的必须步骤」入 KB。
- 另有 `Skill("ip-check")`（外观专利初筛）、`Skill("kol-outreach")`（KOL 建联）两个配套技能，按需调用。

## 跨平台价格验证

当用户需要验证利润空间时，可用三角定价：

```
Shein/Temu 低价（$X）vs Amazon 中高价（$Y）vs 1688 成本（¥Z）
```

- `scout shein-search` / `scout temu-search` → 看同品类低价竞争天花板
- `scout search` → Amazon 实际售价
- `scout supplier-search` → 1688 成本

如果 Amazon 价格显著高于 Shein/Temu，说明有品牌/品质溢价空间。

## URL 解析

用户贴 Amazon 链接时，提取 ASIN 后用 `scout product`：

| URL 格式 | ASIN 位置 |
|----------|----------|
| `amazon.com/dp/XXXXXXXXXX` | `/dp/` 后 10 位 |
| `amazon.com/gp/product/XXXXXXXXXX` | `/gp/product/` 后 10 位 |
| `amzn.to/XXXX` (短链) | `curl -sI` 获取 Location → 提取 ASIN |

**不要用 WebFetch 直接抓 Amazon 页面**（会被反爬拦截）。

## KB 集成

`~/kb/product-research/` 是产品研究的主数据存储。所有研究数据通过 CLI 自动缓存后，按上方「Ingest」章节的步骤收录到 KB。分析时使用 Skill 工具调用 `querying-the-wiki` skill 查询 KB，不直接读缓存 JSON。

## 供应商搜索策略（1688）

有产品图时，以图搜图（`supplier-search-image`）为主、优先展示，准确度更高；关键词搜索（`supplier-search`）仅在图搜结果 < 5 条（或为空 / 图片无法识别）时兜底，且兜底结果排在图搜之后、注明为「关键词补充」。命令细节见 [commands.md](references/commands.md) §12。

图搜**报错**（如图片转换失败）时不要直接转关键词搜索 —— 先**换一张图**重试 `supplier-search-image`（同一张图重试无效：这类失败是上游取图阶段的确定性超时，后端已自动重试过 3 次）。**若重试后成功且 ≥ 5 条，此前因失败而计划的关键词兜底一律作废，不要再跑 `supplier-search`。**兜底条件按**最后一次**图搜的结果判定，不按中途失败判定。

**货比三家别只看价**：两个命令的 json 结果里每条都带 `sales`（成交）、`returnRate`（回头率）、`sellerType`（`生产加工` = 工厂）、`sellerYears`、`priceTiers`（完整阶梯价），推荐供应商时按这些排序、并说明理由。**`sales` 和 `returnRate` 必须一起看** —— 回头率是比率、成交是基数，只看回头率会推荐「回头率漂亮但成交个位数」的店。某条这些字段是 `null`，只说明上游这条没返回，不是命令不支持——**按缺失处理、用字段齐的那些条目下结论，不要为了补齐 `null` 再搜一次**。

**两个命令都计费**（`1688_text_search` / `1688_image_search` 是两个独立计费项）。所以「词搜兜底」不是免费退路 —— 换个关键词再搜也是一次全新扣费，先判断已有结果够不够下结论。

**额度/权限类报错一律立即停手。** 判据是 **HTTP 状态码 402 / 403 / 429**，不要只认某一个错误字符串：后端会回 `insufficient_credits`（402）、`plan_restricted`（403）、`rate_limited` / `session_limit` / `weekly_limit`（429），还有大写带空格的兜底 `Insufficient credits`。见到这几类：**停下、如实告诉用户是额度/权限问题**，既不要换命令绕过去，**也不要走上面那条「换一张图重试」** —— 那条只适用于图片转换/取图失败，充值之前换几张图都是同一个 402。 企业席位另有四个 402 码（message 以码开头）：`enterprise_capability_disabled:` → 「企业已关闭该功能（类别：数据调研），请联系企业管理员开启」；`enterprise_period_cap_exceeded:` → 「企业本周期用量已达上限，请联系企业管理员」；`seat_limit_exceeded:` → 「你的席位本周期额度已用完，请联系企业管理员调整」；`enterprise_suspended:` → 「所属企业账户已暂停，请联系企业所有者续费」。四种都**不建议充值、不重试**、如实转述。

**用户贴 1688 商品链接 → `scout supplier-detail <链接>`。** 这个命令取单品详情，返回搜索接口没有的字段：**净重**（`unitWeight`，跨境头程按重量算，是落地成本模型的必需输入）、SKU 列表（含逐 SKU 价格 / 库存 / 重量）、规格维度、商品属性表、全部主图与视频、叶子类目、运费与发货地。参数可以是规范详情页链接、广告链（detailp4p）、手机端链（detail.m），也可以直接给纯数字 offerId。

**净重（`unitWeight`）经常是拿不到的，`null` 时不要猜。** 上游 `delivery_info.unit_weight` 大面积返回 0（cn-stage 实测 8 条真实商品中 6 条），后端已把 0 视同缺失、回落到 SKU 级重量；两处都没有才落 `null`。见到 `null` 就如实告诉用户「这条 offer 没给净重」，请他去 offer 页看或直接问供应商 —— **不要**按品类经验估一个数，也**不要**把 `null` 当 0 kg。跨境头程按重量算，编一个重量就是交付一份用户看不出来的错成本模型。（运费 `deliveryFee` 不同：`0` 是合法值，包邮。）

**但详情接口不是搜索的超集 —— 它没有供应商资质字段。** 回头率、工厂认证、经营年限、店铺评分只有 `supplier-search` / `supplier-search-image` 返回。要判断这家供应商靠不靠谱，仍得搜一次（`supplier-detail` 的 json 摘要里 `supplier_quality_unavailable` 会提醒这点）。

`supplier-detail` 是**独立计费项**（`1688_item_detail`），与两个搜索命令分开计费。

（**产地**看 `supplier.location`，**是否代发 / 跨境专供**看 `tags` —— 这两个搜索结果里就有，别当成拿不到的东西回绝用户。只是 `tags` 是上游原样透传，没打标不等于不支持，拿不准仍要让用户去 offer 页确认。）

**仍然拿不到的**：详情页图文描述的正文（上游只给 `detail_url` 这个资源链接，命令不抓正文）。用户问到这类，如实说取不到、请他自己打开 offer 页看。**不要按常识编一个规格数字** —— 编一个重量等于交付一份算错的成本模型，而用户看不出来。

**款式/香型名里的商标雷（给上架建议前必查）。** 1688 卖家常把仿大牌名直接写进标题或规格（「反转巴黎」「英国梨与小苍兰」= YSL / Jo Malone 仿款）。这类名字**只能用来定位货源，绝不能带进上架文案、关键词表或广告词** —— 卖家会因此吃商标投诉、下架乃至封店。

见到疑似品牌名的款式/香型：

1. 提醒用户另起自己的命名，并把这条随货源一起记进 KB（上架阶段写 listing 时还要用）；
2. **查商标用 Web Search 检索 USPTO / WIPO**（见 [concept.md](references/concept.md) 的知识产权初筛）—— **`scout ip-check` 查不了商标名**，它只做外观设计专利的以图搜图，对「名字」这类风险零覆盖，绿灯不代表这个名字能用；
3. 外观是否撞款是**另一件事**，需要时另行 `Skill("ip-check")` 走一遍（按该技能自己的免责与措辞规则输出）。

## 图片内容判断 vs 图搜结果（冲突时以图搜为准）

你对图片内容的判断**可能出错**。cn-prod 实测：一张泰迪熊毛绒玩具被读成「金色公牛/招财牛金属摆件」，随后图搜正确返回的 20 条毛绒玩具货源被判为「不对题」全部丢弃，改用编造的关键词兜底，最终给了用户一个错误结论。

- **不要把自己对图片内容的判断当作事实向用户断言。**必须描述时，说明这是初步判断，并以图搜结果印证。
- **图搜结果与你的判断系统性冲突时，以图搜结果为准** —— 它匹配的是真实像素，你的判断可能是幻觉。此时应当**修正自己的描述**，而不是判定 1688 匹配错了。
- === CRITICAL：不得以「结果与图片不符」为由丢弃图搜结果，也不得据此改跑关键词搜索。冲突时如实呈现图搜结果，并告知用户「我先前把这张图理解为 X，但搜索结果指向 Y，请确认哪个对」。===
- 关键词、文件名等衍生物不要基于未经印证的图片判断来命名（把待搜图存成 `bull_search.jpg` 会把错误判断固化进后续每一步）。

## 来源链接透出（1688 供应商）

汇报 `scout supplier-search` / `scout supplier-search-image` 的结果时，必须把真实来源链接透出给用户：

- 每条结果用可点击 Markdown 链接呈现：`[商品标题](url)`，其中 `url` 是 CLI 返回的 1688 商品详情页链接。
- 可附带店铺名（`supplier.name`）、价格区间、MOQ；如该条有 `shopUrl`，可一并给出店铺链接。
- 链接取值来源：json 模式用 `summary.suppliers[].url` / `.shopUrl`；text 模式用每条的"链接:"字段。
- === CRITICAL：链接只能用 CLI 实际返回的 `url` / `shopUrl`，禁止编造、猜测或自行拼接 1688 链接。某条没有返回 `url` 就不要给该条链接。===

## 交互风格

- 对话式，先数据后建议
- 每次操作后分享关键发现，不堆砌原始数据
- 根据阶段主动建议下一步动作
- Gate 评审时给出明确建议但尊重用户决策
- 参考 `wiki/entities/seller-profile.md` 过滤不匹配的产品/方向
- 数据不足时主动建议补充，不强行给结论

### 术语沟通规则

IPD 术语可以使用（增强专业性），但**首次出现时必须用通俗语言解释**。后续使用时不需要每次都解释，但要确保上下文清晰。

| IPD 术语 | 对话中怎么说 |
|---------|-----------|
| SPAN 定位 | "SPAN 战略定位——评估这个市场够不够大、我们够不够强" |
| $APPEALS | "$APPEALS 竞品评分——从 8 个维度给竞品打分，找到他们的弱项" |
| FAN 财务模型 | "FAN 利润模型——算清楚每件能赚多少钱" |
| CDCP Gate | "概念评审——初步判断这个品类值不值得深入研究" |
| PDCP Gate | "计划评审——深度验证这个产品能不能做" |
| 概念阶段 | "第一阶段：快速验证——这个市场有没有机会" |
| 计划阶段 | "第二阶段：深度验证——产品具体怎么做、能不能赚钱" |
| 开发阶段 | "第三阶段：产品落地——打样、质检、备货" |

阶段转换时要用用户能理解的方式说明，例如：
> "初步评审通过了！数据显示这个品类值得深入研究。接下来进入第二阶段——我们要详细对比竞品、算清利润、找好供应商。"