@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/dsh-remote-check.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# dsh-remote-check.sh —— 远程访问（EasyTier 组网 → 端口转发 → dsh web 围栏）一条命令自检。
+#
+# 为什么有它（2026-09-22 事故）：Mac 重启后 PC 打不开 dsh web，排查发现**三处硬编码了同一个
+# 会变的地址**，而失败是"进程还活着、日志写在 /tmp（重启即清）"⇒ 表面看一切正常：
+#   ① EasyTier 用 -d(DHCP) ⇒ 重启后地址 .2 → .1；
+#   ② dsh-portforward.py --listen-host 10.126.126.2 ⇒ bind 失败（日志 /tmp，无迹可查）；
+#   ③ dsh-web --trusted-host 10.126.126.2:3080 ⇒ 新地址被围栏 403。
+# 本脚本按层体检，并明确告诉你卡在哪一层、下一步做什么。
+set -uo pipefail
+CIDR="${ARGENT_OVERLAY_CIDR:-10.126.126.}"
+LOGDIR="$HOME/Library/Logs/argent"
+rc=0
+
+echo "── ① EasyTier 进程与覆盖网地址"
+if pgrep -x easytier-core >/dev/null; then
+  echo "  ✅ easytier-core 在跑（PID $(pgrep -x easytier-core | head -1)）"
+else
+  echo "  ❌ easytier-core 没在跑 ⇒ PC 根本到不了这台机器"
+  echo "     ↳ 修：/Users/$USER/.local/bin/start-easytier.sh（或在 launchd 里 kickstart com.easytier.whyshu）"
+  rc=1
+fi
+mapfile -t OVERLAY < <(ifconfig 2>/dev/null | awk '/inet /{print $2}' | grep "^${CIDR}" || true)
+if [ "${#OVERLAY[@]}" -eq 0 ]; then
+  echo "  ❌ 找不到 ${CIDR}x 的地址（覆盖网没起来 / 地址变了）"
+  rc=1
+else
+  echo "  ✅ 覆盖网地址：${OVERLAY[*]}"
+fi
+
+echo "── ② 端口转发（本机覆盖网 IP:3080 → 127.0.0.1:3080）"
+if launchctl list com.whyshu.dsh-portforward >/dev/null 2>&1; then
+  echo "  ✅ LaunchAgent 已加载（pid=$(launchctl list | awk '/dsh-portforward/{print $1}')）"
+else
+  echo "  ❌ LaunchAgent 未加载 ⇒ 外部无法从覆盖网访问"
+  echo "     ↳ 修：bash ~/Code/argent-dsh/scripts/dsh-remote-access.sh install（若提供）或 launchctl bootstrap gui/\$(id -u) ~/Library/LaunchAgents/com.whyshu.dsh-portforward.plist"
+  rc=1
+fi
+BOUND=$(lsof -nP -iTCP:3080 -sTCP:LISTEN 2>/dev/null | awk -v p="$CIDR" '$9 ~ p {print $9}')
+if [ -n "$BOUND" ]; then
+  echo "  ✅ 已监听：$BOUND"
+else
+  echo "  ❌ 覆盖网上没有监听 3080（转发器多半 bind 失败——典型原因：它被写死到某个已不存在的地址）"
+  echo "     ↳ 看日志：tail -20 $LOGDIR/dsh-portforward.log（历史事故里这条日志曾写在 /tmp，重启即清）"
+  rc=1
+fi
+
+echo "── ③ dsh web 围栏（trusted-host）与可达性"
+TRUST=$(plutil -p ~/Library/LaunchAgents/com.whyshu.dsh-web.plist 2>/dev/null \
+  | grep -oE '[0-9]{1,3}(\.[0-9]{1,3}){3}:[0-9]+' | sort -u | tr '\n' ' ')
+echo "  plist 里的 trusted-host：${TRUST:-（无）}"
+# ⚠️ plist 改了 ≠ 生效：launchd 的 `kickstart -k` 用的是**缓存的旧定义**（2026-09-22 实测：
+# 改完 plist 再 kickstart，运行中的进程仍只有旧地址 ⇒ 新地址继续 403）。必须比对运行参数。
+#
+# 2026-10-01 修**假警报**（与 dsh-restart.sh 同一处判据，用户实测）：dsh web 是**父子两段**
+# 进程（启动器 `dsh-web-launch.mjs web …` + 真正采用参数的 `…/dsh/lib/bin.js web …`），
+# launchd 起的 argv[0] 又是绝对路径。旧的 `grep "[d]sh web" | head -1` 只取一个进程 ⇒
+# 随手就会误报"未采用"。现判据 = **全部相关进程的 trusted-host 并集**，唯一实现
+# 在 `scripts/lib/dsh-web-probe.mjs`（与 dsh-restart.sh 共用，收集/比对/文案都只有一份）。
+# 退出码：0 通过 ｜ 1 **真的缺失** ｜ 2 没找到进程（未运行/进程名不符）｜ 3 探测失败。
+PROBE="$(dirname "${BASH_SOURCE[0]}")/lib/dsh-web-probe.mjs"
+if [ ! -f "$PROBE" ]; then
+  echo "  ⚠️ 探测模块缺失（${PROBE}）⇒ 跳过运行参数核对（不退回旧的单进程判据：它会把父子两段误报成「未采用」）"
+else
+  node "$PROBE" --want "$TRUST" | sed 's/^/  /'
+  PROBE_RC=${PIPESTATUS[0]}
+  case "$PROBE_RC" in
+    0) : ;;
+    1) rc=1 ;;
+    *) echo "     ↳ 这只是**没能核对**（不是「未采用」）；服务是否被信任仍看下面的逐地址探测结果" ;;
+  esac
+fi
+for ip in "${OVERLAY[@]}"; do
+  code=$(curl -s -o /dev/null -m 5 -w "%{http_code}" "http://$ip:3080/api" -H "Host: $ip:3080" || echo 000)
+  case "$code" in
+    401) echo "  ✅ $ip:3080 可达且被信任（HTTP 401 = 需要登录，属正常）" ;;
+    403) echo "  ⚠️ $ip:3080 被 dsh web 围栏拒绝（HTTP 403）⇒ 该地址不在 trusted-host 里"
+         echo "     ↳ plist 已补地址，但要**重启 dsh web** 才生效：bash ~/Code/argent-dsh/scripts/dsh-restart.sh"; rc=1 ;;
+    000) echo "  ❌ $ip:3080 连不上（转发或覆盖网问题，看上两层）"; rc=1 ;;
+    *)   echo "  ⚠️ $ip:3080 返回 HTTP $code" ;;
+  esac
+done
+# 白名单是否覆盖当前地址（未覆盖 ⇒ 重启 dsh web 才生效；没重启就会 403）
+if [ "${#OVERLAY[@]}" -gt 0 ]; then
+  cur="${OVERLAY[0]}:3080"
+  if ! grep -q "$cur" <<<"$TRUST"; then
+    echo "  ⚠️ 当前地址 $cur 不在 trusted-host 里 ⇒ PC 会收到 403"
+    echo "     ↳ 修：plist 已补该地址，需**重启 dsh web** 生效：bash ~/Code/argent-dsh/scripts/dsh-restart.sh"
+    rc=1
+  fi
+fi
+
+echo "── ④ PC 侧应使用的地址"
+if [ "${#OVERLAY[@]}" -gt 0 ]; then
+  echo "  http://${OVERLAY[0]}:3080/     （若 EasyTier 已按 -i 固定地址，则用固定那个）"
+fi
+echo
+[ "$rc" -eq 0 ] && echo "  ✅ 远程访问链路正常" || echo "  ❌ 上面标 ❌/⚠️ 的层需要处理"
+exit $rc

