UU跑腿同城配送服务 Skill

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

功能特性

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

运行环境选择

本 skill 同时提供 Node.js 和 Python 两种版本，可根据你的环境选择：

环境	依赖安装	脚本位置
Node.js	INLINECODE0	INLINECODE1 和 INLINECODE2
Python

pip install -r requirements.txt | uupt_delivery.py |

Agent 会自动检测可用环境并选择合适的版本执行。

首次使用

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

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

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

CODEBLOCK0

或通过环境变量设置：
CODEBLOCK1

配置完成后即可直接使用所有功能，无需注册流程。

方式二：快速体验模式（手机号注册）

首次安装时 config.json 文件不存在，这是正常的。 执行任何功能脚本会自动检测是否需要注册：

• - 如果输出中包含 [REGISTRATION_REQUIRED]，说明需要先完成手机号验证
• Agent 应自动进入场景零（首次注册）引导用户完成注册
• 注册完成后，系统自动创建 config.json 并保存 openId，后续使用无需重复注册
• 此模式使用内置的默认 appId/appSecret

认证状态检查

当 appId、appSecret、openId 三个值都已配置（无论通过哪种方式），后续使用将不再要求用户提供凭证。

触发条件

用户表达了以下意图之一：

• - 询问配送价格（如"从A地址送到B地址多少钱"、"帮我算下配送费"）
• 下单配送（如"帮我发个跑腿单"、"我要寄东西"、"同城配送"）
• 查询订单（如"查看订单状态"、"订单到哪了"）
• 取消订单（如"取消这个订单"、"不想发了"）
• 追踪跑男（如"骑手在哪"、"跑男到哪了"、"配送进度"）
• 包含"跑腿"、"配送"、"寄送"、"订单"、"骑手"、"跑男"等关键词

场景判断

收到用户请求后，先判断属于哪个场景：

• - 场景零：首次注册 — 任何功能执行时检测到 [REGISTRATION_REQUIRED]，先询问用户是否已有凭证
• 场景一：订单询价 - 用户想知道配送费用，需要提供起始地址和目的地址
• 场景二：创建订单 - 用户确认发单，需要询价返回的 priceToken 和收件人电话
• 场景三：查询订单详情 - 用户想查看订单状态，需要订单编号
• 场景四：取消订单 - 用户要取消订单，需要订单编号
• 场景五：跑男追踪 - 用户想查看跑男实时位置，需要订单编号

---

场景零：首次注册 / 获取授权

当执行任何功能脚本时，如果输出中包含 [REGISTRATION_REQUIRED]，说明用户尚未完成配置。

触发条件

• - 执行任何脚本时输出包含 INLINECODE15
• 这是一个自动触发场景，不需要用户主动发起

执行步骤

Step 1: 询问用户是否已有凭证

向用户询问：

CODEBLOCK2

如果用户选择 A（已有凭证）→ 进入 Step 1A
如果用户选择 B（没有凭证）→ 进入 Step 2

---

Step 1A: 获取用户凭证并保存

请用户提供三个值：

• - appId
• appSecret
• openId

获取后，将凭证写入 config.json 文件：
CODEBLOCK3

保存成功后：

• - 告知用户「配置完成！」
• 立即继续执行用户最初要求的功能（无需用户再次操作）

---

Step 2: 询问手机号（快速体验模式）

向用户询问：「请输入您的手机号码，我们将发送验证码完成注册」

Step 3: 发送短信验证码

Node.js 版本：
CODEBLOCK4

Python 版本：
CODEBLOCK5

处理结果：

• - 输出 [SMS_SENT] → 验证码发送成功，提示用户查看手机短信，进入 Step 4
• 输出 [IMAGE_CAPTCHA_REQUIRED] → 需要图片验证码，处理方式：

- 输出中包含 IMAGE_DATA=data:image/png;base64,... 的 base64 图片数据
- 将 base64 图片展示给用户（可使用 show_widget 工具展示 <img src="IMAGE_DATA中的内容">）
- 请用户识别图片中的数字
- 用户回复后，重新调用（带 --imageCode 参数）：
CODEBLOCK6

Step 4: 输入短信验证码

提示用户：「验证码已发送，请输入您收到的短信验证码」

Step 5: 完成授权

Node.js 版本：
CODEBLOCK7

