Zach Product Research

注：本 Skill 已吸收原 zach-market-intelligence 的 Go/No-Go 决策框架与进入壁垒评估能力（见 Step 2.4 / Step 3.5），以及 zach-report-dashboard-renderer 的 Dashboard 可视化看板能力。两者均已标记为 deprecated。

Script Directory

• scripts/render_deliverables.py
  • 用途：把统一 JSON 数据包渲染为 md + html精简 + dashboard看板 + xlsx + json，并执行交付校验
  • v2 模式（推荐）：payload 含 schema_version: “2.0” + chapters，渲染器从结构化数据生成表格 + 插入 LLM 洞察段落
  • v1 兼容模式：payload 含 report_markdown / report_html，直接写入（旧流程）
  • 命令：
    • python skills/zach-product-research/scripts/render_deliverables.py generate --input <payload.json>
    • python skills/zach-product-research/scripts/render_deliverables.py validate --input <payload.json>
    • python skills/zach-product-research/scripts/render_deliverables.py all --input <payload.json>
  • 适用时机：Step 5 交付阶段，禁止手工只补单个文件后直接结束任务
• scripts/parse_top100_dimensions.py
  • 用途：按规则文件解析 Top100 标题维度，输出 top100_parsed.json 与 uncertain_products.json
• scripts/cross_analysis.py
  • 用途：基于解析后的产品 JSON 生成交叉矩阵和机会空白点

References

• references/payload_schema_v2.md
  • 用途：v2 payload 结构定义（10 章 chapters + excel_sheets），准备 render_deliverables.py 输入数据包时查看
• references/payload_schema.md
  • 用途：v1 payload 结构定义（向后兼容参考）
• references/html_report_spec.md
  • 用途：HTML 精简报告区块定义参考
• references/analysis_patterns.md
  • 用途：四种分析模式的模板与示例，报告写作时必须引用（至少使用 3 种）

Assets

• assets/html_report_template.html
  • 用途：HTML 精简报告模板（v1 使用，v2 由 render_deliverables.py 内置渲染）
• assets/dashboard_template.html
  • 用途：Dashboard 可视化看板模板（从 zach-report-dashboard-renderer 迁入），v2 由 render_deliverables.py 自动注入数据

Agents

• agents/data-pipeline.md
  • 用途：负责 Sorftime 原始数据 → 中间 JSON / Excel Sheet 数据
• agents/insight-writer.md（v2 新增，替代 report-writer.md）
  • 用途：负责在固定 10 章结构中撰写分析洞察段落（不写表格格式/HTML）

Evals

• evals/evals.json
  • 用途：最小自测套件
• evals/files/sample_payload_minimal.json
  • 用途：交付链路最小样本

核心原则

1. 权重优先：权重越大，免费流量越多
2. 盈利监控：利润覆盖广告成本，保持健康ROI
3. 战场优先：先选好市场，再打磨产品
4. 数据驱动：用可量化指标判断市场与竞品
5. 差异化竞争：通过优化设计、卖点、包装提升转化

硬性规则（⛔ 不可省略）

以下规则适用于所有场景，不论模型能力或用户是否明确要求：

1. ⛔ 类目 Top100 明细必须输出完整 100 条，不得以"代表产品"缩写
2. ⛔ 竞品差评分析必须附"竞品选择逻辑表"（ASIN + 选择理由 + 竞品类型 + 覆盖维度），竞品总数 6-10 个，覆盖量级标杆/功能差异/价格带/痛点
3. ⛔ 关键词分析必须覆盖至少 3 个维度对比（如：品类大词 vs 属性词 vs 规格/场景词）
4. ⛔ MD 报告中出现的每个数据表/统计结论，必须在 Excel 中有对应 Sheet
5. ⛔ 每个 Step 完成后进行数据完整性检查，再进入下一步
6. ⛔ 输出前执行 Step 5 交付自检清单
7. ⛔ 定向品类分析（场景 4）必须执行 Step 1.5 产品属性标注
8. ⛔ 差评痛点必须按属性维度归类（而非仅按产品归类）

报告写作硬性规则（⛔ 不可省略）

以下规则确保每份报告达到「充电宝 v2」级别的分析深度，而非纯数据堆砌：

9. ⛔ 禁止纯数据呈现：每个数据表格后必须紧跟「关键洞察」段落（2-4 条 bullet），说明数据的业务含义，不得只放表格不做解读
10. ⛔ 必须有 Executive Summary：报告开头必须有 3-5 条核心结论，每条结构为：数据点 → 含义 → 行动建议
11. ⛔ 交叉分析必须解释原因：每个"空白"/"薄供给"标签必须附带原因分析（技术限制？需求不存在？被市场忽视？供应链难度？），不得只标注状态
12. ⛔ 差评痛点必须映射品牌机会：每个维度的差评痛点必须完成 痛点 → 品牌能力 → 产品方案 的映射，不得只列痛点不给方案
13. ⛔ 策略建议必须有产品矩阵：至少给出 Tier 1 产品的完整规格（维度规格表 + 决策理由 + 目标定价 + 差异化主张 + 对标竞品 + 预估月销潜力），绝不允许"待确认"占位
14. ⛔ 供需缺口必须排优先级：按三维评估（市场规模 40% + 技术可行性 30% + 品牌匹配 30%）排序，不得平铺罗列
15. ⛔ 必须使用分析模式：每份报告至少使用以下 4 种分析模式中的 3 种（详见 references/analysis_patterns.md）：

