Skill: skyfile/online-shopping-discount (version 1.0.2)

--- name: online-shopping-discount description: 在有购物需求的情况下，提供查找优惠商品信息、生成优惠建议和优惠链接的能力。支持商品搜索、价格比较、优惠推荐和链接生成。 --- # 在线购物优惠查询技能 这个技能使 AI 能够帮助用户查找优惠商品、比较价格、生成优惠链接，提供智能购物建议。 ## 技能描述 本技能提供完整的优惠商品查询流程： 1. 注册并获取合法身份凭证 2. 使用凭证和关键词查询商品信息 3. 分析并推荐优惠商品 4. 生成优惠优惠链接 ## 适用场景 - 用户询问某类商品的优惠信息 - 用户需要比较不同平台的商品价格 - 用户想要获取商品的优惠链接 - 用户需要购物建议和优惠推荐 ## 触发关键词 ``` 优惠, 折扣, 商品搜索, 购物, 推荐, 比价, 淘宝, 京东, 拼多多, 买, 便宜, buy, discount, shopping, product search, deals, promotion ``` ## 前置条件 - 需要有效的 API 凭证（通过注册流程获取） - 网络连接正常 - 查询脚本和链接生成脚本已配置 ## 技能实现 ### 工作流程 ``` ┌─────────────────┐ │ 1. 注册认证 │ │ 获取凭证 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 2. 商品查询 │ │ 使用凭证调用 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 3. 分析推荐 │ │ 筛选优惠商品 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 4. 用户确认 │ │ 选择商品 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 5. 生成链接 │ │ 返回优惠链接 │ └─────────────────┘ ``` ### 核心脚本 #### 1. 注册认证脚本 ```bash # scripts/register.sh # 用途：注册并获取 API 凭证 ``` #### 2. 商品查询脚本 ```bash # scripts/search_products.sh # 用途：根据关键词查询商品信息 ``` #### 3. 链接生成脚本 ```bash # scripts/generate_link.sh # 用途：为选定商品生成优惠优惠链接 ``` ### 参数说明 #### 商品查询参数 | 参数名 | 类型 | 必填 | 说明 | 示例 | |--------|------|------|------|------| | credential | string | 是 | 注册脚本返回的 UUID，实际请求会自动复用 | 'token_xxx' | | keyword | string | 是 | 商品搜索关键词 | '无线耳机' | | platform | string | 否 | 平台参数（当前仅支持 `taobao` 与 `jd`，默认 `taobao`，可在拿到结果后再二次筛选） | 'taobao', 'jd' | | user_id | string | 否 | 自定义 user_id（默认与 credential 相同） | 'demo-user' | | start_price | number | 否 | 最低成交价（仅在用户要求限定下限时传入） | 100 | | end_price | number | 否 | 最高成交价（仅在用户要求限定上限时传入） | 500 | #### 链接生成参数 | 参数名 | 类型 | 必填 | 说明 | 示例 | |--------|------|------|------|------| | product_id | string | 是 | 商品ID | '12345678' | | platform | string | 是 | 商品平台（脚本默认 `taobao`，可通过 `--platform` 覆盖为 `jd`） | 'taobao', 'jd' | | credential | string | 是 | API凭证 | 'token_xxx' | ## 使用步骤 ### 步骤 1: 注册并获取凭证 ```bash # 调用注册脚本（首次会注册，后续会使用缓存） ./scripts/register.sh # 返回示例 { "result": "success", "data": { "uuid": [REDACTED_SECRET], "username": "dafasdfsadfsa" } } # 可选参数 ./scripts/register.sh --force # 强制重新注册 ./scripts/register.sh --clear-cache # 清除本地缓存 ``` **凭证缓存机制：** - 首次调用会向服务端注册并获取凭证 - 凭证会自动保存到本地文件 `.credential_cache` - 后续调用会优先使用缓存的凭证 - 凭证过期前1小时会自动重新注册 - 缓存文件权限设置为 600（仅所有者可读写） ### 平台偏好与查询策略 1. **先问偏好**：首次对话或用户未说明平台时，主动询问“更偏好淘宝、京东，还是都看看？”。如果用户给出明确选择，就沿用该平台；若回答“都可以”，则在当前会话记为“both”。 2. **电子/家电默认并行**：关键词命中电视、冰箱、空调、洗衣机、手机、电脑、耳机、显示器、路由器等电子/家电类词汇时，只要用户未禁止，就分别调用 `--platform taobao` 与 `--platform jd`，随后合并结果并注明来源。 3. **其他品类**：沿用用户偏好；若还未知，可默认淘宝并在回复中提示“如需京东价格请告诉我”。 4. **偏好切换**：用户随时可以重新指定平台，AI 必须立即切换并在下一轮结果中确认“已按照XX平台重新查询”。 ### 步骤 2: 查询商品信息 ```bash # 使用凭证查询商品 ./scripts/search_products.sh \ --credential "token_abc123xyz" \ --keyword "无线耳机" \ --platform "taobao" # 只有在用户需要限定成交价区间时才补充以下参数 # ./scripts/search_products.sh ... --start_price 200 --end_price 500 ``` **并行示例（电子/家电场景）** ```bash TAOBAO_RESULT=$(./scripts/search_products.sh \ --credential "$CREDENTIAL" \ --keyword "65寸电视" \ --platform "taobao") JD_RESULT=$(./scripts/search_products.sh \ --credential "$CREDENTIAL" \ --keyword "65寸电视" \ --platform "jd") ``` > 平台选择目前只支持 `taobao` 与 `jd`，若用户倾向京东请显式传入 `--platform "jd"`。 > > `start_price` / `end_price` 默认不需要传入，除非用户明确要求限定成交价区间。 **返回示例** { "result": "success", "data": { "total": 70342, "products": [ { "item_id": [REDACTED_SECRET], "title": "商品完整标题", "short_title": "商品短标题", "pict_url": "https://item_pic.jpg", "reserve_price": "247.76", "zk_final_price": "127.65", "final_promotion_price": "71.65", "income_rate": "1.5", "commission_amount": "1.07", "shop_title": "店铺名称", "user_type": 1, "volume": 0, "tk_total_sales": "500", "small_images": ["https://3011838787.jpg"], "promotion_tags": [ "淘金币频道抵扣1.28元起", "40元", "满1件8.75折", "包邮" ], "category_name": "厨房置物架/置物柜/角架", "brand_name": "家图腾", "final_promotion_list": [ { "promotion_title": "商品券", "promotion_desc": "满108减40", "promotion_fee": "40", "promotion_start_time": "1773072000000", "promotion_end_time": "1773935999000", "promotion_id": [REDACTED_SECRET] } ], "best_promotion_id": [REDACTED_SECRET], "best_promotion": { "promotion_title": "商品券", "promotion_desc": "满108减40", "promotion_fee": "40", "promotion_start_time": "1773072000000", "promotion_end_time": "1773935999000", "promotion_id": [REDACTED_SECRET] } } ] } ``` ### 步骤 3: 分析并推荐商品 AI 根据以下维度分析商品： - 折扣力度（优先推荐折扣大的） - 销量和评价（确保商品质量） - 价格区间（符合用户预算） - 性价比（综合评分） - 图片与卖点（参考 `pict_url`、`short_title`） - 价格结构（原价 `reserve_price`、优惠价 `zk_final_price`、成交价/券后价 `final_promotion_price`） - 平台信誉/物流（结合 `platform` 字段，提示淘宝/京东在售后或发货速度上的差异） **展示形态要求：** 1. 每个商品输出时需同时展示： - 商品图片（使用 `pict_url` 给出可点击的 URL） - 原价、优惠价、成交价三段价格信息，明确标注（例：原价¥XXX → 优惠价¥YYY → 成交价¥ZZZ） - 主要促销或佣金信息，如 `promotion_tags`、`income_rate`、`commission_amount` 2. 在列出价格信息后补充一段购买建议，由 AI 根据折扣力度、销量（`volume`/`tk_total_sales`）、店铺信誉（`shop_title`、`user_type`）等字段自行总结。例如提示“折扣翻半且销量 1w+，适合追求性价比”。 3. 建议段落必须说明推荐理由（折扣、销量、品牌或场景），无需脚本额外字段，完全由 AI 归纳。 4. 如果列表混合了淘宝和京东，务必在标题或首行标记“【淘宝】/【京东】”，并说明物流与售后差异。 ### 步骤 4: 用户确认选择 向用户展示推荐商品列表，等待用户选择： ``` 我为您找到以下优惠商品： 1. 某品牌无线蓝牙耳机 - 价格：¥299（原价 ¥599，5折） - 销量：10000+ - 评分：4.8/5.0 - 平台：淘宝 2. 另一品牌降噪耳机 - 价格：¥399（原价 ¥699，5.7折） - 销量：5000+ - 评分：4.9/5.0 - 平台：京东（自营，物流更快） 请问您想要哪一款的优惠链接？ ``` 在对商品做推荐时，优先读取 `best_promotion_id`/`best_promotion` 字段：这是脚本根据可用促销列表自动挑选出的“最划算活动”。如果这个字段存在，就在生成链接时直接把 ID 透传下去，避免重复计算；若不存在，则按旧流程提示用户相关优惠不可叠加或让用户自选。 ### 步骤 5: 生成优惠链接 ```bash # 为用户选择的商品生成链接 ./scripts/generate_link.sh \ --credential "token_abc123xyz" \ --product_id "12345678" \ --platform "taobao" \ --promotion_id [REDACTED_SECRET] # 返回示例 { "status": "success", "product_id": "12345678", "link_type": "both", "url": "https://xxxxx.html", "code": "￥f7B4UETZsMl￥", "expire_time": "2026-03-16T00:00:00Z", "user_id": "token_abc123xyz" } ``` > 兼容参数：`--activity_id` 仍可使用，但会提示逐步改用 `--promotion_id`。当搜索结果未包含最佳活动 ID 时，可省略该参数，后端将按默认活动生成链接。 ## 示例对话流程 ### 场景 1: 用户查询特定商品 ``` 用户: 帮我找一下无线耳机的优惠 AI: 1. [调用注册脚本获取凭证] 2. [使用凭证查询"无线耳机"] 3. [分析商品数据] 4. 我为您找到了几款优惠的无线耳机： 1. 某品牌无线蓝牙耳机 - ¥299（5折） 2. 另一品牌降噪耳机 - ¥399（5.7折） 请问您想要哪一款的购买链接？ 用户: 第一款 AI: [调用链接生成脚本] 已为您生成优惠链接：https://s.click.taobao.com/xxx 这个链接7天内有效，点击即可享受优惠价格。 ``` ### 场景 2: 用户指定价格区间 ``` 用户: 帮我找200-400元的蓝牙音箱 AI: [执行完整流程，调用 `./scripts/search_products.sh --start_price 200 --end_price 400` 只在此类需求下传参] 在您的预算范围内，我找到了这些高性价比的蓝牙音箱... ``` ## AI 执行指南 ### 必须遵循的流程 1. **获取有效凭证** - 首次使用时调用注册脚本获取凭证 - 凭证会自动缓存到本地，后续直接使用 - 无需每次会话都重新注册 - 凭证过期时会自动重新注册 2. **查询前理解用户需求** - 提取关键词（商品类型） - 识别价格区间 - 了解平台偏好 3. **智能推荐** - 优先推荐折扣力度大的 - 考虑销量和评价 - 最多推荐 3-5 款商品 4. **等待用户确认** - 不要自动生成链接 - 让用户选择具体商品 - 确认后再生成链接 5. **清晰展示信息** - 使用结构化格式 - 突出价格和折扣 - 提供必要的商品信息 ### 推荐话术模板 ``` 我为您找到了 [数量] 款符合条件的优惠商品： [序号]. [商品标题] - 图片： ![商品图片]([pict_url]) - 价格：原价 ¥[reserve_price] → 优惠价 ¥[zk_final_price] → 成交价 ¥[final_promotion_price] - 销量：[volume]/淘客销量 [tk_total_sales] - 店铺：[shop_title]（[天猫/淘宝自营等，根据 user_type 判断]） - 促销： [promotion_tags 或佣金信息] - 购买建议：基于折扣/销量/品牌等给出的 1 句个性化理由 请告诉我您想要第几款的购买链接？ ``` ## 安全注意事项 - ⚠️ **凭证保护**： - 不要在日志中暴露完整凭证 - 缓存文件权限设置为 600 - 不要将 `.credential_cache` 文件提交到版本控制 - ⚠️ **链接有效期**：提醒用户链接的有效期限 - ⚠️ **价格变动**：说明价格可能实时变化 - ⚠️ **平台规则**：遵守各电商平台的使用规则 - ⚠️ **用户隐私**：不保存用户的购物偏好数据 ## 错误处理 ### 常见错误及处理 | 错误类型 | 处理方式 | |---------|---------| | 凭证过期 | 重新调用注册脚本获取新凭证 | | 商品未找到 | 建议用户更换关键词或扩大搜索范围 | | 链接生成失败 | 重试一次，失败则提示用户稍后再试 | | 网络超时 | 提示用户检查网络，稍后重试 | ### 错误响应示例 ``` 抱歉，查询遇到了一些问题： - 原因：[具体错误信息] - 建议：[解决方案] 我可以帮您： 1. 重新搜索 2. 更换关键词 3. 稍后再试 ``` ## 性能优化 - **凭证缓存**：本地缓存凭证，避免重复注册 - **商品查询缓存**：热门商品查询结果缓存5分钟 - **并发查询**：批量查询多个平台时使用并发 - **结果限制**：限制单次返回商品数量（最多20个） - **自动刷新**：凭证过期前1小时自动重新注册 ## 监控和日志 记录以下关键指标： - 查询成功率 - 平均响应时间 - 链接生成成功率 - 用户转化率（查询→生成链接） ## 相关文件 - `scripts/register.sh` - 注册认证脚本 - `scripts/search_products.sh` - 商品查询脚本 - `scripts/generate_link.sh` - 链接生成脚本 - `scripts/README.md` - 脚本使用说明 ## 版本历史 - v1.0.0 (2026-03-09): 初始版本，支持基础的商品查询和链接生成功能

