@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/ziniao-keepalive.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
+# 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:-}" "$ARGENT_DATA_DIR_RESOLVED/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,121 @@
+#!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据
+# 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="$ARGENT_DATA_DIR_RESOLVED/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,154 @@
+#!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
+# 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:-$ARGENT_DATA_DIR_RESOLVED/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/skills/README.md

@@ -0,0 +1,86 @@
+# Argent 技能目录
+
+本目录存放 Argent 的 DSH 技能（SKILL.md 格式）。运行时落位到 `<dshHome>/skills`
+（preset 零配置挂载 `skill-filesystem` 的默认根，扫描直接子目录）。
+
+## 技能目录谁在管（2026-10-04 按现行代码订正）
+
+**升级器有角色过滤了（= 外发白名单）。** 三个环节的行为各不相同：
+
+| 环节 | 行为 | 证据 |
+|---|---|---|
+| **安装**（`install-argent.mjs`） | **完全不碰技能目录**：只 `mkdirSync` 保证存在，不清理、不新增 | `install-argent.mjs:584-590`（注释「KB-061：不再按角色隔离」「已存在的 `<dshHome>/skills` 与仓库技能目录一律不碰」） |
+| **安装**（`install-dsh.sh`） | 旧 bash 安装器，角色只支持 `general` / `hr-office`；`ml-seller` 分支直接 die（企业级订阅专享） | `install-dsh.sh:26-40` |
+| **升级**（`scripts/argent-upgrade.mjs`） | **只同步外发集**（= `verticals/*/manifest.json#skills` 并集，判据复用 `check-skill-classification.mjs#classify()`）；**内部角色技能（`skills/internal.json`）不同步**；宿主里既有的内部/旧技能**只报告不删**；内容 sha 一致 ⇒ 幂等跳过 | `argent-upgrade.mjs#syncSkills`（2026-10-04 修：客户机实测旧版 `✓ 技能同步: 11 项` = 5 外发 + 6 内部，违反 D5）；回归 `scripts/tests/upgrade-skill-whitelist.test.mjs` |
+| **清理**（`scripts/skill-install.mjs --prune-orphans`） | **人工决策**的收敛动词（默认 dry-run）：只列"将删除（点名）/ 未点名 / 拒绝清理"，真删要 `--apply` **且逐个 `--allow <name>` 点名**；只删四条件同时满足的目录（不在外发集 / 不在 `internal.json` / 不在安装器清单 / 含 `SKILL.md`），**先备份再删** | 见下「收敛宿主里的旧残留」；回归 `scripts/tests/skill-subset.test.mjs`【F】 |
+
+**收敛宿主里的旧残留（客户机实测：6 个内部角色技能 + 12 个旧 hermes 期技能）** —— 升级器**故意不删**，
+所以清理是**人的决定**，命令分两步（`--dir` 写死目标最稳；`~/.dsh/skills` 就是 dsh 宿主的技能根）：
+
+```bash
+# ① 先看清单（缺省 dry-run，零副作用）：哪些会被删、哪些拒绝、为什么
+node ~/Code/argent-dsh/scripts/skill-install.mjs --host dsh --prune-orphans --allow-host-dsh-prune
+# ② 逐个核对名字后**逐个点名**真删（备份到 <dir>/.argent-skills-pruned-<ts>/，审计见 .argent-skills-prune-audit.jsonl）
+node ~/Code/argent-dsh/scripts/skill-install.mjs --host dsh --prune-orphans --allow-host-dsh-prune \
+  --apply --allow hermes-era-skill-01 --allow hermes-era-skill-02
+```
+⚠️ **不该自动清的**：`skills/internal.json` 里的 6 个内部角色技能（宿主上它们是**角色包「已装」的判据**，
+清了角色包状态就对不上）、外发集里那 5 个（归升级器/安装器管）、安装器清单里的（用 `--uninstall`）、
+任何**用户自建**（非技能形态一律拒绝；手写技能与旧残留形态无法区分 ⇒ 只能靠逐个点名 + 人眼核对）。
+
+**结论**：技能一旦在仓库 `skills/` 下，**必须先在两处声明里归类**（外发 or 内部）——外发的会被同步给
+每一个 agent 的技能目录，内部的**不会**；**未归类的目录不会被同步**，但门禁会判红（`G2`）。
+角色级的技能可见性由**网关群级** `chats[<chatId>].skills` 决定
+（`plugins/argent-gateway/src/index.js:628-629` 拼成「【本群启用技能】…」进 prompt），
+角色级 `skills` 字段只是权益回显。**不要把 `ml-daily` / `ml-fulfillment` 当技能目录名**——
+它们是套餐装配档标识，实际目录是 `ml-store-daily-report` / `ml-fulfillment-sop`。
+
+> 历史说明：旧文档写的「角色 → 技能集合（`install-argent.mjs` 的 `ROLE_SKILLS`）」**已无实现**——
+> 该符号在全仓库只剩两处注释提及（`plugins/argent-core/src/index.js:195` 与本文），没有任何代码路径。
+
+## 当前技能清单（11 个目录）—— 并且**分成外发 / 内部两半**
+
+> ⚠️ 2026-10-03（P3）更正：本节原写「9 个目录」，实际 **11**（漏了 `ml-invoice-xzh` / `ml-config-guide`）。
+> 清单**不再手抄**，判据在两处声明里：外发 = `verticals/<id>/manifest.json#skills`（**唯一真源**），
+> 内部 = `skills/internal.json`（逐条带理由）。跑 `node scripts/check-skill-classification.mjs` 看当前分类。
+
+**外发（客户可用的流程技能，5 个）** —— 真源：`verticals/mercadolibre/manifest.json#skills`
+
+- `ml-fulfillment-sop/` —— FULL 货件管理（含 references / scripts / template）
+- `ml-store-daily-report/` —— 美客多店铺日报
+- `ml-invoice/` —— 上海文鳐发票全链路
+- `ml-invoice-xzh/` —— 鑫中航发票全链路（同引擎、不同门户）
+- `ml-config-guide/` —— 配置缺口诊断与引导（替代写死 schema 快照的旧校验）
+
+**内部（不外发的角色技能，6 个）** —— 真源：`skills/internal.json`（含逐条理由）
+
+- `argent-dev/` `pet-dev/` `whyshu-web-dev/` `whyshu-pm/` `lktop-pm/` `lktopapp-dev/`
+  （角色包「已装」的硬判据：`plugins/argent-packs/src/index.js` 以 `~/.dsh/skills/<skill>` 是否存在为准）
+
+⚠️ **往 `skills/` 丢一个新目录 = 必须先归类**：外发（写进业务线声明）才会同步给客户，
+未归类的目录**不会**被同步，但门禁 `G2` 会判红（升级器只发外发集，见上表）⇒ 必须先做一次决定：
+写进业务线声明（外发）或写进 `skills/internal.json`（内部）。
+安装到非 dsh 宿主用 `node scripts/skill-install.mjs --host <dsh|claude-code|codex|cursor> --apply`（只装外发 5 个；**缺省只预演**，真装要 `--apply`）。
+
+## 技能格式
+
+```markdown
+---
+name: <skill-id>
+description: <一句话说明，用于技能目录展示与匹配>
+---
+<技能正文指令>
+```
+
+硬约束（`dsh-skill-filesystem` 的 `parseSkillFile()`）：首行 `---` 且**有闭合 `---`**；
+`name` 必须是**严格小写 kebab-case**且等于目录名（**中文名一律非法**，会被静默丢弃）；
+frontmatter 必须**同时含 `name` 与 `description`**。
+
+改完技能后跑门禁：
+
+```bash
+python3 scripts/fix-skill-frontmatter.py --check          # 格式（闭合 + kebab name + description）
+node scripts/tests/skills-frontmatter.test.mjs
+node scripts/check-skill-classification.mjs               # 归类（外发/内部/未归类即红）
+node scripts/tests/skill-subset.test.mjs                  # 归类 + 外发安装器回归
+```

