Name: 1688-pet-product-mining
Availability: InStock
Author: skills
宠物用品爆款挖掘工具 — 整合1688-source-suppliers搜索、筛选、分析推荐、HTML报告生成和上传功能。一键完成：搜索供应商 → 按月订单数排序 → 推荐TOP N → 生成可视化报告 → 上传公网链接。适用于宠物用品（猫砂、狗粮、宠物玩具等）的供应商筛选和爆款挖掘。
SKILL.md

---
name: 1688-pet-product-mining
version: "1.0.0"
description: |
  宠物用品爆款挖掘工具 — 整合1688-source-suppliers搜索、筛选、分析推荐、HTML报告生成和上传功能。
  一键完成：搜索供应商 → 按月订单数排序 → 推荐TOP N → 生成可视化报告 → 上传公网链接。
  适用于宠物用品（猫砂、狗粮、宠物玩具等）的供应商筛选和爆款挖掘。
metadata:
  openclaw:
    emoji: "🐾"
    requires:
      bins: ["python3"]
    primaryEnv: "ALI_1688_AK"
tags: [1688, 宠物用品, 供应商筛选, 爆款挖掘, 报告生成]
trigger: 
  - 宠物用品爆款挖掘
  - 1688供应商筛选
  - 猫砂供应商
  - 狗粮供应商
  - 宠物用品供应商
  - 宠物用品找工厂
  - 宠物用品供应商报告
  - 1688宠物用品分析
---

# 宠物用品爆款挖掘工具

## 功能概述

本工具整合了1688平台供应商搜索、数据分析、可视化报告生成和公网分享功能，实现一键式宠物用品爆款挖掘工作流。

### 核心能力
- **智能搜索**：基于关键词搜索1688平台供应商
- **数据筛选**：按月订单数等关键指标排序筛选
- **智能推荐**：基于数据推荐优质供应商
- **可视化报告**：生成专业HTML分析报告
- **公网分享**：自动上传报告到公网，可直接分享

## 使用方法

### 命令行调用
```bash
python3 scripts/pet_product_mining.py "猫砂 豆腐猫砂"
python3 scripts/pet_product_mining.py "狗粮 幼犬粮" --limit 15 --top 5
```

### 参数说明
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `keyword` | 搜索关键词（必需） | - |
| `--limit` | 筛选数量限制 | 10 |
| `--top` | 推荐数量 | 3 |
| `--output` | 输出JSON文件路径 | 无（仅控制台输出） |

### 输出示例
```json
{
  "success": true,
  "keyword": "猫砂 豆腐猫砂",
  "total_suppliers": 10,
  "filtered_suppliers": 10,
  "recommended_suppliers": 3,
  "top_suppliers": [...],
  "html_report_path": "/tmp/1688_pet_mining_猫砂_豆腐猫砂_20260519_143022.html",
  "dinzee_url": "https://report.dinzee.ai/1688-pet-mining-猫砂_豆腐猫砂-20260519.html",
  "timestamp": "2026-05-19T14:30:22.123456"
}
```

## 工作流程

### 完整工作流
1. **搜索阶段**：调用1688-source-suppliers搜索供应商
2. **筛选阶段**：按月订单数降序排序，取前N条数据
3. **推荐阶段**：基于排序结果推荐TOP N供应商
4. **报告生成**：创建包含供应商卡片、数据表格、分析摘要的HTML报告
5. **上传分享**：自动上传报告到Dinzee服务器，获取公网链接

### 数据字段说明
返回的供应商数据包含以下关键字段：
- `companyName`：公司名称
- `companyUrl`：1688店铺链接
- `monthlyOrders`：近30天月订单数（核心排序指标）
- `satisfiedRate`：好评率
- `location`：所在地区
- `factoryLevel`：工厂等级
- `supportProofing`：是否支持打样
- `cooperationMode`：合作方式（OEM/ODM/OBM等）
- `services`：服务能力

## 报告特性

### HTML报告内容
1. **分析摘要**：总供应商数、筛选结果、推荐数量
2. **推荐供应商卡片**：TOP N供应商详细信息卡片
3. **完整数据表格**：所有筛选供应商的完整数据
4. **推荐理由**：数据驱动的推荐逻辑说明
5. **注意事项**：数据限制和进一步建议

### 报告设计
- 响应式设计，支持手机和电脑查看
- 专业配色方案（深蓝#0f3460 + 红#e94560）
- 交互式卡片设计，鼠标悬停有效果
- 清晰的数据可视化展示