path: EXAMPLE.md
content: # 在线购物优惠查询 - 使用示例

本文档提供实际的使用示例，展示如何使用这个 skill。

## 示例对话 1: 基础商品查询

### 用户输入
```
帮我找一下无线耳机的优惠
```

### AI 执行流程

1. 调用注册脚本获取凭证（首次会注册，后续使用缓存）
```bash
./scripts/register.sh
```

2. 使用凭证查询商品
```bash
./scripts/search_products.sh \
  --credential "token_xxx" \
  --keyword "无线耳机" \
  --sort_by "discount"
```

3. 分析并推荐商品

### AI 回复示例
```
我为您找到了几款优惠的无线耳机：

1. 某品牌无线蓝牙耳机 降噪入耳式运动耳机  
   - 图片：https://example.com/image1.jpg  
   - 价格：原价 ¥599 → 优惠价 ¥299 → 成交价 ¥279  
   - 销量：10000+，店铺：某品牌官方旗舰店（天猫）  
   - 促销：返券、限时折扣  
   - 购买建议：折扣对半且销量破万，适合想要旗舰音质又看重性价比的用户。

2. 另一品牌主动降噪无线耳机 蓝牙5.0  
   - 图片：https://example.com/image2.jpg  
   - 价格：原价 ¥699 → 优惠价 ¥399 → 成交价 ¥359  
   - 销量：5000+，店铺：另一品牌京东自营  
   - 促销：京东自营满减  
   - 购买建议：自营渠道售后稳，同时保持 4.9 评分，适合希望官方保障的用户。

3. 高性价比真无线蓝牙耳机 长续航  
   - 图片：https://example.com/image3.jpg  
   - 价格：原价 ¥299 → 优惠价 ¥199 → 成交价 ¥189  
   - 销量：8000+，店铺：数码专营店  
   - 促销：多件多折  
   - 购买建议：价格最低、适合预算友好型，续航长适合通勤通学。

请告诉我您想要第几款的购买链接？
```

