@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/dsh-offline-pack.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * dsh 离线包打包器 —— **打包/开发工具**（2026-10-12 起：安装器**不再**代装宿主，
+ *                      也就**不再**下载/引用本工具产物；保留它是为了快照留档 / 断网机人工送装）。
+ *
+ * 用法:
+ *   node scripts/dsh-offline-pack.mjs <版本> [--from-dir <已装目录>]
+ *
+ * 做什么:
+ *   1. 校验版本与快照（dsh-version-lock/<版本>.json 必须存在 = 已验证版本）
+ *   2. 校验来源目录的 @deepseek-ai 子包版本分布 == 快照（防打包脏树）
+ *   3. 打包整个 node_modules（197 scope 包 + 顶层非 scope 依赖）→ /tmp/dsh-<版本>-offline.tgz
+ *
+ * 输出文件上传到 https://whyshu.com/dl/dsh-<版本>-offline.tgz（服务器 /home/whyshu/web/dl/）
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO = join(__dirname, "..");
+const LOCK_DIR = join(REPO, "dsh-version-lock");
+
+const target = process.argv[2];
+if (!target) {
+  console.error("用法: node scripts/dsh-offline-pack.mjs <版本> [--from-dir <已装目录>]");
+  process.exit(1);
+}
+const fromIdx = process.argv.indexOf("--from-dir");
+const fromDir = fromIdx > -1 ? process.argv[fromIdx + 1] : null;
+const ok = (m) => console.log("  ✅ " + m);
+const fail = (m) => { console.error("  ❌ " + m); process.exit(1); };
+
+// ── 1. 快照校验 ──────────────────────────────────────────
+const snapFile = join(LOCK_DIR, `${target}.json`);
+if (!existsSync(snapFile)) fail(`快照不存在: ${snapFile}（只有已验证版本才能打包分发）`);
+const snapshot = JSON.parse(readFileSync(snapFile, "utf8"));
+ok(`快照 ${target}: ${Object.keys(snapshot.resolved).length} 个子包`);
+
+// ── 2. 来源目录校验 ──────────────────────────────────────
+const src = fromDir || join("/tmp", `dsh-snap-${target.replace(/\./g, "").replace(/-/g, "")}`);
+const srcNM = join(src, "node_modules");
+if (!existsSync(srcNM)) fail(`来源目录不存在: ${srcNM}（先用 dsh-upgrade.mjs 或手工本地安装好目标版本）`);
+const scope = join(srcNM, "@deepseek-ai");
+if (!existsSync(scope)) fail(`缺少 @deepseek-ai: ${scope}`);
+
+console.log("\n校验 @deepseek-ai 版本分布 == 快照 ...");
+let bad = 0, total = 0;
+for (const name of readdirSync(scope)) {
+  const pj = join(scope, name, "package.json");
+  if (!existsSync(pj)) continue;
+  const pkg = JSON.parse(readFileSync(pj, "utf8"));
+  total++;
+  const expect = snapshot.resolved[name];
+  if (expect && pkg.version !== expect) {
+    console.log(`  ⚠️ ${name}: 期望 ${expect} 实际 ${pkg.version}`);
+    bad++;
+  }
+}
+if (bad) fail(`${bad}/${total} 个子包版本与快照不一致——不要打包脏树`);
+ok(`${total} 个子包版本与快照一致`);
+
+// ── 3. 打包 ──────────────────────────────────────────────
+const out = `/tmp/dsh-${target}-offline.tgz`;
+rmSync(out, { force: true });
+console.log(`\n打包 ${srcNM} → ${out} ...`);
+// -h（--dereference）：node_modules/.bin 的 symlink 转真实文件——
+// Windows 创建 symlink 需要管理员特权，保留链接会导致 PC 解压失败（实测 2026-08-24）
+execSync(`tar -czhf "${out}" -C "${src}" node_modules`, { stdio: "inherit" });
+const mb = (statSync(out).size / 1048576).toFixed(1);
+console.log(`\n✅ 离线包: ${out}（${mb} MB）`);
+console.log(`
+上传到服务器 /home/whyshu/web/dl/（whyshu.com/dl/）:
+  scp -i ~/.ssh/whyshu.pem "${out}" ubuntu@81.69.222.211:/home/whyshu/web/dl/
+验证: curl -sI https://whyshu.com/dl/dsh-${target}-offline.tgz | head -3
+（已无自动引用：安装器自 2026-10-12 起⛔ 不代装宿主。要人工送装请自行解包到目标 node_modules）`);

