kuaidi100-user

by kuaidi100-api

Install this Skill

curl -fsSL -o kuaidi100-user.zip https://skill.seembox.com/api/v1/skills/kuaidi100-user/download && unzip kuaidi100-user.zip

Download kuaidi100-user.zip

SKILL.md About

---
name: kuaidi100-user
description: "快递100用户版智能寄件助手：寄件下单全流程（支持无Key模式/完整模式）、物流查询、订单管理。无Key模式优先使用本地缓存数据自动填充寄件人和收件人，完整模式支持服务端地址簿查询和物流跟踪。Use when: 用户要寄快递、查物流、管理快递订单、比价选快递、查运费，或提到快递100/寄件/查单/运费/快递价格相关服务。"
---

# 快递100用户版

## 运行模式

### 无Key模式（默认）
用户未提供 API Key 时自动进入此模式：

**核心逻辑：优先使用本地数据，减少用户询问**

**寄件人获取流程（本地优先）：**
```
Level 1: data_manager.load_default_sender() (本地缓存)
    ↓ 有数据 → 展示给用户确认
    ↓ 无数据
Level 2: 手动询问
    → 询问姓名、手机号、详细地址
    → 保存到本地缓存供下次使用
```

**收件人获取流程（本地优先）：**
```
1. 用户输入收件人姓名
2. data_manager.find_receiver_by_name() → 本地历史模糊匹配
3. 命中?
   ├── 1条 → 直接展示，让用户确认
   ├── 多条 → 列表展示，让用户选择
   └── 0条 → 询问完整收件人信息 → 保存到本地
```

**本地数据管理：**
- 寄件人：保存1个默认寄件人
- 收件人：保存最近10个，自动去重，90天过期
- 订单：保存最近50个，365天过期
- 存储位置：`~/.openclaw/kuaidi100-user/data/`

**可用功能：**
- ✅ 地址解析、物品重量查询、快递公司比价
- ✅ 本地寄件人/收件人自动填充
- ✅ **预下单**（提交信息获取下单链接）
- ❌ 服务端地址簿查询、物流查询、订单管理

### 完整模式（需API Key）
用户设置 `KUAIDI100_USER_API_KEY` 环境变量后解锁全部功能：
- 服务端默认寄件人查询
- 服务端地址簿匹配收件人
- 物流查询、订单管理

## 前置要求

- **API Key**：环境变量 `KUAIDI100_USER_API_KEY`（可选，无Key时使用本地数据）
- **API 地址**：固定 `https://p.kuaidi100.com`
- **依赖**：Python 3.7+、`requests` 库

## 快速开始

### 无Key模式（首次使用，无需API Key）

```bash
# 1. 测试地址解析
python3 ~/openclaw/workspace/skills/kuaidi100-user/scripts/api_client.py address "深圳市南山区科技园"

# 2. 查询物品重量
python3 ~/openclaw/workspace/skills/kuaidi100-user/scripts/api_client.py weight "手机"

# 3. 开始寄件对话
# 直接说"我要寄快递"，系统会引导您完成全流程
```

### 完整模式（需要API Key）

```bash
# 1. 设置API Key
export KUAIDI100_USER_API_KEY='your_key'

# 2. 检查Key状态
python3 ~/openclaw/workspace/skills/kuaidi100-user/scripts/api_client.py status

# 3. 查询默认寄件人
python3 ~/openclaw/workspace/skills/kuaidi100-user/scripts/api_client.py sender

# 4. 查询最近订单
python3 ~/openclaw/workspace/skills/kuaidi100-user/scripts/api_client.py orders
```

## 获取API Key（可选）

1. 打开微信 → 搜索「快递100」小程序
2. 进入「我的」→ 点击「API KEY」→ 点击「申请」获取 API KEY
3. 生成密钥后设置环境变量：
   ```bash
   export KUAIDI100_USER_API_KEY='your_key'
   ```

## 脚本说明

- **`scripts/api_client.py`** — API客户端，10个接口方法。支持无Key模式自动降级，有Key时所有接口自动传Key。
- **`scripts/data_manager.py`** — 本地数据持久化。提供寄件人缓存、收件人历史、订单存取。与`api_client`配合实现双通道查询。

## 寄件流程概览

