cbs-4px-merchant-cli 0.0.7 → 0.0.8

package/skill/SKILL.md

@@ -2,20 +2,22 @@
 name: cbs-4px-merchant-cli
 description: >-
   BPortal Merchant CLI (`fmc`) — 跨境物流商家命令行工具。
-  支持物流轨迹查询、面单打印、订单管理、产品推荐与报价、理赔查询、
-  异常件管理、服务中心、财务管理、揽收管理、系统公告。
+  支持物流轨迹查询、面单打印、普通下单与订单管理、产品推荐与报价、理赔查询、
+  异常件管理、服务中心、财务管理、揽收管理、系统公告、平台拉单、商家入驻。
   完整命令参考: `reference/index.md` + `reference/<group>.md`。
 ---
 
 # BPortal Merchant CLI (`fmc`)
 
-> 跨境物流商家命令行工具，提供物流轨迹查询、面单打印、订单管理、产品推荐与报价、理赔查询、异常件管理、服务中心、财务管理、揽收管理、系统公告等功能。
+> 跨境物流商家命令行工具，提供物流轨迹查询、面单打印、普通下单与订单管理、产品推荐与报价、理赔查询、异常件管理、服务中心、财务管理、揽收管理、系统公告、平台拉单、商家入驻等功能。
 
 ## 严格禁止 (NEVER DO)
 
 - 不要编造单号、API Key 等标识符，必须从用户输入或命令返回中获取
 - 不要猜测参数值，不确定时先查阅对应 reference 文件或执行 `fmc <command> --help`
 - 参数名不确定时禁止编造 flag，必须先确认
+- **不要自行给写操作加 `-y`**（见下方「写操作」）：下单预报、取消/拦截、推单履约、提交实名资料、开通品牌都有业务副作用，必须先向用户确认
+- 不要编造身份证号、银行卡号、验证码；也不要把这些值写进总结、日志或回复里
 
 ## 核心流程（每次请求必须执行）
 
@@ -34,6 +36,7 @@ description: >-
 | 查询物流轨迹 | [`reference/track.md`](reference/track.md) | 确认参数格式 |
 | 获取面单 | [`reference/label.md`](reference/label.md) | 确认参数格式 |
 | 查看订单详情 | [`reference/order.md`](reference/order.md) | 确认参数和输出字段 |
+| 下单 / 改单 / 预报 / 取消 / 拦截 | [`reference/order.md`](reference/order.md) | 含写操作，字段是嵌套 JSON，必须先读字段结构 |
 | 地址簿 | [`reference/order.md`](reference/order.md) | 确认参数格式 |
 | 国家查询 | [`reference/order.md`](reference/order.md) | 确认参数格式 |
 | 产品推荐 | [`reference/product.md`](reference/product.md) | 参数多（国家/重量/电池/邮编等），必须确认 |
@@ -43,6 +46,9 @@ description: >-
 | 财务管理 | [`reference/finance.md`](reference/finance.md) | 确认子命令和参数格式 |
 | 揽收管理 | [`reference/pickup.md`](reference/pickup.md) | 确认参数格式 |
 | 系统公告 | [`reference/notice.md`](reference/notice.md) | 确认参数格式 |
+| 报关 / 商品备案 / HS 编码 | [`reference/customs.md`](reference/customs.md) | 确认子命令和参数格式 |
+| 平台拉单 / 卖家账号 / 推单 | [`reference/platform.md`](reference/platform.md) | 含写操作，必须确认参数与确认机制 |
+| 入驻 / 实名认证 / 开通品牌 / 合同 | [`reference/onboarding.md`](reference/onboarding.md) | 认证路径分大陆/港澳台/海外，走错就会失败 |
 | 认证相关 / 首次使用 | [`reference/auth.md`](reference/auth.md) | 了解认证方式和 API Key 获取地址 |
 | 配置管理 | [`reference/config.md`](reference/config.md) | 了解可配置项 |
 | 升级 CLI / skill | [`reference/update.md`](reference/update.md) | 了解升级流程和选项 |
@@ -59,7 +65,7 @@ description: >-
 | `config` | 配置管理：查看/设置配置项、导出 tool schema | [`reference/config.md`](reference/config.md) |
 | `track` | 物流轨迹：按单号查询物流全程轨迹、轨迹订阅管理 | [`reference/track.md`](reference/track.md) |
 | `label` | 面单打印：获取面单 PDF 链接 | [`reference/label.md`](reference/label.md) |