package/engine/scripts/dsh-overlay-pin.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# dsh-overlay-pin.sh —— 固定本机在 EasyTier 覆盖网里的地址（默认 10.126.126.2），并验证到位。
+#
+# 为什么要有它（2026-09-22 事故 + 用户实操踩坑）：
+#   · EasyTier 用 `-d`(DHCP) 时地址**每次重启可能变**（.2 → .1），而端口转发与 dsh web 的
+#     trusted-host 都按地址写 ⇒ PC 直接连不上；
+#   · 手工"杀 + 重启"很容易**看起来做了、其实没做**：`sudo pkill -x easytier-core` 在 macOS 上
+#     **匹配不上**（该进程的 comm 是完整路径 `/Users/chester/.local/bin/easytier-core`），
+#     于是旧进程照旧跑着，启动脚本又因"already running"直接退出 —— 地址当然没变。
+# 本脚本把这件事做成可验证的一步：停（按模式匹配并确认已退出）→ 起（固定地址）→ 等地址生效 → 复核。
+#
+# 用法：
+#   bash scripts/dsh-overlay-pin.sh            # 固定到 10.126.126.2/24（默认）
+#   bash scripts/dsh-overlay-pin.sh 10.126.126.9/24
+#   bash scripts/dsh-overlay-pin.sh --status   # 只看当前地址（不改）
+# 需要管理员权限（EasyTier 以 root 运行）——会用 sudo，按提示输入密码。
+set -uo pipefail
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LAUNCHER="$HOME/.local/bin/start-easytier.sh"
+CIDR_PREFIX="${ARGENT_OVERLAY_CIDR:-10.126.126.}"
+WANT="${1:-10.126.126.2/24}"
+
+overlay_ips() { ifconfig 2>/dev/null | awk '/inet /{print $2}' | grep "^${CIDR_PREFIX}" || true; }
+
+if [ "${1:-}" = "--status" ]; then
+  echo "── EasyTier"
+  pgrep -f easytier-core >/dev/null && echo "  ✅ 在跑（$(pgrep -f easytier-core | head -1)）：$(ps -o command= -p "$(pgrep -f easytier-core | head -1)" | cut -c1-120)" \
+    || echo "  ❌ 没在跑"
+  echo "  覆盖网地址：$(overlay_ips | tr '\n' ' ')"
+  exit 0
+fi
+
+if [ ! -x "$LAUNCHER" ]; then
+  echo "❌ 找不到启动脚本 $LAUNCHER" >&2; exit 2
+fi
+if [ "$(id -u)" -ne 0 ] && ! sudo -n true 2>/dev/null; then
+  echo "→ 需要管理员权限（EasyTier 以 root 运行），接下来会提示输入密码"
+fi
+
+echo "── ① 停掉现有 easytier（按**模式**匹配，不用 -x：它的 comm 是完整路径，-x 匹配不上）"
+PIDS="$(pgrep -f easytier-core || true)"
+if [ -n "$PIDS" ]; then
+  echo "  终止 PID: $PIDS"
+  sudo pkill -f easytier-core || true
+  for _ in 1 2 3 4 5 6; do
+    pgrep -f easytier-core >/dev/null || break
+    sleep 1
+  done
+  if pgrep -f easytier-core >/dev/null; then
+    echo "  ⚠️ 仍在运行，强制终止"; sudo pkill -9 -f easytier-core || true; sleep 2
+  fi
+fi
+if pgrep -f easytier-core >/dev/null; then
+  echo "❌ 停不掉（还活着：$(pgrep -f easytier-core | tr '\n' ' ')）——请手工处理" >&2; exit 1
+fi
+echo "  ✅ 已停止"
+
+echo "── ② 以固定地址启动：$WANT"
+# 启动脚本里的地址是可编辑的；这里按需改写（保持单一入口：launchd 也调它）
+if ! grep -q -- "--ipv4" "$LAUNCHER"; then
+  echo "  ⚠️ $LAUNCHER 里没有 --ipv4（DHCP 模式）⇒ 自动补上并去掉 -d"
+  sed -i '' 's/ -d \\/ \\/' "$LAUNCHER" 2>/dev/null || true
+  sed -i '' "s#--hostname chester-mac \\\\#--hostname chester-mac \\\\\n    --ipv4 $WANT \\\\#" "$LAUNCHER" 2>/dev/null || true
+else
+  sed -i '' "s#--ipv4 [0-9./]*#--ipv4 $WANT#" "$LAUNCHER"
+fi
+grep -q -- "--ipv4 $WANT" "$LAUNCHER" || { echo "❌ 未能写入固定地址，请手工检查 $LAUNCHER" >&2; exit 1; }
+
+# 以 root 起（与 launchd 的 osascript 提权等价）
+sudo bash -c "nohup '$LAUNCHER' >/dev/null 2>&1 &" || { echo "❌ 启动失败" >&2; exit 1; }
+
+echo "── ③ 等地址生效（最多 30s）"
+GOT=""
+for _ in $(seq 1 30); do
+  GOT="$(overlay_ips | head -1)"
+  [ "$GOT" = "${WANT%%/*}" ] && break
+  sleep 1
+done
+echo "  当前覆盖网地址：${GOT:-（无）}"
+if [ "$GOT" != "${WANT%%/*}" ]; then
+  echo "  ❌ 未拿到 ${WANT}（实际 ${GOT:-无}）——查日志：$HOME/Library/Logs/argent/easytier.log" >&2
+  exit 1
+fi
+echo "  ✅ 已固定到 $GOT"
+
+echo "── ④ 远程访问链路复核"
+bash "$REPO/scripts/dsh-remote-check.sh"

