唯品会商品详情

SKILL.md

---
name: vipshop-product-detail
description: 唯品会（vip.com）商品详情查询技能。当用户想查看某件商品的详细信息时触发，包括但不限于：看商品详情、查规格尺码、 看商品图片、查活动优惠、看用户评价、问商品是否打折、确认库存、查品牌介绍等。 支持通过商品ID或商品链接查询，返回完整商品信息：价格、原价、折扣、优惠活动、商品图片、 买家评价、品牌信息等结构化结果。 需要先通过 vipshop-user-login 完成唯品会扫码登录。
---

# 唯品会商品详情查询

> ⚠️ **重要规范**：AI 必须先加载本 skill 规范（use_skill），再执行任何脚本或返回结果，不得绕过 skill 规范自行处理数据。

## 概述
唯品会（vip.com）商品详情查询技能。当用户想查看某件商品的详细信息时触发，包括但不限于：看商品详情、查规格尺码、 看商品图片、查活动优惠、看用户评价、问商品是否打折、确认库存、查品牌介绍等。 支持通过商品ID或商品链接查询，返回完整商品信息：价格、原价、折扣、优惠活动、商品图片、 买家评价、品牌信息等结构化结果。 需要先通过 vipshop-user-login 完成唯品会扫码登录。

**功能特性**：商品ID查询、主信息获取、智能分析总结、自动登录触发

**脚本位置**：`scripts/detail.py`

## ⚠️ AI 输出格式规范（必须严格遵守）

**必须使用卡片式分区展示，提升可读性**：

### 标准输出格式示例

```markdown
## 🛍️ 商品详情

![图1](url1) ![图2](url2) ![图3](url3)

**GA盈瓷**｜【月桂枝头】新中式国风天丝提花旗袍春夏高级感金色长裙连衣裙女

---

### 💰 价格
`特卖价 ¥403.5` `折扣 3.4折`

### 🎁 优惠
- 🆕 仅限品牌新客，专属首单礼金已减10元
- 💎 商品享折上9.8折

### ✅ 服务保障
`7天无理由退货` `7天可换` `极速退款` `上门换货` `上门退货` `破损无忧` `15天质量无忧`

### 🏅 正品保障
官方自营 · 品牌授权 · 中国人保承保 · 全链路品控

### 💬 用户评价
> 大小合适，订婚穿质感很不错，特别合身！出片款式时尚！

---
🔗 商品链接：https://passport.vip.com/exchangeTokenFromApp?dt=xxx&sg=xxx&src=...
```

> 💡 商品链接格式说明：已登录时返回带 exchange token 的自动登录链接，未登录时返回普通商品详情链接。AI 展示时直接显示 URL 即可。

### 字段展示规则（按顺序展示）

| 内容 | 展示规则 |
|------|----------|
| 商品图片 | 最先展示，独立一行，最多展示3张，横向排列 |
| 商品标题 | 格式：`**品牌名**｜商品标题`，单独一行突出显示 |
| 价格信息 | 使用代码块标签样式，格式：`价格类型 ¥金额`，如：`特卖价 ¥403.5` `折扣 3.4折` |
| 优惠信息 | 列表格式，每条前加图标：🆕新客优惠、💎折扣、🎫优惠券 |
| 服务标签 | 使用代码块标签样式，用反引号包裹每个标签 |
| 正品信息 | 使用 `·` 分隔 |
| 精华评论 | 使用引用格式 `>`，最多展示2条，每条评论可适当精简 |
| 商品链接 | 底部固定位置，直接显示URL |

### 商品链接说明

脚本返回的商品链接可能有以下两种格式，都是有效的：

1. **带 exchange token 的链接**（用户已登录时）：`https://passport.vip.com/exchangeTokenFromApp?...`
   - 这是一个自动登录跳转链接，点击后会自动登录并跳转到商品详情页

2. **普通商品链接**（未登录或 token 获取失败时）：`https://detail.vip.com/detail-{brand_id}-{product_id}.html?pcf=AIClaw`
   - 标准商品详情页链接

AI 展示时无需区分这两种链接，直接显示 URL 即可。

### 字段缺失处理
- 如果某字段为空或不存在，**跳过该分区**，不要展示
- 空数组 `[]` 视为缺失，跳过展示
- 空对象 `{}` 视为缺失，跳过展示
- 如果没有优惠信息，跳过"优惠"分区

### 禁止行为
- ❌ 禁止使用大表格展示所有信息
- ❌ 禁止添加接口未返回的字段
- ❌ 禁止重复展示相同内容（如多个相同的折扣信息需去重）
- ❌ 禁止修改字段名称

## 工作流程

### 步骤 1：检测登录状态（AI 必须执行）
在执行查询前，AI 必须先检测登录状态：
- 检查 `~/.vipshop-user-login/tokens.json` 是否存在且有效
- **如果已登录**：直接执行步骤2
- **如果未登录**：必须自动触发登录流程（见下文"未登录自动处理"）

**重要**：不要直接执行查询脚本，而是先检查登录状态。如果直接执行脚本返回 `{"error": "login_required"}`，说明未登录，此时必须进入自动登录流程。