-| `order` | 订单管理：查看订单详情、订单列表、地址簿、目的国搜索 | [`reference/order.md`](reference/order.md) |
+| `order` | 订单管理：下单/改单/预报/取消/拦截（**含写操作**）、订单详情、订单列表、地址簿、目的国搜索 | [`reference/order.md`](reference/order.md) |
 | `product` | 产品推荐：推荐产品、产品列表、产品详情、时效查询、搜索产品 | [`reference/product.md`](reference/product.md) |
 | `claim` | 理赔查询：按单号/时间/状态查询理赔列表（挂在 `service` 下，即 `fmc service claim ...`） | [`reference/service.md`](reference/service.md) |
 | `problem` | 异常件管理：问题件列表、AI处理建议、通知件、尾程异常、欠费件、拦截件 | [`reference/problem.md`](reference/problem.md) |
@@ -67,6 +73,9 @@ description: >-
 | `finance` | 财务管理：账户余额、账单、每日费用、未出账汇总及明细、充值记录（在线及线下）、计费明细 | [`reference/finance.md`](reference/finance.md) |
 | `pickup` | 揽收管理：物料申请单查询 | [`reference/pickup.md`](reference/pickup.md) |
 | `notice` | 系统公告：公告列表、公告详情 | [`reference/notice.md`](reference/notice.md) |
+| `customs` | 报关合规：申报品、商品备案列表与详情、HS 编码查询、客户备案信息 | [`reference/customs.md`](reference/customs.md) |
+| `platform` | 平台拉单：卖家账号、拉取平台订单、拉单记录、平台订单列表/详情/推送（**含写操作**） | [`reference/platform.md`](reference/platform.md) |
+| `onboarding` | 商家入驻：入驻进度、实名认证（个人/企业/港澳台海外）、开通品牌、合同申请与签署（**含写操作**） | [`reference/onboarding.md`](reference/onboarding.md) |
 | `update` | 升级：检查并升级 CLI 及 skill 到最新版本 | [`reference/update.md`](reference/update.md) |
 
 运行 `fmc <command> --help` 查看命令帮助。
@@ -105,8 +114,33 @@ description: >-
 用户提到"计费明细" → `fmc finance fee-detail`
 用户提到"地址簿/地址列表" → `fmc order address-book`
 用户提到"目的国/国家查询/搜索国家" → `fmc order country`
+用户提到"下单/开单/建单/寄一个包裹" → `fmc order create --draft`（**写**，先建草稿让用户核对）
+用户提到"改单/修改订单/改地址改重量" → `fmc order edit`（**写**，仅草稿与已取消单可改）
+用户提到"提交预报/发出去/确认发货" → `fmc order forecast`（**写**）
+用户提到"取消订单/不寄了/作废" → `fmc order cancel`（**写**）
+用户提到"拦截/拦下来/别发了"（已预报） → `fmc order intercept`（**写**）
 用户提到"物料/物料申请" → `fmc pickup material`
 用户提到"公告/通知/系统公告" → `fmc notice list`
+用户提到"申报品/报关品名" → `fmc customs cargo list`
+用户提到"商品备案/备案列表" → `fmc customs commodity list`
+用户提到"HS编码/海关编码/税号" → `fmc customs hscode search`
+用户提到"客户备案/海关备案信息" → `fmc customs registration info`
+用户提到"卖家账号/店铺授权" → `fmc platform account list`
+用户提到"拉单/同步平台订单/拉亚马逊订单" → `fmc platform sync`（**写**）
+用户提到"拉单结果/同步记录/拉到多少单" → `fmc platform sync-record list`
+用户提到"平台订单/待推送订单" → `fmc platform order list`
+用户提到"推单/推送订单/交给物流" → `fmc platform order push`（**写**）
+用户提到"入驻进度/卡在哪一步/开通到哪了" → `fmc onboarding progress`
+用户提到"实名认证进度/认证状态" → `fmc onboarding auth schedule`
+用户提到"个人实名/实名认证（大陆）" → `fmc onboarding auth indiv`（**写**）
+用户提到"验证码/收到短信了" → `fmc onboarding auth code`（**写**）
+用户提到"企业实名/公司认证" → `fmc onboarding auth organ`（**写**）
+用户提到"港澳台/海外客户认证" → `fmc onboarding auth gat`（**写**）
+用户提到"对公打款/打款金额验证" → `fmc onboarding auth remit`（**写**）
+用户提到"可开通品牌/有哪些品牌" → `fmc onboarding brand list`
+用户提到"开通品牌/申请合同" → `fmc onboarding brand open`（**写**）
+用户提到"合同/我的合同" → `fmc onboarding contract list`
+用户提到"签合同/签署链接/下载合同" → `fmc onboarding contract url`
 用户提到"登录/配置key/认证" → `fmc auth login`
 用户提到"升级/更新/新版本" → `fmc update`
 
