@optima-chat/optima-agent 0.9.19 → 0.9.21

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

@@ -0,0 +1,267 @@
+# 概念阶段指引
+
+## 目标
+
+验证产品机会是否值得投入更多资源研究。产出 Charter 初版（即完成 RESEARCH.md 概念阶段所有 checklist 项）。
+
+## 何时进入此阶段
+
+- 新建研究项目时自动进入
+- RESEARCH.md 当前阶段 = 概念
+
+## 执行步骤
+
+### 1. 趋势扫描
+
+**目的**：从 Amazon 站外发现热度信号
+
+**具体命令**：
+- `scout tiktok search-videos "关键词"` 或 `scout tiktok shop-search "关键词"`
+- `scout reddit trends "关键词"` 或 `scout reddit search "关键词"`
+- `scout twitter trends "关键词"` 或 `scout twitter search "关键词"`
+- Web Search（补充搜索趋势、新闻报道等）
+
+**分析要点**：
+- 讨论量增长趋势
+- 未满足需求（用户抱怨、求推荐）
+- 竞品投诉（质量差、功能缺失）
+- KOL 推荐（达人带货、测评视频）
+
+**落盘位置**：`market/tiktok.json`、`market/reddit.json`、`market/twitter.json`、`market/web-research.json`
+
+**完成标准**：至少查询 2 个平台，有明确热度信号（或确认无热度）
+
+**跨平台发现→验证链路：**
+- TikTok/Instagram 发现热度 → `scout search` 验证 Amazon 需求 → `scout supplier-search` 确认成本
+- Shein/Temu 发现低价爆品 → `scout search` 对比 Amazon 定价 → 判断品牌溢价空间
+- Reddit/Twitter 发现未满足需求 → `scout search` + `scout reviews` 验证痛点普遍性
+
+---
+
+### 2. Amazon 市场扫描
+
+**目的**：确认站内是否存在市场
+
+**具体命令**：
+- `scout search "主词" --limit 15`
+- 至少 2-3 组关键词覆盖主要同义词
+
+**分析要点**：
+- 产品数量（市场容量）
+- 价格分布（高/中/低档位占比）
+- 评分分布（平均星级、低分占比）
+- "bought in past month" 频率（需求热度）
+- 品牌重复度（垄断程度）
+
+**落盘位置**：`market/searches.json` → 更新 `MARKET.md`
+
+**完成标准**：2-3 组关键词搜索覆盖主要同义词
+
+---
+
+### 3. 需求验证
+
+**目的**：用数据确认有真实购买行为
+
+**具体命令/数据源**：
+- 搜索结果中的 "bought in past month" 数据
+- 可选：`scout keepa product ASIN1,ASIN2 --stats 90`（获取历史销量数据）
+
+**分析要点**：
+- 月搜索量估算
+- BSR 分布（头部产品 BSR 越低 = 销量越大）
+- salesRankDrops（Keepa 销量掉落次数 ≈ 出单次数）
+- "bought in past month" 具体数值
+
+**落盘位置**：更新 `MARKET.md` 需求验证部分
+
+**完成标准**：有具体月销量估算数据
+
+---
+
+### 4. 竞争格局
+
+**目的**：初步判断竞争强度
+
+**分析要点**：
+- 竞品总数
+- 头部产品评论数（评论数越多 = 护城河越深）
+- 品牌垄断情况（前 10 名是否被 2-3 个品牌占据）
+- 品牌集中度（CR3/CR5）
+- 参考 `metrics.md` 竞争指标表
+
+**落盘位置**：更新 `MARKET.md` 竞争格局部分
+
+**完成标准**：知道竞品数量、头部评论数、是否品牌垄断
+
+---
+
+### 5. SPAN 初步定位
+
+**目的**：战略定位评估
+
+**方法**：
+- 参考 `analysis-framework.md` SPAN 评分标准
+- SPAN 是一个 2×2 矩阵工具，两个轴：
+  - Y 轴：市场吸引力（1-5 分，含市场规模、增长趋势、利润潜力、战略价值）
+  - X 轴：竞争地位（1-5 分，含差异化能力、资金匹配度、供应链能力、进入壁垒）
+- 阈值：≥3.5 为"高/强"，<3.5 为"低/弱"
+
+**注意**：概念阶段是初步评估，部分维度可以粗略打分，后续阶段再精确
+
+**落盘位置**：更新 `RESEARCH.md` SPAN 定位 + `MARKET.md` SPAN 评分
+
+**完成标准**：两个维度都有评分
+
+---
+
+### 6. 初步利润估算
+
+**目的**：粗算利润空间，判断是否值得做
+
+**方法**：
+- Amazon 均价（从搜索结果取中位数）
+- 1688 参考价（可选命令：`scout supplier-search "中文关键词" --limit 5`）
+- FBA 费估算（按品类/尺寸估算）
+- 粗略毛利 = 售价 - 1688参考价 - FBA费 - 平台佣金（概念阶段只算毛利，计划阶段用 FAN 模型精算净利率）
+
+**对照**：`PROFILE.md` 中的最低毛利率要求。如果 PROFILE 未填写该阈值，提示用户确认："你的最低可接受毛利率是多少？（默认 50%）"
+
+**落盘位置**：记录在 `RESEARCH.md` 关键发现中
+
+**完成标准**：有售价 + 1688 参考价 + FBA 费估算
+
+---
+
+### 7. IP/合规初筛
+
+**目的**：排除法律风险
+
+**方法**：
+- Web Search 查询：
+  - 商标注册情况（USPTO、WIPO）
+  - 外观专利（Design Patent）
+  - 品类认证要求（FDA、FCC、UL 等）
+  - Amazon 品类限制（Gated Category）
+- 检查是否有已知侵权风险
+
+**落盘位置**：记录在 `RESEARCH.md` 关键发现中（如有风险则同时记入风险清单）
+
+**完成标准**：确认无明显风险（或标注已知风险供后续深入调查）
+
+---
+
+## CDCP Gate 评审
+
+### 触发条件
+
+7 个 checklist 项全部完成。
+
+### 执行方式
+
+1. 读取 `analysis-framework.md` 的 CDCP 标准
+2. 逐一回答 5 个核心问题（引用数据支撑）：
+   - 市场存在吗？（需求验证数据）
+   - 能赚钱吗？（利润估算）
+   - 竞争打得过吗？（竞争格局分析）
+   - 法律风险可控吗？（IP/合规初筛结果）
+   - SPAN 可接受吗？（SPAN 评分）
+3. 给出 **Go / Kill / Redirect** 建议
+4. 等待用户确认决策
+5. 确认后更新：
+   - `RESEARCH.md`（阶段 → 计划，记录决策）
+   - `OVERVIEW.md`（状态更新）
+
+### 评审输出格式模板
+
+```
+## CDCP Gate 评审结果
+
+### 核心问题
+
+| # | 问题 | 结论 | 依据 |
+|---|------|------|------|
+| 1 | 市场存在？ | ✅/❌ | [具体数据：月销量、搜索量等] |
+| 2 | 能赚钱？ | ✅/❌ | [毛利率 XX%，满足/不满足最低毛利率要求] |
+| 3 | 竞争打得过？ | ✅/❌ | [头部评论数、品牌集中度等] |
+| 4 | 法律风险？ | ✅/❌ | [专利/商标/认证情况] |
+| 5 | SPAN 可接受？ | ✅/❌ | [市场吸引力: X/5, 竞争地位: X/5, 象限: 投资/选择性投入/收割/退出] |
+
+### 建议
+
+**决策：Go / Kill / Redirect**
+
+理由：[1-2 句总结]
+
+### 下一步
+- [如果 Go：进入计划阶段需要做什么]
+- [如果 Kill：归档原因]
+- [如果 Redirect：建议调整方向]
+```
+
+### 各决策结果的具体操作
+
+**Go：**
+1. 更新 RESEARCH.md 当前阶段 → 计划
+2. 更新 RESEARCH.md 决策记录
+3. 更新 OVERVIEW.md 阶段列
+4. 加载 planning.md 开始计划阶段
+
+**Kill：**
+1. 更新 RESEARCH.md 状态 → 已决策(No-Go)
+2. 更新 RESEARCH.md 决策记录（记录放弃原因）
+3. 更新 OVERVIEW.md：从活跃移到已完结
+4. 提示更新 CBB.md（即使失败也可能积累了有用信息）
+
+**Redirect：**
+1. 更新 RESEARCH.md 决策记录（记录调整原因和新方向）
+2. 根据调整幅度决定：
+   - **小调整**（如从"无线耳机"缩窄到"开放式耳机"）：修改当前项目的研究目标，重置概念阶段 checklist 中受影响的项（如竞争格局、SPAN），重新执行
+   - **大调整**（方向完全不同）：归档当前项目(No-Go)，新建项目重新开始
+3. 无论哪种，保留已有数据不删除（可能在新方向中有参考价值）
+
+## 完整交互示例
+
+### 示例：研究钛合金杯子
+
+**用户**："我想开店卖钛合金杯子，你觉得合适吗？"
+
+**步骤 1-2：趋势扫描 + Amazon 搜索**
+
+立即执行：
+- `scout search "titanium cup" --limit 15`
+- `scout search "titanium mug" --limit 15`
+
+分享发现：
+> "市场有 50+ 竞品，价格 $15-90，主要在 $20-30 区间。头部产品（TOAKS）月销约 200 件，BSR #530。两个方向：低价位($15-25)竞争激烈，高端保温款($60-90)产品很少。你更倾向哪个价位？"
+
+**步骤 3-4：用户回复后深入**
+
+用户："中高端的，质量好的"
+
+执行：`scout product B0CTKWJDXX`、`scout product B0DNCMN3NX`、`scout product B083NLR6BF`
+
+分享：
+> "TOAKS 中端爆款 BSR #530，月销 250 件，87% 五星。用户最爱：超轻、品质好、无金属味。主要抱怨：散热快（无保温）。KOYASU 高端保温 $89.99，评论少但 4.8 分。保温款市场几乎空白！"
+
+**步骤 5：Keepa 历史验证**
+
+执行：`scout keepa product B0CTKWJDXX,B0DNCMN3NX,B083NLR6BF --stats 180`
+
+分享：
+> "Keepa 数据显示：TOAKS 的 BSR 过去 6 个月从 #2000 降到 #530，市场在增长。卖家数从 3 增到 8，竞争在加剧但还不激烈。价格稳定在 $25-28，无价格战。保温款 KOYASU BSR 波动大但整体下降，刚起步有潜力。"
+
+**步骤 6：供应商和成本**
+
+用户："好的，你看看成本"
+
+执行：
+- `scout search "titanium tumbler" --limit 10`
+- `scout supplier-search "钛合金保温杯"`
+
+分享：
+> "批发价区间 ¥180-450（约 $25-65），起订量 50-100 个。头部供应商：8 年工厂，¥280 批发价。**利润分析**：Amazon 售价 $70-90，1688 成本 ¥280（≈$40），运费+FBA 约 $15，总成本约 $55，毛利率 25-40%。"
+
+**步骤 7：建议**
+
+> "概念阶段数据收集完毕。要不要立项做正式的 IPD 分析？我可以帮你做 SPAN 定位、$APPEALS 竞品评分和 FAN 财务模型。"