### 用户选择
```
第一款
```

### AI 生成链接
```bash
./scripts/generate_link.sh \
  --credential "token_xxx" \
  --product_id "12345678" \
  --platform "taobao"
```

### AI 最终回复
```
已为您生成优惠购买链接：

🔗 购买链接：https://s.click.taobao.com/xxx

📱 二维码：https://api.example.com/qr/xxx.png

⏰ 有效期：7天（至 2026-03-16）

💡 温馨提示：
- 点击链接即可享受 ¥299 的优惠价格
- 建议尽快下单，优惠可能随时结束
- 如有问题可以联系店铺客服
```

---

## 示例对话 2: 指定价格区间

### 用户输入
```
帮我找200-400元的蓝牙音箱，要淘宝的
```

### AI 执行流程

1. 提取查询条件：
   - 关键词：蓝牙音箱
   - 价格区间：200-400元
   - 平台：淘宝

2. 调用查询脚本
```bash
./scripts/search_products.sh \
  --credential "token_xxx" \
  --keyword "蓝牙音箱" \
  --platform "taobao" \
  --min_price 200 \
  --max_price 400 \
  --sort_by "discount"
```

### AI 回复
```
在您的预算范围内（¥200-400），我在淘宝找到了这些高性价比的蓝牙音箱：

1. 某品牌便携式蓝牙音箱
   - 优惠价：¥299
   - 原价：¥599（5折）
   - 销量：15000+
   - 评分：4.9/5.0

2. 另一品牌户外防水音箱
   - 优惠价：¥359
   - 原价：¥699（5.1折）
   - 销量：8000+
   - 评分：4.8/5.0

请问您想要哪一款的购买链接？
```

