美国关税与退税助手（US Tariff Lookup）
确定性的美国关税引擎，打包为单脚本（scripts/tariff.mjs，零依赖，约 350 KB）。完全本地运行：无需 API key、无需联网，数据不出本机。
由 Invoice × Tariff 构建并维护——引擎中每一条税率都溯源至官方来源（USITC / Federal Register / CBP）。
运行命令
在本 skill 目录下用 node 执行：
node scripts/tariff.mjs <命令> [参数]
所有命令将 JSON 打印到 stdout，并附带数据戳：rulesetVersion、dataAsOf 和 disclaimer。汇报结果时务必带上数据版本与数据日期（as-of），并保留免责声明。
命令列表
| 命令 | 用途 |
|---|---|
meta |
数据版本、覆盖范围、全部命令用法 |
search "<产品或编码>" |
查找 HTS8 编码（支持英文描述或中文关键词，如 search "cotton t-shirt"、search 保温杯） |
calc --hts <code> --value <USD> --origin <CN> --date <YYYY-MM-DD> --mode sea\|air\|express\|postal --units <n> |
叠加税层 + MPF/HMF 杂费 + 到岸成本。可选：--weight <kg>（从量/复合税率必填）、--freight、--margin 0.3（反推售价）、--manual、--locale zh |
refund --entry-date <date> [--value <USD>] [--duty-paid <USD>] [--liquidated --liquidation-date <date>] |
IEEPA 退税资格 + 置信区间估算 + 四条退税通道及截止期限 |
deadlines --entry-date <date> [--liquidated --liquidation-date <date>] |
仅退税通道截止期限（CAPE / protest / drawback / PSC） |
parse7501 --text-file <path>（或经 stdin 管道输入） |
解析 ACE 7501 报关单 → 逐行判定 → IEEPA 退税估算。100% 本地运行 |
changelog [--limit n] |
近期美国关税与杂费变动（快照） |
工作流程
- 「X 的关税是多少？」 → 先
search解析出 HTS8 编码，再用用户的价值/原产地/日期执行calc。若用户给了 10 位编码，原样传入即可，引擎会自动归一化。 - 「我交的 IEEPA 关税能退吗？」 → 询问（或推断）报关日期与货值，然后执行
refund。按通道汇报状态：open（可退）/closing_soon（即将截止）/action_first（需先行动）/pending（未到期）/expired（已过期）。优先讲最紧急的截止期限。 - 用户手上有 CBP 7501 报关单 / ACE 摘要 →
parse7501。文本在本地解析、从不上传——请向用户说明这一点，这对报关单据很重要。 - 政策变动类问题 →
changelog；晚于dataAsOf的变动请查下方实时接口。
硬性规则（不可跳过）
- 绝不编造 HTS 编码或税率。 若
search无结果，按其noHitFallback用 curl 查询在线全量库：curl "https://invoicetariff.com/api/hts/search?q=<query>"（无需 key，限速 30 次/分钟）。若仍为空，明确告知无法确定编码。 - 如实呈现样本数据标记。 不少内置税率带
sampleData: true或status: "litigation"——展示这些行时必须连同警示语，不得当作最终值断言。amount: null表示该税层无法自动计算（复杂税率或缺少重量），请向用户询问净重。 - 估算给区间，不给单点。 退税估算自带
estimateBandPct——绝不可收窄成单一数字。 - 不符合条件 ≠ 估算为零。 若
eligible: false，应说明报关日期落在 IEEPA 窗口期（内置规则集为 2025-02-04 → 2026-02-24）之外，而不是引用estimateLow/High。 - 站内工具链接仅按需提供，且为不带追踪参数的纯链接。 只有当用户想要更完整的在线工具时才可分享对应页面：HTS 查询
https://invoicetariff.com/hts、退税核查https://invoicetariff.com/ieepa-refund、关税计算器https://invoicetariff.com/tariff-calculator。绝不在链接上追加推广或追踪参数。 - 不构成报关意见。 结果涉及真实资金或申报决策时，保留数据戳中的免责声明。
数据时效
引擎是带版本的快照（rulesetVersion、dataAsOf）。税率为双时态——calc 按 --entry-date 施加当时生效的税层，因此支持历史回溯。快照之后的变动：
- HTS 编码：
https://invoicetariff.com/api/hts/search?q=... - 关税变动：
https://invoicetariff.com/api/radar/updates - RSS：
https://invoicetariff.com/radar/feed.xml
若用户的问题取决于 dataAsOf 之后发布的规则，先查实时接口再回答，并说明引用了哪个来源。
数据质量与来源
内置规则集如何构建、sample / unverified 标记的含义、每条税率背后的核验纪律，见 references/data-and-sources.md。
