@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow_capability_stats.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""按**能力**观测（迭代 3-⑬）：把"按 flow 平铺"的台账聚合成「能力 → 成功率 / 耗时 / 卡点 / 集成健康度」。
+
+## 为什么要按能力聚合
+2026-09-20 的三次故障（step7 箱唛 64s、放行勾漏清、PO 映射错）都不是"某条 flow 坏了"，而是
+**某个能力/某个集成**的共性问题的两次显形。按 flow 平铺只能看到"今天哪条红了"，
+按能力看才能看到"发票这个能力最近三次都卡在同一阶段"。
+
+## 口径（都从既有台账派生，不新增埋点）
+- 台账事件：`dispatched / done / failed / blocked / failed_ack / phase / retry / wake`；
+- **成功率** = `done / (done + failed + blocked)`（`failed_ack`=人工判定与流程无关 ⇒ 不计入分母）；
+- **耗时** = 同一 caseId 的 `dispatched → 终态` 的秒数差（取终态前最近一次 dispatched）；
+- **卡点** = `phase` 事件里**失败 case 最后停留的阶段**（各能力最多的一条）；
+- **集成健康度** = 该集成适配器声明的 `ERROR_CLASSES` 对失败文本的分类命中数 + 最近一次命中时间；
+- **未处置** = 走 `flow_failure.classify`（与失败回路**同一套判据**，不另立一套）。
+
+用法：
+    python3 scripts/flow_capability_stats.py [--days 7] [--json] [--flow <id>] [--ledger <path>]
+退出码：0 正常；2 读取失败。
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import pathlib
+import sys
+
+try:
+    from flow_registry import consumer_doc as _registry_doc      # P2a：base + 业务线合并（唯一真源）
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else (HERE / "flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+from stdio_utf8 import use_utf8_stdio  # noqa: E402  出口编码钉 UTF-8（中文 Windows 的 GBK 管道下非 ASCII 会崩）
+
+REGISTRY = HERE / "flow-requirements.json"
+TERMINAL = ("done", "failed", "blocked", "failed_ack")
+PHASE_GAP_MAX = 6 * 3600      # 阶段分段上限（超过视为挂起，不计入阶段耗时）
+KIND_CN = {"needs_human": "等人补数据", "needs_agent": "需判断/集成问题",
+           "retryable": "可重试", "unknown": "未分类"}
+
+
+def load() -> dict:
+    return _registry_doc()
+
+
+def read_ledger(path: pathlib.Path) -> list:
+    out = []
+    if not path.exists():
+        return out
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except Exception:  # noqa: BLE001
+            continue
+        if isinstance(rec, dict):
+            out.append(rec)
+    return out
+
+
+def median(xs: list) -> float:
+    xs = sorted(float(x) for x in xs)
+    if not xs:
+        return 0.0
+    mid = len(xs) // 2
+    return xs[mid] if len(xs) % 2 else (xs[mid - 1] + xs[mid]) / 2
+
+
+def _ts(rec: dict) -> float:
+    try:
+        return float(rec.get("ts") or 0)
+    except Exception:  # noqa: BLE001
+        return 0.0
+
+
+def _flow_of(case_id: str) -> str:
+    return str(case_id).split("__", 1)[0] if "__" in str(case_id) else ""
+
+
+def _classify(error: str, attempt=None) -> str:
+    try:
+        from flow_failure import classify          # 与失败回路同一套判据
+        return str(classify(error, attempt).get("kind") or "")
+    except Exception:  # noqa: BLE001
+        return ""
+
+
+def _adapter_error_hits(integration: str, errors: list) -> dict:
+    """集成健康度：用适配器自己的 ERROR_CLASSES 给失败文本归类（不另立一份词表）。"""
+    if not integration:
+        return {"status": "", "hits": {}, "byKind": {}, "lastHitAt": ""}
+    try:
+        import integration_contract as C
+        mod = C.load(integration)
+    except Exception:  # noqa: BLE001
+        return {"status": "", "hits": {}, "byKind": {}, "lastHitAt": ""}
+    import re
+    rules = []
+    for pair in (getattr(mod, "ERROR_CLASSES", None) or {}).items() if isinstance(getattr(mod, "ERROR_CLASSES", None), dict) else []:
+        rules.append((str(pair[0]), str(pair[1])))
+    if not rules:
+        for item in (getattr(mod, "ERROR_CLASSES", None) or []):
+            try:
+                pat, kind = item[0], item[1]
+            except Exception:  # noqa: BLE001
+                continue
+            rules.append((str(pat), str(kind)))
+    hits, by_kind, last = {}, {}, 0.0
+    for err, ts in errors:
+        # ① 集成自身错误词表命中（"这个集成在报错"）
+        for pat, kind in rules:
+            try:
+                if re.search(pat, err, re.I):
+                    hits[kind] = hits.get(kind, 0) + 1
+                    last = max(last, ts)
+                    break
+            except re.error:
+                continue
+        # ② 失败**性质**（与失败回路同一判据）：区分"集成坏了(needs_agent)"与
+        #    "运营没填数据(needs_human)"—— 否则面板上"失败 5 次"会被读成"文鳐门户不稳"，
+        #    实际是等人补字段（2026-09-20 用户读面板时问到的正是这一处）。
+        k = _classify(err) or "unknown"
+        by_kind[k] = by_kind.get(k, 0) + 1
+    return {
+        "status": str(getattr(mod, "STATUS", "") or ""),
+        "hits": hits,
+        "byKind": by_kind,
+        "lastHitAt": dt.datetime.fromtimestamp(last).strftime("%Y-%m-%d %H:%M") if last else "",
+    }
+
+
+def stats(days: float = 7, ledger: pathlib.Path | None = None, only_flow: str = "",
+          doc: dict | None = None) -> dict:
+    d = doc or load()
+    since = dt.datetime.now().timestamp() - days * 86400
+    # 台账目录走**唯一判据**（三级链；勿在此复制链 —— 此前硬编码 ⇒ 隔离实例读生产台账）
+    led = ledger or (pathlib.Path(resolve_data_dir()['dir']) / "flow-ledger.jsonl")
+    recs = [r for r in read_ledger(led) if _ts(r) >= since]
+
+    caps = {k: v for k, v in (d.get("capabilities") or {}).items() if not k.startswith("_")}
+    flows = d.get("flows") or {}
+    out = {}
+    for cid, c in caps.items():
+        out[cid] = {"minPlan": c.get("minPlan", ""), "flows": [], "runs": 0, "done": 0, "failed": 0,
+                    "blocked": 0, "acked": 0, "successRate": None, "avgSec": None, "slowestPhase": "",
+                    "stuckAt": "", "pending": [], "integrations": {}, "lastAt": ""}
+    for fid, spec in flows.items():
+        cid = str((spec or {}).get("capability") or "")
+        if cid not in out:
+            continue
+        # P2a：`--flow` 可能给短名（旧 id）而注册表是规范 id ⇒ 先解析别名
+        _alias0 = d.get("aliases") or {}
+        _only = _alias0.get(only_flow, only_flow) if only_flow else ""
+        if _only and fid != _only:
+            continue
+        out[cid]["flows"].append(fid)
+        # P2a：台账里的 caseId 前缀是**写台账时的流程名**（历史与新数据都可能是旧名），
+        # 而注册表里是规范 id ⇒ 归属比较必须过一遍别名，否则统计会集体归零。
+        _alias = d.get("aliases") or {}
+        _canon = lambda pfx: _alias.get(pfx, pfx)                      # noqa: E731
+        mine = [r for r in recs if _canon(_flow_of(str(r.get("caseId") or ""))) == fid]
+        by_case: dict = {}
+        for r in mine:
+            by_case.setdefault(str(r.get("caseId") or ""), []).append(r)
+        errs = []
+        for case_id, rs in by_case.items():
+            rs.sort(key=_ts)
+            disp = [x for x in rs if x.get("event") == "dispatched"]
+            term = [x for x in rs if x.get("event") in TERMINAL]
+            # runs = 窗口内有活动的 case 数（不是 dispatched 事件数）：跨窗口的长任务
+            # 可能"终态在窗口内、派发在窗口外"，只数 dispatched 会让成功率分母与分子对不上
+            # （2026-09-20 实测 full 出现 done=25 / runs=1 的假象）。
+            if disp or term:
+                out[cid]["runs"] += 1
+            if term:
+                ev = term[-1].get("event")
+                if ev == "done":
+                    out[cid]["done"] += 1
+                elif ev == "failed":
+                    out[cid]["failed"] += 1
+                elif ev == "blocked":
+                    out[cid]["blocked"] += 1
+                elif ev == "failed_ack":
+                    out[cid]["acked"] += 1
+                if disp:
+                    secs = max(0.0, _ts(term[-1]) - _ts(disp[-1]))
+                    if secs and secs < 86400:
+                        out[cid].setdefault("_dur", []).append(secs)
+                if term[-1].get("event") in ("failed", "blocked"):
+                    phases = [x for x in rs if x.get("event") == "phase"]
+                    if phases:
+                        out[cid]["stuckAt"] = str(phases[-1].get("phase") or "") or out[cid]["stuckAt"]
+            # 集成健康度要的是**所有失败事件**（含被 retry 后成功的）：只统计终态失败会漏掉
+            # "这个集成老在超时"这种最该看见的信号（2026-09-20 实测：net::ERR 重试成功后健康度里查无此事）。
+            for x in rs:
+                if x.get("event") != "failed":
+                    continue
+                errs.append((str(x.get("error") or x.get("detail") or "").strip(), _ts(x)))
+            # 阶段耗时：相邻 phase 事件的间隔归给**前一个**阶段（最后一段归给终态）
+            phases = [x for x in rs if x.get("event") == "phase"]
+            marks = [(str(x.get("phase") or ""), _ts(x)) for x in phases]
+            if term:
+                marks.append(("（收尾）", _ts(term[-1])))
+            for i in range(len(marks) - 1):
+                name, t0 = marks[i]
+                gap = marks[i + 1][1] - t0
+                # 只统计 <6h 的分段：隔夜挂起的 case（等运营补数据）会把"某阶段耗时"拉到几十小时，
+                # 那种数字没有诊断价值（≠ 该阶段真的慢）。窗口外的分段直接丢弃并在输出里标注。
+                if name and 0 < gap < PHASE_GAP_MAX:
+                    out[cid].setdefault("_phase", {}).setdefault(name, []).append(gap)
+        out[cid]["lastAt"] = dt.datetime.fromtimestamp(max([_ts(r) for r in mine] or [0])).strftime("%Y-%m-%d %H:%M") if mine else ""
+        # 未处置：**直接复用失败回路的 pending()**（不是"我照它写一遍"）——
+        # 判据含"blocked 之后没有 failed_ack 仍算未处置"这条 2026-09-18 的修正，
+        # 自己重写必然慢慢漂移。
+        try:
+            from flow_failure import pending as failure_pending
+            for it in failure_pending(led, flow=fid):
+                out[cid]["pending"].append({
+                    "caseId": str(it.get("caseId") or ""), "kind": str(it.get("kind") or ""),
+                    "error": str(it.get("error") or "")[:160],
+                    "at": dt.datetime.fromtimestamp(float(it.get("ts") or 0)).strftime("%Y-%m-%d %H:%M"),
+                })
+        except Exception:  # noqa: BLE001
+            pass
+        # 集成健康度（能力下可能挂多个集成，如发票 = 文鳐 + 鑫中航）
+        integ = str((spec or {}).get("integration") or "")
+        if integ:
+            slot = out[cid]["integrations"].setdefault(
+                integ, {"status": "", "hits": {}, "byKind": {}, "lastHitAt": "", "errors": 0, "lastError": ""})
+            h = _adapter_error_hits(integ, errs)
+            slot["status"] = h["status"] or slot["status"]
+            slot["errors"] += len(errs)
+            for k, n in (h.get("byKind") or {}).items():
+                slot["byKind"][k] = slot["byKind"].get(k, 0) + n
+            if errs:
+                newest = max(errs, key=lambda e: e[1])
+                if newest[1] >= 0 and (not slot["lastError"] or True):
+                    slot["lastError"] = str(newest[0])[:160]
+            for k, v in (h["hits"] or {}).items():
+                slot["hits"][k] = slot["hits"].get(k, 0) + v
+            slot["lastHitAt"] = max(slot["lastHitAt"], h["lastHitAt"])
+
+    for cid, v in out.items():
+        dur = v.pop("_dur", [])
+        phase = v.pop("_phase", {})
+        v["avgSec"] = round(sum(dur) / len(dur)) if dur else None
+        # 中位数而不是均值：长挂起的 case（隔夜等运营补数据）会把均值拉到小时级，
+        # 均值看着像"每条发票要跑 3 小时"，中位数才反映典型耗时。
+        v["medianSec"] = round(median(dur)) if dur else None
+        v["phases"] = {k: round(median(x)) for k, x in
+                       sorted(phase.items(), key=lambda kv: -median(kv[1]))[:5]}
+        v["slowestPhase"] = (f"{next(iter(v['phases']))} ≈{v['phases'][next(iter(v['phases']))]}s"
+                            if v["phases"] else "")
+        denom = v["done"] + v["failed"] + v["blocked"]
+        v["successRate"] = round(v["done"] / denom, 3) if denom else None
+        v["pendingCount"] = len(v["pending"])
+        v["pending"] = v["pending"][:5]
+    return {"windowDays": days, "ledger": str(led), "generatedAt": dt.datetime.now().isoformat(timespec="seconds"),
+            "capabilities": out}
+
+
+def main(argv=None) -> int:
+    use_utf8_stdio()   # 唯一出口编码判据：见 scripts/lib/stdio_utf8.py 的事故说明
+    ap = argparse.ArgumentParser(description="按能力观测（成功率/耗时/卡点/集成健康度）")
+    ap.add_argument("--days", type=float, default=7)
+    ap.add_argument("--ledger")
+    ap.add_argument("--flow")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+    try:
+        data = stats(a.days, pathlib.Path(a.ledger) if a.ledger else None, a.flow or "")
+    except Exception as exc:  # noqa: BLE001
+        print(f"❌ 读取台账失败：{exc}", file=sys.stderr)
+        return 2
+    if a.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    print(f"  窗口：最近 {data['windowDays']:g} 天 · 台账 {data['ledger']}")
+    for cid, v in data["capabilities"].items():
+        rate = "—" if v["successRate"] is None else f"{v['successRate'] * 100:.0f}%"
+        dur = "—" if v["medianSec"] is None else f"中位 {v['medianSec']}s"
+        print(f"  {cid:18} 档位={v['minPlan']:11} 流程={len(v['flows'])} 跑={v['runs']} "
+              f"成功={v['done']}/失败={v['failed']}/等人={v['blocked']} 成功率={rate} 平均={dur}")
+        if v["stuckAt"]:
+            print(f"      卡点：{v['stuckAt']}")
+        if v.get("slowestPhase"):
+            print("      阶段耗时中位（只算 <6h 的分段）："
+                  + "、".join(f"{k}≈{s2}s" for k, s2 in v["phases"].items()))
+        for name, h in (v["integrations"] or {}).items():
+            hits = "、".join(f"{k}×{n}" for k, n in (h["hits"] or {}).items()) or "无命中"
+            kinds = "、".join(f"{KIND_CN.get(k, k)} {n}" for k, n in (h.get("byKind") or {}).items()) or "—"
+            print(f"      集成 {name}（{h['status'] or '?'}）：失败 {h['errors']} 次（{kinds}）· 词表命中 {hits}"
+                  + (f" · 最近 {h['lastHitAt']}" if h["lastHitAt"] else ""))
+            if h.get("lastError"):
+                print(f"          最近错误：{h['lastError'][:120]}")
+        if v["pendingCount"]:
+            print(f"      未处置 {v['pendingCount']} 条："
+                  + "；".join(f"{p['caseId']}[{p['kind']}]" for p in v["pending"][:3]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/engine/scripts/flow_case.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""流程「案件（case）」归一化层 —— 把**任意来源**的字段收敛成统一中间表示。
+
+为什么需要：数据源现在只有飞书表，将来会有别的方式（用户在会话里给字段、CSV、其他系统…）。
+做法是**要求侧与供给侧分离**：要求侧固定（`scripts/flow-requirements.json`：每流程必需字段 + 谁补），
+供给侧做**可插拔适配器**；两者之间用 **case** 对接，下游（分诊/闸门/执行/回写）只消费 case。
+
+case 契约（version 1）：
+    {
+      "version": 1,
+      "caseId": "<flowId>__<ticketKey>",         # 幂等键：同流程同票 = 同 case
+      "flowId": "wenyao-invoice",
+      "ticketKey": "76637122",
+      "fields": { "<字段名>": <值>, ... },
+      "provenance": {                              # ★硬要求★ 每个字段的来源与提供者
+         "<字段名>": {"sourceId": "...", "sourceKind": "feishu-base|conversation|cli-json|...",
+                      "providedBy": "<谁>", "at": "<ISO8601>"}
+      },
+      "sources": ["<sourceId>", ...],              # 本 case 累积过的来源
+      "conflicts": [ {"field": "...", "kept": {...}, "rejected": {...}} ],
+      "createdAt": "...", "updatedAt": "..."
+    }
+
+用法：
+    python3 scripts/flow_case.py --flow wenyao-invoice --ticket 76637122 \
+        --source-id lip-feishu --source-kind feishu-base --provided-by 运营 \
+        --fields-from-json /tmp/row.json [--out-dir ~/.dsh/argent/flow-cases] [--json]
+
+退出码：0 = 写入/合并成功且无冲突 ; 1 = 有冲突（**落卡等人确认**，case 仍写入）; 2 = 参数/IO 错误
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+import pathlib
+import sys
+
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链 `ARGENT_DATA_DIR` →
+# `$DSH_HOME/argent` → `~/.dsh/argent`，与 JS 内核 `core/lib/argent-datadir.mjs` 同语义）。
+# 历史：本文件曾**连 ARGENT_DATA_DIR 都不看** ⇒ 隔离跑（MCP 影子沙箱、测试夹具）写的 case
+# 全落进**真实** `~/.dsh/argent/flow-cases/`（2026-10-02 实测：`r-flow__T-NEW` 夹具件污染生产目录）；
+# 后改两级链（不看 DSH_HOME）。现在一律走唯一判据。
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402
+DEFAULT_OUT = pathlib.Path(resolve_data_dir()['dir']) / 'flow-cases'
+CASE_VERSION = 1
+
+
+def _now() -> str:
+    return _dt.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def safe_key(ticket_key: str) -> str:
+    """文件名安全化：票号可能含 `/`（一个单元格写两个货件号）等路径字符。
+
+    逻辑键（caseId 内的 ticketKey）保持原样，仅**落盘文件名**替换危险字符，
+    避免 `a/b` 被当成目录。
+    """
+    bad = '/\\:*?"<>|\n\r\t '
+    out = ''.join('-' if c in bad else c for c in str(ticket_key)).strip('-')
+    return out or 'unknown'
+
+
+def case_id(flow_id: str, ticket_key: str) -> str:
+    return f"{flow_id}__{ticket_key}"
+
+
+def build_case(flow_id: str, ticket_key: str, fields: dict, source_id: str,
+               source_kind: str, provided_by: str, at: str | None = None) -> dict:
+    """从**一个来源**构造 case（新 case）。"""
+    at = at or _now()
+    return {
+        "version": CASE_VERSION,
+        "caseId": case_id(flow_id, ticket_key),
+        "flowId": flow_id,
+        "ticketKey": str(ticket_key),
+        "fields": dict(fields),
+        "provenance": {k: {"sourceId": source_id, "sourceKind": source_kind,
+                           "providedBy": provided_by, "at": at} for k in fields},
+        "sources": [source_id],
+        "conflicts": [],
+        "createdAt": at,
+        "updatedAt": at,
+    }
+
+
+def merge_case(existing: dict, flow_id: str, ticket_key: str, fields: dict, source_id: str,
+               source_kind: str, provided_by: str, at: str | None = None) -> tuple[dict, list]:
+    """把一个来源的字段**合并**进已有 case。
+
+    规则（对应红线要求）：
+    1. **新字段** → 直接并入，记 provenance；
+    2. **同值** → 仅追加来源（幂等，不产生冲突）；
+    3. **不同值** → **不覆盖**，记入 `conflicts` 交人确认（**绝不静默选一个**）。
+       · 例外（2026-09-18 修）：`_` 前缀的**合成字段** 与 **同一来源**的再次读数 ⇒ 覆盖
+         （否则系统字段会被第一次读到的旧值冻住 —— 详见循环内注释）。
+       ⚠️ 这条正是"同一票在飞书表与会话里同时出现"的处理方式：冲突落卡等人。
+    """
+    at = at or _now()
+    out = json.loads(json.dumps(existing))  # 深拷贝，避免调用方对象被改
+    conflicts = []
+    for k, v in fields.items():
+        cur = out["fields"].get(k)
+        prev = out["provenance"].get(k) or {}
+        # 2026-09-18 真实故障修复：**系统维护字段必须刷新**，不能被下面的"不覆盖"规则冻住。
+        # 现场：运营在飞书表勾了「就绪」，但 case 第一次读到的是空值 ⇒ 之后每次合并都判
+        # "不同值 ⇒ 不覆盖" ⇒ `_phase` 永远停在 await_release、分诊恒为 to_dispatch=0，
+        # 触发器连续报"无票可认领"（勾了就绪也不跑）。清掉 case 目录才恢复，说明就是这里。
+        # 两类必须覆盖：① `_` 前缀的合成字段（`_phase`/`_record_id`…，系统算出来的）；
+        #              ② **同一来源**再次读到的值（同一个源刷新自己，不是跨源冲突）。
+        if k in out["fields"] and (str(k).startswith("_") or prev.get("sourceId") == source_id):
+            if str(cur) != str(v):
+                out["fields"][k] = v
+                out["provenance"][k] = {"sourceId": source_id, "sourceKind": source_kind,
+                                        "providedBy": provided_by, "at": at}
+            continue
+        if k not in out["fields"]:
+            out["fields"][k] = v
+            out["provenance"][k] = {"sourceId": source_id, "sourceKind": source_kind,
+                                    "providedBy": provided_by, "at": at}
+        elif str(cur) == str(v):
+            out["provenance"].setdefault(k, {})
+            out["provenance"][k].setdefault("alsoSeenFrom", [])
+            if source_id not in out["provenance"][k]["alsoSeenFrom"]:
+                out["provenance"][k]["alsoSeenFrom"].append(source_id)
+        else:
+            conflicts.append({
+                "field": k,
+                "kept": {"value": cur, "provenance": out["provenance"].get(k)},
+                "rejected": {"value": v, "sourceId": source_id, "sourceKind": source_kind,
+                             "providedBy": provided_by, "at": at},
+            })
+    if source_id not in out["sources"]:
+        out["sources"].append(source_id)
+    out["conflicts"] = (out.get("conflicts") or []) + conflicts
+    out["updatedAt"] = at
+    return out, conflicts
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="流程 case 归一化（多源 → 统一中间表示）")
+    ap.add_argument("--flow", required=True, help="流程 id，如 wenyao-invoice")
+    ap.add_argument("--ticket", required=True, help="票据键，如货件号 76637122")
+    ap.add_argument("--fields-from-json", required=True,
+                    help="字段 JSON 文件路径（对象），或 - 表示从 stdin 读")
+    ap.add_argument("--source-id", required=True, help="来源标识，如 lip-feishu / chat-oc_xxx")
+    ap.add_argument("--source-kind", default="cli-json",
+                    help="来源类型：feishu-base | conversation | cli-json | csv | ...")
+    ap.add_argument("--provided-by", default="unknown", help="提供者（运营/用户/角色名）")
+    ap.add_argument("--out-dir", default=str(DEFAULT_OUT))
+    ap.add_argument("--json", action="store_true", help="把 case 打到 stdout")
+    a = ap.parse_args(argv)
+
+    try:
+        raw = sys.stdin.read() if a.fields_from_json == "-" else pathlib.Path(a.fields_from_json).read_text(encoding="utf-8")
+        fields = json.loads(raw)
+        if not isinstance(fields, dict):
+            raise ValueError("字段必须是 JSON 对象")
+    except Exception as exc:  # noqa: BLE001
+        print(f"读取字段失败: {exc}", file=sys.stderr)
+        return 2
+
+    out_dir = pathlib.Path(a.out_dir).expanduser()
+    path = out_dir / f"{safe_key(case_id(a.flow, a.ticket))}.json"
+    try:
+        out_dir.mkdir(parents=True, exist_ok=True)
+        if path.exists():
+            existing = json.loads(path.read_text(encoding="utf-8"))
+            case, conflicts = merge_case(existing, a.flow, a.ticket, fields,
+                                         a.source_id, a.source_kind, a.provided_by)
+        else:
+            case = build_case(a.flow, a.ticket, fields, a.source_id, a.source_kind, a.provided_by)
+            conflicts = []
+        path.write_text(json.dumps(case, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    except Exception as exc:  # noqa: BLE001
+        print(f"写入失败: {exc}", file=sys.stderr)
+        return 2
+
+    if a.json:
+        print(json.dumps(case, ensure_ascii=False, indent=2))
+    else:
+        print(f"case {case['caseId']} 字段 {len(case['fields'])} 个｜来源 {len(case['sources'])} 个"
+              f"｜冲突 {len(conflicts)} 个 → {path}")
+        for c in conflicts:
+            print(f"  ⚠ 冲突 [{c['field']}] 保留={c['kept']['value']!r}"
+                  f"（{c['kept']['provenance'].get('sourceId') if c['kept'].get('provenance') else '?'}）"
+                  f" 拒绝={c['rejected']['value']!r}（{c['rejected']['sourceId']}）→ 需人确认")
+    return 1 if conflicts else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())