@optima-chat/optima-agent 0.9.20 → 0.9.21

package/.claude/skills/scout/SKILL.md

@@ -1,615 +1,328 @@
 ---
 name: scout
-description: "Interactive Amazon product research consultant with 1688 supplier sourcing and Keepa historical data. Search products, analyze markets, deep-dive reviews for pain points, find suppliers (by keyword or image), track price/BSR history, and generate professional reports. ALWAYS use when user asks about: selling products (卖/开店), product ideas (产品/商品), market research (市场/竞品), reviews/pain points (评论/差评/痛点/用户反馈), suppliers (供应商/厂家), sourcing (采购/进货/货源), image search (图片找货/以图搜货/找同款), evaluating business opportunities (生意/创业), product trends (趋势/走势), price history (价格历史/价格变化), BSR ranking (排名/销量排名), product lifecycle (生命周期/增长期/衰退期). Uses 'scout search', 'scout product', 'scout reviews', 'scout keepa *', 'scout supplier-search', and 'scout supplier-search-image' commands."
+description: "基于 IPD 方法论的产品研究全生命周期工具。在 ~/products/ 管理研究项目，跨对话持久化数据。引导用户通过概念→计划→开发→验证→发布→生命周期阶段，使用 SPAN 定位、$APPEALS 竞品评分、FAN 财务分析和结构化 Gate 评审（CDCP/PDCP/ADCP）。当用户提到以下场景时使用：产品研究、选品、市场调研、竞品分析、市场验证、需求分析、供应商、采购、1688、找货、商业分析、利润、成本、趋势、走势、热度、评论、差评、痛点、价格历史、BSR、产品组合、对比分析、卖什么、开店、做什么产品。"
 ---
 
-# Optima Scout - AI Product Research
+# Scout — IPD 产品研究
 
-## When to Use This Skill
+## 启动 SOP
 
-Use this skill when:
-- User wants to research products or validate product ideas (e.g., "我想开店卖钛合金杯子", "帮我搜索一下XX")
-- User needs market analysis or competitive research
-- User asks about product pricing, ratings, sales data, or market trends
-- User wants to evaluate business opportunities or find products to sell
-- User needs detailed competitor analysis or listing quality assessment
-- User needs to find suppliers or manufacturers (e.g., "帮我找咖啡机供应商", "哪里进货")
-- User wants to source products from 1688/Alibaba China
-- User asks about wholesale prices, bulk purchasing costs, or profit margins (e.g., "成本多少", "批发价", "利润空间")
-- User wants to find suppliers by product image (e.g., "这个图片能找到货源吗", "帮我找同款", "看图找货", "Amazon这个能在1688找到吗")
-- User shares an Amazon product link (e.g., amazon.com/dp/XXXX, amzn.to/XXXX)
+1. 检查 `~/products/` 是否存在
+   - 不存在 → 从 template/user/ 复制 PROFILE.md、OVERVIEW.md、CBB.md、ROADMAP.md 到 `~/products/`
+   - 引导用户填写 PROFILE.md（可跳过，后续补充）
+2. 检查 PROFILE.md 是否已填写
+   - 未填写 → 提示完善（可跳过）
+3. 读取 `~/products/PROFILE.md` + `~/products/OVERVIEW.md` + `~/products/CBB.md` + `~/products/ROADMAP.md`
+4. 判断用户意图：
+   - 指定了具体产品 → 匹配已有项目（按名称/关键词）或新建
+   - 未指定 → 展示当前项目状态，询问继续/新建
+   - 要求跨项目分析 → 加载 [cross-project.md](references/cross-project.md)
+5. 进入项目后读取 `~/products/{slug}/RESEARCH.md`
+6. 根据当前阶段加载对应 reference 文件
 
-## Interaction Style: Conversational → Report
+## 快速研究模式
 
-**Default approach: Interactive & Consultative**
-- Start with quick scans, share findings, ask clarifying questions
-- Iterate based on user feedback and interests
-- **Proactively suggest report generation** after sufficient data gathering
-- Don't assume what user wants - ask and discuss first
+当用户只需要快速了解一个产品/市场（而非启动完整 IPD 流程）时，可使用快速模式：
 
-**When to suggest full report:**
-- After sufficient exploration (typically 3+ searches, 3-5 product analyses)
-- User signals readiness: "所以你觉得呢？" "值得做吗？" "总结一下"
-- Clear insights emerged that warrant documentation
-- **Always ask permission first** - never assume user wants a long report
+**触发信号**：用户说"帮我快速看看"、"这个产品怎么样"、"简单分析一下"、贴了一个 Amazon 链接等。
 
-**Exception - Direct report mode:**
-- User explicitly requests: "给我一份XX市场分析报告"
-- In this case, skip conversation and generate report directly
+**快速模式流程**：
+1. 立即执行 `scout search` 或 `scout product`（先拿数据再说）
+2. 分享关键发现（价格区间、竞争强度、销量信号）
+3. 询问用户："要深入研究吗？我可以立项做完整的 IPD 分析。"
+   - 用户说"深入" → 新建项目，进入概念阶段
+   - 用户说"不用" → 对话结束，数据不落盘
 
-## URL 解析 - Amazon 链接处理
+**原则**：
+- 先数据后建议 — 不要在没有数据的情况下给任何建议
+- 快速模式不创建项目、不落盘、不走 Gate
+- 用户随时可以从快速模式升级为正式 IPD 研究
 
-用户贴 Amazon 链接时，**不要用 WebFetch**（会被反爬拦截），提取 ASIN 后用 `scout product`：
+## 市场管理（MM）
 
