快递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（可选）

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

   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
  • 字段映射速查表（地址簿→下单、快递公司→下单）
• 数据字段 — 地址簿、快递公司、下单返回等完整字段说明