### 无Key模式
```
Step 1: 获取寄件人 → 本地缓存 → 手动询问（保存到本地）
Step 2: 获取收件人 → 本地模糊匹配 → 手动输入（保存到本地）
Step 3: 物品信息   → 查重量 → 确认
Step 4: 地址解析   → 结构化自由文本地址
Step 5: 查快递公司 → 比价 → 用户选择
Step 6: 确认下单   → 预下单 → 展示链接 → 保存订单到本地
```

### 完整模式
```
Step 1: 获取寄件人 → 服务端查询 → 本地缓存 → 手动询问
Step 2: 获取收件人 → 服务端地址簿匹配 → 本地缓存 → 手动输入
Step 3: 物品信息   → 查重量 → 确认
Step 4: 地址解析   → 结构化自由文本地址
Step 5: 查快递公司 → 比价 → 用户选择
Step 6: 确认下单   → 预下单 → 展示链接 → 保存订单到本地
Step 7: 物流查询   → 双通道查询（本地+服务端）
```

每个步骤的决策分支、降级策略、双通道查询逻辑详见 **[references/workflow.md](references/workflow.md)**。

## 物流查询

- **无Key模式**：仅查询本地 `load_recent_orders()`
- **完整模式**：双通道查询
  - 本地 `load_recent_orders()` + 服务端 `queryUserOrders()`
  - 合并去重展示

## 取消订单

- **无Key模式**：不支持（需API Key）
- **完整模式**：确认订单号 + 取消原因 → 调用 `cancelOrder`

## 核心原则

- **分步交互**：每步只问一类信息，等用户回答后再进入下一步。禁止一次性列出所有问题。
- **本地优先（无Key模式）**：新接口能力叠加在原有流程上，原流程步骤完整保留
- **双通道查询（完整模式）**：本地缓存（快速）+ 服务端（实时）互为补充
- **异常降级**：服务端接口失败时回退到本地缓存或手动询问，不中断流程
- **必须询问**：物品类型、最终确认不可跳过
- **绝不自动执行**：不猜测物品、不自动选收件人、不跳过确认直接下单
- **下单后必须展示链接**：获取到下单链接后，**必须以文本形式**展示下单链接和二维码，然后可选地用浏览器工具自动打开。文本展示是必选项，浏览器打开是可选项——无论浏览器是否成功，用户都能看到链接完成下单。
- **适时提示完整模式**：在无Key模式下，以下时机应自然地提醒用户可配置 API Key 解锁完整功能：
  - **寄件下单成功后**：在展示下单结果时附加一句提示，例如「💡 配置 API Key 后可使用物流跟踪、地址簿同步等更多功能，详见 SKILL.md」
  - **用户主动查询物流/订单时**：明确告知当前为无Key模式，只能查本地缓存，引导配置 Key
  - **仅限一次提示**：每次会话最多提示一次，不重复打扰。用户明确拒绝后不再提醒

## 分步交互规则

**关键**：寄件流程是多轮对话，不是一次表单。每次只问一件事，拿到答案再往下走。

```
轮次1: "请提供寄件人信息" → 等用户回答（无Key模式）/ 展示自动填充信息让用户确认（完整模式）
轮次2: "请提供收件人信息" → 等用户回答
轮次3: "要寄什么物品？" → 等用户回答
轮次4: "以下是可选快递，请选择" → 等用户回答
轮次5: "确认以下订单信息，是否下单？" → 等用户确认
```

每步之间可以做 API 调用（查地址簿、查重量、查价格），但对用户只呈现一步的问题或选项。

## 参考资料

- **[工作流](references/workflow.md)** — 完整决策逻辑、双通道策略、异常降级矩阵
  - 包含无Key模式和完整模式的详细流程对比
  - 分步交互规则和降级策略
  - 寄件人/收件人获取的三分支处理逻辑
- **[API文档](references/api_docs.md)** — 10个接口定义、参数、响应格式、错误码
  - 标注每个接口是否需要API Key
  - 字段映射速查表（地址簿→下单、快递公司→下单）
- **[数据字段](references/workflow.md#十一完整数据字段)** — 地址簿、快递公司、下单返回等完整字段说明

_meta.json Metadata

{
  "ownerId": "kn77t48c53bvrrp2mv60d0rf8n832d6r",
  "publishedAt": 1774848931120,
  "slug": "kuaidi100-user",
  "version": "1.0.2"
}