Sorftime MCP 工具清单

执行选品分析时，调用以下 Sorftime MCP 工具（⛔ = 必调，📋 = 按需）：

⛔ 必调说明：无论场景如何，这 6 个工具必须调用，其输出是报告核心数据的来源。📋 按需工具根据场景和用户需求选择性调用。

Gotchas（执行中最容易踩坑）

1. Skill 本地存在，不等于当前会话已加载

   • 如果仓库里已经有 skills/zach-product-research/，但当前会话仍提示 skill 不可用，先检查：
     • 当前 IDE 或 Agent 是否已经重新加载工作区配置
     • 是否存在历史别名（如 product-research）与正式名不一致的问题
   • 重要：即使你修好了磁盘文件，当前会话的 skill 列表也可能不会热更新；必要时要明确提示“当前会话需重开/新会话重载 skill”。

2. Sorftime MCP 在桌面端可能有逐次授权摩擦

   • 大批量并发调用前，优先做“最小闭环”：先拿类目、关键词、Top100 核心数据，再决定是否继续深挖。
   • 批量补调时默认按 <= 8 一批，避免一口气铺太多工具调用，导致中途被用户逐个确认打断。
   • 如果环境允许网络访问，且本机 ~/.cursor/mcp.json 已配置 Sorftime，可考虑走本地直连 HTTP MCP 作为非交互式 fallback；严禁回显真实 key。

3. 泛关键词经常混池，先清词池再估市场

   • 不要默认把用户给的词直接当“机器本体市场”。
   • 典型案例：essential oil diffuser 会混入精油本体、humidifier、reed diffuser、耗材生态。
   • 必须先用 category_name_search / keyword_search_results / 标题样本检查，确认结果池到底是不是同一竞争单元，再做市场规模判断。

4. Top100 大体量数据不要直接硬读

   • 默认先走标题解析，再对未知项补调 product_detail。
   • 如果 Top100 / 评论 / 明细返回很大，先落中间文件，再用脚本抽取字段；不要靠手工读大 JSON。

5. 只产出 Markdown 不算完成

   • 只要用户要正式交付，必须跑 render_deliverables.py all，同时产出 MD + HTML精简 + Dashboard + XLSX。
   • 如果目录里只有 .md，无论分析写得多完整，都视为未完成。

6. render_deliverables.py 有严格校验门槛

   • excel_sheets 第一张必须是 数据来源说明
   • 必选 Sheet 不全会校验失败
   • v2 payload 必须含 10 个 chapters
   • Markdown 洞察深度不足、缺少 Tier 产品矩阵、缺少 Go/No-Go 评分卡，也会在校验阶段暴露出来

执行流程

Step 0: 信息收集（交互式）

收到调用后，首先确认以下关键信息：

📋 选品分析 - 信息确认

1. 目标站点：[US/UK/DE/FR/IT/ES/CA/JP，默认US]
2. 选品场景：[新手入门/蓝海发现/季节性/品牌打造/定向品类分析]
3. 约束条件（可选）：
   - 价格区间：如 $10-40
   - 月销量：如 > 1000
   - 品类偏好：如 家居/电子/宠物
   - 预算：如 10万人民币
4. 产业带优势（可选）：如有特定供应链优势

如果用户未提供信息：默认按「新手入门」场景，美国站，价格 $10-40，无特定产业带。

Step 1: 发现机会市场

1.1 类目市场扫描

调用 search_categories_broadly 或 category_search_from_product_name 筛选符合以下条件的类目：

• 新品销量占比 > 15%
• 品牌数 > 80（分散市场）
• Top3销量占比 < 40%（低垄断）
• 平均价格 $10-40（新手友好）
• 月销量规模适中（视预算而定）

1.2 关键词机会挖掘（⛔ 必须多维度对比）

对候选类目，调用 keyword_search_results + keyword_detail：

• 搜索量 > 10000/月
• 自然位月销量 > 50000
• 首页竞品review数 < 500（门槛可追赶）
• CPC价格（广告成本）可接受

⛔ 多维度关键词对比表：关键词分析必须覆盖至少 3 个层级/维度，不得只分析用户提到的单一维度。

维度示例（根据品类调整）：

每个维度的关键词必须调用 keyword_detail 获取以下数据，输出对比表：

检查点：确认至少 3 个维度的关键词都有 keyword_detail 数据后，再进入 Step 1.3。

1.3 潜力产品初筛

调用 potential_product + product_search：

• 月销量 > 1000
• 价格 $10-30
• 评分 > 4.0
• 上架时间 < 6个月（新品有机会）

Step 1.4: 分析维度自发现（用户未指定维度时执行）

当用户不熟悉目标品类、无法指定分析维度时，模型需要自主发现该品类的关键差异化维度。本步骤在 Step 1.5（属性标注）之前执行，输出为属性标注的维度定义。

触发条件：用户未明确指定分析维度，或指定维度 ≤ 2 个。

执行方法（四路并行，结果综合）：

路径 1：Top100 标题高频词聚类

• 对 category_report 返回的 100 条产品标题做词频统计
• 过滤掉通用词（brand, portable, charger 等品类通用词）
• 保留出现频率 ≥ 10% 的属性词作为候选维度
• 示例输出：slim 出现 23 次 → 候选维度「外观形态」

路径 2：关键词延伸词分析

