cbs-4px-merchant-cli 0.0.2 → 0.0.4

package/scripts/postinstall.js

@@ -1,184 +1,54 @@
 #!/usr/bin/env node
 
 /**
- * Postinstall script: automatically install SKILL.md to all detected AI coding tools.
+ * Postinstall hook — a best-effort convenience wrapper, nothing more.
  *
- * For each tool whose root dir exists, writes SKILL.md + reference/ to
- * <root>/skills/cbs-merchant-cli/.
+ * All skill logic lives in `src/services/skill-installer.ts` and is reachable
+ * as `<bin> skill install`; this hook only spawns that command so users on npm
+ * versions that still run install scripts get the skill without a second step.
  *
- * Inspired by bailian-cli's postinstall approach.
+ * It deliberately owns no logic of its own, because it cannot be relied upon:
+ * npm 11 blocks dependency install scripts by default and *still exits 0*, so
+ * anything that must happen cannot live here. When the hook is skipped, the
+ * install docs' second step (`<bin> skill install`) covers it.
+ *
+ * Never fails the install: any problem exits 0 with a short hint on stderr.
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  copyFileSync,
-  cpSync,
-  openSync,
-  writeSync,
-  writeFileSync,
-  closeSync,
-  readFileSync,
-} from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
-import { homedir } from 'os';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
+import { spawnSync } from 'child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const skillSource = join(__dirname, '..', 'skill', 'SKILL.md');
-const referenceDirSource = join(__dirname, '..', 'skill', 'reference');
-
-if (!existsSync(skillSource)) {
-  process.exit(0);
-}
-
-// ── Site metadata (generated at build time by scripts/build.js) ──
-// Falls back to safe defaults so a source checkout without a build still runs.
-const siteMeta = (() => {
-  const defaults = {
-    siteId: '4px',
-    env: 'prod',
-    baseUrl: 'https://b.4px.com',
-    akUrl: 'https://b.4px.com/site/ak-manage',
-    packageName: 'cbs-merchant-cli',
-    binName: 'mc',
-  };
-  try {
-    const metaPath = join(__dirname, '..', 'site-meta.json');
-    const parsed = JSON.parse(readFileSync(metaPath, 'utf-8'));
-    return { ...defaults, ...parsed };
-  } catch {
-    return defaults;
-  }
-})();
-
-// Skill install dir name derived from package name (e.g. cbs-4px-merchant-cli).
-const skillDirName = siteMeta.packageName.replace(/^@[^/]+\//, '');
-
-// Site-specific CLI command name (e.g. fmc / cmc); falls back to mc.
-const bin = siteMeta.binName || 'mc';
-
-const home = homedir();
+const ROOT = join(__dirname, '..');
+const ENTRY = join(ROOT, 'dist', 'index.js');
 
-const targets = [
-  { root: join(home, '.qoder'), label: 'Qoder' },
-  { root: join(home, '.claude'), label: 'Claude Code' },
-  { root: join(home, '.cline'), label: 'Cline' },
-  { root: join(home, '.qwen'), label: 'QwenCode' },
-  { root: join(home, '.cursor'), label: 'Cursor' },
-  { root: join(home, '.qoderwork'), label: 'QoderWork' },
-  { root: join(home, '.codex'), label: 'Codex' },
-  { root: join(home, '.kilo'), label: 'Kilo Code' },
-  { root: join(home, '.openclaw'), label: 'OpenCLaw' },
-  { root: join(home, '.config', 'opencode'), label: 'OpenCode' },
-];
-
-const available = targets.filter(({ root }) => existsSync(root));
-
-if (available.length === 0) {
+// Source checkout that has not been built yet — nothing to install.
+if (!existsSync(ENTRY) || !existsSync(join(ROOT, 'skill', 'SKILL.md'))) {
   process.exit(0);
 }
 
-// Write to /dev/tty to bypass npm output suppression
-let ttyFd;
-try {
-  ttyFd = openSync('/dev/tty', 'w');
-} catch {
-  ttyFd = null;
-}
-
-function ttyPrint(msg) {
-  if (ttyFd != null) {
-    writeSync(ttyFd, msg + '\n');
-  } else {
-    // Fallback for environments without /dev/tty (e.g. Claude Code, CI agents)
-    console.log(msg);
-  }
-}
-
-ttyPrint(
-  `\n🚀 Installing BPortal Merchant CLI skill to ${available.length} AI coding tool(s):`,
-);
+const result = spawnSync(process.execPath, [ENTRY, 'skill', 'install'], {
+  stdio: ['ignore', 'ignore', 'inherit'],
+});
 
-for (const { root, label } of available) {
-  try {
-    const targetDir = join(root, 'skills', skillDirName);
-    mkdirSync(targetDir, { recursive: true });
-    copyFileSync(skillSource, join(targetDir, 'SKILL.md'));
-    if (existsSync(referenceDirSource)) {
-      cpSync(referenceDirSource, join(targetDir, 'reference'), {
-        recursive: true,
-      });
-    }
-    // Write version marker for drift detection at CLI runtime
-    const pkgJsonPath = join(__dirname, '..', 'package.json');
-    let skillVersion = 'unknown';
-    try {
-      const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-      if (typeof pkg.version === 'string') skillVersion = pkg.version;
-    } catch { /* fallback to unknown */ }
-    writeFileSync(join(targetDir, '.skill-version'), skillVersion);
-    ttyPrint(`  ✓ ${label} (v${skillVersion})`);
-  } catch {
-    // Silent fail — don't block npm install
-  }
+if (result.status !== 0) {
+  const bin = resolveBinName();
+  process.stderr.write(
+    `\n⚠  skill 自动注册未完成，请手动执行: ${bin} skill install\n\n`,
+  );
 }
 
