mcpField
P
pp-fedex

pp-fedex

github.com/mvanhorn其他2.1k162 次安装今天更新
代码仓库

关于 pp-fedex

pp-fedex 是使用 `fedex-pp-cli` 通过 REST API 办理 FedEx 运输的 skill，面向中小型发货业务，并以本地 SQLite 保存运输记录供查询分析。

主要功能

  1. 01比较不同服务的运费
  2. 02从订单 CSV 批量创建标签
  3. 03生成退货标签
  4. 04追踪货件并识别新事件
  5. 05搜索运输档案并统计费用
  6. 06将运输记录导出为 CSV 或 JSON

适用场景

  1. 01批量生成电商发货标签
  2. 02为客户创建退货标签
  3. 03监控运输中的货件
  4. 04查看历史运输费用

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-fedex

安装后在 Claude Code 中输入/pp-fedex确认已加载。

详细介绍

FedEx — Printing Press CLI

前提条件：安装 CLI

此技能通过 fedex-pp-cli 二进制文件运行。**调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

  1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin： 
    npx -y @mvanhorn/printing-press-library install fedex --cli-only
  2. 验证：fedex-pp-cli --version
  3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/commerce/fedex/cmd/fedex-pp-cli@latest

如果安装后 --version 报告 "command not found"，说明运行时无法在 $PATH 中找到二进制文件目录。在验证成功之前，请勿继续执行技能命令。

何时使用此 CLI

如果你运营小型到中型的运输业务，并希望通过编程方式与 FedEx REST API 交互，请使用 fedex-pp-cli。适用场景：电商商店根据订单 CSV 创建运单标签；客服团队生成退货标签；运营团队追踪运输中的货件；以及希望在本地记录每笔货件和运费报价以供会计核算的中小企业主。本地 SQLite 存档使其适合对历史货件进行分析查询。如果你只需要 FedEx、希望掌控自己的数据，并且更偏好通过终端/Agent 自动化而非网页界面操作，那么选择此 CLI，而不是多承运商 SaaS（ShipStation、Shippo）。

独特功能

这些功能在其他用于此 API 的工具中都不可用。

省钱省时

  • rate shop — 并行查询所有适用服务类型的费率，并按费用、运输天数或每日费用排名。

    为货件挑选可行的最低价服务时，此命令可将 6 次以上的 API 调用合并为一个排序结果。这是中小企业货运最能节省成本的核心命令。

    fedex rate shop --from 90210 --to 10001 --weight 5lb --json --select rates.serviceType,rates.totalNetCharge,rates.transitTime

  • ship bulk — 为订单 CSV 批量创建运单标签，具备自适应速率限制、逐行 PASS/FAIL 记录以及从上次成功处恢复的功能。

    适用于“我每天寄 30 个包裹”的工作流。无需再逐个点击 FedEx Ship Manager 来创建运单标签。

    fedex ship bulk --csv orders.csv --service GROUND --output labels/ --resume

  • return create — 通过一条命令，根据现有追踪号生成 Ground Call Tag（退货标签），还可选择通过电子邮件发送给收件人。

    适用于电商客服工作流。签发退货标签是最常见的售后互动。

    fedex return create --tracking 794633071234 --reason damaged --email [email protected]

  • address validate — 以 SHA-256 为键的本地缓存，可避免 FedEx 地址验证 API 因重复查询而重复收费。

    直接节省成本——这是唯一具有可量化单次调用费用影响的功能。

    fedex address validate --street '1600 Amphitheatre Pkwy' --city 'Mountain View' --state CA --zip 94043 --country US --cache

  • ship etd — 通过单条命令使用电子贸易文件进行运输：上传商业发票、获取 docId，并将其整合到创建货件的调用中。

    国际货件需要 ETD；此命令可将容易出错的多步骤流程合并为一个原子操作。

    fedex ship etd --invoice invoice.pdf --orig CN --dest US --recipient-name 'Acme' --weight 2kg --service FEDEX_INTERNATIONAL_PRIORITY
