@optima-chat/optima-agent 0.9.29 → 0.9.31

package/.claude/skills/gen/SKILL.md

@@ -305,7 +305,7 @@ gen task retry <task_id>          # 重试失败的任务
 |---|---|---|
 | `UPSTREAM_MAINTENANCE` | **不立即重试**。告知用户服务维护中，建议 5-10 分钟后再试 | "图片生成服务正在维护，建议 5-10 分钟后我再帮您试一次" |
 | `CONTENT_POLICY_VIOLATION` | **改写 prompt** 去掉敏感/违规元素，自动重试**最多 1 次**。仍失败再交给用户 | "您的描述触发了内容审核，我换个说法重试：……" |
-| `UPSTREAM_TIMEOUT` | 立即重试 1 次（静默） | （重试成功就别提；连续失败再说） |
+| `UPSTREAM_TIMEOUT` | 立即用链中**下一个**模型重试 1 次（链：`nano-banana-fast` → `nano-banana-pro` → `flux-kontext-max`）。两次都失败 → 告知用户，**禁止用 Python/本地库 fallback**（见反面示例最后一条） | "图片编辑服务暂时不可用，请稍后再试" |
 | `UPSTREAM_RATE_LIMITED` | 等 30 秒后重试 1 次 | "请求频率过高，稍等几十秒再试" |
 | `UPSTREAM_NETWORK` | 立即重试 1 次（静默） | （同 timeout） |
 | `PROVIDER_INSUFFICIENT_CREDITS` | **不重试**。明确告诉用户问题不在他、不在他的余额 | "生成服务后端额度不足（与您账户余额无关），已记录" |
@@ -319,9 +319,18 @@ gen task retry <task_id>          # 重试失败的任务
 4. `success: false`（CLI 本身报错）直接报给用户，不重试
 5. 没有 `error_code` 字段的旧版响应：当作 `UPSTREAM_UNKNOWN` 处理
 
+**注**：上面 `UPSTREAM_TIMEOUT` 表格里的 fallback 链顺序（fast → pro → flux-kontext-max）基于经验判断（pro 通常更稳定/质量更高，flux-kontext-max 是不同模型家族的兜底），不是数据驱动结论。待真实 P95/P99 数据回灌后再调整。
+
 ### 反面示例（不要这样做）
 
 ❌ 把 `"维护中"` 三个字直接砸给用户
 ❌ 任何失败都自动 retry 三五次造成账单浪费
 ❌ `CONTENT_POLICY_VIOLATION` 时换汤不换药地原 prompt 重试
 ❌ `PROVIDER_INSUFFICIENT_CREDITS` 时让用户去充值（这跟用户余额无关）
+❌ **任何 `gen` 命令失败后，在 sandbox 里 `pip install` 重 ML 推理库（rembg / onnxruntime / torch / segmentation-models 等）做 fallback** —— 纯像素操作（PIL / cv2 的 crop / paste / resize / 简单 alpha 通道处理）不在此列。真实事故：grsai 超时后 LLM 自己装 rembg → 内存不足被 kill → 反复重试 → 用户等 20 分钟才出图。失败必须**诚实告知用户**，不要在 sandbox 里"自己想办法"。
+
+### 正面示例（这样做对）
+
+✅ `nano-banana-fast` 超时 → 切 `-m nano-banana-pro` 重试 1 次（按 `UPSTREAM_TIMEOUT` 行的处理）
+✅ 两次都失败 → "图片编辑服务暂时不可用，请稍后再试" + 不再尝试，不写代码、不装包
+✅ 简单几何操作（crop / resize / paste / 拼图）→ 用 Python + PIL，不算 fallback（这本来就不需要 AI）

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

@@ -305,6 +305,35 @@ scout search "open ear earbuds" --limit 15 --format json > /tmp/scout-result.jso
 | `scout supplier-search "关键词" --limit N` | 1688 供应商搜索（关键词） | 计划/开发 |
 | `scout supplier-search-image "URL" --limit N` | 1688 供应商搜索（图片） | 计划/开发 |
 
