批量快递查询-快递鸟

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

Security Scan

The skill's code and SKILL.md are coherent and implement a courier-tracking integration, but the registry metadata omits the required API credential, creating an inconsistency you should resolve before trusting it.

Purpose & Capability

Name/description, SKILL.md, and the script all align: this is a kuaidi-bird (快递鸟) tracking skill. However, the registry metadata in the package claims 'Required env vars: none' and 'Primary credential: none' while both SKILL.md and scripts require a KUAIDI_BIRD_API_CREDENTIALS value; this metadata mismatch is an incoherence in the package manifest.

Instruction Scope

Runtime instructions are narrowly scoped to querying the 快递鸟 API: install requests, set KUAIDI_BIRD_API_CREDENTIALS (CUSTOMER_CODE|APP_KEY), run the provided script with a logistic code. The SKILL.md and script only access that environment variable and call the configured API endpoint (defaulting to api.kdniao.com or a user-provided api-url). There are no instructions to read unrelated files or exfiltrate data to unexpected endpoints.

Install Mechanism

This is instruction-only (no install spec). The only dependency is the standard 'requests' Python package, which is proportionate for HTTP API calls. No downloads from arbitrary URLs or archive extraction are present.

Credentials

The skill legitimately needs a single API credential bundled as KUAIDI_BIRD_API_CREDENTIALS (CUSTOMER_CODE|APP_KEY). That is appropriate for the stated purpose. However, the registry metadata did not declare this required environment variable or a primary credential, which is misleading and increases risk (consumers may not realize they need to supply secrets).

Persistence & Privilege

The skill does not request persistent or elevated privileges. always is false and the skill does not attempt to modify other skills or system-wide settings. Autonomous invocation is enabled by default (normal for skills) but is not combined here with other red flags.

What to consider before installing

This skill's code and instructions appear to implement a legitimate 快递鸟 (kdniao) tracking integration and require only one credential (KUAIDI_BIRD_API_CREDENTIALS in the format CUSTOMER_CODE|APP_KEY). However, the package metadata incorrectly omits that requirement — treat that as a red flag. Before installing: (1) Verify the package owner/trustworthiness (source is 'unknown'); (2) Confirm you only need to provide the 快递鸟 CUSTOMER_CODE and APP_KEY and nothing else; (3) Inspect the included script yourself (it is short and readable) or run it in a safe/test environment first; (4) Do not use production or highly privileged API keys until you're confident; (5) Prefer creating a dedicated 快递鸟 account or API key with limited scope/quota and rotate it after testing; (6) Ask the publisher to update the registry metadata to declare KUAIDI_BIRD_API_CREDENTIALS as a required/primary credential so the manifest matches the actual requirements.

快递鸟运单查询

任务目标

• 本 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请求签名的密钥

获取方式：

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

配置示例：

# 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调用额度和使用情况
• 不要在脚本中硬编码凭证

操作步骤

标准流程

1. 确认运单信息

   • 获取用户提供的运单号（LogisticCode）
   • 验证运单号格式（通常为10-20位数字或字母数字组合）

2. 执行查询

   • 调用 scripts/query_tracking.py 处理运单查询
   • 参数说明：
     • --logistic-code：运单号（必需）
     • --api-url：API地址（可选，默认为快递鸟正式环境）
   • 示例：

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

3. 解析与展示结果

   • 脚本返回结构化的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：批量查询

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