可不断积累的本地状态

  • address save — 将常用收件人保存到本地地址簿；在发货命令中按名称引用。

    与付费 SaaS 竞争产品在易用性上保持一致。无需为回头客反复输入地址。

    fedex address save acme --street '500 Main St' --city Denver --state CO --zip 80202 --country US

  • track diff — 针对本地存储中的每个追踪号码，仅显示自上次轮询以来出现的追踪事件。

    取代 Agent 原本需要编写的追踪轮询去重逻辑。

    fedex track diff --since 1h --json

  • track watch — 持续轮询一组追踪号码，并在新事件到达时将其输出到 stdout、webhook 或文件。这是 FedEx 推送通知的轮询替代方案。

    大多数中小型企业都没有配置推送 webhook。轮询守护进程是通用的替代方案。

    fedex track watch --tracking 794633071234 --interval 10m --webhook https://example.com/hook

  • archive — 使用 SQLite FTS5 搜索本地归档中的所有货件，可按收件人姓名、地址、参考信息、追踪号码和服务搜索。

    “上周我们给 ACME 发过货吗？”——中小型企业经常会问的问题。

    fedex archive 'warehouse 47' --service GROUND --json

  • spend report — 根据本地费率报价和货件账本，按服务类型、运输线路或账户汇总净费用。

    “上个月我在 FedEx 上花了多少钱？”——每位中小型企业主都会问的问题。

    fedex spend report --since 30d --by service --json

  • export — 将货件、费用和追踪事件导出为 CSV 或 JSON，以便与 QuickBooks/Xero 对账。

    无需手动录入数据，即可完成会计对账流程。

    fedex export --format csv --since 30d --output fedex-april.csv

  • manifest — 根据本地归档生成可打印的 PDF/文本摘要，列出今天创建的所有货件；也可选择调用 Ground EOD 关闭 API。

    通过一条命令完成仓库日常工作流。

    fedex manifest --date 2026-05-02 --close --output manifest.md

  • sql — 直接对 shipments、rate_quotes、tracking_events、address_validations、addresses 表执行 SQLite SELECT 查询。

    可对本地账本执行任意分析的备用途径。

    fedex sql "select serviceType, count(*) as n, sum(net_charge) as spend from shipments where created_at > date('now','-30 days') group by serviceType order by spend desc"
流畅的设置体验

  • doctor — 验证 OAuth 身份验证、沙盒/生产环境路由、账户号码格式和标签格式兼容性，并显示 BAG（条码分析组）审批状态。

    避免首次使用者最常遇到的“为什么标签无法打印”问题。

    fedex doctor

命令参考

addresses — 地址验证

  • fedex-pp-cli addresses — 验证一个或多个地址（解析/标准化后的形式、分类，以及可选的解析后坐标）

availability — 服务可用性、特殊服务选项和运输时间

  • fedex-pp-cli availability services — 获取一组始发地/目的地可用的服务
  • fedex-pp-cli availability special_services — 获取可用的特殊服务选项（酒精饮料、危险品、签名要求等）
  • fedex-pp-cli availability transit_times — 获取一组始发地/目的地在不同服务下的运输时间

consolidations — 将多个货件合并为一次履约（高级功能；适用于高货量的 3PL）

  • fedex-pp-cli consolidations add_shipment — 将货件添加到合并单
  • fedex-pp-cli consolidations confirm — 确认合并单（锁定费率并触发发货）
  • fedex-pp-cli consolidations confirm_results — 获取合并单确认结果
  • fedex-pp-cli consolidations create — 创建合并单
  • fedex-pp-cli consolidations delete — 删除合并单
  • fedex-pp-cli consolidations delete_shipment — 从合并单中移除货件
  • fedex-pp-cli consolidations modify — 修改合并单
  • fedex-pp-cli consolidations results — 获取合并结果
  • fedex-pp-cli consolidations retrieve — 检索合并单

endofday — 提交和修改 Ground 日终关闭（每日清单）

  • fedex-pp-cli endofday close — 提交 Ground 日终关闭（列出今天发出的包裹）
  • fedex-pp-cli endofday modify — 重新提交或修改之前的日终关闭

freight_pickups — 安排、查询和取消货运（LTL）取件

  • fedex-pp-cli freight_pickups availability — 检查货运取件服务是否可用
  • fedex-pp-cli freight_pickups cancel — 取消货运取件
  • fedex-pp-cli freight_pickups create — 预约货运（LTL）取件

freight_shipments — 创建货运（LTL）货件（面向工业托运人）

  • fedex-pp-cli freight_shipments — 创建货运（LTL）货件

globaltrade — 全球贸易监管详情（HS 编码、限制）

  • fedex-pp-cli globaltrade — 获取监管详情（HS 编码、协调制度、国家限制）

locations — 查找 FedEx Office、投递点和取件点

  • fedex-pp-cli locations — 查找地址或邮政编码附近的 FedEx 网点

openship — 在确认前逐步创建多件货件（高级功能；一般 SMB 工作流不需要）

  • fedex-pp-cli openship add_package — 向未提交的货件添加包裹
  • fedex-pp-cli openship create — 创建未提交的多件货件
  • fedex-pp-cli openship delete — 删除未提交的货件
  • fedex-pp-cli openship delete_package — 从未提交的货件中删除包裹
  • fedex-pp-cli openship modify — 修改未提交的货件
  • fedex-pp-cli openship modify_package — 修改未提交货件中的包裹
  • fedex-pp-cli openship results — 获取已确认的未提交货件的结果
  • fedex-pp-cli openship retrieve — 按索引检索未提交的货件
  • fedex-pp-cli openship retrieve_package — 从未提交的货件中检索指定包裹

