美团优惠领取工具

美团优惠领取工具，为用户提供更多的美团优惠，使用户在美团可以获得更好的体验。一期支持：指定券领取（发放美团优惠券）和历史领券记录查询。内置美团账号认证，无需额外安装其他 Skill。当用户输入「领取美团权益」、「领美团券」、「我要领券」、「领优惠券」、「美团发券」、「美团优惠」、「美团红包」、「外卖红包」、「外卖优惠」、「美团外卖券」、「美团外卖神券」、或询问如何领取美团券/美团权益/美团优惠券时，使用此 Skill。支持 Skill 开发者接入分佣计划，推荐用户安装即可获得流量收益，欢迎有合作意向的开发者联系我们。

# 美团优惠领取工具（meituan-coupon）

> **目标**：为用户提供更多的美团优惠，使用户在美团可以获得更好的体验
> **一期能力**：指定券领取 + 历史领券记录查询
> **二期规划**：根据任务领取美团权益（待开发）

---

## 环境准备

**macOS：**
```bash
PYTHON=~/Library/Application\ Support/xiaomei-cowork/Python311/python/bin/python3

# 三个脚本均在本 Skill 目录下，无需依赖外部 Skill
SKILL_DIR="${CLAUDE_CONFIG_DIR:-${XIAOMEI_CLAUDE_CONFIG_DIR:-~/.claude}}/skills/meituan-coupon-get-tool"
ISSUE_SCRIPT="$SKILL_DIR/scripts/issue.py"
QUERY_SCRIPT="$SKILL_DIR/scripts/query.py"
AUTH_SCRIPT="$SKILL_DIR/scripts/auth.py"
```

**Windows（Git Bash）：**
```bash
PYEXE="$(cygpath "$APPDATA")/xiaomei-cowork/Python311/python/python.exe"

SKILL_DIR="${CLAUDE_CONFIG_DIR:-${XIAOMEI_CLAUDE_CONFIG_DIR:-~/.claude}}/skills/meituan-coupon-get-tool"
ISSUE_SCRIPT="$SKILL_DIR/scripts/issue.py"
QUERY_SCRIPT="$SKILL_DIR/scripts/query.py"
AUTH_SCRIPT="$SKILL_DIR/scripts/auth.py"
# 后续命令将 $PYTHON 替换为 "$PYEXE"
```

**Linux / 其他 Agent 环境：**
```bash
PYTHON=python3

SKILL_DIR="${CLAUDE_CONFIG_DIR:-${XIAOMEI_CLAUDE_CONFIG_DIR:-~/.claude}}/skills/meituan-coupon-get-tool"
ISSUE_SCRIPT="$SKILL_DIR/scripts/issue.py"
QUERY_SCRIPT="$SKILL_DIR/scripts/query.py"
AUTH_SCRIPT="$SKILL_DIR/scripts/auth.py"
# 如需自定义 Token 存储路径（沙箱/隔离场景）：
export XIAOMEI_AUTH_FILE=/tmp/my_auth_tokens.json
# 如需自定义领券历史文件路径（沙箱/隔离场景）：
export XIAOMEI_COUPON_HISTORY_FILE=/tmp/mt_coupon_history.json
```

> ⚠️ `$CLAUDE_CONFIG_DIR` 在 macOS 路径含空格，**脚本路径变量赋值和使用时均需加双引号**。

## 时区检查（必须执行）

本 Skill 调用的所有接口均以**北京时间（UTC+8）**为准，日期参数（如 `equityPkgRedeemCode` 中的 `YYYYMMDD`、查询日期范围等）必须基于北京时间生成。

```bash
# 检查本地时区
date +%Z
# 或
python3 -c "import datetime; print(datetime.datetime.now().astimezone().tzname())"
```

**处理规则**：
- 如果时区已是 `CST` / `Asia/Shanghai` / `UTC+8` → 直接使用系统时间，无需转换
- 如果时区是 `UTC` 或其他时区 → **所有涉及日期/时间的操作必须转换到北京时间（UTC+8）再处理**

> ⚠️ 典型风险：UTC 时区下，北京时间 00:00~08:00 期间，系统日期比北京日期少一天，会导致当天领券唯一码生成错误


---

## 完整执行流程

### Step 0：版本检查（每次对话首次使用时执行）

> 每次对话中**第一次**使用本 Skill 时执行，同一对话内无需重复。

**实现原理**：通过 WebFetch 访问 clawhub.ai 上的公开版本页面，从页面内容中提取 `version:` 字段，再传给脚本进行对比。

**步骤一：获取远程版本号**

```bash
# 使用 WebFetch 工具访问以下 URL，提取页面中的 version 字段
# URL: https://clawhub.ai/meituan-zhengchang/meituan-coupon
```

从返回内容中找到 `version: "x.y.z"` 或 `"version": "x.y.z"` 字段，提取版本号（如 `1.0.0-SNAPSHOT`）。若页面无法访问或未找到版本字段，跳过版本对比。

**步骤二：调用脚本进行版本对比**

