amazon-sorftime-research-category-skill

\r \r

快速参考\r

\r

一键执行工作流 (推荐)\r

\r

# 使用品类名称\r
python .claude/skills/category-selection/scripts/workflow.py "Sofas" US 20\r
\r
# 直接使用 NodeID (推荐，避免类目搜索问题)\r
python .claude/skills/category-selection/scripts/workflow.py 679394011 US 20\r
\r
# 指定分析数量\r
python .claude/skills/category-selection/scripts/workflow.py "Kitchen" US 50\r
```\r
\r
**重要更新 (v4.0)**:\r
- ✅ **自动读取 API Key**: 无需设置环境变量，自动从 `.mcp.json` 读取\r
- ✅ **修复控制字符**: 自动处理 JSON 字符串值中的未转义换行符、制表符\r
- ✅ **改进类目搜索**: 支持模糊匹配和关键词变体\r
- ✅ **详细日志**: 执行日志保存到 `execution.log`\r
\r
### 核心 API 工具\r
\r
| 步骤 | 工具/操作 | 用途 | 返回数据大小 |\r
|------|----------|------|-------------|\r
| 1. 搜索类目 | `category_name_search` | 获取类目 nodeId | 小 |\r
| 2. 类目报告 | `category_report` | 获取 Top 产品列表和统计数据 | **大 (>25KB)** |\r
| 3. 产品详情 | `product_detail` | 获取单个产品详情 | 小 |\r
| 4. 类目关键词 | `category_keywords` | 获取类目核心关键词 | **大 (>25KB)** |\r
| 5. 类目趋势 | `category_trend` | 获取25个月历史趋势 | 中 |\r
| 6. 1688采购 | `products_1688` | 获取采购成本数据 | 小 |\r
\r
### 调用格式\r
```bash\r
curl -s -X POST "https://mcp.sorftime.com?key=YOUR_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{"jsonrpc":"2.0","id":N,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{"amzSite":"US","nodeId":"NODE_ID"}}}'\r
```\r
\r
---\r
\r
## 触发条件\r
\r
当用户使用以下方式请求时，启动此分析流程：\r
- **命令**: `/category-selection {品类名称} {站点} [--limit N]`\r
- **示例**: `/category-selection "Sofas" US --limit 20`\r
- **自然语言**: "分析Amazon美国站的Sofas品类"、"Sofas品类市场调研"、"Sofas品类选品"\r
\r
---\r
\r
## 角色设定\r
\r
你是一位拥有10年经验的"亚马逊选品专家"和"市场分析师"。你精通品类分析方法论，能够通过数据洞察市场机会、竞争格局和进入壁垒，为用户提供可执行的选品建议。\r
\r
---\r
\r
## 五维评分模型 (标准版)\r
\r
**评分标准详解**:\r
\r
| 维度 | 分值 | 评分标准 | 数据来源 |\r
|------|------|----------|----------|\r
| **市场规模** | 20 分 | >$10M=20分, >$5M=17分, >$1M=14分, 其他=10分 | 类目月销额 (top100产品月销额) |\r
| **增长潜力** | 25 分 | 低评论产品占比>40%=22分, >20%=18分, 其他=14分 | 评论数\x3C100的产品占比 |\r
| **竞争烈度** | 20 分 | Top3品牌占比\x3C30%=18分, \x3C50%=14分, 其他=8分 | CR3 品牌集中度 |\r
| **进入壁垒** | 20 分 | Amazon占比\x3C20%且新品>40%=20分, 其他组合6-18分 | Amazon自营占比 + 低评论占比 |\r
| **利润空间** | 15 分 | 均价>$300=12分, >$150=10分, >$50=7分, 其他=4分 | Top100产品平均价格 |\r
\r
**评级标准**:\r
\r
| 总分 | 评级 | 建议 |\r
|------|------|------|\r
| 80-100 | 优秀 | 强烈推荐进入 |\r
| 70-79 | 良好 | 可以考虑进入 |\r
| 50-69 | 一般 | 谨慎进入 |\r
| 0-49 | 较差 | 不建议进入 |\r
\r
**完整标准请参考**: [scoring-standard.md](references/scoring-standard.md)\r
\r
---\r
\r
## 完整分析流程\r
\r
### 阶段一: 数据收集\r
\r
#### 步骤 1: 搜索类目获取 nodeId\r
\r
```bash\r
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \\r
  -H "Content-Type: application/json" \\r
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"category_name_search","arguments":{"amzSite":"US","searchName":"品类关键词"}}}'\r
```\r
\r
**处理多个类目结果时**：\r
- 大类目（如 "Clothing, Shoes & Jewelry"）通常只返回子类目列表\r
- 展示给用户让其选择最匹配的类目\r
- 或使用具体的子类目 NodeID 直接查询\r
\r
**常见类目 NodeID 参考**:\r
```\r
Traditional Laptop Computers: 13896615011\r
2 in 1 Laptop Computers: 13896609011\r
Women's Fashion Sneakers: 679394011\r
Women's Road Running Shoes: 14210388011\r
Men's Fashion Sneakers: 679312011\r
Kitchen Storage Accessories: 3744031\r
```\r
\r
#### 步骤 2: 获取类目报告 (Top100 + 统计)\r
\r
```bash\r
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \\r
  -H "Content-Type: application/json" \\r
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"category_report","arguments":{"amzSite":"US","nodeId":"NODE_ID"}}}'\r
```\r
\r
**关键**: `category_report` 返回数据通常>25KB，会保存到临时文件\r
\r
**响应处理**:\r
```bash\r
# 使用 workflow.py 自动处理 (推荐)\r
python .claude/skills/category-selection/scripts/workflow.py "Sofas" US 20\r
\r
# 或手动解码 SSE 响应\r
python .claude/skills/category-selection/scripts/sse_decoder.py {temp_file} {output_dir} 20\r
```\r
\r
#### 步骤 3: 获取 Top N 产品详情 (并发)\r
\r
```bash\r
# 并发获取 Top3 产品详情\r
curl ... '{"id":3,"method":"tools/call","params":{"name":"product_detail","arguments":{"amzSite":"US","asin":"ASIN1"}}}' &\r
curl ... '{"id":4,"method":"tools/call","params":{"name":"product_detail","arguments":{"amzSite":"US","asin":"ASIN2"}}}' &\r
curl ... '{"id":5,"method":"tools/call","params":{"name":"product_detail","arguments":{"amzSite":"US","asin":"ASIN3"}}}' &\r
wait\r
```\r
\r
#### 步骤 4: 获取类目关键词 (可选)\r
\r
```bash\r
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \\r
  -H "Content-Type: application/json" \\r
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"category_keywords","arguments":{"amzSite":"US","nodeId":"NODE_ID","page":1}}}'\r
```\r
\r
**处理关键词数据**:\r
```bash\r
python .claude/skills/category-selection/scripts/keywords_parser.py \\r
  {temp_file} \\r
  {output_dir} \\r
  20\r