package/engine/scripts/dsh-restart.sh

@@ -0,0 +1,179 @@
+#!/bin/bash
+# dsh-restart.sh — 可靠重启 dsh web 服务（处理 launchd 各种状态）
+#
+# 背景：bootout 后立即 bootstrap 偶发 'Bootstrap failed: 5: Input/output error'
+# （macOS launchd 状态刷新问题）——本脚本自动处理：已加载→kickstart；未加载→
+# enable + bootstrap（带重试）；最后验证 3080 监听。
+#
+# 用法：bash ~/Code/argent-dsh/scripts/dsh-restart.sh
+#       bash ~/Code/argent-dsh/scripts/dsh-restart.sh --check   # **只读**：只报日志落点+启动行（token 脱敏），不重启
+set -u
+
+LABEL="com.whyshu.dsh-web"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+UID_NUM=$(id -u)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ── dsh-web 启动日志的落点：**跟随"日志被挪到哪儿了"**，不再硬编码 /tmp ──────────────
+# 事故（2026-10-08）：这里曾写死 `/tmp/dsh-web.log` ⇒ 运维按 wake-auth 的建议把日志挪到
+# `~/.dsh/logs/`（客户机）后，本脚本仍去读旧路径 ⇒ **打印上一次启动的陈旧 token**（看着成功、其实误导），
+# 且"3080 未监听"分支把人指向一个已经不存在的文件。
+# 顺序与 `scripts/lib/wake-auth.mjs#logPaths()` 的**路径**部分保持一致（那边是唤醒端的鉴权来源链）：
+#   $DSH_WEB_LOG → plist 的 StandardOutPath/StandardErrorPath → $DSH_HOME/dsh-web.log
+#   → ~/Library/Logs/dsh-web.log → /tmp/dsh-web.log（历史兜底，最后）
+# 为什么本脚本**不**直接 import `wake-auth.mjs`（取"最小且无循环依赖"）：
+#   ① 本脚本的价值恰恰在"服务/环境已经坏了"时仍能跑 ⇒ 不引入 node 运行时依赖；
+#   ② `wake-auth.mjs` 的失败文案会指引读者来跑**本脚本**（authFailureText 里点名 dsh-restart.sh）
+#      ⇒ 本脚本反过来 import 它即成循环；
+#   ③ wake-auth 的**主源**是 credentials 里的签名 cookie（唤醒端的凭据面）——重启脚本不需要、
+#      也不该读凭据，更不该对刚起来的服务做网络探测；
+#   ④ 本脚本只需要"日志落点"这一件事，读 plist 就够（`plutil` 本就是本脚本已有的依赖，见下 WANT_TRUST）。
+dsh_web_log_path() {
+  if [ -n "${DSH_WEB_LOG:-}" ]; then printf '%s' "$DSH_WEB_LOG"; return; fi
+  local p=""
+  p=$(plutil -p "$PLIST" 2>/dev/null | sed -n 's/^[[:space:]]*"StandardOutPath"[[:space:]]*=>[[:space:]]*"\(.*\)"$/\1/p' | head -1)
+  case "$p" in /*) printf '%s' "$p"; return;; esac
+  p=$(plutil -p "$PLIST" 2>/dev/null | sed -n 's/^[[:space:]]*"StandardErrorPath"[[:space:]]*=>[[:space:]]*"\(.*\)"$/\1/p' | head -1)
+  case "$p" in /*) printf '%s' "$p"; return;; esac
+  p="${DSH_HOME:-$HOME/.dsh}/dsh-web.log"
+  if [ -f "$p" ]; then printf '%s' "$p"; return; fi
+  p="$HOME/Library/Logs/dsh-web.log"
+  if [ -f "$p" ]; then printf '%s' "$p"; return; fi
+  printf '%s' "/tmp/dsh-web.log"
+}
+
+# token 脱敏：**沿用既有约定**（`scripts/lib/settings-panels.mjs:104`：留首尾各 3 位，中间 ****）。
+mask_token() {
+  local s="$1"
+  if [ "${#s}" -le 8 ]; then printf '%s' '******'; else printf '%s' "${s:0:3}****${s: -3}"; fi
+}
+
+# 只读报告：日志落点 + 启动行（token **脱敏**）；`--check` 与"重启成功后"共用这一份实现（避免两处口径漂移）。
+report_dsh_web_log() {
+  local LOG TOK URL_LINE
+  LOG="$(dsh_web_log_path)"
+  echo "   启动日志: $LOG"
+  # ⛔ **绝不打印 token 明文**（2026-10-08）：token 是每进程随机的，且这行取自日志的**最后一次**启动记录
+  # —— 打印它既无必要（有 cookie 就不需要 token），又会因读到旧记录而**误导**（本脚本的前身就这么错过）。
+  # 这里只确认"日志里有启动行"并按既有约定**脱敏**展示；完整 URL 由操作者按提示自己取。
+  if [ -f "$LOG" ]; then
+    URL_LINE=$(grep "dsh web: http" "$LOG" 2>/dev/null | tail -1 | sed 's/^.*dsh web: //')
+    if [ -n "$URL_LINE" ]; then
+      TOK="${URL_LINE##*token=}"
+      if [ "$TOK" != "$URL_LINE" ]; then
+        echo "   带 token 的 URL（**已脱敏**，仅供确认启动行存在）: ${URL_LINE%token=*}token=$(mask_token "$TOK")"
+      else
+        echo "   启动 URL（该行不含 token=）: $URL_LINE"
+      fi
+      echo "   完整 URL 请自行取（本脚本不打印明文）：grep 'dsh web: http' \"$LOG\" | tail -1"
+    else
+      echo "   ⚠️ 取不到启动 URL：日志 $LOG 里没有 'dsh web: http' 行（刚起来还没写？稍等再看一次）"
+      echo "      grep 'dsh web: http' \"$LOG\" | tail -1"
+    fi
+  else
+    echo "   ⚠️ 取不到启动 URL：日志文件不存在（${LOG}）"
+    echo "      ⇒ 若日志已被挪走，核 plist 的落点声明（本脚本就是按它找的）："
+    echo "         plutil -p \"$PLIST\" | grep -i StandardOutPath"
+    echo "      ⇒ token 的其它来源（不依赖日志）见 scripts/lib/wake-auth.mjs 的来源优先级表"
+  fi
+}
+
+if [ ! -f "$PLIST" ]; then
+  echo "❌ plist 不存在: $PLIST"
+  exit 1
+fi
+
+# ── 只读模式（`--check`）：只报告日志落点与启动行（token 脱敏），**不碰 launchd、不重启** ──
+# 用途：① 运维确认"日志被挪到哪儿了"（本脚本按 plist 解析，不再硬编码 /tmp）；
+#       ② 双端核对 / 回归测试 —— 让"验证这条路径"不必以重启生产服务为代价。
+if [ "${1:-}" = "--check" ] || [ "${1:-}" = "--print-log-path" ]; then
+  if lsof -nP -iTCP:3080 -sTCP:LISTEN 2>/dev/null | grep -q node; then
+    echo "✅ dsh web 正在监听 3080（只读检查，未做任何改动）"
+  else
+    echo "⚠️ 3080 当前没有 node 监听（只读检查，未做任何改动）"
+  fi
+  report_dsh_web_log
+  exit 0
+fi
+
+# 先记下 plist 里的权威参数（重启后要核对进程是否真的采用了）
+WANT_TRUST=$(plutil -p "$PLIST" 2>/dev/null | grep -oE '[0-9]{1,3}(\.[0-9]{1,3}){3}:[0-9]+' | sort -u | tr '\n' ' ')
+
+if launchctl list | grep -q "$LABEL"; then
+  echo "→ 完整重载（bootout → bootstrap）：只有这样才能让**磁盘上改过的 plist 生效**"
+  launchctl bootout "gui/$UID_NUM/$LABEL" 2>/dev/null || true
+  sleep 3
+fi
+launchctl enable "gui/$UID_NUM/$LABEL" 2>/dev/null || true
+if ! launchctl bootstrap "gui/$UID_NUM" "$PLIST"; then
+  echo "⚠️ bootstrap 失败（launchd 偶发 IO error），5s 后重试…"
+  sleep 5
+  launchctl bootstrap "gui/$UID_NUM" "$PLIST" || {
+    echo "❌ 两次 bootstrap 都失败——plist 语法？plutil -lint \"$PLIST\""
+    exit 1
+  }
+fi
+
+echo "→ 等待服务就绪（10s）…"
+sleep 10
+if lsof -nP -iTCP:3080 -sTCP:LISTEN 2>/dev/null | grep -q node; then
+  echo "✅ dsh web 已就绪"
+  echo "   访问: http://127.0.0.1:3080/（已有 cookie 的浏览器直接用，无需 token）"
+  report_dsh_web_log
+  # 运行参数核对：进程实际带的 --trusted-host 必须覆盖 plist 里声明的全部地址，
+  # 否则"重启了但没生效"（2026-09-22 实测：kickstart 沿用缓存旧定义 ⇒ 新地址仍 403）
+  #
+  # 2026-10-01 修**假警报**（用户实测：明明 3 个进程都带参数，却报"未采用"且 `进程=` 是空的）：
+  #   dsh web 是**父子两段**进程 —— 启动器 `dsh-web-launch.mjs web …` + 真正采用参数的
+  #   `…/@deepseek-ai/dsh/lib/bin.js web …`；而 launchd 起的 argv[0] 是**绝对路径**
+  #   （`/opt/homebrew/bin/node`）。旧写法 `grep -E "^node .*/dsh web" | head -1` 两处都不占：
+  #   ① `^node ` 匹配不到绝对路径；② 只看第一个匹配 ⇒ RUN_ARGS 恒空 ⇒ **每个地址都被误报**。
+  # 现判据 = **全部相关进程的 trusted-host 并集**（唯一实现在 scripts/lib/dsh-web-probe.mjs，
+  # dsh-remote-check.sh 复用同一模块；收集/比对/文案都只有一份）。
+  # 退出码语义：0 通过 ｜ 1 **真的缺失**（唯一该失败的情形）｜ 2 没找到进程 ｜ 3 探测失败。
+  # 2/3 明确报"没核对上"，绝不打印空白的"进程="让人误解成"没采用"。
+  PROBE="$SCRIPT_DIR/lib/dsh-web-probe.mjs"
+  if [ -f "$PROBE" ]; then
+    node "$PROBE" --want "$WANT_TRUST"
+    PROBE_RC=$?
+    case "$PROBE_RC" in
+      0) : ;;
+      1) exit 1 ;;
+      *) echo "   ↳ 服务本身已就绪（3080 在监听），但**没能核对**运行参数；如需人工复核：bash $SCRIPT_DIR/dsh-remote-check.sh" ;;
+    esac
+  else
+    echo "   ⚠️ 探测模块缺失（${PROBE}）⇒ 跳过 trusted-host 核对"
+    echo "      （刻意不退回旧的单进程判据：它会把父子两段进程误报成「未采用」）"
+  fi
+
+  # ── 计费/provider 诊断摘要（**只读**；重启成功后打印一次）─────────────────────────
+  # 2026-10-01 处置（任务「计费模式自愈死代码」）：
+  #   · 旧块（`check-billing-mode.sh --fix`）挂在两个 `exit` **之后** ⇒ 永不可达（死代码）；
+  #   · 更要紧的是它的**意图**：`--fix` 历史上会改写 `llm-deepseek.baseURL` / 重写
+  #     `~/.dsh/settings.yaml` —— 前者 = 劫持官方直连 provider（provider id 仍叫 deepseek-official，
+  #     实际指向问述），后者是官方 schema 的自有文件（被"自身 schema 重写"会丢掉未知的 `llm-*` 段，
+  #     实测文件只剩 1 字节 ⇒ 模式静默退回直连、积分不再扣）。**用户明确禁止**这两件事
+  #     （见 ~/.dsh/AGENTS.md「LLM provider 设计」）。所以这里**只报告、绝不写文件**：
+  #     跑一次只读报告；异常时**打印建议命令**，由用户自己决定要不要执行。
+  BILLING="$SCRIPT_DIR/check-billing-mode.sh"
+  if [ -x "$BILLING" ]; then
+    echo
+    echo "── 计费/provider 诊断（只读；本脚本不会替你做任何修改）──"
+    if ! bash "$BILLING"; then
+      echo "   ↳ provider 装配异常（组合**声明了**的 provider 没装上 exit=1 / 无法判定 exit=2）。建议命令（**需你手动执行**）："
+      echo "     bash $SCRIPT_DIR/provider-select.sh status      # 看当前默认 provider"
+      echo "     bash $SCRIPT_DIR/provider-select.sh whyshu      # 或 deepseek；改完需重启 dsh"
+      echo "     ⛔ 不要用 check-billing-mode.sh --fix（已熔断，exit 3）：改 provider 请走模型选择器"
+    fi
+  fi
+  exit 0
+else
+  LOG="$(dsh_web_log_path)"
+  echo "❌ 3080 未监听——检查日志：tail -40 $LOG"
+  echo "   （日志落点按 plist 的 StandardOutPath 解析；若与预期不符：plutil -p \"$PLIST\" | grep -i StandardOutPath）"
+  exit 1
+fi
+
+# ⚠️ 本行之后**不要**再放任何代码：上面两个分支都以 exit 结尾 ⇒ 写在这里的代码**永不可达**。
+# （2026-09-29 的「计费模式自愈」块就是这么变成死代码的：它挂在 exit 之后，从未执行过一次；
+#   而死代码比"没有这段代码"更危险 —— 读代码的人以为它在生效，出问题时排错方向全错。）

