@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/customer-preflight.py

@@ -0,0 +1,892 @@
+#!/usr/bin/env python3
+"""客户机上线核对（**只读自检**）—— 三流程（FULL / 鑫中航 / 上海文鳐）逐项判 PASS/WARN/FAIL。
+
+为什么要有它：客户机与开发机是两台机器，差异恰恰都在"配置/身份/触发"这些不能靠代码门禁覆盖的面上
+（2026-09-17 本机核对已经抓到两类真问题：插件侧 Python 解释器变量名与脚本口径不一致、
+流程源把"空的放行开关"当成已提供 ⇒ 分诊误报 83 张可派发）。逐条人工核对既慢又容易漏，
+故把**能自动判定的部分**固化成这个脚本；判定不了的部分（运营口径、门户步骤）留在
+`docs/客户机部署与上线.md §4.3` 的人工确认清单里。
+
+红线：
+  · 本脚本**只读**：不写业务表、不建会话、不认领票据、不改配置。probe 落盘只落临时目录，
+    台账/案例目录一律不碰（probe 用 --out-dir 指到 tmp，claim 加 --dry-run）。
+  · 默认跑在线探测（读表）——读的是客户生产表，**只读**；`--offline` 可完全离线（测试/无网）。
+
+用法：
+  python3 scripts/customer-preflight.py                 # 全量（环境+凭据+数据面+触发面）
+  python3 scripts/customer-preflight.py --offline        # 跳过读表探测
+  python3 scripts/customer-preflight.py --full           # 追加重量级门禁（preset schema + 启动冒烟）
+  python3 scripts/customer-preflight.py --json           # 机器可读
+  python3 scripts/customer-preflight.py --flow full      # 只看/只测某个流程
+退出码：0 = 无 FAIL；1 = 有 FAIL；2 = 脚本自身出错（参数/环境）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import hashlib
+import importlib.util
+import json
+import os
+import pathlib
+import re
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+
+try:
+    from flow_registry import consumer_doc as _registry_doc      # P2a：base + 业务线合并（唯一真源）
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else (HERE / "flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+
+HERE = pathlib.Path(__file__).resolve().parent
+DEFAULT_REPO = HERE.parent
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链，与 JS 内核同语义）；
+# 客户机自检也必须用同一份实现，否则"自检通过"不代表直跑路径不劈叉。
+sys.path.insert(0, str(HERE / "lib"))
+from argent_datadir import resolve_data_dir  # noqa: E402
+FLOWS_DEFAULT = ["wenyao-invoice", "full", "xzh-invoice"]
+# 触发/投递链路上**必须**存在的脚本：缺一个就等于"触发器静默不干活"
+CORE_SCRIPTS = [
+    "flow_config.py", "flow_source.py", "flow_triage.py", "flow_claim.py",
+    "flow_ledger.py", "flow_failure.py", "flow_case.py", "ml_schema_check.py",
+    "flow-trigger.sh", "flow-trigger-wake.mjs", "flow-requirements.json",
+    # 数据目录判据（2026-10-02）：flow-trigger.sh / dev-window.sh / 常驻巡检脚本**直接调用**
+    # 这个 CLI 包装取数据目录（判据本体在 scripts/lib/argent_datadir.py）⇒ 缺了它触发器会
+    # 响亮停住（fail-closed）。缺文件必须记 fail，不能只算"孤儿文件"warn。
+    "argent-datadir.py", "argent_datadir.py",
+]
+SKIP_DIRS = {"__pycache__", "attic", "tests", "patches", "launchd", "flow-prompts"}
+LOG_MARKERS = {
+    "argent-core": "[argent-core]",
+    "argent-gateway": "[argent-gateway]",
+    "argent-ml": "[argent-ml]",
+    "argent-flow": "[argent-flow]",
+}
+
+
+class Checks:
+    """收集检查结果。level ∈ ok/warn/fail/info。"""
+
+    def __init__(self) -> None:
+        self.items: list[dict] = []
+
+    def add(self, cid: str, group: str, level: str, title: str, detail: str = "",
+            fix: str = "", owner: str = "") -> None:
+        self.items.append({"id": cid, "group": group, "level": level, "title": title,
+                           "detail": detail, "fix": fix, "owner": owner})
+
+    def counts(self) -> dict:
+        out = {"ok": 0, "warn": 0, "fail": 0, "info": 0}
+        for it in self.items:
+            out[it["level"]] = out.get(it["level"], 0) + 1
+        return out
+
+
+def run(cmd: list[str], timeout: int = 60, env: dict | None = None) -> tuple[int, str, str]:
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout,
+                           env={**os.environ, **(env or {})})
+        return p.returncode, (p.stdout or ""), (p.stderr or "")
+    except FileNotFoundError:
+        return 127, "", f"命令不存在: {cmd[0]}"
+    except subprocess.TimeoutExpired:
+        return 124, "", f"超时（{timeout}s）: {' '.join(cmd[:3])}"
+    except Exception as e:                                    # noqa: BLE001
+        return 125, "", f"执行失败: {e}"
+
+
+def sha(path: pathlib.Path) -> str:
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except Exception:                                          # noqa: BLE001
+        return ""
+
+
+def load_json(path: pathlib.Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:                                          # noqa: BLE001
+        return None
+
+
+def ver_tuple(v: str) -> tuple:
+    nums = re.findall(r"\d+", v or "")
+    return tuple(int(x) for x in nums[:3]) or (0,)
+
+
+# ── 环境与挂载 ────────────────────────────────────────────────────────────────
+
+def variant_gate_level(variant: str, active_mode: str) -> str:
+    """FULL 源变体的门禁级别：**当前口径**才算硬门禁，备胎变体只告警。
+
+    2026-09-28 客户机实测：正式口径 lip 可读、legacy（另一张老表）不可读，而流程根本
+    不会读 legacy。若把备胎也判 FAIL，预检就**永远挂着 1 项红** ⇒ 反而训练人忽略真红。
+    """
+    return "fail" if variant == active_mode else "warn"
+
+
+def check_env(chk: Checks, repo: pathlib.Path, data_dir: pathlib.Path, profile: str) -> None:
+    G = "环境"
+    node = shutil.which("node")
+    if not node:
+        chk.add("env.node", G, "fail", "node 缺失", "PATH 里没有 node",
+                "安装 node ≥22.6（客户机用 ~/node/bin/node），并把 PATH 写进 LaunchAgent")
+    else:
+        code, out, _ = run([node, "-v"])
+        ver = out.strip()
+        if code == 0 and ver_tuple(ver) >= (22, 6):
+            chk.add("env.node", G, "ok", f"node {ver}", "满足 dsh ≥22.6 要求")
+        else:
+            chk.add("env.node", G, "fail", f"node {ver or '未知'}", "版本低于 22.6 ⇒ dsh 启动会崩",
+                    "升级 node（客户机历史上 node 20 是启动崩溃根因）")
+
+    dsh = shutil.which("dsh")
+    if not dsh:
+        chk.add("env.dsh", G, "fail", "dsh 缺失", "PATH 里没有 dsh", "按 docs/客户机部署与上线.md 用本地目录方式安装")
+    else:
+        code, out, err = run([dsh, "--version"])
+        ver = (out or err).strip().splitlines()[0] if (out or err).strip() else ""
+        m = re.search(r"\d+\.\d+\.\d+(?:-[0-9A-Za-z.\-]+)?", ver)
+        ver = m.group(0) if m else ver
+        locks = sorted((repo / "dsh-version-lock").glob("*.json")) if (repo / "dsh-version-lock").is_dir() else []
+        known = {p.stem for p in locks}
+        if known and ver in known:
+            chk.add("env.dsh", G, "ok", f"dsh {ver}", f"与版本快照 {ver}.json 一致（快照数 {len(known)}）")
+        else:
+            chk.add("env.dsh", G, "warn", f"dsh {ver or '未知'}",
+                    f"未命中本仓库快照（{', '.join(sorted(known)) or '无快照文件'}）",
+                    "确认升级/回滚是否走 scripts/dsh-upgrade.mjs；不要 npm install -g")
+
+    code, out, _ = run([sys.executable, "-V"])
+    py = (out or "").strip()
+    if code == 0 and ver_tuple(py) >= (3, 10):
+        chk.add("env.python", G, "ok", f"自检解释器 {py}", sys.executable)
+    else:
+        chk.add("env.python", G, "warn", f"自检解释器 {py or '未知'}", "流程脚本需要 ≥3.10",
+                "客户机用 ~/.local/bin/python3.11 跑脚本与触发器（见下一条 ARGENT_PY 判定）")
+
+    # 触发器用的解释器：**两侧口径都要看**（脚本侧读 ARGENT_PY；插件侧按候选顺序自探测）
+    # 解释器默认值（2026-09-22 重启事故）：/tmp 易失 ⇒ 首选持久 venv，其次 PATH 上的 python3。
+    _cands = [os.environ.get("ARGENT_PY"), os.environ.get("ARGENT_PYTHON"),
+              os.path.expanduser("~/.dsh/argent/venv/bin/python3"),
+              shutil.which("python3") or ""]
+    eff = next((c for c in _cands if c and os.path.exists(c)), _cands[-1] or "python3")
+    plugin_pick = next((c for c in (os.environ.get("ARGENT_PYTHON"), os.environ.get("ARGENT_PY"),
+                                    str(pathlib.Path.home() / ".local" / "bin" / "python3.11"),
+                                    os.path.expanduser("~/.dsh/argent/venv/bin/python3"))
+                        if c and pathlib.Path(c).exists()), "python3")
+    if pathlib.Path(eff).exists():
+        chk.add("env.argent_py", G, "ok", f"触发脚本解释器 {eff}",
+                f"插件侧（失败回路）会选：{plugin_pick}")
+    else:
+        chk.add("env.argent_py", G, "fail", f"触发脚本解释器不存在：{eff}",
+                f"插件侧当前会选 {plugin_pick}（持久 venv 优先；/tmp 路径重启即失效，已弃用）",
+                "在 LaunchAgent 的 EnvironmentVariables 里设 ARGENT_PY=~/.local/bin/python3.11"
+                "（插件同时认 ARGENT_PYTHON，两者设一个即可）")
+    if plugin_pick == "python3":
+        chk.add("env.argent_py_plugin", G, "warn", "插件侧未命中任何候选解释器（回退 PATH 的 python3）",
+                "PATH 里若没有 python3，失败回路会静默失效",
+                "设 ARGENT_PYTHON 或 ARGENT_PY 指向 ~/.local/bin/python3.11")
+
+    # 仓库状态：客户机只允许 git pull，不允许本地改动（KB-032：未提交改动阻塞 pull）
+    if (repo / ".git").exists():
+        code, out, _ = run(["git", "-C", str(repo), "rev-parse", "--short", "HEAD"])
+        head = out.strip() if code == 0 else "?"
+        code, out, _ = run(["git", "-C", str(repo), "status", "--porcelain"])
+        dirty = [l for l in out.splitlines() if l.strip()]
+        if dirty:
+            chk.add("env.repo", G, "warn", f"仓库有 {len(dirty)} 处未提交改动（HEAD {head}）",
+                    "；".join(dirty[:3]),
+                    "客户机禁止直接改仓库：改动应回到开发机 commit+push，再 git pull")
+        else:
+            chk.add("env.repo", G, "ok", f"仓库干净（HEAD {head}）", str(repo))
+    else:
+        chk.add("env.repo", G, "warn", "未找到仓库（或不是 git 仓库）", str(repo),
+                "触发器/门禁都假定仓库在 ~/Code/argent-dsh")
+
+    # 技能 frontmatter 门禁（两个坑：未闭合、中文 name ⇒ 技能静默不加载）
+    if (repo / "scripts" / "fix-skill-frontmatter.py").exists():
+        code, out, err = run([sys.executable, str(repo / "scripts" / "fix-skill-frontmatter.py"), "--check"],
+                             timeout=120)
+        if code == 0:
+            chk.add("env.skills", G, "ok", "技能 frontmatter 门禁通过", (out or err).strip().splitlines()[-1:] and
+                    (out or err).strip().splitlines()[-1] or "")
+        else:
+            chk.add("env.skills", G, "fail", "技能 frontmatter 不合法（技能会静默不加载）",
+                    " | ".join((out or err).strip().splitlines()[:3]),
+                    "跑 python3 scripts/fix-skill-frontmatter.py --write")
+
+    # 角色 → preset 映射（三方一致 + 被引用 preset 必须存在）
+    if (repo / "scripts" / "check-role-mapping.mjs").exists() and shutil.which("node"):
+        code, out, err = run(["node", str(repo / "scripts" / "check-role-mapping.mjs")], timeout=180)
+        last = [l for l in (out or err).strip().splitlines() if l.strip()][-1:]
+        if code == 0:
+            chk.add("env.roles", G, "ok", "角色映射门禁通过", last[0] if last else "")
+        else:
+            chk.add("env.roles", G, "fail", "角色映射不一致（角色会唤起错的/不存在的 preset）",
+                    " | ".join((out or err).strip().splitlines()[:3]),
+                    "对齐 gateway PRESET_BY_ROLE / roles.json / presets 目录，再跑 node scripts/check-role-mapping.mjs --write")
+
+    # 插件副本一致性（本仓库 vs 安装克隆 vs profile 快照）
+    install_home = pathlib.Path(os.environ.get("ARGENT_DISH_HOME") or (pathlib.Path.home() / ".argent-dsh"))
+    prof_dir = pathlib.Path.home() / ".dsh" / "profiles" / profile / "node_modules"
+    drift, missing, not_installed = [], [], []
+    for pdir in sorted((repo / "plugins").glob("*/")):
+        name = pdir.name
+        for dest_root, label in ((install_home / "plugins" / name, "安装克隆"), (prof_dir / name, "profile")):
+            if not dest_root.is_dir():
+                not_installed.append(f"{name}@{label}")
+                continue                     # 该目的地没装这个插件（如 argent-flow 只装进 profile）
+            for rel in ("src/index.js", "dist/client.js"):
+                src = pdir / rel
+                if not src.exists():
+                    continue
+                dest = dest_root / rel
+                if not dest.exists():
+                    missing.append(f"{name}/{rel}@{label}")
+                elif sha(dest) != sha(src):
+                    drift.append(f"{name}/{rel}@{label}")
+    if drift:
+        chk.add("env.plugins", G, "fail", f"{len(drift)} 个插件文件与仓库不一致",
+                "、".join(drift[:5]), "在开发机 commit+push 后，客户机跑 bash scripts/sync-plugins.sh（不重启服务不生效）")
+    elif missing:
+        chk.add("env.plugins", G, "fail", f"插件文件缺失：{'、'.join(missing[:5])}",
+                "所在目录存在但缺文件 ⇒ 多半是同步漏项",
+                "重跑 bash scripts/sync-plugins.sh")
+    else:
+        chk.add("env.plugins", G, "ok", "已安装的插件副本与仓库一致",
+                ("未装到：" + "、".join(not_installed)) if not_installed else "安装克隆 + profile 快照均一致")
+
+    # scripts 副本一致性（插件用的是安装克隆里的 scripts ⇒ 漂移会导致"插件跑旧逻辑"）
+    drift, missing, orphans = [], [], []
+    inst_scripts = install_home / "scripts"
+    if inst_scripts.is_dir():
+        for f in (repo / "scripts").rglob("*"):
+            if not f.is_file() or f.suffix not in (".py", ".mjs", ".sh", ".json"):
+                continue
+            rel = f.relative_to(repo / "scripts")
+            if rel.parts and rel.parts[0] in SKIP_DIRS:
+                continue
+            dest = inst_scripts / rel
+            if not dest.exists():
+                ((missing.append if f.name in CORE_SCRIPTS else orphans.append))(str(rel))
+            elif sha(dest) != sha(f):
+                drift.append(str(rel))
+        for f in inst_scripts.rglob("*"):
+            if f.is_file() and f.suffix in (".py", ".mjs", ".sh", ".json"):
+                rel = f.relative_to(inst_scripts)
+                if rel.parts and rel.parts[0] in SKIP_DIRS:
+                    continue
+                if not (repo / "scripts" / rel).exists():
+                    orphans.append(str(rel))
+        if drift or missing:
+            chk.add("env.scripts", G, "fail", f"安装克隆 scripts 与仓库漂移（{len(drift)} 改动 / {len(missing)} 缺失）",
+                    "、".join((drift + missing)[:6]),
+                    "客户机跑 bash scripts/sync-plugins.sh 或 rsync 仓库 scripts/ 到 ~/.argent-dsh/scripts/")
+        else:
+            chk.add("env.scripts", G, "ok", "安装克隆 scripts 与仓库一致",
+                    f"漂移 0；仓库已删除的残留文件 {len(orphans)} 个（无害）" if orphans else "漂移 0")
+    else:
+        chk.add("env.scripts", G, "fail", f"安装克隆 scripts 目录不存在：{inst_scripts}",
+                "插件默认 ARGENT_DISH_HOME=~/.argent-dsh", "按 docs/客户机部署与上线.md 同步安装克隆")
+
+    # 组合挂载：patch 行 + bundle
+    patch = pathlib.Path.home() / ".dsh" / "profiles" / profile / "cordis.patch.yml"
+    pkg = pathlib.Path.home() / ".dsh" / "profiles" / profile / "package.json"
+    text = patch.read_text(encoding="utf-8") if patch.exists() else ""
+    pj = load_json(pkg) or {}
+    bundles = ((pj.get("dsh") or {}).get("profile") or {}).get("bundles") or []
+    deps = pj.get("dependencies") or {}
+    # 组合目标来自 scripts/plugin-composition.json（**唯一真源**，JS 升级器读同一份）——
+    # 2026-09-28 教训：这里曾硬编码 ["argent-core","argent-gateway","argent-flow"]，
+    # 而升级器当时的目标组合没有 argent-flow ⇒ 预检红、升级器却以为正常（两边知识分叉）。
+    comp = load_json(repo / "scripts" / "plugin-composition.json") or {}
+    need_patch = list(((comp.get("business") or {}).get("patch")) or [])
+    need_bundles = list(((comp.get("business") or {}).get("bundles")) or [])
+    lack = [n for n in need_patch if f"id: {n}" not in text]
+    lack += [f"{n}(bundle)" for n in need_bundles if n not in bundles]
+    if not lack:
+        chk.add("env.mount", G, "ok", "组合挂载项齐备",
+                f"patch 行 {len(need_patch)} 个（{', '.join(need_patch)}）；"
+                f"bundles 含 {', '.join(need_bundles) or '-'}；deps 含 argent-ml={'argent-ml' in deps}")
+    else:
+        chk.add("env.mount", G, "fail", f"组合挂载缺项：{'、'.join(lack)}",
+                f"profile={profile} patch={patch}",
+                "对照开发机的 cordis.patch.yml / package.json（dsh.profile.bundles）补齐，再重启服务")
+    if "argent-ml" not in deps:
+        chk.add("env.mount_ml", G, "warn", "profile 依赖里没有 argent-ml",
+                "脚本目录约定由 argent-ml 提供（scriptsDir=~/.argent-dsh/scripts）")
+
+    # 机器相关的**推送时刻**：config.json 的 mlDailyTime（站点本地 HH:MM）决定日报几点发。
+    # 2026-09-28 P10 实测：客户机缺这个键 ⇒ 静默退回默认 08:00（站点本地），
+    # 而开发机一直是 00:05 ⇒ 客户会在**北京 22:00** 收到卡，而不是习惯的 14:05。
+    # 这种"缺了就用另一个默认值"的差异不会报错，只会让人以为"今天怎么没推"。
+    cfg = load_json(data_dir / "config.json") or {}
+    if cfg.get("mlDailyTime"):
+        chk.add("env.daily_time", G, "ok", f"日报推送时刻 {cfg['mlDailyTime']}（站点本地）",
+                "config.json:mlDailyTime", "")
+    else:
+        chk.add("env.daily_time", G, "warn", "config.json 缺 mlDailyTime（默认站点本地 08:00）",
+                f"{data_dir / 'config.json'}",
+                "若与既有推送时刻不一致，客户会以为「今天没推」；按运营口径补 mlDailyTime（如 00:05）")
+
+    # 运行副本活着的证据（日志标记）
+    log = pathlib.Path("/tmp/dsh-web.log")
+    if not log.exists():
+        chk.add("env.live", G, "info", "未找到 /tmp/dsh-web.log（跳过存活标记检查）", "",
+                "用 --log 指定服务日志路径")
+    else:
+        tail = "\n".join(log.read_text(errors="replace").splitlines()[-4000:])
+        # 只对**组合里该有的**插件要求日志标记：2026-09-28 客户机实测，argent-ml 是按需安装的
+        # 独立插件（见 lib/plugin-lifecycle.mjs 的 LEGACY_PLUGIN_SOURCES），**永远不会**出现在
+        # 常驻日志里 ⇒ 原来的"四个插件都要有标记"会永久挂一条误导性告警，
+        # 措辞还写着"可能未重启"（让人白重启）。期望集合改从共享组合定义来。
+        expected = set((comp.get("business") or {}).get("patch") or []) | set((comp.get("business") or {}).get("bundles") or [])
+        absent = [n for n, mk in LOG_MARKERS.items() if n in expected and mk not in tail]
+        not_expected = [n for n in LOG_MARKERS if n not in expected]
+        if absent:
+            chk.add("env.live", G, "warn", f"日志尾部未见插件标记：{'、'.join(absent)}",
+                    "可能是服务未启动，或 host 插件改动后**尚未重启**",
+                    "重启 dsh web 后复核（host 改动必须重启才生效）")
+        else:
+            note = f"组合内 {len(expected)} 个 host 插件都在日志里出现过"
+            if not_expected:
+                note += f"；按设计不常驻（非组合插件）：{'、'.join(not_expected)}"
+            chk.add("env.live", G, "ok", note, "尾部 4000 行内")
+        # 「配置不可用」要看**多久以前**：dsh-web.log 是追加型，尾部 4000 行可能横跨好几天，
+        # 拿历史遗留当现在的故障会吓人（2026-09-20 实测：命中的是 09-17 的三行）。
+        # 判据：能在日志里找到带时间戳的最近一次出现 ⇒ 按 24h 判定；找不到时间戳 ⇒ 保持 warn。
+        if "配置不可用" in tail:
+            recent, when = False, ""
+            watch = data_dir / "flow-watch.log"
+            src = watch if watch.exists() else log
+            stamp = re.compile(r"\[(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})")
+            try:
+                for line in src.read_text(errors="replace").splitlines():
+                    if "配置不可用" not in line:
+                        continue
+                    mt = stamp.search(line)
+                    if not mt:
+                        recent, when = True, ""
+                        continue
+                    seen = dt.datetime.strptime(f"{mt.group(1)} {mt.group(2)}", "%Y-%m-%d %H:%M:%S")
+                    when = f"{mt.group(1)} {mt.group(2)}"
+                    recent = recent or (dt.datetime.now() - seen).total_seconds() < 86400
+            except Exception:                                   # noqa: BLE001
+                recent, when = True, ""
+            if recent:
+                chk.add("env.live_flow_cfg", G, "warn", "日志里出现「流程配置不可用」",
+                        f"最近一次：{when or '（无时间戳）'}"
+                        " —— 失败回路会跳过该流程（常见原因：插件改动后未重启，或部署 env 未加载）",
+                        "重启服务后确认日志里 4 个流程都能解析；仍失败则查 fulfillment.env")
+            else:
+                chk.add("env.live_flow_cfg", G, "info",
+                        f"日志里有「流程配置不可用」，但最近一次是 {when or '更早'}（>24h，历史遗留）",
+                        "当前 4 个流程均可解析即可忽略；复核命令：python3 scripts/flow_config.py --list")
+
+
+def check_heavy(chk: Checks, repo: pathlib.Path) -> None:
+    """重量级门禁：preset schema + 启动冒烟（会起隔离实例，几十秒）。"""
+    G = "环境（--full）"
+    if (repo / "scripts" / "validate-preset-schema.mjs").exists():
+        code, out, err = run(["node", str(repo / "scripts" / "validate-preset-schema.mjs"), "--runtime"], timeout=300)
+        if code == 0:
+            chk.add("full.preset_schema", G, "ok", "preset schema 校验通过", "persona 必须用 prefix:（0.1.5 起写 text: 会挂载失败）")
+        else:
+            chk.add("full.preset_schema", G, "fail", "preset schema 校验失败",
+                    " | ".join((out or err).strip().splitlines()[:3]),
+                    "修 presets/*/agent.cordis.yml 后重跑（写错会导致服务起不来）")
+    if (repo / "scripts" / "plugin-bootcheck.mjs").exists():
+        code, out, err = run(["node", str(repo / "scripts" / "plugin-bootcheck.mjs")], timeout=900)
+        line = [l for l in (out or err).splitlines() if "[PASS]" in l or "[FAIL]" in l or "preset-probe" in l][-1:]
+        if code == 0:
+            chk.add("full.bootcheck", G, "ok", "隔离实例启动冒烟通过", line[0] if line else "")
+        else:
+            chk.add("full.bootcheck", G, "fail", "启动冒烟失败（preset 挂载或插件树有问题）",
+                    " | ".join((out or err).strip().splitlines()[-3:]),
+                    "见 scripts/plugin-bootcheck.mjs 输出；修好前不要重启生产服务")
+
+
+def check_product_gates(chk: Checks, repo: pathlib.Path) -> None:
+    """产品化门禁（迭代 3）：档位矩阵 / 能力包 / 适配器契约三处一致性。
+
+    为什么要进客户机自检：这三处**改了注册表或客户端就必须同步重生成**，
+    漂移的后果是"客户看到的档位/能力与实际不符"（实测：免费版把企业级角色显示成可用）。
+    三条都是**只读**校验，且都能在开发机先跑（同一份仓库）。
+    """
+    G = "产品化"
+    py = os.environ.get("ARGENT_PY") or sys.executable
+    gates = [
+        ("entitlements", "scripts/entitlements.py", "档位矩阵（网关表/客户端判断块/安装器免费集合）",
+         "跑 python3 scripts/entitlements.py --emit-gateway-table / --emit-client-block 重新生成后提交"),
+        ("capability_pack", "scripts/capability_pack.py", "能力包（版本锁 + 文件存在性 + 入口）",
+         "跑 python3 scripts/capability_pack.py --stamp 登记新内容（或回退改动）"),
+        ("integration_contract", "scripts/integration_contract.py", "货代适配器契约（含人工门与错误词表）",
+         "补齐/修正 scripts/integrations/<name>/adapter.py 后重跑"),
+    ]
+    for cid, rel, what, fix in gates:
+        path = repo / rel
+        if not path.exists():
+            chk.add(f"prod.{cid}", G, "warn", f"{rel} 不存在（旧版仓库？）",
+                    "迭代 3 起随仓库提供；客户机 git pull 后应有", "git pull --ff-only 更新仓库")
+            continue
+        code, out, err = run([py, str(path), "--validate"], timeout=120)
+        text = (out or err or "").strip()
+        if code == 0:
+            chk.add(f"prod.{cid}", G, "ok", f"{what} 一致", text.splitlines()[-1][:200] if text else "")
+        else:
+            chk.add(f"prod.{cid}", G, "fail", f"{what} **不一致**",
+                    " | ".join(text.splitlines()[:4]), fix)
+
+
+# ── 凭据与身份 ────────────────────────────────────────────────────────────────
+
+def check_credentials(chk: Checks, repo: pathlib.Path, data_dir: pathlib.Path,
+                      flows: list[str], flows_cfg: dict) -> None:
+    G = "凭据"
+    # P2a：必须走合并（业务线流程不在 base 里）；envFile 可能是规范路径（verticals/<id>/env/x.env）
+    registry = _registry_doc() or {}
+    env_files: set[str] = set()
+    for fid, spec in (registry.get("flows") or {}).items():
+        ef = (spec.get("source") or {}).get("envFile")
+        if ef:
+            env_files.add(str(ef))
+    for name in sorted(env_files):
+        # 规范位置优先（DATA/verticals/<id>/env/<file>），旧平铺兜底（DATA/<file>）——
+        # 与 flow_config._resolve_env_path 同规矩：迁移期两种都要认，否则老机器一律假红。
+        _key = pathlib.Path(name).name          # 检查 id 用 basename：跨布局稳定
+        cands = [data_dir / name, data_dir / _key]
+        p = next((c for c in cands if c.exists()), cands[0])
+        if not p.exists():
+            chk.add(f"cred.env.{_key}", G, "fail", f"部署凭据文件缺失：{_key}", str(p),
+                    "按 docs/客户机部署与上线.md / 部署清单补齐（内容不进仓库、不进对话）")
+            continue
+        mode = stat.S_IMODE(p.stat().st_mode)
+        if mode & 0o077:
+            chk.add(f"cred.env.{_key}", G, "fail", f"{_key} 权限过宽（{oct(mode)}）",
+                    "含密钥的文件必须 600", f"chmod 600 {p}")
+        else:
+            chk.add(f"cred.env.{_key}", G, "ok", f"{_key} 存在且 600", f"{len(p.read_text(errors='replace').splitlines())} 行")
+
+    # 流程配置能否解析（表 id 是否拿得到）—— 这一条是触发器能否干活的前提
+    for fid in flows:
+        cfg = flows_cfg.get(fid)
+        if cfg is None:
+            continue
+        if isinstance(cfg, dict) and cfg.get("_error"):
+            # 解析失败不能静默跳过：触发器/失败回路都会"该流程不可用"，等于这个流程没上线
+            chk.add(f"cred.cfg.{fid}", G, "fail", f"{fid} 配置不可解析：{cfg['_error']}",
+                    "flow_config.py 严格模式失败（缺部署环境变量 / 表 id 拿不到）",
+                    "补齐该流程声明的 envFile / *_BASE_TOKEN / *_TABLE_ID，或让它读的映射文件可读")
+            continue
+        src = cfg.get("source") or {}
+        base, table = str(src.get("base") or ""), str(src.get("table") or "")
+        if base and table:
+            extra = ""
+            if src.get("identityUnresolved"):
+                extra = f"｜⚠️ 身份未由 {src['identityUnresolved']} 指定，暂用声明的 {src.get('identity')}"
+            chk.add(f"cred.cfg.{fid}", G, "ok", f"{fid} 表已解析",
+                    f"{src.get('variant') or '-'}｜base {base[:10]}…｜table {table}｜身份 {src.get('identity')}{extra}")
+        else:
+            chk.add(f"cred.cfg.{fid}", G, "fail", f"{fid} 未解析出 base/table",
+                    json.dumps({k: v for k, v in src.items() if k.endswith("Unresolved")}, ensure_ascii=False),
+                    "在部署 env 文件里补 *_BASE_TOKEN / *_TABLE_ID（本机不可见客户机的真实值）")
+
+    # base/table 来自 *Ref（如鑫中航读 invoice-mapping.json）时确认文件可读
+    refs: set[str] = set()
+    for spec in (registry.get("flows") or {}).values():
+        s = spec.get("source") or {}
+        for key in ("baseRef", "tableRef"):
+            if s.get(key):
+                refs.add(str(s[key]).split("#")[0])
+    for r in sorted(refs):
+        p = pathlib.Path(os.path.expanduser(r))
+        if p.exists():
+            chk.add(f"cred.ref.{p.name}", G, "ok", f"映射文件存在：{p.name}", str(p))
+        else:
+            chk.add(f"cred.ref.{p.name}", G, "fail", f"映射文件缺失：{p}", "流程表 id 由它提供",
+                    "补齐该文件（或把 base/table 直接写进部署 env）")
+
+    # 身份 profile：`lark-cli profile list` 是权威清单（config.json 只有 apps 段，别去解析它）
+    identities = sorted({str((spec.get("source") or {}).get("identity") or "")
+                         for spec in (registry.get("flows") or {}).values()} - {""})
+    if shutil.which("lark-cli"):
+        code, out, err = run(["lark-cli", "profile", "list"], timeout=120)
+        try:
+            profs = json.loads(out)
+            names = {str(p.get("name")) for p in profs if isinstance(p, dict)}
+        except Exception:                                      # noqa: BLE001
+            names = set(re.findall(r'"name":\s*"([^"]+)"', out or ""))
+        if not names:
+            chk.add("cred.lark", G, "warn", "读不到 lark-cli profile 清单",
+                    (err or out).strip().splitlines()[:1] and (err or out).strip().splitlines()[0] or "",
+                    "跑 lark-cli profile list 确认 CLI 可用（见 skills/lark-shared）")
+        else:
+            lack = [i for i in identities if i and i not in names]
+            if lack:
+                chk.add("cred.lark", G, "fail", f"流程声明的身份不存在：{'、'.join(lack)}",
+                        f"流程 identity={identities}｜CLI 现有 {len(names)} 个 profile",
+                        "在客户机上配好该 profile（或改流程声明的 identity），否则读表/回写会 91403/找不到 profile")
+            else:
+                chk.add("cred.lark", G, "ok", f"流程身份都存在（{len(identities)} 个）",
+                        "、".join(identities) + f"｜CLI 共 {len(names)} 个 profile")
+    else:
+        chk.add("cred.lark", G, "warn", "PATH 里没有 lark-cli", "读表/回写都依赖它",
+                "按 skills/lark-shared 安装并登录")
+
+
+# ── 模型凭证（装机红灯门禁的运行时复核；2026-09-29 日报事故固化）──────────────
+
+def check_model_auth(chk: Checks, repo: pathlib.Path, dsh_home: pathlib.Path, online: bool) -> None:
+    """与计费模式匹配的模型凭证必须**在位且可用** —— 否则角色会话第一步就 401、票据空转。
+
+    事故：2026-09-14 whyshu.com 硬切换 JWT 密钥 ⇒ 客户机上那把 08-22 签发的 token 当场失效，
+    但「还在、exp 还没到」⇒ 本核对全绿；直到 09-29 日报第一次真调模型才炸
+    （会话 401、票据"停滞→回收→重派"循环 60 分钟 ×N、**零告警**，唯一信号是"日报没来"）。
+    判据收敛在 `scripts/check-model-auth.py`（安装器与流程预检共用同一份，避免三处漂移）。
+    """
+    G = "模型凭证"
+    script = repo / "scripts" / "check-model-auth.py"
+    if not script.exists():
+        chk.add("auth.script", G, "warn", "缺 scripts/check-model-auth.py（老克隆）", "",
+                "git pull 后重跑（本检查是 2026-09-29 日报事故的固化项）")
+        return
+    cmd = [sys.executable, str(script), "--dsh-home", str(dsh_home), "--json"]
+    if online:
+        cmd.append("--online")
+    code, out, err = run(cmd, timeout=120)
+    txt = (err or out or "").strip()
+    if code == 2 or not (out or "").strip():
+        chk.add("auth.script", G, "warn", "模型凭证体检没跑成（脚本自身错误）",
+                txt.splitlines()[-1] if txt else "", f"手动跑：python3 {script} --online")
+        return
+    try:
+        doc = json.loads(out)
+    except Exception:                                            # noqa: BLE001
+        chk.add("auth.script", G, "warn", "模型凭证体检输出不是 JSON", (out or "").strip()[:200],
+                f"手动跑：python3 {script} --online")
+        return
+    for it in (doc.get("checks") or []):
+        chk.add(str(it.get("id") or "auth"), G, str(it.get("level") or "warn"),
+                str(it.get("title") or ""), str(it.get("detail") or ""), str(it.get("fix") or ""))
+
+
+# ── 数据面（只读探测）─────────────────────────────────────────────────────────
+
+def check_data_plane(chk: Checks, repo: pathlib.Path, data_dir: pathlib.Path,
+                     flows: list[str], flows_cfg: dict, tmp: pathlib.Path) -> None:
+    G = "数据面（只读）"
+    py = sys.executable
+    for fid in flows:
+        cfg = flows_cfg.get(fid)
+        if not isinstance(cfg, dict) or cfg.get("_error") or not (cfg.get("source") or {}).get("table"):
+            chk.add(f"data.{fid}", G, "info", f"{fid} 跳过源探测", "表未解析（见凭据组）")
+            continue
+        cases_dir = tmp / f"cases-{fid}"
+        code, out, err = run([py, str(repo / "scripts" / "flow_source.py"), "--flow", fid,
+                              "--source", "feishu-base", "--limit", "3", "--json",
+                              "--out-dir", str(cases_dir)], timeout=420)
+        if code == 2:
+            chk.add(f"data.{fid}", G, "fail", f"{fid} 读表失败", (err or out).strip().splitlines()[-1:] and
+                    (err or out).strip().splitlines()[-1] or "",
+                    "查 identity/表 id/权限（91403 = 该 bot 对该 base 无权限）")
+        else:
+            n, miss = 0, []
+            try:
+                d = json.loads(out)
+                n = len(d.get("cases") or [])
+                miss = (d.get("cases") or [{}])[0].get("missing") or []
+            except Exception:                                  # noqa: BLE001
+                pass
+            chk.add(f"data.{fid}", G, "ok", f"{fid} 源可读：{n} 行（limit 3）",
+                    f"exit={code}（0=字段齐备 / 1=有缺口，均属正常）｜首行缺口 {len(miss)} 个"
+                    + ("：" + "、".join(miss[:4]) if miss else ""))
+
+        # FULL 的两套表口径都要能读（用户口径：以客户要求为准，先 legacy 后 lip）
+        if fid == "full":
+            for variant in ("legacy", "lip"):
+                code, out, err = run([py, str(repo / "scripts" / "flow_config.py"), "--flow", "full",
+                                      "--json"], timeout=120, env={"FULL_TABLE_MODE": variant})
+                if code != 0:
+                    chk.add(f"data.full.{variant}", G, "warn", f"FULL {variant} 变体配置不可解析",
+                            (err or out).strip().splitlines()[-1:] and (err or out).strip().splitlines()[-1] or "",
+                            f"在 fulfillment.env 里补该变体需要的表 id（legacy=FEISHU_*；lip=FULL_*）")
+                    continue
+                cfgv = json.loads(out)
+                base = str((cfgv.get("source") or {}).get("base") or "")
+                if not base:
+                    chk.add(f"data.full.{variant}", G, "warn", f"FULL {variant} 变体未解析出表",
+                            json.dumps({k: v for k, v in (cfgv.get("source") or {}).items()
+                                        if k.endswith("Unresolved")}, ensure_ascii=False),
+                            "缺哪个 env 就补哪个（本机看不到客户机的真实值）")
+                    continue
+                code, out, err = run([py, str(repo / "scripts" / "flow_source.py"), "--flow", "full",
+                                      "--source", "feishu-base", "--limit", "3", "--json",
+                                      "--out-dir", str(tmp / f"cases-full-{variant}")],
+                                     timeout=420, env={"FULL_TABLE_MODE": variant})
+                # 只有**当前口径**（FULL_TABLE_MODE）那个变体是硬门禁；另一个是"备胎"：
+                # 2026-09-28 客户机实测——正式口径 lip 可读、legacy 不可读（legacy 是另一张
+                # 老表，客户机 bot 未必有权限），流程根本不会读它。把它当 FAIL 会让预检
+                # 永远"有 1 项红"，反而训练人忽略真红。故非当前口径降级为 ⚠️ 并写明原因。
+                active_mode = (os.environ.get("FULL_TABLE_MODE") or "lip").strip()
+                if code == 2:
+                    level = variant_gate_level(variant, active_mode)
+                    title = (f"FULL {variant} 变体读表失败" if level == "fail"
+                             else f"FULL {variant} 变体读表失败（非当前口径 {active_mode}，仅备胎）")
+                    chk.add(f"data.full.{variant}", G, level, title,
+                            (err or out).strip().splitlines()[-1:] and (err or out).strip().splitlines()[-1] or "",
+                            "查该变体的 bot 权限（91403 = 无权限）；切到该口径前必须修好")
+                else:
+                    try:
+                        n = len(json.loads(out).get("cases") or [])
+                    except Exception:                          # noqa: BLE001
+                        n = "?"
+                    chk.add(f"data.full.{variant}", G, "ok", f"FULL {variant} 变体可读：{n} 行（limit 3）",
+                            f"base {base[:10]}…｜exit={code}",
+                            "两个变体都能读 = 迁移期可随时切换；能否读只是权限，**写哪张表由运营口径决定**")
+
+        # 分诊（只读；case 落 tmp，台账只读）
+        # ⛔ `--no-ledger-write`：本步是**只读**巡检（见上一行注释、以及 docs/Argent-宿主适配契约.md §9）——
+        # 上游数据变化时，分诊会往台账写一条信息性的「放行额度重置」（幂等、不改票据状态），
+        # 但**只读**巡检不该写任何文件（真台账由生产链路在它自己那一轮写）。
+        code, out, err = run([py, str(repo / "scripts" / "flow_triage.py"), "--flow", fid, "--json",
+                              "--no-ledger-write",
+                              "--out-dir", str(cases_dir)], timeout=420)
+        try:
+            summ = (json.loads(out).get("summary") or {})
+        except Exception:                                      # noqa: BLE001
+            summ = {}
+        if summ:
+            chk.add(f"triage.{fid}", G, "ok", f"{fid} 分诊：可派发 {summ.get('to_dispatch', '?')}",
+                    json.dumps(summ, ensure_ascii=False) + f"｜exit={code}",
+                    "等人补字段数大 = 放行开关未勾/运营字段未填（**这是期望行为**，不是故障）")
+        else:
+            chk.add(f"triage.{fid}", G, "warn", f"{fid} 分诊无输出",
+                    (err or out).strip().splitlines()[-1:] and (err or out).strip().splitlines()[-1] or "",
+                    "先解决源读取问题")
+
+        # 认领预演（--dry-run：不写台账、不建会话）
+        code, out, err = run([py, str(repo / "scripts" / "flow_claim.py"), "--flow", fid, "--dry-run",
+                              "--json", "--lock", str(tmp / f"claim-{fid}.lock")], timeout=180)
+        try:
+            claimed = json.loads(out).get("claimed")
+        except Exception:                                      # noqa: BLE001
+            claimed = None
+        if claimed is not None:
+            # exit 3 = 无可认领（正常结论）；exit 0 = 认领若干。二者都不是故障。
+            chk.add(f"claim.{fid}", G, "ok", f"{fid} 认领预演：本轮会认领 {len(claimed)} 张",
+                    "、".join(claimed[:3]) or "无可认领（计划为空 ⇒ 触发器醒来也会立刻退出）",
+                    "dry-run 未落盘；真派发由 flow-trigger.sh 负责")
+        else:
+            chk.add(f"claim.{fid}", G, "warn", f"{fid} 认领预演失败（exit={code}）",
+                    (err or out).strip().splitlines()[-1:] and (err or out).strip().splitlines()[-1] or "",
+                    "先解决源读取/配置问题")
+
+        # 未处置失败（只读）
+        code, out, err = run([py, str(repo / "scripts" / "flow_failure.py"), "--scan", "--flow", fid,
+                              "--json"], timeout=180)
+        try:
+            pend = json.loads(out).get("pending") or []
+        except Exception:                                      # noqa: BLE001
+            pend = []
+        if code == 0:
+            lvl = "warn" if pend else "ok"
+            chk.add(f"failures.{fid}", G, lvl, f"{fid} 未处置失败：{len(pend)}",
+                    "、".join(f"{p.get('caseId')}({p.get('level')})" for p in pend[:3]),
+                    "needs_agent 会被失败回路唤醒角色；retryable 由脚本自重试；needs_human 落卡等人")
+
+
+# ── 触发面 ────────────────────────────────────────────────────────────────────
+
+def check_triggers(chk: Checks, flows_cfg: dict, flows: list[str]) -> None:
+    G = "触发面"
+    # 暂停开关现状（影子期应该存在；上线时逐流程摘掉）
+    # 数据目录：走唯一判据（三级链，同 flow_config 口径）；下面用它读 `<数据目录>/*.env`
+    ws = pathlib.Path(resolve_data_dir()["dir"])
+    for fid in flows:
+        cfg = flows_cfg.get(fid) or {}
+        pause = (cfg.get("paths") or {}).get("pauseSwitch")
+        if not pause:
+            continue
+        p = pathlib.Path(pause)
+        chk.add(f"pause.{fid}", G, "info" if p.exists() else "ok",
+                f"{fid} 暂停开关{'存在（不会自动唤起）' if p.exists() else '不存在（会自动唤起）'}",
+                str(p), "上线顺序：先带暂停开关装触发器 → 观察影子轮 → 再逐流程摘掉开关")
+
+    # LaunchAgent / cron：新旧触发器并存 = 双跑（会重复写生产表）
+    labels: list[str] = []
+    if shutil.which("launchctl"):
+        code, out, _ = run(["launchctl", "list"])
+        labels = [l.split("\t")[-1].strip() for l in out.splitlines() if "whyshu" in l]
+    legacy = [l for l in labels if "fulfillment-poll" in l or "invoice-poll" in l]
+    flowtrig = [l for l in labels if "flow-trigger" in l]
+    cron_txt = ""
+    if shutil.which("crontab"):
+        code, out, _ = run(["crontab", "-l"])
+        cron_txt = out or ""
+    cron_legacy = [l for l in cron_txt.splitlines()
+                   if l.strip() and not l.strip().startswith("#")
+                   and ("poll-fulfillment" in l or "poll-invoice" in l)]
+    cron_new = [l for l in cron_txt.splitlines()
+                if l.strip() and not l.strip().startswith("#") and "flow-trigger" in l]
+    chk.add("trig.launchd", G, "info", f"whyshu LaunchAgent：{len(labels)} 个",
+            "、".join(labels) or "(无)", "对照 docs/客户机部署与上线.md 的装载清单")
+    if cron_legacy or cron_new:
+        chk.add("trig.cron", G, "info", f"crontab 里有旧/新轮询 {len(cron_legacy)}/{len(cron_new)} 条",
+                "、".join((cron_legacy + cron_new)[:2]), "客户机历史上因 /var/at/tabs 权限弃用 cron，改用 LaunchAgent")
+    if (legacy or cron_legacy) and (flowtrig or cron_new):
+        chk.add("trig.double", G, "fail", "新旧触发器同时存在 ⇒ 有双跑风险",
+                f"旧：{'、'.join(legacy + [l.split('/')[-1] for l in cron_legacy])}｜"
+                f"新：{'、'.join(flowtrig + [l.split('/')[-1] for l in cron_new])}",
+                "同一流程只能有一路触发：先卸旧（launchctl bootout / 删 cron 行），再上新")
+    elif not (legacy or cron_legacy or flowtrig or cron_new):
+        chk.add("trig.double", G, "warn", "没有任何触发器在跑",
+                "影子期可以如此（手工跑 flow-trigger.sh --dry-run 演练）",
+                "上线时按 docs/客户机部署与上线.md §4.3 的「定时器安装」一节逐流程装载")
+    else:
+        chk.add("trig.double", G, "ok", "触发器不并存",
+                f"旧 {len(legacy) + len(cron_legacy)} / 新 {len(flowtrig) + len(cron_new)}")
+
+    # FULL 表口径（二选一必须由客户确认）
+    mode = os.environ.get("FULL_TABLE_MODE") or ""
+    envf = ws / "fulfillment.env"
+    if not mode and envf.exists():
+        for line in envf.read_text(errors="replace").splitlines():
+            if line.strip().startswith("FULL_TABLE_MODE="):
+                mode = line.split("=", 1)[1].strip()
+    if mode in ("legacy", "lip"):
+        note = "（正式口径）" if mode == "lip" else "（⚠️ 旧测试表：2026-09-17 用户口径现已以 lip 为准，legacy 仅回溯用）"
+        chk.add("trig.full_mode", G, "ok", f"FULL_TABLE_MODE={mode}", f"源变体已显式选定{note}")
+    else:
+        chk.add("trig.full_mode", G, "info", "FULL_TABLE_MODE 未显式设置（按注册表缺省走）",
+                "注册表 default 已改为 **lip**（FULL 现在的正式表）；legacy=FEISHU_BASE_TOKEN/FEISHU_TABLE_ID 仅回溯",
+                "建议在 fulfillment.env 里写 FULL_TABLE_MODE=lip，避免读代码才知道用的是哪张表")
+
+
+# ── 主流程 ────────────────────────────────────────────────────────────────────
+
+def check_verticals(chk: Checks, repo: pathlib.Path, data_dir: pathlib.Path) -> None:
+    """**业务线自检段**（P2a 起）：跑 `verticals/<id>/preflight.py#checks(env)`。
+
+    契约（见 `verticals/README.md`）：每个业务线可选提供
+        checks(env: dict) -> list[(名称, 级别 ok|warn|fail, 说明, 修复建议)]
+    规矩与平台预检一致：**只读探测**、不写客户数据、缺凭据要能区分"没配"与"配了没权限"。
+    业务线自检失败（自身报错）记 warn 而不是 fail —— 免得一条线的脚手架问题把整机预检判死。
+    """
+    G = "业务线"
+    vroot = repo / "verticals"
+    if not vroot.is_dir():
+        return
+    for d in sorted(vroot.iterdir()):
+        if not d.is_dir() or d.name.startswith((".", "_")):
+            continue
+        pf = d / "preflight.py"
+        if not pf.exists():
+            chk.add(f"vertical.{d.name}", G, "info", "该业务线没有 preflight.py（可选）", "需要时补 verticals/<id>/preflight.py")
+            continue
+        try:
+            spec = importlib.util.spec_from_file_location(f"argent_vertical_preflight_{d.name}", pf)
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)
+            items = mod.checks({"data_dir": str(data_dir), "repo": str(repo)}) or []
+        except Exception as exc:                                # noqa: BLE001
+            chk.add(f"vertical.{d.name}", G, "warn", f"自检段执行失败：{exc}",
+                    "修 verticals/<id>/preflight.py#checks（签名见 verticals/README.md）")
+            continue
+        for item in items:
+            try:
+                name, level, msg, fix = item
+            except Exception:                                   # noqa: BLE001
+                chk.add(f"vertical.{d.name}", G, "warn", f"自检段返回格式不对：{item!r}",
+                        "返回 (名称, ok|warn|fail, 说明, 修复建议) 四元组")
+                continue
+            chk.add(f"vertical.{d.name}.{name}", G, level, msg, fix)
+
+
+def flow_configs(repo: pathlib.Path, flows: list[str]) -> dict:
+    """每流程配置（strict），失败记 _error 而不中断（后面按组报）。"""
+    out: dict = {}
+    for fid in flows:
+        code, so, se = run([sys.executable, str(repo / "scripts" / "flow_config.py"),
+                            "--flow", fid, "--json"], timeout=120)
+        if code == 0 and so.strip().startswith("{"):
+            out[fid] = json.loads(so)
+        else:
+            out[fid] = {"_error": (se or so).strip().splitlines()[-1:] and
+                        (se or so).strip().splitlines()[-1] or f"exit={code}"}
+    return out
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="客户机上线核对（只读自检）")
+    ap.add_argument("--repo", default=str(DEFAULT_REPO), help="开发仓库路径（默认脚本上一级）")
+    ap.add_argument("--profile", default=os.environ.get("DSH_PROFILE", "web"))
+    ap.add_argument("--flow", action="append", help="只核对指定流程（可多次）；默认三个都查")
+    ap.add_argument("--offline", action="store_true", help="跳过读表/分诊/认领等在线探测")
+    ap.add_argument("--full", action="store_true", help="追加重量级门禁（preset schema + 启动冒烟）")
+    ap.add_argument("--json", action="store_true", help="JSON 输出")
+    a = ap.parse_args(argv)
+
+    repo = pathlib.Path(os.path.expanduser(a.repo)).resolve()
+    data_dir = pathlib.Path(resolve_data_dir()["dir"])
+    flows = a.flow or FLOWS_DEFAULT
+    chk = Checks()
+
+    if not (repo / "scripts" / "flow-requirements.json").exists():
+        print(f"❌ 不是 argent-dsh 仓库（缺 scripts/flow-requirements.json）：{repo}", file=sys.stderr)
+        return 2
+
+    cfg = flow_configs(repo, flows)
+    tmp = pathlib.Path(tempfile.mkdtemp(prefix="argent-preflight-"))
+    try:
+        check_env(chk, repo, data_dir, a.profile)
+        if a.full:
+            check_heavy(chk, repo)
+        check_product_gates(chk, repo)
+        check_credentials(chk, repo, data_dir, flows, cfg)
+        # 模型凭证：DSH_HOME 优先（多实例机器上 data_dir 可能在别处）
+        dsh_home = pathlib.Path(os.path.expanduser(os.environ.get("DSH_HOME") or str(data_dir.parent)))
+        check_model_auth(chk, repo, dsh_home, online=not a.offline)
+        if not a.offline:
+            check_data_plane(chk, repo, data_dir, flows, cfg, tmp)
+        check_triggers(chk, cfg, flows)
+        check_verticals(chk, repo, data_dir)
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    counts = chk.counts()
+    if a.json:
+        print(json.dumps({"repo": str(repo), "dataDir": str(data_dir), "profile": a.profile,
+                          "offline": a.offline, "flows": flows, "checks": chk.items,
+                          "summary": counts}, ensure_ascii=False, indent=2))
+    else:
+        icon = {"ok": "✅", "warn": "⚠️", "fail": "❌", "info": "·"}
+        group = None
+        for it in chk.items:
+            if it["group"] != group:
+                group = it["group"]
+                print(f"\n─── {group} " + "─" * max(0, 40 - len(group)))
+            print(f"  {icon.get(it['level'], '?')} {it['title']}")
+            if it["detail"]:
+                print(f"      {it['detail']}")
+            if it["level"] == "fail" and it["fix"]:
+                print(f"      ↳ 修法：{it['fix']}")
+        print(f"\n═══ 合计：✅ {counts['ok']}｜⚠️ {counts['warn']}｜❌ {counts['fail']}｜· {counts['info']}")
+        if counts["fail"]:
+            print("   有 FAIL 项：先按「修法」处理，再重跑本脚本（脚本本身不写任何生产数据）")
+        elif counts["warn"]:
+            print("   无 FAIL；⚠️ 项按清单判断是否阻塞上线（有的只是影子期应有的状态）")
+        else:
+            print("   全绿。人工确认清单（运营口径/门户步骤）见 docs/客户机部署与上线.md §4.3")
+    return 1 if counts["fail"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())