@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/drill-clean-machine.sh

@@ -0,0 +1,315 @@
+#!/usr/bin/env bash
+# drill-clean-machine.sh —— **干净机器一条命令**的隔离演练（D1/D2 的可复现证据；2026-10-05）
+#
+# 用途：把 `scripts/install-one-shot.mjs` 放进一个**与真实机器无关的夹具**里真跑一遍，
+#       并按"真实目录零变化"哨兵自证**没有**碰过 `~/.dsh/**`、`~/.argent-dsh/**`。
+#
+# 隔离构造（三条，缺一不可）：
+#   ① `HOME` 指向 `$FIX/home`（全新空目录）⇒ `~/.dsh`、`~/.argent-dsh`、`~/.pnpm` 全落在夹具里；
+#   ② 子进程一律 `env -i`（**极简环境**：只给 HOME/PATH，清掉 DSH_HOME/ARGENT_DATA_DIR/密钥等实例级开关）；
+#   ③ PATH 只含**夹具 bin**（node/git/dsh 的软链）+ 系统目录 ⇒ 包管理器**不在** PATH 上
+#      （演练刻意不跑 pnpm —— 装配走安装器的 `--from-packs` 离线面）。
+#   能力来源 = **离线包目录**（`capability_pack.py --build` 现场构建），不依赖 `~/.argent-dsh` 克隆。
+#
+# 演练内容（六跑）：
+#   A. dry-run             ⇒ 退出码 0，且夹具**零写入**（dry-run 语义）
+#   B. --apply（无许可）   ⇒ 退出码 0，装配 + 技能同步真跑；许可段 skipped（"未装许可"不算失败）
+#   C. 重跑 B              ⇒ 退出码 0，逐段结论与 B 一致（**幂等**）
+#   D. --only license --apply（夹具许可）⇒ 退出码 0，许可真落到夹具数据目录
+#   F. 在线装配面（本地镜像克隆 file://<仓库>、零网络、无包管理器 ⇒ 安装器既有"直拷"回退）
+#   E. 多包一起装（full,invoice）⇒ **预期退出码 0**（2026-10-09 起）：注册表投影在计划阶段与落盘阶段
+#      用**同一个**判据豁免（`isRegistryProjection()`），落盘后盘上注册表 = 两份投影的并集。
+#   收尾：哨兵比对（真实目录零变化）+ 夹具树/清单快照
+#
+# 用法：
+#   bash scripts/drill-clean-machine.sh [--keep] [--dir <夹具根>] [--caps <单个能力>] [--timeout <秒>]
+#   `--caps` 可给**多个**（逗号分隔）：同批发布的包本就该一起装（跨包共用引擎文件必须同版）；
+#   E 步仍单独用全新树演示一次"两个包一起装"的完整判据（退出码 + 装机清单 + 注册表并集）。
+# 退出码：0 四跑与哨兵均符合预期 ｜ 1 有不符合预期项（逐条点名）｜ 2 用法/环境错误
+set -uo pipefail
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
+KEEP=0
+FIX=""
+CAPS="full"
+GUARD_CAPS="full,invoice"   # E 步：多包一起装（回归判据，见文档 §E）
+TIMEOUT=1800
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --keep) KEEP=1; shift ;;
+    --dir) FIX="$2"; shift 2 ;;
+    --caps) CAPS="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    -h|--help) sed -n '2,26p' "$0"; exit 0 ;;
+    *) echo "✗ 未知参数：$1" >&2; exit 2 ;;
+  esac
+done
+case "$CAPS" in
+  *,*) : ;;   # 多能力（逗号分隔）自 2026-10-09 起支持：一起装是**推荐**路径
+  '') echo "✗ --caps 不能为空" >&2; exit 2 ;;
+esac
+[ -n "$FIX" ] || FIX="$(mktemp -d "${TMPDIR:-/tmp}/argent-drill.XXXXXX")"
+FIX="$(cd "$FIX" && pwd -P)"
+mkdir -p "$FIX/bin" "$FIX/home" "$FIX/packs"
+
+ONE="$REPO/scripts/install-one-shot.mjs"
+[ -f "$ONE" ] || { echo "✗ 缺 $ONE" >&2; exit 2; }
+
+FAIL=0
+note() { printf '%s\n' "$*"; }
+ok()   { printf '  ✅ %s\n' "$*"; }
+bad()  { printf '  ✗ %s\n' "$*"; FAIL=1; }
+warn() { printf '  ⚠️  %s\n' "$*"; }
+hdr()  { printf '\n── %s\n' "$*"; }
+
+# ── 夹具 bin：只放 node / git / dsh（**不放** pnpm/npm/corepack）──────────────
+for t in node git dsh; do
+  p="$(command -v "$t" 2>/dev/null || true)"
+  [ -n "$p" ] && ln -sf "$p" "$FIX/bin/$t"
+done
+MINPATH="$FIX/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+RUN=(env -i "HOME=$FIX/home" "PATH=$MINPATH" "TMPDIR=$FIX/tmp" \
+     "ARGENT_REPO_URL=file://$REPO"      # 在线面用**本地镜像**克隆（不是 whyshu 私服）：零网络
+     "ARGENT_SKIP_MODEL_PROBE=1")        # 联网凭证探针在夹具里没有 Key ⇒ 用安装器既有逃逸阀（它会打警告）
+mkdir -p "$FIX/tmp"
+
+note "═══════════════════════════════════════════════════"
+note "  干净机器演练夹具：$FIX"
+note "  HOME=$FIX/home（隔离）｜ PATH=$MINPATH"
+note "  node=$(node --version 2>/dev/null)｜git=$(git --version 2>/dev/null | awk '{print $3}')｜dsh=$(command -v dsh || echo 无)"
+note "  ⛔ 包管理器不在 PATH（演练刻意不跑 pnpm）"
+note "═══════════════════════════════════════════════════"
+
+# ── 哨兵（真实目录）────────────────────────────────────────────────────────
+# 立场：演练**只读**真实目录。哨兵盯"本次演练最可能误写的面"，逐条 sha 比对。
+# 刻意**不**盯会话/日志（常驻 dsh web 在写，盘它必然恒红，属噪声不属判据）。
+# 真实数据目录：**只调内核的唯一判据**（`core/lib/argent-datadir.mjs#resolveDataDir()`），
+# 本脚本里**不写第二份**（`ARGENT_DATA_DIR`/`DSH_HOME` 一律清掉 ⇒ 解析出的就是"本机默认位置"）。
+# 为什么哨兵也必须这样：门禁 scripts/tests/argent-datadir-parity.test.mjs【4】对 .sh 里的
+# `$HOME/.dsh/argent` 式硬编码判据**判红**（2026-10-01 桌面端事故形态）。
+# 用 `env -i` 清掉整份环境（**不点名任何**实例级开关变量 —— 点名它本身就是"第二份三级链"，
+# 会被同一条门禁的 `ARGENT_DATA_DIR` 规则判红）。
+REAL_DATA_DIR="$(env -i "HOME=$HOME" "PATH=$PATH" node -e \
+  'import(process.argv[1]).then(m=>process.stdout.write(m.resolveDataDir().dir))' \
+  "$REPO/core/lib/argent-datadir.mjs" 2>/dev/null)"
+[ -n "$REAL_DATA_DIR" ] || { echo "✗ 解析不出真实数据目录（缺 core/lib/argent-datadir.mjs？）—— 哨兵无法自证，演练中止" >&2; exit 2; }
+
+sentinel() {
+  local out="$1"
+  {
+    echo "# $(date -u +%FT%TZ) 真实目录哨兵（演练前后必须逐字节一致）｜数据目录=${REAL_DATA_DIR}"
+    for f in "$REAL_DATA_DIR/install.json" "$REAL_DATA_DIR/license.json" \
+             "$REAL_DATA_DIR/license.secret" "$REAL_DATA_DIR/skin.json" \
+             "$REAL_DATA_DIR/gateway.json" "$REAL_DATA_DIR/roles.json" \
+             "$HOME/.dsh/settings.yaml" "$HOME/.dsh/.credentials.yaml" \
+             "$HOME/.dsh/profiles/web/package.json" "$HOME/.dsh/profiles/web/cordis.patch.yml"; do
+      if [ -f "$f" ]; then printf '%s  %s\n' "$(shasum -a 256 "$f" | cut -c1-16)" "${f/#$HOME/~}"; else printf 'MISSING           %s\n' "${f/#$HOME/~}"; fi
+    done
+    for d in "$HOME/.dsh/skills" "$HOME/.dsh/.agent-presets"; do
+      if [ -d "$d" ]; then
+        printf 'DIR %s files=%s hash=%s\n' "${d/#$HOME/~}" \
+          "$(find "$d" -type f | wc -l | tr -d ' ')" \
+          "$(find "$d" -type f | LC_ALL=C sort | xargs shasum -a 256 2>/dev/null | shasum -a 256 | cut -c1-16)"
+      else printf 'DIR-MISSING       %s\n' "${d/#$HOME/~}"; fi
+    done
+    if [ -d "$HOME/.argent-dsh" ]; then
+      printf 'ARGENT-DSH head=%s dirty=%s files=%s\n' \
+        "$(git -C "$HOME/.argent-dsh" rev-parse --short HEAD 2>/dev/null || echo 非git)" \
+        "$(git -C "$HOME/.argent-dsh" status --porcelain 2>/dev/null | wc -l | tr -d ' ')" \
+        "$(find "$HOME/.argent-dsh" -type f -not -path '*/.git/*' | wc -l | tr -d ' ')"
+    else printf 'ARGENT-DSH MISSING\n'; fi
+  } > "$out" 2>/dev/null
+}
+sentinel "$FIX/sentinel-before.txt"
+node "$REPO/scripts/check-test-env-safety.mjs" --snapshot "$FIX/sentinel-datadir-before.json" >/dev/null 2>&1 || true
+note ""
+note "哨兵已拍：$FIX/sentinel-before.txt（+ 真实数据目录三层快照）"
+
+# ── 离线包（能力来源；不依赖克隆）───────────────────────────────────────────
+# 演练主线可多包（`--caps a,b`）：自 2026-10-09 起"一起装"是支持路径（E 步另有显式判据）。
+BUILD_CAPS="$CAPS,$GUARD_CAPS"   # 去重后逐个构建（重复目录会撞 --force 守卫）
+hdr "构建离线能力包（主线 --caps ${CAPS}；E 步多包 ${GUARD_CAPS}）"
+PACKARGS=""
+GUARDPACKARGS=""
+OLDIFS="$IFS"; IFS=','
+BUILT=","
+for cap in $BUILD_CAPS; do
+  IFS="$OLDIFS"
+  case "$BUILT" in *",$cap,"*) IFS=','; continue ;; esac
+  if [ -n "$cap" ]; then
+    if python3 "$REPO/scripts/capability_pack.py" --build "$cap" --out-dir "$FIX/packs/$cap" >"$FIX/packs/$cap.build.log" 2>&1; then
+      ok "$cap → $FIX/packs/${cap}（$(tail -1 "$FIX/packs/$cap.build.log" | sed 's/^ *//')）"
+      BUILT="$BUILT$cap,"
+    else
+      bad "$cap 打包失败，见 $FIX/packs/$cap.build.log"; tail -5 "$FIX/packs/$cap.build.log"
+    fi
+  fi
+  IFS=','
+done
+IFS="$OLDIFS"
+IFS=','
+for cap in $CAPS; do
+  IFS="$OLDIFS"; [ -n "$cap" ] || { IFS=','; continue; }
+  if [ -z "$PACKARGS" ]; then PACKARGS="$FIX/packs/$cap"; else PACKARGS="$PACKARGS,$FIX/packs/$cap"; fi
+  IFS=','
+done
+for cap in $GUARD_CAPS; do
+  IFS="$OLDIFS"; [ -n "$cap" ] || { IFS=','; continue; }
+  if [ -z "$GUARDPACKARGS" ]; then GUARDPACKARGS="$FIX/packs/$cap"; else GUARDPACKARGS="$GUARDPACKARGS,$FIX/packs/$cap"; fi
+  IFS=','
+done
+IFS="$OLDIFS"
+[ "$FAIL" = 0 ] || { echo "✗ 打包失败，演练中止"; exit 1; }
+
+one() {  # one <标签> <期望退出码> <参数…>
+  local label="$1" want="$2"; shift 2
+  local t0 t1
+  t0=$(date +%s)
+  "${RUN[@]}" node "$ONE" "$@" >"$FIX/run-$label.out" 2>&1
+  local rc=$?
+  t1=$(date +%s)
+  if [ "$rc" = "$want" ]; then ok "$label 退出码 ${rc}（期望 ${want}，耗时 $((t1-t0))s）"
+  else bad "$label 退出码 ${rc}（期望 ${want}）—— 见 $FIX/run-$label.out"; tail -25 "$FIX/run-$label.out"; fi
+  return 0
+}
+
+BASE=(--tree "$FIX/home/.argent-dsh" --dsh-home "$FIX/home/.dsh" --from-packs "$PACKARGS" --timeout "$TIMEOUT")
+
+# ── A. dry-run ─────────────────────────────────────────────────────────────
+hdr "A. dry-run（默认；必须零写入）"
+one A 0 "${BASE[@]}" --report "$FIX/report-A.json"
+if [ -e "$FIX/home/.dsh" ] || [ -e "$FIX/home/.argent-dsh" ]; then
+  bad "dry-run 竟然写了夹具（$FIX/home 下出现 .dsh/.argent-dsh）"
+else ok "dry-run 零写入（夹具 home 下没有 .dsh / .argent-dsh）"; fi
+
+# ── B. --apply（无许可）────────────────────────────────────────────────────
+hdr "B. --apply（无 --license-file ⇒ 许可段 skipped，不算失败）"
+one B 0 "${BASE[@]}" --apply --report "$FIX/report-B.json"
+[ -f "$FIX/home/.dsh/argent/install.json" ] && ok "装机清单在位：$FIX/home/.dsh/argent/install.json" \
+  || bad "装机清单不在位（--from-packs 装配判据）"
+[ -d "$FIX/home/.dsh/skills" ] && ok "技能已同步到夹具：$FIX/home/.dsh/skills（$(find "$FIX/home/.dsh/skills" -maxdepth 1 -mindepth 1 | wc -l | tr -d ' ') 项）" \
+  || bad "技能目录没生成（技能同步段判据）"
+TREE_HASH_B="$( { [ -d "$FIX/home/.argent-dsh" ] && find "$FIX/home/.argent-dsh" -type f; }  | LC_ALL=C sort | xargs shasum -a 256 2>/dev/null | shasum -a 256 | cut -c1-16)"
+
+# ── C. 重跑（幂等）─────────────────────────────────────────────────────────
+hdr "C. 重跑 --apply（幂等：逐段结论必须与 B 一致）"
+one C 0 "${BASE[@]}" --apply --report "$FIX/report-C.json"
+python3 - "$FIX/report-B.json" "$FIX/report-C.json" <<'PY' && ok "B/C 逐段状态一致（幂等）" || bad "B/C 逐段状态不一致（幂等被破）"
+import json,sys
+b=json.load(open(sys.argv[1])); c=json.load(open(sys.argv[2]))
+sb={s['id']:s['status'] for s in b['steps']}; sc={s['id']:s['status'] for s in c['steps']}
+if sb==sc: print('   B/C 状态：',sb)
+else:
+    print('   B:',sb); print('   C:',sc); sys.exit(1)
+PY
+TREE_HASH_C="$( { [ -d "$FIX/home/.argent-dsh" ] && find "$FIX/home/.argent-dsh" -type f; }  | LC_ALL=C sort | xargs shasum -a 256 2>/dev/null | shasum -a 256 | cut -c1-16)"
+[ "$TREE_HASH_B" = "$TREE_HASH_C" ] && ok "重跑后目标树逐字节不变（${TREE_HASH_C}）" \
+  || warn "重跑后目标树有变化（$TREE_HASH_B → ${TREE_HASH_C}）—— 逐条比对是 churn 还是缺陷"
+
+# ── D. 只跑许可段（夹具许可）───────────────────────────────────────────────
+hdr "D. --only license --apply（夹具密钥自签的许可；验的是「许可段能不能真装」）"
+SECRET="$FIX/fixture-license-secret"
+printf '%s' 'drill-fixture-secret-not-a-real-key' > "$SECRET"; chmod 600 "$SECRET"
+if "${RUN[@]}" node "$REPO/scripts/self-sign-license.mjs" --user drill-fixture --secret-file "$SECRET" \
+      --out "$FIX/fixture-license.json" --sign-v2 --device-from-local --cap full --seats 1 --days 30 \
+      >"$FIX/selfsign.out" 2>&1; then
+  ok "夹具许可已自签：$FIX/fixture-license.json（夹具密钥，⛔ 不是任何真实环境的密钥）"
+else bad "夹具许可自签失败，见 $FIX/selfsign.out"; tail -5 "$FIX/selfsign.out"; fi
+one D 0 --tree "$FIX/home/.argent-dsh" --dsh-home "$FIX/home/.dsh" \
+        --license-file "$FIX/fixture-license.json" --license-secret-file "$SECRET" \
+        --only license --apply --report "$FIX/report-D.json"
+[ -f "$FIX/home/.dsh/argent/license.json" ] && ok "许可已落到夹具数据目录（真实数据目录不动）" \
+  || bad "许可没落盘（许可段判据）"
+
+# ── F. 在线装配面（本地镜像克隆；零网络；无包管理器 ⇒ 走安装器既有"直拷"回退）──────
+hdr "F. 在线装配面（ARGENT_REPO_URL=file://<仓库>，零网络；无包管理器 ⇒ 直拷回退）"
+note "  ⛔ 全程不跑 pnpm：夹具 PATH 里没有 pnpm/npm/corepack ⇒ 安装器走它自己的回退分支。"
+note "  ⚠️ 该回退曾**不可达**（ensurePnpm 的 \`npm install -g pnpm\` 不在 try 里 ⇒ spawn npm ENOENT 未捕获崩），"
+note "     2026-10-05 已修（install-argent.mjs，见文档「失败与修法」）。"
+one F 0 --tree "$FIX/home-f/.argent-dsh" --dsh-home "$FIX/home-f/.dsh" --profile web \
+       --skip-provider --no-venv --apply --report "$FIX/report-F.json"
+[ -f "$FIX/home-f/.dsh/profiles/web/cordis.patch.yml" ] && ok "在线面产物：profile patch 在位（profiles/web/cordis.patch.yml）" \
+  || bad "在线面产物缺失：profiles/web/cordis.patch.yml"
+[ -d "$FIX/home-f/.dsh/.agent-presets" ] && ok "在线面产物：角色已落位（.agent-presets/$(ls "$FIX/home-f/.dsh/.agent-presets" | head -3 | tr '\n' ' ')）" \
+  || warn "在线面没落 preset（机制可能不是目录式；见 report-F.json）"
+[ -d "$FIX/home-f/.argent-dsh/plugins" ] && ok "在线面克隆到夹具树：$FIX/home-f/.argent-dsh（$(find "$FIX/home-f/.argent-dsh" -maxdepth 1 -mindepth 1 | wc -l | tr -d ' ') 个顶层条目）" \
+  || bad "在线面没克隆出树"
+
+# ── E. 多包一起装（2026-10-09 起**支持**，本步验证它真能装成）────────────────
+hdr "E. 多包一起装 --from-packs ${GUARD_CAPS}（期望退出码 0；注册表 = 两份投影的并集）"
+# ⚠ 必须用**全新**的树/home：B 已把主线能力铺好，复用会让安装器走"升级"路径，测不到"首次多包装"。
+one E 0 --tree "$FIX/home-e/.argent-dsh" --dsh-home "$FIX/home-e/.dsh" --profile web \
+       --from-packs "$GUARDPACKARGS" --apply --report "$FIX/report-E.json"
+# 判据三条：① 不再报"多包校验失败"；② 装机清单里两个能力都在且 integrity=verified；③ 盘上注册表是并集
+if grep -q "多包校验失败" "$FIX/run-E.out"; then
+  bad "多包一起装仍被拦下（见 $FIX/run-E.out）；拦下原因：$(grep -m1 '多包校验失败' "$FIX/run-E.out" | sed 's/^ *· *//')"
+else
+  ok "不再报「多包校验失败」（注册表投影已被判据豁免：计划阶段与落盘阶段同一个 isRegistryProjection()）"
+fi
+python3 - "$FIX/home-e/.dsh/argent/install.json" "$FIX/home-e/.argent-dsh/scripts/flow-requirements.json" <<'PY'
+import json, os, sys
+ij, reg = sys.argv[1], sys.argv[2]
+if not os.path.exists(ij):
+    print(f'  ✗ 装机清单不在位：{ij}'); sys.exit(1)
+doc = json.load(open(ij))
+caps = {c['id']: c.get('integrity') for c in doc.get('capabilities', [])}
+want = {'full', 'invoice'}
+if want <= set(caps):
+    print(f"  ✅ 装机清单两个能力都在（{', '.join(f'{k}={v}' for k, v in sorted(caps.items()))}）")
+else:
+    print(f"  ✗ 装机清单缺能力：{sorted(want - set(caps))}（实际 {sorted(caps)}）"); sys.exit(1)
+if all(caps[k] == 'verified' for k in want):
+    print('  ✅ 两个能力的 integrity 都是 verified')
+else:
+    print(f"  ✗ integrity 不是全 verified：{caps}"); sys.exit(1)
+if not os.path.exists(reg):
+    print(f'  ✗ 盘上注册表不在位：{reg}'); sys.exit(1)
+d = json.load(open(reg))
+c = sorted(d.get('capabilities') or {})
+if {'full', 'invoice'} <= set(c):
+    print(f"  ✅ 盘上注册表 = 两份投影的并集（capabilities：{', '.join(c)}）")
+else:
+    print(f"  ✗ 注册表缺能力条目（实际 {c}）—— 并集没写成"); sys.exit(1)
+PY
+[ "$?" = 0 ] || bad "E 步判据未过（装机清单 / 注册表并集，见上）"
+
+# ── 哨兵比对 ───────────────────────────────────────────────────────────────
+hdr "哨兵：真实目录零变化"
+sentinel "$FIX/sentinel-after.txt"
+tail -n +2 "$FIX/sentinel-before.txt" > "$FIX/sentinel-before.body"
+tail -n +2 "$FIX/sentinel-after.txt"  > "$FIX/sentinel-after.body"
+if diff -u "$FIX/sentinel-before.body" "$FIX/sentinel-after.body" > "$FIX/sentinel.diff" 2>&1; then
+  ok "真实目录哨兵逐字节一致（$FIX/sentinel-before.txt）"
+else
+  bad "真实目录哨兵有变化（本次演练本应零写入）："; cat "$FIX/sentinel.diff"
+fi
+if node "$REPO/scripts/check-test-env-safety.mjs" --verify "$FIX/sentinel-datadir-before.json" >"$FIX/sentinel-datadir.out" 2>&1; then
+  ok "真实数据目录三层判据（关键文件/新增文件/配置内容）无本次演练引起的改动"
+else
+  warn "真实数据目录有变化（可能是常驻服务的正常写入；逐条判断）："; tail -12 "$FIX/sentinel-datadir.out"
+fi
+
+# ── 汇总 ───────────────────────────────────────────────────────────────────
+hdr "汇总"
+python3 - "$FIX" <<'PY'
+import json,os,sys
+fix=sys.argv[1]
+for tag in ('A','B','C','D','E','F'):
+    p=os.path.join(fix,f'report-{tag}.json')
+    if not os.path.exists(p): print(f'  {tag}: （无报告）'); continue
+    d=json.load(open(p))
+    st={s['id']:s['status'] for s in d['steps']}
+    print(f"  {tag}: ok={d['ok']} mode={d['mode']} 耗时={d['elapsedSeconds']}s 逐段={st}")
+    print(f"      装配={d['segments']['install']}")
+    print(f"      技能={d['segments']['skills']}")
+    print(f"      许可={d['segments']['license']}")
+    print(f"      自检={d['selfCheck']}")
+PY
+note ""
+if [ "$FAIL" = 0 ]; then
+  note "✅ 演练全部符合预期（夹具：${FIX}）"
+else
+  note "✗ 演练有不符合预期项（夹具：${FIX}）—— 逐条见上"
+fi
+if [ "$KEEP" = 0 ] && [ "$FAIL" = 0 ]; then rm -rf "$FIX"; note "（夹具已清理；要留证据加 --keep）"; else note "（夹具保留：${FIX}）"; fi
+exit "$FAIL"

