Skip to content

LeoYeAI/agent-master-skills / skills/amazon-sorftime-research-reviews-skill

review-analysis

Verified

对亚马逊商品评论进行深度分析,自动识别产品痛点、分析退货原因,生成改进建议和客服回复模板。Invoke when user uses /review-analysis command with a product ASIN.

FileKindSize
SKILL.mdskill md16.9 KB
_meta.jsonconfig333 B
assets/email_templates/quality_issue.mdmarkdown10.2 KB
references/painpoint_taxonomy.mdmarkdown5.5 KB
设计文档.mdmarkdown14.6 KB

设计文档.md

View on GitHub
# 评论分析 Skill 设计文档 (LLM Agent 版)

## 1. 概述

**Skill 名称**: `review-analysis`

**功能描述**: 对亚马逊商品评论进行深度分析,自动识别产品痛点、分析退货原因,并生成改进建议和客服回复模板。

**触发方式**: `/review-analyse {ASIN} {SITE}`

**架构模式**: **LLM Agent 驱动** - 完全由 AI Agent 逐步执行,不依赖 Python 脚本

---

## 2. 核心架构

### 2.1 LLM Agent 工作流

```
┌─────────────────────────────────────────────────────────────────┐
│                     LLM Agent 执行流程                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐     │
│  │ Step 1  │───▶│ Step 2  │───▶│ Step 3  │───▶│ Step 4  │     │
│  │ 数据获取 │    │ 数据解析 │    │ LLM分析 │    │ 报告生成 │     │
│  └────┬────┘    └────┬────┘    └────┬────┘    └────┬────┘     │
│       │              │              │              │           │
│       ▼              ▼              ▼              ▼           │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐     │
│  │ API调用 │    │ 文件解析 │    │ 痛点分类 │    │ Markdown │     │
│  │ curl    │    │ JSON    │    │ 情感分析 │    │ 模板渲染 │     │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘     │
│       │              │              │              │           │
│       ▼              ▼              ▼              ▼           │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐     │
│  │文件保存 │    │文件保存 │    │文件保存 │    │报告文件 │     │
│  │01_*.json│    │02_*.json│    │03_*.json│    │report.md│     │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 与 Python 脚本架构的对比

| 维度 | Python 脚本架构 | LLM Agent 架构 ✅ |
|------|-----------------|-------------------|
| 执行方式 | 运行 .py 文件 | Claude AI 直接执行指令 |
| 数据处理 | 硬编码算法 | LLM 理解和分类 |
| 痛点分类 | 正则表达式匹配 | AI 语义理解 |
| 灵活性 | 需要修改代码 | 调整提示词即可 |
| 扩展性 | 需要重新编程 | 自然语言描述需求 |
| 文件生成 | 程序输出 | Agent 逐步保存 |

---

## 3. 痛点分析框架

### 3.1 五大痛点类别

| 类别 | 典型关键词 | 示例评论 |
|------|------------|----------|
| **结构/组装问题** | 孔位对不上、螺丝滑丝、安装困难、摇晃 | "孔位对不上,装不起来" |
| **电子模块故障** | USB没电、LED不亮、APP闪退、蓝牙失败 | "灯完全不亮,充不进电" |
| **设计/功能缺陷** | 抽屉浅、灯光刺眼、储物不够、线乱 | "抽屉太浅,A4纸都放不下" |
| **外观/材质问题** | 划痕、色差、异味、甲醛、生锈 | "味道很大,开窗散了3天" |
| **描述不符** | 比想象中小、颜色不一样、材质不是 | "比图片小了很多,失望" |

### 3.2 严重程度评估

| 程度 | 判断标准 | 示例 |
|------|----------|------|
| **高** | 影响核心功能或安全隐患 | "柜子散架"、"味道头晕" |
| **中** | 影响使用体验 | "安装花了两小时"、"偶尔连不上" |
| **低** | 外观细节或个人偏好 | "有个小划痕"、"我不喜欢这个颜色" |

---

## 4. 文件流转架构

### 4.1 完整文件链

```
用户输入: /review-analyse B07PWTJ4H1 US
              │
              ▼
    ┌─────────────────────────┐
    │  创建工作目录            │
    │  reports/review-analysis/│
    │  {ASIN}_{SITE}_{DATE}/  │
    └─────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────────────────────────────┐
    │ Step 1: 获取产品详情                                     │
    │ → 01_product_detail.json (ASIN, 标题, 品牌, 价格, 评分)  │
    └─────────────────────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────────────────────────────┐
    │ Step 2: 获取评论数据 (curl product_reviews API)         │
    │ → 02_reviews_raw.txt (SSE 格式原始响应)                  │
    └─────────────────────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────────────────────────────┐
    │ Step 3: 解析评论 (解码 Unicode + 修复 Mojibake)          │
    │ → 03_reviews_parsed.json (标准 JSON 格式评论数组)        │
    └─────────────────────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────────────────────────────┐
    │ Step 4: 情感统计 (计算星级分布)                          │
    │ → 04_sentiment_stats.json (好中差评数量/占比)            │
    └─────────────────────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────────────────────────────┐
    │ Step 5: 痛点分析 (LLM 深度分析每条差评)                  │
    │ → 05_painpoints_analysis.json (痛点矩阵+详细分析)        │
    └─────────────────────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────────────────────────────┐
    │ Step 6: 生成报告 (综合所有数据)                         │
    │ → report.md (完整分析报告 + 邮件模板)                    │
    └─────────────────────────────────────────────────────────┘