+### 卖家精灵（关键词 + 广告 + 市场分析）
+
+| 命令 | 用途 | 阶段 |
+|------|------|------|
+| `scout sp keywords <ASIN>` | ASIN 流量关键词反查（含 PPC 竞价、自然/广告排名） | 计划 |
+| `scout sp keywords-mine <keyword>` | 关键词挖掘（搜索量/竞价/转化率/供需比） | 概念/计划 |
+| `scout sp keywords-order <ASIN>` | 出单关键词反查（转化类型：优质/平稳/流失/无效） | 计划 |
+| `scout sp keywords-research <keyword>` | 关键词市场分析（含品牌/ABA 数据） | 概念 |
+| `scout sp keywords-trends <keyword>` | 关键词历史趋势（2017-至今月度搜索量） | 概念/计划 |
+| `scout sp traffic-stats <ASIN>` | 流量关键词概览 | 计划 |
+| `scout sp traffic-source <ASIN>` | 流量来源结构（自然/广告/关联） | 计划 |
+| `scout sp traffic-listing <ASIN>` | 免费/付费流量分布 | 计划 |
+| `scout sp traffic-related <ASIN>` | 关联商品列表 | 计划 |
+| `scout sp traffic-extend <ASIN>` | 批量关键词拓展 | 计划 |
+| `scout sp predict <ASIN>` | 销量预测（14 个月） | 计划 |
+| `scout sp competitors <ASIN>` | 竞品查询（含销量/销额/利润） | 计划 |
+| `scout sp coupon <ASIN>` | 优惠趋势 | 计划 |
+| `scout sp category <keyword>` | 类目树搜索（支持关键词） | 概念 |
+| `scout sp market <nodeIdPath>` | 类目市场分析（规模/利润/FBA 占比） | 概念 |
+| `scout sp brands <nodeIdPath>` | 品牌集中度 | 概念/计划 |
+| `scout sp sellers <nodeIdPath>` | 卖家集中度 | 概念 |
+| `scout sp demand <nodeIdPath>` | 需求趋势 | 概念 |
+| `scout sp prices <nodeIdPath>` | 价格分布 | 概念 |
+| `scout sp google-trend <keyword>` | 谷歌趋势 | 概念 |
+| `scout sp aba-weekly <keyword>` | ABA 周数据 | 计划 |
+| `scout sp aba-monthly <keyword>` | ABA 月数据 | 计划 |
+
+注：market 类命令的 `<nodeIdPath>` 先通过 `scout sp category <关键词>` 查到。
+
 ### 费用提醒
 
 - `scout reviews` 每页约 $0.0075 Apify credits，`--all-stars --pages 10`（~500 条）约 $0.38

package/.claude/skills/scout/references/analysis-framework.md

@@ -15,7 +15,7 @@ SPAN 是一个 2×2 矩阵工具，用于判断一个商机是否值得投入。
 
 | 维度 | 权重 | 数据来源 | 评分标准 |
 |------|------|----------|----------|
-| 市场规模 | 30% | 月搜索量 + BSR drops 估算月销量 | 5=月销>5000, 4=>1000, 3=>300, 2=>100, 1=<100 |
+| 市场规模 | 30% | 月搜索量 + BSR drops 估算月销量；推荐 `scout sp keywords-mine` 获取精确搜索量 | 5=月销>5000, 4=>1000, 3=>300, 2=>100, 1=<100 |
 | 增长趋势 | 25% | Keepa BSR 6个月趋势 | 5=快速增长(>30%), 4=稳步增长(10-30%), 3=平稳, 2=缓慢下降, 1=快速萎缩 |
 | 利润潜力 | 25% | 售价 - 估算成本（含FBA+头程+关税） | 5=毛利率>50%, 4=40-50%, 3=30-40%, 2=20-30%, 1=<20%（概念阶段用毛利率；计划阶段有 FAN 数据后可用净利率替代） |
 | 战略价值 | 20% | 品类协同性/复购率/关联销售 | 5=高度协同+高复购, 4=较好协同, 3=一般, 2=协同弱, 1=孤立单品 |