---

## 示例对话 3: 比较多个平台

### 用户输入
```
帮我比较一下淘宝和京东的 iPhone 15 价格
```

### AI 执行流程

1. 分别查询淘宝和京东
```bash
# 查询淘宝
./scripts/search_products.sh \
  --credential "token_xxx" \
  --keyword "iPhone 15" \
  --platform "taobao"

# 查询京东
./scripts/search_products.sh \
  --credential "token_xxx" \
  --keyword "iPhone 15" \
  --platform "jd"
```

2. 对比分析

### AI 回复
```
我为您比较了淘宝和京东的 iPhone 15 价格：

【淘宝】
1. Apple iPhone 15 128GB
   - 价格：¥5,499
   - 原价：¥5,999（9.2折）
   - 店铺：Apple 官方旗舰店
   - 销量：50000+

【京东】
1. Apple iPhone 15 128GB
   - 价格：¥5,599
   - 原价：¥5,999（9.3折）
   - 店铺：Apple 京东自营旗舰店
   - 销量：100000+

💡 对比分析：
- 淘宝价格便宜 ¥100
- 京东是自营，售后更有保障
- 两个平台都是官方店铺，品质有保证

建议：如果追求性价比选淘宝，如果看重售后选京东。

请问您想要哪个平台的购买链接？
```