• 对品类核心词调用 keyword_extends，分析消费者用什么修饰词搜索
• 高搜索量的修饰词 = 消费者关注的差异化维度
• 示例：keyword_extends("power bank") → "65W power bank", "slim power bank" → 候选维度「功率」「形态」

路径 3：product_detail 属性字段 Key 提取

• 对 Top5 销量产品调用 product_detail
• 从返回的「属性」字段中提取 key 名称（非 value），作为结构化维度候选
• 示例：属性含 Battery Capacity, Connector Type → 候选维度「容量」「接口类型」

路径 4：WebSearch 品类评测文章（可选）

• 搜索 "[品类] buying guide" 或 "[品类] how to choose"
• 从评测文章中提取消费者决策的关键参数
• 示例：Wirecutter 评测关注 "capacity, charging speed, size, ports" → 候选维度确认

输出：候选维度列表（5-8 个），每个维度含：

• 维度名称
• 发现来源（标题词频/延伸词/属性Key/评测文章）
• 候选分类值（如：功率 → ≤15W / 15-22.5W / 30W / 45W / 65W / 100W+）

⛔ 必须让用户确认：输出候选维度后，请用户确认/删减/补充，再进入 Step 1.5。用户可能有品类知识补充模型发现不了的维度。

检查点：至少确认 3 个分析维度后，进入 Step 1.5。

Step 1.5: Top100 产品属性标注（P0 - 多维度分析必需）

本步骤将 category_report 返回的 Top100 基础数据升级为结构化多维度属性数据，是后续交叉分析与差异化建议的基础。

输入：Step 2.1 category_report 返回的 Top100 产品列表（本步骤可在获取 Top100 后立即执行，与 Step 1 并行推进）

⛔ 必须提取的基础字段（所有品类通用，category_report 直接返回）：

这两个字段在 category_report 返回数据中已有，解析时必须一起提取，不要丢弃。

标注维度（按品类定制，以下为充电宝示例；其他品类需根据品类特征自定义维度）：

执行方法（三阶段）：

1. 标题正则 + 关键词自动标注（覆盖率约 70-80%）

   • 遍历 Top100 产品标题，按上表规则逐维度提取
   • 每条产品标注置信度：高（明确匹配）/ 低（模糊或缺失）

2. ⛔ product_detail 补充验证（针对置信度低的约 20-30% 产品）

   • 对标题无法确认的产品，调用 product_detail 获取 bullet points / 产品描述
   • 从描述中提取缺失的属性信息
   • 每批最多 8 个并行调用以提高效率

3. 手动 override 记录

   • 记录所有手动修正的产品及修正原因
   • 便于后续复查与经验积累

⚠️ 标题解析注意事项（参见文末「标题解析经验库」章节）

输出：

检查点：确认 100 条产品均已完成属性标注（允许部分维度为"未知"，但不允许跳过标注步骤），再进入下一步。

Step 1.6: 多维度交叉分析（P1 - 属性标注完成后执行）

基于 Step 1.5 的结构化属性数据，生成交叉分析矩阵，发现供需缺口与市场机会空白点。

适用条件：

• 产品已完成多维度属性标注（Step 1.5）
• 需要找到供需缺口（搜索需求有但供给少的维度组合）
• 需要发现产品组合机会空白点

标准交叉表：

对所有有意义的维度对（dimension pair）生成交叉矩阵：

示例（充电宝）：功率 x 容量、功率 x 磁吸、容量 x 线材、功率 x 外观形态 等

自动识别供需缺口：

• 空白点：产品数 = 0 的维度组合 → 潜在蓝海机会（需验证需求是否真实存在）
• 薄供给：产品数 ≤ 2 的组合 → 低竞争机会（少量在售，竞争小）
• 高需求低供给：月销量高但产品数少的组合 → 最优机会

品牌集中度分析：

• 每个主要维度组合中，Top3 品牌的销量占比
• 识别品牌垄断严重的组合（避开）vs 品牌分散的组合（机会）

输出：

⛔ 交叉分析输出格式要求：

每对交叉维度的输出不得只有表格，必须包含以下结构：

1. 交叉矩阵表格（产品数 / 月销量 / 月销额 / 均价）
2. 关键发现段落（2-4 条 bullet），必须回答：
   • 哪些组合是市场主力？（高供给 + 高需求）
   • 哪些组合存在供需缺口？（高需求 + 低供给）
   • 哪些组合是伪机会？（低供给 + 低需求，实际无需求）
3. 空白/薄供给标签定义与分析要求：

检查点：确认至少 3 对维度组合完成交叉分析，且每对都有「关键发现」段落（不只表格），空白点/薄供给列表已生成且附原因分析，再进入 Step 1.7。

Step 1.7: 新品分析（⛔ 必做）

基于 Step 1.5 已提取的 上线日期 字段，分析 Top100 中新品的占比、表现和趋势，判断类目对新品的友好程度。这是选品决策的关键输入——新品占比高的类目意味着新进入者有机会，反之则门槛高。

数据来源：

• category_report 返回的 上线日期/上线天数 字段（Step 1.5 已提取，零额外 API 成本）
• category_trend（trendIndex=NewProductSalesAmountShare）→ 1 次 API 调用

执行步骤：

1. 上架时间分桶统计

对 Top100 按上架时间分桶，统计每桶的产品数和销量占比：

2. 半年内新品明细表

列出所有上架 ≤6 个月的产品，按月销量降序：

