@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/ziniao-keepalive.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# ziniao-keepalive.sh —— 紫鸟**常驻 WebDriver 模式**的守护（W2 部署件）
+#
+# ## 为什么需要
+# 2026-09-24 用户选定「生产机常驻 WebDriver 模式」。常驻要成立，三件事必须自动：
+#   ① 开机/登录后**自己起来**（RunAtLoad）；
+#   ② 掉线（客户端退出/内核崩/IPC 端口不再监听）**自己拉回来**；
+#   ③ 授权链路（applyAuth 设备授权）**每天自愈一次**（`ziniao-auth-probe.sh` 已实现，这里复用）。
+#
+# ## 安全口径（这条比功能重要）
+# **默认不 kill 一个正在跑的 GUI 客户端**（那会关掉用户手开的所有店铺窗口 —— W2 已定的口径）。
+# 只有两种情况会启动客户端：① 完全没有紫鸟进程；② 显式 `ZINIAO_KEEPALIVE_RESTART=1`（生产机专用，
+# 表示"这台机器的客户端就该常驻 WebDriver 模式"）。
+# 应急开关：`touch ~/.dsh/argent/PAUSE_ZINIAO_KEEPALIVE` ⇒ 巡检直接跳过（运维在人工操作时用）。
+#
+# 用法：
+#   bash scripts/ziniao-keepalive.sh run            # 单次巡检（LaunchAgent 调的就是它）
+#   bash scripts/ziniao-keepalive.sh run --dry-run   # 只判断不动作（测试/排障）
+#   bash scripts/ziniao-keepalive.sh status         # 看 agent + 当前 IPC/客户端状态
+#   bash scripts/ziniao-keepalive.sh print-plist    # 只打印 plist（不装；测试用）
+#   bash scripts/ziniao-keepalive.sh install        # 写 plist + bootstrap（**改本机系统**）
+#   bash scripts/ziniao-keepalive.sh uninstall      # bootout + 删 plist
+set -uo pipefail
+
+# 仓库根与 agent PATH 都用共享实现（写死会让客户机的 plist 指向不存在的脚本）
+. "$(dirname "${BASH_SOURCE[0]}")/lib/repo-root.sh"
+REPO="$(argent_repo_root "${BASH_SOURCE[0]}")"
+AGENT_PATH="$(argent_agent_path)"
+export PATH="$(printf '%s' "$AGENT_PATH" | tr ':' '\n' | head -3 | paste -sd: -):$PATH"
+LABEL="com.whyshu.ziniao-keepalive"
+AGENTS="$HOME/Library/LaunchAgents"
+PLIST="$AGENTS/$LABEL.plist"
+LOGDIR="${ARGENT_LOG_DIR:-$HOME/Library/Logs/argent}"
+UID_N="$(id -u)"
+WD_PORT="${ZINIAO_WD_PORT:-19515}"
+INTERVAL_SEC="${ZINIAO_KEEPALIVE_INTERVAL_SEC:-180}"
+
+log() { echo "[$(date '+%F %T')] $*"; }
+pick_py() {
+  local c
+  for c in "${ARGENT_PY:-}" "$HOME/.dsh/argent/venv/bin/python3" "$REPO/.venv/bin/python3" \
+           "$(command -v python3 2>/dev/null || true)"; do
+    [ -n "$c" ] && [ -x "$c" ] && { printf '%s' "$c"; return 0; }
+  done
+  return 1
+}
+
+port_listening() {
+  "$PY" - "$WD_PORT" <<'PY' 2>/dev/null
+import socket, sys
+s = socket.socket(); s.settimeout(1.0)
+try:
+    s.connect(("127.0.0.1", int(sys.argv[1]))); print("yes")
+except Exception:
+    print("no")
+finally:
+    s.close()
+PY
+}
+
+client_running() { pgrep -f "[A]pplications/ziniao.app" >/dev/null 2>&1; }
+
+ipc_healthy() {
+  # 端口在听 ≠ 服务正常：真发一次 getRunningInfo（免凭据）
+  [ "$(port_listening)" = "yes" ] || return 1
+  "$PY" - "$REPO" "$WD_PORT" <<'PY' >/dev/null 2>&1
+import importlib.util, pathlib, sys
+repo, port = sys.argv[1], int(sys.argv[2])
+spec = importlib.util.spec_from_file_location("orch", pathlib.Path(repo) / "scripts" / "orchestrator.py")
+m = importlib.util.module_from_spec(spec); sys.modules["orch"] = m; spec.loader.exec_module(m)
+cfg = m.load_config()
+m.wd_running_info(cfg)          # 免凭据；失败会抛
+PY
+}
+
+cmd_run() {
+  local dry=0
+  for a in "$@"; do [ "$a" = "--dry-run" ] && dry=1; done
+  if [ -f "$PAUSE" ]; then
+    log "PAUSE_ZINIAO_KEEPALIVE 存在 ⇒ 跳过本次巡检（运维人工操作中）"; return 0
+  fi
+  if ipc_healthy; then
+    log "✅ WebDriver IPC 正常（端口 ${WD_PORT}）"
+    # ③ 授权链路每天自愈一次（探针自带 12h 去重；失败不阻塞，只叫人）
+    if [ -f "$REPO/scripts/ziniao-auth-probe.sh" ]; then
+      bash "$REPO/scripts/ziniao-auth-probe.sh" --quiet || {
+        local rc=$?
+        [ "$rc" = "2" ] && log "⚠️ 授权链路需要人工（ziniao-auth-probe --force 看详情）"
+      }
+    fi
+    return 0
+  fi
+
+  # IPC 不健康
+  if client_running; then
+    if [ "${ZINIAO_KEEPALIVE_RESTART:-0}" != "1" ]; then
+      log "⚠️ WebDriver IPC 不可用（端口 ${WD_PORT} 未响应）且客户端在跑 ⇒ **不 kill**（会关掉用户手开的窗口）"
+      log "   首因通常是**模式不对**：人工打开客户端 = GUI 模式，与 WebDriver 模式不能并存（**不是登录过期**）"
+      log "   处置：① 人工按部署约定以 --run_type=web_driver 重启；② 或设 ZINIAO_KEEPALIVE_RESTART=1 让本脚本接管重启"
+      return 3
+    fi
+    log "♻️ ZINIAO_KEEPALIVE_RESTART=1 ⇒ 关闭客户端后以 WebDriver 模式拉起（会关闭已开窗口）"
+    [ "$dry" = "1" ] && { log "[dry-run] 将 kill 紫鸟并重启"; return 0; }
+    pkill -f "[A]pplications/ziniao.app" 2>/dev/null || true
+    sleep 5
+  else
+    log "ℹ️ 没有紫鸟进程 ⇒ 以 WebDriver 模式启动"
+    [ "$dry" = "1" ] && { log "[dry-run] 将启动：open -a /Applications/ziniao.app --args --run_type=web_driver --ipc_type=http --port=${WD_PORT}"; return 0; }
+  fi
+
+  # 启动（官方前的提是主进程已完全退出；上面已确保）
+  open -a /Applications/ziniao.app --args --run_type=web_driver --ipc_type=http --port="${WD_PORT}" \
+    >/dev/null 2>&1 || { log "❌ open -a 启动失败（紫鸟是否已安装？）"; return 1; }
+  local deadline=$(( $(date +%s) + 120 ))
+  while [ "$(date +%s)" -lt "$deadline" ]; do
+    if ipc_healthy; then
+      log "✅ 已拉起并确认 IPC 正常（端口 ${WD_PORT}）"
+      [ -f "$REPO/scripts/ziniao-auth-probe.sh" ] && bash "$REPO/scripts/ziniao-auth-probe.sh" --quiet || true
+      return 0
+    fi
+    sleep 3
+  done
+  log "❌ 拉起后 120s 内 IPC 仍不可用 ⇒ 需人工（ziniao-auth-probe --force / 看客户端界面）"
+  "$PY" "$REPO/scripts/telemetry.py" --emit --kind engine --flow full --error-class needs_human \
+    --detail "紫鸟 keepalive：拉起后 IPC 仍不可用" >/dev/null 2>&1 || true
+  "$PY" "$REPO/scripts/telemetry.py" --flush >/dev/null 2>&1 || true
+  return 2
+}
+
+gen_plist() {
+  cat <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- 由 scripts/ziniao-keepalive.sh 生成（勿手改） -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>$LABEL</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>$REPO/scripts/ziniao-keepalive.sh</string>
+    <string>run</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StartInterval</key>
+  <integer>$INTERVAL_SEC</integer>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>ARGENT_PY</key><string>$PY</string>
+    <key>ZINIAO_WD_PORT</key><string>$WD_PORT</string>
+    <key>ZINIAO_KEEPALIVE_RESTART</key><string>${ZINIAO_KEEPALIVE_RESTART:-0}</string>
+    <key>PATH</key><string>$AGENT_PATH</string>
+  </dict>
+  <key>StandardOutPath</key><string>$LOGDIR/ziniao-keepalive.out.log</string>
+  <key>StandardErrorPath</key><string>$LOGDIR/ziniao-keepalive.err.log</string>
+</dict>
+</plist>
+PLIST
+}
+
+cmd_status() {
+  echo "── agent ──"
+  launchctl list 2>/dev/null | grep -i "$LABEL" || echo "  （未安装：bash scripts/ziniao-keepalive.sh install）"
+  echo "── 客户端 ──"
+  client_running && echo "  ✓ 紫鸟客户端进程在" || echo "  ✗ 无紫鸟客户端进程"
+  echo "  IPC ${WD_PORT}: $(port_listening)"
+  ipc_healthy && echo "  ✓ getRunningInfo 正常" || echo "  ✗ getRunningInfo 异常"
+  echo "  ${LOGDIR}/ziniao-keepalive.out.log（最近 5 行）："
+  tail -5 "$LOGDIR/ziniao-keepalive.out.log" 2>/dev/null | sed 's/^/    /' || echo "    （无日志）"
+  [ -f "$PAUSE" ] && echo "  ⏸  PAUSE_ZINIAO_KEEPALIVE 存在 ⇒ 巡检被跳过"
+}
+
+cmd_install() {
+  PY="$(pick_py)" || { echo "❌ 找不到 python3" >&2; exit 2; }
+  mkdir -p "$AGENTS" "$LOGDIR"
+  gen_plist > "$PLIST"
+  launchctl bootout "gui/$UID_N/$LABEL" 2>/dev/null || true
+  launchctl bootstrap "gui/$UID_N" "$PLIST" 2>/dev/null || launchctl load -w "$PLIST" 2>/dev/null || true
+  echo "✅ 已安装 ${PLIST}（RunAtLoad + 每 ${INTERVAL_SEC}s 巡检；日志 $LOGDIR/ziniao-keepalive.*.log）"
+  echo "   立刻生效判定：bash scripts/ziniao-keepalive.sh status"
+  echo "   卸载：bash scripts/ziniao-keepalive.sh uninstall"
+  [ "${ZINIAO_KEEPALIVE_RESTART:-0}" = "1" ] \
+    && echo "   ⚠️ ZINIAO_KEEPALIVE_RESTART=1：客户端不在 WebDriver 模式时脚本会**关闭并重启**它（会关掉已开窗口）" \
+    || echo "   ℹ️ 默认不 kill 正在跑的 GUI 客户端（生产机若要「永远 WebDriver 模式」，安装前设 ZINIAO_KEEPALIVE_RESTART=1）"
+}
+
+cmd_uninstall() {
+  launchctl bootout "gui/$UID_N/$LABEL" 2>/dev/null || true
+  rm -f "$PLIST"
+  echo "🗑  已卸载 ${LABEL}（客户端与店铺窗口**未**被触碰）"
+}
+
+PY="$(pick_py)" || { echo "❌ 找不到 python3" >&2; exit 2; }
+
+# 数据目录：**唯一判据**在 Python 单一实现（scripts/lib/argent_datadir.py，经 CLI 包装
+# scripts/argent-datadir.py）——⛔ 不在 bash 里重写三级链。取不到 ⇒ 响亮停住（fail-closed）。
+# 放在 `$PY` 之后：客户机 launchd 的 PATH 极简，用**已验过可执行**的解释器最稳。
+DATA="$("$PY" "$REPO/scripts/argent-datadir.py" 2>/dev/null || true)"
+if [ -z "$DATA" ]; then
+  echo "❌ $(basename "${BASH_SOURCE[0]}"): 数据目录判据不可用（$REPO/scripts/argent-datadir.py 取不到）⇒ 停住，不猜目录" >&2
+  exit 2
+fi
+PAUSE="$DATA/PAUSE_ZINIAO_KEEPALIVE"
+
+case "${1:-status}" in
+  run)          shift; cmd_run "$@" ;;
+  status)       cmd_status ;;
+  print-plist)  gen_plist ;;
+  install)      cmd_install ;;
+  uninstall)    cmd_uninstall ;;
+  *) echo "用法：bash scripts/ziniao-keepalive.sh run [--dry-run] | status | print-plist | install | uninstall" >&2; exit 2 ;;
+esac