package/engine/scripts/dsh-plane.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * dsh-plane —— 三平面里的**侧车 / 救援面**登记与自检（P5，2026-09-29）
+ *
+ * 背景（评审稿 §5）：主面追新、救援面滞后一版、客户对齐侧车跟客户机同版；三者必须
+ * **各有名字 / 各有 home / 各有端口 / 各有启动项**，否则"救援"和"被救援"会互相踩。
+ * 本工具只做三件事，**都不碰服务**：
+ *   ① `--add`：登记一个平面（校验树布局、独立 home、端口不撞），打印**plist 片段**（不安装）；
+ *   ② `--list`：列出已登记平面与它们的状态；
+ *   ③ `--check`：只读自检（树还能不能跑、home 在不在、端口是否被占、与主面是否隔离）。
+ *
+ * 为什么不让脚本自己装 LaunchAgent / 起服务：那是"激活"动作，会重启服务、会抢端口 ——
+ * 必须由人来做（AGENTS.md「严禁自杀式重启」）。本工具把**该写什么**打印清楚，人复制即可。
+ *
+ * 用法：
+ *   node scripts/dsh-plane.mjs --add sidecar-0.1.5 --scope ~/dsh-0.1.5/lib/node_modules/@deepseek-ai \
+ *        --home ~/.dsh015 --port 3081 [--label com.whyshu.dsh015-web] [--title "客户对齐 0.1.5"]
+ *   node scripts/dsh-plane.mjs --list
+ *   node scripts/dsh-plane.mjs --check all
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveDshScope } from './lib/dsh-scope.mjs'
+import { dshHome, looksLikeScope } from './lib/scope-pointer.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const argOf = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] ?? d : d }
+const PLANE_DIR = join(dshHome(), 'argent', 'planes')
+const REGISTRY = join(PLANE_DIR, 'planes.json')
+
+const load = () => {
+  try { return JSON.parse(readFileSync(REGISTRY, 'utf8')) } catch { return { planes: {} } }
+}
+const save = (doc) => {
+  mkdirSync(PLANE_DIR, { recursive: true })
+  writeFileSync(REGISTRY, `${JSON.stringify(doc, null, 2)}\n`)
+}
+const expand = (p) => (p ? resolve(String(p).replace(/^~(?=\/|$)/, homedir())) : p)
+
+const MODE = process.argv.includes('--add') ? 'add'
+  : process.argv.includes('--list') ? 'list'
+    : process.argv.includes('--check') ? 'check' : ''
+
+const PRIMARY_PORT = 3080
+
+// 主面的 scope（**可选增强**：登记/合并时用得上，⛔ 探不到不该让 `--list` 崩）。
+// 0.6.0 F1 修复批（2026-10-14）：`resolveDshScope()` 探不到 ⇒ `null`（未知）；这里**降级但打印原因**，
+// ⛔ 不再拿一个可能不存在的路径当"主面 scope"（那会把平面的端口/home 冲突判据算错）。
+const PRIMARY_SCOPE = (() => {
+  const hit = resolveDshScope()
+  if (hit && !hit.stale) return hit.scope
+  console.error(hit
+    ? `  ⚠️ 主面 scope 是**空壳**（${hit.scope}：目录在、里面没有 dsh 包）⇒ 主面 scope 记为空（原因见上）`
+    : '  ⚠️ 探不到任何宿主 scope（可能是 **npx 形态**）⇒ 主面 scope 记为空；如需要请显式给 `--scope-dir <…/@deepseek-ai>`')
+  return ''
+})()
+const KNOWN_PLANES = { primary: { port: PRIMARY_PORT, home: dshHome(), scope: PRIMARY_SCOPE, note: '主面（当前服务）' } }
+
+if (MODE === 'add') {
+  const name = argOf('--add')
+  const scope = expand(argOf('--scope'))
+  const home = expand(argOf('--home'))
+  const port = Number(argOf('--port', '0'))
+  const label = argOf('--label', `com.whyshu.dsh-${name}-web`)
+  const title = argOf('--title', name)
+  const problems = []
+  // 允许点：侧车名常带版本（如 sidecar-0.1.5）；只要求小写字母/数字/点/连字符开头合法
+  if (!name || !/^[a-z0-9][a-z0-9.-]*$/.test(name)) problems.push('--add 需要一个 kebab-case 名字（允许点，如 sidecar-0.1.5）')
+  if (!scope) problems.push('--scope 必填（平面用的引擎树）')
+  else if (!looksLikeScope(scope)) problems.push(`--scope 不是可运行的 dsh 树（需要在 node_modules/ 下且含 dsh/lib/bin.js）：${scope}`)
+  if (!home) problems.push('--home 必填（该平面自己的 DSH_HOME，必须与主面隔离）')
+  else if (resolve(home) === resolve(dshHome())) problems.push(`--home 不能与主面相同（${dshHome()}）—— 平面之间必须各自一套 home`)
+  if (!port) problems.push('--port 必填（各平面各占端口）')
+  else if (port === PRIMARY_PORT) problems.push(`--port 不能与主面相同（${PRIMARY_PORT}）`)
+  const doc = load()
+  for (const [n, p] of Object.entries({ ...KNOWN_PLANES, ...doc.planes })) {
+    if (p.port === port) problems.push(`端口 ${port} 已被平面 ${n} 占用（登记里）`)
+    if (p.home && home && resolve(p.home) === resolve(home)) problems.push(`home ${home} 已被平面 ${n} 占用`)
+  }
+  if (problems.length) {
+    console.error('✗ 不能登记：')
+    for (const p of problems) console.error(`   · ${p}`)
+    process.exit(2)
+  }
+  doc.planes[name] = { scope, home, port, label, title, addedAt: new Date().toISOString() }
+  save(doc)
+  // 建 home 骨架（**只建目录**：profiles/ 与 argent/ 由安装器/人工继续填；不安装、不起服务）
+  for (const d of [join(home, 'argent'), join(home, 'profiles')]) {
+    if (!existsSync(d)) mkdirSync(d, { recursive: true })
+  }
+  const bin = join(scope, 'dsh', 'lib', 'bin.js')
+  console.log(`✅ 已登记平面 \`${name}\`（${title}）`)
+  console.log(`   树：${scope}`)
+  console.log(`   home：${home}（已建骨架 argent/ + profiles/；其余由安装器/人工填）`)
+  console.log(`   端口：${port}   启动项 label：${label}`)
+  console.log(`
+下一步（**人工激活**，工具不代劳 —— 会重启/抢端口）：
+  1) 目录：mkdir -p ${home}/argent ${join(dirname(scope), '..')} 2>/dev/null || true
+  2) 写 ~/Library/LaunchAgents/${label}.plist，ProgramArguments 用**绝对路径**：
+       ${process.execPath}  或  ${bin}
+       web --no-open --port ${port}
+     且设置 EnvironmentVariables：DSH_HOME=${home}
+  3) 加载：launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${label}.plist
+  4) 验证：curl -s -o /dev/null -w '%{http_code}\\n' http://127.0.0.1:${port}/   # 401/200 都算起来了
+  5) 自检：node scripts/dsh-plane.mjs --check ${name}`)
+  process.exit(0)
+}
+
+if (MODE === 'list' || (!MODE && process.argv.length <= 2)) {
+  const doc = load()
+  console.log(`平面登记：${REGISTRY}\n`)
+  const rows = [{ name: 'primary（主面）', ...KNOWN_PLANES.primary, label: 'com.whyshu.dsh-web' },
+    ...Object.entries(doc.planes).map(([n, p]) => ({ name: n, ...p }))]
+  for (const r of rows) {
+    const okTree = looksLikeScope(r.scope) ? '✅' : (r.scope ? '❌' : 'ℹ️')
+    console.log(`  ${okTree} ${r.name}｜端口 ${r.port}｜home ${r.home}｜label ${r.label}`)
+    if (r.scope) console.log(`      树 ${r.scope}`)
+  }
+  console.log('\n自检：node scripts/dsh-plane.mjs --check all')
+  process.exit(0)
+}
+
+if (MODE === 'check') {
+  const which = argOf('--check', 'all')
+  const doc = load()
+  const all = { primary: { ...KNOWN_PLANES.primary, label: 'com.whyshu.dsh-web' }, ...doc.planes }
+  const targets = which === 'all' ? Object.keys(all) : [which]
+  let bad = 0
+  for (const t of targets) {
+    const p = all[t]
+    if (!p) { console.error(`  ❌ 未登记平面：${t}`); bad += 1; continue }
+    const issues = []
+    if (!looksLikeScope(p.scope)) issues.push(`树不可运行：${p.scope}`)
+    if (p.home && !existsSync(p.home)) issues.push(`home 不存在（还没建/还没装）：${p.home}`)
+    if (p.home && resolve(p.home) === resolve(dshHome()) && t !== 'primary') issues.push('home 与主面相同（未隔离）')
+    console.log(`  ${issues.length ? '❌' : '✅'} ${t}（端口 ${p.port}）`)
+    for (const i of issues) console.log(`       · ${i}`)
+    if (issues.length) bad += 1
+  }
+  process.exit(bad ? 1 : 0)
+}
+
+console.log(`dsh-plane —— 侧车/救援面登记与自检
+
+  node scripts/dsh-plane.mjs --add <名> --scope <树> --home <dir> --port <n> [--label <label>] [--title <标题>]
+  node scripts/dsh-plane.mjs --list
+  node scripts/dsh-plane.mjs --check [<名>|all]
+
+只做登记与只读自检；**安装启动项/起服务由人来做**（会重启、会抢端口）。`)
+process.exit(process.argv.length <= 2 ? 0 : 2)