| ASIN | 品牌 | 价格 | 月销量 | 上线日期 | 天数 | 评论数 | [各属性维度] |

关注：

• 新品中有哪些品牌？（全是大品牌 vs 有白牌突围）
• 新品进入 Top50 了吗？（能否打进头部）
• 新品的属性组合是什么？（市场供给方向验证）

3. 新品销量占比趋势

调用 category_trend（trendIndex=NewProductSalesAmountShare），获取近 2 年每月的新品销量占比趋势：

• 趋势上升 → 类目活跃，对新品友好
• 趋势平稳低位（<5%）→ 类目成熟，老品主导，新品难突围
• 趋势下降 → 类目固化，不建议新品进入

4. 新品友好度判断

综合以上数据，给出类目的新品友好度评级：

输出：纳入报告的「市场概况」章节，含上架时间分布表、新品明细、趋势图数据、新品友好度评级。

检查点：新品分析完成且新品友好度评级已给出，再进入 Step 2。

Step 2: 验证竞争格局

2.1 类目深度分析

调用 category_report 获取 Top 100，分析：

• 品牌集中度（品牌垄断系数）
• 卖家类型分布（FBA/FBM/亚马逊自营比例）
• 新品比例（半年内上架产品占比）

检查点：确认 category_report 返回的产品数 = 100 条（⛔ 硬性规则第 1 条）。不足则重新调用或说明原因。

2.2 竞品详细分析（⛔ 差评分析须附选择逻辑）

对重点产品，调用 product_detail + product_reviews：

• 销量排名、价格趋势、评分评论数
• 好评关键词（用户重视什么）
• 差评痛点（改进机会）

⛔ 竞品选择逻辑表：做差评分析前，必须先输出竞品选择逻辑表，说明为什么选这些竞品：

⛔ 竞品选择必须满足以下覆盖要求：

• 总数：6-10 个竞品
• 每个主要属性维度（来自 Step 1.5 标注）至少有 1 个代表产品

选择建议：按细分段（如价格带、功率段、使用场景）各选 1-2 个代表，覆盖头部竞品 + 痛点竞品。

检查点：竞品选择逻辑表完成后，再逐一调用 product_reviews（reviewType=Negative）做差评分析。每批最多 8 个并行调用。

⛔ 差评分析按维度分类：差评痛点必须按属性维度归类（如功率相关、线材相关、数显相关、容量相关、磁吸相关、外观形态相关、通用质量问题），而非仅按产品归类。这样才能直接映射到产品设计决策。

2.3 关键词竞争分析

调用 competitor_product_keywords + product_traffic_terms：

• 核心关键词排名
• 流量词数量和分布
• 自然流量 vs 广告流量占比

2.4 进入壁垒评估（⛔ 必做，原 market-intelligence Step 4）

适用场景：所有正式交付版本必须输出。本节用于把“能不能做”的风险讲清楚，避免只给机会不讲门槛。

评估以下壁垒维度，每个维度给出等级（低/中/高）：

站点合规速查：

输出：壁垒汇总表（类型 + 等级 + 预估成本 + 预估时间）+ 预估启动投入合计

Step 3: 投入产出测算

财务公式：

毛利 = 售价 - 采购成本 - FBA费用 - 物流成本
净利润 = 毛利 - 广告成本 - 退货损耗 - 平台佣金(约15%)
毛利率 = 净利润 / 售价 * 100%

预估CPC：从 keyword_detail 获取
目标ACOS = 毛利率 * 50%（保守）
净利率 = 净利润 / 售价 * 100%

物流成本参考：

• 价格 $10-20：物流成本控制在售价 15% 以内
• 价格 $20-40：可承担更高物流成本

采购成本：可调用 ali1688_similar_product 获取1688货源参考价。

Step 3.5: Go/No-Go 综合评分（⛔ 必做，原 market-intelligence Step 6）

适用场景：所有正式交付版本必须输出。即便用户已经倾向进入，也必须把“进入条件、前提风险、最终判断”显式写出来。

评分体系（加权计算）：

决策矩阵：

输出：评分卡 + 决策建议 + Top3 机会 + Top3 风险 + 缓解方案

注意：如果决策为 NO-GO，流程终止，不进入 Step 4。

Step 4: 差异化建议与产品矩阵（⛔ 必须具体到规格）

本步骤是报告的核心价值输出——从数据分析转化为可执行的产品策略。绝不允许"待确认"占位或只列方向不给规格。

4.1 VOC 痛点维度映射

基于 Step 2.2 的差评分析（已按维度归类），对每个维度执行四要素映射：

⛔ 每个属性维度（来自 Step 1.5）都必须完成此映射表，不得遗漏。

4.2 机会空白优先级排序

汇总 Step 1.6 交叉分析发现的所有空白/薄供给/高需求低供给机会，按三维评估排序：

输出格式：

4.3 产品矩阵规划

基于优先级排序，规划具体产品矩阵。至少完成 Tier 1（最优先进入的产品），Tier 2/3 视数据充分度而定：

Tier 模板（每个 Tier 必须包含以下所有字段）：

### Tier [N]: [产品定位一句话]

**目标市场**：[对应的维度组合空白/机会]
**决策理由**：[为什么优先做这个——引用 4.2 的优先级排序数据]

| 维度 | 规格 | 决策依据 |
|------|------|----------|
| [维度1] | [具体规格值] | [为什么选这个值] |
| [维度2] | [具体规格值] | [为什么选这个值] |
| ... | ... | ... |

