cbs-4px-merchant-cli 0.0.1 → 0.0.3

package/skill/reference/update.md

@@ -1,23 +1,31 @@
-# `fmc update`
+# `fmc update` / `fmc skill`
 
-升级 CLI 到最新版本，并自动同步对应的 AI skill。
+升级 CLI 本体，以及把当前版本的 skill 同步到本机 AI 工具。
 
 ## Synopsis
 
 ```bash
 fmc update [--check] [--tag <tag>] [--force] [-y] [--output <format>]
+fmc skill install|status|uninstall [--agent <ids>] [--force] [--dry-run] [--output <format>]
 ```
 
 ## Description
 
-`fmc update` 通过 npm 全局安装机制，将 CLI 升级到 npm registry 上的最新版本。
-升级后由 npm postinstall 自动把新版 SKILL.md 同步到所有已检测到的 AI 工具目录
-（`~/.qoder/skills/`, `~/.claude/skills/`, `~/.cursor/skills/` 等）。
+`fmc update` 通过 npm 全局安装机制，将 CLI 升级到 npm registry 上的最新版本，
+完成后自动调用一次 `fmc skill install`，把新版 SKILL.md 同步到所有已检测到的
+ AI 工具目录（`~/.qoder/skills/`、`~/.claude/skills/`、`~/.cursor/skills/` 等）。
 
-**升级目标**：当前 site 的 npm 包 `cbs-4px-merchant-cli` 在 registry `{{ "https://registry.anpm.alibaba-inc.com" }}` 上。
+> **为何不靠 npm postinstall：**npm 11 默认拦截依赖包的安装期脚本，**且跳过时仍然退出 0**。
+> 所以 skill 铺设不能依赖生命周期钩子，`fmc skill install` 才是唯一可靠的入口；
+> postinstall 仅作为“能跑就顺便跑”的便利钩子保留。
+
+**升级目标**：当前 site 的 npm 包 `cbs-4px-merchant-cli`。registry 以本机 `npm config get registry` 为准，
+可用 `BPORTAL_REGISTRY` 临时覆盖。
 
 ## Options
 
+### `update`
+
 | Flag | Description |
 | --- | --- |
 | `--check` | 只检查是否有新版本，不执行升级 |
@@ -26,6 +34,15 @@ fmc update [--check] [--tag <tag>] [--force] [-y] [--output <format>]
 | `-y, --yes` | 跳过交互式确认 |
 | `--output <format>` | 输出格式: `text` \| `json`（TTY 默认 text，管道默认 json） |
 
+### `skill install` / `skill status` / `skill uninstall`
+
+| Flag | Description |
+| --- | --- |
+| `--agent <ids>` | 只处理指定 AI 工具（逗号分隔，可重复）；非法值会报错并列出全部合法 id |
+| `--force` | 覆盖 / 删除非本 CLI 安装的目录（默认拒绝） |
+| `--dry-run` | 只打印将要执行的操作，不写入任何文件 |
+| `--output <format>` | 输出格式: `text` \| `json` |
+
 ## Environment variables
 
 | Variable | Description |
@@ -53,22 +70,40 @@ fmc update --force -y
 
 # 临时切换 registry 后升级（不修改 ~/.npmrc）
 BPORTAL_REGISTRY=https://registry.npmjs.org fmc update --check
+
+# 把 skill 重新铺到本机所有 AI 工具（安装后的第二步，可反复执行）
+fmc skill install
+
+# 先看将要发生什么，不写入任何文件
+fmc skill install --dry-run --output json
+
+# 只铺到指定工具
+fmc skill install --agent claude-code,qoder
+
+# 查看各工具的安装与版本状态
+fmc skill status --output json
+
+# 移除本 CLI 安装的 skill
+fmc skill uninstall
 ```
 
 ## JSON envelope (`--output json`)
 
+### `update`
+
 ```json
 {
   "ok": true,
   "action": "updated",
   "package": "cbs-4px-merchant-cli",
-  "registry": "https://registry.anpm.alibaba-inc.com",
+  "registry": "https://registry.npmjs.org",
   "tag": "latest",
-  "previous_version": "1.0.10",
-  "current_version": "1.0.11",
-  "latest_version": "1.0.11",
+  "previous_version": "0.0.2",
+  "current_version": "0.0.3",
+  "latest_version": "0.0.3",
   "install_method": "npm",
-  "message": "已升级到 v1.0.11（skill 已通过 postinstall 自动同步）。重新打开终端使生效。"
+  "skill_sync": "ok",
+  "message": "已升级到 v0.0.3，skill 已同步。重新打开终端使生效。"
 }
 ```
 
@@ -82,16 +117,63 @@ BPORTAL_REGISTRY=https://registry.npmjs.org fmc update --check
 | `manual_required` | CLI 非 npm 全局安装，需手动升级 |
 | `error` | 失败（详见 `error.code`：`NETWORK` / `NPM_NOT_FOUND` / `NPM_INSTALL_FAILED` / `EACCES`） |
 
-## Passive update notifier
+`skill_sync` 取值 `ok` \| `failed`。注意：**skill 同步失败不会把 `ok` 置为 false**，
+因为二进制确实升级成功了；此时 `hint` 会提示手动执行 `fmc skill install`。
+
+### `skill install` / `skill status` / `skill uninstall`
+
+```json
+{
+  "ok": true,
+  "action": "installed",
+  "package": "cbs-4px-merchant-cli",
+  "skill": { "name": "cbs-4px-merchant-cli", "version": "0.0.3" },
+  "api_key_configured": false,
+  "targets": [
+    {
+      "agent": "claude-code",
+      "label": "Claude Code",
+      "dir": "/Users/me/.claude/skills/cbs-4px-merchant-cli",
+      "outcome": "updated",
+      "previous_version": "0.0.2",
+      "removed": ["reference/claim.md"]
+    }
+  ],
+  "summary": { "total": 1, "installed": 0, "updated": 1, "skipped": 0, "failed": 0 },
+  "hint": "尚未配置 API Key。申请地址: https://b.4px.com/site/ak-manage，然后执行 fmc auth login --api-key <key>"
+}
+```
+
+`outcome` 取值：
+
+| Value | Meaning |
+| --- | --- |
+| `installed` | 全新安装（目录原本不存在或为空） |
+| `updated` | 覆盖升级，`removed` 列出被清理的孤儿文件 |
+| `skipped` | 目录归属不明或属于其他安装器，未触碰（`reason` 说明原因，`--force` 可覆盖） |
+| `failed` | 写入失败（`reason` 为错误信息） |
+
+`api_key_configured` 只是存在性布尔值，**不会回显 Key 本身**。
+`fmc skill status` 的 `targets` 则携带 `state` / `installed_version` / `installed_source`，
+用于分辨“我装的”和“别人装的”。
+
+## Passive notifiers
 
 普通命令运行后（如 `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"}}