-| URL 格式 | ASIN 位置 |
-|----------|----------|
-| `amazon.com/dp/XXXXXXXXXX` | `/dp/` 后 10 位 |
-| `amazon.com/gp/product/XXXXXXXXXX` | `/gp/product/` 后 10 位 |
-| `amzn.to/XXXX` (短链) | 用 `curl -sI "https://amzn.to/XXXX"` 从 Location header 获取完整 URL → 提取 ASIN |
-
-```bash
-# 1. 提取 ASIN → 获取产品详情
-scout product B08BHXG144
-
-# 2. 如果用户想了解市场竞争
-scout search "产品关键词" --limit 15
-
-# 3. 如果用户想找供应商
-scout supplier-search "中文关键词"
-```
-
-## Quick Start - First Step
-
-When user asks about product opportunities or market research:
-1. **IMMEDIATELY run `scout search`** with 1-2 relevant keywords
-2. Get real Amazon market data before providing any advice
-3. **Share initial findings conversationally** - don't overwhelm with full report
-4. **Ask clarifying questions** based on what you found
-5. Iterate and deepen analysis based on user responses
-
-Example: If user asks "我想开店卖钛合金杯子", your FIRST actions should be:
-```bash
-scout search "titanium cup" --limit 15
-scout search "titanium mug" --limit 10
-```
-
-Then share findings and ask:
-- "我发现市场价格区间是 $15-90，你的目标价位是多少？"
-- "看起来高端保温款竞争少，要不要深入看看？"
+MM 是产品开发的前置流程，负责"做正确的事"。产出是 `~/products/ROADMAP.md`。
 
-**Critical First Steps:**
-- ✅ Always get data before giving advice - run searches immediately
-- ✅ Share findings conversationally - don't dump raw data
-- ✅ Ask clarifying questions - understand user's goals before deep diving
+详细指引见 [market-management.md](references/market-management.md)。
 
-## Available Commands
+**核心流程：** 确定扫描范围 → 多品类快速扫描 → SPAN 快速打分 → 优先级排序 → 更新路标 → P1 立项
 
-### 1. Search Products: `scout search`
+**与概念阶段的关系：** MM 是宏观选择（做哪个品类），概念是微观验证（具体产品行不行）。
 
-Search for products on Amazon to analyze market opportunities.
+## 项目管理
 
-**Syntax:**
-```bash
-scout search "QUERY" --limit NUMBER
-```
-
-**Parameters:**
-- `QUERY`: Product keywords (e.g., "wireless mouse", "titanium water bottle")
-- `--limit`: Number of results (1-50, default: 10)
-- `--domain`: Amazon domain (default: amazon.com)
+### 新建项目
 
-**Returns:**
-- Product list with ASIN, title, price, rating, reviews, recent sales
-- Market overview data for competitive analysis
+1. 确定 slug（英文 kebab-case，如 titanium-tumbler）
+2. 从 template/product/ 复制完整目录到 `~/products/{slug}/`
+3. 在 RESEARCH.md 中填入：产品名称、创建日期、研究目标
+4. 在 OVERVIEW.md 中添加一行到"活跃项目"表
+5. 检查 CBB.md：是否有可复用的能力模块？如有，告知用户并纳入 SPAN 评分考量
 
-**Key metrics to analyze:**
-- Price range and distribution
-- Recent sales ("10K+ bought in past month" = high demand)
-- Ratings_total (review count indicates market maturity)
-- Average rating (competitive quality baseline)
+### 切换项目
 
-### 2. Get Product Details: `scout product`
+读取 OVERVIEW.md → 列出活跃项目 → 用户选择 → 加载对应 RESEARCH.md
 
-Get comprehensive details about a specific product by ASIN.
+### 阶段回退
 
-**Syntax:**
-```bash
-scout product ASIN
-```
+如果用户要求回到前一阶段（如"我想重新评估竞品"）：
+1. 更新 RESEARCH.md 当前阶段（回退）
+2. 保留已有数据不删除
+3. 将对应阶段的 checklist 中需要重做的项取消勾选
+4. 加载对应阶段的 reference 重新执行
 
-**Parameters:**
-- `ASIN`: 10-character Amazon product ID (e.g., B01GJOMWVA)
-- `--domain`: Amazon domain (default: amazon.com)
-
-**Returns:**
-- Complete product data: pricing, sales, reviews, specifications
-- Rating breakdown, BSR, listing quality indicators
-- Feature bullets, images, description, categories
-
-**Key data to extract:**
-- **BSR (Best Seller Rank)** - Sales volume indicator (lower = better)
-  - BSR < 1,000 = very high sales
-  - BSR 1,000-10,000 = good sales
-  - BSR > 50,000 = low sales
-- **Rating breakdown** - Five-star/one-star percentages
-  - 70%+ five-star = excellent satisfaction
-  - 10%+ one-star = quality issues
-- **Top reviews** - User pain points and satisfaction drivers
-- **Feature bullets** - Competitive selling points
-- **Images count** - 7 is standard, fewer = poor optimization
-- **Specifications** - May include BSR in multiple categories
-
-### 3. Get Product Reviews: `scout reviews`
-
-Fetch Amazon product reviews with pagination. Use for deep pain-point analysis beyond the 8-13 top_reviews returned by `scout product`.
-
-**Syntax:**
-```bash
-scout reviews ASIN                              # 默认 3 页 (~30 条)
-scout reviews ASIN --pages 10                   # 最多 10 页 (~100 条)
-scout reviews ASIN --star one_star              # 只看 1 星差评
-scout reviews ASIN --all-stars --pages 5        # 每个星级各 5 页 (~250 条)
-scout reviews ASIN --verified                   # 只看 verified purchase
-scout reviews ASIN --sort helpful               # 按 helpful 排序
-```
+### 并行项目
 