**目标定价**：$XX.XX（基于 Step 3 测算，毛利率 XX%）
**差异化主张**：[一句话核心卖点，区别于竞品的关键]
**对标竞品**：[ASIN] [品牌] [价格] — 我们的优势：[具体差异]
**预估月销潜力**：XX-XX 件/月（基于同维度组合现有产品表现推算）

⛔ 禁止事项：

• 不允许"待 Zach 确认"、"待定"、"建议进一步调研"等占位语
• 不允许只列方向不给具体规格（如"建议做大容量"必须改为"建议做 20000mAh"）
• 不允许不标对标竞品（必须有具体 ASIN）
• 不允许不给目标定价（必须基于 Step 3 测算）
• 如果数据确实不足以支撑某个 Tier，明确标注"数据不足：缺少 XX 数据，建议补充 XX 后再定"，但不得用"待确认"含糊带过

Step 5: 交付前自检（⛔ 必做）

⛔ 交付硬性规则

16. ⛔ 禁止分步输出：不得先手工输出 MD 报告再调用 render_deliverables.py； 所有交付物必须由 render_deliverables.py all 一次性生成
17. ⛔ unified_payload.json 必须包含产品级明细：
    • excel_sheets["类目销量Top100_明细"] 必须包含 100 条产品数据
    • excel_sheets["属性标注_Top100"] 必须包含属性标注结果
    • 两个 Sheet 的数据来源是 top100_raw.json 和 top100_parsed.json
18. ⛔ 竞品选择逻辑必须包含价格和销量：competitor_selection_logic 每条记录 必须含 price/monthly_sales/reviews 字段（从 product_detail 获取）

在输出报告和数据文件之前，逐项检查以下清单。全部通过后才可输出，未通过项必须修正后再输出：

• 类目 Top100 明细 = 100 条？（不足 100 条说明数据获取不完整，需重新调用 category_report）
• Top100 产品已完成属性标注？（Step 1.5，每条产品至少标注了定义的维度）
• 交叉分析已完成至少 3 对维度组合？（Step 1.6，含空白点/薄供给列表）
• 每个分析维度的关键词都有 keyword_detail 数据？（至少 3 个维度）
• 竞品差评分析附有"竞品选择逻辑表"？（含 ASIN + 选择理由 + 竞品类型 + 覆盖维度）
• 竞品选择覆盖了量级标杆、功能差异代表、价格带高中低、痛点参考？（6-10 个）
• 差评痛点已按属性维度归类？（而非仅按产品归类）
• MD 报告中的每个数据表在 Excel 中有对应 Sheet？
• Excel 中的数据条数 >= MD 报告中的数据条数？（Excel 不得少于 MD）
• 所有数据点标注了 Sorftime MCP 来源工具名？
• JSON 第一个 key 为"数据来源说明"？
• Excel Sheet 列表包含"竞品选择逻辑"和"关键词对比_分段"？（若有对应分析）
• Excel 包含"属性标注_Top100"和"交叉分析"Sheet？（若执行了 Step 1.5/1.6）
• 新品分析（Step 1.7）已完成？（含新品数量/占比/时间分桶 + 新品友好度评级）
• HTML 精简报告已生成？（⛔ 三件套：MD + Excel + HTML）
• 若执行了 Step 2.4 进入壁垒评估，壁垒汇总表完整？（6 类壁垒 + 等级 + 成本 + 时间）
• 若执行了 Step 3.5 Go/No-Go 评分，5 维度评分 + 加权总分 + 决策建议完整？
• 「类目销量Top100_明细」Sheet 包含 ≥100 条数据？
• 「属性标注_Top100」Sheet 属性标注完整？
• 竞品选择逻辑表每条含 price/monthly_sales/reviews？
• 调用 render_deliverables.py all 一次性生成（非分步）？

洞察质量检查（⛔ 必须全部通过）：

• 有 Executive Summary（≥ 4 条核心结论，每条含数据点+含义+行动建议）？
• 每个维度分布表后有「关键洞察」段落（2-4 条 bullet）？
• 交叉分析每对维度有「关键发现」段落（不只表格）？
• 所有「空白」/「薄供给」标签都有原因解释（技术/需求/被忽视/供应链）？
• 差评按维度归类后，每个维度有「品牌机会」映射（痛点→能力→方案）？
• 有产品矩阵（至少 Tier 1 含完整规格表+定价+差异化+对标竞品）？
• 机会空白点有优先级排序（三维加权评估）？
• 报告至少使用了 3 种分析模式（见 references/analysis_patterns.md）？

"6合1"隐赚指数标准

隐赚指数（潜力指数）评估以下6项，得分越高越好：

potential_product 可按潜力指数排序，优先筛选高分产品。

"好市场"评判标准

选品输出模板

每个推荐产品必须包含以下结构：

## 【产品名称】

### 一、市场概况
- **所属类目**：[类目名称 + NodeId]
- **目标关键词**：[核心关键词]
- **月销量规模**：[市场规模]
- **平均价格**：[价格区间]
- **数据来源**：[Sorftime MCP 工具名]

### 二、"6合1"验证
- [ ] 排名趋势：[稳定/上升/下降]
- [ ] 销量趋势：[稳定/增长/下降]
- [ ] 价格趋势：[稳定/上涨/下跌]
- [ ] 评价门槛：评论数[XXX]，可追赶
- [ ] 广告成本：CPC $[XXX]
- [ ] 上架时间：[XXX]个月内

