@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow-scaffold.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""新货代脚手架（迭代 2-步骤 3）：把"接一个新货代 = 改 9 处"压到"3 处"。
+
+## 生成什么（幂等：已存在的文件**不覆盖**，只报告）
+1. `scripts/integrations/<name>/adapter.py` —— 适配器骨架，`STATUS = "scaffold"`
+   （契约门禁会**故意拦住**它，直到你填完门户细节并改成 `"ready"`）；
+2. `presets/argent-<role>/` —— 从 `--from-flow` 的 preset 复制（agent.cordis.yml / preset.yml /
+   format-version.txt），顶部加 TODO 提示：persona 里仍有源货代的文字，需要改；
+3. `scripts/flow-prompts/<flow>.md` 与 `<flow>.failure.md` —— 从源流程复制。
+   ⚠️ 这两份**已经是载体无关的模板**（迭代 2-步骤 2 起用 `{{integration}}`/`{{leaseMin}}` 变量），
+   所以复制即可用，通常不需要改；
+4. 注册表片段（`--apply` 时合并进 `scripts/flow-requirements.json`，写前备份）。
+
+## 你还要做的 3 件事
+  ① 填门户细节：适配器的 `RUNNERS` / `MANUAL_GATES` / `ERROR_CLASSES` / `TEMPLATE`，
+     并实现/接入 runner；做完把 `STATUS` 改成 `"ready"`；
+  ② 填模板映射（若该货代需要填模板）；
+  ③ 跑门禁：`integration_contract.py --validate` → `check-role-mapping.mjs` →
+     `check-sop-consistency.mjs` → `tests/run-all-tests.sh`。
+
+用法：
+    python3 scripts/flow-scaffold.py --name xinlong --carrier "鑫隆" --title "鑫隆发票流程" [--apply]
+    python3 scripts/flow-scaffold.py --name demo --carrier "演示货代" --out-dir /tmp/scaffold --apply
+退出码：0 成功；1 有已存在文件（未覆盖）；2 参数错误。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import shutil
+import sys
+import time
+
+HERE = pathlib.Path(__file__).resolve().parent
+REPO = HERE.parent
+REGISTRY = HERE / "flow-requirements.json"
+
+ADAPTER_TMPL = '''#!/usr/bin/env python3
+"""{title} 集成适配器（**脚手架生成，尚未实现**）。
+
+门户：<TODO：门户地址/系统说明>
+执行入口：<TODO：runner 脚本名（放 scripts/ 下，并在 RUNNERS 里声明）>
+
+⚠️ 完成前请保持 `STATUS = "scaffold"` —— 契约门禁会拦住未完成的集成
+（`python3 scripts/integration_contract.py --validate` 会点名缺什么）。
+契约见 `scripts/integration_contract.py`。
+"""
+from __future__ import annotations
+
+NAME = "{name}"
+STATUS = "scaffold"                  # 完成后改为 "ready"
+CARRIER = "{carrier}"                # 必须与注册表 routing.match 完全一致
+CAPABILITIES = {{"invoice": True, "labels": True, "portal_confirm": True}}
+
+MANUAL_GATES = [
+    {{"what": "<TODO：门户账号由谁维护 / 是否有验证码或人工确认>", "who": "运营",
+     "why": "对方生产系统，凭据不进仓库/不进对话", "how": "<TODO>"}},
+    {{"what": "HS 编码等报关敏感字段由运营人工维护", "who": "运营",
+     "why": "红线：系统不预填/不写候选/不自动确认", "how": "运营在表里填好后重勾「发票就绪」"}},
+]
+
+# 门户错误文案 → 失败类（retryable / needs_human / needs_agent）：先抄通用几条，按门户实际报错补
+ERROR_CLASSES = [
+    (r"net::ERR|ECONNRESET|ETIMEDOUT|503|502|429", "retryable"),
+    (r"登录|Login|账号|密码|未授权", "needs_human"),
+    (r"参考单号.*重复|已存在", "needs_agent"),
+    (r"等待选择器超时|选择器超时|locator.*(timeout|超时)", "needs_agent"),
+]
+
+RUNNERS = {{}}                        # TODO：{{"全链路": "<你的 runner>.py"}}（脚本必须真实存在）
+TEMPLATE = ""                         # TODO：模板/映射文件（不需要则留空）
+WRITEBACK_FLOW = "{flow}"
+
+
+def match(row: dict) -> bool:
+    return str((row or {{}}).get("货代公司") or "").strip() == CARRIER
+
+
+def preflight(row: dict, cfg: dict | None = None) -> dict:
+    """缺口分型：TODO 按该货代的必填字段补（运营填 / 我方补）。"""
+    row = row or {{}}
+    ops = [n for n in ("HS编码", "产品名称", "SKU", "数量", "箱数") if not str(row.get(n) or "").strip()]
+    ours = [] if str(row.get("货件号") or "").strip() else ["货件号（应由 FULL 流程回填）"]
+    return {{"ours": ours, "ops": ops}}
+
+
+def plan(row: dict, cfg: dict | None = None) -> list:
+    """可执行计划：TODO 换成该货代真实的命令（先只读核对、再真跑）。"""
+    row = row or {{}}
+    rec = str(row.get("_id") or row.get("record_id") or "")
+    if not rec:
+        raise ValueError("plan() 需要 record_id")
+    return [
+        {{"phase": "核对（只读）", "script": "<TODO: runner>.py", "argv": ["--record-id", rec, "--dry-run"],
+          "writes": False, "why": "先只读核对，不写表、不碰门户"}},
+        {{"phase": "真跑", "script": "<TODO: runner>.py", "argv": ["--record-id", rec, "--yes"],
+          "writes": True, "why": "门户上传 → 下载标签 → 回写"}},
+    ]
+
+
+def classify_error(text: str) -> str:
+    import re
+    for pat, kind in ERROR_CLASSES:
+        if re.search(pat, str(text or ""), re.I):
+            return kind
+    return "needs_agent"
+'''
+
+PRESET_TODO = """# ⚠️ 本 preset 由 `scripts/flow-scaffold.py` 从 `{src_role}` 复制（{ts}）
+# TODO：persona 里仍有源货代的描述（门户地址/流程细节），请按 {carrier} 的实际情况改写；
+#       并把流程 id 从 `{src_flow}` 全文替换为 `{flow}`（若还有遗漏）。
+"""
+
+
+def build_registry_fragment(flow: str, name: str, carrier: str, title: str, role: str, reg: dict) -> dict:
+    """按能力层派生一条 flow 条目（required 的 role 从 capability 共同集 + 该货代额外项派生）。"""
+    caps = (reg.get("capabilities") or {}).get("invoice") or {}
+    common = list(caps.get("requiredCommon") or [])
+    states = list(caps.get("stateFields") or [])
+    required = [{"name": n, "role": "input", "owner": "运营"} for n in common]
+    required += [{"name": n, "role": "state", "owner": "运营"} for n in states]
+    return {
+        flow: {
+            "title": title,
+            "capability": "invoice",
+            "integration": name,
+            "role": role,
+            "routing": {"routeBy": "货代公司", "match": carrier},
+            "source": {
+                "kind": "feishu-base",
+                "envFile": "fulfillment.env",
+                "baseEnv": "FULL_BASE_TOKEN",
+                "tableEnv": "FULL_TABLE_ID",
+                "identityEnv": "FULL_LARK_PROFILE",
+            },
+            "trigger": {
+                "intervalSec": 300, "wake": "session", "mode": "real",
+                "pauseSwitch": "PAUSE_FLOW_" + flow.upper().replace("-", "_"),
+                "promptTemplate": f"flow-prompts/{flow}.md",
+            },
+            "required": required,
+            "overrides": {"requiredExtra": []},
+        }
+    }
+
+
+def _guard_vertical_targeting(argv) -> None:
+    """P2a 防呆（2026-09-29）：本工具原本把新流程写进**引擎级 base 注册表**。
+
+    注册表已拆成「引擎级 base + 每条业务线一份」⇒ 新流程（尤其是各条业务线的货代流程）
+    应当落在业务线里，否则又变成"业务实现掺进引擎"。这里**响亮拦住**并指明正确入口；
+    真要写 base（例如平台级流程）需显式 `--allow-base-write`。
+    """
+    if '--allow-base-write' in argv:
+        return
+    print("✗ flow-scaffold 不再直接写引擎级 base 注册表（P2a：注册表已按业务线拆分）。\n"
+          "  · 新增**业务线流程**：node scripts/vertical-init.mjs --id <vertical> --flow <flow> …\n"
+          "  · 修改**已有业务线**（如给某条线加一条货代流程）：改 verticals/<id>/flows.json +\n"
+          "    verticals/<id>/prompts/<flow>.md + presets/argent-<role>/，然后跑\n"
+          "    python3 scripts/flow_registry.py --check && node scripts/vertical-lint.mjs\n"
+          "  · 确实要写 base（平台级流程）时加 --allow-base-write。", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def main(argv=None) -> int:
+    _guard_vertical_targeting(argv if argv is not None else sys.argv[1:])
+    ap = argparse.ArgumentParser(description="新货代脚手架（适配器 + preset + 提示词 + 注册表片段）")
+    ap.add_argument("--name", required=True, help="集成名（目录名，如 xinlong）")
+    ap.add_argument("--carrier", required=True, help='货代在业务表里的精确写法（= routing.match），如 "鑫隆"')
+    ap.add_argument("--title", help="流程标题（缺省「<carrier>发票流程」）")
+    ap.add_argument("--role", help="角色名（缺省 ml-invoice-<name>）")
+    ap.add_argument("--from-flow", default=None,
+                    help="复制哪条既有发票流程的 preset/提示词（缺省：注册表里 invoice 能力的第一条流程）")
+    ap.add_argument("--out-dir", help="生成到该目录（默认仓库根；供测试/预演）")
+    ap.add_argument("--apply", action="store_true", help="真写（缺省只打印计划）")
+    ap.add_argument("--allow-base-write", action="store_true",
+                    help="P2a 防呆：确需把流程写进**引擎级 base** 时才加（新流程应进 verticals/<id>/）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    flow = f"{a.name}-invoice"
+    role = a.role or f"ml-invoice-{a.name}"
+    title = a.title or f"{a.carrier}发票流程"
+    root = pathlib.Path(a.out_dir).resolve() if a.out_dir else REPO
+    # P2a：源流程可能在业务线里 ⇒ 经加载器合并 + 别名解析（`--from-flow xzh-invoice` 仍可用）
+    try:
+        from flow_registry import load_doc as _load_doc, resolve_flow_id as _resolve
+        reg = _load_doc()
+        if not a.from_flow:
+            # 缺省源：注册表里 invoice 能力的第一条流程（引擎侧不写死业务线名）
+            a.from_flow = next((fid for fid, spec in (reg.get("flows") or {}).items()
+                                if (spec or {}).get("capability") == "invoice"), "")
+        src = (reg.get("flows") or {}).get(_resolve(a.from_flow, reg))
+    except Exception:                                             # noqa: BLE001 —— 加载器不可用时退回单文件
+        reg = json.loads(REGISTRY.read_text(encoding="utf-8"))
+        src = reg["flows"].get(a.from_flow)
+    if not src:
+        print(f"❌ 源流程不存在：{a.from_flow}", file=sys.stderr)
+        return 2
+    src_role = str(src.get("role") or "")
+    ts = time.strftime("%Y-%m-%d %H:%M")
+
+    targets = {
+        "adapter": root / "scripts" / "integrations" / a.name / "adapter.py",
+        "prompt": root / "scripts" / "flow-prompts" / f"{flow}.md",
+        "prompt_failure": root / "scripts" / "flow-prompts" / f"{flow}.failure.md",
+        "preset": root / "presets" / f"argent-{role}" / "agent.cordis.yml",
+        "preset_meta": root / "presets" / f"argent-{role}" / "preset.yml",
+        "preset_fmt": root / "presets" / f"argent-{role}" / "format-version.txt",
+    }
+    fragment = build_registry_fragment(flow, a.name, a.carrier, title, role, reg)
+    plan = {
+        "flow": flow, "role": role, "title": title, "carrier": a.carrier,
+        "integration": a.name, "from_flow": a.from_flow, "root": str(root),
+        "files": {k: str(v) for k, v in targets.items()},
+        "registryFragment": fragment,
+        "next_steps": [
+            "① 填适配器：RUNNERS / MANUAL_GATES / ERROR_CLASSES / TEMPLATE + 接入 runner；完成后 STATUS 改 \"ready\"",
+            "② 填模板映射（需要填模板的货代）",
+            "③ 跑门禁：integration_contract.py --validate → check-role-mapping.mjs → check-sop-consistency.mjs → tests/run-all-tests.sh",
+        ],
+    }
+    if not a.apply:
+        print(json.dumps(plan, ensure_ascii=False, indent=2))
+        print("\n[dry-run] 未写任何文件。加 --apply 落盘。", file=sys.stderr)
+        return 0
+
+    existed = [str(p) for p in targets.values() if p.exists()]
+    if existed:
+        print("❌ 以下文件已存在，脚手架**不覆盖**（请先处理）：", file=sys.stderr)
+        for p in existed:
+            print("   " + p, file=sys.stderr)
+        return 1
+
+    targets["adapter"].parent.mkdir(parents=True, exist_ok=True)
+    targets["adapter"].write_text(
+        ADAPTER_TMPL.format(name=a.name, carrier=a.carrier, title=title, flow=flow), encoding="utf-8")
+    # P2a：源提示词可能在业务线里（注册表 trigger.promptTemplate 是唯一出处），两种基准都认
+    _tpl_rel = str(((src or {}).get("trigger") or {}).get("promptTemplate") or f"flow-prompts/{a.from_flow}.md")
+    src_prompt = next((x for x in (REPO / _tpl_rel, HERE / _tpl_rel) if x.exists()), HERE / _tpl_rel)
+    # ⚠️ 目标目录必须**先建**（2026-10-08 修）：`scripts/flow-prompts/` 是 P2a 之前的提示词位置，
+    #    仓库里已无任何跟踪内容 ⇒ **git 不产生它** ⇒ 真·新克隆上这里 `shutil.copyfile` 会
+    #    `FileNotFoundError`（开发机上它只是被"恰好存在"或测试夹具的 mkdirSync 盖住了）。
+    #    ⛔ 只补父目录，**不**把写入目标迁到 `verticals/<id>/prompts/`（那属 P4 迁移，另开一笔）。
+    targets["prompt"].parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(src_prompt, targets["prompt"])
+    shutil.copyfile(src_prompt.with_name(src_prompt.name[:-3] + ".failure.md"), targets["prompt_failure"])
+    src_preset = REPO / "presets" / f"argent-{src_role}"          # P2a：被上面误删的一行，补回
+    for key, srcname in (("preset", "agent.cordis.yml"), ("preset_meta", "preset.yml"), ("preset_fmt", "format-version.txt")):
+        sp = src_preset / srcname
+        if not sp.exists():
+            continue
+        targets[key].parent.mkdir(parents=True, exist_ok=True)
+        text = sp.read_text(encoding="utf-8")
+        if key == "preset":
+            text = PRESET_TODO.format(src_role=src_role, src_flow=a.from_flow, flow=flow,
+                                      carrier=a.carrier, ts=ts) + text.replace(a.from_flow, flow).replace(src_role, role)
+        targets[key].write_text(text, encoding="utf-8")
+
+    if root == REPO:
+        bak = REGISTRY.with_suffix(f".json.bak-{time.strftime('%Y%m%d-%H%M%S')}")
+        shutil.copyfile(REGISTRY, bak)
+        reg["flows"].update(fragment)
+        REGISTRY.write_text(json.dumps(reg, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        plan["registryBackup"] = str(bak)
+    plan["written"] = {k: str(v) for k, v in targets.items()}
+    print(json.dumps(plan, ensure_ascii=False, indent=2) if a.json else
+          "\n".join(["✅ 已生成："] + [f"   {k}: {v}" for k, v in plan["written"].items()]
+                    + ["", "接下来："] + [f"   {s}" for s in plan["next_steps"]]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/engine/scripts/flow-timers-plist.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# flow-timers-plist.sh —— **激活垫片的 plist 生成器**（纯 stdout，零副作用）。
+#
+# ⭐ 为什么单独一个文件（0.6.0 W8，2026-10-14）：
+#   · 生产姿态**逐字段不许变**（4 条 `com.whyshu.flow-trigger-*` 常驻）⇒ 生成逻辑必须能被
+#     **逐字节回归**（夹具把参数钉死、比对生成物），而"装"（`launchctl bootstrap`）在本机是红线；
+#   · 声明面唯一处 = 注册表 `schedule` 段 ⇒ 本脚本**不自己读注册表**，只接收 `flow-timers.sh`
+#     从 `flow_config.py`（唯一读取点）取来的参数 ⇒ 生成器 = 纯函数（同样的参数 ⇒ 同样的字节）。
+#
+# 用法（只打印，不写文件、不碰 launchctl）：
+#   bash scripts/flow-timers-plist.sh --flow <id> [--label <label>] [--interval <秒>]
+#        [--repo <dir>] [--python <解释器>] [--node-dir <dir>] [--lark-dir <dir>] [--log-dir <dir>]
+#
+# 关键约定（缺一不可，踩过坑；原样保留自 flow-timers.sh）：
+#   · `AbandonProcessGroup=true`  —— 缺此键时 launchd 在脚本退出后清理其后台子进程
+#     （2026-09-03 事故：orchestrator spawn 即死、batch.log 0 字节）；
+#   · `ARGENT_PY`                —— 流程脚本用的解释器；不设会回退到开发机 venv（客户机上不存在）；
+#   · `PATH`                     —— 必须含 node 与 lark-cli 所在目录（launchd 的 PATH 极简）；
+#   · `RunAtLoad=false`          —— 装完**不立刻跑**一轮。
+set -euo pipefail
+
+FLOW=""; LABEL=""; INTERVAL=""; REPO=""; PY=""; NODE_DIR=""; LARK_DIR=""; LOG_DIR=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --flow) FLOW="${2:-}"; shift 2;;
+    --label) LABEL="${2:-}"; shift 2;;
+    --interval) INTERVAL="${2:-}"; shift 2;;
+    --repo) REPO="${2:-}"; shift 2;;
+    --python) PY="${2:-}"; shift 2;;
+    --node-dir) NODE_DIR="${2:-}"; shift 2;;
+    --lark-dir) LARK_DIR="${2:-}"; shift 2;;
+    --log-dir) LOG_DIR="${2:-}"; shift 2;;
+    -h|--help) sed -n '2,22p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0;;
+    *) echo "未知参数: $1" >&2; exit 2;;
+  esac
+done
+
+[ -n "$FLOW" ] || { echo "缺 --flow" >&2; exit 2; }
+[ -n "$INTERVAL" ] || { echo "缺 --interval（⛔ 不在这里给缺省：周期只有一份真源 = 注册表 trigger.intervalSec）" >&2; exit 2; }
+# ⛔ label **不给缺省**：前缀只有一处真源（注册表 `schedule.jobs.labelPrefix`，由 flow-timers.sh 传进来）。
+#   在这里写一个 `com.whyshu.flow-trigger-` 的兜底 = 造出第二份"定时怎么装"。
+[ -n "$LABEL" ] || { echo "缺 --label（⛔ 不在这里拼缺省前缀：label 前缀只有注册表 schedule.jobs.labelPrefix 一处真源）" >&2; exit 2; }
+REPO="${REPO:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+# ⛔ 日志落点也不给缺省：数据目录有**唯一判据**（内核 `core/lib/argent-datadir.mjs` / `scripts/lib/argent_datadir.py`），
+#   在这里拼一个 `$HOME/.dsh/argent` 就是**第二份数据目录判据** —— 隔离实例下会一半写隔离、一半写生产
+#   （门禁 `scripts/tests/argent-datadir-parity.test.mjs` 当场判红）。由 `flow-timers.sh` 传进来。
+[ -n "$LOG_DIR" ] || { echo "缺 --log-dir（⛔ 数据目录有唯一判据，本生成器不拼缺省）" >&2; exit 2; }
+NODE_DIR="${NODE_DIR:-$(dirname "$(command -v node || echo /usr/local/bin/node)")}"
+LARK_DIR="${LARK_DIR:-$(dirname "$(command -v lark-cli || echo /usr/local/bin/lark-cli)")}"
+PY="${PY:-${ARGENT_PY:-$HOME/.dsh/argent/venv/bin/python3}}"
+
+cat <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- 由 scripts/flow-timers.sh 生成（勿手改：声明面 = 注册表 schedule 段；参数来自唯一读取点） -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>$LABEL</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>$REPO/scripts/flow-trigger.sh</string>
+    <string>--flow</string>
+    <string>$FLOW</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>$INTERVAL</integer>
+  <key>RunAtLoad</key>
+  <false/>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>ARGENT_PY</key>
+    <string>$PY</string>
+    <key>PATH</key>
+    <string>$NODE_DIR:$LARK_DIR:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>$LOG_DIR/flow-trigger-$FLOW.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>$LOG_DIR/flow-trigger-$FLOW.err.log</string>
+</dict>
+</plist>
+PLIST

