dsh-remote 0.8.35 → 0.8.36

package/lib/web-attach.js

@@ -0,0 +1,467 @@
+// dsh-remote — "remote DSH web UI" attach sessions (issue #46).
+//
+// The user's intent behind that issue is "use the local DSH as a CLIENT for a
+// DSH running on another machine": they do NOT want the remote to expose an
+// inbound listener. DSH makes that impossible anyway — `dsh-web-app` hard-
+// rejects `--host 0.0.0.0` (startup.js) because it would put remote code
+// execution on the network, and `dsh-host-webserver` only accepts the
+// 127.0.0.1/0.0.0.0 literals.
+//
+// So this module inverts the direction, exactly like the rest of the plugin:
+// we SSH OUT, start (or reuse) a loopback-bound `dsh web` on the remote, and
+// carry its socket back over our own SSH connection with a local TCP forward.
+// The browser then talks to 127.0.0.1:<localPort> on this machine.
+//
+// Verified end-to-end on a real Linux host (dsh 0.1.5-rc.2): a bare TCP forward
+// is sufficient — the SPA, its assets, AND the `/api/remote.mux` WebSocket
+// upgrade all transit it (HTTP/1.1 101), with no reverse proxy and no host
+// rewriting. That works because DSH binds its auth cookie to the request
+// authority, so a cookie minted against `127.0.0.1:<localPort>` is exactly what
+// the browser then sends back to that same authority.
+//
+// Three details drive the design and are worth stating once:
+//
+//  1. The launch token CANNOT be read from anywhere but stdout. It is a
+//     `randomBytes` value held in a process-local WeakMap and printed on one
+//     line (`dsh web: http://127.0.0.1:<port>/?token=…`). No file, no env var.
+//     Therefore the token is captured by redirecting the remote process's
+//     output to a log file and parsing that line out of it.
+//  2. `--port 0` lets the remote OS pick a free port, and the same printed line
+//     reports which port it chose — so we never have to guess or probe for a
+//     free port on the remote.
+//  3. The pairing that must survive is (token, port) from ONE launch. Reading
+//     them from one line is what keeps them consistent.
+//
+// Everything here is read-only with respect to the remote filesystem except
+// the log file it creates under the remote `$HOME`.
+import net from 'node:net'
+
+/** Remote log file per attach session; `$HOME` is expanded by the remote shell. */
+const LOG_NAME = '.dsh-remote-web'
+
+/**
+ * Parse the `dsh web:` startup line out of a remote log.
+ *
+ * The line looks like:
+ *   dsh web: http://127.0.0.1:43129/?token=Iy7FKuPSI5qJKJUFDyah4B6i8Ul6_hvspiJhiWufYt8
+ * and may be followed by a LAN suffix when the remote bound 0.0.0.0 (it never
+ * will here — we never pass `--host` — but tolerate it rather than break).
+ *
+ * @param {string} text - the remote log contents.
+ * @returns {{url: string, port: number, token: string}|null} parsed facts, or
+ *   null when the line has not appeared yet (still booting) or is malformed.
+ */
+export function parseWebStart(text) {
+  if (typeof text !== 'string' || text === '') return null
+  // Take the LAST match: a reused log file may hold an earlier session's line,
+  // and the newest one is the one this launch produced.
+  const matches = [...text.matchAll(/dsh web:\s*(http:\/\/[^\s]+)/g)]
+  if (matches.length === 0) return null
+  const url = matches[matches.length - 1][1]
+  let parsed
+  try {
+    parsed = new URL(url)
+  } catch {
+    return null
+  }
+  const port = Number(parsed.port)
+  const token = parsed.searchParams.get('token') || ''
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null
+  if (!token) return null
+  return { url, port, token }
+}
+
+/** True when the log proves the remote process died instead of booting. */
+export function launchFailed(text) {
+  return typeof text === 'string' && text.includes(DEAD_MARKER)
+}
+
+/** Marker the remote launcher echoes when the process exits before printing. */
+const DEAD_MARKER = '__DSH_REMOTE_DIED__'
+/** Marker separating the parsed line from the raw log tail for diagnostics. */
+export const TAIL_MARKER = '__DSH_TAIL__'
+/** Marker carrying the remote PID so the session can stop its own process. */
+export const PID_MARKER = '__DSH_PID__='
+/** Random ASCII tag so two attach sessions never share a remote log file. */
+function randomTag() {
+  return Math.random().toString(36).slice(2, 8) + Date.now().toString(36).slice(-4)
+}
+
+/**
+ * Build the one-shot remote command that launches `dsh web` detached and waits
+ * for its startup line.
+ *
+ * `setsid` + `nohup` + redirected stdio are all required: the SSH channel closes
+ * as soon as this shell exits, and without detaching the SIGHUP would kill the
+ * server we just started. The loop is bounded so a wedged remote cannot hang the
+ * call past the caller's own timeout, and it reports either the parsed line or
+ * the log tail — never silence.
+ *
+ * @param {object} spec - launch parameters.
+ * @param {boolean} [spec.omitNoOpen] - drop `--no-open`. Older DSH (measured on
+ *   0.1.0-rc.6) has no such flag and exits with "unknown option '--no-open'";
+ *   the caller retries with this set rather than assuming a flag exists.
+ * @returns {string} a POSIX shell command line (no newlines, ASCII only).
+ */
+export function buildLaunchCommand({ command, profile, logPath, remotePort = 0, dshHome = '', waitSeconds = 45, omitNoOpen = false }) {
+  const env = dshHome ? `DSH_HOME="${dshHome}" ` : ''
+  const noOpen = omitNoOpen ? '' : ' --no-open'
+  const args = `--profile ${profile} --port ${Number(remotePort) || 0}${noOpen}`
+  const limit = Number(waitSeconds) || 45
+  // The loop is ONE shell element: `do` is a keyword and `do;` is a syntax error
+  // in POSIX sh, so it must be glued to the first command of the body rather
+  // than separated like the other statements.
+  const loop = `while [ $i -lt ${limit} ]; do grep -q 'token=' "$LOG" 2>/dev/null && break`
+    + `; kill -0 $P 2>/dev/null || { echo ${DEAD_MARKER}; break; }`
+    + `; sleep 1; i=$((i+1)); done`
+  return [
+    `LOG="$HOME/${logPath}"`,
+    `: > "$LOG"`,
+    // `command -v setsid` guards hosts without util-linux (macOS); plain nohup
+    // still detaches from the channel's HUP there.
+    `command -v setsid >/dev/null 2>&1 && SET=setsid || SET=`,
+    `${env}$SET nohup ${command} ${args} >"$LOG" 2>&1 </dev/null & P=$!`,
+    `i=0`,
+    loop,
+    `echo "${PID_MARKER}$P"`,
+    `grep -m1 'dsh web:' "$LOG" 2>/dev/null`,
+    `echo ${TAIL_MARKER}`,
+    `tail -20 "$LOG" 2>/dev/null`,
+  ].join('; ')
+}
+
+/** Extract the remote PID from launcher output (0 when absent). */
+export function parseRemotePid(output) {
+  const m = /__DSH_PID__=(\d+)/.exec(String(output || ''))
+  return m ? Number(m[1]) : 0
+}
+
+/**
+ * Recognize a known remote-side reason the web surface could not start, and
+ * return an actionable sentence for it.
+ *
+ * The point is to keep an operator from reading "the remote DSH did not report a
+ * startup token" and concluding the *plugin* is broken. Measured cause: dsh
+ * ≤ 0.1.0-rc.6 depends on `node-pty@1.1.0`, whose published tarball ships
+ * darwin/win32 prebuilds but **no `linux-x64`**, so `dsh web` cannot boot on
+ * Linux at all — it dies loading the native module. 0.1.5-rc.2 moved to
+ * `node-pty@1.2.0-beta.15`, which does ship Linux builds.
+ *
+ * @param {string} output - the remote log tail.
+ * @returns {string} a hint, or '' when nothing is recognized.
+ */
+export function explainLaunchFailure(output) {
+  const text = String(output || '')
+  if (/pty\.node|Failed to load native module/i.test(text)) {
+    return ' The remote could not load node-pty\'s native module. Known cause: dsh <= 0.1.0-rc.6'
+      + ' depends on node-pty@1.1.0, which publishes no linux-x64 prebuild, so `dsh web` cannot start'
+      + ' on Linux at all. Upgrade the remote dsh to 0.1.5-rc.2 or newer (node-pty@1.2.0-beta.15 ships'
+      + ' the Linux build), or point `webAttachCommand` at a newer dsh installed elsewhere.'
+  }
+  if (/is intentionally not supported|--host 0\.0\.0\.0/i.test(text)) {
+    return ' The remote dsh refused an all-interfaces bind. Attach deliberately never passes `--host`;'
+      + ' check `webAttachCommand` does not add one.'
+  }
+  if (/command not found|No such file or directory|not found/i.test(text)) {
+    return ' The remote shell could not run the dsh command. If the remote dsh is not on the SSH login'
+      + ' PATH (a version manager or private prefix), set `webAttachCommand` to its absolute path.'
+  }
+  return ''
+}
+
+/**
+ * Build the command that stops the remote process THIS session started.
+ *
+ * Two things make this less obvious than it looks, both found by running it
+ * against a real host:
+ *   1. The log path cannot identify the process — it appears only as a shell
+ *      redirect, so it is absent from argv and `pkill -f <logfile>` matches
+ *      nothing (the process survived, verified live).
+ *   2. The PORT cannot identify it either, because we deliberately launch with
+ *      `--port 0` (the remote picks a free port, and the chosen number is only
+ *      known afterwards). A `--port 0` substring match therefore never fires.
+ *
+ * So the recorded PID is the handle, and the kill targets its process GROUP
+ * (`kill -- -PID`): the launch goes through `setsid`, making the child a
+ * session/group leader whose PGID equals its PID, so the group contains exactly
+ * the process tree we started — never a sibling attach session and never the
+ * user's own DSH. Before signalling, the command re-verifies that the PID still
+ * exists and still looks like a `dsh` process, so a recycled PID belonging to an
+ * unrelated program is not killed.
+ *
+ * @param {number} pid - the PID reported by the launch.
+ * @param {string} [logPath] - this session's log file, removed after the kill so
+ *   repeated attaches do not accumulate files in the remote home.
+ * @returns {string} a POSIX shell command (always exits 0, never throws).
+ */
+export function buildStopCommand(pid, logPath = '') {
+  const p = Number(pid) || 0
+  const cleanup = logPath ? `; rm -f "$HOME/${logPath}" 2>/dev/null` : ''
+  if (p < 1) return `true${cleanup}`
+  return `P=${p}`
+    + `; if [ -d "/proc/$P" ]; then`
+    + ` C=$(tr '\\0' ' ' < "/proc/$P/cmdline" 2>/dev/null);`
+    + ` case "$C" in *dsh*) kill -- -"$P" 2>/dev/null || kill "$P" 2>/dev/null;; esac;`
+    + ` fi${cleanup}; true`
+}
+
+/**
+ * One attached remote DSH Web UI: a local listener whose sockets are carried
+ * over SSH to the remote's loopback web port.
+ *
+ * The listener is a plain `net.Server` + `client.forwardOut` pair — the same
+ * mechanism `ForwardManager` uses for user-defined forwards. It is implemented
+ * here rather than through that manager because this tunnel is bound to a
+ * CHOSEN pool (the machine the user picked), whereas `ForwardManager` is wired
+ * to the single "active machine" pool; routing an attach through it would send
+ * the tunnel to whichever machine happened to be active.
+ */
+export class WebAttach {
+  /**
+   * @param {object} opts - injected collaborators (all optional in production).
+   * @param {object} [opts.net] - a `node:net`-compatible module (tests).
+   * @param {number} [opts.localPortStart] - first local port to try.
+   * @param {number} [opts.localPortMax] - how many ports to try before failing.
+   */
+  constructor(opts = {}) {
+    this.net = opts.net || net
+    this.localPortStart = opts.localPortStart || 3088
+    this.localPortMax = opts.localPortMax || 50
+    /** @type {import('node:net').Server|null} */ this.server = null
+    /** @type {Set<import('node:net').Socket>} */ this.sockets = new Set()
+    /** @type {object|null} */ this.client = null
+    this.localPort = 0
+    this.remotePort = 0
+    this.token = ''
+    this.tag = ''
+    this.logPath = ''
+    this.remotePid = 0
+    this.machineId = ''
+    this.command = ''
+    this.startedAt = 0
+  }
+
+  /** Whether the tunnel is currently listening. */
+  get active() {
+    return this.server !== null
+  }
+
+  /**
+   * Attach to a remote DSH Web UI.
+   *
+   * @param {object} spec - the attach request.
+   * @param {object} spec.pool - the SshPool for the chosen machine.
+   * @param {string} spec.machineId - machine id, for bookkeeping.
+   * @param {string} [spec.command] - remote dsh executable (default `dsh`).
+   * @param {string} [spec.profile] - DSH profile to boot (default `web`).
+   * @param {string} [spec.existingUrl] - attach to an ALREADY running remote
+   *   web UI instead of starting one: its `http://127.0.0.1:<port>/?token=…`.
+   * @param {(cmd: string, opts?: object) => Promise<{stdout: string, code: number}>} [spec.exec]
+   *   - remote exec, defaulting to `pool.exec`.
+   * @returns {Promise<{url: string, localPort: number, remotePort: number}>}
+   */
+  async open(spec) {
+    const {
+      pool, machineId = '', command = 'dsh', profile = 'web',
+      existingUrl = '', dshHome = '', waitSeconds = 45,
+    } = spec || {}
+    if (!pool) throw new Error('web-attach: a machine pool is required')
+    this.machineId = String(machineId || '')
+    this.command = command
+
+    const exec = spec.exec || ((cmd, opts) => pool.exec(cmd, opts))
+    // Connecting first also surfaces credential/host-key problems BEFORE we
+    // start a remote process we would then have to clean up.
+    this.client = await pool.connect()
+
+    if (existingUrl) {
+      const parsed = parseWebStart(`dsh web: ${existingUrl}`)
+      if (!parsed) {
+        throw new Error('web-attach: existing URL must look like http://127.0.0.1:<port>/?token=<token>')
+      }
+      this.remotePort = parsed.port
+      this.token = parsed.token
+    } else {
+      this.tag = randomTag()
+      const logPath = `${LOG_NAME}-${this.tag}.log`
+      this.logPath = logPath
+      const timeoutMs = Math.max(30000, (waitSeconds + 20) * 1000)
+      let out = String(await this._launch(exec, { command, profile, logPath, dshHome, waitSeconds, timeoutMs }, false))
+      // Older DSH (0.1.0-rc.6) has no `--no-open` and exits on the unknown flag
+      // before doing anything. Retry once without it: `--no-open` is a nicety
+      // (it stops the REMOTE from opening its own browser), not a requirement,
+      // and a bounded single retry is safe because the first attempt provably
+      // never started a server.
+      if (launchFailed(out) && /unknown option/i.test(out) && /--no-open/.test(out)) {
+        out = String(await this._launch(exec, { command, profile, logPath, dshHome, waitSeconds, timeoutMs }, true))
+        this.omittedNoOpen = true
+      }
+      this.remotePid = parseRemotePid(out)
+      const tail = out.split(TAIL_MARKER).slice(1).join(TAIL_MARKER).trim()
+      // Both failure shapes carry the same diagnostics: the process either died
+      // (its output is the whole story) or is still booting after the deadline.
+      if (launchFailed(out)) {
+        throw new Error('web-attach: the remote DSH exited during startup.'
+          + explainLaunchFailure(tail || out)
+          + ` ${tail || 'no output'}`)
+      }
+      const parsed = parseWebStart(out)
+      if (!parsed) {
+        throw new Error(
+          `web-attach: the remote DSH did not report a startup token within ${waitSeconds}s.`
+          + ` Check that \`${command}\` exists on the remote and can boot a web profile.`
+          + explainLaunchFailure(tail || out)
+          + (tail ? ` Remote output: ${tail}` : ''),
+        )
+      }
+      this.remotePort = parsed.port
+      this.token = parsed.token
+    }
+
+    await this._listen()
+    this.startedAt = Date.now()
+    return this.describe()
+  }
+
+  /**
+   * Run one launch attempt and return its raw output.
+   *
+   * @param {(cmd: string, opts?: object) => Promise<{stdout: string}>} exec - remote exec.
+   * @param {object} d - launch parameters plus the exec timeout.
+   * @param {boolean} omitNoOpen - drop `--no-open` for old DSH.
+   * @returns {Promise<string>} the launcher's stdout.
+   */
+  async _launch(exec, d, omitNoOpen) {
+    const cmd = buildLaunchCommand({ ...d, omitNoOpen })
+    const res = await exec(cmd, { timeoutMs: d.timeoutMs })
+    return String(res && res.stdout ? res.stdout : '')
+  }
+
+  /** Bind the local listener, advancing past ports already in use. */
+  async _listen() {
+    let lastError = null
+    for (let i = 0; i < this.localPortMax; i++) {
+      const port = this.localPortStart + i
+      try {
+        await this._listenOn(port)
+        this.localPort = port
+        return
+      } catch (err) {
+        lastError = err
+        // Only a taken port is worth retrying; anything else (permissions,
+        // an unusable interface) will not be fixed by the next number.
+        if (err && err.code !== 'EADDRINUSE') break
+      }
+    }
+    throw new Error(
+      `web-attach: no free local port in ${this.localPortStart}..${this.localPortStart + this.localPortMax - 1}`
+      + (lastError ? ` (${lastError.code || lastError.message})` : ''),
+    )
+  }
+
+  _listenOn(port) {
+    return new Promise((resolve, reject) => {
+      const server = this.net.createServer((socket) => this._pipe(socket))
+      const onError = (err) => {
+        server.removeListener('listening', onListening)
+        try { server.close() } catch { /* never listened */ }
+        reject(err)
+      }
+      const onListening = () => {
+        server.removeListener('error', onError)
+        // A post-bind error must not crash the host process: report and drop
+        // the tunnel so the UI can show "disconnected" instead of dying.
+        server.on('error', (err) => {
+          this.server = null
+          this.lastError = String((err && err.message) || err)
+        })
+        this.server = server
+        resolve()
+      }
+      server.once('error', onError)
+      server.once('listening', onListening)
+      // Loopback only: this endpoint reaches a full remote harness, so it must
+      // never be reachable from the network even on a LAN-facing machine.
+      server.listen(port, '127.0.0.1')
+    })
+  }
+
+  /** Carry one local socket to the remote web port over SSH. */
+  _pipe(socket) {
+    if (!this.client) { try { socket.destroy() } catch { /* already gone */ } return }
+    this.client.forwardOut('127.0.0.1', 0, '127.0.0.1', this.remotePort, (err, channel) => {
+      if (err) { try { socket.destroy() } catch { /* already gone */ } return }
+      this.sockets.add(socket)
+      socket.pipe(channel)
+      channel.pipe(socket)
+      const kill = () => {
+        try { socket.destroy() } catch { /* already gone */ }
+        try { channel.close() } catch { /* already closed */ }
+        this.sockets.delete(socket)
+      }
+      socket.on('error', kill)
+      channel.on('error', kill)
+      socket.on('close', kill)
+      channel.on('close', kill)
+    })
+  }
+
+  /**
+   * The URL to open, carrying the one-time launch token.
+   *
+   * The token is a credential, so it stays on loopback and is never sent
+   * anywhere; DSH exchanges it for a 30-day signed cookie on the first request
+   * and redirects to a clean `/`.
+   */
+  get url() {
+    return `http://127.0.0.1:${this.localPort}/?token=${this.token}`
+  }
+
+  /** The clean URL (no token) — what the address bar shows after the exchange. */
+  get cleanUrl() {
+    return `http://127.0.0.1:${this.localPort}/`
+  }
+
+  /** Serializable status for the settings UI. */
+  describe() {
+    return {
+      machineId: this.machineId,
+      url: this.url,
+      cleanUrl: this.cleanUrl,
+      token: this.token,
+      localPort: this.localPort,
+      remotePort: this.remotePort,
+      active: this.active,
+      startedAt: this.startedAt,
+      // Only a process we launched can be stopped by us; an attach onto the
+      // user's own running instance is deliberately hands-off.
+      managed: this.remotePid > 0,
+      error: this.lastError || '',
+    }
+  }
+
+  /**
+   * Tear the tunnel down. The remote process is left running by default: the
+   * user may be using that DSH elsewhere, and silently killing a process we did
+   * not start is worse than a leftover one. `stopRemote` opts in.
+   *
+   * @param {object} [opts] - close options.
+   * @param {boolean} [opts.stopRemote] - also terminate the remote process.
+   * @param {(cmd: string) => Promise<unknown>} [opts.exec] - remote exec.
+   */
+  async close({ stopRemote = false, exec } = {}) {
+    for (const socket of [...this.sockets]) {
+      try { socket.destroy() } catch { /* already gone */ }
+    }
+    this.sockets.clear()
+    const server = this.server
+    this.server = null
+    if (server) await new Promise((resolve) => server.close(() => resolve()))
+    // Only a process we started has a recorded PID; an attach to the user's own
+    // running instance must never signal anything.
+    if (stopRemote && exec && this.remotePid) {
+      await Promise.resolve(exec(buildStopCommand(this.remotePid, this.logPath))).catch(() => {})
+    }
+    this.client = null
+  }
+}