package/engine/scripts/dsh-portforward.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+dsh-portforward — dsh web 对外入口（EasyTier 组网内访问）
+
+背景：dsh 0.1.5+ 出于安全设计只允许监听 127.0.0.1（--host 0.0.0.0 被 CLI 拒绝，
+自定义 IP 被 schema 拒绝）。组网设备（手机/其他电脑）通过本转发器访问：
+
+    <本机 EasyTier IP>:3080  →  127.0.0.1:3080 (dsh web)
+
+配套：dsh web 启动参数需加 `--trusted-host <本机 EasyTier IP>:3080`
+（browser-trust fence 白名单，否则 /api 请求 403）；token 鉴权照旧
+（首次访问用带 `?token=` 的 URL 换取 30 天 cookie）。
+
+用法：
+    dsh-portforward.py [--listen-host 10.126.126.2] [--listen-port 3080]
+                       [--target-host 127.0.0.1] [--target-port 3080]
+
+特性：bind 失败自动重试（EasyTier 接口未就绪时自愈）；多连接并发；
+      半开/静默连接在一侧 EOF 后限时回收，不泄漏 fd（2026-09-22 修复，见下方注释）。
+"""
+import argparse
+import os
+import socket
+import sys
+import threading
+import time
+
+BUF = 65536
+RETRY_INTERVAL = 5
+# 一侧已 EOF 后，留给另一侧把剩余数据排完的时间；超时即强制关两端。
+# 不能无限等：对端静默（EasyTier 抖动、浏览器挂死、隧道半开）时另一侧会永久阻塞在
+# recv()，handle() 就永远走不到 close() —— 每条连接泄漏 2 个 fd，最终耗尽
+# launchd 下发的 256 句柄上限，accept() 开始 EMFILE，远程将彻底进不来。
+DRAIN_GRACE = float(os.environ.get("DSH_PORTFORWARD_DRAIN_GRACE", "10"))
+
+
+def close_quietly(sock):
+    """幂等关闭：先 shutdown 唤醒阻塞在对端的线程，再 close 释放 fd。"""
+    try:
+        sock.shutdown(socket.SHUT_RDWR)
+    except OSError:
+        pass
+    try:
+        sock.close()
+    except OSError:
+        pass
+
+
+def handle(client, target):
+    try:
+        upstream = socket.create_connection(target, timeout=10)
+    except OSError as e:
+        print(f"[portforward] 上游连接失败 {target}: {e}", flush=True)
+        close_quietly(client)
+        return
+    # 转发阶段不设超时：dsh web 的 WebSocket 可以长时间静默，超时会误杀正常连接
+    upstream.settimeout(None)
+    client.settimeout(None)
+
+    finished = threading.Event()
+
+    def relay(src, dst):
+        try:
+            while True:
+                data = src.recv(BUF)
+                if not data:
+                    break
+                dst.sendall(data)
+        except OSError:
+            pass
+        finally:
+            try:
+                dst.shutdown(socket.SHUT_WR)  # 传播半关闭
+            except OSError:
+                pass
+            finished.set()
+
+    t1 = threading.Thread(target=relay, args=(client, upstream), daemon=True)
+    t2 = threading.Thread(target=relay, args=(upstream, client), daemon=True)
+    t1.start()
+    t2.start()
+
+    # 健康的长连接两个方向都不会 EOF，这里会一直等 —— 正确，不做超时打扰。
+    while not finished.wait(1.0):
+        pass
+
+    # 有一侧结束了：给另一侧 DRAIN_GRACE 秒排空，然后无论如何都关掉两端。
+    t1.join(DRAIN_GRACE)
+    t2.join(DRAIN_GRACE)
+    close_quietly(client)
+    close_quietly(upstream)
+
+
+def _local_ipv4(prefix: str) -> list:
+    """本机所有匹配前缀的 IPv4（覆盖网地址/utun 也要能看到）。
+
+    ⚠️ 不能用 `socket.getaddrinfo(gethostname())`：它只返回主机名解析结果，**看不到 utun 这类
+    点对点接口**（2026-09-22 实测：EasyTier 的 10.126.126.1 完全查不到 ⇒ auto 会一直判"未就绪"）。
+    这里直接枚举接口地址：① ioctl(仅 Unix，无子进程) ② 兜底解析 /sbin/ifconfig。
+    """
+    found = []
+
+    def add(ip):
+        if ip.startswith(prefix) and ip not in found:
+            found.append(ip)
+
+    # ① ioctl（stdlib）：逐接口取 SIOCGIFADDR
+    try:
+        import fcntl, struct
+        SIOCGIFADDR = 0xC0206921                      # macOS
+        for _, name in socket.if_nameindex():
+            try:
+                sk = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+                packed = fcntl.ioctl(sk.fileno(), SIOCGIFADDR, struct.pack('256s', name.encode()[:15]))
+                sk.close()
+                add(socket.inet_ntoa(packed[20:24]))
+            except OSError:
+                continue
+    except Exception:
+        pass
+
+    # ② 兜底：解析 ifconfig（ioctl 在个别系统/权限下会失败）
+    if not found:
+        try:
+            import subprocess
+            out = subprocess.run(['/sbin/ifconfig'], capture_output=True, text=True, timeout=5).stdout
+            for line in out.splitlines():
+                line = line.strip()
+                if line.startswith('inet '):
+                    add(line.split()[1])
+        except Exception:
+            pass
+    return found
+
+
+def resolve_listen_host(spec: str, prefix: str = '10.126.126.') -> tuple:
+    """把 --listen-host 解析成真正要 bind 的地址 → (ip 或 None, 说明)。
+
+    · 具体 IP：原样返回（并提示它当前是否真的在本机 —— 这一条就是 2026-09-22 事故的判据）
+    · 'auto'：按前缀自动挑一个本机覆盖网地址（地址变了也能自愈）
+    """
+    if spec and spec != 'auto':
+        # 明确给了地址就照用（不擅自改），但**必须能判断它是否存在** —— 这正是 2026-09-22
+        # 事故的判据：plist 写死 .2，而重启后本机只有 .1 ⇒ bind 永久失败却看不出原因。
+        same_subnet = _local_ipv4(spec.rsplit('.', 1)[0] + '.')
+        if spec in same_subnet:
+            return spec, 'explicit（本机存在）'
+        return spec, 'explicit（⚠️ 该地址当前不在本机接口上，bind 会失败；建议改用 auto）'
+    found = _local_ipv4(prefix)
+    if not found:
+        return None, f'未找到 {prefix}x 的本机地址（EasyTier 未就绪？）'
+    return found[0], f'auto（选中 {found[0]}）'
+
+
+def raise_fd_limit(target=8192):
+    """抬高本进程的 fd 软上限。
+
+    launchd 给 LaunchAgent 的 maxfiles 默认是 256（实测 `launchctl limit maxfiles`
+    = 256 unlimited）。远程访问全靠这个转发器，一旦连接堆积撞上 256，
+    accept() 会 EMFILE，远程会彻底进不来。硬上限是 unlimited，进程内可自行抬高。
+    """
+    try:
+        import resource
+        soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)
+        if hard != resource.RLIM_INFINITY and hard < target:
+            target = hard
+        if soft < target:
+            resource.setrlimit(resource.RLIMIT_NOFILE, (target, hard))
+            print(f"[portforward] fd 上限 {soft} → {target}", flush=True)
+    except Exception as e:  # 抬不动不算致命，继续跑
+        print(f"[portforward] 抬高 fd 上限失败（忽略）：{e}", flush=True)
+
+
+def main():
+    raise_fd_limit()
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--listen-host', default='auto',
+                    help="监听地址：'auto'（默认，自动探测 EasyTier 覆盖网 IP）或具体 IP。"
+                         "⚠️ 2026-09-22 事故：EasyTier 用 -d(DHCP) 拿到的地址**重启后会变**"
+                         "（.2 → .1），而这里与 dsh-web 的 --trusted-host 都写死了 .2 ⇒ "
+                         "转发器 bind 失败、界面报连不上（日志还在 /tmp，重启即清，无迹可查）")
+    ap.add_argument('--auto-cidr', default='10.126.126.',
+                    help='auto 模式下用于识别覆盖网地址的前缀（默认 10.126.126.）')
+    ap.add_argument('--listen-port', type=int, default=3080,
+                    help='监听端口（转发入口）')
+    ap.add_argument('--target-host', default='127.0.0.1', help='目标地址')
+    ap.add_argument('--target-port', type=int, default=3080, help='目标端口')
+    args = ap.parse_args()
+
+    target = (args.target_host, args.target_port)
+
+    while True:  # bind 失败自动重试（EasyTier 接口未就绪时自愈）
+        host, why = resolve_listen_host(args.listen_host, args.auto_cidr)
+        if host is None:
+            print(f"[portforward] 暂无可监听地址（{why}），{RETRY_INTERVAL}s 后重试", flush=True)
+            time.sleep(RETRY_INTERVAL)
+            continue
+        listen = (host, args.listen_port)
+        srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            srv.bind(listen)
+            srv.listen(64)
+            break
+        except OSError as e:
+            srv.close()
+            print(f"[portforward] bind {listen} 失败（{e}），{RETRY_INTERVAL}s 后重试", flush=True)
+            time.sleep(RETRY_INTERVAL)
+
+    print(f"[portforward] {listen[0]}:{listen[1]} → {target[0]}:{target[1]} 已就绪"
+          f"（listen-host={args.listen_host}）", flush=True)
+    while True:
+        try:
+            conn, addr = srv.accept()
+        except OSError as e:
+            print(f"[portforward] accept 异常: {e}，2s 后继续", flush=True)
+            time.sleep(2)
+            continue
+        threading.Thread(target=handle, args=(conn, target), daemon=True).start()
+
+
+if __name__ == '__main__':
+    main()