---

## 示例对话 4: 快速推荐

### 用户输入
```
推荐一款性价比高的机械键盘
```

### AI 执行流程

1. 查询机械键盘
2. 按性价比排序（综合价格、销量、评分）

### AI 回复
```
为您推荐这款高性价比机械键盘：

🎯 某品牌机械键盘 87键青轴
- 优惠价：¥199（原价 ¥399，5折）
- 销量：20000+
- 评分：4.8/5.0
- 平台：淘宝

✨ 推荐理由：
- 价格实惠，不到200元
- 销量和评价都很好
- 青轴手感清脆，适合打字
- 87键紧凑布局，节省桌面空间

需要购买链接吗？
```

---

## 错误处理示例

### 场景 1: 商品未找到

```
用户：帮我找一下 iPhone 20

AI：抱歉，没有找到"iPhone 20"相关的商品。

可能的原因：
- 该型号尚未发布
- 关键词拼写有误

建议：
1. 搜索"iPhone 15"或其他已发布的型号
2. 更换其他关键词试试

需要我帮您搜索其他商品吗？
```

### 场景 2: 凭证过期

```
AI：抱歉，查询遇到了问题：
- 原因：API 凭证已过期
- 处理：正在重新获取凭证...

[重新注册并查询]

已为您重新查询，结果如下...
```