package/engine/skills/argent-dev/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: argent-dev
+description: Argent开发者角色技能：Argent on DSH 开发知识（安装器/插件/preset/脚本）与 dsh 插件三种角色能力设计。接 whyshu-pm 任务，完成后飞书群 @ 汇报。
+version: 1.0.0
+author: 问述科技 (Whyshu)
+license: MIT
+metadata:
+  argent:
+    role: argent-dev
+    tags: [argent, dsh, cordis, plugin]
+---
+
+# Argent开发者（argent-dev）
+
+## 角色定位
+
+Argent 产品开发者，负责 argent-dsh 仓库（安装器/插件/preset/脚本/skills）与策划文档的落地。
+
+## 核心知识入口
+
+- **Argent 仓库**：`/Users/chester/Code/argent-dsh`（本机开发仓库，远端 whyshu 裸仓库镜像）
+  - `install-argent.mjs`：跨平台安装器（`--role / --dsh-home / --port` 等）
+  - `plugins/`：argent-core / argent-skin / argent-files / argent-ml（cordis 插件）
+  - `presets/`：各角色 Agent Preset（agent.cordis.yml 组合）
+  - `scripts/`：daily-report.mjs / orchestrator.py / feishu-bridge.js 等
+- **策划文档**：`/Users/chester/Code/whyshu/docs/products/argent-*`（含
+  `argent-edition-multi-instance-plan.md` 多实例生态策划案 v0.9）
+- **dsh 插件开发**：三种角色能力设计（Service Definition / Provider / Consumer，
+  参考 deepseek-harness 官方 practice 文档）。
+
+## 协作流
+
+1. whyshu-pm 在飞书群 @ 开发者分配任务并附验收标准（旧看板已退场；新任务机制上线前以此为准）；
+2. 在飞书群/会话中确认验收标准；
+3. 完成后在飞书群 @whyshu-pm 汇报。
+
+## 红线（仓库全局规则）
+
+- **严禁重启本机 dsh web 服务**（LaunchAgent com.whyshu.dsh-web，自杀式重启）；
+- **严禁擅自升级/重装全局 dsh**（锁定 0.1.1-rc.1，快照安装流程）；
+- 客户端插件改动浏览器硬刷新生效；host 端插件改动需用户手动重启服务。