us-tariff-lookup npm 包使用教程：CLI + 库双形态（附可运行代码）

这个包是什么

us-tariff-lookup 是驱动本站计算器的同一个确定性引擎的 Node 封装：零依赖、纯 TypeScript、无需 API Key、无网络请求。版本化规则快照——MFN 税率、对华 301、全球 301、Section 232、MPF/HMF 规费表、IEEPA 历史层和机器可读 changelog——随包内置，所以结果与网页计算器完全一致，且对固定版本永远可复现。

MIT 许可；每条税率行都带 legalBasis 与官方 source 链接（USITC / USTR / CBP / Federal Register）。

安装

npm install us-tariff-lookup        # 作为库使用
npx us-tariff meta                  # 或不安装直接用 CLI

CLI：五条命令

所有命令向 stdout 输出 JSON，并附带 rulesetVersion、dataAsOf 与 disclaimer——可以直接接 jq、表格或 LLM 提示词。

# 看包里有什么 / 当前数据版本
npx us-tariff meta

# 查 HTS 码——编码前缀、英文描述或中文关键词都行
npx us-tariff search "cotton t-shirt"
npx us-tariff search 保温杯

# 叠加关税 + 规费 + 落地成本
npx us-tariff calc --hts 61091000 --value 20000 --origin CN --mode sea --units 5000 --locale en

# 2026 年 IEEPA 裁决后适用哪条退税通道
npx us-tariff refund --entry-date 2026-03-01

# 近期已发布的规则变更
npx us-tariff changelog --limit 5

calc 的 mode 取值：sea | air | express | postal——HMF 只对海运征收，2,500 美元及以下邮政件走非正式报关固定规费档。--entry-date 默认今天，且必须落在快照窗口内（data-as-of + 90 天），保证历史回放不失真。

库：第一次计算

import { rulesetSeed, searchHts, calculateLandedCost } from "us-tariff-lookup";

// searchHts 同时匹配编码前缀、英文与中文关键词
const hits = searchHts(rulesetSeed, "cotton t-shirt", 5);

const result = calculateLandedCost(rulesetSeed, {
  hts: "61091000",        // 棉制 T 恤
  value: 20_000,          // 美元申报值
  originCountry: "CN",
  entryDate: "2026-10-10",
  mode: "sea",
  units: 5_000,
  locale: "en",
});

result.totalDuty;         // 7394.28 —— 已含关税 + MPF + HMF
result.effectiveTaxRate;  // 36.97（占申报值百分比）
result.layers;            // 每一关税行：金额、税率文本、法律依据、来源 URL

这两个输出数字是包的黄金测试用例——在当前快照上运行应精确复现。result.layers 里每一项就是你要渲染的一行：税率、金额、法律依据和指回官方原文的链接。

接进 API

一个按需计价的极简 Express 端点：

import express from "express";
import { rulesetSeed, calculateLandedCost } from "us-tariff-lookup";

const app = express();
app.use(express.json());

app.post("/api/landed-cost", (req, res) => {
  try {
    const result = calculateLandedCost(rulesetSeed, { ...req.body, locale: "en" });
    res.json({
      ...result,
      rulesetVersion: rulesetSeed.version,
      dataAsOf: rulesetSeed.asOf,
      disclaimer:
        "Estimates for planning only — final duty is determined by U.S. Customs and Border Protection at entry.",
    });
  } catch (e) {
    res.status(400).json({ error: String(e) });
  }
});

app.listen(3000);

永远展示版本号和免责声明

两个习惯区分可信集成与埋雷集成：

1. 每个结果都回显 rulesetVersion 与 dataAsOf。 税率月月在变，不带数据日期的报价无法复现。本站批量导出的 CSV 就是这么做的。
2. 把免责声明透传给终端用户。 包会把尚未对照 FR 原文核实的行打上 sample / unverified 标——用于规划与演示没问题，但不能作为正式报关依据。签字的是你的报关行，不是这个包。

保持数据新鲜

规则快照每月重建（重大政策落地时临时加更），来源是开放的税率数据仓。用 npm update us-tariff-lookup 升级；用 changelogEntries()（或 npx us-tariff changelog）查看版本之间动了什么。带新旧值的实时 changelog 在关税雷达，附 RSS，方便你自动化响应。

包内规则快照一览

税层	内容
mfn	精选高频 HTS 8 位码，官方 USITC 普通税率（中英双语品名）
china301	对华 301 各清单税行（清单 2/3/4A + 2026 四年复审新增）
global301	2026 全球 301 计划：60 个经济体档位 + HTS 前缀豁免
section232	钢 / 铝 / 铜 / 汽车 / 家具 / 药品 / 半导体 / 木材措施
fees	FY2027 MPF/HMF + 非正式报关规费档
ieepaHistorical	已终止的 IEEPA 层，供退税查询
changelog	机器可读规则变更（已发布 + 预告）

全量 5,689 码 HTS 表不在包内——它在 hs-codes-database 仓和 HTS 搜索页；批量取数见数据集教程。