@@ -122,6 +156,9 @@ description: >-
 | "查理赔" | `service claim list` | `service claim detail` | 前者查列表，后者按理赔单号查详情 |
 | "我的订单" | `order list` | `order get` | 前者是列表，后者按单号查详情 |
 | "运费/多少钱" | `product recommend`（发货前询价） | `order get`（已发货查费用） | 发货前用 product recommend 试算；已发货查费用用 order get |
+| "同步订单/拉单" | `platform sync` | `order list` | `platform` 是从电商平台拉取；`order` 是已下单的物流单 |
+| "平台订单 vs 物流订单" | `platform order list`（拉回来未推送的） | `order list`（已下单的物流单） | 两者是推单前后两个阶段 |
+| "实名认证" | 先 `onboarding progress` 确认客户类型，再选 `auth indiv` / `auth organ` / `auth gat` | 直接猜一个 | 大陆走 indiv/organ，港澳台与海外走 gat |
 
 ---
 
@@ -153,6 +190,46 @@ export BPORTAL_API_KEY=sk-xxxxx
 
 ---
 
+## 写操作（需用户确认）
+
+以下命令会真实改变商家数据，必须按「后果」列判断可逆性并取得用户确认：
+
+| 命令 | 后果 |
+| --- | --- |
+| `order create`（不带 `--draft`） | 直接建单并提交预报，进入履约 |
+| `order edit`（不带 `--draft`） | 改完立即提交预报 |
+| `order forecast` | 草稿转预报，进入履约 |
+| `order cancel` | 取消订单 |
+| `order intercept` | 向承运商申请拦截 |
+| `platform sync` | 提交拉单任务（异步） |
+| `platform order push` | 订单进入物流履约流程 |
+| `onboarding auth indiv` / `auth code` / `auth organ` / `auth gat` | 提交实名认证资料 |
+| `onboarding auth remit` | 消耗打款校验重试次数 |
+| `onboarding brand open` | 开通品牌并发起合同申请 |
+
+执行规则：
+
+1. **先向用户展示完整命令并得到明确确认**，不要把确认省掉
+2. 不确定参数是否正确时，先加 `--dry-run` 看请求内容（不会发送）
+3. 用户确认后才加 `-y` 执行（AI 工具非 TTY，不加 `-y` 会直接报错退出）
+4. 输出中的敏感参数（身份证号、银行卡号、验证码、手机号）已遮蔽为 `****`，但**真实值仍会发送**；不要在回复里重复这些值
+
+### 下单必须走草稿确认
+
+**默认用 `order create --draft` 建草稿，不要直接提交预报。** 草稿已落库、可查、可改、可取消，是唯一能让用户核对后再发货的方式：
+
+1. `order create --file <json> --draft -y` → 拿到 `orderId`
+2. `order get <orderNo>` 把收件人、重量、申报品念给用户核对
+3. 有错就 `order edit --order-id <id> --file <json> --draft -y` 改，改到对
+4. 用户明确同意后 `order forecast --ids <id> -y` 提交预报
+5. `label get <orderNo>` 取面单
+
+只有用户明确说"直接下单/不用确认"时，才允许省掉 `--draft`。
+
+`order create` 会对缺失字段发 `⚠` 告警（收件人、重量、申报品等）。**告警不等于可以忽略** —— 后端只校验 `productCode` 和 `destinationCountry`，其余字段缺失要到清关或派送环节才报错，届时已不可撤回。有告警就先补齐再提交。
+
+---
+
 ## Quick examples
 
 ```bash
@@ -168,6 +245,17 @@ fmc order get FPX12345678
 # 查询订单列表
 fmc order list --status IN_TRANSIT
 
+# 下单（写操作）—— 先建草稿，用户核对无误后再预报
+fmc order create --file ./order.json --draft -y
+fmc order forecast --ids 1001 -y
+
+# 改草稿（写操作，只传要改的字段）
+fmc order edit --order-id 1001 --file ./patch.json --draft -y
+
+# 取消 / 拦截（写操作）
+fmc order cancel --ids 1001 --reason "客户取消" -y
+fmc order intercept --ids 1001 -y
+
 # 获取推荐产品（寄美国）
 fmc product recommend --country US
 
@@ -185,6 +273,23 @@ fmc order country 美国
 
 # JSON 格式输出
 fmc track get FPX12345678 --output json
+
+# 查询已授权的卖家账号
+fmc platform account list
+
+# 查询待推送的平台订单
+fmc platform order list --status 0
+
+# 拉单（写操作，用户确认后才加 -y）
+fmc platform sync --seller-account-id 10086 \
+  --time-from "2026-08-01 00:00:00" --time-to "2026-08-31 23:59:59" -y
+
+# 查询入驻进度
+fmc onboarding progress
+
+# 查询合同并获取签署链接
+fmc onboarding contract list
+fmc onboarding contract url CT20260801001
 ```
 
 ---
