kuaidi100-logistics
v1.0.4快递100物流查询与寄件指导技能。使用企业版API提供准确快速的快递查询服务，支持主流快递公司（中通、圆通、顺丰、申通、韵达、京东、EMS等）。当用户询问快递状态、物流轨迹、包裹位置、预计到达时间、快递单号查询、寄快递时，必须使用本技能。也适用于需要手机号验证的快递查询（如顺丰、中通）、需要时效预测的查询、以及国际快递查询。本技能提供标准化的输出格式、准确的时效预测和专业的错误处理指导。
Sourced from ClawHub,
Authored by peterlcm
Installation
🚚 快递100 物流信息服务
⚠️ 安全使用指南
重要安全提示：
1. 环境变量安全：本技能会读取环境变量KUAIDI100_KEY和KUAIDI100_CUSTOMER。请仅在可信环境中配置这些敏感信息。
2. 脚本审计：建议在使用前检查scripts/目录下的Python脚本，它们都是开源可审计的。
3. 权限控制：如果不信任当前运行环境，建议不要配置API密钥，仅使用Playwright网页查询模式。
4. 网络请求：本技能会向快递100 API或官网发起网络请求。
推荐使用方式： - 可信环境：配置API密钥，享受快速准确的查询服务 - 不可信环境：不配置API密钥，使用Playwright网页查询（用户可在浏览器中查看结果） - 本地运行：优先在本地环境中使用，避免将API密钥暴露给不可控的托管服务
快速开始：当用户提到快递、物流、包裹、单号查询时，立即使用本技能！
✨ 技能优势
- ✅ 数据准确：使用快递100企业版API，数据实时可靠
- ✅ 执行快速：相比手动查询，效率提升50%以上
- ✅ 功能全面：支持100+家快递公司，包括国际快递
- ✅ 专业处理：正确处理手机验证、时效预测等复杂场景
- ✅ 标准输出：提供统一格式的查询结果和错误处理
📋 何时必须使用本技能
立即触发本技能当用户： - 提供快递单号需要查询状态、轨迹、位置 - 询问包裹到哪里了、什么时候能到 - 需要时效预测、预计到达时间 - 查询顺丰、中通等需要手机验证的快递 - 需要寄快递、下单快递、快递上门取件 - 询问国际快递、跨境物流状态 - 提到物流跟踪、包裹查询、运单查询
关键词触发：快递查询、物流查询、包裹跟踪、快递单号、运单号、物流单号、预计到达、时效预测、什么时候到、寄快递、下单快递、快递上门、顺丰、中通、圆通、韵达、申通、京东、EMS、DHL、FedEx、UPS。
🚀 快速使用指南
场景1：基础快递查询
用户：圆通快递YT2584197775718现在到哪里了？
你：使用本技能查询，参数：com=yuantong, num=YT2584197775718
场景2：带手机验证的查询
用户：帮我查一下中通快递73598926941388，手机尾号5052
你：使用本技能查询，参数：com=zhongtong, num=73598926941388, phone=5052
场景3：需要时效预测的查询
用户：这个快递什么时候能到拉萨？
你：使用本技能查询，参数：resultv2=8, to=目的地地址
场景4：寄快递指导
用户：我想寄个快递到北京
你：使用本技能引导用户通过快递100官网/APP/小程序下单
📊 标准输出模板
查询结果报告模板
## 📦 快递查询结果
**基本信息**
- 快递单号：{单号}
- 快递公司：{公司名称}
- 查询时间：{查询时间}
- 当前状态：{状态描述}
**物流轨迹**
{按时间倒序列出轨迹，每条包含时间、地点、状态}
**时效预测**（如可提供）
- 预计到达：{预计时间}
- 剩余时间：{剩余时间}
- 准确率：{概率}
**温馨提示**
- 同一单号查询间隔请至少30分钟
- 如有问题可联系快递公司客服
- 更多详情请使用快递100APP
错误响应模板
## ⚠️ 查询遇到问题
**错误信息**：{错误描述}
**错误码**：{错误代码}
**可能原因**：{原因分析}
**解决建议**：{处理建议}
**常见问题**：
1. 单号错误：请核对快递单号
2. 公司错误：确认快递公司是否正确
3. 频率限制：请30分钟后再查询
4. 手机验证：顺丰、中通需要手机号
🔧 查快递：实时查询接口
核心优势
- 企业版API：数据更准确、更新更及时
- 批量查询：支持同时查询多个快递
- 智能识别：自动识别快递公司
- 时效预测：提供准确的到达时间预测
1.1 请求说明
| 项目 | 说明 |
|---|---|
| 请求地址 | https://poll.kuaidi100.com/poll/query.do |
| 请求方式 | POST |
| Content-Type | application/x-www-form-urlencoded |
1.2 环境变量配置
重要：使用API查询前，需要配置以下环境变量：
| 环境变量 | 说明 | 获取方式 |
|---|---|---|
KUAIDI100_KEY |
快递100企业版API密钥 | 从快递100企业版后台获取 |
KUAIDI100_CUSTOMER |
快递100企业版客户编码 | 从快递100企业版后台获取 |
配置示例：
# 在可信环境中配置
export KUAIDI100_KEY="your_api_key_here"
export KUAIDI100_CUSTOMER="your_customer_code_here"
安全建议： 1. 仅在可信环境中配置这些环境变量 2. 不要将密钥提交到版本控制系统 3. 定期轮换API密钥 4. 如果不信任当前环境，请使用Playwright网页查询模式
1.3 必填参数
| 参数 | 说明 | 关键点 |
|---|---|---|
| customer | 企业版授权码 | 从环境变量KUAIDI100_CUSTOMER读取 |
| sign | MD5签名 | param+key+customer拼接后MD5大写 |
| param | JSON字符串 | 包含查询参数 |
param 关键字段：
- com：快递公司编码（小写，如zhongtong、yuantong、shunfeng）
- num：快递单号（6-32位）
- phone：手机号（顺丰、中通必填）
- to：目的地（时效预测必填）
- resultv2：8（启用时效预测）
1.3 环境变量配置
# 必须配置的环境变量
export KUAIDI100_KEY="你的key"
export KUAIDI100_CUSTOMER="你的customer"
配置检查：执行查询前先检查环境变量是否已配置！
🐛 常见错误处理
错误码速查表
| 代码 | 含义 | 处理建议 |
|---|---|---|
| 200 | 查询成功 | - |
| 400 | 找不到对应公司 | 检查com编码、账号权限 |
| 408 | 验证码错误 | 检查phone参数（顺丰/中通） |
| 500 | 查询无结果 | 确认单号正确、是否已发货 |
| 503 | 签名验证失败 | 检查sign计算：param+key+customer |
| 601 | key已过期 | 账号需要充值 |
特殊快递处理
顺丰快递： - 必须提供收件人手机号后4位 - 虚拟号码传「-」后四位 - 查询频率限制严格
中通快递： - 需要手机号验证 - 支持虚拟号码 - 时效预测较准确
国际快递： - 支持DHL、FedEx、UPS等 - 可能需要额外参数 - 时效预测可能不准确
📱 寄快递服务
服务渠道
- 官网：https://www.kuaidi100.com
- APP：应用商店搜索"快递100"
- 小程序：微信搜索"快递100"
服务流程
- 用户选择寄件渠道（官网/APP/小程序）
- 填写收寄信息、选择快递公司
- 下单后快递员按约定时间上门取件
- 支付运费，获取电子运单
回答模板
## 📮 寄快递指导
您可以通过以下渠道下单寄件：
**推荐渠道**：
1. **快递100官网**：https://www.kuaidi100.com
2. **快递100 APP**：应用商店搜索下载
3. **微信小程序**：搜索"快递100"
**操作流程**：
1. 选择"寄快递"服务
2. 填写收件人、寄件人信息
3. 选择快递公司和服务类型
4. 预约上门取件时间
5. 快递员按时上门取件
**优势**：
- 多家快递公司比价
- 上门取件，方便快捷
- 电子运单，环保安全
- 实时跟踪，全程可视
🛡️ 隐私与安全
数据保护
- 单号、手机号、地址仅用于API请求
- 不持久化存储用户隐私数据
- 环境变量中的key不写入日志
使用规范
- 同一单号查询间隔≥30分钟
- 企业版key勿泄露或写入代码
- 遵守快递100API使用条款
🔍 更多资源
参考文档
- 快递公司编码表
- API接口文档
- 错误码说明
- 本地编码参考 - 常用快递公司编码速查
技能脚本
scripts/query_express.py- API查询脚本
技术支持
- 快递100客服：400-000-0387
- 企业版技术支持：企业后台工单系统
📈 性能指标（基于评估）
基准测试结果
- 执行效率：比无技能版本快51.9%
- Token节省：比无技能版本节省20.6%
- 数据准确性：企业版API确保数据可靠
- 用户满意度：标准化输出提升体验
持续优化
本技能已通过skill-creator评估优化，将持续迭代改进。如有问题或建议，请反馈以便进一步优化。