@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/verticals/mercadolibre/manifest.json

@@ -0,0 +1,538 @@
+{
+  "id": "mercadolibre",
+  "version": "0.1.2",
+  "title": "美客多（MercadoLibre）业务线",
+  "_note": "P2a 落位：flows/prompts/暂停开关/日志/会话文件已命名空间化；角色/preset/技能仍是旧名（legacyNaming，P2b/P5 在有重启窗口时改名）；能力与计费单位仍在 base（随重装窗口改 SKU id）；适配器仍在 scripts/integrations（P4 端口化时搬）。",
+  "_versionNote": "0.1.1（2026-10-06）：`requires.argent` 由 `>=0.2 <0.3` 抬到 `>=0.3 <0.4`（平台现役 VERSION=0.3.0）—— 修前「Argent 能力 → 概览」把这唯一的业务线标成 `⚠️ 版本不满足`，而它实际能跑（口径与事实相反）。同批 `version` +1（P0-5，见 docs/Argent-工作台口径审计-2026-10-06.md）。｜0.1.2（2026-10-09）：**平台抬到 0.4.0** ⇒ `requires.argent` 同步抬到 `>=0.4 <0.5`（不改则会重演 P0-5：兼容区间把现役平台挡在门外）。判据已固化为门禁 `node scripts/check-version-consistency.mjs`（**平台版本必须落在每条业务线声明的兼容区间内**），不再靠人记得复核。⚠️ `verifiedOn.argent` **刻意维持 `0.3.0`**：该字段记的是\"**真装真跑过**\"，本批只抬版本号、内核无行为改动，未在 0.4.0 上跑过生产 ⇒ 落地后补登，⛔ 不预填。",
+  "requires": {
+    "argent": ">=0.4 <0.5",
+    "dsh": ">=0.1.5 <0.2"
+  },
+  "verifiedOn": {
+    "argent": [
+      "0.3.0"
+    ],
+    "dsh": [
+      "0.1.5-rc.1",
+      "0.1.7-rc.2"
+    ]
+  },
+  "ports": {
+    "source": "feishu-base",
+    "transport": "feishu",
+    "notify": "feishu-card",
+    "actor": "portal",
+    "identity": "env"
+  },
+  "_capabilitiesNote": "2026-10-09（变现分层落地）：`daily-report` 由 `enterprise` 降为 **`pro`** —— 判据 = 「**只读 ⇒ Pro / 写操作 ⇒ 企业版**」：日报只走官方 API 只读查询 + 生成推送，⛔ 不写客户任何系统、⛔ 不动浏览器；`full`（箱唛等写操作）与 `invoice`（门户写操作）**保持 `enterprise`**。唯一真源仍是 `scripts/flow-requirements.json#capabilities.<id>.minPlan`（本文件是业务线侧的同批声明，`node scripts/vertical-lint.mjs` 校验两处不得漂移）。",
+  "capabilities": [
+    {
+      "id": "daily-report",
+      "minPlan": "pro"
+    },
+    {
+      "id": "full",
+      "minPlan": "enterprise"
+    },
+    {
+      "id": "invoice",
+      "minPlan": "enterprise"
+    }
+  ],
+  "roles": [
+    "argent-ml-fulfillment",
+    "argent-ml-invoice-wy",
+    "argent-ml-invoice-xzh",
+    "argent-ml-daily"
+  ],
+  "skills": [
+    "ml-fulfillment-sop",
+    "ml-invoice",
+    "ml-invoice-xzh",
+    "ml-store-daily-report",
+    "ml-config-guide"
+  ],
+  "flows": [
+    "mercadolibre.full",
+    "mercadolibre.wenyao-invoice",
+    "mercadolibre.xzh-invoice",
+    "mercadolibre.daily-report"
+  ],
+  "preflight": "preflight.py",
+  "legacyNaming": [
+    "roles",
+    "skills"
+  ],
+  "_settingsPanelNote": "能力包设置页契约（docs/能力包设置页契约.md）：**一个能力一页**，按 `capabilities` 绑定 —— 装了就出现、没装不出现（判据在 host/仓库脚本，客户端零名单）。面板级档位见各面板的 `minPlan`（缺省由绑定能力的注册表 minPlan 派生，**不新建第二份档位表**）。字段值只读；env 字段在 `ARGENT_ENV_WRITER=1` 时走受控写入器（写前备份 + 写后读回 + 审计 JSONL，只落 ~/.dsh/argent/** 的约定 env 路径），其余字段只复用既有端点（/api/argent-state/config、/api/argent-state/ziniao-key）。",
+  "settingsPanels": [
+    {
+      "id": "mercadolibre.settings",
+      "title": "美客多业务线",
+      "order": 10,
+      "capabilities": [
+        "full",
+        "invoice",
+        "daily-report"
+      ],
+      "hint": "本页字段来自能力包自己的声明（verticals/mercadolibre/manifest.json）；未安装美客多能力包时本页不出现。",
+      "fields": [
+        {
+          "key": "feishuAppId",
+          "label": "飞书应用 App ID",
+          "type": "text",
+          "placeholder": "cli_xxx",
+          "hint": "推送/对话用的自建应用；保存后立刻切换 lark-cli 身份。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "feishuAppId"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "feishuAppId"
+            }
+          }
+        },
+        {
+          "key": "feishuAppSecret",
+          "label": "飞书应用 App Secret",
+          "type": "password",
+          "placeholder": "仅保存在本机",
+          "hint": "留空 = 保持原值（不会清空）。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "feishuAppSecretConfigured"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "feishuAppSecret"
+            }
+          }
+        },
+        {
+          "key": "feishuChatId",
+          "label": "飞书推送群（可选）",
+          "type": "text",
+          "placeholder": "oc_xxx / ou_xxx",
+          "hint": "通用群（非日报专用）：流程通知/告警的兜底落点；日报群另有 mlDailyChatId（在「美客多日报」页）。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "feishuChatId"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "feishuChatId"
+            }
+          }
+        },
+        {
+          "key": "feishuBaseUrl",
+          "label": "飞书表格 URL（Base）",
+          "type": "text",
+          "placeholder": "https://xxx.feishu.cn/base/XXX",
+          "hint": "已有 Base 时填写；留空则由一键体检自动代建。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "feishuBaseUrl"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "feishuBaseUrl"
+            }
+          }
+        },
+        {
+          "key": "ziniaoApiKey",
+          "label": "紫鸟 API Key",
+          "type": "password",
+          "placeholder": "open.ziniao.com 获取（用户应用管理）",
+          "hint": "写入 ziniao-cli 自身配置（--no-keychain），不入 config.json。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "ziniaoApiKeyMasked"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/ziniao-key",
+              "field": "apiKey"
+            }
+          }
+        },
+        {
+          "key": "stores",
+          "label": "店铺映射（紫鸟实时读取）",
+          "type": "text",
+          "hint": "只读：由「一键体检 / 刷新店铺」从紫鸟写入 STORES_JSON 指向的文件。",
+          "bind": {
+            "read": {
+              "from": "json",
+              "pathFromEnv": "STORES_JSON",
+              "mode": "keys"
+            }
+          }
+        }
+      ],
+      "_note": "业务线级面板（**任一已装即显示**）：只放跨能力共用的对外配置面 —— 飞书应用凭据（App ID/Secret/推送群）/ 客户飞书表 URL / 紫鸟 API Key / 店铺映射。各能力**专属**的字段在下面的能力面板里（FULL 货件 / 发票 / 美客多日报）：2026-10-01 迁移，`mlDailyTime` 与 `mlDailyStoreCount` 已移入 mercadolibre.daily-report。2026-10-01 第二层（清理迁移期重复）：这些字段的**唯一入口就是本页** —— skin 通用区（Argent 页「账号与密钥 / 美客多业务线」）里的同名输入框已删除（契约 §14）；`feishuChatId` 原本只在 skin 里有入口，属**漏项**，本次补进本页声明（写入口 /api/argent-state/config 的 CONFIG_KEYS 白名单里本就有它）。"
+    },
+    {
+      "id": "mercadolibre.full",
+      "title": "FULL 货件",
+      "order": 20,
+      "capabilities": [
+        "full"
+      ],
+      "hint": "FULL（美客多货件）专属配置：货件表、通知模式、紫鸟店铺浏览器凭据。env 字段写入 ~/.dsh/argent/verticals/mercadolibre/env/ 下的约定文件（写前备份 + 写后读回 + 审计；写入器默认关闭）。",
+      "fields": [
+        {
+          "key": "fullTableId",
+          "label": "FULL 货件表 ID（Base table）",
+          "type": "text",
+          "env": "FULL_TABLE_ID",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "placeholder": "tbl…",
+          "hint": "FULL 流程认领/回写的飞书表 id；改错 ⇒ 认领不到票。"
+        },
+        {
+          "key": "fullBaseToken",
+          "label": "FULL 表 Base Token",
+          "type": "password",
+          "env": "FULL_BASE_TOKEN",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "hint": "该表的读写身份 token（只保存在本机）。"
+        },
+        {
+          "key": "fullNotifyMode",
+          "label": "FULL 通知模式",
+          "type": "select",
+          "env": "FULL_NOTIFY_MODE",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "hint": "final=只发最终完成卡（默认）｜facts=全静默、只记事实（排障）｜feishu=旧行为（步骤消息+卡片全发）。",
+          "options": [
+            "final",
+            "facts",
+            "feishu"
+          ]
+        },
+        {
+          "key": "fullLarkProfile",
+          "label": "FULL 推送身份（lark-cli profile）",
+          "type": "text",
+          "env": "FULL_LARK_PROFILE",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "hint": "发卡片用哪个 Bot 身份；客户机没有独立 Bot 时填主 Bot 的 profile。"
+        },
+        {
+          "key": "fullDoneChatId",
+          "label": "完成卡群 id",
+          "type": "text",
+          "env": "FULL_DONE_CHAT_ID",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "placeholder": "oc_…"
+        },
+        {
+          "key": "fullDoneProfile",
+          "label": "完成卡推送身份",
+          "type": "text",
+          "env": "FULL_DONE_PROFILE",
+          "envFile": "fulfillment.env",
+          "scope": "vertical"
+        },
+        {
+          "key": "fullInternalChatId",
+          "label": "内部群 id（需人工裁定用）",
+          "type": "text",
+          "env": "FULL_INTERNAL_CHAT_ID",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "placeholder": "oc_…"
+        },
+        {
+          "key": "ziniaoMode",
+          "label": "紫鸟接入模式",
+          "type": "select",
+          "env": "ZINIAO_MODE",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "hint": "bridge=ziniao-cli（默认）｜webdriver=常驻 WebDriver（推荐）｜selenium=官方 Selenium 客户端。",
+          "options": [
+            "bridge",
+            "webdriver",
+            "selenium"
+          ]
+        },
+        {
+          "key": "ziniaoDl",
+          "label": "紫鸟下载目录",
+          "type": "text",
+          "env": "ZINIAO_DL",
+          "envFile": "fulfillment.env",
+          "scope": "vertical",
+          "hint": "标签/箱唛下载落点；留空则用 orchestrator 的缺省目录。"
+        },
+        {
+          "key": "ziniaoWdCompany",
+          "label": "紫鸟企业号（WebDriver）",
+          "type": "text",
+          "env": "ZINIAO_WD_COMPANY",
+          "envFile": "ziniao-webdriver.env",
+          "scope": "vertical",
+          "hint": "紫鸟客户端（常驻 WebDriver）登录凭据 —— FULL 用店铺浏览器取标签/箱唛。"
+        },
+        {
+          "key": "ziniaoWdUsername",
+          "label": "紫鸟登录账号",
+          "type": "text",
+          "env": "ZINIAO_WD_USERNAME",
+          "envFile": "ziniao-webdriver.env",
+          "scope": "vertical"
+        },
+        {
+          "key": "ziniaoWdPassword",
+          "label": "紫鸟登录密码",
+          "type": "password",
+          "env": "ZINIAO_WD_PASSWORD",
+          "envFile": "ziniao-webdriver.env",
+          "scope": "vertical"
+        },
+        {
+          "key": "ziniaoWdPort",
+          "label": "WebDriver 端口",
+          "type": "text",
+          "env": "ZINIAO_WD_PORT",
+          "envFile": "ziniao-webdriver.env",
+          "scope": "vertical",
+          "placeholder": "19515"
+        }
+      ]
+    },
+    {
+      "id": "mercadolibre.invoice",
+      "title": "发票（文鳐 / 鑫中航）",
+      "order": 30,
+      "capabilities": [
+        "invoice"
+      ],
+      "hint": "两条发票流程的门户凭据：文鳐（上海文鳐）走 env 文件，鑫中航走 config.json。门户是生产系统 ⇒ 改动后在客户机上跑一次 dry-run 验证。",
+      "fields": [
+        {
+          "key": "wenyaoUrl",
+          "label": "文鳐门户地址",
+          "type": "text",
+          "env": "WENYAO_URL",
+          "envFile": "wenyao.env",
+          "scope": "vertical",
+          "placeholder": "https://my.ffl-tech.com"
+        },
+        {
+          "key": "wenyaoPhone",
+          "label": "文鳐门户账号（手机号）",
+          "type": "text",
+          "env": "WENYAO_PHONE",
+          "envFile": "wenyao.env",
+          "scope": "vertical"
+        },
+        {
+          "key": "wenyaoPassword",
+          "label": "文鳐门户密码",
+          "type": "password",
+          "env": "WENYAO_PASSWORD",
+          "envFile": "wenyao.env",
+          "scope": "vertical"
+        },
+        {
+          "key": "xhInvoiceUser",
+          "label": "鑫中航门户账号",
+          "type": "text",
+          "hint": "写生产系统用；改动需在客户机验证。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "xhInvoiceUser"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "xhInvoiceUser"
+            }
+          }
+        },
+        {
+          "key": "xhInvoicePass",
+          "label": "鑫中航门户密码",
+          "type": "password",
+          "hint": "留空 = 保持原值（不会清空）。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "xhInvoicePass"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "xhInvoicePass"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "id": "mercadolibre.daily-report",
+      "title": "美客多日报",
+      "order": 40,
+      "capabilities": [
+        "daily-report"
+      ],
+      "hint": "美客多日报（官方 API 采集 → 飞书群卡片）：ML OAuth 应用凭据 + 推送参数。推送时间/TopN/补货参数是「单值调参 + 有默认 + 改完能当场验证」⇒ 也可以在会话里让角色改（角色会说清影响）。",
+      "fields": [
+        {
+          "key": "mlAppId",
+          "label": "ML 应用 App ID",
+          "type": "text",
+          "env": "ML_APP_ID",
+          "envFile": "daily-report.env",
+          "scope": "vertical",
+          "hint": "美客多开发者后台的应用 id（OAuth 授权用）。"
+        },
+        {
+          "key": "mlAppSecret",
+          "label": "ML 应用 Secret",
+          "type": "password",
+          "env": "ML_APP_SECRET",
+          "envFile": "daily-report.env",
+          "scope": "vertical",
+          "hint": "只保存在本机；留空 = 保持原值。"
+        },
+        {
+          "key": "mlDailyChatId",
+          "label": "日报推送群 id",
+          "type": "text",
+          "placeholder": "oc_…",
+          "hint": "形如 oc_…；留空则回落到 daily-report.env 的 ML_DAILY_CHAT_ID / 内置默认。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlDailyChatId"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "mlDailyChatId"
+            }
+          }
+        },
+        {
+          "key": "mlDailyTime",
+          "label": "日报推送时间（站点本地时间）",
+          "type": "text",
+          "placeholder": "08:00",
+          "hint": "按各店站点本地时间计算；错过或失败会在 +5 小时窗口内逐小时补试（幂等防重）。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlDailyTime"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "mlDailyTime"
+            }
+          }
+        },
+        {
+          "key": "mlDailyTopN",
+          "label": "畅销榜条数（1–20）",
+          "type": "text",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlDailyTopN"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "mlDailyTopN"
+            }
+          }
+        },
+        {
+          "key": "mlRestockLeadDays",
+          "label": "补货预警提前天数（0–90）",
+          "type": "text",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlRestockLeadDays"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "mlRestockLeadDays"
+            }
+          }
+        },
+        {
+          "key": "mlRestockBufferDays",
+          "label": "补货缓冲天数（0–90）",
+          "type": "text",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlRestockBufferDays"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "mlRestockBufferDays"
+            }
+          }
+        },
+        {
+          "key": "mlDailyAlertChatId",
+          "label": "告警落点群 id",
+          "type": "text",
+          "placeholder": "oc_…",
+          "hint": "流程失败/需人工裁定/待放行汇总的卡片发到哪个群；改错 ⇒ 你收不到需要确认的提醒。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlDailyAlertChatId"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "mlDailyAlertChatId"
+            }
+          }
+        },
+        {
+          "key": "mlDailyAlertProfile",
+          "label": "告警推送身份",
+          "type": "text",
+          "hint": "须在该群里；内部群实测 ml-daily 不在群内 ⇒ 用主 Bot。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlDailyAlertProfile"
+            },
+            "write": {
+              "endpoint": "/api/argent-state/config",
+              "field": "mlDailyAlertProfile"
+            }
+          }
+        },
+        {
+          "key": "mlDailyStoreCount",
+          "label": "已授权店铺（ML OAuth）",
+          "type": "text",
+          "hint": "只读：0 表示还没逐店授权 —— 运行 node ml-oauth-setup.mjs（或 init-ml.sh --daily-report）。",
+          "bind": {
+            "read": {
+              "from": "config",
+              "key": "mlDailyStoreCount"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

package/engine/verticals/mercadolibre/migrate-machine-state.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * migrate-machine-state —— 美客多线落位的**机器状态迁移**（P2a，2026-09-29）
+ *
+ * 位置说明：这是**该业务线专属**的运维工具（提到该线的 env 与开关名）⇒ 放在业务线目录内，
+ * 引擎目录（scripts/）不得出现业务词（门禁 vertical-lint 的「引擎不掺业务」）。
+ *
+ * 代码侧（flows/prompts 落位 + 命名空间化）在仓库里；机器侧还有三样东西要跟着搬，
+ * 否则会出现"注册表改了、机器上的旧文件还在"的静默故障：
+ *
+ *   ① **env 文件**：`~/.dsh/argent/fulfillment.env` → `verticals/mercadolibre/env/`。
+ *      仓库里还有 ~10 个脚本按旧平铺路径 source 它 ⇒ **旧路径留软链 shim**（不 churn 生产脚本），
+ *      shim 清单进"退休待办"。
+ *   ② **暂停开关**：`PAUSE_POLL` 等 → `verticals/mercadolibre/PAUSE.<flow>`。
+ *      ⚠️ 顺序要紧：**先建新开关再改注册表**，否则"改注册表那一刻流程被静默解停"
+ *      （本机流程当前全部暂停，绝不能因为迁移而跑起来）。flow-trigger 迁移期两条都查。
+ *   ③ **会话复用文件**：`flow-dispatch-<flow>.json` → `verticals/mercadolibre/`（角色会话不中断）。
+ *
+ * 默认 **dry-run**（只打印计划）；`--apply` 才落盘。幂等：可反复跑。
+ *
+ * 用法：
+ *   node verticals/mercadolibre/migrate-machine-state.mjs            # 看计划
+ *   node verticals/mercadolibre/migrate-machine-state.mjs --apply    # 执行
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, renameSync, symlinkSync, unlinkSync, readlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
+import { loadRegistryDoc } from '../../scripts/lib/registry.mjs'   // 引擎侧加载器（唯一真源）
+
+const APPLY = process.argv.includes('--apply')
+const argOf = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] ?? d : d }
+const DATA = argOf('--data-dir', process.env.ARGENT_DATA_DIR || join(homedir(), '.dsh', 'argent'))
+const VERT = 'mercadolibre'
+const VDIR = join(DATA, 'verticals', VERT)
+const envDir = join(VDIR, 'env')
+const logDir = join(VDIR, 'logs')
+
+// 属于美客多线的 env（按内容判定：飞书表/ML API/文鳐门户/紫鸟；`whyshu.env` 是平台级，不动）
+const ENV_FILES = ['fulfillment.env', 'daily-report.env', 'wenyao.env', 'ziniao-webdriver.env']
+
+const plan = []
+const todos = []
+const note = (kind, msg) => plan.push({ kind, msg })
+
+console.log(`\n【美客多线机器状态迁移】数据目录：${DATA}｜模式：${APPLY ? 'APPLY（落盘）' : 'dry-run'}\n`)
+
+// ── 0. 目录 ─────────────────────────────────────────────────────
+for (const d of [envDir, logDir]) {
+  if (!existsSync(d)) {
+    note('mkdir', d.replace(DATA, '~/.dsh/argent'))
+    if (APPLY) mkdirSync(d, { recursive: true })
+  }
+}
+
+// ── 1. env 文件：搬到规范位置 + 旧路径留软链 ────────────────────
+for (const name of ENV_FILES) {
+  const legacy = join(DATA, name)
+  const target = join(envDir, name)
+  const rel = `verticals/${VERT}/env/${name}`
+  if (existsSync(target)) {
+    if (!existsSync(legacy)) note('ok', `${name}: 已在规范位置（${rel}）`)
+    else {
+      let isLink = false
+      try { isLink = readlinkSync(legacy) === target } catch { isLink = false }
+      if (isLink) note('ok', `${name}: 规范位置 + 旧路径软链 shim（退休待办）`)
+      else { note('warn', `${name}: 两处都有实体文件 ⇒ 人工确认哪份为准（**不动**）`); todos.push(`${name}: 两处重复，人工去重`) }
+    }
+    continue
+  }
+  if (!existsSync(legacy)) { note('skip', `${name}: 不存在（该线可能不用它）`); continue }
+  note('move+symlink', `${name} → ${rel}（旧路径留软链，退休待办）`)
+  todos.push(`退休 shim：~/.dsh/argent/${name}（脚本改读规范路径后删）`)
+  if (APPLY) {
+    renameSync(legacy, target)
+    symlinkSync(target, legacy)
+  }
+}
+
+// ── 2. 暂停开关：先建新的（绝不能因为迁移把流程解停）────────────
+let doc
+try {
+  doc = loadRegistryDoc()
+} catch (e) {
+  console.error(`✗ 读注册表失败：${e.message}`)
+  process.exit(2)
+}
+const mlFlows = Object.entries(doc.flows || {}).filter(([, f]) => (f.trigger || {}).pauseSwitch?.startsWith?.(`verticals/${VERT}/`))
+console.log(`  注册表里属于该线的流程：${mlFlows.length} 条`)
+for (const [fid, f] of mlFlows) {
+  const t = f.trigger || {}
+  const newRel = String(t.pauseSwitch || '')
+  const oldRel = String(t.pauseSwitchLegacy || '')
+  if (!newRel) continue
+  const newPath = join(DATA, newRel)
+  const oldPath = oldRel ? join(DATA, oldRel) : ''
+  const local = fid.split('.').pop()
+  if (existsSync(newPath)) { note('ok', `暂停开关已在规范位置：${newRel}`); continue }
+  if (oldPath && existsSync(oldPath)) {
+    note('pause', `新建 ${newRel}（镜像旧开关 ${oldRel}）`)
+    todos.push(`退休旧开关：~/.dsh/argent/${oldRel}（确认新开关生效后删）`)
+    if (APPLY) {
+      mkdirSync(join(newPath, '..'), { recursive: true })
+      copyFileSync(oldPath, newPath)
+    }
+  } else {
+    note('pause', `⚠️ ${fid}: 新旧开关都不存在 ⇒ 该流程**当前是未暂停状态**（本机应为全暂停，请确认）`)
+    todos.push(`${fid}: 确认是否应处于暂停（本机约定全暂停）`)
+  }
+}
+// 流程看门狗（全局开关）保持原样
+if (existsSync(join(DATA, 'PAUSE_FLOW_WATCH'))) note('ok', 'PAUSE_FLOW_WATCH（流程看门狗，全局）保持原样')
+
+// ── 3. 会话复用文件：搬进业务线（角色会话不中断）────────────────
+for (const [fid] of mlFlows) {
+  const local = fid.split('.').pop()
+  const legacy = join(DATA, `flow-dispatch-${local}.json`)
+  const target = join(VDIR, `flow-dispatch-${local}.json`)
+  if (existsSync(target)) { note('ok', `会话文件已就位：verticals/${VERT}/${basename(target)}`); continue }
+  if (!existsSync(legacy)) { note('skip', `flow-dispatch-${local}.json: 不存在（该线还没唤醒过）`); continue }
+  note('move', `flow-dispatch-${local}.json → verticals/${VERT}/（保留角色会话）`)
+  if (APPLY) renameSync(legacy, target)
+}
+
+// ── 4. 汇总 ─────────────────────────────────────────────────────
+console.log('\n计划：')
+for (const p of plan) console.log(`  [${p.kind}] ${p.msg}`)
+if (todos.length) {
+  console.log('\n⏳ 退休待办（迁移期允许存在，改完调用点后清理）：')
+  for (const t of todos) console.log(`  · ${t}`)
+}
+if (!APPLY) console.log('\n（dry-run：未落盘；确认无误后加 --apply）')
+else {
+  console.log('\n✅ 已落盘。建议验证：')
+  console.log('  python3 scripts/flow_registry.py --check')
+  console.log('  node scripts/vertical-lint.mjs')
+  console.log('  python3 scripts/flow_config.py --list          # 路径应全部指向 verticals/mercadolibre/')
+  console.log('  bash scripts/flow-trigger.sh --flow full --dry-run   # 应报"已暂停"')
+}