### 三、竞争分析
- **品牌垄断系数**：[XX%]
- **Top3销量占比**：[XX%]
- **新品活跃度**：[高/中/低]
- **主要竞品**：[竞品ASIN及特点]

### 四、财务测算（USD）
| 项目 | 金额 |
|------|------|
| 售价建议 | $XX.XX |
| 采购成本 | $X.XX |
| FBA费用 | $X.XX |
| 平台佣金(15%) | $X.XX |
| 物流成本 | $X.XX |
| 预估毛利 | $X.XX |
| 毛利率 | XX% |
| 预估CPC | $X.XX |
| 目标ACOS | XX% |
| 净利率 | XX% |

### 五、差异化建议
- **痛点改进**：[具体改进方向]
- **卖点提炼**：[差异化卖点]
- **定价策略**：[价格方案]

### 六、风险提示
- [ ] 季节性风险：[是/否]
- [ ] 认证要求：[是/否]
- [ ] 专利风险：[是/否]
- [ ] 供应链风险：[注意事项]

常见场景策略

场景1：新手入门（预算<15万）

• 价格 $10-20
• 轻小件（降低FBA成本）
• 无售后风险品类
• 中国卖家占比 > 70% 的类目
• 推荐：厨房收纳、宠物用品、头巾面罩

场景2：蓝海发现（低竞争）

• 筛选低垄断类目（search_categories_broadly 设 top3Product_sales_share < 0.4）
• 关注新品出单明显的细分市场
• 寻找 Top400 长尾机会
• 验证关键词竞争强度（keyword_detail）

场景3：季节性产品

• 使用 keyword_trend 验证季节性
• 提前 2-3 个月备货
• 关注搜索量变化趋势
• 评估淡季库存风险

场景4：定向品类/产品分析（用户已指定品类）

适用于用户已确定要分析的产品/品类（如"分析美国站充电宝市场"、"分析某品类竞争格局"），与场景 1-3 的"发现未知机会"不同。

与发现型场景的区别：

执行要点：

• 直接从 Step 0 收集的品类/产品名进入 Step 1.2 关键词分析
• 关键词维度覆盖必须全面（⛔ 硬性规则第 3 条）
• ⛔ 必须执行 Step 1.5 属性标注 + Step 1.6 交叉分析（定向分析的核心价值）
• 竞品选择必须附选择逻辑表（⛔ 硬性规则第 2 条），覆盖量级标杆/功能差异/价格带/痛点
• 差评分析必须按属性维度归类
• 类目 Top100 仍需完整 100 条（⛔ 硬性规则第 1 条）

输出规范

1. 数据来源标注：每个数据点必须标注来源 Sorftime MCP 工具名
2. 量化指标优先：用具体数字而非模糊描述
3. 逻辑链完整：从市场发现 → 竞争验证 → 财务测算 → 差异化建议
4. 风险提示：必须包含潜在风险和应对方案
5. 可执行性：建议必须具体可落地

数据诚信规则（必须遵守）

• 绝不捏造数据：所有数据必须来自 Sorftime MCP 调用结果，不得编造
• 标注数据来源：每个数据点标注来源工具（如 mcp_sorftime_product_search）
• 区分事实与推测：事实用数据支撑，推测必须标注「⚠️ 推测」
• 标注数据时效：注明数据的获取时间或适用时间范围

product_detail 返回字段与可信度指南

Sorftime product_detail 返回的字段来源不同，可信度差异大。标注属性时需按可信度优先级使用。

使用优先级：标题 > 产品描述（五点） > 属性字段（后台）

属性字段常见问题：

• Special Feature：卖家经常堆砌不相关关键词，不可作为属性判断依据
• Battery Capacity：通常准确（亚马逊有格式要求），可直接使用
• Connector Type：格式不统一（有的写 "USB-C"，有的写 "Output: USB-C2+USB-A1"），需解析
• Color / Style：通常准确，可直接使用
• 空字段：特征 字段经常为空 {}，不要依赖

中间数据持久化规则

多维度分析流程通常需要 2-3 小时甚至跨 session 完成。为防止上下文压缩或 session 中断导致数据丢失，必须在关键节点持久化中间结果。

⛔ 持久化检查点：

原则：

• 每个 Step 完成后，将结果写入文件再进入下一步
• 如果 session 中断，下次可从最后保存的文件恢复，避免重新调用 API
• JSON 文件命名与标准输出目录一致（见「标准输出目录结构」）

Sorftime 返回数据处理规则（⛔ 必须用 Python 脚本）

Sorftime MCP 返回的数据量通常较大（Top100 约 50KB+），直接用 Read 工具读取会超出 token 限制导致失败。所有 Sorftime 大数据返回一律用 Python 脚本解析，不要尝试 Read 工具直读。

哪些工具的返回需要 Python 脚本处理

category_report 数据结构与解析模板

Sorftime category_report 返回数据的结构不是标准 JSON，而是包裹在 list[0]['text'] 中，前面带有一行指令文本。必须用以下方式解析：

import json

# raw_data 是 category_report 的返回值（保存为文件后读取）
with open('top100_raw.json', 'r') as f:
    raw = json.load(f)

# 结构：list[0]['text'] 包含 JSON，前面有指令前缀
text_content = raw[0]['text']
json_start = text_content.index('{')  # 找到第一个 { 的位置
data = json.loads(text_content[json_start:])