package/.claude/skills/scout/references/cross-project.md

@@ -0,0 +1,79 @@
+# 跨项目分析指引
+
+## 何时使用
+
+当用户要求对比多个产品研究项目时加载。典型请求：
+- "把我所有概念阶段的产品对比一下"
+- "哪个产品利润空间最大？"
+- "我的供应商有没有能同时供多个产品的？"
+- "帮我做一个 Portfolio 分析"
+
+## 数据获取
+
+1. 读取 ~/products/OVERVIEW.md 获取项目列表和状态
+2. 对每个相关项目读取 RESEARCH.md（SPAN、FAN、$APPEALS）
+3. 如需详细对比，读取各项目活文档
+
+## 分析类型
+
+### Portfolio SPAN 矩阵
+
+将所有活跃项目画在 SPAN 矩阵上（用文字表示象限图）。
+评估：
+- 是否过度集中某象限
+- 是否有足够"投资区"项目
+- "选择性投入"区项目是否值得补强
+
+### 财务对比
+
+表格：项目、阶段、毛利率、净利率（计划阶段后）、回本周期、首批投入、月销预估、风险等级
+按回报率排序辅助资源分配。
+
+### 供应商资源复用
+
+检查各项目 suppliers/suppliers.json：
+- 同一供应商能否供多个产品
+- 合并采购的议价空间
+- 供应商地域风险分散
+
+### 品类协同分析
+
+- 品牌：多产品能否组成品牌矩阵
+- 运营：是否共享关键词/客户群
+- 物流：能否合并发货降低运费
+
+### CBB 能力货架管理
+
+CBB（Common Building Block，共用构建模块）是跨产品可复用的能力模块。
+
+**数据位置：** `~/products/CBB.md`
+
+**CBB 的 6 种类型：**
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| 供应商能力 | 已验证的供应商、工厂关系 | "深圳XX钛合金厂，MOQ 100，配合度高" |
+| 物流能力 | 验证过的头程线路、货代 | "XX货代美西海运，15天到仓，$3/kg" |
+| 品类知识 | 认证经验、合规方案 | "FDA 认证流程已跑通，费用$2000，4周" |
+| 运营能力 | Listing 方案、关键词库 | "户外品类拍摄 SOP，7图+视频方案" |
+| 品牌资产 | 已注册商标、视觉体系 | "XX品牌已注册美国/欧盟，VI 已定稿" |
+| 技术/设计 | 已开模部件、包装方案 | "通用缓冲包装方案，适用 FBA 标准尺寸" |
+
+**何时更新 CBB：**
+- 项目完成（Go 或 No-Go）后，提示用户："这次研究积累了什么可复用的能力？"
+- 用户确认后更新 `~/products/CBB.md` 对应分类
+
+**何时查询 CBB：**
+- 新建项目时，读取 CBB.md 识别可复用能力
+- 影响 SPAN 评分：有可复用的供应商/品类知识/品牌资产 → 竞争地位中"供应链能力"和"差异化能力"得分提升
+- 影响 FAN 模型：已有供应商关系可降低成本估算风险，已有物流线路可精确运费
+
+**与供应商资源复用的区别：**
+- 供应商资源复用是"看各项目有没有重叠的供应商"（被动发现）
+- CBB 是"主动积累和管理可复用能力"（主动建设）
+
+## 产出
+
+更新 ~/products/OVERVIEW.md "跨产品洞察"部分。
+如用户要求，生成 Portfolio 分析报告。
+项目完成后更新 ~/products/CBB.md 能力货架。

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