package/engine/scripts/dsh-api-client.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * dsh-api-client.mjs — dsh `/api` 最小客户端（2026-09-12 协议摸底产出）
+ *
+ * 用途：给「Argent 手机 APP」做底座验证——证明**外部客户端**能直接驱动 dsh：
+ * 会话列表、消息分页、流式订阅。全程**只读**（不 prompt / 不 create / 不 fork）。
+ *
+ * 协议（从 dsh 源码与 typert 描述符实测得出，详见 docs/dsh-api-protocol.md）
+ * ────────────────────────────────────────────────────────────────────────
+ * · 一元方法：`POST /api/<namespace>/<method>`，`Content-Type: application/json`
+ *     body: { type:"client-request", rpcId:"<任意串>", method:"<ns>/<method>", payload:{ args:{...} } }
+ *     resp: { type:"server-response", rpcId, result:{ ok:true, value } | { ok:false, error:{code,message,details} } }
+ *   · **args 的字段名按方法而定**：`session/list` → `_request`；`session/page` → `request`；
+ *     `session/modelCatalog` → 无参。写错会得到 `gateway/arguments-invalid` 并**告诉你缺哪个字段**。
+ * · 流式方法（`mode:'stream'`，如 `session/follow`、`session/control`）**不能**走上面的 POST
+ *   （会报 `gateway/signature-invalid`），要走 **WebSocket `/api/remote.mux`**：
+ *     发 { type:"open", streamId, endpoint, payload }
+ *     收 { type:"item", value } … 直到终止帧 / { type:"error", error }
+ * · 鉴权：浏览器用 `/?token=<43字符>` 换 `dsh-auth-*` cookie（30 天）；本脚本直接带 cookie。
+ * · 围栏：Host 必须是回环，或在 dsh 的 `--trusted-host` 名单里（否则 `/api` 一律 403）。
+ *
+ * 用法
+ * ────
+ *   node scripts/dsh-api-client.mjs list
+ *   node scripts/dsh-api-client.mjs page <sessionId> [throughSeq] [maxMessages]
+ *   node scripts/dsh-api-client.mjs follow <sessionId> [--seconds 8]
+ *   node scripts/dsh-api-client.mjs catalog
+ * 环境变量：DSH_BASE（默认 http://127.0.0.1:3080）、DSH_TOKEN（显式 token；缺省走**来源链** ——
+ *   见 `scripts/lib/wake-auth.mjs`：凭据签名 cookie → 日志落点链（DSH_WEB_LOG → plist → $DSH_HOME →
+ *   ~/Library/Logs → /tmp 兜底）。⛔ 不再只读写死的 `/tmp/dsh-web.log`（日志被系统清理/被运维挪走即失效）
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { acquireWakeAuth, authFailureText, authSources } from './lib/wake-auth.mjs'
+
+const BASE = process.env.DSH_BASE || 'http://127.0.0.1:3080'
+const WS_BASE = BASE.replace(/^http/, 'ws')
+
+let COOKIE = null
+/**
+ * 取鉴权 cookie：**来源链与唤醒端同一份**（`scripts/lib/wake-auth.mjs`，唯一真源）。
+ *
+ * ⑩a（2026-10-08）：本函数此前硬编码 `/tmp/dsh-web.log` —— 而该文件会被系统清理（进程还握着已
+ * unlink 的 inode）、运维也可能按 wake-auth 的建议把日志挪到稳定目录 ⇒ 客户端**静默失效**
+ * （Windows 上更是恒失效：根本没有 /tmp）。改走同一条链 + 先验后用（每个来源都真打一次服务）。
+ */
+async function authenticate() {
+  if (COOKIE) return COOKIE
+  const sources = []
+  const tok = String(process.env.DSH_TOKEN || '').trim()
+  if (tok) {
+    sources.push({ id: 'env-token', label: 'DSH_TOKEN 环境变量', obtain: async () => ({ status: 'ok', token: tok }) })
+  }
+  sources.push(...authSources({ base: BASE }))
+  const r = await acquireWakeAuth({ sources, base: BASE })
+  if (!r.ok) {
+    throw new Error(authFailureText({ tried: r.tried, base: BASE })
+      + (r.unreachable ? `\n  服务不可达：${r.unreachable}` : ''))
+  }
+  COOKIE = `${r.cookie.name}=${r.cookie.value}`
+  return COOKIE
+}
+
+/** 一元 RPC。 */
+async function call(endpoint, args, { timeoutMs = 30000 } = {}) {
+  const cookie = await authenticate()
+  const body = JSON.stringify({
+    type: 'client-request',
+    rpcId: `c-${Math.random().toString(36).slice(2, 10)}`,
+    method: endpoint,
+    payload: { args: args ?? {} },
+  })
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  try {
+    const res = await fetch(`${BASE}/api/${endpoint}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', cookie },
+      body,
+      signal: ac.signal,
+    })
+    const text = await res.text()
+    if (res.status !== 200) throw new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`)
+    const env = JSON.parse(text)
+    const r = env.result
+    if (!r?.ok) throw new Error(`${r?.error?.code || 'unknown'}: ${r?.error?.message || text.slice(0, 200)}`)
+    return r.value
+  } finally { clearTimeout(timer) }
+}
+
+/** WebSocket 实现：Node 内置的 **不能带 Cookie 头**（/api 用 cookie 鉴权）⇒ 优先用 ws 包。 */
+async function loadWs() {
+  // 先按常规解析（脚本自己所在的 node_modules）
+  try { const m = await import('ws'); return m.default ?? m } catch { /* 继续 */ }
+  // 再借 dsh 全局安装里的 ws（`import('<dir>')` 不支持目录，必须走 createRequire）。
+  // 2026-09-28：候选根目录**动态探测**，不再写死 homebrew —— 客户机 node 官方包布局下
+  // /opt/homebrew/... 不存在，写死会让这里的回落整条失效。
+  try {
+    const { createRequire } = await import('node:module')
+    const { scopeCandidates } = await import('./lib/dsh-scope.mjs')
+    for (const scope of scopeCandidates()) {
+      const root = dirname(dirname(scope)) // <...>/lib/node_modules
+      for (const pkg of ['ws', '@deepseek-ai/dsh/node_modules/ws']) {
+        try { return createRequire(join(root, pkg, 'package.json'))('ws') } catch { /* 下一个候选 */ }
+      }
+    }
+  } catch { /* 继续 */ }
+  return null
+}
+
+/** 流式 RPC：WebSocket /api/remote.mux（帧：{type:"open",streamId,endpoint,payload}）。 */
+async function stream(endpoint, args, { seconds = 8, onItem } = {}) {
+  const cookie = await authenticate()
+  const WS = await loadWs()
+  if (!WS) throw new Error('流式需要 `ws` 包（Node 内置 WebSocket 无法携带 Cookie 头）')
+  const ws = new WS(`${WS_BASE}/api/remote.mux`, { headers: { cookie } })
+  const streamId = `s-${Math.random().toString(36).slice(2, 10)}`
+  let opened = false
+  return await new Promise((resolve, reject) => {
+    const done = (v) => { try { ws.close() } catch {} ; resolve(v) }
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ type: 'open', streamId, endpoint, payload: { args: args ?? {} } }))
+      opened = true
+    })
+    ws.on('message', (data) => {
+      let frame
+      try { frame = JSON.parse(String(data)) } catch { return }
+      if (frame.type === 'item') { onItem?.(frame.value); return }
+      if (frame.type === 'error') { reject(new Error(`${frame.error?.code}: ${frame.error?.message}`)); return }
+      done(frame)   // 终止帧
+    })
+    ws.on('unexpected-response', (_req, res) => reject(new Error(`WS 被拒：HTTP ${res.statusCode}（401=缺 cookie，403=Host 未信任）`)))
+    ws.on('error', (e) => reject(new Error(`WS 错误：${e?.message || 'unknown'}`)))
+    ws.on('close', () => resolve({ closed: true, opened }))
+    setTimeout(() => done({ timedOut: true, opened }), seconds * 1000)
+  })
+}
+
+// ───────────────────────────── CLI ─────────────────────────────
+
+const [cmd, a1, a2, a3] = process.argv.slice(2)
+
+if (cmd === 'list') {
+  const v = await call('session/list', { _request: {} })
+  const items = v.items ?? []
+  console.log(`会话 ${items.length} 个：`)
+  for (const s of items.slice(0, 25)) {
+    const t = s.projections?.values?.title || '(无标题)'
+    console.log(`  ${s.sessionId}  ${s.running ? '▶ 运行中' : '· 空闲'}  ${t}`)
+  }
+} else if (cmd === 'page') {
+  if (!a1) throw new Error('用法：page <sessionId> [throughSeq] [maxMessages]')
+  const list = await call('session/list', { _request: {} })
+  const meta = list.items.find((s) => s.sessionId === a1)
+  const throughSeq = a2 !== undefined ? Number(a2) : (meta?.projections?.asOfSeq ?? -1)
+  const v = await call('session/page', {
+    request: { address: { kind: 'session', sessionId: a1 }, throughSeq, maxMessages: a3 ? Number(a3) : 10 },
+  })
+  console.log(`throughSeq=${throughSeq} 记录 ${v.records?.length ?? 0} 条 hasMore=${v.hasMore}`)
+  for (const rec of v.records ?? []) {
+    const e = rec.event ?? {}
+    const d = e.data ?? {}
+    const kind = e.type === 'assistant/message' ? `assistant(${d.message?.content?.map((c) => c.type).join('+') || ''})`
+      : e.type === 'tool/call' ? `tool:${d.name}`
+        : e.type
+    console.log(`  seq=${e.seq} turn=${d.turn ?? '-'} ${kind}`)
+  }
+} else if (cmd === 'follow') {
+  if (!a1) throw new Error('用法：follow <sessionId> [--seconds N]')
+  const sec = process.argv.includes('--seconds') ? Number(process.argv[process.argv.indexOf('--seconds') + 1]) : 8
+  console.log(`订阅 session/follow ${sec}s（只读，不发 prompt）…`)
+  const r = await stream('session/follow', {
+    request: { address: { kind: 'session', sessionId: a1 }, maxMessages: 1 },
+  }, { seconds: sec, onItem: (v) => console.log('  帧:', JSON.stringify(v).slice(0, 160)) })
+  console.log('  结束:', JSON.stringify(r))
+} else if (cmd === 'create') {
+  // 写路径①：新建会话（默认用 minimal preset，只有一个 shell 工具，最安全）
+  const preset = process.argv.includes('--preset') ? process.argv[process.argv.indexOf('--preset') + 1] : 'minimal'
+  const cwd = process.argv.includes('--cwd') ? process.argv[process.argv.indexOf('--cwd') + 1] : '/tmp'
+  const v = await call('session/create', { request: { cwd, agentPreset: preset } })
+  console.log('已创建会话：', JSON.stringify(v))
+} else if (cmd === 'prompt') {
+  // 写路径②：发消息（会真跑一轮 agent）+ 可选跟随流式
+  if (!a1 || !a2) throw new Error('用法：prompt <sessionId> "<文本>" [--follow N]')
+  const v = await call('session/prompt', {
+    request: {
+      requestId: `req-${Math.random().toString(36).slice(2, 10)}`,
+      sessionId: a1,
+      mode: 'queue',
+      content: [{ type: 'text', text: a2 }],
+      clientTimeZone: 'Asia/Shanghai',
+    },
+  })
+  console.log('已接受：', JSON.stringify(v))
+  if (process.argv.includes('--follow')) {
+    const sec = Number(process.argv[process.argv.indexOf('--follow') + 1]) || 30
+    console.log(`跟随流式 ${sec}s …`)
+    await stream('session/follow', {
+      request: { address: { kind: 'session', sessionId: a1 }, maxMessages: 1 },
+    }, { seconds: sec, onItem: (x) => {
+      const e = x?.event ?? x
+      if (e?.type) console.log(`  ← ${e.type}${e.data?.name ? ':' + e.data.name : ''}`)
+    } })
+  }
+} else if (cmd === 'cancel') {
+  if (!a1) throw new Error('用法：cancel <sessionId>')
+  console.log('已取消：', JSON.stringify(await call('session/cancel', { request: { sessionId: a1 } })))
+} else if (cmd === 'catalog') {
+  const v = await call('session/modelCatalog', {})
+  console.log('默认模型:', JSON.stringify(v.default))
+  for (const g of v.groups ?? []) console.log(`  ${g.id} (${g.name}): ${g.models.map((m) => m.id).join(', ')}`)
+} else {
+  console.log(readFileSync(new URL(import.meta.url), 'utf8').split('用法')[1]?.slice(0, 400) || '')
+  process.exit(2)
+}

