---
name: workshop-session-1-category
description: VOC虾工作坊 Session 1 — 教虾认品类（品类全景分析）+ Side Quests
version: 3.0.0
session: 1
prevSession: workshop-session-0-intake.md
nextSession: workshop-session-2-brand.md
---

# Session 1：教虾认品类（品类全景分析）

> **前置依赖：必须先加载 `workshop-global-rules.md`**

## 前置检查
- ✅ `brand-context.json` 已存在且 categoryKeywords 非空
- 🔐 `workshop-progress.preflight.status === "valid"` 或 通过 Step 1.0 Token 快检

---

## Step 1.0: Token 快检（Session 1 入口必过）

> **⚠️ 在调用任何付费 skill 之前必须执行**
>
> 详细规则见 `workshop-global-rules.md` 「🔐 Token 预飞协议」。

### 判定逻辑

```
1. 读取 memory/workshop-progress.json 的 preflight 字段
2. 如果 preflight.status === "valid" 且 preflight.lastValidatedAt 距今 <= 30 分钟：
   → 跳过本步骤，直接进入"对话开场"（复用 Session 0 的 preflight 结果）
3. 否则：
   → 调用 voc-token-preflight(apigId = "7HwdQZk55B")
   → 根据 status 分支处理
```

### 各 status 的处理

#### status = `valid`
更新 `workshop-progress.preflight`，简短确认后进入对话开场：
```
🔐 VOC-AI 服务已就绪（余额 {{balance}} 次），开始跑品类分析...
```

#### status = `missing` 或 `expired`
按全局规则「Token 预飞协议 → status = missing / expired」展示完整支付引导，**HARD STOP** 等用户粘 token。收到后运行 `set-voc-token.js` + 再跑 preflight，然后重回本步骤。

#### status = `insufficient_balance`
按全局规则「Token 预飞协议 → status = insufficient_balance」展示专属续费链接，等用户扫码支付后回复"已支付"，再跑 preflight 确认。

### 禁止行为（重申）

```
❌ 忽略快检结果，直接调用 category-landscape
❌ 把 "Token 失效" / "余额不足" 错误吞没为 "品类分析失败"
❌ preflight 失败时强行推进到对话开场
```

---

## Side Quest 触发条件速查（主线执行时参考）

> Agent 在执行主线分析时，**必须同时对照此表检测触发信号**，发现匹配时写入 `_sideQuestTriggers`。

| questId | 名称 | 触发信号（满足任一即触发） |
|---------|------|-------------------------|
| `keyword-deep-dive` | 🔑 关键词深潜 | ① 某关键词月搜索量 >10,000 但首页品牌数 <5 ② 某关键词近3月搜索量环比增长 >30% ③ 用户校准中对某关键词追问 |
| `category-tree-explorer` | 🌳 品类树探索 | ① CR5 <30%（分散市场暗示细分机会） ② 品类树中某子节点产品数/评论数比值异常 ③ 主品类与相邻品类存在交叉机会 |
| `price-band-mining` | 💰 价格带掘金 | ① 存在价格空白带（某 $5 区间内产品数 <3 但相邻区间 >15） ② 黄金价格带均价与用户品牌价格差距 >25% ③ 某价格带利润空间显著高于均值 |
| `top-player-decode` | 🏆 头部玩家解密 | ① Top1 品牌市占率 >20% 且策略独特（高溢价+高销量） ② CR5 中某品牌近6月增长率 >50% ③ 某头部ASIN评分 >4.5 且月销量 >5000 |

## 对话开场

```
虾：📊 阶段一：品类全景分析
━━━━━━━━━━━━━━━━━━━━

我现在要分析 {{categoryKeywords}} 这个品类的整体格局。
需要跑的内容：
• 品类Top100产品数据
• 市场集中度（CR5/HHI）
• 价格带分布
• 搜索趋势

预计需要3-5分钟，开始了！
```

## 技能调用序列

```
1. category-landscape(
     keywords = brand-context.categoryKeywords,
     domain = brand-context.amazonDomain,
     topN = 100
   )
   → 输出: 原始品类数据

2. [数据合成] 使用 synthesis-prompts.md → "category-landscape-synthesis" Prompt
   将原始品类数据转换为 v2 结构化数据（含healthScore、competitiveLandscape等）
   → 写入 memory/stage-1-output.json
```

## 结果展示模板

> **展示规则：以下所有带 📊/📈/💰/📉/🏗️/⚠️/🎯 标记的区块都是必须展示的，不可省略。**
> **如果某个字段数据缺失，展示"暂无数据"而不是跳过整个区块。**
> **Top 5 品牌必须展示完整表格（含品牌名、份额、均价、评分、月销量、代表ASIN）。**