package/engine/scripts/ziniao-post-upgrade-check.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# ziniao-post-upgrade-check.sh —— 紫鸟客户端**升级后**的一键复核（只读 + 幂等；不改业务数据）
+#
+# 背景：2026-09-24 排查"30 天人工登录"，定位到根因 = 客户端 6.26.6.6 太旧（Bridge 没有 /login 路由
+# ⇒ `zclaw login` 报 `parse login response: invalid character '<'`）。升级客户端后要确认：
+#   ① 版本变了；② doctor 的"终端绑定检查"不再报版本不支持；③ `zclaw login` 能成功（这是"免人工"关键）；
+#   ④ WebDriver 授权链路（IPC + applyAuth/getBrowserList）仍正常；⑤ 客户端回到常驻 WebDriver 模式。
+#
+# 用法：bash scripts/ziniao-post-upgrade-check.sh
+# 退出码：0=全部通过 / 2=有需要人工的项（逐条打印）
+set -uo pipefail
+# 仓库根：共享解析（脚本自身位置优先）—— 写死 ~/Code/argent-dsh 会让客户机
+# （克隆在 ~/.argent-dsh）上找不到本仓文件（2026-09-28 实测）
+. "$(dirname "${BASH_SOURCE[0]}")/lib/repo-root.sh"
+REPO="$(argent_repo_root "${BASH_SOURCE[0]}")"
+# 数据目录：**唯一判据**在 Python 单一实现（scripts/lib/argent_datadir.py，经 CLI 包装
+# scripts/argent-datadir.py）——⛔ 不在 bash 里重写三级链。取不到 ⇒ 响亮停住（fail-closed）。
+# 本脚本自身不依赖 python（纯 shell 诊断）⇒ 这里显式给候选解释器（与各脚本 pick_py 的候选表同源）：
+# ARGENT_PY → PATH 的 python3 → 默认位置的 venv。
+_DATA_PY="${ARGENT_PY:-$(command -v python3 2>/dev/null || true)}"
+if [ -z "$_DATA_PY" ] || [ ! -x "$_DATA_PY" ]; then
+  _DATA_PY="$HOME/.dsh/argent/venv/bin/python3"
+fi
+DATA="$("$_DATA_PY" "$REPO/scripts/argent-datadir.py" 2>/dev/null || true)"
+if [ -z "$DATA" ]; then
+  echo "❌ $(basename "${BASH_SOURCE[0]}"): 数据目录判据不可用（$REPO/scripts/argent-datadir.py 取不到）⇒ 停住，不猜目录" >&2
+  exit 2
+fi
+PRE="$DATA/.ziniao-pre-upgrade.txt"
+fails=0
+say() { echo "$*"; }
+ok()  { echo "  ✅ $*"; }
+bad() { echo "  ❌ $*"; fails=$((fails+1)); }
+warn(){ echo "  ⚠️  $*"; }
+
+say "═══ 紫鸟客户端升级后复核 $(date '+%F %T') ═══"
+
+say
+say "【0】版本：升级前 → 现在"
+[ -f "$PRE" ] && say "  升级前（快照）：$(grep -m1 '^version=' "$PRE" 2>/dev/null | cut -d= -f2-)"
+now="$(defaults read /Applications/ziniao.app/Contents/Info.plist CFBundleShortVersionString 2>/dev/null || echo '?')"
+say "  现在：${now}"
+if [ -d "$DATA/backup" ]; then
+  say "  回滚备份：$(ls -d "$DATA"/backup/ziniao-app-*.app 2>/dev/null | tail -1 || echo '（无）')"
+fi
+
+say
+say "【1】doctor（期望：终端绑定检查不再报「版本不支持」）"
+doc="$(ziniao-cli doctor 2>&1 || true)"
+if echo "$doc" | grep -q "不支持终端绑定检查"; then
+  bad "仍报「当前客户端版本不支持终端绑定检查」⇒ 客户端可能没升级成功"
+else
+  ok "终端绑定检查不再报版本不支持"
+fi
+echo "$doc" | grep -E "客户端登录用户|API Key 有效|Bridge" | sed 's/^/     /'
+echo "$doc" | grep -q "客户端登录用户" && ok "客户端已登录" || warn "客户端未登录（若被登出，需人工登录一次）"
+
+say
+say "【2】zclaw login（「免人工登录」的关键一环）"
+out="$(ziniao-cli zclaw login 2>&1)"; rc=$?
+case "$out" in
+  *次数过多*|*请1分钟后再试*)
+    warn "zclaw login 被**限流**（供应商：apiKey 登录验证次数过多，请1分钟后再试）⇒ 本次未判定，不是 Key 失效"
+    say "     （本脚本反复跑会撞限流；等 1 分钟后单独复跑：ziniao-cli zclaw login）" ;;
+  *)
+    if [ "$rc" = "0" ] && ! echo "$out" | grep -q "invalid character"; then
+      ok "zclaw login 成功 ⇒ 以后客户端会话到期可**程序化**恢复，不再需要人工点登录"
+    else
+      bad "zclaw login 仍失败：$(echo "$out" | head -2 | tr '\n' ' ')"
+      say "     ⇒ 把这条证据发给紫鸟支持：新 CLI 需要 Bridge 的 /login 路由；并问 WebDriver 模式下该端点是否可用"
+    fi ;;
+esac
+
+say
+say "【3】WebDriver 授权链路（跑票用；与上面那层无关）"
+if [ -f "$REPO/scripts/ziniao-auth-probe.sh" ]; then
+  ZINIAO_AUTH_PROBE_TTL_H=0 bash "$REPO/scripts/ziniao-auth-probe.sh" --force 2>&1 | sed 's/^/     /'
+  probe_rc=${PIPESTATUS[0]}
+  [ "$probe_rc" = "0" ] && ok "授权链路正常（⓪①② 全绿）" || bad "授权探针退出码 ${probe_rc}（看上面 ⓪①② 分层结论）"
+else
+  warn "找不到 ziniao-auth-probe.sh（跳过）"
+fi
+
+say
+say "【4】常驻形态：客户端是否在 WebDriver 模式"
+if [ -f "$REPO/scripts/ziniao-keepalive.sh" ]; then
+  bash "$REPO/scripts/ziniao-keepalive.sh" status 2>&1 | sed 's/^/     /' | head -8
+  say "     （若 IPC 不在听：升级期间守护被 PAUSE_ZINIAO_KEEPALIVE 挡住了，"
+  say "      确认无票在跑后执行：rm -f $DATA/PAUSE_ZINIAO_KEEPALIVE && bash scripts/*-keepalive.sh run）"
+else
+  warn "找不到 *-keepalive.sh（跳过）"
+fi
+
+say
+say "【5】ChromeDriver 缓存面 ↔ 内核大版本（只读；P1-g）"
+WINDOWS="$REPO/scripts/ziniao-windows.sh"
+if [ -f "$WINDOWS" ]; then
+  # 只读：缓存里有哪些大版本的驱动 ↔ 在跑窗口的内核大版本（免凭据：getRunningInfo + 窗口 CDP）。
+  # ⛔ 不下载、不删除、不调需凭据接口；结果只打印，不参与 fails 判据（缓存缺失不是"升级失败"）。
+  bash "$WINDOWS" cache 2>&1 | sed 's/^/     /' || warn "缓存面巡检未跑成（看上面输出；只读项，不影响升级判定）"
+else
+  warn "找不到 *-windows.sh（跳过缓存面巡检）"
+fi
+
+say
+say "【6】插件安装状态（只读探测；P1-f）"
+if [ -f "$WINDOWS" ]; then
+  # 官方 getPluginInstalled 免凭据，但需要 pluginIds 来源；没有来源时只报「能力未接」（⛔ 不猜）。
+  bash "$WINDOWS" plugins 2>&1 | sed 's/^/     /' || warn "插件探测未跑成（只读项，不影响升级判定）"
+else
+  warn "找不到 *-windows.sh（跳过插件探测）"
+fi
+
+say
+if [ "$fails" = "0" ]; then
+  say "✅ 全部通过。下一步（确认无票在跑后）：bash scripts/dev-window.sh off（恢复被本窗口暂停的轮询）"
+  exit 0
+fi
+say "❌ 有 ${fails} 项需要处理（见上）"
+exit 2