+{"_notice":{"type":"update","package":"cbs-4px-merchant-cli","current":"0.0.2","latest":"0.0.3","hint":"Run: fmc update to upgrade"}}
+```
+
+若本机已安装的 skill 版本与 CLI 不一致，还会额外输出一条漂移通知：
+
+```json
+{"_notice":{"type":"skills","current":"0.0.2","expected":"0.0.3","hint":"Run: fmc skill install to sync skills with CLI v0.0.3"}}
 ```
 
-AI Agent 可据此提示用户升级。设置 `BPORTAL_NO_UPDATE_NOTIFIER=1` 即可关闭。
+漂移检测会扫描**所有**已安装目录；多个工具版本不一致时 `current` 为数组。
+AI Agent 可据此提示用户升级或同步。设置 `BPORTAL_NO_UPDATE_NOTIFIER=1` 即可关闭升级提示。
 
 ## Failure handling
 
@@ -100,3 +182,6 @@ AI Agent 可据此提示用户升级。设置 `BPORTAL_NO_UPDATE_NOTIFIER=1` 即
   或使用 `sudo`。
 - **网络/registry 不可达**：检查 VPN，或用 `BPORTAL_REGISTRY` 临时切换。
 - **非 npm 安装**：`action=manual_required`，envelope 内 `upgrade_command` 字段给出确切的手动升级命令。
+- **skill 同步失败**：`skill_sync=failed`，二进制已升级，手动执行 `fmc skill install` 即可。
+- **目录被跳过**：`outcome=skipped` 说明该目录不是本 CLI 装的（比如技能市场装的）。
+  先用 `fmc skill status` 看 `installed_source` 确认归属，确实该覆盖再加 `--force`。

package/skill/reference/claim.md

@@ -1,66 +0,0 @@
-# `fmc claim` command
-
-## Command details
-
-### `fmc claim list`
-
-| Field | Value |
-| --- | --- |
-| **Name** | `claim list` |
-| **Description** | 查询理赔列表 |
-| **Usage** | `fmc claim list [flags]` |
-
-需要 API Key 认证。`--biz-no` 与时间范围至少传一项。
-
-#### Options
-
-| Flag | Type | Required | Description |
-| --- | --- | --- | --- |
-| `--biz-no <nos>` | string | no | 业务单号，多个用英文逗号分隔 |
-| `--start-time <time>` | string | no | 起始创建时间，格式 yyyy-MM-dd HH:mm:ss |
-| `--end-time <time>` | string | no | 结束创建时间，格式 yyyy-MM-dd HH:mm:ss |
-| `--status <code>` | string | no | 理赔状态：0 全部、1 待处理、2 受理中、3 已解决、4 已退回 |
-| `--page <num>` | number | no | 页码，默认 1 |
-| `--size <num>` | number | no | 每页数量，默认 10，最大 100 |
-
-支持全局选项: `--output`, `--verbose`, `--dry-run`
-
-#### Examples
-
-```bash
-fmc claim list --biz-no FPX12345678
-```
-
-```bash
-fmc claim list --start-time "2024-01-01 00:00:00" --end-time "2024-12-31 23:59:59"
-```
-
-```bash
-fmc claim list --status 1 --page 1 --size 20
-```
-
-```bash
-fmc claim list --biz-no FPX111,FPX222 --output json
-```
-
-#### Output (text mode)
-
-```
-理赔列表
-──────────────────────────────────────────────────
-  页码 1/1  共 2 条
-
-  CLM20240115001  受理中
-    业务单号    FPX12345678
-    索赔原因    包裹丢失
-    货值赔偿    150.00 USD
-    最新反馈    正在核实物流信息
-    创建时间    2024-01-15 10:30:00
-
-  CLM20240110002  已解决
-    业务单号    FPX87654321
-    索赔原因    包裹破损
-    货值赔偿    50.00 USD
-    服务赔偿    20.00 USD
-    创建时间    2024-01-10 08:00:00
-```