# data 现在是标准 dict，包含 Top100 产品列表
products = data.get('products', [])  # 具体 key 视返回格式而定

⛔ 不要：

• 不要用 Read 工具直接读取 category_report 的返回文件（会超 token 限制）
• 不要假设返回是标准 JSON（有指令前缀）

product_detail 批量调用规则

标准两步流程（Step 1.5 细化）：

Step 1: 标题正则解析 100 个产品 → 标注已知/未知
Step 2: 对"未知"产品批量调 product_detail（每批 ≤8 并行）→ 从描述/属性中提取缺失值

这比对全部 100 个产品调 product_detail 节省约 70-80% 的 API 调用量。

product_reviews 处理建议

• 每个竞品的差评数据量约 5-20KB
• 可批量并行调用：与 product_detail 一致，每批最多 8 个 ASIN 并行调用，再合并解析，以减少总耗时
• 批量获取 6-10 个竞品的差评后，用 Python 脚本按维度归类
• 归类结果保存为 voc_analysis.json

标题解析经验库（P1 - 按品类持续积累）

本节记录标题正则解析中的常见陷阱与经验规则，供 Step 1.5 执行时参考，避免重复踩坑。按品类积累，新品类调研后应补充新的经验条目。

通用陷阱

品类特定经验：充电宝（Portable Charger / Power Bank）

品类特定经验：充电器（Wall Charger / Charger Block）

经验库使用规则

1. 执行 Step 1.5 前，先查阅本节对应品类的经验条目
2. 发现新陷阱时，在调研报告末尾记录，后续合并回本节
3. 品类首次调研，经验库可能为空，调研结束后必须补充至少 3 条经验
4. 置信度标注：凡命中上述陷阱条目的产品，自动标注为"低置信度"，进入 product_detail 验证队列

标准输出目录结构（P2）

定向品类分析（场景 4）的标准输出文件结构：

outputs/market-research/{brand}/{品类}/{version}/
├── top100_raw.json              # 原始 Top100 数据（category_report 直接输出）
├── top100_parsed.json           # 属性标注后的 Top100 数据（Step 1.5 输出）
├── uncertain_products.json      # 需 product_detail 验证的产品列表
├── cross_analysis.json          # 交叉分析结果（Step 1.6 输出）
├── voc_analysis.json            # VOC 差评分析结果
├── {date}_{site}_{品类}_市场调研报告_{version}.md     # 完整 MD 报告
├── {date}_{site}_{品类}_市场调研_数据_{version}.xlsx   # Excel 数据（多 Sheet）
├── {date}_{site}_{品类}_精简报告_{version}.html        # ⛔ HTML 精简报告（三件套必出）
├── parse_top100_dimensions.py   # 标题解析脚本（可选，复杂品类用）
├── apply_overrides.py           # 手动修正脚本（可选）
├── cross_analysis.py            # 交叉分析脚本（可选）
└── export_to_excel.py           # Excel 导出脚本

其中 {version} 格式为 v{N}_{YYYYMMDD}（如 v2_20260228），便于同品类多次调研的版本管理。

报告与数据文件存储

必须同时输出三类文件（⛔ 三件套必出）（与 market-comparison 及「外部数据调用规范」一致）：MD 报告 + Excel 多 Sheet + HTML 精简报告，便于负责人逐项、逐 ASIN 验证且来源可追溯。

HTML 精简报告输出规范（⛔ 所有品类统一，参考充电宝 v2 / 充电器水准）：

HTML 精简报告须与 MD/Excel 同源数据一致，且结构、样式、区块完整，禁止仅「一段话 + 简单表格」的简陋版。必须包含以下区块与样式约定：

样式约定：使用 CSS 变量统一主色与灰度（如 --blue, --gray-100）；容器 max-width 960px、padding 40px 24px；表格带圆角、斑马悬停、表头背景；响应式：小屏 KPI 两列、痛点单列。参考实现：使用当前任务输出的公开示例 HTML 结构作为基准，不引用品牌专属历史案例路径。

自检：交付前确认 HTML 含上述 6 个必选区块且无「少量」「约」等模糊表述；与同目录 MD 报告数据一致。

存储位置：统一为 outputs/market-research/[品牌名]/[品类slug]/[version]/；品牌未指定时建议使用 outputs/market-research/_draft/[品类slug]/[version]/。不要把正式交付文件直接散落在仓库根目录。

Excel 多 Sheet 结构（必须包含数据来源说明、总结与明细；凡「Top100」等须在数据来源说明中区分含义）：

数据来源说明示例行：

命名与含义：

• 「类目销量 Top100」= category_report 返回的该类目按销量排序的前 100 个产品。
• 「关键词 XXX 自然位」= keyword_search_results 返回的该关键词搜索下的自然位产品。二者不得混用；报告与 Excel 中凡出现 Top100/自然位等，须与数据来源说明一致。
• 每个明细 Sheet 建议含列「数据来源_工具」「数据来源_含义」，或至少在「数据来源说明」中有一行对应。

生成方式：默认使用 skill 自带脚本，不再要求手工分别拼 MD / HTML / Excel。

统一数据包格式（供 render_deliverables.py 使用）

v2 格式（推荐）