pickups — 预约、查询可用情况并取消 Express/Ground 取件

  • fedex-pp-cli pickups availability — 检查指定日期是否可在某邮政编码处取件
  • fedex-pp-cli pickups cancel — 取消此前预约的 Express/Ground 取件
  • fedex-pp-cli pickups create — 预约在指定地址进行 Express 或 Ground 取件

postal — 邮政编码验证和国家服务范围查询

  • fedex-pp-cli postal — 验证 FedEx 是否在某个国家为指定邮政编码提供服务

rates — 查询 Express、Ground、Home、Ground Economy 和货运的运费

  • fedex-pp-cli rates quote — 查询货件运费（Express/Ground/Home/Ground Economy）
  • fedex-pp-cli rates quote_freight — 查询货运（LTL）货件的运费

shipments — 创建、验证、取消和检索货件

  • fedex-pp-cli shipments cancel — 按追踪号码取消货件
  • fedex-pp-cli shipments create — 创建货件并生成标签
  • fedex-pp-cli shipments results — 检索异步货件任务的结果
  • fedex-pp-cli shipments tag — 为现有货件创建 Ground Call Tag（退货标签）
  • fedex-pp-cli shipments tag_cancel — 取消 Ground Call Tag
  • fedex-pp-cli shipments validate — 验证货件包裹但不创建标签（可在计费前发现拒收情况）

track — 按追踪号码、参考编号、TCN 或关联货件追踪货件；检索文件并配置通知

  • fedex-pp-cli track associated — 追踪与主追踪号码关联的货件（多件货件）
  • fedex-pp-cli track documents — 检索追踪文件（签收证明等）
  • fedex-pp-cli track notifications — 为货件配置追踪通知（电子邮件/SMS）
  • fedex-pp-cli track number — 一次调用最多追踪 30 个追踪号码（返回每件货件的完整事件时间线）
  • fedex-pp-cli track reference — 按参考编号追踪（采购订单/客户参考编号/RMA）
  • fedex-pp-cli track tcn — 按运输控制编号追踪（军事/政府用途）

手写命令

  • fedex-pp-cli auth login [--client-id <id>] [--client-secret <secret>] [--env sandbox|prod] — 通过 client_credentials 获取 OAuth2 bearer token 并缓存到磁盘
  • fedex-pp-cli auth logout — 清除缓存的 bearer token
  • fedex-pp-cli auth status — 显示缓存令牌的过期时间，以及检测到的环境变量
  • fedex-pp-cli rate shop --from <zip> --to <zip> --weight <n>[lb|kg] — 并行查询所有适用服务类型的报价，并按费用或运输时间排序
  • fedex-pp-cli ship bulk --csv <path> --service <type> [--output <dir>] [--resume] [--concurrency N] — 为 CSV 文件中的订单创建标签；采用自适应速率限制，并可在部分失败后恢复
  • fedex-pp-cli ship etd --invoice <pdf> --orig <country> --dest <country> ... — 一条命令完成电子贸易文件运输（一次调用完成上传、关联和发货）
  • fedex-pp-cli address save <name> --street <s> --city <c> --state <s> --zip <z> --country <c> — 将收件人保存到本地地址簿
  • fedex-pp-cli address list — 列出本地地址簿中保存的收件人
  • fedex-pp-cli address delete <name> — 从本地地址簿中删除已保存的收件人
  • fedex-pp-cli track diff [--since <duration>] [--tracking <num>...] — 仅显示上次轮询后出现的追踪事件
  • fedex-pp-cli track watch --tracking <num> [--interval <duration>] [--webhook <url>] — 长轮询守护进程：持续轮询追踪信息并发送新事件
  • fedex-pp-cli return create --tracking <orig-tracking> [--reason <reason>] [--email <addr>] — 为现有货件生成退货标签（Ground Call Tag）
  • fedex-pp-cli spend report [--since <duration>] [--by service|account|lane] — 汇总本地货件账本中各服务类型的净费用
  • fedex-pp-cli archive <query> — 使用 FTS5 搜索本地归档中的货件
  • fedex-pp-cli export [--format csv|json] [--since <duration>] [--output <file>] — 导出货件历史，以便进行会计对账
  • fedex-pp-cli manifest [--date YYYY-MM-DD] [--close] [--output <file>] — 根据本地归档生成日终清单报告；也可选择执行 Ground EOD 关闭
  • fedex-pp-cli doctor — 验证身份验证、sandbox/prod 路由、账号格式、标签格式兼容性和 BAG 审批状态