```\r
\r
#### 步骤 5: 获取历史趋势数据 (可选)\r
\r
```bash\r
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \\r
  -H "Content-Type: application/json" \\r
  -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"category_trend","arguments":{"amzSite":"US","nodeId":"NODE_ID"}}}'\r
```\r
\r
**趋势数据类型**:\r
- 类目月销量趋势 (25个月)\r
- 平均售价趋势\r
- 平均星级趋势\r
- 品牌数量趋势\r
\r
### 阶段二: 数据分析\r
\r
#### 核心分析指标\r
\r
**1. 市场集中度分析**\r
```python\r
# HHI 指数 (赫芬达尔-赫希曼指数)\r
# 计算: 各品牌市场份额平方和 × 10000\r
# 解读: \x3C1500=低集中度, 1500-2500=中等, >2500=高集中度\r
\r
# CR3/CR5 (前N品牌集中度)\r
# 计算: 前N大品牌销量占比\r
# 解读: \x3C30%=分散, 30-50%=中等, >50%=集中\r
```\r
\r
**2. 品牌分析**\r
```python\r
# 品牌分布: 按销量/销额排序\r
# 品牌数量: 统计独立品牌数\r
# 品牌多样性: HHI 指数评估\r
```\r
\r
**3. 卖家来源分析**\r
```python\r
# Amazon 自营占比\r
# 中国卖家占比\r
# 美国本土卖家占比\r
# 其他国际卖家占比\r
```\r
\r
**4. 价格分析**\r
```python\r
# 价格区间分布\r
# 平均价格\r
# 价格中位数\r
# 价格标准差\r
```\r
\r
**5. 新品分析**\r
```python\r
# 新产品定义: 上架时间 \x3C 90天\r
# 新品占比: 新品数量 / 总数量\r
# 新品表现: 新品平均销量、评论数\r
```\r
\r
### 阶段三: 报告生成\r
\r
#### 生成完整报告\r
\r
```bash\r
# 一键生成所有报告格式\r
python .claude/skills/category-selection/scripts/workflow.py "Sofas" US 20\r
\r
# 或分步骤生成\r
python .claude/skills/category-selection/scripts/generate_reports.py {data_json}\r
```\r
\r
**输出文件结构**:\r
```\r
category-reports/\r
└── {Category}_{Site}_{YYYYMMDD}/\r
    ├── report.md                      # Markdown 分析报告\r
    ├── data.json                      # 完整解码数据 (中文键)\r
    ├── top_products.json              # Top N 产品列表\r
    ├── scores.json                    # 五维评分结果\r
    ├── execution.log                  # 执行日志 (v4.0 新增)\r
    ├── keywords.json                  # 类目关键词\r
    ├── trend_data.json                # 25个月趋势数据\r
    ├── adapted_data.json              # Excel 适配数据 (英文键)\r
    ├── category_analysis_report.xlsx  # Excel 报告\r
    ├── dashboard.html                 # HTML 可视化仪表板\r
    ├── data/                          # 原始数据目录\r
    │   ├── statistics.csv             # 统计数据\r
    │   ├── products.csv               # 产品列表\r
    │   └── scores.csv                 # 评分详情\r
    └── *_raw.txt                      # 原始 SSE 响应\r