-**Parameters:**
-- `ASIN`: 10-character Amazon product ID
-- `--pages`: Number of pages per request (1-10, default: 3, ~10 reviews/page)
-- `--sort`: `recent` (default) or `helpful`
-- `--star`: Filter by star rating (`one_star` ~ `five_star`)
-- `--all-stars`: Fetch all 5 star ratings in one batch (max ~500 reviews)
-- `--verified`: Only verified purchase reviews
-- `--domain`: Amazon domain code (default: com)
-- `--format`: `json` (default) or `text`
+- 支持同时进行多个项目（OVERVIEW.md 多行活跃）
+- 建议同时进行的概念/计划阶段项目不超过 3 个（避免资源分散）
+- 每次对话聚焦一个项目，切换时明确告知用户
 
-**Returns:**
-- Review list: id, title, body, rating, date, verified, helpful_votes, images
-- Product summary: title, rating, total_ratings, rating_breakdown (percentages)
+### 归档项目
 
-**When to use:**
-- `scout product` gives 8-13 top_reviews — enough for quick scan
-- `scout reviews` gives 30-500 reviews — use for **deep pain-point analysis**, sentiment clustering, and improvement opportunity identification
-- **痛点分析**：`scout reviews ASIN --star one_star --pages 5` 拉差评做聚类
-- **竞品评论对比**：分别拉两个竞品的差评，找差异化机会
+1. 更新 RESEARCH.md 状态 → 已决策(Go) 或 已决策(No-Go)
+2. 更新 OVERVIEW.md：从"活跃项目"移到"已完结"
+3. 提示用户："这次研究积累了什么可复用的能力？"→ 更新 CBB.md
 
-**Cost awareness:** Each page costs ~$0.0075 Apify credits. `--all-stars --pages 10` (~500 reviews) costs ~$0.38.
+## 数据落盘规则
 
-### 4. Search 1688 Suppliers (Keyword): `scout supplier-search`
-
-Search for suppliers on 1688.com using keywords.
-
-**Syntax:**
-```bash
-scout supplier-search "KEYWORD" --limit NUMBER
-```
+### 前提
 
-**Parameters:**
-- `KEYWORD`: Product keywords in Chinese (e.g., "咖啡机", "蓝牙耳机", "钛合金杯子")
-- `--limit`: Number of results (1-100, default: 20)
-- `--format`: Output format - `text` or `json`
+数据只在**有明确关联项目**时自动落盘：
+- 已选定项目 → 自动落盘到对应目录
+- 未选定项目 → 提示："这个搜索结果要保存到某个项目里吗？"
+  - 指定项目 → 落盘
+  - 新建项目 → 初始化后落盘
+  - 不保存 → 仅存在于对话上下文
 
-**Returns:**
-- Supplier list with product info, pricing, MOQ, supplier ratings
-- Price tiers for bulk ordering (e.g., "2~49台: ¥599", "≥100台: ¥429")
-- Supplier details: location, years in business, seller type
-- Tags: shipping policies (退货包运费), payment terms (先采后付), certifications (实力商家)
+### 落盘映射
 
-**Key analysis:**
-- MOQ constraints (minimum order quantity)
-- Supplier type: 生产加工 (manufacturer) vs. 经销批发 (trader)
-- Years in business (8+ years = established)
-- Return rate (lower = better, typical: 30-50%)
+| 命令 | 存储位置 | JSON 文件 | 更新的活文档 |
+|------|---------|----------|------------|
+| `scout search` | market/ | searches.json | MARKET.md |
+| `scout tiktok *` | market/ | tiktok.json | MARKET.md |
+| `scout reddit *` | market/ | reddit.json | MARKET.md |
+| `scout twitter *` | market/ | twitter.json | MARKET.md |
+| `scout instagram *` | market/ | instagram.json | MARKET.md |
+| `scout douyin *` | market/ | douyin.json | MARKET.md |
+| `scout xhs *` | market/ | xhs.json | MARKET.md |
+| `scout shein-search` | market/ | shein.json | MARKET.md |
+| `scout temu-search` | market/ | temu.json | MARKET.md |
+| `scout taobao *` | market/ | taobao.json | MARKET.md |
+| Web Search | market/ | web-research.json | MARKET.md |
+| `scout product` | competitors/ | {ASIN}.json | COMPETITORS.md |
+| `scout reviews` | reviews/ | {ASIN}-reviews.json | PAIN-POINTS.md |
+| `scout keepa product` | trends/ | keepa-data.json | TRENDS.md |
+| `scout supplier-search` | suppliers/ | suppliers.json | SUPPLIERS.md |
+| `scout supplier-search-image` | suppliers/ | suppliers.json | SUPPLIERS.md |
 
-### 5. Search 1688 Suppliers (Image): `scout supplier-search-image`
+### JSON 格式
 
