kuaidi100-user

# 快递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#十一完整数据字段)** — 地址簿、快递公司、下单返回等完整字段说明