@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/lib/cdp_ports.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""cdp_ports —— 「本机 CDP 调试端口」的**唯一实现**：发现 / 归属 / 页面探针（**只读**）。
+
+## 为什么有这个模块（2026-10-11 生产现场：真判据是端口，不是云端清单）
+
+客户机 FULL 触发器被认领前环境预检挡下（"Bridge 正常但没有任何店铺"）的恢复窗口里，逐步量到：
+
+| 事实 | 实测 |
+|---|---|
+| ① 客户端自带的清单命令 `store list` | ✅ 能列出 6 个店铺（CLI 通道正常） |
+| ② **WebDriver API 的 `getBrowserList`** | ❌ `statusCode=0, data=None`（**0 个店铺**）⇒ `startBrowser` 报 `-10004 browserId或browserOauth缺失` ⇒ **API 开窗这条路当场不可用** |
+| ③ 改用 **CLI 开窗** | ✅ `✓ 店铺已打开` ⇒ 窗口真开出来了、CDP 可连 |
+| ④ 但 `getRunningInfo`（上一批那条"本地已运行窗口"回退的判据）**也是 0** | ❌ ⇒ **那条回退在这个现场无效**（窗口明明在跑） |
+| ⑤ 真正救回来的判据 | `lsof` 找客户端监听的端口 → 逐个 `GET /json/version` 校验 → 按 **`--user-data-dir=…/chrome_<store_id>`** 归属到具体店铺：实测 `[13018, 27893]`（1 店 → 27893、2 店 → 13018） |
+
+⇒ 判"环境能不能干活"时，**端口 + 归属**是比两个云端/API 清单都更贴近事实的证据。
+那段判据原本只写在 `scripts/orchestrator.py` 里；本模块把它抽出来，让**编排器**与
+**认领前环境预检**（`scripts/env_probe.py`）**共用同一份**（⛔ 全仓库不得出现第二份端口发现/归属实现，
+回归 `scripts/tests/env-probe-cdp-port-fallback.test.py` 有静态判据钉住）。
+
+## 只读纪律（本模块的硬边界）
+- 只做三件事：`GET /json/version`、`GET /json/list`、`lsof`/`ps` **只读查询**。
+- ⛔ 不含任何生命周期动作（开/关窗口、内核更新、授权、清缓存…），⛔ 不写任何文件、⛔ 不读凭据。
+- ⛔ **不猜**：归属确认不到就返回 `None`（调用方**不得**取 `ports[0]` 当目标店铺）。
+
+## 分层与命名
+L1 执行内核（`scripts/`）⇒ 只 import 标准库；⛔ 不 import 宿主模块（`@deepseek-ai/*`、`cordis`、
+`dsh-*`、`plugins/argent-*`）。门禁：`scripts/tests/kernel-purity.test.mjs`。
+⚠️ 文件名与正文**刻意不带任何业务线词汇**（门禁 `scripts/vertical-lint.mjs` 的 engine-words 档：
+引擎文件不得新增业务词，⛔ 不抬基线）——"是哪个厂商的客户端"由调用方决定：
+**客户端进程名**（`lsof` 行里的匹配子串）由调用方**按参数**传进来，本模块不认识任何厂商。
+"""
+from __future__ import annotations
+import json
+import re
+import subprocess
+import urllib.request
+from typing import Any, Callable, Optional, Sequence
+
+# 进程名匹配不上时的**已知端口段兜底**（逐个 `/json/version` 试）——与既有实现逐字一致。
+DEFAULT_PORT_RANGE = (52420, 52461)
+# 店铺 user-data 目录前缀：客户端把每个店铺的窗口数据放在 `…/userdata/<前缀><store_id>`（实测可靠）。
+USER_DATA_DIR_PREFIX = "chrome_"
+
+
+def _default_fetch(url: str, timeout: float) -> str:
+    """本机回环只读取文本（测试注入点：`fetch(url, timeout)`）。"""
+    with urllib.request.urlopen(url, timeout=timeout) as resp:   # noqa: S310（本机回环只读）
+        return resp.read().decode("utf-8", "replace")
+
+
+def is_cdp_port(port: int, timeout: float = 1.0) -> bool:
+    """`GET /json/version` 可读且含 `Browser` ⇒ 这是**浏览器调试端口**（排除客户端本地 API 端口）。"""
+    try:
+        with urllib.request.urlopen(
+                f"http://127.0.0.1:{int(port)}/json/version", timeout=timeout) as r:   # noqa: S310
+            return b"Browser" in r.read(200)
+    except Exception:                                            # noqa: BLE001
+        return False
+
+
+def client_ports(process_markers: Sequence[str], timeout: float = 10.0) -> list[int]:
+    """客户端进程**监听**的本机端口（`lsof -i -P -n` 按进程名子串过滤）⇒ 逐个 `/json/version` 校验。
+
+    `process_markers` = 进程名匹配子串（大小写不敏感；空序列 ⇒ 匹配不到任何进程 ⇒ 返回 `[]`，
+    由调用方决定是否接受"只剩端口段兜底"的结论）。
+    """
+    markers = tuple(str(m).lower() for m in (process_markers or ()) if str(m).strip())
+    if not markers:
+        return []
+    ports: list[int] = []
+    try:
+        out = subprocess.run(["lsof", "-i", "-P", "-n"],
+                             capture_output=True, text=True, timeout=timeout)
+        for line in (out.stdout or "").splitlines():
+            low = line.lower()
+            if any(m in low for m in markers) and "LISTEN" in line:
+                m = re.search(r"127\.0\.0\.1:(\d+)", line)
+                if m:
+                    ports.append(int(m.group(1)))
+        ports = [p for p in sorted(set(ports)) if is_cdp_port(p)]
+    except Exception:                                            # noqa: BLE001
+        ports = []
+    return ports
+
+
+def discover_ports(process_markers: Sequence[str], *,
+                   port_range: tuple[int, int] = DEFAULT_PORT_RANGE,
+                   timeout: float = 1.0,
+                   range_timeout: float = 0.5,
+                   lsof_timeout: float = 10.0) -> list[int]:
+    """跨平台 CDP 端口发现：先按客户端进程名找监听端口（逐个 `/json/version` 校验），
+    **一个都没匹配到**时回退已知端口段（`port_range` 半开区间）逐个试。
+
+    ⛔ 只读；⛔ 不猜归属（那一步是 `match_port_by_user_data_dir`）。
+    """
+    ports = client_ports(process_markers, timeout=lsof_timeout)
+    if not ports:
+        for p in range(int(port_range[0]), int(port_range[1])):
+            if is_cdp_port(p, timeout=range_timeout):
+                ports.append(p)
+    return sorted(set(ports))
+
+
+def listener_commands(port: int, *, lsof_timeout: float = 10.0,
+                      ps_timeout: float = 5.0) -> list[str]:
+    """监听该端口的进程**命令行**（`lsof -iTCP:<port> -sTCP:LISTEN` 拿 pid → `ps` 拿 command）。
+
+    任何异常/取不到 ⇒ `[]`（"查不到"由调用方按"没命中"处理，⛔ 不猜）。
+    """
+    try:
+        lines = subprocess.run(["lsof", f"-iTCP:{int(port)}", "-sTCP:LISTEN"],
+                               capture_output=True, text=True,
+                               timeout=lsof_timeout).stdout or ""
+    except Exception:                                            # noqa: BLE001
+        return []
+    out: list[str] = []
+    for line in lines.splitlines():
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        try:
+            pid = int(parts[1])
+        except ValueError:
+            continue
+        try:
+            cmd = subprocess.run(["ps", "-p", str(pid), "-o", "command="],
+                                 capture_output=True, text=True,
+                                 timeout=ps_timeout).stdout or ""
+        except Exception:                                        # noqa: BLE001
+            continue
+        if cmd.strip():
+            out.append(cmd)
+    return out
+
+
+def match_port_by_user_data_dir(store_id: str, ports: Sequence[int], *,
+                                dir_prefix: str = USER_DATA_DIR_PREFIX,
+                                lsof_timeout: float = 10.0,
+                                ps_timeout: float = 5.0) -> Optional[int]:
+    """**归属判据**：进程命令行里含 `--user-data-dir=…/<dir_prefix><store_id>` ⇒ 该端口属于这家店。
+
+    按 `ports` 的**给定顺序**取第一个命中的（与既有实现逐字同序）；一个都不命中 ⇒ `None`
+    （调用方**不得**退化成"取 `ports[0]`"——多店会错配到别人家的窗口）。
+    """
+    if not store_id:
+        return None
+    needle = f"{dir_prefix}{store_id}"
+    for port in ports:
+        cmds = listener_commands(port, lsof_timeout=lsof_timeout, ps_timeout=ps_timeout)
+        if any(needle in cmd for cmd in cmds):
+            return int(port)
+    return None
+
+
+def page_targets(port: int, timeout: float = 2.0,
+                 fetch: Optional[Callable[[str, float], str]] = None) -> list[dict[str, Any]]:
+    """只读 `GET http://127.0.0.1:<port>/json/list` ⇒ 可附加的 `type=="page"` 目标。
+
+    「**页面可达**」判据用它：`/json/version` 只证明浏览器进程在，**不证明有可驱动的标签页**
+    （实测过"进程在、目标被关掉"的形态）。⛔ 任何异常都吞成 `[]`（"查不到"绝不当"可达"）。
+    """
+    getter = fetch or _default_fetch
+    try:
+        raw = getter(f"http://127.0.0.1:{int(port)}/json/list", timeout)
+        items = json.loads(raw or "[]")
+    except Exception:                                            # noqa: BLE001
+        return []
+    if not isinstance(items, list):
+        return []
+    return [t for t in items
+            if isinstance(t, dict)
+            and str(t.get("type") or "") == "page"
+            and str(t.get("webSocketDebuggerUrl") or "")]
+
+
+def browser_version(port: int, timeout: float = 2.0,
+                    fetch: Optional[Callable[[str, float], str]] = None) -> str:
+    """`GET /json/version` 的 `Browser` 值 → **版本号**（`Chrome/142.0.7444.168` → `142.0.7444.168`）。
+
+    只用于把证据行写成与窗口清单同一形状（`店名:端口@内核(handle=…)`）；取不到 ⇒ `''`。
+    """
+    getter = fetch or _default_fetch
+    try:
+        doc = json.loads(getter(f"http://127.0.0.1:{int(port)}/json/version", timeout) or "{}")
+        browser = str((doc or {}).get("Browser") or "")
+    except Exception:                                            # noqa: BLE001
+        return ""
+    return browser.rsplit("/", 1)[-1].strip()
+
+
+def target_handle(targets: Sequence[dict[str, Any]]) -> str:
+    """首个 page 目标的 `id`（CDP 附着的句柄）；没有 ⇒ `''`。"""
+    for t in (targets or ()):
+        if isinstance(t, dict) and t.get("id"):
+            return str(t["id"])
+    return ""

package/engine/scripts/lib/customer-env.mjs

@@ -0,0 +1,102 @@
+/**
+ * 客户机 env 键迁移（**纯函数 + 依赖注入**，可离线测试）。
+ *
+ * 由来（2026-09-28 客户机 P9 预检 6 红）：客户机的 `~/.dsh/argent/fulfillment.env` 是旧一代
+ * （缺 `FULL_LARK_PROFILE`）⇒ 流程读客户 Base 时身份解析不出来 ⇒ 91403/99991672，
+ * 整条 FULL 流程读不了表。而"该用哪个身份"**必须实测**：各机器 lark-cli 的 profile 命名
+ * 并不一致（开发机叫 `lip-customer`，客户机用 appId `cli_aaf7cafb66b85ccc`），
+ * 且同名不同 app 的坑真实存在（客户机的 `ml-fulfillment` 指向缺 base:record:read 的 app）。
+ *
+ * 所以：**逐个候选身份真读一次表**，谁读得通就用谁；一个都读不通就响亮失败、绝不猜。
+ */
+import { spawnSync } from 'node:child_process'
+
+/**
+ * 列出本机 lark-cli 的候选身份（profile 名）。
+ * @param {(cmd: string, args: string[]) => {status: number, stdout: string}} run
+ * @returns {string[]}
+ */
+export function listLarkProfiles(run) {
+  const r = run('lark-cli', ['profile', 'list'])
+  if (r.status !== 0) return []
+  try {
+    const arr = JSON.parse(r.stdout)
+    if (!Array.isArray(arr)) return []
+    return arr.map((p) => p.name || p.appId).filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 探测哪个身份能读指定的 base/table（窄投影 1 列 1 条，只读）。
+ * @returns {{ profile: string|null, tried: {profile: string, ok: boolean, code?: number, msg?: string}[] }}
+ */
+export function findBaseReader({ run, baseToken, tableId, fieldId, profiles }) {
+  const tried = []
+  for (const profile of profiles) {
+    const r = run('lark-cli', [
+      '--profile', profile, 'base', '+record-list',
+      '--base-token', baseToken, '--table-id', tableId,
+      '--as', 'bot', '--format', 'json', '--field-id', fieldId, '--page-size', '1',
+    ])
+    if (r.status === 0) {
+      tried.push({ profile, ok: true })
+      return { profile, tried }
+    }
+    let code
+    let msg = ''
+    try { const j = JSON.parse(r.stdout); code = j?.error?.code; msg = j?.error?.subtype || j?.error?.message || '' } catch { msg = (r.stdout || '').slice(0, 80) }
+    tried.push({ profile, ok: false, code, msg })
+  }
+  return { profile: null, tried }
+}
+
+/** 默认 runner（真实进程；测试注入假 runner）。 */
+export function realRun(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 60000 })
+  return { status: r.status ?? 1, stdout: `${r.stdout || ''}${r.stderr || ''}` }
+}
+
+/**
+ * 解析 env 文本为键值（保留注释与空行由调用方用 applyEnvKeys 处理）。
+ */
+export function parseEnvKeys(text) {
+  const out = {}
+  for (const line of String(text).split('\n')) {
+    const m = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line)
+    if (m) out[m[1]] = m[2]
+  }
+  return out
+}
+
+/**
+ * 把缺失的键**追加**到 env 文本末尾（不动已有键、不动注释；已有键默认不覆盖）。
+ * @returns {{ text: string, added: string[], skipped: {key: string, reason: string}[] }}
+ */
+export function applyEnvKeys(text, keys, { force = false } = {}) {
+  const existing = parseEnvKeys(text)
+  const added = []
+  const skipped = []
+  const lines = String(text).replace(/\n*$/, '\n').split('\n')
+  const insert = []
+  for (const [key, value] of Object.entries(keys)) {
+    if (value === undefined || value === null || value === '') { skipped.push({ key, reason: '无可用取值（探测未命中）' }); continue }
+    if (existing[key] !== undefined && !force) { skipped.push({ key, reason: `已存在（${existing[key]}）` }); continue }
+    if (existing[key] !== undefined && force) {
+      const idx = lines.findIndex((l) => new RegExp(`^\\s*${key}\\s*=`).test(l))
+      lines[idx] = `${key}=${value}`
+      added.push(key)
+      continue
+    }
+    insert.push(`${key}=${value}`)
+    added.push(key)
+  }
+  if (insert.length) {
+    // 插在最后一个非空行之后，避免落进注释块
+    let at = lines.length
+    while (at > 0 && lines[at - 1].trim() === '') at--
+    lines.splice(at, 0, ...insert)
+  }
+  return { text: lines.join('\n'), added, skipped }
+}