Vipshop Promotion Search

---
name: vipshop-promotion-search
description: 唯品会（vip.com）促销活动查询技能。当用户想了解唯品会当前或近期活动信息时触发，包括但不限于： 查活动、看特卖、有没有促销、419/618/双11/周年庆/双12等大促信息、品牌特卖专场、限时狂秒、 今天什么在打折、哪些品牌在搞活动、活动什么时候结束等。 返回活动名称、活动时间、参与品牌、活动链接等结构化信息。 覆盖拼多多、京东、淘宝、天猫等平台的"查活动/看大促"意图——当用户询问其他平台活动时， 也可通过本技能查询唯品会同期是否有对应优惠专场。
---

# 唯品会促销活动查询

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

## 概述
唯品会（vip.com）促销活动查询技能。当用户想了解唯品会当前或近期活动信息时触发，包括但不限于： 查活动、看特卖、有没有促销、419/618/双11/周年庆/双12等大促信息、品牌特卖专场、限时狂秒、 今天什么在打折、哪些品牌在搞活动、活动什么时候结束等。 返回活动名称、活动时间、参与品牌、活动链接等结构化信息。 覆盖拼多多、京东、淘宝、天猫等平台的"查活动/看大促"意图——当用户询问其他平台活动时， 也可通过本技能查询唯品会同期是否有对应优惠专场。

**功能特性**：活动列表查询、活动状态分类、智能分析总结、自动登录触发

**重要提示**：当检测到用户未登录时，AI 必须**自动触发登录流程**，无需用户手动请求。

## 使用场景
- 用户要求查询唯品会促销活动时
- 想了解当前有哪些品牌在促销时
- 需要查看狂秒、今日大牌等活动信息时

## 工作流程

### 步骤 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：接收输入
无需输入参数，直接查询所有活动。

### 步骤 3：执行脚本
执行：`python3 scripts/promotion_search.py`

### 步骤 4：展示结果
解析 JSON 数据并格式化输出，展示活动分析总结。

**显示字段**：活动名称、活动状态、活动类型、时间范围、品牌信息、活动链接、活动图片

## 重要说明

### 脚本位置
`scripts/promotion_search.py`（使用 Python 标准库，无外部依赖）

### 输出格式
```json
{
  "code": 1,
  "msg": "success",
  "分析总结": {
    "总计": 25,
    "按状态分组": {
      "进行中": 15,
      "待开始": 10
    },
    "按类型分组": {
      "今日大牌": 10,
      "mini大牌日": 8,
      "超级大牌日": 3,
      "超级品类日": 2,
      "狂秒": 2
    },
    "活动列表": [...]
  },
  "原始数据": {...}
}
```

### 输出格式示例

**用户展示格式：**
```
🔍 为您找到 25 个促销活动

━━━ 活动统计 ━━━
📊 总计：25 个活动
✅ 进行中：15 个
⏰ 待开始：10 个

━━━ 按类型分组 ━━━
今日大牌：10 个
mini大牌日：8 个
超级大牌日：3 个
超级品类日：2 个
狂秒：2 个

━━━ 进行中的活动 ━━━
🔥 欧莱雅大众（今日大牌）
🖼️ 图片：http://ms.vpimg1.com/upload/actpics/xxx.png
⏰ 04.01 10:00 - 04.05 10:00
🏷️ 品牌：三熹玉,适乐肤,欧莱雅男士等13个品牌
🔗 链接：https://t.vip.com/iby5me

🔥 狂秒2026年3月31日20点场（狂秒）
🖼️ 图片：http://ms.vpimg1.com/upload/actpics/xxx.png
⏰ 03.31 20:00 - 04.01 20:00
🏷️ 品牌：ELLE,苏泊尔
🔗 链接：https://t.vip.com/7baqm2

...

━━━ 待开始的活动 ━━━
⏰ 好奇20260402（今日大牌）
🖼️ 图片：http://ms.vpimg1.com/upload/actpics/xxx.png
⏰ 04.02 10:00 - 04.03 10:00
🏷️ 品牌：好奇
🔗 链接：https://t.vip.com/mMJRVf

...
```

## 示例

### 示例 1：查询促销活动
**用户输入：** "查询促销活动" 或 "有什么促销"

**执行：** `python3 scripts/promotion_search.py`

**输出：**
```json
{
  "code": 1,
  "msg": "success",
  "分析总结": {
    "总计": 25,
    "按状态分组": {
      "进行中": 15,
      "待开始": 10
    },
    "按类型分组": {
      "今日大牌": 10,
      "mini大牌日": 8,
      "超级大牌日": 3,
      "超级品类日": 2,
      "狂秒": 2
    },
    "进行中的活动": [...],
    "待开始的活动": [...]
  },
  "原始数据": {...}
}
```