```
虾：品类分析跑完了！以下是核心发现：

📊 {{categoryKeywords[0]}} 品类全景
━━━━━━━━━━━━━━━━━━━━

🎯 品类健康度评分：{{healthScore.overall}}/100
┌──────────────────────────────────┐
│ 市场吸引力 {{healthScore.marketAttractiveness}}/100
│ 竞争烈度   {{healthScore.competitiveIntensity}}/100
│ 增长潜力   {{healthScore.growthPotential}}/100
│ 进入难度   {{healthScore.entryDifficulty}}/100
└──────────────────────────────────┘

📈 市场规模
• 品类月销量：{{totalMonthlySales}} 件
• 品类月销售额：${{totalMonthlyRevenue}}
• 上架产品数：{{totalProducts}} 个
• 平均评分：{{avgRating}} | 平均评论数：{{avgReviewCount}}
• 近90天新入场者：{{newEntrantsLast90d}} 个

🏢 市场集中度
• CR5（前5品牌份额）：{{cr5}}%
• CR10：{{cr10}}%
• HHI指数：{{hhi}}
• 判断：{{concentrationLevel}} （高度集中/中等竞争/分散竞争）

📋 Top 5 品牌详细对比：
| # | 品牌 | 市场份额 | 均价 | 评分 | 月销量 | 代表ASIN | 定位标签 |
|---|------|---------|------|------|--------|---------|---------|
{{#each topBrands}}
| {{@index+1}} | {{name}} | {{share}}% | ${{avgPrice}} | {{rating}} | {{monthlySales}} | {{topAsin}} | {{positioning}} |
{{/each}}

📊 Top 10 热销产品明细：
| # | 品牌 | ASIN | 售价 | 评分 | 评论数 | 月销量 | BSR |
|---|------|------|------|------|--------|--------|-----|
{{#each top10Products}}
| {{@index+1}} | {{brand}} | {{asin}} | ${{price}} | {{rating}} | {{reviewCount}} | {{monthlySales}} | #{{bsr}} |
{{/each}}

💰 价格带分布
| 价格区间 | 产品数 | 占比 | 平均评分 | 月销量占比 | 竞争密度 |
|----------|--------|------|---------|----------|---------|
{{#each priceBands.bands}}
| ${{min}}-${{max}} | {{productCount}} | {{sharePercent}}% | {{avgRating}} | {{salesShare}}% | {{competitionLevel}} |
{{/each}}

• 🏆 黄金价格带：${{goldenPriceBand.min}}-${{goldenPriceBand.max}} (占{{goldenPriceBand.sharePercent}}%)
• 📍 你的品牌均价：${{brandAvgPrice}} → {{brandPricePosition}}
• 💡 价格空白机会：
{{#each priceGapOpportunities}}
  • ${{range}} — {{description}}
{{/each}}

📉 趋势判断
• 品类搜索趋势：{{trendDirection}}（同比{{yoyGrowthRate}}%）
• 季节性特征：{{seasonality}}
• 旺季月份：{{peakMonths}}
• Top搜索词：{{topSearchTerms}}

🏗️ 竞争格局
• 进入壁垒：{{entryBarrier}}
• 市场成熟度：{{marketMaturity}}
• FBA使用率：{{fbaAdoptionRate}}%
• 视频listing占比：{{videoAdoptionRate}}%
• A+页面占比：{{aPlusAdoptionRate}}%

⚠️ 风险预警
{{#each riskAlerts}}
• {{this}}
{{/each}}

🎯 优先行动建议
{{#each priorityActions}}
• {{this}}
{{/each}}

━━━━━━━━━━━━━━━━━━━━
```

## 校准环节（必做）

```
虾：以上是虾的分析结果。老板你是这个品类的专家，帮虾校准一下：

1️⃣ 市场规模数据和你了解的大致一致吗？
2️⃣ CR5的品牌排名对不对？有没有我漏掉的头部品牌？
3️⃣ 价格带分布符合你的体感吗？
4️⃣ 还有什么我分析里没提到但你觉得重要的？

你可以直接说"没问题"，也可以告诉我哪里需要纠偏。
```

## 校准记录
将用户反馈记录到 `memory/calibration-notes.json`:
```json
{
  "session1": {
    "timestamp": "...",
    "userFeedback": "用户原话",
    "corrections": [
      { "field": "cr5", "original": "35.2%", "corrected": "约50%", "reason": "用户说头部3家就占了一半" }
    ],
    "forwardActions": {
      "adjustForSession2": ["竞品分析时使用校准后的CR5数据", "重点关注用户提到的头部品牌"],
      "adjustForLater": []
    }
  }
}
```