-// ── API Key detection ──
-const configPath = join(home, '.bportal', 'config.json');
-let hasApiKey = false;
+process.exit(0);
 
-if (process.env.BPORTAL_API_KEY) {
-  hasApiKey = true;
-}
-if (!hasApiKey && existsSync(configPath)) {
+/** Site-specific command name (fmc / cmc); falls back to the base name. */
+function resolveBinName() {
   try {
-    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
-    if (typeof cfg.apiKey === 'string' && cfg.apiKey.length > 0) hasApiKey = true;
+    // site-meta.json is written by scripts/build.js; absent in an unbuilt checkout.
+    const meta = JSON.parse(readFileSync(join(ROOT, 'site-meta.json'), 'utf-8'));
+    return meta.binName || 'mc';
   } catch {
-    /* ignore */
+    return 'mc';
   }
 }
-
-if (hasApiKey) {
-  ttyPrint('');
-  ttyPrint('🎯 Try these commands:');
-  ttyPrint('');
-  ttyPrint(`   ${bin} track get <orderNo>        查询物流轨迹`);
-  ttyPrint(`   ${bin} label get <orderNo>        获取面单 PDF`);
-  ttyPrint(`   ${bin} order get <orderNo>        查看订单详情`);
-  ttyPrint(`   ${bin} order get <orderNo> --output json`);
-  ttyPrint('');
-} else {
-  ttyPrint('');
-  ttyPrint('💡 Set up your API Key to get started:');
-  ttyPrint('');
-  ttyPrint('   1️⃣  Get an API Key:');
-  ttyPrint(`      ${siteMeta.akUrl}`);
-  ttyPrint('');
-  ttyPrint('   2️⃣  Sign in:');
-  ttyPrint(`      ${bin} auth login --api-key SK_xxxxx`);
-  ttyPrint('');
-  ttyPrint('   3️⃣  Then try:');
-  ttyPrint(`      ${bin} track get <orderNo>`);
-  ttyPrint(`      ${bin} order get <orderNo>`);
-  ttyPrint('');
-}
-
-// ── PATH check ──
-try {
-  execSync(`which ${bin}`, { stdio: 'ignore' });
-} catch {
-  ttyPrint(`⚠️  Command "${bin}" not found in PATH.`);
-  ttyPrint('   Your npm global bin directory may not be on PATH.');
-  ttyPrint('   Run `npm config get prefix` and add its `bin/` to your PATH,');
-  ttyPrint('   or reinstall with:');
-  ttyPrint('');
-  ttyPrint(`   npm install -g ${siteMeta.packageName}`);
-  ttyPrint('');
-}
-
-if (ttyFd != null) {
-  closeSync(ttyFd);
-}

package/skill/SKILL.md

@@ -37,7 +37,7 @@ description: >-
 | 地址簿 | [`reference/order.md`](reference/order.md) | 确认参数格式 |
 | 国家查询 | [`reference/order.md`](reference/order.md) | 确认参数格式 |
 | 产品推荐 | [`reference/product.md`](reference/product.md) | 参数多（国家/重量/电池/邮编等），必须确认 |
-| 理赔查询 | [`reference/claim.md`](reference/claim.md) | 参数多（单号/时间/状态/分页），必须确认 |
+| 理赔查询 | [`reference/service.md`](reference/service.md) | 参数多（单号/时间/状态/分页），必须确认 |
 | 异常件管理 | [`reference/problem.md`](reference/problem.md) | 确认子命令和参数格式 |
 | 服务中心 | [`reference/service.md`](reference/service.md) | 确认子命令和参数格式 |
 | 财务管理 | [`reference/finance.md`](reference/finance.md) | 确认子命令和参数格式 |
@@ -61,7 +61,7 @@ description: >-
 | `label` | 面单打印：获取面单 PDF 链接 | [`reference/label.md`](reference/label.md) |
 | `order` | 订单管理：查看订单详情、订单列表、地址簿、目的国搜索 | [`reference/order.md`](reference/order.md) |
 | `product` | 产品推荐：推荐产品、产品列表、产品详情、时效查询、搜索产品 | [`reference/product.md`](reference/product.md) |
-| `claim` | 理赔查询：按单号/时间/状态查询理赔列表 | [`reference/claim.md`](reference/claim.md) |
+| `claim` | 理赔查询：按单号/时间/状态查询理赔列表（挂在 `service` 下，即 `fmc service claim ...`） | [`reference/service.md`](reference/service.md) |
 | `problem` | 异常件管理：问题件列表、AI处理建议、通知件、尾程异常、欠费件、拦截件 | [`reference/problem.md`](reference/problem.md) |
 | `service` | 服务中心：售后工单、查件、投诉、服务单详情、处理记录、理赔详情 | [`reference/service.md`](reference/service.md) |
 | `finance` | 财务管理：账户余额、账单、每日费用、未出账汇总及明细、充值记录（在线及线下）、计费明细 | [`reference/finance.md`](reference/finance.md) |
@@ -86,7 +86,7 @@ description: >-
 用户提到"试算运费/运费计算" → `fmc product recommend`
 用户提到"时效/预估时效" → `fmc product eta`
 用户提到"搜索产品/找产品" → `fmc product search`
-用户提到"理赔/索赔/赔偿/丢件赔付" → `fmc claim list`
+用户提到"理赔/索赔/赔偿/丢件赔付" → `fmc service claim list`
 用户提到"异常件/问题件/异常单/异常订单" → `fmc problem list`
 用户提到"处理建议/异常建议/AI建议" → `fmc problem suggest`
 用户提到"通知件" → `fmc problem notify`
@@ -116,10 +116,10 @@ description: >-
 |-----------|---------|--------|------|
 | "查一下这个单号" | `track get`（默认） | — | 无额外上下文时默认查轨迹；若用户要费用/收件人则走 `order get` |
 | "这个包裹的详情" | `order get` | `track get` | "详情"含收件人/费用等结构化信息 |
-| "我的包裹丢了" | `claim list` | `track get` | 用户意图是理赔而非查轨迹 |
+| "我的包裹丢了" | `service claim list` | `track get` | 用户意图是理赔而非查轨迹 |
 | "寄快递/发货选什么" | `product recommend` | — | 发货前选品，需要国家参数 |
 | "运费多少" | `product recommend` | `order get` | 发货前询价用 product；已发货查费用用 order |
-| "查理赔" | `claim list` | `service claim-detail` | 前者查列表，后者按理赔单号查详情 |
+| "查理赔" | `service claim list` | `service claim detail` | 前者查列表，后者按理赔单号查详情 |
 | "我的订单" | `order list` | `order get` | 前者是列表，后者按单号查详情 |
 | "运费/多少钱" | `product recommend`（发货前询价） | `order get`（已发货查费用） | 发货前用 product recommend 试算；已发货查费用用 order get |
 
@@ -129,10 +129,10 @@ description: >-
 
 ```bash
 # 配置 API Key（持久化到 ~/.bportal/config.json）
-fmc auth login --api-key SK_xxxxx
+fmc auth login --api-key sk-xxxxx
 
 # 或通过环境变量
-export BPORTAL_API_KEY=SK_xxxxx
+export BPORTAL_API_KEY=sk-xxxxx
 ```
 
 获取 API Key: https://b.4px.com/site/ak-manage
@@ -172,7 +172,7 @@ fmc order list --status IN_TRANSIT
 fmc product recommend --country US
 
 # 查询理赔列表（按单号）
-fmc claim list --biz-no FPX12345678
+fmc service claim list --biz-no FPX12345678
 
 # 查询异常件
 fmc problem list
@@ -217,9 +217,8 @@ fmc config set baseUrl https://b.4px.com
 - [`reference/label.md`](reference/label.md) — 面单打印详细参数
 - [`reference/order.md`](reference/order.md) — 订单管理详细参数
 - [`reference/product.md`](reference/product.md) — 产品推荐与查询详细参数
-- [`reference/claim.md`](reference/claim.md) — 理赔查询详细参数
 - [`reference/problem.md`](reference/problem.md) — 异常件管理详细参数
-- [`reference/service.md`](reference/service.md) — 服务中心详细参数
+- [`reference/service.md`](reference/service.md) — 服务中心与理赔查询详细参数
 - [`reference/finance.md`](reference/finance.md) — 财务管理详细参数
 - [`reference/pickup.md`](reference/pickup.md) — 揽收管理详细参数
 - [`reference/notice.md`](reference/notice.md) — 系统公告详细参数

package/skill/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "cbs-4px-merchant-cli",
+  "version": "0.0.4",
+  "description": "BPortal Merchant CLI (fmc) skill — BPortal",
+  "files": [
+    "SKILL.md",
+    "package.json",
+    "reference/auth.md",
+    "reference/config.md",
+    "reference/customs.md",
+    "reference/finance.md",
+    "reference/index.md",
+    "reference/label.md",
+    "reference/notice.md",
+    "reference/order.md",
+    "reference/pickup.md",
+    "reference/problem.md",
+    "reference/product.md",
+    "reference/service.md",
+    "reference/track.md",
+    "reference/update.md"
+  ],
+  "installSource": "cbs-4px-merchant-cli",
+  "installMethod": "cli"
+}