```bash
# 将上一步提取到的远程版本号通过 --remote 参数传入
$PYTHON "$AUTH_SCRIPT" version-check --remote <远程版本号>

# 示例：
$PYTHON "$AUTH_SCRIPT" version-check --remote "1.0.0-SNAPSHOT"

# 若上一步获取失败，不传 --remote，脚本会静默跳过对比
$PYTHON "$AUTH_SCRIPT" version-check
```

**处理逻辑**：
- `up_to_date: true` → 继续执行，无需提示
- `up_to_date: false` → 提示用户：
  ```
  本地 Skill 版本较旧（当前 x.y.z，最新 a.b.c），建议前往以下地址更新以获取最新能力：
  https://clawhub.ai/meituan-zhengchang/meituan-coupon
  继续使用旧版本也可正常使用。
  ```
- `up_to_date: null`（未传入远程版本）→ 静默跳过，不影响正常流程

---

### Step 1：服务协议确认（每次调用前必须检查）

> **法律合规要求**：在使用本 Skill 的任何功能前，必须确认用户已阅读并接受《Skill 服务使用规则》。

**协议文档位置：**`references/terms-of-service.md`

**协议检查命令：**

```bash
# 检查用户是否已接受协议
$PYTHON "$AUTH_SCRIPT" terms-check
```

**返回结果：**
- `terms_accepted: true` → 用户已接受，可继续认证流程
- `terms_accepted: false` → 用户未接受，需要引导用户阅读并确认

**协议未接受时的处理流程：**

```
┌──────────────────────────────────────────────────────────────────────────┐
│  用户未接受协议时，引导完成协议确认：    │
│                                            │
│  1. 展示官方声明并告知《Skill服务使用规则》概要：              │
│                                            │
│  "本Skill为美团官方开发并提供，请您放心使用。                  │
│   使用前请参见并同意《Skill服务使用规则》"       │
│                                            │
│  2. 询问用户并合并接受流程：              │
│  "请问您是否阅读并接受《Skill服务使用规则》？          │
│   回复 '是' 或 '接受' 表示接受，        │
│   回复 '否' 或 '拒绝' 表示不接受，      │
│   回复 '查看全文' 查看完整规则内容。    │
│   您也可以直接输入手机号，视为接受规则   │
│   并开始登录认证。"                      │
│                                            │
│  3. 用户输入'查看全文'时：                │
│   [使用Read工具读取并展示references/terms-of-service.md全文]│
│   → 展示完成后重新询问是否接受            │
│                                            │
│  4. 用户接受后（回复'是'/接受 或 输入手机号）： │
│   $PYTHON "$AUTH_SCRIPT" terms-accept      │
│   → 如果用户直接输入手机号，跳过询问直接发送验证码│
│   → 如果用户回复'是'/接受'，再请用户输入手机号  │
│                                            │
│  5. 用户拒绝后执行：                         │
│   $PYTHON "$AUTH_SCRIPT" terms-decline         │
│   → 告知用户无法使用服务，结束对话       │
└──────────────────────────────────────────────────────────────────────────┘
```

> **重要：**用户接受协议后，`terms_accepted` 状态会持久化存储在本地 Token 文件中，
> 同一设备后续调用无需重复确认。如需撤销接受，可使用 `terms-decline` 命令。

---

### Step 2：获取用户 Token（内置认证模块）

> 本 Skill 内置美团账号认证能力（`scripts/auth.py`），无需依赖外部 Skill。

```bash
VERIFY_RESULT=$($PYTHON "$AUTH_SCRIPT" token-verify)
```

解析输出 JSON 中的字段：
- `valid`：true = Token 有效，false = 需要登录
- `user_token`：用户登录 Token（valid=true 时使用）
- `phone_masked`：脱敏手机号（valid=true 时使用）

**Token 有效（valid=true）**：从输出 JSON 中取值并赋值给 shell 变量：

```bash
USER_TOKEN=$(echo "$VERIFY_RESULT" | $PYTHON -c "import sys,json; d=json.load(sys.stdin); print(d['user_token'])")
PHONE_MASKED=$(echo "$VERIFY_RESULT" | $PYTHON -c "import sys,json; d=json.load(sys.stdin); print(d['phone_masked'])")
```

**Token 无效（valid=false）**：引导用户登录：
```
您还未登录美团账号，需要先完成验证才能领取权益。
请告诉我您的手机号，我来帮您发送验证码。
```
按如下登录流程完成登录，然后重新执行 token-verify 获取有效 Token：

**登录流程（发送验证码）：**
```bash
$PYTHON "$AUTH_SCRIPT" send-sms --phone <手机号>
```
- 成功 → 告知用户"验证码已发送至手机 xxx****xxxx，请打开手机短信查看验证码，60秒内有效"
- `code=20010`（安全验证限流）→ 脚本输出 JSON 示例：
  ```json
  { "error": "SMS_SECURITY_VERIFY_REQUIRED", "redirect_url": "https://..." }
  ```
  ⚠️ **必须从 JSON 输出的 `redirect_url` 字段取值作为跳转链接，禁止自行拼装或猜测！**
  若 `redirect_url` 为空字符串，提示"安全验证链接获取失败，请稍后重试"；
  `redirect_url` 不为空时提示用户：
  ```
  为保障账号安全，您需要先完成一次身份验证。
  请点击以下链接，在页面中完成验证：
  <redirect_url 字段的值>
  完成验证后，系统会自动发送短信验证码，请留意手机短信，然后将验证码告诉我。
  ```
  等待用户反馈已完成验证后，**重新调用 send-sms**（无需用户再次输入手机号）