**校准后必做**：更新 `calibration-notes._forwardPassSummary`，汇总本次校准的关键调整。

## 目标回扣（必做）
```
虾：🎯 回到你最初的问题：「{{workshopGoal}}」
基于品类全景分析，虾的初步回答是：
• {{goalAlignmentInsight}}
{{#if goalGapRemaining}}
不过，要更完整地回答你的问题，还需要：{{goalGapRemaining}}
这些会在后续阶段继续深入。
{{/if}}
```

## 阶段交付
1. 存储输出到 `memory/stage-1-output.json`（含 `_goalAlignment`、`_anomalies`、`_sideQuestTriggers`）
2. 更新 `workshop-progress.json` → session-1.status = "awaitingCalibration"
3. 更新 `calibration-notes._forwardPassSummary`
4. 展示交付物清单

```
虾：✅ 阶段一主线完成！

📦 已产出交付物：
• 《品类认知校准表》
• 品类核心关键词库
• 市场集中度分析
• 价格带分布图
• 趋势判断 + 风险预警

所有数据已存入记忆，后续阶段会自动引用。
```

**🛑 SESSION GATE: 此处 HARD STOP。Agent 必须停止并等待用户回复校准意见。禁止自动进入 Side Quest 菜单或 Session 2。**
**更新 workshop-progress.json: session-1.status = "awaitingCalibration"**

---

## Side Quest 发现（主线分析中自动标记）

Agent 在执行主线分析时，根据数据发现标记 Side Quest 触发器。以下为各 Side Quest 的典型触发条件：

### 🔑 关键词深潜 (keyword-deep-dive)
```
技能调用：keyword-search-trend(keywords=[触发关键词], months=12) → keyword-product-ranking(keyword, domain)
关键输出：月均搜索量+12月趋势+季节性峰值+竞争度+建议出价 | Top10产品表(ASIN+品牌+售价+评分+月销量) | 机会判断
轻量校准：这个关键词方向对你有价值吗？
```

### 🌳 品类树探索 (category-tree-explorer)
```
技能调用：category-tree(rootCategory) → category-products(categoryId, topN=20)
关键输出：品类结构地图(树形可视化) | 蓝海子品类列表(名称+竞品数+均价+月销量+机会评估)
轻量校准：这些细分赛道有你感兴趣的吗？
```

### 💰 价格带掘金 (price-band-mining)
```
技能调用：product-search(keyword, priceRange=目标价格带) → asin-sales-volume(价格带内Top产品)
关键输出：价格空白机会表(价格带+产品数+月销量+竞争密度+利润空间+评分) | 最佳切入价格点+理由
轻量校准：这个价格策略建议实际可行吗？
```

### 🏆 头部玩家解密 (top-player-decode)
```
技能调用：product-detail-query(asin) → product-deep-analysis(asin) → asin-reverse-keywords(asin)
关键输出：策略拆解(Listing+定价+流量+关键词覆盖) | 反查关键词Top10表(关键词+排名+搜索量+你的排名) | 可借鉴策略+竞争风险
轻量校准：这个分析有帮助吗？有想进一步了解的吗？
```

---

## 校准后进入探索模式

**当用户回复校准意见后，Agent 执行以下流程：**

1. 记录校准到 `calibration-notes.json`
2. 更新 `workshop-progress.json`: session-1.status = "exploring"
3. 将所有 `discovered` 的 Side Quest 状态改为 `available`
4. 按照全局规则 SQ2 展示 Side Quest 菜单

```
虾：校准意见已记录！

🗺️ 在刚才的品类分析中，虾发现了几条值得深入的线索：

┌─────────────────────────────────────────────┐
│  🎮 Side Quest 支线任务                      │
├─────────────────────────────────────────────┤
{{#each availableSideQuests}}
│  {{emoji}} {{name}}                          │
│  📍 {{trigger}}                              │
│  ⏱️ 预计 {{estimatedTime}}                   │
│                                              │
{{/each}}
├─────────────────────────────────────────────┤
│  ⏭️ 说"继续"直接进入阶段二：品牌画像+竞品       │
│  💾 说"暂停"保存进度下次再探索                   │
└─────────────────────────────────────────────┘

你对哪条线索感兴趣？选一个深入探索，或者直接继续主线。
虾建议：如果你对某个关键词或某个价格区间特别好奇，现在是最佳深入时机！
```

**当用户说"继续"时：**
- 将所有 `available` 的 Side Quest 标记为 `skipped`
- 更新 session-1.status = "completed"
- 进入 Session 2