package/engine/scripts/dsh-backup-scope.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# dsh-backup-scope —— 给**当前默认入口树**打一份整树备份（P5/P6，2026-09-29）
+#
+# 为什么需要它：升级失败要能物理回滚，前提是"旧树还在"。升级脚本（dsh-upgrade.mjs）
+# 自己也备份，但它备份到 /tmp/... 且是**替换前**那一刻；/tmp 会被系统清理、也不便于人找。
+# 本脚本把备份落到持久位置（`~/.dsh/argent/backup/dsh-<版本>-<日期>/scope`），
+# 并按 `<root>/lib/node_modules/@deepseek-ai` 的布局**顺带摆好**（可直接当侧车树用 ——
+# 2026-09-29 实测：普通目录里的整树备份 `node scope/dsh/lib/bin.js` 会 ERR_MODULE_NOT_FOUND）。
+#
+# 用法：
+#   bash scripts/dsh-backup-scope.sh                      # 备份当前默认入口（全局）树
+#   bash scripts/dsh-backup-scope.sh --scope <树> --label <名>
+#   bash scripts/dsh-backup-scope.sh --list               # 看已有备份
+# 退出码：0 成功；2 参数/环境错误。**只读源树，不重启任何服务。**
+set -uo pipefail
+DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+BACKUP_ROOT="$DSH_HOME/argent/backup"
+SCOPE_DEFAULT="/opt/homebrew/lib/node_modules/@deepseek-ai"
+SCOPE=""; LABEL=""; MODE=backup
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --list) MODE=list; shift;;
+    --scope) SCOPE="${2:-}"; shift 2;;
+    --label) LABEL="${2:-}"; shift 2;;
+    -h|--help) sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 0;;
+    *) echo "未知参数：$1（--help）" >&2; exit 2;;
+  esac
+done
+
+if [ "$MODE" = list ]; then
+  echo "备份根：$BACKUP_ROOT"
+  for d in "$BACKUP_ROOT"/*/; do
+    [ -d "$d" ] || continue
+    tree="$d/scope"
+    if [ -f "$tree/dsh/lib/bin.js" ]; then
+      n=$(ls -1 "$tree" 2>/dev/null | wc -l | tr -d ' ')
+      echo "  ✅ $(basename "$d")（$n 个包，${tree}）"
+    else
+      echo "  ⚠️  $(basename "$d")（缺 scope/dsh/lib/bin.js）"
+    fi
+  done
+  exit 0
+fi
+
+[ -n "$SCOPE" ] || SCOPE="$SCOPE_DEFAULT"
+[ -d "$SCOPE" ] || { echo "✗ 源树不存在：$SCOPE" >&2; exit 2; }
+[ -f "$SCOPE/dsh/lib/bin.js" ] || { echo "✗ 源树不像 dsh 安装（缺 dsh/lib/bin.js）：$SCOPE" >&2; exit 2; }
+
+if [ -z "$LABEL" ]; then
+  ver="$(node -e 'try{const p=require(process.argv[1]+"/dsh/package.json");process.stdout.write(p.version||"unknown")}catch{process.stdout.write("unknown")}' "$SCOPE" 2>/dev/null || echo unknown)"
+  LABEL="dsh-${ver}-$(date +%Y%m%d-%H%M%S)"
+fi
+DEST="$BACKUP_ROOT/$LABEL/lib/node_modules/@deepseek-ai"
+[ -e "$DEST" ] && { echo "✗ 目标已存在：${DEST}（换 --label）" >&2; exit 2; }
+
+echo "备份：$SCOPE"
+echo "  → ${DEST}"
+echo "      （布局 = <root>/lib/node_modules/@deepseek-ai ⇒ 可直接当侧车/救援树；另建 scope 软链兼容旧引用）"
+mkdir -p "$DEST"
+# 用 cp -R（保留符号链接语义：scope 里可能有指向包内的相对链接）；失败即停，不留半份
+if ! cp -R "$SCOPE/." "$DEST/"; then
+  echo "✗ 复制失败 ⇒ 删除半份备份" >&2
+  rm -rf "$BACKUP_ROOT/$LABEL"
+  exit 2
+fi
+n=$(ls -1 "$DEST" | wc -l | tr -d ' ')
+[ -f "$DEST/dsh/lib/bin.js" ] || { echo "✗ 备份不完整（缺 dsh/lib/bin.js）" >&2; exit 2; }
+# 落一个说明文件，免得日后没人知道它是什么
+cat > "$BACKUP_ROOT/$LABEL/README.txt" <<EOF
+dsh 整树备份
+  来源：$SCOPE
+  时间：$(date '+%F %T')
+  包数：$n
+  布局：lib/node_modules/@deepseek-ai（**可直接运行**的形态：<root>/lib/node_modules/ 下才算数）
+        scope 是指向它的软链（兼容旧文档/脚本里的 .../scope 引用）
+  用途：升级失败时回滚（dsh-restore.sh --to <本目录/lib/node_modules/@deepseek-ai>），
+        或直接当侧车/救援树
+  校验：ls "\$(dirname "$DEST")/scope" | wc -l   # 应为 $n
+EOF
+ln -sfn "lib/node_modules/@deepseek-ai" "$BACKUP_ROOT/$LABEL/scope"   # 兼容旧引用
+echo "  ✅ 完成（$n 个包）"
+echo "  验证：node scripts/dsh-upgrade-readiness.mjs --target <目标版本>"