@@ -0,0 +1,50 @@
+# 开发阶段指引
+
+## 目标
+完成供应商选定、产品规格确认、Listing 素材准备。产出可下单生产的完整方案。
+
+## 何时进入此阶段
+- PDCP Gate 通过后自动进入
+- RESEARCH.md 当前阶段 = 开发
+
+## Scout 在此阶段的角色
+
+开发阶段大部分工作发生在线下（与供应商沟通、打样、质检等）。Scout 的角色是：
+- **记录员**：帮用户结构化记录每一步的进展和决策
+- **分析员**：用 FAN 模型验证成本变化对财务的影响
+- **提醒员**：追踪 checklist 进度，适时提醒 Gate 评审
+
+当用户汇报线下进展时，agent 帮助更新 RESEARCH.md 和相关文档。
+
+## 执行步骤
+
+### 1. 供应商评估与选定
+- 评估矩阵 7 维度（各 1-10 分）：产品质量、MOQ灵活性、交期可靠性、沟通配合度、定制能力、价格竞争力、认证资质
+- 建议选 2 家（主选+备选）
+- 更新 SUPPLIERS.md 评估矩阵
+
+### 2. 成本模型定稿
+- 用实际报价替换计划阶段估算
+- 更新 RESEARCH.md FAN 财务模型
+- 重新计算场景分析
+
+### 3. 产品规格确认
+- 材料、尺寸重量（影响FBA费分级）、包装、颜色/变体、认证清单
+- **落盘位置**：记录在 RESEARCH.md 关键发现中
+
+### 4. 样品迭代
+- 至少 2 轮（基础功能确认 → 修改后最终确认）
+- 记录每轮问题和修改
+- **落盘位置**：记录在 RESEARCH.md 关键发现中（每轮追加）
+
+### 5. 包装设计
+- 品牌包装、FBA 尺寸优化、内包装保护、Insert card
+- **落盘位置**：记录在 RESEARCH.md 关键发现中
+
+### 6. Listing 素材准备
+- 主图+6副图、A+ Content、视频（可选）、关键词列表
+- **落盘位置**：记录在 RESEARCH.md 关键发现中（可附注素材链接）
+
+## 开发 Gate 评审
+5 个问题：样品达标？成本在预算内？认证已获得？Listing就绪？供应商可承诺批量交期？
+全 Yes → Go（下首批订单，进入验证阶段）

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