{
  "schema_version": "2.0",
  "metadata": {
    "brand": "AORYVIC",
    "category": "wood-furniture-legs",
    "version": "v1_20260311",
    "date": "20260311",
    "site": "US",
    "keyword": "wood-furniture-legs",
    "created": "2026-03-11 16:20",
    "topic": "AORYVIC Wood Furniture Legs Sofa Legs",
    "type": "选品报告",
    "data_sources": [
      "sorftime MCP: category_report",
      "sorftime MCP: keyword_detail"
    ]
  },
  "chapters": {
    "ch01_executive_summary": { "conclusions": [...], "go_nogo_verdict": "GO", "one_line_summary": "..." },
    "ch02_market_overview": { "kpis": [...], "keyword_comparison": [...], "insight": "..." },
    "ch03_dimension_distribution": { "dimensions": [...] },
    "ch04_cross_analysis": { "matrices": [...] },
    "ch05_competitor_brands": { "competitor_selection_logic": [...], "brand_landscape": [...], "insight": "..." },
    "ch06_voc_pain_points": { "by_dimension": [...] },
    "ch07_opportunity_gaps": { "opportunities": [...], "scoring_method": "...", "insight": "..." },
    "ch08_strategic_recommendations": { "tiers": [...], "brand_strategy": "...", "timeline": "..." },
    "ch09_barriers_go_nogo": { "barriers": [...], "go_nogo_scorecard": [...], "verdict": "GO", "risks": [...] },
    "ch10_appendix": { "tool_calls": [...], "data_date": "...", "files": [...] }
  },
  "excel_sheets": {
    "数据来源说明": [{ "...": "..." }],
    "市场概况": [{ "...": "..." }]
  },
  "artifacts": {
    "top100_raw.json": [],
    "cross_analysis.json": []
  }
}

完整 v2 Schema 详见 references/payload_schema_v2.md

v1 格式（向后兼容）

v1 payload 含 report_markdown / report_html 字段，无 schema_version 和 chapters。渲染器自动检测并走旧路径。

脚本职责

render_deliverables.py 会自动：

1. 按规范目录写入 outputs/market-research/{brand}/{category}/{version}/
2. v2 生成（4 个交付文件）：
   • {date}_{site}_{keyword}_市场调研报告_{version}.md（从 chapters 模板渲染）
   • {date}_{site}_{keyword}_精简报告_{version}.html（从 chapters 模板渲染）
   • {date}_{site}_{keyword}_可视化看板_{version}.html（Dashboard，从 chapters 构建 view-model）
   • {date}_{site}_{keyword}_市场调研_数据_{version}.xlsx
   • excel_sheets_data.json、unified_payload.json 与 artifacts 中声明的原始/中间 JSON
3. 校验：
   • v2: 四件套齐全 + chapters 10 章完整性 + 各章必填字段校验
   • Markdown 含 YAML 头
   • HTML 含 10 个必选区块
   • Excel 首 Sheet 为 数据来源说明
   • 文件名、目录结构符合 skill 规范

交付完成定义（DoD）

执行 python skills/zach-product-research/scripts/render_deliverables.py all --input <payload.json> 后，必须同时满足：

• 命令返回 validate_ok
• 正式交付文件位于 outputs/market-research/...
• v2: MD / HTML精简 / Dashboard看板 / XLSX 四件套都存在
• Excel 首 Sheet 为 数据来源说明
• 报告中引用的关键结论在 Excel 对应 Sheet 中可追溯

未调用的工具对应 Sheet 可省略或留空列表，不得用估算填充。

• 报告中的每个关键数字都应在对应 Sheet 中有对应行/列；所有结论可逐条或逐 ASIN 核对，且通过「数据来源说明」可确认来源与含义。

自测命令

每次修改脚本或模板后，至少运行一次：

python skills/zach-product-research/scripts/render_deliverables.py all --input skills/zach-product-research/evals/files/sample_payload_minimal.json --root .

只有返回 validate_ok，才说明交付链路没有被改坏。

风险与边界

• 本 Skill 不做：不执行采购、不下单、不修改 Listing、不操作广告
• 以下情况升级人工：
  • Go/No-Go 评分落在 CONDITIONAL GO 区间时，必须人工决策
  • 数据异常（如 Top100 返回不足 50 条）时标注数据缺失
  • 涉及合规/认证门槛高的品类，提醒用户确认
• risk-level: low — 纯分析/信息收集，不影响资金或账号

上游 / 下游

• 上游（benefits-from）：无，本 Skill 是链路起点
• 下游（建议后续）：
  • → /zach-competitor-deep-dive — 竞品深度拆解
  • → /zach-pricing-strategy — 定价策略
  • → /zach-keyword-expansion — 关键词拓展

可选的下游集成

本公开版只负责产出和校验四件套交付物，不内置任何私有系统写回逻辑。

如果你有自己的工作流系统，可以在交付完成后自行把这些字段接到：

• 飞书、多维表格或内部数据库
• Notion、Airtable、Google Sheets
• 自己的项目看板或选品归档系统

建议同步的最小字段包括：

• 调研关键词
• 站点
• 调研日期
• 月搜索量估算
• 主流售价区间
• 预估毛利率
• Go / No-Go
• 交付目录
• 报告文件名
• Excel 文件名
• Dashboard 文件名

完成后

报告完成状态（四选一）：

• DONE — 四件套全部通过 validate_ok
• DONE_WITH_CONCERNS — 交付完成但数据有缺失（如 Top100 不满 100 条）
• BLOCKED — Sorftime MCP 不可用或品类 ID 无法定位
• NEEDS_CONTEXT — 用户未提供关键词/品类/站点