--- name: "meituan-c-user-auth" description: "美团C端用户Agent认证工具。为需要美团用户身份的 Skill（如发券、查订单等）提供手机号验证码登录认证，管理用户Token，实现“一次认证、持续有效”。当其他 Skill 需要校验用户身份、获取用户Token时，作为前置认证模块调用。触发词：美团登录、用户认证、手机号验证、发送验证码、获取Token、切换账号、退出登录。" version: "1.0.5" --- # 美团C端用户认证工具 --- ## 环境准备 **macOS：** ```bash PYTHON=~/Library/Application\ Support/xiaomei-cowork/Python311/python/bin/python3 SCRIPT="$CLAUDE_CONFIG_DIR/skills/meituan-c-user-auth/scripts/auth.py" ``` **Windows（Git Bash）：** ```bash PYEXE="$(cygpath "$APPDATA")/xiaomei-cowork/Python311/python/python.exe" SCRIPT="$CLAUDE_CONFIG_DIR/skills/meituan-c-user-auth/scripts/auth.py" # 后续命令将 $PYTHON 替换为 "$PYEXE" ``` **Linux / 其他 Agent 环境：** ```bash # 使用系统 Python 3（或自定义路径） PYTHON=python3 SCRIPT="$CLAUDE_CONFIG_DIR/skills/meituan-c-user-auth/scripts/auth.py" # 如需自定义 Token 存储路径（沙箱/隔离场景）： export XIAOMEI_AUTH_FILE=/tmp/my_auth_tokens.json ``` > ⚠️ `$CLAUDE_CONFIG_DIR` 在 macOS 路径含空格，**SCRIPT 变量赋值和使用时均需加双引号**。 ## 时区检查（必须执行） 本 Skill 调用的所有接口均以**北京时间（UTC+8）**为准。 ```bash # 检查本地时区 date +%Z ``` **处理规则**： - 如果时区已是 `CST` / `Asia/Shanghai` / `UTC+8` → 直接使用系统时间，无需转换 - 如果时区是 `UTC` 或其他时区 → **处理所有命令时需将时间转换到北京时间（UTC+8）再使用** --- ## 命令一览 | 命令 | 说明 | 是否调用远程接口 | |------|------|----------------| | `version-check` | 检查本地 Skill 版本，与广场版本对比 | ⚡ 本地为主，有远程源时才请求 | | `terms-check` | 检查用户是否已接受服务协议 | ❌ 本地只读 | | `terms-accept` | 用户接受服务协议 | ❌ 本地操作 | | `terms-decline` | 用户拒绝服务协议 | ❌ 本地操作 | | `status` | 本地检查 Token 是否存在 | ❌ 本地只读 | | `token-verify` | 调用服务端校验 Token 真实有效性 | ✅ 调用接口 | | `send-sms --phone <手机号>` | 发送短信验证码 | ✅ 调用接口 | | `verify --phone <手机号> --code <验证码>` | 验证验证码，写入 Token | ✅ 调用接口 | | `logout` | 退出登录，user_token 置空（保留 device_token） | ❌ 本地操作 | --- ## 版本检查（每次对话首次使用时执行） > 每次对话中**第一次**使用本 Skill 时执行，同一对话内无需重复。 **实现原理**：通过 WebFetch 访问 clawhub.ai 上的公开版本页面，从页面内容中提取 `version:` 字段，再传给脚本进行对比。 ### 步骤一：获取远程版本号 ```bash # 使用 WebFetch 工具访问以下 URL，提取页面中 version 字段 # URL: https://clawhub.ai/meituan-zhengchang/meituan-c-user-auth ``` 从返回内容中找到 `version: "x.y.z"` 或 `"version": "x.y.z"` 字段，提取版本号（如 `1.0.0-SNAPSHOT`）。若页面无法访问或未找到版本字段，跳过版本对比。 ### 步骤二：调用脚本进行版本对比 ```bash # 将上一步提取到的远程版本号通过 --remote 参数传入 $PYTHON "$SCRIPT" version-check --remote <远程版本号> # 示例： $PYTHON "$SCRIPT" version-check --remote "1.0.0-SNAPSHOT" # 若上一步获取失败，不传 --remote，脚本会静默跳过对比 $PYTHON "$SCRIPT" version-check ``` **处理逻辑**： - `up_to_date: true` → 继续执行，无需提示 - `up_to_date: false` → 提示用户： ``` 本地 Skill 版本较旧（当前 x.y.z，最新 a.b.c），建议前往以下地址更新以获取最新能力： https://clawhub.ai/meituan-zhengchang/meituan-c-user-auth 继续使用旧版本也可正常登录。 ``` - `up_to_date: null`（未传入远程版本）→ 静默跳过，不影响正常流程 --- ## 服务协议确认（每次调用前必须检查） > **法律合规要求**：在使用本 Skill 的任何功能前，必须确认用户已阅读并接受《Skill 服务使用规则》。 **协议文档位置：**`references/terms-of-service.md` ### 协议检查命令 ```bash # 检查用户是否已接受协议 $PYTHON "$SCRIPT" terms-check ``` **返回结果：** - `terms_accepted: true` → 用户已接受，可继续使用认证流程 - `terms_accepted: false` → 用户未接受，需要引导用户阅读并确认 ### 协议未接受时的处理流程 ``` ┌──────────────────────────────────────────────────────────────────┐ │ 用户未接受协议时，引导完成协议确认： │ │ │ │ 1. 展示官方声明并告知《Skill服务使用规则》概要： │ │ │ │ "本Skill为美团官方开发并提供，请您放心使用。 │ │ 使用前请参见并同意《Skill服务使用规则》" │ │ │ │ 2. 询问用户并合并接受流程： │ │ "请问您是否阅读并接受《Skill服务使用规则》？ │ │ 回复 '是' 或 '接受' 表示接受， │ │ 回复 '否' 或 '拒绝' 表示不接受， │ │ 回复 '查看全文' 查看完整规则内容。 │ │ 您也可以直接输入手机号，视为接受规则 │ │ 并开始登录认证。" │ │ │ │ 3. 用户输入'查看全文'时： │ │ [使用Read工具读取并展示references/terms-of-service.md全文]│ │ → 展示完成后重新询问是否接受 │ │ │ │ 4. 用户接受后（回复'是'/接受 或 输入手机号）： │ │ $PYTHON "$SCRIPT" terms-accept │ │ → 如果用户直接输入手机号，跳过询问直接发送验证码 │ │ → 如果用户回复'是'/接受'，再请用户输入手机号│ │ │ │ 5. 用户拒绝后执行： │ │ $PYTHON "$SCRIPT" terms-decline │ │ → 告知用户无法使用服务，结束对话 │ └──────────────────────────────────────────────────────────────────┘ ``` > **重要：**用户接受协议后，`terms_accepted` 状态会持久化存储在本地 Token 文件中， > 同一设备后续调用无需重复确认。如需撤销接受，可使用 `terms-decline` 命令。 --- ## 标准认证流程（每次调用必须按此步骤执行） ``` ┌──────────────────────────────────────────────────────────────────┐ │ 第一步（协议检查）：检查服务协议确认状态 │ │ $PYTHON "$SCRIPT" terms-check │ │ ├── terms_accepted: true │ │ │ → 进入第二步（Token 校验） │ │ └── terms_accepted: false │ │ → 执行协议确认流程（见上文） │ └──────────────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────────────┐ │ 第二步（Token 校验）：调用远程接口校验 Token │ │ $PYTHON "$SCRIPT" token-verify │ │ ├── valid: true → 告知用户已登录 │ │ │ (手机号 phone_masked) │ │ │ 返回 user_token，流程结束 │ │ └── valid: false → 进入第三步 │ └──────────────────────────────────────────────────────────────────┘ ↓（Token 无效或不存在） ┌──────────────────────────────────────────────────────────────────┐ │ 第三步：引导用户输入手机号 │ │ "请输入您的美团账号手机号：" │ │ 等待用户输入 │ └──────────────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────────────┐ │ 第四步：发送短信验证码 │ │ $PYTHON "$SCRIPT" send-sms --phone <手机号> │ │ ├── 成功 → 告知用户： │ │ │ "验证码已发送至手机 xxx****xxxx， │ │ │ 请打开手机短信查看验证码， │ │ │ 60秒内有效" │ │ ├── code=20010（安全验证）→ 见下方分支 │ │ └── 其他失败 → 告知原因（见错误码说明） │ └──────────────────────────────────────────────────────────────────┘ ↓（当 code=20010 时的安全验证分支） ┌──────────────────────────────────────────────────────────────────┐ │ 安全验证分支：引导用户完成身份校验 │ │ 脚本输出 JSON 示例： │ │ { │ │ "error": "SMS_SECURITY_VERIFY_REQUIRED",│ │ "redirect_url": "https://..." │ │ } │ │ │ │ ⚠️ 必须从 JSON 输出的 redirect_url 字段 │ │ 取值，禁止自行拼装或猜测跳转链接！ │ │ ⚠️ 若 redirect_url 为空字符串，提示用户 │ │ "安全验证链接获取失败，请稍后重试" │ │ │ │ redirect_url 不为空时提示用户： │ │ "为保障账号安全，您需要先完成一次身份验证。 │ │ 请点击以下链接，在页面中完成验证： │ │ │ │ 完成验证后，系统会自动发送短信验证码， │ │ 请留意手机短信，然后将验证码告诉我。" │ │ │ │ 等待用户反馈已完成验证后，重新执行第四步 │ │ （重新发送验证码，不需要用户再次输入手机号）│ └──────────────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────────────┐ │ 第五步：等待用户输入验证码 │ │ "请输入您收到的6位验证码：" │ │ 等待用户输入 │ └──────────────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────────────┐ │ 第六步：验证验证码 │ │ $PYTHON "$SCRIPT" verify \ │ │ --phone <手机号> --code <验证码> │ │ ├── 成功 → "认证成功，xxx****xxxx 已登录" │ │ │ user_token 已自动写入 │ │ │ 返回 user_token 供调用方使用 │ │ └── 失败 → 告知原因，提示重新发送或重试 │ └──────────────────────────────────────────────────────────────────┘ ``` --- ## 错误码说明（告知用户时使用友好描述） | 错误码 | 涉及接口 | 友好提示 | |--------|---------|---------| | 20002 | 发送验证码 | 验证码已发送，请等待1分钟后再试 | | 20003 | 验证验证码 | 验证码错误或已过期（60秒有效），请重新获取 | | 20004 | 发送/验证 | 该手机号未注册美团，请先下载美团APP完成注册 | | 20005 | 校验Token | 登录状态已过期，需要重新认证 | | 20006 | 发送验证码 | 该手机号今日发送次数已达上限（最多5次），请明天再试 | | 20007 | 发送验证码 | 短信发送量已达今日上限，请明天再试 | | 20010 | 发送验证码 | 需要完成安全验证，请按提示访问验证链接，完成后留意手机短信 | | 99997 | 全部 | 系统繁忙，请稍后重试 | | 99998 | 全部 | 未知异常，请稍后重试 | | 99999 | 全部 | 参数错误，请检查手机号格式是否正确 | --- ## 供其他 Skill 调用的约定 在调用方的 SKILL.md 中写： ```markdown ## 前置认证 1. 调用 meituan-c-user-auth Skill，按标准认证流程执行 2. 获取有效 user_token 3. 携带 user_token 调用业务接口 4. 若业务接口返回 Token 无效错误，重新触发认证流程 ``` --- ## 注意事项 1. **Token 校验使用 `token-verify`**（远程接口），而非 `status`（仅本地存在性检查） 2. **验证码60秒有效**，1分钟内不能重复发送，发送前提醒用户 3. **Token 有效性以服务端校验为准**：`token-verify` 返回 `valid: false` 时才需要重新认证，不在本地推算过期时间，不向用户提示 Token 有效期 4. **user_token 不要在对话中显示**，仅传递给业务接口 5. **退出/切换账号**：执行 `logout` 命令清除 Token 6. **device_token 不要在对话中展示**：device_token 是设备唯一标识，属于内部字段，正常交互中不得向用户输出；仅在排查登录问题时，且用户明确要求查看时，才可展示 7. **安全验证（20010）处理**：当 send-sms 返回 `error=SMS_SECURITY_VERIFY_REQUIRED` 时，**必须从脚本 JSON 输出的 `redirect_url` 字段取值作为跳转链接**，禁止自行拼装或猜测链接；若 `redirect_url` 为空则提示用户稍后重试；引导用户点击该链接完成安全验证后，**重新调用 send-sms**（无需用户再次输入手机号）；安全验证后的短信由后端自动触发，用户直接输入收到的验证码即可 8. **法律合规要求**：在使用任何功能前，必须检查并确认用户已接受《Skill 服务使用规则》（使用 `terms-check` 命令） 9. **展示协议全文时必须展示原文**：当用户要求查看《Skill 服务使用规则》全文时，必须使用 Read 工具读取 `references/terms-of-service.md` 原文展示，不得精简、概括或修改内容 --- ## API 信息摘要 | 接口 | 路径 | 方法 | 关键请求字段 | |------|------|------|------------| | 发送验证码 | `/eds/claw/login/sms/code/get` | POST | `mobile`, `uuid`（device_token） | | 验证验证码 | `/eds/claw/login/sms/code/verify` | POST | `mobile`, `smsVerifyCode`, `uuid`（device_token） | | 校验 Token | `/eds/claw/login/token/verify` | POST | `?token=` (Query) | > 当前使用**线上外网**域名：`https://peppermall.meituan.com` 完整接口文档见 `references/api-config.md`