```

### 4.2 数据文件格式

#### 03_reviews_parsed.json (评论数据)
```json
{
  "reviews": [
    {
      "review_id": "...",
      "star_rating": 5,
      "review_date": "2024-01-01",
      "title": "Great product!",
      "content": "评论内容...",
      "is_vp": true,
      "helpful_votes": 10
    }
  ]
}
```

#### 04_sentiment_stats.json (情感统计)
```json
{
  "total_reviews": 100,
  "average_rating": 4.2,
  "rating_distribution": {
    "five_star": 60,
    "four_star": 20,
    "three_star": 10,
    "two_star": 5,
    "one_star": 5
  },
  "sentiment_breakdown": {
    "positive": 80,
    "neutral": 10,
    "negative": 10
  }
}
```

#### 05_painpoints_analysis.json (痛点分析)
```json
{
  "painpoint_matrix": [
    {
      "category": "结构/组装问题",
      "count": 15,
      "percentage": 30,
      "severity_breakdown": {"high": 5, "medium": 8, "low": 2},
      "typical_quotes": ["孔位对不上", "安装困难"]
    }
  ],
  "top_issues": [
    {
      "rank": 1,
      "category": "结构/组装问题",
      "severity": "高",
      "root_cause": {
        "design": "公差设计不合理",
        "production": "质检不到位",
        "packaging": "N/A",
        "manual": "说明书不够详细"
      },
      "improvement_suggestions": [
        "优化孔位公差",
        "在零件上标注编号"
      ],
      "customer_quotes": [
        "孔位对不上,装不起来",
        "螺丝总是滑丝"
      ]
    }
  ]
}
```

---

## 5. LLM Agent 分析流程

### 5.1 痛点分类 Prompt

当 LLM Agent 分析评论时,使用以下思维过程:

```
对于每条 1-3 星评论:

1. 阅读评论内容
2. 匹配痛点类别(5选1)
3. 评估严重程度(高/中/低)
4. 提取关键问题词
5. 分析根本原因(设计/生产/包装/说明书)
6. 生成改进建议

输出 JSON 格式
```

### 5.2 根源分析维度

| 维度 | 检查点 | 改进方向 |
|------|--------|----------|
| **设计** | 功能设计是否合理 | 修改设计方案 |
| **生产** | 质量控制是否到位 | 更换供应商/加强质检 |
| **包装** | 运输保护是否充分 | 改进包装方案 |
| **说明书** | 用户指引是否清晰 | 优化说明/提供视频 |

### 5.3 解决方案双轨制

1. **产品/供应链改进**:
   - ✅ 具体可执行: "建议将抽屉底部无纺布更换为密度板"
   - ❌ 笼统模糊: "提高质量"

2. **客服/Listing优化**:
   - 安抚话术模板
   - Listing 修改建议
   - FAQ 补充

---

## 6. 报告输出

### 6.1 报告结构

```markdown
# {产品标题} - 评论深度分析报告

