@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/flow_learn.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""裁定沉淀闭环（P6，2026-09-17）—— 用户确认一次 → **两边同时落库 + 互相引用**。
+
+分层（docs/Argent-宿主适配契约.md §1「判断归属」）：
+  · **机器判据** → 政策库（`flow-policy.jsonl`，L2 政策层）：下次同类 case 命中即执行，不再问用户；
+  · **判读知识** → 技能里的 pitfalls/SKILL（给角色/人看）：遇到**没见过**的新情况时能推理；
+  · 两边**互相指向**：政策条目带 `whyRef: <skill>#<anchor>`；markdown 条目带「判据权威：政策 `pol-…`」。
+
+为什么必须一次写完两边：只写政策 ⇒ 模型不会判读新情况；只写文档 ⇒ 脚本/引擎读不到、判据漂移。
+`--yes` 才落库（默认 dry-run）；每次落库都写台账事件 `policy_new`（审计：谁授权、依据哪条案例）。
+
+用法：
+  python3 scripts/flow_learn.py --flow full --case full__recvvgPQgoZW9B \\
+    --decision retry --kind retryable --title "瞬时类失败自动重跑" \\
+    --summary "浏览器页面被关/网络超时属瞬时类：清货件号重建（≤2 次），不叫人" \\
+    --skill skills/ml-fulfillment-sop/references/pitfalls.md --anchor C7 --yes
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+import flow_policy  # noqa: E402  政策库（同一个 append/id 生成，避免两套写法）
+
+REPO = HERE.parent
+
+
+def render_entry(policy_id: str, anchor: str, title: str, summary: str, case: str,
+                 authorizer: str, at: str, flow: str) -> str:
+    return (f"\n### {anchor} {title}（{at[:10]}，来源 `{case}`）\n\n"
+            f"- 现象/触发：{summary}\n"
+            f"- 裁定：见政策条目（{flow}）\n"
+            f"- 判据权威：政策 `{policy_id}`（`~/.dsh/argent/flow-policy.jsonl`）\n"
+            f"- 授权人：{authorizer}｜流程：{flow}\n")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="裁定沉淀：政策条目 + 技能条目（互相引用）")
+    ap.add_argument("--flow", required=True)
+    ap.add_argument("--case", required=True, help="来源 case（可追溯）")
+    ap.add_argument("--decision", required=True, choices=flow_policy.DECISIONS)
+    ap.add_argument("--kind", help="失败分类（failureKind），作为匹配条件")
+    ap.add_argument("--status", help="状态匹配条件（可选）")
+    ap.add_argument("--title", required=True, help="pitfalls 条目标题")
+    ap.add_argument("--summary", required=True, help="现象/触发（写进 pitfalls）")
+    ap.add_argument("--skill", required=True, help="pitfalls/SKILL 文件（相对仓库或绝对路径）")
+    ap.add_argument("--anchor", required=True, help="锚点（如 C7），政策 whyRef 指向它")
+    ap.add_argument("--authorizer", default="用户")
+    ap.add_argument("--max-attempts", type=int)
+    ap.add_argument("--yes", action="store_true", help="真写（默认 dry-run）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    skill_path = pathlib.Path(a.skill)
+    if not skill_path.is_absolute():
+        skill_path = REPO / skill_path
+    if not skill_path.exists():
+        print(f"❌ skill 文件不存在：{skill_path}（先建文件再加条目，避免引用悬空）", file=sys.stderr)
+        return 2
+    if a.anchor not in skill_path.read_text(encoding="utf-8") and not a.yes:
+        pass  # 允许首次新增该锚点（dry-run 预览会写出来）
+
+    diff = (f"{a.skill}#{a.anchor}")
+    pid = flow_policy.new_id()
+    at = datetime.datetime.now().isoformat(timespec="seconds")
+    match = {"flow": a.flow}
+    if a.kind:
+        match["failureKind"] = a.kind
+    if a.status:
+        match["status"] = a.status
+    policy = {"id": pid, "match": match, "decision": a.decision,
+              "limits": ({"maxAttempts": a.max_attempts} if a.max_attempts else {}),
+              "authorizer": a.authorizer, "sourceCase": a.case, "whyRef": diff, "at": at, "enabled": True}
+    entry = render_entry(pid, a.anchor, a.title, a.summary, a.case, a.authorizer, at, a.flow)
+
+    print("── 将写入两边（互相引用）──")
+    print(f"  ① 政策：{json_dumps(policy)}")
+    print(f"  ② 技能：{a.skill} 追加锚点 {a.anchor}（{len(entry)} 字）")
+    print(f"  ③ 台账：policy_new（case={a.case}，授权人={a.authorizer}）")
+    if not a.yes:
+        print("\n[dry-run] 未写入。加 --yes 才落库。")
+        return 0
+
+    flow_policy.append(policy)
+    with skill_path.open("a", encoding="utf-8") as fh:
+        fh.write(entry)
+    subprocess.run([sys.executable, str(HERE / "flow_ledger.py"), "--case-id", a.case, "--event", "policy_new",
+                    "--by", a.authorizer or "user", "--detail",
+                    f"新增政策 {pid}（{a.decision}）+ 技能条目 {diff}"], check=False)
+    print(f"\n  ✅ 政策 {pid} 已入库；技能条目已追加（{diff}）")
+    return 0
+
+
+def json_dumps(obj) -> str:
+    import json
+    return json.dumps(obj, ensure_ascii=False)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engine/scripts/flow_ledger.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""flow_ledger —— 流程台账读写（掌舵者与 subagent 共用的确定性入口）。
+
+台账：~/.dsh/argent/flow-ledger.jsonl（单行事件，追加写 + 文件锁，避免并发交错）
+  {"ts":<epoch秒>,"caseId":"<flow>__<ticket>","event":"dispatched|done|failed|blocked","attempt":N,"error":"..","by":"<谁>"}
+  · `planned`（认领）可带 `release`/`releaseRetry`（人工放行重跑）、`externalTiming`/`externalRetry`
+    （外部时序独立通道）、`upstreamFieldHash`（上游逐字段 8 位哈希 = "上次派发快照"）、`upstreamReset`；
+  · `policy_apply` 可带 `policy`（见 `POLICIES`；`release_budget_reset` = 上游数据变化 ⇒ 放行额度重置）。
+
+用法：
+  python3 scripts/flow_ledger.py --case-id wenyao-invoice__76135791 --event dispatched --by gw-ml-invoice-wy
+  python3 scripts/flow_ledger.py --case-id … --event failed --attempt 1 --error "门户登录失败"
+  python3 scripts/flow_ledger.py --status [--json]     # 每 case 最新状态
+  python3 scripts/flow_ledger.py --status --flow wenyao-invoice   # 只看某流程（caseId 前缀）
+  python3 scripts/flow_ledger.py --inflight [--flow X] # 只输出在飞数（限流用）
+退出码：0 成功；2 参数/写入错误
+"""
+from __future__ import annotations
+from typing import Any
+import argparse, json, os, pathlib, sys, time
+
+# 默认台账：数据目录走**唯一判据** `scripts/lib/argent_datadir.py`（三级链，与 JS 内核同语义；
+# 勿在此复制链 —— 旧的两级写法不看 DSH_HOME，隔离实例的 CLI/cron 会写进生产台账）
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402
+# 跨平台文件锁**唯一真源**（POSIX `fcntl.flock` / Windows `msvcrt.locking`）：
+# 此前本文件顶层 `import fcntl` ⇒ Windows 上 `ModuleNotFoundError` ⇒ 台账整个不可用。
+from argent_filelock import best_effort     # noqa: E402
+DEFAULT_LEDGER = pathlib.Path(resolve_data_dir()['dir']) / 'flow-ledger.jsonl'
+EVENTS = ('dispatched', 'done', 'failed', 'blocked', 'planned', 'phase',
+          'wake', 'retry', 'failed_ack',
+          'requeued',       # 停滞回收（flow_stale 写）：triage 认它 ⇒ 票回到 to_dispatch
+          "policy_apply", "policy_new")   # wake=因失败唤醒角色；retry=判定可重试；failed_ack=已人工确认
+DONE_EVENTS = ('done', 'failed', 'blocked')
+# `policy_apply` 可带 `policy` 标记（机器可判的**政策名**）：
+#   · `release_budget_reset` —— 上游数据变化 ⇒ 该票放行额度重置（`flow_triage` 写；
+#     ⛔ 它只把**计数基线归零**，不改变票据状态 —— `flow_triage#INFO_EVENTS` 已含 policy_apply）。
+# 只加键：老台账没有 `policy` 字段照旧可读（未知 policy 一律当普通信息性政策记账）。
+POLICIES = ('release_budget_reset',)
+
+
+def _clean_text(v: Any) -> Any:
+    """把**孤立代理字符**替换成 `?`（缺陷⑦，2026-09-23 角色实测）。
+
+    为什么会有：`--detail` 走 argv 传入超长中文时，某些来源（shell/终端）会给到含孤立 surrogate
+    的字符串；`json.dumps` 能产出它，但**写 UTF-8 文件时会抛**
+    `'utf-8' codec can't encode … surrogates not allowed` ⇒ 整条台账记录丢失（比截断更糟）。
+    只替换代理区（U+D800–U+DFFF），其余字符原样保留。
+    """
+    if isinstance(v, str):
+        if not any(0xD800 <= ord(ch) <= 0xDFFF for ch in v):
+            return v                                     # 常见路径零开销
+        return ''.join('?' if 0xD800 <= ord(ch) <= 0xDFFF else ch for ch in v)
+    if isinstance(v, dict):
+        return {k: _clean_text(x) for k, x in v.items()}
+    if isinstance(v, list):
+        return [_clean_text(x) for x in v]
+    return v
+
+
+def append(path: pathlib.Path, rec: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    rec = _clean_text(rec)          # ⑦：先清代理字符，避免整条记录写盘失败
+    line = json.dumps(rec, ensure_ascii=False) + '\n'
+    with open(path, 'a', encoding='utf-8') as f:
+        # 追加写加锁（避免多 subagent 交错）：策略 (b) **响亮降级** —— 台账自身的约定是
+        # 「绝不阻断主流程」（见模块 docstring），所以锁不可用时无锁继续，但**必须出声**
+        # （旧实现在 Windows 上 `import fcntl` 静默失败 ⇒ 一声不吭地无锁写）。
+        with best_effort(f, site='flow_ledger.append', note='台账追加降级为无锁写'):
+            f.write(line)
+            f.flush()
+            os.fsync(f.fileno())
+
+
+def read(path: pathlib.Path) -> list[dict]:
+    if not path.exists():
+        return []
+    out = []
+    for ln in path.read_text(encoding='utf-8').splitlines():
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            out.append(json.loads(ln))
+        except Exception:
+            continue
+    return out
+
+
+INFLIGHT_WINDOW_MIN = 30
+
+
+def status(path: pathlib.Path, flow: str | None = None, now: float | None = None,
+           inflight_min: int = INFLIGHT_WINDOW_MIN) -> dict:
+    """每 case 最新事件 + 在飞清单。
+
+    `flow` 给定时只统计该流程 —— 多流程共用一份台账（`caseId = <flow>__<业务键>`，
+    由 flow_case.py 保证前缀），所以按前缀过滤即可，**无需数据迁移**。
+
+    ⚠️ 在飞口径（2026-09-18 修，用户实测两处矛盾后统一）：
+      · 最新事件 `planned` 且 `leaseUntil > now` ⇒ 已认领、租约未过期 = **真在飞**
+        （新引擎认领写 `planned`，**从不写 `dispatched`** ⇒ 旧规则永远数不到在跑的票：
+         实测 FULL 真跑时面板显示"在飞=0"）；
+      · 最新事件 `dispatched` 且 `now - ts < inflight_min` ⇒ 旧架构遗留事件按窗口算在飞
+        （旧事件没有收尾事件 ⇒ 不加窗口会让历史票**永久**显示在飞：实测
+         wenyao-invoice__76636923/76637122 两天前的 dispatched ⇒ 面板恒显示"在飞=2"）。
+      与 `flow_claim.live_leases()` / `flow_triage` 的在飞判据一致。
+    """
+    now = time.time() if now is None else now
+    prefix = f'{flow}__' if flow else None
+    last, inflight = {}, []
+    for e in read(path):
+        cid = e.get('caseId')
+        if not cid:
+            continue
+        if prefix and not str(cid).startswith(prefix):
+            continue
+        last[cid] = e
+    for cid, e in last.items():
+        ev = e.get('event')
+        if ev == 'planned':
+            if float(e.get('leaseUntil') or 0) > now:
+                inflight.append(cid)
+        elif ev == 'dispatched':
+            if now - float(e.get('ts') or 0) < inflight_min * 60:
+                inflight.append(cid)
+    return {'last': last, 'inflight': sorted(inflight), 'now': now, 'inflightMin': inflight_min}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='流程台账读写')
+    ap.add_argument('--ledger', default=str(DEFAULT_LEDGER))
+    ap.add_argument('--case-id')
+    ap.add_argument('--event', choices=EVENTS)
+    ap.add_argument('--attempt', type=int)
+    ap.add_argument('--error')
+    ap.add_argument('--by', help='记录者（角色名或 subagent 标识）')
+    ap.add_argument('--phase', help='阶段名（--event phase 时用，如 P1路由/P3填报）')
+    ap.add_argument('--policy', choices=POLICIES,
+                    help='政策名（--event policy_apply 时用；见 POLICIES）')
+    ap.add_argument('--detail', help='阶段细节（产物路径/退出码等）')
+    ap.add_argument('--status', action='store_true')
+    ap.add_argument('--inflight', action='store_true')
+    ap.add_argument('--flow', help='只看该流程的 case（按 caseId 前缀 <flow>__ 过滤 --status/--inflight）')
+    ap.add_argument('--inflight-min', type=int, default=INFLIGHT_WINDOW_MIN,
+                    help='dispatched 事件算在飞的窗口（分钟，缺省 30；与 flow_triage 同口径）')
+    ap.add_argument('--now', type=float, help='覆盖"当前时间"（测试用，保证判定确定）')
+    ap.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+    path = pathlib.Path(a.ledger)
+
+    if a.status or a.inflight:
+        st = status(path, a.flow, now=a.now, inflight_min=a.inflight_min)
+        if a.inflight:
+            print(len(st['inflight']))
+        elif a.json:
+            print(json.dumps({'flow': a.flow, **st}, ensure_ascii=False, indent=2))
+        else:
+            scope = f'｜流程 {a.flow}' if a.flow else ''
+            print(f'  台账 {path}{scope}｜case 数 {len(st["last"])}｜在飞 {len(st["inflight"])}')
+            for cid, e in sorted(st['last'].items()):
+                print(f"    {cid}  {e.get('event')}  attempt={e.get('attempt', '-')}  {str(e.get('error') or '')[:50]}")
+        return 0
+
+    if not (a.case_id and a.event):
+        print('需要 --case-id 与 --event（或用 --status/--inflight）', file=sys.stderr)
+        return 2
+    rec = {'ts': int(time.time()), 'caseId': a.case_id, 'event': a.event}
+    if a.attempt is not None:
+        rec['attempt'] = a.attempt
+    if a.error:
+        rec['error'] = str(a.error)[:500]
+    if a.phase:
+        rec['phase'] = str(a.phase)[:60]
+    if a.policy:
+        rec['policy'] = str(a.policy)
+    if a.detail:
+        rec['detail'] = str(a.detail)[:300]
+    if a.by:
+        rec['by'] = a.by
+    try:
+        append(path, rec)
+    except Exception as e:
+        print(f'台账写入失败: {e}', file=sys.stderr)
+        return 2
+    if not a.json:
+        print(f"  ✅ 已记 {rec['caseId']} → {rec['event']}" + (f"（attempt {rec['attempt']}）" if 'attempt' in rec else ''))
+    else:
+        print(json.dumps(rec, ensure_ascii=False))
+    _telemetry_hook(rec)
+    return 0
+
+
+def _telemetry_hook(rec: dict) -> None:
+    """失败/阻塞 → 采集一条**元数据**遥测事件（2026-09-21）。
+
+    为什么挂在台账这一层：**四条流程的失败都写这里**（FULL/文鳐/鑫中航/日报），
+    一个钩子就全覆盖，不必在每个 runner 里各写一遍。
+
+    三条纪律（照 `scripts/telemetry.py` 的口径）：
+      · 只落本地队列（不联网）—— 联网交给 flow-trigger 每轮的 `--flush`；
+      · **不传原始错误文本**：`detail` 只用 `flow_failure.classify` 给出的**固定措辞**，
+        原始 error 里可能有店铺名/货件号（实测过：数字串能掩，中文店名掩不掉）；
+      · 任何异常都吞掉 —— 遥测绝不允许影响台账写入与主流程。
+    """
+    if rec.get('event') not in ('failed', 'blocked'):
+        return
+    try:
+        sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+        import telemetry as T                      # noqa: PLC0415  同目录模块
+        # 引擎级失败的合成票号（claim__/preflight__/…）由**触发链**发 kind=engine，
+        # 这里跳过 —— 否则同一次失败会写两条事件。
+        if T.is_engine_case(rec.get('caseId')):
+            return
+        from flow_failure import classify          # noqa: PLC0415  与失败回路同一套判据
+        raw = str(rec.get('error') or rec.get('detail') or '')
+        cls = classify(raw, rec.get('attempt'))
+        flow = T.flow_of_case(rec.get('caseId'))
+        T.emit(
+            'failure',
+            flow=flow,
+            capability=T.capability_of(flow),
+            role=str(rec.get('by') or ''),
+            case=str(rec.get('caseId') or ''),
+            phase=str(rec.get('phase') or ''),
+            error_class=str(cls.get('kind') or ''),
+            attempt=int(rec.get('attempt') or 0),
+            detail=str(cls.get('reason') or ''),   # 固定措辞，不含业务值
+        )
+    except Exception:                              # noqa: BLE001
+        pass
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/engine/scripts/flow_policy.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""流程**政策库**（P1，2026-09-17）—— "你确认一次，以后同类不再问你"的落地件。
+
+分层（见 docs/Argent-宿主适配契约.md §1「判断归属」）：
+  · 本文件 = **L2 政策层**的一部分：判据的**唯一权威副本**，机器可读、可匹配、可追溯；
+  · 角色（L4）遇到 case 先 `--match`：命中 ⇒ 依政策执行并记台账 `policy_apply`；
+    未命中 ⇒ 问你，得到答复后由角色 **提议** 一条政策（`--add`）→ 你确认 → 入库。
+  · 权限边界（什么能自动、什么必须问）由 `--authority` 给出（注册表 `flows.<id>.authority`，缺省见下）。
+
+政策条目（每行一条 JSON，`~/.dsh/argent/flow-policy.jsonl`）：
+  {"id":"pol-...", "match":{"flow":"full","failureKind":"retryable"}, "decision":"retry",
+   "limits":{"maxAttempts":2}, "authorizer":"用户", "sourceCase":"full__recvvgPQgoZW9B",
+   "at":"2026-09-17T17:37:00", "whyRef":"skills/.../pitfalls.md#C7", "enabled":true}
+
+匹配规则：`match` 的每个键都要对上（`*` 表示任意；数组表示枚举）；**越具体越优先**
+（命中键数多者胜，其次时间新者胜）。口径类变更（caliber）不允许自动，只能由用户改。
+
+用法：
+  python3 scripts/flow_policy.py --list [--flow full] [--json]
+  python3 scripts/flow_policy.py --match --flow full --failure-kind retryable --status 失败
+  python3 scripts/flow_policy.py --add --decision retry --match-kv flow=full --match-kv failureKind=retryable \\
+      --authorizer 用户 --source-case full__recvvgPQgoZW9B --why-ref skills/ml-fulfillment-sop/references/pitfalls.md#C7
+  python3 scripts/flow_policy.py --retire pol-xxxx        # 软停用（保留审计）
+  python3 scripts/flow_policy.py --authority --flow full  # 权限边界
+"""
+from __future__ import annotations
+
+import argparse
+
+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 pathlib.Path(__file__).resolve().with_name("flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+import datetime
+import json
+import os
+import pathlib
+import sys
+
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链，与 JS 内核同语义）——
+# 勿在此复制链（旧的两级写法不看 DSH_HOME，隔离实例的 CLI 会写进生产政策库）
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402
+DATA_DIR = pathlib.Path(resolve_data_dir()['dir'])
+POLICY = DATA_DIR / "flow-policy.jsonl"
+DECISIONS = ("retry", "hold", "escalate", "discard")
+
+# 权限边界缺省（注册表 flows.<id>.authority 可覆盖）：auto=角色可自行决定；ask=必须问用户
+DEFAULT_AUTHORITY = {
+    "retry": {"auto": True, "maxAttempts": 2, "_why": "瞬时类失败自动重跑，上限内不打扰用户（用户口径 A）"},
+    "hold": {"auto": True, "_why": "等人补数据/落卡：不算处置，属于把球踢回运营"},
+    "escalate": {"auto": True, "_why": "升级给用户（需要口径或授权）"},
+    "discard": {"auto": False, "_why": "作废一票=不可逆，必须用户确认"},
+    "write": {"scope": "guarded", "askOutside": True, "_why": "仅守卫白名单内的字段/产出物可写，越界要授权"},
+    "caliber": {"auto": False, "_why": "口径（阈值/字段语义/候选判据）只能用户改"},
+}
+
+
+def load(path: pathlib.Path | None = None) -> list[dict]:
+    p = path or POLICY
+    out = []
+    try:
+        for line in p.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            try:
+                d = json.loads(line)
+            except Exception:
+                continue
+            if isinstance(d, dict) and d.get("id"):
+                out.append(d)
+    except FileNotFoundError:
+        pass
+    return out
+
+
+def matches(policy: dict, ctx: dict) -> bool:
+    """`match` 的每个键都要对上（`*`=任意；数组=枚举；其余按字符串比较）。"""
+    m = policy.get("match") or {}
+    for key, want in m.items():
+        got = ctx.get(key)
+        if want == "*":
+            continue
+        if isinstance(want, list):
+            if str(got) not in [str(x) for x in want]:
+                return False
+        elif str(got) != str(want):
+            return False
+    return True
+
+
+def pick(policies: list[dict], ctx: dict) -> dict | None:
+    """选中最具体的启用政策：命中键数多者胜 → 时间新者胜。"""
+    hits = [p for p in policies if p.get("enabled", True) and matches(p, ctx)]
+    if not hits:
+        return None
+    hits.sort(key=lambda p: (len(p.get("match") or {}), str(p.get("at") or "")), reverse=True)
+    return hits[0]
+
+
+def authority(flow: str | None) -> dict:
+    """权限边界：注册表 flows.<flow>.authority 覆盖缺省。"""
+    out = {k: dict(v) for k, v in DEFAULT_AUTHORITY.items()}
+    try:
+        reg = _registry_doc()
+        spec = ((reg.get("flows") or {}).get(flow or "") or {})
+        for k, v in (spec.get("authority") or {}).items():
+            out[k] = {**(out.get(k) or {}), **(v if isinstance(v, dict) else {"auto": bool(v)})}
+    except Exception:
+        pass
+    return out
+
+
+def append(entry: dict, path: pathlib.Path | None = None) -> dict:
+    p = path or POLICY
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with p.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    return entry
+
+
+def new_id() -> str:
+    return "pol-" + datetime.datetime.now().strftime("%Y%m%d%H%M%S%f")[:17]
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="流程政策库（L2 政策层）")
+    ap.add_argument("--path", help="政策文件（默认 ~/.dsh/argent/flow-policy.jsonl）")
+    ap.add_argument("--list", action="store_true")
+    ap.add_argument("--match", action="store_true", help="按上下文匹配政策")
+    ap.add_argument("--add", action="store_true", help="新增一条政策")
+    ap.add_argument("--retire", help="软停用某条政策（保留审计）")
+    ap.add_argument("--authority", action="store_true", help="打印权限边界")
+    ap.add_argument("--flow")
+    ap.add_argument("--failure-kind", dest="failureKind")
+    ap.add_argument("--status")
+    ap.add_argument("--store")
+    ap.add_argument("--phase")
+    ap.add_argument("--decision", choices=DECISIONS)
+    ap.add_argument("--match-kv", dest="match_pairs", action="append", default=[],
+                    help="匹配条件 k=v（可多次；v 可用逗号分隔表示枚举）")
+    ap.add_argument("--max-attempts", type=int)
+    ap.add_argument("--authorizer", default="")
+    ap.add_argument("--source-case", default="")
+    ap.add_argument("--why-ref", default="")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    path = pathlib.Path(a.path).expanduser() if a.path else None
+    policies = load(path)
+
+    if a.authority:
+        out = authority(a.flow)
+        print(json.dumps(out, ensure_ascii=False, indent=2) if a.json else
+              "\n".join(f"  {k:9} auto={v.get('auto', '?')}  {v.get('_why', '')}" for k, v in out.items()))
+        return 0
+
+    if a.list:
+        rows = [p for p in policies if not a.flow or (p.get("match") or {}).get("flow") in (a.flow, None, "*")]
+        if a.json:
+            print(json.dumps(rows, ensure_ascii=False, indent=2))
+        else:
+            print(f"  政策 {len(rows)} 条（{path or POLICY}）")
+            for p in rows:
+                flag = "" if p.get("enabled", True) else "（已停用）"
+                print(f"  {p['id']}  {p.get('decision'):8} match={json.dumps(p.get('match'), ensure_ascii=False)}{flag}")
+                if p.get("sourceCase"):
+                    print(f"      来源 case={p['sourceCase']}｜授权人={p.get('authorizer') or '-'}｜{p.get('at') or ''}")
+        return 0
+
+    if a.match:
+        ctx = {k: v for k, v in {"flow": a.flow, "failureKind": a.failureKind, "status": a.status,
+                                 "store": a.store, "phase": a.phase}.items() if v}
+        hit = pick(policies, ctx)
+        if a.json:
+            print(json.dumps({"context": ctx, "policy": hit}, ensure_ascii=False, indent=2))
+        elif hit:
+            print(f"  ✅ 命中政策 {hit['id']}：{hit.get('decision')}"
+                  f"（match={json.dumps(hit.get('match'), ensure_ascii=False)}"
+                  f"｜授权人={hit.get('authorizer') or '-'}｜来源={hit.get('sourceCase') or '-'}）")
+        else:
+            print(f"  ⚠️ 无匹配政策（context={json.dumps(ctx, ensure_ascii=False)}）⇒ 按权限边界决定：能自动就自动，否则问用户；"
+                  "得到答复后用 --add 提议一条政策")
+        return 0 if hit else 1
+
+    if a.add:
+        if not a.decision:
+            print("❌ --add 需要 --decision", file=sys.stderr)
+            return 2
+        match = {}
+        for kv in a.match_pairs:
+            if "=" not in kv:
+                print(f"❌ --match-kv 需要 k=v：{kv}", file=sys.stderr)
+                return 2
+            k, v = kv.split("=", 1)
+            match[k.strip()] = [x.strip() for x in v.split(",")] if "," in v else v.strip()
+        if a.flow and "flow" not in match:
+            match["flow"] = a.flow
+        if a.failureKind and "failureKind" not in match:
+            match["failureKind"] = a.failureKind
+        if not match:
+            print("❌ 至少要有一个匹配条件（--flow 或 --match k=v）—— 无条件政策会吞掉所有判断", file=sys.stderr)
+            return 2
+        if a.decision == "discard" and (a.authorizer or "") not in ("用户", "user"):
+            print("❌ 作废类（discard）必须由用户授权（--authorizer 用户）", file=sys.stderr)
+            return 3
+        entry = {"id": new_id(), "match": match, "decision": a.decision,
+                 "limits": ({"maxAttempts": a.max_attempts} if a.max_attempts else {}),
+                 "authorizer": a.authorizer or "", "sourceCase": a.source_case or "",
+                 "whyRef": a.why_ref or "",
+                 "at": datetime.datetime.now().isoformat(timespec="seconds"), "enabled": True}
+        append(entry, path)
+        print(json.dumps(entry, ensure_ascii=False, indent=2) if a.json else
+              f"  ✅ 已入库 {entry['id']}（{a.decision}｜match={json.dumps(match, ensure_ascii=False)}）")
+        return 0
+
+    if a.retire:
+        target = next((p for p in policies if p["id"] == a.retire), None)
+        if not target:
+            print(f"❌ 找不到政策 {a.retire}", file=sys.stderr)
+            return 2
+        target["enabled"] = False
+        target["retiredAt"] = datetime.datetime.now().isoformat(timespec="seconds")
+        p = path or POLICY
+        keep = [x for x in policies if x["id"] != a.retire] + [target]
+        p.write_text("\n".join(json.dumps(x, ensure_ascii=False) for x in keep) + "\n", encoding="utf-8")
+        print(f"  ✅ 已停用 {a.retire}（保留审计记录）")
+        return 0
+
+    ap.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())