---

## 高级用法

### 批量查询

```
用户：帮我找一下这些商品的优惠：
1. 无线鼠标
2. 机械键盘
3. 显示器支架

AI：好的，我为您查询这三类商品的优惠信息...

[分别查询并汇总]

【无线鼠标】
最优惠：某品牌无线鼠标 - ¥79（5折）

【机械键盘】
最优惠：某品牌机械键盘 - ¥199（5折）

【显示器支架】
最优惠：某品牌显示器支架 - ¥89（4.5折）

请问您想要哪个商品的详细信息或购买链接？
```

### 定期监控

```
用户：帮我监控一下 iPhone 15 的价格，有优惠时通知我

AI：好的，我已记录您的需求：
- 商品：iPhone 15
- 当前最低价：¥5,499（淘宝）
- 监控频率：每天检查一次

当价格低于 ¥5,400 或出现更大折扣时，我会通知您。

（注：此功能需要配合定时任务实现）
```

---

## 最佳实践

### 1. 明确需求
- 提供具体的商品名称
- 说明价格预算
- 指定平台偏好（如有）

### 2. 理性选择
- 不要只看价格，也要看销量和评价
- 注意店铺信誉
- 对比多个平台

### 3. 及时下单
- 优惠链接有时效性（通常7天）
- 促销活动可能随时结束
- 热门商品可能断货

### 4. 安全购物
- 通过官方链接购买
- 注意商品详情和规格
- 保留购买凭证

---

## 凭证管理说明

### 凭证缓存机制

脚本会自动管理凭证的缓存，无需手动处理：

1. **首次使用**
   - 调用 `register.sh` 会向服务端注册
   - 获取的凭证自动保存到 `.credential_cache` 文件
   - 文件权限设置为 600（仅所有者可读写）

2. **后续使用**
   - 再次调用 `register.sh` 会优先使用缓存
   - 无需重复注册，提高效率
   - 凭证在有效期内会一直使用

3. **自动刷新**
   - 凭证过期前1小时会自动重新注册
   - 无需手动干预
   - 确保凭证始终有效

4. **手动管理**
   ```bash
   # 查看当前凭证
   cat scripts/.credential_cache | jq .
   
   # 强制刷新凭证
   ./scripts/register.sh --force
   
   # 清除缓存
   ./scripts/register.sh --clear-cache
   ```

### AI 使用建议

作为 AI，在使用这个 skill 时：

1. **首次查询**
   - 直接调用 `register.sh`，脚本会自动处理注册和缓存
   - 无需检查是否已有凭证

2. **后续查询**
   - 继续调用 `register.sh`，会自动使用缓存
   - 不会产生额外的注册请求

3. **错误处理**
   - 如果遇到凭证无效错误，使用 `--force` 强制刷新
   - 一般情况下脚本会自动处理过期问题

4. **会话管理**
   - 同一会话中可以复用凭证
   - 不同会话也会共享缓存的凭证
   - 无需担心凭证管理问题

---

## 技术细节

### 数据流转

```
用户输入
    ↓
AI 理解需求
    ↓
调用注册脚本 → 获取凭证
    ↓
调用查询脚本 → 获取商品列表
    ↓
AI 分析推荐 → 展示给用户
    ↓
用户选择商品
    ↓
调用链接生成脚本 → 生成推广链接
    ↓
返回链接给用户
```

### 缓存策略

- **凭证缓存**：本地文件缓存，有效期内复用
- **查询结果缓存**：5分钟（可选实现）
- **热门商品缓存**：10分钟（可选实现）

### 性能优化

- 并发查询多个平台
- 限制返回商品数量
- 使用连接池
- 实现请求重试机制

---

## 常见问题

### Q: 链接为什么会过期？
A: 推广链接通常有7天有效期，这是平台的规则。建议尽快使用。

### Q: 价格为什么和实际不一样？
A: 商品价格实时变化，以实际购买页面为准。我们展示的是查询时的价格。