查找合适的命令

如果你知道想做什么，但不知道该用哪个命令，可以直接询问 CLI：

fedex-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有把握足够的匹配项——请改用 --help，或缩小查询范围。

示例

查询价格并选择最便宜的服务
fedex rate shop --from 90210 --to 10001 --weight 5lb --json --select rates.serviceType,rates.totalNetCharge,rates.transitTime

返回所有适用服务类型的费用和运输时间，供 Agent（或人工操作员）选择合适的组合。

批量发货并支持恢复
fedex ship bulk --csv orders.csv --service GROUND --output labels/ --resume --concurrency 2

为 orders.csv 中的每一行创建标签，通过 cliutil.AdaptiveLimiter 遵守 FedEx 每秒 1 个请求的突发限制，并在中断后从最后一行成功记录处恢复。

保存收件人并向其发货
fedex address save acme --street '500 Main St' --city Denver --state CO --zip 80202 --country US

使用地址簿查找收件人信息，无需在每次发货时重复输入。

创建退货标签
fedex return create --tracking 794633071234 --reason damaged --json

根据原始追踪信息生成 Ground Call Tag，并为客户生成 PDF/ZPL 标签。

按服务类型查看月度支出报告
fedex spend report --since 30d --by service --json --select service,total_net_charge,shipment_count

关联本地账本中的货件和报价；回答“我这个月在 FedEx 上花了多少钱”。

身份验证设置

FedEx 使用 OAuth2 client_credentials。使用 sandbox 或 production Client ID 和 Client Secret 运行一次 fedex auth login；CLI 会生成有效期为 1 小时的 bearer token，将其缓存到磁盘，并在过期前主动刷新。生产环境打印标签需要获得 FedEx 针对每个项目的 Bar Code Analysis Group（BAG）审批——fedex doctor 会在你尝试打印前显示审批状态。

运行 fedex-pp-cli doctor 验证设置。

Agent 模式

在任意命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

  • 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

  • 可筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

    fedex-pp-cli addresses --agent --select id,name,status

  • 可预览 — --dry-run 显示请求，但不发送

  • 非交互式 — 绝不提示，每项输入都必须通过标志指定

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

fedex-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
fedex-pp-cli feedback --stdin < notes.txt
fedex-pp-cli feedback list --json --limit 10

条目保存在本地的 ~/.fedex-pp-cli/feedback.jsonl 中。除非设置了 FEDEX_FEEDBACK_ENDPOINT，且传入了 --send 或 FEDEX_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅保存在本地。

写下让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这就是产生累积效应的部分。

输出传递

每条命令都接受 --deliver <sink>。除了输出到 stdout（或代替 stdout）之外，还会将输出发送到指定的目标，这样 Agent 无需手动通过管道传递，就能路由命令结果。支持三种目标：

目标效果
stdout默认；仅输出到 stdout
file:<path>将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>将输出正文 POST 到该 URL（--compact 时使用 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝处理，并返回列出受支持方案的结构化错误。Webhook 失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是已保存的一组标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，就可以使用配置——这是 HeyGen 的“Beacon”模式。

fedex-pp-cli profile save briefing --json
fedex-pp-cli --profile briefing addresses
fedex-pp-cli profile list --json
fedex-pp-cli profile show briefing
fedex-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，让进行自省的 Agent 能在运行时发现它们。

退出代码

代码含义
0成功
2用法错误（参数错误）
3未找到资源
4需要身份验证
5API 错误（上游问题）
7触发速率限制（等待后重试）
10配置错误

参数解析

解析 $ARGUMENTS：

  1. 为空、help 或 --help → 显示 fedex-pp-cli --help 输出
  2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
  3. 其他任何内容 → 直接使用（以带有 --agent 的 CLI 命令执行）

MCP 服务安装

  1. 安装 MCP 服务： 
    go install github.com/mvanhorn/printing-press-library/library/commerce/fedex/cmd/fedex-pp-mcp@latest
  2. 在 Claude Code 中注册： 
    claude mcp add fedex-pp-mcp -- fedex-pp-mcp
  3. 验证：claude mcp list

直接使用

  1. 检查是否已安装：which fedex-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
  2. 根据用户查询，从上文的独特功能和命令参考中匹配最合适的命令。
  3. 使用 --agent 标志执行： 
    fedex-pp-cli <command> [subcommand] [args] --agent
  4. 如果有歧义，可深入查看子命令帮助：fedex-pp-cli <command> --help。

评论

支持 Markdown