## 依赖环境

### 必需组件
1. **1688-source-suppliers**：供应商搜索功能
   - 路径：`~/.agents/skills/1688-source-suppliers`
   - 需要配置AK：`python3 cli.py configure YOUR_AK`

2. **Dinzee上传服务**：报告上传功能
   - 默认配置，无需额外设置
   - 上传地址：`https://report.dinzee.ai/report/upload`

### Python依赖
- Python 3.6+
- 标准库（json, os, sys, subprocess, tempfile, urllib.request, uuid, argparse）

## 使用示例

### 示例1：基础猫砂供应商挖掘
```bash
python3 scripts/pet_product_mining.py "猫砂 豆腐猫砂"
```

### 示例2：狗粮供应商深度筛选
```bash
python3 scripts/pet_product_mining.py "狗粮 幼犬粮" --limit 20 --top 5
```

### 示例3：保存结果到JSON文件
```bash
python3 scripts/pet_product_mining.py "宠物玩具" --output /tmp/pet_toys_result.json
```

## 注意事项

### 数据限制
1. **价格信息**：1688-source-suppliers API不返回价格数据
2. **一件代发**：API不返回一件代发包邮信息
3. **数据量限制**：单次搜索最多返回10家供应商
4. **数据时效**：月订单数为近30天数据

> 📖 **详细 API 限制见** `references/1688-api-limitations.md`

### 进一步操作建议
1. **询盘联系**：通过1688平台链接直接联系供应商
2. **价格谈判**：询问具体价格、起批量、一件代发政策
3. **样品测试**：要求打样测试产品质量
4. **扩展搜索**：可尝试多个相关关键词获取更多供应商

## 扩展开发

### 自定义筛选逻辑
可修改`pet_product_mining.py`中的`filter_and_sort`方法实现自定义筛选：
```python
def filter_and_sort(self, limit: int = 10) -> List[Dict[str, Any]]:
    # 添加自定义筛选条件
    filtered_data = [
        supplier for supplier in self.suppliers_data
        if supplier.get('monthlyOrders', 0) > 50  # 月订单大于50
        and supplier.get('supportProofing', False)  # 支持打样
    ]
    # 然后按月订单数排序
    sorted_data = sorted(filtered_data, key=lambda x: x.get('monthlyOrders', 0), reverse=True)
    return sorted_data[:limit]
```

### 添加更多分析维度
可在HTML报告中添加更多分析维度，如：
- 地域分布分析
- 合作方式分布
- 工厂等级统计
- 历史趋势对比

## 故障排除

### 常见问题
1. **AK未配置**
   ```bash
   cd ~/.agents/skills/1688-source-suppliers
   python3 cli.py configure YOUR_AK
   ```

2. **上传失败 (HTTP 400)**
   - 可能是文件名包含中文或特殊字符
   - 使用 `--verbose` 查看详细错误
   - 检查网络连接

3. **搜索无结果**
   - 尝试更通用的关键词
   - 检查关键词是否正确
   - 确认1688平台有相关供应商

### 已知陷阱

#### Dinzee 上传 CRLF 问题
如果上传返回 HTTP 400，检查 multipart boundary 是否使用了正确的 `\r\n`（不是 `\\r\\n`）。详见 `dinzeeagent-fileupload` skill 的 pitfalls 部分。

#### 1688 搜索结果上限
单次搜索最多返回 10 家供应商，这是 API 限制。如需更多结果，需使用多个关键词扩展搜索。

## 更新日志

### v1.0.0 (2026-05-19)
- 初始版本发布
- 整合1688-source-suppliers搜索功能
- 实现供应商筛选和排序
- 生成HTML可视化报告
- 集成Dinzee上传功能
- 支持命令行参数配置

## 相关技能

### 专用版本
- **1688-pet-cat-litter-mining**：猫砂豆腐猫砂专用版本，包含更精细的7维度评分体系

### 配套使用
- **1688-product-find**：商品维度搜索，可补充商品信息
- **1688-product-sourcing**：出厂价溯源，用于利润测算
- **inquiry-1688**：供应商询盘，用于进一步联系

### 扩展方向
- 添加价格区间筛选（需配合商品搜索）
- 添加一件代发筛选（需获取更多信息）
- 多平台对比（1688 vs 其他平台）
- 历史数据跟踪和趋势分析
1688-pet-product-mining

SKILL.md

related skills