package/engine/scripts/ziniao-windows.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# ziniao-windows.sh —— 紫鸟**窗口**运维小工具（W5：窗口回收由人显式决定，不自动关）
+#
+# 为什么不做"跑完自动关店"（W5 的原始设想被否）：我们刚修好"每轮 startBrowser = 重启窗口"
+# （官方 api-core.md 原文），而**跑完就关店**会让下一轮又得 startBrowser 重启一遍——
+# 等于把刚修掉的病再种回去（端口又会漂、旧标签页又会失效）。
+# 所以：**默认什么都不关**；要回收窗口时由人显式执行本脚本。
+#
+# 用法：
+#   bash scripts/*-windows.sh list                 # 只读：列出当前已开店铺窗口（端口/内核/句柄）
+#   bash scripts/*-windows.sh close <店铺名>        # 关闭指定店铺窗口（stopBrowser，异步，有界等待）
+#   bash scripts/*-windows.sh close --store-id <id>
+#   bash scripts/*-windows.sh cache                # 只读（P1-g）：ChromeDriver 缓存面 ↔ 在跑窗口内核大版本
+#   bash scripts/*-windows.sh plugins              # 只读（P1-f）：插件安装状态（无 pluginIds 来源 ⇒ 只报「能力未接」）
+#   bash scripts/*-windows.sh clear-cache [--oauth <店铺标识>]… [--yes]
+#                                                  # **写**：清理本地缓存（免凭据；⛔ 默认 dry-run）
+#   bash scripts/*-windows.sh clear-online --store <店铺名> [--type 1|2|3] [--yes]
+#                                                  # **写 + 需凭据**：清理在线缓存（⛔ 默认 dry-run；
+#                                                  #   type=3 = 仅保留二步认证 cookie = 登录态在、页面脏时用）
+# ⛔ 后两条**只供人工**：编排路径不会调用它们（默认 dry-run，`--yes` 才真跑）。
+set -uo pipefail
+
+# 仓库根：共享解析（脚本自身位置优先）—— 写死 ~/Code/argent-dsh 会让客户机
+# （克隆在 ~/.argent-dsh）上找不到本仓文件（2026-09-28 实测）
+. "$(dirname "${BASH_SOURCE[0]}")/lib/repo-root.sh"
+REPO="$(argent_repo_root "${BASH_SOURCE[0]}")"
+PY="${ARGENT_PY:-$HOME/.dsh/argent/venv/bin/python3}"
+[ -x "$PY" ] || PY="$(command -v python3)"
+
+cmd="${1:-list}"; shift || true
+exec "$PY" - "$cmd" "$@" <<'PY'
+import json, os, sys, time
+sys.path.insert(0, os.path.join(os.environ.get("ARGENT_DSH_REPO", os.path.expanduser("~/Code/argent-dsh")), "scripts"))
+import importlib.util, pathlib
+repo = os.environ.get("ARGENT_DSH_REPO", os.path.expanduser("~/Code/argent-dsh"))
+spec = importlib.util.spec_from_file_location("orch", pathlib.Path(repo) / "scripts" / "orchestrator.py")
+m = importlib.util.module_from_spec(spec); sys.modules["orch"] = m; spec.loader.exec_module(m)
+cfg = m.load_config()
+cmd = sys.argv[1] if len(sys.argv) > 1 else "list"
+if cmd == "list":
+    inv = m.window_inventory(cfg)
+    print("已开店铺窗口：", inv or "(无)")
+    print("（口径：官方 getRunningInfo；端口/内核/句柄可用于判断窗口是否被重启过）")
+    raise SystemExit(0)
+if cmd == "close":
+    target = " ".join(sys.argv[2:]).strip()
+    if not target:
+        print("用法：ziniao-windows.sh close <店铺名|--store-id <id>>", file=sys.stderr); raise SystemExit(2)
+    creds = m._load_wd_creds()
+    if creds is None:
+        print("✗ 缺少 WebDriver 凭据（~/.dsh/argent/ziniao-webdriver.env）", file=sys.stderr); raise SystemExit(2)
+    try:
+        stores = m.wd_list_stores(cfg, creds)
+    except Exception as exc:
+        print(f"✗ 取店铺清单失败：{exc}", file=sys.stderr); raise SystemExit(2)
+    if target.startswith("--store-id"):
+        sid = target.split()[-1]
+        hit = next((s for s in stores if str(s.get("browserId")) == sid), None)
+    else:
+        hit = next((s for s in stores if str(s.get("browserName")) == target), None)
+    if hit is None:
+        print(f"✗ 店铺清单里没有 {target!r}；先 `ziniao-windows.sh list` 看名字", file=sys.stderr)
+        raise SystemExit(2)
+    print(f"▸ 关闭店铺窗口：{hit.get('browserName')}（stopBrowser，异步有界等待）")
+    m.wd_stop_browser(cfg, creds, hit)
+    print("✅ 已请求关闭；用 list 复核（异步关闭通常数秒完成）")
+    raise SystemExit(0)
+if cmd == "cache":
+    # P1-g（只读）：ChromeDriver 缓存面 ↔ 在跑窗口的内核大版本（免凭据：getRunningInfo + 窗口 CDP）
+    ver, src = m.detect_running_core_version_free(cfg)
+    info = m.chromedriver_cache_inventory(ver)
+    print(m.chromedriver_cache_line(info))
+    print(f"（内核大版本判据：{ver or '取不到'}；来源：{src}）")
+    print("（口径：官方 prerequisites 的缓存目录 {大版本}/chromedriver；⛔ 只读——不下载、不删除、不连需凭据接口）")
+    raise SystemExit(0)
+if cmd == "plugins":
+    # P1-f（只读）：插件安装状态。没有 pluginIds 来源 ⇒ 如实报「能力未接」，⛔ 不猜、不硬凑
+    probe = m.probe_plugin_installed(cfg)
+    print(m.format_plugin_probe(probe))
+    print(f"（调用计划：callable={probe.get('callable')} reason={probe.get('reason')} "
+          f"needs_creds={probe.get('needs_creds')} browserId={probe.get('browser_id') or '(无)'}）")
+    raise SystemExit(0)
+if cmd in ("clear-cache", "clear-online"):
+    # P1-h（**写**操作；⛔ 默认 dry-run，`--yes` 才真跑；编排路径不调用本命令）
+    rest = sys.argv[2:]
+    yes = "--yes" in rest
+    where = lambda flag: [rest[i + 1] for i, a in enumerate(rest)
+                          if a == flag and i + 1 < len(rest)]
+    if cmd == "clear-cache":
+        oauths = where("--oauth")
+        payload = m.clear_cache_payload(oauths)
+        print(m.format_clear_preview(m.clear_request_preview(
+            "clear-cache", payload, store_name="、".join(oauths) or "(全部店铺)",
+            notes=["免凭据接口；要指定店铺用 --oauth <店铺标识>（可重复），不给 = 全部"])))
+        if not yes:
+            raise SystemExit(0)
+        try:
+            resp = m.wd_clear_cache(m._wd_ipc_port(cfg), oauths)
+        except Exception as exc:                            # noqa: BLE001
+            print(f"✗ ClearCache 调用失败：{exc}", file=sys.stderr); raise SystemExit(2)
+        print(f"✅ ClearCache 已调用：statusCode={resp.get('statusCode')}"
+              f"{(' LastError=' + str(resp.get('LastError'))) if resp.get('LastError') else ''}")
+        raise SystemExit(0)
+    # clear-online：需凭据 + 目标店铺
+    typ = 3
+    for v in where("--type"):
+        try:
+            typ = int(v)
+        except ValueError:
+            print("✗ --type 只能是 1/2/3", file=sys.stderr); raise SystemExit(2)
+    creds = m._load_wd_creds()
+    if creds is None:
+        print("✗ ClearOnline 需要凭据（~/.dsh/argent/ziniao-webdriver.env）", file=sys.stderr)
+        raise SystemExit(2)
+    target = (where("--store-id") or where("--store") or [""])[0]
+    oauth = (where("--oauth") or [""])[0]
+    if target and not oauth:
+        try:
+            stores = m.wd_list_stores(cfg, creds)
+        except Exception as exc:                            # noqa: BLE001
+            print(f"✗ 取店铺清单失败：{exc}", file=sys.stderr); raise SystemExit(2)
+        key = "--store-id" if where("--store-id") else "--store"
+        hit = next((s for s in stores if str(s.get("browserId" if key == "--store-id" else "browserName")) == target), None)
+        if hit is None:
+            print(f"✗ 店铺清单里没有 {target!r}；先 `scripts/*-windows.sh list` 看名字", file=sys.stderr)
+            raise SystemExit(2)
+        oauth = str(hit.get("browserOauth") or hit.get("browserId") or "")
+    if not oauth:
+        print("✗ ClearOnline 需要 --store <店铺名> / --store-id <id> / --oauth <店铺标识> 之一", file=sys.stderr)
+        raise SystemExit(2)
+    try:
+        payload = m.clear_online_payload(creds, oauth, typ)
+    except ValueError as exc:
+        print(f"✗ {exc}", file=sys.stderr); raise SystemExit(2)
+    print(m.format_clear_preview(m.clear_request_preview(
+        "clear-online", payload, store_name=target or oauth,
+        notes=[f"type={typ} 的适用场景见上一行；写操作会改本机店铺缓存的在线状态",
+               "真要跑请确认该店铺**没有**在跑票（编排路径不会自动调用本命令）"])))
+    if not yes:
+        raise SystemExit(0)
+    try:
+        resp = m.wd_clear_online(m._wd_ipc_port(cfg), creds, oauth, typ)
+    except Exception as exc:                                # noqa: BLE001
+        print(f"✗ ClearOnline 调用失败：{exc}", file=sys.stderr); raise SystemExit(2)
+    print(f"✅ ClearOnline 已调用（type={typ}）：statusCode={resp.get('statusCode')}"
+          f" {resp.get('statusMsg') or ''}"
+          f"{(' LastError=' + str(resp.get('LastError'))) if resp.get('LastError') else ''}")
+    raise SystemExit(0)
+print("用法：list | close <店铺名|--store-id <id>> | cache | plugins | "
+      "clear-cache [--oauth <店铺标识>]… [--yes] | "
+      "clear-online (--store <店铺名>|--oauth <店铺标识>) [--type 1|2|3] [--yes]",
+      file=sys.stderr); raise SystemExit(2)
+PY