package/skill/reference/auth.md

@@ -21,14 +21,18 @@
 
 | Flag | Type | Required | Description |
 | --- | --- | --- | --- |
-| `--api-key <key>` | string | yes | API Key（格式：SK_xxx） |
+| `--api-key <key>` | string | yes | API Key（控制台生成的原串，常见前缀 `SK_` 或 `sk-`） |
 
 获取 API Key: https://b.4px.com/site/ak-manage
 
+> **不要校验或改写用户给的 Key。** 后端同时接受 `SK_xxx` 与 `sk-xxx` 两种前缀，CLI 也不做格式校验。
+> 原样传入即可 —— 因为“看起来格式不对”而拒用、或自行转成大写，只会把一个有效的 Key 弄坏。
+> 有效性以调用结果为准：返回 401 才是无效。
+
 #### Examples
 
 ```bash
-fmc auth login --api-key SK_xxxxx
+fmc auth login --api-key sk-xxxxx
 ```
 
 ### `fmc auth status`
@@ -57,6 +61,6 @@ fmc auth status --output json
 Authentication Status:
   Status:   ✔ 已认证
   Source:   ~/.bportal/config.json
-  Key:      SK_1***3456
+  Key:      sk-1***3456
   Base URL: https://b.4px.com
 ```

package/skill/reference/config.md

@@ -29,7 +29,7 @@
 
 ```bash
 fmc config set baseUrl https://b.4px.com
