\r \r

UU跑腿同城配送服务 Skill\r

\r UU跑腿同城配送服务为用户提供便捷的同城即时配送能力，包括订单询价、发单、订单管理和跑男实时追踪等功能。\r \r

功能特性\r

\r

• 📱 手机号一键注册（首次使用自动引导）\r
• 💰 订单询价（计算配送费用）\r
• 📦 创建配送订单\r
• 💳 在线支付（余额不足时提供支付链接，支持微信/支付宝）\r
• 📋 查询订单详情\r
• ❌ 取消订单\r
• 🏃 跑男实时位置追踪\r
• 💾 配置本地持久化存储\r \r

运行环境选择\r

\r 本 skill 同时提供 Node.js 和 Python 两种版本，可根据你的环境选择：\r \r | 环境 | 依赖安装 | 脚本位置 |\r |------|---------|---------|\r | Node.js | npm install | scripts/*.js 和 index.js |\r | Python | pip install -r requirements.txt | uupt_delivery.py |\r \r Agent 会自动检测可用环境并选择合适的版本执行。\r \r

首次使用\r

\r 本 skill 支持两种认证方式，可根据实际情况选择：\r \r

方式一：开发者模式（已有凭证）\r

\r 如果你已经拥有自己的 appId、appSecret、openId，在 config.json 中配置：\r \r

{\r
  "appId": "你的appId",\r
  "appSecret": "你的appSecret",\r
  "openId": "你的openId"\r
}\r
```\r
\r
或通过环境变量设置：\r
```bash\r
export UUPT_APP_ID=你的appId\r
export UUPT_APP_SECRET=你的appSecret\r
export UUPT_OPEN_ID=你的openId\r
```\r
\r
配置完成后即可直接使用所有功能，无需注册流程。\r
\r
### 方式二：快速体验模式（手机号注册）\r
\r
**首次安装时 config.json 文件不存在，这是正常的。** 执行任何功能脚本会自动检测是否需要注册：\r
\r
- 如果输出中包含 `[REGISTRATION_REQUIRED]`，说明需要先完成手机号验证\r
- Agent 应自动进入**场景零（首次注册）**引导用户完成注册\r
- 注册完成后，系统自动创建 config.json 并保存 openId，后续使用无需重复注册\r
- 此模式使用内置的默认 appId/appSecret\r
\r
### 认证状态检查\r
\r
当 `appId`、`appSecret`、`openId` 三个值都已配置（无论通过哪种方式），后续使用将不再要求用户提供凭证。\r
\r
## 触发条件\r
\r
用户表达了以下意图之一：\r
- 询问配送价格（如"从A地址送到B地址多少钱"、"帮我算下配送费"）\r
- 下单配送（如"帮我发个跑腿单"、"我要寄东西"、"同城配送"）\r
- 查询订单（如"查看订单状态"、"订单到哪了"）\r
- 取消订单（如"取消这个订单"、"不想发了"）\r
- 追踪跑男（如"骑手在哪"、"跑男到哪了"、"配送进度"）\r
- 包含"跑腿"、"配送"、"寄送"、"订单"、"骑手"、"跑男"等关键词\r
\r
## 场景判断\r
\r
收到用户请求后，先判断属于哪个场景：\r
\r
- **场景零**：首次注册 — 任何功能执行时检测到 `[REGISTRATION_REQUIRED]`，先询问用户是否已有凭证\r
- **场景一**：订单询价 - 用户想知道配送费用，需要提供起始地址和目的地址\r
- **场景二**：创建订单 - 用户确认发单，需要询价返回的 priceToken 和收件人电话\r
- **场景三**：查询订单详情 - 用户想查看订单状态，需要订单编号\r
- **场景四**：取消订单 - 用户要取消订单，需要订单编号\r
- **场景五**：跑男追踪 - 用户想查看跑男实时位置，需要订单编号\r
\r
---\r
\r
## 场景零：首次注册 / 获取授权\r
\r
当执行任何功能脚本时，如果输出中包含 `[REGISTRATION_REQUIRED]`，说明用户尚未完成配置。\r
\r
### 触发条件\r
\r
- 执行任何脚本时输出包含 `[REGISTRATION_REQUIRED]`\r
- 这是一个**自动触发**场景，不需要用户主动发起\r
\r
### 执行步骤\r
\r
**Step 1: 询问用户是否已有凭证**\r
\r
向用户询问：\r
\r
```\r
首次使用需要配置认证信息，请问您是否已有 UU跑腿开放平台的凭证（appId、appSecret、openId）？\r
- A: 已有凭证，直接配置\r
- B: 没有凭证，通过手机号注册\r
```\r
\r
**如果用户选择 A（已有凭证）→ 进入 Step 1A**\r
**如果用户选择 B（没有凭证）→ 进入 Step 2**\r
\r
---\r
\r
**Step 1A: 获取用户凭证并保存**\r
\r
请用户提供三个值：\r
- appId\r
- appSecret  \r
- openId\r
\r
获取后，将凭证写入 `config.json` 文件：\r
```json\r
{\r
  "appId": "用户提供的appId",\r
  "appSecret": "用户提供的appSecret",\r
  "openId": "用户提供的openId"\r
}\r
```\r
\r
保存成功后：\r
- 告知用户「配置完成！」\r
- **立即继续执行用户最初要求的功能**（无需用户再次操作）\r
\r
---\r
\r
**Step 2: 询问手机号（快速体验模式）**\r
\r
向用户询问：「请输入您的手机号码，我们将发送验证码完成注册」\r
\r
**Step 3: 发送短信验证码**\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/register.js --mobile="用户手机号"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py register --mobile="用户手机号"\r
```\r
\r
处理结果：\r
- 输出 `[SMS_SENT]` → 验证码发送成功，提示用户查看手机短信，进入 Step 4\r
- 输出 `[IMAGE_CAPTCHA_REQUIRED]` → 需要图片验证码，处理方式：\r
  - 输出中包含 `IMAGE_DATA=data:image/png;base64,...` 的 base64 图片数据\r
  - 将 base64 图片展示给用户（可使用 show_widget 工具展示 `\x3Cimg src="IMAGE_DATA中的内容">`）\r
  - 请用户识别图片中的数字\r
  - 用户回复后，重新调用（带 `--imageCode` 参数）：\r
    ```bash\r
    node scripts/register.js --mobile="手机号" --imageCode="用户输入的数字"\r
    ```\r
\r
**Step 4: 输入短信验证码**\r
\r
提示用户：「验证码已发送，请输入您收到的短信验证码」\r
\r
**Step 5: 完成授权**\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/register.js --mobile="手机号" --smsCode="用户输入的验证码"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py register --mobile="手机号" --sms-code="用户输入的验证码"\r
```\r
\r
处理结果：\r
- 输出 `[REGISTRATION_SUCCESS]` → 注册成功，openId 已自动保存到配置文件\r
  - 告知用户注册成功\r
  - **立即继续执行用户最初要求的功能**（无需用户再次操作）\r
- 输出 `[REGISTRATION_FAILED]` → 注册失败\r
  - **不需要重新询问手机号**\r
  - 从 Step 3 开始重试（重新发送验证码 → 用户输入新验证码 → 重新授权）\r
  - 最多重试 3 次\r
  - 3 次仍失败 → 告知用户稍后再试或联系客服\r
\r
### 回复模板（注册成功后）\r
\r
```\r
注册成功！您的账号已激活。\r
现在为您继续执行之前的操作...\r
```\r
\r
---\r
\r
## 场景一：订单询价\r
\r
计算从起始地址到目的地址的配送费用。用户可以只询价不发单。\r
\r
### 执行步骤\r
\r
1. **执行询价脚本**：从用户输入中提取起始地址、目的地址、城市（可选）\r
2. **如果输出 `[REGISTRATION_REQUIRED]`**：进入场景零完成注册后，重新执行询价\r
\r
### 使用方法\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/order-price.js --fromAddress="郑州市金水区农业路经三路交叉口" --toAddress="郑州市二七区德化街100号" --cityName="郑州市"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py price --from-address="郑州市金水区农业路经三路交叉口" --to-address="郑州市二七区德化街100号" --city="郑州市"\r
```\r
\r
### 参数说明\r
\r
| 参数 (JS) | 参数 (Python) | 说明 | 必填 |\r
|-----------|--------------|------|------|\r
| `--fromAddress` | `--from-address` | 起始地址（完整地址） | 是 |\r
| `--toAddress` | `--to-address` | 目的地址（完整地址） | 是 |\r
| `--cityName` | `--city` | 城市名称（需要带"市"字） | 否 |\r
\r
### 返回结果\r
\r
返回包含 `priceToken` 和价格信息，价格单位为分，需要格式化为元展示给用户。\r
\r
### 回复模板\r
\r
```\r
💰 配送费用查询结果：\r
\r
起点：{fromAddress}\r
终点：{toAddress}\r
预估费用：{price/100} 元\r
\r
📝 如需下单，请提供收件人电话。\r
```\r
\r
---\r
\r
## 场景二：创建订单（发单）\r
\r
当用户明确表示要发单/下单时，**询价后直接创建订单**，无需二次确认。\r
\r
### 触发条件\r
\r
用户表达了发单意图，如：\r
- "帮我发个单"、"我要寄东西"、"帮我下单"\r
- "从A送到B，收件人电话xxx"\r
- "帮我配送xxx到xxx"\r
\r
### 执行步骤\r
\r
1. **获取必要信息**：起始地址、目的地址、收件人电话（必须在发单前获取）\r
2. **调用询价接口**：获取 priceToken\r
3. **立即创建订单**：使用 priceToken 直接创建订单，**不询问用户是否确认**\r
4. **处理返回结果**：根据余额情况进行不同处理\r
\r
### 使用方法\r
\r
**Step 1: 先询价获取 priceToken**\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/order-price.js --fromAddress="起始地址" --toAddress="目的地址"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py price --from-address="起始地址" --to-address="目的地址"\r
```\r
\r
**Step 2: 立即创建订单**\r
\r
⚠️ **重要**：如果是微信渠道，必须传递 `--channel="wechat"` 参数以生成支付二维码图片。\r
\r
**Node.js 版本：**\r
```bash\r
# 微信渠道（生成二维码图片）\r
node scripts/create-order.js --priceToken="xxx" --receiverPhone="13800138000" --channel="wechat"\r
\r
# 其他渠道（只输出支付链接）\r
node scripts/create-order.js --priceToken="xxx" --receiverPhone="13800138000"\r
```\r
\r
**Python 版本：**\r
```bash\r
# 微信渠道（生成二维码图片）\r
python uupt_delivery.py create --price-token="xxx" --receiver-phone="13800138000" --channel="wechat"\r
\r
# 其他渠道（只输出支付链接）\r
python uupt_delivery.py create --price-token="xxx" --receiver-phone="13800138000"\r
```\r
\r
### 参数说明\r
\r
| 参数 (JS) | 参数 (Python) | 说明 | 必填 |\r
|-----------|--------------|------|------|\r
| `--priceToken` | `--price-token` | 询价接口返回的 token | 是 |\r
| `--receiverPhone` | `--receiver-phone` | 收件人手机号 | 是 |\r
| `--channel` | `--channel` | 聊天渠道（wechat/feishu/dingtalk 等） | 否 |\r
\r
### 返回结果处理\r
\r
**情况一：余额充足，订单创建成功**\r
\r
直接返回订单编号，告知用户订单已创建成功。\r
\r
**回复模板：**\r
```\r
订单创建成功！\r
\r
订单编号：{order_code}\r
配送费用：{price/100} 元\r
\r
骑手正在接单中，请保持电话畅通。\r
```\r
\r
---\r
\r
**情况二：余额不足，需要在线支付**\r
\r
当返回的 JSON 中 `body.orderUrl` 不为空时，表示需要用户完成支付。\r
\r
**识别标记**：脚本输出包含 `[PAYMENT_REQUIRED]` 时表示需要支付。\r
\r
**关键输出**：\r
- `ORDER_CODE={order_code}` — 订单编号\r
- `PAYMENT_URL={payment_url}` — 支付链接（用户点击后可选择微信或支付宝支付）\r
- `QRCODE_FILE={qrcode_path}` — 支付二维码图片本地路径（**只有传递 `--channel="wechat"` 时才有此输出**）\r
\r
**处理流程：**\r
\r
1. **根据渠道调用脚本**：\r
\r
- 微信渠道：必须传递 `--channel="wechat"` 参数以生成二维码图片\r
- 其他渠道：无需传递 `--channel` 参数\r
\r
2. **根据渠道展示支付信息**：\r
\r
### 渠道适配：发送支付信息\r
\r
⚠️ **微信渠道特殊处理**：微信中链接无法直接打开，必须发送二维码图片附件！\r
\r
**微信渠道：**\r
```\r
message(action=send, channel="wechat", path="{QRCODE_FILE}", message="请扫码支付 {price/100} 元")\r
```\r
\r
**其他渠道（飞书/钉钉/企业微信/QQ/Telegram/其他）**：直接发送支付链接：\r
```\r
💳 请点击以下链接完成支付（支持微信/支付宝）：\r
{PAYMENT_URL}\r
```\r
\r
### 回复模板\r
\r
**微信渠道专用：**\r
```\r
账户余额不足，需要完成支付\r
\r
订单编号：{order_code}\r
配送费用：{price/100} 元\r
\r
请扫码支付，支付完成后告诉我。\r
\r
（附件：支付二维码）\r
```\r
\r
**其他渠道：**\r
```\r
账户余额不足，需要完成支付\r
\r
订单编号：{order_code}\r
配送费用：{price/100} 元\r
\r
💳 请点击以下链接完成支付（支持微信/支付宝）：\r
{PAYMENT_URL}\r
\r
支付完成后请告诉我。\r
```\r
\r
**重要说明**：\r
- 微信渠道必须用 `message(action=send, channel="wechat", path="{QRCODE_FILE}")` 发送二维码图片附件\r
- 其他渠道直接发送 `{PAYMENT_URL}` 支付链接\r
\r
3. **等待用户返回**：用户支付后会回来\r
\r
4. **确认支付状态**：当用户回来时，询问用户是否已完成支付：\r
```\r
您好，请问是否已完成支付？\r
- 是，已支付完成\r
- 否，还未支付\r
```\r
\r
5. **用户确认支付完成后**：立即调用订单详情接口查询订单状态\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/order-detail.js --orderCode="{order_code}"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py detail --order-code="{order_code}"\r
```\r
\r
6. **展示订单详情**：\r
\r
```\r
支付成功！订单详情如下：\r
\r
订单编号：{order_code}\r
订单状态：{status}\r
起点：{from_address}\r
终点：{to_address}\r
配送费：{price/100} 元\r
\r
骑手正在接单中，请保持电话畅通。\r
```\r
\r
### 完整交互流程示例\r
\r
```\r
用户：帮我从金水区农业路送到二七区德化街，收件人电话 13800138000\r
\r
Agent：\r
1. 执行询价 → 获取 priceToken\r
2. 立即执行创建订单（不询问确认）\r
3. 如果余额充足 → 返回成功信息\r
4. 如果余额不足 → 输出支付链接，用户点击后可选择微信/支付宝\r
\r
--- 用户去支付 ---\r
\r
用户：我支付完了\r
\r
Agent：\r
1. 询问确认：请问是否已完成支付？\r
2. 用户确认后 → 查询订单详情\r
3. 展示订单状态\r
```\r
\r
---\r
\r
## 场景三：查询订单详情\r
\r
查看订单的当前状态和详细信息。\r
\r
### 执行步骤\r
\r
1. **获取订单编号**：从用户输入或上下文中获取订单编号\r
2. **调用查询接口**\r
\r
### 使用方法\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/order-detail.js --orderCode="UU123456789"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py detail --order-code="UU123456789"\r
```\r
\r
### 参数说明\r
\r
| 参数 (JS) | 参数 (Python) | 说明 | 必填 |\r
|-----------|--------------|------|------|\r
| `--orderCode` | `--order-code` | 订单编号 | 是 |\r
\r
### 回复模板\r
\r
```\r
📋 订单详情：\r
\r
订单编号：{order_code}\r
订单状态：{status}\r
起点：{from_address}\r
终点：{to_address}\r
配送费：{price/100} 元\r
骑手信息：{driver_name} {driver_phone}\r
```\r
\r
---\r
\r
## 场景四：取消订单\r
\r
取消未完成的配送订单。\r
\r
### 执行步骤\r
\r
1. **获取订单编号**：从用户输入获取\r
2. **确认取消原因**：询问用户取消原因（可选）\r
3. **调用取消接口**\r
\r
### 使用方法\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/cancel-order.js --orderCode="UU123456789" --reason="用户改变主意"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py cancel --order-code="UU123456789" --reason="用户改变主意"\r
```\r
\r
### 参数说明\r
\r
| 参数 (JS) | 参数 (Python) | 说明 | 必填 |\r
|-----------|--------------|------|------|\r
| `--orderCode` | `--order-code` | 订单编号 | 是 |\r
| `--reason` | `--reason` | 取消原因 | 否 |\r
\r
### 回复模板\r
\r
```\r
订单已取消\r
\r
订单编号：{order_code}\r
取消原因：{reason}\r
\r
如需重新下单，请告诉我配送地址。\r
```\r
\r
---\r
\r
## 场景五：跑男实时追踪\r
\r
查询配送骑手的实时位置和状态。\r
\r
### 执行步骤\r
\r
1. **获取订单编号**：从用户输入获取\r
2. **调用跑男追踪接口**\r
\r
### 使用方法\r
\r
**Node.js 版本：**\r
```bash\r
node scripts/driver-track.js --orderCode="UU123456789"\r
```\r
\r
**Python 版本：**\r
```bash\r
python uupt_delivery.py track --order-code="UU123456789"\r
```\r
\r
### 参数说明\r
\r
| 参数 (JS) | 参数 (Python) | 说明 | 必填 |\r
|-----------|--------------|------|------|\r
| `--orderCode` | `--order-code` | 订单编号 | 是 |\r
\r
### 回复模板\r
\r
```\r
跑男实时位置：\r
\r
骑手姓名：{driver_name}\r
联系电话：{driver_phone}\r
当前位置：{current_location}\r
预计送达：{estimated_time}\r
```\r
\r
---\r
\r
## 配置管理\r
\r
配置分为两层：\r
\r
- **`defaults.json`**：内置应用凭证（appId、appSecret、apiUrl），随 Skill 分发，**请勿修改**\r
- **`config.json`**：用户级配置，首次安装时不存在，通过以下方式创建：\r
  - **开发者模式**：用户提供 appId、appSecret、openId 后写入\r
  - **快速体验模式**：注册成功后自动创建，仅包含 openId\r
\r
### 配置优先级（从高到低）\r
\r
| 配置项 | 环境变量 | config.json | defaults.json |\r
|--------|---------|-------------|---------------|\r
| appId | `UUPT_APP_ID` | `appId` | `appId` |\r
| appSecret | `UUPT_APP_SECRET` | `appSecret` | `appSecret` |\r
| openId | `UUPT_OPEN_ID` | `openId` | - |\r
| apiUrl | `UUPT_API_URL` | `apiUrl` | `apiUrl` |\r
\r
### 配置示例\r
\r
**开发者模式**（用户提供凭证后写入 config.json）：\r
```json\r
{\r
  "appId": "你的appId",\r
  "appSecret": "你的appSecret", \r
  "openId": "你的openId"\r
}\r
```\r
\r
**快速体验模式**（注册后自动生成的 config.json）：\r
```json\r
{\r
  "openId": "注册成功后自动保存的openId"\r
}\r
```\r
\r
### 可选 API 环境\r
\r
| 环境 | URL |\r
|------|-----|\r
| 生产环境 | `https://api-open.uupt.com/openapi/v3/` |\r
| 测试环境 | `http://api-open.test.uupt.com/openapi/v3/` |\r
\r
---\r
\r
## 在代码中使用\r
\r
### Node.js\r
\r
```javascript\r
const { orderPrice, createOrder, orderDetail, cancelOrder, driverTrack } = require('./index');\r
\r
// 订单询价\r
const priceResult = await orderPrice({\r
  fromAddress: '郑州市金水区农业路经三路交叉口',\r
  toAddress: '郑州市二七区德化街100号',\r
  cityName: '郑州市'\r
});\r
\r
// 创建订单\r
const orderResult = await createOrder({\r
  priceToken: priceResult.body.priceToken,\r
  receiverPhone: '13800138000'\r
});\r
\r
// 检查是否需要支付\r
if (orderResult.body.orderUrl) {\r
  console.log('需要支付，打开链接:', orderResult.body.orderUrl);\r
}\r
\r
// 查询订单\r
const detailResult = await orderDetail({\r
  orderCode: orderResult.body.orderCode\r
});\r
```\r
\r
### Python\r
\r
```python\r
from uupt_delivery import order_price, create_order, order_detail, cancel_order, driver_track\r
\r
# 订单询价\r
price_result = order_price(\r
    from_address='郑州市金水区农业路经三路交叉口',\r
    to_address='郑州市二七区德化街100号',\r
    city_name='郑州市'\r
)\r
\r
# 创建订单\r
order_result = create_order(\r
    price_token=price_result['body']['priceToken'],\r
    receiver_phone='13800138000'\r
)\r
\r
# 检查是否需要支付\r
if order_result['body'].get('orderUrl'):\r
    print('需要支付，打开链接:', order_result['body']['orderUrl'])\r
\r
# 查询订单\r
detail_result = order_detail(\r
    order_code=order_result['body']['orderCode']\r
)\r
```\r
\r
---\r
\r
## 注意事项\r
\r
- **首次使用**：首次使用时需要通过手机号验证获取授权，之后无需重复操作\r
- **图片验证码**：如果发送短信验证码时返回 `[IMAGE_CAPTCHA_REQUIRED]`，需要展示 base64 图片让用户识别数字后重试\r
- **注册重试**：授权失败时自动重试，最多 3 次（不用重新输入手机号）\r
- **询价有效期**：priceToken 有时效性，建议获取后尽快创建订单\r
- **地址完整性**：地址信息越完整，配送越准确\r
- **城市默认值**：如未指定城市，默认使用"郑州市"\r
- **价格单位**：API 返回的价格单位是分，展示时需除以 100 转换为元\r
- **订单状态**：创建订单后请关注订单状态变化\r
- **余额不足**：当返回 `[PAYMENT_REQUIRED]` 时，微信渠道用 `message` 工具发送 `{QRCODE_FILE}` 二维码图片附件；其他渠道直接发送 `{PAYMENT_URL}` 支付链接\r
- **配置文件**：`defaults.json` 为内置凭证，请勿修改或删除\r
\r
## 相关链接\r
\r
- [UU跑腿开放平台](https://open.uupt.com)\r
- [API 文档](https://open.uupt.com/docs)\r