@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/flow_preflight.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""每流程**前置检查 + 操作指南**（用户要求 2026-09-17：缺配置必须暴露并给出人工操作步骤）。
+
+与 `customer-preflight.py` 的分工：
+  · customer-preflight = 整机/环境级（node/dsh/版本/挂载/凭据文件/触发器并存…），人工按需跑；
+  · **本脚本 = 单流程级，跑流程前必跑**：缺 lark-cli 身份 / 缺表权限 / 缺推送身份 / 缺角色 BOT，
+    都要**响亮报出 + 给出"谁去做、做什么、在哪做"的指南**，绝不静默降级。
+
+用法：
+  python3 scripts/flow_preflight.py --flow full [--online] [--json]
+  （--online 会真读一次表做权限探测；缺省只查配置与身份，秒级）
+退出码：0 全绿；1 有 FAIL（**调用方必须据此停下并暴露指南**）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+DATA = pathlib.Path(resolve_data_dir()['dir'])
+
+GUIDE = {
+    "lark-cli": {"who": "用户（终端）", "steps": [
+        "安装 lark-cli（见 skills/lark-shared）",
+        "登录：`lark-cli auth login`（浏览器确认）",
+    ]},
+    "profile": {"who": "用户（终端，Secret 不进对话）", "steps": [
+        "新建/补配置：`lark-cli config init --new`（会打印授权链接，浏览器里完成应用创建/授权）",
+        "或已有应用：`lark-cli config init --api-key-stdin`（App Secret 从标准输入喂入，不要贴在聊天里）",
+        "完成后复核：`lark-cli profile list` 应能看到该 profile",
+    ]},
+    "table": {"who": "用户（飞书开放平台）", "steps": [
+        "确认该应用已开权限点：多维表格 `base:table:read`（写表再加 `base:table:record:update` 等）",
+        "把该 bot 加为目标 Base 的协作者（可编辑/可阅读）",
+        "重新发布应用版本，等待生效后重试",
+    ]},
+    "push": {"who": "用户（飞书建群/加机器人）", "steps": [
+        "把推送用的 bot 拉进目标群（否则报 230002 Bot/User can NOT be out of the chat）",
+        "在部署配置里填对群 ID（`FULL_INTERNAL_CHAT_ID` / `mlDailyChatId` / `*_CHAT_ID`）",
+        "验证：`node scripts/feishu-card.mjs --template flow-result --flow <id> --result 'TEST=done|自检' --to internal --send`",
+    ]},
+    "role-bot": {"who": "用户（飞书开放平台）+ 开发接线", "steps": [
+        "若需要该角色有独立飞书入口：开放平台新建自建应用 → 开 `im:message`、`base:*` 等权限 → 发布",
+        "把 App Secret 在终端喂进 lark-cli（`config init`），**不要贴进聊天**",
+        "把 appId 告知开发 → 改 `~/.dsh/argent/gateway.json` 的该角色 botAppId + 复核 `roles.json` 映射 → 重启 dsh web",
+        "不需要独立入口时：**可共用主 bot**（通知走 `NOTIFY_PROFILE`），流程照跑",
+    ]},
+    "model-auth": {"who": "用户（问述账号登录 / DeepSeek Key）", "steps": [
+        "**问述积分模式**：客户机浏览器打开 http://127.0.0.1:<port> → 设置 → Argent → 「✦ 一键登录问述科技账号」（设备流授权一次，token 90 天）",
+        "**DeepSeek 官方直连模式**：确认本机 dsh credentials 里有 `DEEPSEEK_API_KEY`，且 `bash scripts/provider-switch.sh status` 显示「DeepSeek 官方直连」",
+        "⚠️ 2026-09-14 whyshu.com **硬切换过 JWT 密钥**（无灰度）⇒ 那之前签发的问述 token **全部作废**；"
+        "现象是 HTTP 401「未登录或 Token 已过期」，**不是** exp 过期，重登才会好",
+        "复核：`python3 scripts/check-model-auth.py --online`（红灯必须清零）；"
+        "排障现场确需临时放行时设 `ARGENT_SKIP_MODEL_AUTH=1`（会照旧 401 空转，不推荐）",
+    ]},
+}
+
+
+class R:
+    def __init__(self): self.items = []
+    def add(self, cid, level, title, detail="", guide=None):
+        self.items.append({"id": cid, "level": level, "title": title, "detail": detail,
+                           "guide": GUIDE.get(guide) if guide else None})
+
+
+def run(cmd, timeout=60):
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return p.returncode, (p.stdout or ""), (p.stderr or "")
+    except FileNotFoundError:
+        return 127, "", f"命令不存在: {cmd[0]}"
+    except Exception as e:  # noqa: BLE001
+        return 125, "", str(e)
+
+
+def read_env_file(name):
+    out = {}
+    try:
+        for line in (DATA / name).read_text(encoding="utf-8").splitlines():
+            t = line.strip()
+            if t and not t.startswith("#") and "=" in t:
+                k, v = t.split("=", 1)
+                out[k.strip()] = v.strip()
+    except FileNotFoundError:
+        pass
+    return out
+
+
+def check_lease(cfg: dict, r: "R") -> None:
+    """能力租约状态（批 C4，2026-09-21）——把"这个能力现在还有效吗"放进前置检查。
+
+    未启用强制（注册表 lease.enforce=false）时报 ok 并附当前状态 ⇒ **不制造噪音**；
+    启用后：无租约/超出宽限 ⇒ fail（附换租约命令），宽限期内 ⇒ warn（仍可跑）。
+    """
+    cap = str(cfg.get("capability") or "")
+    try:
+        _code, out, err = run([sys.executable, str(HERE / "lease.py"), "--check", cap, "--json"])
+        data = json.loads(out) if out.strip().startswith("{") else {}
+    except Exception as exc:                                     # noqa: BLE001
+        r.add("lease", "warn", f"租约检查执行失败：{exc}", "", "lease")
+        return
+    verdict = str(data.get("verdict") or "")
+    reason = str(data.get("reason") or (err or "").strip()[:160])
+    if verdict == "ok":
+        r.add("lease", "ok", f"能力租约：{reason}", "", "lease")
+    elif verdict == "grace":
+        r.add("lease", "warn", "能力租约已过期（宽限期内，本轮仍可跑）", reason,
+              "python3 scripts/lease.py --refresh")
+    else:
+        r.add("lease", "fail", "能力租约不可用 ⇒ 该能力应停跑", reason,
+              "python3 scripts/lease.py --refresh（需 WHYSHU_API_KEY）；或联系问述科技续订")
+
+
+def check_model_auth(r: "R") -> None:
+    """模型凭证必须在位且（离线可判的）没死 —— 跑流程前的**红灯闸门**（2026-09-29 事故固化）。
+
+    事故：2026-09-14 whyshu.com 硬切换 JWT 密钥 ⇒ 客户机上那把 08-22 签发的 token 当场失效，
+    但「还在、exp 没到」⇒ 上线核对全绿；09-29 日报唤醒后**第一步 401**，
+    票据「停滞→回收→重派」循环 60 分钟 ×N，**零告警**，唯一信号是"日报没来"。
+    这里把它提前成开跑前的 FAIL（调用方据此停下）——比空转 60 分钟强，但代价是"凭证坏 = 全停"，
+    故留 `ARGENT_SKIP_MODEL_AUTH=1` 应急旁路（需人明确设置）。
+
+    只做**离线**判定（文件/环境 + exp/旧密钥验签），不联网、不花时间；在线探针在装机与
+    `customer-preflight.py`（非 --offline）里做。
+    """
+    if os.environ.get("ARGENT_SKIP_MODEL_AUTH") == "1":
+        r.add("model-auth", "warn", "模型凭证体检被 ARGENT_SKIP_MODEL_AUTH=1 跳过",
+              "仅在已确认凭证可用的排障现场使用", "model-auth")
+        return
+    script = HERE / "check-model-auth.py"
+    if not script.exists():
+        r.add("model-auth", "warn", "缺 scripts/check-model-auth.py（老克隆，跳过）",
+              "git pull 后即生效", None)
+        return
+    dsh_home = os.environ.get("DSH_HOME") or str(DATA.parent)
+    code, out, err = run([sys.executable, str(script), "--dsh-home", dsh_home, "--json"], timeout=60)
+    doc = None
+    try:
+        doc = json.loads(out) if (out or "").strip().startswith("{") else None
+    except Exception:                                            # noqa: BLE001
+        doc = None
+    if not isinstance(doc, dict):
+        r.add("model-auth", "warn", "模型凭证体检没跑成（不阻断本轮）",
+              (err or out or "").strip().splitlines()[-1:][0] if (err or out or "").strip() else "", None)
+        return
+    bad = [i for i in (doc.get("checks") or []) if i.get("level") == "fail"]
+    if bad:
+        for i in bad:
+            r.add(f"model-auth.{i.get('id', '')}", "fail", str(i.get("title") or "模型凭证红灯"),
+                  str(i.get("detail") or ""), "model-auth")
+        return
+    fps = [str(i.get("detail") or "") for i in (doc.get("checks") or [])
+           if str(i.get("id", "")).startswith("auth.cred.") and i.get("level") == "ok"]
+    r.add("model-auth", "ok", f"模型凭证在位（计费模式 {doc.get('mode')}）", "｜".join(fps)[:220])
+
+
+def check_write_guards(cfg: dict, r: "R") -> None:
+    """注册表声明的写守卫 vs **实际写手**的姿态 —— 必须一致（2026-09-20 迭代1-步骤4）。
+
+    此前 `guards.backup/audit/writeFields` 只被 flow_config 归一化、**没有执行者**：
+    两条发票 flow 声明相反（true/true vs false/false），而 false 那条的注释又写着
+    "写前整行备份 + 读回验收 + 审计" ⇒ 声明与实际不符，读文档的人会被误导。
+    这里把它接上：读写手导出的姿态，逐项比对；不一致 = FAIL（调用方据此停下）。
+    """
+    g = cfg.get("guards") or {}
+    want_fields = sorted(g.get("writeFields") or [])
+    if not want_fields:
+        return                      # 该流程没有声明写字段（只读流程）⇒ 无需比对
+    wb = HERE / "wenyao-invoice-writeback.mjs"
+    if not wb.exists():
+        r.add("guards.writer", "fail", "写回器缺失，无法校验写守卫",
+              f"{wb} 不存在", guide=None)
+        return
+    code, out, err = run(["node", str(wb), "--print-posture"], timeout=60)
+    if code != 0 or not out.strip().startswith("{"):
+        r.add("guards.writer", "fail", "写回器姿态导出失败", (err or out).strip()[:200])
+        return
+    try:
+        posture = json.loads(out)
+    except Exception as exc:  # noqa: BLE001
+        r.add("guards.writer", "fail", "写回器姿态无法解析", str(exc)[:200])
+        return
+    got_fields = sorted(posture.get("allowedFields") or [])
+    if got_fields != want_fields:
+        r.add("guards.writeFields", "fail",
+              "注册表 guards.writeFields 与实际写手白名单不一致",
+              f"注册表={want_fields}｜写手={got_fields}"
+              " ⇒ 改注册表或改写手（守卫必须只有一处真源）")
+    else:
+        r.add("guards.writeFields", "ok", "写字段白名单与写手一致", f"{len(got_fields)} 个字段")
+    # 备份/审计/读回：注册表若声明了就必须真做（写手侧导出的是实际姿态）
+    for key, label in (("backup", "写前整行备份"), ("audit", "审计 JSONL"), ("readback", "写后读回验收")):
+        if key in g and bool(g.get(key)) != bool(posture.get(key)):
+            r.add(f"guards.{key}", "fail",
+                  f"注册表声明 guards.{key}={bool(g.get(key))}，而写手实际={bool(posture.get(key))}",
+                  f"（{label}）⇒ 声明与实际必须一致")
+        elif key in g:
+            r.add(f"guards.{key}", "ok", f"{label}：注册表与写手一致（{bool(posture.get(key))}）")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="单流程前置检查 + 操作指南")
+    ap.add_argument("--flow", required=True)
+    ap.add_argument("--online", action="store_true", help="真读一次表（权限探测）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+    r = R()
+
+    code, out, err = run([sys.executable, str(HERE / "flow_config.py"), "--flow", a.flow, "--json"])
+    if code != 0:
+        r.add("config", "fail", f"流程配置不可解析：{(err or out).strip().splitlines()[-1:]}",
+              "缺部署 env（表 id / base token）", "table")
+        return _emit(r, a.json)
+    cfg = json.loads(out)
+    src = cfg.get("source") or {}
+    fid_env = src.get("envFile")
+
+    # ① lark-cli
+    if not any((pathlib.Path(p) / "lark-cli").exists() for p in os.environ.get("PATH", "").split(":") if p):
+        code, _, _ = run(["lark-cli", "--version"])
+        if code == 127:
+            r.add("lark-cli", "fail", "PATH 里没有 lark-cli（读/写飞书表与推送都要它）", "", "lark-cli")
+    if not any(i["id"] == "lark-cli" for i in r.items):
+        r.add("lark-cli", "ok", "lark-cli 可用")
+
+    # ② 身份 profile（表读写）
+    identity = str(src.get("identity") or "")
+    envs = {**read_env_file(fid_env)} if fid_env else {}
+    if a.flow == "full":
+        identity = str(envs.get("FULL_LARK_PROFILE") or envs.get("LARK_PROFILE") or identity)
+    code, out, _ = run(["lark-cli", "profile", "list"])
+    names = set()
+    try:
+        names = {str(p.get("name")) for p in json.loads(out) if isinstance(p, dict)}
+    except Exception:
+        names = set(__import__("re").findall(r'"name":\s*"([^"]+)"', out or ""))
+    if identity and identity not in names:
+        r.add("profile", "fail", f"读表身份 `{identity}` 不在 lark-cli profile 列表里",
+              f"流程 {a.flow} 声明 identity={identity}；CLI 现有 {len(names)} 个 profile", "profile")
+    else:
+        r.add("profile", "ok", f"读表身份 `{identity or '(未声明)'}` 已配置")
+
+    # ③ 表可读（可选在线探测）
+    if a.online:
+        code, out, err = run([sys.executable, str(HERE / "flow_source.py"), "--flow", a.flow,
+                              "--source", "feishu-base", "--limit", "1", "--skip-gap", "--json",
+                              "--out-dir", "/tmp/flow-preflight-cases"], timeout=300)
+        if code == 2:
+            r.add("table", "fail", "读表失败（权限/身份/表 id）",
+                  (err or out).strip().splitlines()[-1:][0] if (err or out).strip() else "", "table")
+        else:
+            r.add("table", "ok", "表可读（在线探测通过）")
+    else:
+        r.add("table", "warn", "未做在线探测（加 --online 真读一次表）", "缺省只查配置，避免每次跑流程都读表")
+
+    # ④ 推送身份 + 目标群
+    cfgj = {}
+    try:
+        cfgj = json.loads((DATA / "config.json").read_text(encoding="utf-8"))
+    except Exception:
+        pass
+    # 与 feishu-card.mjs 同口径：通知身份/群 id 可能来自**共用**的部署 env（发票流程自己没有 envFile）。
+    # ⚠️ 第一版只看本流程 envFile ⇒ 对发票流程误报 FAIL（"静默/误报"同类问题）。
+    shared = read_env_file("fulfillment.env")
+    de = read_env_file("daily-report.env")
+    if a.flow == "daily-report":
+        notify = de.get("LARK_PROFILE") or cfgj.get("mlDailyProfile") or ""
+        chat = de.get("ML_DAILY_CHAT_ID") or cfgj.get("mlDailyChatId") or ""
+    else:
+        notify = envs.get("NOTIFY_PROFILE") or shared.get("NOTIFY_PROFILE") or \
+            cfgj.get("mlDailyAlertProfile") or ""
+        chat = envs.get("FULL_INTERNAL_CHAT_ID") or shared.get("FULL_INTERNAL_CHAT_ID") \
+            or cfgj.get("feishuChatId") or ""
+    notify = notify or (cfgj.get("mlDailyAlertProfile") or "") or "cli_a93b9354c6e35cd1"
+    if not notify or (names and notify not in names and not notify.startswith("cli_")):
+        r.add("push", "fail", f"推送身份不可用：`{notify or '(未配置)'}`", "卡片/通知会发不出去", "push")
+    elif not chat:
+        r.add("push", "fail", "推送目标群未配置", "缺 *_CHAT_ID / config 里的群 id", "push")
+    else:
+        r.add("push", "ok", f"推送身份 `{notify}` + 目标群 `{chat[:12]}…` 已配置")
+
+    # ⑤ 角色 → preset / BOT
+    role = str(cfg.get("role") or "")
+    preset = (cfg.get("dispatch") or {}).get("preset") or ""
+    roles = {}
+    try:
+        roles = json.loads((DATA / "roles.json").read_text(encoding="utf-8")).get("presets", {})
+    except Exception:
+        pass
+    if roles.get(role) != preset:
+        r.add("role", "fail", f"角色映射不一致：{role} → {roles.get(role) or '(缺)'}，流程要 {preset}",
+              "角色会挂错 preset", None)
+    else:
+        bot = ""
+        try:
+            g = json.loads((DATA / "gateway.json").read_text(encoding="utf-8"))
+            for x in (g.get("roles") or []):
+                if isinstance(x, dict) and x.get("role") == role:
+                    bot = x.get("botAppId") or ""
+        except Exception:
+            pass
+        if bot:
+            r.add("role", "ok", f"角色 {role} → {preset}（BOT {bot}）")
+        else:
+            r.add("role", "warn", f"角色 {role} 没有自己的 BOT（流程照样跑；但飞书里 @ 不到它、也不能以自己身份发言）",
+                  f"角色 {role} → {preset}；通知可共用主 bot（NOTIFY_PROFILE）", "role-bot")
+    # ⑥ 写守卫一致性（注册表声明 vs 实际写手；2026-09-20 迭代1-步骤4）
+    check_write_guards(cfg, r)
+    check_lease(cfg, r)          # 批 C4：能力租约（未启用强制时不制造噪音）
+    # ⑦ 模型凭证（2026-09-29 日报事故固化）：缺/死 ⇒ 跑起来也只会 401 空转 ⇒ 提前 FAIL
+    check_model_auth(r)
+
+    return _emit(r, a.json)
+
+
+def _emit(r: R, as_json: bool) -> int:
+    fails = [i for i in r.items if i["level"] == "fail"]
+    if as_json:
+        print(json.dumps({"checks": r.items, "fail": len(fails)}, ensure_ascii=False, indent=2))
+    else:
+        icon = {"ok": "✅", "warn": "⚠️", "fail": "❌"}
+        for i in r.items:
+            print(f"  {icon[i['level']]} {i['title']}" + (f"\n      {i['detail']}" if i["detail"] else ""))
+            if i["level"] == "fail" and i.get("guide"):
+                g = i["guide"]
+                print(f"      ↳ **需要人操作**（{g['who']}）：")
+                for s in g["steps"]:
+                    print(f"        · {s}")
+    return 1 if fails else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())