package/engine/scripts/dsh-restore.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# dsh-restore —— 默认入口的**人工还原**（P5，2026-09-29）：不依赖 dsh，纯 shell + node。
+#
+# 用途（救援面也挂了时的最后一道保险）：
+#   bash scripts/dsh-restore.sh --list                # 看当前指针、审计、可用树
+#   bash scripts/dsh-restore.sh --to <树目录>          # 把默认入口指到某棵树（并重载服务）
+#   bash scripts/dsh-restore.sh --to <树目录> --no-reload
+#   bash scripts/dsh-restore.sh --rollback            # 回退到审计里的上一棵 known-good 树
+#
+# 为什么单独有它：`dsh-web-launch.mjs` 的熔断也走同一套指针与审计 —— 两边共用
+# `scripts/lib/scope-pointer.mjs`（唯一真源），所以人工还原和自动熔断不会各写一套。
+#
+# ⛔ 重载服务 = 重启 dsh web（会中断当前会话）。除本脚本的人工调用与熔断那一次自动重启外，
+#    任何自动化都不得重启服务（AGENTS.md「严禁自杀式重启」）。
+set -uo pipefail
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+LABEL="${DSH_RESTORE_LABEL:-com.whyshu.dsh-web}"
+POINTER="$DSH_HOME/argent/base/current-scope"
+NODE="${ARGENT_NODE:-$(command -v node || true)}"
+
+[ -n "$NODE" ] || { echo "✗ 找不到 node（可用 ARGENT_NODE 指定）" >&2; exit 2; }
+
+MODE=""; TARGET=""; RELOAD=1
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --list) MODE=list; shift;;
+    --rollback) MODE=rollback; shift;;
+    --to) MODE=to; TARGET="${2:-}"; shift 2;;
+    --no-reload) RELOAD=0; shift;;
+    -h|--help) sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0;;
+    *) echo "未知参数：$1（--help）" >&2; exit 2;;
+  esac
+done
+
+pointer_of() { "$NODE" -e '
+import { readPointer } from "./scripts/lib/scope-pointer.mjs"
+process.stdout.write(readPointer() || "")
+' ; }
+
+if [ "$MODE" = list ] || [ -z "$MODE" ]; then
+  echo "指针文件：$POINTER"
+  echo "当前指向：$("$NODE" -e '
+import { readPointer } from "./scripts/lib/scope-pointer.mjs"
+console.log(readPointer() || "(未设置)")
+' 2>/dev/null)"
+  echo
+  echo "审计（最近 10 条切换）："
+  "$NODE" -e '
+import { readHistory } from "./scripts/lib/scope-pointer.mjs"
+const h = readHistory(process.env, 10)
+if (!h.length) console.log("  （无）")
+for (const e of h) console.log(`  ${e.at || "?"}  → ${e.scopeDir}${e.reason ? "（" + e.reason + "）" : ""}`)
+' 2>/dev/null | sed 's/^/  /'
+  echo
+  echo "候选树（存在且像 dsh 安装）："
+  for c in /opt/homebrew/lib/node_modules/@deepseek-ai "$HOME/node/lib/node_modules/@deepseek-ai" \
+           "$HOME"/dsh-*/lib/node_modules/@deepseek-ai; do
+    [ -d "$c" ] || continue
+    if [ -f "$c/dsh/lib/bin.js" ]; then echo "  ✅ $c"; else echo "  ⚠️  ${c}（缺 dsh/lib/bin.js）"; fi
+  done
+  echo
+  echo "整树备份（⚠️ 需先搬到 node_modules/ 下才能当默认入口）："
+  for b in "$HOME"/.dsh/argent/backup/*/scope; do
+    [ -d "$b" ] || continue
+    if "$NODE" -e 'import("./scripts/lib/scope-pointer.mjs").then(m => process.exit(m.looksLikeScope(process.argv[1]) ? 0 : 1))' "$b" 2>/dev/null; then
+      echo "  ✅ ${b}（布局可用）"
+    else
+      echo "  ⚠️  ${b}（有 dsh 入口但布局不可直接运行 ⇒ 搬到 <root>/lib/node_modules/@deepseek-ai）"
+    fi
+  done
+  [ -n "$MODE" ] && exit 0
+fi
+
+if [ "$MODE" = rollback ]; then
+  TARGET="$("$NODE" -e '
+import { previousScope } from "./scripts/lib/scope-pointer.mjs"
+console.log(previousScope(process.env) || "")
+')"
+  [ -n "$TARGET" ] || { echo "✗ 审计里找不到可回退的树（用 --to 显式指定）" >&2; exit 2; }
+  echo "回退目标（来自审计）：$TARGET"
+fi
+
+if [ "$MODE" = to ] || [ "$MODE" = rollback ]; then
+  [ -n "$TARGET" ] || { echo "✗ --to 需要一个树目录" >&2; exit 2; }
+  [ -f "$TARGET/dsh/lib/bin.js" ] || { echo "✗ 目标不是 dsh 安装树（缺 dsh/lib/bin.js）：$TARGET" >&2; exit 2; }
+  "$NODE" -e '
+import { writePointer, readPointer } from "./scripts/lib/scope-pointer.mjs"
+const target = process.argv[1]
+const before = readPointer()
+writePointer(target, { reason: "manual restore (dsh-restore.sh)", previous: before })
+console.log(`✅ 指针：${before || "(未设置)"} → ${target}`)
+' "$TARGET" || exit 1
+
+  # 人工还原 = "人已介入" ⇒ 顺手解除熔断标记（否则下次启动会被启动器拒绝）
+  if "$NODE" --input-type=module -e 'import { clearFused } from "./scripts/lib/scope-pointer.mjs"; process.exit(clearFused() ? 0 : 1)' 2>/dev/null; then
+    echo "  ✅ 已解除熔断标记（如曾有）"
+  fi
+
+  if [ "$RELOAD" = 1 ]; then
+    echo "重载 LaunchAgent：${LABEL}（这会重启 dsh web 服务）"
+    launchctl kickstart -k "gui/$(id -u)/$LABEL" 2>/dev/null \
+      || { echo "  ⚠️ kickstart 失败，尝试 bootout+bootstrap"; \
+           launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null; \
+           launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/$LABEL.plist"; }
+    sleep 3
+    if pgrep -f "dsh web" >/dev/null; then echo "  ✅ 服务进程在跑"; else echo "  ✗ 服务未起来 —— 看 /tmp/dsh-web.log 与 --list 的候选树"; fi
+  else
+    echo "（--no-reload：未重启服务；下次服务重启时生效）"
+  fi
+fi