Python 版本：
CODEBLOCK8

处理结果：

• - 输出 [REGISTRATION_SUCCESS] → 注册成功，openId 已自动保存到配置文件

- 告知用户注册成功
- 立即继续执行用户最初要求的功能（无需用户再次操作）

• - 输出 [REGISTRATION_FAILED] → 注册失败

- 不需要重新询问手机号
- 从 Step 3 开始重试（重新发送验证码 → 用户输入新验证码 → 重新授权）
- 最多重试 3 次
- 3 次仍失败 → 告知用户稍后再试或联系客服

回复模板（注册成功后）

CODEBLOCK9

---

场景一：订单询价

计算从起始地址到目的地址的配送费用。用户可以只询价不发单。

执行步骤

1. 1. 执行询价脚本：从用户输入中提取起始地址、目的地址、城市（可选）
2. 如果输出 [REGISTRATION_REQUIRED]：进入场景零完成注册后，重新执行询价

使用方法

Node.js 版本：
CODEBLOCK10

Python 版本：
CODEBLOCK11

参数说明

参数 (JS)	参数 (Python)	说明	必填
INLINECODE25	INLINECODE26	起始地址（完整地址）	是
INLINECODE27

--to-address | 目的地址（完整地址） | 是 | | --cityName | --city | 城市名称（需要带"市"字） | 否 |

返回结果

返回包含 priceToken 和价格信息，价格单位为分，需要格式化为元展示给用户。

回复模板

CODEBLOCK12

---

场景二：创建订单（发单）

当用户明确表示要发单/下单时，询价后直接创建订单，无需二次确认。

触发条件

用户表达了发单意图，如：

• - "帮我发个单"、"我要寄东西"、"帮我下单"
• "从A送到B，收件人电话xxx"
• "帮我配送xxx到xxx"

执行步骤

1. 1. 获取必要信息：起始地址、目的地址、收件人电话（必须在发单前获取）
2. 调用询价接口：获取 priceToken
3. 立即创建订单：使用 priceToken 直接创建订单，不询问用户是否确认
4. 处理返回结果：根据余额情况进行不同处理

使用方法

Step 1: 先询价获取 priceToken

Node.js 版本：
CODEBLOCK13

Python 版本：
CODEBLOCK14

Step 2: 立即创建订单

⚠️ 重要：如果是微信渠道，必须传递 --channel="wechat" 参数以生成支付二维码图片。

Node.js 版本：
CODEBLOCK15

Python 版本：
CODEBLOCK16

参数说明

参数 (JS)	参数 (Python)	说明	必填
INLINECODE33	INLINECODE34	询价接口返回的 token	是
INLINECODE35

--receiver-phone | 收件人手机号 | 是 | | --channel | --channel | 聊天渠道（wechat/feishu/dingtalk 等） | 否 |

返回结果处理

情况一：余额充足，订单创建成功

直接返回订单编号，告知用户订单已创建成功。

回复模板：

订单创建成功！

订单编号：{order_code}
配送费用：{price/100} 元

骑手正在接单中，请保持电话畅通。

---

情况二：余额不足，需要在线支付

当返回的 JSON 中 body.orderUrl 不为空时，表示需要用户完成支付。

识别标记：脚本输出包含 [PAYMENT_REQUIRED] 时表示需要支付。

关键输出：

• - ORDER_CODE={order_code} — 订单编号
• INLINECODE42 — 支付链接（用户点击后可选择微信或支付宝支付）
• INLINECODE43 — 支付二维码图片本地路径（只有传递 --channel="wechat" 时才有此输出）

处理流程：

1. 1. 根据渠道调用脚本：

• - 微信渠道：必须传递 --channel="wechat" 参数以生成二维码图片
• 其他渠道：无需传递 --channel 参数

1. 2. 根据渠道展示支付信息：

渠道适配：发送支付信息

⚠️ 微信渠道特殊处理：微信中链接无法直接打开，必须发送二维码图片附件！

微信渠道：
CODEBLOCK18

其他渠道（飞书/钉钉/企业微信/QQ/Telegram/其他）：直接发送支付链接：
CODEBLOCK19

回复模板

微信渠道专用：
CODEBLOCK20

其他渠道：
CODEBLOCK21

重要说明：