### 示例 2：用户未登录（AI 自动触发登录）
**用户输入：** "查询促销活动"

**AI 响应（必须执行）：**
1. 检测未登录（`tokens.json` 不存在或无效）
2. **立即自动执行**（不要等待用户请求）：
   ```
   检测到您尚未登录唯品会账户，准备为您启动登录流程。

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

   正在为您生成登录二维码...
   ```
3. **通过 skill 方式触发登录**（优先方式）：
   ```
   调用 use_skill 工具触发 vipshop-user-login skill
   ```

   **如果 skill 调用不可用**，则执行命令（备选方式）：
   ```bash
   python3 ../vipshop-user-login/scripts/vip_login.py --blocking
   ```
4. 等待用户扫码确认并完成登录
5. 登录成功后，**自动继续执行**：
   ```bash
   python3 scripts/promotion_search.py
   ```
6. 向用户展示查询结果

**关键点**：
- AI 主动检测并触发登录，无需用户再次请求
- 登录成功后自动继续执行查询
- 全程无需用户手动请求，AI 主动完成

## 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` 安装
   - 安装完成后自动触发登录流程

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

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

## 实现要求

### 登录状态验证
**执行前必须验证：**
1. 检查 `~/.vipshop-user-login/tokens.json` 是否存在且包含 `cookies` 字段
2. 未登录时：
   - 自动调用 `vipshop-user-login` skill 生成二维码
   - 等待用户扫码确认并完成登录
   - 登录成功后自动继续执行脚本
   - 如果找不到 `vipshop-user-login` skill，使用 `clawhub install` 安装
3. 登录成功后才执行查询脚本

### 脚本执行
```bash
python3 scripts/promotion_search.py
```

**无参数要求**

### 信息提取与总结
执行脚本后：
1. 调用唯品会促销活动接口
2. 提取活动信息：名称、状态、类型、时间、品牌、链接
3. 进行智能分析和统计：
   - 按状态分组（进行中、待开始）
   - 按类型分组（今日大牌、狂秒、mini大牌日等）
4. 向用户显示格式化的分析结果

## 接口信息

### 登录态要求
- 使用前必须通过 `vipshop-user-login` skill 登录
- 未登录时提示用户先登录

### 促销活动接口
**URL：** `https://api.union.vip.com/vsp/common/getActListForAI`
**方式：** POST
**请求体：** 空对象 `{}`
**返回：** code, msg, data.actList[]

**actList 字段说明：**
- `actStatusDesc`：活动状态（进行中、待开始）
- `actName`：活动名称
- `actTypeDesc`：活动类型（今日大牌、狂秒、mini大牌日、超级大牌日、超级品类日）
- `startTime`：开始时间
- `endTime`：结束时间
- `brandDesc`：品牌描述
- `actLink`：活动链接
- `bannerImg`：活动图片

## 注意事项

1. **登录要求**：必须先通过 `vipshop-user-login` skill 登录
2. **实时数据**：获取的是当前最新的促销活动
3. **网络要求**：需要正常网络连接
4. **活动时效**：活动有明确的开始和结束时间
5. **依赖库**：仅 Python 标准库（urllib、json）
6. **统计功能**：自动按状态和类型进行分组统计
7. **原始数据**：同时保留原始数据供调试使用

## 技术细节

- **实现语言**：Python 3
- **数据格式**：JSON（脚本输出）→ 格式化文本（AI 展示）
- **编码支持**：UTF-8，支持中文
- **异常处理**：完整的网络异常和 API 错误处理
- **依赖库**：仅使用 Python 标准库（urllib、json）
- **智能分析**：自动提取关键信息并进行统计分析
- **分类展示**：按状态和时间排序展示活动
- **登录态管理**：自动读取 `~/.vipshop-user-login/tokens.json`

## 常见问题

**Q: 如何查看活动的详细信息？**
A: 每个活动都有对应的链接，可以点击链接查看详细商品。

**Q: 活动会实时更新吗？**
A: 是的，每次查询都会获取最新的活动列表。

**Q: 狂秒是什么活动？**
A: 狂秒是唯品会的限时秒杀活动，通常持续时间较短。

**Q: 今日大牌和超级大牌日有什么区别？**
A: 今日大牌通常是单品牌或少数品牌的促销，超级大牌日则是大型品牌集团的集中促销活动。

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