@vibe-x/dsh-html-workbench 0.2.0 → 0.3.1

package/src/host.js

@@ -28,38 +28,340 @@ return {
     const PORT = opts.port || 4317
     const SCRIPT = opts.script || null
     const EDITOR_ROOT = opts.editorRoot || null
+    const PLATFORM = opts.platform || (typeof process !== 'undefined' ? process.platform : null)
+    const IS_WINDOWS = PLATFORM === 'win32'
+    // Reported verbatim in the diagnostics. A dynamic (cordis_define) load has no
+    // config, so `version` stays null — which is itself the answer to "is this the
+    // packaged build or a hot-loaded one?", the first question every report raises.
+    const VERSION = opts.version || null
+    // Candidates must be a SINGLE executable token: every call site appends its
+    // own arguments, so a multi-token entry like `py -3` would place the script
+    // path after the launcher's own flags and break argument forwarding. The `py`
+    // launcher is still supported — see `expandWindowsLauncher`, which asks it for
+    // the interpreter's absolute path and uses that instead.
+    const PYTHON_CANDIDATES = opts.pythonCommand
+      ? [opts.pythonCommand]
+      : (IS_WINDOWS ? ['python3', 'python'] : ['python3'])
+    // Static packages inject the runtime directory resolved (and probed) by
+    // src/index.js. Keep a dynamic-loader fallback too: TEMP/TMPDIR cover
+    // Windows/macOS/Linux; only the final fallback is POSIX because dynamic
+    // runners may not expose Node's `os` module. The folder name matches
+    // RUNTIME_DIR_NAME in workbench.py so both halves agree on one location.
+    const tempRoot = typeof process !== 'undefined' && process.env
+      ? (process.env.TEMP || process.env.TMP || process.env.TMPDIR)
+      : null
+    // Strip a trailing separator from EITHER source: `%TEMP%` and an injected
+    // runtimeDir both legitimately end in one, and appending '/logs' to it would
+    // yield `C:\Temp\hwb\/logs` — a path Python tolerates but that reads as
+    // corruption in every log line and error message a user pastes back.
+    const trimSeparator = (value) => String(value).replace(/[\\/]+$/, '')
+    const RUNTIME_DIR = opts.runtimeDir
+      ? trimSeparator(opts.runtimeDir)
+      : (tempRoot ? trimSeparator(tempRoot) + '/.html-workbench' : '/tmp/.html-workbench')
+
+    // These are REQUESTS, not guarantees. The service runs as a DSH sandboxed
+    // child that may write only the session workspace and a private temp folder
+    // the sandbox hands it — the ambient %TEMP% root seen by this parent is
+    // denied, so a folder the parent can create is not necessarily one the child
+    // can use. workbench.py therefore re-probes in-process, falls back on its
+    // own, and advertises the directories it settled on; `adoptResolvedPaths`
+    // below surfaces those, so the panel describes where the service really
+    // writes instead of echoing the path we merely asked for. Both are disposable
+    // cache/log data either way.
+    const LOG_DIR = RUNTIME_DIR + '/logs'
+    const VENDOR_CACHE = RUNTIME_DIR + '/vendor'
+
+    // Directories the running service reported; null until it says so.
+    let resolvedPaths = null
 
     let assets = []
     let seq = 0
     let ownedProcess = null
     let serviceRunning = false
     let startError = null
+    let pythonCommand = opts.pythonCommand || (IS_WINDOWS ? null : 'python3')
+    // A failed probe must be remembered: `resolve` runs on every keystroke and
+    // `health` on a timer, so re-probing would spawn three 5s subprocesses per
+    // call and flood the journal with one repeated line. The TTL still lets a
+    // user who just installed Python recover without reloading the plugin.
+    const PROBE_RETRY_MS = 30000
+    let pythonProbeFailedAt = 0
+    let pythonProbe = null
     let disposed = false
 
     const shell = ctx.get('shell')
 
+    // ── Diagnostics journal ──────────────────────────────────────────────────
+    //
+    // A failed start used to surface as nothing but a red dot: the only signal
+    // was `running: false`, while the actual cause (a Python traceback, a busy
+    // port, a missing interpreter) stayed inside this Node process. Every
+    // subprocess outcome now lands in this ring buffer, which `status` returns
+    // and the panel renders, so the failure is readable where it is observed.
+    const JOURNAL_LIMIT = 40
+    // Errors are the whole point of the journal, yet they are also the rarest
+    // entries: a service that fails at start then gets polled by `status` every
+    // few seconds would push the original traceback out of a plain ring buffer
+    // long before anyone opens the panel. So evict by level — drop the oldest
+    // non-error first, and only sacrifice an error when nothing else is left.
+    const JOURNAL_ERROR_FLOOR = 12
+    let journal = []
+
+    const trimJournal = () => {
+      if (journal.length <= JOURNAL_LIMIT) return
+      const overflow = journal.length - JOURNAL_LIMIT
+      let dropped = 0
+      const errors = journal.filter((entry) => entry.level === 'error').length
+      const keep = []
+      for (let i = 0; i < journal.length; i += 1) {
+        const entry = journal[i]
+        const isError = entry.level === 'error'
+        // Never let noise starve the error history, but do not grow without
+        // bound either: past the floor, errors age out like anything else.
+        const expendable = !isError || errors - dropped > JOURNAL_ERROR_FLOOR
+        if (dropped < overflow && expendable) {
+          dropped += 1
+          continue
+        }
+        keep.push(entry)
+      }
+      // Errors alone can exceed the limit; fall back to a plain tail so the
+      // buffer still has a hard ceiling.
+      journal = keep.length > JOURNAL_LIMIT ? keep.slice(-JOURNAL_LIMIT) : keep
+    }
+
+    const note = (level, message, detail) => {
+      const text = String(message || '')
+      const body = detail ? String(detail).slice(0, 4000) : null
+      // Retrying a broken start replays the SAME failure verbatim, interleaved
+      // with the "restarting" line — so consecutive-only folding would miss it.
+      // Match anywhere, then move the entry to the end so its position still
+      // agrees with its timestamp when the panel renders newest-first.
+      let index = -1
+      for (let i = journal.length - 1; i >= 0; i -= 1) {
+        const entry = journal[i]
+        if (entry.level === level && entry.message === text && entry.detail === body) { index = i; break }
+      }
+      if (index >= 0) {
+        const entry = journal.splice(index, 1)[0]
+        entry.at = Date.now()
+        entry.repeated = (entry.repeated || 1) + 1
+        journal.push(entry)
+      } else {
+        journal.push({ at: Date.now(), level: level, message: text, detail: body })
+        trimJournal()
+      }
+      if (level === 'error') console.error('[html-workbench] ' + text, body || '')
+    }
+
+    // `CollectedOutput` carries more than text (truncation flags, spill paths);
+    // reduce it to the part a human reads, and say so when bytes were dropped.
+    const outputText = (collected) => {
+      if (!collected) return ''
+      const text = typeof collected === 'string' ? collected : (collected.text || '')
+      const trimmed = String(text).trim()
+      if (collected && collected.truncated) return trimmed + '\n…（输出被截断）'
+      return trimmed
+    }
+
+    // `shell.resolve({ command })` takes ONE command line, so every embedded path
+    // must be quoted for the platform's parser. Naive `'"' + p + '"'` breaks on
+    // Windows, where `C:\dir\` ends in a backslash that escapes the closing quote
+    // and swallows the rest of the line. Never use JSON.stringify here: it emits
+    // JSON escapes (`\\`), which cmd.exe passes through verbatim, so Python
+    // receives a path with doubled separators and reports every file as missing.
+    const quoteArg = (value) => {
+      const raw = String(value == null ? '' : value)
+      if (IS_WINDOWS) {
+        // Double only the run of backslashes that precedes the closing quote;
+        // interior ones are literal to cmd.exe. Inner quotes cannot appear in a
+        // Windows path, but strip them rather than emit an unbalanced line.
+        const cleaned = raw.replace(/"/g, '')
+        const tail = cleaned.match(/\\*$/)[0]
+        return '"' + cleaned + tail + '"'
+      }
+      return "'" + raw.replace(/'/g, "'\\''") + "'"
+    }
+
+    const describeRun = (result) => {
+      if (!result) return 'shell.run threw'
+      const parts = []
+      if (result.timedOut) parts.push('超时（' + result.timeoutMs + 'ms）')
+      if (result.aborted) parts.push('被取消')
+      if (result.signal) parts.push('信号 ' + result.signal)
+      parts.push('exit=' + String(result.exitCode))
+      const streams = [outputText(result.stderr), outputText(result.stdout)].filter(Boolean)
+      return parts.join(' ') + (streams.length ? '\n' + streams.join('\n') : '')
+    }
+
+    // Windows ships a `py` launcher that resolves versions the PATH may not
+    // expose. It is NOT usable as a command prefix (`py -3 script.py` mangles
+    // forwarded arguments), so ask it for the interpreter's absolute path and use
+    // that as a normal single-token executable.
+    const expandWindowsLauncher = async () => {
+      if (!IS_WINDOWS || !shell) return null
+      const probe = 'py -3 -c ' + quoteArg('import sys; print(sys.executable)')
+      try {
+        const result = await shell.run(shell.resolve({ command: probe, timeoutMs: 5000, stdoutMaxBytes: 4096 }))
+        if (!result || result.exitCode !== 0) return { failure: 'py -3: ' + describeRun(result) }
+        const executable = outputText(result.stdout).split('\n').pop().trim()
+        if (!executable) return { failure: 'py -3: 没有返回解释器路径' }
+        return { command: quoteArg(executable) }
+      } catch (e) {
+        return { failure: 'py -3: ' + ((e && e.message) || String(e)) }
+      }
+    }
+
+    const resolvePythonCommand = async () => {
+      if (pythonCommand) return pythonCommand
+      if (!shell) return null
+      // Collapse concurrent callers onto one probe: the panel's poll, an `open`
+      // and a keystroke-driven `resolve` can all arrive inside the same tick.
+      if (pythonProbe) return pythonProbe
+      if (pythonProbeFailedAt && Date.now() - pythonProbeFailedAt < PROBE_RETRY_MS) return null
+      pythonProbe = (async () => {
+        const failures = []
+        for (const candidate of PYTHON_CANDIDATES) {
+          try {
+            const spec = shell.resolve({ command: candidate + ' --version', timeoutMs: 5000, stdoutMaxBytes: 4096 })
+            const result = await shell.run(spec)
+            if (result && result.exitCode === 0) {
+              pythonCommand = candidate
+              pythonProbeFailedAt = 0
+              note('info', '使用 Python 解释器：' + candidate)
+              return pythonCommand
+            }
+            failures.push(candidate + ': ' + describeRun(result))
+          } catch (e) {
+            failures.push(candidate + ': ' + ((e && e.message) || String(e)))
+          }
+        }
+        const launcher = await expandWindowsLauncher()
+        if (launcher && launcher.command) {
+          pythonCommand = launcher.command
+          pythonProbeFailedAt = 0
+          note('info', '使用 Python 解释器（经 py 启动器解析）：' + launcher.command)
+          return pythonCommand
+        }
+        if (launcher && launcher.failure) failures.push(launcher.failure)
+        pythonProbeFailedAt = Date.now()
+        startError = '找不到可用的 Python 3 解释器（已尝试：'
+          + PYTHON_CANDIDATES.join('、') + (IS_WINDOWS ? '、py -3' : '')
+          + '）。请安装 Python 3.9+ 并确保它在 PATH 中，然后点「重启服务」。'
+        note('error', startError, failures.join('\n'))
+        return null
+      })()
+      try {
+        return await pythonProbe
+      } finally {
+        pythonProbe = null
+      }
+    }
+
     const runCli = async (args, timeoutMs) => {
+      if (!shell) { note('error', 'shell 服务不可用，无法执行 workbench.py'); return null }
+      if (!SCRIPT) { note('error', 'workbench.py 路径未配置'); return null }
+      const python = await resolvePythonCommand()
+      if (!python) return null
+      const command = python + ' ' + quoteArg(SCRIPT) + ' ' + args
+      try {
+        const spec = shell.resolve({ command: command, timeoutMs: timeoutMs || 15000, stdoutMaxBytes: 64 * 1024 })
+        const result = await shell.run(spec)
+        // A non-zero exit is the interesting case and used to be discarded: the
+        // CLI prints a structured `{ok:false,error:{code,message}}` on stdout.
+        if (!result || result.exitCode !== 0) note('error', 'workbench.py ' + args.split(' ')[0] + ' 执行失败', describeRun(result))
+        return result
+      } catch (e) {
+        note('error', 'workbench.py ' + args.split(' ')[0] + ' 无法执行', (e && e.message) || String(e))
+        return null
+      }
+    }
+
+    // `health` runs on a timer, so its failures are expected and must not flood
+    // the journal — poll quietly and let the caller decide what is worth noting.
+    const probeHealth = async () => {
       if (!shell || !SCRIPT) return null
+      const python = await resolvePythonCommand()
+      if (!python) return null
       try {
         const spec = shell.resolve({
-          command: 'python3 "' + SCRIPT + '" ' + args,
-          timeoutMs: timeoutMs || 15000,
+          command: python + ' ' + quoteArg(SCRIPT) + ' health --port ' + PORT,
+          timeoutMs: 8000,
           stdoutMaxBytes: 64 * 1024,
         })
-        return await shell.run(spec)
+        const result = await shell.run(spec)
+        if (!result || result.exitCode !== 0) return { ok: false, result: result }
+        try {
+          const payload = JSON.parse(outputText(result.stdout) || '')
+          return payload && payload.ok === true ? { ok: true, payload: payload } : { ok: false, result: result }
+        } catch (e) {
+          return { ok: false, result: result }
+        }
       } catch (e) {
-        return null
+        return { ok: false, error: (e && e.message) || String(e) }
       }
     }
 
+    // `/api/health` advertises the directories the service really writes to. The
+    // paths it was ASKED for may be exactly what the sandbox refused, so adopting
+    // the reported ones is what lets the panel stay truthful — for a service we
+    // started and for one we merely reused (a reused service leaves us no startup
+    // output to read them from).
+    const adoptResolvedPaths = (payload) => {
+      if (!payload) return
+      const logDir = typeof payload.logDir === 'string' ? payload.logDir : null
+      const vendorCache = typeof payload.vendorCache === 'string' ? payload.vendorCache : null
+      if (logDir || vendorCache) resolvedPaths = { logDir: logDir, vendorCache: vendorCache }
+    }
+
     const health = async () => {
-      const r = await runCli('health --port ' + PORT, 8000)
-      if (!r || r.exitCode !== 0) return null
+      const probe = await probeHealth()
+      if (!probe || !probe.ok) return null
+      adoptResolvedPaths(probe.payload)
+      return probe.payload
+    }
+
+    // `workbench.py` reports failures as one structured JSON line on stderr. Turn
+    // the machine code into the sentence a person can act on; keep the raw line
+    // in the detail so nothing is lost when the code is one we do not know.
+    const CLI_HINTS = {
+      PORT_IN_USE: '端口已被占用。可能有别的进程（或旧版服务）占着它 —— 点「重启服务」会先退役占用者。',
+      ASSET_NOT_FOUND: '前端资源缺失，插件安装目录不完整（缺 assets/workbench.html）。',
+      PYTHON_TOO_OLD: '需要 Python 3.9 或更高版本。',
+      SERVER_OUTDATED: '端口上有旧版服务且无法自动停止，请手动结束该进程。',
+      FILE_NOT_FOUND: '找不到文件。',
+      VENDOR_DOWNLOAD_FAILED: '首次启动需要联网下载 GrapesJS，下载失败了。',
+    }
+
+    const explainOutput = (text) => {
+      if (!text) return null
+      for (const line of String(text).split('\n')) {
+        const trimmed = line.trim()
+        if (!trimmed.startsWith('{')) continue
+        try {
+          const payload = JSON.parse(trimmed)
+          if (payload && payload.ok === false && payload.error) {
+            const hint = CLI_HINTS[payload.error]
+            return (hint || payload.message || payload.error) + '（' + payload.error + '）'
+          }
+        } catch (e) { /* not the JSON line; keep scanning */ }
+      }
+      return null
+    }
+
+    // Everything the started process wrote since the last read. DSH settles a
+    // spawn failure as `killed` with the error on stderr, so this is the only
+    // place a "python3: command not found" or a traceback can be observed.
+    const drain = (proc) => {
       try {
-        const p = JSON.parse((r.stdout && r.stdout.text) || '')
-        return p && p.ok === true ? p : null
+        const read = proc.readOutput()
+        if (!read) return ''
+        let text = String(read.delta || '').trim()
+        if (read.lossy) text += '\n…（部分输出丢失）'
+        if (read.stderrSpillPath) text += '\n完整 stderr: ' + read.stderrSpillPath
+        return text
       } catch (e) {
-        return null
+        return ''
       }
     }
 
@@ -67,34 +369,143 @@ return {
       if (disposed) return null
       if (serviceRunning) return health()
       const existing = await health()
-      if (existing) { serviceRunning = true; startError = null; return existing }
-      if (!shell) { startError = 'shell service unavailable'; return null }
-      if (!SCRIPT) { startError = 'workbench.py 路径未配置（请用静态装载并随包分发 scripts/workbench.py）'; return null }
+      if (existing) {
+        serviceRunning = true
+        startError = null
+        healthConfirmedAt = Date.now()
+        // Record the reuse too, so the journal always explains the CURRENT state
+        // rather than only the failures.
+        note('info', '复用已在运行的服务：版本 ' + (existing.version || '未知') + '，端口 ' + PORT)
+        return existing
+      }
+      if (!shell) { startError = 'shell 服务不可用（DSH 未提供 shell，插件无法拉起本地服务）'; note('error', startError); return null }
+      if (!SCRIPT) { startError = 'workbench.py 路径未配置（请用静态装载并随包分发 scripts/workbench.py）'; note('error', startError); return null }
+      const python = await resolvePythonCommand()
+      if (!python) return null
       let proc = null
+      const command = python + ' ' + quoteArg(SCRIPT) + ' serve --port ' + PORT
+        + ' --log-dir ' + quoteArg(LOG_DIR)
+        + ' --vendor-cache ' + quoteArg(VENDOR_CACHE)
+        + (EDITOR_ROOT ? ' --editor-root ' + quoteArg(EDITOR_ROOT) : '')
       try {
-        const editorRootArg = EDITOR_ROOT ? ' --editor-root "' + EDITOR_ROOT + '"' : ''
-        const spec = shell.resolve({
-          command: 'python3 "' + SCRIPT + '" serve --port ' + PORT + editorRootArg,
-          stdoutMaxBytes: 64 * 1024,
-        })
-        proc = shell.start(spec)
+        note('info', '启动本地服务：端口 ' + PORT, command)
+        proc = shell.start(shell.resolve({ command: command, stdoutMaxBytes: 64 * 1024 }))
         if (disposed) { try { proc.kill() } catch (e) {} return null }
         ownedProcess = proc
+        let transcript = ''
         for (let i = 0; i < 240; i += 1) {
-          const h = await health()
-          if (h) { serviceRunning = true; startError = null; return h }
+          const chunk = drain(proc)
+          if (chunk) transcript += (transcript ? '\n' : '') + chunk
+          const probe = await probeHealth()
+          if (probe && probe.ok) {
+            serviceRunning = true
+            startError = null
+            healthConfirmedAt = Date.now()
+            adoptResolvedPaths(probe.payload)
+            note('info', '本地服务就绪：版本 ' + (probe.payload.version || '未知') + '，端口 ' + PORT)
+            return probe.payload
+          }
+          // Stop waiting the moment the process is gone. Polling health for the
+          // full 60s after `serve` already exited hides the reason and makes a
+          // fast, loud failure look like a hang.
+          if (proc.status !== 'running') {
+            const tail = drain(proc)
+            if (tail) transcript += (transcript ? '\n' : '') + tail
+            // Lead with the CLI's own diagnosis when it gave one — "端口已被占用"
+            // is actionable, "exit=1" is not.
+            const explained = explainOutput(transcript)
+            startError = explained || ('serve 进程已退出（exit=' + String(proc.exitCode) + (proc.signal ? ', 信号 ' + proc.signal : '') + '）')
+            note('error', startError, transcript || '进程没有任何输出。命令：' + command)
+            ownedProcess = null
+            return null
+          }
           await ctx.timeout(250)
         }
-        startError = 'service did not become healthy'
+        startError = '服务在 60 秒内没有就绪（端口 ' + PORT + ' 未通过健康检查）'
+        note('error', startError, transcript || '进程仍在运行但健康检查一直失败。命令：' + command)
         return null
       } catch (e) {
-        startError = e && e.message ? String(e.message) : String(e)
+        startError = 'serve 进程启动失败：' + ((e && e.message) || String(e))
+        note('error', startError, command)
         if (proc) { try { proc.kill() } catch (e2) {} }
         ownedProcess = null
         return null
       }
     }
 
+    // A service that dies AFTER a successful start used to leave the plugin
+    // frozen: nothing ever re-checked the process, so the panel kept showing a
+    // stale dot while every open failed with no explanation. Reading
+    // `ownedProcess.status` costs nothing (no subprocess), so the panel's
+    // existing poll can supervise the process for free.
+    const superviseOwnedProcess = () => {
+      const proc = ownedProcess
+      if (!proc || proc.status === 'running') return
+      const tail = drain(proc)
+      const explained = explainOutput(tail)
+      ownedProcess = null
+      serviceRunning = false
+      startError = explained || ('服务进程已退出（exit=' + String(proc.exitCode) + (proc.signal ? ', 信号 ' + proc.signal : '') + '）')
+      note('error', '服务进程意外退出', tail || '进程没有留下输出。可用「重启服务」重新拉起。')
+    }
+
+    // A REUSED service has no process handle, so its death is invisible to the
+    // check above. Revalidate with a real health call — throttled, because this
+    // spawns a subprocess and the panel polls every few seconds. The window is
+    // seeded when the service is confirmed up, so a freshly verified service is
+    // not immediately re-checked.
+    const REVALIDATE_MS = 10000
+    let healthConfirmedAt = 0
+    let revalidating = false
+
+    const revalidateService = () => {
+      if (revalidating || ownedProcess || !serviceRunning) return
+      if (Date.now() - healthConfirmedAt < REVALIDATE_MS) return
+      revalidating = true
+      void (async () => {
+        try {
+          if (await health()) { healthConfirmedAt = Date.now(); return }
+          serviceRunning = false
+          startError = '之前复用的服务已经不再响应（端口 ' + PORT + '）。'
+          note('error', '复用的服务失去响应', '健康检查失败。可用「重启服务」重新拉起。')
+        } finally {
+          revalidating = false
+        }
+      })()
+    }
+
+    // Everything the panel needs to explain a red dot without opening a terminal.
+    // Reaping first means a process that died since the last call is reported as
+    // dead here, instead of leaving a stale "running" dot behind.
+    const diagnostics = () => {
+      superviseOwnedProcess()
+      revalidateService()
+      return {
+        ok: true,
+        running: serviceRunning,
+        owned: !!ownedProcess,
+        version: VERSION,
+        platform: PLATFORM,
+        port: PORT,
+        script: SCRIPT,
+        editorRoot: EDITOR_ROOT,
+        runtimeDir: RUNTIME_DIR,
+        pythonCommand: pythonCommand,
+        pythonCandidates: PYTHON_CANDIDATES.slice(),
+        // Where the service really writes, once it has told us. The requested
+        // paths stand in only until then: they may be exactly what the sandbox
+        // refused, and showing them after the fact is what made a working service
+        // look broken.
+        logDir: (resolvedPaths && resolvedPaths.logDir) || LOG_DIR,
+        vendorCache: (resolvedPaths && resolvedPaths.vendorCache) || VENDOR_CACHE,
+        hasShell: !!shell,
+        processStatus: ownedProcess ? ownedProcess.status : null,
+        exitCode: ownedProcess ? ownedProcess.exitCode : null,
+        startError: startError,
+        journal: journal.slice().reverse(),
+      }
+    }
+
     // 生命周期副作用：卸载时停掉本插件自己启动的服务进程。
     ctx.effect(() => () => {
       disposed = true
@@ -133,18 +544,59 @@ return {
     const snapshot = () => assets.slice().sort((a, b) => b.seq - a.seq)
 
     const openFile = async (file) => {
-      if (typeof file !== 'string' || !file) return { ok: false, error: 'file is required' }
-      if (!/\.html?$/i.test(file)) return { ok: false, error: 'only .html files are supported' }
-      if (!SCRIPT) return { ok: false, error: startError || 'workbench.py 路径未配置' }
+      if (typeof file !== 'string' || !file) return { ok: false, error: '请填写文件路径' }
+      if (!/\.html?$/i.test(file)) return { ok: false, error: '只支持 .html / .htm 文件' }
+      if (!SCRIPT) return { ok: false, error: startError || 'workbench.py 路径未配置', diagnostics: diagnostics() }
       const wasUp = await health()
       if (!wasUp) await startService()
       const h = await health()
-      if (!h) return { ok: false, error: startError || 'workbench service unavailable' }
+      // Carry the diagnostics WITH the failure: the panel can then show the real
+      // cause instead of a generic "unavailable" that sends the user hunting.
+      if (!h) return { ok: false, error: startError || '本地服务未就绪', diagnostics: diagnostics() }
       return {
         ok: true,
         url: 'http://127.0.0.1:' + PORT + '/?file=' + encodeURIComponent(file),
         reused: !!wasUp,
         port: PORT,
+        version: h.version || null,
+      }
+    }
+
+    const restartService = async () => {
+      const proc = ownedProcess
+      ownedProcess = null
+      serviceRunning = false
+      startError = null
+      if (proc) { try { proc.kill() } catch (e) {} }
+      note('info', '手动重启本地服务')
+      // Killing our own handle is not enough when the port is held by a process
+      // we do not own (a leftover from a previous DSH run, or an outdated
+      // version) — the spawn would then die with PORT_IN_USE. Clear the port
+      // first; `stop` is a no-op when nothing is listening.
+      const stopped = await runCli('stop --port ' + PORT, 20000)
+      if (stopped && stopped.exitCode !== 0) {
+        return { ok: false, error: '端口 ' + PORT + ' 上的旧进程无法停止，请手动结束后重试。', diagnostics: diagnostics() }
+      }
+      const h = await startService()
+      return h ? { ok: true, info: h, diagnostics: diagnostics() } : { ok: false, error: startError || '重启失败', diagnostics: diagnostics() }
+    }
+
+    // Browser address bars yield file:///… URLs while the CLI expects a native
+    // path. Normalize only for the local existence probe; the Python service
+    // repeats this normalization authoritatively for every request.
+    const normalizeFileReference = (value) => {
+      const raw = String(value || '').trim()
+      if (!/^file:/i.test(raw)) return raw
+      try {
+        const url = new URL(raw)
+        if (url.protocol !== 'file:' || url.search || url.hash) return raw
+        let path = decodeURIComponent(url.pathname)
+        const isWindows = typeof process !== 'undefined' && process.platform === 'win32'
+        if (isWindows && /^[\\/][A-Za-z]:\//.test(path)) path = path.slice(1)
+        if (isWindows && url.hostname && url.hostname !== 'localhost') path = '//' + url.hostname + path
+        return path
+      } catch (e) {
+        return raw
       }
     }
 
@@ -152,24 +604,75 @@ return {
       if (typeof file !== 'string') return { ok: false, error: 'file is required' }
       const trimmed = file.trim()
       if (!trimmed) return { ok: true, empty: true, isHtml: false, exists: false }
-      if (!/\.html?$/i.test(trimmed)) return { ok: true, isHtml: false, exists: false }
-      if (!shell) return { ok: true, isHtml: true, exists: null }
-      const arg = JSON.stringify(trimmed)
-      const spec = shell.resolve({ command: 'python3 -c "import os,sys; sys.exit(0 if os.path.isfile(sys.argv[1]) else 1)" ' + arg, timeoutMs: 5000, stdoutMaxBytes: 1024 })
+      const normalized = normalizeFileReference(trimmed)
+      if (!/\.html?$/i.test(normalized)) return { ok: true, isHtml: false, exists: false }
+      if (!shell) return { ok: true, isHtml: true, exists: null, normalized: normalized }
+      const python = await resolvePythonCommand()
+      // Say WHY the check could not run. Returning a bare `exists: null` renders
+      // as no indicator at all, which reads as "the field is ignoring me".
+      if (!python) {
+        return { ok: true, isHtml: true, exists: null, normalized: normalized, error: startError }
+      }
+      const probe = 'import os,sys; sys.exit(0 if os.path.isfile(sys.argv[1]) else 1)'
+      const spec = shell.resolve({
+        command: python + ' -c ' + quoteArg(probe) + ' ' + quoteArg(normalized),
+        timeoutMs: 5000,
+        stdoutMaxBytes: 1024,
+      })
       try {
         const r = await shell.run(spec)
-        return { ok: true, isHtml: true, exists: !!(r && r.exitCode === 0) }
+        return { ok: true, isHtml: true, exists: !!(r && r.exitCode === 0), normalized: normalized }
       } catch (e) {
-        return { ok: true, isHtml: true, exists: null }
+        return { ok: true, isHtml: true, exists: null, normalized: normalized, error: (e && e.message) || String(e) }
+      }
+    }
+
+    const listPayload = () => {
+      const base = diagnostics()
+      base.assets = snapshot()
+      return base
+    }
+
+    const statusPayload = async () => {
+      const h = await health()
+      const out = diagnostics()
+      out.ok = !!h
+      out.running = !!h
+      out.info = h || null
+      return out
+    }
+
+    // `diagnostics()` supervises the child process and revalidates the service,
+    // so it can itself throw (a dead handle, a shell that rejects). Since it is
+    // the payload every error path attaches, it must never be the thing that
+    // turns a readable failure back into an opaque one.
+    const safeDiagnostics = () => {
+      try {
+        return diagnostics()
+      } catch (error) {
+        return {
+          ok: false,
+          degraded: true,
+          error: '收集诊断信息时出错：' + ((error && error.message) || String(error)),
+          version: VERSION,
+          platform: PLATFORM,
+          port: PORT,
+          script: SCRIPT,
+          runtimeDir: RUNTIME_DIR,
+          startError: startError,
+          journal: journal.slice().reverse(),
+        }
       }
     }
 
     // 动态传输：Package-private RPC（仅动态运行时存在 harness）。
     if (typeof harness !== 'undefined') {
-      harness.handle('list', () => ({ ok: true, running: serviceRunning, owned: !!ownedProcess, port: PORT, assets: snapshot() }))
-      harness.handle('status', async () => { const h = await health(); return { ok: !!h, running: !!h, owned: !!ownedProcess, port: PORT, info: h || null } })
+      harness.handle('list', () => listPayload())
+      harness.handle('status', () => statusPayload())
       harness.handle('open', async (args) => openFile(args && args.file))
       harness.handle('resolve', async (args) => resolvePath(args && args.file))
+      harness.handle('diagnostics', () => safeDiagnostics())
+      harness.handle('restart', async () => restartService())
     }
 
     // 静态传输：HTTP 路由，供静态 client bundle（fetch）与直接浏览器访问使用。
@@ -191,36 +694,78 @@ return {
         })
         return out
       }
+      // A handler that throws leaves the request hanging until the browser gives
+      // up, and `fetch` then rejects with a bare "Failed to fetch" — the exact
+      // dead end this plugin's users hit. Always answer, and answer with the
+      // reason plus the journal, so the panel can render something actionable.
+      const guard = (name, handler) => async (req, res) => {
+        try {
+          await handler(req, res)
+        } catch (error) {
+          const reason = (error && error.stack) || (error && error.message) || String(error)
+          note('error', '路由 ' + name + ' 处理失败', reason)
+          try {
+            sendJson(res, 500, {
+              ok: false,
+              error: '插件内部错误（' + name + '）：' + ((error && error.message) || String(error)),
+              detail: reason,
+              diagnostics: safeDiagnostics(),
+            })
+          } catch (_) { /* the socket is already gone; the journal has the reason */ }
+        }
+      }
+      // Registered FIRST and deliberately dependency-free: if anything below
+      // fails to register, this route still answers, which is the only way to
+      // read the failure without access to the terminal that started DSH.
+      ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/html-workbench/diagnostics',
+        handler: guard('diagnostics', (req, res) => sendJson(res, 200, safeDiagnostics())),
+      }), 'html-workbench: diagnostics route')
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/html-workbench/list',
-        handler: (req, res) => sendJson(res, 200, { ok: true, running: serviceRunning, owned: !!ownedProcess, port: PORT, assets: snapshot() }),
+        handler: guard('list', (req, res) => sendJson(res, 200, listPayload())),
       }), 'html-workbench: list route')
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/html-workbench/status',
-        handler: async (req, res) => { const h = await health(); sendJson(res, 200, { ok: !!h, running: !!h, owned: !!ownedProcess, port: PORT, info: h || null }) },
+        handler: guard('status', async (req, res) => sendJson(res, 200, await statusPayload())),
       }), 'html-workbench: status route')
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/html-workbench/open',
-        handler: async (req, res) => {
+        handler: guard('open', async (req, res) => {
           const file = parseQuery(req).file
           const out = await openFile(file)
           sendJson(res, out.ok ? 200 : 400, out)
-        },
+        }),
       }), 'html-workbench: open route')
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/html-workbench/resolve',
-        handler: async (req, res) => {
+        handler: guard('resolve', async (req, res) => {
           const out = await resolvePath(parseQuery(req).file)
           sendJson(res, out.ok ? 200 : 400, out)
-        },
+        }),
       }), 'html-workbench: resolve route')
+      ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/html-workbench/restart',
+        handler: guard('restart', async (req, res) => {
+          const out = await restartService()
+          sendJson(res, out.ok ? 200 : 500, out)
+        }),
+      }), 'html-workbench: restart route')
     }
 
     // 注册时主动拉起服务（异步，不阻塞 apply）。
-    void startService()
+    // A rejection here must not escape into Cordis: `apply` has already wired up
+    // the transports, and losing them would take the diagnostics route down with
+    // it — leaving the panel with nothing but "Failed to fetch" again.
+    Promise.resolve().then(startService).catch((error) => {
+      startError = '启动本地服务时发生未预期的错误：' + ((error && error.message) || String(error))
+      note('error', startError, (error && error.stack) || null)
+    })
   },
 }