快递100 Skills (kuaidi100-skills) 产品文档
一、产品介绍
快递100 Skills是一套专为 AI Agent 设计的物流查询技能包，将快递100「百递云·API开放平台」的全链路快递物流能力封装为开箱即用的标准化技能文件。支持 Claude、Cursor、WorkBuddy、OpenClaw、Hermes 等 AI Agent 工具，通过 Node.js 脚本调用快递100官方 API，实现快递物流查询相关功能。
无论您是电商运营、物流从业者还是普通用户，这套 Skill 都能让 AI 帮您快速获取快递物流信息——无需二次开发，一键安装即可让您的 AI 智能体拥有专业级查快递、估算运费、预估时效等核心能力。
二、产品特点
2.1 精准可靠
基于快递100官方 API 构建，已连接全球 超过 3,000 家 快递物流公司。快递100深耕快递物流行业16年，服务B端客户超250万家。API接口可用性达 99.9%，可承载日均4亿次查询请求，具备百万级订单量处理能力。物流轨迹实时同步，送达时间预测基于快递100自研AI时效预估模型。
2.2 安全优先
内置密钥配置指南，支持配置文件和 environment variables 两种方式，避免敏感信息硬编码。免费额度兜底机制让您无需配置即可体验核心功能。
2.3 模块化设计
按功能模块组织四个核心接口——轨迹查询、快递识别、运费估算、时效预估。AI 可按需调用，精准回答您的物流查询需求。
2.4 即插即用
Node.js 单脚本实现，无外部依赖。所有接口直接返回结构化数据，AI 可即时解析并呈现给用户，无需额外处理。
三、能力介绍
3.1 轨迹查询
| 能力 | 说明 |
|---|---|
| 物流轨迹查询 | 根据快递单号实时查询物流轨迹，支持全球3000+快递物流商 |
| 物流轨迹可视化 | 支持返回物流节点信息、预计到达时间、快递单状态等多维度信息 |
3.2 快递识别
| 能力 | 说明 |
|---|---|
| 智能识别 | 根据快递单号自动识别所属快递公司 |
3.3 运费估算
| 能力 | 说明 |
|---|---|
| 运费查询 | 根据寄件地址、收件地址和重量估算快递运费 |
| 多公司比价 | 支持顺丰、京东、德邦快递、圆通、中通、申通、韵达、EMS 等主流快递比价 |
注意：接口返回价格为预估价格，实际费用以快递公司实际产生为准。
3.4 时效预估
| 能力 | 说明 |
|---|---|
| 寄件时效预估 | 寄件前根据出发地、目的地和快递公司预估送达时间 |
| 在途时效预估 | 已寄出快递结合轨迹数据动态预测剩余到达时间 |
快递100的智能时效预估能力实现了快递查询从"快递到哪里了"向"快递何时可到"的范式转变。提供发货前的"全程预估"和发货后的"在途预估"两种模式，实现更精准的动态预测。
四、快速接入
4.1 获取 Skills 文件
通过以下渠道获取技能包文件：
| 获取渠道 | 操作内容 |
|---|---|
| 渠道一（推荐）：ClawHub | 访问链接： https://clawhub.ai/kuaidi100-api/kuaidi100-skill |
| 渠道二：腾讯云 SkillHub | 访问链接：https://skillhub.cloud.tencent.com/skills/kuaidi100-skill |
| 渠道三：OpenClaw 一键安装 | 执行命令：openclaw skills install kuaidi100-skill |
下载技能文件后，将 SKILL.md、script/kuaidi100.js 和 config.json 放置到您的 Agent Skill 目录下。
4.2 配置 API Key
方式一：配置文件
编辑 config.json：
{
"apiKey": "your_api_key_here"
}
方式二：环境变量
# Linux / macOS
export KUAIDI100_API_KEY=your_api_key_here
# Windows PowerShell
$env:KUAIDI100_API_KEY="your_api_key_here"
Key 处理规则（优先级从高到低）：
- 1）配置文件
config.json中的apiKey字段（若已设置且不为空） - 2）环境变量
KUAIDI100_API_KEY（若已设置且不为空） - 3）使用默认值（使用免费额度）
4.3 验证配置
向 AI 提问测试：
帮我查一下快递单号 SF1234567890 到哪里了
如果 AI 能够正确调用 query_trace 接口并返回物流轨迹信息，说明 Skill 已成功加载。
4.4 获取快递100 API Key（可选）
如果您需要更高的调用额度：
- 1）访问 快递100 API 开放平台
- 2）注册并登录账号
- 3）进入「API 管理」获取专属 API Key
- 4）将 Key 更新到配置文件或环境变量
额度耗尽处理：若接口返回内容包含"免费调用额度已耗尽""今日免费""额度不足"等字样，请按上述第四步获取专属 API Key 后继续使用。
五、使用示例
5.1 查询物流轨迹示例
向 AI 描述您的需求：
查一下快递单号 SF1234567890 到哪里了
AI 将调用 query_trace 接口返回实时物流轨迹。
5.2 识别快递公司示例
这个单号 1234567890123 是哪家快递公司的？
AI 将调用 auto_number 接口识别快递公司。
5.3 估算运费示例
从北京寄5公斤到深圳，用顺丰多少钱？
AI 将调用 estimate_price 接口估算运费。
5.4 预估送达时间示例
寄件前预估：
从上海寄中通快递到广州，大概几天能到？
AI 将调用 estimate_time 接口预估寄件送达时间。
在途快递预估：
我的快递到哪了？还要几天到？
AI 将调用 query_trace 获取物流轨迹，再调用 estimate_time_with_logistic 预估剩余时间。
六、接口速查表
| 接口 | 功能 | 必填参数 | 可选参数 |
|---|---|---|---|
query_trace | 查询物流轨迹 | 快递单号 | 手机号（顺丰/中通必填） |
auto_number | 识别快递公司 | 快递单号 | — |
estimate_price | 估算运费 | 快递公司编码、收件地址、寄件地址、重量 | — |
estimate_time | 预估寄件送达时间 | 快递公司编码、收件地址、寄件地址 | — |
estimate_time_with_logistic | 预估在途快递送达时间 | 快递单号 | 手机号 |
七、目录结构
kuaidi100-skill/
├── SKILL.md # 技能主文件（AI 入口）
├── README.md # 产品介绍文档
├── config.json # API Key 配置文件
└── script/
└── kuaidi100.js # Node.js 接口脚本
八、常见问题
Q: 免费额度有多少？
快递100Skills为用户提供每日10次免费调用额度。
Q: 额度耗尽怎么办？
AI 会自动检测接口返回中的"免费调用额度已耗尽""今日免费""额度不足"等提示，需前往百递云·开放平台充值开通对应服务方可继续使用。
Q: 支持哪些快递公司？
快递100已连接全球超过 3,000 家快递物流公司。运费估算和时效预估接口支持多个主流快递商，详情可查看API文档（https://api.kuaidi100.com/document/）。
Q: Skill 支持哪些 AI Agent 工具？
支持 Claude、Cursor、WorkBuddy、OpenClaw、Hermes 等主流 AI Agent 工具。