@@ -222,4 +327,7 @@ fmc config set baseUrl https://b.4px.com
 - [`reference/finance.md`](reference/finance.md) — 财务管理详细参数
 - [`reference/pickup.md`](reference/pickup.md) — 揽收管理详细参数
 - [`reference/notice.md`](reference/notice.md) — 系统公告详细参数
+- [`reference/customs.md`](reference/customs.md) — 报关、商品备案与 HS 编码详细参数
+- [`reference/platform.md`](reference/platform.md) — 平台拉单与推单详细参数
+- [`reference/onboarding.md`](reference/onboarding.md) — 入驻、实名认证、品牌与合同详细参数
 - [`reference/update.md`](reference/update.md) — CLI / skill 升级详细参数

package/skill/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbs-4px-merchant-cli",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "BPortal Merchant CLI (fmc) skill — BPortal",
   "files": [
     "SKILL.md",
@@ -12,8 +12,10 @@
     "reference/index.md",
     "reference/label.md",
     "reference/notice.md",
+    "reference/onboarding.md",
     "reference/order.md",
     "reference/pickup.md",
+    "reference/platform.md",
     "reference/problem.md",
     "reference/product.md",
     "reference/service.md",

package/skill/reference/index.md

@@ -21,6 +21,11 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `fmc order list` | 查询订单列表 | [order.md](order.md) |
 | `fmc order address-book` | 查询地址簿列表 | [order.md](order.md) |
 | `fmc order country` | 模糊搜索目的国家 | [order.md](order.md) |
+| `fmc order create` | 创建物流订单（写） | [order.md](order.md) |
+| `fmc order edit` | 编辑草稿/已取消订单（写） | [order.md](order.md) |
+| `fmc order forecast` | 草稿提交为预报（写） | [order.md](order.md) |
+| `fmc order cancel` | 取消订单（写） | [order.md](order.md) |
+| `fmc order intercept` | 申请拦截订单（写） | [order.md](order.md) |
 | `fmc product recommend` | 获取推荐物流产品及报价 | [product.md](product.md) |
 | `fmc product list` | 查询可用产品列表 | [product.md](product.md) |
 | `fmc product detail` | 查询产品详情 | [product.md](product.md) |
@@ -62,6 +67,24 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `fmc customs commodity detail` | 查询商品备案详情 | [customs.md](customs.md) |
 | `fmc customs hscode search` | 查询海关编码 | [customs.md](customs.md) |
 | `fmc customs registration info` | 查询客户备案信息 | [customs.md](customs.md) |
+| `fmc platform account list` | 查询已授权的卖家账号列表 | [platform.md](platform.md) |
+| `fmc platform sync` | 拉取平台订单（写） | [platform.md](platform.md) |
+| `fmc platform sync-record list` | 查询拉单记录 | [platform.md](platform.md) |
+| `fmc platform order list` | 查询平台订单列表 | [platform.md](platform.md) |
+| `fmc platform order detail` | 查询平台订单详情 | [platform.md](platform.md) |
+| `fmc platform order push` | 推送平台订单履约（写） | [platform.md](platform.md) |
+| `fmc onboarding progress` | 查询入驻进度 | [onboarding.md](onboarding.md) |
+| `fmc onboarding customer-type` | 查询可选客户类型 | [onboarding.md](onboarding.md) |
+| `fmc onboarding auth schedule` | 查询实名认证进度 | [onboarding.md](onboarding.md) |
+| `fmc onboarding auth indiv` | 发起个人实名认证（写） | [onboarding.md](onboarding.md) |
+| `fmc onboarding auth code` | 提交验证码完成实名认证（写） | [onboarding.md](onboarding.md) |
+| `fmc onboarding auth organ` | 发起企业实名认证（写） | [onboarding.md](onboarding.md) |
+| `fmc onboarding auth gat` | 提交港澳台/海外实名资料（写） | [onboarding.md](onboarding.md) |
+| `fmc onboarding auth remit` | 校验对公打款金额（写） | [onboarding.md](onboarding.md) |
+| `fmc onboarding brand list` | 查询可开通品牌 | [onboarding.md](onboarding.md) |
+| `fmc onboarding brand open` | 开通品牌并申请合同（写） | [onboarding.md](onboarding.md) |
+| `fmc onboarding contract list` | 查询合同列表 | [onboarding.md](onboarding.md) |
+| `fmc onboarding contract url` | 获取合同签署/下载链接 | [onboarding.md](onboarding.md) |
 | `fmc update` | 升级 CLI 及对应 skill 到最新版本 | [update.md](update.md) |
 | `fmc skill install` | 把当前版本的 skill 同步到本机 AI 工具 | [update.md](update.md) |
 | `fmc skill status` | 查看各 AI 工具的 skill 安装与版本状态 | [update.md](update.md) |
@@ -75,7 +98,7 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `config` | `set`, `list`, `export-schema` | [config.md](config.md) |
 | `track` | `get`, `sub order`, `sub product` | [track.md](track.md) |
 | `label` | `get` | [label.md](label.md) |
-| `order` | `get`, `list`, `address-book`, `country` | [order.md](order.md) |
+| `order` | `get`, `list`, `address-book`, `country`, `create`, `edit`, `forecast`, `cancel`, `intercept` | [order.md](order.md) |
 | `product` | `recommend`, `list`, `detail`, `eta`, `search` | [product.md](product.md) |
 | `problem` | `list`, `suggest`, `notify list`, `notify type`, `lastmile list`, `arrear list`, `intercepted list` | [problem.md](problem.md) |
 | `service` | `repair list`, `check list`, `complaint list`, `detail`, `record`, `claim list`, `claim detail`, `claim reason` | [service.md](service.md) |
@@ -83,6 +106,8 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `pickup` | `material list`, `material detail`, `material quota`, `address list` | [pickup.md](pickup.md) |
 | `notice` | `list`, `detail`, `message list`, `message detail`, `message unread` | [notice.md](notice.md) |
 | `customs` | `cargo list`, `commodity list`, `commodity detail`, `hscode search`, `registration info` | [customs.md](customs.md) |
+| `platform` | `account list`, `sync`, `sync-record list`, `order list`, `order detail`, `order push` | [platform.md](platform.md) |
+| `onboarding` | `progress`, `customer-type`, `auth schedule`, `auth indiv`, `auth code`, `auth organ`, `auth gat`, `auth remit`, `brand list`, `brand open`, `contract list`, `contract url` | [onboarding.md](onboarding.md) |
 | `update` | (no subcommand) | [update.md](update.md) |
 | `skill` | `install`, `status`, `uninstall` | [update.md](update.md) |
 
@@ -100,8 +125,10 @@ Command **details** are in sibling `<group>.md` files in this directory.
 
 - `track get` 命令无需认证即可使用。
 - 其余大部分命令需要先配置 API Key：`fmc auth login --api-key <key>`。Key 是控制台生成的原串（常见前缀 `SK_` 或 `sk-`），原样传入，不要校验或改写。
-- 新增的 `problem`、`service`、`finance`、`pickup`、`notice`、`customs` 模块均需要 API Key 认证。`order` 模块下的 `address-book`、`country` 子命令也需要认证。
+- 新增的 `problem`、`service`、`finance`、`pickup`、`notice`、`customs`、`platform`、`onboarding` 模块均需要 API Key 认证。`order` 模块下的 `address-book`、`country` 子命令也需要认证。
+- **写操作**（`platform sync`、`platform order push`、`onboarding auth *`、`onboarding brand open`）默认在终端二次确认；非交互环境（管道、CI、AI Agent）必须显式加 `-y`，否则命令会拒绝执行并以退出码 1 结束。先用 `--dry-run` 可查看将发送的请求。
+- 实名认证会提交身份证号、银行卡号、验证码、手机号等敏感信息。这些参数在 `--verbose` / `--dry-run` 的**打印**里被遮蔽为 `****`，但真实值仍会随请求发送。
 - 配置文件位于 `~/.bportal/config.json`；升级状态缓存位于 `~/.bportal/update-state.json`。
 - 当检测到新版本可用时，stderr 会输出 `{"_notice":{"type":"update",...}}`；设置环境变量 `BPORTAL_NO_UPDATE_NOTIFIER=1` 可关闭。
 - 当已安装的 skill 版本与 CLI 不一致时，stderr 会输出 `{"_notice":{"type":"skills",...}}`；执行 `fmc skill install` 即可同步。
-- `npm install -g cbs-4px-merchant-cli` **不保证**会自动注册 skill（npm 11 默认拦截安装期脚本，且仍退出 0），安装后应显式执行 `fmc skill install`。
+- `npm install -g cbs-4px-merchant-cli` **不保证**会自动注册 skill（npm 12 默认拦截安装期脚本，且仍退出 0），安装后应显式执行 `fmc skill install`。