package/engine/scripts/flow-timers.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# 定时触发器安装器（P5 客户机部署件，2026-09-17）—— **每流程一个 LaunchAgent**。
+#
+# ⭐ **0.6.0 W8（2026-10-14）起「定时怎么来」只有一处声明**：
+#    注册表 `schedule` 段（`scripts/flow-requirements.json`）—— `mechanism`
+#    （`auto|native|activation-shim|none`）+ `jobs.labelPrefix` / `jobs.installCommand`。
+#    本脚本是**激活垫片（0.1.7 线）的实现**，只**读**那份声明（经
+#    `flow_config.py --schedule-declaration`），⛔ 不在这里写第二份"定时怎么装"；
+#    判据（含"两条线同时在场 ⇒ 报冲突"）在 `scripts/lib/schedule-mechanism.mjs`（唯一实现）。
+#    ⛔ 两条线**不许同时**调度同一条流程（单一调度者纪律）。
+#
+# 为什么用脚本生成而不是手写 plist：每流程的间隔/暂停开关/日志名都在**注册表**里
+# （`scripts/flow_config.py` 是唯一读取点）⇒ 手写 plist 必然与注册表漂移。
+#
+# 关键约定（缺一不可，踩过坑）：
+#   · `AbandonProcessGroup=true`  —— 缺此键时 launchd 在脚本退出后清理其后台子进程
+#     （2026-09-03 事故：orchestrator spawn 即死、batch.log 0 字节）。本触发器会 spawn
+#     角色会话投递进程，同样需要它。
+#   · `ARGENT_PY`                —— 流程脚本用的解释器；不设会回退到开发机 venv
+#     （客户机上不存在 ⇒ 触发器 exec 失败）。默认取当前 `ARGENT_PY` 或 ~/.dsh/argent/venv/bin/python3。
+#   · `PATH`                     —— 必须含 node 与 lark-cli 所在目录（launchd 的 PATH 极简）。
+#   · 暂停开关                    —— 由流程注册表的 `trigger.pauseSwitch` 决定；装完**先别删**，
+#     观察影子轮没问题再逐流程摘（见 docs/客户机部署与上线.md §4.4）。
+#
+# 用法：
+#   bash scripts/flow-timers.sh status
+#   bash scripts/flow-timers.sh install --flow wenyao-invoice [--flow xzh-invoice] [--dry-run]
+#   bash scripts/flow-timers.sh install --all [--dry-run]
+#   bash scripts/flow-timers.sh uninstall --flow wenyao-invoice
+set -euo pipefail
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# 解释器解析（2026-09-22 重启事故：默认值写死 ~/.dsh/argent/venv ⇒ 重启后静默空转）
+pick_py() {
+  local c
+  # 候选（2026-09-22）：ARGENT_PY → DSH_HOME/argent/venv → ~/.dsh/argent/venv → 仓库 .venv → PATH
+  for c in "${ARGENT_PY:-}" "${DSH_HOME:-$HOME/.dsh}/argent/venv/bin/python3" \
+           "$HOME/.dsh/argent/venv/bin/python3" "${REPO:-}/.venv/bin/python3" \
+           "$(command -v python3 2>/dev/null || true)"; do
+    [ -n "$c" ] || continue
+    [ -x "$c" ] || continue
+    "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue   # 硬要求：配置/发票生成必需
+    "$c" -c 'import PIL, playwright' 2>/dev/null || \
+      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：node install-argent.mjs --venv-only）" >&2
+    printf '%s' "$c"; return 0
+  done
+  return 1
+}
+if ! PY="$(pick_py)"; then
+  echo "❌ 找不到可用解释器（需含 openpyxl + yaml）：ARGENT_PY / ~/.dsh/argent/venv/bin/python3 / <repo>/.venv / PATH 的 python3" >&2
+  echo "   修复: python3 -m venv ~/.dsh/argent/venv && ~/.dsh/argent/venv/bin/pip install openpyxl pyyaml" >&2
+  exit 2
+fi
+AGENTS="$HOME/Library/LaunchAgents"
+LOGDIR="$HOME/.dsh/argent"
+# ── 声明面（唯一）：注册表 `schedule` 段 ────────────────────────────────────────
+# `DECL` 只在本进程读一次；`--dry-run` 与 `status` 也走同一份（⛔ 不再各自读一遍）。
+_DECL_STATUS=0
+if DECL="$("$PY" "$REPO/scripts/flow_config.py" --schedule-declaration 2>/dev/null)"; then
+  :
+else
+  _DECL_STATUS=$?
+  DECL='{}'
+  echo "⚠️ 读不到注册表的 schedule 声明（flow_config.py --schedule-declaration exit ${_DECL_STATUS}）：" >&2
+  echo "   本脚本按**内置口径**继续（label 前缀/命令模板），但请先修注册表 —— 声明面是唯一真源。" >&2
+fi
+decl() {  # $1=点号路径（如 jobs.labelPrefix / mechanism）
+  printf '%s' "$DECL" | "$PY" -c 'import json,sys
+try:
+    cur = json.load(sys.stdin)
+except Exception:
+    print(""); raise SystemExit(0)
+for part in sys.argv[1].split("."):
+    if not isinstance(cur, dict) or part not in cur:
+        print(""); raise SystemExit(0)
+    cur = cur[part]
+print("" if cur is None else (("true" if cur else "false") if isinstance(cur, bool) else cur))' "$1"
+}
+LABEL_PREFIX="$(decl jobs.labelPrefix)"; [ -n "$LABEL_PREFIX" ] || LABEL_PREFIX="com.whyshu.flow-trigger"
+
+usage() { sed -n '2,26p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+
+cfg() { "$PY" "$REPO/scripts/flow_config.py" --flow "$1" --get "$2"; }
+
+flows_arg() {  # 解析 --flow/--all
+  local out=() all=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --flow) out+=("$2"); shift 2;;
+      --all) all=1; shift;;
+      *) shift;;
+    esac
+  done
+  if [ "$all" = 1 ] || [ ${#out[@]} -eq 0 ]; then
+    out=()
+    while IFS= read -r f; do out+=("$f"); done < <("$PY" "$REPO/scripts/flow_config.py" --list 2>/dev/null | awk '{print $1}' | grep -v '^$')
+  fi
+  printf '%s\n' "${out[@]}"
+}
+
+node_dir() { dirname "$(command -v node || echo /usr/local/bin/node)"; }
+lark_dir() { dirname "$(command -v lark-cli || echo /usr/local/bin/lark-cli)"; }
+
+# 生成器**独立成文件**（`flow-timers-plist.sh`）：纯 stdout、零副作用 ⇒ 可被逐字节回归
+# （本机 ⛔ 不许 `launchctl bootstrap`，所以"生成物与生产形态等价"只能这样证）。
+# ⛔ 周期不给缺省：读不到就**响亮失败**（见 `gen_plist`）。
+gen_plist() {  # $1=flow ⇒ stdout=plist；失败 ⇒ 非零
+  local flow="$1" interval label
+  interval="$(cfg "$flow" trigger.intervalSec 2>/dev/null || true)"
+  if [ -z "$interval" ]; then
+    echo "❌ 流程 $flow 读不到 trigger.intervalSec（注册表声明缺失或 flow 名不对）⇒ 拒绝生成 plist" >&2
+    return 1
+  fi
+  label="$LABEL_PREFIX-$flow"
+  bash "$REPO/scripts/flow-timers-plist.sh" \
+    --flow "$flow" --label "$label" --interval "$interval" \
+    --repo "$REPO" --python "$PY" \
+    --node-dir "$(node_dir)" --lark-dir "$(lark_dir)" --log-dir "$LOGDIR"
+}
+
+cmd_status() {
+  echo "── 本机定时器状态（label / 退出码 / PID）"
+  launchctl list | grep -i "whyshu" || echo "  （无 whyshu agent）"
+  echo
+  echo "── 最近一次触发结果（launchd 捕获的 stdout 尾部；空=还没跑过）"
+  for f in "$LOGDIR"/flow-trigger-*.out.log; do
+    [ -f "$f" ] || continue
+    b="$(basename "$f")"; b="${b#flow-trigger-}"; b="${b%.out.log}"
+    printf '  %-16s %s\n' "$b" "$(tail -1 "$f" | cut -c1-120)"
+  done
+  echo
+  echo "── 每流程的暂停开关（存在=不唤起）"
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    local p; p="$(cfg "$f" paths.pauseSwitch 2>/dev/null || echo '?')"
+    if [ -f "$p" ]; then echo "  ⏸  ${f}：已暂停（${p}）"; else echo "  ▶️  ${f}：未暂停"; fi
+  done < <(flows_arg --all)
+}
+
+cmd_install() {
+  local dry=0; case " $* " in *" --dry-run "*) dry=1;; esac
+  mkdir -p "$AGENTS" "$LOGDIR"
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    local label plist ins
+    label="$LABEL_PREFIX-$f"; plist="$AGENTS/$label.plist"
+    if ! ins="$(gen_plist "$f")"; then
+      echo "❌ ${f}：生成 plist 失败（见上面那句）⇒ 本轮跳过这一条（⛔ 不写半成品 plist）" >&2
+      continue
+    fi
+    if [ "$dry" = 1 ]; then
+      echo "── [dry-run] $f → $plist"; printf '%s\n' "$ins" | sed -n '1,12p'; echo "   …（完整 plist 见上方结构）"; continue
+    fi
+    printf '%s\n' "$ins" > "$plist"
+    launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+    launchctl enable "gui/$(id -u)/$label" 2>/dev/null || true
+    if launchctl bootstrap "gui/$(id -u)" "$plist" 2>/dev/null; then
+      echo "  ✅ 已装并加载：${label}（间隔 $(cfg "$f" trigger.intervalSec 2>/dev/null || echo 300)s）"
+    else
+      echo "  ⚠️ 已写 plist 但 bootstrap 失败：${plist}（看 launchctl print gui/$(id -u)/${label}）"
+    fi
+  done < <(flows_arg "$@")
+}
+
+cmd_uninstall() {
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    local label; label="$LABEL_PREFIX-$f"
+    launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+    launchctl disable "gui/$(id -u)/$label" 2>/dev/null || true
+    rm -f "$AGENTS/$label.plist"
+    echo "  ⏏️  已卸载：$label"
+  done < <(flows_arg "$@")
+}
+
+case "${1:-}" in
+  status) shift; cmd_status ;;
+  install) shift; cmd_install "$@" ;;
+  uninstall) shift; cmd_uninstall "$@" ;;
+  -h|--help|"") usage ;;
+  *) echo "未知子命令: $1"; usage; exit 2 ;;
+esac