• - 微信渠道必须用 message(action=send, channel="wechat", path="{QRCODE_FILE}") 发送二维码图片附件
• 其他渠道直接发送 {PAYMENT_URL} 支付链接

1. 3. 等待用户返回：用户支付后会回来

1. 4. 确认支付状态：当用户回来时，询问用户是否已完成支付：

CODEBLOCK22

1. 5. 用户确认支付完成后：立即调用订单详情接口查询订单状态

Node.js 版本：
CODEBLOCK23

Python 版本：
CODEBLOCK24

1. 6. 展示订单详情：

CODEBLOCK25

完整交互流程示例

CODEBLOCK26

---

场景三：查询订单详情

查看订单的当前状态和详细信息。

执行步骤

1. 1. 获取订单编号：从用户输入或上下文中获取订单编号
2. 调用查询接口

使用方法

Node.js 版本：
CODEBLOCK27

Python 版本：
CODEBLOCK28

参数说明

参数 (JS)	参数 (Python)	说明	必填
INLINECODE49	INLINECODE50	订单编号	是

回复模板

CODEBLOCK29

---

场景四：取消订单

取消未完成的配送订单。

执行步骤

1. 1. 获取订单编号：从用户输入获取
2. 确认取消原因：询问用户取消原因（可选）
3. 调用取消接口

使用方法

Node.js 版本：
CODEBLOCK30

Python 版本：
CODEBLOCK31

参数说明

参数 (JS)	参数 (Python)	说明	必填
INLINECODE51	INLINECODE52	订单编号	是
INLINECODE53

--reason | 取消原因 | 否 |

回复模板

CODEBLOCK32

---

场景五：跑男实时追踪

查询配送骑手的实时位置和状态。

执行步骤

1. 1. 获取订单编号：从用户输入获取
2. 调用跑男追踪接口

使用方法

Node.js 版本：
CODEBLOCK33

Python 版本：
CODEBLOCK34

参数说明

参数 (JS)	参数 (Python)	说明	必填
INLINECODE55	INLINECODE56	订单编号	是

回复模板

CODEBLOCK35

---

配置管理

配置分为两层：

• - defaults.json：内置应用凭证（appId、appSecret、apiUrl），随 Skill 分发，请勿修改
• config.json：用户级配置，首次安装时不存在，通过以下方式创建：

- 开发者模式：用户提供 appId、appSecret、openId 后写入 - 快速体验模式：注册成功后自动创建，仅包含 openId

配置优先级（从高到低）

配置项	环境变量	config.json	defaults.json
appId	INLINECODE59	INLINECODE60	INLINECODE61
appSecret

UUPT_APP_SECRET | appSecret | appSecret | | openId | UUPT_OPEN_ID | openId | - | | apiUrl | UUPT_API_URL | apiUrl | apiUrl |

配置示例

开发者模式（用户提供凭证后写入 config.json）：
CODEBLOCK36

快速体验模式（注册后自动生成的 config.json）：
CODEBLOCK37

可选 API 环境

环境	URL
生产环境	INLINECODE70
测试环境

http://api-open.test.uupt.com/openapi/v3/ |

---

在代码中使用

Node.js

CODEBLOCK38

Python

CODEBLOCK39

---

注意事项

• - 首次使用：首次使用时需要通过手机号验证获取授权，之后无需重复操作
• 图片验证码：如果发送短信验证码时返回 [IMAGE_CAPTCHA_REQUIRED]，需要展示 base64 图片让用户识别数字后重试
• 注册重试：授权失败时自动重试，最多 3 次（不用重新输入手机号）
• 询价有效期：priceToken 有时效性，建议获取后尽快创建订单
• 地址完整性：地址信息越完整，配送越准确
• 城市默认值：如未指定城市，默认使用"郑州市"
• 价格单位：API 返回的价格单位是分，展示时需除以 100 转换为元
• 订单状态：创建订单后请关注订单状态变化
• 余额不足：当返回 [PAYMENT_REQUIRED] 时，微信渠道用 message 工具发送 {QRCODE_FILE} 二维码图片附件；其他渠道直接发送 {PAYMENT_URL} 支付链接
• 配置文件：defaults.json 为内置凭证，请勿修改或删除

相关链接

• - UU跑腿开放平台
• API 文档