```\r
\r
---\r
\r
## 数据处理工具\r
\r
### 核心工具脚本\r
\r
| 脚本 | 用途 | 版本 |\r
|------|------|------|\r
| `workflow.py` | 一键执行完整分析流程 | **v4.0** |\r
| `sse_decoder.py` | 解码 category_report SSE 响应 | v6.0 |\r
| `keywords_parser.py` | 解码 category_keywords 响应 | v3.0 |\r
| `trend_parser.py` | 解析趋势数据 | v1.0 |\r
| `data_adapter.py` | 数据格式转换 (中文→英文键) | v1.0 |\r
| `data_utils.py` | 数据处理工具类 | v2.0 |\r
| `generate_reports.py` | 统一报告生成器 | v3.0 |\r
| `generate_excel_report.py` | Excel 报告生成 | v2.0 |\r
| `generate_markdown_report.py` | Markdown 报告生成 | v2.0 |\r
| `fix_encoding.py` | 编码修复工具 | v1.0 |\r
\r
### 数据字段映射\r
\r
**API 响应字段 → 标准化字段**:\r
\r
| API 字段 | 标准化字段 | 说明 |\r
|----------|-----------|------|\r
| ASIN | asin | 产品唯一标识 |\r
| 标题/title | title | 产品标题 |\r
| 价格/price | price | 当前售价 |\r
| 月销量/monthlySales | monthly_sales | 月销量 |\r
| 月销额/monthlyRevenue | monthly_revenue | 月销售额 |\r
| 评论数/reviews | review_count | 评论数量 |\r
| 星级/rating | rating | 平均评分 |\r
| 品牌/brand | brand | 品牌名称 |\r
| 卖家/seller | seller | 卖家名称 |\r
| 上架时间/daysOnline | days_online | 上架天数 |\r
\r
---\r
\r
## HTML 可视化仪表板\r
\r
### 特性\r
- 基于 ECharts 的交互式图表\r
- 五维评分可视化进度条\r
- KPI 指标卡片展示\r
- 7 个动态图表：销量趋势、价格趋势、价格分布、评分分布、品牌份额、卖家来源、品牌评分趋势\r
- Top50 产品详细表格\r
- 关键发现智能分析\r
\r
### 模板变量支持\r
\r
| 变量类型 | 示例变量 | 说明 |\r
|---------|---------|------|\r
| 基础信息 | `{{CATEGORY_NAME}}`, `{{SITE}}`, `{{DATA_DATE}}` | 报告基本信息 |\r
| 五维评分 | `{{MARKET_SIZE_SCORE}}`, `{{MARKET_SIZE_PERCENT}}` | 各维度得分和进度条百分比 |\r
| KPI指标 | `{{TOTAL_PRODUCTS}}`, `{{AVG_PRICE}}`, `{{CR3}}` | 关键指标数据 |\r
| 图表数据 | `{{SALES_TREND_DATA}}`, `{{BRAND_SHARE_DATA}}` | JavaScript JSON 数据 |\r
| 分析结论 | `{{CONCENTRATION_LEVEL}}`, `{{RECOMMENDATION}}` | 智能分析文本 |\r
\r
---\r
\r
## 故障排查\r
\r
### 常见问题与解决方案 (v4.0 更新)\r
\r
#### 1. API Key 未设置\r
**问题**: `❌ API Key 未设置` 或 `Authentication required`\r
\r
**原因**:\r
1. 环境变量 `SORFTIME_API_KEY` 未设置\r
2. `.mcp.json` 文件不存在或格式错误\r
\r
**解决方案** (v4.0 已修复):\r
- workflow.py v4.0 会自动从 `.mcp.json` 读取 API Key\r
- 确保项目根目录存在 `.mcp.json` 文件，格式如下：\r
```json\r
{\r
  "mcpServers": {\r
    "sorftime": {\r
      "url": "https://mcp.sorftime.com?key=YOUR_API_KEY"\r
    }\r
  }\r
}\r
```\r
\r
**手动设置环境变量 (备用)**:\r
```bash\r
# Windows PowerShell\r
$env:SORFTIME_API_KEY="your_api_key"\r
\r
# Linux/Mac\r
export SORFTIME_API_KEY="your_api_key"\r
```\r
\r
#### 2. JSON 解析失败 - 未转义的控制字符\r
**问题**: `JSONDecodeError: Invalid control character at: line 1 column 3401`\r
\r
**原因**: API 返回的 JSON 字符串值中包含原始的换行符（\
）、制表符（	）等控制字符，这些控制字符没有被正确转义\r
\r
**示例**:\r
```json\r
// 错误格式（API 返回的原始格式）\r
{"标题": "类目：Renewed Laptops，排名:2\r
类目：Traditional Laptops，排名:11"}\r
\r
// 正确格式\r
{"标题": "类目：Renewed Laptops，排名:2\\
类目：Traditional Laptops，排名:11"}\r
```\r
\r
**解决方案** (v4.0 已修复):\r
- `escape_control_chars_in_json_strings()` 函数自动转义字符串值内的控制字符\r
- 该函数只处理字符串值内部的控制字符，不影响 JSON 结构\r
\r
#### 3. 类目未找到\r
**问题**: 搜索类目时返回"未查询到对应类目"\r
\r
**原因**:\r
1. 大类目（如 "Computers & Accessories"）可能只返回子类目列表\r
2. 类目名称不准确\r
\r
**解决方案** (v4.0 已改进):\r
1. workflow.py v4.0 会自动尝试多种搜索变体\r
2. 使用更具体的子类目名称\r
3. **推荐**: 直接使用类目 NodeID 查询\r
\r
**获取 NodeID 的方法**:\r
```bash\r
# 先用大类目搜索，查看返回的子类目列表\r
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \\r
  -H "Content-Type: application/json" \\r
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"category_name_search","arguments":{"amzSite":"US","searchName":"Laptop"}}}'\r
```\r
\r
#### 4. 数据解析失败 (Mojibake 编码问题)\r
**问题**: data.json 中的中文显示为 "Top100产å" 等乱码\r
\r
**原因**: API 返回 Unicode-escape 格式 (\u4ea7\u54c1)，解码后产生 Mojibake\r
\r
**解决方案** (v4.0 已自动修复):\r
- `fix_mojibake()` 函数自动修复编码问题\r
- 在 Unicode-escape 解码后立即应用 `.encode('latin-1').decode('utf-8')`\r
\r
#### 5. Python dict 格式问题\r
**问题**: "Expecting property name enclosed in double quotes"\r
\r
**原因**: API 返回 Python dict 格式（单引号），不是标准 JSON\r
\r
**解决方案** (v4.0 已修复):\r
- `python_dict_to_json()` 函数正确处理单引号转换\r
- 同时处理 True/False/None 字面量\r
\r
#### 6. 大类目搜索失败\r
**问题**: "Computers & Accessories" 等大类目搜索无结果\r
\r
**解决方案**:\r
1. 使用子类目名称（如 "Laptops", "Computer Accessories"）\r
2. 先搜索大类目获取子类目列表，让用户选择\r
3. 直接使用已知 NodeID\r
\r
### 版本更新记录\r
\r
| 脚本 | 版本 | 更新内容 |\r
|------|------|----------|\r
| `workflow.py` | **v4.0** | ✅ 从 .mcp.json 自动读取 API Key\x3Cbr>✅ 修复 JSON 字符串中未转义的控制字符\x3Cbr>✅ 改进类目搜索策略\x3Cbr>✅ 新增执行日志\x3Cbr>✅ 更详细的错误信息 |\r
| `sse_decoder.py` | v6.0 | Mojibake 自动修复、括号匹配、Python dict 转换 |\r
| `generate_reports.py` | v3.0 | 完整变量替换、分析文本生成 |\r
\r
### 调试技巧\r
\r
1. **查看执行日志**:\r
```bash\r
# workflow.py v4.0 会自动保存执行日志\r
cat category-reports/{Category}_{Site}_{YYYYMMDD}/execution.log\r
```\r
\r
2. **查看原始响应**:\r
```bash\r
# workflow.py 会自动保存原始 SSE 响应\r
cat category-reports/{Category}_{Site}_{YYYYMMDD}/category_report_raw.txt\r
```\r
\r
3. **检查编码问题**:\r
```python\r
# 检查文件字节\r
with open('data.json', 'rb') as f:\r
    print(f.read(100))\r
