← 返回 Skills 市场

批量快递查询API-快递鸟

Name: 批量快递查询API-快递鸟
Author: 15814059255

作者 kdnaio · GitHub ↗ · v1.0.0 · MIT-0

cross-platform ✓ 安全检测通过

116

总下载

当前安装

版本数

在 OpenClaw 中安装

/install kdniaoapi-skill

功能描述

支持通过快递鸟API实时查询运单轨迹信息；当用户需要查询快递物流状态、追踪运单进度或获取包裹配送详情时使用

使用说明 (SKILL.md)

快递鸟运单查询

任务目标

本 Skill 用于：查询快递运单的实时物流轨迹信息
能力包含：调用快递鸟API获取物流状态、解析轨迹数据、展示配送进度
触发条件：用户提出查询快递物流、追踪运单、查看配送状态等需求

前置准备

依赖安装

Python依赖：requests>=2.28.0
安装命令：
```
pip install requests>=2.28.0
```

凭证配置

必需环境变量：

KUAIDI_BIRD_API_CREDENTIALS：快递鸟API凭证

凭证格式：

CUSTOMER_CODE|APP_KEY

格式说明：

使用竖线（|）分隔商户ID和API密钥
商户ID（CUSTOMER_CODE）：快递鸟账号的唯一标识
API密钥（APP_KEY）：用于API请求签名的密钥

获取方式：

访问快递鸟官网（https://www.kdniao.com/）注册账号
登录后进入"API管理"或"开发者中心"
在商户信息中获取商户ID（CUSTOMER_CODE）
在API密钥管理中获取API密钥（APP_KEY）
使用竖线（|）拼接两个值作为环境变量值

配置示例：

# Linux/Mac
export KUAIDI_BIRD_API_CREDENTIALS="1292092|703d0b97-07fa-478c-bfea-ca3597f2ce0f"

# Windows PowerShell
$env:KUAIDI_BIRD_API_CREDENTIALS="1292092|703d0b97-07fa-478c-bfea-ca3597f2ce0f"

# Windows CMD
set KUAIDI_BIRD_API_CREDENTIALS=1292092|703d0b97-07fa-478c-bfea-ca3597f2ce0f

套餐要求

快递鸟账号需开通快递查询服务套餐（免费或付费）

安全建议

妥善保管API密钥，避免泄露到代码仓库或公共平台
建议使用环境变量或密钥管理工具存储凭证
在生产环境使用前，先在测试环境验证
定期检查API调用额度和使用情况
不要在脚本中硬编码凭证

操作步骤

标准流程

确认运单信息
- 获取用户提供的运单号（LogisticCode）
- 验证运单号格式（通常为10-20位数字或字母数字组合）
执行查询
- 调用 scripts/query_tracking.py 处理运单查询
- 参数说明：
  - --logistic-code：运单号（必需）
  - --api-url：API地址（可选，默认为快递鸟正式环境）
- 示例：
```
python /workspace/projects/kuaidi-bird-tracking/scripts/query_tracking.py --logistic-code 773367326370601
```
解析与展示结果
- 脚本返回结构化的JSON结果
- 智能体解析返回数据，提取关键信息：
  - 物流状态（已揽收、运输中、派送中、已签收等）
  - 轨迹时间线（按时间顺序的物流节点）
  - 当前最新状态
- 以自然语言向用户展示查询结果

可选分支

当运单号无效或不存在：提示用户检查运单号是否正确
当提示"缺少快递鸟API凭证配置"：检查环境变量 KUAIDI_BIRD_API_CREDENTIALS 是否已正确设置
当提示"凭证解析失败"：确认凭证格式为 CUSTOMER_CODE|APP_KEY，使用竖线（|）分隔
当查询失败或API异常：检查凭证配置，确认账号套餐状态，建议稍后重试
当提示"没有可用套餐"：说明快递鸟账号未开通查询服务，需在快递鸟官网开通套餐
当物流信息为空：说明该运单暂无轨迹更新

资源索引

必要脚本：见 scripts/query_tracking.py（用途：调用快递鸟API查询运单轨迹；参数：运单号、API地址）

注意事项

环境变量配置

必需环境变量：KUAIDI_BIRD_API_CREDENTIALS
格式要求：CUSTOMER_CODE|APP_KEY（使用竖线分隔）

配置示例：

export KUAIDI_BIRD_API_CREDENTIALS="1292092|703d0b97-07fa-478c-bfea-ca3597f2ce0f"

API使用

本Skill使用快递鸟API，需要先配置商户ID和API密钥
默认使用快递鸟正式环境API地址（https://api.kdniao.com/api/dist）
快递鸟账号需开通快递查询服务套餐（免费或付费），否则会提示"没有可用套餐"

安全建议