package/lib/web-deploy-skill.js

@@ -0,0 +1,205 @@
+// dsh-remote — built-in agent skill for remote DSH deployment (issue #46, P3).
+//
+// Layer 1 (`lib/web-deploy.js`) handles the deterministic path: probe the
+// remote, install to a private prefix, verify, attach. This module is the
+// ESCAPE HATCH for everything that path cannot express — a missing package
+// manager, a proxy, sudo-only systems, an internal mirror, a Windows remote, or
+// a failure whose message does not match any known signature.
+//
+// It is a skill rather than more code because the value here is JUDGEMENT over
+// arbitrary output, and because there is no closed set of remote environments to
+// enumerate. The skill body is therefore written as a diagnosis-first playbook:
+// the symptoms actually measured while building issue #46 come first, because
+// those are the ones that waste the most time.
+//
+// Two deliberate properties:
+//
+//  1. **The skill is registered at runtime, not shipped as a file.** The plugin
+//     is a single npm package; a filesystem skill would need a writable
+//     `$DSH_HOME/skills` and would collide with whatever the user keeps there.
+//     `ctx.skills.register()` keeps it self-contained and namespaced.
+//  2. **It is user-invocable and model-invocable.** The settings button starts a
+//     session that already has the skill selected; the model may also reach for
+//     it on its own when an `rw_*` call fails with a deployment-shaped error.
+import { DEFAULT_INSTALL_VERSION, DEFAULT_PREFIX_SUFFIX } from './web-deploy.js'
+
+/** Stable skill name; kebab-case is required by the registry. */
+export const SKILL_NAME = 'dsh-remote-deploy'
+
+/**
+ * The skill body.
+ *
+ * Written for an agent that already has this plugin's `rw_*` tools. It is
+ * intentionally explicit about the two failure signatures measured on a real
+ * host, because a generic "install it" instruction would have been useless for
+ * both of them.
+ */
+export const SKILL_BODY = `# 在远端机器部署并验证 DSH
+
+用途：用户想连一台机器的 DSH 网页界面（\`dsh web\`），但连不上。你负责把环境修好并**证明**
+它真的能用。确定性流程（探测/私有前缀安装/校验）已经由插件的「部署并验证」按钮实现；
+你只在它做不到或失败时才被叫来。
+
+## 先用工具，不要一上来就手工
+
+**第一件事：调 \`rw_deploy_probe\`。** 它是只读的，给出结构化体检：平台/架构、node/npm、
+现有 dsh 及版本、**原生模块能否启动**、是否认识 \`--no-open\`、Git Bash、代理与 npm 源、
+安装前缀可写性，以及判定结论（blocker/warn/info）与修复建议。先读它的结论，不要自己拼命令猜。
+
+它**只读、不安装**（刻意的）。要装就用设置页的「部署并验证」卡片——它装到私有前缀并逐步校验。
+你在这里的价值是处理那条路径覆盖不到的情况（见下文的长尾）。真需要自己安装时照本文流程做，
+并在结论里说明为什么自动路径不适用。
+
+## 两个已实测的失败签名（最重要）
+
+### 1. \`Failed to load native module: pty.node\`
+
+**根因**：dsh 依赖 node-pty，而某些版本发布的包里**没有当前平台的预编译产物**。
+实测：\`node-pty@1.1.0\`（dsh 0.1.0-rc.6 依赖它）只带 darwin/win32 的 prebuild，
+**没有 linux-x64**，所以 \`dsh web\` 在 Linux 上**根本起不来**。
+\`node-pty@1.2.0-beta.15\`（dsh 0.1.5-rc.2 起）带 Linux 产物。
+
+**判断**：\`ls <dsh根>/node_modules/node-pty/prebuilds/\` —— 少了 \`linux-x64\` 就是这个病。
+**修复**：装 \`@deepseek-ai/dsh@${DEFAULT_INSTALL_VERSION}\` 或更新到私有前缀（见下）。
+
+### 2. \`error: unknown option '--no-open'\`
+
+**根因**：\`--no-open\` 是较新版本的 flag；老版本（实测 0.1.0-rc.6）不认识它，直接退出。
+**修复**：插件会自动去掉该 flag 重试一次，通常**不需要你处理**。只有当你手工拼命令时才注意。
+
+### 不是部署问题的报错（别修错方向）
+
+- \`NO_ADAPTER: no adapter registered for provider ...\` / \`no API key for provider route\`
+  ⇒ 是**宿主模型/provider 配置**问题，与远端部署无关。
+- \`NO_COOKIE\` / 401 ⇒ 登录态问题。
+- \`QUOTA\` / \`Insufficient Balance\` ⇒ 额度问题。
+
+## 标准部署流程（私有前缀，绝不污染用户环境）
+
+**原则**：默认**不要** \`npm i -g\`。全局安装需要系统目录写权限、改用户 PATH、
+还可能覆盖用户正在用的版本。用私有前缀：
+
+\`\`\`bash
+PREFIX="$HOME/${DEFAULT_PREFIX_SUFFIX}"
+mkdir -p "$PREFIX"
+printf '%s\\n' '{"name":"dsh-remote-install","private":true,"version":"0.0.0"}' > "$PREFIX/package.json"
+cd "$PREFIX" && npm install --prefix "$PREFIX" --no-audit --no-fund \\
+  '@deepseek-ai/dsh@${DEFAULT_INSTALL_VERSION}'
+"$PREFIX/node_modules/.bin/dsh" --version
+\`\`\`
+
+（写一个私有 \`package.json\` 是为了防止 npm 向上找到无关项目、改掉它的依赖树。）
+
+**校验**（三步都要过，缺一步不算成功）：
+\`\`\`bash
+BIN="$PREFIX/node_modules/.bin/dsh"
+test -x "$BIN" && "$BIN" --version                      # 1. 二进制存在
+ls "$PREFIX/node_modules/node-pty/prebuilds/"            # 2. 有当前平台产物
+"$BIN" web --help | grep -q -- '--port'                  # 3. web 子命令在
+\`\`\`
+
+⚠️ **常见误判**：\`.bin/dsh\` 是符号链接。\`realpath\` 后 \`dirname(dirname(...))\` 会落在
+\`<prefix>/node_modules/@deepseek-ai/dsh\`（包**内部**），那里**没有**兄弟 \`node-pty\`，
+于是好安装被判成「缺 pty」。正确做法是**向上找到第一个含 \`node_modules\` 目录的祖先**。
+
+**最后必须端到端证明**（否则「装好了」没有意义）：
+\`\`\`bash
+# 起一个只监听 127.0.0.1 的 web，抓到它打印的 token 行
+DSH_HOME=/tmp/dshweb-check setsid nohup "$BIN" --profile web --port 0 --no-open \\
+  >/tmp/dshweb-check.log 2>&1 </dev/null &
+sleep 8; grep -m1 'dsh web:' /tmp/dshweb-check.log
+\`\`\`
+拿到 \`http://127.0.0.1:<port>/?token=…\` 即成功。**用完要清理**（kill 掉并删 log）。
+
+## 长尾情况
+
+- **没有 node/npm**：先装 Node（nvm 最不侵入）。装不了就问用户要权限。
+- **公司内网/镜像源**：用 \`npm install --registry <url>\`，或让用户指路。**不要**擅自改
+  用户全局 npm 配置。
+- **Windows 远端**：启动命令是 POSIX shell（依赖 \`setsid\`/\`nohup\`）。远端有 Git Bash
+  时可工作（插件会经 \`bash -s\` 执行）；没有则如实说明暂不支持，不要硬试。
+- **代理**：\`HTTP_PROXY\`/\`HTTPS_PROXY\` 对 npm 生效；先探测是否需要。
+- **需要 sudo**：**停下来问用户**，不要自作主张提权。
+
+## 纪律
+
+1. **只读优先**：先诊断，再动手。诊断阶段不要写任何东西。
+2. **不改用户环境**：不 \`npm i -g\`（除非用户明确要求）、不改 PATH、不动 \`~/.dsh\`。
+3. **可回退**：安装只落在私有前缀，删掉那个目录就完全恢复。告诉用户路径。
+4. **收尾清理**：你起的进程、写的临时 log、用的临时 DSH_HOME 都要清掉。
+5. **报结论要带证据**：贴出关键命令的实际输出，不要只说「已修复」。
+6. **不确定就问**：涉及提权、改全局配置、删文件时先确认。
+`
+
+/**
+ * Register the deployment skill with the session skill registry.
+ *
+ * Optional by design: a composition without `ctx.skills` simply has no skill,
+ * and the deterministic deploy path keeps working. Failures are contained —
+ * a skill that fails to register must never take down the plugin.
+ *
+ * @param {object} ctx - plugin context.
+ * @returns {boolean} whether the skill was registered.
+ */
+export function registerDeploySkill(ctx) {
+  try {
+    const skills = ctx.get('skills')
+    if (!skills || typeof skills.register !== 'function') return false
+    skills.register({
+      name: SKILL_NAME,
+      description: '在远端机器部署并验证 DSH 网页界面：诊断「连不上」的原因、'
+        + '装到私有前缀、校验原生模块与 web 子命令，并端到端证明可用。'
+        + '当远端 dsh 缺失、版本过旧、或 dsh web 起不来时使用。',
+      whenToUse: '远端 DSH 界面连不上；远端没有 dsh 或版本过旧；'
+        + '出现 Failed to load native module: pty.node；需要判断是部署问题还是宿主问题。',
+      content: SKILL_BODY,
+      source: 'dsh-remote',
+      // Both entry points are wanted: the settings button starts a session with
+      // it pre-selected, and the model may reach for it when an rw_* call fails
+      // in a deployment-shaped way.
+      invocation: { modelInvocable: true, userInvocable: true },
+    })
+    return true
+  } catch (err) {
+    // A missing skill only costs the AI fallback; never break the plugin.
+    try { ctx.logger?.warn?.(new Error('dsh-remote: deploy skill not registered: ' + String((err && err.message) || err))) } catch { /* no logger */ }
+    return false
+  }
+}
+
+/**
+ * Build the prompt handed to the AI when the user asks it to investigate.
+ *
+ * The failure context is included verbatim because the whole point is that the
+ * deterministic path could not classify it — paraphrasing would throw away the
+ * only evidence there is.
+ *
+ * @param {object} context - what the deterministic path learned.
+ * @returns {string} the prompt text.
+ */
+export function buildInvestigatePrompt(context = {}) {
+  const c = context || {}
+  const lines = [
+    `请用 ${SKILL_NAME} 技能，帮我修好这台远端机器的 DSH 网页界面问题。`,
+    '',
+    `远端：${c.host || '(未知主机)'}${c.user ? ' (' + c.user + ')' : ''}`,
+  ]
+  if (c.prefix) lines.push(`建议安装位置：${c.prefix}`)
+  if (c.findings && c.findings.length) {
+    lines.push('', '自动体检已发现：')
+    for (const f of c.findings) {
+      lines.push(`- [${f.severity}] ${f.summary}${f.detail ? ' —— ' + f.detail : ''}`)
+    }
+  }
+  if (c.error) lines.push('', '自动部署/连接失败信息：', '```', String(c.error).slice(0, 2000), '```')
+  if (c.facts && Object.keys(c.facts).length) {
+    lines.push('', '体检原始事实：', '```json', JSON.stringify(c.facts, null, 2).slice(0, 2000), '```')
+  }
+  lines.push(
+    '',
+    '要求：先诊断、只读优先；装到私有前缀而不是全局；装完要**端到端证明**能起 web',
+    '（拿到 `dsh web: http://127.0.0.1:<port>/?token=…`）；收尾清理你起的进程和临时文件；',
+    '最后用证据说明结论。涉及提权或改全局配置时先问我。',
+  )
+  return lines.join('\n')
+}