@@ -27,7 +27,7 @@ SPAN 是一个 2×2 矩阵工具，用于判断一个商机是否值得投入。
 | 差异化能力 | 35% | $APPEALS 竞品缺口分析 | 5=明确可实现的差异化, 4=较明确, 3=有空间但不确定, 2=空间小, 1=无差异化空间 |
 | 资金匹配度 | 25% | PROFILE 预算 vs 所需投入 | 5=充裕(>3倍), 4=宽裕(2-3倍), 3=匹配, 2=紧张, 1=不足 |
 | 供应链能力 | 25% | 1688 供应商搜索结果 | 5=多家优质+低MOQ, 4=多家可选, 3=少量可用, 2=选择有限, 1=极少或无 |
-| 进入壁垒 | 15% | 头部评论数/品牌占比/认证要求 | 5=低壁垒(无品牌垄断), 4=较低, 3=中等, 2=较高, 1=极高(强品牌+认证+专利) |
+| 进入壁垒 | 15% | 头部评论数/品牌占比/认证要求；可用 `scout sp brands` 量化品牌集中度 | 5=低壁垒(无品牌垄断), 4=较低, 3=中等, 2=较高, 1=极高(强品牌+认证+专利) |
 
 ### 象限阈值与策略
 
@@ -79,7 +79,7 @@ SPAN 是一个 2×2 矩阵工具，用于判断一个商机是否值得投入。
              - 头程运费（海运/空运分摊）
              - 关税（税率×申报价）
              - FBA 费用（配送费+仓储费）
