cbs-4px-merchant-cli 0.0.1

package/skill/reference/index.md

@@ -0,0 +1,51 @@
+# `fmc` command reference
+
+> BPortal Merchant CLI — 跨境物流商家命令行工具。
+
+Command **details** are in sibling `<group>.md` files in this directory.
+
+## Quick index
+
+| Command | Description | Detail |
+| --- | --- | --- |
+| `fmc auth login` | 配置 API Key | [auth.md](auth.md) |
+| `fmc auth status` | 查看当前认证状态 | [auth.md](auth.md) |
+| `fmc config set` | 设置配置项 | [config.md](config.md) |
+| `fmc config list` | 查看当前配置 | [config.md](config.md) |
+| `fmc config export-schema` | 导出命令的 JSON tool schema | [config.md](config.md) |
+| `fmc track get` | 查询物流轨迹 | [track.md](track.md) |
+| `fmc label get` | 获取面单打印信息（PDF 链接） | [label.md](label.md) |
+| `fmc order get` | 获取订单详情 | [order.md](order.md) |
+| `fmc product recommend` | 获取推荐物流产品及报价 | [product.md](product.md) |
+| `fmc claim list` | 查询理赔列表 | [claim.md](claim.md) |
+| `fmc update` | 升级 CLI 及对应 skill 到最新版本 | [update.md](update.md) |
+
+## By group
+
+| Group | Commands | Reference |
+| --- | --- | --- |
+| `auth` | `login`, `status` | [auth.md](auth.md) |
+| `config` | `set`, `list`, `export-schema` | [config.md](config.md) |
+| `track` | `get` | [track.md](track.md) |
+| `label` | `get` | [label.md](label.md) |
+| `order` | `get` | [order.md](order.md) |
+| `product` | `recommend` | [product.md](product.md) |
+| `claim` | `list` | [claim.md](claim.md) |
+| `update` | (no subcommand) | [update.md](update.md) |
+
+## Global flags
+
+| Flag | Description |
+| --- | --- |
+| `--output <format>` | 输出格式: text \| json（TTY 默认 text，管道默认 json） |
+| `--verbose` | 打印请求详情（URL、Headers、状态码） |
+| `--dry-run` | 仅打印请求信息，不实际发送 |
+| `--help` | 查看帮助 |
+| `--version` | 打印版本号 |
+
+## Notes
+
+- `track get` 命令无需认证即可使用。
+- `label get`、`order get`、`product recommend`、`claim list` 命令需要先配置 API Key：`fmc auth login --api-key <SK_xxx>`。
+- 配置文件位于 `~/.bportal/config.json`；升级状态缓存位于 `~/.bportal/update-state.json`。
+- 当检测到新版本可用时，stderr 会输出 `{"_notice":{"type":"update",...}}`；设置环境变量 `BPORTAL_NO_UPDATE_NOTIFIER=1` 可关闭。

package/skill/reference/label.md

@@ -0,0 +1,51 @@
+# `fmc label` command
+
+## Command details
+
+### `fmc label get`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `label get` |
+| **Description** | 获取面单打印信息（PDF 链接） |
+| **Usage** | `fmc label get <orderNo> [flags]` |
+
+需要 API Key 认证。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<orderNo>` | string | yes | 运单号 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc label get FPX12345678
+```
+
+```bash
+fmc label get FPX12345678 --output json
+```
+
+```bash
+fmc label get FPX12345678 --dry-run
+```
+
+#### Output (text mode)
+
+```
+标签打印信息
+──────────────────────────────────────────────────
+  PDF 链接  https://xxx.com/label.pdf
+
+  订单基础信息
+  运单号    FPX12345678
+  FPX单号   FPX12345678
+  产品代码  STANDARD
+  起运国    CN
+  目的国    US
+  状态      已签收
+```

package/skill/reference/order.md