-Search for suppliers on 1688.com using product images - perfect for finding sources for products you see on Amazon, Shopify, or other platforms.
-
-**Syntax:**
-```bash
-scout supplier-search-image "IMAGE_URL" --limit NUMBER
+每个 JSON 文件是数组，每次追加带时间戳的条目：
+```json
+[
+  { "timestamp": "2026-05-05T10:30:00Z", "command": "scout search", "args": {"query": "titanium cup", "limit": 15}, "results": [...] }
+]
 ```
 
-**Parameters:**
-- `IMAGE_URL`: Product image URL (Amazon, Alibaba, or any accessible image URL)
-- `--limit`: Number of results (1-100, default: 20)
-- `--format`: Output format - `text` or `json`
-
-**Returns:** Same as `supplier-search` (supplier list, pricing, MOQ, ratings)
+### 活文档更新策略
 
-**Use cases:**
-- Finding 1688 alternatives for Amazon/Shopify products
-- "找同款" / "看图找货" scenarios
-- Visual products where images are more descriptive than keywords
-- When user provides product image URL
+活文档不是追加原始数据，而是**分析性更新**：
+- 新数据进来后重新审视文档，更新总结和判断
+- 新数据与旧分析矛盾时，更新结论并标注变化原因
+- 保持简洁可读（原始数据的职责在 JSON 中）
 
-**Important notes:**
-- Works with images from any platform (Amazon, Alibaba, direct URLs)
-- Non-Alibaba images are automatically converted for 1688 search
-- If image is inaccessible (404, expired, auth-required), will return helpful error message
-- **Best practice**: Try both image and keyword search for comprehensive results
+### Checklist 自动更新
 
-### 历史数据（Keepa API）
+每次落盘后判断对应 checklist 项是否满足完成标准：
+- 不是"跑过命令=完成"，而是**数据充分性**判断
+- 未完成时主动建议补充数据
+- 全部完成时主动发起 Gate 评审
 
-#### `scout keepa product` — 产品历史数据（核心命令）
+## 阶段路由
 
-```bash
-scout keepa product B09V3KXJPB                    # 默认 90 天统计
-scout keepa product B09V3KXJPB --stats 180         # 180 天统计
-scout keepa product B09V3KXJPB --buybox --rating   # 含 BuyBox 和评分历史
-scout keepa product B09V3KXJPB,B0D4J2QLCR          # 批量查询（逗号分隔，最多100）
-scout keepa product B09V3KXJPB --domain amazon.de  # 指定站点
-```
+根据 RESEARCH.md "当前阶段"加载对应指引：
 
-返回（关键字段）：
-- **stats.current[3]** — 当前 BSR
-- **stats.salesRankDrops30/90** — 30/90 天 BSR 下降次数 ≈ 出单次数
-- **stats.outOfStockPercentage30** — 30 天断货率
-- **csv[0]** — Amazon 自营价格历史
-- **csv[1]** — 第三方新品价格历史
-- **csv[3]** — BSR 排名历史
-- **csv[11]** — 在售卖家数量历史（COUNT_NEW）
-- **csv[16]** — 评分历史
-- **csv[17]** — 评论数历史
+| 阶段 | Reference |
+|------|-----------|
+| 市场管理(MM) | [market-management.md](references/market-management.md) |
+| 概念 | [concept.md](references/concept.md) |
+| 计划 | [planning.md](references/planning.md) |
+| 开发 | [development.md](references/development.md) |
+| 验证 | [qualification.md](references/qualification.md) |
+| 发布 | [launch.md](references/launch.md) |
+| 生命周期 | [lifecycle.md](references/lifecycle.md) |
+| 跨项目 | [cross-project.md](references/cross-project.md) |
 
-价格单位：美分（÷100 得美元）。评分：×10（45 = 4.5 星）。
+**贯穿多阶段的流程：**
+- 需求管理：[requirements.md](references/requirements.md)（计划→开发→验证→生命周期）
+- 分析方法论：[analysis-framework.md](references/analysis-framework.md)
+- 基础指标：[metrics.md](references/metrics.md)
+- 命令详细参考：[commands.md](references/commands.md)
 
-**When to use:** 在 `scout product` 获取实时数据后，用 `scout keepa product` 拉历史数据判断趋势和生命周期。
+## Gate 评审
 
-#### `scout keepa search` — Product Finder（按条件筛选全库）
+**触发：** 当前阶段所有 checklist 项完成。
 
-```bash
-# 找 BSR < 1万、评论 < 500、价格 $20-50 的新机会
-# 注意：currentRange 单位是美分，$20-50 = [2000,5000]
-scout keepa search '{"salesRankRange":[1,10000],"avg90_COUNT_REVIEWS_lte":500,"currentRange":[2000,5000]}'
+**流程：**
+1. 读取 analysis-framework.md 对应 Gate 标准
+2. 逐项回答评审问题，引用已收集数据作为证据
+3. 给出 Go/Kill/Redirect 建议
+4. 等待用户确认
+5. 确认后更新 RESEARCH.md（阶段、决策记录）+ OVERVIEW.md
 
