@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/flow_return_to_ops.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""发票流程·缺口回填「退回运营」（用户口径 2026-09-17）。
+
+规则（两个发票流程一致：文鳐 + 鑫中航，同一张 lip 表）：
+  · **只有需要运营填的字段缺口**（owner 不含「系统」）才动作：
+      ① 写 `发票错误信息` = **结论+动作**的运营文案（`flow_failure.ops_message()` 产出，
+         ⛔ 不在本文件里另写一份；2026-10-09 缺陷 B 收口）；
+      ② 把 `发票就绪` 置 **false**（取消放行 —— 运营补齐后需自己重勾，那是他的确认动作）。
+  · **我方/系统类缺口**：`发票错误信息` 是**给运营看的**字段 ⇒ **不写**；我方缺口自行解决
+    （记台账/发卡片/补录），绝不污染运营那一列，也不取消勾选。
+  · **同源同文**（2026-10-09）：表字段那串 == 台账 `blocked.detail` 那串（逐字相同，
+    `blocked.error` 放**规范原因**供分类器/取数口用）——⛔ 不许两处各写一套。
+
+守卫（写生产表）：
+  ① 字段白名单：只许 `发票错误信息` / `发票就绪`；
+  ② **单向**：`发票就绪` 只允许置 false —— 勾选权永远归运营，流程永不自己勾上；
+  ③ 记录白名单：必须显式 `--case`/`--record`，一次一条；
+  ④ 前提校验：该行必须是已开启的行（`FULL状态=已完成 ∧ 发票就绪=true`），否则不动；
+  ⑤ 写前整行备份 + 写后读回 + 审计 JSONL + 台账 `blocked`；
+  ⑥ 默认 dry-run，真写要 `--yes`。
+
+用法：
+  python3 scripts/flow_return_to_ops.py --flow wenyao-invoice --case wenyao-invoice__rec1        # 预览
+  python3 scripts/flow_return_to_ops.py --flow wenyao-invoice --case wenyao-invoice__rec1 --yes  # 真写
+  # 测试/离线：--fields-from-json <行字段JSON>（跳过读表）
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+import flow_config  # noqa: E402  唯一配置读取点
+import flow_failure as F  # noqa: E402  失败/缺口文案的**唯一来源**（结论+动作，与台账同源同文）
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+DATA_DIR = pathlib.Path(resolve_data_dir()['dir'])
+AUDIT = DATA_DIR / "flow-return-audit.jsonl"
+BACKUP_DIR = DATA_DIR / "flow-return-backup"
+LEDGER = DATA_DIR / "flow-ledger.jsonl"
+WRITE_FIELDS = ("发票错误信息", "发票就绪")
+
+
+def field_ids(profile: str, base: str, table: str) -> dict:
+    p = subprocess.run(["lark-cli", "--profile", profile, "base", "+field-list",
+                        "--base-token", base, "--table-id", table, "--as", "bot", "--format", "json"],
+                       capture_output=True, text=True,
+                       timeout=int(os.environ.get('ARGENT_CMD_TIMEOUT') or 120))
+    if p.returncode != 0:
+        raise SystemExit(f"❌ 取字段表失败：{(p.stderr or p.stdout).strip()[:200]}")
+    d = json.loads(p.stdout or "{}")
+    return {str(f.get("field_name") or f.get("name")): str(f.get("field_id") or f.get("id"))
+            for f in (((d.get("data") or {}).get("fields")) or [])}
+
+
+def read_row(profile: str, base: str, table: str, record: str) -> dict:
+    p = subprocess.run(["lark-cli", "--profile", profile, "base", "+record-get", "--base-token", base,
+                        "--table-id", table, "--record-id", record, "--as", "bot", "--format", "json"],
+                       capture_output=True, text=True,
+                       timeout=int(os.environ.get('ARGENT_CMD_TIMEOUT') or 120))
+    if p.returncode != 0:
+        raise SystemExit(f"❌ 读记录失败：{(p.stderr or p.stdout).strip()[:200]}")
+    data = (json.loads(p.stdout or "{}").get("data") or {})
+    for c in (((data.get("record") or {}).get("fields")), data.get("fields")):
+        if isinstance(c, dict) and c:
+            return c
+    vals, names = data.get("data"), data.get("fields")
+    if isinstance(vals, list) and vals and isinstance(vals[0], list) and isinstance(names, list):
+        return {str(n): v for n, v in zip(names, vals[0])}
+    raise SystemExit(f"❌ 读不到记录 {record} 的字段（形状异常：{list(data)[:6]}）")
+
+
+def human_gaps(flow: str, fields: dict) -> list[str]:
+    """算出**需要运营填**的缺口（owner 不含「系统」）。复用 ml_schema_check 的判据，避免第二套实现。"""
+    req = flow_config.load_config(flow).get("required") or []
+    owner = {str(r.get("name")): str(r.get("owner") or "") for r in req}
+    # ⚠️ ml_schema_check 的 --fields-from-json 只接受**文件路径**（不支持 `-`）——
+    # 第一版传 `-` 导致子进程失败、异常被吞 ⇒ 缺口恒为空（"静默空"老毛病）⇒ 落临时文件 + 失败要响亮。
+    import tempfile
+    with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False, encoding="utf-8") as tf:
+        json.dump(fields, tf, ensure_ascii=False)
+        tmp = tf.name
+    try:
+        p = subprocess.run([sys.executable, str(HERE / "ml_schema_check.py"), "--flow", flow,
+                            "--fields-from-json", tmp, "--json"], capture_output=True, text=True)
+    finally:
+        pathlib.Path(tmp).unlink(missing_ok=True)
+    if not (p.stdout or "").strip().startswith("{"):
+        raise SystemExit(f"❌ 缺口检查失败（不当作无缺口）：{(p.stderr or p.stdout).strip()[:200]}")
+    missing = [str(m.get("name")) for m in (json.loads(p.stdout).get("missing") or [])]
+    return [m for m in missing if "系统" not in owner.get(m, "")]
+
+
+def truthy(v) -> bool:
+    if isinstance(v, list):
+        return truthy(v[0]) if v else False
+    if isinstance(v, bool):
+        return v
+    return str(v or "").strip().lower() not in ("", "false", "0", "no", "否")
+
+
+def one(v):
+    return v[0] if isinstance(v, list) and v else v
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="发票缺口回填：写「发票错误信息」+ 取消「发票就绪」（仅运营缺口）")
+    ap.add_argument("--flow", required=True)
+    ap.add_argument("--case", help="台账 case id（<flow>__<record_id>）")
+    ap.add_argument("--record", help="record_id")
+    ap.add_argument("--fields-from-json", help="离线：直接给该行字段 JSON（测试用，跳过读表）")
+    ap.add_argument("--yes", action="store_true", help="真写（默认 dry-run）")
+    a = ap.parse_args(argv)
+
+    cfg = flow_config.load_config(a.flow)
+    src = cfg.get("source") or {}
+    base, table, profile = str(src.get("base") or ""), str(src.get("table") or ""), str(src.get("identity") or "")
+    record = a.record or (a.case.split("__", 1)[1] if a.case and "__" in a.case else "")
+    if not record:
+        print("❌ 需要 --case <flow>__<record_id> 或 --record <record_id>（记录白名单，一次一条）", file=sys.stderr)
+        return 2
+
+    if a.fields_from_json:
+        row = json.loads(pathlib.Path(a.fields_from_json).read_text(encoding="utf-8"))
+        fmap = {k: k for k in WRITE_FIELDS}          # 离线模式按字段名写（仅预览用）
+    else:
+        fmap = field_ids(profile, base, table)
+        row = read_row(profile, base, table, record)
+
+    gate_full, gate_ready = one(row.get("FULL状态")), one(row.get("发票就绪"))
+    gaps = human_gaps(a.flow, row)
+    print("── 现场 ──")
+    print(f"  流程/表 : {a.flow}｜{table or '(离线)'}")
+    print(f"  记录    : {record}")
+    print(f"  开启前提: FULL状态={gate_full!r}｜发票就绪={gate_ready!r}")
+    print(f"  运营缺口: {gaps or '（无）'}")
+
+    if not gaps:
+        print("\n  ✅ 无运营缺口 ⇒ **不写任何字段**（`发票错误信息` 是给运营看的；我方缺口自行解决）")
+        return 0
+    if not a.fields_from_json and not (str(gate_full).strip() == "已完成" and truthy(gate_ready)):
+        print(f"\n  ⚠️ 该行未处于已开启状态（需 FULL状态=已完成 ∧ 发票就绪=true）⇒ 不回填（避免误改未开启的行）")
+        return 0
+
+    msg = F.ops_message(a.flow, f"缺 {'、'.join(gaps)}", missing=gaps)
+    patch = {fmap.get("发票错误信息", "发票错误信息"): msg,
+             fmap.get("发票就绪", "发票就绪"): False}     # 单向：只允许 false
+    print("── 计划（退回运营）──")
+    for k, v in patch.items():
+        print(f"  {k} → {v!r}")
+    if not a.yes:
+        print("\n[dry-run] 未写入。加 --yes 才落库。")
+        return 0
+
+    BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+    at = datetime.datetime.now().isoformat(timespec="seconds")
+    bk = BACKUP_DIR / f"{a.flow}__{record}__{at.replace(':', '')}.json"
+    bk.write_text(json.dumps({"flow": a.flow, "record": record, "at": at, "fields": row},
+                             ensure_ascii=False, indent=2), encoding="utf-8")
+    p = subprocess.run(["lark-cli", "--profile", profile, "base", "+record-batch-update", "--base-token", base,
+                        "--table-id", table, "--json",
+                        json.dumps({"update_records": {record: patch}}, ensure_ascii=False),
+                        "--as", "bot", "--format", "json"], capture_output=True, text=True,
+                       timeout=int(os.environ.get('ARGENT_CMD_TIMEOUT') or 120))
+    if p.returncode != 0:
+        print(f"❌ 写入失败：{(p.stderr or p.stdout).strip()[:250]}", file=sys.stderr)
+        return 3
+    after = read_row(profile, base, table, record)
+    ok = (not truthy(one(after.get("发票就绪")))) and str(one(after.get("发票错误信息")) or "").strip() != ""
+    with AUDIT.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps({"at": at, "flow": a.flow, "record": record, "gaps": gaps,
+                             "wrote": {"发票错误信息": msg, "发票就绪": False}, "backup": str(bk), "ok": bool(ok)},
+                            ensure_ascii=False) + "\n")
+    subprocess.run([sys.executable, str(HERE / "flow_ledger.py"), "--case-id", a.case or f"{a.flow}__{record}",
+                    "--event", "blocked", "--by", "flow_return_to_ops",
+                    "--error", f"缺 {'、'.join(gaps)}",       # 规范原因（分类器/取数口用）
+                    "--detail", msg], check=False)            # **与表里那一串逐字相同**（同源同文）
+    print(f"  ✅ 已回填并读回{'一致' if ok else '**不一致**'}｜备份 {bk.name}｜审计 flow-return-audit.jsonl")
+    print(f"     表「发票错误信息」= 台账 blocked.detail = {msg}")
+    return 0 if ok else 4
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engine/scripts/flow_source.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""flow_source —— 流程「源适配器」：把**任意来源**的字段归一化成 case，并给出字段缺口。
+
+设计（见 docs/argent-architecture.md「流程引擎」+ docs/流程能力分层与迭代计划.md）：要求侧固定（flow-requirements.json），
+供给侧可插拔（本脚本的 --source），两者之间用 **case** 对接，下游只消费 case。
+
+来源：
+  cli-json    字段来自 JSON 文件/stdin（人工、夹具、其它系统导出，**单张票**）
+  cases-json  **批量**待处理清单（`[{ticketKey, fields}]`；日报这类"单元不在表里"的流程用）
+  conversation 会话里由用户/角色提供的字段（同为 JSON，但记录 providedBy=用户）
+  feishu-base 只读拉取飞书表行（**窄投影**，按表头名映射；身份/表来自流程声明或参数）
+
+用法：
+  python3 scripts/flow_source.py --flow wenyao-invoice --source cli-json \
+      --ticket 76637122 --fields-from-json /tmp/row.json --provided-by 运营 [--json]
+  python3 scripts/flow_source.py --flow wenyao-invoice --source feishu-base \
+      --record recXXXX [--field-ids 货件号,店铺,HS编码] [--out-dir DIR] [--json]
+
+退出码：0 = 建案且字段齐备；1 = 建案但**存在缺口**（据此落卡/提示补录）；2 = 参数或源读取失败
+"""
+from __future__ import annotations
+import argparse, json, os, pathlib, subprocess, sys, tempfile, time
+
+HERE = pathlib.Path(__file__).resolve().parent
+REQ = HERE / 'flow-requirements.json'
+sys.path.insert(0, str(HERE))
+from flow_config import load_env_file      # noqa: E402 部署环境文件（唯一实现）
+try:
+    from flow_registry import consumer_doc as _registry_doc
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else REQ
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+
+FLOW_CASE = HERE / 'flow_case.py'
+SCHEMA_CHECK = HERE / 'ml_schema_check.py'
+
+# ── P4：实现已按端口拆出去（纯搬家，行为不变）─────────────────────────
+# 共享原语从这里**再导出**：`flow_triage` 的 `_truthy`、`flow_retry` 的 `load_allowed_stores`、
+# 测试里的 `ticket_key`/`wanted_pick_columns`/`apply_pick` 都还按老路径 import。
+sys.path.insert(0, str(HERE))
+from flow_sources.common import (          # noqa: E402,F401  （F401：再导出，供历史调用点）
+    CMD_RETRIES, CMD_TIMEOUT_SEC, LAST_NARROW, LAST_PICK_NOTES, PHASES, TRANSIENT_PAT,
+    _flat, _has_value, _is_transient, _truthy, apply_pick, load_allowed_stores,
+    read_cases_batch, read_cases_notes, read_fields, required_projection, run,
+    ticket_key, wanted_pick_columns, wanted_upstream_columns,
+)
+from flow_sources import kinds as _source_kinds, load as _load_source   # noqa: E402
+
+
+
+# ── Source 端口表（P4 第一步，2026-09-29）─────────────────────────
+# 为什么要有它：`--source` 此前只是**命令行参数**，业务线的数据面无法在注册表里声明，
+# 也无法被门禁校验。现在：**注册表 `source.kind` 声明该流程的数据面**，本表声明引擎实现了哪些。
+#   kind          ：注册表里的取值
+#   needs_args    ：必须由命令行补齐的输入（cli-json/conversation 要 --ticket + --fields-from-json）
+#   registry_driven：是否支持"完全按注册表声明跑"（= 定时轮能用），否则只作手工/夹具通道
+SOURCES: dict = {
+    'feishu-base': {'needs_args': (), 'registry_driven': True, 'module': 'flow_sources.feishu_base',
+                    'note': '飞书 Base 行（窄投影 + 表头名映射）—— 当前唯一的定时轮数据面'},
+    'cases-json': {'needs_args': ('--from-json 或 source.file',), 'registry_driven': True,
+                   'module': 'flow_sources.cases_json',
+                   'note': '批量清单文件（生成器产出的待处理单元；日报走这条）'},
+    'cli-json': {'needs_args': ('--ticket', '--fields-from-json'), 'registry_driven': False, 'inline': True,
+                 'note': '手工/外部喂字段（会话与排障用）'},
+    'conversation': {'needs_args': ('--ticket', '--fields-from-json'), 'registry_driven': False, 'inline': True,
+                     'note': '会话来源（同 cli-json，provenance 记为 conversation）'},
+}
+
+
+def source_kinds() -> list:
+    """已实现的 source kind（供门禁/文档/CLI 消费）。"""
+    return sorted(SOURCES)
+
+
+def _assert_kinds_aligned() -> None:
+    """**声明了 module 的 kind 必须有对应模块**（两处漂移会让"声明了但没实现"溜过去）。
+
+    注意区分两件事（P4 迁移中的真实状态）：
+      · `SOURCES`   = 引擎**已实现**的数据面（含三个仍内联在 main() 里的手工/夹具通道）；
+      · `MODULES`   = 已抽成端口模块的实现（目前只有 feishu-base）。
+    等三个内联通道也抽成模块后，这里的判据收紧为"两者相等"。
+    """
+    claim_module = {k for k, v in SOURCES.items() if v.get('module')}
+    implemented = set(_source_kinds())
+    # 每个已实现的数据面必须**要么**登记了 module（端口实现），**要么**显式标 inline（引擎内联：手工/夹具通道）
+    inline = {k for k, v in SOURCES.items() if v.get('inline')}
+    covered = claim_module | inline
+    if covered != set(SOURCES):
+        raise SystemExit(f'source 端口表有未归类项：{sorted(set(SOURCES) - covered)}'
+                         f'（要么给它 module，要么标 inline —— 别让它含糊地"存在但没交代"）')
+    if claim_module != implemented:
+        raise SystemExit(f'source 端口表不一致：声明了 module 但没实现={sorted(claim_module - implemented)}；'
+                         f'实现了但没登记={sorted(implemented - claim_module)}')
+    # 逐个校验契约（KIND 一致 + 恰好一个 pull/pull_cases）——半迁移的模块启动即失败
+    from flow_sources import validate_module                     # noqa: PLC0415
+    for k in sorted(implemented):
+        validate_module(k)
+
+
+def declared_kind(spec: dict) -> str:
+    """该流程在注册表里声明的数据面（`source.kind`），缺省 feishu-base（历史行为）。"""
+    return str((spec.get('source') or {}).get('kind') or 'feishu-base')
+
+
+def load_flow(flow_id: str, registry: str | None = None) -> dict:
+    req = pathlib.Path(registry) if registry else REQ
+    # ⚠️ 两个坑（2026-09-29 P2a 实测）：
+    #   ① 只有**调用方显式给了 registry** 才按单文件读；否则必须走合并
+    #      （`req` 恒为真 ⇒ 原写法把合并退化成"只读 base"，业务线流程全部"未知"）；
+    #   ② 旧 id（`full`）要经别名解析成规范 id（`<vertical>.<flow>`）后再查。
+    doc = _registry_doc(str(registry) if registry else None)
+    canonical = (doc.get('aliases') or {}).get(flow_id, flow_id)
+    spec = (doc.get('flows') or {}).get(canonical)
+    # 字段要求按**当前变体**取（FULL：legacy 用「店铺名称/品名」，lip 用「店铺/产品名称」）。
+    # 这里是投影列的唯一来源 ⇒ 失败时退回流程级，宁可退也不能炸。
+    try:
+        import flow_config as _fc
+        # ⚠️ 不能把 base 路径当 registry_path 传（那会强制单文件读 ⇒ 业务线流程全部"未知"，
+        # 且 flow_config.die 抛的是 SystemExit，不被 except Exception 捕获 —— 2026-09-29 实测）。
+        _req = _fc.load_config(flow_id, registry_path=registry, strict=False).get('required')
+        if _req:
+            spec = {**spec, 'required': _req}
+    except Exception:
+        pass
+    if not spec:
+        print(f'未知流程: {flow_id}（可用: {", ".join((doc.get("flows") or {}).keys())}）', file=sys.stderr)
+        sys.exit(2)
+    return spec
+
+
+# 瞬时故障特征（飞书 API / 网关）：命中就重试，其余错误立即返回（不掩盖真问题）
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+def main(argv=None) -> int:
+    _assert_kinds_aligned()
+    ap = argparse.ArgumentParser(description='流程源适配器：来源 → case → 字段缺口')
+    ap.add_argument('--flow', help='流程 id（--list-sources 时可省）')
+    ap.add_argument('--registry', help='覆盖流程注册表（测试/多部署用，同 flow_config --registry）')
+    ap.add_argument('--source', choices=source_kinds(),
+                    help='数据面种类（默认取注册表 source.kind；choices 从 SOURCES 表派生）')
+    ap.add_argument('--list-sources', action='store_true',
+                    help='列出引擎实现的 source kind（P4 端口表，供门禁/文档消费）')
+    ap.add_argument('--list-phases', action='store_true',
+                    help='列出引擎**实际产出**的相位（唯一真源 = flow_sources/common.py#PHASES；'
+                         'check-sop-consistency.mjs 的 C2 问这里，不再解析源码文本）')
+    ap.add_argument('--no-regenerate', action='store_true',
+                    help='不跑 source.regenerate、也不查过期（仅夹具/排障：读别处的临时清单时用）')
+    ap.add_argument('--from-json', dest='from_json',
+                    help='cases-json 的批量输入文件（- = stdin；省略则用流程声明的 source.file）')
+    ap.add_argument('--ticket', help='票据键（cli-json/conversation 必填；feishu 可作按票号过滤）')
+    ap.add_argument('--fields-from-json', help='字段 JSON 文件路径或 -（stdin）')
+    ap.add_argument('--provided-by', default='运营', help='字段提供者（provenance）')
+    ap.add_argument('--base'); ap.add_argument('--table'); ap.add_argument('--profile')
+    ap.add_argument('--record', help='只取指定 record（feishu-base）')
+    ap.add_argument('--field-ids', help='窄投影列（**字段 id 或名**，逗号分隔；省略则用流程必需字段前 6 个非系统字段）')
+    ap.add_argument('--ticket-field', default='货件号', help='用哪一列作为票据键（默认 货件号）')
+    ap.add_argument('--no-pick-filter', action='store_true',
+                    help='不按流程声明的 pick（候选收窄）过滤；默认按声明过滤')
+    ap.add_argument('--no-route-filter', action='store_true',
+                    help='关闭按 routing.routeBy==match 的候选行收窄（默认开启）')
+    ap.add_argument('--limit', type=int, help='最多取多少行（feishu-base）')
+    ap.add_argument('--out-dir', help='case 落盘目录（默认 ~/.dsh/argent/flow-cases）')
+    ap.add_argument('--skip-gap', action='store_true', help='只建案，不做字段缺口检查')
+    ap.add_argument('--json', action='store_true')
+    args = ap.parse_args(argv)
+    if args.list_sources:
+        print(json.dumps(SOURCES, ensure_ascii=False, indent=2))
+        return 0
+    if args.list_phases:
+        # 一行 JSON（门禁按行解析）：相位的**唯一真源**在 common.py，这里只做转达
+        print(json.dumps({'phases': list(PHASES)}, ensure_ascii=False))
+        return 0
+    if not args.flow:
+        ap.error('--flow 必填（除非用 --list-sources）')
+
+    spec = load_flow(args.flow, args.registry)
+    # P4：数据面由**注册表声明**（`source.kind`），命令行只作覆盖（测试/排障）。
+    if not args.source:
+        args.source = declared_kind(spec)
+    if args.source not in SOURCES:
+        print(f'❌ 未实现的 source kind：{args.source}（已实现：{", ".join(source_kinds())}）', file=sys.stderr)
+        return 2
+
+    # ① 取字段
+    if args.source == 'feishu-base':
+        # P4：实现按端口载入（`flow_sources.MODULES` 是 kind → 模块的唯一映射）
+        rows = _load_source('feishu-base').pull(spec, args)
+        if not rows:
+            if LAST_NARROW.get('emptied'):
+                # 读到了行、但按流程声明的 pick 收窄后为空 ⇒ **合法结论**（本轮无事可做）
+                info = dict(LAST_NARROW.get('info') or {})
+                notes = list(info.pop('notes', []) or [])
+                if info.get('droppedDone'):
+                    notes.append(f'已排除 {info["droppedDone"]} 张已完成'
+                                 f'（人工/既往做过的行，判据 pick.exclude*）')
+                if info.get('before'):
+                    notes.append(f'读取 {info["before"]} 行 → 门内 0 行（说明是历史/未放行数据，不是遗漏）')
+                if args.json:
+                    print(json.dumps({'flow': args.flow, 'source': args.source, 'cases': [], 'exit': 0,
+                                      'narrowedToEmpty': True, 'pick': info, 'notes': notes},
+                                     ensure_ascii=False, indent=2))
+                else:
+                    print('  · 候选收窄后为空（当前没有该动的行）'
+                          + (f'：{"；".join(notes)}' if notes else ''))
+                return 0
+            print('⚠️ 未取到任何行（检查 --record/筛选条件）', file=sys.stderr)
+            return 2
+    elif args.source == 'cases-json':
+        # P4：实现已抽到 flow_sources.cases_json（契约：(exit_code|None, rows)）
+        code, rows = _load_source('cases-json').pull_cases(spec, args)
+        if code is not None:
+            return code
+    else:
+        if not args.ticket or not args.fields_from_json:
+            print('❌ cli-json/conversation 需要 --ticket 与 --fields-from-json', file=sys.stderr)
+            return 2
+        try:
+            rows = [(str(args.ticket), read_fields(args.fields_from_json))]
+        except Exception as e:
+            print(f'❌ 读取字段失败: {e}', file=sys.stderr)
+            return 2
+
+    kind = ('conversation' if args.source == 'conversation'
+            else 'feishu-base' if args.source == 'feishu-base'
+            else 'cases-json' if args.source == 'cases-json' else 'cli-json')
+    source_id = (f'chat-{args.profile or spec.get("source", {}).get("identity", "session")}'
+                 if kind == 'conversation' else f'{args.flow}-{kind}')
+    results, worst = [], 0
+    for ticket, fields in rows:
+        # ② 建/合并 case
+        case_cmd = [sys.executable, str(FLOW_CASE), '--flow', args.flow, '--ticket', ticket,
+                    '--source-id', source_id, '--source-kind', kind, '--provided-by', args.provided_by,
+                    '--fields-from-json', '-']
+        if args.out_dir:
+            case_cmd += ['--out-dir', args.out_dir]
+        p = subprocess.run(case_cmd, input=json.dumps(fields, ensure_ascii=False),
+                           capture_output=True, text=True)
+        if p.returncode not in (0, 1):
+            print(f'❌ 建案失败 {ticket}: {(p.stderr or p.stdout).strip()[:300]}', file=sys.stderr)
+            return 2
+        worst = max(worst, p.returncode)
+
+        item = {'ticket': ticket, 'caseExit': p.returncode, 'caseLine': (p.stdout or '').strip().splitlines()[:1]}
+        # ③ 字段缺口
+        if not args.skip_gap:
+            # **只把"真有值"的字段算作已提供** —— 见 `_has_value()` 的说明：
+            # 投影覆盖的列即使为空也会出现在 fields 里，不过滤 ⇒ 放行开关（发票就绪）形同虚设。
+            provided = sorted(k for k, v in (fields or {}).items() if _has_value(v))
+            with tempfile.NamedTemporaryFile('w', suffix='.json', delete=False, encoding='utf-8') as tf:
+                json.dump(provided, tf, ensure_ascii=False); tmp = tf.name
+            g = subprocess.run([sys.executable, str(SCHEMA_CHECK), '--flow', args.flow,
+                                '--fields-from-json', tmp, '--json'], capture_output=True, text=True)
+            pathlib.Path(tmp).unlink(missing_ok=True)
+            if g.returncode in (0, 1) and g.stdout.strip().startswith('{'):
+                gj = json.loads(g.stdout)
+                item['ok'] = bool(gj.get('ok'))
+                item['missing'] = [m.get('name') for m in (gj.get('missing') or [])]
+                if not gj.get('ok'):
+                    worst = max(worst, 1)
+            else:
+                item['gapError'] = (g.stderr or g.stdout).strip()[:200]
+                worst = max(worst, 1)      # 缺口检查失败 ⇒ 不低于"有缺口"的严重度
+        results.append(item)
+
+    if args.json:
+        print(json.dumps({'flow': args.flow, 'source': args.source, 'cases': results,
+                          'exit': worst, 'notes': list(LAST_PICK_NOTES)}, ensure_ascii=False, indent=2))
+    else:
+        for r in results:
+            if r.get('ok'):
+                print(f'  ✅ {r["ticket"]}：字段齐备（case 退出码 {r["caseExit"]}）')
+            else:
+                miss = '、'.join((r.get('missing') or [])[:8]) or '(未知)'
+                print(f'  ⚠️ {r["ticket"]}：缺 {len(r.get("missing") or [])} 个字段 → {miss}')
+    return worst
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/engine/scripts/flow_sources/__init__.py

@@ -0,0 +1,53 @@
+"""Source 端口实现（P4，2026-09-29）。
+
+一个数据面 = 本目录下**一个模块**：模块导出 `KIND` 与 `pull(spec, args)`（返回
+`[(record_id, fields), …]`），引擎只负责调度与输出形状（见 `scripts/flow_source.py`）。
+加一种数据面 = 加一个文件 + 在注册表 `source.kind` 里声明 ⇒ **不改引擎**。
+
+为什么这么切：`flow_source.py` 曾是"引擎 + 飞书实现"糊在一起（897 行），
+业务线想接自己的数据面只能改引擎 —— 那正是"底座被单一通道绑架"的形态。
+"""
+from __future__ import annotations
+
+import importlib
+
+# kind → 实现模块（模块必须导出 KIND 与 pull）
+MODULES: dict = {
+    'feishu-base': 'flow_sources.feishu_base',
+    'cases-json': 'flow_sources.cases_json',
+}
+
+
+def kinds() -> list:
+    """已实现的数据面种类（与 flow_source.SOURCES 的键必须一致，门禁会校验）。"""
+    return sorted(MODULES)
+
+
+def validate_module(kind: str) -> str:
+    """校验某 kind 的实现模块符合端口契约，返回它的**形态**（`rows` | `cases`）。
+
+    两种形态（现实里确实有两种数据面，别硬凑成一种）：
+      · `rows` ：外部数据源给"记录 + 字段"，引擎负责建案/缺口检查 —— 导出 `pull(spec, args)`；
+      · `cases`：上游已产出**待处理单元**（如日报的店铺×日期×幂等标记差集）—— 导出 `pull_cases(spec, args)`。
+
+    契约自校验放在这里（而不是各实现里）⇒ 半迁移的模块会在**启动时**响亮失败，
+    而不是运行到一半才炸。`flow_source._assert_kinds_aligned()` 会逐个调用它。
+    """
+    mod = load(kind)
+    declared = getattr(mod, 'KIND', None)
+    if declared != kind:
+        raise SystemExit(f'source 实现 {MODULES[kind]} 的 KIND={declared!r} 与登记不一致（应为 {kind!r}）')
+    has_pull = callable(getattr(mod, 'pull', None))
+    has_cases = callable(getattr(mod, 'pull_cases', None))
+    if has_pull == has_cases:
+        raise SystemExit(f'source 实现 {MODULES[kind]} 必须**恰好**导出 pull() 或 pull_cases() 之一'
+                         f'（当前 pull={has_pull} pull_cases={has_cases}）')
+    return 'rows' if has_pull else 'cases'
+
+
+def load(kind: str):
+    """按 kind 载入实现模块（惰性 import：没装/没用的实现不该拖慢每次分诊）。"""
+    mod_name = MODULES.get(kind)
+    if not mod_name:
+        raise KeyError(kind)
+    return importlib.import_module(mod_name)