@@ -0,0 +1,68 @@
+# `fmc order` command
+
+## Command details
+
+### `fmc order get`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `order get` |
+| **Description** | 获取订单详情（含收件人信息、申报信息、费用明细） |
+| **Usage** | `fmc order get <orderNo> [flags]` |
+
+需要 API Key 认证。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<orderNo>` | string | yes | 运单号 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc order get FPX12345678
+```
+
+```bash
+fmc order get FPX12345678 --output json
+```
+
+```bash
+fmc order get FPX12345678 --verbose
+```
+
+#### Output (text mode)
+
+```
+订单详情
+──────────────────────────────────────────────────
+  基础信息
+  运单号      FPX12345678
+  FPX单号     FPX12345678
+  产品代码    STANDARD
+  起运国      CN
+  目的国      US
+  状态        已签收
+  实重(g)     500
+  计费重(g)   600
+
+  收件人信息
+  姓名        John Doe
+  国家        US
+  城市        New York
+  地址        123 Main St
+  邮编        10001
+  电话        +1234567890
+
+  申报信息
+  1    T-Shirt              10.00 USD
+
+  费用明细
+  运费             应付: 25.00 USD
+  燃油附加费       应付: 5.00 USD
+  ────────────────────────────────────────
+  合计        30.00 USD
+```

package/skill/reference/product.md

@@ -0,0 +1,70 @@
+# `fmc product` command
+
+## Command details
+
+### `fmc product recommend`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `product recommend` |
+| **Description** | 根据条件获取推荐物流产品及报价 |
+| **Usage** | `fmc product recommend --country <code> [flags]` |
+
+需要 API Key 认证。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--country <code>` | string | yes | 目的国家二字码，如 US、GB、JP |
+| `--start-city <city>` | string | no | 起运城市中文名，默认深圳 |
+| `--weight <kg>` | number | no | 重量(kg)，默认 1 |
+| `--post-code <code>` | string | no | 目的地邮编 |
+| `--is-battery <flag>` | string | no | 是否带电：1-带电 2-普货 |
+| `--declare-value <amount>` | number | no | 申报总价值 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc product recommend --country US
+```
+
+```bash
+fmc product recommend --country US --weight 2.5 --start-city 广州
+```
+
+```bash
+fmc product recommend --country GB --is-battery 1 --post-code SW1A1AA
+```
+
+```bash
+fmc product recommend --country JP --output json
+```
+
+#### Output (text mode)
+
+```
+产品推荐
+──────────────────────────────────────────────────
+  目的国    US (美国)
+
+  推荐产品（共 3 个）
+
+  4PX经济小包 ★推荐
+    产品代码    ECO-PKG
+    服务等级    经济
+    跟踪类型    全程跟踪
+    时效        7-15工作日
+    总费用(RMB) 35.00
+    计费重      1000g
+
+  4PX标准快递
+    产品代码    STD-EXP
+    服务等级    标准
+    跟踪类型    全程跟踪
+    时效        5-8工作日
+    总费用(RMB) 58.00
+    计费重      1000g
+```

package/skill/reference/track.md

@@ -0,0 +1,57 @@
+# `fmc track` command
+
+## Command details
+
+### `fmc track get`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `track get` |
+| **Description** | 查询物流轨迹 |
+| **Usage** | `fmc track get <orderNo> [flags]` |
+
+无需认证即可使用。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<orderNo>` | string | yes | 运单号 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc track get FPX12345678
+```
+
+```bash
+fmc track get FPX12345678 --output json
+```
+
+```bash
+fmc track get FPX12345678 --verbose
+```
+
+```bash
+fmc track get FPX12345678 --dry-run
+```
+
+#### Output (text mode)
+
+```
+物流轨迹查询
+──────────────────────────────────────────────────
+  单号     FPX12345678
+  起运地   中国
+  目的地   美国
+
+  最新轨迹
+  2024-01-15 10:30  纽约  已签收
+
+  全部轨迹
+  2024-01-15 10:30  纽约      已签收
+  2024-01-14 08:00  洛杉矶    海关放行
+  2024-01-10 14:20  深圳      已发出
+```

package/skill/reference/update.md

