# Kuaidi100 Logistics

> 快递100物流查询与寄件指导技能。使用企业版API提供准确快速的快递查询服务，支持主流快递公司（中通、圆通、顺丰、申通、韵达、京东、EMS等）。当用户询问快递状态、物流轨迹、包裹位置、预计到达时间、快递单号查询、寄快递时，必须使用本技能。也适用于需要手机号验证的快递查询（如顺丰、中通）、需要时效预测的查询、以及国际快递查询。本技能提供标准化的输出格式、准确的时效预测和专业的错误处理指导。

- Skill: `dvcrn/kuaidi100-logistics` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add dvcrn/kuaidi100-logistics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/kuaidi100-logistics/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/kuaidi100-logistics

---


# 🚚 快递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企业版后台获取 |

**配置示例**：
```bash
# 在可信环境中配置
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 环境变量配置
```bash
# 必须配置的环境变量
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](https://www.kuaidi100.com)
- **APP**：应用商店搜索"快递100"
- **小程序**：微信搜索"快递100"

### 服务流程
1. 用户选择寄件渠道（官网/APP/小程序）
2. 填写收寄信息、选择快递公司
3. 下单后快递员按约定时间上门取件
4. 支付运费，获取电子运单

### 回答模板
```
## 📮 寄快递指导

您可以通过以下渠道下单寄件：

**推荐渠道**：
1. **快递100官网**：https://www.kuaidi100.com
2. **快递100 APP**：应用商店搜索下载
3. **微信小程序**：搜索"快递100"

**操作流程**：
1. 选择"寄快递"服务
2. 填写收件人、寄件人信息
3. 选择快递公司和服务类型
4. 预约上门取件时间
5. 快递员按时上门取件

**优势**：
- 多家快递公司比价
- 上门取件，方便快捷
- 电子运单，环保安全
- 实时跟踪，全程可视
```

---

## 🛡️ 隐私与安全

### 数据保护
- 单号、手机号、地址仅用于API请求
- 不持久化存储用户隐私数据
- 环境变量中的key不写入日志

### 使用规范
- 同一单号查询间隔≥30分钟
- 企业版key勿泄露或写入代码
- 遵守快递100API使用条款

---

## 🔍 更多资源

### 参考文档
- [快递公司编码表](https://api.kuaidi100.com/manager/openapi/download/kdbm.do)
- [API接口文档](https://api.kuaidi100.com/document/5f0ffb5ebc8da837cbd8aefc)
- [错误码说明](https://api.kuaidi100.com/document/5f0ffb5ebc8da837cbd8aefc#h2-8)
- [本地编码参考](reference.md) - 常用快递公司编码速查

### 技能脚本
- `scripts/query_express.py` - API查询脚本

### 技术支持
- 快递100客服：400-000-0387
- 企业版技术支持：企业后台工单系统

---

## 📈 性能指标（基于评估）

### 基准测试结果
- **执行效率**：比无技能版本快51.9%
- **Token节省**：比无技能版本节省20.6%
- **数据准确性**：企业版API确保数据可靠
- **用户满意度**：标准化输出提升体验

### 持续优化
本技能已通过skill-creator评估优化，将持续迭代改进。如有问题或建议，请反馈以便进一步优化。