妥善保管API密钥，避免泄露到代码仓库或公共平台
建议使用环境变量或密钥管理工具存储凭证
在生产环境使用前，先在测试环境验证
定期检查API调用额度和使用情况
脚本代码简短清晰，建议在使用前阅读并理解其逻辑
环境变量使用清晰命名（KUAIDI_BIRD_API_CREDENTIALS），易于理解和维护

其他

不同快递公司的查询结果格式可能略有差异
建议在查询前提醒用户确认运单号准确性

使用示例

示例1：查询顺丰运单

功能说明：查询顺丰快递的物流轨迹
执行方式：脚本查询 + 智能体解析展示
关键参数：运单号 SF1234567890

执行：

python /workspace/projects/kuaidi-bird-tracking/scripts/query_tracking.py --logistic-code SF1234567890

结果：智能体展示"包裹已揽收→运输中→派送中→已签收"的完整轨迹

示例2：查询圆通运单

功能说明：查询圆通速递的物流状态
执行方式：脚本查询 + 智能体解析展示
关键参数：运单号 YT1234567890123

执行：

python /workspace/projects/kuaidi-bird-tracking/scripts/query_tracking.py --logistic-code YT1234567890123

结果：智能体展示当前物流状态和最新物流节点

示例3：批量查询

功能说明：依次查询多个运单的物流信息
执行方式：循环调用脚本
执行：智能体依次处理每个运单号，汇总展示结果

安全使用建议

This skill appears to do what it says: it calls the 快递鸟 (Kdniao) API using a single API credential stored in KUAIDI_BIRD_API_CREDENTIALS (format CUSTOMER_CODE|APP_KEY). Before installing, verify the registry metadata is updated to declare that env var (a packaging omission), review the included script (it's short and readable), and ensure you: (1) provide only valid service credentials via environment variables (do not hard-code them), (2) avoid pasting real API keys into public examples or logs, and (3) confirm your environment can make outbound HTTPS calls to https://api.kdniao.com. If you want extra assurance, run the script locally with a test account first. Confidence in this assessment is high given the clear one-to-one mapping between purpose, docs, and code.

功能分析

Type: OpenClaw Skill Name: kdniaoapi-skill Version: 1.0.0 The skill is a legitimate tool for querying express delivery tracking information via the Kuaidi Bird API. The script `scripts/query_tracking.py` correctly handles API authentication using environment variables and communicates only with the official endpoint (api.kdniao.com). No evidence of data exfiltration, malicious execution, or prompt injection was found.

能力评估

ℹ Purpose & Capability

The skill's name, description, SKILL.md, and the included script consistently implement real-time queries to the 快递鸟 (Kdniao) API and require an API credential (CUSTOMER_CODE|APP_KEY). However, registry metadata at the top of the submission lists no required environment variables while SKILL.md and the script require KUAIDI_BIRD_API_CREDENTIALS — this mismatch is likely a packaging/metadata omission rather than malicious.

✓ Instruction Scope

SKILL.md describes installing requests, setting the KUAIDI_BIRD_API_CREDENTIALS env var, passing a logistic-code argument, and delegating to scripts/query_tracking.py. The instructions do not ask the agent to read unrelated files, other env vars, or send data to unexpected endpoints; the script posts to the documented https://api.kdniao.com/api/dist endpoint and prints structured JSON results.

✓ Install Mechanism

There is no automated install spec (instruction-only), and dependencies are a single standard Python package (requests). No arbitrary downloads, extract steps, or non-standard installers are present. Risk from installation is low.

✓ Credentials

The skill requires a single service credential (KUAIDI_BIRD_API_CREDENTIALS in format CUSTOMER_CODE|APP_KEY) which is proportional to calling the Kdniao API. The credential is used only to sign requests; no other unrelated secrets are requested. Note: SKILL.md contains an example credential value (sample) — users should avoid using real keys in examples or public repos.

✓ Persistence & Privilege

The skill does not request permanent presence (always:false) and does not modify other skills or system-wide settings. It runs as an invoked script and prints results; autonomous invocation is allowed by default but not excessive for this type of integration.

如何使用

确保已安装 OpenClaw（本地或 Docker 部署）
在对话框中输入安装命令：/install kdniaoapi-skill
安装完成后，直接呼叫该 Skill 的名称或使用 /kdniaoapi-skill 触发
根据 Skill 的参数说明提供必要输入，即可获得结构化输出

版本历史

v1.0.0

kuaidi-bird-tracking 1.0.0 - Initial release - Provides real-time express package tracking via the Kuaidi Bird (快递鸟) API. - Supports querying and displaying shipment status, tracking progress, and delivery details. - Requires setup of the `KUAIDI_BIRD_API_CREDENTIALS` environment variable (`CUSTOMER_CODE|APP_KEY` format). - Includes clear setup, security, and usage instructions for both individual and batch waybill checks. - Uses a Python script (`scripts/query_tracking.py`) and requires the `requests>=2.28.0` package.

元数据

Slug kdniaoapi-skill

版本 1.0.0

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 1

常见问题