package/engine/version.mjs

@@ -0,0 +1 @@
+export const VERSION = "0.6.0"

package/engine/verticals/README.md

@@ -0,0 +1,103 @@
+# 业务线（vertical）契约
+
+> Argent 0.2 起，**底座与业务线分离**：底座（引擎/角色运行时/装机器/门禁/商业机制）业务中立，
+> 一条业务线 = 一个可独立开发、安装、授权、迭代、回滚的单元。
+> 本文件是**业务线作者**（含将来的第三方）的唯一入口；引擎侧规则见
+> `docs/Argent-0.2-平台与业务线架构-评审稿-2026-09-29.md`。
+
+## 一条业务线长什么样
+
+```
+verticals/<id>/
+  manifest.json      元数据：版本、依赖区间、端口、能力、角色、技能、流程清单
+  flows.json         流程声明（局部 id；合并后规范 id = <id>.<local>）
+  prompts/<flow>.md  派发提示词（引擎按轮次投给角色）
+  roles/             角色 preset 源 → 安装到 `presets/argent-<id>-<role>/`
+  skills/            技能源 → 安装到 `skills/<id>-<skill>/`
+  adapters/<system>/ 外部系统适配器（人工门、错误词表、可执行计划）
+  billing.json       计费单位（只算成功 / 一票一结 / 证据可核）
+  preflight.py       本线验收检查段（由 customer-preflight 汇总）
+  tests/             本线测试与夹具（run-all-tests.sh 自动收集）
+  env/               本线环境变量（600；**只在本线可见**）
+```
+
+## 三条硬规矩（`vertical-lint.mjs` 会拦）
+
+1. **命名空间**：所有对外可见的名字都带业务线前缀 —— 两条线装在同一台机器上不允许撞名。
+
+   | 对象 | 规则 | 例（`id=customer-order`） |
+   |---|---|---|
+   | flow id | `<id>.<local>` | `customer-order.intake` |
+   | 角色（preset） | `argent-<id>-<role>` | `argent-customer-order-clerk` |
+   | 技能 | `<id>-<skill>` | `customer-order-intake` |
+   | 暂停开关 | `verticals/<id>/PAUSE.<flow>` | `verticals/customer-order/PAUSE.intake` |
+   | 定时器 label | `com.whyshu.flow-trigger.<id>.<flow>` | 自动派生 |
+   | env 文件 | `verticals/<id>/env/*.env` | `verticals/customer-order/env/prod.env` |
+   | 提示词 | `verticals/<id>/prompts/*.md` | — |
+   | 能力包 id | `<id>.<unit>` | `customer-order.intake` |
+
+2. **跨线引用为零**：`verticals/A` 不得引用 `verticals/B` 的路径、flow、角色、技能。
+   两条线需要共享的东西，**上提到引擎或端口**，不要在业务线之间拉手。
+
+3. **引擎不掺业务**：`scripts/` 与 `plugins/<plugin>/src/` 不得出现业务词（美客多/文鳐/紫鸟/…）。
+   历史存量记在 `_engine-words.baseline.txt`，门禁只拦**新增**；搬迁完成后基线应清零。
+
+## 冲突判据在加载器，不在 lint
+
+`scripts/flow_registry.py` 负责合并 **base（`scripts/flow-requirements.json`）+ 各业务线**，并保证：
+同名 flow / 能力 / 计费单位 / 失败类 / 别名 **一律 fail（不静默覆盖）**；`manifest.id`、
+`flows.json#vertical` 与目录名不一致也 fail（防复制粘贴串线）。
+
+```bash
+python3 scripts/flow_registry.py --check     # 合并与冲突
+python3 scripts/flow_registry.py --list      # 规范 flow id
+python3 scripts/flow_registry.py --flow intake   # 别名 → 规范 id
+node scripts/vertical-lint.mjs               # 业务线门禁
+```
+
+回退开关：`ARGENT_REGISTRY_MODE=legacy`（只读 base，不扫业务线）；显式 `--registry <file>` 亦为 legacy 单文件行为。
+
+## 端口（该线用到哪些底座能力）
+
+在 `manifest.json#ports` 声明；新增实现时同步更新 `vertical-lint.mjs` 的 `KNOWN_PORTS`。
+
+| 端口 | 职责 | 现有实现 |
+|---|---|---|
+| `source` | 任务队列/数据源 | `feishu-base`（唯一实现；`http-json`/`sql`/`file`/`manual` 待做，见 P4） |
+| `transport` | 人机通道（收指令、唤醒） | `feishu`（`gateway-core` 拆分后可有 `web`/`wecom`） |
+| `notify` | 出站通知/卡片 | `feishu-card`、`log` |
+| `actor` | 外部系统动作 | `none`、`internal-http`；货代类见 `scripts/integrations/`（待泛化） |
+| `identity` | 凭据/身份 | `env`（`verticals/<id>/env/*.env`） |
+
+## 开一条新线
+
+```bash
+node scripts/vertical-init.mjs --id customer-order --title "客单系统" \
+     --flow intake --role clerk --skill intake
+```
+
+生成物是**安全态**（`wake=off`、`mode=shadow`），按 `verticals/<id>/README.md` 的待办清单逐项填。
+上线顺序固定：**只读跑通 → `mode=real` → `wake=session`**。
+
+## 门禁（每条线都要过）
+
+```bash
+node scripts/vertical-lint.mjs          # 本文件的三条硬规矩 + manifest 自洽
+python3 scripts/flow_registry.py --check
+node scripts/tests/run-all-tests.sh     # 平台回归 + 本线测试（tests/ 自动收集）
+node scripts/gen-preset-rows.mjs        # 改了角色后必跑（0.1.7 行式 preset）
+node scripts/validate-preset-schema.mjs --runtime && node scripts/plugin-bootcheck.mjs
+```
+
+## 安装与授权
+
+- 业务线是**安装边界**：`install-argent.mjs --add-capability <id>` 只落本线声明的文件，
+  别的线的文件不会上机器；`--rollback` 按线回退上一版。
+- 授权：`manifest.capabilities[].minPlan` + 注册表 `entitlements`（档位矩阵是唯一出处）。
+- 装机前校验 `manifest.requires.{argent,dsh}` 与 `verifiedOn`（"已在哪些版本实测过"）——
+  不允许把没验过的线装到目标机器上。
+
+## 与 profile 的关系
+
+**能力包能分开的，用包分；包分不开的（专属插件/专属通道/不同 dsh 版本/独立 UI），
+才用 dsh profile 分**（`dsh web --profile <v> --port <n>`）。默认形态是"业务线包 + 共用 base profile"。