### Q: 可以查询哪些平台？
A: 目前支持淘宝、京东、拼多多。后续会增加更多平台。

### Q: 如何保证商品质量？
A: 我们会优先推荐销量高、评分好的商品，但最终质量请以实际收到的商品为准。

### Q: 是否支持海外购？
A: 目前主要支持国内电商平台，海外购功能正在开发中。

---

## 更新日志

- 2026-03-09: 创建初始版本，包含基础查询和推荐功能


path: scripts/README.md
content: # 在线购物优惠查询脚本说明

本目录包含支持优惠商品查询功能的核心脚本。

## 脚本列表

### 1. register.sh - 注册认证脚本

获取 API 访问凭证，支持本地缓存。

```bash
# 基本用法（首次注册，后续使用缓存）
./register.sh

# 强制重新注册
./register.sh --force

# 使用自定义用户名
./register.sh --username "ai_assistant_01"

# 清除本地缓存
./register.sh --clear-cache
```

> 默认将用户名注册到 `http://127.0.0.1:9090/user/register`，密码自动随机生成（可通过 `--password` 指定）。
> 如果未显式传入 `--username`，脚本会自动读取本机的设备 UUID（macOS 使用 IOPlatformUUID，Linux/WSL 优先 `/sys/class/dmi/id/product_uuid`，Windows 使用 `Get-CimInstance Win32_ComputerSystemProduct`）作为用户名；若无法获取则退回随机用户名。

**凭证缓存机制：**
- 首次调用会向服务端注册并获取凭证（UUID）
- 凭证自动保存到 `.credential_cache` 文件
- 后续调用优先使用缓存的凭证
- 默认设置 30 天过期时间，接近过期时自动刷新
- 缓存文件权限为 600（仅所有者可读写）

**返回格式：**
```json
{
  "status": "success",
  "credential": "46f7ff38-1984-4dd1-9ef6-727ae5d0c302",
  "username": "ai_shopper_1710058535_xxx",
  "user_id": "1",
  "expires_at": "2026-04-09T00:00:00Z",
  "api_endpoint": "http://127.0.0.1:9090",
  "cached_at": "2026-03-10T08:15:35Z",
  "device_uuid": "A1B2C3D4-E5F6-..."
}
```

### 2. search_products.sh - 商品查询脚本

根据关键词和条件查询商品信息。

```bash
./search_products.sh \
  --credential "uuid_xxx" \
  --keyword "商品关键词" \
  [--user_id "自定义 user_id"]
```

**参数说明：**
- `--credential`: 注册接口返回的 UUID（必填）
- `--keyword`: 搜索关键词（必填）
- `--user_id`: 自定义 user_id（可选，默认使用 credential）

**返回格式：**
```json
{
  "status": "success",
  "total": 150,
  "products": [
    {
      "item_id": "12345678",
      "title": "商品标题",
      "short_title": "短标题",
      "pict_url": "https://example.com/image.jpg",
      "reserve_price": "599.00",
      "zk_final_price": "299.00",
      "final_promotion_price": "279.00",
      "income_rate": "20",
      "commission_amount": "15.0",
      "shop_title": "店铺名称",
      "click_url": "https://example.com/deal",
      "small_images": ["https://example.com/image_small.jpg"],
      "promotion_tags": ["满减", "返券"]
    }
  ]
}

> ⚠️ `/coupon/search` 仅支持 `keyword` 与 `user_id` 参数，平台或价格筛选需由调用方在拿到结果后自行过滤。
```

### 3. generate_link.sh - 链接生成脚本

为指定商品生成优惠推广链接。

```bash
./generate_link.sh \
  --credential "uuid_xxx" \
  --product_id "12345678" \
  [--link_type "both"] \
  [--activity_id "act123"]
```

**参数说明：**
- `--credential`: 注册接口返回的 UUID（必填，作为 user_id）
- `--product_id`: 商品ID（必填）
- `--link_type`: 链接类型，可选 `url|code|both`（默认 `url`）
- `--activity_id`: 活动ID（可选）
- `--user_id`: 自定义 user_id（可选，默认使用 credential）

