kuaidi100-skill

快递100 API 技能，用于查询快递物流相关信息。当用户提到快递单号、物流轨迹、查快递、运费估算、预计到达时间、识别快递公司等需求时，必须使用此技能。支持：查询物流轨迹（query_trace）、识别快递公司（auto_number）、估算运费（estimate_price）、预估寄件送达时间（estimate...

Security Scan

The skill's code, instructions, and required configuration are coherent with its stated purpose (calling 快递100 APIs); it only requests an API key and performs HTTPS calls to api.kuaidi100.com.

Purpose & Capability

Name/description match the implementation: the script implements query_trace, auto_number, estimate_price, estimate_time and related calls to api.kuaidi100.com. Required inputs (API key via config.json or KUAIDI100_API_KEY) are appropriate for this purpose.

Instruction Scope

SKILL.md limits runtime actions to invoking script/kuaidi100.js and reading config.json or the KUAIDI100_API_KEY env var. It does not instruct reading unrelated files, contacting unexpected endpoints, or exfiltrating data beyond the 快递100 API.

Install Mechanism

No install spec is provided (instruction-only install). The skill includes a single Node.js script and a small config.json — nothing is downloaded from arbitrary URLs or written to unusual locations.

Credentials

Only a single optional credential is used (apiKey via config.json or KUAIDI100_API_KEY). This is proportional to the described API usage; no unrelated secrets or high-privilege env vars are requested.

Persistence & Privilege

always is false and the skill does not request persistent system privileges or modify other skills. It only reads its own config and environment variables.

Assessment

This skill appears coherent and limited to calling the 快递100 API. Before installing, ensure you: (1) trust the skill source (homepage is missing and owner ID is not human-friendly); (2) provide a valid KUAIDI100_API_KEY in config.json or KUAIDI100_API_KEY env var if you need higher quota; (3) run it in an environment with Node.js available; (4) be aware the script will send the API key and provided tracking data to api.kuaidi100.com — avoid putting unrelated secrets into config.json or environment variables. Note: there is a minor implementation quirk (estimateTimeWithLogistic calls the same endpoint path as estimateTime), but this is a correctness bug, not a security issue.

快递100 API 技能

通过 Node.js 脚本调用快递100 API 接口，实现快递物流查询相关功能。

配置文件

• config.json：配置文件，用于存储 API Key

  {
      "apiKey": "your_api_key_here"
  }
  

环境变量

• KUAIDI100_API_KEY：快递100 API Key（可选，作为备用配置方式）

脚本路径

script/kuaidi100.js

Key 处理规则

优先级从高到低：

1. 配置文件 config.json 中的 apiKey 字段（若已设置且不为空）
2. 环境变量 KUAIDI100_API_KEY（若已设置且不为空）
3. 使用默认值 null（使用免费额度）

额度耗尽处理

若接口返回内容包含"免费调用额度已耗尽"、"今日免费"、"额度不足"等字样，需告知用户：

今日免费调用额度已耗尽。您可前往 快递100 API 开放平台 注册账号并获取专属 API Key，然后将 Key 更新到配置文件 config.json 的 apiKey 字段中，或设置环境变量 KUAIDI100_API_KEY 即可继续使用。

---

工具列表

1. query_trace — 查询快递物流轨迹

触发场景：用户询问某快递单号的物流状态、快递到哪了、轨迹查询等。

参数：

• kuaidiNum（必填）：快递单号
• phone（可选）：手机号，顺丰速运、顺丰快运、中通快递必填

Node.js 调用：

node script/kuaidi100.js queryTrace <快递单号> [手机号]

若手机号为空则省略手机号参数：

node script/kuaidi100.js queryTrace <快递单号>

---

2. auto_number — 识别快递公司

触发场景：用户想知道某快递单号属于哪家快递公司，或需要在调用其他接口前识别快递公司编码。

参数：

• kuaidiNum（必填）：快递单号

Node.js 调用：

node script/kuaidi100.js autoNumber <快递单号>

---

3. estimate_price — 估算运费

触发场景：用户询问从某地寄快递到某地的费用、运费是多少等。

参数：

• kuaidicom（必填）：快递公司编码（小写），支持：
  • 顺丰：shunfeng
  • 京东：jd
  • 德邦快递：debangkuaidi
  • 圆通：yuantong
  • 中通：zhongtong
  • 申通：shentong
  • 韵达：yunda
  • EMS：ems
• recAddr（必填）：收件地址，如 广东深圳南山区
• sendAddr（必填）：寄件地址，如 北京海淀区
• weight（必填）：重量（kg，不带单位），默认 1

Node.js 调用：

node script/kuaidi100.js estimatePrice <快递公司编码> <收件地址> <寄件地址> [重量]

---

4. estimate_time — 预估寄件送达时间

触发场景：用户寄件前询问预计几天到、送达时间等（尚未寄出，无物流轨迹）。

参数：

• kuaidicom（必填）：快递公司编码（小写），支持： 圆通yuantong、中通zhongtong、顺丰shunfeng、顺丰快运shunfengkuaiyun、京东jd、极兔速递jtexpress、申通shentong、韵达yunda、EMSems、跨越kuayue、德邦快递debangkuaidi、EMS-国际件emsguoji、邮政国内youzhengguonei、国际包裹youzhengguoji、宅急送zhaijisong、芝麻开门zhimakaimen、联邦快递lianbangkuaidi、天地华宇tiandihuayu、安能快运annengwuliu、京广速递jinguangsudikuaijian、加运美jiayunmeiwuliu
• from（必填）：出发地，如 广东省深圳市南山区
• to（必填）：目的地，如 北京市海淀区
• orderTime（可选）：下单时间，格式 yyyy-MM-dd HH:mm:ss，默认当前时间
• expType（可选）：业务/产品类型，如 标准快递

Node.js 调用：

node script/kuaidi100.js estimateTime <快递公司编码> <出发地> <目的地> [下单时间] [业务类型]

---

5. estimate_time_with_logistic — 预估在途快递送达时间

触发场景：用户查询了物流轨迹（query_trace）后，询问还需多久到达、预计几号能到等，通常在 query_trace 之后调用。

参数：

• kuaidicom（必填）：快递公司编码（同 estimate_time，见上方支持列表）
• from（必填）：出发地，如 广东省深圳市南山区
• to（必填）：目的地，如 北京市海淀区
• orderTime（必填）：取 query_trace 返回的最早物流轨迹时间，格式 yyyy-MM-dd HH:mm:ss
• logistic（必填）：历史物流轨迹 JSON 数组，取自 query_trace 返回数据，格式：

  [{"time":"2025-12-29 12:43:35","context":"您的快件已到达快递驿站，请及时取件","status":"投柜或驿站"},{"time":"2025-12-29 08:48:27","context":"【河北省承德市隆化县】的郭工正在派件","status":"派件"}]
  

Node.js 调用：

node script/kuaidi100.js estimateTimeWithLogistic <快递公司编码> <出发地> <目的地> <下单时间> <物流轨迹JSON>

---

结果处理

所有接口均直接返回 Markdown 格式内容，无需额外处理，直接将结果返回给用户即可。

典型调用流程

用户询问快递还需多久到
  → 1. query_trace 查询物流轨迹（获取快递公司、轨迹数据）
  → 2. estimate_time_with_logistic 预估剩余时间（携带轨迹数据）
  → 返回结果给用户