@@ -0,0 +1,32 @@
+# 发布阶段指引
+
+## 目标
+正式上架推广，建立销售飞轮。
+
+## 何时进入此阶段
+- ADCP Gate 通过后进入
+- RESEARCH.md 当前阶段 = 发布
+
+## 关键活动
+
+### 1. 库存管理
+- 首批正式库存（预估 2-3 个月销量）
+- 设置补货提醒
+
+### 2. Launch 推广
+- PPC 预算放量
+- 站外引流（Deal 网站、社交媒体）
+- 优惠券/促销
+
+### 3. 评论加速
+- Vine 计划
+- Insert card 引导
+- 优质售后
+
+### 4. 竞品动态监控
+- 定期复查竞品价格和 BSR
+- `scout product COMPETITOR_ASIN`
+- `scout keepa product COMPETITOR_ASIN --stats 30`
+
+## Scout 在此阶段的作用
+主要是手动复查：用户定期要求检查竞品，scout 执行命令更新数据。暂无自动化监控（未来可加定时任务）。

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

@@ -0,0 +1,39 @@
+# 生命周期阶段指引
+
+## 目标
+持续监控产品表现，做出扩展或退出决策。
+
+## 何时进入此阶段
+- 产品正式上架并稳定销售后
+- RESEARCH.md 当前阶段 = 生命周期
+
+## 关键活动
+
+### 月度复盘
+对比实际 vs Business Case：
+
+| 指标 | 预估 | 实际 | 偏差 |
+|------|------|------|------|
+| 月销量 | | | |
+| 售价 | | | |
+| ACoS | | | |
+| 退货率 | | | |
+| 净利率 | | | |
+
+命令：`scout keepa product MY_ASIN --stats 30`、`scout product MY_ASIN`
+
+### 变体扩展评估
+- 颜色/尺寸/配件/升级版
+- 每个变体视为一个小型"概念→计划"循环
+
+### EOL 决策（LDCP）
+退出信号：
+- 连续 3 月利润低于 PROFILE.md 最低净利率
+- BSR 持续恶化无改善
+- ACoS 不可控
+- 库存积压超 6 月周转
+
+EOL 后：清仓策略 → 更新 RESEARCH.md 状态(No-Go) → 更新 OVERVIEW.md 移入已完结
+
+## Scout 在此阶段的作用
+定期手动复查数据，更新月度对比。未来可通过定时任务自动化。