-fmc config set apiKey SK_xxxxx
+fmc config set apiKey sk-xxxxx
 ```
 
 ### `fmc config list`

package/skill/reference/index.md

@@ -63,6 +63,9 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `fmc customs hscode search` | 查询海关编码 | [customs.md](customs.md) |
 | `fmc customs registration info` | 查询客户备案信息 | [customs.md](customs.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) |
+| `fmc skill uninstall` | 移除本 CLI 安装的 skill | [update.md](update.md) |
 
 ## By group
 
@@ -81,6 +84,7 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `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) |
 | `update` | (no subcommand) | [update.md](update.md) |
+| `skill` | `install`, `status`, `uninstall` | [update.md](update.md) |
 
 ## Global flags
 
@@ -95,7 +99,9 @@ Command **details** are in sibling `<group>.md` files in this directory.
 ## Notes
 
 - `track get` 命令无需认证即可使用。
-- 其余大部分命令需要先配置 API Key：`fmc auth login --api-key <SK_xxx>`。
+- 其余大部分命令需要先配置 API Key：`fmc auth login --api-key <key>`。Key 是控制台生成的原串（常见前缀 `SK_` 或 `sk-`），原样传入，不要校验或改写。
 - 新增的 `problem`、`service`、`finance`、`pickup`、`notice`、`customs` 模块均需要 API Key 认证。`order` 模块下的 `address-book`、`country` 子命令也需要认证。
 - 配置文件位于 `~/.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`。

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`。