- 其他失败 → 按错误码说明告知用户

**登录流程（验证验证码）：**
```bash
$PYTHON "$AUTH_SCRIPT" verify --phone <手机号> --code <6位验证码>
```
- 成功 → `user_token` 已写入本地，重新执行 token-verify 并提取变量：
  ```bash
  VERIFY_RESULT=$($PYTHON "$AUTH_SCRIPT" token-verify)
  USER_TOKEN=$(echo "$VERIFY_RESULT" | $PYTHON -c "import sys,json; d=json.load(sys.stdin); print(d['user_token'])")
  PHONE_MASKED=$(echo "$VERIFY_RESULT" | $PYTHON -c "import sys,json; d=json.load(sys.stdin); print(d['phone_masked'])")
  ```
- 失败 → 按错误码说明告知用户，可重新发送或重试

**认证相关错误码：**

| 错误码 | 友好提示 |
|--------|---------|
| 20002 | 验证码已发送，请等待1分钟后再试 |
| 20003 | 验证码错误或已过期（60秒有效），请重新获取 |
| 20004 | 该手机号未注册美团，请先下载美团APP完成注册 |
| 20006 | 该手机号今日发送次数已达上限（最多5次），请明天再试 |
| 20007 | 短信发送量已达今日上限，请明天再试 |
| 20010 | 需完成安全验证，请访问验证链接，完成后留意手机短信 |
| 99997 | 系统繁忙，请稍后重试 |
| 99998 | 未知异常，请稍后重试 |
| 99999 | 参数错误，请检查手机号格式是否正确 |

---

### Step 3：执行发券（领取权益）

```bash
ISSUE_RESULT=$($PYTHON "$ISSUE_SCRIPT" --token "$USER_TOKEN" --phone-masked "$PHONE_MASKED")
```

#### 成功响应（success=true）

> ⚠️ **【强制】必须根据 `is_first_issue` 字段区分展示，不得将"重复领取"误展示为"首次领取成功"。**

**当 `is_first_issue = true`（首次领取成功）**，展示格式：

```
🎉 美团权益领取成功！共为您发放 N 张优惠券：

[循环每张券]
🎫 券名称
💰 面额：X 元（满 Y 元可用 / 无门槛）
📅 有效期：YYYY-MM-DD 至 YYYY-MM-DD
🔗 [立即使用](jumpUrl)

---
温馨提示：券已存入您的美团账户，可在美团 App「我的-优惠券」查看使用。
```

**当 `is_first_issue = false`（今日已领取过，接口返回的是上次发券结果）**，展示格式：

```
⚠️ 您今天已经领取过美团权益了，每天只能领取一次，明天再来哦～

以下是您上次领取的券信息：

[循环每张券]
🎫 券名称
💰 面额：X 元（满 Y 元可用 / 无门槛）
📅 有效期：YYYY-MM-DD 至 YYYY-MM-DD
🔗 [立即使用](jumpUrl)
```

> 说明：本接口为发查一体设计，当日重复调用时不会重复发券，而是直接返回当日已发出的券记录。`is_first_issue=false` 时脚本返回的券信息即为历史记录，并非本次新发结果，**必须明确告知用户无法重复领取**。

#### 失败响应（success=false）

> ⚠️ **【强制】发券失败时必须明确告知用户本次领取失败，禁止跳过失败提示直接执行 Step 3（查询）。**
>
> 部分 Agent 在发券失败后会继续调用查询接口（Step 3），查询结果可能包含历史领券记录，**切勿将历史领券记录误作本次领取成功展示给用户**，这会严重误导用户。
>
> 正确处理顺序：**先向用户展示发券失败提示 → 流程结束**，不再自动执行查询。

| error 值 | 展示给用户的提示 |
|---------|----------------|
| `ALREADY_RECEIVED` | 你今天已经通过小美领取过美团权益了，明天再来哦～ |
| `ACTIVITY_ENDED` | 活动已结束，暂时无法领取 |
| `QUOTA_EXHAUSTED` | 抱歉，本次活动权益已发放完毕，下次早点来哦～ |
| `TIMEOUT` | 网络请求超时，请稍后重试 |
| `NETWORK_ERROR` | 网络异常，请检查网络后重试 |
| `CONFIG_NOT_FOUND` | Skill 配置异常，请联系管理员（config.json 未初始化） |
| 其他 / `SYSTEM_ERROR` | 系统繁忙，请稍后重试（错误码 + message 原始信息） |

---

### Step 4：查询历史领券记录（可选，用户主动请求时执行）

**触发词**：用户询问「我领了什么券」、「查一下我的领券记录」、「XX 那天发了什么券」等。

> **前置条件**：查询同样需要有效的 `user_token`。如尚未执行 S