name: kuaidi100-logistics description: | 快递100物流查询与寄件指导技能。使用企业版API提供准确快速的快递查询服务，支持主流快递公司（中通、圆通、顺丰、申通、韵达、京东、EMS等）。当用户询问快递状态、物流轨迹、包裹位置、预计到达时间、快递单号查询、寄快递时，必须使用本技能。也适用于需要手机号验证的快递查询（如顺丰、中通）、需要时效预测的查询、以及国际快递查询。本技能提供标准化的输出格式、准确的时效预测和专业的错误处理指导。 requires: env: - KUAIDI100_KEY: 快递100企业版API密钥（可选，用于API查询） - KUAIDI100_CUSTOMER: 快递100企业版客户编码（可选，用于API查询） scripts: - query_express.py: Python脚本，需要urllib、hashlib、json、os模块 security:

本技能会读取环境变量KUAIDI100_KEY和KUAIDI100_CUSTOMER（如果配置）
如果未配置API密钥，会使用Playwright打开快递100官网进行网页查询
建议在可信环境中使用，或仅使用Playwright网页查询模式
脚本代码开源可审计，建议在使用前检查脚本内容

🚚 快递100 物流信息服务

⚠️ 安全使用指南

重要安全提示：

环境变量安全：本技能会读取环境变量KUAIDI100_KEY和KUAIDI100_CUSTOMER。请仅在可信环境中配置这些敏感信息。
脚本审计：建议在使用前检查scripts/目录下的Python脚本，它们都是开源可审计的。
权限控制：如果不信任当前运行环境，建议不要配置API密钥，仅使用Playwright网页查询模式。
网络请求：本技能会向快递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"

安全建议：

仅在可信环境中配置这些环境变量
不要将密钥提交到版本控制系统
定期轮换API密钥
如果不信任当前环境，请使用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使用条款

🔍 更多资源

参考文档

技能脚本

scripts/query_express.py - API查询脚本

技术支持

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

📈 性能指标（基于评估）

基准测试结果

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

持续优化

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

kuaidi100-logistics

Description