@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/env_probe.py

@@ -0,0 +1,411 @@
+#!/usr/bin/env python3
+"""env_probe —— 认领前的**环境预检**（只读）：浏览器客户端到底能不能干活。
+
+## 为什么要有它（2026-09-23 实测）
+紫鸟客户端"进程在、Bridge 通、但**未登录**"时，FULL 的认领**照常把票派给角色**，
+角色跑进去才发现环境不可用 ⇒ 记 blocked。代价有两笔：
+  ① 白烧一轮派发与角色算力；
+  ② 这些票的**认领租约到期后变成「停滞」**，而停滞票当时没有任何自动回收路径
+     ⇒ 票静静躺着，还占着同店铺的批次（那天"可派发 6 却连续 4 轮无票可认领"）。
+本探针把这类"环境不可用"提前到**认领之前**发现：不可用就不认领，日志一句话说清原因。
+
+语义：exit 0 = 可用；exit 2 = 不可用（**不**重试、**不**认领本轮）；exit 3 = 流程未声明探针（无需探）。
+只读：`ziniao-cli store list` 不点浏览器、不改任何数据。
+
+## 回退判据（2026-10-11 加，**只放宽这一处认领前闸门**）
+生产现场实测：客户机 FULL 触发器**每轮**都被本预检挡下（"Bridge 正常但没有任何店铺"）、
+**当天 0 票处理**；而同一时刻浏览器客户端在跑、**本地 1 店店铺窗口开着且 CDP 可达**
+（`curl http://127.0.0.1:32826/json/version` → `Chrome/142…`），用
+`orchestrator.py --mode full --cdp-url http://127.0.0.1:32826` 手工跑**同一批 6 票全成功**。
+⇒ 判据过窄：云端店铺列表（`store list` 的 `data.items`）拉不到 ≠ 环境不可用。
+
+判据是**三层**（顺序固定；第 0 层非空 ⇒ 直接可用，⛔ 两层回退一次都不探）：
+
+| 层 | 判据 | 实现 | 现场实测（2026-10-11） |
+|---|---|---|---|
+| 0 | 云端店铺列表**非空** ⇒ 可用 | 既有（**逐字不变**） | 正常路径 |
+| ① | 本机**已运行的店铺窗口**（`getRunningInfo`） | `scripts/lib/webdriver_ipc.py` | 上午现场有效（1 店窗口在跑，`32826` 可连） |
+| ② | 本机 **CDP 端口 + `chrome_<store_id>` 归属 + 页面可达** | `scripts/lib/cdp_ports.py` | **恢复窗口现场：`getBrowserList`=0、`getRunningInfo` 也是 0**（窗口明明在跑）⇒ 真救回来的是这一层：实测端口 `[13018, 27893]`，1 店=27893 / 2 店=13018 |
+
+⇒ 第 ① 层**不是万能的**：同一天里 `getRunningInfo` 也返回 0，而窗口在跑、CDP 可连。
+第 ② 层才是"窗口在跑"这件事最贴近事实的证据 —— 端口 ∧ 进程命令行里的 user-data 目录
+`…/chrome_<store_id>` **一一对应到店铺**（⛔ 归属确认不到就判不可用，绝不猜是哪家店）。
+
+保守边界（回归钉住，见 `scripts/tests/env-probe-cdp-port-fallback.test.py`）：
+· 列表为空 ∧ **两层都没有**窗口/端口 ⇒ 仍判**不可用**（文案与改动前**逐字一致**）；
+· **有端口但归属不上任何在册店铺 ⇒ 不可用**（⛔ 不猜、⛔ 不取第一个端口）；
+· 两层探针**本身失败/超时** ⇒ 仍判不可用，且文案写明"回退判据不可用（原因）"
+  （⛔ "查不到"绝不当"可用"；⛔ 绝不上抛：预检崩掉比判不可用更糟）；
+· `store list` 正常且非空 ⇒ 行为**逐字不变**（不触发任何回退、零次额外探针）；
+· 只对**该流程在册/声明的店铺**判（`~/.dsh/argent/stores.json`；⛔ 不遍历无关店铺）；
+· ⛔ **只读**：⛔ 不开窗、⛔ 不关窗、⛔ 不写 `cdp-port-map.json`（那是
+  `scripts/ensure-store-windows.py` 的职责）、⛔ 不改任何状态；
+· ⛔ "窗口已开" **不等于** "账号已授权" —— 该等价关系**只**用于这一处认领前闸门，
+  不得被别的判据（店铺归属、授权、开票资格…）引用。
+
+开关：`ARGENT_PREFLIGHT_LOCAL_WINDOW_FALLBACK=0`（`false`/`off`/`no` 亦可）**关闭两层回退**，
+默认**开启**（理由：回退只是把"能不能干活"的判据换成更贴近事实的那个证据，且所有保守边界都还在）；
+更细的一层：`ARGENT_PREFLIGHT_CDP_PORT_FALLBACK=0` 只关第 ② 层（第 ① 层照旧）。
+流程 spec 也可写 `localWindowFallback: false`（两层一起关）/ `cdpPortFallback: false`（只关第 ② 层）。
+"""
+from __future__ import annotations
+import argparse, json, os, pathlib, subprocess, sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+import webdriver_ipc  # noqa: E402  客户端 WebDriver 只读查询的**唯一实现**（⛔ 不另造客户端）
+import cdp_ports  # noqa: E402  CDP 端口发现/归属/page 探针的**唯一实现**（⛔ 不另造第二份）
+PROBE_TIMEOUT = 45
+# 默认清单命令（**唯一字面量**：多处默认值都引用它 —— 第二份字面量会被 engine-words 记成新增）
+DEFAULT_STORE_CMD = ['ziniao-cli', 'store', 'list']
+# 回退判据的开关（默认开；见模块 docstring 的"回退判据"段）。
+LOCAL_WINDOW_FALLBACK_ENV = 'ARGENT_PREFLIGHT_LOCAL_WINDOW_FALLBACK'
+# 第 ② 层（CDP 端口）的**更细**开关：默认开；关它只退掉第 ② 层（第 ① 层照旧）。
+CDP_PORT_FALLBACK_ENV = 'ARGENT_PREFLIGHT_CDP_PORT_FALLBACK'
+# 本地窗口查询超时（秒）：比清单命令短 —— 它只是回退证据，不该把认领前的预算吃光。
+LOCAL_WINDOW_TIMEOUT = 20.0
+# 第 ② 层的单次探针超时（秒）：`/json/version` 与 `/json/list` 都是本机回环只读，2s 足够。
+CDP_PROBE_TIMEOUT = 2.0
+# "没有任何店铺"的**既有文案**：回退未通过时必须**逐字**保持（改动前什么样，现在还什么样）。
+NO_STORE_DETAIL = "Bridge 正常但**没有任何店铺**（未登录 / 账号无授权）"
+
+
+def _off(raw: str) -> bool:
+    return str(raw or '').strip().lower() in ('0', 'false', 'off', 'no')
+
+
+def local_window_fallback_enabled(spec: dict | None = None) -> bool:
+    """回退判据是否启用：**默认开**；env 关闭优先，其次流程 spec 的 `localWindowFallback:false`。
+
+    为什么默认开：现场的根本代价是"**整天 0 票**"，而回退只在"云端列表拿不到"时生效，
+    且"本地没有窗口 / 查不到"仍然一律判不可用（保守边界全在）。要一键退回旧行为用
+    `ARGENT_PREFLIGHT_LOCAL_WINDOW_FALLBACK=0`（现场排障、复现旧日志时用）。
+    """
+    if (spec or {}).get('localWindowFallback') is False:
+        return False
+    return not _off(os.environ.get(LOCAL_WINDOW_FALLBACK_ENV, ''))
+
+
+def cdp_port_fallback_enabled(spec: dict | None = None) -> bool:
+    """**第 ② 层**（CDP 端口 + 店铺归属）是否启用：默认开，且**从属于**粗开关。
+
+    从属关系是有意的（回归⑤钉住）：`ARGENT_PREFLIGHT_LOCAL_WINDOW_FALLBACK=0` ⇒ **两层回退都不走、
+    零探针**、文案逐字旧常量 —— 现场排障时"一键回到改动前"必须仍然成立。
+    只想关第 ② 层（第 ① 层照旧）时用 `ARGENT_PREFLIGHT_CDP_PORT_FALLBACK=0`，
+    或流程 spec 写 `cdpPortFallback: false`。
+    """
+    if not local_window_fallback_enabled(spec):
+        return False
+    if (spec or {}).get('cdpPortFallback') is False:
+        return False
+    return not _off(os.environ.get(CDP_PORT_FALLBACK_ENV, ''))
+
+
+def local_wd_port(spec: dict | None = None) -> int:
+    """本机 WebDriver IPC 端口：env `ZINIAO_WD_PORT` → spec `wdPort` → 官方默认 19515。"""
+    raw = os.environ.get('ZINIAO_WD_PORT') or (spec or {}).get('wdPort') or webdriver_ipc.DEFAULT_WD_PORT
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return webdriver_ipc.DEFAULT_WD_PORT
+
+
+def _local_running_windows(port: int, timeout: float = LOCAL_WINDOW_TIMEOUT) -> dict:
+    """**只读**查本机"已运行的店铺窗口"（测试注入点）→ `webdriver_ipc.running_windows_probe`。
+
+    ⛔ 只读：只发 `getRunningInfo`（免凭据），⛔ 不开窗口、不点按钮、不改任何状态。
+    ⛔ **绝不上抛**（本函数的契约）：异常一律折成 `{"ok": False, "error": "…"}` ——
+    "查不到"与"没有"必须分开（`error` 字段），且**预检绝不能因为回退这一段而崩掉**
+    （崩掉 = 认领前的整条链路报 traceback；那比"判不可用"更糟、更难排查）。
+    """
+    try:
+        probe = webdriver_ipc.running_windows_probe(port, timeout=timeout)
+    except Exception as exc:                                    # noqa: BLE001
+        return {'ok': False, 'count': 0, 'summary': '',
+                'error': f'{type(exc).__name__}: {exc}', 'port': port}
+    if not isinstance(probe, dict):                             # 契约外的返回值 ⇒ 当作"查不到"
+        return {'ok': False, 'count': 0, 'summary': '',
+                'error': f'running_windows_probe 返回非 dict：{type(probe).__name__}', 'port': port}
+    return probe
+
+
+def _fallback_detail(spec: dict, *, lead: str, summary: str, count: int) -> str:
+    """第 ① 层回退（本机已运行窗口）通过时的说明文案（**逐字不变**：既有回归按它断言）。"""
+    return (f"就绪（**回退判据**：`{_cmd_label(spec)}`{lead}，"
+            f"但本地已运行 {count} 个窗口：{summary}）")
+
+
+def _cdp_fallback_detail(spec: dict, *, head: str, summary: str, count: int) -> str:
+    """第 ② 层回退（CDP 端口 + 归属）通过时的说明文案。
+
+    **必须**含「回退判据（CDP 端口）」与「店铺列表为空，但本机已运行属于 N 个店铺的窗口：…」
+    —— 回归按这几段逐字断言（⛔ 别改措辞而不改回归）。
+    """
+    return (f"就绪（**回退判据（CDP 端口）**：{head}，但本机已运行属于 {count} 个店铺的窗口："
+            f"{summary}；依据 `{_cmd_label(spec)}`）")
+
+
+def _engine_store_scope(spec: dict) -> tuple:
+    """第 ② 层要用的**既有事实源** → `(scope, error)`（**测试注入点**）。
+
+    · `scope['stores']` = `[(店名, store_id), …]` —— **只含该流程在册/声明的店铺**
+      （流程 spec 声明子集 ⇒ 只用子集；⛔ 不遍历无关店铺）；
+    · `scope['markers']` = `lsof` 行里匹配客户端进程的子串（引擎那一份字面量，⛔ 本文件不复制）。
+
+    ⚠️ **为什么用 `importlib` 动态取引擎，而不是行首 `import orchestrator`**：
+    `env_probe.py` 属 `pack.engine`（**每个带 flow 的能力包都带**），而 `scripts/orchestrator.py`
+    只在 full 的能力包脚本集里 ⇒ 静态 import 会让 invoice/daily-report 的
+    `check-pack-closure --strict` 报缺件（实测 3 条，含它的两跳依赖）。而这条引用在那些机器上
+    **永远走不到**：只有声明了 `envProbe` 的流程才进得了第 ② 层（今天只有 full；
+    `flow_probe_spec()` 对别的流程返回 `{}` ⇒ `main()` 在 import 之前就 exit 3）。
+    ⇒ 形态 = **可选依赖**：取不到就**如实报"回退判据不可用"**（⛔ 不静默降级、⛔ 不猜店铺），
+    降级路径由回归钉住。同族先例：`scripts/flow_config.py` 用 `importlib` 取业务线适配器。
+    """
+    try:
+        import importlib
+        orch = importlib.import_module('orchestrator')
+    except Exception as exc:                                     # noqa: BLE001
+        return {}, f"引擎店铺解析不可用（{type(exc).__name__}: {exc}）"
+    markers = tuple(str(m).strip() for m in
+                    (getattr(orch, 'CDP_CLIENT_PROC_MARKERS', ()) or ()) if str(m).strip())
+    if not markers:
+        return {}, '引擎未声明客户端进程名判据（CDP_CLIENT_PROC_MARKERS 缺失）'
+    declared = [str(n).strip() for n in ((spec or {}).get('stores') or []) if str(n).strip()]
+    scope: list = []
+    if declared:
+        # 流程声明了店铺子集 ⇒ **只用子集**；解析走引擎既有实现（⛔ 不新造第二份）
+        for name in declared:
+            info, _dev = orch._resolve_store(name)
+            sid = str((info or {}).get('store_id') or '').strip()
+            if sid:
+                scope.append((name, sid))
+        if not scope:
+            return {}, f"流程声明的店铺在册清单里一个都解析不到（{declared}）"
+    else:
+        # 在册店铺 = stores.json；**缺失/损坏时回退内置映射** —— 与 `orchestrator._resolve_store()`
+        # 同一口径（内置映射是开发/存量机器的兜底，⛔ 不在这里另立一套判据）。
+        stores = orch._load_stores() or dict(getattr(orch, 'STORE_MAP', {}) or {})
+        for key in sorted(stores):
+            sid = str((stores.get(key) or {}).get('store_id') or '').strip()
+            if sid:
+                scope.append((str(key), sid))
+        if not scope:
+            return {}, '本机店铺清单为空（stores.json 缺失 / 损坏？）'
+    return {'stores': scope, 'markers': markers}, ''
+
+
+def _cdp_port_fallback(spec: dict, timeout: float = CDP_PROBE_TIMEOUT) -> dict:
+    """**第 ② 层回退**：本机 CDP 端口 → `chrome_<store_id>` 归属 → 页面可达（**只读**，⛔ 绝不上抛）。
+
+    三态与第 ① 层同一形状（别把三态揉成两态）：
+      · `ok=True` ⇒ 有**属于在册店铺**且**可驱动**的窗口（`count` = 几家店，`summary` = 证据行）；
+      · `ok=False, error=''` ⇒ 查得到但**没有**（真没有：没端口 / 端口归属不上任何在册店铺）；
+      · `ok=False, error!=''` ⇒ **查不到**（引擎/探针失败）—— 与"没有"**必须分开**，
+        "查不到"**不得**当可用。
+
+    实现全部取自 `scripts/lib/cdp_ports.py`（端口发现/归属/页面探针的**唯一实现**）；
+    本函数只做**策略**：范围（哪些店）、顺序、证据行、三态折叠。⛔ 不写任何文件。
+    """
+    scope, err = _engine_store_scope(spec)
+    if err:
+        return {'ok': False, 'count': 0, 'summary': '', 'error': err, 'ports': []}
+    try:
+        ports = cdp_ports.discover_ports(scope['markers'])
+    except Exception as exc:                                     # noqa: BLE001
+        return {'ok': False, 'count': 0, 'summary': '', 'ports': [],
+                'error': f"端口发现失败（{type(exc).__name__}: {exc}）"}
+    if not ports:
+        # 一个端口都没有 ⇒ 没有可归属的东西：**一次归属查询都不发**（真·没有，不是查不到）
+        return {'ok': False, 'count': 0, 'summary': '', 'error': '', 'ports': []}
+    lines: list = []
+    for name, store_id in scope['stores']:
+        try:
+            port = cdp_ports.match_port_by_user_data_dir(store_id, ports)
+            if not port:
+                continue
+            # 可驱动判据（两条都要过）：`/json/version` 可读（discover 已保证，这里再核一次防漂移）
+            # ∧ `/json/list` 至少一个 page 目标（"浏览器进程在" ≠ "有可驱动的标签页"）。
+            if not cdp_ports.is_cdp_port(int(port), timeout=timeout):
+                continue
+            pages = cdp_ports.page_targets(int(port), timeout=timeout)
+            if not pages:
+                continue
+            lines.append(webdriver_ipc.window_item_line({
+                'downloadPath': name,
+                'debuggingPort': int(port),
+                'core_version': cdp_ports.browser_version(int(port), timeout=timeout) or '?',
+                # handle 取 `/json/list` 首个 page 目标的 id（CDP 附着的句柄；与第 ① 层的
+                # `mainHandle` 同义：都是"那个可驱动的窗口句柄"，只是来源不同 —— 如实标注）。
+                'mainHandle': cdp_ports.target_handle(pages) or '?',
+            }))
+        except Exception as exc:                                 # noqa: BLE001
+            return {'ok': False, 'count': 0, 'summary': '', 'ports': list(ports),
+                    'error': f"端口归属/页面探针失败（{type(exc).__name__}: {exc}）"}
+    return {'ok': bool(lines), 'count': len(lines), 'summary': ' ｜ '.join(lines),
+            'error': '', 'ports': list(ports)}
+
+
+def throttle_marker(flow: str) -> tuple:
+    """平台限流熔断标记 → (是否生效, 说明)。
+
+    文件：`<ARGENT_DATA_DIR>/THROTTLE_<FLOW>`（JSON：reason/since/until）
+    为什么（2026-09-23）：美客多限流时，光暂停定时器不够 —— 角色手里还有票在重跑，
+    而人类/角色都没有"现在平台在限流"的统一信号。标记文件给了**一个所有脚本都能读的事实**，
+    到期自动失效（until），无需人工清理。
+    """
+    import time as _time
+    d = pathlib.Path(resolve_data_dir()['dir'])
+    f = d / f'THROTTLE_{flow.upper().replace("-", "_")}'
+    if not f.exists():
+        return False, ''
+    try:
+        doc = json.loads(f.read_text(encoding='utf-8'))
+    except Exception:                                            # noqa: BLE001
+        doc = {}
+    until = str(doc.get('until') or '')
+    if until:
+        try:
+            if _time.mktime(_time.strptime(until, '%Y-%m-%dT%H:%M:%S')) < _time.time():
+                return False, f'熔断标记已过期（{until}）'
+        except Exception:                                        # noqa: BLE001
+            pass
+    return True, f"平台限流熔断中：{doc.get('reason') or '（未写原因）'}（至 {until or '未设'}）"
+
+
+def flow_probe_spec(flow: str) -> dict:
+    """从注册表读该流程声明的环境探针（`envProbe`）。读不到 ⇒ 无探针。"""
+    try:
+        import flow_config
+        spec = flow_config.load_config(flow, strict=False)
+        return (spec or {}).get('envProbe') or {}
+    except Exception:                                            # noqa: BLE001
+        return {}
+
+
+def _store_list_probe(spec: dict) -> tuple:
+    """跑清单命令 → `(bridge_spoke, ok, items, out, stderr, err_detail)`。
+
+    `bridge_spoke` = **Bridge 有响应**（CLI 吐出了带 `ok` 键的 JSON）—— 只有它才允许走回退判据：
+    命令缺失/超时/输出不成 JSON ⇒ 连"Bridge 活没活"都不知道 ⇒ 保守判不可用（⛔ 不猜）。
+    """
+    cmd = list(spec.get('cmd') or DEFAULT_STORE_CMD)
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True,
+                           timeout=int(spec.get('timeoutSec') or PROBE_TIMEOUT))
+    except FileNotFoundError:
+        return False, False, [], '', '', f"找不到命令 {cmd[0]}（紫鸟 CLI 未安装？）"
+    except subprocess.TimeoutExpired:
+        return False, False, [], '', '', f"`{' '.join(cmd)}` 超时 {PROBE_TIMEOUT}s（客户端卡住/未启动）"
+    out = (p.stdout or '').strip()
+    doc: dict = {}
+    try:
+        doc = json.loads(out[out.find('{'):]) if '{' in out else {}
+    except Exception:                                            # noqa: BLE001
+        doc = {}
+    spoke = isinstance(doc, dict) and 'ok' in doc
+    items = ((doc.get('data') or {}).get('items') or []) if isinstance(doc, dict) else []
+    return spoke, bool(doc.get('ok')), list(items), out, (p.stderr or ''), ''
+
+
+def _cmd_label(spec: dict) -> str:
+    """清单命令的可读标签（日志里说清"是哪条命令拿不到店铺"）。"""
+    return ' '.join(list(spec.get('cmd') or DEFAULT_STORE_CMD))
+
+
+def probe_ziniao_store(spec: dict) -> tuple:
+    """紫鸟 ZClaw Bridge：能列出店铺 ⇒ 客户端在且已登录。→ (ok, 说明)
+
+    列表为空（或 `ok:false` 但 Bridge 有响应）时走**两层回退判据**（顺序固定，见模块 docstring）：
+      ① 本机已运行窗口（`getRunningInfo`，复用 `scripts/lib/webdriver_ipc.py`）；
+      ② 本机 CDP 端口 + `chrome_<store_id>` 归属 + 页面可达（复用 `scripts/lib/cdp_ports.py`）。
+    两层都不成立 ⇒ 不可用（文案逐字回到旧常量；只有探针**本身失败**才写"回退判据不可用（原因）"）。
+    """
+    spoke, ok_flag, items, out, err_out, err_detail = _store_list_probe(spec)
+    if err_detail:
+        return False, err_detail
+    if ok_flag and items:
+        return True, f"紫鸟就绪（{len(items)} 个店铺）"      # ← 正常路径：**逐字不变**
+    # ── 走到这里 = 云端店铺列表拿不到（为空 / 未就绪）⇒ 尝试两层回退判据 ──────────────────
+    raw = (out or err_out or '')[:120]
+    if not ok_flag:                     # 判据优先级与改动前**一致**：ok:false 先于"列表为空"
+        no_list = f"Bridge 未就绪或**客户端未登录**：{raw}"
+        lead = f" 未就绪（原文：{raw}）"
+        head = f"未就绪（原文：{raw}）"
+    else:
+        no_list = NO_STORE_DETAIL
+        lead = " 店铺列表为空"
+        head = "店铺列表为空"
+    if not spoke:
+        # Bridge 连"有没有响应"都测不出 ⇒ ⛔ 不回退（文案原样保留）
+        return False, no_list
+    if not local_window_fallback_enabled(spec):
+        # 粗开关关闭 ⇒ 行为与改动前**逐字一致**（连探针都不发：日志里不该出现回退痕迹）
+        return False, no_list
+    # ── ① 本机已运行的店铺窗口（`getRunningInfo`）──────────────────────────────────────
+    probe = _local_running_windows(local_wd_port(spec))
+    if probe.get('ok'):
+        return True, _fallback_detail(spec, lead=lead,
+                                      summary=str(probe.get('summary') or ''),
+                                      count=int(probe.get('count') or 0))
+    # ── ② 本机 CDP 端口 + 店铺归属（现场实测：`getRunningInfo` 也会是 0，而窗口在跑）────────
+    cdp_error = ''
+    if cdp_port_fallback_enabled(spec):
+        cdp = _cdp_port_fallback(spec)
+        if cdp.get('ok'):
+            return True, _cdp_fallback_detail(spec, head=head,
+                                              summary=str(cdp.get('summary') or ''),
+                                              count=int(cdp.get('count') or 0))
+        cdp_error = str(cdp.get('error') or '')
+    # ── 两层都不成立 ⇒ 不可用；把"探针没跑成"如实写出来（否则又成"猜"）──────────────────
+    reasons = []
+    if probe.get('error'):
+        reasons.append(f"本机窗口查询失败（{probe['error']}）")
+    if cdp_error:
+        reasons.append(f"CDP 端口探针失败（{cdp_error}）")
+    if reasons:
+        return False, f"{no_list}；回退判据不可用：{'；'.join(reasons)}"
+    return False, no_list
+
+
+KINDS = {'ziniao-store': probe_ziniao_store}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='认领前环境预检（只读）')
+    ap.add_argument('--flow', required=True)
+    ap.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+    # ① 熔断标记优先（人工/自动写入的"平台在限流"事实）——比探针更权威，且会自行过期
+    hot, hot_why = throttle_marker(a.flow)
+    if hot:
+        if a.json:
+            print(json.dumps({'flow': a.flow, 'probe': 'throttle', 'ok': False, 'detail': hot_why},
+                             ensure_ascii=False))
+        else:
+            print(f"  ❌ 环境预检（throttle）：{hot_why}")
+        return 2
+
+    spec = flow_probe_spec(a.flow)
+    kind = str(spec.get('kind') or '')
+    if not kind:
+        if a.json:
+            print(json.dumps({'flow': a.flow, 'probe': None, 'ok': True, 'skipped': True}, ensure_ascii=False))
+        else:
+            print(f"  · 流程 {a.flow} 未声明 envProbe ⇒ 跳过环境预检")
+        return 3
+    fn = KINDS.get(kind)
+    if fn is None:
+        print(f"❌ 未知探针类型 {kind!r}（可用：{', '.join(KINDS)}）", file=sys.stderr)
+        return 2
+    ok, why = fn(spec)
+    if a.json:
+        print(json.dumps({'flow': a.flow, 'probe': kind, 'ok': ok, 'detail': why}, ensure_ascii=False))
+    else:
+        print(f"  {'✅' if ok else '❌'} 环境预检（{kind}）：{why}")
+    return 0 if ok else 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/engine/scripts/feishu-card.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * 流程/告警类 **飞书交互卡片** 共用构造器（2026-09-17，用户口径：
+ * 「推送到飞书的信息全都改成卡片」→ 范围=**流程/告警类**，日常对话保持文本）。
+ *
+ * 为什么单独一个模块：卡片 JSON 的形状一旦散落在各处（gateway / 脚本 / 插件）就会各自漂移，
+ * 而卡片是要给人看的东西 —— 一处改、处处变。构造器是**纯函数**（无 IO、无网络），
+ * `scripts/tests/feishu-card.test.mjs` 直接 import 断言；发送只有 `sendCard()` 一个出口。
+ *
+ * 通道复用 `daily-report.mjs` 已跑通的那条：
+ *   lark-cli --profile <p> im +messages-send --chat-id <id> --msg-type interactive --content <json> --as bot
+ *
+ * 用法（默认 dry-run，只打印卡片 JSON；加 --send 才真发）：
+ *   node scripts/feishu-card.mjs --template flow-result --to internal \
+ *     --flow wenyao-invoice --flow-title 上海文鳐发票流程 \
+ *     --result "76265639=done|已上传发票与标签" --note "本轮 1 票完成"
+ *   node scripts/feishu-card.mjs --template await-release --to internal --flow full --count 91
+ *   node scripts/feishu-card.mjs --template failure-alert --to internal --flow full \
+ *     --case full__recvvgPQgoEFR3 --level needs_agent --error "门户超时" --attempt 2
+ */
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+// 数据目录：内核三级链（唯一判据）—— 卡片要读 `<数据目录>/config.json`
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+const CONFIG = join(DATA_DIR, 'config.json')
+const LARK_BIN = process.env.LARK_BIN || 'lark-cli'
+const MAX_MD = 4000
+
+/** 卡片配色（飞书 header.template）。 */
+export const COLORS = { ok: 'green', warn: 'orange', fail: 'red', info: 'blue', muted: 'grey' }
+
+export const STATUS_LEVEL = {
+  done: 'ok', ok: 'ok', 完成: 'ok', 已完成: 'ok',
+  blocked: 'warn', await_release: 'warn', 等人: 'warn', need_fields: 'warn',
+  failed: 'fail', fail: 'fail', error: 'fail', 失败: 'fail',
+  needs_human: 'fail', needs_agent: 'warn',
+}
+export const worstLevel = (levels) => {
+  const order = ['fail', 'warn', 'ok', 'info', 'muted']
+  const known = levels.filter((l) => order.includes(l))
+  return known.sort((a, b) => order.indexOf(a) - order.indexOf(b))[0] || 'info'
+}
+export const levelOf = (status) => STATUS_LEVEL[String(status || '').trim().toLowerCase()] || STATUS_LEVEL[String(status || '').trim()] || 'info'
+
+const clip = (s, n = MAX_MD) => {
+  const t = String(s ?? '')
+  return t.length <= n ? t : t.slice(0, n - 20) + `\n…（截断 ${t.length - n + 20} 字）`
+}
+export const md = (content) => ({ tag: 'markdown', content: clip(content) })
+export const hr = () => ({ tag: 'hr' })
+export const note = (text) => ({ tag: 'note', elements: [{ tag: 'plain_text', content: clip(text, 500) }] })
+/** 键值对（两列布局）：`[['票号','76265639'], …]`；奇数个自动补空。 */
+export const kv = (pairs = []) => {
+  const f = pairs.filter(Boolean).map(([k, v]) => ({
+    is_short: true,
+    text: { tag: 'lark_md', content: `**${clip(k, 40)}**\n${clip(v ?? '-', 300)}` },
+  }))
+  return f.length ? { tag: 'div', fields: f } : null
+}
+
+/** 基础卡片：标题 + 配色 + 内容块（自动去掉空块）。 */
+export function card({ title, level = 'info', elements = [], subtitle = '' }) {
+  const els = []
+  if (subtitle) els.push(md(subtitle))
+  for (const e of elements) if (e) els.push(e)
+  return {
+    config: { wide_screen_mode: true, update_multi: true },
+    header: { template: COLORS[level] || COLORS.info, title: { tag: 'plain_text', content: clip(title, 120) } },
+    elements: els.length ? els : [md('（无内容）')],
+  }
+}
+
+/** ① 流程结果汇报：`results = [{ticket, status, detail}]`。 */
+export function flowResultCard({ flow = '', flowTitle = '', results = [], ledger = '', noteText = '' } = {}) {
+  const level = worstLevel(results.map((r) => levelOf(r.status)))
+  const done = results.filter((r) => levelOf(r.status) === 'ok').length
+  const bad = results.filter((r) => ['fail', 'warn'].includes(levelOf(r.status))).length
+  const lines = results.map((r) => {
+    const icon = { ok: '✅', warn: '⏸', fail: '❌', info: '·', muted: '·' }[levelOf(r.status)] || '·'
+    return `${icon} **${r.ticket || '(无票号)'}**　${r.status || ''}${r.detail ? `　—　${r.detail}` : ''}`
+  })
+  return card({
+    title: `${flowTitle || flow}　本轮结果`,
+    level,
+    subtitle: `完成 ${done}　需关注 ${bad}　共 ${results.length} 票`,
+    elements: [
+      lines.length ? md(lines.join('\n')) : md('（本轮无票）'),
+      hr(),
+      kv([['流程', flow || '-'], ['台账', ledger ? '已记录' : '未记录']]),
+      noteText ? note(noteText) : null,
+    ],
+  })
+}
+
+/** ② 需人工裁定（用户口径 2026-09-17：needs_human 由用户本人确认）。 */
+export function needHumanCard({ flow = '', flowTitle = '', caseId = '', ticket = '', reason = '', ask = '', where = '会话里回一句，或在群里回' } = {}) {
+  return card({
+    title: `需要你确认　${flowTitle || flow}`,
+    level: 'fail',
+    subtitle: '这条不能自动往下走：要么缺数据，要么得你拍板。',
+    elements: [
+      kv([['票', ticket || caseId || '-'], ['流程', flow || '-']]),
+      reason ? md(`**卡在哪**\n${reason}`) : null,
+      ask ? md(`**要你定**\n${ask}`) : null,
+      note(`怎么回：${where}`),
+    ],
+  })
+}
+
+/** ③ 待放行汇总（FULL 的 await_release 桶：运营勾「就绪」才开跑）。 */
+export function awaitReleaseCard({ flow = '', flowTitle = '', count = 0, samples = [], gate = '就绪', noteText = '' } = {}) {
+  const many = count >= 20
+  return card({
+    title: `${flowTitle || flow}　待放行 ${count} 张`,
+    level: many ? 'warn' : 'info',
+    subtitle: `系统已识别、卡在放行门（**${gate}**）：没人勾就不会跑。`,
+    elements: [
+      samples.length ? md('例如：\n' + samples.slice(0, 5).map((s) => `· ${s}`).join('\n')) : null,
+      noteText ? note(noteText) : null,
+      note('这是提醒，不是故障：放行由人做（本次不需要任何脚本动作）。'),
+    ],
+  })
+}
+
+/** ④ 失败告警（角色被唤醒处置前后都可用）。 */
+export function failureAlertCard({ flow = '', flowTitle = '', caseId = '', level = 'needs_agent', error = '', attempt = '', max = '', action = '' } = {}) {
+  const lvl = levelOf(level)
+  const label = { needs_agent: '需要判断', needs_human: '需要人补/拍板', retryable: '可自动重试' }[level] || level
+  return card({
+    title: `流程失败　${flowTitle || flow}`,
+    level: lvl === 'info' ? 'warn' : lvl,
+    subtitle: `分类：**${label}**${attempt ? `　第 ${attempt}${max ? `/${max}` : ''} 次` : ''}`,
+    elements: [
+      kv([['票据', caseId || '-'], ['流程', flow || '-']]),
+      error ? md(`**错误摘要**\n${clip(error, 800)}`) : null,
+      action ? md(`**下一步**\n${action}`) : null,
+      note(level === 'needs_human' ? '需要你确认后才会继续（会话里回一句即可）。' : '角色会接手判断；可重试类不需要人介入。'),
+    ],
+  })
+}
+
+// ─────────────────────────── 发送 ───────────────────────────
+
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return {} } }
+const readEnvFile = (p) => {
+  const out = {}
+  try {
+    for (const line of readFileSync(p, 'utf8').split('\n')) {
+      const t = line.trim()
+      if (!t || t.startsWith('#') || !t.includes('=')) continue
+      const i = t.indexOf('=')
+      out[t.slice(0, i).trim()] = t.slice(i + 1).trim()
+    }
+  } catch { /* 文件不存在 = 空 */ }
+  return out
+}
+
+/**
+ * 收件人解析：`internal`=内部群（告警/流程/需人工）、`daily`=日报群；也接受显式 `oc_…`。
+ * 顺序：显式 chatId → 部署 env → config.json → 报错（**绝不猜一个群发出去**）。
+ */
+export function resolveSink(to, { env = process.env, dataDir = DATA_DIR } = {}) {
+  const cfg = readJson(join(dataDir, 'config.json'))
+  const fullEnv = { ...readEnvFile(join(dataDir, 'fulfillment.env')), ...env }
+  const dailyEnv = { ...readEnvFile(join(dataDir, 'daily-report.env')), ...env }
+  const key = String(to || 'internal').trim()
+  if (key.startsWith('oc_')) return { chatId: key, profile: fullEnv.NOTIFY_PROFILE || 'cli_a93b9354c6e35cd1', kind: 'explicit' }
+  if (key === 'daily') {
+    const chatId = dailyEnv.ML_DAILY_CHAT_ID || cfg.mlDailyChatId || ''
+    return { chatId, profile: dailyEnv.LARK_PROFILE || cfg.mlDailyAlertProfile || 'ml-daily', kind: 'daily' }
+  }
+  const chatId = fullEnv.FULL_INTERNAL_CHAT_ID || cfg.feishuChatId || ''
+  return { chatId, profile: fullEnv.NOTIFY_PROFILE || cfg.mlDailyAlertProfile || 'cli_a93b9354c6e35cd1', kind: 'internal' }
+}
+
+/** 真发：走 lark-cli 的 interactive 卡片通道（与日报同一条）。 */
+export function sendCard(cardJson, { chatId, profile, timeoutMs = 60000, bin = LARK_BIN } = {}) {
+  if (!chatId) throw new Error('缺少 chatId（用 --to internal|daily|oc_xxx 指定，或配好部署 env）')
+  if (!profile) throw new Error('缺少 profile（用 --profile 指定，或配 NOTIFY_PROFILE）')
+  const r = spawnSync(bin, ['--profile', String(profile), 'im', '+messages-send',
+    '--chat-id', String(chatId), '--msg-type', 'interactive',
+    '--content', JSON.stringify(cardJson), '--as', 'bot'],
+  { encoding: 'utf8', timeout: timeoutMs })
+  if (r.status !== 0) {
+    throw new Error(`lark-cli 卡片推送失败: ${(r.error?.message || r.stderr || r.stdout || '').slice(0, 300)}`)
+  }
+  return { ok: true, chatId, profile }
+}
+
+// ─────────────────────────── CLI ───────────────────────────
+
+const arg = (argv, name, dflt = '') => {
+  const i = argv.indexOf(`--${name}`)
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : dflt
+}
+const argAll = (argv, name) => argv.map((a, i) => (a === `--${name}` ? argv[i + 1] : null)).filter(Boolean)
+const parseResult = (s) => {
+  const [ticket, rest = ''] = String(s).split('=')
+  const [status, detail = ''] = rest.split('|')
+  return { ticket: ticket.trim(), status: (status || '').trim(), detail: detail.trim() }
+}
+
+export function buildFromArgv(argv = process.argv.slice(2)) {
+  const t = arg(argv, 'template', 'flow-result')
+  const common = { flow: arg(argv, 'flow'), flowTitle: arg(argv, 'flow-title') || arg(argv, 'title') }
+  if (t === 'flow-result') {
+    return flowResultCard({ ...common, results: argAll(argv, 'result').map(parseResult), ledger: arg(argv, 'ledger'), noteText: arg(argv, 'note') })
+  }
+  if (t === 'need-human') {
+    return needHumanCard({ ...common, caseId: arg(argv, 'case'), ticket: arg(argv, 'ticket'), reason: arg(argv, 'reason'), ask: arg(argv, 'ask') })
+  }
+  if (t === 'await-release') {
+    return awaitReleaseCard({ ...common, count: Number(arg(argv, 'count', '0')) || 0, samples: argAll(argv, 'sample'), gate: arg(argv, 'gate', '就绪'), noteText: arg(argv, 'note') })
+  }
+  if (t === 'failure-alert') {
+    return failureAlertCard({ ...common, caseId: arg(argv, 'case'), level: arg(argv, 'level', 'needs_agent'), error: arg(argv, 'error'), attempt: arg(argv, 'attempt'), max: arg(argv, 'max'), action: arg(argv, 'action') })
+  }
+  throw new Error(`未知模板: ${t}（可选 flow-result / need-human / await-release / failure-alert）`)
+}
+
+export function main(argv = process.argv.slice(2)) {
+  let cardJson
+  try {
+    cardJson = buildFromArgv(argv)
+  } catch (e) {
+    console.error(`❌ ${e.message}`)
+    return 2
+  }
+  const send = argv.includes('--send')
+  const to = arg(argv, 'to', 'internal')
+  const base = resolveSink(to)
+  const sink = { ...base, profile: arg(argv, 'profile') || base.profile }
+  if (!send) {
+    console.log(JSON.stringify({ dryRun: true, to, chatId: sink.chatId ? `${String(sink.chatId).slice(0, 8)}…` : '', profile: sink.profile, card: cardJson }, null, 2))
+    return 0
+  }
+  try {
+    const r = sendCard(cardJson, { chatId: sink.chatId, profile: sink.profile })
+    console.log(`✅ 卡片已发送（${r.chatId.slice(0, 8)}… / ${r.profile}）`)
+    return 0
+  } catch (e) {
+    console.error(`❌ ${e.message}`)
+    return 3
+  }
+}
+
+const isMain = isDirectRun(import.meta.url)
+if (isMain) process.exit(main())