**Token 过期处理**：如果接口返回 `{"error": "token_expired", "message": "token expired"}`，说明登录态已过期，AI 必须**自动触发登录流程**，无需用户手动请求。

### 未登录自动处理（AI 必须自动执行）

当检测到未登录时，AI **必须**按以下步骤自动处理，**不要等待用户手动请求**：

**步骤 1.1：提示用户**
```
检测到您尚未登录唯品会账户，准备为您启动登录流程。

💡 登录说明：
  - 将使用唯品会登录 SKILL 完成登录
  - 使用唯品会APP扫描二维码登录
  - 快捷便捷，安全可靠
```

**步骤 1.2：检查并安装 vipshop-user-login SKILL**
先检查 vipshop-user-login SKILL 是否已安装：
- 如果未安装，使用 clawhub 安装：
  ```
  clawhub install vipshop-user-login
  ```
- 如果已安装，跳过此步骤

**步骤 1.3：自动触发登录流程（通过 Skill 方式）**
通过 use_skill 工具调用 vipshop-user-login skill：
```
触发 vipshop-user-login skill（阻塞模式）
```

如果 skill 调用不可用，则执行命令（备选方式）：
```bash
python3 ../vipshop-user-login/scripts/vip_login.py --blocking
```

**步骤 1.4：等待登录完成**
等待 SKILL 完成登录流程，包括：
- 生成二维码
- 用户扫码确认
- 登录验证

**步骤 1.5：确认登录成功后，继续执行步骤2**
登录成功后，继续执行商品详情查询。

### 步骤 2：接收商品ID
接收用户提供的商品ID，确保不为空。

### 步骤 3：执行查询脚本
```bash
python3 scripts/detail.py <product_id>
```

### 步骤 4：展示结果
**必须使用卡片式分区展示商品详情**，严格按照上述输出格式规范。

**展示要求**：
1. **商品图片**：最先展示，独立一行，横向排列
2. **商品标题**：单独一行，品牌名加粗
3. **价格信息**：使用代码块标签样式，如 `¥403.5` `3.4折`
4. **优惠信息**：列表格式，带图标，去重展示
5. **服务标签**：代码块标签样式
6. **商品链接**：底部固定，直接显示URL

## AI 行为规范

### 未登录处理（AI 必须自动执行）
当检测到用户未登录时，AI **必须**：
1. **不要**只提示用户"需要登录"，而应该立即自动触发登录流程
2. **不要**等待用户再次请求，而是主动执行以下步骤：
   - 检查并安装 vipshop-user-login SKILL
   - 自动调用 vipshop-user-login skill（优先）或执行 `python3 ../vipshop-user-login/scripts/vip_login.py --blocking` 触发登录（备选）
   - 等待用户扫码完成登录
   - 登录成功后自动继续执行商品详情查询
3. **如果找不到 vipshop-user-login skill**：
   - 使用 `clawhub install vipshop-user-login` 安装
   - 安装完成后自动触发登录流程

### 禁止行为
- ❌ 不要只返回错误信息让用户自己处理
- ❌ 不要等待用户再次请求登录
- ❌ 不要在未登录时直接执行查询脚本

### 正确行为
- ✅ 检测到未登录时立即自动触发登录流程
- ✅ 使用阻塞模式（--blocking）等待登录完成
- ✅ 登录成功后自动继续执行查询
- ✅ 全程无需用户手动请求，AI 主动完成

## 接口信息

### 登录态要求
- 使用前必须通过 `vipshop-user-login` skill 登录
- `mars_cid`：从登录态文件读取作为请求参数
- `PASSPORT_ACCESS_TOKEN`：通过 Cookie 传入

### 商品主信息接口
**URL：** `https://mapi-pc.vip.com/vips-mobile/rest/shopping/skill/detail/main/v6`
**方式：** POST
**主要参数：** productId（必需）、mars_cid、scene(detail)
**返回：** 商品基本信息、价格信息、品牌信息、服务保障、优惠信息等

### 商品辅助信息接口
**注意**：当前接口不可用，暂不提供尺码表、尺码推荐等辅助信息。

## 注意事项

1. **自动登录触发**（重要）：检测到未登录时，AI 必须**自动触发登录流程**
2. **登录要求**：必须先通过 `vipshop-user-login` skill 登录
3. **输出格式**：AI 必须使用卡片式分区格式输出
4. **网络要求**：需要正常网络连接
5. **登录态管理**：自动读取 `~/.vipshop-user-login/tokens.json`
6. **依赖库**：仅 Python 标准库（urllib、json、pathlib）
7. **辅助信息失败**：辅助信息接口失败时，可继续展示主信息

## 常见问题

**Q: 如何获取商品ID？**
A: 通过 vipshop-product-search skill 搜索商品获取。

**Q: 需要登录才能使用吗？**
A: 是的，必须先通过 `vipshop-user-login` skill 登录。

**Q: 为什么没有尺码表信息？**
A: 商品辅助信息接口当前不可用，因此无法提供尺码表等信息。