@optima-chat/optima-agent 0.9.28 → 0.9.30

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

@@ -9,6 +9,7 @@ description: "基于 IPD 方法论的产品研究全生命周期工具。在 ~/p
 
 1. 检查 `~/products/` 是否存在
    - 不存在 → 从 template/user/ 复制 PROFILE.md、OVERVIEW.md、CBB.md、ROADMAP.md 到 `~/products/`
+   - 初始化 git 仓库：`cd ~/products && git init && git add -A && git commit -m "init: 初始化产品研究工作区"`
    - **必须询问用户填写 PROFILE.md 的关键字段**（至少：主营市场、目标价位、最低毛利率、最低净利率、单品启动预算）。这些信息直接影响 SPAN 评分和 FAN 判断，缺失会导致分析不准确。用户可以简短回答，agent 帮填入。
 2. 检查 PROFILE.md 是否已填写关键字段
    - 未填写 → 必须询问（不能跳过关键字段：最低毛利率、最低净利率、单品启动预算）
@@ -17,7 +18,7 @@ description: "基于 IPD 方法论的产品研究全生命周期工具。在 ~/p
    - 指定了具体产品 → 匹配已有项目（按名称/关键词）或新建
    - 未指定 → 展示当前项目状态，询问继续/新建
    - 要求跨项目分析 → 加载 [cross-project.md](references/cross-project.md)
-5. 进入项目后读取 `~/products/{slug}/RESEARCH.md`
+5. 进入项目后读取 `~/products/{slug}/RESEARCH.md` + `~/products/{slug}/LOGS.md`（了解上次做到哪了）
 6. 根据当前阶段加载对应 reference 文件
 
 ## 快速研究模式
@@ -47,7 +48,9 @@ description: "基于 IPD 方法论的产品研究全生命周期工具。在 ~/p
 3. 在 RESEARCH.md 中填入：产品名称、创建日期、研究目标
 4. 在 OVERVIEW.md 中添加一行到"活跃项目"表
 5. 在 ROADMAP.md 品类机会池中添加该产品（状态=已立项）
-6. 检查 CBB.md：是否有可复用的能力模块？如有，告知用户并纳入 SPAN 评分考量
+6. 在 LOGS.md 中记录："立项：{产品名称}"
+7. 检查 CBB.md：是否有可复用的能力模块？如有，告知用户并纳入 SPAN 评分考量
+8. `cd ~/products && git add -A && git commit -m "新建项目: {slug}"`
 
 ### 切换项目
 
@@ -118,17 +121,21 @@ description: "基于 IPD 方法论的产品研究全生命周期工具。在 ~/p
 
 ### 落盘执行顺序（必须严格遵守）
 
-每次执行 `scout` 命令后，**必须按以下三步操作**：
+每次执行 `scout` 命令后，**必须按以下五步操作**：
 
 1. **存原始数据** — 将命令完整输出保存到 `data/` 对应文件。使用 `--format json` 获取结构化数据。
 2. **更新 INDEX.md** — 在数据索引中添加/更新该条数据的记录（文件路径、时间、关联关系）。
 3. **更新活文档** — 基于新数据更新对应的 Markdown 活文档。
+4. **追加 LOGS.md** — 在操作日志中记录本次操作（时间 + 做了什么 + 关键发现）。
+5. **git commit** — `cd ~/products && git add -A && git commit -m "{简短描述}"`
 
 **绝对不能**：
 - 只写活文档不存原始数据（数据丢失，无法回溯和重新分析）
 - 只在对话中展示结果不落盘（下次对话无法使用）
 - 把摘要当作原始数据存储（必须是完整返回）
 - 忘记更新 INDEX.md（agent 下次无法发现已有数据）
+- 忘记写 LOGS.md（跨会话上下文会丢失）
+- 忘记 git commit（版本历史会断裂）
 
 **JSON 存储示例**：
 ```bash
@@ -298,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/template/product/LOGS.md

@@ -0,0 +1,4 @@
+# 操作日志
+
+按时间倒序记录每次操作，便于跨会话上下文恢复。新会话开始时先读此文件了解上次进展。
+

package/package.json

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