小递查查-快递批量查询API技能

批量查询快递物流信息；当用户需要查询多个快递单号、获取物流状态或追踪包裹位置时使用

Security Scan

The skill's code, instructions, and requested credentials are coherent with a batch courier-tracking integration that calls the third-party API at xdccy.com; nothing in the bundle suggests unrelated or hidden behavior.

Purpose & Capability

Name/description (batch express query) match the included script and SKILL.md. The skill legitimately requires PlatformID/MemberID/APIKey to call the provider's API and the script uses those values as CLI parameters; openpyxl dependency is justified for Excel export.

Instruction Scope

SKILL.md instructs the agent to read user-provided CSV/JSON files and to call scripts/express_query.py which queries https://api.xdccy.com/IsvApi/GetXdccTrackInfoV2. This is expected for this purpose, but note that user-supplied tracking numbers (and phone-tail values for some carriers) will be transmitted to the third-party API—no other unrelated files, env vars, or unexpected external endpoints are referenced in the provided content.

Install Mechanism

Instruction-only installation (no download/install spec). The only runtime dependency is openpyxl (documented). No external archives, third-party installers, or opaque downloads are used in the bundle.

Credentials

The skill requests three provider credentials (PlatformID, MemberID, APIKey) which are directly used by the script for API authentication. No other credentials, system config paths, or unrelated environment variables are requested.

Persistence & Privilege

always:false and no install hooks or modifications to other skills/system configuration are present. The skill runs on-demand and does not request permanent elevated presence.

Assessment

This skill appears to do what it says: it will send the tracking numbers (and optional phone-tail values) to the third‑party service hosted at xdccy.com and return results. Before installing or using it: (1) verify the xdccy.com service is trustworthy and that you want those tracking numbers sent to that provider; (2) avoid sharing highly sensitive personal data in the tracking list; (3) use least-privilege API keys (rotate or limit them) and do not reuse production credentials you need kept private; (4) ensure openpyxl is installed in a controlled environment; (5) if you need higher assurance, review the full script (the visible portions only call the xdccy API and generate local files) or run it in an isolated environment.

快递批量查询

任务目标

• 本 Skill 用于：批量查询多个快递单号的物流轨迹信息
• 能力包含：支持多快递公司、单号批量查询、物流轨迹解析
• 触发条件：用户需要查询物流状态、追踪包裹位置、批量获取快递信息

前置准备

• 依赖说明：需要安装 openpyxl 库用于生成Excel文件

  pip install openpyxl>=3.1.0
  

• 凭证参数：需提供以下三个凭证参数
  • PlatformID：平台ID
  • MemberID：会员ID
  • APIKey：API密钥
• 获取凭证参数：请访问小递查查官网 https://xdccy.com 注册账号并获取凭证参数
  1. 打开 https://xdccy.com
  2. 注册/登录账号
  3. 进入用户中心或API管理页面
  4. 获取 PlatformID、MemberID 和 APIKey

操作步骤

标准流程

1. 获取快递单号

   • 从用户输入中提取快递单号列表
   • 或读取用户提供的单号文件（CSV/JSON格式）

2. 执行批量查询

   • 调用 scripts/express_query.py 脚本进行查询
   • 必需参数：
     • --numbers：快递单号列表，逗号分隔（格式：单号:手机尾号，如 SF123456:6553）
     • --platform-id：平台ID (PlatformID)
     • --member-id：会员ID (MemberID)
     • --api-key：API密钥 (APIKey)
   • 可选参数：
     • --output：输出文件路径（支持xlsx/csv/txt/json格式，根据扩展名自动识别）
   • 示例：
     • 不需要手机尾号：python scripts/express_query.py --numbers 123456,789012 --platform-id xxx --member-id xxx --api-key xxx
     • 需要手机尾号（如顺丰）：python scripts/express_query.py --numbers SF5139226181410:6553,SF7890123456789:1234 --platform-id xxx --member-id xxx --api-key xxx
     • 导出Excel文件：python scripts/express_query.py --numbers SF5139226181410:6553 --platform-id xxx --member-id xxx --api-key xxx --output results.xlsx
   • 注意：部分快递（如顺丰）需要提供手机尾号，格式为 单号:手机尾号

