微盟外贸海关数据

概述

Customs Data Query

查询采购商、供应商和海关交易记录，使用 Trade-Key 鉴权。

1. 海关接口与查询方式

执行前读取 [完整 HTTP 接口文档](references/http-api.md)，按其中的字段构造查询。使用 scripts/common.py query 发送请求：脚本自动读取本地保存的 Key，写入 Trade-Key 请求头，统一处理 HTTP 错误；不要在对话或终端命令中展开真实 Key。

支持三条查询通道：

只查用户要求的通道；未说明对象的“查海关数据”默认 [3]。未给产品、HS、公司等任何筛选信息时，询问要查什么；保留用户已有条件，不要求重新填写。产品放 productName，国家使用二位码，不猜测 HS 编码。

内置默认参数：每个所选通道均为 page=1、size=10，时间为最近 3 个月。 用户未指定的默认字段交给脚本补齐，不手工填写示例日期。脚本按执行时的本地时间自动补齐秒级 startDate、endDate：结束时间为当前时刻，开始时间向前推 3 个日历月，月末日期超出目标月份时取该月最后一天，不固定按 90 天计算。用户明确指定时间或每页数量时使用指定值，不额外询问确认；只给结束时间时从该时间回推 3 个月，只给开始时间时查询到当前时刻。当前聚合接口只返回第一页，不能把重复查询当成下一页。

中文产品关键词先翻译成英文，再调用接口。 从用户请求中提取产品词，按原意翻译后填入所选通道的 productName，适用于采购商、供应商和交易明细查询。例如“童桌”译为 children's table；不要把“帮我查询一下”“数据”等请求用语带入关键词，除上述默认时间和分页外，不额外添加材质、用途等用户未给出的条件。已有英文关键词、品牌、型号和 HS 编码保持原值；公司名称使用用户提供的名称或已确认的英文名称，不自行编造译名。

以下命令均在本 Skill 目录执行，或将脚本路径替换为实际绝对路径：

python3 scripts/common.py query --payload '{"queryCustomsDataList":[1],"queryImpEnterprise":{"productName":"LED","destinationCountry":"US"}}'

查询条件齐全且有 Key 时直接执行。脚本仅使用 Python 3 标准库。

2. Trade-Key：收到后必须保存

用户提供或更新 Trade-Key 后，必须在本轮实际写入本地，再继续查询。 即使用户本轮只发 Key、没有新的查询要求，也要先执行保存。用户提供 Key 即表示同意为本 Skill 保存和复用，无需再次询问是否保存；不能只回复“记住了”或仅设置临时环境变量。

1. 执行 python3 scripts/common.py save-key，通过执行工具的 stdin 输入 Key；交互终端使用隐藏输入。不要把 Key 拼进命令参数或回显。
2. 脚本将 Key 写入 ~/.workbuddy/customs-data-query/.env，并回读校验。只有返回 ok=true、code=TRADE_KEY_SAVED 后，才回复“已保存到本机，后续查询会自动使用”，随后继续待完成的查询。保存失败时停止查询，明确告知未保存成功。
3. 执行工具无法提供 stdin 时，使用本地文件写入工具将 TRADE_KEY=用户提供的值 保存到同一路径，保护文件权限；写入工具成功后再执行 python3 scripts/common.py auth-status 检查，不能省略实际写入。
4. 后续直接执行查询命令，脚本自动读取该文件，跨会话和重新启动后复用；用户提供新 Key 时重新执行保存，以本地新值为准。auth-status 只检查本地是否可读取，不验证远程权限，不输出 Key。

首次查询若仅有环境变量 TRADE_KEY，脚本会先保存并校验再发请求；保存失败就停止。已有本地 Key 时优先使用本地值，旧环境变量不会覆盖新保存的 Key。

缺少 Key 时，给出 [config.json](config.json) 的 trade_key_url，请用户授权获取后复制给 WorkBuddy；收到后执行上述保存流程。Key 只保存在用户本地凭证文件中，不写进 Skill 配置、代码或对话回复。

3. 结果处理

• 只使用本轮接口返回的数据，按 data.impEnterprise、data.expEnterprise、data.customsData 的 records 和 total 输出简洁表格或摘要。
• 总条数与实际返回条数分别说明；只展示请求的通道。未返回的金额币种、重量单位、联系人等不得猜测。
• 业务响应位于脚本输出的 response 下。先检查业务 code、查询权限和额度状态，再展示记录。
• 无权限时引导购买权益：本轮接口返回 data.hasEntitlement=false、HTTP 403（脚本返回 ACCESS_DENIED），或业务错误明确说明“无查询权限 / 未购买 / 未开通对应权益”时，停止展示查询结果，回复：“当前账号暂无海关数据查询权限，请前往 微盟外贸官网 购买对应查询权益，开通后再查询。”展示可点击链接，由用户自行购买；不能将权限拒绝说成“没有查到数据”。例如“查童桌数据”返回 {"code":"200","data":{"hasEntitlement":false}}，也应走此购买引导。
• Key 缺失或失效按 Trade-Key 获取流程处理；仅 data.todayQueryLimited=true 时说明当日额度受限，不将它判断为未购买权益。
• 业务成功、未受限且通道 total=0 才说明无匹配数据，可建议简化关键词或减少筛选；缺少通道或响应格式异常应说明查询未完整返回。
• 不输出 Key、token、st 或含凭证的参数回显。Key 不得进入查询 payload、URL、报告或对外内容。

案例：“帮我查询一下童桌数据” → 提取“童桌”，翻译为 children's table → 默认查询交易明细 [3] → 脚本补齐第 1 页、每页 10 条和最近 3 个月 → 自动读取本地 Key（缺少时引导获取，收到后先保存）→ 携带 Trade-Key 调用接口，传给脚本的业务参数如下 → 根据本轮返回的交易记录用中文展示结果。

{
  "queryCustomsDataList": [3],
  "queryCustomsData": {
    "queryType": 1,
    "productName": "children's table"
  }
}