package/.claude/skills/scout/references/market-management.md

@@ -0,0 +1,120 @@
+# 市场管理（MM）指引
+
+## 目标
+
+MM 是产品开发的前置流程，负责"做正确的事"。通过系统化的市场扫描和机会评估，确定未来的选品方向和优先级，输出产品路标规划（ROADMAP.md）。
+
+## 何时触发
+
+- 用户问"接下来做什么品类？"、"年度选品方向"、"产品线规划"
+- 季度复盘时主动建议
+- 首次使用且 ROADMAP.md 为空时
+- 用户要求"帮我扫描一下市场机会"
+
+## 与概念阶段的关系
+
+- MM 产出的是**方向和机会清单**（ROADMAP.md 品类机会池）
+- 概念阶段针对**具体产品**做深入验证（RESEARCH.md）
+- MM 是宏观选择（做哪个品类），概念是微观验证（这个具体产品行不行）
+- MM 可以同时评估 5-10 个方向，概念阶段一次专注 1 个产品
+
+## 执行步骤
+
+### 1. 确定扫描范围
+
+**目的：** 明确本次 MM 要探索的方向。
+
+**输入来源：**
+- PROFILE.md 中的偏好品类和回避品类
+- CBB.md 中已有能力可延伸的品类
+- 用户提出的兴趣方向
+- 外部趋势信号（社交媒体热度、行业新闻）
+
+**产出：** 5-10 个待评估的品类/方向清单
+
+---
+
+### 2. 多品类快速扫描
+
+**目的：** 对每个方向做快速数据收集，获取 SPAN 打分所需的基础数据。
+
+**命令（对每个方向执行）：**
+```bash
+scout search "品类关键词" --limit 10
+scout tiktok search-videos "品类关键词"
+```
+
+**每个方向只需收集：**
+- 市场规模估算（头部 BSR、"bought in past month"）
+- 价格区间
+- 竞品数量和头部评论数
+- 社交热度信号
+
+**注意：** MM 阶段是**广度优先**，每个方向花 5-10 分钟快速判断，不深入。
+
+---
+
+### 3. SPAN 快速打分
+
+**目的：** 对每个方向做战略定位，确定优先级。
+
+**方法：** 参考 analysis-framework.md 的 SPAN 评分标准，但允许粗略估算：
+
+- 市场吸引力（1-5）：基于步骤 2 收集的市场规模和增长信号
+- 竞争地位（1-5）：基于 PROFILE.md 能力 + CBB.md 可复用资源
+
+**产出：** 每个方向一个 SPAN 坐标 + 象限判断
+
+---
+
+### 4. 优先级排序
+
+**排序依据（权重递减）：**
+
+1. **SPAN 象限**：投资 > 选择性投入 > 收割 > 退出
+2. **与 PROFILE.md 匹配度**：价位区间、品类偏好、风险偏好
+3. **CBB 复用度**：能从能力货架取用多少现有模块？复用越多风险越低
+4. **时间窗口**：是否有季节性或趋势紧迫性？
+
+**优先级分类：**
+- **P1**：SPAN 投资象限 + 高匹配 + 有 CBB 复用 → 立即立项研究
+- **P2**：SPAN 投资/选择性投入 + 中匹配 → 排队等资源
+- **P3**：有潜力但需补强或时机未到 → 持续观察
+- **放弃**：SPAN 退出象限 / 与 PROFILE 不匹配 / 无法补强
+
+---
+
+### 5. 更新产品路标
+
+**更新 `~/products/ROADMAP.md`：**
+- 品类机会池：添加新机会，标注优先级和 SPAN 评分
+- 产品线规划：P1 机会排入时间线
+- 资源预算分配：根据优先级分配预算
+- MM 复盘记录：记录本次 MM 的决策
+
+---
+
+### 6. 立项触发
+
+**P1 机会 → 发起概念阶段：**
+- 从 ROADMAP.md 选取 P1 机会
+- 创建新项目（template/product/ → ~/products/{slug}/）
+- 进入概念阶段深入验证
+
+**控制节奏：**
+- 同时进行中的概念/计划阶段项目不宜超过 3 个（避免资源分散）
+- 参考 PROFILE.md 单品启动预算和总资金情况
+
+## MM 复盘节奏
+
+| 频率 | 内容 |
+|------|------|
+| 季度 | 全面 MM：重新扫描市场、更新 SPAN、调整路标优先级 |
+| 月度 | 轻量检查：有无新趋势信号？路标执行进度如何？ |
+| 随时 | 发现显著趋势变化时（如某品类突然爆发），触发临时 MM |
+
+## MM 与 Portfolio 管理的关系
+
+- MM 负责**输入端**：发现新机会，决定做什么
+- Portfolio 负责**管理端**：已立项产品的资源分配和 Go/Kill 决策
+- 两者共享 SPAN 框架和 ROADMAP.md