-             - PPC 广告费（售价×ACoS%）
+             - PPC 广告费（售价×ACoS%；推荐用 `scout sp keywords-mine` 的 bid 数据获取真实竞价替代估算）
              - 退货损耗（售价×退货率×损耗比例）
              - 其他（品牌备案/图片/测评等分摊）
 ```

package/.claude/skills/scout/references/commands.md

@@ -532,3 +532,269 @@ scout shein-search "titanium cup" --limit 20
 ```bash
 scout temu-search "titanium cup" --limit 20
 ```
+
+---
+
+## 15. scout sp keywords
+
+反查 ASIN 的流量关键词（卖家精灵 SellerSprite 数据）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<asin>` | string | 是 | - | 商品 ASIN |
+| `--marketplace` | string | 否 | US | 站点（US/UK/DE/FR/IT/ES/CA/JP） |
+
+### 返回字段
+
+- `keyword` — 关键词
+- `searches` — 月搜索量
+- `bid` — PPC 建议竞价
+- `bidMin` — PPC 最低竞价
+- `bidMax` — PPC 最高竞价
+- `badges` — 流量标签（如 `["naturalSearching", "ads"]` 表示同时有自然和广告流量）
+- `rankPosition` — 自然排名（page + position）
+- `adPosition` — 广告排名（page + position）
+- `purchases` — 月购买量
+- `purchaseRate` — 转化率
+
+### 典型用法
+
+```bash
+# 反查竞品流量关键词
+scout sp keywords B0D2XRXNGY
+
+# 查看竞品在英国站的流量词
+scout sp keywords B0D2XRXNGY --marketplace UK
+```
+
+### 分析要点
+
+- **badges 含 "ads"**：竞品在该关键词投了广告，可统计广告词数量估算广告预算
+- **rankPosition vs adPosition**：对比自然排名和广告排名，判断竞品的流量获取策略
+- **bid/bidMin/bidMax**：真实 PPC 竞价数据，用于 FAN 模型精算广告成本
+
+### 实测数据样例
+
+```
+earbuds: 搜索量 501,168 | 竞价 $2.11 ($1.32-$2.84) | 自然排名 P3#78 | 广告排名 P1#13
+```
+
+---
+
+## 16. scout sp keywords-mine
+
+关键词挖掘——获取关键词的精确搜索量、PPC 竞价、转化率等数据（卖家精灵数据）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<keyword>` | string | 是 | - | 搜索关键词 |
+| `--marketplace` | string | 否 | US | 站点 |
+
+### 返回字段
+
+- `keyword` — 关键词（含衍生词和长尾词）
+- `searches` — 精确月搜索量
+- `purchases` — 月购买量
+- `purchaseRate` — 转化率
+- `bid` — PPC 建议竞价
+- `bidMin` — PPC 最低竞价
+- `bidMax` — PPC 最高竞价
+- `adProducts` — 广告产品数
+- `supplyDemandRatio` — 供需比
+- `monopolyClickRate` — 垄断点击率
+- `avgPrice` — 搜索结果均价
+
+### 典型用法
+
+```bash
+# 挖掘关键词数据
+scout sp keywords-mine "open ear earbuds"
+
+# 验证市场需求
+scout sp keywords-mine "titanium cup"
+```
+
+### 分析要点
+
+- **searches**：精确月搜索量，比 BSR drops 估算更直接，可直接用于 SPAN 市场规模评分
+- **purchases / purchaseRate**：真实购买量和转化率，验证需求是否真实
+- **bid/bidMin/bidMax**：真实 PPC 竞价，用于 FAN 模型替代 ACoS 估算
+- **supplyDemandRatio**：供需比越高表示供给越饱和，低于 1 表示供不应求
+- **monopolyClickRate**：高垄断点击率（>50%）说明头部品牌吃掉大部分流量
+
+### 实测数据样例
+
+```
+airpods: 搜索量 2,883,637 | 竞价 $1.64 | 转化率 2.52% | 广告产品 52 | 供需比 185.75 | 垄断点击率 72.39%
+```
+
+---
+
+## 17. scout sp keywords-order
+
+反查 ASIN 的出单关键词——哪些关键词真正带来了转化（卖家精灵数据）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<asin>` | string | 是 | - | 商品 ASIN |
+| `--reverse-type` | string | 否 | M | 时间维度：`M`=月, `W`=周 |
+| `--date` | string | 否 | 当前月 | 日期：月维度 `yyyyMM`（如 202604），周维度 `yyyyMMdd` |
+| `--marketplace` | string | 否 | US | 站点 |
+
+### 返回字段
+
+- `keyword` — 出单关键词
+- `searches` — 月搜索量
+- `monopolyClickRate` — 垄断点击率
+- `conversionShare` — 转化份额（该关键词贡献的转化占比）
+- `conversionType` — 转化类型（如"优质词"）
+- `searchGrowth` — 搜索量增长率
+
+### 典型用法
+
+```bash
+# 查看竞品当月出单词
+scout sp keywords-order B0D2XRXNGY
+
+# 查看竞品上月出单词
+scout sp keywords-order B0D2XRXNGY --date 202604
+
+# 按周查看
+scout sp keywords-order B0D2XRXNGY --reverse-type W --date 20260420
+```
+
+### 分析要点
+
+- **区分流量词和出单词**：流量词（`scout sp keywords`）不一定带来转化，出单词才是真正的转化路径
+- **conversionShare**：转化份额高的关键词是竞品的核心出单词，值得重点关注
+- **conversionType**：优质词表示关键词质量高，竞争价值大
+
+### 实测数据样例
+
+```
+open ear earbuds: 搜索量 141,637 | 垄断点击率 18.72% | 转化份额 14.14% | 转化类型=优质词
+```
+
+---
+
+## 18. scout sp market
+
+类目市场分析——获取类目级别的市场规模、竞争、盈利等数据（卖家精灵数据）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<nodeIdPath>` | string | 是 | - | 类目路径（如 `172282:24046923011:172541:12097478011`），通过 `scout sp category` 获取 |
+| `--marketplace` | string | 否 | US | 站点 |
+
+### 返回字段
+
+- 类目规模（总销量、总销额）
+- 均价
+- 利润数据
+- FBA 占比
+- 退货率
+- 卖家数量
+- 需求趋势
+
+### 典型用法
+
+```bash
+# 先查类目路径
+scout sp category "Headphones"
+# 再查市场数据
+scout sp market "172282:24046923011:172541:12097478011"
+```
+
+### 分析要点
+
+- 提供类目级宏观视角，适合 SPAN 评分的市场吸引力评估
+- 退货率和 FBA 占比可直接用于 FAN 财务模型
+
+---
+
+## 19. scout sp brands
+
+类目品牌集中度分析——量化品牌垄断程度（卖家精灵数据）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<nodeIdPath>` | string | 是 | - | 类目路径（通过 `scout sp category` 获取） |
+| `--marketplace` | string | 否 | US | 站点 |
+
+### 返回字段
+
+- 品牌名称
+- ASIN 数量
+- 销量份额（%）
+- 销额份额（%）
+- 新品数量
+
+### 典型用法
+
+```bash
+scout sp brands "172282:24046923011:172541:12097478011"
+```
+
+### 分析要点
+
+- **CR3/CR5**：前 3/5 名品牌的合计份额，直接用于 SPAN 竞争地位评分的进入壁垒维度
+- **销量份额 vs 销额份额**：份额差异大说明存在高溢价品牌，可能有品牌溢价空间
+- **新品数量**：头部品牌新品多=品类活跃，新品少=品类成熟
+
+### 实测数据样例
+
+```
+Apple: 3 ASIN, 销量份额 17.67%, 销额份额 35.48%
+HAOYUYAN: 8 ASIN, 销量份额 13.83%（5 个新品）
+Soundcore: 6 ASIN, 排名第 3
+```
+
+---
+
+## 20. scout sp category
+
+关键词类目查询——获取关键词对应的 Amazon 类目树和 nodeIdPath（卖家精灵数据）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<keyword>` | string | 是 | - | 搜索关键词 |
+| `--marketplace` | string | 否 | US | 站点 |
+
+### 返回字段
+
+- 类目树结构
+- `nodeIdPath` — 类目路径（传给 `scout sp market` / `scout sp brands` 使用）
+- 类目名称
+
+### 典型用法
+
+```bash
+# 查询关键词对应的类目
+scout sp category "Headphones"
+scout sp category "titanium cup"
+```
+
+### 使用场景
+
+`scout sp category` 是 `scout sp market` 和 `scout sp brands` 的前置命令。典型工作流：
+
+```bash
+# 1. 查类目路径
+scout sp category "open ear earbuds"
+# 2. 用返回的 nodeIdPath 查市场数据
+scout sp market "172282:24046923011:172541:12097478011"
+# 3. 用同一 nodeIdPath 查品牌集中度
+scout sp brands "172282:24046923011:172541:12097478011"
+```

package/.claude/skills/scout/references/concept.md

@@ -55,6 +55,8 @@
 
 **落盘位置**：`data/searches/{date}-{keyword}.json` → 更新 `INDEX.md` + `market/MARKET.md`
 
+**可选补充**：`scout sp keywords-mine "关键词"` 获取精确月搜索量、PPC 竞价和转化率，比搜索结果中的 "bought in past month" 更精确
+
 **完成标准**：2-3 组关键词搜索覆盖主要同义词
 
 ---
@@ -72,6 +74,7 @@
 - BSR 分布（头部产品 BSR 越低 = 销量越大）
 - salesRankDrops（Keepa 销量掉落次数 ≈ 出单次数）
 - "bought in past month" 具体数值
+- 推荐：`scout sp keywords-mine "关键词"` 的 `searches`（精确月搜索量）和 `purchases`（月购买量）比 BSR drops 估算更直接
 
 **落盘位置**：更新 `market/MARKET.md` 需求验证部分
 
@@ -88,6 +91,7 @@
 - 头部产品评论数（评论数越多 = 护城河越深）
 - 品牌垄断情况（前 10 名是否被 2-3 个品牌占据）
 - 品牌集中度（CR3/CR5）
+- 可选：`scout sp category "关键词"` 查类目 nodeIdPath，然后 `scout sp brands <nodeIdPath>` 获取量化的品牌集中度数据（各品牌 ASIN 数、销量份额、销额份额）
 - 参考 `metrics.md` 竞争指标表
 
 **落盘位置**：更新 `market/MARKET.md` 竞争格局部分
@@ -107,6 +111,10 @@
   - X 轴：竞争地位（1-5 分，含差异化能力、资金匹配度、供应链能力、进入壁垒）
 - 阈值：≥3.5 为"高/强"，<3.5 为"低/弱"
 
+**补充数据来源**：
+- 市场规模维度：可用 `scout sp keywords-mine` 的 searches 精确验证月搜索量，替代 BSR drops 估算
+- 竞争地位维度：可用 `scout sp brands` 的品牌份额数据辅助判断品牌垄断程度
+
 **注意**：概念阶段是初步评估，部分维度可以粗略打分，后续阶段再精确
 
 **落盘位置**：更新 `RESEARCH.md` SPAN 定位 + `market/MARKET.md` SPAN 评分
@@ -124,6 +132,7 @@
 - 1688 参考价（可选命令：`scout supplier-search "中文关键词" --limit 5`）
 - FBA 费估算（按品类/尺寸估算）
 - 粗略毛利 = 售价 - 1688参考价 - FBA费 - 平台佣金（概念阶段只算毛利，计划阶段用 FAN 模型精算净利率）
+- 可选：`scout sp keywords-mine "关键词"` 的 `bid/bidMin/bidMax` 可以估算 PPC 广告成本，使利润估算更准确
 
 **对照**：`PROFILE.md` 中的最低毛利率要求。如果 PROFILE 未填写该阈值，提示用户确认："你的最低可接受毛利率是多少？（默认 50%）"
 

package/.claude/skills/scout/references/planning.md

@@ -32,6 +32,8 @@
 - A+ 页面有无及质量
 - 变体布局（颜色/尺寸/套装）
 
+**推荐补充**：`scout sp keywords <ASIN>` 反查竞品流量关键词（含搜索量、竞价、自然排名、广告排名），了解竞品的流量结构
+
 **落盘位置**：`data/products/{ASIN}.json` → 更新 `INDEX.md` + `competitors/COMPETITORS.md`
 
 **完成标准**：3-5 个竞品有完整数据
@@ -56,6 +58,7 @@
 - 识别权重最高维度（好评高频词 → 用户最在乎什么）
 - 识别集体弱项（差评聚类 → 竞品普遍做不好什么）
 - 差异化公式：用户在乎 × 竞品弱 = 机会
+- 可选：`scout sp keywords <ASIN>` 的 badges 字段可判断竞品是否投了广告（含 "ads" = 有投放），辅助评估竞品的广告投入力度
 
 **落盘位置**：更新 `RESEARCH.md` $APPEALS 评分卡 + `competitors/COMPETITORS.md`
 
@@ -78,6 +81,8 @@
 
 **落盘位置**：`data/reviews/{ASIN}-{star}.json` → 更新 `INDEX.md` + `reviews/PAIN-POINTS.md`
 
+**推荐补充**：`scout sp keywords-order <ASIN>` 反查竞品出单词（哪些关键词真正带来转化），区分流量词和出单词，找到竞品的核心转化路径
+
 **完成标准**：≥30 条差评分析，形成 3+ 个痛点聚类
 
 ### 4. 历史趋势分析
@@ -137,7 +142,8 @@
 - 供应商报价（1688 搜索结果）
 - 运费（头程 + FBA 配送费）
 - FBA 费率（仓储 + 配送）
-- 品类 ACoS（广告成本占比）
+- PPC 广告费：推荐用 `scout sp keywords-mine "关键词"` 的 bid 数据获取真实竞价，替代 ACoS 估算，使 FAN 模型更准确
+- 可选：`scout sp keywords <ASIN>` 可查看竞品在多少关键词投了广告（badges 含 "ads" 的数量），辅助估算广告预算
 - 退货率（品类基准）
 
 **产出**：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/optima-agent",
-  "version": "0.9.29",
+  "version": "0.9.31",
   "description": "基于 Claude Agent SDK 的电商运营 AI 助手",
   "type": "module",
   "main": "dist/src/index.js",