- 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）
# 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）
# 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（可选）
- 打开微信 → 搜索「快递100」小程序
- 进入「我的」→ 点击「API KEY」→ 点击「申请」获取 API KEY
- 生成密钥后设置环境变量：
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。
物流查询
- 无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 调用（查地址簿、查重量、查价格），但对用户只呈现一步的问题或选项。
参考资料
- 工作流 — 完整决策逻辑、双通道策略、异常降级矩阵
- 包含无Key模式和完整模式的详细流程对比 - 分步交互规则和降级策略 - 寄件人/收件人获取的三分支处理逻辑
- API文档 — 10个接口定义、参数、响应格式、错误码
- 标注每个接口是否需要API Key - 字段映射速查表（地址簿→下单、快递公司→下单）
- 数据字段 — 地址簿、快递公司、下单返回等完整字段说明