@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow_config.py

@@ -0,0 +1,1024 @@
+#!/usr/bin/env python3
+"""flow_config —— **每流程运行时配置的唯一读取点**（引擎泛化的配置面）。
+
+为什么要有它（2026-09-16，P0 引擎泛化）：
+  泛化前，"并发上限 / 暂停开关 / 日志名 / 唤醒目标 preset / 提示词模板"这些**运行时参数**
+  硬编码在 `flow-trigger.sh`（`--flow wenyao-invoice`、`PAUSE_FLOW_TRIGGER`、`flow-trigger.log`）
+  和 `flow-trigger-wake.mjs`（`agentPreset:'argent-ml-invoice-wy'` + 内嵌提示词）里 ⇒ 加一条流程
+  就要改脚本、就会漏改。现在全部收进注册表，本模块是唯一读取点 + 缺省推导；
+  bash / node / python 一律通过它取配置（`--get` / `--json` / `--paths`）。
+
+配置分段（`scripts/flow-requirements.json#flows.<id>`）：
+  source       {base,table,identity,routing,required}   数据源与字段要求（既有段，不动）
+               · **多源变体**（2026-09-16 用户口径："开始用 legacy 表，后面用 lip 表，无论要求用
+                 什么我们都要适配"）⇒ `source.variants{<名>: {...}}` + `source.select`
+                 （`env:VAR` 或字面量，缺省 `source.default` 或第一个变体）+ `source.default`；
+                 解析结果放在输出的 `source`（含 `variant` 字段）与 `sourceVariant`。
+               · 表 id 可来自**部署环境**而非仓库：`baseEnv`/`tableEnv`（环境变量名）
+                 或 `baseRef`/`tableRef`（`路径#a.b` 引用，如 invoice-mapping.json）。
+  trigger      {intervalSec,wake,pauseSwitch,log,promptTemplate,
+                dispatch{preset,cwd,sessionIdFile}}      触发与唤醒
+  concurrency  {max,leaseMin}                            并发上限与租约
+  guards       {dryRunDefault,backup,audit,writeFields}  写入守卫（P3 用）
+  failures     {enabled,scanSec,maxPerCase,cooldownMin,maxPerRound}
+               「失败→唤醒角色」回路策略（P0.6）：默认 **enabled=false**；只有显式打开的流程
+               才会被引擎唤醒（当前仅 wenyao-invoice）。仅 needs_agent 类失败会唤醒。
+
+缺省推导（**新流程只写 source 也能跑起来**，运行时参数全部有缺省）：
+  pauseSwitch     → PAUSE_FLOW_<FLOW_ID 大写、`-`→`_`>
+  log             → flow-trigger-<flow>.log
+  promptTemplate  → flow-prompts/<flow>.md
+  sessionIdFile   → flow-dispatch-<flow>.json     （唤醒复用常驻会话，避免每轮 session/create）
+  dispatch.preset → argent-<role>                 （role 取自注册表）
+  dispatch.cwd    → ~/Code
+  lock            → flow-claim-<flow>.lock        （认领锁按流程分文件）
+  wake            → session（合法值只有 session|off；旧的"飞书 @ 唤醒"已废弃，不保留）
+
+用法：
+  python3 scripts/flow_config.py --list
+  python3 scripts/flow_config.py --flow wenyao-invoice --json
+  python3 scripts/flow_config.py --flow wenyao-invoice --get trigger.pauseSwitch
+  python3 scripts/flow_config.py --flow wenyao-invoice --paths --json
+  python3 scripts/flow_config.py --flow full --json --lax     # 缺部署配置也不报错（控制台用）
+退出码：0 成功；2 未知流程/参数错误。
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import pathlib
+import re
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+REGISTRY = HERE / 'flow-requirements.json'
+# P1（2026-09-29）：注册表改为「引擎级 base + 每条业务线一份」，合并与冲突判据在
+# flow_registry 里（唯一真源）。显式传 registry_path 时走 legacy 单文件（历史行为）。
+sys.path.insert(0, str(HERE))
+try:
+    import flow_registry  # noqa: E402
+except Exception:  # noqa: BLE001 —— 加载器缺失时退回单文件，避免整条链路瘫痪
+    flow_registry = None
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链 `ARGENT_DATA_DIR` →
+# `$DSH_HOME/argent` → `~/.dsh/argent`，与 JS 内核 `core/lib/argent-datadir.mjs` 同语义）。
+# 此前这里只认两级（**不看 DSH_HOME**）⇒ 只设 `DSH_HOME` 的隔离实例里插件写隔离目录，
+# 而 CLI/cron 直跑（flow_config/flow_claim/flow_triage…）读**生产**目录（2026-10-01 事故形态）。
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  —— 数据目录唯一判据（勿在此复制链）
+DATA_DIR = pathlib.Path(resolve_data_dir()['dir'])
+
+DEFAULTS = {
+    # B2（2026-09-24）：jitterSec = 每轮认领前随机等待的上限（秒）。固定 300s 整点起是最规律的
+    # 机器节拍；人工不会每次都在同一秒发起。可被注册表 flows.<id>.trigger.jitterSec 覆盖；
+    # 0 = 关闭（flow-trigger.sh 里另有 FLOW_TRIGGER_NO_JITTER=1 应急开关）。
+    'trigger': {'intervalSec': 300, 'jitterSec': 45, 'wake': 'session', 'mode': 'shadow'},
+    'concurrency': {'max': 2, 'leaseMin': 10},
+    'guards': {'dryRunDefault': True, 'backup': False, 'audit': False, 'writeFields': []},
+    'failures': {'enabled': False, 'scanSec': 60, 'maxPerCase': 3, 'cooldownMin': 15, 'maxPerRound': 2},
+    # 失败自动重试（用户口径方案 a，2026-10-13）：**可用性类**失败（唯一分类器判 retryable）
+    # 在上限 + 冷却约束下自动"重置后重建"，而不是等人工手跑。四个量的**唯一读取点**在这里
+    # （判据与守卫在 `scripts/flow-auto-retry.py`；⛔ 触发器与脚本都不得自带第二份默认值）。
+    'autoRetry': {'enabled': True, 'max': 2, 'cooldownMin': 20, 'perCycle': 2},
+}
+WAKE_MODES = ('session', 'off')
+# 本轮语义：real=真实写入生产；shadow=只读/零副作用（缺省 shadow —— 不宣称真实写入）
+WRITE_MODES = ('real', 'shadow')
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 配置中心：声明的 `default` 读取（2026-10-10，FULL 自动路径成功率修复批）
+# ══════════════════════════════════════════════════════════════════════════
+# **为什么需要它**：配置项的声明面（`configs/<域>.json` 引擎级 + `verticals/<id>/config.json`
+# 业务线级）是「有哪些可配项、默认值是多少」的**唯一真源**，而它的读取器
+# （`core/lib/config-catalog.mjs`）是 **Node 侧**实现 —— Python 侧（编排器/CLI）import 不到。
+# 若在 Python 里再写一个字面量默认值，同一个数就有两处真源 ⇒ 迟早漂移（本仓库反复踩的
+# "判据第二份"形态：门禁能证明"注册表与代码一致"，但证明不了"两个字面量恰好相等"）。
+#
+# ⛔ **它不是第二条解析链**：本函数**只**按 key 取声明的 `default` 一个字段，
+#    **不**解析 env / envfile / json / 机器文件的优先级 —— 那条链仍然只有 Node 读取器一份
+#    （`node scripts/config-explain.mjs --key <k>` 是它的只读出口）。
+# ✅ 生效链（与声明逐字一致，见 `configs/*.json#items[].todayChain`）：
+#    ① 进程环境变量 `<binding.env>` → ② 声明的 `default`。env **优先**（逃生阀：运维临时改大窗口）。
+def catalog_default(key: str, root: pathlib.Path | None = None):
+    """按 key 从配置声明面取 `default`（**只读声明，不解析链**）；取不到返回 `None`。
+
+    扫描面与 Node 读取器**同源**：`<root>/configs/*.json` + `<root>/verticals/*/config.json`。
+    ⛔ 读不到 / 声明非法 / 解析失败一律返回 `None`（调用方决定怎么保守），**不抛异常**。
+    """
+    import glob as _glob  # 局部 import：本模块被 CLI 高频调用，避免污染模块级命名空间
+    root = pathlib.Path(root) if root else HERE.parent
+    pats = [str(root / 'configs' / '*.json'),
+            str(root / 'verticals' / '*' / 'config.json')]
+    for pat in pats:
+        for fp in sorted(_glob.glob(pat)):
+            try:
+                doc = json.loads(pathlib.Path(fp).read_text(encoding='utf-8'))
+            except Exception:                                      # noqa: BLE001
+                continue
+            for it in (doc.get('items') or []):
+                if isinstance(it, dict) and it.get('key') == key:
+                    return it.get('default')
+    return None
+
+
+def _coerce_int(raw, dflt: int) -> int:
+    try:
+        return int(str(raw).strip())
+    except (TypeError, ValueError):
+        return dflt
+
+
+def _coerce_bool(raw, dflt: bool) -> bool:
+    """声明里的布尔（缺省值取 `dflt`）。字符串按常见真/假写法认，认不出 ⇒ 取缺省（保守）。"""
+    if raw is None:
+        return dflt
+    if isinstance(raw, bool):
+        return raw
+    s = str(raw).strip().lower()
+    if s in ('1', 'true', 'yes', 'on'):
+        return True
+    if s in ('0', 'false', 'no', 'off', ''):
+        return False
+    return dflt
+
+
+def resolve_auto_retry(spec: dict) -> dict:
+    """「失败自动重试」的四个量 —— **唯一读取点**（2026-10-13，用户口径方案 a）。
+
+    背景：可用性类失败（网络/限流/浏览器瞬时类，由 `flow_failure.classify` 判 `retryable`）
+    落到台账 `failed` → `blocked` 之后，触发器只会报"需人工"，从此不再自动跑（现场两条票就是
+    人工手跑回来的）。方案 a = 这类失败在**上限 + 冷却**约束下自动重试。
+
+    生效链：注册表 `flows.<id>.autoRetry.<键>`（按流程覆盖，可选）→ 本模块 `DEFAULTS['autoRetry']`。
+    ⛔ 调用方（`scripts/flow-auto-retry.py` / `scripts/flow-trigger.sh`）**不得自带第二份默认值**：
+    需要这几个数就只经 `flow_config --get autoRetry.<键>` 取；本段缺失即"配置读取点版本过旧"，
+    调用方应停住并点名，而不是猜一个数继续。
+    """
+    raw = (spec or {}).get('autoRetry') or {}
+    if not isinstance(raw, dict):
+        die(f'autoRetry 声明非法（需要对象）: {raw!r}')
+    d = DEFAULTS['autoRetry']
+    out = {
+        'enabled': _coerce_bool(raw.get('enabled'), d['enabled']),
+        'max': _coerce_int(raw.get('max') if raw.get('max') is not None else d['max'], d['max']),
+        'cooldownMin': _coerce_int(raw.get('cooldownMin') if raw.get('cooldownMin') is not None
+                                   else d['cooldownMin'], d['cooldownMin']),
+        'perCycle': _coerce_int(raw.get('perCycle') if raw.get('perCycle') is not None
+                                else d['perCycle'], d['perCycle']),
+    }
+    if out['max'] < 1 or out['perCycle'] < 1 or out['cooldownMin'] < 0:
+        die(f'autoRetry 取值非法: {out}（max/perCycle ≥ 1、cooldownMin ≥ 0）')
+    return out
+
+
+def appointment_max_day() -> int:
+    """步骤4 顺延窗口（天）——**配置中心唯一入口**：`advanced.appointment.max_day`。
+
+    生效链：`ARGENT_APPOINTMENT_MAX_DAY`（进程 env，**优先**）→ 声明 `default`。
+    ⛔ **行为变更（2026-10-10）**：默认值 3 → **5**。理由（用户亲历 + 我方实测）：
+    约 1/3 的 FULL 失败与"最近几天都被平台拒"相关，窗口=3（最多顺延 2 天）**够不到**
+    可约日期；手动串行路径显式用 10 跑 6 票 8/8 成功。取 5 是"够用且不至于把店铺窗口
+    耗在无望的日期上"的折中；窗口越大会线性增加单票最长耗时（每天一次导航 + 最多 3 次提交）。
+    运维要改回旧行为：`ARGENT_APPOINTMENT_MAX_DAY=3`（env 优先，不必改声明）。
+    """
+    raw = os.environ.get('ARGENT_APPOINTMENT_MAX_DAY')
+    if raw is not None and str(raw).strip() != '':
+        return max(1, min(90, _coerce_int(raw, 5)))
+    d = catalog_default('advanced.appointment.max_day')
+    return max(1, min(90, _coerce_int(d, 5) if d is not None else 5))
+
+
+def die(msg: str) -> None:
+    """错误口径：一律 stderr + exit 2（与 flow_case/flow_source/flow_claim 一致）。"""
+    print(msg, file=sys.stderr)
+    raise SystemExit(2)
+
+
+
+def _resolve_prompt_path(rel: str) -> pathlib.Path:
+    """提示词路径解析（P2a，2026-09-29）。
+
+    历史缺省是 `flow-prompts/<flow>.md`（相对 `scripts/`）；业务线落位后注册表声明的是
+    **仓库根相对**路径（`verticals/<id>/prompts/<flow>.md`）。两种都要认 ——
+    否则业务线提示词会被解析成 `scripts/verticals/...`（实测踩过），投递时报找不到模板。
+    """
+    p = pathlib.Path(str(rel))
+    if p.is_absolute():
+        return p
+    for base in (HERE.parent, HERE):
+        cand = base / p
+        if cand.exists():
+            return cand
+    return (HERE.parent if str(rel).startswith('verticals/') else HERE) / p
+
+def load_registry(registry_path=None) -> dict:
+    """读 flows（历史形状）。P1 起经 flow_registry 合并 base + verticals。"""
+    if flow_registry is not None:
+        try:
+            return flow_registry.load_flows(registry_path)
+        except flow_registry.Conflict as exc:
+            die(f'流程注册表合并失败: {exc}')
+        except SystemExit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            die(f'读取流程注册表失败: {exc}')
+    p = pathlib.Path(registry_path) if registry_path else REGISTRY
+    try:
+        doc = json.loads(p.read_text(encoding='utf-8'))
+    except Exception as exc:
+        die(f'读取流程注册表失败: {p}: {exc}')
+    flows = doc.get('flows')
+    if not isinstance(flows, dict):
+        die(f'流程注册表格式错误（缺 flows 对象）: {p}')
+    return flows
+
+
+def load_capabilities(registry_path=None) -> dict:
+    """读注册表文档里的 `capabilities` 段（与 `flows` 同级）。
+
+    ⚠️ `load_registry()` 只返回 `flows`（历史形状，多处依赖）⇒ 能力层必须单独取，
+    否则 `_derive` 里会看到"未知 capability"（2026-09-20 实现步骤 3 时踩到）。
+    """
+    if flow_registry is not None:
+        try:
+            return flow_registry.load_capabilities(registry_path)
+        except Exception:  # noqa: BLE001 —— 能力层缺失不该拖垮配置解析
+            return {}
+    p = pathlib.Path(registry_path) if registry_path else REGISTRY
+    try:
+        doc = json.loads(p.read_text(encoding='utf-8'))
+    except Exception:
+        return {}
+    caps = doc.get('capabilities')
+    return caps if isinstance(caps, dict) else {}
+
+
+def flow_ids(registry_path=None) -> list:
+    return sorted(load_registry(registry_path).keys())
+
+
+
+def _resolve_env_path(rel_or_abs: str) -> pathlib.Path:
+    """env 文件解析（P2a，2026-09-29）：**规范路径优先、旧平铺路径兜底**。
+
+    规范：`verticals/<id>/env/<name>.env`（入库相对路径，落在仓库内或 DATA_DIR 下均可）。
+    兜底：`~/.dsh/argent/<name>.env`（历史平铺，两条业务线同机时会撞名 ⇒ 逐阶段退休）。
+    迁移期两种都要能读，否则"改注册表"那一刻流程会读不到凭据。
+    """
+    p = pathlib.Path(os.path.expanduser(rel_or_abs))
+    if p.is_absolute():
+        return p
+    if rel_or_abs.startswith('verticals/'):
+        for base in (HERE.parent, DATA_DIR):
+            cand = base / rel_or_abs
+            if cand.exists():
+                return cand
+        # 规范路径不存在 ⇒ 回退旧平铺文件（`~/.dsh/argent/<name>.env`）：装机脚本/历史机器
+        # 可能仍把 env 写在旧位置，宁可用上也不能"静默没有凭据"（strict 时会打印路径）。
+        flat = DATA_DIR / p.name
+        if flat.exists():
+            return flat
+        return DATA_DIR / rel_or_abs            # 两处都没有：按规范路径报错
+    # 旧平铺名：若规范位置已有同名文件（verticals/*/env/），优先用它
+    for hit in sorted((DATA_DIR / 'verticals').glob(f'*/env/{p.name}')):
+        return hit
+    return DATA_DIR / p
+
+
+def load_env_file(rel_or_abs: str, strict: bool = False) -> int:
+    """加载部署环境文件（KEY=VALUE 逐行；`#` 注释；已存在的环境变量**不覆盖**）。
+
+    为什么：FULL 的表 id/凭据放在 `~/.dsh/argent/fulfillment.env`（不进仓库、不进进程 env），
+    流程要能读到它才能工作。返回加载的键数；文件不存在时 strict=False 静默返回 0。
+    """
+    if not rel_or_abs:
+        return 0
+    path = _resolve_env_path(str(rel_or_abs))
+    if not path.exists():
+        if strict:
+            die(f'流程声明的环境文件不存在: {path}')
+        return 0
+    n = 0
+    try:
+        for raw in path.read_text(encoding='utf-8').splitlines():
+            line = raw.strip()
+            if not line or line.startswith('#') or '=' not in line:
+                continue
+            k, _, v = line.partition('=')
+            k, v = k.strip(), v.strip().strip('"').strip("'")
+            if k and k not in os.environ:
+                os.environ[k] = v
+                n += 1
+    except Exception as exc:
+        if strict:
+            die(f'读取环境文件失败 {path}: {exc}')
+    return n
+
+
+def _read_ref(ref: str, strict: bool = True) -> str:
+    """解析 `路径#a.b.c` 引用（数据目录里的部署配置，如 invoice-mapping.json）。"""
+    path_part, _, dotted = ref.partition('#')
+    p = pathlib.Path(os.path.expanduser(path_part))
+    try:
+        cur = json.loads(p.read_text(encoding='utf-8'))
+    except Exception as exc:
+        if not strict:
+            return ''
+        die(f'读取配置引用失败: {p}: {exc}')
+    for part in [x for x in dotted.split('.') if x]:
+        if not isinstance(cur, dict) or part not in cur:
+            if not strict:
+                return ''
+            die(f'配置引用缺键: {ref}（在 {part} 处）')
+        cur = cur[part]
+    return str(cur)
+
+
+def resolve_source(flow_id: str, spec: dict, strict: bool = True) -> tuple:
+    """把 source 解析成**当前生效的一份**：变体选择 + 表 id 的 env/ref 解析。
+
+    返回 (resolved_source, variant_name|None, variants_raw)。
+    """
+    src = dict(spec.get('source') or {})
+    variants = src.pop('variants', None)
+    select = src.pop('select', None)
+    default = src.pop('default', None)
+    if not variants:
+        return _resolve_ids(flow_id, src, strict), None, {}
+    if not isinstance(variants, dict) or not variants:
+        die(f'流程 {flow_id} 的 source.variants 必须是非空对象')
+    if isinstance(select, str) and select.startswith('env:'):
+        var = select[4:]
+        active = os.environ.get(var) or default or next(iter(variants))
+    else:
+        active = (select if isinstance(select, str) and select else None) or default or next(iter(variants))
+    if active not in variants:
+        die(f'流程 {flow_id} 的源变体非法: {active}（可选: {", ".join(variants)}；选择器: {select or "缺省"}）')
+    merged = {**src, **(variants[active] or {})}
+    merged['variant'] = active
+    return _resolve_ids(flow_id, merged, strict), active, variants
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 宿主排程声明（P1-A，2026-10-12）—— `trigger.schedule` 的**唯一运行期读取点**
+# ══════════════════════════════════════════════════════════════════════════
+# 为什么要有：把某条流程的触发从「每 5 分钟轮询」改成「宿主原生 daily 排程」时，"排程器该读哪一段"
+# 必须有**唯一**答案，否则装机脚本、运维命令、声明门禁各读一份 ⇒ 迟早漂移。这里与
+# `scripts/vertical-lint.mjs#schedule` **同一套判据**（那边是装配期门禁，这边是运行期读取）：
+#   · 键白名单（⛔ 不许把业务规则/字段名/阈值写进排程段 —— 那属 L0/L1）；
+#   · 选择器自洽（kind/time/timeZone/weekdays/expression/everySecondsFrom）；
+#   · `taskTitle` 1..120 且无首尾空白（宿主硬约束）；
+#   · `promptFile` **必须存在**且是**静态**指令（宿主在创建任务时固定 prompt）；
+#   · `onPause` ∈ deactivate|prompt-guard。
+# ⛔ 周期**不在**这一段：`kind=every` 时用 `everySecondsFrom: "intervalSec"` 指回 `trigger.intervalSec`
+#    （周期只有一份真源，本仓库为"第二份真源"付过多次代价）。
+SCHEDULE_KEYS = ('enabled', 'kind', 'time', 'timeZone', 'weekdays', 'expression', 'at',
+                 'everySecondsFrom', 'taskTitle', 'promptFile', 'onPause')
+SCHEDULE_KINDS = ('every', 'daily', 'weekly', 'cron', 'at')
+SCHEDULE_ON_PAUSE = ('deactivate', 'prompt-guard')
+_SCHEDULE_TIME_RE = re.compile(r'^([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,3})?)?$')
+_SCHEDULE_BAD_CRON_RE = re.compile(r'[LW#]|\b(?:JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|MON|TUE|WED|THU|FRI|SAT|SUN)\b|^@')
+# `{{name}}` 形态的模板占位符（宿主 prompt 创建时固定 ⇒ 静态指令里 ⛔ 不许出现）
+_SCHEDULE_TEMPLATE_RE = re.compile(r'\{\{\s*[A-Za-z_][\w.-]*\s*\}\}')
+
+
+def _resolve_vertical_path(flow_id: str, rel: str) -> pathlib.Path:
+    """业务线文件的路径解析（P1-A）：**相对业务线目录**优先，也接受 `verticals/<id>/…` 的仓库根相对写法。
+
+    `flow_id` 是规范 id（`<vertical>.<local>`）⇒ 业务线 id 取点号前的那一段。
+    两种写法都认的理由：注册表里既有 `verticals/<id>/prompts/x.md`（trigger.promptTemplate 的历史形态），
+    P1-A 的 `schedule.promptFile` 用的是业务线内相对路径（`prompts/x.md`）—— 同一个解析器认两种，
+    好过在两处各写一套拼接规则。
+    """
+    p = pathlib.Path(str(rel))
+    if p.is_absolute():
+        return p
+    if str(rel).startswith('verticals/'):
+        return HERE.parent / p
+    vid = str(flow_id).split('.', 1)[0] if '.' in str(flow_id) else ''
+    if vid:
+        return HERE.parent / 'verticals' / vid / p
+    return HERE.parent / p
+
+
+def resolve_schedule(flow_id: str, spec: dict, strict: bool = True) -> dict:
+    """解析并校验 `trigger.schedule`（未声明 ⇒ 返回 `{}`，不产生任何副作用）。
+
+    `strict=True`（运行路径）⇒ 声明非法**响亮失败**（exit 2）；`strict=False`（`--list` 巡查）
+    ⇒ 不中断列表，把问题放进返回值 `_errors`（并保证**不静默**：调用方会打印）。
+    """
+    raw_t = spec.get('trigger') or {}
+    raw = raw_t.get('schedule')
+    if raw is None:
+        return {}
+    errs: list = []          # 致命：违反宿主硬约束或自相矛盾（会 die）
+    warns: list = []         # 响亮告警：**不许**因为一段尚未启用的排程声明把在跑的触发器打死
+    if not isinstance(raw, dict):
+        errs.append('trigger.schedule 必须是对象')
+        raw = {}
+    for k in raw:
+        if str(k).startswith('_') or k in SCHEDULE_KEYS:
+            continue
+        errs.append(f'trigger.schedule 未登记键 `{k}`（白名单：{" / ".join(SCHEDULE_KEYS)}）')
+    kind = str(raw.get('kind') or '')
+    if kind not in SCHEDULE_KINDS:
+        errs.append(f'trigger.schedule.kind={raw.get("kind")!r} 不在 {"|".join(SCHEDULE_KINDS)} 内')
+    enabled = raw.get('enabled')
+    if not isinstance(enabled, bool):
+        errs.append(f'trigger.schedule.enabled 必须是布尔（当前 {enabled!r}）')
+    if kind == 'every':
+        if str(raw.get('everySecondsFrom') or '') != 'intervalSec':
+            errs.append('trigger.schedule: kind=every 必须写 "everySecondsFrom": "intervalSec"（周期只有一份真源）')
+        iv = raw_t.get('intervalSec')
+        try:
+            ivn = int(iv)
+        except (TypeError, ValueError):
+            ivn = None
+        if ivn is None:
+            errs.append('trigger.schedule: kind=every 但 trigger.intervalSec 缺失 ⇒ 没有周期可用')
+        elif ivn < 60:
+            errs.append(f'trigger.schedule: trigger.intervalSec={ivn} < 60（宿主 every_seconds 硬下限）')
+    tz = raw.get('timeZone')
+    if kind in ('daily', 'weekly', 'cron'):
+        if not str(tz or ''):
+            errs.append(f'trigger.schedule: kind={kind} 必须显式给 timeZone（IANA）')
+        else:
+            try:
+                import zoneinfo as _zi                    # 3.9+ 标准库
+                _zi.ZoneInfo(str(tz))
+            except Exception:                             # noqa: BLE001 —— 含 tzdata 缺失的机器
+                errs.append(f'trigger.schedule.timeZone={tz!r} 不是可用的 IANA 时区')
+    if kind in ('daily', 'weekly') and not _SCHEDULE_TIME_RE.match(str(raw.get('time') or '')):
+        errs.append(f'trigger.schedule.time={raw.get("time")!r} 不是 `HH:mm:ss`')
+    if kind == 'weekly':
+        wd = raw.get('weekdays')
+        if not isinstance(wd, list) or not wd or any(not isinstance(d, int) or d < 1 or d > 7 for d in wd):
+            errs.append('trigger.schedule: kind=weekly 的 weekdays 必须是 1..7 的非空整数数组（ISO 周一=1）')
+    if kind == 'cron':
+        fields = str(raw.get('expression') or '').split()
+        if len(fields) != 5:
+            errs.append(f'trigger.schedule: kind=cron 的 expression 必须是**五字段** Vixie（当前 {len(fields)} 段）')
+        if _SCHEDULE_BAD_CRON_RE.search(str(raw.get('expression') or '')):
+            errs.append('trigger.schedule: cron 表达式用了宿主明确拒绝的方言（L/W/#、月份/星期英文名、@宏）')
+    if kind == 'at':
+        at_v = str(raw.get('at') or '')
+        if not at_v:
+            errs.append('trigger.schedule: kind=at 必须给绝对时点 `at`')
+    title = str(raw.get('taskTitle') or '')
+    if not title.strip():
+        errs.append('trigger.schedule 缺 taskTitle（宿主必填，去空白后 1..120 字符）')
+    elif title != title.strip():
+        errs.append('trigger.schedule.taskTitle 首尾有空白（宿主拒）')
+    elif len(title) > 120:
+        errs.append(f'trigger.schedule.taskTitle 超长（{len(title)} > 120，宿主硬上限）')
+    rel = str(raw.get('promptFile') or '')
+    pf_path = None
+    if not rel:
+        errs.append('trigger.schedule 缺 promptFile（静态轮次指令；⛔ 与 trigger.promptTemplate 是两份不同的东西）')
+    else:
+        pf_path = _resolve_vertical_path(flow_id, rel)
+        if not pf_path.exists():
+            # ⚠️ **只告警、不 die**（2026-10-12 定）：`promptFile` 是"**将来**建宿主任务时才用得上"的
+            # 资产，而 `flow_config` 是在跑的触发器**每一轮**都要走的路。若因为一个尚未启用的排程
+            # 声明把 `flow-trigger.sh` 打死，那是"用一段没在用的配置停掉在跑的生产路径"。
+            # 装配期的**硬判据在 vertical-lint**（声明期就拦住），运行期只要求"绝不静默"。
+            warns.append(f'trigger.schedule.promptFile 指向的文件不存在：{pf_path}'
+                         '（宿主排程尚未启用时可忽略；要启用必须先补齐该文件）')
+        else:
+            try:
+                body = pf_path.read_text(encoding='utf-8')
+                if _SCHEDULE_TEMPLATE_RE.search(body):
+                    errs.append('trigger.schedule.promptFile 含模板占位符（双花括号包住的名字）—— '
+                                '宿主在**创建任务时**就固定 prompt，占位符不会被替换')
+            except Exception as exc:                      # noqa: BLE001
+                warns.append(f'trigger.schedule.promptFile 读不了：{exc}')
+    on_pause = str(raw.get('onPause') or '')
+    if on_pause not in SCHEDULE_ON_PAUSE:
+        errs.append(f'trigger.schedule.onPause={raw.get("onPause")!r} 不在 {"|".join(SCHEDULE_ON_PAUSE)} 内')
+    if enabled is True:
+        for need in ('kind', 'taskTitle', 'promptFile'):
+            if not raw.get(need):
+                errs.append(f'trigger.schedule: enabled=true 必须同时给 `{need}`')
+    if errs and strict:
+        die(f'流程 {flow_id} 的 trigger.schedule 声明非法：\n    - ' + '\n    - '.join(errs))
+    out = {
+        'enabled': enabled is True,
+        'kind': kind,
+        'time': raw.get('time'),
+        'timeZone': raw.get('timeZone'),
+        'weekdays': raw.get('weekdays'),
+        'expression': raw.get('expression'),
+        'at': raw.get('at'),
+        'everySecondsFrom': raw.get('everySecondsFrom'),
+        'taskTitle': title,
+        'promptFile': rel,
+        'promptPath': str(pf_path) if pf_path else '',
+        'onPause': on_pause,
+    }
+    if warns:
+        out['_warnings'] = warns
+        print(f'⚠️ 流程 {flow_id} 的 trigger.schedule 声明有告警：' + '；'.join(warns), file=sys.stderr)
+    if errs and not strict:
+        out['_errors'] = errs
+        print(f'⚠️ 流程 {flow_id} 的 trigger.schedule 声明有问题（非严格模式，继续）：'
+              + '；'.join(errs), file=sys.stderr)
+    return out
+
+
+def schedule_declaration(registry_path=None, strict: bool = True) -> dict:
+    """**「定时怎么来」的 Python 侧唯一读取点**（0.6.0 W8）—— 读合并注册表的 `schedule` 段。
+
+    ⭐ 判据**不在这里**：声明面 = 注册表顶层 `schedule`（引擎级 base：`scripts/flow-requirements.json`），
+    唯一判据实现 = `scripts/lib/schedule-mechanism.mjs#resolveScheduleMechanism()`
+    （本函数只**读**、只**归一化**，⛔ 不重写判据、⛔ 不写任何文件）。
+    与 Node 侧的 `scripts/lib/schedule-mechanism.mjs#declaredScheduleMechanism()` 读的是**同一份**
+    合并注册表（`flow_registry.py` 是合并的唯一真源）。
+
+    返回结构（`--schedule-declaration` 的原样输出）::
+
+        {"source": "...", "mechanism": "auto|native|activation-shim|none",
+         "jobs": {"source","labelPrefix","platform","installCommand"}, "flows": [...]}
+
+    未声明 `schedule` 段 ⇒ 返回**中性默认**（`mechanism="auto"` + 本仓库的垫片口径），
+    ⛔ 不报错（老树/旧注册表是合法输入），但 `_note` 里写明"声明段缺失"。
+    """
+    doc = {}
+    if flow_registry is not None:
+        try:
+            doc = flow_registry.load_doc(registry_path) if hasattr(flow_registry, 'load_doc') \
+                else flow_registry.merge()
+        except SystemExit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            die(f'读取流程注册表失败（schedule 声明面）: {exc}')
+    else:
+        path = pathlib.Path(registry_path) if registry_path else REGISTRY
+        try:
+            doc = json.loads(path.read_text(encoding='utf-8'))
+        except Exception as exc:  # noqa: BLE001
+            die(f'读取流程注册表失败（schedule 声明面）: {path}: {exc}')
+    raw = doc.get('schedule') if isinstance(doc, dict) else None
+    if raw is not None and not isinstance(raw, dict):
+        die('注册表 `schedule` 段必须是对象')
+    raw = raw or {}
+    mech = raw.get('mechanism', 'auto')
+    allowed = ('auto', 'native', 'activation-shim', 'none')
+    if mech not in allowed:
+        die(f'注册表 schedule.mechanism={mech!r} 不在 {"|".join(allowed)} 内'
+            f'（唯一声明点：scripts/flow-requirements.json#schedule）')
+    rj = raw.get('jobs') if isinstance(raw.get('jobs'), dict) else {}
+    jobs = {
+        'source': str(rj.get('source') or 'scripts/flow-timers.sh'),
+        'labelPrefix': str(rj.get('labelPrefix') or 'com.whyshu.flow-trigger'),
+        'platform': str(rj.get('platform') or 'darwin'),
+        'installCommand': str(rj.get('installCommand')
+                              or 'bash {repo}/scripts/flow-timers.sh install --flow {flow}'),
+    }
+    install_tpl = jobs['installCommand'].replace('{repo}', str(HERE.parent))
+    # 逐流程 job（**周期/日志/暂停开关** 只从 load_config 取 —— 那是这些字段的唯一读取点）
+    reg = load_registry(registry_path)
+    aliases = (doc.get('aliases') or {}) if isinstance(doc, dict) else {}
+    back = {v: k for k, v in aliases.items()}
+    flows = []
+    for canonical in sorted(reg):
+        try:
+            cfg = load_config(canonical, registry_path=registry_path, strict=False)
+        except SystemExit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            if strict:
+                die(f'流程 {canonical} 的配置读不到（schedule 声明面需要它）: {exc}')
+            continue
+        t = cfg.get('trigger') or {}
+        sch = t.get('schedule')
+        if not isinstance(sch, dict):
+            continue
+        local = back.get(canonical, canonical.split('.')[-1])
+        label = f"{jobs['labelPrefix']}-{local}"
+        flows.append({
+            'flowId': canonical,
+            'localId': local,
+            'label': label,
+            'enabled': sch.get('enabled') is True,
+            'kind': str(sch.get('kind') or ''),
+            'taskTitle': str(sch.get('taskTitle') or ''),
+            'promptFile': str(sch.get('promptPath') or sch.get('promptFile') or ''),
+            'onPause': str(sch.get('onPause') or ''),
+            'intervalSec': t.get('intervalSec'),
+            'jitterSec': t.get('jitterSec'),
+            'pauseSwitch': str((cfg.get('paths') or {}).get('pauseSwitch') or ''),
+            'pauseSwitchLegacy': str((cfg.get('paths') or {}).get('pauseSwitchLegacy') or ''),
+            'log': str((cfg.get('paths') or {}).get('log') or ''),
+            'installCommand': install_tpl.replace('{flow}', local).replace('{label}', label),
+        })
+    note = raw.get('_note')
+    out = {
+        'source': 'registry:schedule',
+        'declared': bool(raw),
+        'mechanism': mech,
+        'onConflict': str(raw.get('onConflict') or 'refuse'),
+        'jobs': jobs,
+        'flows': flows,
+        'judge': 'scripts/lib/schedule-mechanism.mjs#resolveScheduleMechanism（唯一判据实现）',
+    }
+    if note:
+        out['_note'] = note
+    else:
+        out['_note'] = '注册表未声明 `schedule` 段 ⇒ 按中性默认（auto + 本仓库垫片口径）；' \
+                        '声明面唯一落点是 scripts/flow-requirements.json#schedule'
+    return out
+
+
+def _resolve_ids(flow_id: str, src: dict, strict: bool = True) -> dict:
+    """表 id 解析优先级：env > ref > 字面量。
+
+    `strict=True`（运行路径）：部署配置缺失 ⇒ 立刻 exit 2（早失败胜过静默用错表）。
+    `strict=False`（`--list` 巡查）：把未解析的键标成空串并留 `*Unresolved`，绝不中断列表。
+    """
+    out = dict(src)
+    if out.get('envFile'):
+        load_env_file(str(out['envFile']), strict=False)   # 部署凭据：先加载再解析表 id
+    for key in ('base', 'table'):
+        env_key = out.get(f'{key}Env')
+        ref = out.get(f'{key}Ref')
+        if env_key:
+            val = os.environ.get(str(env_key))
+            if not val:
+                if strict:
+                    die(f'流程 {flow_id} 需要环境变量 {env_key}（{key}），当前未设置')
+                out[f'{key}Unresolved'] = str(env_key)
+            out[key] = val or ''
+        elif ref:
+            val = _read_ref(str(ref), strict)
+            if not val and not strict:
+                out[f'{key}Unresolved'] = str(ref)
+            out[key] = val
+        out.pop(f'{key}Env', None)
+        out.pop(f'{key}Ref', None)
+    # identity（用哪个 bot 身份读/写这张表）同样是**部署事实** ⇒ 允许用 env 覆盖声明的缺省值。
+    # 2026-09-17 用户口径：FULL 现在以 lip 表为准，注册表要同时在两台机器上跑，各自身份 profile 名
+    # 可能不同（客户机用自家 bot），故引入 `identityEnv`；未设置时**沿用声明里的 identity** ——
+    # 宁可读表时因权限而响亮失败（91403），也不要在这里提前把流程判死。
+    id_env = out.get('identityEnv')
+    if id_env:
+        val = os.environ.get(str(id_env))
+        if val:
+            out['identity'] = val
+        else:
+            out['identityUnresolved'] = str(id_env)
+        out.pop('identityEnv', None)
+    return out
+
+
+def _derive(flow_id: str, spec: dict, caps: dict | None = None, caps_from_doc: bool = False) -> dict:
+    role = str(spec.get('role') or flow_id)
+    return {
+        'pauseSwitch': 'PAUSE_FLOW_' + flow_id.upper().replace('-', '_'),
+        'log': f'flow-trigger-{flow_id}.log',
+        'promptTemplate': f'flow-prompts/{flow_id}.md',
+        'sessionIdFile': f'flow-dispatch-{flow_id}.json',
+        'preset': f'argent-{role}',
+        'cwd': '~/Code',
+        'lock': f'flow-claim-{flow_id}.lock',
+    }
+
+
+def resolve_flow_id(flow_id: str, registry_path=None) -> str:
+    """别名 → 规范 id（P2a）：业务线落位后旧 id（`full`）仍可用，避免全仓库/全机器改名。"""
+    if flow_registry is None:
+        return flow_id
+    try:
+        return flow_registry.resolve_flow_id(flow_id, flow_registry.load_doc(registry_path))
+    except Exception:  # noqa: BLE001 —— 解析器不可用时按原样处理（历史行为）
+        return flow_id
+
+
+def load_config(flow_id: str, registry=None, registry_path=None, strict: bool = True) -> dict:
+    """合并缺省后的流程配置。registry 可直接传 dict（测试/批量用，避免重复读盘）。
+
+    `strict=False` 只用于 `--list` 这类**巡查**场景（缺部署环境变量时标 `*Unresolved` 而不中断）。
+    """
+    reg = registry if registry is not None else load_registry(registry_path)
+    # 能力层与 flows 同级；registry 直传（测试夹具/批量）时拿不到 ⇒ 传 {} 跳过能力检查
+    caps = load_capabilities(registry_path) if registry is None else {}
+    caps_from_doc = registry is None
+    # ── 别名解析（P2a，2026-09-29）：业务线落位后规范 id 是 `<vertical>.<flow>`，
+    # 而全仓库/全机器的旧调用点仍写短名。别名让两者同时可用，避免一次性大改名
+    # （改名要动 10+ 个生产脚本与机器配置，风险远大于收益）。显式传 registry 时不解析。
+    canonical = resolve_flow_id(flow_id, registry_path) if registry is None else flow_id
+    spec = reg.get(canonical)
+    if spec is None:
+        hint = f'（`{flow_id}` 解析为 `{canonical}`）' if canonical != flow_id else ''
+        die(f'未知流程: {flow_id}{hint}（可用: {", ".join(sorted(reg)) or "无"}）')
+    if not isinstance(spec, dict):
+        die(f'流程 {flow_id} 的配置不是对象')
+
+    # ── 集成层（2026-09-20 迭代2）：声明的货代适配器必须存在、货代写法必须与路由一致 ──
+    # 为什么在配置解析期就校验：货代细节散落曾是"接一个新货代要改 9 处"的根因；
+    # 声明与实现对不上（如 routing.match 改了、适配器没改）必须**当场响亮失败**。
+    integ = str(spec.get('integration') or '')
+    if integ:
+        _integ_dir = pathlib.Path(__file__).resolve().parent / 'integrations' / integ
+        _adapter = _integ_dir / 'adapter.py'
+        if not _adapter.exists():
+            die(f'流程 {flow_id} 声明了 integration={integ!r}，但适配器不存在：{_adapter}')
+        try:
+            import importlib.util as _ilu
+            _sp = _ilu.spec_from_file_location(f'integration_{integ}', _adapter)
+            _mod = _ilu.module_from_spec(_sp)
+            _sp.loader.exec_module(_mod)
+        except Exception as exc:  # noqa: BLE001
+            die(f'流程 {flow_id} 的集成适配器加载失败（{integ}）：{exc}')
+        _match = str((spec.get('routing') or {}).get('match') or '')
+        _carrier = str(getattr(_mod, 'CARRIER', '') or '')
+        if _match and _carrier and _match != _carrier:
+            die(f'流程 {flow_id} 的 routing.match={_match!r} 与适配器 CARRIER={_carrier!r} 不一致\n'
+                f'    ⇒ 二者必须同源（适配器是货代事实的唯一出处）')
+        # P2a：业务线落位后规范 id 带前缀（`<vertical>.<flow>`），而适配器里写的可能仍是旧名
+        # ⇒ 用别名解析后再比（回写守卫按流程 id 解析目标，两种写法都指向同一条流程）。
+        _wb = str(getattr(_mod, 'WRITEBACK_FLOW', '') or '')
+        if _wb != flow_id and resolve_flow_id(_wb, registry_path) != flow_id:
+            die(f'流程 {flow_id} 的适配器 WRITEBACK_FLOW='
+                f'{getattr(_mod, "WRITEBACK_FLOW", "")!r} 与流程 id 不一致（回写守卫按流程 id 解析目标）')
+
+    # ── capability 层（2026-09-20 迭代1-步骤3）────────────────────────────────────
+    # 同一 capability 的多个 flow 必须共享共同规则；**差异必须显式写在 flow.overrides 里**。
+    # 这里做两件事：① 把 capability 的共同声明合并进本次解析结果（缺省继承）；
+    #              ② 若 flow 自己声明了与 capability **冲突**的值且未在 overrides 里登记 ⇒ 拒绝。
+    # 为什么：两条发票流程此前已静默漂移（required 20 vs 8、guards.writeFields 一方缺失、
+    # 暂停开关命名不一）——漂移只能靠"看见"来治理，不能靠自觉。
+    caps = caps if caps is not None else {}
+    # 只有"从注册表文档读到能力层"时才做未知-capability 校验 —— 调用方直接传 flows 字典
+    # （测试夹具 / --list 的旧路径）时结构上就没有 capabilities，不该误报。
+    _caps_known = bool(caps_from_doc or caps)
+    cap_id = str(spec.get('capability') or '')
+    ov = spec.get('overrides') or {}
+    cap = caps.get(cap_id) or {}
+    if cap_id and not cap and _caps_known:
+        die(f'流程 {flow_id} 声明了未知 capability={cap_id!r}（可用: '
+            f'{", ".join(k for k in caps if not k.startswith("_")) or "无"}）')
+    if cap_id and not cap and not _caps_known:
+        cap = {}          # 结构上无法校验 ⇒ 跳过能力检查（不误报）
+    if cap:
+        # ① gate.equals：flow 未声明则继承；声明了但不同 ⇒ 必须显式 override
+        flow_gate = ((spec.get('source') or {}).get('pick') or {}).get('equals') or {}
+        cap_gate = (cap.get('gate') or {}).get('equals') or {}
+        if cap_gate and not flow_gate and 'gate' not in ov:
+            spec.setdefault('source', {}).setdefault('pick', {})['equals'] = dict(cap_gate)
+        elif cap_gate and flow_gate and flow_gate != cap_gate and 'gate' not in ov:
+            die(f'流程 {flow_id} 的 pick.equals 与 capability「{cap_id}」冲突且未在 overrides 声明\n'
+                f'    flow      = {flow_gate}\n    capability= {cap_gate}\n'
+                f'    ⇒ 要么改成一致，要么在 flow.overrides 里加 "gate" 说明差异')
+        # ①b 排除规则（excludeEquals / excludeAllPresent）：与 gate.equals 同一套纪律 ——
+        # 能力层声明"哪些行已经做完了、不该进候选"，流程未声明则继承；声明了但不同 ⇒ 必须
+        # 显式写 overrides。为什么放能力层：两个发票流程读的是同一张 lip 表，判据必须一致。
+        cap_ex = cap.get('gate') or {}
+        flow_pick = spec.setdefault('source', {}).setdefault('pick', {})
+        for ek in ('excludeEquals', 'excludeAllPresent'):
+            cap_val = cap_ex.get(ek)
+            if not cap_val:
+                continue
+            flow_val = flow_pick.get(ek)
+            if flow_val is None and ek not in ov:
+                flow_pick[ek] = cap_val
+            elif flow_val is not None and flow_val != cap_val and ek not in ov:
+                die(f'流程 {flow_id} 的 pick.{ek} 与 capability「{cap_id}」冲突且未在 overrides 声明\n'
+                    f'    flow      = {flow_val}\n    capability= {cap_val}\n'
+                    f'    ⇒ 排除判据是能力的共同属性（两个发票流程读同一张表），不要各写一套')
+        # ② guards.writeFields：同上
+        cap_wf = list(cap.get('writeFields') or [])
+        flow_wf = list((spec.get('guards') or {}).get('writeFields') or [])
+        if cap_wf:
+            if not flow_wf and 'writeFields' not in ov:
+                # 继承：写回 spec（`raw_g` 在下方才取，届时能读到）
+                spec.setdefault('guards', {})['writeFields'] = list(cap_wf)
+            elif flow_wf and flow_wf != cap_wf and 'writeFields' not in ov:
+                die(f'流程 {flow_id} 的 guards.writeFields 与 capability「{cap_id}」冲突且未声明 overrides\n'
+                    f'    flow      = {flow_wf}\n    capability= {cap_wf}')
+        # ②b guards.backup/audit：能力层声明 ⇒ flow 继承；声明冲突且未 overrides ⇒ 拒绝
+        cap_g = cap.get('guards') or {}
+        flow_g = spec.get('guards') or {}
+        for gk in ('backup', 'audit'):
+            if gk not in cap_g:
+                continue
+            if gk not in flow_g:
+                spec.setdefault('guards', {})[gk] = bool(cap_g[gk])
+            elif bool(flow_g[gk]) != bool(cap_g[gk]) and f'guards.{gk}' not in ov:
+                die(f'流程 {flow_id} 的 guards.{gk}={bool(flow_g[gk])} 与 capability「{cap_id}」'
+                    f'声明的 {bool(cap_g[gk])} 冲突且未在 overrides 声明\n'
+                    f'    ⇒ 守卫姿态是能力的共同属性（写手只有一份），不要每个流程各写一套')
+        # ③ requiredCommon：flow 必须至少覆盖共同必需字段
+        # ⚠️ 只比 **input** 字段：state（状态位）/output（产物）/derived（生成器提供）由能力层
+        #    的 stateFields/writeFields/producedFields 声明，不属于"运营要填什么"的差异。
+        common = list(cap.get('requiredCommon') or [])
+        input_names = {str(r.get('name')) for r in (spec.get('required') or [])
+                       if str(r.get('role') or '') == 'input'}
+        miss = [c for c in common if c not in input_names]
+        if miss:
+            die(f'流程 {flow_id} 缺少 capability「{cap_id}」的共同必需字段: {miss}')
+        # ④ 超出共同部分的 input 字段必须显式登记（否则就是漂移）
+        extra = sorted(input_names - set(common))
+        declared = sorted(str(x) for x in (ov.get('requiredExtra') or []))
+        undeclared = [x for x in extra if x not in declared]
+        if undeclared:
+            die(f'流程 {flow_id} 有未登记的能力差异字段 {undeclared} ⇒ 请在 flow.overrides.requiredExtra 里声明'
+                f'（capability「{cap_id}」的共同字段: {common}）')
+
+    # 2026-09-20：required 的机器判据是显式 role（不再用 owner 的中文子串匹配）。
+    # 缺 role / 非法值 ⇒ **响亮拒绝**（静默回退会重现"发票状态被排除出投影"那类隐性行为改变）。
+    REQUIRED_ROLES = ('input', 'state', 'output', 'derived')
+    for _r in (spec.get('required') or []):
+        _n = str((_r or {}).get('name') or '?')
+        _role = (_r or {}).get('role')
+        if _role not in REQUIRED_ROLES:
+            die(f'流程 {flow_id} 的 required「{_n}」缺少合法 role（当前={_role!r}；'
+                f'可选: {" / ".join(REQUIRED_ROLES)}）—— 见注册表 _requiredRoles')
+    d = _derive(canonical, spec, caps, caps_from_doc)
+    # 顶层直通段（引擎级开关）：注册表里写了就原样带出，供 flow_config --get 与各脚本读取。
+    # 2026-09-23：envProbe / staleReclaim 加进来时漏了这一步 ⇒ CLI 报"未知配置键"、
+    # 探针与停滞回收都被当成"未声明"（静默不生效）。新增顶层段时**必须**登记在此。
+    for _k in ('envProbe', 'staleReclaim'):
+        if _k in spec:
+            d[_k] = spec[_k]
+
+    raw_t = spec.get('trigger') or {}
+    raw_d = raw_t.get('dispatch') or {}
+    raw_c = spec.get('concurrency') or {}
+    raw_g = spec.get('guards') or {}
+
+    wake = str(raw_t.get('wake') or DEFAULTS['trigger']['wake'])
+    if wake not in WAKE_MODES:
+        die(f'流程 {flow_id} 的 trigger.wake 非法: {wake}（可选: {", ".join(WAKE_MODES)}）')
+
+    # 2026-09-18：本轮**是否真实写入**必须来自注册表 —— 此前 flow-trigger.sh / flow-trigger-wake.mjs
+    # 把「影子模式」写死在日志里，FULL 已转真实运行后日志仍在说"影子模式"（误导操作者）。
+    # 保守默认 shadow：注册表没写 mode 的流程，日志一律按影子播报，绝不宣称真实写入。
+    mode = str(raw_t.get('mode') or DEFAULTS['trigger']['mode'])
+    if mode not in WRITE_MODES:
+        die(f'流程 {flow_id} 的 trigger.mode 非法: {mode}（可选: {", ".join(WRITE_MODES)}）')
+
+    trigger = {
+        'intervalSec': int(raw_t.get('intervalSec') or DEFAULTS['trigger']['intervalSec']),
+        'jitterSec': int(raw_t.get('jitterSec') if raw_t.get('jitterSec') is not None
+                         else DEFAULTS['trigger']['jitterSec']),
+        'wake': wake,
+        'mode': mode,
+        'pauseSwitch': str(raw_t.get('pauseSwitch') or d['pauseSwitch']),
+        'log': str(raw_t.get('log') or d['log']),
+        'promptTemplate': str(raw_t.get('promptTemplate') or d['promptTemplate']),
+    }
+    # 迁移期兜底开关（P2a）：白名单不放行的话，注册表里声明了也会被静默丢弃
+    # （首版就踩了：paths 里读不到 pauseSwitchLegacy ⇒ 兜底形同虚设）
+    if raw_t.get('pauseSwitchLegacy'):
+        trigger['pauseSwitchLegacy'] = str(raw_t['pauseSwitchLegacy'])
+    # P1-A（2026-10-12）：宿主排程声明（只声明了才出现这个键 —— 未迁移的流程 cfg 形状**逐字不变**）
+    schedule = resolve_schedule(canonical, spec, strict)
+    if schedule:
+        trigger['schedule'] = schedule
+    dispatch = {
+        'preset': str(raw_d.get('preset') or d['preset']),
+        'cwd': str(raw_d.get('cwd') or d['cwd']),
+        'sessionIdFile': str(raw_d.get('sessionIdFile') or d['sessionIdFile']),
+    }
+    concurrency = {
+        'max': int(raw_c.get('max') if raw_c.get('max') is not None else DEFAULTS['concurrency']['max']),
+        'leaseMin': int(raw_c.get('leaseMin') if raw_c.get('leaseMin') is not None else DEFAULTS['concurrency']['leaseMin']),
+        # P5：同店并发上限（0=不限）。full 设为 1（一个店铺=一个浏览器实例+下载目录）
+        'perStore': int((spec.get('concurrency') or {}).get('perStore') or 0),
+        # 2026-09-18（用户口径 B「一店一批」）：同店单轮最多带回几张；>1 时由**一个**
+        # subagent 跑 `orchestrator.py --records a,b`（KB-085 单 CDP 多标签页、顺序执行），
+        # 且"该店已有活租约 ⇒ 整店跳过"（绝不追加到正在跑的批）。缺省 1 = 旧的同店串行。
+        'batchPerStore': int((spec.get('concurrency') or {}).get('batchPerStore') or 1),
+    }
+    if concurrency['max'] < 0 or concurrency['leaseMin'] <= 0:
+        die(f'流程 {flow_id} 的 concurrency 非法: {concurrency}')
+    raw_f = spec.get('failures') or {}
+    failures = {
+        'enabled': bool(raw_f.get('enabled', DEFAULTS['failures']['enabled'])),
+        'scanSec': int(raw_f.get('scanSec') or DEFAULTS['failures']['scanSec']),
+        'maxPerCase': int(raw_f.get('maxPerCase') or DEFAULTS['failures']['maxPerCase']),
+        'cooldownMin': int(raw_f.get('cooldownMin') or DEFAULTS['failures']['cooldownMin']),
+        'maxPerRound': int(raw_f.get('maxPerRound') or DEFAULTS['failures']['maxPerRound']),
+    }
+    guards = {
+        'dryRunDefault': bool(raw_g.get('dryRunDefault', DEFAULTS['guards']['dryRunDefault'])),
+        'backup': bool(raw_g.get('backup', DEFAULTS['guards']['backup'])),
+        'audit': bool(raw_g.get('audit', DEFAULTS['guards']['audit'])),
+        'writeFields': list(raw_g.get('writeFields') or []),
+    }
+    # 2026-10-09（缺陷 B）：**能力专属的守卫声明也透出**（标量键，如 `writer`=写手路径、
+    # `errorField`=失败原因列）。为什么必须透出：不透出 ⇒ 声明了也读不到 ⇒ 调用方只能各自把
+    # 路径/列名写死（那正是"判据第二份"与业务词泄漏进引擎的来源）。只透出标量、跳过 `_` 注释键，
+    # 且**不覆盖**上面四个归一化键（它们有缺省与冲突校验，语义更强）。
+    for _gk, _gv in (raw_g or {}).items():
+        if _gk.startswith('_') or _gk in guards:
+            continue
+        if isinstance(_gv, (str, bool, int, float)):
+            guards[_gk] = _gv
+    resolved_source, variant, variants = resolve_source(flow_id, spec, strict)
+    return {
+        'flowId': canonical,
+        # 调用方传进来的旧 id（别名）；与 flowId 相同表示本来就是规范 id
+        'flowIdRequested': flow_id,
+        'capability': cap_id,
+        # 引擎级顶层段（2026-09-23）：注册表写了就带出。**新增顶层段必须登记在此 + _derive 直通**，
+        # 否则 flow_config --get 报"未知配置键"，而 env_probe/flow_stale 会把它当"未声明"静默不生效。
+        'envProbe': spec.get('envProbe') or {},
+        'staleReclaim': spec.get('staleReclaim') or {},
+        # 失败自动重试（方案 a，2026-10-13）：四个量在这里**归一化后**透出（按流程声明覆盖 → 缺省），
+        # `flow_config --get autoRetry.<键>` 与调用方读的都是这一份。
+        'autoRetry': resolve_auto_retry(spec),
+        'integration': integ,
+        'title': str(spec.get('title') or flow_id),
+        'role': str(spec.get('role') or flow_id),
+        'source': resolved_source,
+        'sourceVariant': variant,
+        'sourceVariants': sorted(variants.keys()),
+        'routing': spec.get('routing') or {},
+        # 字段要求也可按变体覆盖（2026-09-17：FULL 的 legacy 表与 lip 表列名不同 ——
+        # legacy 用「店铺名称/品名」，lip 用「店铺/产品名称」⇒ 写死一套必然在另一套上响亮失败）。
+        'required': (variants.get(variant) or {}).get('required') or spec.get('required') or [],
+        'requiredSource': f'variant:{variant}' if (variants.get(variant) or {}).get('required') else 'flow',
+        'trigger': trigger,
+        'dispatch': dispatch,
+        'concurrency': concurrency,
+        'guards': guards,
+        'failures': failures,
+        'paths': {
+            'log': str(DATA_DIR / trigger['log']),
+            'pauseSwitch': str(DATA_DIR / trigger['pauseSwitch']),
+            # 迁移期兜底：业务线落位后开关搬到 `verticals/<id>/PAUSE.<flow>`，
+            # 但机器上的旧开关还在 ⇒ 两条都查（flow-trigger.sh），退休见 base._aliasNote
+            **({'pauseSwitchLegacy': str(DATA_DIR / trigger['pauseSwitchLegacy'])}
+               if trigger.get('pauseSwitchLegacy') else {}),
+            'sessionIdFile': str(DATA_DIR / dispatch['sessionIdFile']),
+            'promptTemplate': str(_resolve_prompt_path(trigger['promptTemplate'])),
+            # P1-A：静态轮次指令（宿主排程用）—— 只有声明了 schedule 的流程才有这个键
+            **({'schedulePromptFile': str(schedule.get('promptPath') or '')} if schedule else {}),
+            'lock': str(DATA_DIR / d['lock']),
+            'ledger': str(DATA_DIR / 'flow-ledger.jsonl'),
+            'watchLog': str(DATA_DIR / 'flow-watch.log'),
+            'pauseWatch': str(DATA_DIR / 'PAUSE_FLOW_WATCH'),
+        },
+    }
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='每流程运行时配置（唯一读取点）')
+    ap.add_argument('--flow', help='流程 id，如 wenyao-invoice')
+    ap.add_argument('--registry', help='注册表路径（默认 scripts/flow-requirements.json）')
+    ap.add_argument('--list', action='store_true', help='列出已注册流程及关键参数')
+    ap.add_argument('--paths', action='store_true', help='只输出解析后的路径')
+    ap.add_argument('--get', help='取单个键（点号路径，如 trigger.pauseSwitch / concurrency.max）')
+    ap.add_argument('--json', action='store_true', help='JSON 输出（--get 时忽略）')
+    ap.add_argument('--lax', action='store_true', help='非严格：缺部署环境变量时标 *Unresolved 而不报错（控制台/巡查用）')
+    ap.add_argument('--schedule-declaration', action='store_true',
+                    help='打印「定时怎么来」的唯一声明（注册表 schedule 段 + 逐流程 job；只读）')
+    a = ap.parse_args(argv)
+
+    if a.list:
+        reg = load_registry(a.registry)
+        if not reg:
+            print('  （注册表为空）')
+            return 0
+        for fid in sorted(reg):
+            cfg = load_config(fid, registry=None, registry_path=a.registry, strict=False)
+            vs = f" 源变体={'/'.join(cfg['sourceVariants'])}→{cfg['sourceVariant']}" if cfg['sourceVariant'] else ''
+            un = [f"{k}={v}" for k, v in cfg['source'].items() if k.endswith('Unresolved')]
+            if un:
+                vs += '（部署配置未设置: ' + '、'.join(un) + '）'
+            print(f"  {fid:22s} role={cfg['role']:18s} preset={cfg['dispatch']['preset']:26s}"
+                  f" max={cfg['concurrency']['max']} 租约={cfg['concurrency']['leaseMin']}m"
+                  f" wake={cfg['trigger']['wake']} pause={cfg['trigger']['pauseSwitch']}{vs}")
+        return 0
+
+    if a.schedule_declaration:
+        print(json.dumps(schedule_declaration(a.registry), ensure_ascii=False, indent=2))
+        return 0
+
+    if not a.flow:
+        print('需要 --flow（或用 --list）', file=sys.stderr)
+        return 2
+    cfg = load_config(a.flow, registry_path=a.registry, strict=not a.lax)
+
+    if a.get:
+        cur = cfg
+        for part in a.get.split('.'):
+            if not isinstance(cur, dict) or part not in cur:
+                print(f'未知配置键: {a.get}（流程 {a.flow}）', file=sys.stderr)
+                return 2
+            cur = cur[part]
+        if isinstance(cur, (dict, list)):
+            print(json.dumps(cur, ensure_ascii=False))
+        elif isinstance(cur, bool):
+            print('true' if cur else 'false')
+        else:
+            print(cur)
+        return 0
+
+    print(json.dumps(cfg['paths'] if a.paths else cfg, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())