## 执行摘要
## 一、评论情感分布
## 二、痛点分析矩阵
## 三、核心痛点深度分析 (Top 5)
## 四、产品改进优先级
## 五、Listing 优化建议
## 六、邮件回复模板库
```

### 6.2 邮件模板生成规则

基于痛点类别自动匹配对应模板:

| 痛点类别 | 邮件模板 | 关键要素 |
|----------|----------|----------|
| 结构/组装问题 | template_quality.md | 补发配件、技术支持 |
| 电子模块故障 | template_electronics.md | 更换控制器、故障排查 |
| 设计/功能缺陷 | template_design.md | 功能说明、使用指导 |
| 外观/材质问题 | template_quality.md | 退换货、补偿方案 |
| 描述不符 | template_design.md | 尺寸说明、预期管理 |

---

## 7. 与 amazon-analyse 的关系

### 7.1 技术架构对比

| 方面 | amazon-analyse | review-analysis |
|------|----------------|-----------------|
| 数据获取 | curl API | curl API (相同) |
| 数据解析 | SSE 解码 | SSE 解码 (相同) |
| 分析核心 | LLM Agent | LLM Agent (相同) |
| 输出报告 | Markdown | Markdown + 模板 |
| 依赖脚本 | 无 | 无 |

### 7.2 功能互补

```
amazon-analyse (竞品全维度分析)
    │
    ├─ Listing 分析
    ├─ 关键词分析
    └─ 评论分析 (Top3 优劣势)
            │
            ▼
    review-analysis (评论深度分析) ← 继承数据获取逻辑
            │
            ├─ 痛点矩阵 (5大类)
            ├─ 严重程度评估
            ├─ 根源分析
            └─ 邮件模板生成
```

---

## 8. 技术要点

### 8.1 SSE 响应处理

Sorftime 返回格式:
```
event: message
data: {"result":{"content":[{"type":"text","text":"{Unicode转义的JSON}"}]}}
```

处理步骤:
1. 提取 `data:` 行
2. 解析 JSON 获取 `text` 字段
3. 解码 Unicode 转义 (`\u4ea7\u54c1` → `产品`)
4. 修复 Mojibake 编码 (如有)
5. 保存为标准 JSON

### 8.2 编码问题处理

```python
# Unicode 解码
decoded = codecs.decode(text, 'unicode-escape')

# Mojibake 修复
fixed = bad_text.encode('latin-1').decode('utf-8')
```

### 8.3 JSON 转义处理

保存 JSON 时注意转义:
- 换行符 `\n` → `\\n`
- 引号 `"` → `\"`
- 反斜杠 `\` → `\\`

---

## 9. 使用示例

### 9.1 命令触发

```
用户: /review-analyse B07PWTJ4H1 US
```

### 9.2 Agent 执行流程

```
Agent: 开始评论分析...
Agent: ✓ 创建工作目录: reports/review-analysis/B07PWTJ4H1_US_20260315/
Agent: ✓ 获取产品详情
Agent: ✓ 获取评论数据 (100条)
Agent: ✓ 解析评论数据
Agent: ✓ 情感统计完成
Agent: ✓ 痛点分析完成 (识别5大类, 23个痛点)
Agent: ✓ 生成报告
Agent: ✓ 生成邮件模板 (3个)
Agent: 分析完成!
       报告位置: reports/review-analysis/B07PWTJ4H1_US_20260315/report.md
```

---

## 10. 目录结构

```
.claude/skills/review-analysis/
├── SKILL.md                      # 主文档 (LLM Agent 执行指令)
├── 设计文档.md                   # 本文档
├── references/
│   └── painpoint_taxonomy.md     # 痛点分类体系参考
└── assets/
    └── email_templates/
        ├── quality_issue.md      # 质量/组装问题模板
        ├── electronics_issue.md  # 电子功能故障模板
        └── expectation_gap.md    # 预期偏差模板
```

---

*文档版本: v2.0 (LLM Agent 架构)*
*最后更新: 2026-03-15*
*参考资料有: https://mp.weixin.qq.com/s/agrml8THPvCmMxOMMmxKzA
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall