@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/webdriver_ipc.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""webdriver_ipc —— 浏览器客户端 **WebDriver IPC 层**的唯一实现（只读查询面 + 调用原语）。
+
+## 为什么有这个模块（2026-10-11）
+认领前的环境预检（`scripts/env_probe.py`）此前只看 `store list` 的 `data.items` 是否非空；
+而生产现场实测「云端店铺列表拉不到、但**本机店铺窗口已开且可驱动**」时，预检把环境判成不可用
+⇒ 自动路径整轮不认领（票不派、租约不耗，但**当天 0 票处理**），而同一批票手工用
+`orchestrator.py --cdp-url …` 跑是 6/6 成功。
+
+修法是给预检加一条**回退判据**（列表为空 ⇒ 再看本机有没有已运行的店铺窗口）。
+而"再查一次本机窗口"**必须复用**编排器里既有的 WebDriver 查询（`getRunningInfo`），
+⛔ 不能新造第二个 WebDriver 客户端（两套 HTTP/重试/错误解析 = 迟早漂移）。
+故把该层抽到这里：本模块是**唯一实现**，`orchestrator.py` 与 `env_probe.py` 都调用它。
+
+## 只读纪律（本模块的硬边界）
+- 本模块**只实现**只读接口：`getRunningInfo`（窗口清单）与通用 `wd_call` 原语。
+- ⛔ 本模块**不含**任何生命周期动作：开/关窗口、内核更新、授权、清缓存等一律不在实现里
+  （调用方仍可用 `wd_call` 发它们，但"点下去"的那一步留在调用方，且各带自己的守卫与语义）。
+- ⛔ 不写任何文件、不起子进程、不读凭据。
+- 回归：`scripts/tests/env-probe-local-window-fallback.test.py` 的只读性断言
+  （静态 AST：本模块零写 API、零动作名；运行时：探针只发 `getRunningInfo`）。
+
+## 分层与命名
+L1 执行内核（`scripts/`）⇒ 只 import 标准库；⛔ 不 import 宿主模块（`@deepseek-ai/*`、
+`cordis`、`dsh-*`、`plugins/argent-*`）。门禁：`scripts/tests/kernel-purity.test.mjs`。
+⚠️ 文件名与正文**刻意不带任何业务线词汇**（门禁 `scripts/vertical-lint.mjs` 的 engine-words 档：
+引擎文件不得新增业务词，⛔ 不抬基线）——"是哪个厂商的客户端"由调用方（业务线声明/编排器）决定，
+本模块只认"客户端 WebDriver IPC 协议"这一件事。
+"""
+from __future__ import annotations
+import errno as _errno
+import json
+import os
+import socket
+import sys
+import time
+import urllib.request
+from typing import Any, Optional
+
+# 默认 IPC 端口：客户端 `--run_type=web_driver --ipc_type=http --port=19515`（官方默认）。
+DEFAULT_WD_PORT = 19515
+
+# ── P1-d（2026-10-08）：IPC **连接类**异常 1 次退避重试 ─────────────────────────────
+# 依据：官方 `reference/prerequisites.md`（「连接接口失败 ⇒ 客户端未启动完成，轮询 updateCore
+# 直到连接成功」/「请求超时 ⇒ 超时设置过短」）。连接被拒这类**请求肯定没送达**的瞬时故障
+# 不该直接判失败 —— 旧行为是立刻上抛 ⇒ 调用方回退 bridge 生命周期（放大非官方路径）。
+# ⛔ 业务错误码（statusCode != 0）**不重试**：那是内核的真实结论，重试只会白等。
+WD_IPC_RETRY_BACKOFF = 2.0          # 重试前退避（秒）
+# 语义**有歧义**的连接类异常（超时/连接被重置）：请求可能已送达并被执行 ⇒ 对**开店动作**
+# 不重试 —— 官方 `api-core.md:188`：连续两次开店调用会被内核视为**重启**，重试可能把
+# 正在跑的店铺窗口关掉再开（生产双跑风险）。只有 `refused`（连接未建立 ⇒ 请求必然未送达）
+# 才对它重试。
+WD_IPC_AMBIGUOUS_NO_RETRY = frozenset({"startBrowser"})
+
+
+def wd_err_fields(resp: Any) -> tuple[str, str]:
+    """从 IPC 响应里取 `(err, LastError)`（P1-c，2026-10-08）。
+
+    官方陷阱 2（官方 Skill 的 `SKILL.md:111`）：**优先读 `err`** —— 它是中文可读描述、
+    最贴近根因；`LastError` 是内核内部错误串（`reference/api-core.md` 的接口响应示例里就有它）。
+    旧实现**只读 `err`** ⇒ 内核窗口/代理类失败时排障信息少一半。
+
+    ⛔ 纯取值：不参与任何判断、不改任何控制流；`LastError` 兼容 `lastError` 拼写。
+    """
+    if not isinstance(resp, dict):
+        return "", ""
+    err = str(resp.get("err") or "").strip()
+    last = str(resp.get("LastError") or resp.get("lastError") or "").strip()
+    return err, last
+
+
+class WebDriverError(Exception):
+    """WebDriver API 调用失败，携带 statusCode / err / LastError 供日志（P1-c 起带 LastError）。"""
+
+    def __init__(self, action: str, status_code: Any = None,
+                 err: str = "", extra: str = "", last_error: str = "") -> None:
+        self.action = action
+        self.status_code = status_code
+        self.err = err
+        # 内核内部错误串。**优先级**：`err` 在前（官方陷阱 2：优先读 err），`LastError` 作附加
+        # 线索；`err` 为空时 LastError 照样打出来（旧行为 = 这条信息根本没有）。
+        self.last_error = last_error
+        msg = f"WebDriver {action} 失败"
+        if status_code is not None:
+            msg += f" statusCode={status_code}"
+        if err:
+            msg += f" err={err}"
+        if last_error:
+            msg += f" LastError={last_error}"
+        if extra:
+            msg += f"（{extra}）"
+        super().__init__(msg)
+
+
+def wd_log_call(action: str, request_id: str, status_code: Any,
+                started: float, err: str = "", last_error: str = "") -> None:
+    """每接口**一行**调用日志（P1-a，2026-10-08）：`action / statusCode / 耗时ms / requestId / err`。
+
+    为什么：`requestId` 自接口层落地起就在构造，却**从不落日志** ⇒ 出问题无法与客户端侧对账；
+    也没有每接口耗时 ⇒ "哪一步慢"只能靠人翻多处日志。⛔ 只打印，不参与任何判断
+    （不放宽超时、不重试、不改返回、不改抛出语义）。
+    P1-c：`LastError`（内核内部错误串）一并落日志，与 `err` 各截 80 字。
+    """
+    ms = int((time.time() - started) * 1000)
+    code = "调用异常" if status_code is None else status_code
+    parts = []
+    if err:
+        parts.append(f"err={err[:80]}")
+    if last_error:
+        parts.append(f"LastError={last_error[:80]}")
+    tail = (" " + " ".join(parts)) if parts else ""
+    print(f"[{time.strftime('%H:%M:%S')}] 🌐 WebDriver {action} statusCode={code} {ms}ms "
+          f"req={request_id}{tail}", file=sys.stderr, flush=True)
+
+
+def wd_conn_error_kind(exc: BaseException) -> str:
+    """连接类故障细分：`""`(非连接类) / `refused` / `timeout` / `reset` / `conn`。
+
+    ⛔ 刻意**不**把裸 `OSError` 当连接类：未知 OSError 一律不重试，保持"异常原样上抛"
+    （既有语义与既有回归都依赖这一点）。判定优先看异常结构（`URLError.reason` + errno），
+    结构认不出时才回落到文本特征。
+    """
+    reason: Any = getattr(exc, "reason", None)     # urllib.error.URLError.reason
+    cands = [c for c in (reason, exc) if isinstance(c, BaseException)]
+    kinds: list[str] = []
+    for c in cands:
+        eno = getattr(c, "errno", None)
+        if isinstance(c, ConnectionRefusedError) or eno == _errno.ECONNREFUSED:
+            kinds.append("refused")
+        elif isinstance(c, (TimeoutError, socket.timeout)) or eno == _errno.ETIMEDOUT:
+            kinds.append("timeout")
+        elif isinstance(c, (ConnectionResetError, BrokenPipeError)) or \
+                eno in (_errno.ECONNRESET, _errno.EPIPE):
+            kinds.append("reset")
+        elif isinstance(c, OSError) and reason is not None:
+            kinds.append("conn")                   # URLError 包着的其它 OSError
+    if not (set(kinds) & {"refused", "timeout", "reset"}):
+        # 结构认不出**具体**类别时（含"URLError 包着字符串 reason"与"其它 OSError"）看文本特征
+        blob = f"{reason!r} {exc}".lower()
+        text_kind = ""
+        if "refused" in blob or "econnrefused" in blob:
+            text_kind = "refused"
+        elif "reset" in blob or "broken pipe" in blob or "aborted" in blob:
+            text_kind = "reset"
+        elif "timed out" in blob or "timeout" in blob:
+            text_kind = "timeout"
+        if text_kind:
+            kinds.insert(0, text_kind)
+    for k in ("refused", "timeout", "reset", "conn"):   # refused 最明确 ⇒ 优先
+        if k in kinds:
+            return k
+    return ""
+
+
+def wd_call(port: int, action: str, payload: Optional[dict] = None,
+            timeout: float = 120.0, *,
+            backoff: float = WD_IPC_RETRY_BACKOFF,
+            no_retry_actions: frozenset = WD_IPC_AMBIGUOUS_NO_RETRY) -> dict[str, Any]:
+    """调用客户端 WebDriver HTTP API（POST JSON，UTF-8 解码 err 防乱码）。
+
+    P1-a：成功/失败各落一行 `wd_log_call`（含 requestId 与耗时）；成功路径返回值、
+    失败路径抛出的异常类型与文案**逐字不变**（HTTP 异常仍原样上抛，JSON 解析异常同样原样）。
+    P1-c：日志与错误对象一并带上 `LastError`（内核内部错误串）。
+    P1-d：**连接类**异常（`refused`/`timeout`/`reset`/`conn`）退避 `backoff` 秒后
+    重试**一次**；业务错误码与其它异常**不重试**。开店动作撞到有歧义的连接类异常
+    （timeout/reset）时**不重试**（见常量注释：重试会被内核当作"重启"）。
+
+    `backoff` / `no_retry_actions` 是**可注入**的：调用方（`orchestrator._wd_call`）把自家模块
+    常量按值传进来 ⇒ 常量仍可在调用方被改写（既有回归就靠这条），而 HTTP/重试逻辑只有这一份。
+    """
+    request_id = f"{action}-{int(time.time() * 1000)}-{os.getpid()}"
+    body: dict[str, Any] = {"action": action, "requestId": request_id}
+    if payload:
+        body.update(payload)
+    req = urllib.request.Request(
+        f"http://127.0.0.1:{port}",
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json; charset=utf-8"},
+        method="POST",
+    )
+    attempt = 0
+    while True:
+        attempt += 1
+        started = time.time()
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                raw = r.read()
+            resp = json.loads(raw.decode("utf-8"))
+        except Exception as exc:                            # noqa: BLE001
+            wd_log_call(action, request_id, None, started, f"{type(exc).__name__}: {exc}")
+            kind = wd_conn_error_kind(exc)
+            ambiguous = kind in ("timeout", "reset") and action in no_retry_actions
+            if kind and attempt == 1 and not ambiguous:
+                print(f"[{time.strftime('%H:%M:%S')}] ⏳ WebDriver IPC 连接类异常"
+                      f"（{kind}，action={action}）⇒ 退避 {backoff}s 重试 1 次",
+                      file=sys.stderr, flush=True)
+                time.sleep(backoff)
+                continue
+            if kind and attempt == 1 and ambiguous:
+                print(f"[{time.strftime('%H:%M:%S')}] ⚠️ WebDriver {action} 撞连接类异常"
+                      f"（{kind}）⇒ **不重试**：该异常下请求可能已送达，重试会被内核视为"
+                      f"「重启」（官方 api-core.md:188）⇒ 原样上抛，交调用方与人工处置",
+                      file=sys.stderr, flush=True)
+            raise
+        err, last_error = wd_err_fields(resp)
+        wd_log_call(action, request_id, resp.get("statusCode"), started, err, last_error)
+        return resp
+
+
+def wd_check(resp: dict[str, Any], action: str) -> dict[str, Any]:
+    """statusCode!=0 → 抛 WebDriverError（**优先读 `err`**，并带上 `LastError` 供排障）。"""
+    code = resp.get("statusCode")
+    if code not in (0, "0"):
+        err, last_error = wd_err_fields(resp)
+        raise WebDriverError(action, status_code=code, err=err, last_error=last_error)
+    return resp
+
+
+# ── 只读查询面：`getRunningInfo`（免凭据、零副作用）────────────────────────────────
+# ⛔ 本段是认领前预检回退判据的唯一来源；⛔ 不含任何开/关窗口的动作。
+
+def running_windows(port: int, timeout: float = 30.0) -> list[dict[str, Any]]:
+    """`getRunningInfo` → 当前已开启店铺列表（**无需凭据**）。
+
+    端口显式传入（而不是收一个 `Config`）：本模块不认识编排器的配置对象，
+    这样预检（`env_probe.py`）与编排器（`orchestrator.wd_running_info`）**共用同一个查询**。
+    """
+    resp = wd_check(wd_call(port, "getRunningInfo", timeout=timeout), "getRunningInfo")
+    return resp.get("browsers") or []
+
+
+def window_item_name(b: dict[str, Any]) -> str:
+    """窗口条目 → 店名（downloadPath 末段优先，回退 userData 末段；都没有 ⇒ `?`）。"""
+    return (str(b.get("downloadPath") or "").rstrip("/").split("/")[-1]
+            or str(b.get("userData") or "").split("/")[-1] or "?")
+
+
+def window_item_line(b: dict[str, Any]) -> str:
+    """窗口条目 → 一行摘要 `店名:端口@内核(handle=…)`。"""
+    return (f"{window_item_name(b)}:{b.get('debuggingPort')}"
+            f"@{b.get('core_version') or '?'}(handle={b.get('mainHandle') or '?'})")
+
+
+def windows_summary(items: Any) -> str:
+    """窗口清单 → 一行摘要（`店名:端口@内核(handle=…) ｜ …`）；空/异常 ⇒ 空串。"""
+    return " ｜ ".join(window_item_line(b) for b in (items or []) if isinstance(b, dict))
+
+
+def running_windows_probe(port: int, timeout: float = 30.0) -> dict[str, Any]:
+    """**只读**探测"本机有没有已运行的店铺窗口" → 结构化结论（**绝不抛异常**）。
+
+    ⛔ 语义边界（认领前回退判据就靠它，别把三态揉成两态）：
+      · `ok=True`  ⟺ 查询**成功** ∧ `count ≥ 1`（有窗口 = 可驱动）；
+      · `ok=False` + `error=""` ⇒ 查询成功但**一个窗口都没有**（真·没有）；
+      · `ok=False` + `error!=""` ⇒ **查不到**（超时/客户端没起/解析失败）——
+        与"没有窗口"**必须分开**：查不到时**不得**当可用（⛔ 不猜）。
+    """
+    try:
+        items = [b for b in (running_windows(port, timeout=timeout) or []) if isinstance(b, dict)]
+    except Exception as exc:                                # noqa: BLE001
+        return {"ok": False, "count": 0, "summary": "",
+                "error": f"{type(exc).__name__}: {exc}", "port": port}
+    return {"ok": bool(items), "count": len(items), "summary": windows_summary(items),
+            "error": "", "port": port}

package/engine/scripts/lib/zstd-frames.mjs

@@ -0,0 +1,104 @@
+/**
+ * 多帧 zstd 会话日志的切帧与解码（**唯一真源**）。
+ *
+ * 为什么必须自己切帧：dsh 的会话日志 `session.jsonl.zstd` 是**多帧拼接**的 zstd
+ * （首帧 = header 行，必须恰好一行；其后每帧若干事件行）。而 Node 的
+ * `zstdDecompressSync` / `createZstdDecompress` **只解首帧就停**（2026-09-28 实测：
+ * 65MB 的日志只解出 182 字节）⇒ 直接用它会把"只看到 header"当成"日志没问题"，
+ * 门禁**假绿**、掩盖真实损坏。所以这里扫描 frame magic + 逐切片试解压来切帧：
+ * 压缩数据里偶发假 magic，解不出来的切片自动并入前一帧。
+ *
+ * 本实现原在 scripts/session-repair-tool-result-content.mjs（2026-09-18 会话毒化事故
+ * 的修复工具里实战验证过），现抽出供会话修复与升级门禁共用。
+ */
+import { constants, zstdCompressSync, zstdDecompressSync } from 'node:zlib'
+import { closeSync, openSync, readSync } from 'node:fs'
+
+export const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+/** 与 dsh 写帧参数一致（校验和开启）。 */
+export const FRAME_COMPRESS_OPTS = { params: { [constants.ZSTD_c_checksumFlag]: 1 } }
+
+/**
+ * 按帧切分一个多帧 zstd 缓冲区。
+ * @param {Buffer} buf
+ * @returns {{ start: number, end: number, plain: Buffer }[]}
+ * @throws 文件不以 magic 开头 / 切分未覆盖整个文件（宁可响亮失败，也不静默截断）
+ */
+export function splitFrames(buf) {
+  const candidates = []
+  let at = 0
+  while ((at = buf.indexOf(ZSTD_MAGIC, at)) !== -1) { candidates.push(at); at += ZSTD_MAGIC.length }
+  if (candidates.length === 0 || candidates[0] !== 0) throw new Error('不是以 zstd 帧 magic 开头')
+  const frames = []
+  let frameStart = 0
+  for (let k = 1; k <= candidates.length; k += 1) {
+    const end = k < candidates.length ? candidates[k] : buf.length
+    if (end <= frameStart) continue
+    let plain
+    try { plain = zstdDecompressSync(buf.subarray(frameStart, end)) } catch { continue } // 假 magic
+    if (plain.length === 0 || plain[plain.length - 1] !== 0x0a) continue                  // 真帧必以换行结尾
+    frames.push({ start: frameStart, end, plain })
+    frameStart = end
+    if (frameStart >= buf.length) break
+  }
+  if (frameStart !== buf.length) throw new Error(`帧切分未覆盖整个文件：停在 ${frameStart}/${buf.length}`)
+  return frames
+}
+
+/**
+ * 解出事件行（首帧是 header 行，其后每行一个事件）。
+ * @param {Buffer} buf
+ * @returns {{ frames: object[], header: string, lines: { frame: number, raw: string }[] }}
+ */
+export function decodeSessionLines(buf) {
+  const frames = splitFrames(buf)
+  const header = frames[0].plain.toString('utf8')
+  if (header.split('\n').length !== 2) throw new Error('首帧不是恰好一行 header')
+  const lines = []
+  for (let f = 1; f < frames.length; f += 1) {
+    const parts = frames[f].plain.toString('utf8').split('\n')
+    if (parts[parts.length - 1] !== '') throw new Error(`第 ${f} 帧不以换行结尾`)
+    parts.pop()
+    for (const raw of parts) lines.push({ frame: f, raw })
+  }
+  return { frames, header, lines }
+}
+
+/**
+ * 把「整文件解出来的文本」编码回多帧 zstd 字节流（首帧 = 第一行 header）。
+ * @param {string} text 完整的 jsonl 文本（首行为 header）
+ * @returns {Buffer}
+ */
+export function encodeSessionFrames(text) {
+  const all = text.split('\n')
+  if (all[all.length - 1] === '') all.pop()
+  const [header, ...events] = all
+  const frames = [zstdCompressSync(Buffer.from(`${header}\n`, 'utf8'), FRAME_COMPRESS_OPTS)]
+  if (events.length) frames.push(zstdCompressSync(Buffer.from(`${events.join('\n')}\n`, 'utf8'), FRAME_COMPRESS_OPTS))
+  return Buffer.concat(frames)
+}
+
+/** 供诊断：单帧解压能解出多少（用来说明"内置解压只解首帧"的陷阱）。 */
+export function firstFrameBytes(buf) {
+  return zstdDecompressSync(buf).length
+}
+
+/**
+ * 只解**首帧**拿会话 header（廉价）：扫描会话目录找子会话时用，避免为每个文件解压整个多帧日志。
+ * 首帧极小（一行 header），故只读文件前 64KB 再切第一帧。
+ * @param {string} file
+ * @returns {object|null}
+ */
+export function readSessionHeader(file) {
+  try {
+    const fd = openSync(file, 'r')
+    const buf = Buffer.alloc(65536)
+    const n = readSync(fd, buf, 0, buf.length, 0)
+    closeSync(fd)
+    const head = buf.subarray(0, n)
+    const first = splitFrames(head)[0]
+    if (!first) return null
+    const line = first.plain.toString('utf8').split('\n')[0]
+    return JSON.parse(line)
+  } catch { return null }
+}