-# 找特定品牌
-scout keepa search '{"brand":"Apple","salesRankRange":[1,50000]}' --per-page 10
+**评审结果格式：**
 ```
+{阶段} Gate 评审结果：
 
-返回：符合条件的 ASIN 列表。selection 支持几百个筛选条件。
+1. {问题} → {Yes/No} — {证据}
+2. ...
 
-#### `scout keepa bestsellers` — 品类热卖榜
-
-```bash
-scout keepa bestsellers 172282                # Electronics 品类
-scout keepa bestsellers 172282 --range 90     # 90 天平均排名
+建议：{Go/Kill/Redirect} — {理由}
+同意进入下一阶段吗？
 ```
 
-返回：品类 top ASIN 列表（根类目最多 10 万个）。先用 `scout keepa category 0` 获取品类 ID。
-
-#### `scout keepa category` — 品类树
-
-```bash
-scout keepa category 0                        # 所有根类目（拿品类 ID）
-scout keepa category 172282                   # Electronics 子类目
-```
+## 报告生成
+
+用户可随时要求生成报告，保存到 `~/products/{slug}/reports/YYYY-MM-DD-{标题}.md`。
+
+报告类型对齐 IPD 交付物：
+- 概念阶段 → Charter（产品立项书）
+- 计划阶段 → Business Case（商业计划书）
+- 开发阶段 → 产品规格书 + 供应商评估报告
+- 验证阶段 → Pre-launch 验证报告
+- 跨项目 → Portfolio 分析报告
+
+**报告建议时机：**
+- 概念阶段完成后（3+ 搜索 + SPAN 定位完成）
+- 计划阶段完成后（$APPEALS + FAN + 供应商数据齐全）
+- 用户主动要求："总结一下"、"值得做吗？"、"所以你觉得呢？"
+
+**建议话术：**
+> "我已经分析了 X 组搜索和 Y 个竞品，有一些发现。要不要我整理成一份 {Charter/Business Case}？"
+
+如果用户拒绝，尊重决策："好的，有需要随时告诉我。"后续发现新数据后可再次建议。
+
+**Charter 报告必含章节：**
+- 市场概况（规模、增长、价格区间）
+- SPAN 定位（市场吸引力 + 竞争地位评分）
+- 竞争格局（头部竞品、品牌集中度）
+- 初步利润估算
+- 机会与风险
+- 建议（Go/Kill/Redirect）
+
+**Business Case 报告必含章节：**
+- $APPEALS 竞品对比分析
+- 用户痛点与差异化策略
+- 历史趋势分析（Keepa 数据）
+- FAN 财务模型（含场景分析）
+- 供应商评估
+- 风险清单与应对
+- 进入策略建议
 
-#### `scout keepa seller` — 卖家画像
+## 命令速查
 
-```bash
-scout keepa seller ATVPDKIKX0DER              # Amazon.com 自己
-scout keepa seller A2R2RITDJNW1Q6 --storefront # 含店铺全部 ASIN
-```
+### Amazon 核心
 
-返回：卖家名称、评分、店铺 ASIN 总数。
+| 命令 | 用途 | 阶段 |
+|------|------|------|
+| `scout search "关键词" --limit N` | Amazon 关键词搜索 | 概念 |
+| `scout product ASIN` | 产品详情 | 计划 |
+| `scout reviews ASIN [--star one_star] [--pages N] [--all-stars] [--verified] [--sort helpful]` | 评论分析 | 计划 |
 
-#### `scout keepa deals` — 降价商品监控
+### Keepa 历史数据
 
-```bash
-scout keepa deals                             # 默认 BuyBox 降价
-scout keepa deals --category 172282           # Electronics 品类降价
-scout keepa deals --title "wireless earbuds"  # 按标题搜索
-```
+| 命令 | 用途 | 阶段 |
+|------|------|------|
+| `scout keepa product ASIN1,ASIN2 --stats 180` | 产品历史数据 | 计划 |
+| `scout keepa search '{...}'` | Product Finder 条件筛选 | 概念/计划 |
+| `scout keepa bestsellers ID` | 品类热卖榜 | 概念 |
+| `scout keepa category ID` | 品类树（获取品类 ID） | 概念 |
+| `scout keepa seller ID [--storefront]` | 卖家画像 | 计划 |
+| `scout keepa deals [--category ID] [--title "关键词"]` | 降价商品监控 | 概念 |
+| `scout keepa graph ASIN -o chart.png` | 价格走势图 | 计划 |
+| `scout keepa tokens` | API 余额查询 | - |
 
-返回：最近降价的商品列表（ASIN、标题、当前价、降幅）。
+### 社交媒体趋势
 
-#### `scout keepa graph` — 价格走势图
+| 命令 | 用途 | 阶段 |
+|------|------|------|
+| `scout tiktok search-videos "关键词"` | TikTok 视频搜索 | 概念 |
+| `scout tiktok shop-search "关键词"` | TikTok Shop 商品搜索 | 概念 |
+| `scout tiktok trending` | TikTok 热门趋势 | 概念 |
+| `scout tiktok creators` | 热门达人发现 | 概念 |
+| `scout tiktok creator-products <username>` | 达人带货商品 | 概念 |
+| `scout reddit trends "关键词"` | Reddit 趋势预判 | 概念 |
+| `scout reddit search "关键词"` | Reddit 帖子搜索 | 概念 |
+| `scout reddit ads "关键词"` | Reddit 广告竞品情报 | 计划 |
+| `scout twitter trends "关键词"` | Twitter 趋势预判 | 概念 |
+| `scout twitter search "关键词"` | Twitter 帖子搜索 | 概念 |
+| `scout instagram reels "关键词"` | Instagram Reels 搜索 | 概念 |
 
-```bash
-scout keepa graph B09V3KXJPB -o price-chart.png
-```
+### 中国平台（趋势发现 + 供应链）
 
-返回：Keepa 价格走势 PNG 图片。
+| 命令 | 用途 | 阶段 |
+|------|------|------|
+| `scout douyin search-videos "关键词"` | 抖音视频搜索 | 概念 |
+| `scout douyin hot-search` | 抖音热搜榜 | 概念 |
+| `scout xhs search-notes "关键词"` | 小红书笔记搜索 | 概念 |
+| `scout taobao search "关键词"` | 淘宝/天猫搜索 | 计划/开发 |
+| `scout shein-search "关键词" --limit N` | Shein 商品搜索 | 概念 |
+| `scout temu-search "关键词" --limit 20` | Temu 商品搜索（最低 20 条） | 概念 |
 
-#### `scout keepa tokens` — API 余额
+### 供应商
 
-```bash
-scout keepa tokens
-```
+| 命令 | 用途 | 阶段 |
+|------|------|------|
+| `scout supplier-search "关键词" --limit N` | 1688 供应商搜索（关键词） | 计划/开发 |
+| `scout supplier-search-image "URL" --limit N` | 1688 供应商搜索（图片） | 计划/开发 |
 
-## Research Workflow
-
-### Interactive Research Flow (Recommended):
-
-**Phase 1: Initial Discovery & Discussion**
-1. **Quick Market Scan** → Run 1-2 searches with key terms
-2. **Share Initial Findings** → Present key metrics (price range, competition level, demand signals)
-3. **Discuss with User** → Ask clarifying questions about target price, market segment, priorities
-
-**Phase 2: Deep Dive & Refinement**
-4. **Targeted Analysis** → Based on user feedback, run `scout product` on relevant ASINs
-5. **Deep Review Analysis** → Run `scout reviews ASIN --star one_star --pages 5` to extract pain points, then `scout reviews ASIN --sort helpful --pages 3` to see most impactful reviews
-6. **Historical Trend Analysis** → Run `scout keepa product ASIN1,ASIN2,ASIN3 --stats 180` to get historical data
-7. **Extract Insights** → Combine realtime + historical + review data:
-   - BSR trend → 增长期/成熟期/衰退期？
-   - `salesRankDrops30/90` → 估算月销量
-   - 价格历史 → 利润空间稳定吗？有价格战吗？
-   - 卖家数量变化 → 竞争在加剧吗？
-   - 差评聚类 → 用户核心痛点是什么？能改进吗？
-   - 好评亮点 → 用户最看重什么功能？
-8. **Iterate & Explore** → User may request different keywords, specific competitor analysis, or alternative product categories
-
-**Phase 2.5: Supplier Sourcing (Optional but Recommended)**
-9. **Trigger**: User shows interest in costs/sourcing, or after market validation
-   - "成本大概多少？" "批发价怎么样？" "利润空间大吗？"
-   - "哪里进货？" "供应商怎么找？"
-   - "这个图片能找到货源吗？" "Amazon这个能在1688找到吗？"
-
-10. **Choose search method**:
-   - **With image**: `scout supplier-search-image "https://..."` ← More accurate for visual products
-   - **With keyword**: `scout supplier-search "产品关键词"`
-   - **Best practice**: Try both and compare results
-
-11. **Share Findings**:
-    - Wholesale price range (e.g., ¥429-599)
-    - MOQ (minimum order quantity)
-    - Profit margin calculation: Amazon price ($60-80) - 1688 cost (¥429 ≈ $60) - shipping ($10-15)
-    - Supplier quality indicators (years in business, certifications)
-
-12. **Ask**: "要不要我详细分析几个供应商？" or proceed to report
-
-**Phase 3: Report Generation (Proactive Suggestion)**
-13. **Gauge Completion** → After sufficient data, suggest: "要不要我整理成一份完整的市场分析报告？"
-14. **Generate Report** → Create comprehensive markdown report with all findings
-15. **Save & Iterate** → Offer to save report and refine based on feedback
+### 费用提醒
 
----
+- `scout reviews` 每页约 $0.0075 Apify credits，`--all-stars --pages 10`（~500 条）约 $0.38
+- `scout keepa product` 每个 ASIN 消耗 1 token，批量查询注意余额（`scout keepa tokens`）
 
-### Alternative: Quick Research Flow
+## 跨平台价格验证
 
-When user explicitly requests a report upfront:
-1. Run 3-4 diverse keyword searches
-2. Analyze top 3-5 products with `scout product`
-3. Deep review analysis: `scout reviews ASIN --star one_star --pages 5` on top competitors
-4. Pull historical trends with `scout keepa product` (batch ASINs)
-5. Search 1688 suppliers (image + keyword)
-6. Generate comprehensive report directly
+当用户需要验证利润空间时，可用三角定价：
 
-### Multi-Keyword Research Strategy
-
-**Example: Researching titanium cups**
-```bash
-scout search "titanium cup" --limit 15
-scout search "titanium mug" --limit 15
-scout search "titanium tumbler" --limit 10
 ```
-
-**Why multiple keywords:**
-- Different keywords reveal different market segments
-- Find niche opportunities
-- Cross-validate market size
-- Discover related products
-
-## Usage Examples
-
-### Example 1: Interactive Research (Keyword-based)
-
-**User**: "我想开个店卖钛合金杯子，你觉得合适吗"
-
-**Flow:**
-1. Run `scout search "titanium cup"` + `scout search "titanium mug"`
-2. Share: "市场有50+竞品，价格$15-90，主要在$20-30。头部产品月销约200件。两个方向：低价位($15-25)竞争激烈，高端保温款($60-90)产品很少。你更倾向哪个？"
-3. User: "中高端的，质量好的"
-4. Run `scout product` on 3 representative ASINs (B0CTKWJDXX, B0DNCMN3NX, B083NLR6BF)
-5. Share: "TOAKS中端爆款BSR#530，月销250件，87%五星。用户最爱：超轻、品质好、无金属味。主要抱怨：散热快（无保温）。KOYASU高端保温$89.99，评论少但4.8分。保温款市场几乎空白！"
-6. Run `scout keepa product B0CTKWJDXX,B0DNCMN3NX,B083NLR6BF --stats 180` 拉历史数据
-7. Share: "Keepa 历史数据显示：TOAKS 的 BSR 过去 6 个月持续走低（从#2000 降到#530），说明市场在增长。卖家数量从 3 个增到 8 个，竞争在加剧。价格近 6 个月稳定在 $25-28，没有价格战。保温款 KOYASU 的 BSR 波动大但整体下降趋势，说明刚起步有潜力。"
-8. User: "好的，你看看"
-9. Run `scout search "titanium tumbler"`
-10. Share: "titanium tumbler竞品只5-6个，$60-110。现在查供应商成本？"
-11. Run `scout supplier-search "钛合金保温杯"`
-12. Share: "批发价区间：¥180-450（约$25-65），起订量多数50-100个。头部供应商：8年工厂，¥280批发价。**利润分析**：Amazon售价$70-90，1688成本¥280（约$40），运费+关税约$15，总成本约$55，**毛利率25-40%**。"
-13. Suggest report generation
-
-### Example 2: Image-Based Supplier Search
-
-**User**: "我在Amazon看到这个蓝牙耳机很火，帮我找1688供应商 https://m.media-amazon.com/images/..."
-
-**Flow:**
-```bash
-scout supplier-search-image "https://m.media-amazon.com/images/..." --limit 20
+Shein/Temu 低价（$X）vs Amazon 中高价（$Y）vs 1688 成本（¥Z）
 ```
 
-**Response**: "通过图片搜索找到15个供应商：
+- `scout shein-search` / `scout temu-search` → 看同品类低价竞争天花板
+- `scout search` → Amazon 实际售价
+- `scout supplier-search` → 1688 成本
 
-**TOP 3 推荐：**
-1. 深圳某电子厂（8年工厂）
-   - 批发价：¥45-68 | Amazon售价：$89.99
-   - 起订量：50件 | 评分：4.8★
-   - **利润空间：~40-50%**
+如果 Amazon 价格显著高于 Shein/Temu，说明有品牌/品质溢价空间。
 
-2. 东莞某科技（5年工厂）
-   - 批发价：¥38-55 | 起订量：100件
-   - 标签：退货包运费、7天包换
+## URL 解析
 
-3. [...]
+用户贴 Amazon 链接时，提取 ASIN 后用 `scout product`：
 
-要详细对比这几个供应商吗？"
-
-### Example 3: Competitor Analysis
+| URL 格式 | ASIN 位置 |
+|----------|----------|
+| `amazon.com/dp/XXXXXXXXXX` | `/dp/` 后 10 位 |
+| `amazon.com/gp/product/XXXXXXXXXX` | `/gp/product/` 后 10 位 |
+| `amzn.to/XXXX` (短链) | `curl -sI` 获取 Location → 提取 ASIN |
 
-**User**: "帮我分析这个产品 B0788F3R8X"
+**不要用 WebFetch 直接抓 Amazon 页面**（会被反爬拦截）。
 
-**Action:**
-```bash
-scout product B0788F3R8X
-```
+## KB 集成（可选）
 
-**Analysis Checklist:**
-- ✅ **BSR & Market Position**
-  - Check BSR in specifications → estimate sales volume
-  - Compare with category averages
-- ✅ **Customer Satisfaction**
-  - Rating breakdown (five-star %, one-star %)
-  - Total reviews count (market maturity indicator)
-  - Review trends over time
-- ✅ **Listing Quality**
-  - Images count (7 is standard, fewer = poor optimization)
-  - Feature bullets count and quality
-  - Product description completeness
-  - A+ content presence
-- ✅ **User Feedback Deep-Dive**
-  - Quick scan: `scout product` top_reviews (8-13 条精选)
-  - Deep dive: `scout reviews ASIN --star one_star --pages 5` (差评痛点聚类)
-  - Top 3 positive mentions and top 3 complaints
-  - Improvement opportunities and common feature requests
-- ✅ **Competitive Advantages**
-  - Unique selling points in feature_bullets
-  - Price positioning vs. competitors
-  - Brand strength and trust signals
-  - Differentiation factors
-
-## Analysis Framework
-
-### Market Viability Quick Reference
-
-| 指标 | 优秀市场 | 正常市场 | 风险市场 |
-|------|---------|---------|---------|
-| 竞品数量 | 10-50 | 5-10 或 50-100 | <5 或 >100 |
-| 头部评论数 | 100-1000 | 50-100 或 1K-5K | <50 或 >5K |
-| 价格区间 | 宽（差异化） | 中等 | 窄（价格战） |
-| BSR范围 | 1K-10K | 10K-50K | >50K |
-| 进入难度 | 适中 | 需差异化 | 很难或需求不明 |
-
-### 选品五要素（Keepa 历史数据驱动）
-
-| 要素 | 数据来源 | 怎么判断 |
-|------|---------|---------|
-| **市场体量** | `salesRankDrops30/90` + BSR | drops 多 = 出单多 |
-| **垄断程度** | `csv[11]` 卖家数量 + BuyBox | 卖家少且稳定 = 垄断 |
-| **历史趋势** | `csv[3]` BSR 曲线 | 持续走低 = 增长期 |
-| **所处阶段** | BSR 曲线形态 + 评论增速 | 增长/成熟/衰退 |
-| **新品方向** | Product Finder 筛选低竞争品 | 评论少 + BSR 好 = 机会 |
-
-**产品生命周期判断：**
-- **增长期**：BSR 持续走低，评论数快速增长，卖家数量开始增加
-- **成熟期**：BSR 平稳波动，评论数增速放缓，卖家数量稳定
-- **衰退期**：BSR 持续走高，新评论减少，卖家数量下降或价格战
-
-### Key Metrics
-
-**BSR (Best Seller Rank):**
-- <1K = 月销500+件 | 1K-10K = 100-500件 | 10K-50K = 20-100件 | >50K = <20件
-
-**Rating Breakdown:**
-- 70%+ five-star = 优秀 | 60-70% = 正常 | <60% = 质量问题 | 10%+ one-star = 严重问题
-
-**Market Maturity:**
-- ratings_total >1000 = 成熟 | 100-1000 = 发展中 | <100 = 新兴/小众
-
-**Demand Signals:**
-
-High Demand:
-- ✅ "10K+ bought in past month"
-- ✅ 多个产品 ratings_total >500
-- ✅ BSR <10K
-- ✅ 搜索结果超过 30 个相关产品
-
-Low Demand:
-- ⚠️ 少于 10 个搜索结果
-- ⚠️ 头部产品 ratings_total < 50
-- ⚠️ BSR > 100,000
-- ⚠️ 没有 "bought in past month" 标签
-
-**Entry Difficulty Assessment:**
-
-| 维度 | 容易进入 | 中等难度 | 困难进入 |
-|------|---------|---------|---------|
-| 头部产品评论数 | <200 | 200-2000 | >2000 |
-| 品牌集中度 | 无知名品牌 | 少数品牌 | 大品牌垄断 |
-| 价格竞争 | 差异化定价 | 价格区间宽 | 价格战 |
-| 评分分布 | <4.5 平均分 | 4.5-4.7 | >4.7（难超越） |
-
-### Report Generation
-
-**When to suggest:**
-- 3+ searches + 3-5 product analyses completed
-- User asks: "所以你觉得呢？" "值得做吗？" "总结一下"
-- Clear opportunity/risk identified that should be documented
-
-**How to suggest (use this natural template):**
-```
-"我已经分析了 X 个搜索和 Y 个竞品，发现了一些有意思的模式。
+如果 `~/kb/` 存在且有相关知识库：
+- 分析阶段可查询已有实体页、综述页辅助判断
+- 避免重复研究已知信息
 