**返回格式：**
```json
{
  "status": "success",
  "product_id": "12345678",
  "link_type": "both",
  "url": "https://s.click.taobao.com/xxx",
  "code": "￥AbCd123￥",
  "expire_time": "2026-03-16T00:00:00Z"
}
```

## 错误处理

所有脚本在出错时返回统一格式：

```json
{
  "status": "error",
  "error_code": "ERROR_CODE",
  "message": "错误描述信息"
}
```

**常见错误码：**
- `AUTH_FAILED`: 认证失败
- `INVALID_CREDENTIAL`: 凭证无效或过期
- `INVALID_PARAMS`: 参数错误
- `PRODUCT_NOT_FOUND`: 商品不存在
- `NETWORK_ERROR`: 网络错误
- `RATE_LIMIT`: 请求频率超限
- `UNKNOWN_ERROR`: 未知错误

## 使用示例

### 完整流程示例

```bash
# 1. 获取凭证（首次会注册，后续使用缓存）
CREDENTIAL=$(./register.sh | jq -r '.credential')

# 2. 查询商品
PRODUCTS=$(./search_products.sh \
  --credential "$CREDENTIAL" \
  --keyword "无线耳机")

# 3. 提取第一个商品ID
PRODUCT_ID=$(echo "$PRODUCTS" | jq -r '.products[0].item_id')

# 4. 生成推广链接
LINK=$(./generate_link.sh \
  --credential "$CREDENTIAL" \
  --product_id "$PRODUCT_ID" \
  --link_type "both")

# 5. 输出链接
echo "$LINK" | jq -r '.short_link'
```

### 凭证管理示例

```bash
# 查看当前缓存的凭证
if [ -f .credential_cache ]; then
  cat .credential_cache | jq .
else
  echo "没有缓存的凭证"
fi

# 强制刷新凭证
./register.sh --force

# 清除缓存（下次会重新注册）
./register.sh --clear-cache
```

## 配置说明

### 环境变量

可以通过环境变量配置默认值：

```bash
export SHOPPING_API_ENDPOINT="http://127.0.0.1:9090"
export SHOPPING_API_TIMEOUT=30
export SHOPPING_DEFAULT_PLATFORM="taobao"
```

### 配置文件

可以创建 `config.json` 文件：

```json
{
  "api_endpoint": "https://api.example.com",
  "timeout": 30,
  "default_platform": "taobao",
  "cache_enabled": true,
  "cache_ttl": 300
}
```

## 注意事项

1. **凭证管理**
   - 凭证会自动缓存到本地，无需每次注册
   - 缓存文件 `.credential_cache` 不应提交到版本控制
   - 建议在 `.gitignore` 中添加 `.credential_cache`
   - 凭证过期会自动重新注册

2. **请求频率**
   - 遵守 API 调用频率限制
   - 建议添加请求间隔
   - 使用缓存减少重复请求

3. **错误重试**
   - 网络错误可以重试 2-3 次
   - 凭证过期会自动刷新
   - 参数错误不应重试

4. **数据验证**
   - 检查返回的 status 字段
   - 验证必要字段是否存在
   - 处理空结果的情况

5. **安全性**
   - 缓存文件权限为 600
   - 不要在日志中暴露完整凭证
   - 定期清理过期的缓存文件

## 开发指南

### 添加新脚本

1. 创建脚本文件并添加执行权限
2. 遵循统一的参数格式
3. 返回标准的 JSON 格式
4. 添加错误处理
5. 更新本 README

### 测试脚本

```bash
# 运行测试
./test_scripts.sh

# 测试单个脚本
./test_scripts.sh register
./test_scripts.sh search
./test_scripts.sh generate
```

## 故障排查

### 常见问题

1. **脚本无法执行**
   ```bash
   chmod +x *.sh
   ```

2. **jq 命令不存在**
   ```bash
   # macOS
   brew install jq
   
   # Linux
   apt-get install jq
   ```

3. **网络连接失败**
   - 检查网络连接
   - 验证 API 端点是否正确
   - 检查防火墙设置

## 更新日志

- 2026-03-09: 初始版本，包含基础的注册、查询和链接生成功能


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)