```\r
\r
4. **验证 JSON 格式**:\r
```bash\r
# 使用 Python 验证 JSON\r
python -m json.tool data.json\r
```\r
\r
5. **测试 API 连接**:\r
```bash\r
curl -s -X POST "https://mcp.sorftime.com?key={YOUR_KEY}" \\r
  -H "Content-Type: application/json" \\r
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"category_name_search","arguments":{"amzSite":"US","searchName":"Kitchen"}}}'\r
```\r
\r
---\r
\r
## 支持的站点\r
\r
**Amazon**: US, GB, DE, FR, IN, CA, JP, ES, IT, MX, AE, AU, BR, SA\r
**TikTok**: US, GB, MY, PH, VN, ID\r
**1688**: 中国批发平台\r
\r
---\r
\r
## 注意事项\r
\r
1. **API Key 配置**:\r
   - 推荐在 `.mcp.json` 中配置（v4.0 自动读取）\r
   - 也可以使用环境变量 `SORFTIME_API_KEY`\r
2. **参数名称**: 使用 `amzSite` 而非 `site`\r
3. **id 递增**: 每个请求的 `id` 字段必须递增 (1, 2, 3...)\r
4. **并发限制**: 建议最多 3-5 个并发请求\r
5. **数据时效**: 数据可能有 1-7 天延迟\r
6. **报告命名**: 使用 `{Category}_{Site}_{YYYYMMDD}` 格式\r
\r
---\r
\r
## 参考文档\r
\r
- [评分标准详解](references/scoring-standard.md)\r
- [API 快速参考](references/api-quick-reference.md)\r
- [Sorftime MCP API 文档](references/sorftime-mcp-api.md)\r
- [类目 API 参考](references/category-api-reference.md)\r
\r
---\r
\r
*本 Skill 由 Claude Code 维护 | 最后更新: 2026-03-05 (v4.0)*\r