-核心发现：
-- [1-2 句话总结主要发现]
-- [机会或风险点]
+报告生成后可建议用户 ingest 到 KB：
+- "这份报告要收录到知识库吗？"
+- 用户同意 → 触发 ingesting-sources 流程
 
-要不要我把这些整理成一份完整的市场分析报告？可以包括：
-- 市场规模和竞争格局
-- 头部产品深度分析
-- 差异化机会点
-- 进入策略建议
-- 财务预测（如果你需要的话）
+**不自动创建 KB。** 当积累 3+ 个完成的研究项目后，可主动建议创建产品研究知识库。
 
-报告会保存为 markdown 文件，方便你后续参考和分享。"
-```
+## 交互风格
 
-**If user declines:**
-- Respect decision: "好的，有需要随时告诉我"
-- Continue exploration or answer follow-up questions
-- Offer report again later if more data gathered
-
-**Report must include:**
-- Executive Summary（核心结论前置：适合进入？风险是什么？）
-- Market Analysis（基于搜索数据的市场概况）
-- Historical Trend Analysis（基于 Keepa 数据的趋势分析：BSR 走势、价格稳定性、卖家数量变化、生命周期阶段判断）
-- Competitor Deep-Dive（基于product details的竞品分析：BSR, rating breakdown, top reviews insights）
-- Opportunity Assessment（SWOT 或机会/挑战分析，结合五要素框架）
-- Entry Strategy（产品定位、定价、差异化策略）
-- Supplier Analysis (if Phase 2.5 completed)（1688供应商、成本、利润空间）
-
-**Report naming:** `{产品类型}市场分析报告.md`
-
-## Cross-Skill Integration
-
-**TikTok/Instagram → Scout → Supplier 完整链路：**
-
-1. **Discover** (TikTok/Instagram) → Find trending products
-2. **Validate** (Scout Amazon) → Verify market demand
-   ```bash
-   scout search "product name" --limit 15
-   scout product <top_asin>
-   ```
-3. **Source** (Scout 1688) → Find suppliers and cost
-   ```bash
-   # Method A: Image search (recommended for visual match)
-   scout supplier-search-image "https://amazon-image-url"
-
-   # Method B: Keyword search
-   scout supplier-search "产品关键词"
-
-   # Best: Try both
-   ```
-4. **Decide** →综合分析三者数据，都通过→值得做
-
-**Shein → Scout → Supplier 价格验证链路：**
-
-1. **Discover** (Shein) → Find low-price trending products
-   ```bash
-   scout shein-search "product keyword" --limit 20
-   ```
-2. **Validate** (Scout Amazon) → Compare pricing and demand in broader market
-   ```bash
-   scout search "product name" --limit 15
-   scout product <top_asin>
-   ```
-3. **Source** (Scout 1688) → Find suppliers and calculate margins
-   ```bash
-   scout supplier-search "产品关键词"
-   ```
-4. **Analyze** → Shein 低价（$X） vs Amazon 中高价（$Y） vs 1688 成本（¥Z）→ 找到最佳销售渠道和利润空间
-
-**Proactive suggestion after cross-skill analysis:**
-"我已经分析了TikTok热度、Amazon市场需求、Shein价格定位、1688供应商成本。要不要生成一份完整的产品机会分析报告？"
+- 对话式，先数据后建议
+- 每次操作后分享关键发现，不堆砌原始数据
+- 根据阶段主动建议下一步动作
+- Gate 评审时给出明确建议但尊重用户决策
+- 参考 PROFILE.md 过滤不匹配的产品/方向
+- 数据不足时主动建议补充，不强行给结论