@@ -0,0 +1,102 @@
+# `fmc update`
+
+升级 CLI 到最新版本，并自动同步对应的 AI skill。
+
+## Synopsis
+
+```bash
+fmc update [--check] [--tag <tag>] [--force] [-y] [--output <format>]
+```
+
+## Description
+
+`fmc update` 通过 npm 全局安装机制，将 CLI 升级到 npm registry 上的最新版本。
+升级后由 npm postinstall 自动把新版 SKILL.md 同步到所有已检测到的 AI 工具目录
+（`~/.qoder/skills/`, `~/.claude/skills/`, `~/.cursor/skills/` 等）。
+
+**升级目标**：当前 site 的 npm 包 `cbs-4px-merchant-cli` 在 registry `{{ "https://registry.anpm.alibaba-inc.com" }}` 上。
+
+## Options
+
+| Flag | Description |
+| --- | --- |
+| `--check` | 只检查是否有新版本，不执行升级 |
+| `--tag <tag>` | npm dist-tag（默认 `latest`，可选 `pre` / `test`） |
+| `--force` | 强制重装当前版本（修复 skill 损坏） |
+| `-y, --yes` | 跳过交互式确认 |
+| `--output <format>` | 输出格式: `text` \| `json`（TTY 默认 text，管道默认 json） |
+
+## Environment variables
+
+| Variable | Description |
+| --- | --- |
+| `BPORTAL_REGISTRY` | 临时覆盖默认 registry（开发/镜像调试用） |
+| `BPORTAL_NO_UPDATE_NOTIFIER` | 设为任意值即关闭被动 `_notice.update` 提示 |
+
+## Examples
+
+```bash
+# 检查是否有新版本（不执行升级）
+fmc update --check
+
+# 检查并以 JSON 输出（适合 AI Agent 解析）
+fmc update --check --output json
+
+# 升级到 latest（交互确认）
+fmc update
+
+# 升级到预发布版本
+fmc update --tag pre
+
+# 重装当前版本（修复 skill）
+fmc update --force -y
+
+# 临时切换 registry 后升级（不修改 ~/.npmrc）
+BPORTAL_REGISTRY=https://registry.npmjs.org fmc update --check
+```
+
+## JSON envelope (`--output json`)
+
+```json
+{
+  "ok": true,
+  "action": "updated",
+  "package": "cbs-4px-merchant-cli",
+  "registry": "https://registry.anpm.alibaba-inc.com",
+  "tag": "latest",
+  "previous_version": "1.0.10",
+  "current_version": "1.0.11",
+  "latest_version": "1.0.11",
+  "install_method": "npm",
+  "message": "已升级到 v1.0.11（skill 已通过 postinstall 自动同步）。重新打开终端使生效。"
+}
+```
+
+`action` 取值：
+
+| Value | Meaning |
+| --- | --- |
+| `updated` | 升级成功 |
+| `already_up_to_date` | 已是最新版本（包括本地版本领先 registry 的情况） |
+| `update_available` | 仅在 `--check` 模式下：发现新版本 |
+| `manual_required` | CLI 非 npm 全局安装，需手动升级 |
+| `error` | 失败（详见 `error.code`：`NETWORK` / `NPM_NOT_FOUND` / `NPM_INSTALL_FAILED` / `EACCES`） |
+
+## Passive update notifier
+
+普通命令运行后（如 `fmc track get ...`），若本地缓存（`~/.bportal/update-state.json`，
+TTL 24 小时）发现 registry 上有新版本，stderr 会输出一条 JSON 通知：
+
+```json
+{"_notice":{"type":"update","package":"cbs-4px-merchant-cli","current":"1.0.10","latest":"1.0.11","hint":"Run: fmc update to upgrade"}}
+```
+
+AI Agent 可据此提示用户升级。设置 `BPORTAL_NO_UPDATE_NOTIFIER=1` 即可关闭。
+
+## Failure handling
+
+- **EACCES 权限错误**：通常发生在 `/usr/local/lib/node_modules` 等目录。建议修复 npm prefix
+  让全局安装无需特权（参见 [npm 官方指南](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)），
+  或使用 `sudo`。
+- **网络/registry 不可达**：检查 VPN，或用 `BPORTAL_REGISTRY` 临时切换。
+- **非 npm 安装**：`action=manual_required`，envelope 内 `upgrade_command` 字段给出确切的手动升级命令。