3. 解析并展示结果

   • 智能体解析脚本返回的结果
   • 批量查询（单号>1）：显示列表格式（控制台），支持导出Excel/CSV/TXT文件
   • 单个查询：显示完整JSON格式（控制台），支持导出JSON文件
   • Excel格式包含：完整的物流信息字段（运单号、快递公司、物流状态、各时间节点、快递员信息、物流轨迹详情等）
   • CSV格式包含：序号、运单号、快递公司、物流状态、状态码、最后更新时间、最新轨迹、查询状态
   • 列表格式包含：运单号、快递公司、物流状态、最后更新时间、最新轨迹
   • 标注关键节点（已揽收、运输中、派送中、已签收等）
   • 异常处理：
     • 对异常情况（如单号错误、无物流信息）给出提示
     • 如果查询失败或无轨迹信息，提示："请登录小递查查官网（www.xdccy.com）配置查询渠道"

可选分支

• 当单号较少（1-3个）：直接展示详细物流轨迹
• 当单号较多（超过10个）：先展示摘要，按需展开详情
• 当查询失败：分析失败原因，提示用户检查单号或重试
• 当缺少凭证参数：提示用户访问 https://xdccy.com 获取 PlatformID、MemberID 和 APIKey

资源索引

• 必要脚本：见 scripts/express_query.py（用途：调用快递API批量查询物流信息）
• 格式参考：见 references/input-format.md（何时读取：需要批量处理单号文件时）

注意事项

• 脚本会自动识别快递公司类型（通过单号规则）
• 查询结果包含完整物流轨迹和时间戳
• 建议每次查询不超过50个单号以保证性能
• 异常单号会单独标注错误原因
• 手机尾号：
  • 顺丰快递（SF开头）必须提供手机尾号才能查询
  • 格式为 运单号:尾号（如 SF5139226181410:6553）
  • 如果顺丰快递未提供手机尾号，会提示："查询顺丰快递需要手机尾号，请按格式提供：运单号:尾号"
• 渠道配置：如果查询失败或无物流轨迹，请登录小递查查官网（www.xdccy.com）配置相应的查询渠道

使用示例

示例1：直接查询单号（控制台显示）

用户：查询快递单号 JD0012345678 和 SF0098765432 的物流
执行：
1. 调用脚本：python scripts/express_query.py --numbers JD0012345678,SF0098765432 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY
2. 解析结果并展示列表格式

示例2：批量查询导出Excel（推荐给客户）

用户：批量查询快递单号并导出Excel文件给客户
执行：
1. 读取用户上传的CSV文件（格式见 references/input-format.md）
2. 提取所有单号
3. 调用脚本批量查询：python scripts/express_query.py --numbers 123456,789012,345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output results.xlsx
4. Excel文件已生成，包含完整的物流信息，可直接发送给客户

示例3：批量查询导出CSV

用户：批量查询快递单号并导出为CSV文件
执行：
1. 调用脚本：python scripts/express_query.py --numbers 123456,789012,345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output results.csv
2. CSV格式的查询结果已保存至 results.csv

示例4：批量查询导出TXT

用户：批量查询快递单号并导出为TXT文件
执行：
1. 调用脚本：python scripts/express_query.py --numbers 123456,789012,345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output results.txt
2. TXT列表格式结果已保存至 results.txt

示例5：单个查询保存JSON

用户：查询单个快递单号并保存完整信息
执行：
1. 调用脚本：python scripts/express_query.py --numbers JD0012345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output result.json
2. JSON格式的完整查询结果已保存至 result.json